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

package/clients/cli/commands/integration-authoring.test.mjs

@@ -120,39 +120,94 @@ describe('integration authoring CLI', () => {
     );
   });
 
-  it('packs the generated contribution and proves the consumer inventory', async () => {
+  it('pack-check rejects a generated component without an exports map (no-map false green)', async () => {
     const added = await runCli(
       ['integration', 'add', 'component', 'AcmeWidget', '--json'],
       tmpDir,
     );
     expect(added.status).toBe(0);
 
-    const checked = await runCli(
-      ['integration', 'pack', '--check', '--json'],
-      tmpDir,
-    );
-    expect(checked.status).toBe(0);
-    expect(parseEnvelope(checked.stdout)).toMatchObject({
+    const checked = await runCli(['integration', 'verify', '--json'], tmpDir);
+    // Without an exports map, the extensionless import cannot resolve —
+    // pack-check must fail, not false-green.
+    expect(checked.status).not.toBe(0);
+    const envelope = parseEnvelope(checked.stdout);
+    expect(envelope).toMatchObject({
       type: 'integration.pack-check',
       data: {
         name: '@acme/widgets',
-        version: '1.0.0',
-        packable: true,
-        contributions: {
-          local: {components: ['AcmeWidget']},
-          packed: {components: ['AcmeWidget']},
-        },
+        packable: false,
       },
     });
+    expect(envelope.data.issues).toContainEqual(
+      expect.objectContaining({
+        severity: 'error',
+        message: expect.stringContaining('AcmeWidget'),
+      }),
+    );
   });
 
-  it('requires the explicit --check gate on pack', async () => {
-    const result = await runCli(['integration', 'pack', '--json'], tmpDir);
-    expect(result.status).not.toBe(0);
-    expect(parseEnvelope(result.stdout)).toMatchObject({
-      code: 'ERR_INVALID_ARGUMENT',
-      error: 'Pass --check to verify the integration tarball.',
+  it('keeps `integration pack --check` as a deprecated alias of `integration verify`', async () => {
+    // The old spelling runs the same check: the same JSON, the same exit code.
+    const verify = await runCli(['integration', 'verify', '--json'], tmpDir);
+    const old = await runCli(
+      ['integration', 'pack', '--check', '--json'],
+      tmpDir,
+    );
+    expect(old.status).toBe(verify.status);
+    const verifyEnvelope = parseEnvelope(verify.stdout);
+    const oldEnvelope = parseEnvelope(old.stdout);
+    expect(oldEnvelope.type).toBe('integration.pack-check');
+    expect(oldEnvelope.type).toBe(verifyEnvelope.type);
+    expect(oldEnvelope.data.packable).toBe(verifyEnvelope.data.packable);
+    expect(oldEnvelope.data.issues).toEqual(verifyEnvelope.data.issues);
+    // The global flag may come first, as agents usually write it.
+    const lead = await runCli(
+      ['--json', 'integration', 'pack', '--check'],
+      tmpDir,
+    );
+    expect(parseEnvelope(lead.stdout).type).toBe('integration.pack-check');
+    // In text, it says to use the new name, on stderr, so stdout is the same.
+    const text = await runCli(['integration', 'pack', '--check'], tmpDir);
+    const verifyText = await runCli(['integration', 'verify'], tmpDir);
+    expect(text.status).toBe(verifyText.status);
+    expect(text.stdout).toBe(verifyText.stdout);
+    expect(text.stderr).toContain('`integration pack --check` is deprecated');
+    expect(text.stderr).toContain('astryx integration verify');
+    // Without --check it fails, as it did, and names both spellings.
+    const bare = await runCli(['integration', 'pack'], tmpDir);
+    expect(bare.status).not.toBe(0);
+    expect(bare.stderr).toContain('--check');
+    expect(bare.stderr).toContain('astryx integration verify');
+    // Help lists it, marked deprecated: nothing is hidden.
+    const help = await runCli(['integration', '--help'], tmpDir);
+    expect(help.stdout).toMatch(
+      /pack .*Deprecated: the old name of `integration verify`/,
+    );
+    // `verify` itself takes no --check.
+    const flag = await runCli(['integration', 'verify', '--check'], tmpDir);
+    expect(flag.status).not.toBe(0);
+    expect(flag.stderr).toContain("unknown option '--check'");
+    // An unknown subcommand with a flag names the subcommand, in text and JSON.
+    const unknown = await runCli(['integration', 'bogus', '--check'], tmpDir);
+    expect(unknown.status).not.toBe(0);
+    expect(unknown.stderr).toContain("unknown subcommand 'integration bogus'");
+    expect(unknown.stderr).toMatch(/verify\s+\(available subcommand\)/);
+    const unknownJson = await runCli(
+      ['integration', 'bogus', '--check', '--json'],
+      tmpDir,
+    );
+    expect(parseEnvelope(unknownJson.stdout)).toMatchObject({
+      code: 'ERR_UNKNOWN_SUBCOMMAND',
+      error: "unknown subcommand 'integration bogus'",
+      suggestions: expect.arrayContaining([
+        expect.objectContaining({name: 'verify'}),
+      ]),
     });
+    // A flag alone is an unknown option, not an unknown subcommand.
+    const flagOnly = await runCli(['integration', '--bogus'], tmpDir);
+    expect(flagOnly.status).not.toBe(0);
+    expect(flagOnly.stderr).toContain("unknown option '--bogus'");
   });
 
   it('refuses kind-specific options on another kind', async () => {

package/clients/cli/commands/integration-pack.doc.mjs

@@ -5,23 +5,19 @@ export const doc = {
   type: 'command',
   name: 'integration pack',
   displayName: 'astryx integration pack',
-  namespace: 'cli',
-  summary: 'Prove the packed integration is what consumers receive',
+  namespace: 'cli/commands',
+  summary: 'Deprecated: the old name of `integration verify`',
   description:
-    'Runs the package lifecycle, packs with npm, checks every required contribution file against the real tarball, extracts it into a scratch consumer, and compares the local and packed contribution inventories through one shared contract.',
+    '`astryx integration pack --check` is the name this check had before {@link command:integration verify}. It still runs the same check, with the same output, JSON, and exit codes, and prints a note that names `integration verify`. It will be removed in a later release.',
   fn: 'integrationPackCheck',
   options: [
     {
       flag: '--check',
-      description: 'Run the packed-package verification gate',
+      description: 'Run the check. Required, as before.',
     },
   ],
   examples: [
-    {label: 'Verify before publishing', cli: 'astryx integration pack --check'},
-    {
-      label: 'Machine-readable result',
-      cli: 'astryx integration pack --check --json',
-    },
+    {label: 'The old spelling', cli: 'astryx integration pack --check'},
   ],
   exitCodes: [
     {code: 0, when: 'the packed package exposes the same valid contributions'},
@@ -30,5 +26,5 @@ export const doc = {
       when: '--check is omitted or the tarball is incomplete or invalid',
     },
   ],
-  related: ['integration add', 'doctor integration validate'],
+  related: ['integration verify'],
 };

package/clients/cli/commands/integration-real-world.test.mjs

@@ -201,13 +201,6 @@ export const oceanTheme = defineTheme({
 });
 `,
     );
-    const catalogFile = path.join(providerDir, 'themes', 'manifest.json');
-    const catalog = JSON.parse(fs.readFileSync(catalogFile, 'utf-8'));
-    catalog.themes[0].files.push(
-      'tokens/ocean.palette.ts',
-      'tokens/ocean.palette.receipt.json',
-    );
-    writeJson(catalogFile, catalog);
 
     const providerPackage = JSON.parse(
       fs.readFileSync(path.join(providerDir, 'package.json'), 'utf-8'),
@@ -221,7 +214,7 @@ export const oceanTheme = defineTheme({
     ]);
 
     const checked = await runCli(
-      ['integration', 'pack', '--check', '--json'],
+      ['integration', 'verify', '--json'],
       providerDir,
     );
     expect(checked.status, checked.stderr).toBe(0);
@@ -464,8 +457,9 @@ export const oceanTheme = defineTheme({
         outputDir: target,
         files: [
           'oceanTheme.ts',
-          'tokens/ocean.palette.ts',
+          'oceanTheme.doc.mjs',
           'tokens/ocean.palette.receipt.json',
+          'tokens/ocean.palette.ts',
         ],
       },
     });
@@ -612,7 +606,7 @@ export const oceanTheme = defineTheme({
     expect(corruptedInstall.status).not.toBe(0);
     expect(parseEnvelope(corruptedInstall.stdout)).toMatchObject({
       code: 'ERR_THEME_INVALID',
-      error: expect.stringContaining('ocean.palette.ts'),
+      error: expect.stringContaining('./tokens/ocean.palette'),
     });
   }, 120_000);
 });

package/clients/cli/commands/integration-verify.doc.mjs

@@ -0,0 +1,22 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').CommandDoc} */
+export const doc = {
+  type: 'command',
+  name: 'integration verify',
+  displayName: 'astryx integration verify',
+  namespace: 'cli/commands',
+  summary: 'Check the package the way npm will publish it, before you publish',
+  description:
+    'Packs the package with npm, unpacks the tarball into a temporary app without installing its dependencies, and checks that the app sees the same components, templates, themes, docs, and codemods as the package, that every public import resolves, and that the package declares a CLI new enough to read it. It publishes nothing and leaves no tarball behind. It runs the package\'s own pack lifecycle scripts, as `npm pack` does.',
+  fn: 'integrationPackCheck',
+  examples: [
+    {label: 'Check before publishing', cli: 'astryx integration verify'},
+    {label: 'Machine-readable result', cli: 'astryx integration verify --json'},
+  ],
+  exitCodes: [
+    {code: 0, when: 'the packed package exposes the same valid contributions'},
+    {code: 1, when: 'the tarball is incomplete or invalid'},
+  ],
+  related: ['integration add', 'doctor integration validate'],
+};

package/clients/cli/commands/integration.doc.mjs

@@ -5,19 +5,19 @@ export const doc = {
   type: 'command',
   name: 'integration',
   displayName: 'astryx integration',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Author and verify an Astryx integration package',
   description:
-    'Add contributions that are valid on arrival, then prove the packed package exposes the same contributions a consumer will receive.',
-  subcommands: ['add', 'pack'],
+    'Add contributions to your package, then check the packed package the way an app receives it. The guides start at {@link namespace:integrations}.',
+  subcommands: ['add', 'verify', 'pack'],
   examples: [
     {
       label: 'Add a component',
       cli: 'astryx integration add component AcmeWidget',
     },
     {
-      label: 'Check the package tarball',
-      cli: 'astryx integration pack --check',
+      label: 'Check the package before publishing',
+      cli: 'astryx integration verify',
     },
   ],
   exitCodes: [

package/clients/cli/commands/integration.mjs

@@ -12,6 +12,7 @@ import {cliError} from '../lib/cli-error.mjs';
 import {defineCommand} from '../lib/define-command.mjs';
 import {doc as integrationGroup} from './integration.doc.mjs';
 import {doc as integrationAddCommand} from './integration-add.doc.mjs';
+import {doc as integrationVerifyCommand} from './integration-verify.doc.mjs';
 import {doc as integrationPackCommand} from './integration-pack.doc.mjs';
 import {doc as integrationAddFn} from '../../../api/integration/integrationAdd.doc.mjs';
 import {doc as integrationPackCheckFn} from '../../../api/integration/integrationPackCheck.doc.mjs';
@@ -24,8 +25,16 @@ import {doc as integrationPackCheckFn} from '../../../api/integration/integratio
  */
 function showGroupOrUnknown(command, label, options, invoked) {
   const extras = invoked?.args ?? [];
-  if (extras.length > 0) {
-    return cliError(`unknown subcommand '${label} ${String(extras[0])}'`, {
+  // allowUnknownOption keeps an unknown flag among the args: a word there is
+  // an unknown subcommand, and a flag alone is an unknown option.
+  const word = extras.find(arg => !String(arg).startsWith('-'));
+  if (word == null && extras.length > 0) {
+    return cliError(`unknown option '${String(extras[0])}'`, {
+      code: ERROR_CODES.ERR_INVALID_OPTION,
+    });
+  }
+  if (word != null) {
+    return cliError(`unknown subcommand '${label} ${String(word)}'`, {
       suggestions: (command.commands ?? []).map(child => ({
         name: child.name(),
         reason: 'available subcommand',
@@ -37,6 +46,48 @@ function showGroupOrUnknown(command, label, options, invoked) {
   return NO_RESULT_SET;
 }
 
+/**
+ * Run `integration verify` and print its result, as text or JSON.
+ * @param {import('commander').Command} program
+ */
+async function verifyPackage(program) {
+  const result = await integrationPackCheck({cwd: process.cwd()});
+  if (program.opts().json) {
+    jsonOut(result);
+  } else {
+    const {name, version, packable, tarball, inventory, issues} = result.data;
+    const identity = [name, version].filter(Boolean).join('@');
+    const blocks = [
+      section(
+        packable
+          ? 'Integration package ready'
+          : 'Integration package check failed',
+      ),
+      text(`${packable ? '[ok]' : '[fail]'} ${identity || 'local package'}`),
+    ];
+    if (tarball != null) {
+      blocks.push(
+        text(
+          `${tarball.fileCount} packed files; ${inventory.packedFiles}/${inventory.expectedFiles} required files present.`,
+        ),
+      );
+    }
+    if (issues.length > 0) {
+      blocks.push(
+        list(
+          issues.map(
+            issue =>
+              `[${issue.severity === 'error' ? 'fail' : 'warn'}] ${issue.message}`,
+          ),
+        ),
+      );
+    }
+    emit(...blocks);
+  }
+  if (!result.data.packable) process.exitCode = 1;
+  return NO_RESULT_SET;
+}
+
 /** @param {import('commander').Command} program */
 export function registerIntegration(program) {
   /** @type {import('commander').Command} */
@@ -45,6 +96,10 @@ export function registerIntegration(program) {
     action: (options, command) =>
       showGroupOrUnknown(integration, 'integration', options, command),
   });
+  // An unknown subcommand given with a flag reports the unknown subcommand
+  // and lists the ones the group has, not the unknown option. Each subcommand
+  // still parses its own options.
+  integration.allowUnknownOption(true);
 
   defineCommand(integration, integrationAddCommand, {
     fn: integrationAddFn,
@@ -58,6 +113,7 @@ export function registerIntegration(program) {
           templateType: options.type,
           replaces: options.replaces,
           extends: options.extends,
+          parent: options.parent,
           to: options.to,
         });
       } catch (error) {
@@ -101,53 +157,29 @@ export function registerIntegration(program) {
     },
   });
 
+  defineCommand(integration, integrationVerifyCommand, {
+    fn: integrationPackCheckFn,
+    action: async () => verifyPackage(program),
+  });
+  // The name this check had before `integration verify`. It stays as a
+  // deprecated alias, listed as one in help, so scripts that call it keep
+  // working; it runs the same check with the same output and exit codes.
   defineCommand(integration, integrationPackCommand, {
     fn: integrationPackCheckFn,
     action: async options => {
       if (!options.check) {
-        return cliError('Pass --check to verify the integration tarball.', {
-          code: ERROR_CODES.ERR_INVALID_ARGUMENT,
-        });
+        return cliError(
+          'Pass --check to verify the integration tarball, or run `astryx integration verify`.',
+          {code: ERROR_CODES.ERR_INVALID_ARGUMENT},
+        );
       }
-
-      const result = await integrationPackCheck({cwd: process.cwd()});
-      if (program.opts().json) {
-        jsonOut(result);
-      } else {
-        const {name, version, packable, tarball, inventory, issues} =
-          result.data;
-        const identity = [name, version].filter(Boolean).join('@');
-        const blocks = [
-          section(
-            packable
-              ? 'Integration package ready'
-              : 'Integration package check failed',
-          ),
-          text(
-            `${packable ? '[ok]' : '[fail]'} ${identity || 'local package'}`,
-          ),
-        ];
-        if (tarball != null) {
-          blocks.push(
-            text(
-              `${tarball.fileCount} packed files; ${inventory.packedFiles}/${inventory.expectedFiles} required files present.`,
-            ),
-          );
-        }
-        if (issues.length > 0) {
-          blocks.push(
-            list(
-              issues.map(
-                issue =>
-                  `[${issue.severity === 'error' ? 'fail' : 'warn'}] ${issue.message}`,
-              ),
-            ),
-          );
-        }
-        emit(...blocks);
+      // stderr, and only in text: JSON callers get the same envelope as verify.
+      if (!program.opts().json) {
+        console.error(
+          'Note: `integration pack --check` is deprecated. Run `astryx integration verify`: it runs the same check.',
+        );
       }
-      if (!result.data.packable) process.exitCode = 1;
-      return NO_RESULT_SET;
+      return verifyPackage(program);
     },
   });
 }

package/clients/cli/commands/interactive-guard.test.mjs

@@ -1,17 +1,19 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file Subprocess no-hang tests for `astryx init`.
+ * @file Subprocess no-hang tests: the CLI never waits on stdin (INV1).
  *
- * TTY was removed from the CLI: `init` is non-interactive by default and must
- * run cleanly (exit 0, writing the agent cheat sheet) instead of hanging on a
- * prompt. These tests spawn the CLI with stdin/stdout NOT a TTY (the CI / piped
- * / agent condition). A hang would show as signal SIGTERM + status null; we
- * assert `signal === null && status === 0` to prove it exits cleanly and works.
+ * Every run gets a stdin pipe that stays open and silent, the way an agent's
+ * harness holds it. A prompt or a stdin read for control flow then blocks until
+ * the deadline, and the run ends with signal SIGTERM and status null. With stdin
+ * ignored or closed, the same read would see EOF at once and pass.
+ *
+ * Every command and group in the manifest runs once, with a placeholder for
+ * each required argument so its action is reached, plus the bare `astryx`.
  */
 
 import {describe, it, expect, beforeEach, afterEach} from 'vitest';
-import {spawnSync} from 'node:child_process';
+import {spawn, spawnSync} from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
@@ -19,37 +21,112 @@ import {fileURLToPath} from 'node:url';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const CLI = path.resolve(__dirname, '..', 'bin', 'astryx.mjs');
+const DEADLINE_MS = 20_000;
+// Keeps every run offline: `blog` fetches its feed when run bare.
+const OFFLINE = `data:text/javascript,${encodeURIComponent(
+  "globalThis.fetch = () => Promise.reject(new TypeError('fetch failed'));",
+)}`;
+
+/**
+ * Run `node <argv>` with a stdin pipe that is never written or ended.
+ * @param {string[]} argv
+ * @param {string} cwd
+ * @param {number} [deadline]
+ * @returns {Promise<{status: number | null, signal: NodeJS.Signals | null, output: string}>}
+ */
+function runHeld(argv, cwd, deadline = DEADLINE_MS) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, argv, {
+      cwd,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: {...process.env, FORCE_COLOR: '0', CI: ''},
+    });
+    // Never written or ended; a late EPIPE after exit is not a result.
+    child.stdin.on('error', () => {});
+    let output = '';
+    child.stdout.setEncoding('utf8').on('data', chunk => (output += chunk));
+    child.stderr.setEncoding('utf8').on('data', chunk => (output += chunk));
+    const timer = setTimeout(() => child.kill('SIGTERM'), deadline);
+    child.on('error', error => {
+      clearTimeout(timer);
+      reject(error);
+    });
+    child.on('close', (status, signal) => {
+      clearTimeout(timer);
+      resolve({status, signal, output});
+    });
+  });
+}
 
-let tmpDir;
+/**
+ * @param {string[]} args
+ * @param {string} cwd
+ */
+function runCli(args, cwd) {
+  return runHeld(['--import', OFFLINE, CLI, ...args], cwd);
+}
 
-function runCli(args) {
-  return spawnSync(process.execPath, [CLI, ...args], {
-    cwd: tmpDir,
+/** @returns {Array<[string, string[]]>} */
+function manifestInvocations() {
+  const manifest = spawnSync(process.execPath, [CLI, 'manifest', '--json'], {
     encoding: 'utf8',
-    timeout: 20_000,
-    stdio: ['ignore', 'pipe', 'pipe'],
-    env: {...process.env, FORCE_COLOR: '0', CI: ''},
   });
+  /** @type {string[][]} */
+  const invocations = [[]];
+  /** @param {any[]} commands */
+  const walk = commands => {
+    for (const command of commands) {
+      invocations.push([
+        ...command.name.split(' '),
+        ...command.arguments.filter((/** @type {any} */ a) => a.required).map(() => 'x'),
+      ]);
+      walk(command.subcommands ?? []);
+    }
+  };
+  walk(JSON.parse(manifest.stdout).data.commands);
+  return invocations.map(args => [['astryx', ...args].join(' '), args]);
 }
 
-beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-interactive-guard-'));
+describe('the harness holds stdin open', () => {
+  it('so a stdin read is reported as a hang', async () => {
+    const r = await runHeld(['-e', 'process.stdin.resume()'], os.tmpdir(), 1_000);
+    expect(r.signal).toBe('SIGTERM');
+    expect(r.status).toBeNull();
+  });
 });
 
-afterEach(() => {
-  fs.rmSync(tmpDir, {recursive: true, force: true});
+describe('every command exits without waiting on stdin', () => {
+  it.concurrent.for(manifestInvocations())('%s', async ([label, args], {expect}) => {
+    const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-interactive-guard-'));
+    try {
+      const r = await runCli(args, cwd);
+      expect(r.signal, `${label} waited on stdin:\n${r.output.slice(-500)}`).toBeNull();
+    } finally {
+      fs.rmSync(cwd, {recursive: true, force: true});
+    }
+  });
 });
 
 describe('init is non-interactive by default (no TTY needed)', () => {
-  it('runs cleanly (exit 0, no hang) and writes agent docs', () => {
-    const r = runCli(['init']);
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-interactive-guard-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, {recursive: true, force: true});
+  });
+
+  it('runs cleanly (exit 0, no hang) and writes agent docs', async () => {
+    const r = await runCli(['init'], tmpDir);
     expect(r.signal).toBeNull(); // did not hang
     expect(r.status).toBe(0); // succeeded without a TTY
     expect(fs.readdirSync(tmpDir).length).toBeGreaterThan(0); // wrote the cheat sheet
   });
 
-  it('writes an agent-doc file containing the ASTRYX cheat-sheet marker', () => {
-    runCli(['init']);
+  it('writes an agent-doc file containing the ASTRYX cheat-sheet marker', async () => {
+    await runCli(['init'], tmpDir);
     // init injects into existing agent-doc files if present, else creates AGENTS.md
     const candidates = ['AGENTS.md', 'CLAUDE.md', '.cursorrules', path.join('.claude', 'CLAUDE.md')];
     const doc = candidates.find(f => fs.existsSync(path.join(tmpDir, f)));
@@ -57,8 +134,8 @@ describe('init is non-interactive by default (no TTY needed)', () => {
     expect(fs.readFileSync(path.join(tmpDir, doc), 'utf8')).toMatch(/ASTRYX:START/);
   });
 
-  it('still runs --features agents non-interactively', () => {
-    const r = runCli(['init', '--features', 'agents']);
+  it('still runs --features agents non-interactively', async () => {
+    const r = await runCli(['init', '--features', 'agents'], tmpDir);
     expect(r.signal).toBeNull();
     expect(r.status).toBe(0);
     expect(fs.readdirSync(tmpDir).length).toBeGreaterThan(0);

package/clients/cli/commands/json-contract.test.mjs

@@ -172,3 +172,36 @@ describe('--json contract: supported commands emit valid envelopes', () => {
     expect(parsed.data.summary.fail).toBeGreaterThan(0);
   });
 });
+
+describe('--json contract: the flag describes the envelopes it emits', () => {
+  /** @param {string} shape e.g. ` apiVersion, error, code, suggestions? ` */
+  const fields = shape => shape.split(',').map(f => f.trim().replace(/\?$/, ''));
+
+  it('names every field of the success and error envelopes', async () => {
+    const manifest = parseJson((await runCli(['manifest', '--json'], {cwd: tmpDir})).stdout);
+    const {description} = manifest.data.globalOptions.find(o => o.flag === '--json');
+    const match = /Success envelope: \{([^}]*)\}.*Error envelope: \{([^}]*)\}/.exec(description);
+    expect(match, description).not.toBeNull();
+    const [, success, error] = /** @type {RegExpExecArray} */ (match);
+
+    for (const key of Object.keys(manifest)) expect(fields(success)).toContain(key);
+    expect(fields(success)).toContain('meta');
+
+    // An unknown command's envelope carries every error field, suggestions included.
+    const failure = parseJson((await runCli(['bogus-cmd', '--json'], {cwd: tmpDir})).stdout);
+    expect(Object.keys(failure)).toContain('suggestions');
+    for (const key of Object.keys(failure)) expect(fields(error)).toContain(key);
+  });
+
+  it('the CLI README describes the same envelopes', () => {
+    const readme = fs.readFileSync(new URL('../../../README.md', import.meta.url), 'utf8');
+    const line = readme
+      .split('\n')
+      .find(l => l.startsWith('- `--json`: Output as typed JSON envelope:'));
+    expect(line, 'README global --json line').toBeDefined();
+    const [success, error] = [...String(line).matchAll(/`\{([^}]*)\}`/g)].map(m => fields(m[1]));
+    expect(success).toEqual(expect.arrayContaining(['apiVersion', 'type', 'data', 'meta']));
+    expect(error).toEqual(expect.arrayContaining(['apiVersion', 'error', 'code', 'suggestions']));
+    expect(readme).toContain('{"apiVersion": 1, "type": "component.detail"');
+  });
+});

package/clients/cli/commands/layout-check.doc.mjs

@@ -13,7 +13,7 @@ export const doc = {
   type: 'command',
   name: 'layout check',
   displayName: 'astryx layout check',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary:
     'Validate a layout expression and echo canonical compact/outline forms',
   description:
@@ -21,9 +21,20 @@ export const doc = {
     'echoes it back in both canonical surfaces (compact and outline). An invalid but ' +
     'parseable expression is reported with line/col and suggestions, and exits non-zero.',
   fn: 'layoutCheck',
-  args: [{name: 'expression', param: 'expression', required: false}],
+  args: [
+    {
+      name: 'expression',
+      param: 'expression',
+      required: false,
+      description:
+        'The XLE/XLO expression. Pass - to read it from stdin; --file reads it from a file instead.',
+    },
+  ],
   options: [
-    {flag: '--file <file>', description: 'Read the expression from a file'},
+    {
+      flag: '--file <file>',
+      description: 'Read the expression from a file (used instead of the argument when both are given)',
+    },
     {
       flag: '--form <form>',
       param: 'options.form',
@@ -47,7 +58,7 @@ export const doc = {
     {code: 0, when: 'the expression is valid'},
     {
       code: 1,
-      when: 'the expression is invalid or empty, has a syntax error, or a bad --form',
+      when: 'the expression is invalid, empty or over 5 MB (from stdin or --file), has a syntax error, or a bad --form',
     },
   ],
   related: ['layout expand', 'layout grammar'],