@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.2

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

@@ -18,8 +18,11 @@ export const doc = {
     'Runs read-only project health diagnostics by default: Node version, @astryxdesign/core ' +
     'install and version alignment, theme packages, generated app themes when present, earlier copied-theme migration, config, integrations (every one astryx.config names must load, linked without a config entry, ' +
     'provider identity, contribution issues), agent docs, core peer dependencies, package manager, ' +
-    "and the docs the CLI reads. It writes nothing, but loading astryx.config runs that file's code. " +
-    'The `integration` subcommands provide authoring checks for one integration package.',
+    "the docs the CLI reads, the newest release the computer knows of, with the install and upgrade commands when the project's release is older, and every `astryx` command on the search path, warning when the first one is not the Astryx CLI or predates the hand-off. It writes nothing, but loading astryx.config runs that file's code. " +
+    'The `integration` subcommands provide authoring checks for one integration package. ' +
+    'Outside a project it checks the computer instead: the Node version, the release that answered, ' +
+    'the newest release this computer knows of, with the command that upgrades the CLI installed for the computer when it is older, the astryx commands on the search path, the integrations installed for the computer (warning about one it skips), and whether the computer-level agent text (`astryx init --user`) is present, matches this release, was edited, or is turned off (info only). ' +
+    'It never fails a check because the folder has no project.',
   fn: 'doctor',
   subcommands: ['integration'],
   examples: [
@@ -42,9 +45,16 @@ export const doc = {
       cli: 'astryx doctor integration docs @acme/widgets',
     },
   ],
+  outsideProject: 'own',
   exitCodes: [
     {code: 0, when: 'no checks failed (warnings are allowed)'},
     {code: 1, when: 'one or more checks failed'},
   ],
   related: ['init', 'upgrade'],
+  notes: [
+    {
+      type: 'prose',
+      text: "In global mode: outside a project, doctor checks your computer instead of a folder: `node-version`, `answering-release` (the version that answered), `newest-release`, `cli-on-path` (every astryx command on your PATH), `computer-integrations` (integrations installed globally), and `computer-agent-text` (the agent guide). It never fails a check because the folder has no project. In a project, the project's version of Astryx runs it, whichever astryx command you start. See {@link namespace:global} and {@link generic:who-answers}.",
+    },
+  ],
 };

package/clients/cli/commands/doctor.mjs

@@ -38,6 +38,8 @@ import {doc as integrationDocConflictsFn} from '../../../api/integration/integra
 import {NO_RESULT_SET} from '../../../foundation/debug/index.mjs';
 import {cliError} from '../lib/cli-error.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
+import {formatCliCommand} from '../../../foundation/env/package-manager.mjs';
+import {isOutsideProject} from '../../../foundation/env/project-scope.mjs';
 
 const STATUS = {
   pass: '[ok]',
@@ -92,12 +94,91 @@ function issueBlocks(issues) {
   return [
     section('Integration issues'),
     records(issues, {
-      fields: ['severity', 'code', 'message'],
+      fields: ['severity', 'code', 'message', 'fix', 'file', 'line'],
       format: {severity: statusToken},
     }),
   ];
 }
 
+/**
+ * The docs checked against the authoring types: a visible line when it was
+ * skipped, the findings (all warnings), the files it could not check, or an
+ * [ok] (never after a failed check).
+ * @param {import('../../../api/integration/validate-integration.type.mjs').DocTypesReport | undefined} report
+ * @param {boolean} failed
+ */
+function docTypesBlocks(report, failed) {
+  if (!report) return [];
+  if (
+    report.status === 'checked' &&
+    report.docs === 0 &&
+    report.findings.length === 0 &&
+    report.unchecked.length === 0
+  ) {
+    return [
+      text('[info] No doc files to type-check.'),
+      ...(report.fixtures
+        ? [text(`[info] ${report.fixtures} test fixture doc(s) not checked.`)]
+        : []),
+    ];
+  }
+  if (report.status === 'skipped') {
+    return [text(`[skip] Docs not type-checked: ${report.reason}`)];
+  }
+  const blocks = [
+    section(
+      `Checking ${report.docs} doc(s) against the authoring types${report.typescript ? ` (TypeScript ${report.typescript})` : ''}`,
+    ),
+  ];
+  if (report.findings.length > 0) {
+    const files = new Set(report.findings.map(f => f.doc)).size;
+    blocks.push(
+      records(report.findings, {
+        fields: [
+          'severity',
+          'doc',
+          'line',
+          'export',
+          'type',
+          'field',
+          'problem',
+          'message',
+          'fix',
+        ],
+        format: {severity: statusToken},
+      }),
+      text(
+        `${report.findings.length} doc field(s) in ${files} file(s) do not match the authoring types. ` +
+          'These are warnings; `astryx docs authoring` lists every field.',
+      ),
+    );
+  }
+  if (report.unchecked.length > 0) {
+    blocks.push(
+      text(`[info] Not type-checked: ${report.unchecked.length} doc file(s):`),
+      records(report.unchecked, {fields: ['doc', 'reason']}),
+    );
+  }
+  if (report.fixtures) {
+    blocks.push(
+      text(`[info] ${report.fixtures} test fixture doc(s) not checked.`),
+    );
+  }
+  if (report.findings.length === 0 && report.docs > 0) {
+    // After a failed check an [ok] reads as a pass, but the result still shows.
+    blocks.push(
+      text(
+        failed
+          ? `[info] No doc field differs from its authoring type (${report.docs} checked).`
+          : report.unchecked.length > 0
+            ? `[ok] Every doc that was checked matches its authoring type (${report.docs} checked).`
+            : `[ok] Every doc matches its authoring type (${report.docs} checked).`,
+      ),
+    );
+  }
+  return blocks;
+}
+
 /**
  * @param {import('../../../api/integration/validate-integration.type.mjs').ValidateIntegrationResponse['data']} data
  */
@@ -110,15 +191,19 @@ function printIntegrationValidation(data) {
     ...(data.issues.length > 0
       ? [
           records(data.issues, {
-            fields: ['severity', 'code', 'message'],
+            fields: ['severity', 'code', 'message', 'fix', 'file', 'line'],
             format: {severity: statusToken},
           }),
         ]
       : [text('[ok] No integration issues found.')]),
+    ...(data.notes ?? []).map(note =>
+      text(`note (${note.code}): ${note.message}`),
+    ),
     text(
       `Summary: ${errors} error${errors === 1 ? '' : 's'}, ` +
         `${warnings} warning${warnings === 1 ? '' : 's'}`,
     ),
+    ...docTypesBlocks(data.docTypes, errors > 0),
   );
 }
 
@@ -173,6 +258,101 @@ function printTemplateConflicts(data) {
   emit(...output);
 }
 
+/**
+ * The documented-props comparison, with every field its JSON carries: a
+ * visible line when it was skipped, the findings (all warnings), the
+ * components it could not read, and how many were compared with which
+ * TypeScript, as an [ok] when nothing differs (never after a failed check).
+ * Then how many documented prop types were judged and which were not.
+ * @param {import('../../../api/integration/authoring-checks.type.mjs').PropDriftReport | undefined} report
+ * @param {boolean} failed
+ */
+function propDriftBlocks(report, failed) {
+  if (!report) return [];
+  if (report.status === 'skipped') {
+    return [text(`[skip] Props not compared: ${report.reason}`)];
+  }
+  const blocks = [];
+  if (report.findings.length > 0) {
+    // Two docs of one name are two components.
+    const components = new Set(
+      report.findings.map(f => `${f.doc}\0${f.component}`),
+    ).size;
+    blocks.push(
+      records(report.findings, {
+        fields: [
+          'severity',
+          'component',
+          'prop',
+          'kind',
+          'message',
+          'doc',
+          'source',
+          'docType',
+          'codeType',
+          'docRequired',
+          'codeRequired',
+          'docDefault',
+          'codeDefault',
+          'fix',
+        ],
+        format: {severity: statusToken},
+      }),
+      text(
+        `${report.findings.length} prop(s) differ between the docs and the code in ${components} of ${report.components} component(s) compared (TypeScript ${report.typescript}). ` +
+          'These are warnings: update the doc, or the code if the doc is right.',
+      ),
+    );
+  }
+  if (report.unchecked.length > 0) {
+    blocks.push(
+      text(
+        `[info] Props not compared for ${report.unchecked.length} documented component(s):`,
+      ),
+      records(report.unchecked, {fields: ['component', 'doc', 'reason']}),
+    );
+  }
+  const notChecked = report.propsNotChecked ?? [];
+  if (notChecked.length > 0) {
+    blocks.push(
+      text(
+        `[info] Props not checked for a doc entry in ${notChecked.length} component(s):`,
+      ),
+      records(notChecked, {fields: ['component', 'doc', 'reason', 'props']}),
+    );
+  }
+  if (report.findings.length === 0) {
+    const apart =
+      notChecked.length > 0 ? ', apart from the props not checked' : '';
+    blocks.push(
+      text(
+        !failed && report.components > 0
+          ? `[ok] Documented prop names and required flags match the code in ${report.components} component(s)${apart} (TypeScript ${report.typescript}).`
+          : `[info] Props compared in ${report.components} component(s) (TypeScript ${report.typescript}).`,
+      ),
+    );
+  }
+  if (report.typesSkipped) {
+    blocks.push(text(`[skip] Prop types not judged: ${report.typesSkipped}.`));
+    return blocks;
+  }
+  const notCompared = report.typesNotCompared.flatMap(entry => entry.props);
+  blocks.push(
+    text(
+      `[info] Documented prop types judged: ${report.typesCompared}; not compared: ${notCompared.length}. ` +
+        'A type is judged when the doc writes it the same as the source (exactly, if it contains `readonly`), or when both are primitives, literals, arrays and unions of those, or names for them.',
+    ),
+  );
+  if (notCompared.length > 0) {
+    blocks.push(
+      records(report.typesNotCompared, {
+        fields: ['component', 'doc', 'reason', 'props'],
+      }),
+    );
+  }
+  return blocks;
+}
+
 /**
  * @param {import('../../../api/integration/authoring-checks.type.mjs').IntegrationComponentConflictResponse['data']} data
  */
@@ -186,7 +366,8 @@ function printComponentConflicts(data) {
   // An [ok] after a failed check reads as a pass: say nothing it could not check.
   const failed = data.issues.some(issue => issue.severity === 'error');
   if (data.conflicts.length === 0) {
-    if (!failed) output.push(text('[ok] No component names conflict with Core.'));
+    if (!failed)
+      output.push(text('[ok] No component names conflict with Core.'));
   } else {
     output.push(
       records(data.conflicts, {
@@ -205,6 +386,7 @@ function printComponentConflicts(data) {
       ),
     );
   }
+  output.push(...propDriftBlocks(data.propDrift, failed));
   emit(...output);
 }
 
@@ -216,7 +398,16 @@ function printDocConflicts(data) {
     section(
       `Checking integration docs: ${integrationLabel(data) ?? '(local package)'}`,
     ),
-    ...issueBlocks(data.issues),
+    // A copied passage or fluff is listed below with its detail, so its
+    // issue is not printed twice.
+    ...issueBlocks(
+      data.issues.filter(
+        issue =>
+          issue.code !== 'copied_passage' &&
+          issue.code !== 'doc_fluff' &&
+          issue.code !== 'stray_doc_pointer',
+      ),
+    ),
   ];
   if (
     !data.issues.some(
@@ -239,9 +430,99 @@ function printDocConflicts(data) {
       }),
     );
   }
+  const copied = data.copiedPassages ?? [];
+  if (copied.length === 0) {
+    if (!data.issues.some(issue => issue.severity === 'error')) {
+      output.push(text('[ok] No topic copies a passage from another.'));
+    }
+  } else {
+    output.push(
+      text(
+        `[warn] ${copied.length} copied passage(s) (copied_passage): two topics say the same thing word for word. Keep the text in one and link to it from the other.`,
+      ),
+      records(copied, {
+        fields: [
+          'topic',
+          'section',
+          'line',
+          'otherTopic',
+          'otherOwner',
+          'owner',
+          'text',
+          'words',
+          'passages',
+          'message',
+        ],
+      }),
+    );
+  }
+  const fluff = data.fluff ?? [];
+  if (fluff.length === 0) {
+    if (!data.issues.some(issue => issue.severity === 'error')) {
+      output.push(text('[ok] No filler phrases or low-density topics.'));
+    }
+  } else {
+    output.push(
+      text(
+        `[warn] ${fluff.length} fluff finding(s) (doc_fluff): words that add length, not meaning. Cut each one.`,
+      ),
+      records(fluff, {
+        fields: [
+          'topic',
+          'kind',
+          'phrase',
+          'section',
+          'file',
+          'line',
+          'density',
+          'message',
+        ],
+      }),
+    );
+  }
+  const stray = data.strayPointers ?? [];
+  if (stray.length === 0) {
+    if (!data.issues.some(issue => issue.severity === 'error')) {
+      output.push(text('[ok] Every pointer to a doc is a link.'));
+    }
+  } else {
+    output.push(
+      text(
+        `[warn] ${stray.length} stray doc pointer(s) (stray_doc_pointer): a written \`astryx docs <name>\` where a link would be checked. Replace each with the link shown.`,
+      ),
+      records(stray, {
+        fields: [
+          'topic',
+          'section',
+          'file',
+          'line',
+          'pointer',
+          'link',
+          'message',
+        ],
+      }),
+    );
+  }
   emit(...output);
 }
 
+/**
+ * Print one `doctor integration` check's result as its own subcommand prints
+ * it. `astryx integration check` prints each check it runs through this.
+ * @param {import('../../../api/integration/integration-check.type.mjs').IntegrationCheckResponse} response
+ */
+export function printIntegrationCheckResponse(response) {
+  if (response.type === 'integration.validate') {
+    printIntegrationValidation(response.data);
+  } else if (response.type === 'integration.component-conflicts') {
+    printComponentConflicts(response.data);
+  } else if (response.type === 'integration.template-conflicts') {
+    printTemplateConflicts(response.data);
+  } else {
+    printDocConflicts(response.data);
+  }
+}
+
 /** @param {import('commander').Command} program */
 async function runProjectDoctor(program) {
   const report = await runChecks();
@@ -265,7 +546,7 @@ async function runIntegrationValidation(program, pkg) {
         noPackage
           ? 'Nothing was validated: no package.json found. Run this command inside a package directory.'
           : 'Nothing was validated: no astryx.integration.* found next to package.json. ' +
-            'To validate an installed integration: astryx doctor integration validate <package>',
+              `To validate an installed integration: ${formatCliCommand('doctor integration validate <package>')}`,
       ),
     );
   } else printIntegrationValidation(result.data);
@@ -288,10 +569,14 @@ async function runAuthoringCheck(program, pkg, kind) {
 
   if (program.opts().json) jsonOut(result);
   else if (!result.data.validated) {
+    // Outside a project no integration is installed to check by name
+    // (spec AST-081 FR3).
     emit(
       text(
-        'Nothing was checked: no astryx.integration.* found next to package.json. ' +
-          `To check an installed integration: astryx doctor integration ${kind} <package>`,
+        isOutsideProject()
+          ? 'Nothing was checked: no astryx.integration.* found next to package.json, and this folder is outside a project.'
+          : 'Nothing was checked: no astryx.integration.* found next to package.json. ' +
+              `To check an installed integration: ${formatCliCommand(`doctor integration ${kind} <package>`)}`,
       ),
     );
   } else if (kind === 'templates') {

package/clients/cli/commands/doctor.test.mjs

@@ -20,6 +20,7 @@ import {
   checkPackageManager,
 } from '../../../api/doctor/doctor.mjs';
 import {MIN_NODE_VERSION} from '../../../foundation/env/node-version.mjs';
+import {CLI_VERSION, linkThisCliAsProjectCli} from '../../../test-utils/release-fixtures.mjs';
 
 let tmpDir;
 let logCalls;
@@ -101,7 +102,7 @@ describe('doctor — individual checks', () => {
   });
 
   it('app themes: reports unmanaged state as one INFO check', async () => {
-    fs.writeFileSync(path.join(tmpDir, 'package.json'), '{"name":"app"}\n');
+    fs.writeFileSync(path.join(tmpDir, 'package.json'), '{"name":"app","dependencies":{"@astryxdesign/core":"*"}}\n');
     const result = await runChecks({cwd: tmpDir});
     const themeChecks = result.checks.filter(check =>
       check.id.startsWith('theme-'),
@@ -176,13 +177,16 @@ describe('doctor — individual checks', () => {
   it('agent-docs: the fix names the scoped package when the project has no local CLI', () => {
     fs.writeFileSync(path.join(tmpDir, 'package-lock.json'), '{}');
     const res = checkAgentDocs({cwd: tmpDir});
-    expect(res.fix).toContain('`npx @astryxdesign/cli init --features agents`');
+    expect(res.fix).toContain(
+      `\`npx @astryxdesign/cli@${CLI_VERSION} init --features agents\``,
+    );
   });
 
   it('agent-docs: the fix keeps `npx astryx` when the project has a local CLI', () => {
     fs.writeFileSync(path.join(tmpDir, 'package-lock.json'), '{}');
     fs.mkdirSync(path.join(tmpDir, 'node_modules', '.bin'), {recursive: true});
     fs.writeFileSync(path.join(tmpDir, 'node_modules', '.bin', 'astryx'), '');
+    linkThisCliAsProjectCli(tmpDir);
     const res = checkAgentDocs({cwd: tmpDir});
     expect(res.fix).toContain('`npx astryx init --features agents`');
   });
@@ -301,7 +305,8 @@ describe('doctor — runChecks / report', () => {
     expect(total).toBe(report.checks.length);
   });
 
-  it('reports a FAIL for core when run in a bare directory', async () => {
+  it('reports a FAIL for core in a project that declares Core but installs none', async () => {
+    fs.writeFileSync(path.join(tmpDir, 'package.json'), '{"name":"app","dependencies":{"@astryxdesign/core":"*"}}\n');
     const report = await runChecks({cwd: tmpDir});
     expect(find(report.checks, 'core-installed').status).toBe('fail');
     expect(report.summary.fail).toBeGreaterThan(0);
@@ -346,7 +351,8 @@ describe('doctor — command', () => {
     process.exitCode = prevExit;
   });
 
-  it('sets exit code 1 when a check FAILs (bare dir, no @astryxdesign/core)', async () => {
+  it('sets exit code 1 when a check FAILs (Core declared, not installed)', async () => {
+    fs.writeFileSync(path.join(tmpDir, 'package.json'), '{"name":"app","dependencies":{"@astryxdesign/core":"*"}}\n');
     const prevCwd = process.cwd();
     const prevExit = process.exitCode;
     process.exitCode = undefined;

package/clients/cli/commands/gap-report.doc.mjs

@@ -16,6 +16,8 @@ export const doc = {
     'Reports a missing component, variant, layout, styling, accessibility, API, or documentation capability to the package that owns it: the --package you name, else the integration whose component replaces it, else the one package that provides the component, else Core. ' +
     'Every configured handler receives the report: the project config handler first, then each integration handler in config order. Public handlers run only with --confirm-public; internal handlers always run. A failing handler does not stop the others. ' +
     "With no handler it files a GitHub issue for the owning package, only with --confirm-public (without it nothing is sent), or returns the package's issues URL when that is not on GitHub. " +
+    "With --to <package>, the report goes only to that integration's issues URL instead, under the same --confirm-public rule. " +
+    'When loaded integrations name their own issues URLs, the output lists every destination: an agent asks the person where to file and passes their choice with --to; it never picks a package itself, and without a choice the default is used. ' +
     'The report records whether an agent or a person ran it.',
   fn: 'gapReport',
   args: [
@@ -55,13 +57,19 @@ export const doc = {
       flag: '--confirm-public',
       param: 'options.confirmPublic',
       description:
-        'Allow public delivery: public handlers run, and with no handler it files a GitHub issue with your gh login',
+        'Allow public delivery: public handlers run, and a GitHub issues URL gets an issue filed with your gh login',
+    },
+    {
+      flag: '--to <package>',
+      param: 'options.to',
+      description:
+        "Send the report only to this loaded integration's issues URL, as the person chose; the destinations the output lists are the choices",
     },
     {
       flag: '--list-categories',
       param: 'options.listCategories',
       description:
-        'List valid report categories without filing; the component and the other gap-report options are refused with ERR_INVALID_ARGUMENT',
+        'List valid report categories, and the destinations when there is more than one, without filing; the component and the other gap-report options are refused with ERR_INVALID_ARGUMENT',
     },
   ],
   examples: [
@@ -70,7 +78,12 @@ export const doc = {
       label: 'Prepare a report (nothing public happens without --confirm-public)',
       cli: "astryx gap-report Button --category missing_variant --reason 'Need a compact size'",
     },
+    {
+      label: 'File where the person chose',
+      cli: "astryx gap-report Button --category missing_variant --reason 'Need a compact size' --to @acme/widgets",
+    },
   ],
+  outsideProject: 'same',
   exitCodes: [
     {
       code: 0,

package/clients/cli/commands/gap-report.mjs

@@ -7,7 +7,7 @@
 import {gapReport as gapReportApi} from '../../../api/gap-report/gap-report.mjs';
 import {NO_RESULT_SET, resultSet} from '../../../foundation/debug/index.mjs';
 import {jsonOut} from '../../../foundation/response/json.mjs';
-import {emit, record, records, section} from '../formatters/index.mjs';
+import {emit, record, records, section, text} from '../formatters/index.mjs';
 import {cliError} from '../lib/cli-error.mjs';
 import {defineCommand} from '../lib/define-command.mjs';
 import {doc as gapReportCommand} from './gap-report.doc.mjs';
@@ -19,7 +19,7 @@ export function registerGapReport(program) {
     fn: gapReportFn,
     action: async (
       /** @type {string|undefined} */ component,
-      /** @type {{category?: string, reason?: string, additionalContext?: string, package?: string, confirmPublic?: boolean, listCategories?: boolean}} */ options,
+      /** @type {{category?: string, reason?: string, additionalContext?: string, package?: string, confirmPublic?: boolean, listCategories?: boolean, to?: string}} */ options,
     ) => {
       /** @type {Awaited<ReturnType<typeof gapReportApi>>} */
       let result;
@@ -35,6 +35,7 @@ export function registerGapReport(program) {
           package: options.package,
           confirmPublic: options.confirmPublic,
           listCategories: options.listCategories,
+          to: options.to,
         });
       } catch (error) {
         const err =
@@ -78,6 +79,9 @@ export function registerGapReport(program) {
           section('Gap report categories'),
           records(result.data, {fields: ['value', 'label']}),
         );
+        if (result.meta) {
+          emit(...destinationBlocks(result.meta.destinations, result.meta.ask));
+        }
         return answered;
       }
 
@@ -119,8 +123,26 @@ export function registerGapReport(program) {
         );
       }
 
+      if (result.data.destinations && result.data.ask) {
+        emit(...destinationBlocks(result.data.destinations, result.data.ask));
+      }
+
       if (isFailure) process.exitCode = 1;
       return answered;
     },
   });
 }
+
+/**
+ * The destinations a report can go to, then the line telling an agent to ask
+ * the person (architecture:cli-surface INV36).
+ * @param {import('../../../api/gap-report/gap-report.type.mjs').GapReportDestination[]} destinations
+ * @param {string} ask
+ */
+function destinationBlocks(destinations, ask) {
+  return [
+    section('Destinations'),
+    records(destinations, {fields: ['to', 'default', 'issuesUrl']}),
+    text(ask),
+  ];
+}

package/clients/cli/commands/gap-report.test.mjs

@@ -331,3 +331,82 @@ describe('gap-report control docs', () => {
     ).rejects.toMatchObject({code: 'ERR_INVALID_ARGUMENT'});
   });
 });
+
+describe('gap-report destinations in text', () => {
+  it('lists the destinations and tells the agent to ask the person', async () => {
+    const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-gap-dest-'));
+    try {
+      fs.writeFileSync(
+        path.join(cwd, 'package.json'),
+        JSON.stringify({name: 'fixture-app'}),
+      );
+      const pkg = path.join(cwd, 'node_modules', '@test', 'widgets');
+      fs.mkdirSync(pkg, {recursive: true});
+      fs.writeFileSync(
+        path.join(pkg, 'package.json'),
+        JSON.stringify({name: '@test/widgets', version: '1.0.0'}),
+      );
+      fs.writeFileSync(
+        path.join(pkg, 'astryx.integration.mjs'),
+        "export default {issuesUrl: 'https://tracker.example/widgets'};\n",
+      );
+      fs.writeFileSync(
+        path.join(cwd, 'astryx.config.mjs'),
+        `export default {
+  integrations: ['@test/widgets'],
+  gapReport: {audience: 'internal', handle: () => ({status: 'filed', message: 'shared'})},
+};\n`,
+      );
+
+      const listed = await runCli(['gap-report', '--list-categories'], {cwd});
+      expect(listed.status).toBe(0);
+      expect(listed.stdout).toContain('Destinations');
+      expect(listed.stdout).toMatch(/^default:\s+true$/m);
+      expect(listed.stdout).toMatch(/^to:\s+@test\/widgets$/m);
+      expect(listed.stdout).toMatch(
+        /^issuesUrl:\s+https:\/\/tracker\.example\/widgets$/m,
+      );
+      expect(listed.stdout).toMatch(/ask the person/i);
+
+      const filed = await runCli(
+        [
+          'gap-report',
+          'Button',
+          '--category',
+          'docs_gap',
+          '--reason',
+          'Need a keyboard example',
+        ],
+        {cwd},
+      );
+      expect(filed.status).toBe(0);
+      expect(filed.stdout).toContain('Destinations');
+      expect(filed.stdout).toMatch(/ask the person/i);
+
+      const chosen = await runCli(
+        [
+          'gap-report',
+          'Button',
+          '--category',
+          'docs_gap',
+          '--reason',
+          'Need a keyboard example',
+          '--to',
+          '@test/widgets',
+          '--json',
+        ],
+        {cwd},
+      );
+      expect(chosen.status).toBe(0);
+      expect(JSON.parse(chosen.stdout).data.deliveries).toEqual([
+        expect.objectContaining({
+          handler: 'issuesUrl',
+          status: 'routed_only',
+          url: 'https://tracker.example/widgets',
+        }),
+      ]);
+    } finally {
+      fs.rmSync(cwd, {recursive: true, force: true});
+    }
+  });
+});

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

@@ -40,6 +40,7 @@ export const doc = {
     {label: 'Browse the catalog', cli: 'astryx hook --list'},
     {label: 'One hook as JSON', cli: 'astryx hook useFocusTrap --json'},
   ],
+  outsideProject: 'same',
   exitCodes: [
     {code: 0, when: 'success'},
     {

package/clients/cli/commands/init.behavior.test.mjs

@@ -39,6 +39,11 @@ const exists = rel => fs.existsSync(path.join(tmpDir, rel));
 
 describe('astryx init — default (no flags)', () => {
   it('installs the tool-agnostic AGENTS.md cheat sheet and prints next steps', async () => {
+    // Inside a project; outside one the steps are left out (outside-project.test.mjs).
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      '{"name":"app","dependencies":{"@astryxdesign/core":"*"}}',
+    );
     const {status, stdout} = await runCli(['init'], {cwd: tmpDir});
     expect(status).toBe(0);
     expect(exists('AGENTS.md')).toBe(true);