@canonical/pragma-cli 0.34.0 → 0.35.0

package/dist/src/capabilities/setup/shell.js

@@ -0,0 +1,196 @@
+/**
+ * Shell detection + completion-script install paths.
+ *
+ * Shell selection is detection-only, and detection means the shell the user is
+ * RUNNING — read from the process tree — not the login shell `$SHELL` records.
+ * The two differ constantly and the difference is invisible until TAB fails.
+ * `$HOME` is read at call time so tests can isolate it.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { BIN_NAME } from "../../constants.js";
+const SHELL_MAP = {
+    zsh: "zsh",
+    bash: "bash",
+    fish: "fish",
+};
+/** How far up the process tree to look before giving up. */
+const MAX_ANCESTRY = 8;
+/**
+ * The command name and parent of a pid, read from `/proc` (Linux).
+ *
+ * `/proc/<pid>/stat` is `pid (comm) state ppid …`, and `comm` may itself
+ * contain spaces and parentheses — so the fields are taken after the LAST
+ * `)`, never by splitting the whole line.
+ *
+ * @param pid - The process to inspect.
+ * @returns Its command name and parent pid, or undefined when unreadable.
+ * @note Impure — reads /proc.
+ */
+function procEntry(pid) {
+    try {
+        const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+        const close = stat.lastIndexOf(")");
+        const open = stat.indexOf("(");
+        if (close < 0 || open < 0)
+            return undefined;
+        const name = stat.slice(open + 1, close);
+        const rest = stat.slice(close + 2).split(" ");
+        const ppid = Number.parseInt(rest[1] ?? "", 10);
+        return Number.isFinite(ppid) ? { name, ppid } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The same lookup for platforms without `/proc`, via one `ps` call.
+ *
+ * @param pid - The process to inspect.
+ * @returns Its command name and parent pid, or undefined.
+ * @note Impure — spawns `ps`.
+ */
+function psEntry(pid) {
+    try {
+        const out = execFileSync("ps", ["-o", "ppid=,comm=", "-p", String(pid)], {
+            encoding: "utf8",
+            timeout: 2000,
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        const match = /^(\d+)\s+(.*)$/.exec(out);
+        if (match === null)
+            return undefined;
+        return { name: match[2] ?? "", ppid: Number.parseInt(match[1] ?? "", 10) };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Normalize a process name to a shell id: `-zsh`, `/bin/bash`, `zsh` all map. */
+function asShell(name) {
+    const base = (name.split("/").pop() ?? "").replace(/^-/, "");
+    return SHELL_MAP[base];
+}
+/**
+ * Walk the process ancestry looking for the shell this invocation is running
+ * inside.
+ *
+ * The walk matters: a CLI reached through `npm run`, `bunx`, or a wrapper
+ * script has `node` or `sh` as its immediate parent, and the user's actual
+ * shell is a level or two further up.
+ *
+ * @returns The shell found, or undefined.
+ * @note Impure — reads the process table.
+ */
+function runningShell(read) {
+    const entryOf = read ?? (existsSync("/proc") ? procEntry : psEntry);
+    let pid = process.ppid;
+    for (let step = 0; step < MAX_ANCESTRY && pid > 1; step += 1) {
+        const entry = entryOf(pid);
+        if (entry === undefined)
+            return undefined;
+        const shell = asShell(entry.name);
+        if (shell !== undefined)
+            return shell;
+        pid = entry.ppid;
+    }
+    return undefined;
+}
+/**
+ * Detect the shell the user is actually running in.
+ *
+ * This reads the PROCESS TREE, not `$SHELL`. `$SHELL` is the login shell
+ * recorded in `/etc/passwd`; it is not changed by starting a different shell,
+ * so a user whose account says `bash` but who lives in `zsh` was silently
+ * given a bash script — and `doctor` then reported `✓ Shell completions: bash
+ * up to date and resolving`, a green check for a shell they never open, while
+ * the shell they do use had nothing.
+ *
+ * `$SHELL` survives only as a CONTRADICTION detector. When the process tree
+ * gives no answer (a CI runner, an editor task, a daemon), a `$SHELL` value is
+ * a guess about a session that may not exist, so the answer is `ambiguous` and
+ * the caller is expected to say so rather than pick.
+ *
+ * @param read - Injected process-table reader; defaults to the real one.
+ * @returns What could be established about the running shell.
+ * @note Impure — reads the process table and `$SHELL`.
+ */
+export function detectShell(read) {
+    const running = runningShell(read);
+    if (running !== undefined)
+        return { kind: "detected", shell: running };
+    const login = SHELL_MAP[(process.env.SHELL ?? "").split("/").pop() ?? ""];
+    return login === undefined
+        ? { kind: "unknown" }
+        : { kind: "ambiguous", login };
+}
+/**
+ * The standard install path for a shell's completion script.
+ *
+ * The BASENAME is {@link BIN_NAME}, never a literal, because `emitScripts`
+ * derives the script's own `#compdef` / `complete -F` / `complete -c` from that
+ * same name, and for two of the three shells the basename decides whether the
+ * file is ever loaded. Measured against real shells with the distribution
+ * renamed to `widget9`:
+ *
+ * - **fish** autoloads `completions/<cmd>.fish` BY NAME. A correct `widget9`
+ *   script in a file called `pragma.fish` is never loaded — TAB silently falls
+ *   back to filenames. Verified: renaming that one file is the entire
+ *   difference between candidates and no candidates.
+ * - **bash-completion** looks up `completions/<cmd>` by the command name the
+ *   same way. Verified against bash-completion 2.11's `__load_completion`:
+ *   with the file named `widget9`, `complete -p widget9` reports
+ *   `complete -F _widget9 widget9`; with the identical file named `pragma`,
+ *   `_widget9` is never defined and bash falls back to `_minimal`.
+ * - **zsh** does NOT work that way: `compinit` binds by the `#compdef` tag
+ *   inside the file, so `~/.zfunc/_pragma` holding `#compdef widget9` does
+ *   complete `widget9` (verified — `_comps[widget9]` resolves to `_pragma`).
+ *   The basename still matters, for a different reason: it names the function
+ *   zsh autoloads, and two distributions both writing `_pragma` would silently
+ *   overwrite each other's completions.
+ *
+ * Either way `setup completions` and `doctor` report success, so nothing else
+ * would tell the user.
+ *
+ * @param shell - The target shell.
+ * @returns The absolute path the completion script is written to.
+ * @note Impure — reads the home directory.
+ */
+export function completionScriptPath(shell) {
+    const home = homedir();
+    switch (shell) {
+        case "zsh":
+            return join(home, ".zfunc", `_${BIN_NAME}`);
+        case "bash":
+            return join(home, ".local", "share", "bash-completion", "completions", BIN_NAME);
+        case "fish":
+            return join(home, ".config", "fish", "completions", `${BIN_NAME}.fish`);
+    }
+}
+/**
+ * The post-install activation hint for a shell.
+ *
+ * bash and fish install into directories their completion systems auto-load, so
+ * the only step left is a fresh shell. zsh's `~/.zfunc` is NOT auto-loaded: the
+ * script never loads unless `~/.zfunc` is on `$fpath` BEFORE `compinit` runs —
+ * the single trap every zsh user hits, so we spell out the exact `.zshrc` lines.
+ *
+ * @param shell - The shell the script was installed for.
+ * @returns A one-or-more-line activation instruction.
+ */
+export function activationHint(shell) {
+    switch (shell) {
+        case "zsh":
+            return ("To activate, ensure ~/.zfunc is on your fpath BEFORE compinit. Add to ~/.zshrc:\n" +
+                "    fpath=(~/.zfunc $fpath)\n" +
+                "    autoload -Uz compinit && compinit\n" +
+                "Then restart your shell (or run `exec zsh`).");
+        case "bash":
+            return "To activate, restart your shell (bash-completion auto-loads the script).";
+        case "fish":
+            return "To activate, restart your shell (fish auto-loads the script).";
+    }
+}
+//# sourceMappingURL=shell.js.map

package/dist/src/capabilities/setup/shell.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell.js","sourceRoot":"","sources":["../../../../src/capabilities/setup/shell.ts"],"names":[],"mappings":"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"}

package/dist/src/capabilities/setup/targets.js

@@ -0,0 +1,263 @@
+/**
+ * THE target table — the one list `setup` and `doctor` both read.
+ *
+ * Five rows, each with a band column. This table drives the `setup <target>`
+ * sub-verbs, the wizard's choices, the `--dry-run` plan, the progress lines, the
+ * recap, the doctor rows, and each doctor row's `fix:` line. Adding a sixth
+ * target is one row here — not a new sub-verb, a new check, a new recap branch
+ * and a new fix string that four separate files have to agree about.
+ *
+ * A row owns: its identity (`id` is BOTH the sub-verb argument and the doctor
+ * row name, so `mcp` and `setup mcp` visibly share a token), which bands it can
+ * be installed into, how to DETECT its current state, how to PLAN a run from
+ * that detection, and how to COMPOSE the forward and removal effects. Detection
+ * runs once per invocation and feeds every reader, so setup and doctor cannot
+ * disagree about what they looked at.
+ *
+ * What a row does NOT own is diagnosis. `doctor/runChecks.ts` maps a row's
+ * detection onto a check result itself: the completions check needs helpers that
+ * live under `doctor/`, and importing them here would make the two directories
+ * import each other. The bijection is unaffected — doctor enumerates THIS table
+ * and derives every row name and `fix:` line from it.
+ *
+ * This module is reached only through the verb's lazy dynamic import (and
+ * doctor's), so nothing here lands on the `--help`/`__complete` fast path.
+ */
+import { BIN_NAME } from "../../constants.js";
+import { composeCompletions, composeCompletionsRemoval, detectCompletions, } from "./operations/setupCompletions.js";
+import { composeConfigFile, composeConfigRemoval, detectConfigFile, } from "./operations/setupConfig.js";
+import { composeLsp, composeLspRemoval, detectLsp, LSP_SKIP_REMEDY, lspEditorNames, lspSkipReason, lspUninstallRemedy, } from "./operations/setupLsp.js";
+import { composeMcp, composeMcpRemoval, detectMcp, mcpGroupState, ownedMcpGroups, selectedGroups, } from "./operations/setupMcp.js";
+import { composeSkills, composeSkillsRemoval, detectSkills, ownedSkillLinks, skillsSkipReason, } from "./operations/setupSkills.js";
+import { shortenPath, } from "./plan.js";
+/** Erase a row's detection type so the five rows can share one array. */
+const defineTarget = (target) => target;
+// =============================================================================
+// The rows
+// =============================================================================
+const configTarget = defineTarget({
+    id: "config",
+    title: "Global configuration",
+    bands: ["global"],
+    detect: () => detectConfigFile(),
+    plan: (d, _band, roots) => {
+        const path = shortenPath(d.path, roots);
+        if (!d.exists)
+            return { action: "install", detail: path };
+        return { action: "none", detail: `${path} — present` };
+    },
+    removalPlan: (d, _band, roots) => {
+        const path = shortenPath(d.path, roots);
+        if (!d.exists)
+            return { action: "none", detail: `${path} — absent` };
+        if (!d.isSeed) {
+            return {
+                action: "skip",
+                detail: path,
+                reason: "kept — it holds your settings",
+            };
+        }
+        return { action: "remove", detail: path };
+    },
+    compose: (d) => composeConfigFile(d),
+    composeRemoval: (d) => composeConfigRemoval(d),
+});
+const completionsTarget = defineTarget({
+    id: "completions",
+    title: "Shell completions",
+    bands: ["global"],
+    detect: (rt) => detectCompletions(rt.cwd),
+    plan: (d, _band, roots) => {
+        // Never guess a shell. Installing for the wrong one is invisible until the
+        // user presses TAB and nothing happens, so an unresolved shell is a named
+        // skip whose remedy is the one action that DOES settle it.
+        if (d.detection.kind === "ambiguous") {
+            return {
+                action: "skip",
+                detail: "the running shell cannot be identified",
+                reason: `the running shell cannot be identified — SHELL names ${d.detection.login}, which is the login shell, not necessarily the one in use`,
+                remedy: `run \`${BIN_NAME} setup completions\` from the shell you want completions in`,
+            };
+        }
+        if (d.detection.kind === "unknown" || d.shell === null || d.path === null) {
+            return {
+                action: "skip",
+                detail: "no supported shell detected",
+                reason: "no bash, zsh, or fish was found in this process tree",
+                remedy: `run \`${BIN_NAME} setup completions\` from bash, zsh, or fish`,
+            };
+        }
+        // The script spawns the binary for every name context. Installing one that
+        // cannot reach it writes a file that silently does nothing.
+        if (!d.binOnPath) {
+            return {
+                action: "skip",
+                detail: `${BIN_NAME} is not on PATH`,
+                reason: `the completion script runs \`${BIN_NAME}\`, which this shell cannot find on PATH`,
+                remedy: `put \`${BIN_NAME}\` on your PATH, then run this again`,
+            };
+        }
+        const where = `${d.shell} → ${shortenPath(d.path, roots)}`;
+        if (d.state === "installed")
+            return { action: "none", detail: where };
+        return {
+            action: d.state === "stale" ? "update" : "install",
+            detail: where,
+        };
+    },
+    removalPlan: (d, _band, roots) => {
+        if (d.path === null || d.state === "absent") {
+            return { action: "none", detail: "no script installed" };
+        }
+        return { action: "remove", detail: shortenPath(d.path, roots) };
+    },
+    compose: (d) => composeCompletions(d),
+    composeRemoval: (d) => composeCompletionsRemoval(d),
+});
+const lspTarget = defineTarget({
+    id: "lsp",
+    title: "Terrazzo LSP extension",
+    bands: ["global"],
+    detect: (rt) => detectLsp(rt.cwd),
+    plan: (d) => {
+        if (d.state === "unknown") {
+            return {
+                action: "skip",
+                detail: lspSkipReason(d),
+                reason: lspSkipReason(d),
+                remedy: LSP_SKIP_REMEDY,
+            };
+        }
+        // One child per detected editor, exactly like the mcp row's files: a
+        // machine with several VS Code forks on PATH should not have the extension
+        // pushed into all of them because they happen to be installed.
+        const children = d.editors.map((e) => ({
+            key: e.editor.cli,
+            label: `${e.editor.cli} — ${e.editor.name}`,
+            action: e.installed ? "unchanged" : "add",
+        }));
+        if (d.state === "installed") {
+            return {
+                action: "none",
+                detail: `installed (${lspEditorNames(d).join(", ")})`,
+                children,
+            };
+        }
+        const pending = d.editors.filter((e) => !e.installed);
+        return {
+            action: "install",
+            detail: `${pending.length} ${pending.length === 1 ? "editor" : "editors"}`,
+            children,
+        };
+    },
+    removalPlan: (d) => ({
+        action: "skip",
+        detail: "not removed",
+        reason: "an extension install cannot be reversed from here",
+        remedy: lspUninstallRemedy(d) ??
+            "no editor CLI is on PATH — uninstall it from your editor",
+    }),
+    compose: (d, chosen) => composeLsp(d, chosen),
+    composeRemoval: (d) => composeLspRemoval(d),
+});
+/** One MCP file as a plan child: its path, the harnesses sharing it, its state. */
+const mcpChild = (d, group, roots) => {
+    const state = mcpGroupState(d, group.path);
+    return {
+        key: group.path,
+        label: shortenPath(group.path, roots),
+        action: state === "configured"
+            ? "unchanged"
+            : state === "drifted"
+                ? "update"
+                : "add",
+    };
+};
+const mcpTarget = defineTarget({
+    id: "mcp",
+    title: "MCP server registration",
+    bands: ["global", "project"],
+    detect: (rt, band) => detectMcp(rt, band),
+    plan: (d, band, roots) => {
+        if (d.groups.length === 0) {
+            return {
+                action: "skip",
+                detail: "no harness config location in this band",
+                reason: band === "project"
+                    ? "no AI harness in this project writes a per-repository config"
+                    : "no detected AI harness declares a user-level config location",
+            };
+        }
+        const children = d.groups.map((group) => mcpChild(d, group, roots));
+        const pending = children.filter((c) => c.action !== "unchanged");
+        return {
+            action: pending.length === 0 ? "none" : "update",
+            detail: `${d.groups.length} ${d.groups.length === 1 ? "file" : "files"}`,
+            children,
+        };
+    },
+    removalPlan: (d, _band, roots) => {
+        const owned = ownedMcpGroups(d);
+        if (owned.length === 0) {
+            return { action: "none", detail: "no entry to remove" };
+        }
+        return {
+            action: "remove",
+            detail: `${owned.length} ${owned.length === 1 ? "file" : "files"}`,
+            children: owned.map((group) => ({
+                key: group.path,
+                label: shortenPath(group.path, roots),
+                action: "update",
+            })),
+        };
+    },
+    compose: (d, chosen) => composeMcp(d, chosen ? selectedGroups(d, chosen) : d.groups),
+    composeRemoval: (d) => composeMcpRemoval(d),
+});
+const skillsTarget = defineTarget({
+    id: "skills",
+    title: "Skill symlinks",
+    bands: ["global", "project"],
+    detect: (rt, band) => detectSkills(rt, band),
+    plan: (d, band, roots) => {
+        if (!d.available) {
+            const reason = skillsSkipReason(shortenPath(d.sourceRoot, roots), band);
+            return { action: "skip", detail: reason, reason };
+        }
+        const dirs = d.targets.map((t) => shortenPath(t.dir, roots)).join(", ");
+        const where = `${d.skillCount} ${d.skillCount === 1 ? "skill" : "skills"} → ${d.targets.length} ${d.targets.length === 1 ? "dir" : "dirs"} (${dirs})`;
+        const pending = d.actions.filter((a) => a.action !== "skipped");
+        return { action: pending.length === 0 ? "none" : "link", detail: where };
+    },
+    removalPlan: (d, _band, roots) => {
+        const owned = ownedSkillLinks(d);
+        if (owned.length === 0) {
+            return { action: "none", detail: "no link to remove" };
+        }
+        const dirs = [...new Set(owned.map((a) => shortenPath(a.linkPath, roots)))];
+        return {
+            action: "remove",
+            detail: `${owned.length} ${owned.length === 1 ? "link" : "links"}`,
+            children: dirs.map((dir) => ({
+                key: dir,
+                label: dir,
+                action: "update",
+            })),
+        };
+    },
+    compose: (d) => composeSkills(d),
+    composeRemoval: (d) => composeSkillsRemoval(d),
+});
+/** THE table, in display order. */
+export const TARGETS = [
+    configTarget,
+    completionsTarget,
+    lspTarget,
+    mcpTarget,
+    skillsTarget,
+];
+/** Look a row up by id. */
+export const findTarget = (id) => TARGETS.find((target) => target.id === id);
+/** Whether a target can be installed into a band. */
+export const supportsBand = (target, band) => target.bands.includes(band);
+//# sourceMappingURL=targets.js.map

package/dist/src/capabilities/setup/targets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"targets.js","sourceRoot":"","sources":["../../../../src/capabilities/setup/targets.ts"],"names":[],"mappings":"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"}

package/dist/src/capabilities/setup/types.js

@@ -0,0 +1,5 @@
+/**
+ * Data shapes for `pragma setup` and its sub-verbs.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/capabilities/setup/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/capabilities/setup/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/src/capabilities/shared/assertExecOk.js

@@ -0,0 +1,137 @@
+/**
+ * Guard an `exec`-composing Task against a silently-swallowed nonzero exit.
+ *
+ * The `@canonical/task` interpreter RESOLVES the `exec` effect on a nonzero exit
+ * code — it only REJECTS on a spawn error (e.g. ENOENT). A consumer that yields
+ * `exec` and ignores `ExecResult.exitCode` therefore reports a failed command
+ * (the common case being an EACCES-denied global `npm i -g`) as a silent
+ * success, discarding the subprocess's own stderr. Every `exec` consumer in
+ * `next/src` (`upgrade`, `setup lsp`) calls this immediately after its `exec`
+ * yield, so a failed subprocess surfaces as UNSUPPORTED (exit 1) carrying the
+ * command and the captured stderr instead of being reported as done.
+ *
+ * A denied `npm i -g` (EACCES), a registry/network failure, or any other
+ * nonzero exit is a fixable ENVIRONMENT condition — NOT a pragma bug — so it is
+ * classified UNSUPPORTED with an actionable recovery, never INTERNAL_ERROR's
+ * "report this issue". (A spawn error like ENOENT REJECTS the effect
+ * instead of resolving, so it never reaches here.)
+ */
+import { fail, pure, recover, } from "@canonical/task";
+import { PragmaError } from "../../kernel/error/index.js";
+/**
+ * Route a {@link PragmaError} through the Task FAILURE CHANNEL (a `Fail` node
+ * carrying the error as `cause`) instead of a synchronous throw.
+ *
+ * The distinction is load-bearing: a synchronous throw from a bind/recover
+ * continuation ESCAPES the interpreter's trampoline entirely — no enclosing
+ * `recover` can see it — whereas a `Fail` node unwinds to the nearest recovery
+ * frame. Setup's run-all isolates each step with `recover` so one failed step
+ * cannot abort the rest (S1-1); that only works if step failures travel the
+ * failure channel. The boundary (`asPragmaError`) unwraps the carried cause,
+ * so a failure that escapes un-recovered still renders with its own code,
+ * message, and recovery — never the INTERNAL_ERROR catch-all.
+ */
+export function failPragma(error) {
+    return fail({ code: error.code, message: error.message, cause: error });
+}
+/**
+ * The failure-channel sibling of {@link assertExecOk}: yield `pure(undefined)`
+ * on exit 0, otherwise fail with an UNSUPPORTED {@link PragmaError} carrying
+ * the command, exit code, trimmed stderr, and the CALLER'S recovery — the
+ * recovery must name an action that works on this machine now, not the generic
+ * "permissions or network" guess.
+ *
+ * @param command - Human-readable command, surfaced in the error message.
+ * @param result - The {@link ExecResult} the `exec` effect yielded.
+ * @param recovery - The actionable, site-specific recovery.
+ * @returns A Task that succeeds on exit 0 and fails (recoverably) otherwise.
+ */
+export function checkExecOk(command, result, recovery) {
+    if (result.exitCode === 0)
+        return pure(undefined);
+    const stderr = result.stderr.trim();
+    return failPragma(new PragmaError({
+        code: "UNSUPPORTED",
+        message: `\`${command}\` exited with code ${result.exitCode}.${stderr ? `\n${stderr}` : ""}`,
+        recovery,
+    }));
+}
+/**
+ * Raise UNSUPPORTED when an `exec` result carries a nonzero exit code.
+ *
+ * @param command - Human-readable command, surfaced in the error message.
+ * @param result - The {@link ExecResult} the `exec` effect yielded.
+ * @throws PragmaError UNSUPPORTED (exit 1) when `result.exitCode !== 0`,
+ *   including the trimmed stderr when the subprocess emitted any, plus an
+ *   actionable recovery (a permissions/network failure the user can retry).
+ */
+export function assertExecOk(command, result) {
+    if (result.exitCode === 0)
+        return;
+    const stderr = result.stderr.trim();
+    throw new PragmaError({
+        code: "UNSUPPORTED",
+        message: `\`${command}\` exited with code ${result.exitCode}.${stderr ? `\n${stderr}` : ""}`,
+        recovery: {
+            message: "Check the command's output above; a global install may need elevated privileges.",
+        },
+    });
+}
+/**
+ * True when a rejected/normalised `exec` error is a missing-binary spawn failure.
+ *
+ * A spawn `ENOENT` (the command is absent from PATH) REJECTS the `exec` effect —
+ * unlike a nonzero exit, which RESOLVES it (see {@link assertExecOk}). The task
+ * interpreter normalises that reject into a `FILE_NOT_FOUND` TaskError carrying
+ * the raw spawn error as `.cause`, so this unwraps one level to recognise both
+ * the raw and normalised shapes.
+ *
+ * @param error - The thrown/rejected value (raw spawn error or its TaskError).
+ * @returns Whether it denotes a binary missing from PATH.
+ */
+export function isMissingBinaryError(error) {
+    const codeOf = (value) => value && typeof value === "object" && "code" in value
+        ? value.code
+        : undefined;
+    if (codeOf(error) === "ENOENT")
+        return true;
+    const cause = error?.cause;
+    return codeOf(cause) === "ENOENT";
+}
+/**
+ * Wrap an `exec`-composing Task so a missing-binary spawn (ENOENT) surfaces as a
+ * named UNSUPPORTED "`<bin>` not found on PATH" error with actionable recovery,
+ * rather than the interpreter's raw reject collapsing to INTERNAL_ERROR ("please
+ * report this issue") at the CLI/MCP boundary. Every spawn site that may hit an
+ * absent binary (`upgrade`'s package manager, `setup lsp`'s `bunx`) wraps its
+ * Task with this so they never reach the catch-all.
+ *
+ * Only real execution can trip it: a dry-run/plan mocks `exec` (exit 0, no
+ * spawn), so the guard is transparent to the preview. A nonzero exit RESOLVES
+ * the effect and is still {@link assertExecOk}'s job (its throw is a synchronous
+ * generator-body throw, not an effect failure, so it bypasses this handler); any
+ * other effect failure re-raises unchanged.
+ *
+ * @param bin - The binary name surfaced in the error message.
+ * @param recovery - The install/PATH recovery hint.
+ * @param task - The Task whose `exec` effect may reject with ENOENT.
+ * @returns The Task, guarded against a missing-binary spawn.
+ */
+export function guardMissingBinary(bin, recovery, task) {
+    return recover(task, (error) => {
+        if (isMissingBinaryError(error)) {
+            // Failure CHANNEL, not a synchronous throw: an enclosing recover (the
+            // run-all's per-step isolation, S1-1) must be able to catch this, and
+            // the boundary unwraps the carried PragmaError when nothing does.
+            return failPragma(new PragmaError({
+                code: "UNSUPPORTED",
+                message: `\`${bin}\` was not found on your PATH.`,
+                recovery,
+            }));
+        }
+        // Not a missing binary — re-raise unchanged (the interpreter rethrows it as
+        // a TaskExecutionError, exactly as it would with no guard installed).
+        return fail(error);
+    });
+}
+//# sourceMappingURL=assertExecOk.js.map

package/dist/src/capabilities/shared/assertExecOk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assertExecOk.js","sourceRoot":"","sources":["../../../../src/capabilities/shared/assertExecOk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAEL,IAAI,EACJ,IAAI,EACJ,OAAO,GAER,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAE1D;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,UAAU,CAAC,KAAkB;IAC3C,OAAO,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;AAC1E,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,WAAW,CACzB,OAAe,EACf,MAAkB,EAClB,QAAkB;IAElB,IAAI,MAAM,CAAC,QAAQ,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC;IAClD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IACpC,OAAO,UAAU,CACf,IAAI,WAAW,CAAC;QACd,IAAI,EAAE,aAAa;QACnB,OAAO,EAAE,KAAK,OAAO,uBAAuB,MAAM,CAAC,QAAQ,IACzD,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC,CAAC,EAC3B,EAAE;QACF,QAAQ;KACT,CAAC,CACH,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe,EAAE,MAAkB;IAC9D,IAAI,MAAM,CAAC,QAAQ,KAAK,CAAC;QAAE,OAAO;IAClC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IACpC,MAAM,IAAI,WAAW,CAAC;QACpB,IAAI,EAAE,aAAa;QACnB,OAAO,EAAE,KAAK,OAAO,uBAAuB,MAAM,CAAC,QAAQ,IACzD,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC,CAAC,EAC3B,EAAE;QACF,QAAQ,EAAE;YACR,OAAO,EACL,kFAAkF;SACrF;KACF,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAc;IACjD,MAAM,MAAM,GAAG,CAAC,KAAc,EAAW,EAAE,CACzC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,IAAI,KAAK;QACnD,CAAC,CAAE,KAA2B,CAAC,IAAI;QACnC,CAAC,CAAC,SAAS,CAAC;IAChB,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC5C,MAAM,KAAK,GAAI,KAAgD,EAAE,KAAK,CAAC;IACvE,OAAO,MAAM,CAAC,KAAK,CAAC,KAAK,QAAQ,CAAC;AACpC,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,kBAAkB,CAChC,GAAW,EACX,QAAkB,EAClB,IAAa;IAEb,OAAO,OAAO,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,EAAE;QAC7B,IAAI,oBAAoB,CAAC,KAAK,CAAC,EAAE,CAAC;YAChC,sEAAsE;YACtE,sEAAsE;YACtE,kEAAkE;YAClE,OAAO,UAAU,CACf,IAAI,WAAW,CAAC;gBACd,IAAI,EAAE,aAAa;gBACnB,OAAO,EAAE,KAAK,GAAG,gCAAgC;gBACjD,QAAQ;aACT,CAAC,CACH,CAAC;QACJ,CAAC;QACD,4EAA4E;QAC5E,sEAAsE;QACtE,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC;IACrB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/src/capabilities/shared/bands.js

@@ -0,0 +1,16 @@
+/**
+ * User-facing labels for the two config bands, shared by the setup recap
+ * ({@link ../setup/setup.render}) and the doctor report
+ * ({@link ../doctor/doctor.render}) so ONE consistent vocabulary appears across
+ * both. The pair matches the CLI grammar users already meet elsewhere: the
+ * `--global`/`--local` flags, the `--scope project|global|both` enum, config
+ * show's `[global]`/`[project]` origin markers, and the `setup` manifest's
+ * `[global]`/`[project]` lines. (Earlier these two surfaces said MACHINE/PROJECT
+ * — a third term for the same bands; this is the single source that unifies it.)
+ */
+/** The user-facing display label for each of the two config bands. */
+export const BAND_LABELS = {
+    global: "Global",
+    project: "Project",
+};
+//# sourceMappingURL=bands.js.map

package/dist/src/capabilities/shared/bands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bands.js","sourceRoot":"","sources":["../../../../src/capabilities/shared/bands.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,sEAAsE;AACtE,MAAM,CAAC,MAAM,WAAW,GAAyC;IAC/D,MAAM,EAAE,QAAQ;IAChB,OAAO,EAAE,SAAS;CACnB,CAAC"}