@astryxdesign/cli 0.7.2 → 0.7.3-canary.0bf23bd

package/api/init/init.test.mjs

@@ -10,6 +10,7 @@
 
 import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 import {init, getNextSteps} from './init.mjs';
 import {logger} from '../logger.mjs';
@@ -21,7 +22,8 @@ const MARKER_START = '<!-- ASTRYX:START -->';
 let tmpDir;
 
 beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-init-api-'));
+  // Outside any package: init writes agent docs at the nearest package.json.
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-init-api-'));
 });
 
 afterEach(() => {
@@ -30,6 +32,18 @@ afterEach(() => {
 
 /** @param {string} rel */
 const read = rel => fs.readFileSync(path.join(tmpDir, rel), 'utf8');
+
+/**
+ * Make tmpDir a project that declares Astryx: a folder that declares nothing
+ * is outside a project, where init prints no getting-started steps (spec
+ * AST-081 FR3).
+ */
+function asProject() {
+  fs.writeFileSync(
+    path.join(tmpDir, 'package.json'),
+    JSON.stringify({name: 'app', dependencies: {'@astryxdesign/core': '*'}}),
+  );
+}
 /** @param {string} rel */
 const exists = rel => fs.existsSync(path.join(tmpDir, rel));
 
@@ -58,6 +72,7 @@ function writeIntegration() {
 
 describe('init() — receipts + side effects', () => {
   it('default mode installs AGENTS.md and returns an init.run receipt', async () => {
+    asProject();
     const res = await init({}, {cwd: tmpDir});
     expect(res.type).toBe('init.run');
     if (res.type !== 'init.run') return;
@@ -217,6 +232,7 @@ describe('init() — logger', () => {
   });
 
   it('emits the install line + full next-steps through the shared logger', async () => {
+    asProject();
     /** @type {string[]} */
     const lines = [];
     const logSpy = vi.spyOn(console, 'log').mockImplementation((...a) => lines.push(a.join(' ')));
@@ -243,7 +259,7 @@ describe('init() — ASCII output', () => {
     const lines = [];
     const logSpy = vi.spyOn(console, 'log').mockImplementation((...a) => lines.push(a.join(' ')));
     const errSpy = vi.spyOn(console, 'error').mockImplementation((...a) => lines.push(a.join(' ')));
-    const empty = fs.mkdtempSync(path.join(process.cwd(), '.astryx-init-remove-'));
+    const empty = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-init-remove-'));
     logger.setSilent(false);
     try {
       await init({}, {cwd: tmpDir});

package/api/init/init.type.d.mts

@@ -11,11 +11,11 @@ export type InitRunData = {
      */
     features: string[];
     /**
-     * Agent-doc files written (empty if agents weren't run or install failed).
+     * Agent-doc files written, relative to the directory init ran in (empty if agents weren't run or install failed). Without --agent-docs-path they sit at the project root: the nearest folder at or above it whose package.json declares an Astryx package, else the nearest with any package.json, within its repository and never the home folder; with none, the directory init ran in.
      */
     docsWritten: string[];
     /**
-     * Soft agent-docs failure, if any. `path-safety` also implies a non-zero exit.
+     * Soft agent-docs failure, if any. `path-safety` also implies a non-zero exit. `install-failed` carries a message when init wrote no agent docs (the home folder, or a settings folder in it outside a project) or skipped a file that resolves outside the project; docsWritten then lists what was written.
      */
     docsError: {
         kind: "path-safety" | "install-failed";
@@ -113,7 +113,7 @@ export type InitOptions = {
      */
     all?: boolean | undefined;
     /**
-     * Remove the managed agent-docs block instead of installing; with `user`, remove the computer-level agent text.
+     * Remove the managed agent-docs block, at the project root and in the folder init runs in, instead of installing; with `user`, remove the computer-level agent text.
      */
     removeAgents?: boolean | undefined;
     /**

package/api/init/init.type.mjs

@@ -10,8 +10,8 @@
  * @typedef {object} InitRunData
  * @property {'default' | 'features'} mode `default` (no flags) or `features` (--features/--all).
  * @property {string[]} features Features that were run, in order.
- * @property {string[]} docsWritten Agent-doc files written (empty if agents weren't run or install failed).
- * @property {{kind: 'path-safety' | 'install-failed', message?: string} | null} docsError Soft agent-docs failure, if any. `path-safety` also implies a non-zero exit.
+ * @property {string[]} docsWritten Agent-doc files written, relative to the directory init ran in (empty if agents weren't run or install failed). Without --agent-docs-path they sit at the project root: the nearest folder at or above it whose package.json declares an Astryx package, else the nearest with any package.json, within its repository and never the home folder; with none, the directory init ran in.
+ * @property {{kind: 'path-safety' | 'install-failed', message?: string} | null} docsError Soft agent-docs failure, if any. `path-safety` also implies a non-zero exit. `install-failed` carries a message when init wrote no agent docs (the home folder, or a settings folder in it outside a project) or skipped a file that resolves outside the project; docsWritten then lists what was written.
  * @property {boolean} theme Whether the theme feature ran.
  * @property {'created' | 'skipped' | 'failed' | null} themeTemplate Outcome of writing the annotated theme template (`skipped` = a file was already there).
  * @property {string | null} themeTemplatePath Relative output path when `themeTemplate === 'created'`.
@@ -70,7 +70,7 @@
  * @typedef {object} InitOptions
  * @property {string} [features] Comma-separated features to install (agents, theme, template).
  * @property {boolean} [all] Install all features.
- * @property {boolean} [removeAgents] Remove the managed agent-docs block instead of installing; with `user`, remove the computer-level agent text.
+ * @property {boolean} [removeAgents] Remove the managed agent-docs block, at the project root and in the folder init runs in, instead of installing; with `user`, remove the computer-level agent text.
  * @property {boolean} [user] Write the computer-level agent text (`~/.agents/skills/astryx/SKILL.md`, linked into `~/.claude/skills` and the skill folders of other installed tools, with a copy for Continue) instead of setting up the folder.
  * @property {string} [agent] Agent preset: claude, cursor, codex, hermes, muse, all. Refused with `user`.
  * @property {string | string[]} [agentDocsPath] Explicit agent-docs file path(s).

package/api/init/remove/remove.mjs

@@ -4,15 +4,16 @@
  * @file init.remove leaf — the `--remove-agents` path behind `astryx init`.
  *
  * `remove(ctx)` deletes the managed agent-docs block from every agent-doc file
- * and returns an `init.remove` receipt. The removal engine lives in
- * lib/agent-docs; this leaf only wires the cwd.
+ * at the project root, where init writes it, and in the working folder, and
+ * returns an `init.remove` receipt. The removal engine lives in
+ * foundation/agent-docs; this leaf only wires the cwd.
  *
  * Note: removeAgentDocs() still logs its own per-file lines via humanLog
  * (shared lib behavior) — so a programmatic remove is not perfectly silent yet.
  * Threading a logger through agent-docs is a separate cleanup.
  */
 
-import {removeAgentDocs} from '../../../foundation/agent-docs/agent-docs.mjs';
+import {removeProjectAgentDocs} from '../../../foundation/agent-docs/agent-docs.mjs';
 import {logger} from '../../logger.mjs';
 
 /**
@@ -23,7 +24,19 @@ import {logger} from '../../logger.mjs';
  * @returns {Promise<import('../init.type.mjs').InitRemoveResponse>}
  */
 export async function remove({cwd = process.cwd()} = {}) {
-  const removedFrom = removeAgentDocs(cwd);
+  /** @type {string[]} */
+  const skipped = [];
+  const removedFrom = removeProjectAgentDocs(cwd, {
+    onSkipped: (rel, reason) => skipped.push(`${rel} (${reason})`),
+  });
+  if (skipped.length > 0) {
+    // Below the project root, as install does there (0.7.x touched only the
+    // working folder): a root agent file outside the project is left alone.
+    logger.warn(
+      `Note: Left as ${skipped.length === 1 ? 'it is' : 'they are'}: ${skipped.join('; ')}. ` +
+        'To remove the Astryx block there, delete it by hand.',
+    );
+  }
   const removed = removedFrom.length > 0;
   logger.log(
     removed

package/api/init/remove/remove.test.mjs

@@ -1,12 +1,124 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
-import * as fs from 'node:fs'; import * as path from 'node:path';
+import * as fs from 'node:fs'; import * as path from 'node:path'; import * as os from 'node:os';
 import {init} from '../init.mjs'; import {remove} from './remove.mjs'; import {logger} from '../../logger.mjs';
 let dir;
-beforeEach(() => { dir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-rm-')); fs.writeFileSync(path.join(dir,'package.json'),JSON.stringify({name:'c',version:'1.0.0'})); });
+beforeEach(() => { dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-rm-')); fs.writeFileSync(path.join(dir,'package.json'),JSON.stringify({name:'c',version:'1.0.0'})); });
 afterEach(() => { fs.rmSync(dir,{recursive:true,force:true}); logger.setSilent(true); });
 describe('init.remove says whether anything was removed', () => {
   it('false on clean', async () => { const r=await remove({cwd:dir}); expect(r.type).toBe('init.remove'); expect(r.data.removed).toBe(false); });
   it('true then false', async () => { await init({features:['agents']},{cwd:dir}); expect(fs.readFileSync(path.join(dir,'AGENTS.md'),'utf8')).toContain('<!-- ASTRYX:START -->'); const a=await remove({cwd:dir}); expect(a.data.removed).toBe(true); const b=await remove({cwd:dir}); expect(b.data.removed).toBe(false); });
   it('human line', async () => { const l=[]; const s=vi.spyOn(console,'log').mockImplementation((...a)=>l.push(a.join(' '))); logger.setSilent(false); try{await remove({cwd:dir});}finally{logger.setSilent(true);s.mockRestore();} expect(l.join('\n')).toContain('Nothing to remove'); });
 });
+
+describe('init.remove acts where init writes, the project root, and in the folder it runs in', () => {
+  /** @type {string} */
+  let project;
+  beforeEach(() => {
+    project = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-rm-root-'));
+    fs.writeFileSync(
+      path.join(project, 'package.json'),
+      JSON.stringify({name: 'app', dependencies: {'@astryxdesign/core': '1.0.0'}}),
+    );
+    fs.mkdirSync(path.join(project, 'src', 'app'), {recursive: true});
+  });
+  afterEach(() => { fs.rmSync(project, {recursive: true, force: true}); });
+  const block = '<!-- ASTRYX:START -->\nAstryx v0.7.0 · old\n<!-- ASTRYX:END -->\n';
+
+  it('removes from a subfolder what init wrote at the project root', async () => {
+    const sub = path.join(project, 'src', 'app');
+    const written = await init({features: ['agents']}, {cwd: sub});
+    expect(written.data.docsWritten).toEqual(['../../AGENTS.md', '../../GEMINI.md']);
+
+    const r = await remove({cwd: sub});
+    expect(r).toEqual({type: 'init.remove', data: {removed: true}});
+    // Both files held only what init wrote, so they are deleted.
+    expect(fs.existsSync(path.join(project, 'AGENTS.md'))).toBe(false);
+    expect(fs.existsSync(path.join(project, 'GEMINI.md'))).toBe(false);
+    expect((await remove({cwd: sub})).data.removed).toBe(false);
+  });
+
+  it('removes a block an earlier version left in the subfolder, and keeps the files\' own text', async () => {
+    const sub = path.join(project, 'src', 'app');
+    fs.writeFileSync(path.join(project, 'AGENTS.md'), `# Agents\n\nRoot rules.\n\n${block}`);
+    fs.writeFileSync(path.join(sub, 'AGENTS.md'), `# App\n\nApp rules.\n\n${block}`);
+
+    expect((await remove({cwd: sub})).data.removed).toBe(true);
+    expect(fs.readFileSync(path.join(project, 'AGENTS.md'), 'utf8').trimEnd()).toBe('# Agents\n\nRoot rules.');
+    expect(fs.readFileSync(path.join(sub, 'AGENTS.md'), 'utf8').trimEnd()).toBe('# App\n\nApp rules.');
+  });
+
+  it('run at the project root, leaves a subfolder alone', async () => {
+    const sub = path.join(project, 'src', 'app');
+    fs.writeFileSync(path.join(project, 'AGENTS.md'), `# Agents\n\n${block}`);
+    fs.writeFileSync(path.join(sub, 'AGENTS.md'), `# App\n\n${block}`);
+
+    expect((await remove({cwd: project})).data.removed).toBe(true);
+    expect(fs.readFileSync(path.join(sub, 'AGENTS.md'), 'utf8')).toContain('<!-- ASTRYX:START -->');
+  });
+
+  it('below the root, leaves a root agent file linked outside the project with a note, and removes the rest (0.7.x exited 0)', async () => {
+    // A workspace member whose CLAUDE.md links to the monorepo's.
+    const monorepo = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-rm-mono-'));
+    try {
+      const web = path.join(monorepo, 'apps', 'web');
+      const sub = path.join(web, 'src');
+      fs.mkdirSync(sub, {recursive: true});
+      fs.writeFileSync(
+        path.join(web, 'package.json'),
+        JSON.stringify({name: 'web', dependencies: {'@astryxdesign/core': '1.0.0'}}),
+      );
+      fs.writeFileSync(path.join(monorepo, 'CLAUDE.md'), `# Shared\n\n${block}`);
+      fs.symlinkSync('../../CLAUDE.md', path.join(web, 'CLAUDE.md'));
+      fs.writeFileSync(path.join(web, 'AGENTS.md'), `# Web\n\n${block}`);
+      fs.writeFileSync(path.join(sub, 'AGENTS.md'), `# Src\n\n${block}`);
+      const warned = [];
+      const warn = vi.spyOn(console, 'error').mockImplementation((...a) => warned.push(a.join(' ')));
+      logger.setSilent(false);
+      let r;
+      try {
+        r = await remove({cwd: sub});
+      } finally {
+        logger.setSilent(true);
+        warn.mockRestore();
+      }
+      expect(r).toEqual({type: 'init.remove', data: {removed: true}});
+      expect(fs.readFileSync(path.join(web, 'AGENTS.md'), 'utf8').trimEnd()).toBe('# Web');
+      expect(fs.readFileSync(path.join(sub, 'AGENTS.md'), 'utf8').trimEnd()).toBe('# Src');
+      // The file outside the project keeps its block.
+      expect(fs.readFileSync(path.join(monorepo, 'CLAUDE.md'), 'utf8')).toContain('<!-- ASTRYX:START -->');
+      expect(warned.join('\n')).toMatch(/Note: Left as it is: \.\.\/CLAUDE\.md \(/u);
+    } finally {
+      fs.rmSync(monorepo, {recursive: true, force: true});
+    }
+  });
+
+  it('at the root, a root agent file linked outside the project still refuses the run', async () => {
+    const outside = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-rm-outside-'));
+    try {
+      fs.writeFileSync(path.join(outside, 'CLAUDE.md'), `# Shared\n\n${block}`);
+      fs.symlinkSync(path.join(outside, 'CLAUDE.md'), path.join(project, 'CLAUDE.md'));
+      fs.writeFileSync(path.join(project, 'AGENTS.md'), `# Agents\n\n${block}`);
+      await expect(remove({cwd: project})).rejects.toMatchObject({code: 'ERR_PATH_TRAVERSAL'});
+      expect(fs.readFileSync(path.join(project, 'AGENTS.md'), 'utf8')).toContain('<!-- ASTRYX:START -->');
+    } finally {
+      fs.rmSync(outside, {recursive: true, force: true});
+    }
+  });
+
+  it('a link in the subfolder that escapes it refuses the run before anything is written', async () => {
+    const sub = path.join(project, 'src', 'app');
+    const outside = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-rm-outside-'));
+    try {
+      fs.writeFileSync(path.join(project, 'AGENTS.md'), `# Agents\n\n${block}`);
+      fs.writeFileSync(path.join(outside, 'CLAUDE.md'), `# Shared\n\n${block}`);
+      fs.symlinkSync(path.join(outside, 'CLAUDE.md'), path.join(sub, 'CLAUDE.md'));
+
+      await expect(remove({cwd: sub})).rejects.toMatchObject({code: 'ERR_PATH_TRAVERSAL'});
+      expect(fs.readFileSync(path.join(project, 'AGENTS.md'), 'utf8')).toContain('<!-- ASTRYX:START -->');
+      expect(fs.readFileSync(path.join(outside, 'CLAUDE.md'), 'utf8')).toContain('<!-- ASTRYX:START -->');
+    } finally {
+      fs.rmSync(outside, {recursive: true, force: true});
+    }
+  });
+});

package/api/init/run/run.mjs

@@ -4,10 +4,12 @@
  * @file init.run leaf — non-interactive project setup + feature installer.
  *
  * `run(options, ctx)` is the default / `--features` / `--all` path behind
- * `astryx init`. It installs the AGENTS.md/CLAUDE.md agent-docs cheat sheet,
- * points at the theme + page-building workflows, and (optionally) scaffolds a
- * starter template — with NO prompts, so it behaves identically for humans,
- * agents, CI, and piped I/O. It performs the side effects and returns an
+ * `astryx init`. It installs the agent-docs cheat sheet at the project root so
+ * every agent reads it (AGENTS.md, a copy in the project's Claude Code file, and
+ * a GEMINI.md import), points at the theme + page-building workflows, and
+ * (optionally) scaffolds a starter template — with NO prompts, so it behaves
+ * identically for humans, agents, CI, and piped I/O. It performs the side
+ * effects and returns an
  * `init.run` receipt. Hard errors (unknown feature/template) throw AstryxError
  * with a stable code. Human output is emitted through the shared `logger`
  * (silent by default) so the CLI keeps its exact plain output and a
@@ -21,8 +23,11 @@ import {PathSafetyError, assertWithin} from '../../../foundation/fs/path-safety.
 import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
 import {isOutsideProject} from '../../../foundation/env/project-scope.mjs';
 import {
+  AgentDocsHomeError,
+  assertAgentDocsTarget,
   installAgentDocs,
   renderAgentDocsBlock,
+  agentDocsTargetDir,
 } from '../../../foundation/agent-docs/agent-docs.mjs';
 import {themeTemplate} from '../../theme/template/template.mjs';
 import {listTemplates} from '../../template/template.mjs';
@@ -64,6 +69,24 @@ export function getNextSteps(invocation) {
   ];
 }
 
+/**
+ * Whether two paths name one folder, links resolved.
+ * @param {string} a
+ * @param {string} b
+ * @returns {boolean}
+ */
+function sameFolder(a, b) {
+  /** @param {string} p */
+  const real = p => {
+    try {
+      return fs.realpathSync(p);
+    } catch {
+      return path.resolve(p);
+    }
+  };
+  return real(a) === real(b);
+}
+
 /**
  * Install the agent-docs block; records the outcome (or soft error) on `data`.
  * Mirrors the CLI's historical soft-error policy: a PathSafetyError surfaces its
@@ -92,14 +115,46 @@ async function applyAgents(cwd, options, invocation, data) {
         ? options.agentDocsPath
         : [options.agentDocsPath]
       : undefined;
-    const renderedBlock = await renderAgentDocsBlock(cwd);
-    const written = installAgentDocs(cwd, {
+    // The docs belong at the project root, not in the subfolder init ran in;
+    // with no project above, they go where init ran, as before. Explicit
+    // --agent-docs-path entries stay relative to where init ran.
+    const root = agentDocsTargetDir(cwd);
+    const targetDir = paths ? cwd : root;
+    // With explicit paths, installAgentDocs checks each file's own folder.
+    if (!paths) assertAgentDocsTarget(targetDir);
+    const renderedBlock = await renderAgentDocsBlock(root);
+    /** @type {string[]} */
+    const skipped = [];
+    const files = installAgentDocs(targetDir, {
       agent: options.agent,
       paths,
       renderedBlock,
+      onSkipped: (rel, reason) => skipped.push(`${rel} (${reason})`),
+      // Below the project root, 0.7.1 wrote in the folder init ran in, so a
+      // project-root file that escapes the project is skipped and reported,
+      // not refused.
+      refuseEscapes: sameFolder(targetDir, cwd),
     });
+    // Each file is reported from where init ran, as before.
+    const written =
+      path.resolve(targetDir) === path.resolve(cwd)
+        ? files
+        : files.map(rel =>
+            path.relative(cwd, path.join(targetDir, rel)).split(path.sep).join('/'),
+          );
     data.docsWritten = written;
     logger.log(`[ok] AI agent docs installed -> ${written.join(', ')}`);
+    // A file 0.7.1 did not write (GEMINI.md, or a project-root file when init
+    // runs below the root) that resolves outside the project is left as it
+    // is, reported in docsError with one note; the exit code stays 0. A file
+    // 0.7.1 wrote whose path escapes the project still fails the run (below).
+    if (skipped.length > 0) {
+      const message =
+        `Left as ${skipped.length === 1 ? 'it is' : 'they are'}: ${skipped.join('; ')}. ` +
+        'To have init write the Astryx block there, make it a regular file inside the project, or copy the block from AGENTS.md by hand.';
+      logger.warn(`Note: ${message}`);
+      data.docsError = {kind: 'install-failed', message};
+    }
   } catch (err) {
     // PathSafetyError carries a precise, user-actionable message — surface it
     // (and flag exit 1) instead of the generic "could not install" warning so
@@ -109,6 +164,14 @@ async function applyAgents(cwd, options, invocation, data) {
       data.docsError = {kind: 'path-safety', message: err.message};
       return;
     }
+    // The home folder, and a settings folder in it outside a project, are
+    // refused: nothing is written, the reason is printed as a note, and the
+    // exit code stays 0.
+    if (err instanceof AgentDocsHomeError) {
+      logger.warn(`Note: ${err.message}`);
+      data.docsError = {kind: 'install-failed', message: err.message};
+      return;
+    }
     logger.error(
       `Could not install agent docs. Try again with \`${invocation} init --features agents\`.`,
     );

package/api/integration/_adapter.d.mts

@@ -40,6 +40,14 @@ export function integrationFluff(discovered: Parameters<typeof findFluff>[0]): P
  *   read too
  */
 export function integrationStrayPointers(discovered: Parameters<typeof findStrayPointers>[0], integration?: any): Promise<import("./authoring-checks.type.mjs").StrayPointer[]>;
+/**
+ * Each Astryx command a package's topics write with a package runner. A
+ * package whose topics cannot be discovered has none here: the other checks
+ * report topics that do not load.
+ * @param {any} integration a loaded integration
+ * @returns {Promise<import('../../foundation/discovery/runner-commands.mjs').RunnerCommand[]>}
+ */
+export function integrationRunnerCommands(integration: any): Promise<import("../../foundation/discovery/runner-commands.mjs").RunnerCommand[]>;
 import { findCopiedPassages } from '../../foundation/discovery/copied-passages.mjs';
 import { findFluff } from '../../foundation/discovery/doc-fluff.mjs';
 import { findStrayPointers } from '../../foundation/discovery/stray-pointers.mjs';

package/api/integration/_adapter.mjs

@@ -2,7 +2,8 @@
 
 /**
  * @file The integration subject's access to the environment (INV21): reading
- * one package's component docs and sources with the project's own TypeScript.
+ * one package's component docs and sources with the project's own TypeScript,
+ * and its topics.
  *
  * @input a loaded integration and the directory the command runs in
  * @output the reports the integration checks attach to their results
@@ -14,9 +15,11 @@ import {
   forEachIntegrationDoc,
   integrationSourceForDoc,
 } from '../../foundation/discovery/component-discovery.mjs';
+import {discoverIntegrationDocs} from '../../foundation/discovery/docs-discovery.mjs';
 import {comparePropDocs} from '../../foundation/discovery/prop-drift.mjs';
 import {findCopiedPassages} from '../../foundation/discovery/copied-passages.mjs';
 import {findFluff} from '../../foundation/discovery/doc-fluff.mjs';
+import {findRunnerCommands} from '../../foundation/discovery/runner-commands.mjs';
 import {findStrayPointers} from '../../foundation/discovery/stray-pointers.mjs';
 
 /**
@@ -110,3 +113,20 @@ export async function integrationStrayPointers(discovered, integration) {
   }
   return findStrayPointers({...discovered, components});
 }
+
+/**
+ * Each Astryx command a package's topics write with a package runner. A
+ * package whose topics cannot be discovered has none here: the other checks
+ * report topics that do not load.
+ * @param {any} integration a loaded integration
+ * @returns {Promise<import('../../foundation/discovery/runner-commands.mjs').RunnerCommand[]>}
+ */
+export async function integrationRunnerCommands(integration) {
+  let discovered;
+  try {
+    discovered = await discoverIntegrationDocs(integration);
+  } catch {
+    return [];
+  }
+  return findRunnerCommands(discovered);
+}

package/api/integration/authoring-checks.mjs

@@ -51,6 +51,8 @@ import {
   validateInstalledIntegration,
   validateLocalIntegration,
 } from './validate-integration.mjs';
+import {rootProblem} from '../../foundation/integrations/validate-contributions.mjs';
+import {normalizeProviderId} from '../../foundation/identity/provider-identity.mjs';
 
 /** @param {string} value */
 export function shellArg(value) {
@@ -58,15 +60,61 @@ export function shellArg(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 
+/**
+ * The provider ID a package without a name is checked under: a valid bare
+ * package name no published package can hold (npm names are lowercase).
+ */
+const UNNAMED_PROVIDER = 'astryx-unnamed-local-package';
+
+/**
+ * A message as the package sees it: the stand-in provider ID gone, its docs
+ * named by their path in the package.
+ * @param {string} message
+ */
+function unnamedShown(message) {
+  return message
+    .split(`${UNNAMED_PROVIDER}/`)
+    .join('')
+    .split(UNNAMED_PROVIDER)
+    .join('this package');
+}
+
 /**
  * Resolve one local or installed integration for an authoring check.
  * @param {string | undefined} pkg
  * @param {string} cwd
  */
 async function resolveIntegration(pkg, cwd) {
-  return pkg
-    ? validateInstalledIntegration(pkg, cwd)
-    : validateLocalIntegration(cwd);
+  const resolved = pkg
+    ? await validateInstalledIntegration(pkg, cwd)
+    : await validateLocalIntegration(cwd);
+  const integration = resolved.found ? resolved.integration : undefined;
+  if (!integration) return resolved;
+  // A root that is not a readable folder is reported in the issues; the
+  // checks read nothing from it rather than fail on it.
+  /** @type {typeof integration & {__unnamed?: boolean}} */
+  const usable = {...integration};
+  // The provider ID readers key the package on: the manifest's providerId,
+  // else its name. A package with neither (validate warned about it) is
+  // still checked; the docs check names its docs under a stand-in ID.
+  try {
+    usable.providerId = normalizeProviderId(
+      integration.__declaredProviderId ?? integration.name,
+    );
+  } catch {
+    usable.__unnamed = true;
+  }
+  for (const kind of /** @type {const} */ ([
+    'components',
+    'templates',
+    'codemods',
+    'docs',
+    'themes',
+  ])) {
+    const root = usable[kind];
+    if (root != null && rootProblem(root)) usable[kind] = undefined;
+  }
+  return {...resolved, integration: usable};
 }
 
 /**
@@ -387,8 +435,20 @@ export async function integrationDocConflicts(pkg, options = {}) {
     };
   }
 
+  // The docs tree names a package's docs by its provider ID, which a
+  // package.json without a name does not give: its docs are checked under a
+  // stand-in ID, which no message names.
+  const unnamed = /** @type {{__unnamed?: boolean}} */ (resolved.integration)
+    .__unnamed;
+  const docsIntegration = unnamed
+    ? {
+        ...resolved.integration,
+        name: UNNAMED_PROVIDER,
+        providerId: UNNAMED_PROVIDER,
+      }
+    : resolved.integration;
   const [discovered, builtinTopics] = await Promise.all([
-    discoverIntegrationDocs(resolved.integration),
+    discoverIntegrationDocs(docsIntegration),
     Promise.resolve(discoverBuiltinTopics()),
   ]);
   const {records, errors} = discovered;
@@ -458,27 +518,40 @@ export async function integrationDocConflicts(pkg, options = {}) {
   // its docs (spec:AST-046, spec:AST-047).
   if (errors.length === 0) {
     for (const {severity, message} of await packageDocsProblems(
-      /** @type {{name: string}} */ (resolved.integration),
+      /** @type {{name: string}} */ (docsIntegration),
       discovered,
     )) {
-      issues.push({code: 'invalid_doc_graph', severity, message});
+      issues.push({
+        code: 'invalid_doc_graph',
+        severity,
+        message: unnamedShown(message),
+      });
     }
 
     // A reference block includes content rather than linking to it, so one
     // that cannot include what it names loses that content for every reader:
     // an error, where a link that names no doc still prints as written.
     for (const message of await packageReferenceProblems(
-      /** @type {{name: string}} */ (resolved.integration),
+      /** @type {{name: string}} */ (docsIntegration),
       discovered,
     )) {
-      issues.push({code: 'invalid_doc_reference', severity: 'error', message});
+      issues.push({
+        code: 'invalid_doc_reference',
+        severity: 'error',
+        message: unnamedShown(message),
+      });
     }
 
     // One fact has one owner: a passage two topics repeat goes stale in one
     // of them. Each is listed and is a warning (architecture:cli-surface
     // DEC-8), so `integration check --strict` fails until it is fixed;
     // `doctor integration docs` keeps its exit code, as it fails on errors.
-    copiedPassages.push(...(await integrationCopiedPassages(discovered)));
+    copiedPassages.push(
+      ...(await integrationCopiedPassages(discovered)).map(passage => ({
+        ...passage,
+        message: unnamedShown(passage.message),
+      })),
+    );
     for (const {message} of copiedPassages) {
       issues.push({code: 'copied_passage', severity: 'warning', message});
     }
@@ -488,6 +561,7 @@ export async function integrationDocConflicts(pkg, options = {}) {
       ...(await integrationFluff(discovered)).map(each => ({
         ...each,
         file: fromPackage(each.file),
+        message: unnamedShown(each.message),
       })),
     );
     for (const {message} of fluff) {