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

package/clients/cli/lib/manifest.mjs

@@ -14,7 +14,8 @@
  * `type` discriminators it can emit — are layered on from:
  *
  *   - JSON_SUPPORTED  (the allowlist in index.mjs), and
- *   - RESPONSE_TYPES  (the declarative map below).
+ *   - RESPONSE_TYPES  (the declarative map below; ROOT_RESPONSE_TYPES names the
+ *     two, help and version, that no single command owns).
  *
  * A drift-guard test (manifest.test.mjs) asserts every registered command
  * appears in the manifest and every JSON-supported command has a response-type
@@ -35,6 +36,8 @@
  */
 
 import {API_VERSION} from '../../../foundation/response/json.mjs';
+import {commandDocsOf} from './define-command.mjs';
+import {doc as manifestDoc} from '../commands/manifest.doc.mjs';
 
 /**
  * Response `type` discriminators each fully-qualified command can emit in
@@ -49,18 +52,26 @@ export const RESPONSE_TYPES = {
   init: ['init.run', 'init.remove'],
   component: [
     'component.list',
+    'component.batch',
     'component.detail',
     'component.detail.props',
     'component.detail.source',
     'component.detail.showcase',
     'component.detail.blocks',
   ],
-  docs: ['docs.list', 'docs.detail', 'docs.detail.section'],
+  docs: [
+    'docs.list',
+    'docs.index',
+    'docs.detail',
+    'docs.detail.section',
+    'docs.node',
+  ],
   blog: ['blog.list', 'blog.detail'],
   discover: [
     'discover.list',
     'discover.detail',
     'discover.detail.doc',
+    'discover.item',
     'discover.search',
   ],
   search: ['search'],
@@ -82,8 +93,9 @@ export const RESPONSE_TYPES = {
   'theme targets': ['theme.targets'],
   'theme palette generate': ['theme.palette.generate'],
   'integration add': ['integration.add'],
+  'integration verify': ['integration.pack-check'],
   'integration pack': ['integration.pack-check'],
-  upgrade: ['upgrade.list', 'upgrade.status', 'upgrade.run'],
+  upgrade: ['upgrade.list', 'upgrade.registry', 'upgrade.status', 'upgrade.run'],
   manifest: ['manifest'],
   doctor: ['doctor'],
   'doctor integration validate': ['integration.validate'],
@@ -95,6 +107,14 @@ export const RESPONSE_TYPES = {
   'layout grammar': ['layout.grammar'],
 };
 
+/**
+ * Response types no single command owns: `help` (a bare `astryx --json`, and
+ * `--help --json` on any command) and `version` (`astryx --version --json`).
+ * The response-types enum lists them beside {@link RESPONSE_TYPES}.
+ * @type {readonly string[]}
+ */
+export const ROOT_RESPONSE_TYPES = Object.freeze(['help', 'version']);
+
 /**
  * Example invocations per fully-qualified command. Optional, agent-facing.
  * @type {Record<string, string[]>}
@@ -103,16 +123,23 @@ const EXAMPLES = {
   component: [
     'astryx component',
     'astryx component XDSButton',
+    'astryx component Button Badge Text',
     'astryx component XDSButton --props --json',
   ],
-  docs: ['astryx docs', 'astryx docs spacing --json'],
+  docs: [
+    'astryx docs',
+    'astryx docs spacing --json',
+    'astryx docs theme',
+    'astryx docs theme quick-start',
+    'astryx docs cli/integrations/quick-start --full',
+  ],
   discover: ['astryx discover --json'],
   search: [
     'astryx search modal --json',
     'astryx search button --type component --json',
   ],
   build: ['astryx build', 'astryx build "analytics dashboard" --json'],
-  swizzle: ['astryx swizzle XDSButton'],
+  swizzle: ['astryx swizzle Button'],
   'gap-report': [
     'astryx gap-report --list-categories',
     "astryx gap-report Button --category docs_gap --reason 'Missing keyboard example'",
@@ -145,7 +172,7 @@ const EXAMPLES = {
     'astryx integration add component AcmeWidget',
     'astryx integration add doc deploying --dry-run --json',
   ],
-  'integration pack': ['astryx integration pack --check --json'],
+  'integration verify': ['astryx integration verify --json'],
   upgrade: ['astryx upgrade --json'],
   manifest: ['astryx manifest --json', 'astryx --json'],
   doctor: ['astryx doctor', 'astryx doctor --json'],
@@ -232,6 +259,18 @@ function fullName(cmd, root) {
   return parts.join(' ');
 }
 
+/**
+ * The docs a command was built from. `manifest` is registered by hand in
+ * index.mjs, so its CommandDoc is read here.
+ * @param {import('commander').Command} cmd
+ * @param {string} name
+ */
+function docsOf(cmd, name) {
+  return (
+    commandDocsOf(cmd) ?? (name === 'manifest' ? {doc: manifestDoc} : undefined)
+  );
+}
+
 /**
  * Recursively describe a Commander command and its subcommands.
  *
@@ -247,6 +286,8 @@ function describeCommand(cmd, root, jsonSupported) {
   // `_hidden` is a Commander internal not present on its public types.
   if (!name || /** @type {any} */ (cmd)._hidden || name === 'help') return null;
 
+  const docs = docsOf(cmd, name);
+
   const subcommands = /** @type {object[]} */ (
     (cmd.commands || [])
       .map(sub => describeCommand(sub, root, jsonSupported))
@@ -279,6 +320,12 @@ function describeCommand(cmd, root, jsonSupported) {
 
   if (EXAMPLES[name]) entry.examples = [...EXAMPLES[name]];
 
+  const exitCodes = (docs?.doc.exitCodes ?? []).map(({code, when}) => ({
+    code,
+    when,
+  }));
+  if (exitCodes.length > 0) entry.exitCodes = exitCodes;
+
   // Sort subcommands by name for a stable, agent-facing contract — the same
   // guarantee the top-level command list makes. Otherwise Commander
   // registration order leaks into the manifest and a pure reorder of

package/clients/cli/lib/manifest.test.mjs

@@ -156,7 +156,10 @@ describe('manifest: shape', () => {
 
   it('derives arguments from Commander metadata', () => {
     const component = allEntries.find((c) => c.name === 'component');
-    expect(component.arguments.map((a) => a.name)).toContain('name');
+    const names = component.arguments.find((a) => a.name === 'names');
+    expect(names.required).toBe(false);
+    expect(names.variadic).toBe(true);
+    expect(names.description).toContain('Two or more return one ordered batch');
     const themeBuild = allEntries.find((c) => c.name === 'theme build');
     expect(themeBuild.arguments.map((a) => a.name)).toContain('files');
     const files = themeBuild.arguments.find((a) => a.name === 'files');
@@ -193,6 +196,23 @@ describe('manifest: e2e', () => {
     // Enriched: the full structured manifest is embedded.
     expect(parsed.data.manifest).toBeDefined();
     expect(parsed.data.manifest.commands.find((c) => c.name === 'component').responseTypes)
-      .toContain('component.list');
+      .toEqual(expect.arrayContaining(['component.list', 'component.batch']));
+  });
+});
+
+describe('manifest: text projection', () => {
+  it('astryx manifest (text) uses the JSON entry keys as its field names', async () => {
+    const text = await runCli(['manifest']);
+    expect(text.status).toBe(0);
+    const json = JSON.parse((await runCli(['manifest', '--json'])).stdout);
+    const jsonKeys = new Set(json.data.commands.flatMap((c) => Object.keys(c)));
+    const textKeys = new Set(
+      text.stdout
+        .split('\n')
+        .map((line) => /^([A-Za-z]+):\s/.exec(line)?.[1])
+        .filter(Boolean),
+    );
+    expect(textKeys).toContain('name');
+    for (const key of textKeys) expect(jsonKeys).toContain(key);
   });
 });

package/clients/cli/lib/parse-error-format.test.mjs

@@ -0,0 +1,81 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file A parse failure reads like every other Astryx error in text mode.
+ *
+ * `astryx theme list --lang zh-Hans` printed Commander's own line —
+ * `error: option '--lang <locale>' argument 'zh-Hans' is invalid…` — while
+ * every other CLI error prints `Error: …`. `--json` was already correct
+ * (ERR_INVALID_LANG), so text and JSON disagreed on everything except the exit
+ * code. Commander writes that line before any Astryx code runs, so the shim is
+ * the only place that can speak for it.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {Command} from 'commander';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+import {installJsonShim} from './json-shim.mjs';
+
+describe('a parse error prints the Astryx error format', () => {
+  it.each([
+    ['invalid --lang value', ['theme', 'list', '--lang', 'zh-Hans'], 'ERR_INVALID_LANG'],
+    ['invalid --detail value', ['theme', 'list', '--detail', 'nope'], 'ERR_INVALID_DETAIL'],
+    ['unknown option', ['component', '--bogus-flag'], 'ERR_INVALID_OPTION'],
+    ['missing argument', ['theme', 'build'], 'ERR_MISSING_ARGUMENT'],
+  ])('%s', async (_label, args, code) => {
+    const human = await runCli(args);
+
+    expect(human.status).toBe(1);
+    expect(human.stderr).toContain('Error: ');
+    // Commander's own lowercase line must not reach the user.
+    expect(human.stderr).not.toMatch(/(^|\n)error: /);
+
+    // --json is unchanged, and the two modes agree on the exit code.
+    const json = await runCli(['--json', ...args]);
+    expect(json.status).toBe(human.status);
+    expect(JSON.parse(json.stdout).code).toBe(code);
+    expect(json.stderr).toBe('');
+  });
+
+  it('carries Commander\'s explanation, not just a generic line', async () => {
+    const {stderr} = await runCli(['theme', 'list', '--lang', 'zh-Hans']);
+    expect(stderr).toContain("'zh-Hans' is invalid");
+    expect(stderr).toContain('en, zh, dense');
+  });
+
+  it('leaves --help and --version at exit 0 with nothing on stderr', async () => {
+    for (const args of [['--help'], ['theme', '--help']]) {
+      const r = await runCli(args);
+      expect(r.status).toBe(0);
+      expect(r.stderr).toBe('');
+    }
+  });
+
+  // Commander writes help through the same stderr channel when it shows help
+  // BECAUSE the invocation failed, so suppressing that channel wholesale would
+  // have taken the help with it. Driven on a throwaway program rather than a
+  // real command, so the guard outlives whichever command happens to have a
+  // subcommand group today.
+  it('still lets help reach stderr when help IS the failure report', () => {
+    const program = new Command('probe');
+    const group = program.command('group');
+    group.command('leaf').action(() => {});
+    installJsonShim(program);
+
+    /** @type {string[]} */
+    const written = [];
+    const original = process.stderr.write;
+    // @ts-expect-error test double for the write signature
+    process.stderr.write = str => {
+      written.push(String(str));
+      return true;
+    };
+    try {
+      group.outputHelp({error: true});
+    } finally {
+      process.stderr.write = original;
+    }
+
+    expect(written.join('')).toMatch(/Usage: probe group/);
+  });
+});

package/foundation/agent-docs/agent-docs.d.mts

@@ -78,8 +78,9 @@ export function detectStylingSystem(targetDir: string): "stylex" | "tailwind" |
  * Generate the agent cheat sheet from live CLI metadata.
  *
  * Structured as: workflow (behavioral) → rules (error prevention) → CLI reference.
- * Templates are positioned first in the workflow to teach agents the
- * "look at reference code" reflex before writing any UI.
+ * Templates lead the workflow: every page starts from a scaffolded template,
+ * because the template already carries the frame and spacing that an agent
+ * composing from components would have to re-derive, and usually gets wrong.
  *
  * `stylingSystem` tailors the custom-styling guidance to what the project has
  * configured (see {@link detectStylingSystem}) so the agent never reaches for a
@@ -182,6 +183,8 @@ export function removeXdsBlock(filePath: string, { deleteIfEmpty }?: {
 /**
  * Remove Astryx section from all known agent doc files.
  * @param {string} targetDir
+ * @throws {PathSafetyError} `ERR_PATH_TRAVERSAL` when a file it would change
+ *   resolves outside `targetDir`; nothing is changed.
  */
 export function removeAgentDocs(targetDir: string): void;
 /**
@@ -208,6 +211,8 @@ export function removeAgentDocs(targetDir: string): void;
  * @param {string} [options.renderedBlock] - Fully rendered expected block. Init
  *   and upgrade pass one shared block to every target.
  * @returns {string[]} List of files written
+ * @throws {import('../fs/path-safety.mjs').PathSafetyError} when a file it would
+ *   write resolves outside `targetDir`; nothing is written.
  */
 export function installAgentDocs(targetDir: string, { zh, lang, agent, paths, onlyReplace, topics, renderedBlock, }?: {
     zh?: boolean | undefined;

package/foundation/agent-docs/agent-docs.mjs

@@ -22,11 +22,12 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {findCoreDir, CLI_ROOT} from '../fs/paths.mjs';
-import {assertWithin} from '../fs/path-safety.mjs';
+import {assertWithin, PathSafetyError} from '../fs/path-safety.mjs';
 import {getCliInvocation} from '../env/package-manager.mjs';
 import {discoverComponents} from '../discovery/component-discovery.mjs';
 import {Project} from '../config/project.mjs';
 import {humanLog} from '../response/json.mjs';
+import {ERROR_CODES} from '../response/error-codes.mjs';
 import {
   AGENTS_MD,
   CLAUDE_MD,
@@ -353,8 +354,9 @@ export function detectStylingSystem(targetDir) {
  * Generate the agent cheat sheet from live CLI metadata.
  *
  * Structured as: workflow (behavioral) → rules (error prevention) → CLI reference.
- * Templates are positioned first in the workflow to teach agents the
- * "look at reference code" reflex before writing any UI.
+ * Templates lead the workflow: every page starts from a scaffolded template,
+ * because the template already carries the frame and spacing that an agent
+ * composing from components would have to re-derive, and usually gets wrong.
  *
  * `stylingSystem` tailors the custom-styling guidance to what the project has
  * configured (see {@link detectStylingSystem}) so the agent never reaches for a
@@ -427,17 +429,19 @@ export function generateCompressedIndex(
   lines.push('  import "@astryxdesign/core/astryx.css";');
   lines.push('');
 
-  // Workflow — `build` is the front door; discover before writing UI.
-  lines.push("WORKFLOW — discover, don't guess. Before writing UI:");
-  lines.push('1. `astryx build "<idea>"` — START HERE: returns a kit (closest [page] + [block]s + [component]s). No args = full playbook.');
-  lines.push('2. `astryx template <name> [--skeleton]` — scaffold the [page]/[block]s it named, or study their layout. Templates are reference code.');
-  lines.push('3. `astryx component <Name>` — props + examples for every component you use.');
+  // Workflow — `build` is the front door, and every page starts from the
+  // template it names.
+  lines.push('WORKFLOW — start every page from a template. Never lay out a page from scratch:');
+  lines.push('1. `astryx build "<idea>"` — START HERE: names the [page] template to start from (always one: the closest match, or the app shell), two other templates, and the [block]s + [component]s for parts it lacks. No args = full playbook.');
+  lines.push('2. `astryx template <name> <path>` — scaffold that template into your project. Keep its frame, gap and padding; replace its data, copy and sections; delete sections you do not need.');
+  lines.push('3. `astryx template <Block>` for a part the template lacks; `astryx component <Name>` for props + examples before you use or change a component.');
+  lines.push('Changing a page you already have? Keep it: skip step 2 and add blocks and components inside its sections.');
   lines.push('');
 
   // Rules — the top error-preventers.
   lines.push('RULES:');
   lines.push('- No <div> — components do all layout/spacing, page frame included.');
-  lines.push('- Frame first: read `astryx docs layout` before writing any page or screen — page frame, region widths, breakpoint behavior.');
+  lines.push('- Frame first: the template you scaffold sets the page frame. Read `astryx docs layout` before you change it — region widths, breakpoint behavior.');
   lines.push('- Dense data = rows (Table, List/Item), never Card-wrapped list items; Card is for standalone widgets. Status = StatusDot/Token; Badge = counts only.');
   // Styling guidance tailored to the project's configured system — never
   // recommend a path that isn't compiled here (xstyle needs the StyleX compiler;
@@ -462,7 +466,7 @@ export function generateCompressedIndex(
     css: 'replace any raw <div>/<span> layout, imported .css/@apply, or hardcoded value (#hex, 16px) with the component or a token (var(--color-*|--spacing-*|…))',
   };
   lines.push(
-    `- SELF-CHECK before you finish: re-read the file and ${selfCheckFix[stylingSystem] ?? selfCheckFix.css}. If unsure a component/prop exists, run \`astryx component <Name>\` / \`astryx search "<thing>"\`; don't hand-roll CSS.`,
+    `- SELF-CHECK before you finish: re-read the file and ${selfCheckFix[stylingSystem] ?? selfCheckFix.css}. Confirm the page kept its template's frame, gap and padding. If unsure a component/prop exists, run \`astryx component <Name>\` / \`astryx search "<thing>"\`; don't hand-roll CSS.`,
   );
   lines.push('');
 
@@ -485,8 +489,9 @@ export function generateCompressedIndex(
   if (resolvedTopics.length > 0) {
     lines.push(`  docs <topic>       ${resolvedTopics.join(', ')}`);
   }
+  lines.push('  docs cli           commands, API reference, integration authoring (one level at a time)');
   lines.push('  swizzle <Name>     eject component source for deep customization');
-  lines.push('  upgrade --apply    run after any Astryx or integration dependency bump');
+  lines.push('  upgrade --from <old version> --apply   run after any Astryx or integration dependency bump');
   const appendCount = agentDocs.reduce(
     (count, contribution) => count + contribution.append.length,
     0,
@@ -705,12 +710,65 @@ export function removeXdsBlock(filePath, {deleteIfEmpty = false} = {}) {
   return true;
 }
 
+/**
+ * Whether an agent-doc file already carries a managed-block marker.
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+function hasManagedMarker(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return content.includes(MARKER_START) || content.includes(LEGACY_MARKER_START);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Whether `removeXdsBlock` would change `filePath`: it holds one well-formed
+ * managed block.
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+function hasRemovableBlock(filePath) {
+  try {
+    return findManagedBlock(fs.readFileSync(filePath, 'utf-8')) != null;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Every file a run writes must resolve inside `targetDir`, symlinks
+ * included. Checked for the whole write set before the first write, so an
+ * escape writes nothing.
+ * @param {string} targetDir
+ * @param {Iterable<string>} relPaths
+ */
+function assertTargetsWithin(targetDir, relPaths) {
+  for (const p of relPaths) {
+    assertWithin(p, targetDir, {label: 'agent docs path'});
+  }
+}
+
 /**
  * Remove Astryx section from all known agent doc files.
  * @param {string} targetDir
+ * @throws {PathSafetyError} `ERR_PATH_TRAVERSAL` when a file it would change
+ *   resolves outside `targetDir`; nothing is changed.
  */
 export function removeAgentDocs(targetDir) {
   const allPaths = discoverAgentDocs(targetDir);
+  try {
+    assertTargetsWithin(
+      targetDir,
+      allPaths.filter(p => hasRemovableBlock(path.join(targetDir, p))),
+    );
+  } catch (err) {
+    // The code reaches the error envelope as is, so it must be registered.
+    if (!(err instanceof PathSafetyError)) throw err;
+    throw new PathSafetyError(err.message, ERROR_CODES.ERR_PATH_TRAVERSAL);
+  }
 
   for (const p of allPaths) {
     const filePath = path.join(targetDir, p);
@@ -718,9 +776,9 @@ export function removeAgentDocs(targetDir) {
     const deleteIfEmpty = p === AGENTS_MD || p === CLAUDE_DIR_MD;
     if (removeXdsBlock(filePath, {deleteIfEmpty})) {
       if (!fs.existsSync(filePath)) {
-        humanLog(`✓ Removed empty ${p}`);
+        humanLog(`[ok] Removed empty ${p}`);
       } else {
-        humanLog(`✓ Removed design system section from ${p}`);
+        humanLog(`[ok] Removed design system section from ${p}`);
       }
     }
   }
@@ -750,6 +808,8 @@ export function removeAgentDocs(targetDir) {
  * @param {string} [options.renderedBlock] - Fully rendered expected block. Init
  *   and upgrade pass one shared block to every target.
  * @returns {string[]} List of files written
+ * @throws {import('../fs/path-safety.mjs').PathSafetyError} when a file it would
+ *   write resolves outside `targetDir`; nothing is written.
  */
 export function installAgentDocs(
   targetDir,
@@ -806,6 +866,7 @@ export function installAgentDocs(
   // Agent preset
   if (agent) {
     const {inject, create} = resolveAgentPaths(targetDir, agent);
+    assertTargetsWithin(targetDir, [...inject, ...create]);
     for (const p of inject) {
       injectXdsBlock(path.join(targetDir, p), compressedIndex);
       written.push(p);
@@ -833,6 +894,14 @@ export function installAgentDocs(
   if (existing.length > 0) {
     const wrappers = discoverAgentDocWrappers(targetDir, existing);
     const targets = existing.filter(p => !wrappers.has(p));
+    // A refresh skips unmarked files and a wrapper is only written when it
+    // carries a block, so only the files this run writes are checked.
+    /** @param {string} p */
+    const marked = p => hasManagedMarker(path.join(targetDir, p));
+    assertTargetsWithin(targetDir, [
+      ...targets.filter(p => !onlyReplace || marked(p)),
+      ...[...wrappers].filter(marked),
+    ]);
 
     for (const p of targets) {
       const didWrite = injectXdsBlock(path.join(targetDir, p), compressedIndex, {onlyReplace});
@@ -860,6 +929,7 @@ export function installAgentDocs(
   if (onlyReplace) return written;
 
   const defaultPath = AGENTS_MD;
+  assertTargetsWithin(targetDir, [defaultPath]);
   injectXdsBlock(path.join(targetDir, defaultPath), compressedIndex, {
     createIfMissing: true,
     header: `# AGENTS.md\n\nProject-specific guidance for AI coding agents.`,