@canonical/pragma-cli 0.34.0 → 0.36.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,435 @@
+/**
+ * THE target table — the one list `setup` and `doctor` both read.
+ *
+ * Five rows, each with a scope 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 scopes 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,
+  ownedLspEditors,
+} 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,
+  skillsSkipRemedy,
+  staleSkillLinks,
+} from "./operations/setupSkills.js";
+import {
+  type PlanAction,
+  type PlanChildRow,
+  type SetupPlan,
+  shortenPath,
+  type TargetId,
+} from "./plan.js";
+import type { Scope } 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 scopes: readonly Scope[];
+  /** Real reads, up front, once per (target, scope) per invocation. */
+  detect(rt: PragmaRuntime, scope: Scope): Promise<D>;
+  /** What a forward run would do. */
+  plan(detection: D, scope: Scope, roots: Roots): TargetDraft;
+  /** What a removal would do — composed from what detection says we own. */
+  removalPlan(detection: D, scope: Scope, 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",
+  scopes: ["global"],
+  detect: () => detectConfigFile(),
+  plan: (d, _scope, roots) => {
+    const path = shortenPath(d.path, roots);
+    if (!d.exists) return { action: "install", detail: path };
+    return { action: "none", detail: `${path} — present` };
+  },
+  removalPlan: (d, _scope, 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: `it holds your own settings, so ${path} stays`,
+      };
+    }
+    return { action: "remove", detail: path };
+  },
+  compose: (d) => composeConfigFile(d),
+  composeRemoval: (d) => composeConfigRemoval(d),
+});
+
+const completionsTarget = defineTarget<CompletionsDetection>({
+  id: "completions",
+  title: "Shell completions",
+  scopes: ["global"],
+  detect: (rt) => detectCompletions(rt.cwd),
+  plan: (d, _scope, 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)}`;
+    // A no-op row says what it FOUND, not just where it looked: `no change`
+    // beside a bare path leaves the reader to guess whether the script is
+    // there and current or missing and unreachable.
+    if (d.state === "installed") {
+      return { action: "none", detail: `${where} — already up to date` };
+    }
+    return {
+      action: d.state === "stale" ? "update" : "install",
+      detail: where,
+    };
+  },
+  removalPlan: (d, _scope, 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",
+  scopes: ["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),
+    }));
+    // The detail names WHAT is being placed and WHERE — never the row's own
+    // state, which the action column already carries. `installed (VSCodium)`
+    // beside a child row reading `codium — VSCodium (unchanged)` said the
+    // editor's name twice and "nothing happens here" twice.
+    if (d.state === "installed") {
+      return {
+        action: "none",
+        detail: `Terrazzo extension in ${lspEditorNames(d).join(", ")}`,
+        children,
+      };
+    }
+    const pending = d.editors.filter((e) => !e.installed);
+    return {
+      action: "install",
+      detail: `Terrazzo extension → ${pending
+        .map((e) => e.editor.name)
+        .join(", ")}`,
+      children,
+    };
+  },
+  removalPlan: (d) => {
+    // No editor CLI on PATH is the SAME named skip the forward plan reports:
+    // there is nothing on this machine to run an uninstall with.
+    if (d.state === "unknown") {
+      return {
+        action: "skip",
+        detail: lspSkipReason(d),
+        reason: lspSkipReason(d),
+        remedy: LSP_SKIP_REMEDY,
+      };
+    }
+    // Removal is composed from what detection says we OWN — a copy that is
+    // present, whatever its version. The forward plan's version gate would let
+    // a dead pre-0.8.3 copy this command installed survive its own `--undo`.
+    const owned = ownedLspEditors(d);
+    if (owned.length === 0) {
+      return { action: "none", detail: "no editor carries the extension" };
+    }
+    return {
+      action: "remove",
+      detail: `Terrazzo extension from ${owned
+        .map((e) => e.editor.name)
+        .join(", ")}`,
+      children: owned.map((e) => ({
+        key: e.editor.cli,
+        label: `${e.editor.cli} — ${e.editor.name}`,
+        action: "update" as const,
+      })),
+    };
+  },
+  compose: (d, chosen) => composeLsp(d, chosen),
+  composeRemoval: (d) => composeLspRemoval(d),
+});
+
+/**
+ * Why the `mcp` row has nothing to write in a scope — authored once, because
+ * `setup`'s row and `doctor`'s row are the same finding and must not word it
+ * differently. Neither sentence says "scope": the two scopes are `global` and
+ * `local project`, after the `--global` / `--local` flags that select them.
+ */
+export const MCP_NO_LOCATION: Record<Scope, string> = {
+  global: "no AI harness on this machine keeps a global config",
+  project: "no AI harness in this project keeps a per-project config",
+};
+
+/** 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 === "registered"
+        ? "unchanged"
+        : state === "drifted"
+          ? "update"
+          : "add",
+  };
+};
+
+const mcpTarget = defineTarget<McpDetection>({
+  id: "mcp",
+  title: "MCP server registration",
+  scopes: ["global", "project"],
+  detect: (rt, scope) => detectMcp(rt, scope),
+  plan: (d, scope, roots) => {
+    if (d.groups.length === 0) {
+      return {
+        action: "skip",
+        detail: MCP_NO_LOCATION[scope],
+        reason: MCP_NO_LOCATION[scope],
+      };
+    }
+    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 ? "config file" : "config files"
+      }`,
+      children,
+    };
+  },
+  removalPlan: (d, _scope, 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 ? "config file" : "config 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",
+  scopes: ["global", "project"],
+  detect: (rt, scope) => detectSkills(rt, scope),
+  plan: (d, scope, roots) => {
+    // A forward run RECONCILES: stale links this scope owns are its work too, so
+    // an orphan-only tree is actionable rather than a row that plans `none` and
+    // is then deselected into doing nothing. `staleSkillLinks` carries the
+    // absent-root safety gate, so a machine whose source root does not exist
+    // contributes no sweep and the row falls back to the honest skip.
+    const stale = staleSkillLinks(d);
+    if (!d.available && stale.length === 0) {
+      const short = shortenPath(d.sourceRoot, roots);
+      const reason = skillsSkipReason(short, scope, d.rootExists);
+      // A skip with no remedy is a dead end — this one names the command that
+      // fills the scope's source root, exactly as the completions and lsp skips
+      // beside it name theirs.
+      return {
+        action: "skip",
+        detail: reason,
+        reason,
+        remedy: skillsSkipRemedy(short, scope),
+      };
+    }
+    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 ? "folder" : "folders"} (${dirs})`;
+    const detail =
+      stale.length === 0
+        ? where
+        : `${where}, ${stale.length} stale ${stale.length === 1 ? "link" : "links"} to remove`;
+    const pending = d.actions.filter((a) => a.action !== "skipped");
+    if (pending.length > 0) return { action: "link", detail };
+    // Nothing to link, but something to retire: `update` is the table's word
+    // for "this row has work that is not a fresh install".
+    if (stale.length > 0) return { action: "update", detail };
+    return { action: "none", detail };
+  },
+  removalPlan: (d, _scope, 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 scope. */
+export const supportsScope = (target: AnyTarget, scope: Scope): boolean =>
+  target.scopes.includes(scope);