@canonical/pragma-cli 0.33.0 → 0.35.0

package/src/capabilities/doctor/checks/checkPragmaVersion.ts

@@ -1,9 +1,10 @@
-import type { PragmaRuntime } from "../../../kernel/runtime/types.js";
-import { detectInstallSource } from "../../shared/packageManager.js";
+import { BIN_NAME } from "../../../constants.js";
+import type { PragmaRuntime } from "../../../kernel/runtime/index.js";
+import { detectInstallSource } from "../../shared/index.js";
 import type { CheckResult } from "../types.js";
 
 /**
- * Report the pragma version and how it was installed. Always passes — purely
+ * Report the CLI version and how it was installed. Always passes — purely
  * informational.
  *
  * @param rt - The per-invocation runtime (for `version`).
@@ -15,7 +16,7 @@ export async function checkPragmaVersion(
 ): Promise<CheckResult> {
   const install = detectInstallSource();
   return {
-    name: "pragma version",
+    name: `${BIN_NAME} version`,
     status: "pass",
     detail: `v${rt.version} (installed via ${install.label})`,
   };

package/src/capabilities/doctor/checks/checkShellCompletions.test.ts

@@ -1,19 +1,33 @@
 /**
  * `checkShellCompletions` — the doctor check that verifies completions are
- * installed AND functional.
+ * installed AND up to date AND functional.
  *
- * Runs against an isolated HOME and a controlled `$SHELL` so the three gates —
- * the resolver effect test, the real install-path probe, and the zsh fpath
- * activation gate — are deterministic. The effect test (gate 1) drives the real
+ * Runs against an isolated HOME and an injected shell so the gates —
+ * the resolver effect test, the install probe, and the zsh fpath activation
+ * gate — are deterministic. The effect test (gate 1) drives the real
  * `runComplete` resolver; the install/fpath gates write real files under the
  * temp HOME rather than mocking the fs.
+ *
+ * Gate 2 compares BYTES, not existence, so the "installed" cases here write the
+ * real `emitScripts(capabilities)[shell]` body. A file that merely exists is
+ * now the failing case, and it has its own test — as does the boundary on the
+ * other side, where a per-project `completion` config must NOT be able to
+ * condemn the one global script.
  */
 
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { completionScriptPath } from "../../setup/shell.js";
+import { emitScripts } from "../../../kernel/completion/emitScripts.js";
+import { capabilities } from "../../index.js";
+import { detectCompletions } from "../../setup/operations/setupCompletions.js";
+import {
+  completionScriptPath,
+  type ShellDetection,
+  type ShellId,
+} from "../../setup/shell.js";
+import type { CheckResult } from "../types.js";
 import { checkShellCompletions } from "./checkShellCompletions.js";
 
 const roots: string[] = [];
@@ -24,25 +38,49 @@ const tmp = (): string => {
 };
 
 let prevHome: string | undefined;
-let prevShell: string | undefined;
+let prevPath: string | undefined;
 beforeEach(() => {
   prevHome = process.env.HOME;
-  prevShell = process.env.SHELL;
+  prevPath = process.env.PATH;
   process.env.HOME = tmp();
+  // The installed script spawns `pragma` for every name context, and the check
+  // now verifies that it can. Put one on an isolated PATH so these cases are
+  // about the SCRIPT rather than about the host's install.
+  const bin = tmp();
+  writeFileSync(join(bin, "pragma"), "");
+  process.env.PATH = bin;
 });
 afterEach(() => {
   process.env.HOME = prevHome;
-  if (prevShell === undefined) delete process.env.SHELL;
-  else process.env.SHELL = prevShell;
+  process.env.PATH = prevPath;
   for (const dir of roots) rmSync(dir, { recursive: true, force: true });
   roots.length = 0;
 });
 
-/** Write the (empty) completion script to the shell's real install path. */
-function installScript(shell: "zsh" | "bash" | "fish"): void {
+/** Write `body` to the shell's real install path. */
+function writeScript(shell: ShellId, body: string): void {
   const path = completionScriptPath(shell);
   mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, "# stub\n");
+  writeFileSync(path, body);
+}
+
+/** Install the script `setup completions` would write for this shell. */
+function installScript(shell: ShellId): void {
+  writeScript(shell, emitScripts(capabilities)[shell]);
+}
+
+/**
+ * Run the check the way `doctor` does: the `completions` target detects once
+ * per invocation and the check reads that one answer, so the test drives the
+ * same pairing rather than letting the check re-read behind its own back.
+ */
+async function check(cwd: string, shell: ShellId | null): Promise<CheckResult> {
+  // The shell is INJECTED rather than forced through `$SHELL`: detection reads
+  // the process tree now, and a test that set `$SHELL` was only ever asserting
+  // against the login shell — the exact confusion this check exists to catch.
+  const detection: ShellDetection =
+    shell === null ? { kind: "unknown" } : { kind: "detected", shell };
+  return checkShellCompletions(cwd, await detectCompletions(cwd, detection));
 }
 
 /** Write a `.zshrc` that puts ~/.zfunc on fpath. */
@@ -57,43 +95,99 @@ describe("checkShellCompletions — effect test (gate 1)", () => {
   it("passes the resolver gate: `pragma <TAB>` resolves nouns", async () => {
     // No shell → skip, but only AFTER the resolver answered — the detail proves
     // the effect test ran and succeeded.
-    delete process.env.SHELL;
-    const result = await checkShellCompletions(tmp());
+    const result = await check(tmp(), null);
     expect(result.status).toBe("skip");
     expect(result.detail).toMatch(/resolver OK/);
   });
 });
 
 describe("checkShellCompletions — install probe (gate 2)", () => {
-  it("fails when $SHELL is set but no script is installed", async () => {
-    process.env.SHELL = "/usr/bin/bash";
-    const result = await checkShellCompletions(tmp());
-    expect(result.status).toBe("fail");
+  it("a never-installed script is available (opt-in, not a fault) with the setup command", async () => {
+    const result = await check(tmp(), "bash");
+    expect(result.status).toBe("available");
     expect(result.detail).toMatch(/not installed/);
     expect(result.remedy).toBe("pragma setup completions");
   });
 
-  it("passes for bash once the script exists at its real path", async () => {
-    process.env.SHELL = "/usr/bin/bash";
+  it("does not claim a script is installed when the binary is off PATH", async () => {
+    // This gate runs before the install probe, so it saw only that the binary
+    // does not resolve — and reported `bash script installed, but ...` on a
+    // machine where nothing had ever been installed. Anyone invoking this CLI
+    // by absolute path lands here, and the row invented the file it exists to
+    // report on.
+    process.env.PATH = tmp(); // an empty PATH: no binary to find
+    const result = await check(tmp(), "bash");
+    expect(result.detail).not.toMatch(/script installed/);
+    expect(result.detail).toMatch(/is not on PATH/);
+    // Nothing was installed, so nothing that exists is broken.
+    expect(result.status).toBe("available");
+    expect(result.remedy).toMatch(/on your PATH/);
+  });
+
+  it("fails when an INSTALLED script cannot reach the binary", async () => {
     installScript("bash");
-    const result = await checkShellCompletions(tmp());
+    process.env.PATH = tmp();
+    const result = await check(tmp(), "bash");
+    expect(result.status).toBe("fail");
+    expect(result.detail).toMatch(/script installed, but/);
+  });
+
+  it("passes for bash once the up-to-date script is at its real path", async () => {
+    installScript("bash");
+    const result = await check(tmp(), "bash");
     expect(result.status).toBe("pass");
-    expect(result.detail).toMatch(/bash installed and resolving/);
+    expect(result.detail).toMatch(
+      /bash \(the shell in use\) up to date and resolving/,
+    );
   });
 
-  it("passes for fish once the script exists at its real path", async () => {
-    process.env.SHELL = "/usr/bin/fish";
+  it("passes for fish once the up-to-date script is at its real path", async () => {
     installScript("fish");
-    const result = await checkShellCompletions(tmp());
+    const result = await check(tmp(), "fish");
     expect(result.status).toBe("pass");
   });
+
+  it("fails when the installed script is out of date", async () => {
+    // Reproduced against the compiled binary before this was fixed: overwrite
+    // the installed script with junk and `doctor` still reported
+    // "✓ Shell completions: bash installed and resolving (19 nouns)", while
+    // `setup completions` in the same breath said "Updating bash completions".
+    // Every user upgrading across a grammar change lands here: the old script
+    // offers the old nouns and misses the new ones, and doctor is the one
+    // command whose job is to say so.
+    writeScript("bash", "# STALE JUNK\n");
+    const result = await check(tmp(), "bash");
+    expect(result.status).toBe("fail");
+    expect(result.detail).toMatch(/out of date/);
+    expect(result.remedy).toBe("pragma setup completions");
+  });
+
+  it("does NOT condemn the global script for one project's `completion` config", async () => {
+    // The script is ONE file per user; `completion` config is layered per
+    // project. Comparing the global file against only THIS directory's body
+    // made `doctor`'s verdict flip with `cd`: reproduced against the real
+    // check, a project declaring `minChars: 5` passed in its own directory and
+    // failed in every other, and running the offered remedy there moved the
+    // failure back rather than closing it. The first assertion is the
+    // discriminator — this project really does ask for a different body — so
+    // deleting the config write below turns the test red.
+    installScript("bash");
+    const cwd = tmp();
+    writeFileSync(
+      join(cwd, "pragma.config.ts"),
+      "export default { completion: { minChars: 5 } };\n",
+    );
+    expect(
+      (await detectCompletions(cwd, { kind: "detected", shell: "bash" })).state,
+    ).toBe("stale");
+    expect((await check(cwd, "bash")).status).toBe("pass");
+  });
 });
 
 describe("checkShellCompletions — zsh fpath activation (gate 3)", () => {
   it("fails when the zsh script is installed but ~/.zfunc is not on fpath", async () => {
-    process.env.SHELL = "/usr/bin/zsh";
     installScript("zsh");
-    const result = await checkShellCompletions(tmp());
+    const result = await check(tmp(), "zsh");
     expect(result.status).toBe("fail");
     expect(result.detail).toMatch(/not on your fpath/);
     // The remedy IS the activation hint — the exact ~/.zshrc lines.
@@ -101,11 +195,12 @@ describe("checkShellCompletions — zsh fpath activation (gate 3)", () => {
   });
 
   it("passes once the zsh script is installed AND ~/.zfunc is on fpath", async () => {
-    process.env.SHELL = "/usr/bin/zsh";
     installScript("zsh");
     wireZfunc();
-    const result = await checkShellCompletions(tmp());
+    const result = await check(tmp(), "zsh");
     expect(result.status).toBe("pass");
-    expect(result.detail).toMatch(/zsh installed and resolving/);
+    expect(result.detail).toMatch(
+      /zsh \(the shell in use\) up to date and resolving/,
+    );
   });
 });

package/src/capabilities/doctor/checks/checkShellCompletions.ts

@@ -1,20 +1,48 @@
-import { existsSync, readFileSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { BIN_NAME } from "../../../constants.js";
 import {
+  emitScripts,
   indexCompletionEnv,
   runComplete,
 } from "../../../kernel/completion/index.js";
 import { capabilities } from "../../index.js";
-import {
-  activationHint,
-  completionScriptPath,
-  detectShell,
-} from "../../setup/shell.js";
+import type { CompletionsDetection } from "../../setup/operations/index.js";
+import { activationHint, type ShellId } from "../../setup/shell.js";
 import type { CheckResult } from "../types.js";
 
 const NAME = "Shell completions";
 
+/** The one remedy for an absent or out-of-date script. */
+const INSTALL_REMEDY = `${BIN_NAME} setup completions`;
+
+/**
+ * Whether the installed script is the config-free emit — the body
+ * `setup completions` writes when no `completion` config tunes it.
+ *
+ * The completion script is ONE file per user, but the `completion` config it is
+ * rendered from is layered per project. So `detectCompletions(cwd)`'s `stale`
+ * means only "not what THIS directory would write", and on its own it would let
+ * any project that tunes `minChars` call a globally-correct script out of date
+ * from every other directory — a `doctor` verdict that flips with `cd`, and a
+ * remedy that just moves the failure to the project you came from. A script
+ * that matches neither this project's body nor the untuned one is the one that
+ * is genuinely stale.
+ *
+ * @param path - The install path.
+ * @param shell - The detected shell.
+ * @returns Whether the file there is byte-identical to the untuned emit.
+ * @note Impure — reads the install path. An unreadable file counts as `false`.
+ */
+function isUntunedScript(path: string, shell: ShellId): boolean {
+  try {
+    return readFileSync(path, "utf-8") === emitScripts(capabilities)[shell];
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Whether the user's `.zshrc` puts `~/.zfunc` on `$fpath` — the activation step
  * `setup completions` cannot perform for the user. zsh loads nothing from
@@ -53,25 +81,42 @@ async function completeProbe(cwd: string): Promise<number> {
 }
 
 /**
- * Check that shell completions are installed AND functional.
+ * Check that shell completions are installed AND up to date AND functional.
  *
  * Three gates, in order:
  * 1. The resolver answers (`completeProbe` drives `runComplete` end to end) —
  *    the effect every installed script depends on. A failure here is a real
  *    regression, so it fails even when nothing is installed.
- * 2. The script file exists at the shell's real install path (`shell.ts`) —
- *    NOT a `"pragma"` substring in an RC file, which `setup completions` never
- *    writes.
+ * 2. The installed script is present AND is a script `setup completions` would
+ *    write. Bytes, not existence: a file that merely exists proves nothing — a
+ *    user upgrading across a grammar change keeps the old script, loses the
+ *    moved nouns from TAB, and used to be told everything was fine. The path
+ *    and this project's body come from `detectCompletions`, the ONE owner of
+ *    that decision; {@link isUntunedScript} is what keeps a per-project
+ *    `completion` config from condemning a global file (see its docblock).
  * 3. For zsh, `~/.zfunc` is on `$fpath` — the activation step setup can only
  *    hint. Installed-but-unwired reports a distinct remedy.
  *
- * @param cwd - The project directory (for the resolver's entity seam).
- * @returns A CheckResult: pass (installed + wired + answering), fail (with the
- *   attributable remedy), or skip (shell undetected).
- * @note Impure — reads `$SHELL`, the install path, `.zshrc`, and drives the
- *   storeless resolver.
+ * Fault tiers: a broken resolver, a stale installed script, or an unwired zsh
+ * install are `fail` — something that exists does not work. A script that was
+ * never installed is `available`: completions are opt-in and a fresh install
+ * is healthy without them.
+ *
+ * The detection is passed IN rather than re-read: the `completions` target
+ * detects once per invocation and both the setup plan and this row read that
+ * one answer, so the two surfaces cannot describe different files.
+ *
+ * @param cwd - The project directory (the resolver's entity seam).
+ * @param d - The `completions` target's detection for this invocation.
+ * @returns A CheckResult: pass (up to date + wired + answering), available
+ *   (never installed, with the setup remedy), fail (with the attributable
+ *   remedy), or skip (shell undetected).
+ * @note Impure — reads the install path, `.zshrc`, and drives the resolver.
  */
-export async function checkShellCompletions(cwd: string): Promise<CheckResult> {
+export async function checkShellCompletions(
+  cwd: string,
+  d: CompletionsDetection,
+): Promise<CheckResult> {
   // 1. Effect test: the resolver the scripts delegate to must actually answer.
   let candidates: number;
   try {
@@ -82,34 +127,75 @@ export async function checkShellCompletions(cwd: string): Promise<CheckResult> {
       name: NAME,
       status: "fail",
       detail: `completion resolver failed: ${reason}`,
-      remedy: "Report this as a bug — `pragma __complete` should never throw.",
+      remedy: `Report this as a bug — \`${BIN_NAME} __complete\` should never throw.`,
     };
   }
   if (candidates === 0) {
     return {
       name: NAME,
       status: "fail",
-      detail: "completion resolver returned no candidates for `pragma <TAB>`",
+      detail: `completion resolver returned no candidates for \`${BIN_NAME} <TAB>\``,
       remedy: "Report this as a bug — the noun context is always non-empty.",
     };
   }
 
-  // 2. The script file exists at the shell's real install path.
-  const shell = detectShell();
-  if (!shell) {
+  // 2. The check is about the shell the user is IN. Reporting on the login
+  //    shell instead is what let this row print a green check for a shell the
+  //    user never opens while the one they live in had nothing installed.
+  const { shell, path, state } = d;
+  if (d.detection.kind === "ambiguous") {
     return {
       name: NAME,
       status: "skip",
-      detail: "resolver OK; shell not detected ($SHELL unset)",
+      detail: `resolver OK; the running shell cannot be identified (SHELL names ${d.detection.login}, the login shell)`,
+      remedy: `Run \`${INSTALL_REMEDY}\` from the shell you want completions in.`,
     };
   }
-  const path = completionScriptPath(shell);
-  if (!existsSync(path)) {
+  if (shell === null || path === null) {
     return {
       name: NAME,
-      status: "fail",
+      status: "skip",
+      detail: "resolver OK; no bash, zsh, or fish in this process tree",
+    };
+  }
+  // The installed script delegates every name context to the binary. A script
+  // that cannot reach it is inert, and reporting it as current is the same
+  // false green this row already told once.
+  //
+  // This gate runs BEFORE the install probe, so it says only what it has
+  // verified: that the binary does not resolve. Claiming "script installed" here
+  // told a user running this CLI by absolute path that a script they had never
+  // installed was broken — an invented file, in the row whose whole job is to
+  // report the real one. Nothing installed is still the opt-in `available` tier.
+  if (!d.binOnPath) {
+    const installed = state !== "absent";
+    return {
+      name: NAME,
+      status: installed ? "fail" : "available",
+      detail: installed
+        ? `${shell} script installed, but \`${BIN_NAME}\` is not on PATH — the script cannot run it`
+        : `resolver OK; \`${BIN_NAME}\` is not on PATH — an installed script cannot run it`,
+      remedy: `Put \`${BIN_NAME}\` on your PATH.`,
+    };
+  }
+  if (state === "absent") {
+    // Never installed is `available`, not a fault: completions are opt-in and
+    // a fresh install is healthy without them. An INSTALLED script that is
+    // out of date or unwired (below) is the real failure — something the user
+    // set up no longer works.
+    return {
+      name: NAME,
+      status: "available",
       detail: `resolver OK; ${shell} script not installed`,
-      remedy: "pragma setup completions",
+      remedy: INSTALL_REMEDY,
+    };
+  }
+  if (state === "stale" && !isUntunedScript(path, shell)) {
+    return {
+      name: NAME,
+      status: "fail",
+      detail: `resolver OK; ${shell} script at ${path} is out of date`,
+      remedy: INSTALL_REMEDY,
     };
   }
 
@@ -126,6 +212,6 @@ export async function checkShellCompletions(cwd: string): Promise<CheckResult> {
   return {
     name: NAME,
     status: "pass",
-    detail: `${shell} installed and resolving (${candidates} nouns)`,
+    detail: `${shell} (the shell in use) up to date and resolving (${candidates} nouns)`,
   };
 }

package/src/capabilities/doctor/checks/index.ts

@@ -0,0 +1,27 @@
+/**
+ * The doctor check catalogue — the diagnoses `doctor` composes into a report.
+ *
+ * A check is the whole shape of this domain: it inspects ONE thing, decides
+ * pass or fail, and hands back a `CheckResult` carrying the remedy. Keeping
+ * them apart from the report body is what lets `runChecks` stay a composition
+ * — it orders and awaits, and knows nothing about what any check looks at.
+ *
+ * Two kinds live here, and the barrel exposes them differently. The UNBANDED
+ * checks diagnose what `setup` cannot install — the Node floor, the CLI's own
+ * version and install source, the pack answering this project's reads, and the
+ * store — so each is its own named entry point. The BANDED rows are derived
+ * per target, per band, from the setup target table rather than authored here,
+ * so they surface as the one generator that derives them, never as a list of
+ * row names this file would then have to keep in step with `setup`.
+ *
+ * The per-target probes (the completions script check, the MCP command
+ * resolution helpers) stay internal on purpose: `bandedChecks` is the only way
+ * they are meant to be reached, and a row reachable past its band is a row
+ * `doctor` can report and `setup` cannot fix.
+ */
+
+export { checkKeStore } from "./checkKeStore.js";
+export { checkNodeVersion } from "./checkNodeVersion.js";
+export { checkPackageRefs } from "./checkPackageRefs.js";
+export { checkPragmaVersion } from "./checkPragmaVersion.js";
+export { bandedChecks } from "./targetHealth.js";

package/src/capabilities/doctor/checks/mcpCommand.test.ts

@@ -0,0 +1,100 @@
+/**
+ * `commandOf` reads BOTH registered entry shapes.
+ *
+ * A harness whose schema requires `command` to be an argv array (OpenCode)
+ * carries the executable in the first element; a string-valued `command` IS the
+ * executable. Reading only the string form made doctor skip an entry `setup`
+ * had just written correctly — and report no command-based servers on a fully
+ * configured machine. The two shapes must resolve to the same executable, which
+ * is what these cases pin.
+ */
+
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { PlatformEnv } from "@canonical/harnesses";
+import { afterAll, describe, expect, it } from "vitest";
+import { commandOf, commandResolves } from "./mcpCommand.js";
+
+describe("commandOf — one executable, either entry shape", () => {
+  it("reads a string command", () => {
+    expect(commandOf({ command: "pragma", args: ["mcp", "serve"] })).toBe(
+      "pragma",
+    );
+  });
+
+  it("reads the executable out of an argv array", () => {
+    expect(commandOf({ command: ["pragma", "mcp", "serve"] })).toBe("pragma");
+  });
+
+  it("skips the leading empty element rather than returning it", () => {
+    expect(commandOf({ command: ["", "pragma"] })).toBe("pragma");
+  });
+
+  it("has no command for an HTTP entry", () => {
+    expect(commandOf({ type: "http", url: "https://example.test" })).toBe(
+      undefined,
+    );
+  });
+
+  it("has no command for an empty string, an empty array, or a non-entry", () => {
+    expect(commandOf({ command: "" })).toBe(undefined);
+    expect(commandOf({ command: [] })).toBe(undefined);
+    expect(commandOf(null)).toBe(undefined);
+    expect(commandOf("pragma")).toBe(undefined);
+  });
+});
+
+describe("commandResolves — the host's own resolution rules", () => {
+  const dirs: string[] = [];
+  const tmp = (): string => {
+    const dir = mkdtempSync(join(tmpdir(), "pragma-mcp-path-"));
+    dirs.push(dir);
+    return dir;
+  };
+  afterAll(() => {
+    for (const dir of dirs) rmSync(dir, { recursive: true, force: true });
+  });
+
+  const hostOf = (
+    platform: PlatformEnv["platform"],
+    dir: string,
+  ): PlatformEnv => ({
+    platform,
+    env: { PATH: dir },
+    home: dir,
+    isWsl: false,
+  });
+
+  it("resolves a Windows shim, which a bare-name PATH join cannot see", async () => {
+    // npm installs the CLI as `pragma.cmd` on Windows. Joining the bare name
+    // onto each PATH directory found nothing, so a registration `setup` had
+    // just written correctly was reported as a dead command. (The file is
+    // spelled to match a default `PATHEXT` entry exactly, because this test
+    // runs on a case-sensitive filesystem.)
+    const dir = tmp();
+    writeFileSync(join(dir, "pragma.CMD"), "");
+    expect(await commandResolves("pragma", dir, hostOf("win32", dir))).toBe(
+      true,
+    );
+  });
+
+  it("resolves a bare name off PATH elsewhere, and says no when it is absent", async () => {
+    const dir = tmp();
+    writeFileSync(join(dir, "pragma"), "");
+    expect(await commandResolves("pragma", dir, hostOf("linux", dir))).toBe(
+      true,
+    );
+    expect(await commandResolves("absent", dir, hostOf("linux", dir))).toBe(
+      false,
+    );
+  });
+
+  it("checks a path-bearing command as a file, relative to the project root", async () => {
+    const dir = tmp();
+    writeFileSync(join(dir, "local-bin"), "");
+    expect(
+      await commandResolves("./local-bin", dir, hostOf("linux", dir)),
+    ).toBe(true);
+  });
+});

package/src/capabilities/doctor/checks/mcpCommand.ts

@@ -0,0 +1,69 @@
+/**
+ * Command resolution for MCP server entries.
+ *
+ * A dead `command` makes every agent session try and fail to boot the server,
+ * so the `mcp` doctor row reports whether the entry it owns resolves. The row
+ * judges ONLY the entry this CLI writes: an aggregate check over every server
+ * in the file failed the row whenever some FOREIGN server had a dead command,
+ * which is a fact about someone else's tool reported as this one's fault.
+ */
+
+import { existsSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import type { PlatformEnv } from "@canonical/harnesses";
+
+/**
+ * Extract the stdio command from an MCP server config entry, if any. HTTP/SSE
+ * entries (`{ type: "http", url }`) have no command and are not checked.
+ *
+ * Both entry shapes resolve to the same executable. A harness whose schema
+ * requires `command` to be an argv array (OpenCode) carries the executable in
+ * its first element; a string-valued `command` IS the executable. Reading only
+ * the string form made this check skip an entry `setup` had just written
+ * correctly, and report no command-based servers on a configured machine.
+ */
+export function commandOf(entry: unknown): string | undefined {
+  if (typeof entry !== "object" || entry === null) return undefined;
+  const command = (entry as { command?: unknown }).command;
+  if (typeof command === "string") {
+    return command.length > 0 ? command : undefined;
+  }
+  if (Array.isArray(command)) {
+    return command.find(
+      (part): part is string => typeof part === "string" && part.length > 0,
+    );
+  }
+  return undefined;
+}
+
+/**
+ * Resolve a command the way the host would: a path-bearing entry is checked as
+ * a file (relative to the project root), a bare name is searched across `PATH`
+ * through `@canonical/harnesses`' `executableCandidates`, which owns the PATH
+ * split and the win32 `PATHEXT` rules in one place.
+ *
+ * The bare-name arm used to join the name onto each PATH directory, which
+ * cannot see the `.cmd` shim npm installs on Windows: a registration this CLI
+ * had just written correctly was reported as a dead command.
+ *
+ * @param command - The executable the entry names.
+ * @param cwd - The project root a relative command is resolved against.
+ * @param platform - The captured host to use instead of this one (tests).
+ * @returns Whether the command resolves on this machine.
+ * @note Impure — tests candidate paths on the filesystem.
+ */
+export async function commandResolves(
+  command: string,
+  cwd: string,
+  platform?: PlatformEnv,
+): Promise<boolean> {
+  if (command.includes("/") || command.includes("\\")) {
+    return existsSync(isAbsolute(command) ? command : join(cwd, command));
+  }
+  const { executableCandidates, readPlatformEnv } = await import(
+    "@canonical/harnesses"
+  );
+  return executableCandidates(command, platform ?? readPlatformEnv()).some(
+    (candidate) => existsSync(candidate),
+  );
+}