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.mdnew file mode 100644index 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.++@josephfarinadiff --git a/packages/cli/README.md b/packages/cli/README.mdindex 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.```bashastryx 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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 scriptsdiff --git a/packages/cli/clients/cli/lib/define-command.mjs b/packages/cli/clients/cli/lib/define-command.mjsindex 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.mjsnew file mode 100644index 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.tsindex 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.mjsindex 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 ofdiff --git a/packages/cli/foundation/response/response-types.doc.mjs b/packages/cli/foundation/response/response-types.doc.mjsindex 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