Skip to content

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.md
new file mode 100644
index 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.
+
+@josephfarina
diff --git a/.github/scripts/api-cli-parity-test.mjs b/.github/scripts/api-cli-parity-test.mjs
index 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.mjs
index 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.l
const 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.md
index de8dd6c395..ba84ace6e8 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -361,41 +361,37 @@ detail.data.name; // narrowed
Every 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` |
## Doctor
diff --git a/packages/cli/api/component/component.mjs b/packages/cli/api/component/component.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.ts
index 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.ts
index 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.ts
index 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';