@astryxdesign/cli 0.6.3 → 0.6.4-canary.06c8fa3

package/api/layout/layoutExpand.doc.mjs

@@ -1,106 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file FunctionDoc for `layoutExpand()` / `astryx layout expand`. Colocated
- * with the API function it documents; the response-shape source of truth stays
- * in `layout.type.mjs`.
- * @position packages/cli/api/layout — function documentation
- */
-
-/** @type {import('@astryxdesign/cli/authoring').FunctionDoc} */
-export const doc = {
-  type: 'function',
-  kind: 'api',
-  name: 'layoutExpand',
-  displayName: 'layoutExpand()',
-  summary: 'Expand a validated layout expression into XDS TSX.',
-  description:
-    'The generator behind `astryx layout expand`. Parses and validates a compressed XLE/XLO ' +
-    'expression, then expands it into ready-to-use XDS TSX, auto-routing structural children ' +
-    'into the right slots, scaffolding typed useState for interactive controls, and splicing or ' +
-    'importing any referenced template blocks. Returns the code (and metadata) in a layout.expand ' +
-    'envelope, optionally writing it to a path within cwd.',
-  importPath: '@astryxdesign/cli/api',
-  signature:
-    'layoutExpand(expression: string, options?: LayoutExpandOptions): Promise<LayoutExpandResponse>',
-  keywords: ['layout', 'expand', 'xle', 'xlo', 'tsx', 'scaffold', 'generate'],
-  params: [
-    {
-      name: 'expression',
-      type: 'string',
-      description:
-        'The layout expression to expand (XLE compact or XLO outline form).',
-      required: true,
-    },
-    {
-      name: 'options.targetPath',
-      type: 'string',
-      description:
-        'Write the generated TSX here (validated to stay within cwd). A directory gets <name>.tsx; a file path is used as-is. Omit to return the code without writing.',
-    },
-    {
-      name: 'options.form',
-      type: "'compact' | 'outline' | 'auto'",
-      description:
-        'Force which input surface the expression is parsed as, or auto-detect it.',
-      default: "'auto'",
-    },
-    {
-      name: 'options.loose',
-      type: 'boolean',
-      description:
-        'Downgrade unknown {hint} references to TODO warnings instead of hard errors.',
-      default: 'false',
-    },
-    {
-      name: 'options.name',
-      type: 'string',
-      description: 'PascalCase name for the generated component.',
-      default: "'GeneratedLayout'",
-    },
-    {
-      name: 'options.cwd',
-      type: 'string',
-      description:
-        'Directory the block catalog, registry, and target path resolve against.',
-    },
-  ],
-  returns: [
-    {
-      type: 'layout.expand',
-      description:
-        'The expansion: the parsed form, the generated TSX code, componentsUsed, states (count of useState hooks scaffolded), todos, blocksReferenced (each {name, mode}), warnings, and written (the relative output path, or null when nothing was written).',
-    },
-  ],
-  throws: [
-    {
-      code: 'ERR_INVALID_ARGUMENT',
-      when: 'the expression is empty, or name is not a PascalCase identifier',
-    },
-    {
-      code: 'ERR_INVALID_OPTION',
-      when: 'form is not one of "compact", "outline", or "auto"',
-    },
-    {
-      code: 'ERR_LAYOUT_PARSE',
-      when: 'the expression has a syntax error (reported with line/col)',
-    },
-    {
-      code: 'ERR_LAYOUT_INVALID',
-      when: 'the expression parses but fails validation (unknown component/prop/enum/block)',
-    },
-    {code: 'ERR_PATH_TRAVERSAL', when: 'the target path escapes cwd'},
-  ],
-  examples: [
-    {
-      label: 'Expand to TSX',
-      code: 'const r = await layoutExpand(\'VStack[g4] > Heading"Title" + Text"Body"\');',
-    },
-    {
-      label: 'Write to a file',
-      code: "await layoutExpand('Card > Text\"Hi\"', {targetPath: 'src/Generated.tsx', name: 'Generated'});",
-    },
-  ],
-  command: 'layout expand',
-  related: ['layoutCheck', 'layoutGrammar'],
-};

package/api/layout/layoutGrammar.doc.d.mts

@@ -1,11 +0,0 @@
-// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
-// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
-
-/**
- * @file FunctionDoc for `layoutGrammar()` / `astryx layout grammar`. Colocated
- * with the API function it documents; the response-shape source of truth stays
- * in `layout.type.mjs`.
- * @position packages/cli/api/layout — function documentation
- */
-/** @type {import('@astryxdesign/cli/authoring').FunctionDoc} */
-export const doc: import("@astryxdesign/cli/authoring").FunctionDoc;

package/api/layout/layoutGrammar.doc.mjs

@@ -1,56 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file FunctionDoc for `layoutGrammar()` / `astryx layout grammar`. Colocated
- * with the API function it documents; the response-shape source of truth stays
- * in `layout.type.mjs`.
- * @position packages/cli/api/layout — function documentation
- */
-
-/** @type {import('@astryxdesign/cli/authoring').FunctionDoc} */
-export const doc = {
-  type: 'function',
-  kind: 'api',
-  name: 'layoutGrammar',
-  displayName: 'layoutGrammar()',
-  summary: 'Return the XLE/XLO grammar cheatsheet for this install.',
-  description:
-    'The reference behind `astryx layout grammar`: the agent cheatsheet for writing XLE/XLO ' +
-    "layout expressions, with the alias table generated from this branch's registry rather than " +
-    'hand-maintained, so short names always reflect the components actually installed.',
-  importPath: '@astryxdesign/cli/api',
-  signature:
-    'layoutGrammar(options?: LayoutGrammarOptions): Promise<LayoutGrammarResponse>',
-  keywords: [
-    'layout',
-    'grammar',
-    'cheatsheet',
-    'xle',
-    'xlo',
-    'aliases',
-    'reference',
-  ],
-  params: [
-    {
-      name: 'options.cwd',
-      type: 'string',
-      description:
-        'Directory the component registry (and its alias table) resolves against.',
-    },
-  ],
-  returns: [
-    {
-      type: 'layout.grammar',
-      description:
-        "The cheatsheet: a text field with the full grammar reference, plus an aliases map (short name → canonical component) generated from this install's registry.",
-    },
-  ],
-  examples: [
-    {
-      label: 'Get the cheatsheet',
-      code: 'const {data} = await layoutGrammar();',
-    },
-  ],
-  command: 'layout grammar',
-  related: ['layoutExpand', 'layoutCheck'],
-};

package/assets/templates/themes/manifest.json

@@ -1,95 +0,0 @@
-{
-  "version": 1,
-  "generatedBy": "scripts/generate-cli-themes.mjs",
-  "themes": [
-    {
-      "slug": "butter",
-      "displayName": "Butter",
-      "description": "Warm, creamy yellows with a friendly blue accent. Playful enough for consumer surfaces, soft enough to stay readable.",
-      "maintained": false,
-      "entry": "butterTheme.ts",
-      "exportName": "butterTheme",
-      "files": [
-        "butterTheme.ts",
-        "icons.tsx"
-      ]
-    },
-    {
-      "slug": "chocolate",
-      "displayName": "Chocolate",
-      "description": "Warm chocolate theme for Astryx — rich brown palette with Fraunces headings, Albert Sans body, and Lucide icons",
-      "maintained": false,
-      "entry": "chocolateTheme.ts",
-      "exportName": "chocolateTheme",
-      "files": [
-        "chocolateTheme.ts",
-        "icons.tsx"
-      ]
-    },
-    {
-      "slug": "gothic",
-      "displayName": "Gothic",
-      "description": "Deep blue-grays and a signature display serif. Dramatic and editorial, for surfaces that want to be remembered.",
-      "maintained": false,
-      "entry": "gothicTheme.ts",
-      "exportName": "gothicTheme",
-      "files": [
-        "gothicTheme.ts",
-        "icons.tsx"
-      ]
-    },
-    {
-      "slug": "matcha",
-      "displayName": "Matcha",
-      "description": "Earthy greens with a calm, organic feel. Naturalistic and grounded, great for wellness or content-first apps.",
-      "maintained": false,
-      "entry": "matchaTheme.ts",
-      "exportName": "matchaTheme",
-      "files": [
-        "matchaTheme.ts",
-        "icons.tsx"
-      ]
-    },
-    {
-      "slug": "neutral",
-      "displayName": "Neutral",
-      "description": "Restrained warm grays. Minimal and quiet, so the content stays the focus.",
-      "maintained": true,
-      "entry": "neutralTheme.ts",
-      "exportName": "neutralTheme",
-      "files": [
-        "neutralTheme.ts",
-        "icons.tsx",
-        "neutralPalettes.ts",
-        "neutralPalettes.generated.ts",
-        "neutralPaletteRefs.generated.ts",
-        "neutralPalettes.generated.receipt.json",
-        "palette.config.json"
-      ]
-    },
-    {
-      "slug": "stone",
-      "displayName": "Stone",
-      "description": "Warm stone and slate, earthy and understated, with just enough character to feel handcrafted.",
-      "maintained": false,
-      "entry": "stoneTheme.ts",
-      "exportName": "stoneTheme",
-      "files": [
-        "stoneTheme.ts",
-        "icons.tsx"
-      ]
-    },
-    {
-      "slug": "y2k",
-      "displayName": "Y2K",
-      "description": "Hot pinks, lime greens, and Poppins. Bubbly, playful, and unmistakably retro.",
-      "maintained": false,
-      "entry": "y2kTheme.ts",
-      "exportName": "y2kTheme",
-      "files": [
-        "y2kTheme.ts",
-        "icons.tsx"
-      ]
-    }
-  ]
-}

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

@@ -1,54 +0,0 @@
-// 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',
-  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}],
-  options: [
-    {flag: '--file <file>', description: 'Read the expression from a file'},
-    {
-      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 or empty, has a syntax error, or a bad --form',
-    },
-  ],
-  related: ['layout expand', 'layout grammar'],
-};

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

@@ -1,66 +0,0 @@
-// 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',
-  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},
-    {name: 'path', param: 'options.targetPath', required: false},
-  ],
-  options: [
-    {flag: '--file <file>', description: 'Read the expression from a file'},
-    {
-      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 expression, 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

@@ -1,30 +0,0 @@
-// 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',
-  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

@@ -1,34 +0,0 @@
-// 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',
-  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: 'success (help shown, or a subcommand succeeded)'},
-    {code: 1, when: 'an unknown subcommand'},
-  ],
-  related: ['template', 'build'],
-};

package/clients/cli/commands/layout.error-codes.test.mjs

@@ -1,66 +0,0 @@
-// 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

@@ -1,41 +0,0 @@
-// 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);
-});