@astryxdesign/cli 0.6.4-canary.06c8fa3 → 0.6.4-canary.0e1fbdb

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

@@ -8,16 +8,16 @@ export const doc = {
   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,
@@ -102,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/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);
+});