Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(cli): show each command's exit codes in help and the manifest (#6586)

Joeyd20eaa6b9af4
diff --git a/.changeset/cli-spec-exit-codes-in-help.md b/.changeset/cli-spec-exit-codes-in-help.md
new file mode 100644
index 0000000000..4fc1978d15
--- /dev/null
+++ b/.changeset/cli-spec-exit-codes-in-help.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[fix] `astryx <command> --help` (including `astryx manifest --help`) now ends with the command's documented exit codes, and each command in `astryx manifest --json` carries them as `exitCodes: [{code, when}]`. `astryx doctor --help` shows them once, and the `layout` and `discover` exit codes now say when they apply: bare `astryx layout` exits 1, and a blank `discover` query exits 1 when packages are discovered.
+
+@josephfarina
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 6e401ef9ca..7ec42eaf06 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -200,8 +200,9 @@ if (isError(result)) {
Agents don't have to scrape `--help` to learn the CLI. A single call returns a
**self-describing manifest**: every command, its arguments, flags (with types,
-choices, and defaults), whether it supports `--json`, and the response `type`
-discriminators each command can emit. Think of it as an OpenAPI spec for the CLI.
+choices, and defaults), whether it supports `--json`, the response `type`
+discriminators each command can emit, and its documented exit codes. Think of it
+as an OpenAPI spec for the CLI.
```bash
astryx manifest --json # dedicated surface — type: "manifest"
@@ -263,6 +264,10 @@ Shape:
"…",
],
"examples": ["astryx component Button --props --json"],
+ "exitCodes": [
+ {"code": 0, "when": "success"},
+ {"code": 1, "when": "…"},
+ ],
},
// …one entry per command; subcommands (e.g. `theme build`) nest under `subcommands`
],
@@ -438,7 +443,7 @@ Every response has a `type` discriminant. The full set is below (generated from
| `upgrade.list` | Every available codemod, oldest→newest, as {name, title, version, optional}; returned for --list without running anything. |
| `upgrade.status` | A short-circuit outcome with no codemods run (up_to_date, no_codemods, or config_fixable), each carrying the agent-docs summary. |
| `upgrade.run` | The run receipt: from/to versions, codemod count, integrations processed, the agent-docs summary, and (apply mode) filesChanged, transformsApplied, and per-codemod errors. |
-| `manifest` | The self-describing CLI capability manifest: name, version, apiVersion, global options, the command tree (args, options, json flag, response types, examples), the jsonSupported allowlist, and the flat responseTypes index. |
+| `manifest` | The CLI capability manifest: name, version, apiVersion, description, globalOptions, commands (each name, description, arguments, options, json, aliases?, responseTypes?, examples?, exitCodes? as [{code, when}], subcommands?), jsonSupported, and the flat responseTypes index. |
| `doctor` | The health-check report: `checks` (each with id, label, status: pass \| warn \| fail \| info, a message, and a fix when not passing) plus a `summary` of counts per status. |
| `integration.add` | A contribution-writer receipt: kind, name, optional root {path, created}, integration-manifest path, every affected project-relative path, written, and dryRun. |
| `integration.pack-check` | The packed-package check: package identity, tarball facts, local and packed contribution inventories, and issues. |
diff --git a/packages/cli/clients/cli/commands/discover.doc.mjs b/packages/cli/clients/cli/commands/discover.doc.mjs
index a35f961352..a39605ead9 100644
--- a/packages/cli/clients/cli/commands/discover.doc.mjs
+++ b/packages/cli/clients/cli/commands/discover.doc.mjs
@@ -38,7 +38,7 @@ export const doc = {
{code: 0, when: 'success'},
{
code: 1,
- when: 'unknown package or component, a malformed doc, or an empty free-text query',
+ when: 'unknown package or component, a malformed doc, or a blank query when packages are discovered',
},
],
related: ['component', 'search', 'template'],
diff --git a/packages/cli/clients/cli/commands/doctor.mjs b/packages/cli/clients/cli/commands/doctor.mjs
index a8c4c5053a..a7a4e54cee 100644
--- a/packages/cli/clients/cli/commands/doctor.mjs
+++ b/packages/cli/clients/cli/commands/doctor.mjs
@@ -290,13 +290,6 @@ export function registerDoctor(program) {
fn: doctorFn,
action: async () => runProjectDoctor(program),
});
- doctorCmd.addHelpText(
- 'after',
- '\nExit code:\n' +
- ' 0 no failures (warnings are allowed) — safe as a CI gate\n' +
- ' 1 one or more checks failed\n',
- );
-
/** @type {import('commander').Command} */
let integrationCmd;
integrationCmd = defineCommand(doctorCmd, doctorIntegrationGroup, {
diff --git a/packages/cli/clients/cli/commands/layout.doc.mjs b/packages/cli/clients/cli/commands/layout.doc.mjs
index fd18e42ebc..64fb9d8ae1 100644
--- a/packages/cli/clients/cli/commands/layout.doc.mjs
+++ b/packages/cli/clients/cli/commands/layout.doc.mjs
@@ -27,8 +27,8 @@ export const doc = {
},
],
exitCodes: [
- {code: 0, when: 'success (help shown, or a subcommand succeeded)'},
- {code: 1, when: 'an unknown subcommand'},
+ {code: 0, when: 'a subcommand succeeded, or --help'},
+ {code: 1, when: 'no subcommand (help is printed) or an unknown subcommand'},
],
related: ['template', 'build'],
};
diff --git a/packages/cli/clients/cli/index.mjs b/packages/cli/clients/cli/index.mjs
index d0e88680b0..0e15a38305 100644
--- a/packages/cli/clients/cli/index.mjs
+++ b/packages/cli/clients/cli/index.mjs
@@ -24,7 +24,8 @@ import {emit, 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 {markReportsResult} from './lib/define-command.mjs';
+import {addExitCodesHelp, markReportsResult} from './lib/define-command.mjs';
+import {doc as manifestDoc} from './commands/manifest.doc.mjs';
import {isAstryxInitialized} from '../../foundation/agent-docs/agent-docs.mjs';
import * as debug from '../../foundation/debug/index.mjs';
@@ -596,6 +597,7 @@ export async function createProgram() {
text(`Run \`${getCliInvocation()} manifest --json\` for the full structured manifest.`),
);
});
+ addExitCodesHelp(manifestCommand, manifestDoc.exitCodes);
markReportsResult(manifestCommand);
// Hidden command used by package.json postinstall scripts
diff --git a/packages/cli/clients/cli/lib/define-command.mjs b/packages/cli/clients/cli/lib/define-command.mjs
index 38394dfe7a..d772cd2edb 100644
--- a/packages/cli/clients/cli/lib/define-command.mjs
+++ b/packages/cli/clients/cli/lib/define-command.mjs
@@ -25,6 +25,7 @@
*/
import {recordCommandResult} from '../../../foundation/debug/index.mjs';
+import {text} from '../formatters/index.mjs';
/**
* Marks a Commander command that reports what it answered with, and says HOW:
@@ -78,6 +79,21 @@ export function markReportsResult(cmd) {
return cmd;
}
+/** The CommandDoc and wrapped FunctionDoc a command was built from. */
+export const COMMAND_DOCS = Symbol.for('astryx.command.docs');
+
+/**
+ * The docs a command was built from; undefined for a hand-registered command.
+ * @param {import('commander').Command} cmd
+ * @returns {{
+ * doc: import('@astryxdesign/cli/authoring').CommandDoc,
+ * fn?: import('@astryxdesign/cli/authoring').FunctionDoc,
+ * } | undefined}
+ */
+export function commandDocsOf(cmd) {
+ return /** @type {any} */ (cmd)?.[COMMAND_DOCS];
+}
+
/**
* Build a Commander command from a CommandDoc and attach it to `parent`.
*
@@ -102,6 +118,7 @@ export function defineCommand(parent, doc, {fn, action} = {}) {
.join(' ');
const cmd = parent.command(argSpec ? `${token} ${argSpec}` : token);
+ Object.defineProperty(cmd, COMMAND_DOCS, {value: {doc, fn}, configurable: true});
if (doc.summary) cmd.description(doc.summary);
const paramDesc = (/** @type {string | undefined} */ name) =>
@@ -126,12 +143,10 @@ export function defineCommand(parent, doc, {fn, action} = {}) {
cmd.addOption(option);
}
- // `choices` and `examples` are doc metadata surfaced by `astryx docs` and the
- // doc site; they are intentionally NOT injected into `--help` here. Choices
- // stay described in the option text (Commander `.choices()` would also change
- // validation from the api layer's ERR_INVALID_ARGUMENT), and the current CLI
- // help carries no per-command examples epilog. Keeping both out preserves the
- // exact `--help`/manifest surface as registrations migrate to this converter.
+ // Help ends with the documented exit codes. `choices` stay in the option
+ // text: Commander `.choices()` would replace the api layer's
+ // ERR_INVALID_ARGUMENT validation.
+ addExitCodesHelp(cmd, doc.exitCodes);
if (action) {
// The recording seam. An action's job ends at "here is what I answered
@@ -149,3 +164,14 @@ export function defineCommand(parent, doc, {fn, action} = {}) {
}
return cmd;
}
+
+/**
+ * End `cmd`'s help with a CommandDoc's exit codes.
+ * @param {import('commander').Command} cmd
+ * @param {import('@astryxdesign/cli/authoring').CommandDoc['exitCodes']} exitCodes
+ */
+export function addExitCodesHelp(cmd, exitCodes) {
+ if (!exitCodes?.length) return;
+ const lines = exitCodes.map(({code, when}) => ` ${code} ${when}`);
+ cmd.addHelpText('after', `\n${text(['Exit codes:', ...lines].join('\n')).toString()}`);
+}
diff --git a/packages/cli/clients/cli/lib/exit-codes.test.mjs b/packages/cli/clients/cli/lib/exit-codes.test.mjs
new file mode 100644
index 0000000000..4b26ce6e5e
--- /dev/null
+++ b/packages/cli/clients/cli/lib/exit-codes.test.mjs
@@ -0,0 +1,97 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Every CommandDoc's exit codes reach generated help and the manifest.
+ */
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {fileURLToPath, pathToFileURL} from 'node:url';
+import {describe, it, expect} from 'vitest';
+import {program, JSON_SUPPORTED} from '../index.mjs';
+import {buildManifest} from './manifest.mjs';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+
+const COMMANDS = path.join(path.dirname(fileURLToPath(import.meta.url)), '../commands');
+
+/** @type {any[]} */
+const commandDocs = [];
+for (const file of fs.readdirSync(COMMANDS).sort()) {
+ if (!file.endsWith('.doc.mjs')) continue;
+ const {doc} = await import(pathToFileURL(path.join(COMMANDS, file)).href);
+ if (doc?.type === 'command') commandDocs.push(doc);
+}
+
+const manifest = buildManifest(program, {jsonSupported: JSON_SUPPORTED, version: '0.0.0-test'});
+/** @type {Map<string, any>} */
+const entries = new Map();
+const walk = (/** @type {any} */ c) => {
+ entries.set(c.name, c);
+ (c.subcommands || []).forEach(walk);
+};
+manifest.commands.forEach(walk);
+
+describe('command exit codes', () => {
+ it('every CommandDoc documents its exit codes', () => {
+ expect(commandDocs.length).toBeGreaterThan(30);
+ for (const doc of commandDocs) {
+ expect(doc.exitCodes?.length, doc.name).toBeGreaterThan(0);
+ }
+ });
+
+ it.each(commandDocs.map((d) => [d.name, d]))(
+ '`astryx %s --help` lists the documented exit codes',
+ async (name, doc) => {
+ const {status, stdout} = await runCli([...name.split(' '), '--help']);
+ expect(status).toBe(0);
+ const section = stdout.slice(stdout.indexOf('\nExit codes:\n'));
+ expect(section.startsWith('\nExit codes:\n'), stdout).toBe(true);
+ expect(stdout.match(/\nExit codes?:\n/g), 'one exit-code section').toHaveLength(1);
+ for (const {code, when} of doc.exitCodes) {
+ expect(section).toContain(`\n ${code} ${when}\n`);
+ }
+ },
+ );
+
+ it('bare `astryx layout` exits 1 in both modes, as documented', async () => {
+ const doc = commandDocs.find((d) => d.name === 'layout');
+ expect(doc.exitCodes.find((e) => e.code === 1)?.when).toMatch(/^no subcommand/);
+ expect((await runCli(['layout'])).status).toBe(1);
+ expect((await runCli(['layout', '--json'])).status).toBe(1);
+ });
+
+ it('`astryx discover` with a blank query exits 1 only when packages are discovered', async () => {
+ const doc = commandDocs.find((d) => d.name === 'discover');
+ expect(doc.exitCodes.find((e) => e.code === 1)?.when).toMatch(/blank query when packages are discovered/);
+ const project = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-exit-discover-'));
+ try {
+ expect((await runCli(['discover', ' ', '--json'], {cwd: project})).status).toBe(0);
+ const pkg = path.join(project, 'node_modules/@acme/ui');
+ fs.mkdirSync(path.join(pkg, 'components'), {recursive: true});
+ fs.writeFileSync(path.join(pkg, 'package.json'), '{"name":"@acme/ui","version":"1.0.0","type":"module"}');
+ fs.writeFileSync(path.join(pkg, 'astryx.integration.mjs'), "export default {components: './components'};\n");
+ fs.writeFileSync(
+ path.join(pkg, 'components/Widget.doc.mjs'),
+ 'export const doc = {type: "component", name: "Widget", description: "A widget"};\n',
+ );
+ fs.writeFileSync(path.join(pkg, 'components/Widget.tsx'), 'export function Widget() { return null; }\n');
+ fs.writeFileSync(path.join(project, 'package.json'), '{"name":"app","type":"module"}');
+ fs.writeFileSync(path.join(project, 'astryx.config.mjs'), "export default {integrations: ['@acme/ui']};\n");
+ expect((await runCli(['discover', '--json'], {cwd: project})).status).toBe(0);
+ const blank = await runCli(['discover', ' ', '--json'], {cwd: project});
+ expect(blank.status).toBe(1);
+ expect(JSON.parse(blank.stdout).code).toBe('ERR_INVALID_ARGUMENT');
+ } finally {
+ fs.rmSync(project, {recursive: true, force: true});
+ }
+ });
+
+ it('the manifest carries every command exit code', () => {
+ for (const doc of commandDocs) {
+ 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.d.ts b/packages/cli/clients/cli/lib/manifest.d.ts
index 0e3aa6af77..c783816c25 100644
--- a/packages/cli/clients/cli/lib/manifest.d.ts
+++ b/packages/cli/clients/cli/lib/manifest.d.ts
@@ -48,6 +48,8 @@ export interface ManifestCommand {
responseTypes?: string[];
/** Example invocations. */
examples?: string[];
+ /** Documented exit codes: the process exit status and when it occurs. */
+ exitCodes?: {code: number; when: string}[];
/** Nested subcommands (e.g. `theme build` under `theme`). */
subcommands?: ManifestCommand[];
}
diff --git a/packages/cli/clients/cli/lib/manifest.mjs b/packages/cli/clients/cli/lib/manifest.mjs
index 154514f559..080b2363b8 100644
--- a/packages/cli/clients/cli/lib/manifest.mjs
+++ b/packages/cli/clients/cli/lib/manifest.mjs
@@ -35,6 +35,8 @@
*/
import {API_VERSION} from '../../../foundation/response/json.mjs';
+import {commandDocsOf} from './define-command.mjs';
+import {doc as manifestDoc} from '../commands/manifest.doc.mjs';
/**
* Response `type` discriminators each fully-qualified command can emit in
@@ -237,6 +239,18 @@ function fullName(cmd, root) {
return parts.join(' ');
}
+/**
+ * The docs a command was built from. `manifest` is registered by hand in
+ * index.mjs, so its CommandDoc is read here.
+ * @param {import('commander').Command} cmd
+ * @param {string} name
+ */
+function docsOf(cmd, name) {
+ return (
+ commandDocsOf(cmd) ?? (name === 'manifest' ? {doc: manifestDoc} : undefined)
+ );
+}
+
/**
* Recursively describe a Commander command and its subcommands.
*
@@ -252,6 +266,8 @@ function describeCommand(cmd, root, jsonSupported) {
// `_hidden` is a Commander internal not present on its public types.
if (!name || /** @type {any} */ (cmd)._hidden || name === 'help') return null;
+ const docs = docsOf(cmd, name);
+
const subcommands = /** @type {object[]} */ (
(cmd.commands || [])
.map(sub => describeCommand(sub, root, jsonSupported))
@@ -284,6 +300,12 @@ function describeCommand(cmd, root, jsonSupported) {
if (EXAMPLES[name]) entry.examples = [...EXAMPLES[name]];
+ const exitCodes = (docs?.doc.exitCodes ?? []).map(({code, when}) => ({
+ code,
+ when,
+ }));
+ if (exitCodes.length > 0) entry.exitCodes = exitCodes;
+
// Sort subcommands by name for a stable, agent-facing contract — the same
// guarantee the top-level command list makes. Otherwise Commander
// registration order leaks into the manifest and a pure reorder of
diff --git a/packages/cli/foundation/response/response-types.doc.mjs b/packages/cli/foundation/response/response-types.doc.mjs
index 067f8a4c8a..5d4e36087e 100644
--- a/packages/cli/foundation/response/response-types.doc.mjs
+++ b/packages/cli/foundation/response/response-types.doc.mjs
@@ -257,7 +257,7 @@ export const doc = {
{
value: 'manifest',
description:
- 'The self-describing CLI capability manifest: name, version, apiVersion, global options, the command tree (args, options, json flag, response types, examples), the jsonSupported allowlist, and the flat responseTypes index.',
+ 'The CLI capability manifest: name, version, apiVersion, description, globalOptions, commands (each name, description, arguments, options, json, aliases?, responseTypes?, examples?, exitCodes? as [{code, when}], subcommands?), jsonSupported, and the flat responseTypes index.',
},
// doctor