@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.2

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.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,
     );
   }
@@ -397,7 +410,7 @@ function printThemeApp(result) {
   emit(
     text('Wire the generated module once in the app root:'),
     code(
-      "import {Theme} from '@astryxdesign/core';\n" +
+      "import {Theme} from '@astryxdesign/core/theme';\n" +
         `import {themes, defaultThemeSlug} from './${stem}';\n\n` +
         '<Theme theme={themes[defaultThemeSlug]}>\n  <App />\n</Theme>',
     ),

package/clients/cli/commands/build-theme.path-safety.test.mjs

@@ -9,6 +9,12 @@
  *   - Multi-file write is atomic: if one file fails, none are left behind.
  *   - An `--out` escape, or an output directory that cannot be created, fails
  *     with a registered error code.
+ *   - Every output a build writes stays inside the working directory: an
+ *     absolute `--out` path or a theme file outside it fails before anything
+ *     is written, while absolute paths inside it build, also through a
+ *     symlinked spelling. `--check` writes nothing, so it compares those
+ *     outside outputs read-only, and a stale report for them ends with a
+ *     remedy that works: the directory to build and check from.
  *
  * Runs the CLI in-process (shared runCli harness) against a tiny synthetic theme file.
  */
@@ -22,6 +28,7 @@ import {runCli} from '../../../test-utils/run-cli.mjs';
 import {themeBuild} from '../../../api/theme/build/build.mjs';
 import {AstryxError} from '../../../api/error.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
+import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
 
 function writeTheme(dir, name) {
   fs.mkdirSync(dir, {recursive: true});
@@ -59,7 +66,9 @@ describe('theme build path safety', () => {
     );
 
     expect(result.code).not.toBe(0);
-    expect(result.stderr + result.stdout).toMatch(/path separator|invalid theme name/i);
+    expect(result.stderr + result.stdout).toMatch(
+      /path separator|invalid theme name/i,
+    );
 
     // The traversal target must not exist.
     expect(fs.existsSync(path.join(tmpDir, 'escaped.js'))).toBe(false);
@@ -92,7 +101,10 @@ describe('theme build path safety', () => {
 
     const themeFile = writeTheme(themesDir, '../leak');
 
-    await runCli(['theme', 'build', path.relative(project, themeFile)], project);
+    await runCli(
+      ['theme', 'build', path.relative(project, themeFile)],
+      project,
+    );
 
     // Neither the CSS nor any sibling JS should have been written.
     const entries = fs.readdirSync(themesDir).sort();
@@ -114,19 +126,200 @@ describe('theme build output-path failures carry registered codes', () => {
     return {result, envelope: JSON.parse(result.stdout)};
   }
 
-  it('reports an --out path outside the project as ERR_PATH_TRAVERSAL', async () => {
+  it('reports a relative --out path outside the project as ERR_PATH_TRAVERSAL, with --check too', async () => {
     const project = path.join(tmpDir, 'project');
     const themeFile = writeTheme(path.join(project, 'themes'), 'ocean');
 
+    for (const extra of [[], ['--check']]) {
+      const {result, envelope} = await buildJson(
+        [
+          path.relative(project, themeFile),
+          '--out',
+          '../escaped.css',
+          ...extra,
+        ],
+        project,
+      );
+
+      expect(result.code).toBe(1);
+      expect(envelope.code).toBe(ERROR_CODES.ERR_PATH_TRAVERSAL);
+      expect(registered.has(envelope.code)).toBe(true);
+    }
+    expect(fs.existsSync(path.join(tmpDir, 'escaped.css'))).toBe(false);
+  });
+
+  it('reports an absolute --out path outside the project as ERR_PATH_TRAVERSAL', async () => {
+    const project = path.join(tmpDir, 'project');
+    const outside = path.join(tmpDir, 'outside');
+    fs.mkdirSync(outside, {recursive: true});
+    const themeFile = writeTheme(path.join(project, 'themes'), 'ocean');
+    const out = path.join(outside, 'ocean.css');
+
     const {result, envelope} = await buildJson(
-      [path.relative(project, themeFile), '--out', '../escaped.css'],
+      [path.relative(project, themeFile), '--out', out],
       project,
     );
 
     expect(result.code).toBe(1);
     expect(envelope.code).toBe(ERROR_CODES.ERR_PATH_TRAVERSAL);
-    expect(registered.has(envelope.code)).toBe(true);
-    expect(fs.existsSync(path.join(tmpDir, 'escaped.css'))).toBe(false);
+    expect(fs.readdirSync(outside)).toEqual([]);
+  });
+
+  it('checks an absolute --out path outside the project read-only', async () => {
+    const project = path.join(tmpDir, 'project');
+    const outside = path.join(tmpDir, 'outside');
+    fs.mkdirSync(outside, {recursive: true});
+    const themeFile = path.relative(
+      project,
+      writeTheme(path.join(project, 'themes'), 'ocean'),
+    );
+    const out = path.join(outside, 'ocean.css');
+
+    const missing = await buildJson(
+      [themeFile, '--out', out, '--check'],
+      project,
+    );
+    expect(missing.result.code).toBe(1);
+    expect(missing.envelope.type).toBe('theme.build.check');
+    expect(missing.envelope.data.upToDate).toBe(false);
+    expect(fs.readdirSync(outside)).toEqual([]);
+
+    // Outputs built inside the project compare equal once copied outside:
+    // only the volatile Command line, which --check ignores, names --out.
+    const dist = path.join(project, 'dist');
+    const built = await buildJson(
+      [themeFile, '--out', path.join(dist, 'ocean.css')],
+      project,
+    );
+    expect(built.result.code).toBe(0);
+    for (const file of fs.readdirSync(dist)) {
+      fs.copyFileSync(path.join(dist, file), path.join(outside, file));
+    }
+    const copied = fs.readdirSync(outside).sort();
+
+    const current = await buildJson(
+      [themeFile, '--out', out, '--check'],
+      project,
+    );
+    expect(current.result.code).toBe(0);
+    expect(current.envelope.type).toBe('theme.build.check');
+    expect(current.envelope.data.upToDate).toBe(true);
+    expect(fs.readdirSync(outside).sort()).toEqual(copied);
+  });
+
+  it('reports a theme file outside the project as ERR_PATH_TRAVERSAL, because its outputs go beside it; --check only compares them', async () => {
+    const project = path.join(tmpDir, 'project');
+    fs.mkdirSync(project, {recursive: true});
+    const shared = path.join(tmpDir, 'shared');
+    const themeFile = writeTheme(shared, 'ocean');
+
+    for (const file of [themeFile, path.relative(project, themeFile)]) {
+      const {result, envelope} = await buildJson([file], project);
+
+      expect(result.code).toBe(1);
+      expect(envelope.code).toBe(ERROR_CODES.ERR_PATH_TRAVERSAL);
+
+      const checked = await buildJson([file, '--check'], project);
+      expect(checked.result.code).toBe(1);
+      expect(checked.envelope.type).toBe('theme.build.check');
+      expect(checked.envelope.data.upToDate).toBe(false);
+    }
+    expect(fs.readdirSync(shared)).toEqual(['theme.mjs']);
+  });
+
+  /**
+   * Read the remedy that ends a stale report for outputs outside cwd: the
+   * directory to run from, then the build and check arguments after `theme
+   * build`. Each command starts with the install-aware invocation for it.
+   * @param {string} stderr
+   */
+  function readRemedy(stderr) {
+    const lines = stderr.split('\n').map(line => line.trim());
+    const cd = lines.find(line => line.startsWith('cd '));
+    expect(cd).toBeDefined();
+    const dir = /** @type {string} */ (cd).slice('cd '.length);
+    const stem = `${getCliInvocation(dir)} theme build `;
+    const commands = lines.filter(line => line.startsWith(stem));
+    expect(commands).toHaveLength(2);
+    const [build, check] = commands.map(line =>
+      line.slice(stem.length).split(' '),
+    );
+    expect(check).toEqual([...build, '--check']);
+    return {dir, build, check};
+  }
+
+  it('ends a stale report for outputs outside cwd with a remedy that works, and keeps the report for outputs inside it', async () => {
+    const project = path.join(tmpDir, 'project');
+    const inside = path.relative(
+      project,
+      writeTheme(path.join(project, 'themes'), 'ocean'),
+    );
+    const shared = writeTheme(path.join(tmpDir, 'shared'), 'ocean');
+    const outside = path.join(tmpDir, 'outside');
+
+    for (const args of [
+      [path.relative(project, shared)],
+      [inside, '--out', path.join(outside, 'ocean.css')],
+    ]) {
+      const stale = await runCli(
+        ['theme', 'build', ...args, '--check'],
+        project,
+      );
+      expect(stale.code).toBe(1);
+      // The old remedy ran the build from cwd, which refuses these outputs.
+      expect(stale.stderr).not.toContain('Rebuild with:');
+      expect(stale.stderr).not.toContain(`theme build ${args.join(' ')}`);
+
+      // Following the remedy builds, and the check from there passes.
+      const remedy = readRemedy(stale.stderr);
+      const built = await runCli(
+        ['theme', 'build', ...remedy.build],
+        remedy.dir,
+      );
+      expect(built.code).toBe(0);
+      const checked = await runCli(
+        ['--json', 'theme', 'build', ...remedy.check],
+        remedy.dir,
+      );
+      expect(checked.code).toBe(0);
+      expect(JSON.parse(checked.stdout).data.upToDate).toBe(true);
+    }
+
+    // Outputs inside cwd keep the plain rebuild line.
+    const local = await runCli(['theme', 'build', inside, '--check'], project);
+    expect(local.code).toBe(1);
+    expect(local.stderr).toContain(
+      `Rebuild with: astryx theme build ${inside}`,
+    );
+    expect(local.stderr).not.toMatch(/^\s*cd /m);
+  });
+
+  it('builds absolute paths inside the project, also when they reach it through a symlink', async () => {
+    const project = path.join(tmpDir, 'project');
+    const themeFile = writeTheme(path.join(project, 'themes'), 'ocean');
+    const alias = path.join(tmpDir, 'alias');
+    fs.symlinkSync(project, alias, 'dir');
+
+    for (const [args, written] of [
+      [
+        [themeFile, '--out', path.join(project, 'dist', 'direct.css')],
+        path.join(project, 'dist', 'direct.css'),
+      ],
+      [
+        [themeFile, '--out', path.join(alias, 'dist', 'aliased.css')],
+        path.join(project, 'dist', 'aliased.css'),
+      ],
+      [
+        [path.join(alias, 'themes', 'theme.mjs')],
+        path.join(project, 'themes', 'ocean.css'),
+      ],
+    ]) {
+      const {result, envelope} = await buildJson(args, project);
+
+      expect(result.code).toBe(0);
+      expect(envelope.type).toBe('theme.build');
+      expect(fs.existsSync(written)).toBe(true);
+    }
   });
 
   it('reports an --out path that escapes through a symlink as ERR_PATH_TRAVERSAL', async () => {
@@ -177,4 +370,29 @@ describe('theme build output-path failures carry registered codes', () => {
       code: ERROR_CODES.ERR_PATH_TRAVERSAL,
     });
   });
+
+  it('themeBuild() rejects an output outside cwd, an absolute out path or the default beside a theme file outside cwd, and checks it read-only', async () => {
+    const project = path.join(tmpDir, 'project');
+    const inside = writeTheme(path.join(project, 'themes'), 'ocean');
+    const shared = path.join(tmpDir, 'shared');
+    const outsideTheme = writeTheme(shared, 'ocean');
+    const outDir = path.join(tmpDir, 'out');
+
+    for (const [file, options] of [
+      [path.relative(project, inside), {out: path.join(outDir, 'ocean.css')}],
+      [outsideTheme, {}],
+    ]) {
+      await expect(
+        themeBuild(file, options, {cwd: project}),
+      ).rejects.toMatchObject({code: ERROR_CODES.ERR_PATH_TRAVERSAL});
+      await expect(
+        themeBuild(file, {...options, check: true}, {cwd: project}),
+      ).resolves.toMatchObject({
+        type: 'theme.build.check',
+        data: {upToDate: false},
+      });
+    }
+    expect(fs.existsSync(outDir)).toBe(false);
+    expect(fs.readdirSync(shared)).toEqual(['theme.mjs']);
+  });
 });

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

@@ -126,7 +126,10 @@ describe('theme build emits a live TextInput selector (#4109)', () => {
         `};\n`,
     );
 
-    const result = await runCli(['theme', 'build', themeFile, '-o', outFile]);
+    const result = await runCli(
+      ['theme', 'build', themeFile, '-o', outFile],
+      tmpDir,
+    );
     const css = fs.readFileSync(outFile, 'utf8');
 
     expect(result.status).toBe(0);
@@ -148,7 +151,7 @@ describe('theme build emits a live TextInput selector (#4109)', () => {
         `};\n`,
     );
 
-    await runCli(['theme', 'build', themeFile, '-o', outFile]);
+    await runCli(['theme', 'build', themeFile, '-o', outFile], tmpDir);
     const css = fs.readFileSync(outFile, 'utf8');
 
     expect(css).toContain('.astryx-text-input');

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}.",
+    },
+  ],
 };