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

package/clients/cli/commands/hook/index.mjs

@@ -20,7 +20,6 @@ import {defineCommand} from '../../lib/define-command.mjs';
 import {resultSet} from '../../../../foundation/debug/index.mjs';
 import {ERROR_CODES} from '../../../../foundation/response/error-codes.mjs';
 import {hook as hookApi} from '../../../../api/hook/hook.mjs';
-import {findRelatedBlocks} from '../../../../api/template/template.mjs';
 import {doc as hookCommand} from '../hook.doc.mjs';
 import {doc as hookFn} from '../../../../api/hook/hook.doc.mjs';
 
@@ -169,24 +168,15 @@ export function registerHook(program) {
                   )
                 : formatHookFull(result.data);
 
-          // Show related block templates from relatedComponents
-          const relatedComps = result.data.relatedComponents || [];
-          /** @type {import('../../../../api/template/template.mjs').DiscoveredTemplate[]} */
-          const allBlocks = [];
-          for (const comp of relatedComps) {
-            const blocks = await findRelatedBlocks(comp);
-            for (const b of blocks) {
-              if (!allBlocks.some(existing => existing.dirName === b.dirName)) {
-                allBlocks.push(b);
-              }
-            }
-          }
-
+          // Text projects the envelope only. Block templates are JSON-backed
+          // under `component <name> --blocks`.
+          const related = result.data.relatedComponents ?? [];
           emit(
             code(doc),
-            allBlocks.length > 0 && section('Related block templates'),
-            allBlocks.length > 0 &&
-              records(allBlocks, {fields: ['dirName', 'description']}),
+            related.length > 0 &&
+              text(
+                `Block templates: ${run} component <name> --blocks for ${related.join(', ')}`,
+              ),
           );
           break;
         }

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

@@ -12,7 +12,7 @@ export const doc = {
   type: 'command',
   name: 'hook',
   displayName: 'astryx hook',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'List hooks or print hook docs',
   description:
     'Resolves a hook by name and prints its authored doc, or lists the catalog grouped ' +

package/clients/cli/commands/hook.text-projection.test.mjs

@@ -0,0 +1,45 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx hook <name>` text is a projection of `hook.detail`: it shows
+ * nothing the JSON envelope does not carry.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+import {findRelatedBlocks} from '../../../api/template/template.mjs';
+
+const HOOK = 'useAnnounce';
+
+describe('hook detail text projection', () => {
+  it('prints no block templates that the JSON envelope lacks', async () => {
+    const json = await runCli(['--json', 'hook', HOOK]);
+    expect(json.status).toBe(0);
+    const envelope = JSON.parse(json.stdout);
+    expect(envelope.type).toBe('hook.detail');
+    const related = envelope.data.relatedComponents;
+    expect(related.length).toBeGreaterThan(0);
+
+    const blockNames = [];
+    for (const component of related) {
+      for (const block of await findRelatedBlocks(component)) {
+        blockNames.push(block.dirName);
+      }
+    }
+    expect(blockNames.length).toBeGreaterThan(0);
+
+    const text = await runCli(['hook', HOOK]);
+    expect(text.status).toBe(0);
+    const shownButNotInJson = blockNames.filter(
+      name => text.stdout.includes(name) && !json.stdout.includes(name),
+    );
+    expect(shownButNotInJson).toEqual([]);
+  });
+
+  it('points at the JSON-backed block lookup for each related component', async () => {
+    const text = await runCli(['hook', HOOK]);
+    expect(text.stdout).toMatch(/component <name> --blocks/);
+    expect(text.stdout).toContain('VisuallyHidden');
+    expect(text.stdout).toContain('Toast');
+  });
+});

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

@@ -12,43 +12,54 @@ export const doc = {
   type: 'command',
   name: 'init',
   displayName: 'astryx init',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Initialize the design system in your project',
   description:
     'Non-interactive project setup (no prompts, so it behaves the same for humans, ' +
     'agents, and CI). By default it installs the AGENTS.md/CLAUDE.md agent-docs, ' +
     'including guidance from configured integrations, and prints getting-started ' +
-    'guidance; features/--all add theme and page-building ' +
-    'guidance and can scaffold a starter template.',
+    "steps. --features and --all print only the chosen features' guidance (no " +
+    'getting-started steps); the theme feature also writes an annotated theme template.',
   fn: 'init',
   options: [
     {
       flag: '--features <list>',
       param: 'options.features',
       description:
-        'Comma-separated features to install (agents, theme, template)',
+        'Comma-separated features: agents (agent docs), theme (writes theme.template.ts), template (prints the page-building commands; writes no file). ' +
+        'An unknown feature exits 1 with ERR_UNKNOWN_FEATURE. Ignored with --all or --remove-agents',
     },
     {
       flag: '--all',
       param: 'options.all',
-      description: 'Install all features, no prompts',
+      description:
+        'Install all features (agents, theme, template); overrides --features. Prints their guidance instead of the getting-started steps',
     },
     {
       flag: '--remove-agents',
       param: 'options.removeAgents',
-      description: 'Remove AI agent docs from all agent doc files',
+      description:
+        'Remove the managed block from AGENTS.md, CLAUDE.md, .claude/CLAUDE.md, .cursorrules, .hermes.md and HERMES.md ' +
+        "(deleting AGENTS.md or .claude/CLAUDE.md when only init's heading is left) and do nothing else. " +
+        '--features, --all, --agent and --agent-docs-path are ignored; a file written with --agent-docs-path keeps its block',
     },
     {
       flag: '--agent <tool>',
       param: 'options.agent',
       choices: ['claude', 'cursor', 'codex', 'hermes', 'muse', 'all'],
       description:
-        'Target AI tool for agent docs: claude, cursor, codex, hermes, muse, all',
+        'Target AI tool for agent docs: claude (CLAUDE.md or .claude/CLAUDE.md, else creates .claude/CLAUDE.md), cursor (.cursorrules if present, else AGENTS.md), ' +
+        'codex and muse (AGENTS.md), hermes (.hermes.md or HERMES.md if present, else AGENTS.md), all (every existing agent doc, else AGENTS.md and .claude/CLAUDE.md). ' +
+        'An unknown tool exits 1 with ERR_UNKNOWN_AGENT. ' +
+        'Used only when agent docs are installed (the default, --all, or --features agents); --agent-docs-path takes precedence',
     },
     {
       flag: '--agent-docs-path <path...>',
       param: 'options.agentDocsPath',
-      description: 'Explicit file path(s) for agent docs',
+      description:
+        'Explicit file path(s) for agent docs, inside the project; takes precedence over --agent. ' +
+        'If any path is outside the project, no agent docs are written and the command exits 1. ' +
+        'Used only when agent docs are installed',
     },
   ],
   examples: [
@@ -57,10 +68,13 @@ export const doc = {
     {label: 'Machine-readable receipt', cli: 'astryx init --json'},
   ],
   exitCodes: [
-    {code: 0, when: 'success'},
+    {
+      code: 0,
+      when: 'success, including agent docs that could not be written for a reason other than a path escape (reported as docsError)',
+    },
     {
       code: 1,
-      when: 'unknown --agent, an unknown feature or template, or a starter template would overwrite an existing page',
+      when: 'an unknown --agent or feature, or an --agent-docs-path outside the project',
     },
   ],
   related: ['doctor', 'upgrade', 'build', 'theme'],

package/clients/cli/commands/init.flag-help.test.mjs

@@ -0,0 +1,153 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx init` documents how its flags interact and when it exits 1, and
+ * behaves as documented. Option text is read from the generated manifest (the
+ * same strings `--help` prints); exit codes from the CommandDoc.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+import {doc as initDoc} from './init.doc.mjs';
+
+const MARKER_START = '<!-- ASTRYX:START -->';
+
+/** @type {string} */
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-init-flags-'));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/** @param {string} rel */
+const exists = rel => fs.existsSync(path.join(tmpDir, rel));
+/** @param {string} rel */
+const read = rel => fs.readFileSync(path.join(tmpDir, rel), 'utf8');
+
+/**
+ * init's option descriptions from the manifest, keyed by long flag.
+ * @returns {Promise<Record<string, string>>}
+ */
+async function initOptions() {
+  const {stdout} = await runCli(['--json', 'manifest'], tmpDir);
+  const init = JSON.parse(stdout).data.commands.find(
+    (/** @type {{name: string}} */ c) => c.name === 'init',
+  );
+  return Object.fromEntries(
+    init.options.map((/** @type {{flag: string, description: string}} */ o) => [
+      o.flag.match(/--[a-z-]+/)?.[0],
+      o.description,
+    ]),
+  );
+}
+
+/** @param {string[]} args */
+async function initJson(args) {
+  const result = await runCli(['--json', 'init', ...args], tmpDir);
+  return {status: result.status, envelope: JSON.parse(result.stdout)};
+}
+
+/** @param {number} code */
+const exitWhen = code => initDoc.exitCodes?.find(e => e.code === code)?.when ?? '';
+
+describe('astryx init flag interactions', () => {
+  it('--remove-agents: help says it only removes the block, and it ignores every install flag', async () => {
+    const help = (await initOptions())['--remove-agents'];
+    for (const flag of ['--features', '--all', '--agent', '--agent-docs-path']) {
+      expect(help).toContain(flag);
+    }
+    for (const file of ['AGENTS.md', '.claude/CLAUDE.md', '.cursorrules', '.hermes.md', 'HERMES.md']) {
+      expect(help).toContain(file);
+    }
+    expect(help).toMatch(/--agent-docs-path keeps its block/);
+
+    await initJson(['--agent-docs-path', 'docs/AI.md']);
+    await initJson([]);
+    expect(exists('AGENTS.md')).toBe(true);
+
+    const removed = await initJson([
+      '--remove-agents',
+      '--features',
+      'bogus',
+      '--all',
+      '--agent',
+      'bogus',
+      '--agent-docs-path',
+      'docs/AI.md',
+    ]);
+    expect(removed.status).toBe(0);
+    expect(removed.envelope.type).toBe('init.remove');
+    expect(exists('AGENTS.md')).toBe(false);
+    expect(exists('theme.template.ts')).toBe(false);
+    expect(read('docs/AI.md')).toContain(MARKER_START);
+  });
+
+  it('--all: help says it overrides --features, and an unknown feature beside it is not checked', async () => {
+    const options = await initOptions();
+    expect(options['--all']).toMatch(/overrides --features/);
+    expect(options['--features']).toMatch(/Ignored with --all or --remove-agents/);
+    expect(options['--features']).toContain('ERR_UNKNOWN_FEATURE');
+
+    const {status, envelope} = await initJson(['--all', '--features', 'bogus']);
+    expect(status).toBe(0);
+    expect(envelope.data.features).toEqual(['agents', 'theme', 'template']);
+  });
+
+  it('--agent and --agent-docs-path: help states their scope and precedence, and the CLI follows it', async () => {
+    const options = await initOptions();
+    expect(options['--agent']).toMatch(/Used only when agent docs are installed/);
+    expect(options['--agent']).toMatch(/--agent-docs-path takes precedence/);
+    expect(options['--agent']).toContain('ERR_UNKNOWN_AGENT');
+    expect(options['--agent-docs-path']).toMatch(/takes precedence over --agent/);
+    expect(options['--agent-docs-path']).toMatch(/outside the project.*exits 1/);
+    expect(options['--agent-docs-path']).toMatch(/Used only when agent docs are installed/);
+
+    const unused = await initJson([
+      '--features',
+      'theme',
+      '--agent',
+      'bogus',
+      '--agent-docs-path',
+      '../outside.md',
+    ]);
+    expect(unused.status).toBe(0);
+    expect(unused.envelope.data.docsWritten).toEqual([]);
+
+    const explicit = await initJson(['--agent', 'claude', '--agent-docs-path', 'docs/AI.md']);
+    expect(explicit.status).toBe(0);
+    expect(explicit.envelope.data.docsWritten).toEqual(['docs/AI.md']);
+    expect(exists('CLAUDE.md') || exists('.claude/CLAUDE.md')).toBe(false);
+  });
+});
+
+describe('astryx init exit codes', () => {
+  it('exit 1: the CommandDoc lists an --agent-docs-path escape, which exits 1 in both modes and writes nothing', async () => {
+    expect(exitWhen(1)).toMatch(/--agent-docs-path outside the project/);
+    // The CLI never scaffolds a page template, so no template case can exit 1.
+    expect(exitWhen(1)).not.toMatch(/template/);
+
+    const text = await runCli(['init', '--agent-docs-path', 'ok.md', '../outside.md'], tmpDir);
+    const json = await initJson(['--agent-docs-path', 'ok.md', '../outside.md']);
+    expect(text.status).toBe(1);
+    expect(json.status).toBe(1);
+    expect(json.envelope.data.docsError.kind).toBe('path-safety');
+    expect(exists('ok.md')).toBe(false);
+  });
+
+  it('exit 0: the CommandDoc says a soft agent-docs failure still exits 0, and it does', async () => {
+    expect(exitWhen(0)).toMatch(/docsError/);
+
+    // A directory where AGENTS.md belongs makes the write fail without a path escape.
+    fs.mkdirSync(path.join(tmpDir, 'AGENTS.md'));
+    const {status, envelope} = await initJson([]);
+    expect(status).toBe(0);
+    expect(envelope.data.docsError).toEqual({kind: 'install-failed'});
+  });
+});

package/clients/cli/commands/integration-add.controls.test.mjs

@@ -0,0 +1,132 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {createProgram} from '../index.mjs';
+import {buildManifest} from '../lib/manifest.mjs';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+import {doc as fnDoc} from '../../../api/integration/integrationAdd.doc.mjs';
+
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(
+    path.join(process.cwd(), '.astryx-integration-add-controls-'),
+  );
+  fs.writeFileSync(
+    path.join(tmpDir, 'package.json'),
+    `${JSON.stringify({name: '@acme/widgets', version: '1.0.0'})}\n`,
+  );
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/** What each `integration add` control must define on the discovery surfaces. */
+const DEFINITIONS = {
+  name: [
+    'PascalCase for component',
+    'lowercase kebab-case for template, codemod, and theme',
+    'letters, digits, _ and - for doc',
+    'literal guidance line for agent-doc',
+  ],
+  '--type <type>': ['page (default) or block', 'only valid for template'],
+  '--replaces <topic>': ['only valid for doc', 'not with --extends'],
+  '--extends <topic>': ['only valid for doc', 'not with --replaces'],
+  '--to <version>': ['Exact semver', 'required for codemod and only valid there'],
+};
+
+describe('integration add control definitions', () => {
+  it('defines accepted values, defaults, and interactions in help', async () => {
+    const program = await createProgram();
+    const add = program.commands
+      .find(command => command.name() === 'integration')
+      ?.commands.find(command => command.name() === 'add');
+    const help = add?.helpInformation() ?? '';
+
+    for (const phrases of Object.values(DEFINITIONS)) {
+      for (const phrase of phrases) expect(help).toContain(phrase);
+    }
+  });
+
+  it('defines the same controls in the manifest', async () => {
+    const manifest = buildManifest(await createProgram());
+    const add = manifest.commands
+      .find(command => command.name === 'integration')
+      ?.subcommands?.find(command => command.name === 'integration add');
+    /** @type {Record<string, string>} */
+    const described = {};
+    for (const arg of add?.arguments ?? []) described[arg.name] = arg.description;
+    for (const option of add?.options ?? []) {
+      described[option.flag] = option.description;
+    }
+
+    for (const [control, phrases] of Object.entries(DEFINITIONS)) {
+      for (const phrase of phrases) {
+        expect(described[control], control).toContain(phrase);
+      }
+    }
+  });
+
+  it('defines the same controls for integrationAdd()', () => {
+    /** @param {string} name */
+    const param = name => fnDoc.params?.find(item => item.name === name);
+
+    for (const phrase of DEFINITIONS.name.slice(0, 3)) {
+      expect(param('name')?.description).toContain(phrase);
+    }
+    expect(param('options.templateType')?.default).toBe("'page'");
+    expect(param('options.replaces')?.description).toContain(
+      'not with options.extends',
+    );
+    expect(param('options.extends')?.description).toContain(
+      'not with options.replaces',
+    );
+    expect(param('options.to')?.description).toContain('Exact target semver');
+    expect(param('options.to')?.description).toContain('only valid there');
+  });
+
+  it('behaves as the definitions say', async () => {
+    const both = await runCli(
+      [
+        'integration',
+        'add',
+        'doc',
+        'acme-guide',
+        '--replaces',
+        'getting-started',
+        '--extends',
+        'theme',
+        '--json',
+      ],
+      tmpDir,
+    );
+    expect(both.status).toBe(1);
+    expect(JSON.parse(both.stdout).code).toBe('ERR_INVALID_ARGUMENT');
+
+    const looseVersion = await runCli(
+      ['integration', 'add', 'codemod', 'rename-prop', '--to', '1.2', '--json'],
+      tmpDir,
+    );
+    expect(looseVersion.status).toBe(1);
+    expect(JSON.parse(looseVersion.stdout).code).toBe('ERR_INVALID_ARGUMENT');
+
+    const typeElsewhere = await runCli(
+      ['integration', 'add', 'component', 'AcmeWidget', '--type', 'page', '--json'],
+      tmpDir,
+    );
+    expect(typeElsewhere.status).toBe(1);
+    expect(JSON.parse(typeElsewhere.stdout).code).toBe('ERR_INVALID_ARGUMENT');
+
+    const page = await runCli(
+      ['integration', 'add', 'template', 'acme-page', '--json'],
+      tmpDir,
+    );
+    expect(page.status).toBe(0);
+    expect(
+      fs.readFileSync(path.join(tmpDir, 'templates', 'acme-page.doc.mjs'), 'utf-8'),
+    ).toContain("type: 'page'");
+  });
+});

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

@@ -5,10 +5,10 @@ export const doc = {
   type: 'command',
   name: 'integration add',
   displayName: 'astryx integration add',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Add one working contribution to an integration package',
   description:
-    'Writes the complete minimum shape the selected contribution needs, creates the integration manifest on first use, declares the root only after a valid contribution exists, and verifies the result through the same discovery contract the packed-package check uses.',
+    'Writes the files one contribution needs, creates the integration manifest on first use, and declares a root only after a contribution the CLI can read exists behind it. A component or template import also needs an `exports` entry: add writes one only when package.json already has an `exports` map, so start a new package with `"exports": {}`. See {@link generic:quick-start}.',
   fn: 'integrationAdd',
   args: [
     {
@@ -22,7 +22,7 @@ export const doc = {
       param: 'name',
       required: true,
       description:
-        'Contribution name; for agent-doc this is the literal guidance line',
+        'Contribution name: PascalCase for component (AcmeWidget); lowercase kebab-case for template, codemod, and theme (account-card); letters, digits, _ and - for doc; the literal guidance line for agent-doc',
     },
   ],
   options: [
@@ -35,25 +35,39 @@ export const doc = {
       flag: '--type <type>',
       param: 'options.templateType',
       choices: ['page', 'block'],
-      description: 'Template type (page or block); only valid for template',
+      description:
+        'Template type: page (default) or block; only valid for template',
     },
     {
       flag: '--replaces <topic>',
       param: 'options.replaces',
-      description: 'Replace an existing doc topic; only valid for doc',
+      description:
+        'Existing doc topic this one replaces (letters, digits, _ and -); only valid for doc and not with --extends',
     },
     {
       flag: '--extends <topic>',
       param: 'options.extends',
-      description: 'Extend an existing doc topic; only valid for doc',
+      description:
+        'Existing doc topic this one extends (letters, digits, _ and -); only valid for doc and not with --replaces',
+    },
+    {
+      flag: '--parent <namespace>',
+      param: 'options.parent',
+      description:
+        "Namespace of this package to place the doc in, as a guide in its `guides` slot; writes the namespace doc when it is missing, and declares the CLI that reads it as an optional `@astryxdesign/cli` peer. Only valid for doc, and not with --replaces or --extends",
     },
     {
       flag: '--to <version>',
       param: 'options.to',
-      description: 'Target version for a codemod; required for codemod',
+      description:
+        'Exact semver of the @astryxdesign/core version whose upgrade runs the codemod (e.g. 0.7.0); required for codemod and only valid there',
     },
   ],
   examples: [
+    {
+      label: 'Preview',
+      cli: 'astryx integration add component AcmeWidget --dry-run --json',
+    },
     {
       label: 'Add a component',
       cli: 'astryx integration add component AcmeWidget',
@@ -61,7 +75,23 @@ export const doc = {
     {label: 'Add a doc topic', cli: 'astryx integration add doc deploying'},
     {
       label: 'Add a page template',
-      cli: 'astryx integration add template dashboard',
+      cli: 'astryx integration add template acme-dashboard',
+    },
+    {
+      label: 'Add a block template',
+      cli: 'astryx integration add template account-card --type block',
+    },
+    {
+      label: 'Replace a doc topic',
+      cli: 'astryx integration add doc acme-getting-started --replaces getting-started',
+    },
+    {
+      label: 'Extend a doc topic',
+      cli: 'astryx integration add doc acme-theming --extends theme',
+    },
+    {
+      label: 'Add a guide to the package\'s own docs section',
+      cli: 'astryx integration add doc releasing --parent acme',
     },
     {
       label: 'Add a codemod',
@@ -72,10 +102,6 @@ export const doc = {
       cli: "astryx integration add agent-doc 'Run acme verify before finishing.'",
     },
     {label: 'Add a source theme', cli: 'astryx integration add theme ocean'},
-    {
-      label: 'Preview',
-      cli: 'astryx integration add component AcmeWidget --dry-run --json',
-    },
   ],
   exitCodes: [
     {code: 0, when: 'the contribution is written or the dry run succeeds'},
@@ -84,5 +110,5 @@ export const doc = {
       when: 'the kind, name, options, package, or target files are invalid or conflict',
     },
   ],
-  related: ['integration pack', 'doctor integration validate', 'theme add'],
+  related: ['integration verify', 'doctor integration validate', 'theme add'],
 };