An open source design system that's fully customizable and agent ready
TypeScript
fix(cli): make check:cli-structure enforce the command file layout (#6515)
Joeyc5e01c026af4
diff --git a/.changeset/cli-command-layout-check.md b/.changeset/cli-command-layout-check.mdnew file mode 100644index 0000000000..cce65eaa47--- /dev/null+++ b/.changeset/cli-command-layout-check.md@@ -0,0 +1,7 @@+---+'@astryxdesign/cli': patch+---++[docs] `astryx docs cli/commands/postinstall` now documents the hidden `postinstall` hook, `astryx docs cli/commands` lists it, and `astryx postinstall --help` shows its exit code and an example. The summary of `astryx docs cli/commands/manifest` (text and `--json`) drops its final period, so it matches the description the manifest has always printed. What each command prints when it runs, its JSON and its exit codes are unchanged.++@josephfarinadiff --git a/apps/sandbox/scripts/generate-cli-registry.mjs b/apps/sandbox/scripts/generate-cli-registry.mjsindex 2f479bf728..b61fbc65ca 100644--- a/apps/sandbox/scripts/generate-cli-registry.mjs+++ b/apps/sandbox/scripts/generate-cli-registry.mjs@@ -38,12 +38,12 @@ programconst commandModules = [{name: 'init', path: './commands/init.mjs', register: 'registerInit'},- {name: 'component', path: './commands/component/index.mjs', register: 'registerComponent'},+ {name: 'component', path: './commands/component.mjs', register: 'registerComponent'},{name: 'docs', path: './commands/docs.mjs', register: 'registerDocs'},{name: 'swizzle', path: './commands/swizzle.mjs', register: 'registerSwizzle'},{name: 'template', path: './commands/template.mjs', register: 'registerTemplate'},{name: 'upgrade', path: './commands/upgrade.mjs', register: 'registerUpgrade'},- {name: 'theme', path: './commands/build-theme.mjs', register: 'registerTheme'},+ {name: 'theme', path: './commands/theme.mjs', register: 'registerTheme'},{name: 'discover', path: './commands/discover.mjs', register: 'registerDiscover'},];diff --git a/eslint.config.js b/eslint.config.jsindex 9b04cba5f3..422479140a 100644--- a/eslint.config.js+++ b/eslint.config.js@@ -794,7 +794,7 @@ export default defineConfig(// still fails there.{files: [- 'packages/cli/clients/cli/commands/build-theme.mjs',+ 'packages/cli/clients/cli/commands/theme.mjs','packages/cli/clients/cli/commands/docs.mjs',],rules: {diff --git a/packages/cli/CONTRIBUTING.md b/packages/cli/CONTRIBUTING.mdindex 3b86d458f2..e0718ee437 100644--- a/packages/cli/CONTRIBUTING.md+++ b/packages/cli/CONTRIBUTING.md@@ -10,7 +10,7 @@ The CLI is a thin wrapper around type-safe API functions. Each command follows tUser calls API function User runs CLI| |v v- api/component/component.mjs ◄─ clients/cli/commands/component/index.mjs+ api/component/component.mjs ◄─ clients/cli/commands/component.mjs| |v v{ type, data } jsonOut(response) or formatText(data)diff --git a/packages/cli/api/component/component.mjs b/packages/cli/api/component/component.mjsindex fca536856d..3207cb5b57 100644--- a/packages/cli/api/component/component.mjs+++ b/packages/cli/api/component/component.mjs@@ -293,7 +293,7 @@ async function componentRead(name, options = {}) {const selectorList = Array.isArray(name) ? name : null;const noName = selectorList == null && !name;- // Default detail level mirrors the CLI (see commands/component/index.mjs):+ // Default detail level mirrors the CLI (see commands/component.mjs):// single-component views default to 'full', list-style views (--list,// --category, or no name) default to 'brief' (scannable name lists).// An explicit array remains a batch even when it is empty or a caller alsodiff --git a/packages/cli/api/hook/hook.mjs b/packages/cli/api/hook/hook.mjsindex 58c8360bcc..e92ebd0199 100644--- a/packages/cli/api/hook/hook.mjs+++ b/packages/cli/api/hook/hook.mjs@@ -43,7 +43,7 @@ export async function hook(name, options = {}) {zh = false,} = options;- // Default detail level mirrors the CLI (see commands/hook/index.mjs):+ // Default detail level mirrors the CLI (see commands/hook.mjs):// single-hook views default to 'full', list-style views (--list,// --category, or no name) default to 'brief' (scannable name lists).// Keeping this in sync with the CLI is what the API↔CLI parity test checks.diff --git a/packages/cli/clients/cli/command-result-coverage.test.mjs b/packages/cli/clients/cli/command-result-coverage.test.mjsindex ab457839e4..4dc3f085ff 100644--- a/packages/cli/clients/cli/command-result-coverage.test.mjs+++ b/packages/cli/clients/cli/command-result-coverage.test.mjs@@ -44,12 +44,13 @@ const NO_ACTION_OF_THEIR_OWN = [];/*** Commands that record for themselves instead of returning a descriptor.*- * They cannot come from a CommandDoc — `manifest` introspects the live program,- * `postinstall` is a package-script hook — so they carry the mark by hand. The- * mark is a hatch, and a hatch nobody watches is a hole: this list is the- * watch. The root program is checked separately below.+ * Empty: every command, `manifest` and the hidden `postinstall` hook included,+ * registers through defineCommand. The mark is a hatch, and a hatch nobody+ * watches is a hole: this list is the watch. The root program is checked+ * separately below.+ * @type {string[]}*/-const RECORD_FOR_THEMSELVES = ['manifest', 'postinstall'];+const RECORD_FOR_THEMSELVES = [];/*** Every command in the program, depth first, with its fully qualified name.diff --git a/packages/cli/clients/cli/commands/build-theme.color-scheme.test.mjs b/packages/cli/clients/cli/commands/build-theme.color-scheme.test.mjsindex fc314f4cbc..c964785554 100644--- a/packages/cli/clients/cli/commands/build-theme.color-scheme.test.mjs+++ b/packages/cli/clients/cli/commands/build-theme.color-scheme.test.mjs@@ -73,7 +73,7 @@ describe('theme build color-scheme output', () => {const project = path.join(tmpDir, 'project');const themesDir = path.join(project, 'themes');// A raw light-dark() token value is what triggers the color-scheme- // injection in build-theme.mjs. `defineTheme.test.ts` already covers the+ // injection in theme.mjs. `defineTheme.test.ts` already covers the// separate [light, dark] tuple -> light-dark() conversion; this fixture// writes the string directly so this test stays focused on the CLI's own// color-scheme decision, not on that conversion.diff --git a/packages/cli/clients/cli/commands/component/index.mjs b/packages/cli/clients/cli/commands/component.mjssimilarity index 85%rename from packages/cli/clients/cli/commands/component/index.mjsrename to packages/cli/clients/cli/commands/component.mjsindex e96244b08b..7b5f64a0d3 100644--- a/packages/cli/clients/cli/commands/component/index.mjs+++ b/packages/cli/clients/cli/commands/component.mjs@@ -6,30 +6,30 @@* Global options: --detail full|compact|brief, --lang en|zh|dense*/-import {findCoreDir} from '../../../../foundation/fs/paths.mjs';+import {findCoreDir} from '../../../foundation/fs/paths.mjs';import {resolveImportPath,-} from '../../../../foundation/discovery/component-discovery.mjs';+} from '../../../foundation/discovery/component-discovery.mjs';import {formatFull,formatCompact,formatBrief,formatProps,formatBriefAll,-} from '../../lib/component-format.mjs';-import {resolveTheme} from '../../lib/resolve-theme.mjs';-import {getCliInvocation} from '../../../../foundation/env/package-manager.mjs';-import {jsonOut} from '../../../../foundation/response/json.mjs';-import {emit, section, text, list, record, records, code} from '../../formatters/index.mjs';-import {cliError} from '../../lib/cli-error.mjs';-import {defineCommand} from '../../lib/define-command.mjs';-import {resultSet} from '../../../../foundation/debug/index.mjs';-import {ERROR_CODES} from '../../../../foundation/response/error-codes.mjs';-import {component as componentApi} from '../../../../api/component/component.mjs';-import {Project} from '../../../../foundation/config/project.mjs';-import {warnOnIntegrationIssues} from '../../../../foundation/integrations/integration-warnings.mjs';-import {doc as componentCommand} from '../component.doc.mjs';-import {doc as componentFn} from '../../../../api/component/component.doc.mjs';+} from '../lib/component-format.mjs';+import {resolveTheme} from '../lib/resolve-theme.mjs';+import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';+import {jsonOut} from '../../../foundation/response/json.mjs';+import {emit, section, text, list, record, records, code} from '../formatters/index.mjs';+import {cliError} from '../lib/cli-error.mjs';+import {defineCommand} from '../lib/define-command.mjs';+import {resultSet} from '../../../foundation/debug/index.mjs';+import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';+import {component as componentApi} from '../../../api/component/component.mjs';+import {Project} from '../../../foundation/config/project.mjs';+import {warnOnIntegrationIssues} from '../../../foundation/integrations/integration-warnings.mjs';+import {doc as componentCommand} from './component.doc.mjs';+import {doc as componentFn} from '../../../api/component/component.doc.mjs';/*** The api layer's component() widens its return to `{type: string, data: unknown}`,@@ -37,13 +37,13 @@ import {doc as componentFn} from '../../../../api/component/component.doc.mjs';* src/types/component to get narrowing + typed data.** @typedef {(- * | import('../../../../api/component/component.type.mjs').ComponentListResponse- * | import('../../../../api/component/component.type.mjs').ComponentBatchResponse- * | import('../../../../api/component/component.type.mjs').ComponentDetailResponse- * | import('../../../../api/component/component.type.mjs').ComponentDetailPropsResponse- * | import('../../../../api/component/component.type.mjs').ComponentDetailSourceResponse- * | import('../../../../api/component/component.type.mjs').ComponentDetailShowcaseResponse- * | import('../../../../api/component/component.type.mjs').ComponentDetailBlocksResponse+ * | import('../../../api/component/component.type.mjs').ComponentListResponse+ * | import('../../../api/component/component.type.mjs').ComponentBatchResponse+ * | import('../../../api/component/component.type.mjs').ComponentDetailResponse+ * | import('../../../api/component/component.type.mjs').ComponentDetailPropsResponse+ * | import('../../../api/component/component.type.mjs').ComponentDetailSourceResponse+ * | import('../../../api/component/component.type.mjs').ComponentDetailShowcaseResponse+ * | import('../../../api/component/component.type.mjs').ComponentDetailBlocksResponse* )} ComponentResult*/@@ -57,7 +57,7 @@ import {doc as componentFn} from '../../../../api/component/component.doc.mjs';* the thing that resolved (the component) is not the thing being counted.** @param {ComponentResult} result- * @returns {import('../../../../foundation/debug/command-result.mjs').CommandResult}+ * @returns {import('../../../foundation/debug/command-result.mjs').CommandResult}*/function summarize(result) {switch (result.type) {@@ -90,11 +90,11 @@ function summarize(result) {/*** Project one single-component API result through the existing formatter kit.- * @param {import('../../../../api/component/component.type.mjs').ComponentSingleResponse} result+ * @param {import('../../../api/component/component.type.mjs').ComponentSingleResponse} result* @param {string} requestedName* @param {'full'|'compact'|'brief'} detail* @param {Awaited<ReturnType<typeof resolveTheme>>} themeData- * @returns {import('../../formatters/index.mjs').Block[]}+ * @returns {import('../formatters/index.mjs').Block[]}*/function componentDetailBlocks(result, requestedName, detail, themeData) {const requested = (requestedName.split('/').pop() ?? requestedName).replace(@@ -111,7 +111,7 @@ function componentDetailBlocks(result, requestedName, detail, themeData) {: requested;switch (result.type) {case 'component.detail': {- /** @type {import('../../formatters/index.mjs').Block[]} */+ /** @type {import('../formatters/index.mjs').Block[]} */const out = [record({package: result.package})];if (result.data.parentDoc) {out.push(record(result.data, {fields: ['parentDoc']}));@@ -150,7 +150,7 @@ function componentDetailBlocks(result, requestedName, detail, themeData) {/** @param {{package: string}} block @param {string} label */const owned = (block, label) =>block.package === result.package ? label : `${label} (${block.package})`;- /** @type {import('../../formatters/index.mjs').Block[]} */+ /** @type {import('../formatters/index.mjs').Block[]} */const out = [record({package: result.package})];if (showcase) {out.push(@@ -243,7 +243,7 @@ export function registerComponent(program) {lang, zh, dense,}));} catch (e) {- const err = /** @type {import('../../../../api/error.mjs').AstryxError} */ (e);+ const err = /** @type {import('../../../api/error.mjs').AstryxError} */ (e);return cliError(err.message, {suggestions: err.suggestions, code: err.code});}@@ -326,7 +326,7 @@ export function registerComponent(program) {// description), grouped by category. Fields mirror the JSON keys.const groups = result.data.components;const entries = Object.entries(groups);- /** @type {import('../../formatters/index.mjs').Block[]} */+ /** @type {import('../formatters/index.mjs').Block[]} */const out = [];for (const [cat, items] of entries) {// Skip the synthetic group header when there's only one ungrouped category@@ -362,7 +362,7 @@ export function registerComponent(program) {nameCounts.set(item.name, set);}}- /** @param {import('../../../../api/component/component.type.mjs').ComponentListEntry} item */+ /** @param {import('../../../api/component/component.type.mjs').ComponentListEntry} item */const importCell = item => {// Use a precomputed import when the API supplies one (integration// components carry it); only fall back to the core resolver for@@ -392,7 +392,7 @@ export function registerComponent(program) {}case 'component.batch': {- /** @type {import('../../formatters/index.mjs').Block[]} */+ /** @type {import('../formatters/index.mjs').Block[]} */const out = [section('Component batch'),record({count: result.data.count}),@@ -474,8 +474,8 @@ export function registerComponent(program) {// Re-export lib functions for backward compatibility// (agent-docs.mjs, tests, and generate-skill-doc.sh import from here)-export {discoverComponents, discoverExternalComponentsGrouped, findComponentReadme, findComponentSource, findExternalComponentDoc, resolveImportPath} from '../../../../foundation/discovery/component-discovery.mjs';-export {discoverExternalPackages} from '../../../../foundation/fs/paths.mjs';-export {loadDocs} from '../../../../foundation/discovery/component-loader.mjs';-export {formatFull, formatCompact, formatBrief, formatProps, formatBriefAll} from '../../lib/component-format.mjs';-export {levenshteinDistance, findClosestComponents, searchComponents} from '../../../../foundation/text/string-utils.mjs';+export {discoverComponents, discoverExternalComponentsGrouped, findComponentReadme, findComponentSource, findExternalComponentDoc, resolveImportPath} from '../../../foundation/discovery/component-discovery.mjs';+export {discoverExternalPackages} from '../../../foundation/fs/paths.mjs';+export {loadDocs} from '../../../foundation/discovery/component-loader.mjs';+export {formatFull, formatCompact, formatBrief, formatProps, formatBriefAll} from '../lib/component-format.mjs';+export {levenshteinDistance, findClosestComponents, searchComponents} from '../../../foundation/text/string-utils.mjs';diff --git a/packages/cli/clients/cli/commands/component.test.mjs b/packages/cli/clients/cli/commands/component.test.mjsindex 8a59a32be2..e2cd910265 100644--- a/packages/cli/clients/cli/commands/component.test.mjs+++ b/packages/cli/clients/cli/commands/component.test.mjs@@ -12,7 +12,7 @@ import {findComponentSource,levenshteinDistance,findClosestComponents,-} from './component/index.mjs';+} from './component.mjs';import {runCli} from '../../../test-utils/run-cli.mjs';const REPO_ROOT = path.resolve(import.meta.dirname, '../../../../..');@@ -528,7 +528,7 @@ describe('findExternalComponentDoc', () => {describe('searchComponents', () => {it('finds Collapsible when searching "accordion"', async () => {const {searchComponents, discoverComponents} =- await import('./component/index.mjs');+ await import('./component.mjs');const components = discoverComponents('packages/core');const results = await searchComponents('accordion',@@ -542,7 +542,7 @@ describe('searchComponents', () => {it('finds Dialog when searching "modal"', async () => {const {searchComponents, discoverComponents} =- await import('./component/index.mjs');+ await import('./component.mjs');const components = discoverComponents('packages/core');const results = await searchComponents('modal',@@ -556,7 +556,7 @@ describe('searchComponents', () => {it('returns multiple matches for ambiguous terms like "select"', async () => {const {searchComponents, discoverComponents} =- await import('./component/index.mjs');+ await import('./component.mjs');const components = discoverComponents('packages/core');const results = await searchComponents('select',@@ -571,7 +571,7 @@ describe('searchComponents', () => {it('finds exact name matches with score 100', async () => {const {searchComponents, discoverComponents} =- await import('./component/index.mjs');+ await import('./component.mjs');const components = discoverComponents('packages/core');const results = await searchComponents('Button',@@ -584,7 +584,7 @@ describe('searchComponents', () => {it('returns empty array for complete gibberish', async () => {const {searchComponents, discoverComponents} =- await import('./component/index.mjs');+ await import('./component.mjs');const components = discoverComponents('packages/core');const results = await searchComponents('zzzzzzzzzzz',diff --git a/packages/cli/clients/cli/commands/hook/index.mjs b/packages/cli/clients/cli/commands/hook.mjssimilarity index 82%rename from packages/cli/clients/cli/commands/hook/index.mjsrename to packages/cli/clients/cli/commands/hook.mjsindex 41613d93f6..2034ad86a0 100644--- a/packages/cli/clients/cli/commands/hook/index.mjs+++ b/packages/cli/clients/cli/commands/hook.mjs@@ -11,17 +11,17 @@ import {formatHookCompact,formatHookBrief,formatHookParams,-} from '../../lib/hook-format.mjs';-import {getCliInvocation} from '../../../../foundation/env/package-manager.mjs';-import {jsonOut} from '../../../../foundation/response/json.mjs';-import {emit, section, text, list, records, code, record} from '../../formatters/index.mjs';-import {cliError} from '../../lib/cli-error.mjs';-import {defineCommand} from '../../lib/define-command.mjs';-import {resultSet} from '../../../../foundation/debug/index.mjs';-import {ERROR_CODES} from '../../../../foundation/response/error-codes.mjs';-import {hook as hookApi} from '../../../../api/hook/hook.mjs';-import {doc as hookCommand} from '../hook.doc.mjs';-import {doc as hookFn} from '../../../../api/hook/hook.doc.mjs';+} from '../lib/hook-format.mjs';+import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';+import {jsonOut} from '../../../foundation/response/json.mjs';+import {emit, section, text, list, records, code, record} from '../formatters/index.mjs';+import {cliError} from '../lib/cli-error.mjs';+import {defineCommand} from '../lib/define-command.mjs';+import {resultSet} from '../../../foundation/debug/index.mjs';+import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';+import {hook as hookApi} from '../../../api/hook/hook.mjs';+import {doc as hookCommand} from './hook.doc.mjs';+import {doc as hookFn} from '../../../api/hook/hook.doc.mjs';/*** The api layer's hook() widens its return to `{type: string, data: unknown}`,@@ -29,9 +29,9 @@ import {doc as hookFn} from '../../../../api/hook/hook.doc.mjs';* the colocated api/hook/hook.type.mjs to get narrowing + typed data.** @typedef {(- * | import('../../../../api/hook/hook.type.mjs').HookListResponse- * | import('../../../../api/hook/hook.type.mjs').HookDetailResponse- * | import('../../../../api/hook/hook.type.mjs').HookDetailParamsResponse+ * | import('../../../api/hook/hook.type.mjs').HookListResponse+ * | import('../../../api/hook/hook.type.mjs').HookDetailResponse+ * | import('../../../api/hook/hook.type.mjs').HookDetailParamsResponse* )} HookResult*/@@ -40,7 +40,7 @@ import {doc as hookFn} from '../../../../api/hook/hook.doc.mjs';* count is every hook across the groups — names or docs, depending on detail.** @param {HookResult} result- * @returns {import('../../../../foundation/debug/command-result.mjs').CommandResult}+ * @returns {import('../../../foundation/debug/command-result.mjs').CommandResult}*/function summarize(result) {if (result.type === 'hook.list') {@@ -90,7 +90,7 @@ export function registerHook(program) {lang, zh,}));} catch (e) {- const err = /** @type {import('../../../../api/error.mjs').AstryxError} */ (e);+ const err = /** @type {import('../../../api/error.mjs').AstryxError} */ (e);return cliError(err.message, {suggestions: err.suggestions, code: err.code});}@@ -112,7 +112,7 @@ export function registerHook(program) {// The whole view is one markdown document: a `## <category>` heading// over each category's concatenated hook docs.const groups = result.data.components;- /** @type {import('../../formatters/index.mjs').Block[]} */+ /** @type {import('../formatters/index.mjs').Block[]} */const out = [];for (const [cat, items] of Object.entries(groups)) {const body = items@@ -130,7 +130,7 @@ export function registerHook(program) {// --detail compact — one record (name + description) per hook,// grouped by category.const groups = result.data.components;- /** @type {import('../../formatters/index.mjs').Block[]} */+ /** @type {import('../formatters/index.mjs').Block[]} */const out = [];for (const [cat, items] of Object.entries(groups)) {out.push(section(cat), records(items, {fields: ['name', 'description']}));@@ -147,7 +147,7 @@ export function registerHook(program) {const [cat, hookNames] = Object.entries(groups)[0];emit(section(`${cat}:`), list(hookNames));} else {- /** @type {import('../../formatters/index.mjs').Block[]} */+ /** @type {import('../formatters/index.mjs').Block[]} */const out = [];for (const [category, hookNames] of Object.entries(groups)) {out.push(section(category), list(hookNames));@@ -197,12 +197,12 @@ export function registerHook(program) {}// Re-export lib functions for external consumers-export {discoverHooks, findHookDoc, getAllHookNames} from '../../../../foundation/discovery/hook-discovery.mjs';-export {loadDocs} from '../../../../foundation/discovery/component-loader.mjs';+export {discoverHooks, findHookDoc, getAllHookNames} from '../../../foundation/discovery/hook-discovery.mjs';+export {loadDocs} from '../../../foundation/discovery/component-loader.mjs';export {formatHookFull,formatHookCompact,formatHookBrief,formatHookBriefAll,formatHookParams,-} from '../../lib/hook-format.mjs';+} from '../lib/hook-format.mjs';diff --git a/packages/cli/clients/cli/commands/import-hint-correctness.test.mjs b/packages/cli/clients/cli/commands/import-hint-correctness.test.mjsindex fba81765fe..0266faab28 100644--- a/packages/cli/clients/cli/commands/import-hint-correctness.test.mjs+++ b/packages/cli/clients/cli/commands/import-hint-correctness.test.mjs@@ -21,7 +21,7 @@ import {resolveImportPath,discoverComponents,findComponentSource,-} from './component/index.mjs';+} from './component.mjs';import {findCoreDir} from '../../../foundation/fs/paths.mjs';import {runCli} from '../../../test-utils/run-cli.mjs';diff --git a/packages/cli/clients/cli/commands/manifest.doc.mjs b/packages/cli/clients/cli/commands/manifest.doc.mjsindex 5db7b93b4a..53b2194dd6 100644--- a/packages/cli/clients/cli/commands/manifest.doc.mjs+++ b/packages/cli/clients/cli/commands/manifest.doc.mjs@@ -13,7 +13,7 @@ export const doc = {name: 'manifest',displayName: 'astryx manifest',namespace: 'cli/commands',- summary: 'Print the full CLI capability manifest (use with --json).',+ summary: 'Print the full CLI capability manifest (use with --json)',description:'Emits the complete CLI surface: every command with its arguments, options, ' +'subcommands, and JSON response types, as a single typed envelope for agents and ' +diff --git a/packages/cli/clients/cli/commands/manifest.mjs b/packages/cli/clients/cli/commands/manifest.mjsnew file mode 100644index 0000000000..b0640a5059--- /dev/null+++ b/packages/cli/clients/cli/commands/manifest.mjs@@ -0,0 +1,67 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file manifest command — `astryx manifest`, the CLI capability manifest.+ *+ * A single, self-describing view of the whole CLI so agents can discover every+ * command, argument, flag, and response type without scraping `--help`.+ * `astryx manifest --json` is the dedicated surface; the bare `astryx --json`+ * embeds the same payload under data.manifest for convenience.+ *+ * Intentionally CLI-special — no `api/manifest`. It introspects the live+ * Commander `program`, so extracting it to `api/` would create an `api → cli`+ * cycle. `buildManifest(program)` lives in lib/; see its header. Register it+ * after every other command: the manifest lists commands in registration order.+ *+ * The command surface comes from the colocated CommandDoc via `defineCommand`.+ */++import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';+import {jsonOut} from '../../../foundation/response/json.mjs';+import {emit, section, text, records} from '../formatters/index.mjs';+import {buildManifest} from '../lib/manifest.mjs';+import {defineCommand} from '../lib/define-command.mjs';+import {resultSet} from '../../../foundation/debug/index.mjs';+import {doc as manifestCommand} from './manifest.doc.mjs';++/**+ * @param {import('commander').Command} program the root program+ * @param {{jsonSupported: Set<string>, version: string}} context the commands+ * that accept --json, and the CLI's version+ */+export function registerManifest(program, {jsonSupported, version}) {+ defineCommand(program, manifestCommand, {+ action: () => {+ const manifest = buildManifest(program, {jsonSupported, version});+ // The manifest IS a result set: one entry per command the CLI ships.+ const answered = resultSet({+ count: manifest.commands.length,+ resultKind: 'command',+ });+ if (program.opts().json) {+ jsonOut({type: 'manifest', data: manifest});+ return answered;+ }+ // Human-readable summary as greppable records (agents should use --json).+ // One record per command: name, whether it supports --json, and the+ // description. Field names are the manifest entry's own keys.+ emit(+ section(+ `${manifest.name} v${manifest.version} (${manifest.commands.length} commands)`,+ ),+ records(+ manifest.commands.map(c => ({+ name: c.name,+ json: c.json ? 'yes' : '',+ description: c.description || '',+ })),+ {fields: ['name', 'json', 'description']},+ ),+ text(+ `Run \`${getCliInvocation()} manifest --json\` for the full structured manifest.`,+ ),+ );+ return answered;+ },+ });+}diff --git a/packages/cli/clients/cli/commands/postinstall.doc.mjs b/packages/cli/clients/cli/commands/postinstall.doc.mjsnew file mode 100644index 0000000000..f04754d4ec--- /dev/null+++ b/packages/cli/clients/cli/commands/postinstall.doc.mjs@@ -0,0 +1,23 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file CommandDoc for `astryx postinstall`. A hidden, CLI-only hook with no+ * wrapped API function (so no `fn`): it prints the welcome box.+ * @position packages/cli/clients/cli/commands — command documentation+ */++/** @type {import('@astryxdesign/cli/authoring').CommandDoc} */+export const doc = {+ type: 'command',+ name: 'postinstall',+ displayName: 'astryx postinstall',+ namespace: 'cli/commands',+ summary: 'Print the welcome message shown after install',+ description:+ 'Prints a short welcome box that names the first commands to run. It is hidden ' ++ 'from help and the manifest, looks nothing up, and does not support --json.',+ examples: [{label: 'Print the welcome box', cli: 'astryx postinstall'}],+ outsideProject: 'same',+ exitCodes: [{code: 0, when: 'success'}],+ related: ['init'],+};diff --git a/packages/cli/clients/cli/commands/postinstall.mjs b/packages/cli/clients/cli/commands/postinstall.mjsnew file mode 100644index 0000000000..a37a97fd5c--- /dev/null+++ b/packages/cli/clients/cli/commands/postinstall.mjs@@ -0,0 +1,31 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file postinstall command — the hidden `astryx postinstall` hook.+ *+ * Prints the welcome box (lib/welcome-box.mjs). Hidden from help and the+ * manifest; it looks nothing up and does not support --json.+ *+ * The command surface comes from the colocated CommandDoc via `defineCommand`.+ */++import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';+import {emit, code} from '../formatters/index.mjs';+import {defineCommand} from '../lib/define-command.mjs';+import {welcomeBox} from '../lib/welcome-box.mjs';+import {NO_RESULT_SET} from '../../../foundation/debug/index.mjs';+import {doc as postinstallCommand} from './postinstall.doc.mjs';++/**+ * @param {import('commander').Command} program+ */+export function registerPostinstall(program) {+ defineCommand(program, postinstallCommand, {+ hidden: true,+ action: () => {+ emit(code(welcomeBox(getCliInvocation())));+ // Prints the welcome box. Nothing is looked up.+ return NO_RESULT_SET;+ },+ });+}diff --git a/packages/cli/clients/cli/commands/build-theme.mjs b/packages/cli/clients/cli/commands/theme.mjssimilarity index 99%rename from packages/cli/clients/cli/commands/build-theme.mjsrename to packages/cli/clients/cli/commands/theme.mjsindex e9b59fcf70..44174a9c70 100644--- a/packages/cli/clients/cli/commands/build-theme.mjs+++ b/packages/cli/clients/cli/commands/theme.mjs@@ -96,7 +96,7 @@ import {doc as themePaletteGenerateFn} from '../../../api/theme/themePaletteGene/*** Path to this CLI's real entry (clients/cli/bin/astryx.mjs), resolved from- * this module's location (clients/cli/commands/build-theme.mjs → ../bin/+ * this module's location (clients/cli/commands/theme.mjs → ../bin/* astryx.mjs). Used to re-invoke `theme build` as a child process in watch mode.*/function resolveCliBin() {diff --git a/packages/cli/clients/cli/index.mjs b/packages/cli/clients/cli/index.mjsindex 5d9de5ac43..9542a945b4 100644--- a/packages/cli/clients/cli/index.mjs+++ b/packages/cli/clients/cli/index.mjs@@ -26,12 +26,11 @@ import {projectRootOf} from '../../foundation/release/choose.mjs';import {readReleaseFacts} from '../../foundation/release/project.mjs';import {buildManifest} from './lib/manifest.mjs';import {cliError} from './lib/cli-error.mjs';-import {emit, section, text, records} from './formatters/index.mjs';+import {section, text, records} from './formatters/index.mjs';import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';import {levenshteinDistance} from '../../foundation/text/string-utils.mjs';import {installJsonShim} from './lib/json-shim.mjs';-import {addDocHelp, markReportsResult} from './lib/define-command.mjs';-import {doc as manifestDoc} from './commands/manifest.doc.mjs';+import {markReportsResult} from './lib/define-command.mjs';import {agentDocsTargetDir,assertAgentDocsTarget,@@ -297,7 +296,7 @@ function captureInvocation(actionCommand, root) {*/const commands = [{name: 'init', path: './commands/init.mjs', register: 'registerInit'},- {name: 'component', path: './commands/component/index.mjs', register: 'registerComponent'},+ {name: 'component', path: './commands/component.mjs', register: 'registerComponent'},{name: 'docs', path: './commands/docs.mjs', register: 'registerDocs'},{name: 'blog', path: './commands/blog.mjs', register: 'registerBlog'},{name: 'swizzle', path: './commands/swizzle.mjs', register: 'registerSwizzle'},@@ -305,13 +304,17 @@ const commands = [// agent-docs folded into init — functions still importable from agent-docs.mjs{name: 'template', path: './commands/template.mjs', register: 'registerTemplate'},{name: 'upgrade', path: './commands/upgrade.mjs', register: 'registerUpgrade'},- {name: 'theme', path: './commands/build-theme.mjs', register: 'registerTheme'},+ {name: 'theme', path: './commands/theme.mjs', register: 'registerTheme'},{name: 'integration', path: './commands/integration.mjs', register: 'registerIntegration'},- {name: 'hook', path: './commands/hook/index.mjs', register: 'registerHook'},+ {name: 'hook', path: './commands/hook.mjs', register: 'registerHook'},{name: 'discover', path: './commands/discover.mjs', register: 'registerDiscover'},{name: 'search', path: './commands/search.mjs', register: 'registerSearch'},{name: 'build', path: './commands/build.mjs', register: 'registerBuild'},{name: 'doctor', path: './commands/doctor.mjs', register: 'registerDoctor'},+ // Registered after every other command: the manifest lists the commands in+ // registration order.+ {name: 'manifest', path: './commands/manifest.mjs', register: 'registerManifest'},+ {name: 'postinstall', path: './commands/postinstall.mjs', register: 'registerPostinstall'},];const SETUP_NUDGE_EXEMPT = new Set(['init', 'agent-docs']);@@ -677,7 +680,7 @@ export async function createProgram() {for (const cmd of commands) {try {const mod = await import(cmd.path);- mod[cmd.register](program);+ mod[cmd.register](program, {jsonSupported: JSON_SUPPORTED, version: pkg.version});} catch (e) {// Command fails to load but CLI still worksconst reason = /** @type {any} */ (e).message;@@ -697,84 +700,6 @@ export async function createProgram() {}}- // Capability manifest — a single, self-describing view of the whole CLI so- // agents can discover every command, argument, flag, and response type without- // scraping `--help`. `astryx manifest --json` is the dedicated surface; the bare- // `xds --json` embeds the same payload under data.manifest for convenience.- // Intentionally CLI-special — no `api/manifest`. It introspects the live- // Commander `program`, so extracting it to `api/` would create the `api → cli`- // cycle from #4302. `buildManifest(program)` lives in lib/; see its header.- const manifestCommand = program- .command('manifest')- .description('Print the full CLI capability manifest (use with --json)')- .action(() => {- const manifest = buildManifest(program, {- jsonSupported: JSON_SUPPORTED,- version: pkg.version,- });- // The manifest IS a result set: one entry per command the CLI ships.- debug.recordCommandResult(- debug.resultSet({- count: manifest.commands.length,- resultKind: 'command',- }),- );- if (program.opts().json) {- process.__xdsJsonHandled = true;- console.log(JSON.stringify({apiVersion: API_VERSION, type: 'manifest', data: manifest, meta: {answeredBy: answeredBy()}}, null, 2));- return;- }- // Human-readable summary as greppable records (agents should use --json).- // One record per command: name, whether it supports --json, and the- // description. Field names are the manifest entry's own keys.- emit(- section(`${manifest.name} v${manifest.version} (${manifest.commands.length} commands)`),- records(- manifest.commands.map(c => ({- name: c.name,- json: c.json ? 'yes' : '',- description: c.description || '',- })),- {fields: ['name', 'json', 'description']},- ),- text(`Run \`${getCliInvocation()} manifest --json\` for the full structured manifest.`),- );- });- addDocHelp(manifestCommand, manifestDoc);- markReportsResult(manifestCommand);-- // Hidden command used by package.json postinstall scripts- const postinstallCommand = program- .command('postinstall', {hidden: true})- .action(() => {- // Prints the welcome box. Nothing is looked up.- debug.recordCommandResult(debug.NO_RESULT_SET);- const r = getCliInvocation();- const pad = (/** @type {string} */ s, /** @type {number} */ len) => s + ' '.repeat(Math.max(0, len - s.length));- const W = 49; // inner width of the box- const line = (/** @type {string} */ s) => ` │ ${pad(s, W)}│`;- console.log(`- ╭${'─'.repeat(W + 2)}╮-${line('')}-${line(' Design system installed!')}-${line('')}-${line(' Get started:')}-${line(` ${r} init Setup + AI agent docs`)}-${line(` ${r} --help See all commands`)}-${line('')}-${line(' Or run directly:')}-${line(` ${r} init Setup + AI agent docs`)}-${line(` ${r} component Browse component docs`)}-${line(` ${r} hook Browse hook docs`)}-${line(` ${r} docs Design system reference`)}-${line(` ${r} swizzle Customize a component`)}-${line(` ${r} template Add a page template`)}-${line('')}- ╰${'─'.repeat(W + 2)}╯-`);- });- markReportsResult(postinstallCommand);-// Install the JSON shim AFTER all commands are registered so we can// patch outputHelp on every command (root + subcommands). The shim// extends the --json contract to cover Commander's parse-time shortdiff --git a/packages/cli/clients/cli/lib/component-format.mjs b/packages/cli/clients/cli/lib/component-format.mjsindex 9228ea7d4b..2460d4598b 100644--- a/packages/cli/clients/cli/lib/component-format.mjs+++ b/packages/cli/clients/cli/lib/component-format.mjs@@ -21,7 +21,7 @@ import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';* (→ `.astryx-table-cell`), and `astryx-button` → key `button`.** Keep the `astryx-` literal in sync with packages/core/src/naming.ts- * (NAMESPACE / classPrefix), the same way build-theme.mjs mirrors it.+ * (NAMESPACE / classPrefix), the same way commands/theme.mjs mirrors it.* <!-- SYNC: packages/core/src/naming.ts (namespace prefix source of truth) -->* @param {import('@astryxdesign/cli/authoring').ComponentThemingTarget} target* @returns {string}diff --git a/packages/cli/clients/cli/lib/define-command.mjs b/packages/cli/clients/cli/lib/define-command.mjsindex d6c4a6c015..05d046e0be 100644--- a/packages/cli/clients/cli/lib/define-command.mjs+++ b/packages/cli/clients/cli/lib/define-command.mjs@@ -63,10 +63,10 @@ export function reportsResultVia(cmd) {/*** Mark a hand-registered command as reporting its result.*- * For the handful of commands that cannot come from a CommandDoc — the root- * program, `manifest` (it introspects the live program, so it cannot be- * declared by one), `postinstall`, and the stub left behind when a command- * module fails to load. They call {@link recordCommandResult} themselves; this+ * For what does not come from a CommandDoc: the root program, and the stub+ * left behind when a command module fails to load. Every command, `manifest`+ * and the hidden `postinstall` hook included, registers through+ * {@link defineCommand}. These call {@link recordCommandResult} themselves; this* says so, and the coverage test pins the set of commands allowed to, so the* mark cannot become a quiet way around the contract.*@@ -105,10 +105,12 @@ export function commandDocsOf(cmd) {* fn?: import('@astryxdesign/cli/authoring').FunctionDoc,* action?: (...args: any[]) => import('../../../foundation/debug/command-result.mjs').CommandResult* | Promise<import('../../../foundation/debug/command-result.mjs').CommandResult>,- * }} [impl]+ * hidden?: boolean,+ * }} [impl] `hidden` keeps the command out of help and the manifest (a+ * package-script hook, not a command for people or agents).* @returns {import('commander').Command} the created command.*/-export function defineCommand(parent, doc, {fn, action} = {}) {+export function defineCommand(parent, doc, {fn, action, hidden} = {}) {// The command token is the last path segment ("theme build" -> "build"),// since subcommands are added to their group command, not the program.const token = doc.name.split(' ').pop() ?? doc.name;@@ -119,7 +121,10 @@ export function defineCommand(parent, doc, {fn, action} = {}) {}).join(' ');- const cmd = parent.command(argSpec ? `${token} ${argSpec}` : token);+ const cmd = parent.command(+ argSpec ? `${token} ${argSpec}` : token,+ hidden ? {hidden: true} : {},+ );Object.defineProperty(cmd, COMMAND_DOCS, {value: {doc, fn}, configurable: true});if (doc.summary) cmd.description(doc.summary);if (doc.deprecated) {diff --git a/packages/cli/clients/cli/lib/exit-codes.test.mjs b/packages/cli/clients/cli/lib/exit-codes.test.mjsindex c2ec796256..39563e83b8 100644--- a/packages/cli/clients/cli/lib/exit-codes.test.mjs+++ b/packages/cli/clients/cli/lib/exit-codes.test.mjs@@ -24,6 +24,10 @@ for (const file of fs.readdirSync(COMMANDS).sort()) {}const manifest = buildManifest(program, {jsonSupported: JSON_SUPPORTED, version: '0.0.0-test'});+/** Hidden commands (a package-script hook): documented, never in the manifest. */+const HIDDEN = new Set(+ program.commands.filter((c) => /** @type {any} */ (c)._hidden).map((c) => c.name()),+);/** @type {Map<string, any>} */const entries = new Map();const walk = (/** @type {any} */ c) => {@@ -98,6 +102,7 @@ describe('command exit codes', () => {it('the manifest carries every command exit code', () => {for (const doc of commandDocs) {+ if (HIDDEN.has(doc.name)) continue;expect(entries.get(doc.name)?.exitCodes, doc.name).toEqual(doc.exitCodes.map(({code, when}) => ({code, when})),);diff --git a/packages/cli/clients/cli/lib/manifest.test.mjs b/packages/cli/clients/cli/lib/manifest.test.mjsindex 7cf06ed7ed..bd9103a6fb 100644--- a/packages/cli/clients/cli/lib/manifest.test.mjs+++ b/packages/cli/clients/cli/lib/manifest.test.mjs@@ -55,6 +55,10 @@ const CLI_LAYER_TYPES = {};const manifest = buildManifest(program, {jsonSupported: JSON_SUPPORTED, version: '0.0.0-test'});+/** Hidden commands (a package-script hook): documented, never in the manifest. */+const HIDDEN = new Set(+ program.commands.filter((c) => /** @type {any} */ (c)._hidden).map((c) => c.name()),+);/** Flatten the manifest command tree into fully-qualified names. */function flatten(cmds, out = []) {@@ -116,12 +120,19 @@ describe('manifest: drift guards', () => {it('takes every command example from its CommandDoc', () => {for (const [name, doc] of commandDocs) {+ if (HIDDEN.has(name)) continue;const entry = allEntries.find((c) => c.name === name);expect(entry, `CommandDoc "${name}" has no manifest entry`).toBeDefined();expect(entry.examples ?? [], name).toEqual((doc.examples ?? []).map((e) => e.cli));}});+ it('documents the hidden postinstall hook and keeps it out of the manifest', () => {+ expect([...HIDDEN]).toEqual(['postinstall']);+ expect(commandDocs.has('postinstall')).toBe(true);+ expect(allNames.has('postinstall')).toBe(false);+ });+it('lists every response type the wrapped API function returns', () => {for (const [name, doc] of commandDocs) {if (!doc.fn) continue;@@ -152,6 +163,7 @@ describe('manifest: drift guards', () => {it('takes response types from the wrapped FunctionDoc, plus CLI-layer envelopes', () => {for (const [name, doc] of commandDocs) {+ if (HIDDEN.has(name)) continue;const entry = allEntries.find((c) => c.name === name);const returns = doc.fn ? functionDocs.get(doc.fn).returns.map((r) => r.type) : [];const expected = [...returns, ...(CLI_LAYER_TYPES[name] ?? [])];diff --git a/packages/cli/clients/cli/lib/welcome-box.mjs b/packages/cli/clients/cli/lib/welcome-box.mjsnew file mode 100644index 0000000000..2ffb40d335--- /dev/null+++ b/packages/cli/clients/cli/lib/welcome-box.mjs@@ -0,0 +1,50 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file The welcome box `astryx postinstall` prints after the package installs.+ *+ * A fixed banner, not tabular output, so it is drawn here rather than with the+ * formatter kit; the command prints it verbatim through `emit(code(...))`.+ * @input The CLI invocation for this project (e.g. `pnpm exec astryx`).+ * @output {@link welcomeBox}+ * @position clients/cli/lib — presentation helper for commands/postinstall.mjs+ */++/** Inner width of the box. */+const W = 49;++/**+ * @param {string} s+ * @param {number} len+ */+const pad = (s, len) => s + ' '.repeat(Math.max(0, len - s.length));++/** @param {string} s */+const line = s => ` │ ${pad(s, W)}│`;++/**+ * The welcome box, with a blank line before and after it.+ * @param {string} r the CLI invocation, e.g. `pnpm exec astryx`+ * @returns {string}+ */+export function welcomeBox(r) {+ return `+ ╭${'─'.repeat(W + 2)}╮+${line('')}+${line(' Design system installed!')}+${line('')}+${line(' Get started:')}+${line(` ${r} init Setup + AI agent docs`)}+${line(` ${r} --help See all commands`)}+${line('')}+${line(' Or run directly:')}+${line(` ${r} init Setup + AI agent docs`)}+${line(` ${r} component Browse component docs`)}+${line(` ${r} hook Browse hook docs`)}+${line(` ${r} docs Design system reference`)}+${line(` ${r} swizzle Customize a component`)}+${line(` ${r} template Add a page template`)}+${line('')}+ ╰${'─'.repeat(W + 2)}╯+`;+}diff --git a/packages/cli/foundation/discovery/runner-commands.mjs b/packages/cli/foundation/discovery/runner-commands.mjsindex 437d32c0f6..bb76ad6c72 100644--- a/packages/cli/foundation/discovery/runner-commands.mjs+++ b/packages/cli/foundation/discovery/runner-commands.mjs@@ -67,6 +67,7 @@ export const CLI_COMMANDS = Object.freeze(['init','integration','manifest',+ 'postinstall','search','swizzle','template',diff --git a/packages/cli/foundation/doc-compiler/doc-loads.test.mjs b/packages/cli/foundation/doc-compiler/doc-loads.test.mjsindex 47446c2b0f..2c1fb39b79 100644--- a/packages/cli/foundation/doc-compiler/doc-loads.test.mjs+++ b/packages/cli/foundation/doc-compiler/doc-loads.test.mjs@@ -102,7 +102,15 @@ const RUNNERS = {runs: SELF_DOCS,sites: ['import ../../../api/blog/blog.doc.mjs', 'import ./blog.doc.mjs'],},- 'clients/cli/commands/build-theme.mjs': {+ 'clients/cli/commands/manifest.mjs': {+ runs: SELF_DOCS,+ sites: ['import ./manifest.doc.mjs'],+ },+ 'clients/cli/commands/postinstall.mjs': {+ runs: SELF_DOCS,+ sites: ['import ./postinstall.doc.mjs'],+ },+ 'clients/cli/commands/theme.mjs': {runs: `${SELF_DOCS}; and \`astryx theme build\`, a child process per theme`,sites: ['child_process.spawn',@@ -135,11 +143,11 @@ const RUNNERS = {'import ./build.doc.mjs',],},- 'clients/cli/commands/component/index.mjs': {+ 'clients/cli/commands/component.mjs': {runs: SELF_DOCS,sites: [- 'import ../../../../api/component/component.doc.mjs',- 'import ../component.doc.mjs',+ 'import ../../../api/component/component.doc.mjs',+ 'import ./component.doc.mjs',],},'clients/cli/commands/discover.mjs': {@@ -180,11 +188,11 @@ const RUNNERS = {'import ./gap-report.doc.mjs',],},- 'clients/cli/commands/hook/index.mjs': {+ 'clients/cli/commands/hook.mjs': {runs: SELF_DOCS,sites: [- 'import ../../../../api/hook/hook.doc.mjs',- 'import ../hook.doc.mjs',+ 'import ../../../api/hook/hook.doc.mjs',+ 'import ./hook.doc.mjs',],},'clients/cli/commands/init.mjs': {@@ -233,8 +241,8 @@ const RUNNERS = {],},'clients/cli/index.mjs': {- runs: 'the command modules, to register each command, and the manifest command doc',- sites: ['import ./commands/manifest.doc.mjs', 'import(<computed>)'],+ runs: 'the command modules, to register each command',+ sites: ['import(<computed>)'],},'clients/cli/lib/manifest.mjs': {runs: 'the manifest command doc, for the exit codes the manifest reports',diff --git a/packages/cli/test/docs-graph.test.mjs b/packages/cli/test/docs-graph.test.mjsindex 9ebcd929b1..b3d77093d9 100644--- a/packages/cli/test/docs-graph.test.mjs+++ b/packages/cli/test/docs-graph.test.mjs@@ -237,6 +237,15 @@ function cliSurface() {}};add(manifest.commands);+ // Hidden commands (a package-script hook) are documented but left out of+ // the manifest; they are still real commands.+ for (const command of program.commands) {+ if (!(/** @type {any} */ (command)._hidden)) continue;+ commands.set(+ command.name(),+ flagsOf(command.options.map(option => ({flag: option.flags}))),+ );+ }return {commands, groups, global: flagsOf(manifest.globalOptions)};}diff --git a/packages/cli/test/drift/docs-drift.mjs b/packages/cli/test/drift/docs-drift.mjsindex 52cd547a22..afd4e47e0c 100644--- a/packages/cli/test/drift/docs-drift.mjs+++ b/packages/cli/test/drift/docs-drift.mjs@@ -5,7 +5,8 @@* the hand-authored docs honest against their sources of truth:* - every `*.doc.mjs` under a production doc root parses via `parseDoc`;* - each CommandDoc's `fn` resolves to a FunctionDoc, its arg/option `param`s- * exist on that function, and its `name` is a real manifest command;+ * exist on that function, and its `name` is a real manifest command (or a+ * hidden one, which the manifest leaves out);* - the error-codes EnumDoc == ERROR_CODES exactly;* - the response-types EnumDoc == the manifest's response discriminants plus* the root types (help, version) no single command owns.@@ -110,9 +111,17 @@ export async function runDrift() {(c.subcommands || []).forEach(walkCmd);};manifest.commands.forEach(walkCmd);+ // Hidden commands (a package-script hook) have a CommandDoc but no manifest+ // entry, by design.+ const {program} = await import('../../clients/cli/index.mjs');+ const hiddenNames = new Set(+ program.commands+ .filter(c => /** @type {any} */ (c)._hidden)+ .map(c => c.name()),+ );for (const {file, doc} of of('command')) {- if (doc.name && !manifestNames.has(doc.name)) {+ if (doc.name && !manifestNames.has(doc.name) && !hiddenNames.has(doc.name)) {errors.push(`${file}: command "${doc.name}" is not in the manifest`);}if (doc.fn) {diff --git a/packages/cli/test/taught-core-imports.test.mjs b/packages/cli/test/taught-core-imports.test.mjsindex bfb64b77ed..b2e8116265 100644--- a/packages/cli/test/taught-core-imports.test.mjs+++ b/packages/cli/test/taught-core-imports.test.mjs@@ -25,7 +25,7 @@ const CORE_PACKAGE = path.resolve(CLI, '..', 'core', 'package.json');/** Command modules whose printed text shows app code. */const OUTPUT_MODULES = ['api/init/run/run.mjs',- 'clients/cli/commands/build-theme.mjs',+ 'clients/cli/commands/theme.mjs','api/theme/build/build.mjs','api/doctor/theme-checks.mjs','api/build/help/help.mjs',diff --git a/scripts/check-cli-structure.mjs b/scripts/check-cli-structure.mjsindex e11dea0989..c3f3de5e89 100644--- a/scripts/check-cli-structure.mjs+++ b/scripts/check-cli-structure.mjs@@ -26,11 +26,16 @@* *.doc.mjs the FunctionDoc* *.test.mjs coverage (may be nested, e.g. api/theme/build/build.test.mjs)*- * Deliberately NOT checked here: command <-> CommandDoc pairing. That is not a- * filename convention — subcommand docs (layout-expand, theme-add, ...) live- * inside their group's handler and `manifest` registers in index.mjs — and the- * drift harness already validates it semantically against the live manifest,- * which is strictly stronger than matching filenames.+ * 3. Every CLI command and CommandDoc sits where cli-surface INV6 puts it:+ * clients/cli/commands/<name>.mjs (or <name>/index.mjs for a group:+ * a CommandDoc that lists subcommands)+ * clients/cli/commands/<name>.doc.mjs+ * clients/cli/commands/<parent>-<child>.doc.mjs for each subcommand+ * Top-level commands come from clients/cli/index.mjs (its `commands`+ * registry and any literal `.command()` call there); subcommands come from+ * each CommandDoc's `subcommands`. The docs drift harness holds those docs+ * equal to the live CLI (args, options, subcommands); this check owns where+ * the files are.** Usage: node scripts/check-cli-structure.mjs*/@@ -71,6 +76,30 @@ function walk(dir) {return out;}+/**+ * Every `*.doc.mjs` under `dir`, group folders included, as `/`-separated paths+ * relative to `dir`, sorted.+ * @param {string} dir+ * @returns {string[]}+ */+function docFilesUnder(dir) {+ /** @type {string[]} */+ const out = [];+ const entries = fs+ .readdirSync(dir, {withFileTypes: true})+ .sort((a, b) => a.name.localeCompare(b.name));+ for (const entry of entries) {+ if (entry.isDirectory()) {+ for (const file of docFilesUnder(path.join(dir, entry.name))) {+ out.push(`${entry.name}/${file}`);+ }+ } else if (entry.name.endsWith('.doc.mjs')) {+ out.push(entry.name);+ }+ }+ return out;+}+/** @type {string[]} */const errors = [];let doctypeCount = 0;@@ -313,11 +342,11 @@ const HANDLER_DIR = path.join(CLI, 'clients/cli/commands');/** @type {Map<string, Set<string>>} known gaps recorded in AST-042;* remove an entry when the file is fixed; do not add entries */const INV22_KNOWN_GAPS = new Map([- ['build-theme.mjs', new Set(['fs', 'child_process', 'project'])],- ['component/index.mjs', new Set(['project', 'discovery'])],+ ['theme.mjs', new Set(['fs', 'child_process', 'project'])],+ ['component.mjs', new Set(['project', 'discovery'])],['discover.mjs', new Set(['project'])],['ensure-core-built.mjs', new Set(['fs', 'child_process'])],- ['hook/index.mjs', new Set(['discovery'])],+ ['hook.mjs', new Set(['discovery'])],// remove with the layout command['layout.mjs', new Set(['fs'])],['search.mjs', new Set(['project'])],@@ -670,21 +699,179 @@ for (const name of apiExports) {}}-if (errors.length > 0) {- console.error('❌ CLI structure violations:\n');- for (const e of errors) console.error(` ${e}`);- console.error(- `\n${errors.length} error(s). See CONTRIBUTING > "Working on the astryx CLI".`,+// ── 6. INV6: command files and CommandDocs ──────────────────────────+/**+ * Check INV6 (docs/architecture/cli-surface.md) for the CLI rooted at+ * `cliRoot`: every registered command's file and CommandDoc, every+ * subcommand's CommandDoc, and no CommandDoc anywhere else.+ *+ * @param {string} cliRoot the `packages/cli` directory+ * @returns {Promise<{errors: string[], commands: number}>}+ */+export async function checkCommandLayout(cliRoot) {+ const {default: ts} = await import('typescript');+ const {pathToFileURL} = await import('node:url');+ const COMMANDS = 'clients/cli/commands';+ const INDEX = 'clients/cli/index.mjs';+ /** @type {string[]} */+ const errors = [];++ const indexFile = path.join(cliRoot, INDEX);+ const source = ts.createSourceFile(+ indexFile,+ fs.readFileSync(indexFile, 'utf8'),+ ts.ScriptTarget.Latest,+ true,+ ts.ScriptKind.JS,);- process.exit(1);+ /** @type {{name: string, file: string | null}[]} */+ const registered = [];+ let registryFound = false;+ /** @param {import('typescript').Node} node */+ const visit = node => {+ if (+ ts.isVariableDeclaration(node) &&+ ts.isIdentifier(node.name) &&+ node.name.text === 'commands' &&+ node.initializer &&+ ts.isArrayLiteralExpression(node.initializer)+ ) {+ registryFound = true;+ for (const entry of node.initializer.elements) {+ if (!ts.isObjectLiteralExpression(entry)) continue;+ /** @param {string} key */+ const field = key => {+ const prop = entry.properties.find(+ p => ts.isPropertyAssignment(p) && p.name.getText(source) === key,+ );+ return prop &&+ ts.isPropertyAssignment(prop) &&+ ts.isStringLiteralLike(prop.initializer)+ ? prop.initializer.text+ : null;+ };+ const name = field('name');+ const file = field('path');+ if (name && file) registered.push({name, file});+ }+ }+ // A command registered by hand, e.g. `program.command('manifest')`.+ if (+ ts.isCallExpression(node) &&+ ts.isPropertyAccessExpression(node.expression) &&+ node.expression.name.text === 'command' &&+ node.arguments.length > 0 &&+ ts.isStringLiteralLike(node.arguments[0])+ ) {+ registered.push({name: node.arguments[0].text.split(' ')[0], file: null});+ }+ ts.forEachChild(node, visit);+ };+ visit(source);+ if (!registryFound) {+ errors.push(+ `found no \`commands\` registry in ${INDEX} — has it moved? Update this check.`,+ );+ }++ /** @type {Set<string>} */+ const expectedDocs = new Set();+ let commands = 0;+ /**+ * Check `name`'s CommandDoc and, through its `subcommands`, theirs.+ * @param {string} name+ * @returns {Promise<any>} the CommandDoc, or null when it is missing or+ * documents another command+ */+ const checkDoc = async name => {+ const docPath = `${COMMANDS}/${name.replaceAll(' ', '-')}.doc.mjs`;+ expectedDocs.add(docPath);+ const docFile = path.join(cliRoot, docPath);+ if (!fs.existsSync(docFile)) {+ errors.push(`command "${name}" has no CommandDoc at ${docPath}`);+ return null;+ }+ const mod = await import(pathToFileURL(docFile).href);+ const doc = mod.doc ?? mod.docs ?? mod.default;+ if (doc?.name !== name) {+ errors.push(`${docPath} documents "${doc?.name}", not "${name}"`);+ return null;+ }+ commands++;+ for (const child of doc.subcommands ?? [])+ await checkDoc(`${name} ${child}`);+ return doc;+ };++ for (const {name, file} of registered) {+ const flat = `${COMMANDS}/${name}.mjs`;+ const group = `${COMMANDS}/${name}/index.mjs`;+ const doc = await checkDoc(name);+ // INV6 allows the folder form only for a group: a command whose+ // CommandDoc lists subcommands. With no readable doc, that error is+ // already reported, so the folder is not judged.+ const isGroup = doc == null || (doc.subcommands ?? []).length > 0;+ if (file === null) {+ errors.push(+ `command "${name}" is registered in ${INDEX}, not in its own ${flat}`,+ );+ } else {+ const actual = path.posix.join('clients/cli', file);+ if (actual === group && !isGroup) {+ errors.push(+ `command "${name}" is registered from ${actual}, but only a group (a CommandDoc that lists subcommands) uses a folder; move it to ${flat}`,+ );+ } else if (actual !== flat && actual !== group) {+ errors.push(+ isGroup+ ? `command "${name}" is registered from ${actual}, not ${flat} or ${group}`+ : `command "${name}" is registered from ${actual}, not ${flat}`,+ );+ } else if (!fs.existsSync(path.join(cliRoot, actual))) {+ errors.push(+ `command "${name}" is registered from ${actual}, which does not exist`,+ );+ }+ }+ }++ for (const file of docFilesUnder(path.join(cliRoot, COMMANDS))) {+ const docPath = `${COMMANDS}/${file}`;+ if (!expectedDocs.has(docPath)) {+ errors.push(`${docPath} is not the CommandDoc of any registered command`);+ }+ }++ return {errors, commands};}-console.log(- [- `✅ CLI structure is intact:`,- ` ${doctypeCount} doc-type(s), ${apiCount} api folder(s),`,- ` ${inv22Count} handler(s) checked for INV22, ${clientHelperBoundaryCount} client helper boundary, ${inv21Count} api module(s) for INV21,`,- ` ${inv23Count} handler(s) checked for INV23,`,- ` ${fr1Count} CommandDoc fn(s) checked for FR1, ${fr2Count} api export(s) for FR2.`,- ].join('\n'),-);+// Run as a script; stay importable for the tests.+if (process.argv[1] === fileURLToPath(import.meta.url)) {+ const layout = await checkCommandLayout(CLI);+ errors.push(...layout.errors);+ if (layout.commands === 0) {+ errors.push(+ 'found no CommandDocs under packages/cli/clients/cli/commands — has the directory moved? Update this check.',+ );+ }++ if (errors.length > 0) {+ console.error('❌ CLI structure violations:\n');+ for (const e of errors) console.error(` ${e}`);+ console.error(+ `\n${errors.length} error(s). See CONTRIBUTING > "Working on the astryx CLI".`,+ );+ process.exit(1);+ }++ console.log(+ [+ `✅ CLI structure is intact:`,+ ` ${doctypeCount} doc-type(s), ${apiCount} api folder(s),`,+ ` ${inv22Count} handler(s) checked for INV22, ${clientHelperBoundaryCount} client helper boundary, ${inv21Count} api module(s) for INV21,`,+ ` ${inv23Count} handler(s) checked for INV23,`,+ ` ${fr1Count} CommandDoc fn(s) checked for FR1, ${fr2Count} api export(s) for FR2,`,+ ` ${layout.commands} command(s) checked for INV6.`,+ ].join('\n'),+ );+}diff --git a/scripts/check-cli-structure.test.mjs b/scripts/check-cli-structure.test.mjsnew file mode 100644index 0000000000..29ebcd7655--- /dev/null+++ b/scripts/check-cli-structure.test.mjs@@ -0,0 +1,251 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file `pnpm check:cli-structure` is the evidence cli-surface INV6 names for+ * the command layout, so it must fail when a command's file or CommandDoc is+ * missing or sits at the wrong path.+ */++import {spawnSync} from 'node:child_process';+import * as fs from 'node:fs';+import * as os from 'node:os';+import * as path from 'node:path';+import {fileURLToPath} from 'node:url';+import {afterEach, describe, expect, it} from 'vitest';+import {checkCommandLayout} from './check-cli-structure.mjs';++const REPO_ROOT = path.resolve(+ path.dirname(fileURLToPath(import.meta.url)),+ '..',+);++/** @type {string[]} */+const roots = [];+afterEach(() => {+ for (const root of roots.splice(0)) {+ fs.rmSync(root, {recursive: true, force: true});+ }+});++/**+ * A CLI tree with an index.mjs registry. `docs` maps a command name to its+ * subcommand names; each becomes a CommandDoc at its INV6 path.+ *+ * @param {{+ * registry?: Record<string, string>,+ * inline?: string[],+ * files?: string[],+ * docs?: Record<string, string[]>,+ * extraDocs?: Record<string, string>,+ * }} tree+ * @returns {string} the tree's `packages/cli` equivalent+ */+function cliTree({+ registry = {},+ inline = [],+ files = [],+ docs = {},+ extraDocs = {},+}) {+ const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cli-structure-'));+ roots.push(root);+ const commands = path.join(root, 'clients/cli/commands');+ fs.mkdirSync(commands, {recursive: true});+ const entries = Object.entries(registry)+ .map(+ ([name, file]) => ` {name: '${name}', path: '${file}', register: 'r'},`,+ )+ .join('\n');+ const calls = inline.map(name => `program.command('${name}');`).join('\n');+ fs.writeFileSync(+ path.join(root, 'clients/cli/index.mjs'),+ `const commands = [\n${entries}\n];\n${calls}\n`,+ );+ for (const file of files) {+ const target = path.join(root, 'clients/cli', file);+ fs.mkdirSync(path.dirname(target), {recursive: true});+ fs.writeFileSync(target, 'export {};\n');+ }+ const writeDoc = (/** @type {string} */ file, /** @type {object} */ doc) => {+ fs.mkdirSync(path.dirname(path.join(commands, file)), {recursive: true});+ fs.writeFileSync(+ path.join(commands, file),+ `export const doc = ${JSON.stringify(doc)};\n`,+ );+ };+ for (const [name, subcommands] of Object.entries(docs)) {+ writeDoc(`${name.replaceAll(' ', '-')}.doc.mjs`, {+ type: 'command',+ name,+ subcommands,+ });+ }+ for (const [file, name] of Object.entries(extraDocs)) {+ writeDoc(file, {type: 'command', name});+ }+ return root;+}++/** A conforming tree: a flat command, and a group with nested subcommands. */+const CONFORMING = {+ registry: {+ alpha: './commands/alpha.mjs',+ beta: './commands/beta/index.mjs',+ },+ files: ['commands/alpha.mjs', 'commands/beta/index.mjs'],+ docs: {+ alpha: [],+ beta: ['one'],+ 'beta one': ['deep'],+ 'beta one deep': [],+ },+};++describe('checkCommandLayout', () => {+ it('accepts commands, groups, and nested subcommands at their INV6 paths', async () => {+ const {errors, commands} = await checkCommandLayout(cliTree(CONFORMING));+ expect(errors).toEqual([]);+ expect(commands).toBe(4);+ });++ it('fails when a command has no CommandDoc', async () => {+ const docs = {...CONFORMING.docs};+ delete docs['beta one deep'];+ const {errors} = await checkCommandLayout(cliTree({...CONFORMING, docs}));+ expect(errors).toEqual([+ 'command "beta one deep" has no CommandDoc at clients/cli/commands/beta-one-deep.doc.mjs',+ ]);+ });++ it('fails when a command is registered from another file', async () => {+ const {errors} = await checkCommandLayout(+ cliTree({+ ...CONFORMING,+ registry: {...CONFORMING.registry, alpha: './commands/build-alpha.mjs'},+ files: [...CONFORMING.files, 'commands/build-alpha.mjs'],+ }),+ );+ expect(errors).toEqual([+ 'command "alpha" is registered from clients/cli/commands/build-alpha.mjs, not clients/cli/commands/alpha.mjs',+ ]);+ });++ it('names the folder form too when a group is registered from another file', async () => {+ const {errors} = await checkCommandLayout(+ cliTree({+ ...CONFORMING,+ registry: {...CONFORMING.registry, beta: './commands/build-beta.mjs'},+ files: [...CONFORMING.files, 'commands/build-beta.mjs'],+ }),+ );+ expect(errors).toEqual([+ 'command "beta" is registered from clients/cli/commands/build-beta.mjs, not clients/cli/commands/beta.mjs or clients/cli/commands/beta/index.mjs',+ ]);+ });++ it('fails when a command with no subcommands uses the folder form', async () => {+ const {errors} = await checkCommandLayout(+ cliTree({+ ...CONFORMING,+ registry: {...CONFORMING.registry, alpha: './commands/alpha/index.mjs'},+ files: ['commands/alpha/index.mjs', 'commands/beta/index.mjs'],+ }),+ );+ expect(errors).toEqual([+ 'command "alpha" is registered from clients/cli/commands/alpha/index.mjs, but only a group (a CommandDoc that lists subcommands) uses a folder; move it to clients/cli/commands/alpha.mjs',+ ]);+ });++ it('accepts a group in a flat file', async () => {+ const {errors} = await checkCommandLayout(+ cliTree({+ ...CONFORMING,+ registry: {...CONFORMING.registry, beta: './commands/beta.mjs'},+ files: ['commands/alpha.mjs', 'commands/beta.mjs'],+ }),+ );+ expect(errors).toEqual([]);+ });++ it('fails when the registered file is missing', async () => {+ const {errors} = await checkCommandLayout(+ cliTree({...CONFORMING, files: ['commands/beta/index.mjs']}),+ );+ expect(errors).toEqual([+ 'command "alpha" is registered from clients/cli/commands/alpha.mjs, which does not exist',+ ]);+ });++ it('fails when a command is registered by hand in index.mjs', async () => {+ const {errors} = await checkCommandLayout(+ cliTree({+ ...CONFORMING,+ inline: ['gamma'],+ docs: {...CONFORMING.docs, gamma: []},+ }),+ );+ expect(errors).toEqual([+ 'command "gamma" is registered in clients/cli/index.mjs, not in its own clients/cli/commands/gamma.mjs',+ ]);+ });++ it('fails when a CommandDoc documents a different command', async () => {+ const tree = cliTree(CONFORMING);+ fs.writeFileSync(+ path.join(tree, 'clients/cli/commands/beta-one.doc.mjs'),+ `export const doc = ${JSON.stringify({type: 'command', name: 'beta uno'})};\n`,+ );+ const {errors} = await checkCommandLayout(tree);+ expect(errors).toEqual([+ 'clients/cli/commands/beta-one.doc.mjs documents "beta uno", not "beta one"',+ 'clients/cli/commands/beta-one-deep.doc.mjs is not the CommandDoc of any registered command',+ ]);+ });++ it('fails when a CommandDoc sits at no registered command path', async () => {+ const {errors} = await checkCommandLayout(+ cliTree({...CONFORMING, extraDocs: {'beta_two.doc.mjs': 'beta two'}}),+ );+ expect(errors).toEqual([+ 'clients/cli/commands/beta_two.doc.mjs is not the CommandDoc of any registered command',+ ]);+ });++ it('fails when a CommandDoc sits inside a group folder', async () => {+ const {errors} = await checkCommandLayout(+ cliTree({...CONFORMING, extraDocs: {'beta/beta-one.doc.mjs': 'beta one'}}),+ );+ expect(errors).toEqual([+ 'clients/cli/commands/beta/beta-one.doc.mjs is not the CommandDoc of any registered command',+ ]);+ });++ it('fails when index.mjs has no command registry', async () => {+ const tree = cliTree(CONFORMING);+ fs.writeFileSync(path.join(tree, 'clients/cli/index.mjs'), 'export {};\n');+ const {errors} = await checkCommandLayout(tree);+ expect(errors[0]).toBe(+ 'found no `commands` registry in clients/cli/index.mjs — has it moved? Update this check.',+ );+ });+});++describe('the repository', () => {+ it('puts every command and CommandDoc at its INV6 path', async () => {+ const {errors, commands} = await checkCommandLayout(+ path.join(REPO_ROOT, 'packages/cli'),+ );+ expect(commands).toBeGreaterThan(0);+ expect(errors).toEqual([]);+ });++ it('passes pnpm check:cli-structure', () => {+ const res = spawnSync(+ process.execPath,+ [path.join(REPO_ROOT, 'scripts/check-cli-structure.mjs')],+ {encoding: 'utf8'},+ );+ expect(res.status, res.stderr).toBe(0);+ expect(res.stdout).toMatch(/\d+ command\(s\) checked for INV6/);+ });+});