@astryxdesign/cli 0.6.3 → 0.6.4-canary.078fd25

package/foundation/response/base.d.ts

@@ -29,6 +29,8 @@ export interface Suggestion {
  * human-readable `error` string, which changes freely.
  */
 export interface CLIError {
+  /** Version of the JSON envelope contract, as on the success envelope. */
+  apiVersion: number;
   error: string;
   code: ErrorCode;
   suggestions?: Suggestion[];
@@ -36,13 +38,15 @@ export interface CLIError {
 
 /** Returned by the fallback hook for commands without --json support. */
 export interface CLIUnsupportedError {
+  apiVersion: number;
   error: `JSON output is not supported for the '${string}' command`;
   code: ErrorCode;
 }
 
 /**
- * A success response envelope: a `type` discriminator, its `data` payload, and
- * an optional `meta` sidecar (emitted as a sibling of `data`, never merged in).
+ * A success response: a `type` discriminator, its `data` payload, and an
+ * optional `meta` sidecar (emitted as a sibling of `data`, never merged in).
+ * `--json` prints it with `apiVersion` added (see `parseResponse`).
  *
  * Structural by design — there is no central union of every response `type`.
  * A specific command narrows `data` via its own return type.
@@ -75,7 +79,7 @@ export function jsonError(
 /** Parse raw CLI output (string or object) into a typed result. */
 export function parseResponse(
   raw: unknown,
-): CLIResponse | CLIError | CLIUnsupportedError;
+): (CLIResponse & {apiVersion: number}) | CLIError | CLIUnsupportedError;
 
 /** Type guard: returns true if result is an error. */
 export function isError(
@@ -90,7 +94,7 @@ export function isError(
 export function assertResponse<T extends string>(
   raw: unknown,
   type: T,
-): CLIResponse & {type: T};
+): CLIResponse & {apiVersion: number; type: T};
 
 declare global {
   namespace NodeJS {

package/foundation/response/batch.type.d.mts

@@ -0,0 +1,33 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * One complete row for an accepted selector.
+ */
+export type BatchRow<TResult, TCandidate> = ({
+    selector: string;
+    status: "found";
+    result: TResult;
+} | {
+    selector: string;
+    status: "ambiguous";
+    code: string;
+    error: string;
+    candidates: TCandidate[];
+} | {
+    selector: string;
+    status: "not_found" | "error";
+    code: string;
+    error: string;
+    suggestions?: import("./base").Suggestion[];
+});
+/**
+ * One ordered batch receipt inside the shared `{type, data}` success envelope.
+ */
+export type BatchResponse<TType extends string, TResult, TCandidate> = {
+    type: TType;
+    data: {
+        count: number;
+        results: BatchRow<TResult, TCandidate>[];
+    };
+};

package/foundation/response/batch.type.mjs

@@ -0,0 +1,34 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Shared published types for complete multi-selector lookup receipts.
+ * Adopting API subjects specialize these types with their single-result and
+ * ambiguity-candidate types instead of defining command-specific row shapes.
+ *
+ * @input One exact selector, its single-result response, and its candidate shape.
+ * @output BatchRow and BatchResponse for every AST-053 lookup adopter.
+ * @position packages/cli/foundation/response — shared JSON response types
+ */
+
+/**
+ * One complete row for an accepted selector.
+ * @template TResult
+ * @template TCandidate
+ * @typedef {(
+ *   | {selector: string; status: 'found'; result: TResult}
+ *   | {selector: string; status: 'ambiguous'; code: string; error: string; candidates: TCandidate[]}
+ *   | {selector: string; status: 'not_found' | 'error'; code: string; error: string; suggestions?: import('./base').Suggestion[]}
+ * )} BatchRow
+ */
+
+/**
+ * One ordered batch receipt inside the shared `{type, data}` success envelope.
+ * @template {string} TType
+ * @template TResult
+ * @template TCandidate
+ * @typedef {object} BatchResponse
+ * @property {TType} type
+ * @property {{count: number; results: BatchRow<TResult, TCandidate>[]}} data
+ */
+
+export {};

package/foundation/response/error-codes.d.mts

@@ -75,6 +75,8 @@ export function allErrorCodes(): string[];
  *   | 'ERR_UNKNOWN_FEATURE'
  *   | 'ERR_UNKNOWN_CODEMOD'
  *   | 'ERR_CODEMOD_FAILED'
+ *   | 'ERR_CODEMOD_PROTECTED'
+ *   | 'ERR_CODEMOD_PROTECTION_SOURCE'
  *   | 'ERR_NOT_FOUND'
  *   | 'ERR_NO_DOC'
  *   | 'ERR_NO_SHOWCASE'
@@ -107,4 +109,4 @@ export const ERROR_CODES: Readonly<Record<ErrorCode, ErrorCode>>;
 /**
  * Stable error-code string union. Append-only.
  */
-export type ErrorCode = ("ERR_UNKNOWN" | "ERR_UNKNOWN_COMMAND" | "ERR_UNKNOWN_SUBCOMMAND" | "ERR_INVALID_OPTION" | "ERR_INVALID_ARGUMENT" | "ERR_MISSING_ARGUMENT" | "ERR_INVALID_LANG" | "ERR_INVALID_DETAIL" | "ERR_NODE_VERSION" | "ERR_CORE_NOT_FOUND" | "ERR_CORE_INCOMPATIBLE" | "ERR_UNKNOWN_COMPONENT" | "ERR_UNKNOWN_HOOK" | "ERR_UNKNOWN_TOPIC" | "ERR_UNKNOWN_SECTION" | "ERR_UNKNOWN_CATEGORY" | "ERR_UNKNOWN_TEMPLATE" | "ERR_AMBIGUOUS_TEMPLATE" | "ERR_AMBIGUOUS_COMPONENT" | "ERR_AMBIGUOUS_THEME" | "ERR_UNKNOWN_THEME" | "ERR_INTEGRATION_ROOT_CONFLICT" | "ERR_INTEGRATION_EXPORT_CONFLICT" | "ERR_UNKNOWN_PACKAGE" | "ERR_UNKNOWN_AGENT" | "ERR_UNKNOWN_FEATURE" | "ERR_UNKNOWN_CODEMOD" | "ERR_CODEMOD_FAILED" | "ERR_NOT_FOUND" | "ERR_NO_DOC" | "ERR_NO_SHOWCASE" | "ERR_NO_SOURCE" | "ERR_INVALID_DOC" | "ERR_FILE_NOT_FOUND" | "ERR_FILE_EXISTS" | "ERR_PATH_TRAVERSAL" | "ERR_WRITE_FAILED" | "ERR_THEME_INVALID" | "ERR_THEME_LOAD" | "ERR_PALETTE_GENERATION" | "ERR_VERSION_DETECT" | "ERR_INVALID_VERSION" | "ERR_DEP_MISSING" | "ERR_GH_CLI" | "ERR_UNKNOWN_POST" | "ERR_FETCH_FAILED" | "ERR_LAYOUT_PARSE" | "ERR_LAYOUT_INVALID" | "ERR_UNCLASSIFIED_EXIT" | "ERR_SIGNAL_TERMINATED");
+export type ErrorCode = ("ERR_UNKNOWN" | "ERR_UNKNOWN_COMMAND" | "ERR_UNKNOWN_SUBCOMMAND" | "ERR_INVALID_OPTION" | "ERR_INVALID_ARGUMENT" | "ERR_MISSING_ARGUMENT" | "ERR_INVALID_LANG" | "ERR_INVALID_DETAIL" | "ERR_NODE_VERSION" | "ERR_CORE_NOT_FOUND" | "ERR_CORE_INCOMPATIBLE" | "ERR_UNKNOWN_COMPONENT" | "ERR_UNKNOWN_HOOK" | "ERR_UNKNOWN_TOPIC" | "ERR_UNKNOWN_SECTION" | "ERR_UNKNOWN_CATEGORY" | "ERR_UNKNOWN_TEMPLATE" | "ERR_AMBIGUOUS_TEMPLATE" | "ERR_AMBIGUOUS_COMPONENT" | "ERR_AMBIGUOUS_THEME" | "ERR_UNKNOWN_THEME" | "ERR_INTEGRATION_ROOT_CONFLICT" | "ERR_INTEGRATION_EXPORT_CONFLICT" | "ERR_UNKNOWN_PACKAGE" | "ERR_UNKNOWN_AGENT" | "ERR_UNKNOWN_FEATURE" | "ERR_UNKNOWN_CODEMOD" | "ERR_CODEMOD_FAILED" | "ERR_CODEMOD_PROTECTED" | "ERR_CODEMOD_PROTECTION_SOURCE" | "ERR_NOT_FOUND" | "ERR_NO_DOC" | "ERR_NO_SHOWCASE" | "ERR_NO_SOURCE" | "ERR_INVALID_DOC" | "ERR_FILE_NOT_FOUND" | "ERR_FILE_EXISTS" | "ERR_PATH_TRAVERSAL" | "ERR_WRITE_FAILED" | "ERR_THEME_INVALID" | "ERR_THEME_LOAD" | "ERR_PALETTE_GENERATION" | "ERR_VERSION_DETECT" | "ERR_INVALID_VERSION" | "ERR_DEP_MISSING" | "ERR_GH_CLI" | "ERR_UNKNOWN_POST" | "ERR_FETCH_FAILED" | "ERR_LAYOUT_PARSE" | "ERR_LAYOUT_INVALID" | "ERR_UNCLASSIFIED_EXIT" | "ERR_SIGNAL_TERMINATED");

package/foundation/response/error-codes.d.ts

@@ -34,6 +34,8 @@ export type ErrorCode =
   | 'ERR_UNKNOWN_FEATURE'
   | 'ERR_UNKNOWN_CODEMOD'
   | 'ERR_CODEMOD_FAILED'
+  | 'ERR_CODEMOD_PROTECTED'
+  | 'ERR_CODEMOD_PROTECTION_SOURCE'
   | 'ERR_NOT_FOUND'
   | 'ERR_NO_DOC'
   | 'ERR_NO_SHOWCASE'

package/foundation/response/error-codes.doc.mjs

@@ -12,7 +12,7 @@ export const doc = {
   type: 'enum',
   name: 'error-codes',
   displayName: 'Error Codes',
-  namespace: 'cli',
+  namespace: 'cli/api',
   description:
     'Stable, append-only machine-readable error codes on the --json error envelope (envelope.code). Codes never change or get removed; branch on these, not on prose.',
   members: [
@@ -36,17 +36,16 @@ export const doc = {
     {
       value: 'ERR_INVALID_OPTION',
       description:
-        'An unknown flag/option was passed (Commander `unknownOption`).',
+        'An unknown option was passed, --json was given to a command without JSON output, or layout --form got a value other than compact, outline, or auto.',
     },
     {
       value: 'ERR_INVALID_ARGUMENT',
       description:
-        "An option/argument had a value Commander's parser rejected.",
+        'An argument or option value is invalid: wrong type, out of range, an unknown choice, an extra argument, or a conflicting combination.',
     },
     {
       value: 'ERR_MISSING_ARGUMENT',
-      description:
-        'A required positional argument was omitted (Commander `missingArgument`).',
+      description: 'A required argument or option value was omitted.',
     },
     {
       value: 'ERR_INVALID_LANG',
@@ -134,12 +133,11 @@ export const doc = {
     },
     {
       value: 'ERR_UNKNOWN_PACKAGE',
-      description: 'No package matched the requested name (discover).',
+      description: 'No package matched the requested name.',
     },
     {
       value: 'ERR_UNKNOWN_AGENT',
-      description:
-        'An unrecognized `--agent` value was passed to agent-docs/init.',
+      description: 'An unrecognized `--agent` value was passed to init.',
     },
     {
       value: 'ERR_UNKNOWN_FEATURE',
@@ -154,6 +152,16 @@ export const doc = {
       value: 'ERR_CODEMOD_FAILED',
       description: 'One or more codemods failed during an upgrade run.',
     },
+    {
+      value: 'ERR_CODEMOD_PROTECTED',
+      description:
+        'A required codemod change remains blocked by a protected consumer file.',
+    },
+    {
+      value: 'ERR_CODEMOD_PROTECTION_SOURCE',
+      description:
+        'A working-tree protection declaration could not be read or parsed.',
+    },
     {
       value: 'ERR_NOT_FOUND',
       description:
@@ -187,8 +195,7 @@ export const doc = {
     },
     {
       value: 'ERR_FILE_EXISTS',
-      description:
-        'Refused to overwrite an existing file in non-interactive mode.',
+      description: 'Refused to overwrite an existing file.',
     },
     {
       value: 'ERR_PATH_TRAVERSAL',
@@ -204,7 +211,7 @@ export const doc = {
     {
       value: 'ERR_THEME_INVALID',
       description:
-        'A theme definition or contributed theme catalog is invalid.',
+        'A theme definition or contributed theme descriptor is invalid.',
     },
     {
       value: 'ERR_THEME_LOAD',
@@ -263,7 +270,7 @@ export const doc = {
     {
       value: 'ERR_UNCLASSIFIED_EXIT',
       description:
-        'Recorded in the debug log, never printed: a command exited non-zero without going through cliError/jsonError, so no stable code was available.',
+        'Recorded in the debug log, never printed: a command exited non-zero without reporting an error code.',
     },
     {
       value: 'ERR_SIGNAL_TERMINATED',

package/foundation/response/error-codes.mjs

@@ -64,6 +64,8 @@
  *   | 'ERR_UNKNOWN_FEATURE'
  *   | 'ERR_UNKNOWN_CODEMOD'
  *   | 'ERR_CODEMOD_FAILED'
+ *   | 'ERR_CODEMOD_PROTECTED'
+ *   | 'ERR_CODEMOD_PROTECTION_SOURCE'
  *   | 'ERR_NOT_FOUND'
  *   | 'ERR_NO_DOC'
  *   | 'ERR_NO_SHOWCASE'
@@ -161,6 +163,10 @@ export const ERROR_CODES = Object.freeze({
   ERR_UNKNOWN_CODEMOD: 'ERR_UNKNOWN_CODEMOD',
   /** One or more codemods failed during an upgrade run. */
   ERR_CODEMOD_FAILED: 'ERR_CODEMOD_FAILED',
+  /** A required codemod change remains blocked by a protected consumer file. */
+  ERR_CODEMOD_PROTECTED: 'ERR_CODEMOD_PROTECTED',
+  /** A working-tree protection declaration could not be read or parsed. */
+  ERR_CODEMOD_PROTECTION_SOURCE: 'ERR_CODEMOD_PROTECTION_SOURCE',
   /** A generic discover/lookup query matched nothing in any package. */
   ERR_NOT_FOUND: 'ERR_NOT_FOUND',
 
@@ -177,7 +183,7 @@ export const ERROR_CODES = Object.freeze({
   // ── Filesystem ───────────────────────────────────────────────────
   /** A required input file did not exist. */
   ERR_FILE_NOT_FOUND: 'ERR_FILE_NOT_FOUND',
-  /** Refused to overwrite an existing file in non-interactive mode. */
+  /** Refused to overwrite an existing file. */
   ERR_FILE_EXISTS: 'ERR_FILE_EXISTS',
   /** A path escaped its allowed root, or a name contained traversal markers. */
   ERR_PATH_TRAVERSAL: 'ERR_PATH_TRAVERSAL',
@@ -185,7 +191,7 @@ export const ERROR_CODES = Object.freeze({
   ERR_WRITE_FAILED: 'ERR_WRITE_FAILED',
 
   // ── Theme build ──────────────────────────────────────────────────
-  /** A theme definition or contributed theme catalog is invalid. */
+  /** A theme definition or contributed theme descriptor is invalid. */
   ERR_THEME_INVALID: 'ERR_THEME_INVALID',
   /** A theme file could not be loaded / parsed into a defineTheme result. */
   ERR_THEME_LOAD: 'ERR_THEME_LOAD',

package/foundation/response/error-codes.test.mjs

@@ -15,6 +15,9 @@
  */
 
 import {describe, it, expect} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
 import {ERROR_CODES, isErrorCode, allErrorCodes} from './error-codes.mjs';
 import {runCli} from '../../test-utils/run-cli.mjs';
 
@@ -75,20 +78,133 @@ describe('error-codes taxonomy', () => {
   });
 });
 
+describe('error codes: shipped set', () => {
+  // Every code a release has published. INV3: a shipped code is never removed
+  // or respelled. Add a code here once it ships; never delete an entry.
+  const SHIPPED = [
+    'ERR_AMBIGUOUS_COMPONENT',
+    'ERR_AMBIGUOUS_TEMPLATE',
+    'ERR_AMBIGUOUS_THEME',
+    'ERR_CODEMOD_FAILED',
+    'ERR_CODEMOD_PROTECTED',
+    'ERR_CODEMOD_PROTECTION_SOURCE',
+    'ERR_CORE_INCOMPATIBLE',
+    'ERR_CORE_NOT_FOUND',
+    'ERR_DEP_MISSING',
+    'ERR_FETCH_FAILED',
+    'ERR_FILE_EXISTS',
+    'ERR_FILE_NOT_FOUND',
+    'ERR_GH_CLI',
+    'ERR_INTEGRATION_EXPORT_CONFLICT',
+    'ERR_INTEGRATION_ROOT_CONFLICT',
+    'ERR_INVALID_ARGUMENT',
+    'ERR_INVALID_DETAIL',
+    'ERR_INVALID_DOC',
+    'ERR_INVALID_LANG',
+    'ERR_INVALID_OPTION',
+    'ERR_INVALID_VERSION',
+    'ERR_LAYOUT_INVALID',
+    'ERR_LAYOUT_PARSE',
+    'ERR_MISSING_ARGUMENT',
+    'ERR_NODE_VERSION',
+    'ERR_NOT_FOUND',
+    'ERR_NO_DOC',
+    'ERR_NO_SHOWCASE',
+    'ERR_NO_SOURCE',
+    'ERR_PALETTE_GENERATION',
+    'ERR_PATH_TRAVERSAL',
+    'ERR_SIGNAL_TERMINATED',
+    'ERR_THEME_INVALID',
+    'ERR_THEME_LOAD',
+    'ERR_UNCLASSIFIED_EXIT',
+    'ERR_UNKNOWN',
+    'ERR_UNKNOWN_AGENT',
+    'ERR_UNKNOWN_CATEGORY',
+    'ERR_UNKNOWN_CODEMOD',
+    'ERR_UNKNOWN_COMMAND',
+    'ERR_UNKNOWN_COMPONENT',
+    'ERR_UNKNOWN_FEATURE',
+    'ERR_UNKNOWN_HOOK',
+    'ERR_UNKNOWN_PACKAGE',
+    'ERR_UNKNOWN_POST',
+    'ERR_UNKNOWN_SECTION',
+    'ERR_UNKNOWN_SUBCOMMAND',
+    'ERR_UNKNOWN_TEMPLATE',
+    'ERR_UNKNOWN_THEME',
+    'ERR_UNKNOWN_TOPIC',
+    'ERR_VERSION_DETECT',
+    'ERR_WRITE_FAILED',
+  ];
+
+  it('still carries every shipped code, spelled the same', () => {
+    const missing = SHIPPED.filter(
+      code => !isErrorCode(code) || ERROR_CODES[code] !== code,
+    );
+    expect(missing, 'shipped codes removed or respelled').toEqual([]);
+  });
+});
+
 describe('error codes: end-to-end JSON envelopes', () => {
   const cases = [
-    {name: 'unknown component', args: ['component', 'Bogus', '--json'], code: 'ERR_UNKNOWN_COMPONENT'},
-    {name: 'unknown hook', args: ['hook', 'bogusHook', '--json'], code: 'ERR_UNKNOWN_HOOK'},
-    {name: 'unknown topic', args: ['docs', 'bogusTopic', '--json'], code: 'ERR_UNKNOWN_TOPIC'},
-    {name: 'unknown template', args: ['template', 'bogusTemplate', '--json'], code: 'ERR_UNKNOWN_TEMPLATE'},
-    {name: 'unknown command', args: ['bogus-cmd', '--json'], code: 'ERR_UNKNOWN_COMMAND'},
-    {name: 'invalid --lang', args: ['docs', 'color', '--lang', 'fr', '--json'], code: 'ERR_INVALID_LANG'},
-    {name: 'invalid --detail', args: ['docs', 'color', '--detail', 'bogus', '--json'], code: 'ERR_INVALID_DETAIL'},
-    {name: 'unknown option', args: ['component', 'Button', '--bogus-flag', '--json'], code: 'ERR_INVALID_OPTION'},
-    {name: 'missing argument', args: ['theme', 'build', '--json'], code: 'ERR_MISSING_ARGUMENT'},
+    {
+      name: 'unknown component',
+      args: ['component', 'Bogus', '--json'],
+      code: 'ERR_UNKNOWN_COMPONENT',
+    },
+    {
+      name: 'unknown hook',
+      args: ['hook', 'bogusHook', '--json'],
+      code: 'ERR_UNKNOWN_HOOK',
+    },
+    {
+      name: 'unknown topic',
+      args: ['docs', 'bogusTopic', '--json'],
+      code: 'ERR_UNKNOWN_TOPIC',
+    },
+    {
+      name: 'unknown template',
+      args: ['template', 'bogusTemplate', '--json'],
+      code: 'ERR_UNKNOWN_TEMPLATE',
+    },
+    {
+      name: 'unknown command',
+      args: ['bogus-cmd', '--json'],
+      code: 'ERR_UNKNOWN_COMMAND',
+    },
+    {
+      name: 'invalid --lang',
+      args: ['docs', 'color', '--lang', 'fr', '--json'],
+      code: 'ERR_INVALID_LANG',
+    },
+    {
+      name: 'invalid --detail',
+      args: ['docs', 'color', '--detail', 'bogus', '--json'],
+      code: 'ERR_INVALID_DETAIL',
+    },
+    {
+      name: 'unknown option',
+      args: ['component', 'Button', '--bogus-flag', '--json'],
+      code: 'ERR_INVALID_OPTION',
+    },
+    {
+      name: 'missing argument',
+      args: ['theme', 'build', '--json'],
+      code: 'ERR_MISSING_ARGUMENT',
+    },
     // `theme` is not on the --json allowlist, so --json on any theme subcommand
     // is rejected at the preAction gate with a stable invalid-option code.
-    {name: 'json not supported', args: ['theme', 'bogus-sub', '--json'], code: 'ERR_INVALID_OPTION'},
+    {
+      name: 'json not supported',
+      args: ['theme', '--json'],
+      code: 'ERR_INVALID_OPTION',
+    },
+    // A group given a word it does not have names the unknown subcommand,
+    // in JSON as in text.
+    {
+      name: 'unknown subcommand of a group',
+      args: ['theme', 'bogus-sub', '--json'],
+      code: 'ERR_UNKNOWN_SUBCOMMAND',
+    },
   ];
 
   for (const {name, args, code} of cases) {
@@ -104,6 +220,24 @@ describe('error codes: end-to-end JSON envelopes', () => {
     });
   }
 
+  it('a filesystem failure carries a registered code, never the Node errno', async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-errno-'));
+    try {
+      // A file where the target directory should be: mkdir fails with ENOTDIR.
+      fs.writeFileSync(path.join(dir, 'blocker'), 'x');
+      const {status, stdout} = await runCli(
+        ['template', 'dashboard', 'blocker/out', '--json'],
+        {cwd: dir},
+      );
+      expect(status).toBe(1);
+      const env = envelope(stdout);
+      expect(env.error).toMatch(/ENOTDIR/);
+      expect(isErrorCode(env.code)).toBe(true);
+    } finally {
+      fs.rmSync(dir, {recursive: true, force: true});
+    }
+  });
+
   it('every error envelope carries a code (even unmatched paths fall back to ERR_UNKNOWN)', async () => {
     const {stdout} = await runCli(['component', 'Bogus', '--json']);
     const env = envelope(stdout);
@@ -122,13 +256,31 @@ describe('error codes: human mode stays clean', () => {
     expect(stdout).not.toContain('ERR_UNKNOWN_COMPONENT');
   });
 
-  it('unknown subcommand exits 1 in human mode (code carried internally)', async () => {
-    // `theme` is not JSON-capable, so this path is human-only; we assert the
-    // failure surfaces with exit 1 and a helpful message. The stable
-    // ERR_UNKNOWN_SUBCOMMAND code rides along on the cliError call.
+  it('unknown subcommand exits 1, with the code in JSON and not in text', async () => {
+    // A group that is not JSON-capable itself still answers an unknown
+    // subcommand in JSON, so a JSON caller learns the subcommands it has.
     const {status, stderr} = await runCli(['theme', 'bogus-sub']);
     expect(status).toBe(1);
     expect(stderr).toContain("unknown subcommand 'theme bogus-sub'");
     expect(stderr).not.toContain('ERR_UNKNOWN_SUBCOMMAND');
+    for (const args of [
+      ['--json', 'theme', 'bogus-sub'],
+      ['theme', 'bogus-sub', '--json'],
+      ['--json', 'doctor', 'integration', 'bogus-sub'],
+    ]) {
+      const json = await runCli(args);
+      expect(json.status, args.join(' ')).toBe(1);
+      expect(JSON.parse(json.stdout), args.join(' ')).toMatchObject({
+        code: 'ERR_UNKNOWN_SUBCOMMAND',
+        suggestions: expect.arrayContaining([expect.objectContaining({reason: 'available subcommand'})]),
+      });
+    }
+    // Text and JSON agree for a group that shows help when run bare.
+    const text = await runCli(['doctor', 'integration', 'bogus-sub']);
+    expect(text.status).toBe(1);
+    expect(text.stderr).toContain("unknown subcommand 'doctor integration bogus-sub'");
+    const doctor = await runCli(['doctor', 'integrations']);
+    expect(doctor.status).toBe(1);
+    expect(doctor.stderr).toContain("unknown subcommand 'doctor integrations'");
   });
 });

package/foundation/response/json-contract.test.mjs

@@ -13,6 +13,8 @@
 
 import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
 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 {
@@ -27,10 +29,20 @@ import {
 } from './json.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const CLI = path.resolve(__dirname, '..', '..', 'clients', 'cli', 'bin', 'astryx.mjs');
-
-function runCli(args) {
+const CLI = path.resolve(
+  __dirname,
+  '..',
+  '..',
+  'clients',
+  'cli',
+  'bin',
+  'astryx.mjs',
+);
+
+/** @param {string[]} args @param {{cwd?: string}} [options] */
+function runCli(args, {cwd = process.cwd()} = {}) {
   return spawnSync(process.execPath, [CLI, ...args], {
+    cwd,
     encoding: 'utf8',
     timeout: 20_000,
     stdio: ['ignore', 'pipe', 'pipe'],
@@ -42,7 +54,9 @@ describe('json envelope shape', () => {
   let logs;
   beforeEach(() => {
     logs = [];
-    vi.spyOn(console, 'log').mockImplementation((...a) => logs.push(a.join(' ')));
+    vi.spyOn(console, 'log').mockImplementation((...a) =>
+      logs.push(a.join(' ')),
+    );
     setJsonMode(false);
   });
   afterEach(() => {
@@ -80,11 +94,13 @@ describe('json envelope shape', () => {
   });
 
   it('toErrorEnvelope honors an explicit code argument', () => {
-    expect(toErrorEnvelope('boom', undefined, 'ERR_UNKNOWN_COMPONENT')).toEqual({
-      apiVersion: API_VERSION,
-      error: 'boom',
-      code: 'ERR_UNKNOWN_COMPONENT',
-    });
+    expect(toErrorEnvelope('boom', undefined, 'ERR_UNKNOWN_COMPONENT')).toEqual(
+      {
+        apiVersion: API_VERSION,
+        error: 'boom',
+        code: 'ERR_UNKNOWN_COMPONENT',
+      },
+    );
   });
 
   it('toErrorEnvelope reads a code carried on a thrown Error', () => {
@@ -96,6 +112,17 @@ describe('json envelope shape', () => {
     });
   });
 
+  it('toErrorEnvelope never emits an unregistered code', () => {
+    // A Node system error carries `code: 'EACCES'`; that is not an Astryx code.
+    const sysErr = Object.assign(new Error('EACCES: permission denied'), {
+      code: 'EACCES',
+    });
+    expect(toErrorEnvelope(sysErr).code).toBe('ERR_UNKNOWN');
+    expect(toErrorEnvelope('boom', undefined, 'ENOENT').code).toBe('ERR_UNKNOWN');
+    const docErr = Object.assign(new Error('no doc'), {code: 'ERR_NO_DOC'});
+    expect(toErrorEnvelope(docErr, undefined, 'ENOENT').code).toBe('ERR_NO_DOC');
+  });
+
   it('toErrorEnvelope includes suggestions when present', () => {
     const env = toErrorEnvelope('x', [{name: 'Button', reason: 'close match'}]);
     expect(env.suggestions).toEqual([{name: 'Button', reason: 'close match'}]);
@@ -109,8 +136,12 @@ describe('json envelope shape', () => {
     // The guard is `Array.isArray(...) && .length`, not a bare `?.length` — a
     // string ("hello".length === 5) or a `{length: n}` object must NOT slip
     // through as `suggestions`, which is contractually a Suggestion[].
-    expect('suggestions' in toErrorEnvelope('x', /** @type {any} */ ('hello'))).toBe(false);
-    expect('suggestions' in toErrorEnvelope('x', /** @type {any} */ ({length: 3}))).toBe(false);
+    expect(
+      'suggestions' in toErrorEnvelope('x', /** @type {any} */ ('hello')),
+    ).toBe(false);
+    expect(
+      'suggestions' in toErrorEnvelope('x', /** @type {any} */ ({length: 3})),
+    ).toBe(false);
   });
 });
 
@@ -119,8 +150,12 @@ describe('stdout discipline (humanLog / humanWarn)', () => {
   beforeEach(() => {
     logs = [];
     errs = [];
-    vi.spyOn(console, 'log').mockImplementation((...a) => logs.push(a.join(' ')));
-    vi.spyOn(console, 'error').mockImplementation((...a) => errs.push(a.join(' ')));
+    vi.spyOn(console, 'log').mockImplementation((...a) =>
+      logs.push(a.join(' ')),
+    );
+    vi.spyOn(console, 'error').mockImplementation((...a) =>
+      errs.push(a.join(' ')),
+    );
   });
   afterEach(() => {
     vi.restoreAllMocks();
@@ -174,10 +209,15 @@ describe('contract: every --json emission is valid JSON with apiVersion', () =>
   });
 
   it('init emits its install receipt', () => {
-    const r = runCli(['init', '--json']);
-    const env = JSON.parse(r.stdout);
-    expect(env.apiVersion).toBe(API_VERSION);
-    expect(env.type).toBe('init.run');
+    const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-json-contract-'));
+    try {
+      const r = runCli(['init', '--json'], {cwd});
+      const env = JSON.parse(r.stdout);
+      expect(env.apiVersion).toBe(API_VERSION);
+      expect(env.type).toBe('init.run');
+    } finally {
+      fs.rmSync(cwd, {recursive: true, force: true});
+    }
   });
 
   it('supported command (discover) emits clean JSON, no human chatter leak', () => {

package/foundation/response/json.d.mts

@@ -50,8 +50,10 @@ export function jsonOut(response: {
  *
  * The `code` is resolved in priority order: an explicit `code` argument,
  * then a `code` property carried on a thrown Error/AstryxError, then the
- * generic `ERR_UNKNOWN` fallback. It always appears on the envelope so
- * consumers can branch on it unconditionally.
+ * generic `ERR_UNKNOWN` fallback. Only a registered code (error-codes.mjs) is
+ * taken from either source, so a Node system error's `ENOENT` never reaches
+ * the envelope. It always appears on the envelope so consumers can branch on
+ * it unconditionally.
  *
  * @param {unknown} err
  * @param {import('./base').Suggestion[]} [suggestions]

package/foundation/response/json.mjs

@@ -28,7 +28,7 @@
  * Version of the JSON envelope contract. Bump on breaking shape changes so
  * consumers can negotiate. Exposed on every envelope as `apiVersion`.
  */
-import {ERROR_CODES} from './error-codes.mjs';
+import {ERROR_CODES, isErrorCode} from './error-codes.mjs';
 import {recordEnvelope, setOutcome} from '../debug/index.mjs';
 
 export const API_VERSION = 1;
@@ -118,8 +118,10 @@ export function jsonOut(response) {
  *
  * The `code` is resolved in priority order: an explicit `code` argument,
  * then a `code` property carried on a thrown Error/AstryxError, then the
- * generic `ERR_UNKNOWN` fallback. It always appears on the envelope so
- * consumers can branch on it unconditionally.
+ * generic `ERR_UNKNOWN` fallback. Only a registered code (error-codes.mjs) is
+ * taken from either source, so a Node system error's `ENOENT` never reaches
+ * the envelope. It always appears on the envelope so consumers can branch on
+ * it unconditionally.
  *
  * @param {unknown} err
  * @param {import('./base').Suggestion[]} [suggestions]
@@ -130,13 +132,9 @@ export function jsonOut(response) {
 export function toErrorEnvelope(err, suggestions, code) {
   const message =
     err instanceof Error ? err.message : typeof err === 'string' ? err : String(err);
-  const resolvedCode =
-    code ||
-    (err && typeof err === 'object' &&
-    typeof (/** @type {any} */ (err).code) === 'string'
-      ? /** @type {any} */ (err).code
-      : undefined) ||
-    ERROR_CODES.ERR_UNKNOWN;
+  const carried =
+    err && typeof err === 'object' ? /** @type {any} */ (err).code : undefined;
+  const resolvedCode = [code, carried].find(isErrorCode) ?? ERROR_CODES.ERR_UNKNOWN;
   /** @type {any} */
   const env = {apiVersion: API_VERSION, error: message, code: resolvedCode};
   if (Array.isArray(suggestions) && suggestions.length) env.suggestions = suggestions;