@astryxdesign/cli 0.7.2-canary.fdd384f → 0.7.2

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,10 +53,24 @@ if (!isNodeVersionSupported(process.versions.node)) {
   process.exit(1);
 }
 
+// Global mode: choose the release that answers this folder and, when it is
+// not this copy, hand the run to it before anything the project provides (its
+// astryx.config, integrations, or Core) is loaded. Returns only when this copy
+// answers. See foundation/release/handoff.mjs and spec AST-081 FR2 and FR9.
+const {startRun} = await importSrc('../../foundation/release/handoff.mjs');
+await startRun({
+  cliRoot: join(binDir, '..', '..', '..'),
+  argv: process.argv.slice(2),
+});
+
 // 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 {
+  program,
+  loadProjectDebugHandler,
+  loadProjectForHelp,
+  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');
@@ -107,6 +121,9 @@ 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();
+// Help prints its commands while Commander parses, so a help run reads the
+// project's declared `cliCommand` here.
+await loadProjectForHelp();
 
 // `--version --json` answers and exits without Commander, so it runs here —
 // after the handler exists, or the run would go unrecorded.

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/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. */

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');

package/clients/cli/commands/build-theme.mjs

@@ -34,6 +34,7 @@ import * as path from 'node:path';
 import {fileURLToPath} from 'node:url';
 import {spawn} from 'node:child_process';
 import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
+import {isOutsideProject} from '../../../foundation/env/project-scope.mjs';
 import {jsonOut} from '../../../foundation/response/json.mjs';
 import {
   emit,
@@ -224,10 +225,13 @@ async function runThemeBuildWatch(entries, options) {
   emit(text(watchingLine));
 
   await new Promise((/** @type {(value?: void) => void} */ resolve) => {
+    let stopping = false;
     /** @param {NodeJS.Signals} signal */
     const stop = async signal => {
-      process.removeListener('SIGINT', stop);
-      process.removeListener('SIGTERM', stop);
+      // A second interrupt while stopping (a terminal's Ctrl-C and the same
+      // signal passed on by the copy that started the run) changes nothing.
+      if (stopping) return;
+      stopping = true;
       stopped = true;
       queued.clear();
       for (const d of debounces.values()) clearTimeout(d);
@@ -237,10 +241,12 @@ async function runThemeBuildWatch(entries, options) {
       rebuildChild?.kill(signal);
       await rebuildDone;
       emit(text('\nStopped watching.'));
+      process.removeListener('SIGINT', stop);
+      process.removeListener('SIGTERM', stop);
       resolve();
     };
-    process.once('SIGINT', stop);
-    process.once('SIGTERM', stop);
+    process.on('SIGINT', stop);
+    process.on('SIGTERM', stop);
   });
 }
 
@@ -283,14 +289,24 @@ function printThemeAddList(themes) {
         return theme.description ? [head, theme.description] : head;
       }),
     ),
-    text(
-      `Import one: ${run} theme add <slug> [--package <package>]\n` +
-        `Fork source: ${run} theme eject <slug> [target-path]`,
-    ),
+    text(themeNextSteps(run)),
     more,
   );
 }
 
+/**
+ * What to do with a listed theme. Outside a project there is no app to add one
+ * to, so only the fork step is named (spec AST-081 FR3).
+ * @param {string} run the CLI invocation
+ * @returns {string}
+ */
+function themeNextSteps(run) {
+  const fork = `Fork source: ${run} theme eject <slug> [target-path]`;
+  return isOutsideProject()
+    ? fork
+    : `Import one: ${run} theme add <slug> [--package <package>]\n${fork}`;
+}
+
 /**
  * Print every field in the `theme.list` entries. Duplicate slugs stay separate
  * because each record names its owner.
@@ -325,10 +341,7 @@ function printThemeList(themes, unmigratedCopies = []) {
           default: (/** @type {boolean} */ value) => (value ? 'yes' : 'no'),
         },
       }),
-      text(
-        `Import one: ${run} theme add <slug> [--package <package>]\n` +
-          `Fork source: ${run} theme eject <slug> [target-path]`,
-      ),
+      text(themeNextSteps(run)),
       more,
     );
   }

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

@@ -47,6 +47,7 @@ export const doc = {
       cli: 'astryx build "analytics dashboard" --json',
     },
   ],
+  outsideProject: 'same',
   exitCodes: [
     {code: 0, when: 'success (including zero matches)'},
     {

package/clients/cli/commands/build.exit-codes-doc.test.mjs

@@ -11,6 +11,7 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import {runCli} from '../../../test-utils/run-cli.mjs';
 import {doc as buildDoc} from './build.doc.mjs';
+import {linkThisCliAsProjectCli} from '../../../test-utils/release-fixtures.mjs';
 
 const SLOW = 30_000;
 
@@ -20,6 +21,9 @@ let tmpDir;
 beforeEach(() => {
   tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-build-no-core-'));
   fs.writeFileSync(path.join(tmpDir, 'package.json'), JSON.stringify({name: 'consumer'}));
+  // A project whose own CLI answers and that installs no Core: outside a
+  // project a copy answers from the Core it carries instead (AST-081 FR3).
+  linkThisCliAsProjectCli(tmpDir);
 });
 
 afterEach(() => {

package/clients/cli/commands/cli-postinstall.test.mjs

@@ -8,9 +8,16 @@
  * transient fetch (path _npx or npm_command=exec), and once set up.
  */
 
-import {describe, it, expect} from 'vitest';
+import {describe, it, expect, beforeEach, afterEach} 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 {fileURLToPath} from 'node:url';
 import {shouldNudge} from '../../../scripts/postinstall.mjs';
 
+const CLI = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..');
+
 const DEP = '/proj/node_modules/@astryxdesign/cli/scripts/postinstall.mjs'; // real dep install
 const NPX = '/Users/x/.npm/_npx/a1b2/node_modules/@astryxdesign/cli/scripts/postinstall.mjs';
 const REPO = '/repo/packages/cli/scripts/postinstall.mjs'; // monorepo/source
@@ -40,3 +47,44 @@ describe('cli postinstall — shouldNudge', () => {
     expect(shouldNudge({})).toBe(false);
   });
 });
+
+// Install time, end to end: the real script and the leaf it loads, installed
+// under a monorepo's node_modules, run the way npm runs them for a package.
+describe('cli postinstall — inside a monorepo package', () => {
+  let repo;
+  beforeEach(() => {
+    repo = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-cli-postinstall-'));
+    fs.mkdirSync(path.join(repo, '.git'));
+    fs.mkdirSync(path.join(repo, 'packages/app'), {recursive: true});
+    fs.writeFileSync(path.join(repo, 'packages/app/package.json'), '{"name":"app"}');
+    const installed = path.join(repo, 'node_modules/@astryxdesign/cli');
+    for (const rel of ['scripts/postinstall.mjs', 'foundation/agent-docs/agent-doc-state.mjs']) {
+      fs.mkdirSync(path.dirname(path.join(installed, rel)), {recursive: true});
+      fs.copyFileSync(path.join(CLI, rel), path.join(installed, rel));
+    }
+  });
+  afterEach(() => fs.rmSync(repo, {recursive: true, force: true}));
+
+  const install = () =>
+    spawnSync(
+      process.execPath,
+      [path.join(repo, 'node_modules/@astryxdesign/cli/scripts/postinstall.mjs')],
+      {
+        env: {...process.env, INIT_CWD: path.join(repo, 'packages/app'), npm_command: 'install'},
+        encoding: 'utf8',
+      },
+    );
+
+  it('stays quiet when init ran at the repository root', () => {
+    fs.writeFileSync(path.join(repo, 'AGENTS.md'), '<!-- ASTRYX:START -->\n');
+    const r = install();
+    expect(r.status).toBe(0);
+    expect(r.stdout).toBe('');
+  });
+
+  it('still nudges when no folder up to the repository root ran init', () => {
+    const r = install();
+    expect(r.status).toBe(0);
+    expect(r.stdout).toMatch(/finish setup and install the Astryx agent prompt/);
+  });
+});

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

@@ -90,6 +90,7 @@ export const doc = {
       cli: 'astryx component SideNav --package @astryxdesign/core',
     },
   ],
+  outsideProject: 'same',
   exitCodes: [
     {code: 0, when: 'success'},
     {

package/clients/cli/commands/discover.broken-integration.test.mjs

@@ -68,8 +68,8 @@ describe('astryx discover with a manifest that fails to load', () => {
     const {status, stdout, stderr} = await runCli(['discover'], {cwd: project});
 
     expect(status).toBe(0);
-    expect(stderr).toContain(
-      'Warning: @test/broken has 1 integration issue(s). Run: astryx doctor',
+    expect(stderr).toMatch(
+      /Warning: @test\/broken has 1 integration issue\(s\)\. Run: .+ doctor/,
     );
     expect(stdout).not.toContain('No integrations configured.');
     expect(stdout).toContain(
@@ -83,7 +83,11 @@ describe('astryx discover with a manifest that fails to load', () => {
     });
 
     expect(status).toBe(0);
-    expect(JSON.parse(stdout).meta).toEqual({configured: true});
+    const {meta} = JSON.parse(stdout);
+    expect(meta.configured).toBe(true);
+    // The official list still answers; nothing else is claimed.
+    expect(meta.sources.map(s => s.name)).toEqual(['Astryx']);
+    expect(meta.answeredBy).toEqual(expect.any(Object));
     expect(stderr).not.toContain('integration issue');
   });
 });
@@ -129,8 +133,8 @@ describe('astryx discover with a configured package that is not installed', () =
     const {status, stderr} = await runCli(['discover'], {cwd: project});
 
     expect(status).toBe(0);
-    expect(stderr).toContain(
-      'Warning: @test/missing has 1 integration issue(s). Run: astryx doctor\n',
+    expect(stderr).toMatch(
+      /Warning: @test\/missing has 1 integration issue\(s\)\. Run: .+ doctor\n/,
     );
   });
 });
@@ -148,8 +152,8 @@ describe('astryx search with a manifest that fails to load', () => {
     const {status, stderr} = await runCli(['search', 'button'], {cwd: project});
 
     expect(status).toBe(0);
-    expect(stderr).toContain(
-      'Warning: @test/broken has 1 integration issue(s). Run: astryx doctor',
+    expect(stderr).toMatch(
+      /Warning: @test\/broken has 1 integration issue\(s\)\. Run: .+ doctor/,
     );
 
     const asJson = await runCli(['search', 'button', '--json'], {cwd: project});

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

@@ -17,7 +17,8 @@ export const doc = {
   summary:
     'Browse and search integrations: the ones you have and the ones you could add',
   description:
-    'Lists the integrations this project loads and, when it has a discover source, the ones it could add, with what each one adds. ' +
+    'Lists what this project has, the integrations it loads and the official packages it declares, then what it could add: the official Astryx packages first, then whatever its discover sources list, with what each one adds. ' +
+    'Inside a project, integrations installed for the computer, beside the CLI installed for it, are listed as ones the project could add, with its install command; outside one they load. ' +
     'A package query shows one package: what it adds, every version a source knows, and the command that adds it. ' +
     "An @scope/name/Component path prints an installed component's doc; any other item path shows that item. " +
     'Anything else, even an exact component name, searches every item and package and lists the matches. Discover only reads: your package manager installs, updates, and removes packages.',
@@ -78,6 +79,7 @@ export const doc = {
       cli: 'astryx discover dashboard --type template --available',
     },
   ],
+  outsideProject: 'same',
   exitCodes: [
     {code: 0, when: 'success'},
     {
@@ -86,4 +88,10 @@ export const doc = {
     },
   ],
   related: ['component', 'search', 'template'],
+  notes: [
+    {
+      type: 'prose',
+      text: "In global mode: outside a project, integrations installed next to your global install are listed as installed and their items show up; inside a project, only the project's integrations are, and the global ones the project could add are listed under available, with the project's install command. In a project, the project's version of Astryx runs it, whichever astryx command you start. See {@link namespace:global} and {@link generic:computer-integrations}.",
+    },
+  ],
 };