@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.3-canary.02f5fe4

package/api/doctor/doctor.d.mts

@@ -168,6 +168,114 @@ 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 | null} [agentTextCommand] the command the skill file
+ *   tells agents to run, or null
+ * @property {string | null} [agentTextInstall] the install step the skill
+ *   file records for when that command is not found, or null
+  * @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, runner?: boolean}>} [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) | null, elsewhere?: boolean}} input
+ *   `install`: the command that adds a package with the project's package
+ *   manager (read by the adapter); null when the folder belongs to no
+ *   project, or `elsewhere`: its package.json is not the project's, where the
+ *   fix points at the project's folder
+ * @returns {DoctorCheck}
+ */
+export function checkComputerIntegrationsAvailable({ installed, candidates, install, elsewhere }: {
+    installed: Set<string>;
+    candidates: import("../../foundation/integrations/computer-integrations.mjs").ComputerIntegrationCandidate[];
+    install: ((name: string) => string) | null;
+    elsewhere?: boolean;
+}): DoctorCheck;
 /**
  * Run all diagnostic checks and return a structured report.
  *
@@ -192,6 +300,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 +353,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 +424,98 @@ 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 command the skill file
+     * tells agents to run, or null
+     */
+    agentTextCommand?: string | null | undefined;
+    /**
+     * the install step the skill
+     * file records for when that command is not found, or null
+     */
+    agentTextInstall?: string | null | 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;
+        runner?: boolean;
+    })[] | 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()',
     },
   ],