@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.3-canary.02f5fe4

package/authoring/integration/schema.mjs

@@ -19,6 +19,7 @@ import {formatZodError} from '../_shared/errors.mjs';
 /** @typedef {import('./type.js').AstryxIntegration} AstryxIntegration */
 
 const MAX_AGENT_DOC_LINES = 8;
+const MAX_CLI_COMMAND_CODE_POINTS = 120;
 const MAX_AGENT_DOC_LINE_CODE_POINTS = 240;
 const MANAGED_MARKER_TEXT = /(?:ASTRYX|XDS):(START|END)/u;
 const PROVIDER_ID_RE =
@@ -51,6 +52,21 @@ function invalidAgentDocLine(value) {
   return null;
 }
 
+export const cliCommandSchema = z.string().superRefine((value, ctx) => {
+  const message = invalidAgentDocLine(value);
+  if (message) {
+    ctx.addIssue({code: 'custom', message});
+    return;
+  }
+  const codePoints = [...value].length;
+  if (codePoints > MAX_CLI_COMMAND_CODE_POINTS) {
+    ctx.addIssue({
+      code: 'custom',
+      message: `must contain at most ${MAX_CLI_COMMAND_CODE_POINTS} Unicode code points (received ${codePoints})`,
+    });
+  }
+});
+
 const agentDocLineSchema = z.string().superRefine((value, ctx) => {
   const message = invalidAgentDocLine(value);
   if (message) ctx.addIssue({code: 'custom', message});
@@ -78,6 +94,7 @@ export const integrationBaseSchema = z.object({
   docs: z.string().optional(),
   themes: z.string().optional(),
   issuesUrl: z.string().url().optional(),
+  docsiteUrl: z.string().url().optional(),
 });
 
 // Unknown top-level keys are stripped rather than rejected. `.strict()` made a key from a
@@ -91,14 +108,15 @@ export const integrationBaseSchema = z.object({
 // IS an authoring mistake and still fails here.
 export const integrationSchema = integrationBaseSchema.extend({
   agentDocs: agentDocsSchema.optional(),
+  cliCommand: cliCommandSchema.optional(),
 });
 
 /**
  * Parse every default-manifest field except the independently isolated
- * `agentDocs` contribution.
+ * `agentDocs` and `cliCommand` fields.
  * @param {unknown} input
  * @param {string} label
- * @returns {Omit<AstryxIntegration, 'agentDocs'>}
+ * @returns {Omit<AstryxIntegration, 'agentDocs' | 'cliCommand'>}
  */
 export function parseIntegrationBase(input, label) {
   const result = integrationBaseSchema.safeParse(input);
@@ -118,6 +136,20 @@ export function parseAgentDocsField(input, label) {
   return result.data;
 }
 
+/**
+ * Parse only the optional `cliCommand` field. Isolated like `agentDocs`: an
+ * invalid command is ignored with a warning, and the rest of the manifest
+ * still contributes.
+ * @param {unknown} input
+ * @param {string} label
+ * @returns {string}
+ */
+export function parseCliCommandField(input, label) {
+  const result = cliCommandSchema.safeParse(input);
+  if (!result.success) throw new Error(formatZodError(label, result.error));
+  return result.data;
+}
+
 /**
  * Compile-time drift-lock: sealed schema must infer exactly {@link AstryxIntegration}.
  *

package/authoring/integration/type.ts

@@ -11,7 +11,7 @@
  * The manifest module may also carry `debug` and `gapReport` NAMED exports.
  * They are not fields here on purpose: a CLI released before a given manifest
  * field existed could reject it and lose every contribution, while an unknown
- * named export is simply not read. See `astryx docs cli/integrations`.
+ * named export is simply not read. See `astryx docs authoring`.
  */
 export interface AstryxIntegration {
   /** Stable logical provider ID. Omit to use package.json#name. Set this only
@@ -44,6 +44,18 @@ export interface AstryxIntegration {
   };
   /** Where to file issues/feedback for this integration. */
   issuesUrl?: string;
+  /** Link to this integration's docs site, such as its home page. The CLI
+   *  accepts it as a known field; catalogs that list the package may show
+   *  it. */
+  docsiteUrl?: string;
+  /** The command that runs the Astryx CLI for this package's users, such as
+   *  `acme astryx`. Every command the CLI prints in a project that loads
+   *  this package starts with it, in place of the package-manager prefix
+   *  (`pnpm exec astryx`, `yarn astryx`). One line, no subcommand. When two
+   *  loaded integrations set different commands, neither is used and
+   *  `astryx doctor` warns. An invalid value is ignored with a warning; the
+   *  rest of the manifest still loads. JSON output keeps commands bare. */
+  cliCommand?: string;
 }
 
 /**

package/clients/cli/bin/astryx.mjs

@@ -14,7 +14,7 @@
 // unsupported runtimes this guard protects against.
 //
 // Sibling package modules (e.g. `cli/`, `lib/`) are resolved by this bin's REAL
-// path. When the CLI is installed as a package, `npx astryx` runs this file
+// path. When the CLI is installed as a package, the package manager runs this file
 // through the `node_modules/.bin/astryx` symlink, and some Node versions resolve
 // relative specifiers from the symlink's directory rather than the real package
 // — breaking bare `../…` imports with a cryptic ERR_MODULE_NOT_FOUND.
@@ -53,67 +53,13 @@ if (!isNodeVersionSupported(process.versions.node)) {
   process.exit(1);
 }
 
-// Imports that transitively load `styleText` must happen AFTER the gate above,
-// so they are dynamically imported here rather than at the top of the module.
-const {program, loadProjectDebugHandler, handleVersionJsonPreflight} =
-  await importSrc('index.mjs');
-const {isJsonMode, toErrorEnvelope} = await importSrc('../../foundation/response/json.mjs');
-const {handleCommanderError} = await importSrc('lib/json-shim.mjs');
-const {setOutcome} = await importSrc('../../foundation/debug/index.mjs');
-
-/**
- * Top-level error boundary (contract guarantee #4): an uncaught throw must
- * never reach a --json consumer as a raw stack trace. If we're in JSON mode,
- * convert it to the contract's error envelope on stdout and exit 1; otherwise
- * preserve the normal human-facing behavior.
- *
- * We detect JSON mode two ways: the global flag (set once root options are
- * parsed) and a raw argv check, since a throw can occur during parsing/command
- * load — before the preAction hook engages the flag.
- */
-function inJsonMode() {
-  return isJsonMode() || process.argv.slice(2).includes('--json');
-}
-
-/** @param {unknown} err */
-function handleFatal(err) {
-  // CommanderError (parse errors, --help, unknown command) routes
-  // through the JSON shim so that a --json consumer always gets a
-  // valid envelope and the right exit code. handleCommanderError
-  // calls process.exit when it owns the error.
-  if (handleCommanderError(err)) return;
-
-  // Anything still here is an uncaught throw or an unhandled rejection —
-  // a bug rather than a user error, and the class of failure most worth
-  // having a record of.
-  setOutcome('fatal', {exitCode: 1, error: err});
-
-  if (inJsonMode()) {
-    // Only emit if a command didn't already produce an envelope.
-    if (!process.__xdsJsonHandled) {
-      process.__xdsJsonHandled = true;
-      console.log(JSON.stringify(toErrorEnvelope(err), null, 2));
-    }
-    process.exit(1);
-  }
-  // Human mode: preserve Commander/Node default-ish behavior.
-  console.error(err instanceof Error ? err.stack || err.message : String(err));
-  process.exit(1);
-}
-
-process.on('unhandledRejection', handleFatal);
-process.on('uncaughtException', handleFatal);
-
-// Pick up the project's `debug` function before parsing, so parse errors and
-// `--help` — which short-circuit before any hook runs — are reported too.
-await loadProjectDebugHandler();
-
-// `--version --json` answers and exits without Commander, so it runs here —
-// after the handler exists, or the run would go unrecorded.
-handleVersionJsonPreflight();
-
-try {
-  await program.parseAsync(process.argv);
-} catch (err) {
-  handleFatal(err);
-}
+// Global mode: the run chooses the release that answers this folder and, when
+// it is not this copy, hands the run to it before anything the project
+// provides (its astryx.config, integrations, or Core) is loaded; only then
+// does it load and dispatch the command. See clients/cli/run.mjs,
+// foundation/release/handoff.mjs, and spec AST-081 FR2 and FR9.
+const {runCli} = await importSrc('run.mjs');
+await runCli({
+  cliRoot: join(binDir, '..', '..', '..'),
+  argv: process.argv.slice(2),
+});

package/clients/cli/cli-command.test.mjs

@@ -0,0 +1,166 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Every printed command starts with the project's CLI command: the door a host
+ * sets, or the `cliCommand` a loaded integration declares. JSON keeps commands
+ * bare.
+ */
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import {spawnSync} from 'node:child_process';
+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 {
+  hasRecordedProject,
+  runWithCliDoor,
+} from '../../foundation/env/cli-command.mjs';
+import {getCliInvocation} from '../../foundation/env/package-manager.mjs';
+import {loadProjectForHelp} from './index.mjs';
+
+const BIN = path.resolve(import.meta.dirname, 'bin', 'astryx.mjs');
+
+/** @type {string} */
+let tmpDir;
+
+beforeEach(() => {
+  // Repo-local, so Vite permits importing the integration manifest.
+  tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-cli-command-'));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/**
+ * An app that installs one integration declaring `cliCommand`, with no
+ * astryx.config: the integration is autolinked.
+ * @param {string} cliCommand
+ */
+function appWithIntegration(cliCommand) {
+  fs.writeFileSync(
+    path.join(tmpDir, 'package.json'),
+    JSON.stringify({name: 'app', dependencies: {'@acme/x': '1.0.0'}}),
+  );
+  fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '<!-- ASTRYX:START -->\n');
+  const pkg = path.join(tmpDir, 'node_modules', '@acme', 'x');
+  fs.mkdirSync(pkg, {recursive: true});
+  fs.writeFileSync(
+    path.join(pkg, 'package.json'),
+    JSON.stringify({name: '@acme/x', version: '1.0.0'}),
+  );
+  fs.writeFileSync(
+    path.join(pkg, 'astryx.integration.mjs'),
+    `export default ${JSON.stringify({cliCommand})};\n`,
+  );
+}
+
+describe("an integration's cliCommand", () => {
+  it('starts the hints of a command that never loads the project itself', async () => {
+    appWithIntegration('acme astryx');
+    const {status, stderr} = await runCli(['theme', 'remove', 'nope'], tmpDir);
+    expect(status).toBe(1);
+    expect(stderr).toContain('`acme astryx theme add nope`');
+  });
+});
+
+describe('the setup nudge in a project with no CLI of its own', () => {
+  it('names the declared cliCommand for the step after installing the CLI (spec AST-081 FR5)', async () => {
+    // Outside this repository: the nudge stays quiet in the CLI's own checkout.
+    const app = fs.mkdtempSync(
+      path.join(os.tmpdir(), 'astryx-cli-command-nudge-'),
+    );
+    try {
+      // Only Core, of another release than the CLI that answers, an
+      // integration declaring cliCommand, and no agent docs yet.
+      fs.writeFileSync(
+        path.join(app, 'package.json'),
+        JSON.stringify({
+          name: 'app',
+          dependencies: {'@acme/x': '1.0.0', '@astryxdesign/core': '0.0.1'},
+        }),
+      );
+      fs.writeFileSync(path.join(app, 'package-lock.json'), '{}');
+      for (const [name, version, extra] of [
+        ['@acme/x', '1.0.0', 'acme astryx'],
+        ['@astryxdesign/core', '0.0.1', null],
+      ]) {
+        const dir = path.join(app, 'node_modules', ...name.split('/'));
+        fs.mkdirSync(dir, {recursive: true});
+        fs.writeFileSync(
+          path.join(dir, 'package.json'),
+          JSON.stringify({name, version}),
+        );
+        if (extra) {
+          fs.writeFileSync(
+            path.join(dir, 'astryx.integration.mjs'),
+            `export default ${JSON.stringify({cliCommand: extra})};\n`,
+          );
+        }
+      }
+
+      const {stderr} = await runCli(['docs', 'tokens'], app);
+      expect(stderr).toContain(
+        'Next step: run `npm install @astryxdesign/cli@0.0.1`, then `acme astryx init`',
+      );
+    } finally {
+      fs.rmSync(app, {recursive: true, force: true});
+    }
+  });
+});
+
+describe('help', () => {
+  it('loads the project for a help run, and only for one', async () => {
+    appWithIntegration('acme astryx');
+    const cwd = process.cwd();
+    process.chdir(tmpDir);
+    try {
+      await loadProjectForHelp(['docs', 'theme']);
+      expect(hasRecordedProject(tmpDir)).toBe(false);
+      await loadProjectForHelp(['component', '--help']);
+      expect(getCliInvocation(tmpDir)).toBe('acme astryx');
+    } finally {
+      process.chdir(cwd);
+    }
+  });
+
+  it("prints the integration's command in `--help`", () => {
+    appWithIntegration('acme astryx');
+    const result = spawnSync(process.execPath, [BIN, '--help'], {
+      cwd: tmpDir,
+      encoding: 'utf-8',
+    });
+    expect(result.status).toBe(0);
+    expect(result.stdout).toContain('acme astryx search button');
+  });
+});
+
+describe("a host's door", () => {
+  it('prefixes doc commands in text and leaves them bare in JSON', async () => {
+    const text = await runWithCliDoor('acme astryx', () =>
+      runCli(['docs', 'getting-started', '--full']),
+    );
+    expect(text.stdout).toContain('acme astryx init');
+
+    const json = await runWithCliDoor('acme astryx', () =>
+      runCli(['docs', 'getting-started', '--json']),
+    );
+    expect(json.stdout).toContain('astryx init');
+    expect(json.stdout).not.toContain('acme astryx');
+  });
+
+  it('prefixes suggested commands in text and leaves them bare in JSON', async () => {
+    const text = await runWithCliDoor('acme astryx', () =>
+      runCli(['search', '']),
+    );
+    expect(text.stderr).toContain('acme astryx search button');
+
+    const json = await runWithCliDoor('acme astryx', () =>
+      runCli(['search', '', '--json']),
+    );
+    expect(JSON.parse(json.stdout).suggestions[0].name).toBe(
+      'astryx search button',
+    );
+  });
+});

package/clients/cli/command-result-coverage.test.mjs

@@ -44,12 +44,13 @@ const NO_ACTION_OF_THEIR_OWN = [];
 /**
  * Commands that record for themselves instead of returning a descriptor.
  *
- * They cannot come from a CommandDoc — `manifest` introspects the live program,
- * `postinstall` is a package-script hook — so they carry the mark by hand. The
- * mark is a hatch, and a hatch nobody watches is a hole: this list is the
- * watch. The root program is checked separately below.
+ * Empty: every command, `manifest` and the hidden `postinstall` hook included,
+ * registers through defineCommand. The mark is a hatch, and a hatch nobody
+ * watches is a hole: this list is the watch. The root program is checked
+ * separately below.
+ * @type {string[]}
  */
-const RECORD_FOR_THEMSELVES = ['manifest', 'postinstall'];
+const RECORD_FOR_THEMSELVES = [];
 
 /**
  * Every command in the program, depth first, with its fully qualified name.

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

@@ -24,6 +24,7 @@ export const doc = {
     {label: 'List posts', cli: 'astryx blog'},
     {label: 'Read one post', cli: 'astryx blog introducing-astryx --json'},
   ],
+  outsideProject: 'same',
   exitCodes: [
     {code: 0, when: 'success'},
     {code: 1, when: 'unknown slug, or the feed or a post cannot be fetched'},

package/clients/cli/commands/build-theme.batch-report.test.mjs

@@ -91,12 +91,24 @@ function count(text, pattern) {
 
 /** @param {string} stdout */
 function lines(stdout) {
-  return stdout.split('\n').filter(Boolean);
+  return bareRecipe(stdout).split('\n').filter(Boolean);
+}
+
+/**
+ * The font recipe names `docs typography` with the project's CLI invocation,
+ * which depends on where the test runs; compare it as bare `astryx`.
+ * @param {string} stdout
+ */
+function bareRecipe(stdout) {
+  return stdout.replace(
+    /(recipe: |guidance: )\S.*? docs typography/g,
+    '$1astryx docs typography',
+  );
 }
 
 /** @param {string} stdout The sizes follow Core's CSS, so goldens keep the shape. */
 function normalized(stdout) {
-  return stdout.replace(/\d+(\.\d+)? KB/g, '<size> KB');
+  return bareRecipe(stdout).replace(/\d+(\.\d+)? KB/g, '<size> KB');
 }
 
 /** Bytes of the full report printed by one invocation per theme. */
@@ -168,7 +180,9 @@ describe('theme build report', () => {
     }
     expect(count(out, 'Install in your app')).toBe(1);
     expect(count(out, 'Or with a <link> tag:')).toBe(1);
-    expect(count(out, "import { Theme } from '@astryxdesign/core';")).toBe(2);
+    expect(
+      count(out, "import { Theme } from '@astryxdesign/core/theme';"),
+    ).toBe(2);
     expect(count(out, '[note]')).toBe(1);
     expect(count(out, 'note: Font')).toBe(0);
     expect(count(out, 'fonts.googleapis.com/css2')).toBe(1);

package/clients/cli/commands/build-theme.color-scheme.test.mjs

@@ -73,7 +73,7 @@ describe('theme build color-scheme output', () => {
     const project = path.join(tmpDir, 'project');
     const themesDir = path.join(project, 'themes');
     // A raw light-dark() token value is what triggers the color-scheme
-    // injection in build-theme.mjs. `defineTheme.test.ts` already covers the
+    // injection in theme.mjs. `defineTheme.test.ts` already covers the
     // separate [light, dark] tuple -> light-dark() conversion; this fixture
     // writes the string directly so this test stays focused on the CLI's own
     // color-scheme decision, not on that conversion.

package/clients/cli/commands/build-theme.font-warning.test.mjs

@@ -75,7 +75,7 @@ describe('theme build font-loading warning', () => {
     expect(result.stdout).toContain('display=swap');
     expect(result.stdout).toContain('@font-face');
     expect(result.stdout).toContain('font-display: swap');
-    expect(result.stdout).toContain('astryx docs typography');
+    expect(result.stdout).toContain(' docs typography');
     // The one-line summaries follow the CLI's stream contract. These are
     // NOTICES about a correct theme, not warnings, so they go to stdout with
     // the rest of the build's progress — stderr stays for the defects an
@@ -105,8 +105,8 @@ describe('theme build font-loading warning', () => {
     );
 
     expect(result.code).toBe(0);
-    expect(result.stdout).toContain(
-      '[note] Fonts named but not loaded: "Space Grotesk", "JetBrains Mono". Load them in your app (recipe: astryx docs typography).\n',
+    expect(result.stdout).toMatch(
+      /\[note\] Fonts named but not loaded: "Space Grotesk", "JetBrains Mono"\. Load them in your app \(recipe: .+ docs typography\)\.\n/,
     );
     expect(result.stdout).not.toContain('fonts.googleapis.com');
     expect(result.stdout).not.toContain('@font-face');