@astryxdesign/cli 0.7.2-canary.fdd384f → 0.7.2

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

@@ -42,7 +42,7 @@ export type InitRunData = {
      */
     templatePath: string | null;
     /**
-     * Whether the getting-started "Next steps" were emitted (default mode).
+     * Whether the getting-started "Next steps" were emitted (default mode inside a project; false outside one).
      */
     nextSteps: boolean;
 };
@@ -59,6 +59,47 @@ export type InitRemoveResponse = {
         removed: boolean;
     };
 };
+/**
+ * What `init --user` did with one file of the computer-level agent text.
+ * `written`: created or refreshed. `unchanged`: already this release's text.
+ * `removed`: deleted (with `--remove-agents`). `absent`: nothing to remove.
+ * `kept`: a file left as it is, because a person edited it or Astryx did not
+ * write it (see `reason`).
+ */
+export type InitUserAction = "written" | "linked" | "unchanged" | "removed" | "absent" | "kept";
+export type InitUserFile = {
+    /**
+     * Absolute path in the home folder: the skill file,
+     * or a link to its folder.
+     */
+    path: string;
+    action: InitUserAction;
+    /**
+     * Only on `kept`: `edited`, the
+     * text no longer matches the hash Astryx recorded in it; `not-astryx`, it
+     * has no Astryx markers or is a symlink, or a link target holds something
+     * Astryx did not create.
+     */
+    reason?: "edited" | "not-astryx" | undefined;
+};
+export type InitUserData = {
+    /**
+     * One row per path acted on: `~/.agents/skills/astryx/SKILL.md` first, then each link to its folder: `~/.claude/skills/astryx` always, and another agent's skills folder when that agent's folder exists (`linked`, or `unchanged` when the link is already there). Removal removes the file and the links Astryx made.
+     */
+    files: InitUserFile[];
+    /**
+     * The command the text tells agents to run: `astryx`, or the host's command when a host started the run.
+     */
+    command: string;
+    /**
+     * Non-fatal notes, such as no `astryx` on the computer that runs the Astryx CLI.
+     */
+    warnings: string[];
+};
+export type InitUserResponse = {
+    type: "init.user";
+    data: InitUserData;
+};
 /**
  * Options for `init()`.
  */
@@ -72,11 +113,15 @@ export type InitOptions = {
      */
     all?: boolean | undefined;
     /**
-     * Remove the managed agent-docs block instead of installing.
+     * Remove the managed agent-docs block instead of installing; with `user`, remove the computer-level agent text.
      */
     removeAgents?: boolean | undefined;
     /**
-     * Agent preset: claude, cursor, codex, hermes, muse, all.
+     * 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.
+     */
+    user?: boolean | undefined;
+    /**
+     * Agent preset: claude, cursor, codex, hermes, muse, all. Refused with `user`.
      */
     agent?: string | undefined;
     /**

package/api/init/init.type.mjs

@@ -17,7 +17,7 @@
  * @property {string | null} themeTemplatePath Relative output path when `themeTemplate === 'created'`.
  * @property {'workflow' | 'created' | 'skipped' | null} template Template outcome (`workflow` is the CLI default; `created`/`skipped` are programmatic).
  * @property {string | null} templatePath Relative output path when `template === 'created'`.
- * @property {boolean} nextSteps Whether the getting-started "Next steps" were emitted (default mode).
+ * @property {boolean} nextSteps Whether the getting-started "Next steps" were emitted (default mode inside a project; false outside one).
  */
 
 /**
@@ -32,13 +32,47 @@
  * @property {{removed: boolean}} data False when no managed agent-docs block was found, so nothing was removed.
  */
 
+/**
+ * What `init --user` did with one file of the computer-level agent text.
+ * `written`: created or refreshed. `unchanged`: already this release's text.
+ * `removed`: deleted (with `--remove-agents`). `absent`: nothing to remove.
+ * `kept`: a file left as it is, because a person edited it or Astryx did not
+ * write it (see `reason`).
+ * @typedef {'written' | 'linked' | 'unchanged' | 'removed' | 'absent' | 'kept'} InitUserAction
+ */
+
+/**
+ * @typedef {object} InitUserFile
+ * @property {string} path Absolute path in the home folder: the skill file,
+ *   or a link to its folder.
+ * @property {InitUserAction} action
+ * @property {'edited' | 'not-astryx'} [reason] Only on `kept`: `edited`, the
+ *   text no longer matches the hash Astryx recorded in it; `not-astryx`, it
+ *   has no Astryx markers or is a symlink, or a link target holds something
+ *   Astryx did not create.
+ */
+
+/**
+ * @typedef {object} InitUserData
+ * @property {InitUserFile[]} files One row per path acted on: `~/.agents/skills/astryx/SKILL.md` first, then each link to its folder: `~/.claude/skills/astryx` always, and another agent's skills folder when that agent's folder exists (`linked`, or `unchanged` when the link is already there). Removal removes the file and the links Astryx made.
+ * @property {string} command The command the text tells agents to run: `astryx`, or the host's command when a host started the run.
+ * @property {string[]} warnings Non-fatal notes, such as no `astryx` on the computer that runs the Astryx CLI.
+ */
+
+/**
+ * @typedef {object} InitUserResponse
+ * @property {'init.user'} type
+ * @property {InitUserData} data
+ */
+
 /**
  * Options for `init()`.
  * @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.
- * @property {string} [agent] Agent preset: claude, cursor, codex, hermes, muse, all.
+ * @property {boolean} [removeAgents] Remove the managed agent-docs block 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).
  * @property {string} [templateName] Scaffold a named page template (programmatic only; the CLI never sets it).
  */

package/api/init/run/run.d.mts

@@ -8,7 +8,7 @@
  * installed built themes and imports their production and font stylesheets. The
  * app imports that module once and passes its default to <Theme>.
  *
- * @param {string} invocation install-aware CLI invocation stem (e.g. `npx astryx`, `pnpm exec astryx`, or `npx @astryxdesign/cli` for one-off runs)
+ * @param {string} invocation install-aware CLI invocation stem (e.g. `pnpm exec astryx`, `yarn astryx`, or `npx @astryxdesign/cli` for one-off runs)
  * @returns {string[]} ordered list of human-facing lines
  */
 export function getNextSteps(invocation: string): string[];

package/api/init/run/run.mjs

@@ -19,6 +19,7 @@ import * as fs from 'node:fs';
 import {CLI_ROOT} from '../../../foundation/fs/paths.mjs';
 import {PathSafetyError, assertWithin} from '../../../foundation/fs/path-safety.mjs';
 import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
+import {isOutsideProject} from '../../../foundation/env/project-scope.mjs';
 import {
   installAgentDocs,
   renderAgentDocsBlock,
@@ -39,7 +40,7 @@ const VALID_AGENTS = ['claude', 'cursor', 'codex', 'hermes', 'muse', 'all'];
  * installed built themes and imports their production and font stylesheets. The
  * app imports that module once and passes its default to <Theme>.
  *
- * @param {string} invocation install-aware CLI invocation stem (e.g. `npx astryx`, `pnpm exec astryx`, or `npx @astryxdesign/cli` for one-off runs)
+ * @param {string} invocation install-aware CLI invocation stem (e.g. `pnpm exec astryx`, `yarn astryx`, or `npx @astryxdesign/cli` for one-off runs)
  * @returns {string[]} ordered list of human-facing lines
  */
 export function getNextSteps(invocation) {
@@ -140,8 +141,11 @@ function applyTheme(cwd, invocation, data) {
     data.themeTemplate = 'failed';
     logger.error('Could not write the theme template.');
   }
+  // Outside a project there is no app to add a theme to (spec AST-081 FR3).
   logger.log(
-    `  Edit the blank template for a new theme, or run \`${invocation} theme add <slug>\` to import an installed built theme (\`${invocation} theme list\` to browse). Extend an imported theme for ordinary customization; use \`${invocation} theme eject <slug>\` only to fork source.`,
+    isOutsideProject(cwd)
+      ? `  Edit the blank template for a new theme, or run \`${invocation} theme eject <slug>\` to start from the source of a built theme (\`${invocation} theme list\` to browse).`
+      : `  Edit the blank template for a new theme, or run \`${invocation} theme add <slug>\` to import an installed built theme (\`${invocation} theme list\` to browse). Extend an imported theme for ordinary customization; use \`${invocation} theme eject <slug>\` only to fork source.`,
   );
 }
 
@@ -276,7 +280,10 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {
   }
 
   // No flags: TTY-free default — install the AI agent cheat sheet with NO
-  // prompts, then print the getting-started guidance.
+  // prompts, then print the getting-started guidance. Outside a project the
+  // steps would set up a project the folder does not have, so they are left
+  // out (spec AST-081 FR3).
+  const outside = isOutsideProject(cwd);
   /** @type {import('../init.type.mjs').InitRunData} */
   const data = {
     mode: 'default',
@@ -288,13 +295,17 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {
     themeTemplatePath: null,
     template: null,
     templatePath: null,
-    nextSteps: true,
+    nextSteps: !outside,
   };
   await applyAgents(cwd, options, invocation, data);
   logger.log('');
   logger.log(
     `  Tip: \`${invocation} init --all\` also points you to the theme and page-building workflows.`,
   );
+  if (outside) {
+    logger.log('');
+    return {type: 'init.run', data};
+  }
   for (const line of getNextSteps(invocation)) logger.log(line);
   return {type: 'init.run', data};
 }

package/api/init/user/user.d.mts

@@ -0,0 +1,14 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Write or remove the computer-level agent text and return an `init.user`
+ * receipt. Progress is emitted through the shared `logger` (silent by
+ * default); warnings go to its warn channel.
+ *
+ * @param {{remove?: boolean}} [options]
+ * @returns {Promise<import('../init.type.mjs').InitUserResponse>}
+ */
+export function user({ remove }?: {
+    remove?: boolean;
+}): Promise<import("../init.type.mjs").InitUserResponse>;

package/api/init/user/user.mjs

@@ -0,0 +1,87 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file init.user leaf — the `--user` path behind `astryx init`.
+ *
+ * `user(options)` writes, refreshes, or (with `remove`) removes the
+ * computer-level agent text: one skill file in the home folder, linked into
+ * the skill folders agents read (spec AST-081 FR7, FR8). It records the
+ * setting and the links it made in the settings file, so the global copy,
+ * which keeps the text current in the background, does the same, or, after
+ * `remove`, writes nothing. The adapter does every file access. It works in any
+ * folder and never touches a project's agent docs. A file without the Astryx
+ * markers, one a person edited, or a symlinked one is kept as it is. When no
+ * `astryx` on the computer's search path runs the Astryx CLI, the text is
+ * still written and the receipt warns that the CLI should be installed for
+ * the computer.
+ *
+ * @input  `remove`; the home folder, search path, and settings of
+ *   the computer
+ * @output an `init.user` receipt
+ * @position packages/cli/api/init — dispatched by init.mjs
+ */
+
+import {
+  COMPUTER_COMMAND,
+  COMPUTER_INSTALL_STEP,
+  applyComputerAgentText,
+  displayHomePath,
+} from '../_adapter.mjs';
+import {logger} from '../../logger.mjs';
+
+/**
+ * @param {string} file
+ * @param {string} home
+ * @returns {string}
+ */
+const display = (file, home) => displayHomePath(file, home);
+
+/** @type {Record<import('../init.type.mjs').InitUserAction, string>} */
+const ACTION_LINES = {
+  written: '[ok] Wrote',
+  linked: '[ok] Linked',
+  unchanged: '[ok] Already current:',
+  removed: '[ok] Removed',
+  absent: '[ok] Nothing to remove:',
+  kept: '[skip] Kept',
+};
+
+/** @type {Record<'edited' | 'not-astryx', string>} */
+const KEPT_REASONS = {
+  edited: '(edited since Astryx wrote it; delete it to get the current text):',
+  'not-astryx': '(not created by Astryx):',
+};
+
+/**
+ * Write or remove the computer-level agent text and return an `init.user`
+ * receipt. Progress is emitted through the shared `logger` (silent by
+ * default); warnings go to its warn channel.
+ *
+ * @param {{remove?: boolean}} [options]
+ * @returns {Promise<import('../init.type.mjs').InitUserResponse>}
+ */
+export async function user({remove = false} = {}) {
+  const {home, command, files, cliOnSearchPath} = applyComputerAgentText({
+    remove,
+  });
+  /** @type {string[]} */
+  const warnings = [];
+  // A host's door is its own command; only the plain `astryx` needs a copy of
+  // the CLI installed for the computer.
+  if (!remove && command === COMPUTER_COMMAND && !cliOnSearchPath) {
+    warnings.push(
+      `No \`${COMPUTER_COMMAND}\` command on this computer runs the Astryx CLI, so agents cannot run the commands this text names. Install the CLI for the computer: ${COMPUTER_INSTALL_STEP}`,
+    );
+  }
+  for (const file of files) {
+    const reason = file.reason ? ` ${KEPT_REASONS[file.reason]}` : '';
+    logger.log(
+      `${ACTION_LINES[file.action]}${reason || (file.action === 'kept' ? ':' : '')} ${display(file.path, home)}`,
+    );
+  }
+  for (const warning of warnings) logger.warn(`[warn] ${warning}`);
+  return {
+    type: 'init.user',
+    data: {files, command, warnings},
+  };
+}

package/api/init/user/user.test.mjs

@@ -0,0 +1,232 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `init({user})` and `astryx init --user`: the `init.user` receipt, the
+ * install warning, the refused combinations, and that it touches nothing in
+ * the folder it runs in. Every test uses a temporary home folder and search
+ * path.
+ */
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+import {init} from '../init.mjs';
+import {user} from './user.mjs';
+import {runWithCliDoor} from '../../../foundation/env/cli-command.mjs';
+import {renderComputerAgentText} from '../../../foundation/agent-docs/computer-agent-text.mjs';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+import {settingsFile} from '../../../foundation/env/user-settings.mjs';
+import {readGlobalState} from '../../../foundation/release/global-state.mjs';
+import {cliVersion} from '../../../foundation/release/run-context.mjs';
+
+/** @type {string[]} */
+const dirs = [];
+/** @param {string} label */
+function tmp(label) {
+  const dir = fs.mkdtempSync(
+    path.join(os.tmpdir(), `astryx-init-user-${label}-`),
+  );
+  dirs.push(dir);
+  return dir;
+}
+
+let home = '';
+let emptyPath = '';
+beforeEach(() => {
+  home = tmp('home');
+  emptyPath = tmp('path');
+  vi.stubEnv('HOME', home);
+  vi.stubEnv('USERPROFILE', home);
+  vi.stubEnv('PATH', emptyPath);
+  // The settings file and the cache live under this home folder too.
+  vi.stubEnv('XDG_CONFIG_HOME', path.join(home, '.config'));
+  vi.stubEnv('XDG_CACHE_HOME', path.join(home, '.cache'));
+  vi.stubEnv('APPDATA', path.join(home, 'AppData', 'Roaming'));
+  vi.stubEnv('LOCALAPPDATA', path.join(home, 'AppData', 'Local'));
+});
+
+/** The settings file under the temporary home folder. */
+const settings = () => {
+  try {
+    return JSON.parse(fs.readFileSync(settingsFile(), 'utf8'));
+  } catch {
+    return null;
+  }
+};
+afterEach(() => {
+  vi.unstubAllEnvs();
+  while (dirs.length) {
+    fs.rmSync(/** @type {string} */ (dirs.pop()), {
+      recursive: true,
+      force: true,
+    });
+  }
+});
+
+const FILE = path.join('.agents', 'skills', 'astryx', 'SKILL.md');
+const CLAUDE = path.join('.claude', 'skills', 'astryx');
+
+/** Put a linked Astryx CLI first on the search path. */
+function installCliOnPath() {
+  const prefix = tmp('prefix');
+  const pkg = path.join(prefix, 'lib', 'node_modules', '@astryxdesign', 'cli');
+  fs.mkdirSync(pkg, {recursive: true});
+  fs.writeFileSync(
+    path.join(pkg, 'package.json'),
+    '{"name":"@astryxdesign/cli"}',
+  );
+  fs.writeFileSync(path.join(pkg, 'bin.mjs'), '#!/usr/bin/env node\n');
+  fs.chmodSync(path.join(pkg, 'bin.mjs'), 0o755);
+  fs.mkdirSync(path.join(prefix, 'bin'));
+  fs.symlinkSync(path.join(pkg, 'bin.mjs'), path.join(prefix, 'bin', 'astryx'));
+  vi.stubEnv('PATH', path.join(prefix, 'bin'));
+}
+
+describe('init({user: true})', () => {
+  it('writes the file, links Claude Code to it, and returns the init.user receipt, warning when no astryx runs the CLI', async () => {
+    const r = await init({user: true}, {cwd: tmp('cwd')});
+    expect(r.type).toBe('init.user');
+    if (r.type !== 'init.user') return;
+    expect(r.data.files).toEqual([
+      {path: path.join(home, FILE), action: 'written'},
+      {path: path.join(home, CLAUDE), action: 'linked'},
+    ]);
+    expect(r.data.command).toBe('astryx');
+    expect(r.data.warnings).toHaveLength(1);
+    expect(r.data.warnings[0]).toContain('npm i -g @astryxdesign/cli');
+    expect(fs.readFileSync(path.join(home, FILE), 'utf8')).toBe(
+      renderComputerAgentText({command: 'astryx'}),
+    );
+    expect(fs.readFileSync(path.join(home, CLAUDE, 'SKILL.md'), 'utf8')).toBe(
+      renderComputerAgentText({command: 'astryx'}),
+    );
+  });
+
+  it.skipIf(process.platform === 'win32')(
+    'does not warn when the astryx on the search path is the Astryx CLI',
+    async () => {
+      installCliOnPath();
+      const r = await user();
+      expect(r.data.warnings).toEqual([]);
+    },
+  );
+
+  it("names the host's door and does not ask for a global install", async () => {
+    const r = await runWithCliDoor('acme astryx', () => user());
+    expect(r.data.command).toBe('acme astryx');
+    expect(r.data.warnings).toEqual([]);
+    expect(fs.readFileSync(path.join(home, FILE), 'utf8')).toContain(
+      "`acme astryx search '<what you need>'`",
+    );
+  });
+
+  it('works inside a project and writes nothing in it', async () => {
+    const dir = tmp('project');
+    fs.writeFileSync(
+      path.join(dir, 'package.json'),
+      '{"name":"app","dependencies":{"@astryxdesign/core":"*"}}',
+    );
+    const before = fs.readdirSync(dir).sort();
+    const r = await init({user: true}, {cwd: dir});
+    expect(r.type).toBe('init.user');
+    expect(fs.readdirSync(dir).sort()).toEqual(before);
+  });
+
+  it('records the links it made, and the release that wrote the text', async () => {
+    await init({user: true});
+    expect(settings()).toEqual({
+      computerAgentText: {install: true, links: [path.join(home, CLAUDE)]},
+    });
+    expect(readGlobalState().agentText).toEqual({writtenBy: cliVersion()});
+  });
+
+  it('keeps every other setting when it records the choice', async () => {
+    fs.mkdirSync(path.dirname(settingsFile()), {recursive: true});
+    fs.writeFileSync(settingsFile(), '{"other": 1}');
+    await init({user: true, removeAgents: true});
+    expect(settings()).toEqual({
+      other: 1,
+      computerAgentText: {install: false, links: []},
+    });
+  });
+
+  it('with removeAgents removes the file and the links it made, and records that the text is not wanted', async () => {
+    await init({user: true});
+    const r = await init({user: true, removeAgents: true});
+    expect(r.type).toBe('init.user');
+    if (r.type !== 'init.user') return;
+    expect(r.data.files).toEqual([
+      {path: path.join(home, FILE), action: 'removed'},
+      {path: path.join(home, CLAUDE), action: 'removed'},
+    ]);
+    expect(r.data.warnings).toEqual([]);
+    expect(fs.existsSync(path.join(home, FILE))).toBe(false);
+    expect(fs.existsSync(path.join(home, CLAUDE))).toBe(false);
+    expect(settings()).toEqual({
+      computerAgentText: {install: false, links: []},
+    });
+  });
+
+  it.each([
+    [{features: 'agents'}, '--features'],
+    [{all: true}, '--all'],
+    [{agentDocsPath: 'X.md'}, '--agent-docs-path'],
+    [{agent: 'claude'}, '--agent'],
+    [{removeAgents: true, agent: 'claude'}, '--agent'],
+  ])(
+    'refuses %o with ERR_INVALID_ARGUMENT and writes nothing',
+    async (extra, flag) => {
+      await expect(init({user: true, ...extra})).rejects.toMatchObject({
+        code: 'ERR_INVALID_ARGUMENT',
+        message: expect.stringContaining(flag),
+      });
+      expect(fs.existsSync(path.join(home, '.agents'))).toBe(false);
+      expect(fs.existsSync(path.join(home, '.claude'))).toBe(false);
+    },
+  );
+});
+
+describe('astryx init --user', () => {
+  it('prints the file, the link, and the install warning in text mode', async () => {
+    const r = await runCli(['init', '--user'], tmp('cwd'));
+    expect(r.status).toBe(0);
+    expect(r.stdout).toContain(`Wrote ~${path.sep}${FILE}`);
+    expect(r.stdout).toContain(`Linked ~${path.sep}${CLAUDE}`);
+    expect(r.stderr).toContain('npm i -g @astryxdesign/cli');
+  });
+
+  it('emits the init.user envelope under --json', async () => {
+    const r = await runCli(['--json', 'init', '--user'], tmp('cwd'));
+    expect(r.status).toBe(0);
+    const env = JSON.parse(r.stdout);
+    expect(env.type).toBe('init.user');
+    expect(
+      env.data.files.map((/** @type {{action: string}} */ f) => f.action),
+    ).toEqual(['written', 'linked']);
+    expect(env.data.command).toBe('astryx');
+  });
+
+  it('names a file a person edited as kept, and why', async () => {
+    await runCli(['init', '--user'], tmp('cwd'));
+    const file = path.join(home, FILE);
+    fs.appendFileSync(file, 'my note\n');
+    const r = await runCli(['init', '--user'], tmp('cwd'));
+    expect(r.status).toBe(0);
+    expect(r.stdout).toContain(
+      `Kept (edited since Astryx wrote it; delete it to get the current text): ~${path.sep}${FILE}`,
+    );
+    expect(fs.readFileSync(file, 'utf8')).toMatch(/my note\n$/u);
+  });
+
+  it('exits 1 with ERR_INVALID_ARGUMENT when combined with --all or --agent', async () => {
+    for (const extra of [['--all'], ['--agent', 'claude']]) {
+      const r = await runCli(
+        ['--json', 'init', '--user', ...extra],
+        tmp('cwd'),
+      );
+      expect(r.status).toBe(1);
+      expect(JSON.parse(r.stdout).code).toBe('ERR_INVALID_ARGUMENT');
+    }
+  });
+});

package/api/integration/_adapter.d.mts

@@ -10,3 +10,36 @@
  * @returns {Promise<import('../../foundation/discovery/prop-drift.mjs').PropDriftReport>}
  */
 export function integrationPropDrift(integration: any, cwd: string): Promise<import("../../foundation/discovery/prop-drift.mjs").PropDriftReport>;
+/**
+ * The passages two of a package's topics, or one of them and a Core topic,
+ * repeat word for word (architecture:cli-surface DEC-8). Reads the package's
+ * topics and Core's guides.
+ *
+ * @param {Parameters<typeof findCopiedPassages>[0]} discovered the package's
+ *   docs, as discoverIntegrationDocs returns them
+ */
+export function integrationCopiedPassages(discovered: Parameters<typeof findCopiedPassages>[0]): Promise<import("./authoring-checks.type.mjs").CopiedPassage[]>;
+/**
+ * Padding phrases and low-density topics in a package's prose
+ * (architecture:cli-surface DEC-8). Reads the package's topics, and Core's
+ * guides for the density median a finding names.
+ *
+ * @param {Parameters<typeof findFluff>[0]} discovered the package's docs, as
+ *   discoverIntegrationDocs returns them
+ */
+export function integrationFluff(discovered: Parameters<typeof findFluff>[0]): Promise<import("./authoring-checks.type.mjs").DocFluff[]>;
+/**
+ * Code spans in a package's prose that write `astryx docs <name>` for a doc
+ * that exists, where `{@link generic:<name>}` would be checked
+ * (architecture:cli-surface DEC-8). Reads the package's topics, its own
+ * component docs, and the names of Core's docs.
+ *
+ * @param {Parameters<typeof findStrayPointers>[0]} discovered the package's
+ *   docs, as discoverIntegrationDocs returns them
+ * @param {any} [integration] the loaded integration, whose component docs are
+ *   read too
+ */
+export function integrationStrayPointers(discovered: Parameters<typeof findStrayPointers>[0], integration?: any): Promise<import("./authoring-checks.type.mjs").StrayPointer[]>;
+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

@@ -15,6 +15,9 @@ import {
   integrationSourceForDoc,
 } from '../../foundation/discovery/component-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 {findStrayPointers} from '../../foundation/discovery/stray-pointers.mjs';
 
 /**
  * Each component doc's props compared with the component's TypeScript props,
@@ -52,3 +55,58 @@ export async function integrationPropDrift(integration, cwd) {
     resolveFrom: [cwd, packageDir],
   });
 }
+
+/**
+ * The passages two of a package's topics, or one of them and a Core topic,
+ * repeat word for word (architecture:cli-surface DEC-8). Reads the package's
+ * topics and Core's guides.
+ *
+ * @param {Parameters<typeof findCopiedPassages>[0]} discovered the package's
+ *   docs, as discoverIntegrationDocs returns them
+ */
+export function integrationCopiedPassages(discovered) {
+  return findCopiedPassages(discovered);
+}
+
+/**
+ * Padding phrases and low-density topics in a package's prose
+ * (architecture:cli-surface DEC-8). Reads the package's topics, and Core's
+ * guides for the density median a finding names.
+ *
+ * @param {Parameters<typeof findFluff>[0]} discovered the package's docs, as
+ *   discoverIntegrationDocs returns them
+ */
+export function integrationFluff(discovered) {
+  return findFluff(discovered);
+}
+
+/**
+ * Code spans in a package's prose that write `astryx docs <name>` for a doc
+ * that exists, where `{@link generic:<name>}` would be checked
+ * (architecture:cli-surface DEC-8). Reads the package's topics, its own
+ * component docs, and the names of Core's docs.
+ *
+ * @param {Parameters<typeof findStrayPointers>[0]} discovered the package's
+ *   docs, as discoverIntegrationDocs returns them
+ * @param {any} [integration] the loaded integration, whose component docs are
+ *   read too
+ */
+export async function integrationStrayPointers(discovered, integration) {
+  /** @type {{name: string, file: string}[]} */
+  const components = [];
+  if (integration?.components) {
+    const seen = new Set();
+    try {
+      const {components: records} =
+        await discoverValidIntegrationComponents(integration);
+      for (const record of records) {
+        if (!record.docPath || seen.has(record.docPath)) continue;
+        seen.add(record.docPath);
+        components.push({name: record.name, file: record.docPath});
+      }
+    } catch {
+      // `validate` reports component docs that do not load.
+    }
+  }
+  return findStrayPointers({...discovered, components});
+}