@astryxdesign/cli 0.6.4-canary.ed2e54e → 0.6.4

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

@@ -0,0 +1,65 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CommandDoc for `astryx layout check`. The terminal binding of the
+ * `layoutCheck()` function (referenced via `fn`); its args/flags map to that
+ * function's params so a converter can build Commander config + --help from one
+ * source of truth.
+ * @position packages/cli/clients/cli/commands — command documentation
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').CommandDoc} */
+export const doc = {
+  type: 'command',
+  name: 'layout check',
+  displayName: 'astryx layout check',
+  namespace: 'cli/commands',
+  summary:
+    'Validate a layout expression and echo canonical compact/outline forms',
+  description:
+    'Parses and validates a compressed XLE/XLO expression without generating any TSX, and ' +
+    '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,
+      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 (used instead of the argument when both are given)',
+    },
+    {
+      flag: '--form <form>',
+      param: 'options.form',
+      choices: ['compact', 'outline', 'auto'],
+      default: 'auto',
+      description: 'Input surface: compact, outline, or auto',
+    },
+    {
+      flag: '--loose',
+      param: 'options.loose',
+      description: 'Downgrade unknown {block} hints to TODO placeholders',
+    },
+  ],
+  examples: [
+    {
+      label: 'Validate an expression',
+      cli: "astryx layout check 'A[cp6] > L > LC > S[p6]' --json",
+    },
+  ],
+  exitCodes: [
+    {code: 0, when: 'the expression is valid'},
+    {
+      code: 1,
+      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

@@ -0,0 +1,83 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CommandDoc for `astryx layout expand`. The terminal binding of the
+ * `layoutExpand()` function (referenced via `fn`); its args/flags map to that
+ * function's params so a converter can build Commander config + --help from one
+ * source of truth.
+ * @position packages/cli/clients/cli/commands — command documentation
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').CommandDoc} */
+export const doc = {
+  type: 'command',
+  name: 'layout expand',
+  displayName: 'astryx layout expand',
+  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 ' +
+    'ready-to-use XDS TSX, routing children into slots, scaffolding typed useState for ' +
+    'interactive controls, and splicing referenced blocks. Writes to a path, or returns the code.',
+  fn: 'layoutExpand',
+  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.',
+    },
+    {
+      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 (used instead of the argument when both are given)',
+    },
+    {
+      flag: '--form <form>',
+      param: 'options.form',
+      choices: ['compact', 'outline', 'auto'],
+      default: 'auto',
+      description: 'Input surface: compact, outline, or auto',
+    },
+    {
+      flag: '--name <name>',
+      param: 'options.name',
+      default: 'GeneratedLayout',
+      description: 'Generated component name (PascalCase)',
+    },
+    {
+      flag: '--loose',
+      param: 'options.loose',
+      description: 'Downgrade unknown {block} hints to TODO placeholders',
+    },
+  ],
+  examples: [
+    {
+      label: 'Expand to a file',
+      cli: "astryx layout expand 'V[g6] > C{card-callout}*4' ./src/Page.tsx",
+    },
+    {
+      label: 'From a file, named',
+      cli: 'astryx layout expand --file layout.xlo --name Dashboard',
+    },
+  ],
+  exitCodes: [
+    {code: 0, when: 'success'},
+    {
+      code: 1,
+      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

@@ -0,0 +1,30 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CommandDoc for `astryx layout grammar`. The terminal binding of the
+ * `layoutGrammar()` function (referenced via `fn`); it carries only CLI-surface
+ * facts so a converter can build Commander config + --help from one source of
+ * truth.
+ * @position packages/cli/clients/cli/commands — command documentation
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').CommandDoc} */
+export const doc = {
+  type: 'command',
+  name: 'layout grammar',
+  displayName: 'astryx layout grammar',
+  namespace: 'cli/commands',
+  summary:
+    'Print the XLE/XLO cheatsheet (alias table generated from this branch)',
+  description:
+    'Prints the XLE/XLO grammar cheatsheet for writing layout expressions, with the alias ' +
+    "table generated from this install's registry so short names always reflect the " +
+    'components actually available.',
+  fn: 'layoutGrammar',
+  examples: [{label: 'Get the cheatsheet', cli: 'astryx layout grammar'}],
+  exitCodes: [
+    {code: 0, when: 'success'},
+    {code: 1, when: 'the component registry cannot be read'},
+  ],
+  related: ['layout expand', 'layout check'],
+};

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

@@ -0,0 +1,34 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CommandDoc for the `astryx layout` command group. A parent group with no
+ * behavior of its own; it dispatches to the expand/check/grammar subcommands,
+ * which carry the actual args, flags, and wrapped functions.
+ * @position packages/cli/clients/cli/commands — command documentation
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').CommandDoc} */
+export const doc = {
+  type: 'command',
+  name: 'layout',
+  displayName: 'astryx layout',
+  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 ' +
+    'subcommand list; the work happens in the subcommands: expand an expression into ' +
+    'TSX (expand), validate one (check), or print the grammar cheatsheet (grammar).',
+  subcommands: ['expand', 'check', 'grammar'],
+  examples: [
+    {label: 'Print the grammar', cli: 'astryx layout grammar'},
+    {
+      label: 'Expand to TSX',
+      cli: "astryx layout expand 'V[g6] > C{card-callout}*4' ./src/Page.tsx",
+    },
+  ],
+  exitCodes: [
+    {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.error-codes.test.mjs

@@ -0,0 +1,66 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Error-code contract tests for the layout command wrapper. Locks the
+ * two foreseeable input errors to STABLE ERR_* codes (never ERR_UNKNOWN or a
+ * raw fs errno) and asserts --json/human exit parity:
+ *   - empty expression  → ERR_MISSING_ARGUMENT
+ *   - --file <missing>  → ERR_FILE_NOT_FOUND (not raw ENOENT), no stack leak
+ * Spawns the real binary so the bin error boundary is exercised faithfully.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {spawnSync} from 'node:child_process';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CLI_BIN = path.resolve(__dirname, '../bin/astryx.mjs');
+
+function run(args) {
+  const res = spawnSync('node', [CLI_BIN, ...args], {
+    encoding: 'utf-8',
+    timeout: 20_000,
+  });
+  return {status: res.status, stdout: res.stdout || '', stderr: res.stderr || ''};
+}
+
+describe('layout --json error codes', () => {
+  for (const sub of ['expand', 'check']) {
+    it(`layout ${sub} "" → ERR_MISSING_ARGUMENT (not ERR_UNKNOWN)`, () => {
+      const r = run(['--json', 'layout', sub, '']);
+      expect(r.status).toBe(1);
+      const env = JSON.parse(r.stdout);
+      expect(env.code).toBe('ERR_MISSING_ARGUMENT');
+      expect(r.stderr).toBe('');
+      expect(r.stdout).not.toMatch(/\n\s+at /); // no stack frames
+    });
+
+    it(`layout ${sub} --file <missing> → ERR_FILE_NOT_FOUND (not ENOENT)`, () => {
+      const r = run([
+        '--json',
+        'layout',
+        sub,
+        '--file',
+        '/tmp/definitely-missing-astryx-xyz.mjs',
+      ]);
+      expect(r.status).toBe(1);
+      const env = JSON.parse(r.stdout);
+      expect(env.code).toBe('ERR_FILE_NOT_FOUND');
+      expect(r.stderr).toBe('');
+    });
+
+    it(`layout ${sub}: --json and human agree on exit code (empty input)`, () => {
+      const human = run(['layout', sub, '']);
+      const json = run(['--json', 'layout', sub, '']);
+      expect(json.status).toBe(human.status);
+      expect(json.status).toBe(1);
+    });
+
+    it(`layout ${sub} --file <missing> in human mode leaks no stack trace`, () => {
+      const r = run(['layout', sub, '--file', '/tmp/definitely-missing-astryx-xyz.mjs']);
+      expect(r.status).toBe(1);
+      expect(r.stderr).not.toMatch(/\n\s+at /);
+    });
+  }
+});

package/clients/cli/commands/layout.exit-parity.test.mjs

@@ -0,0 +1,41 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CLI-level tests for `astryx layout check` exit-code parity.
+ *
+ * The exit code is the contract and must NOT depend on --json vs human mode:
+ * an invalid (but parseable) layout exits 1 in BOTH modes so `layout check`
+ * works as a CI gate / agent check without parsing stdout. Runs the real
+ * program in-process via the shared runCli harness.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+
+const SLOW = 30_000;
+// Parses fine, but references an unknown component -> data.valid: false
+// (a semantic error, surfaced as data, not a thrown ERR_LAYOUT_PARSE).
+const INVALID = 'ZzzUnknownComponent[foo=bar]';
+const VALID = 'K';
+
+describe('layout check — exit-code parity (--json vs human)', () => {
+  it('human mode exits 1 for an invalid (parseable) expression', async () => {
+    const {status} = await runCli(['layout', 'check', INVALID]);
+    expect(status).toBe(1);
+  }, SLOW);
+
+  it('--json exits 1 for the SAME invalid expression (modes agree)', async () => {
+    const {status, stdout} = await runCli(['layout', 'check', INVALID, '--json']);
+    const env = JSON.parse(stdout);
+    expect(env.type).toBe('layout.check');
+    expect(env.data.valid).toBe(false);
+    expect(status).toBe(1);
+  }, SLOW);
+
+  it('a valid expression exits 0 in both modes', async () => {
+    expect((await runCli(['layout', 'check', VALID])).status).toBe(0);
+    const {status, stdout} = await runCli(['layout', 'check', VALID, '--json']);
+    expect(JSON.parse(stdout).data.valid).toBe(true);
+    expect(status).toBe(0);
+  }, SLOW);
+});

package/clients/cli/commands/layout.mjs

@@ -0,0 +1,275 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file layout command — thin CLI wrapper around api/layout.mjs.
+ *
+ * Subcommands:
+ *   astryx layout expand "<expr>" [path]   compressed expression → validated TSX
+ *   astryx layout check "<expr>"           validate + echo both canonical surfaces
+ *   astryx layout grammar                  agent cheatsheet (alias table is branch-generated)
+ *
+ * The expression argument may also come from --file or stdin (`-`),
+ * which is how multi-line outline (XLO) input usually arrives.
+ *
+ * The command surface (group + subcommand descriptions, args, flags) is sourced
+ * from the colocated CommandDocs via `defineCommand`; this file supplies only the
+ * actions.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {jsonOut} from '../../../foundation/response/json.mjs';
+import {emit, section, text, list, record, code, WARN} from '../formatters/index.mjs';
+import {cliError} from '../lib/cli-error.mjs';
+import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
+import {layoutExpand, layoutCheck, layoutGrammar} from '../../../api/layout/layout.mjs';
+import {defineCommand} from '../lib/define-command.mjs';
+import {doc as layoutGroup} from './layout.doc.mjs';
+import {doc as layoutExpandCommand} from './layout-expand.doc.mjs';
+import {doc as layoutCheckCommand} from './layout-check.doc.mjs';
+import {doc as layoutGrammarCommand} from './layout-grammar.doc.mjs';
+import {doc as layoutExpandFn} from '../../../api/layout/layoutExpand.doc.mjs';
+import {doc as layoutCheckFn} from '../../../api/layout/layoutCheck.doc.mjs';
+import {doc as layoutGrammarFn} from '../../../api/layout/layoutGrammar.doc.mjs';
+import {NO_RESULT_SET, resultSet} from '../../../foundation/debug/index.mjs';
+
+/**
+ * The api layer's @returns for these functions widen the `type` discriminator
+ * to `string`, so annotate the command-local result with the precise response
+ * shapes from the colocated api/layout/layout.type.mjs so narrowing + jsonOut
+ * typecheck.
+ *
+ * @typedef {import('../../../api/layout/layout.type.mjs').LayoutExpandResponse} LayoutExpandResponse
+ * @typedef {import('../../../api/layout/layout.type.mjs').LayoutCheckResponse} LayoutCheckResponse
+ * @typedef {import('../../../api/layout/layout.type.mjs').LayoutGrammarResponse} LayoutGrammarResponse
+ */
+
+/**
+ * @typedef {object} LayoutExpandOptions
+ * @property {string} [file]
+ * @property {'compact'|'outline'|'auto'} [form]
+ * @property {string} [name]
+ * @property {boolean} [loose]
+ */
+
+/**
+ * @typedef {object} LayoutCheckOptions
+ * @property {string} [file]
+ * @property {'compact'|'outline'|'auto'} [form]
+ * @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]
+ * @param {{file?: string}} [options]
+ * @returns {Promise<string>}
+ */
+async function readExpression(expr, options = {}) {
+  if (options.file) {
+    // Validate the file exists + is a regular file + is reasonably sized.
+    // We intentionally do NOT confine the read path (the user running the CLI
+    // controls --file; this is a read, not a write). The size cap prevents OOM
+    // from infinite streams like /dev/zero.
+    const filePath = path.resolve(process.cwd(), options.file);
+    const stat = fs.statSync(filePath, {throwIfNoEntry: false});
+    if (!stat || !stat.isFile()) {
+      cliError(`File not found: ${options.file}`, {
+        code: ERROR_CODES.ERR_FILE_NOT_FOUND,
+      });
+    }
+    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},
+      );
+    }
+    try {
+      return fs.readFileSync(filePath, 'utf-8');
+    } catch (e) {
+      const errno = /** @type {NodeJS.ErrnoException} */ (e);
+      if (errno && errno.code === 'ENOENT') {
+        // A --file pointing at a missing file is foreseeable — surface a
+        // stable code, not the raw ENOENT errno (and no stack in human mode).
+        cliError(`File not found: ${options.file}`, {
+          code: ERROR_CODES.ERR_FILE_NOT_FOUND,
+        });
+      }
+      throw e;
+    }
+  }
+  if (expr === '-') {
+    // Capped like --file: an endless stream must not be buffered whole.
+    /** @type {Buffer[]} */
+    const chunks = [];
+    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 ?? '';
+}
+
+/**
+ * @param {import('commander').Command} program
+ */
+export function registerLayout(program) {
+  const layoutCmd = defineCommand(program, layoutGroup);
+
+  defineCommand(layoutCmd, layoutExpandCommand, {
+    fn: layoutExpandFn,
+    action: async (/** @type {string} */ expression, /** @type {string} */ targetPath, /** @type {LayoutExpandOptions} */ options) => {
+      const json = program.opts().json || false;
+      const source = await readExpression(expression, options);
+      if (!source || source.trim() === '') {
+        return cliError(
+          'No layout expression given — pass it as an argument, via --file, or on stdin',
+          {code: ERROR_CODES.ERR_MISSING_ARGUMENT},
+        );
+      }
+      /** @type {LayoutExpandResponse} */
+      let result;
+      try {
+        result = /** @type {LayoutExpandResponse} */ (await layoutExpand(source, {
+          targetPath,
+          form: options.form,
+          loose: options.loose || false,
+          name: options.name,
+          cwd: process.cwd(),
+        }));
+      } catch (e) {
+        const err = /** @type {import('../../../api/error.mjs').AstryxError} */ (e);
+        return cliError(err.message, {suggestions: err.suggestions || [], code: err.code});
+      }
+      // Expanding turns an expression into TSX — a transformation, not a
+      // lookup. What it produced is in the output; there is no set to count.
+      if (json) {
+        jsonOut(result);
+        return NO_RESULT_SET;
+      }
+
+      /** @type {import('../formatters/index.mjs').Block[]} */
+      const out = [];
+      if (result.data.warnings.length > 0) {
+        out.push(text(result.data.warnings.map(w => `${WARN} ${w}`).join('\n')));
+      }
+      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},
+            {
+              format: {
+                todos: (/** @type {string[]} */ todos) =>
+                  `${todos.length} (search for "TODO(xle)")`,
+              },
+            },
+          ),
+        );
+      } else {
+        // Raw expanded TSX (no target path) — preformatted, emitted verbatim.
+        out.push(code(result.data.code));
+      }
+      emit(...out);
+      return NO_RESULT_SET;
+    },
+  });
+
+  defineCommand(layoutCmd, layoutCheckCommand, {
+    fn: layoutCheckFn,
+    action: async (/** @type {string} */ expression, /** @type {LayoutCheckOptions} */ options) => {
+      const json = program.opts().json || false;
+      const source = await readExpression(expression, options);
+      if (!source || source.trim() === '') {
+        return cliError(
+          'No layout expression given — pass it as an argument, via --file, or on stdin',
+          {code: ERROR_CODES.ERR_MISSING_ARGUMENT},
+        );
+      }
+      /** @type {LayoutCheckResponse} */
+      let result;
+      try {
+        result = /** @type {LayoutCheckResponse} */ (await layoutCheck(source, {
+          form: options.form,
+          loose: options.loose || false,
+          cwd: process.cwd(),
+        }));
+      } catch (e) {
+        const err = /** @type {import('../../../api/error.mjs').AstryxError} */ (e);
+        return cliError(err.message, {suggestions: err.suggestions || [], code: err.code});
+      }
+      // Exit code is the contract and must NOT depend on --json vs human: an
+      // invalid (but parseable) layout exits 1 in BOTH modes so `layout check`
+      // works as a CI gate / agent check without parsing stdout. Decide it
+      // before the JSON return (parity with doctor integration validate).
+      if (!result.data.valid) process.exitCode = 1;
+
+      // A verdict on one expression: valid or not, with the errors that made
+      // it so. Nothing was looked up.
+      if (json) {
+        jsonOut(result);
+        return NO_RESULT_SET;
+      }
+
+      const {valid, form, errors, warnings, compact, outline} = result.data;
+      if (!valid) {
+        // Each error: the formatted issue, with a hanging "did you mean" line.
+        const items = errors.map(e =>
+          e.suggestions && e.suggestions.length > 0
+            ? [e.formatted, `did you mean: ${e.suggestions.join(', ')}?`]
+            : [e.formatted],
+        );
+        emit(
+          text(`[fail] Invalid (${errors.length} error${errors.length === 1 ? '' : 's'}):`),
+          list(items),
+        );
+        return NO_RESULT_SET;
+      }
+
+      /** @type {import('../formatters/index.mjs').Block[]} */
+      const out = [text(`[ok] Valid (parsed as ${form})`)];
+      if (warnings.length > 0) {
+        out.push(text(warnings.map(w => `${WARN} ${w}`).join('\n')));
+      }
+      // The canonical compact/outline surfaces are preformatted — emit verbatim.
+      out.push(section('compact'), code(compact), section('outline'), code(outline));
+      emit(...out);
+      return NO_RESULT_SET;
+    },
+  });
+
+  defineCommand(layoutCmd, layoutGrammarCommand, {
+    fn: layoutGrammarFn,
+    action: async () => {
+      const json = program.opts().json || false;
+      /** @type {LayoutGrammarResponse} */
+      let result;
+      try {
+        result = /** @type {LayoutGrammarResponse} */ (await layoutGrammar({cwd: process.cwd()}));
+      } catch (e) {
+        const err = /** @type {import('../../../api/error.mjs').AstryxError} */ (e);
+        return cliError(err.message, {suggestions: err.suggestions || [], code: err.code});
+      }
+      // One document, the same one every time: the grammar cheatsheet.
+      const answered = resultSet({count: 1, resultKind: 'doc'});
+      if (json) {
+        jsonOut(result);
+        return answered;
+      }
+      // The cheatsheet is a preformatted document — emit verbatim.
+      emit(code(result.data.text));
+      return answered;
+    },
+  });
+}

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);
+});