@canonical/pragma-cli 0.34.0 → 0.35.0

package/src/capabilities/setup/shell.ts

@@ -1,12 +1,14 @@
 /**
- * Shell detection + completion-script install paths (ported from the old
- * shell's `setup/helpers/detectShell` + `completionScripts` path helpers).
+ * Shell detection + completion-script install paths.
  *
- * The covenant `setup completions` sub-verb carries NO flags, so shell selection
- * is detection-only (the old `--zsh`/`--bash`/`--fish` force-flags are dropped).
+ * 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";
@@ -21,15 +23,139 @@ const SHELL_MAP: Record<string, ShellId> = {
 };
 
 /**
- * Detect the user's shell from `$SHELL`.
+ * What detection concluded about the shell the user is actually in.
  *
- * @returns The detected shell, or `null` when `$SHELL` is unset/unrecognized.
- * @note Impure — reads `process.env.SHELL`.
+ * `ambiguous` is a first-class answer, not a failure to try harder. Installing
+ * for the wrong shell is INVISIBLE: the file is written, `doctor` goes green,
+ * and the user finds out when they press TAB months later and nothing happens.
+ * A named skip that says what was seen is worth more than a confident guess.
  */
-export function detectShell(): ShellId | null {
-  const shell = process.env.SHELL ?? "";
-  const basename = shell.split("/").pop() ?? "";
-  return SHELL_MAP[basename] ?? null;
+export type ShellDetection =
+  | { readonly kind: "detected"; readonly shell: ShellId }
+  | {
+      readonly kind: "ambiguous";
+      /** What `$SHELL` claims, when it names a shell we support. */
+      readonly login: ShellId;
+    }
+  | { readonly kind: "unknown" };
+
+/** One process in the ancestry: what it is called, and who started it. */
+export interface ProcessEntry {
+  readonly name: string;
+  readonly ppid: number;
+}
+
+/** Look up one process. Injected in tests so the tree is deterministic. */
+export type ProcessReader = (pid: number) => ProcessEntry | undefined;
+
+/** 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: number): { name: string; ppid: number } | undefined {
+  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: number): { name: string; ppid: number } | undefined {
+  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: string): ShellId | undefined {
+  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?: ProcessReader): ShellId | undefined {
+  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?: ProcessReader): ShellDetection {
+  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 };
 }
 
 /**

package/src/capabilities/setup/targets.ts

@@ -0,0 +1,367 @@
+/**
+ * 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 type { Task } from "@canonical/task";
+import { BIN_NAME } from "../../constants.js";
+import type { PragmaRuntime } from "../../kernel/runtime/index.js";
+import {
+  type CompletionsDetection,
+  composeCompletions,
+  composeCompletionsRemoval,
+  detectCompletions,
+} from "./operations/setupCompletions.js";
+import {
+  type ConfigDetection,
+  composeConfigFile,
+  composeConfigRemoval,
+  detectConfigFile,
+} from "./operations/setupConfig.js";
+import {
+  composeLsp,
+  composeLspRemoval,
+  detectLsp,
+  LSP_SKIP_REMEDY,
+  type LspDetection,
+  lspEditorNames,
+  lspSkipReason,
+  lspUninstallRemedy,
+} from "./operations/setupLsp.js";
+import {
+  composeMcp,
+  composeMcpRemoval,
+  detectMcp,
+  type McpDetection,
+  mcpGroupState,
+  ownedMcpGroups,
+  selectedGroups,
+} from "./operations/setupMcp.js";
+import {
+  composeSkills,
+  composeSkillsRemoval,
+  detectSkills,
+  ownedSkillLinks,
+  type SkillsDetection,
+  skillsSkipReason,
+} from "./operations/setupSkills.js";
+import {
+  type PlanAction,
+  type PlanChildRow,
+  type SetupPlan,
+  shortenPath,
+  type TargetId,
+} from "./plan.js";
+import type { ScopeBand } from "./types.js";
+
+/** What a target contributes to one plan row, before selection is applied. */
+export interface TargetDraft {
+  readonly action: PlanAction;
+  readonly detail: string;
+  /** REQUIRED when the action is `skip`. */
+  readonly reason?: string;
+  readonly children?: readonly PlanChildRow[];
+  /** An action that works on THIS machine NOW, or absent. */
+  readonly remedy?: string;
+}
+
+/** The context a draft is rendered against — the plan's two named roots. */
+export type Roots = SetupPlan["roots"];
+
+/**
+ * One row of the table, generic over its own detection type. Every consumer
+ * treats the detection as opaque and hands it straight back to the same row,
+ * which is what lets five unrelated detections share one loop.
+ */
+export interface TargetDefinition<D> {
+  readonly id: TargetId;
+  /** Human title, used where a sentence needs one; the id is the row name. */
+  readonly title: string;
+  readonly bands: readonly ScopeBand[];
+  /** Real reads, up front, once per (target, band) per invocation. */
+  detect(rt: PragmaRuntime, band: ScopeBand): Promise<D>;
+  /** What a forward run would do. */
+  plan(detection: D, band: ScopeBand, roots: Roots): TargetDraft;
+  /** What a removal would do — composed from what detection says we own. */
+  removalPlan(detection: D, band: ScopeBand, roots: Roots): TargetDraft;
+  /**
+   * The forward effects. `chosen` is the row's per-child selection (MCP file
+   * paths); a row without children ignores it.
+   */
+  compose(detection: D, chosen?: readonly string[]): Task<void>;
+  /** The removal effects: forward re-assertion carrying the reversal as `undo`. */
+  composeRemoval(detection: D): Task<void>;
+}
+
+/** A table row with its detection type erased — how every consumer holds one. */
+export type AnyTarget = TargetDefinition<never>;
+
+/** Erase a row's detection type so the five rows can share one array. */
+const defineTarget = <D>(target: TargetDefinition<D>): AnyTarget =>
+  target as unknown as AnyTarget;
+
+// =============================================================================
+// The rows
+// =============================================================================
+
+const configTarget = defineTarget<ConfigDetection>({
+  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<CompletionsDetection>({
+  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<LspDetection>({
+  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: PlanChildRow[] = d.editors.map((e) => ({
+      key: e.editor.cli,
+      label: `${e.editor.cli} — ${e.editor.name}`,
+      action: e.installed ? ("unchanged" as const) : ("add" as const),
+    }));
+    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: McpDetection,
+  group: McpDetection["groups"][number],
+  roots: Roots,
+): PlanChildRow => {
+  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<McpDetection>({
+  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" as const,
+      })),
+    };
+  },
+  compose: (d, chosen) =>
+    composeMcp(d, chosen ? selectedGroups(d, chosen) : d.groups),
+  composeRemoval: (d) => composeMcpRemoval(d),
+});
+
+const skillsTarget = defineTarget<SkillsDetection>({
+  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" as const,
+      })),
+    };
+  },
+  compose: (d) => composeSkills(d),
+  composeRemoval: (d) => composeSkillsRemoval(d),
+});
+
+/** THE table, in display order. */
+export const TARGETS: readonly AnyTarget[] = [
+  configTarget,
+  completionsTarget,
+  lspTarget,
+  mcpTarget,
+  skillsTarget,
+];
+
+/** Look a row up by id. */
+export const findTarget = (id: string): AnyTarget | undefined =>
+  TARGETS.find((target) => target.id === id);
+
+/** Whether a target can be installed into a band. */
+export const supportsBand = (target: AnyTarget, band: ScopeBand): boolean =>
+  target.bands.includes(band);

package/src/capabilities/setup/types.ts

@@ -2,14 +2,18 @@
  * Data shapes for `pragma setup` and its sub-verbs.
  */
 
-import type { ShellId } from "./shell.js";
-
 /**
  * Which setup entry point is running: the run-all self-verb or one sub-verb.
  * Lives here (a leaf type module) so `setup.verb.ts` can name it WITHOUT a
  * static import of the generator ops — keeping them dynamic-only (lazy-React).
  */
-export type SetupMode = "all" | "completions" | "lsp" | "mcp" | "skills";
+export type SetupMode =
+  | "all"
+  | "config"
+  | "completions"
+  | "lsp"
+  | "mcp"
+  | "skills";
 
 /**
  * One of the two config bands: the per-user/home `global` band or the per-repo
@@ -20,9 +24,11 @@ export type SetupMode = "all" | "completions" | "lsp" | "mcp" | "skills";
 export type ScopeBand = "project" | "global";
 
 /**
- * The resolved `--scope` selection: which config band(s) a run touches. `both`
- * (the default) runs each detected harness's default band; `global`/`project`
- * run only that band. Structurally mirrors the harnesses `ScopeSelection`.
+ * The resolved `--scope` selection: which config band(s) a run touches.
+ * `global` is the DEFAULT — the user/home band a machine-level installer
+ * configures; `project` is the opt-in per-repository band; `both` is the
+ * explicit "run each band in one invocation". Structurally mirrors the
+ * harnesses `ScopeSelection`.
  */
 export type ScopeSelection = "project" | "global" | "both";
 
@@ -35,18 +41,6 @@ export type ScopeSelection = "project" | "global" | "both";
  */
 export type McpTargetState = "absent" | "configured" | "drifted";
 
-/**
- * One configured MCP target in a result: the file that was written, which band
- * it belongs to, the harness name(s) that share it, and its prior
- * {@link McpTargetState} (so the recap can report new vs updated vs unchanged).
- */
-export interface ConfiguredTarget {
-  readonly name: string;
-  readonly band: ScopeBand;
-  readonly path: string;
-  readonly state: McpTargetState;
-}
-
 /**
  * The prior on-disk state of the shell-completion script, read up front by
  * `detectCompletions`: `absent` (no script), `installed` (a byte-identical
@@ -56,44 +50,11 @@ export interface ConfiguredTarget {
 export type CompletionsState = "absent" | "installed" | "stale";
 
 /**
- * The detected state of the Terrazzo LSP VS Code extension, probed up front by
- * `detectLsp`: `installed` (already present — a re-run skips it), `absent` (not
- * present, so the installer runs), or `unknown` (the `code` CLI is not on PATH,
- * so we cannot enumerate and the installer runs regardless).
+ * The detected state of the Terrazzo LSP extension across the VS Code-family
+ * editors on this machine, probed up front by `detectLsp`: `installed` (every
+ * editor whose CLI is on PATH already has it — a re-run skips), `absent` (at
+ * least one detected editor is missing it, so the sideload runs for those), or
+ * `unknown` (NO editor CLI was found on PATH — the step is a named skip, since
+ * there is nothing to install into).
  */
 export type LspState = "installed" | "absent" | "unknown";
-
-/** One symlink create/skip/replace action performed during skill setup. */
-export interface SymlinkAction {
-  readonly skillName: string;
-  readonly target: string;
-  readonly linkPath: string;
-  readonly action: "created" | "skipped" | "replaced";
-  readonly harnessName: string;
-}
-
-/** Aggregate result of `pragma setup skills`. */
-export interface SetupSkillsResult {
-  readonly actions: readonly SymlinkAction[];
-  readonly harnessCount: number;
-  readonly skillCount: number;
-  readonly warnings: readonly string[];
-}
-
-/** The result of one setup verb, tagged by which verb produced it. */
-export type SetupResult =
-  | {
-      readonly kind: "completions";
-      readonly shell: ShellId | null;
-      readonly path: string | null;
-      readonly installed: boolean;
-      readonly state: CompletionsState;
-    }
-  | { readonly kind: "lsp"; readonly state: LspState }
-  | {
-      readonly kind: "mcp";
-      readonly configured: readonly string[];
-      readonly targets: readonly ConfiguredTarget[];
-    }
-  | { readonly kind: "skills"; readonly result: SetupSkillsResult }
-  | { readonly kind: "all"; readonly steps: readonly string[] };