An open source design system that's fully customizable and agent ready
TypeScript
feat(cli)!: collapse component/hook list taxonomy to one type + data.detail (#4466)
Joey943ed8f18c63
diff --git a/.changeset/component-hook-list-taxonomy.md b/.changeset/component-hook-list-taxonomy.mdnew file mode 100644index 0000000000..2f0848c9ad--- /dev/null+++ b/.changeset/component-hook-list-taxonomy.md@@ -0,0 +1,7 @@+---+'@astryxdesign/cli': minor+---++[breaking] component/hook `--json` list responses collapsed. `--detail compact`/`full` previously emitted distinct `component.brief`/`component.full` (and `hook.*`) envelopes; they now all emit `component.list` (resp. `hook.list`) with a `data.detail: 'names' | 'compact' | 'full'` field. Migrate: switch on `data.detail`, not the `.brief`/`.full` discriminator. Removed types: ComponentBriefResponse, ComponentFullResponse, HookBriefResponse, HookFullResponse.++@josephfarinadiff --git a/.github/scripts/api-cli-parity-test.mjs b/.github/scripts/api-cli-parity-test.mjsindex 5d822414f7..f3f12f82bf 100644--- a/.github/scripts/api-cli-parity-test.mjs+++ b/.github/scripts/api-cli-parity-test.mjs@@ -76,11 +76,14 @@ console.log('Discovering...');const api = await import('../../packages/cli/api/index.mjs');const componentList = cliJson(['component', '--list']);-// `component --list` data is package-qualified: each group value is an array-// of { name, package } objects. Map to bare names for the per-component cases.-// (Tolerate plain strings too, in case the shape is ever simplified.)-const allComponents = componentList.data && !componentList.error- ? Object.values(componentList.data)+// `component --list` nests the grouped map under data.components (the depth tag+// lives in data.detail). Each group value is an array of { name, package }+// objects. Map to bare names for the per-component cases. (Tolerate plain+// strings too, in case the shape is ever simplified.)+const componentGroups =+ componentList.data && !componentList.error ? componentList.data.components : null;+const allComponents = componentGroups+ ? Object.values(componentGroups).flat().map(c => (typeof c === 'string' ? c : c.name)): [];@@ -90,15 +93,13 @@ const allTopics = docsList.data && !docsList.error? docsList.data.map(e => e.topic): [];-const categories = componentList.data ? Object.keys(componentList.data) : [];+const categories = componentGroups ? Object.keys(componentGroups) : [];const hookList = cliJson(['hook', '--list']);-const allHooks = hookList.data && !hookList.error- ? Object.values(hookList.data).flat()- : [];-const hookCategories = hookList.data && !hookList.error- ? Object.keys(hookList.data)- : [];+const hookGroups =+ hookList.data && !hookList.error ? hookList.data.components : null;+const allHooks = hookGroups ? Object.values(hookGroups).flat() : [];+const hookCategories = hookGroups ? Object.keys(hookGroups) : [];console.log(` ${allComponents.length} components, ${allTopics.length} doc topics, ${categories.length} categories`);console.log(` ${allHooks.length} hooks, ${hookCategories.length} hook categories`);diff --git a/.github/scripts/cli-json-smoke-test.mjs b/.github/scripts/cli-json-smoke-test.mjsindex e40232f6e2..3f15f1d3ad 100644--- a/.github/scripts/cli-json-smoke-test.mjs+++ b/.github/scripts/cli-json-smoke-test.mjs@@ -203,7 +203,7 @@ checkJson('component --list', ['component', '--list'], {expectType: 'component.lconst catResult = runJson(['component', '--list']);try {const catData = JSON.parse(catResult.stdout);- const firstCategory = Object.keys(catData.data)[0];+ const firstCategory = Object.keys(catData.data.components)[0];if (firstCategory) {checkJson(`component --category ${firstCategory}`, ['component', '--category', firstCategory], {expectType: 'component.list'});}diff --git a/packages/cli/README.md b/packages/cli/README.mdindex de8dd6c395..ba84ace6e8 100644--- a/packages/cli/README.md+++ b/packages/cli/README.md@@ -361,41 +361,37 @@ detail.data.name; // narrowedEvery response has a `type` string that uniquely identifies it:-| Command | Type | Response |-| ------------------------------------------------- | --------------------------- | --------------------------------- |-| `astryx --json component [--list]` | `component.list` | `ComponentListResponse` |-| `astryx --json component --list --detail compact` | `component.brief` | `ComponentBriefResponse` |-| `astryx --json component --list --detail full` | `component.full` | `ComponentFullResponse` |-| `astryx --json component <name>` | `component.detail` | `ComponentDetailResponse` |-| `astryx --json component <name> --props` | `component.detail.props` | `ComponentDetailPropsResponse` |-| `astryx --json component <name> --source` | `component.detail.source` | `ComponentDetailSourceResponse` |-| `astryx --json component <name> --showcase` | `component.detail.showcase` | `ComponentDetailShowcaseResponse` |-| `astryx --json component <name> --blocks` | `component.detail.blocks` | `ComponentDetailBlocksResponse` |-| `astryx --json discover` | `discover.list` | `DiscoverListResponse` |-| `astryx --json discover @scope/name` | `discover.detail` | `DiscoverDetailResponse` |-| `astryx --json discover @scope/name/Comp` | `discover.detail.doc` | `DiscoverDetailDocResponse` |-| `astryx --json discover <search>` | `discover.search` | `DiscoverSearchResponse` |-| `astryx --json docs` | `docs.list` | `DocsListResponse` |-| `astryx --json docs <topic>` | `docs.detail` | `DocsDetailResponse` |-| `astryx --json docs <topic> <section>` | `docs.detail.section` | `DocsDetailSectionResponse` |-| `astryx --json template [--list]` | `template.list` | `TemplateListResponse` |-| `astryx --json template <name>` | `template.show` | `TemplateShowResponse` |-| `astryx --json template <name> --skeleton` | `template.skeleton` | `TemplateSkeletonResponse` |-| `astryx --json template <name> [path]` | `template.copy` | `TemplateCopyResponse` |-| `astryx --json hook [--list]` | `hook.list` | `HookListResponse` |-| `astryx --json hook --list --detail compact` | `hook.brief` | `HookBriefResponse` |-| `astryx --json hook --list --detail full` | `hook.full` | `HookFullResponse` |-| `astryx --json hook <name>` | `hook.detail` | `HookDetailResponse` |-| `astryx --json hook <name> --params` | `hook.detail.params` | `HookDetailParamsResponse` |-| `astryx --json search <query>` | `search` | `SearchResponse` |-| `astryx --json swizzle [--list]` | `swizzle.list` | `SwizzleListResponse` |-| `astryx --json swizzle <component>` | `swizzle.copy` | `SwizzleCopyResponse` |-| `astryx --json theme build <file>` | `theme.build` | `ThemeBuildResponse` |-| `astryx --json upgrade --list` | `upgrade.list` | `UpgradeListResponse` |-| `astryx --json upgrade [--apply]` | `upgrade.run` | `UpgradeRunResponse` |-| `astryx --json doctor` | `doctor` | `DoctorResponse` |-| any error | — | `CLIError` |-| unsupported command | — | `CLIUnsupportedError` |+| Command | Type | Response |+| ------------------------------------------------------------------ | ------------------------------------ | --------------------------------- |+| `astryx --json component [--list] [--detail names\|compact\|full]` | `component.list` (see `data.detail`) | `ComponentListResponse` |+| `astryx --json component <name>` | `component.detail` | `ComponentDetailResponse` |+| `astryx --json component <name> --props` | `component.detail.props` | `ComponentDetailPropsResponse` |+| `astryx --json component <name> --source` | `component.detail.source` | `ComponentDetailSourceResponse` |+| `astryx --json component <name> --showcase` | `component.detail.showcase` | `ComponentDetailShowcaseResponse` |+| `astryx --json component <name> --blocks` | `component.detail.blocks` | `ComponentDetailBlocksResponse` |+| `astryx --json discover` | `discover.list` | `DiscoverListResponse` |+| `astryx --json discover @scope/name` | `discover.detail` | `DiscoverDetailResponse` |+| `astryx --json discover @scope/name/Comp` | `discover.detail.doc` | `DiscoverDetailDocResponse` |+| `astryx --json discover <search>` | `discover.search` | `DiscoverSearchResponse` |+| `astryx --json docs` | `docs.list` | `DocsListResponse` |+| `astryx --json docs <topic>` | `docs.detail` | `DocsDetailResponse` |+| `astryx --json docs <topic> <section>` | `docs.detail.section` | `DocsDetailSectionResponse` |+| `astryx --json template [--list]` | `template.list` | `TemplateListResponse` |+| `astryx --json template <name>` | `template.show` | `TemplateShowResponse` |+| `astryx --json template <name> --skeleton` | `template.skeleton` | `TemplateSkeletonResponse` |+| `astryx --json template <name> [path]` | `template.copy` | `TemplateCopyResponse` |+| `astryx --json hook [--list] [--detail names\|compact\|full]` | `hook.list` (see `data.detail`) | `HookListResponse` |+| `astryx --json hook <name>` | `hook.detail` | `HookDetailResponse` |+| `astryx --json hook <name> --params` | `hook.detail.params` | `HookDetailParamsResponse` |+| `astryx --json search <query>` | `search` | `SearchResponse` |+| `astryx --json swizzle [--list]` | `swizzle.list` | `SwizzleListResponse` |+| `astryx --json swizzle <component>` | `swizzle.copy` | `SwizzleCopyResponse` |+| `astryx --json theme build <file>` | `theme.build` | `ThemeBuildResponse` |+| `astryx --json upgrade --list` | `upgrade.list` | `UpgradeListResponse` |+| `astryx --json upgrade [--apply]` | `upgrade.run` | `UpgradeRunResponse` |+| `astryx --json doctor` | `doctor` | `DoctorResponse` |+| any error | — | `CLIError` |+| unsupported command | — | `CLIUnsupportedError` |## Doctordiff --git a/packages/cli/api/component/component.mjs b/packages/cli/api/component/component.mjsindex 3dc1bf420f..c6a9dd536c 100644--- a/packages/cli/api/component/component.mjs+++ b/packages/cli/api/component/component.mjs@@ -164,7 +164,7 @@ export async function component(name, options = {}) {entries.push({name: comp, description: '', import: resolveImportPath(coreDir, comp)});}}- return {type: 'component.brief', data: {[match[0]]: entries}};+ return {type: 'component.list', data: {detail: 'compact', components: {[match[0]]: entries}}};}if (detail === 'full') {@@ -181,7 +181,7 @@ export async function component(name, options = {}) {entries.push({name: `XDS${comp}`, description: ''});}}- return {type: 'component.full', data: {[match[0]]: entries}};+ return {type: 'component.list', data: {detail: 'full', components: {[match[0]]: entries}}};}// Default: brief — package-qualified object list for the category.@@ -189,7 +189,7 @@ export async function component(name, options = {}) {// strings, so consumers can disambiguate ownership.return {type: 'component.list',- data: {[match[0]]: match[1].map(n => ({name: n, package: CORE_PACKAGE}))},+ data: {detail: 'names', components: {[match[0]]: match[1].map(n => ({name: n, package: CORE_PACKAGE}))}},};}@@ -213,7 +213,7 @@ export async function component(name, options = {}) {}}}- return {type: 'component.brief', data: result};+ return {type: 'component.list', data: {detail: 'compact', components: result}};}if (detail === 'full') {@@ -234,7 +234,7 @@ export async function component(name, options = {}) {}}}- return {type: 'component.full', data: result};+ return {type: 'component.list', data: {detail: 'full', components: result}};}// Default: brief — package-qualified object list (core + integrations).@@ -299,7 +299,7 @@ export async function component(name, options = {}) {}}}- return {type: 'component.list', data: listData};+ return {type: 'component.list', data: {detail: 'names', components: listData}};}// ── Single component ───────────────────────────────────────────diff --git a/packages/cli/api/hook/hook.mjs b/packages/cli/api/hook/hook.mjsindex d94cd35253..85c3e35e3f 100644--- a/packages/cli/api/hook/hook.mjs+++ b/packages/cli/api/hook/hook.mjs@@ -85,7 +85,7 @@ export async function hook(name, options = {}) {entries.push({name: hookName, description: '', import: '@astryxdesign/core/hooks'});}}- return {type: 'hook.brief', data: {[match[0]]: entries}};+ return {type: 'hook.list', data: {detail: 'compact', components: {[match[0]]: entries}}};}if (detail === 'full') {@@ -102,11 +102,11 @@ export async function hook(name, options = {}) {entries.push({name: hookName});}}- return {type: 'hook.full', data: {[match[0]]: entries}};+ return {type: 'hook.list', data: {detail: 'full', components: {[match[0]]: entries}}};}- // Default: brief — names only- return {type: 'hook.list', data: {[match[0]]: match[1]}};+ // Default: names only+ return {type: 'hook.list', data: {detail: 'names', components: {[match[0]]: match[1]}}};}// All hooks@@ -133,7 +133,7 @@ export async function hook(name, options = {}) {}}}- return {type: 'hook.brief', data: result};+ return {type: 'hook.list', data: {detail: 'compact', components: result}};}if (detail === 'full') {@@ -154,11 +154,11 @@ export async function hook(name, options = {}) {}}}- return {type: 'hook.full', data: result};+ return {type: 'hook.list', data: {detail: 'full', components: result}};}- // Default: brief — names only- return {type: 'hook.list', data: hooks};+ // Default: names only+ return {type: 'hook.list', data: {detail: 'names', components: hooks}};}// ── Single hook ────────────────────────────────────────────────diff --git a/packages/cli/cli/commands/build-theme.mjs b/packages/cli/cli/commands/build-theme.mjsindex f6581562c3..b0901c4487 100644--- a/packages/cli/cli/commands/build-theme.mjs+++ b/packages/cli/cli/commands/build-theme.mjs@@ -77,8 +77,6 @@ async function runThemeBuildWatch(file, filePath, options) {// Initial build.await runThemeBuildOnceChild(file, options);- humanLog(`\n👀 Watching ${rel} for changes — press Ctrl-C to stop.`);-let building = false;let queued = false;/** @type {ReturnType<typeof setTimeout> | undefined} */@@ -113,6 +111,11 @@ async function runThemeBuildWatch(file, filePath, options) {debounce = setTimeout(rebuild, 100);});+ // Announce readiness only AFTER fs.watch is armed — the log is the "safe to+ // edit" signal (tests and humans rely on it), so printing it before the watch+ // is registered would race: a change in that gap is silently missed.+ humanLog(`\n👀 Watching ${rel} for changes — press Ctrl-C to stop.`);+await new Promise((/** @type {(value?: void) => void} */ resolve) => {const stop = () => {clearTimeout(debounce);diff --git a/packages/cli/cli/commands/build-theme.watch.test.mjs b/packages/cli/cli/commands/build-theme.watch.test.mjsindex a051487317..70110ee6dc 100644--- a/packages/cli/cli/commands/build-theme.watch.test.mjs+++ b/packages/cli/cli/commands/build-theme.watch.test.mjs@@ -111,23 +111,33 @@ describe('theme build --watch', () => {expect(firstCss).toMatch(/#ffffff/);// Wait until the watcher is actually watching before editing, so the- // change isn't missed.+ // change isn't missed. The "Watching" line is printed only after fs.watch+ // is armed, so it's a truthful "safe to edit now" signal.await waitFor(() => /Watching/i.test(stdout));// Change the theme — the token value changes so the CSS must change.- fs.writeFileSync(- themeFile,- `export default { name: 'wt', tokens: { '--color-bg': '#010203' } };\n`,- );-- // The rebuilt CSS should reflect the new value.- const rebuilt = await waitFor(() => {- try {- return fs.readFileSync(cssFile, 'utf-8').includes('#010203');- } catch {+ // fs.watch event delivery is best-effort on some platforms/under load, so+ // re-touch the file until the rebuild is observed (idempotent write).+ const changed = `export default { name: 'wt', tokens: { '--color-bg': '#010203' } };\n`;+ fs.writeFileSync(themeFile, changed);++ const rebuilt = await waitFor(+ () => {+ try {+ if (fs.readFileSync(cssFile, 'utf-8').includes('#010203')) return true;+ } catch {+ // CSS mid-write; fall through to re-touch.+ }+ // Re-touch to recover a dropped watch event under load.+ try {+ fs.writeFileSync(themeFile, changed);+ } catch {+ // Re-touch failed (e.g. dir mid-teardown); the next poll retries.+ }return false;- }- });+ },+ {timeout: 20000, interval: 200},+ );expect(rebuilt).toBe(true);expect(stdout).toMatch(/rebuild/i);} finally {diff --git a/packages/cli/cli/commands/component-ownership.test.mjs b/packages/cli/cli/commands/component-ownership.test.mjsindex 1bd52c14c6..e0fdf7923d 100644--- a/packages/cli/cli/commands/component-ownership.test.mjs+++ b/packages/cli/cli/commands/component-ownership.test.mjs@@ -27,6 +27,13 @@ vi.mock('../../lib/project.mjs', () => ({// Import the api AFTER the mock is registered.const {component} = await import('../../api/component/component.mjs');+// These are real-filesystem integration tests: each `component()` call scans+// the entire core library (recursive readdir + hundreds of existsSync probes).+// Under saturated parallel CI workers that I/O gets starved and can exceed the+// 5s default, surfacing as a spurious timeout. Size the budget to the work, as+// detail-levels.test.mjs already does for its discovery beforeAll.+vi.setConfig({testTimeout: 30_000, hookTimeout: 30_000});+let tmpDir;const INTEGRATION_NAME = '@test/meta';@@ -214,7 +221,8 @@ describe('component() — integration ownership via config', () => {createFixture();const result = await component(undefined, {cwd: tmpDir, list: true});expect(result.type).toBe('component.list');- const allEntries = Object.values(result.data).flat();+ expect(result.data.detail).toBe('names');+ const allEntries = Object.values(result.data.components).flat();for (const entry of allEntries) {expect(typeof entry.name).toBe('string');expect(typeof entry.package).toBe('string');diff --git a/packages/cli/cli/commands/component/index.mjs b/packages/cli/cli/commands/component/index.mjsindex 768b007c70..a61028692e 100644--- a/packages/cli/cli/commands/component/index.mjs+++ b/packages/cli/cli/commands/component/index.mjs@@ -34,8 +34,6 @@ import {warnOnIntegrationIssues} from '../../../lib/integration-warnings.mjs';** @typedef {(* | import('../../../types/component').ComponentListResponse- * | import('../../../types/component').ComponentBriefResponse- * | import('../../../types/component').ComponentFullResponse* | import('../../../types/component').ComponentDetailResponse* | import('../../../types/component').ComponentDetailPropsResponse* | import('../../../types/component').ComponentDetailSourceResponse@@ -118,16 +116,48 @@ export function registerComponent(program) {switch (result.type) {case 'component.list': {- // --detail brief (default for list views). The API now returns+ // One list type across all three detail levels; the depth is carried+ // in result.data.detail and the grouped map in result.data.components.+ if (result.data.detail === 'full') {+ // --detail full — dense per-component docs (signature, props, theming, examples).+ humanLog(await formatBriefAll(coreDir, {zh, lang, themeData}));+ break;+ }++ if (result.data.detail === 'compact') {+ // --detail compact — name + 1-line description per entry.+ const groups = result.data.components;+ humanLog('');+ const entries = Object.entries(groups);+ for (const [cat, items] of entries) {+ // Skip the synthetic group header when there's only one ungrouped category+ const isUngrouped =+ entries.length === 1 && items.length === 1 && items[0]?.name === cat;+ if (!isUngrouped) humanLog(`${cat} (group)`);+ for (const item of items) {+ const importHint = item.import ? ` ← ${item.import}` : '';+ const desc = item.description ? ` — ${item.description}` : '';+ humanLog(` XDS${item.name}${importHint}${desc}`);+ }+ humanLog('');+ }+ humanLog(`Import from the path shown (e.g. import {Button} from '@astryxdesign/core/Button')`);+ humanLog(`Usage: ${run} component <name>`);+ humanLog('');+ break;+ }++ // --detail names (default for list views). The API now returns// package-qualified entries ({name, package}); the human view omits// the core package label for readability but ALWAYS shows the package// for integration components (and whenever names collide).+ const groups = result.data.components;const CORE_PKG = '@astryxdesign/core';// Names that appear under more than one package across the whole// listing — these must always be package-qualified to disambiguate./** @type {Map<string, Set<string>>} */const nameCounts = new Map();- for (const items of Object.values(result.data)) {+ for (const items of Object.values(groups)) {for (const item of items) {const set = nameCounts.get(item.name) ?? new Set();set.add(item.package);@@ -144,7 +174,7 @@ export function registerComponent(program) {};if (options.category) {- const [cat, comps] = Object.entries(result.data)[0];+ const [cat, comps] = Object.entries(groups)[0];humanLog(`\n${cat}:`);for (const item of comps) {const importPath = resolveImportPath(coreDir, item.name);@@ -153,7 +183,7 @@ export function registerComponent(program) {humanLog('');} else {humanLog('');- for (const [key, comps] of Object.entries(result.data)) {+ for (const [key, comps] of Object.entries(groups)) {const isUngrouped = comps.length === 1 && comps[0]?.name === key;if (isUngrouped) {const item = comps[0];@@ -175,34 +205,6 @@ export function registerComponent(program) {break;}- case 'component.brief': {- // --detail compact — name + 1-line description per entry.- humanLog('');- const entries = Object.entries(result.data);- for (const [cat, items] of entries) {- // Skip the synthetic group header when there's only one ungrouped category- const isUngrouped =- entries.length === 1 && items.length === 1 && items[0]?.name === cat;- if (!isUngrouped) humanLog(`${cat} (group)`);- for (const item of items) {- const importHint = item.import ? ` ← ${item.import}` : '';- const desc = item.description ? ` — ${item.description}` : '';- humanLog(` XDS${item.name}${importHint}${desc}`);- }- humanLog('');- }- humanLog(`Import from the path shown (e.g. import {Button} from '@astryxdesign/core/Button')`);- humanLog(`Usage: ${run} component <name>`);- humanLog('');- break;- }-- case 'component.full': {- // --detail full — dense per-component docs (signature, props, theming, examples).- humanLog(await formatBriefAll(coreDir, {zh, lang, themeData}));- break;- }-case 'component.detail': {if (detail === 'brief') {const resolvedName = (name || '').replace(/^XDS/, '');diff --git a/packages/cli/cli/commands/detail-levels.test.mjs b/packages/cli/cli/commands/detail-levels.test.mjsindex e0bf7c5731..3a08c8e886 100644--- a/packages/cli/cli/commands/detail-levels.test.mjs+++ b/packages/cli/cli/commands/detail-levels.test.mjs@@ -69,13 +69,23 @@ describe('--detail level ordering: component --list', () => {expect(full).toMatch(/children/);});- it('full --json returns a valid component.full envelope', async () => {- const {stdout} = await runCli(['component', '--list', '--detail', 'full', '--json'], REPO_ROOT);- const parsed = JSON.parse(stdout);- expect(parsed.type).toBe('component.full');- expect(parsed.apiVersion).toBe(1);- expect(typeof parsed.data).toBe('object');- });+ it('--json list emits one component.list type across all detail levels, tagged by data.detail', async () => {+ const names = JSON.parse((await runCli(['component', '--list', '--json'], REPO_ROOT)).stdout);+ expect(names.type).toBe('component.list');+ expect(names.apiVersion).toBe(1);+ expect(names.data.detail).toBe('names');+ expect(typeof names.data.components).toBe('object');++ const compact = JSON.parse((await runCli(['component', '--list', '--detail', 'compact', '--json'], REPO_ROOT)).stdout);+ expect(compact.type).toBe('component.list');+ expect(compact.data.detail).toBe('compact');+ expect(typeof compact.data.components).toBe('object');++ const full = JSON.parse((await runCli(['component', '--list', '--detail', 'full', '--json'], REPO_ROOT)).stdout);+ expect(full.type).toBe('component.list');+ expect(full.data.detail).toBe('full');+ expect(typeof full.data.components).toBe('object');+ }, 60_000);});describe('--detail level ordering: hook --list', () => {@@ -113,11 +123,21 @@ describe('--detail level ordering: hook --list', () => {expect(full).toMatch(/import \{/);});- it('full --json returns a valid hook.full envelope', async () => {- const {stdout} = await runCli(['hook', '--list', '--detail', 'full', '--json'], REPO_ROOT);- const parsed = JSON.parse(stdout);- expect(parsed.type).toBe('hook.full');- expect(parsed.apiVersion).toBe(1);- expect(typeof parsed.data).toBe('object');- });+ it('--json list emits one hook.list type across all detail levels, tagged by data.detail', async () => {+ const names = JSON.parse((await runCli(['hook', '--list', '--json'], REPO_ROOT)).stdout);+ expect(names.type).toBe('hook.list');+ expect(names.apiVersion).toBe(1);+ expect(names.data.detail).toBe('names');+ expect(typeof names.data.components).toBe('object');++ const compact = JSON.parse((await runCli(['hook', '--list', '--detail', 'compact', '--json'], REPO_ROOT)).stdout);+ expect(compact.type).toBe('hook.list');+ expect(compact.data.detail).toBe('compact');+ expect(typeof compact.data.components).toBe('object');++ const full = JSON.parse((await runCli(['hook', '--list', '--detail', 'full', '--json'], REPO_ROOT)).stdout);+ expect(full.type).toBe('hook.list');+ expect(full.data.detail).toBe('full');+ expect(typeof full.data.components).toBe('object');+ }, 60_000);});diff --git a/packages/cli/cli/commands/hook/index.mjs b/packages/cli/cli/commands/hook/index.mjsindex b039dc49d7..31fe0d5a66 100644--- a/packages/cli/cli/commands/hook/index.mjs+++ b/packages/cli/cli/commands/hook/index.mjs@@ -26,8 +26,6 @@ import {findRelatedBlocks} from '../../../api/template/template.mjs';** @typedef {(* | import('../../../types/hook').HookListResponse- * | import('../../../types/hook').HookBriefResponse- * | import('../../../types/hook').HookFullResponse* | import('../../../types/hook').HookDetailResponse* | import('../../../types/hook').HookDetailParamsResponse* )} HookResult@@ -85,15 +83,50 @@ export function registerHook(program) {// ── Text output ────────────────────────────────────────────switch (result.type) {case 'hook.list': {- // --detail brief (default for list views) — names only.+ // One list type across all three detail levels; the depth is carried+ // in result.data.detail and the grouped map in result.data.components.+ if (result.data.detail === 'full') {+ // --detail full — dense per-hook docs grouped by category+ // (import block, best practices, full params + returns tables, related).+ const groups = result.data.components;+ humanLog('');+ for (const [cat, items] of Object.entries(groups)) {+ humanLog(`## ${cat}\n`);+ for (const item of items) {+ const importPath = item.importPath || '@astryxdesign/core/hooks';+ humanLog(formatHookCompact(item, importPath));+ }+ }+ break;+ }++ if (result.data.detail === 'compact') {+ // --detail compact — name + 1-line description per entry.+ const groups = result.data.components;+ humanLog('');+ for (const [cat, items] of Object.entries(groups)) {+ humanLog(cat);+ for (const item of items) {+ const desc = item.description ? ` — ${item.description}` : '';+ humanLog(` ${item.name}${desc}`);+ }+ humanLog('');+ }+ humanLog(`Usage: ${run} hook <name>`);+ humanLog('');+ break;+ }++ // --detail names (default for list views) — names only.+ const groups = result.data.components;if (options.category) {- const [cat, hookNames] = Object.entries(result.data)[0];+ const [cat, hookNames] = Object.entries(groups)[0];humanLog(`\n${cat}:`);for (const h of hookNames) humanLog(` ${h}`);humanLog('');} else {humanLog('');- for (const [category, hookNames] of Object.entries(result.data)) {+ for (const [category, hookNames] of Object.entries(groups)) {humanLog(category);for (const h of hookNames) humanLog(` ${h}`);}@@ -104,36 +137,6 @@ export function registerHook(program) {break;}- case 'hook.brief': {- // --detail compact — name + 1-line description per entry.- humanLog('');- for (const [cat, items] of Object.entries(result.data)) {- humanLog(cat);- for (const item of items) {- const desc = item.description ? ` — ${item.description}` : '';- humanLog(` ${item.name}${desc}`);- }- humanLog('');- }- humanLog(`Usage: ${run} hook <name>`);- humanLog('');- break;- }-- case 'hook.full': {- // --detail full — dense per-hook docs grouped by category- // (import block, best practices, full params + returns tables, related).- humanLog('');- for (const [cat, items] of Object.entries(result.data)) {- humanLog(`## ${cat}\n`);- for (const item of items) {- const importPath = item.importPath || '@astryxdesign/core/hooks';- humanLog(formatHookCompact(item, importPath));- }- }- break;- }-case 'hook.detail': {if (detail === 'brief') {humanLog(formatHookBrief(result.data));diff --git a/packages/cli/lib/manifest.mjs b/packages/cli/lib/manifest.mjsindex 41ddcead35..b5ada4da6b 100644--- a/packages/cli/lib/manifest.mjs+++ b/packages/cli/lib/manifest.mjs@@ -48,8 +48,6 @@ import {API_VERSION} from './json.mjs';export const RESPONSE_TYPES = {component: ['component.list',- 'component.brief',- 'component.full','component.detail','component.detail.props','component.detail.source',@@ -68,7 +66,7 @@ export const RESPONSE_TYPES = {'template.skeleton','template.copy',],- hook: ['hook.list', 'hook.brief', 'hook.full', 'hook.detail', 'hook.detail.params'],+ hook: ['hook.list', 'hook.detail', 'hook.detail.params'],'theme build': ['theme.build'],'theme list': ['theme.list'],'theme add': ['theme.list', 'theme.add'],diff --git a/packages/cli/types/api.d.ts b/packages/cli/types/api.d.tsindex 6b8306d2a4..0fcf1df118 100644--- a/packages/cli/types/api.d.ts+++ b/packages/cli/types/api.d.ts@@ -9,8 +9,6 @@import type {ComponentListResponse,- ComponentBriefResponse,- ComponentFullResponse,ComponentDetailResponse,ComponentDetailPropsResponse,ComponentDetailSourceResponse,@@ -36,8 +34,6 @@ import type {} from './template';import type {HookListResponse,- HookBriefResponse,- HookFullResponse,HookDetailResponse,HookDetailParamsResponse,} from './hook';@@ -93,8 +89,6 @@ export interface ComponentOptions {type ComponentResult =| ComponentListResponse- | ComponentBriefResponse- | ComponentFullResponse| ComponentDetailResponse| ComponentDetailPropsResponse| ComponentDetailSourceResponse@@ -180,11 +174,7 @@ export interface HookOptions {}type HookResult =- | HookListResponse- | HookBriefResponse- | HookFullResponse- | HookDetailResponse- | HookDetailParamsResponse;+ HookListResponse | HookDetailResponse | HookDetailParamsResponse;export declare function hook(name?: string,diff --git a/packages/cli/types/component.d.ts b/packages/cli/types/component.d.tsindex d2cdaa2a15..92bcd15940 100644--- a/packages/cli/types/component.d.ts+++ b/packages/cli/types/component.d.ts@@ -10,11 +10,11 @@** Invocation -> type discriminator* ------------------------------------------------------------------- * xds --json component -> component.list- * xds --json component --list -> component.list+ * xds --json component -> component.list (data.detail='names')+ * xds --json component --list -> component.list (data.detail='names')* xds --json component --category Form -> component.list (filtered)- * xds --json component --list --detail compact -> component.brief- * xds --json component --list --detail full -> component.full+ * xds --json component --list --detail compact -> component.list (data.detail='compact')+ * xds --json component --list --detail full -> component.list (data.detail='full')* xds --json component Button -> component.detail* xds --json component Button --props -> component.detail.props* xds --json component Button --source -> component.detail.source@@ -25,16 +25,31 @@import type {ComponentDoc, PropDoc} from '../../core/src/docs-types';-/** xds --json component [--list] [--category X] [--detail brief] */+/**+ * xds --json component [--list] [--category X] [--detail names|compact|full]+ *+ * The list view emits ONE `component.list` type across all three detail levels;+ * the depth is carried in `data.detail` and `data.components` holds the grouped+ * map whose entry shape depends on that level:+ * - 'names' -> ComponentListEntry[] (name + owner package)+ * - 'compact' -> ComponentBriefEntry[] (name + 1-line description + import)+ * - 'full' -> ComponentDoc[] (full authored doc per entry)+ */export interface ComponentListResponse {type: 'component.list';- data: Record<string, ComponentListEntry[]>;+ data: ComponentListData;}+/** Detail-tagged payload for `component.list` (discriminated on `detail`). */+export type ComponentListData =+ | {detail: 'names'; components: Record<string, ComponentListEntry[]>}+ | {detail: 'compact'; components: Record<string, ComponentBriefEntry[]>}+ | {detail: 'full'; components: Record<string, ComponentDoc[]>};+/**- * A single entry in a `component.list` group. Pre-1.0 the list moved from bare- * strings to package-qualified objects so consumers can disambiguate ownership- * (core vs. an integration package).+ * A single entry in a `component.list` group at `detail: 'names'`. Pre-1.0 the+ * list moved from bare strings to package-qualified objects so consumers can+ * disambiguate ownership (core vs. an integration package).*/export interface ComponentListEntry {name: string;@@ -42,24 +57,13 @@ export interface ComponentListEntry {package: string;}-/** xds --json component --list --detail compact */-export interface ComponentBriefResponse {- type: 'component.brief';- data: Record<string, ComponentBriefEntry[]>;-}-+/** A single entry in a `component.list` group at `detail: 'compact'`. */export interface ComponentBriefEntry {name: string;description: string;import: string;}-/** xds --json component --list --detail full */-export interface ComponentFullResponse {- type: 'component.full';- data: Record<string, ComponentDoc[]>;-}-/** xds --json component <name> */export interface ComponentDetailResponse {type: 'component.detail';diff --git a/packages/cli/types/hook.d.ts b/packages/cli/types/hook.d.tsindex 0c4ea4c80b..25b794d0b3 100644--- a/packages/cli/types/hook.d.ts+++ b/packages/cli/types/hook.d.ts@@ -10,11 +10,11 @@** Invocation -> type discriminator* ------------------------------------------------------------------- * xds --json hook -> hook.list- * xds --json hook --list -> hook.list+ * xds --json hook -> hook.list (data.detail='names')+ * xds --json hook --list -> hook.list (data.detail='names')* xds --json hook --category State -> hook.list (filtered)- * xds --json hook --list --detail compact -> hook.brief- * xds --json hook --list --detail full -> hook.full+ * xds --json hook --list --detail compact -> hook.list (data.detail='compact')+ * xds --json hook --list --detail full -> hook.list (data.detail='full')* xds --json hook useMediaQuery -> hook.detail* xds --json hook useMediaQuery --params -> hook.detail.params* (not found) -> CLIError@@ -22,30 +22,34 @@import type {HookDoc, HookParamDoc} from '../../core/src/docs-types';-/** xds --json hook [--list] [--category X] [--detail brief] */+/**+ * xds --json hook [--list] [--category X] [--detail names|compact|full]+ *+ * The list view emits ONE `hook.list` type across all three detail levels; the+ * depth is carried in `data.detail` and `data.components` holds the grouped map+ * whose entry shape depends on that level:+ * - 'names' -> string[] (hook names only)+ * - 'compact' -> HookBriefEntry[] (name + 1-line description + import)+ * - 'full' -> HookDoc[] (full authored doc per entry)+ */export interface HookListResponse {type: 'hook.list';- data: Record<string, string[]>;+ data: HookListData;}-/** xds --json hook --list --detail compact */-export interface HookBriefResponse {- type: 'hook.brief';- data: Record<string, HookBriefEntry[]>;-}+/** Detail-tagged payload for `hook.list` (discriminated on `detail`). */+export type HookListData =+ | {detail: 'names'; components: Record<string, string[]>}+ | {detail: 'compact'; components: Record<string, HookBriefEntry[]>}+ | {detail: 'full'; components: Record<string, HookDoc[]>};+/** A single entry in a `hook.list` group at `detail: 'compact'`. */export interface HookBriefEntry {name: string;description: string;import: string;}-/** xds --json hook --list --detail full */-export interface HookFullResponse {- type: 'hook.full';- data: Record<string, HookDoc[]>;-}-/** xds --json hook <name> */export interface HookDetailResponse {type: 'hook.detail';