@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.2

package/foundation/integrations/computer-integrations.test.mjs

@@ -0,0 +1,292 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Computer-level integrations (spec AST-081 FR12): which install root
+ * counts, which packages in it are integrations, and the peer-range check.
+ */
+
+import {afterEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {
+  computerInstallRoot,
+  computerInstallRoots,
+  loadComputerIntegrations,
+  peerProblem,
+  scanComputerIntegrations,
+} from './computer-integrations.mjs';
+import {
+  cleanupFixtures,
+  tempDir,
+  writeJson,
+} from '../../test-utils/release-fixtures.mjs';
+
+afterEach(cleanupFixtures);
+
+/**
+ * A package at `dir`, with a manifest when `manifest` is set.
+ * @param {string} dir
+ * @param {Record<string, unknown>} pkg
+ * @param {string | null} [manifest]
+ */
+function pkgAt(dir, pkg, manifest = 'export default {};\n') {
+  writeJson(path.join(dir, 'package.json'), pkg);
+  if (manifest != null) {
+    fs.writeFileSync(path.join(dir, 'astryx.integration.mjs'), manifest);
+  }
+  return dir;
+}
+
+/** An npm-style global folder (no package.json) holding the CLI and others. */
+function npmGlobal() {
+  const root = path.join(tempDir('prefix'), 'lib');
+  const modules = path.join(root, 'node_modules');
+  const cli = pkgAt(
+    path.join(modules, '@astryxdesign', 'cli'),
+    {name: '@astryxdesign/cli', version: '0.8.0'},
+    null,
+  );
+  pkgAt(path.join(modules, '@astryxdesign', 'core'), {
+    name: '@astryxdesign/core',
+    version: '0.8.0',
+  });
+  pkgAt(path.join(modules, '@acme', 'widgets'), {
+    name: '@acme/widgets',
+    version: '1.2.0',
+    description: 'Acme widgets',
+  });
+  pkgAt(path.join(modules, 'plain-tool'), {name: 'plain-tool'}, null);
+  pkgAt(path.join(modules, 'zeta-kit'), {
+    name: 'zeta-kit',
+    version: '2.0.0',
+    peerDependencies: {'@astryxdesign/core': '>=9.0.0'},
+  });
+  return {root, cli};
+}
+
+describe('computerInstallRoot', () => {
+  it('is the folder whose node_modules holds the CLI; none for a runner cache or a folder outside node_modules', () => {
+    const {root, cli} = npmGlobal();
+    expect(computerInstallRoot(cli)).toBe(fs.realpathSync(root));
+    const runner = pkgAt(
+      path.join(
+        tempDir('npx'),
+        '_npx',
+        'ab12',
+        'node_modules',
+        '@astryxdesign',
+        'cli',
+      ),
+      {name: '@astryxdesign/cli', version: '0.8.0'},
+      null,
+    );
+    expect(computerInstallRoot(runner)).toBeNull();
+    expect(computerInstallRoot(tempDir('checkout'))).toBeNull();
+  });
+
+  it('is none for a release in the per-user release cache', () => {
+    const cacheDir = tempDir('cache');
+    const cli = pkgAt(
+      path.join(
+        cacheDir,
+        'releases',
+        '0.8.0',
+        'node_modules',
+        '@astryxdesign',
+        'cli',
+      ),
+      {name: '@astryxdesign/cli', version: '0.8.0'},
+      null,
+    );
+    expect(computerInstallRoot(cli, {cacheDir})).toBeNull();
+  });
+});
+
+describe('computerInstallRoots', () => {
+  it("is pnpm's shared global folder before pnpm 11", () => {
+    const g5 = path.join(tempDir('pnpm'), 'global', '5');
+    const cli = pkgAt(
+      path.join(
+        g5,
+        '.pnpm',
+        '@astryxdesign+cli@0.8.0',
+        'node_modules',
+        '@astryxdesign',
+        'cli',
+      ),
+      {name: '@astryxdesign/cli', version: '0.8.0'},
+      null,
+    );
+    expect(computerInstallRoots(cli)).toEqual([fs.realpathSync(g5)]);
+  });
+
+  it('is every pnpm global folder since pnpm 11, when one of them installs this CLI', () => {
+    const home = tempDir('pnpm-home');
+    const cli = pkgAt(
+      path.join(
+        home,
+        'store',
+        'v11',
+        'links',
+        '@astryxdesign',
+        'cli',
+        '0.8.0',
+        'h',
+        'node_modules',
+        '@astryxdesign',
+        'cli',
+      ),
+      {name: '@astryxdesign/cli', version: '0.8.0'},
+      null,
+    );
+    const a = path.join(home, 'global', 'v11', 'a');
+    const b = path.join(home, 'global', 'v11', 'b');
+    writeJson(path.join(b, 'package.json'), {
+      dependencies: {'@acme/widgets': '1.0.0'},
+    });
+    // No global folder installs this CLI yet: only its own install root.
+    expect(computerInstallRoots(cli)).toHaveLength(1);
+    writeJson(path.join(a, 'package.json'), {
+      dependencies: {'@astryxdesign/cli': '0.8.0'},
+    });
+    fs.mkdirSync(path.join(a, 'node_modules', '@astryxdesign'), {
+      recursive: true,
+    });
+    fs.symlinkSync(cli, path.join(a, 'node_modules', '@astryxdesign', 'cli'));
+    expect(computerInstallRoots(cli)).toEqual([a, b]);
+  });
+
+  it("is every pnpm global folder when the CLI's files sit inside its own global folder (pnpm 12)", () => {
+    const globalDir = path.join(tempDir('pnpm12'), 'global', 'v11');
+    const a = path.join(globalDir, 'a');
+    const b = path.join(globalDir, 'b');
+    writeJson(path.join(a, 'package.json'), {
+      dependencies: {'@astryxdesign/cli': '0.8.0'},
+    });
+    const cli = pkgAt(
+      path.join(
+        a,
+        'node_modules',
+        '.pnpm',
+        '@astryxdesign+cli@0.8.0',
+        'node_modules',
+        '@astryxdesign',
+        'cli',
+      ),
+      {name: '@astryxdesign/cli', version: '0.8.0'},
+      null,
+    );
+    fs.mkdirSync(path.join(a, 'node_modules', '@astryxdesign'), {
+      recursive: true,
+    });
+    fs.symlinkSync(cli, path.join(a, 'node_modules', '@astryxdesign', 'cli'));
+    writeJson(path.join(b, 'package.json'), {
+      dependencies: {'@acme/widgets': '1.0.0'},
+    });
+    pkgAt(path.join(b, 'node_modules', '@acme', 'widgets'), {
+      name: '@acme/widgets',
+      version: '1.0.0',
+    });
+    expect(computerInstallRoots(cli)).toEqual([
+      fs.realpathSync(a),
+      fs.realpathSync(b),
+    ]);
+    expect(
+      scanComputerIntegrations({cliRoot: cli, release: '0.8.0'}).map(
+        c => c.name,
+      ),
+    ).toEqual(['@acme/widgets']);
+  });
+});
+
+describe('scanComputerIntegrations', () => {
+  it('lists every package beside the CLI that ships a manifest, never the CLI or Core, and marks an incompatible one', () => {
+    const {cli} = npmGlobal();
+    const found = scanComputerIntegrations({cliRoot: cli, release: '0.8.0'});
+    expect(found.map(c => [c.name, c.version, c.incompatible])).toEqual([
+      ['@acme/widgets', '1.2.0', null],
+      [
+        'zeta-kit',
+        '2.0.0',
+        "it needs @astryxdesign/core >=9.0.0, and this computer's CLI is 0.8.0",
+      ],
+    ]);
+    expect(found[0].description).toBe('Acme widgets');
+  });
+
+  it("reads a door's package set from the root's declared dependencies", () => {
+    const root = tempDir('runtime');
+    writeJson(path.join(root, 'package.json'), {
+      name: 'runtime',
+      private: true,
+      dependencies: {
+        '@astryxdesign/cli': '0.8.0',
+        '@astryxdesign/core': '0.8.0',
+        '@acme/meta-kit': '3.0.0',
+      },
+    });
+    const modules = path.join(root, 'node_modules');
+    const cli = pkgAt(
+      path.join(modules, '@astryxdesign', 'cli'),
+      {name: '@astryxdesign/cli', version: '0.8.0'},
+      null,
+    );
+    pkgAt(path.join(modules, '@acme', 'meta-kit'), {
+      name: '@acme/meta-kit',
+      version: '3.0.0',
+    });
+    // Installed but not declared: not part of the set.
+    pkgAt(path.join(modules, 'stray-kit'), {name: 'stray-kit'});
+    expect(
+      scanComputerIntegrations({cliRoot: cli, release: '0.8.0'}).map(
+        c => c.name,
+      ),
+    ).toEqual(['@acme/meta-kit']);
+  });
+
+  it('lists nothing for a copy with no install root', () => {
+    expect(
+      scanComputerIntegrations({
+        cliRoot: tempDir('checkout'),
+        release: '0.8.0',
+      }),
+    ).toEqual([]);
+  });
+});
+
+describe('peerProblem', () => {
+  it('checks the Core and CLI peer ranges against the answering release', () => {
+    expect(peerProblem({}, '0.8.0')).toBeNull();
+    expect(
+      peerProblem(
+        {peerDependencies: {'@astryxdesign/core': '^0.8.0'}},
+        '0.8.2',
+      ),
+    ).toBeNull();
+    expect(
+      peerProblem(
+        {peerDependencies: {'@astryxdesign/cli': '>=0.9.0'}},
+        '0.8.2',
+      ),
+    ).toBe(
+      "it needs @astryxdesign/cli >=0.9.0, and this computer's CLI is 0.8.2",
+    );
+    expect(
+      peerProblem({peerDependencies: {react: '>=99'}}, '0.8.2'),
+    ).toBeNull();
+  });
+});
+
+describe('loadComputerIntegrations', () => {
+  it("loads the compatible ones, marked as the computer's, and leaves out excluded and incompatible ones", async () => {
+    const {cli} = npmGlobal();
+    const found = scanComputerIntegrations({cliRoot: cli, release: '0.8.0'});
+    const loaded = await loadComputerIntegrations(found);
+    expect(loaded.map(c => [c.spec, c.integration?.__computer])).toEqual([
+      ['@acme/widgets', true],
+    ]);
+    expect(
+      await loadComputerIntegrations(found, {exclude: ['@acme/widgets']}),
+    ).toEqual([]);
+  });
+});

package/foundation/integrations/contribution-inventory.d.mts

@@ -95,6 +95,17 @@ export function compareIdentities(local: ContributionIdentities, packed: Contrib
  * @returns {string[]} unregistered PascalCase names
  */
 export function findSourceOnlyCandidates(componentsRoot: string | undefined, registeredNames: string[]): string[];
+/**
+ * Find `.tsx` files directly in a templates root that have no same-stem
+ * template metadata, so template discovery never lists them. Like the
+ * component check, it scans only direct children of the root: a file in a
+ * subfolder may be a helper a template imports. A file with a dotted stem (a
+ * test, story, or similar companion) is never a candidate.
+ *
+ * @param {string|undefined} templatesRoot absolute path
+ * @returns {string[]} basenames of the unpaired sources, sorted
+ */
+export function findTemplateSourceOnlyCandidates(templatesRoot: string | undefined): string[];
 export type FileInventoryRoot = {
     kind: "themes" | "components" | "templates" | "codemods" | "docs";
     /**

package/foundation/integrations/contribution-inventory.mjs

@@ -248,11 +248,16 @@ export async function collectIdentities(loaded) {
   if (loaded.components && fs.existsSync(loaded.components)) {
     try {
       const records = discoverIntegrationComponents(loaded) ?? [];
+      // A family doc backs several records: load it, and report it, once.
+      const loads = new Map();
       for (const record of records) {
+        const first = !loads.has(record.docPath);
+        if (first) loads.set(record.docPath, loadComponentDoc(record.docPath));
         try {
-          await loadComponentDoc(record.docPath);
+          await loads.get(record.docPath);
           identities.components.push(record.name);
         } catch (err) {
+          if (!first) continue;
           errors.push({
             kind: 'components',
             message: `${path.relative(loaded.components, record.docPath)}: ${
@@ -314,8 +319,11 @@ export async function collectIdentities(loaded) {
 
   if (loaded.docs && fs.existsSync(loaded.docs)) {
     try {
-      const {records, guides, errors: docErrors} =
-        await discoverIntegrationDocs(loaded);
+      const {
+        records,
+        guides,
+        errors: docErrors,
+      } = await discoverIntegrationDocs(loaded);
       for (const docError of docErrors) {
         errors.push({kind: 'docs', message: docError.message});
       }
@@ -498,3 +506,48 @@ export function findSourceOnlyCandidates(componentsRoot, registeredNames) {
   }
   return candidates.sort();
 }
+
+/**
+ * Metadata suffixes that pair a template source with its spec: the canonical
+ * `.doc.*` family and the released `.template.*` compatibility family.
+ */
+const TEMPLATE_DOC_SUFFIXES = [
+  '.doc.ts',
+  '.doc.mjs',
+  '.doc.js',
+  '.template.ts',
+  '.template.mjs',
+  '.template.js',
+];
+
+/** A `.tsx` source and its stem, which may hold a dot (`landing.page`). */
+const TSX_SOURCE = /^(.+)\.tsx$/u;
+
+/** A test, spec or story stem: never a template. */
+const NOT_A_TEMPLATE = /\.(?:test|spec|stories)$/u;
+
+/**
+ * Find `.tsx` files directly in a templates root that have no same-stem
+ * template metadata, so template discovery never lists them. Like the
+ * component check, it scans only direct children of the root: a file in a
+ * subfolder may be a helper a template imports. A file with a dotted stem (a
+ * test, story, or similar companion) is never a candidate.
+ *
+ * @param {string|undefined} templatesRoot absolute path
+ * @returns {string[]} basenames of the unpaired sources, sorted
+ */
+export function findTemplateSourceOnlyCandidates(templatesRoot) {
+  if (!templatesRoot || !fs.existsSync(templatesRoot)) return [];
+  /** @type {string[]} */
+  const candidates = [];
+  for (const entry of fs.readdirSync(templatesRoot, {withFileTypes: true})) {
+    if (!entry.isFile() && !entry.isSymbolicLink()) continue;
+    const match = entry.name.match(TSX_SOURCE);
+    if (!match || NOT_A_TEMPLATE.test(match[1])) continue;
+    const paired = TEMPLATE_DOC_SUFFIXES.some(suffix =>
+      fs.existsSync(path.join(templatesRoot, `${match[1]}${suffix}`)),
+    );
+    if (!paired) candidates.push(entry.name);
+  }
+  return candidates.sort();
+}

package/foundation/integrations/integration-warnings.mjs

@@ -21,6 +21,7 @@
  */
 
 import {validateLoadedIntegration} from './validate-contributions.mjs';
+import {formatCliCommand} from '../env/package-manager.mjs';
 
 /**
  * For each configured (already-loaded) integration, compute its issues using
@@ -81,8 +82,8 @@ export async function warnOnIntegrationIssues(source, {json = false} = {}) {
 
     for (const [pkg, count] of issueCounts) {
       const command = fromProject
-        ? 'astryx doctor'
-        : `astryx doctor integration validate ${pkg}`;
+        ? formatCliCommand('doctor')
+        : formatCliCommand(`doctor integration validate ${pkg}`);
       console.error(
         `Warning: ${pkg} has ${count} integration issue(s). Run: ${command}`,
       );

package/foundation/integrations/integration-warnings.test.mjs

@@ -61,9 +61,8 @@ describe('warnOnIntegrationIssues', () => {
     await warnOnIntegrationIssues([integration], {json: false});
 
     expect(errLines).toHaveLength(1);
-    expect(errLines[0]).toBe(
-      'Warning: @acme/widgets has 1 integration issue(s). ' +
-        'Run: astryx doctor integration validate @acme/widgets',
+    expect(errLines[0]).toMatch(
+      /^Warning: @acme\/widgets has 1 integration issue\(s\)\. Run: .+ doctor integration validate @acme\/widgets$/,
     );
   });
 
@@ -81,9 +80,10 @@ describe('warnOnIntegrationIssues', () => {
 
     await warnOnIntegrationIssues(project, {json: false});
 
-    expect(errLines).toEqual([
-      'Warning: @acme/later has 1 integration issue(s). Run: astryx doctor',
-    ]);
+    expect(errLines).toHaveLength(1);
+    expect(errLines[0]).toMatch(
+      /^Warning: @acme\/later has 1 integration issue\(s\)\. Run: .+ doctor$/,
+    );
   });
 
   it('emits nothing in --json mode (keeps stdout/JSON clean)', async () => {
@@ -103,9 +103,8 @@ describe('warnOnIntegrationIssues', () => {
     await warnOnIntegrationIssues([integration], {json: false});
 
     expect(errLines).toHaveLength(1);
-    expect(errLines[0]).toBe(
-      'Warning: @acme/stale has 1 integration issue(s). ' +
-        'Run: astryx doctor integration validate @acme/stale',
+    expect(errLines[0]).toMatch(
+      /^Warning: @acme\/stale has 1 integration issue\(s\)\. Run: .+ doctor integration validate @acme\/stale$/,
     );
   });
 

package/foundation/integrations/integrations.d.mts

@@ -45,7 +45,7 @@ export function findManifestPaths(dir: string): string[];
  * @param {string} file absolute manifest path
  * @param {string} [label] used in error messages
  * @param {{fresh?: boolean}} [options]
- * @returns {Promise<{manifest: import('../../authoring/integration/type').AstryxIntegration, unknownKeys: string[], debug?: import('../../authoring/debug/type').DebugEventHandler, gapReport?: import('../../authoring/gap-report/type').GapReportHandler, gapReportError?: string, discover?: import('../../authoring/discover/type').DiscoverSource, discoverError?: string, agentDocsError?: string}>}
+ * @returns {Promise<{manifest: import('../../authoring/integration/type').AstryxIntegration, unknownKeys: string[], debug?: import('../../authoring/debug/type').DebugEventHandler, gapReport?: import('../../authoring/gap-report/type').GapReportHandler, gapReportError?: string, discover?: import('../../authoring/discover/type').DiscoverSource, discoverError?: string, agentDocsError?: string, cliCommandError?: string}>}
  */
 export function loadManifest(file: string, label?: string, { fresh }?: {
     fresh?: boolean;
@@ -58,6 +58,7 @@ export function loadManifest(file: string, label?: string, { fresh }?: {
     discover?: import("../../authoring/discover/type").DiscoverSource;
     discoverError?: string;
     agentDocsError?: string;
+    cliCommandError?: string;
 }>;
 /**
  * Load and validate a manifest module's default export against the integration
@@ -126,6 +127,10 @@ export function loadIntegrations(specs?: string[], { cwd, fresh, resolveProvider
  * @property {string} [themes]
  * @property {string} [issuesUrl]
  * @property {{append?: readonly string[]}} [agentDocs]
+ * @property {string} [cliCommand] the command this package's users run the
+ *   CLI with; read by the picker in foundation/env (see cli-command.mjs)
+ * @property {string} [__cliCommandError] why a declared `cliCommand` was
+ *   ignored; the rest of the manifest still contributes
  * @property {string} [__agentDocsError] contribution-specific validation
  *   failure; other manifest contributions remain available
  * @property {string} __spec
@@ -145,6 +150,9 @@ export function loadIntegrations(specs?: string[], { cwd, fresh, resolveProvider
  * @property {boolean} [__autolinked] loaded because the project declares the
  *   package as a dependency and it ships a manifest, with no astryx.config
  *   entry naming it — see foundation/integrations/autolink.mjs
+ * @property {boolean} [__computer] loaded because it is installed beside the
+ *   running CLI and the folder is outside a project (spec AST-081 FR12) — see
+ *   foundation/integrations/computer-integrations.mjs
  * @property {boolean} [__local] loaded from the package containing the current
  *   working directory, so an author sees the exact bytes they are editing
  * @property {string} [__dependencyField] for an autolinked integration, the
@@ -186,6 +194,16 @@ export type LoadedIntegration = {
     agentDocs?: {
         append?: readonly string[];
     } | undefined;
+    /**
+     * the command this package's users run the
+     * CLI with; read by the picker in foundation/env (see cli-command.mjs)
+     */
+    cliCommand?: string | undefined;
+    /**
+     * why a declared `cliCommand` was
+     * ignored; the rest of the manifest still contributes
+     */
+    __cliCommandError?: string | undefined;
     /**
      * contribution-specific validation
      * failure; other manifest contributions remain available
@@ -226,6 +244,12 @@ export type LoadedIntegration = {
      * entry naming it — see foundation/integrations/autolink.mjs
      */
     __autolinked?: boolean | undefined;
+    /**
+     * loaded because it is installed beside the
+     * running CLI and the folder is outside a project (spec AST-081 FR12) — see
+     * foundation/integrations/computer-integrations.mjs
+     */
+    __computer?: boolean | undefined;
     /**
      * loaded from the package containing the current
      * working directory, so an author sees the exact bytes they are editing

package/foundation/integrations/integrations.mjs

@@ -6,7 +6,8 @@
  * Integrations are PACKAGE NAMES listed in astryx.config.{ts,mjs,js}. Each
  * package declares a single conventional root manifest sibling to its
  * package.json — astryx.integration.{ts,mjs,js} — which contributes
- * components/templates/codemods/docs/themes roots and an optional issuesUrl.
+ * components/templates/codemods/docs/themes roots, an optional issuesUrl, and
+ * an optional cliCommand.
  * Stable provider identity and package metadata come from package.json, not the
  * manifest.
  *
@@ -24,6 +25,7 @@ import {normalizeProviderId} from '../identity/provider-identity.mjs';
 // the loader can isolate an invalid optional contribution from valid roots.
 import {
   parseAgentDocsField,
+  parseCliCommandField,
   parseIntegrationBase,
   unknownIntegrationKeys,
 } from '../../authoring/integration/schema.mjs';
@@ -51,6 +53,10 @@ import {resolveProviders} from './provider-resolution.mjs';
  * @property {string} [themes]
  * @property {string} [issuesUrl]
  * @property {{append?: readonly string[]}} [agentDocs]
+ * @property {string} [cliCommand] the command this package's users run the
+ *   CLI with; read by the picker in foundation/env (see cli-command.mjs)
+ * @property {string} [__cliCommandError] why a declared `cliCommand` was
+ *   ignored; the rest of the manifest still contributes
  * @property {string} [__agentDocsError] contribution-specific validation
  *   failure; other manifest contributions remain available
  * @property {string} __spec
@@ -70,6 +76,9 @@ import {resolveProviders} from './provider-resolution.mjs';
  * @property {boolean} [__autolinked] loaded because the project declares the
  *   package as a dependency and it ships a manifest, with no astryx.config
  *   entry naming it — see foundation/integrations/autolink.mjs
+ * @property {boolean} [__computer] loaded because it is installed beside the
+ *   running CLI and the folder is outside a project (spec AST-081 FR12) — see
+ *   foundation/integrations/computer-integrations.mjs
  * @property {boolean} [__local] loaded from the package containing the current
  *   working directory, so an author sees the exact bytes they are editing
  * @property {string} [__dependencyField] for an autolinked integration, the
@@ -204,7 +213,7 @@ function parseDiscoverSourceExport(value, label) {
  * @param {string} file absolute manifest path
  * @param {string} [label] used in error messages
  * @param {{fresh?: boolean}} [options]
- * @returns {Promise<{manifest: import('../../authoring/integration/type').AstryxIntegration, unknownKeys: string[], debug?: import('../../authoring/debug/type').DebugEventHandler, gapReport?: import('../../authoring/gap-report/type').GapReportHandler, gapReportError?: string, discover?: import('../../authoring/discover/type').DiscoverSource, discoverError?: string, agentDocsError?: string}>}
+ * @returns {Promise<{manifest: import('../../authoring/integration/type').AstryxIntegration, unknownKeys: string[], debug?: import('../../authoring/debug/type').DebugEventHandler, gapReport?: import('../../authoring/gap-report/type').GapReportHandler, gapReportError?: string, discover?: import('../../authoring/discover/type').DiscoverSource, discoverError?: string, agentDocsError?: string, cliCommandError?: string}>}
  */
 export async function loadManifest(
   file,
@@ -239,8 +248,31 @@ export async function loadManifest(
     }
   }
 
+  /** @type {string | undefined} */
+  let cliCommand;
+  /** @type {string | undefined} */
+  let cliCommandError;
+  const rawCliCommand =
+    raw != null && typeof raw === 'object' && !Array.isArray(raw)
+      ? /** @type {{cliCommand?: unknown}} */ (raw).cliCommand
+      : undefined;
+  if (rawCliCommand !== undefined) {
+    try {
+      cliCommand = parseCliCommandField(
+        rawCliCommand,
+        `${label} field "cliCommand"`,
+      );
+    } catch (err) {
+      cliCommandError = err instanceof Error ? err.message : String(err);
+    }
+  }
+
   return {
-    manifest: agentDocs == null ? baseManifest : {...baseManifest, agentDocs},
+    manifest: {
+      ...baseManifest,
+      ...(agentDocs == null ? {} : {agentDocs}),
+      ...(cliCommand == null ? {} : {cliCommand}),
+    },
     unknownKeys: unknownIntegrationKeys(raw),
     debug:
       typeof mod?.debug === 'function'
@@ -253,6 +285,7 @@ export async function loadManifest(
     discover: discover.source,
     discoverError: discover.error,
     agentDocsError,
+    cliCommandError,
   };
 }
 
@@ -375,6 +408,8 @@ export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
   let discoverError;
   /** @type {string | undefined} */
   let agentDocsError;
+  /** @type {string | undefined} */
+  let cliCommandError;
   try {
     ({
       manifest,
@@ -385,6 +420,7 @@ export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
       discover: discoverSource,
       discoverError,
       agentDocsError,
+      cliCommandError,
     } = await loadManifest(manifestFile, `Integration ${spec}`, {fresh}));
   } catch (err) {
     return {
@@ -422,6 +458,8 @@ export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
     themes: resolveRoot(manifest.themes),
     issuesUrl: manifest.issuesUrl,
     agentDocs: manifest.agentDocs,
+    cliCommand: manifest.cliCommand,
+    __cliCommandError: cliCommandError,
     __agentDocsError: agentDocsError,
     __unknownKeys: unknownKeys,
     __debug: debugHandler,
@@ -486,6 +524,8 @@ export async function loadIntegrations(
     let discoverError;
     /** @type {string | undefined} */
     let agentDocsError;
+    /** @type {string | undefined} */
+    let cliCommandError;
     try {
       ({
         manifest,
@@ -496,6 +536,7 @@ export async function loadIntegrations(
         discover: discoverSource,
         discoverError,
         agentDocsError,
+        cliCommandError,
       } = await loadManifest(manifestFile, `Integration ${spec}`, {fresh}));
     } catch (err) {
       // A manifest that throws on import or fails schema validation must NOT take
@@ -540,6 +581,8 @@ export async function loadIntegrations(
       themes: resolveRoot(manifest.themes),
       issuesUrl: manifest.issuesUrl,
       agentDocs: manifest.agentDocs,
+      cliCommand: manifest.cliCommand,
+      __cliCommandError: cliCommandError,
       __agentDocsError: agentDocsError,
       __unknownKeys: unknownKeys,
       __debug: debugHandler,

package/foundation/integrations/issue.ts

@@ -15,4 +15,10 @@ export interface AstryxIntegrationIssue {
   code: string;
   severity: 'warning' | 'error';
   message: string;
+  /** What to change, ready to paste, when the check knows it. */
+  fix?: string;
+  /** The file the issue is in, relative to the package. */
+  file?: string;
+  /** The 1-based line in `file`, when the check can locate it. */
+  line?: number;
 }

package/foundation/integrations/validate-contributions.d.mts

@@ -38,6 +38,8 @@ export function validateLoadedIntegration(loaded: LoadedIntegration): Promise<Is
  */
 /** Stable issue code for an invalid optional agent-doc contribution. */
 export const INVALID_AGENT_DOCS: "invalid_agent_docs";
+/** Stable issue code for a `cliCommand` that was ignored as invalid. */
+export const INVALID_CLI_COMMAND: "invalid_cli_command";
 /** Stable issue code for a package whose provider ID is already claimed. */
 export const DUPLICATE_PROVIDER: "duplicate_provider";
 export type Issue = import("./issue").AstryxIntegrationIssue;