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

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

@@ -12,43 +12,51 @@ 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.',
+    'guidance and write 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 to install (agents, theme, template). 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',
     },
     {
       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, cursor, codex, hermes, muse, all. 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 +65,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,7 +5,7 @@ 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.',
@@ -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,22 +35,32 @@ 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 the codemod migrates to (e.g. 1.2.0); required for codemod and only valid there',
     },
   ],
   examples: [
@@ -63,6 +73,22 @@ export const doc = {
       label: 'Add a page template',
       cli: 'astryx integration add template 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 deploying --parent acme',
+    },
     {
       label: 'Add a codemod',
       cli: 'astryx integration add codemod rename-widget --to 1.2.0',

package/clients/cli/commands/integration-authoring.test.mjs

@@ -120,7 +120,7 @@ describe('integration authoring CLI', () => {
     );
   });
 
-  it('packs the generated contribution and proves the consumer inventory', async () => {
+  it('pack-check rejects a generated component without an exports map (no-map false green)', async () => {
     const added = await runCli(
       ['integration', 'add', 'component', 'AcmeWidget', '--json'],
       tmpDir,
@@ -131,19 +131,23 @@ describe('integration authoring CLI', () => {
       ['integration', 'pack', '--check', '--json'],
       tmpDir,
     );
-    expect(checked.status).toBe(0);
-    expect(parseEnvelope(checked.stdout)).toMatchObject({
+    // Without an exports map, the extensionless import cannot resolve —
+    // pack-check must fail, not false-green.
+    expect(checked.status).not.toBe(0);
+    const envelope = parseEnvelope(checked.stdout);
+    expect(envelope).toMatchObject({
       type: 'integration.pack-check',
       data: {
         name: '@acme/widgets',
-        version: '1.0.0',
-        packable: true,
-        contributions: {
-          local: {components: ['AcmeWidget']},
-          packed: {components: ['AcmeWidget']},
-        },
+        packable: false,
       },
     });
+    expect(envelope.data.issues).toContainEqual(
+      expect.objectContaining({
+        severity: 'error',
+        message: expect.stringContaining('AcmeWidget'),
+      }),
+    );
   });
 
   it('requires the explicit --check gate on pack', async () => {

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

@@ -5,7 +5,7 @@ export const doc = {
   type: 'command',
   name: 'integration pack',
   displayName: 'astryx integration pack',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Prove the packed integration is what consumers receive',
   description:
     'Runs the package lifecycle, packs with npm, checks every required contribution file against the real tarball, extracts it into a scratch consumer, and compares the local and packed contribution inventories through one shared contract.',

package/clients/cli/commands/integration-real-world.test.mjs

@@ -201,13 +201,6 @@ export const oceanTheme = defineTheme({
 });
 `,
     );
-    const catalogFile = path.join(providerDir, 'themes', 'manifest.json');
-    const catalog = JSON.parse(fs.readFileSync(catalogFile, 'utf-8'));
-    catalog.themes[0].files.push(
-      'tokens/ocean.palette.ts',
-      'tokens/ocean.palette.receipt.json',
-    );
-    writeJson(catalogFile, catalog);
 
     const providerPackage = JSON.parse(
       fs.readFileSync(path.join(providerDir, 'package.json'), 'utf-8'),
@@ -464,8 +457,9 @@ export const oceanTheme = defineTheme({
         outputDir: target,
         files: [
           'oceanTheme.ts',
-          'tokens/ocean.palette.ts',
+          'oceanTheme.doc.mjs',
           'tokens/ocean.palette.receipt.json',
+          'tokens/ocean.palette.ts',
         ],
       },
     });
@@ -612,7 +606,7 @@ export const oceanTheme = defineTheme({
     expect(corruptedInstall.status).not.toBe(0);
     expect(parseEnvelope(corruptedInstall.stdout)).toMatchObject({
       code: 'ERR_THEME_INVALID',
-      error: expect.stringContaining('ocean.palette.ts'),
+      error: expect.stringContaining('./tokens/ocean.palette'),
     });
   }, 120_000);
 });

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

@@ -5,7 +5,7 @@ export const doc = {
   type: 'command',
   name: 'integration',
   displayName: 'astryx integration',
-  namespace: 'cli',
+  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.',

package/clients/cli/commands/integration.mjs

@@ -58,6 +58,7 @@ export function registerIntegration(program) {
           templateType: options.type,
           replaces: options.replaces,
           extends: options.extends,
+          parent: options.parent,
           to: options.to,
         });
       } catch (error) {