@astryxdesign/cli 0.6.3-canary.ea2f048 → 0.6.3-canary.ee13359

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

@@ -120,7 +120,7 @@ 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,
@@ -131,19 +131,23 @@ describe('integration authoring CLI', () => {
       ['integration', 'pack', '--check', '--json'],
       tmpDir,
     );
-    expect(checked.status).toBe(0);
-    expect(parseEnvelope(checked.stdout)).toMatchObject({
+    // 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 () => {

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

@@ -5,7 +5,7 @@ export const doc = {
   type: 'command',
   name: 'integration pack',
   displayName: 'astryx integration pack',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Prove the packed integration is what consumers receive',
   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.',

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'),
@@ -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.doc.mjs

@@ -5,7 +5,7 @@ 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.',

package/clients/cli/commands/integration.mjs

@@ -58,6 +58,7 @@ export function registerIntegration(program) {
           templateType: options.type,
           replaces: options.replaces,
           extends: options.extends,
+          parent: options.parent,
           to: options.to,
         });
       } catch (error) {

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'],

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

@@ -13,7 +13,7 @@ export const doc = {
   type: 'command',
   name: 'layout expand',
   displayName: 'astryx layout expand',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Expand a layout expression into validated XDS TSX',
   description:
     'Parses and validates a compressed XLE/XLO expression, then expands it into ' +
@@ -21,11 +21,28 @@ export const doc = {
     'interactive controls, and splicing referenced blocks. Writes to a path, or returns the code.',
   fn: 'layoutExpand',
   args: [
-    {name: 'expression', param: 'expression', required: false},
-    {name: 'path', param: 'options.targetPath', required: false},
+    {
+      name: 'expression',
+      param: 'expression',
+      required: false,
+      description:
+        'The XLE/XLO expression. Pass - to read it from stdin; --file reads it from a file instead.',
+    },
+    {
+      name: 'path',
+      param: 'options.targetPath',
+      required: false,
+      description:
+        'Where to write the TSX, relative to the project root. A path that ends in .tsx, .ts, .jsx, .js, .mjs, .cjs, .css, .scss, .json, .md or .html is the file to write; ' +
+        'any other path is a directory, which receives <Name>.tsx (see --name). An existing file there is replaced. ' +
+        'Omit it to print the code.',
+    },
   ],
   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',
@@ -59,7 +76,7 @@ export const doc = {
     {code: 0, when: 'success'},
     {
       code: 1,
-      when: 'a missing/empty expression, a bad --name or --form, a parse/validation error, or a path escape',
+      when: 'a missing, empty or over-5 MB expression (from stdin or --file), a bad --name or --form, a parse/validation error, or a path escape',
     },
   ],
   related: ['layout check', 'layout grammar'],

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

@@ -13,7 +13,7 @@ export const doc = {
   type: 'command',
   name: 'layout grammar',
   displayName: 'astryx layout grammar',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary:
     'Print the XLE/XLO cheatsheet (alias table generated from this branch)',
   description:

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

@@ -12,7 +12,7 @@ export const doc = {
   type: 'command',
   name: 'layout',
   displayName: 'astryx layout',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Generate XDS layouts from compressed expressions (XLE/XLO)',
   description:
     'The layout command group. Running astryx layout with no subcommand prints the ' +
@@ -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'],
 };

package/clients/cli/commands/layout.mjs

@@ -59,6 +59,9 @@ import {NO_RESULT_SET, resultSet} from '../../../foundation/debug/index.mjs';
  * @property {boolean} [loose]
  */
 
+/** The largest layout expression read from --file or stdin. */
+const MAX_EXPRESSION_BYTES = 5 * 1024 * 1024; // 5 MB
+
 /**
  * Resolve the expression from arg, --file, or stdin ('-').
  * @param {string} [expr]
@@ -78,8 +81,7 @@ async function readExpression(expr, options = {}) {
         code: ERROR_CODES.ERR_FILE_NOT_FOUND,
       });
     }
-    const MAX_FILE_SIZE = 5 * 1024 * 1024; // 5 MB
-    if (stat.size > MAX_FILE_SIZE) {
+    if (stat.size > MAX_EXPRESSION_BYTES) {
       cliError(
         `File "${options.file}" is too large (${(stat.size / 1024 / 1024).toFixed(1)} MB, max 5 MB)`,
         {code: ERROR_CODES.ERR_FILE_NOT_FOUND},
@@ -100,9 +102,19 @@ async function readExpression(expr, options = {}) {
     }
   }
   if (expr === '-') {
+    // Capped like --file: an endless stream must not be buffered whole.
     /** @type {Buffer[]} */
     const chunks = [];
-    for await (const chunk of process.stdin) chunks.push(/** @type {Buffer} */ (chunk));
+    let size = 0;
+    for await (const chunk of process.stdin) {
+      size += /** @type {Buffer} */ (chunk).length;
+      if (size > MAX_EXPRESSION_BYTES) {
+        cliError('The layout expression on stdin is too large (max 5 MB)', {
+          code: ERROR_CODES.ERR_INVALID_ARGUMENT,
+        });
+      }
+      chunks.push(/** @type {Buffer} */ (chunk));
+    }
     return Buffer.concat(chunks).toString('utf-8');
   }
   return expr ?? '';
@@ -154,15 +166,15 @@ export function registerLayout(program) {
       if (result.data.written) {
         out.push(
           text(`[ok] Expanded to ${result.data.written}`),
+          // Field names are the JSON keys; todos are summarised, not listed.
           record(
+            {componentsUsed: result.data.componentsUsed, todos: result.data.todos},
             {
-              components: result.data.componentsUsed,
-              todos:
-                result.data.todos.length > 0
-                  ? `${result.data.todos.length} (search for "TODO(xle)")`
-                  : '',
+              format: {
+                todos: (/** @type {string[]} */ todos) =>
+                  `${todos.length} (search for "TODO(xle)")`,
+              },
             },
-            {labels: {components: 'Components', todos: 'TODOs'}},
           ),
         );
       } else {

package/clients/cli/commands/layout.path-help.test.mjs

@@ -0,0 +1,33 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `layout expand` and `layout check` document their input modes (the
+ * argument, `-` for stdin, --file) and where `layout expand` writes.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+import {isFilePathArg} from '../../../foundation/fs/path-safety.mjs';
+
+const SLOW = 30_000;
+
+describe('layout argument behavior is documented', () => {
+  it('layout expand help covers stdin, --file precedence and the output path rule', async () => {
+    const {status, stdout} = await runCli(['layout', 'expand', '--help']);
+    expect(status).toBe(0);
+    expect(stdout).toMatch(/Pass - to read it from stdin/);
+    expect(stdout).toMatch(/instead of the argument/);
+    expect(stdout).toContain('<Name>.tsx');
+    expect(stdout).toMatch(/existing file there is replaced/);
+    const exts = [...(stdout.match(/ends in ([.\w, ]+ or \.\w+)/)?.[1] ?? '').matchAll(/\.\w+/g)];
+    expect(exts.length).toBeGreaterThan(0);
+    for (const [ext] of exts) expect(isFilePathArg(`src/Page${ext}`)).toBe(true);
+  }, SLOW);
+
+  it('layout check help covers stdin and --file precedence', async () => {
+    const {status, stdout} = await runCli(['layout', 'check', '--help']);
+    expect(status).toBe(0);
+    expect(stdout).toMatch(/Pass - to read it from stdin/);
+    expect(stdout).toMatch(/instead of the argument/);
+  }, SLOW);
+});

package/clients/cli/commands/layout.stdin-cap.test.mjs

@@ -0,0 +1,47 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `layout check -` reads the expression from stdin under the same 5 MB
+ * cap as --file, instead of buffering whatever the pipe delivers. Spawns the
+ * real bin, since the in-process harness has no stdin.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {spawnSync} from 'node:child_process';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const BIN = path.resolve(HERE, '../bin/astryx.mjs');
+// Run against the monorepo root so @astryxdesign/core is discoverable.
+const REPO = path.resolve(HERE, '../../../..');
+const SLOW = 60_000;
+
+/** @param {string} input @param {string[]} [extra] */
+function checkFromStdin(input, extra = []) {
+  return spawnSync(process.execPath, [BIN, 'layout', 'check', '-', ...extra], {
+    cwd: REPO,
+    input,
+    encoding: 'utf-8',
+    maxBuffer: 16 * 1024 * 1024,
+  });
+}
+
+describe('layout check - (stdin)', () => {
+  it('refuses more than 5 MB with ERR_INVALID_ARGUMENT, in both modes', () => {
+    // Valid once trimmed, so only the cap can reject it.
+    const big = ' '.repeat(5 * 1024 * 1024 + 1) + 'V';
+    const json = checkFromStdin(big, ['--json']);
+    expect(json.status).toBe(1);
+    expect(JSON.parse(json.stdout).code).toBe('ERR_INVALID_ARGUMENT');
+    const human = checkFromStdin(big);
+    expect(human.status).toBe(1);
+    expect(human.stderr + human.stdout).toMatch(/too large/);
+  }, SLOW);
+
+  it('still reads a normal expression', () => {
+    const r = checkFromStdin('V > B', ['--json']);
+    expect(r.status).toBe(0);
+    expect(JSON.parse(r.stdout).data.valid).toBe(true);
+  }, SLOW);
+});

package/clients/cli/commands/layout.text-fields.test.mjs

@@ -0,0 +1,39 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `layout expand` text output names its fields after the JSON keys, so
+ * the two views stay greppable against each other.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+
+const SLOW = 60_000;
+
+describe('layout expand text fields mirror the JSON keys', () => {
+  let cwd;
+  beforeEach(() => {
+    // Inside the workspace so @astryxdesign/core resolves.
+    cwd = fs.mkdtempSync(path.join(process.cwd(), '.xle-text-fields-'));
+  });
+  afterEach(() => fs.rmSync(cwd, {recursive: true, force: true}));
+
+  it('labels every record field with a key of the layout.expand data', async () => {
+    const expr = 'V > B + {not-a-real-block}';
+    const json = await runCli(['layout', 'expand', expr, './a', '--loose', '--json'], cwd);
+    expect(json.status).toBe(0);
+    const {data} = JSON.parse(json.stdout);
+    expect(data.todos.length).toBeGreaterThan(0);
+
+    const human = await runCli(['layout', 'expand', expr, './b', '--loose'], cwd);
+    expect(human.status).toBe(0);
+    const fields = human.stdout
+      .split('\n')
+      .map(line => /^([A-Za-z]+):\s/.exec(line)?.[1])
+      .filter(Boolean);
+    expect(fields).toEqual(['componentsUsed', 'todos']);
+    for (const field of fields) expect(Object.keys(data)).toContain(field);
+  }, SLOW);
+});

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

@@ -12,7 +12,7 @@ export const doc = {
   type: 'command',
   name: 'manifest',
   displayName: 'astryx manifest',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Print the full CLI capability manifest (use with --json).',
   description:
     'Emits the complete CLI surface: every command with its arguments, options, ' +