@astryxdesign/cli 0.7.2-canary.fdd384f → 0.7.2

package/api/doctor/_adapter.d.mts

@@ -43,8 +43,116 @@ export function findDoctorInstalledPackage(projectDir: string, packageName: stri
 export function listDoctorThemePackages(cwd: string): string[];
 /** @param {string} file */
 export function readPackageJson(file: string): any;
+/**
+ * The integrations installed for the computer, and, outside a project, which
+ * of them the folder loads (spec AST-081 FR12): those it uses, and the names
+ * of the integrations the folder loads itself, whose copies win.
+ * @param {string} cwd
+ * @returns {Promise<{computerIntegrations: import('../../foundation/integrations/computer-integrations.mjs').ComputerIntegrationCandidate[], loadedComputerIntegrations: string[], folderIntegrations: string[]}>}
+ */
+export function computerIntegrationsOutside(cwd: string): Promise<{
+    computerIntegrations: import("../../foundation/integrations/computer-integrations.mjs").ComputerIntegrationCandidate[];
+    loadedComputerIntegrations: string[];
+    folderIntegrations: string[];
+}>;
+/**
+ * Inside a project: the integrations installed for the computer it could add
+ * (spec AST-081 FR12), leaving out every package it loads or declares.
+ * @param {string} cwd
+ * @param {string[]} loadedNames the integrations the project loads
+ * @returns {Promise<import('../../foundation/integrations/computer-integrations.mjs').ComputerIntegrationCandidate[]>}
+ */
+export function computerIntegrationsToAdd(cwd: string, loadedNames: string[]): Promise<import("../../foundation/integrations/computer-integrations.mjs").ComputerIntegrationCandidate[]>;
+/**
+ * The computer-level agent text's setting and its state on disk.
+ * @returns {{settings: import('../../foundation/env/user-settings.mjs').ComputerAgentTextSettings, entries: Array<{path: string, state: import('../../foundation/agent-docs/computer-agent-text.mjs').ComputerAgentTextState, link?: true}>}}
+ */
+export function computerAgentTextState(): {
+    settings: import("../../foundation/env/user-settings.mjs").ComputerAgentTextSettings;
+    entries: Array<{
+        path: string;
+        state: import("../../foundation/agent-docs/computer-agent-text.mjs").ComputerAgentTextState;
+        link?: true;
+    }>;
+};
+/**
+ * The release facts doctor reports, read here so the checks stay pure
+ * (spec AST-081 FR5, FR6, FR10; architecture:cli-surface INV21): who
+ * answered, the newest release the computer knows of, how far the global copy
+ * or the project is behind, and every `astryx` on the search path with the
+ * command that upgrades it.
+ * @param {string} cwd
+ * @param {{project: boolean}} options
+ * @returns {{answeredBy: {cli: string, core: string | null, copy: string}, latest: string | null, globalBehind: ReturnType<typeof globalBehind> | null, projectLag: ReturnType<typeof projectLag> | null, lastNoticeSkip: ReturnType<typeof lastNoticeSkip>, lastCheckFailure: ReturnType<typeof lastCheckFailure>, stateLock: ReturnType<typeof stateLockHolder>, searchPathCommands: Array<import('../../foundation/env/search-path.mjs').SearchPathCommand & {upgrade: string | null}>}}
+ */
+export function releaseFacts(cwd: string, { project }: {
+    project: boolean;
+}): {
+    answeredBy: {
+        cli: string;
+        core: string | null;
+        copy: string;
+    };
+    latest: string | null;
+    globalBehind: ReturnType<typeof globalBehind> | null;
+    projectLag: ReturnType<typeof projectLag> | null;
+    lastNoticeSkip: ReturnType<typeof lastNoticeSkip>;
+    lastCheckFailure: ReturnType<typeof lastCheckFailure>;
+    stateLock: ReturnType<typeof stateLockHolder>;
+    searchPathCommands: Array<import("../../foundation/env/search-path.mjs").SearchPathCommand & {
+        upgrade: string | null;
+    }>;
+};
+/** Whether `cwd` is outside every project. */
+export function outsideProject(cwd: string): boolean;
+/**
+ * The commands that bring a project's own CLI and Core to one release, with
+ * the project's package manager: Core up to the CLI, then its codemods, when
+ * the CLI is newer; else the CLI to the Core's release.
+ * @param {string} cwd
+ * @param {string} cli
+ * @param {string} core
+ * @returns {string}
+ */
+export function alignCommand(cwd: string, cli: string, core: string): string;
+/**
+ * The Core release the project at `cwd` names: installed, else locked, else
+ * declared; the version the daily hint and notice compare against (spec
+ * AST-081 FR2). Null outside a project or when it names none.
+ * @param {string} cwd
+ * @returns {string | null}
+ */
+export function projectCoreVersion(cwd: string): string | null;
+/**
+ * Whether the project at `cwd` installs its own CLI (spec AST-081 FR2).
+ * @param {string} cwd
+ * @returns {boolean}
+ */
+export function projectHasOwnCli(cwd: string): boolean;
+/**
+ * The command that adds the CLI at `version` with the project's package
+ * manager.
+ * @param {string} cwd
+ * @param {string} version
+ * @returns {string}
+ */
+export function addCliCommandFor(cwd: string, version: string): string;
+/**
+ * The command that adds a package with the folder's package manager, read
+ * from its lockfiles and `packageManager` field.
+ * @param {string} cwd
+ * @returns {(name: string) => string}
+ */
+export function installCommandFor(cwd: string): (name: string) => string;
 export { resolveRecordedTheme } from "../theme/theme.mjs";
 export { collectUnloadedFonts } from "../theme/build/font-warning.mjs";
 export const SOURCE_EXTENSIONS: Set<string>;
+export { displayHomePath };
+import { globalBehind } from '../../foundation/release/notices.mjs';
+import { projectLag } from '../../foundation/release/notices.mjs';
+import { lastNoticeSkip } from '../../foundation/release/notices.mjs';
+import { lastCheckFailure } from '../../foundation/release/global-state.mjs';
+import { stateLockHolder } from '../../foundation/release/global-state.mjs';
+import { displayHomePath } from '../../foundation/agent-docs/computer-agent-text.mjs';
 export { isLocalThemeOwner, planThemeAppWrite, readThemeState, resolveThemeModule } from "../../foundation/config/theme-state.mjs";
 export { themeBuild, validateThemePrivateInputs } from "../theme/build/build.mjs";

package/api/doctor/_adapter.mjs

@@ -2,15 +2,52 @@
 
 /** @file Environment adapter for app-theme doctor evidence. */
 
+import {isOutsideProject} from '../../foundation/env/project-scope.mjs';
+import {answeredBy} from '../../foundation/release/run-context.mjs';
+import {
+  knownLatestRelease,
+  lastCheckFailure,
+  stateLockHolder,
+} from '../../foundation/release/global-state.mjs';
+import {
+  addCliCommand,
+  alignCliAndCore,
+  globalBehind,
+  globalUpgradeCommand,
+  lastNoticeSkip,
+  projectLag,
+} from '../../foundation/release/notices.mjs';
+import {
+  coreVersionOf,
+  isGlobalCopy,
+  projectRootOf,
+} from '../../foundation/release/choose.mjs';
+import {readReleaseFacts} from '../../foundation/release/project.mjs';
+import {detectPackageManager} from '../../foundation/env/package-manager.mjs';
+import {astryxCommandsOnSearchPath} from '../../foundation/env/search-path.mjs';
+import {readDeclaredDependencies} from '../../foundation/integrations/autolink.mjs';
+import {
+  displayHomePath,
+  inspectComputerAgentText,
+} from '../../foundation/agent-docs/computer-agent-text.mjs';
+import {computerAgentTextSettings} from '../../foundation/env/user-settings.mjs';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import {Project} from '../../foundation/config/project.mjs';
+import {
+  Project,
+  availableComputerIntegrations,
+  computerIntegrationCandidates,
+} from '../../foundation/config/project.mjs';
 import {
   discoverUnmigratedThemeCopies,
   themeImportPackage,
 } from '../../foundation/discovery/theme-discovery.mjs';
 import {resolveThemeImports} from '../../foundation/discovery/theme-imports.mjs';
-import {findCoreDir, findInstalledPackage} from '../../foundation/fs/paths.mjs';
+import {
+  CLI_ROOT,
+  findProjectCoreDir,
+  findInstalledPackage,
+} from '../../foundation/fs/paths.mjs';
 export {
   isLocalThemeOwner,
   planThemeAppWrite,
@@ -104,7 +141,7 @@ export function listProjectSourceFiles(root, generatedModule) {
 
 /** @param {string} projectDir */
 export async function discoverDoctorThemes(projectDir) {
-  const project = await Project.load(projectDir);
+  const project = await Project.load(projectDir, {core: 'project'});
   return project.themes();
 }
 
@@ -124,7 +161,7 @@ export function discoverDoctorUnmigratedCopies(projectDir) {
 
 /** @param {string} projectDir */
 export function findDoctorCoreDir(projectDir) {
-  return findCoreDir(projectDir);
+  return findProjectCoreDir(projectDir);
 }
 
 /** @param {string} projectDir @param {string} packageName */
@@ -188,3 +225,185 @@ export function readPackageJson(file) {
     return null;
   }
 }
+
+/**
+ * The integrations installed for the computer, and, outside a project, which
+ * of them the folder loads (spec AST-081 FR12): those it uses, and the names
+ * of the integrations the folder loads itself, whose copies win.
+ * @param {string} cwd
+ * @returns {Promise<{computerIntegrations: import('../../foundation/integrations/computer-integrations.mjs').ComputerIntegrationCandidate[], loadedComputerIntegrations: string[], folderIntegrations: string[]}>}
+ */
+export async function computerIntegrationsOutside(cwd) {
+  const computerIntegrations = computerIntegrationCandidates(cwd);
+  if (computerIntegrations.length === 0) {
+    return {
+      computerIntegrations,
+      loadedComputerIntegrations: [],
+      folderIntegrations: [],
+    };
+  }
+  try {
+    const project = await Project.load(cwd, {core: 'project'});
+    /** @type {Array<{name: string, __computer?: boolean, __loadError?: string}>} */
+    const loaded = project.loadedIntegrations;
+    return {
+      computerIntegrations,
+      loadedComputerIntegrations: loaded
+        .filter(i => i.__computer && !i.__loadError)
+        .map(i => i.name),
+      folderIntegrations: loaded.filter(i => !i.__computer).map(i => i.name),
+    };
+  } catch {
+    return {
+      computerIntegrations,
+      loadedComputerIntegrations: [],
+      folderIntegrations: [],
+    };
+  }
+}
+
+/**
+ * Inside a project: the integrations installed for the computer it could add
+ * (spec AST-081 FR12), leaving out every package it loads or declares.
+ * @param {string} cwd
+ * @param {string[]} loadedNames the integrations the project loads
+ * @returns {Promise<import('../../foundation/integrations/computer-integrations.mjs').ComputerIntegrationCandidate[]>}
+ */
+export async function computerIntegrationsToAdd(cwd, loadedNames) {
+  const installed = new Set([...loadedNames, ...declaredPackageNames(cwd)]);
+  return availableComputerIntegrations(cwd, installed);
+}
+
+/**
+ * The package names the folder's package.json declares, nearest first.
+ * @param {string} cwd
+ * @returns {string[]}
+ */
+function declaredPackageNames(cwd) {
+  for (let dir = path.resolve(cwd); ;) {
+    if (fs.existsSync(path.join(dir, 'package.json'))) {
+      return readDeclaredDependencies(dir).map(d => d.name);
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return [];
+    dir = parent;
+  }
+}
+
+/**
+ * The computer-level agent text's setting and its state on disk.
+ * @returns {{settings: import('../../foundation/env/user-settings.mjs').ComputerAgentTextSettings, entries: Array<{path: string, state: import('../../foundation/agent-docs/computer-agent-text.mjs').ComputerAgentTextState, link?: true}>}}
+ */
+export function computerAgentTextState() {
+  const settings = computerAgentTextSettings();
+  return {settings, entries: inspectComputerAgentText({links: settings.links})};
+}
+
+export {displayHomePath};
+
+/**
+ * The release facts doctor reports, read here so the checks stay pure
+ * (spec AST-081 FR5, FR6, FR10; architecture:cli-surface INV21): who
+ * answered, the newest release the computer knows of, how far the global copy
+ * or the project is behind, and every `astryx` on the search path with the
+ * command that upgrades it.
+ * @param {string} cwd
+ * @param {{project: boolean}} options
+ * @returns {{answeredBy: {cli: string, core: string | null, copy: string}, latest: string | null, globalBehind: ReturnType<typeof globalBehind> | null, projectLag: ReturnType<typeof projectLag> | null, lastNoticeSkip: ReturnType<typeof lastNoticeSkip>, lastCheckFailure: ReturnType<typeof lastCheckFailure>, stateLock: ReturnType<typeof stateLockHolder>, searchPathCommands: Array<import('../../foundation/env/search-path.mjs').SearchPathCommand & {upgrade: string | null}>}}
+ */
+export function releaseFacts(cwd, {project}) {
+  const answered = answeredBy(cwd);
+  return {
+    answeredBy: answered,
+    latest: knownLatestRelease(),
+    lastNoticeSkip: lastNoticeSkip(),
+    lastCheckFailure: lastCheckFailure(),
+    stateLock: stateLockHolder(),
+    globalBehind:
+      !project && isGlobalCopy(CLI_ROOT)
+        ? globalBehind({self: {version: answered.cli, root: CLI_ROOT}})
+        : null,
+    // The project's version is its own CLI's, or, with none, its Core's:
+    // installed, else locked, else declared, as the daily notice reads it.
+    projectLag: project
+      ? projectLag({
+          cwd,
+          current:
+            (answered.copy === 'starting' && projectCoreVersion(cwd)) ||
+            answered.cli,
+        })
+      : null,
+    searchPathCommands: astryxCommandsOnSearchPath().map(row => ({
+      ...row,
+      upgrade: row.cliRoot ? globalUpgradeCommand(row.cliRoot) : null,
+    })),
+  };
+}
+
+/** Whether `cwd` is outside every project. */
+export function outsideProject(/** @type {string} */ cwd) {
+  return isOutsideProject(cwd);
+}
+
+/**
+ * The commands that bring a project's own CLI and Core to one release, with
+ * the project's package manager: Core up to the CLI, then its codemods, when
+ * the CLI is newer; else the CLI to the Core's release.
+ * @param {string} cwd
+ * @param {string} cli
+ * @param {string} core
+ * @returns {string}
+ */
+export function alignCommand(cwd, cli, core) {
+  return alignCliAndCore({cwd, cli, core});
+}
+
+/**
+ * The Core release the project at `cwd` names: installed, else locked, else
+ * declared; the version the daily hint and notice compare against (spec
+ * AST-081 FR2). Null outside a project or when it names none.
+ * @param {string} cwd
+ * @returns {string | null}
+ */
+export function projectCoreVersion(cwd) {
+  return coreVersionOf(readReleaseFacts(cwd));
+}
+
+/**
+ * Whether the project at `cwd` installs its own CLI (spec AST-081 FR2).
+ * @param {string} cwd
+ * @returns {boolean}
+ */
+export function projectHasOwnCli(cwd) {
+  return Boolean(readReleaseFacts(cwd).cli);
+}
+
+/**
+ * The command that adds the CLI at `version` with the project's package
+ * manager.
+ * @param {string} cwd
+ * @param {string} version
+ * @returns {string}
+ */
+export function addCliCommandFor(cwd, version) {
+  return addCliCommand(projectRootOf(readReleaseFacts(cwd)) ?? cwd, version);
+}
+
+/**
+ * The command that adds a package with the folder's package manager, read
+ * from its lockfiles and `packageManager` field.
+ * @param {string} cwd
+ * @returns {(name: string) => string}
+ */
+export function installCommandFor(cwd) {
+  const pm = detectPackageManager(cwd);
+  const verb =
+    pm === 'pnpm'
+      ? 'pnpm add'
+      : pm === 'yarn'
+        ? 'yarn add'
+        : pm === 'bun'
+          ? 'bun add'
+          : 'npm install';
+  return name => `${verb} ${name}`;
+}

package/api/doctor/doctor.d.mts

@@ -168,6 +168,107 @@ export function checkDocsTree(_ctx: DoctorContext | Partial<DoctorContext>, opti
  * @returns {Promise<DoctorCheck>}
  */
 export function checkDocsProgressiveDisclosure(ctx: DoctorContext | Partial<DoctorContext>): Promise<DoctorCheck>;
+/**
+ * Check 11 — the command every printed command starts with, and a warning when
+ * loaded integrations declare different ones (their `cliCommand`). Then the
+ * picker uses neither, so commands fall back to the package-manager guess.
+ *
+ * @param {DoctorContext} ctx
+ * @returns {DoctorCheck}
+ */
+export function checkCliCommand(ctx: DoctorContext): DoctorCheck;
+/**
+ * What a computer check reads: the running Node, the release that answered
+ * (`meta.answeredBy`), and the newest release the computer knows of.
+ * @typedef {object} ComputerContext
+ * @property {string} nodeVersion
+ * @property {{cli: string, core: string | null, copy: string}} answeredBy
+ * @property {string | null} latest the newest release known, or null
+ * @property {Array<{path: string, state: import('../../foundation/agent-docs/computer-agent-text.mjs').ComputerAgentTextState}>} [agentText]
+  *   each file of the computer-level agent text against this release's rendering
+ * @property {import('../../foundation/env/user-settings.mjs').ComputerAgentTextSettings} [agentTextSettings]
+ *   the person's choices about the computer-level agent text
+  * @property {string} [cwd] the folder doctor runs in, for the printed fix
+ * @property {import('../../foundation/release/notices.mjs').GlobalBehind | null} [globalBehind]
+ *   the CLI installed for the computer, when it is older than the newest
+ *   release (outside a project)
+ * @property {import('../../foundation/release/notices.mjs').ProjectLag | null} [projectLag]
+ *   the project's release, when it is behind the newest (inside a project)
+ * @property {{key: string, reason: string, at: number} | null} [lastNoticeSkip]
+ * @property {{at: number, reason: string} | null} [lastCheckFailure] why the
+ *   last update check did not reach the registry, after the last that did
+ *   the newest update notice that did not print, and why (diagnostic only)
+ * @property {{pid: number | null, host: string | null, since: number} | null} [stateLock]
+ *   who holds the state file's lock now (diagnostic only)
+  * @property {Array<import('../../foundation/env/search-path.mjs').SearchPathCommand & {upgrade?: string | null}>} [searchPathCommands]
+ *   every `astryx` on the search path, with the command that upgrades it
+ *   the `astryx` commands on the search path, in order
+ * @property {import('../../foundation/integrations/computer-integrations.mjs').ComputerIntegrationCandidate[]} [computerIntegrations]
+ *   the integrations installed beside the running CLI
+ * @property {string[]} [loadedComputerIntegrations] the names of those that
+ *   loaded outside a project
+ * @property {string[]} [folderIntegrations] the names of the integrations the
+ *   folder loads itself, whose copies win over the computer's
+ */
+/**
+ * The release that answered this run outside a project, and the Core it
+ * reads from.
+ * @param {ComputerContext} ctx
+ * @returns {DoctorCheck}
+ */
+export function checkAnsweringRelease(ctx: ComputerContext): DoctorCheck;
+/**
+ * The newest release this computer knows of, beside the one that answered
+ * (spec AST-081 FR10). Runs inside and outside a project, and is always
+ * info. Inside one, a release behind the newest names the install and
+ * upgrade commands; outside one, a CLI installed for the computer that is
+ * behind names the command of the package manager that installed it, after
+ * the Node it needs when the computer runs an older one. Doctor installs
+ * nothing.
+ * @param {ComputerContext} ctx
+ * @returns {DoctorCheck}
+ */
+export function checkNewestRelease(ctx: ComputerContext): DoctorCheck;
+/**
+ * The `astryx` commands on the search path (spec AST-081 FR11): the first is
+ * the one a shell runs. Warns when it is not the Astryx CLI, or is a release
+ * that predates the hand-off and so answers every folder itself.
+ * @param {ComputerContext} ctx
+ * @returns {DoctorCheck}
+ */
+export function checkCliOnPath(ctx: ComputerContext): DoctorCheck;
+/**
+ * The computer-level agent text (spec AST-081 FR4, FR8): turned off, present
+ * and equal to this release's rendering, present but different, or absent,
+ * for the files the chosen agents read. Always `info`: the text is optional,
+ * so it never warns or fails. A file Astryx did not write counts as absent,
+ * and a file a person edited is named; both are kept as they are.
+ * @param {ComputerContext} ctx
+ * @returns {DoctorCheck}
+ */
+export function checkComputerAgentText(ctx: ComputerContext): DoctorCheck;
+/**
+ * The integrations installed for the computer (spec AST-081 FR12). Outside a
+ * project: each one that loads, and a warning for each that is skipped
+ * because its peer ranges exclude the answering release, or fails to load.
+ * @param {ComputerContext} ctx
+ * @returns {DoctorCheck}
+ */
+export function checkComputerIntegrations(ctx: ComputerContext): DoctorCheck;
+/**
+ * Inside a project, the integrations installed for the computer that the
+ * project does not install: available, never used (spec AST-081 FR12).
+ * Always info.
+ * @param {{installed: Set<string>, candidates: import('../../foundation/integrations/computer-integrations.mjs').ComputerIntegrationCandidate[], install: (name: string) => string}} input
+ *   `install`: the command that adds a package with the project's package
+ *   manager (read by the adapter)
+ * @returns {DoctorCheck}
+ */
+export function checkComputerIntegrationsAvailable({ installed, candidates, install }: {
+    installed: Set<string>;
+    candidates: import("../../foundation/integrations/computer-integrations.mjs").ComputerIntegrationCandidate[];
+    install: (name: string) => string;
+}): DoctorCheck;
 /**
  * Run all diagnostic checks and return a structured report.
  *
@@ -192,6 +293,11 @@ export function doctor(options?: {
     type: "doctor";
     data: DoctorReport;
 }>;
+/**
+ * The checks doctor runs outside a project, in order.
+ * @type {Array<(ctx: ComputerContext) => DoctorCheck>}
+ */
+export const COMPUTER_CHECKS: Array<(ctx: ComputerContext) => DoctorCheck>;
 /**
  * Ordered list of synchronous check functions. Append here to add a check.
  * (checkConfig is async and is awaited separately by {@link runChecks}.)
@@ -240,6 +346,16 @@ export type DoctorContext = {
      * - Resolved core package directory, or null.
      */
     coreDir: string | null;
+    /**
+     * - Whether the project installs its own CLI;
+     * false means the copy that started the run answered it (spec AST-081 FR2).
+     */
+    ownCli?: boolean | undefined;
+    /**
+     * - The Core release the project names
+     * (installed, else locked, else declared), as the daily hint reads it.
+     */
+    projectCore?: string | null | undefined;
     /**
      * - Resolved astryx.config.mjs path, or null.
      */
@@ -301,4 +417,87 @@ export type DoctorContext = {
      */
     projectError?: string | null | undefined;
 };
+/**
+ * What a computer check reads: the running Node, the release that answered
+ * (`meta.answeredBy`), and the newest release the computer knows of.
+ */
+export type ComputerContext = {
+    nodeVersion: string;
+    answeredBy: {
+        cli: string;
+        core: string | null;
+        copy: string;
+    };
+    /**
+     * the newest release known, or null
+     */
+    latest: string | null;
+    /**
+     * each file of the computer-level agent text against this release's rendering
+     */
+    agentText?: {
+        path: string;
+        state: import("../../foundation/agent-docs/computer-agent-text.mjs").ComputerAgentTextState;
+    }[] | undefined;
+    /**
+     * the person's choices about the computer-level agent text
+     */
+    agentTextSettings?: import("../../foundation/env/user-settings.mjs").ComputerAgentTextSettings | undefined;
+    /**
+     * the folder doctor runs in, for the printed fix
+     */
+    cwd?: string | undefined;
+    /**
+     * the CLI installed for the computer, when it is older than the newest
+     * release (outside a project)
+     */
+    globalBehind?: import("../../foundation/release/notices.mjs").GlobalBehind | null | undefined;
+    /**
+     * the project's release, when it is behind the newest (inside a project)
+     */
+    projectLag?: import("../../foundation/release/notices.mjs").ProjectLag | null | undefined;
+    lastNoticeSkip?: {
+        key: string;
+        reason: string;
+        at: number;
+    } | null | undefined;
+    /**
+     * why the
+     * last update check did not reach the registry, after the last that did
+     * the newest update notice that did not print, and why (diagnostic only)
+     */
+    lastCheckFailure?: {
+        at: number;
+        reason: string;
+    } | null | undefined;
+    /**
+     * who holds the state file's lock now (diagnostic only)
+     */
+    stateLock?: {
+        pid: number | null;
+        host: string | null;
+        since: number;
+    } | null | undefined;
+    /**
+     * every `astryx` on the search path, with the command that upgrades it
+     * the `astryx` commands on the search path, in order
+     */
+    searchPathCommands?: (import("../../foundation/env/search-path.mjs").SearchPathCommand & {
+        upgrade?: string | null;
+    })[] | undefined;
+    /**
+     * the integrations installed beside the running CLI
+     */
+    computerIntegrations?: import("../../foundation/integrations/computer-integrations.mjs").ComputerIntegrationCandidate[] | undefined;
+    /**
+     * the names of those that
+     * loaded outside a project
+     */
+    loadedComputerIntegrations?: string[] | undefined;
+    /**
+     * the names of the integrations the
+     * folder loads itself, whose copies win over the computer's
+     */
+    folderIntegrations?: string[] | undefined;
+};
 import { DocsCatalog } from '../../foundation/discovery/docs-discovery.mjs';

package/api/doctor/doctor.doc.mjs

@@ -24,7 +24,8 @@ export const doc = {
     'integration provider identity and contribution issues, agent docs, the ' +
     'detected package manager, and the health of the docs the CLI reads (authoring ' +
     'and CLI docs, the docs tree, doc size), and returns a structured ' +
-    'report. Theme checks run when the generated app module exists; without one, doctor reports that the CLI manages no themes and names theme add. Earlier descriptor-less copies are a non-failing upgrade warning. It never installs, writes, or mutates. It imports astryx.config, executes every added theme source while validating private inputs, and loads every recorded built theme module to prove its runtime imports work, including themes from installed packages. Local theme source also runs during build-freshness checks. Stylesheets are parsed without execution. Config and theme top-level code therefore run, so use doctor only with project code you trust.',
+    'report. Theme checks run when the generated app module exists; without one, doctor reports that the CLI manages no themes and names theme add. Earlier descriptor-less copies are a non-failing upgrade warning. It never installs, writes, or mutates. It imports astryx.config, executes every added theme source while validating private inputs, and loads every recorded built theme module to prove its runtime imports work, including themes from installed packages. Local theme source also runs during build-freshness checks. Stylesheets are parsed without execution. Config and theme top-level code therefore run, so use doctor only with project code you trust. Outside a project it checks the computer instead: the Node version (`node-version`), the release that answered (`answering-release`), the newest release the computer knows of (`newest-release`), the astryx commands on the search path (`cli-on-path`), the integrations installed for the computer (`computer-integrations`: each one used outside a project, and a warning for one skipped because its peer range excludes the answering release or that fails to load), and the computer-level agent text (`computer-agent-text`): present and matching this release, present but different, edited, absent, or turned off, and where it is linked, with `astryx init --user` as the fix for the stale and absent cases. The agent-text check is always info. The newest-release check also runs inside a project: it names a newer release when the computer knows of one; inside a project whose release is older it names the install and upgrade commands; outside one, when the CLI installed for the computer is older, it names the command of the package manager that installed it, after the Node the newest release needs when the computer runs an older one. It is always info and installs nothing. The `cli-on-path` check also runs inside a project: it lists every astryx command on the search path in order, passes when the first is a release that hands each project run to the release of that project, and warns when the first is another program or a release that predates the hand-off, naming `npm i -g @astryxdesign/cli@latest`. Inside a project, `computer-integrations` lists, as info, the integrations installed for the computer that the project does not install, with its install command; they are not used there. It never fails a check because the folder has no project, and installs nothing.' +
+    ' In global mode: with `cwd` outside a project, it checks the computer instead (the Node version, the version that answered, the newest version it knows of, the astryx commands on the search path, the integrations installed globally, and the agent guide for the computer) and never fails a check because the folder has no project. See {@link namespace:global} and {@link generic:who-answers}.',
   importPath: '@astryxdesign/cli/api',
   signature: 'doctor(options?: DoctorOptions): Promise<DoctorResponse>',
   keywords: ['doctor', 'diagnose', 'health', 'check', 'verify', 'environment'],
@@ -33,7 +34,7 @@ export const doc = {
       name: 'options.cwd',
       type: 'string',
       description:
-        'Directory to diagnose. A missing directory is not an error; it shows up in the checks (e.g. core-installed: fail).',
+        'Directory to diagnose. A directory outside any project, a missing one included, gets the computer checks.',
       default: 'process.cwd()',
     },
   ],