Skip to content

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.md
new file mode 100644
index 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.
+
+@josephfarina
diff --git a/apps/sandbox/scripts/generate-cli-registry.mjs b/apps/sandbox/scripts/generate-cli-registry.mjs
index 2f479bf728..b61fbc65ca 100644
--- a/apps/sandbox/scripts/generate-cli-registry.mjs
+++ b/apps/sandbox/scripts/generate-cli-registry.mjs
@@ -38,12 +38,12 @@ program
const 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.js
index 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.md
index 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 t
User 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.mjs
index 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 also
diff --git a/packages/cli/api/hook/hook.mjs b/packages/cli/api/hook/hook.mjs
index 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.mjs
index 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.mjs
index 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.mjs
similarity index 85%
rename from packages/cli/clients/cli/commands/component/index.mjs
rename to packages/cli/clients/cli/commands/component.mjs
index 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.mjs
index 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.mjs
similarity index 82%
rename from packages/cli/clients/cli/commands/hook/index.mjs
rename to packages/cli/clients/cli/commands/hook.mjs
index 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.mjs
index 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.mjs
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
similarity index 99%
rename from packages/cli/clients/cli/commands/build-theme.mjs
rename to packages/cli/clients/cli/commands/theme.mjs
index 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.mjs
index 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 works
const 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 short
diff --git a/packages/cli/clients/cli/lib/component-format.mjs b/packages/cli/clients/cli/lib/component-format.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
new file mode 100644
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
new file mode 100644
index 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/);
+ });
+});