@canonical/pragma-cli 0.34.0 → 0.35.0

package/src/capabilities/setup/setup.verb.ts

@@ -1,49 +1,73 @@
 /**
- * The `setup` verbs — the run-all self-verb plus the four CLI-only sub-verbs
- * (`mcp`/`completions`/`skills`/`lsp`).
+ * The `setup` verbs — the run-all self-verb plus the five CLI-only sub-verbs
+ * (`config`/`completions`/`lsp`/`mcp`/`skills`), every one of them derived from
+ * the target table.
  *
  * `setup` is the ONE covenant noun that is BOTH directly runnable and has
- * sub-verbs (see the buildProgram mixed-noun change). All five are storeless,
- * interactive mutations. The sub-verbs are `mcp: false` (the covenant marks
- * them so — `buildServer` skips them, `buildProgram` still registers them); only
- * the self-verb `setup` is an MCP tool. `destructive: false` (D4) keeps MCP from
- * advertising the `setup` tool as destructive.
+ * sub-verbs. All of them are storeless, interactive mutations. The sub-verbs are
+ * `mcp: false` (`buildServer` skips them, `buildProgram` still registers them);
+ * only the self-verb is an MCP tool. `destructive: false` keeps MCP from
+ * advertising the tool as destructive.
  *
- * ALL FIVE now flow through the SAME summon `execute` seam `create` uses: each
- * `run` synthesizes a `GeneratorDefinition` (detection up front, a pure
- * `generate`), picks the Ink wizard / auto / MCP strategy off `rt.interaction`,
- * and returns `execute` — so setup inherits the recap, live progress, colours,
- * and the shared cancel fixes. summon-core + the generator ops stay behind a
- * LAZY dynamic import (mirroring `create`'s `loadCreateRuntime`), so building the
- * command tree / `--help` / `__complete` — and `setup --yes` — load no
- * React/Ink. `params: []` on every verb keeps the command surface frozen.
+ * THE BAND DEFAULT IS GLOBAL. `--scope` used to default to `both`, and `both`
+ * runs each harness's own default band — which is `project` for most of the
+ * registry — so a bare `setup` scattered `.mcp.json`, `.gemini/settings.json`
+ * and `opencode.json` into whatever directory you happened to be standing in.
+ * The user band is what a machine-level installer configures; the project band
+ * is a deliberate, checked-in, team-shared choice, and is now chosen with
+ * `--local` rather than assumed.
+ *
+ * Every sub-verb registers the scope flags UNIFORMLY. That is what lets the band
+ * answer come from the table instead of per-verb flag wiring — previously
+ * `setup completions --local` died as an unknown option, while `setup mcp
+ * --local` worked, for no reason a user could see. Asking a target for a band it
+ * cannot honour is a usage error (exit 2) with the corrected command; asking the
+ * RUN-ALL for such a band merely filters, and the out-of-band target still shows
+ * as a named row.
+ *
+ * summon-core + the generator ops stay behind a LAZY dynamic import (mirroring
+ * `create`'s `loadCreateRuntime`), so building the command tree / `--help` /
+ * `__complete` — and `setup --yes` — load no React/Ink.
  */
 
 import type { GeneratorResult } from "@canonical/summon-core";
-import { $, gen, type Task } from "@canonical/task";
+import { $, gen, pure, type Task } from "@canonical/task";
 import { BIN_NAME } from "../../constants.js";
-import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+import { PragmaError } from "../../kernel/error/index.js";
+import type { PragmaRuntime } from "../../kernel/runtime/index.js";
 import { asVerb } from "../../kernel/spec/asVerb.js";
 import type {
   CapabilityModule,
   ParamSpec,
   VerbSpec,
-} from "../../kernel/spec/types.js";
-import { setupFormatters } from "./setup.render.js";
-import type { ScopeSelection, SetupMode, SetupResult } from "./types.js";
+} from "../../kernel/spec/index.js";
+import { resolveSetupMode, setupModeInput } from "./mode.js";
+import {
+  planExitFailed,
+  planTally,
+  type SetupPlan,
+  TARGET_IDS,
+} from "./plan.js";
+import { renderProgressLine, renderRecap } from "./plan.render.js";
+import { renderDryRun, setupFormatters } from "./setup.render.js";
+import type { ScopeBand, ScopeSelection, SetupMode } from "./types.js";
 
 /**
- * The `--scope` flag + its `--global`/`--local` boolean sugars, shared by the
- * band-aware verbs (`setup`/`mcp`/`skills`). `completions`/`lsp` never carry
- * them — they are single-band installers.
+ * The `--scope` flag + its `--global`/`--local` boolean sugars. Registered by
+ * EVERY setup verb, including the single-band ones: a flag that exists on some
+ * sub-verbs and not others is a grammar the user has to memorise, and the band
+ * a single-band target can honour is a question the target table answers.
+ *
+ * `--global` is a synonym of the default; it stays for scripts and for symmetry
+ * with `--local`.
  */
 const SCOPE_PARAMS: readonly ParamSpec[] = [
   {
     kind: "enum",
     name: "scope",
-    doc: "Which config band(s) to configure: project, global, or both.",
+    doc: "Which config band(s) to configure: global (the default), project, or both.",
     values: ["project", "global", "both"],
-    default: "both",
+    default: "global",
   },
   {
     kind: "boolean",
@@ -62,13 +86,46 @@ const SCOPE_PARAMS: readonly ParamSpec[] = [
  * The boolean sugars win over `--scope`; `--global` wins over `--local`.
  *
  * @param params - The coerced param bag.
- * @returns The resolved scope selection (defaults to `both`).
+ * @returns The resolved scope selection (defaults to `global`).
  */
 function resolveScope(params: Record<string, unknown>): ScopeSelection {
   if (params.global === true) return "global";
   if (params.local === true) return "project";
   const scope = params.scope;
-  return scope === "global" || scope === "project" ? scope : "both";
+  return scope === "project" || scope === "both" ? scope : "global";
+}
+
+/**
+ * Reject a sub-verb asked for a band its target cannot hold.
+ *
+ * This is a usage error, not a skip: the user typed a contradiction, and
+ * correcting it is exactly what exit 2 means. The message names the band the
+ * target DOES have and prints the command that works, so the correction is one
+ * paste rather than one manual page.
+ *
+ * @param mode - The sub-verb's target, or `all`.
+ * @param scope - The resolved selection.
+ * @throws PragmaError INVALID_INPUT when the target has no such band.
+ */
+async function assertBandIsPossible(
+  mode: SetupMode,
+  scope: ScopeSelection,
+): Promise<void> {
+  if (mode === "all" || scope === "both") return;
+  const { findTarget } = await import("./targets.js");
+  const target = findTarget(mode);
+  if (target === undefined || target.bands.includes(scope as ScopeBand)) return;
+  const only = target.bands[0] as ScopeBand;
+  const level = only === "global" ? "user-level" : "project-level";
+  const corrected =
+    only === "global"
+      ? `${BIN_NAME} setup ${mode}`
+      : `${BIN_NAME} setup ${mode} --local`;
+  throw new PragmaError({
+    code: "INVALID_INPUT",
+    message: `${mode} is ${level} — it has no ${scope} band.`,
+    recovery: { message: `Run: ${corrected}` },
+  });
 }
 
 /** The exposed-to-MCP capability the run-all self-verb declares. */
@@ -101,38 +158,59 @@ const SUB_CAPABILITY = {
 
 /**
  * The one summon↔pragma seam per setup invocation: lazily load summon-core + the
- * generator ops, build the plan (detection up front), pick the prompt strategy
- * off `rt.interaction`, wire `rt.exec`, and return `execute` mapped back onto
- * {@link SetupResult}.
+ * generator ops, detect and plan, resolve the interaction mode, wire `rt.exec`,
+ * and return the plan with its outcomes filled in.
  *
  * NOTE: `rt.exec` carries NO per-call `cwd`. Unlike `create` (whose generator
- * emits RELATIVE paths jailed to `rt.cwd`), setup's ops build ABSOLUTE effect
- * paths themselves ($HOME/…, resolve(cwd,…)); the interpreter leaves absolute
- * paths unchanged, so no per-call write root is threaded. No stamping either —
- * setup writes symlinks / config / scripts, not generated source.
+ * emits RELATIVE paths jailed to `rt.cwd`), setup's targets build ABSOLUTE
+ * effect paths themselves; the interpreter leaves absolute paths unchanged, so
+ * no per-call write root is threaded. No stamping either — setup writes
+ * symlinks, config and scripts, not generated source.
  *
- * @param mode - Which entry point (`all` or one sub-verb).
- * @param rt - The per-invocation runtime (mutated: `rt.exec` is set).
- * @returns The `Task<SetupResult>` the dispatcher/MCP handler interprets.
- * @note Impure — runs each step's real detection; may throw EMPTY_RESULTS
- *   (direct `setup skills` with no skills) before returning a Task.
+ * @param mode - Which entry point (`all` or one target).
+ * @param rt - The per-invocation runtime (mutated: `rt.exec` and `rt.planData`).
+ * @param scope - The resolved band selection.
+ * @returns The `Task<SetupPlan>` the dispatcher/MCP handler interprets.
+ * @note Impure — runs every target's real detection before returning a Task.
  */
 async function runSetup(
   mode: SetupMode,
   rt: PragmaRuntime,
   scope: ScopeSelection,
-): Promise<Task<SetupResult>> {
-  // Lazy dynamic imports (R1 lazy-React discipline): summon-core's barrel is
+): Promise<Task<SetupPlan>> {
+  await assertBandIsPossible(mode, scope);
+
+  // Lazy dynamic imports (lazy-React discipline): summon-core's barrel is
   // React-free, and the non-TTY branch picks autoPrompt/mcpPrompt (never mounts
   // Ink), so `setup --yes` loads no React — the guard test enforces this.
-  const [summon, ops] = await Promise.all([
+  const [summon, projection, ops] = await Promise.all([
     import("@canonical/summon-core"),
+    import("@canonical/summon-core/projection"),
     import("./operations/setupGenerator.js"),
   ]);
 
-  const { generator, toResult } = await ops.buildSetupPlan(rt, mode, scope);
+  const input = setupModeInput(rt);
+  const run = await ops.buildSetupRun(rt, mode, scope, input.undo);
+  const interactionMode = resolveSetupMode(input, projection.decideInteraction);
+
+  // The dry-run seam: the kernel's `--dry-run` branch renders THIS instead of
+  // the raw effect dump, while its honest preview still runs underneath and
+  // still fails exactly when the real run would.
+  rt.planData = { ...run.plan, preview: true };
+
+  // Whether this invocation only PREVIEWS. The task below is driven either way
+  // — that is what makes the preview honest — so anything it says out loud has
+  // to know which of the two it is.
+  const previewing = interactionMode === "batch-dry-run";
+
+  // Adaptation (b): a non-interactive run without `--yes` previews rather than
+  // mutating. It is the same plan the dry-run prints, plus one hint line, at
+  // exit 0 — the invocation completed a real read-only unit of work.
+  if (interactionMode === "refuse") {
+    return pure<SetupPlan>({ ...run.plan, preview: true });
+  }
 
-  const { isTTY, transport, yes, signal, abort } = rt.interaction ?? {
+  const { transport, yes, signal, abort } = rt.interaction ?? {
     isTTY: false,
     transport: "cli" as const,
     yes: true,
@@ -140,10 +218,14 @@ async function runSetup(
 
   // TTY without --yes → the Ink wizard (recap + live progress). Its callbacks
   // ride rt.exec; `onCancel` threads the run's abort in so an in-Ink Ctrl-C
-  // during execution actually stops the writes (H2). No stamping (A5).
+  // during execution actually stops the writes.
   let task: Task<GeneratorResult>;
-  if (isTTY && !yes) {
-    const session = summon.inkPrompt(generator, { signal, onCancel: abort });
+  const wizard = interactionMode === "wizard";
+  if (wizard) {
+    const session = summon.inkPrompt(run.generator, {
+      signal,
+      onCancel: abort,
+    });
     rt.exec = {
       promptHandler: session.promptHandler,
       onEffectStart: session.onEffectStart,
@@ -152,7 +234,7 @@ async function runSetup(
       dispose: session.dispose,
       signal,
     };
-    task = summon.execute(generator, {
+    task = summon.execute(run.generator, {
       prompt: session.promptHandler,
       params: {},
       signal,
@@ -166,56 +248,117 @@ async function runSetup(
       onLog: (_level, message) => process.stderr.write(`${message}\n`),
       signal,
     };
-    task = summon.execute(generator, { prompt, params: {}, signal });
+    task = summon.execute(run.generator, { prompt, params: {}, signal });
   }
 
-  // execute yields a GeneratorResult; map it back onto setup's tagged result
-  // union (its --format json shape is frozen). The completion view is driven by
-  // controller phase, not this value, so mapping after execute is invisible to
-  // the wizard.
   return gen(function* () {
     const result = yield* $(task);
-    return toResult(result.answers);
+    const applied = run.applied(result.answers);
+
+    // Progress: one line per row on stderr for an unattended run (the Ink
+    // session already draws them for the wizard). stdout stays the data stream.
+    //
+    // A dry run reports NOTHING here. Its honest preview drives this very task
+    // with writes recorded, so the progress lines ran for real and announced
+    // "✓ config — installed" above a plan that had installed nothing.
+    if (!previewing && (!wizard || yes)) {
+      const width = Math.max(...applied.rows.map((row) => row.target.length));
+      for (const row of applied.rows) {
+        if (row.outcome === undefined) continue;
+        rt.report?.(renderProgressLine(row, width));
+      }
+    }
+
+    // A failed row exits 1, and the recap is still shown — partial success is
+    // first class, so the run reports every row before naming the ones that did
+    // not happen. The recap goes to stderr here because the error renderer owns
+    // stdout on a failing run.
+    if (planExitFailed(applied)) {
+      rt.report?.(renderRecap(applied));
+      const failed = applied.rows.filter(
+        (row) => row.outcome?.status === "failed",
+      );
+
+      // ONE failure reports itself. The row already carries the cause it was
+      // given ("`bun` is not found on your PATH") and a remedy that runs on
+      // this machine; replacing them with a count would throw away the only
+      // two sentences that say what is wrong and what to do about it.
+      const only = failed.length === 1 ? failed[0] : undefined;
+      if (only?.outcome !== undefined) {
+        throw new PragmaError({
+          code: "UNSUPPORTED",
+          message: `${only.target}: ${only.outcome.note ?? "the step did not complete"}`,
+          ...(only.outcome.remedy === undefined
+            ? {}
+            : { recovery: { message: only.outcome.remedy } }),
+        });
+      }
+
+      // Several failures: name every one with its own cause, then point at the
+      // recap above. A bare list of target names would make the reader re-run
+      // each one to find out why it failed.
+      const named = failed
+        .map(
+          (row) =>
+            `${row.target} (${row.outcome?.note ?? "no cause recorded"})`,
+        )
+        .join("; ");
+      throw new PragmaError({
+        code: "UNSUPPORTED",
+        message: `${failed.length} of ${planTally(applied).accountable} targets did not complete: ${named}.`,
+        recovery: {
+          message: `The other targets are configured. Re-run the ones that did not complete: ${failed
+            .map((row) => `\`${BIN_NAME} setup ${row.target}\``)
+            .join(", ")}.`,
+        },
+      });
+    }
+    return applied;
   });
 }
 
 /** Build a setup verb bound to its {@link SetupMode}. */
 function setupVerb(
-  path: VerbSpec<Record<string, unknown>, SetupResult>["path"],
+  path: VerbSpec<Record<string, unknown>, SetupPlan>["path"],
   summary: string,
   mode: SetupMode,
   capability: typeof SELF_CAPABILITY | typeof SUB_CAPABILITY,
-  extras: Partial<VerbSpec<Record<string, unknown>, SetupResult>> = {},
-): VerbSpec<Record<string, unknown>, SetupResult> {
+  extras: Partial<VerbSpec<Record<string, unknown>, SetupPlan>> = {},
+): VerbSpec<Record<string, unknown>, SetupPlan> {
   return {
     path,
     summary,
-    params: [],
-    output: { formatters: setupFormatters },
+    params: SCOPE_PARAMS,
+    output: {
+      formatters: setupFormatters,
+      // The kernel's dry-run branch renders the plan through this seam instead
+      // of dumping raw effects. Absent on every other verb, so nothing else
+      // changes shape.
+      formatPlan: (planData) => renderDryRun(planData as SetupPlan),
+    },
     capability,
     ...extras,
     run: (params, rt) =>
-      runSetup(mode, rt, resolveScope(params)) as unknown as Task<SetupResult>,
+      runSetup(mode, rt, resolveScope(params)) as unknown as Task<SetupPlan>,
   };
 }
 
 const setupAllVerb = setupVerb(
   ["setup"],
-  "Configure MCP, completions, skills, and the LSP for this project.",
+  "Configure the global config, completions, the LSP, MCP, and skills.",
   "all",
   SELF_CAPABILITY,
   {
-    params: SCOPE_PARAMS,
-    doc: "Runs the shell-completions, LSP, MCP, and skills installers as a single wizard: pick the steps, review the recap, then apply. The scope option targets the project band, the user/home band, or both.",
+    doc: "Plans every target in the selected band, then applies the ones you keep. The user/home band is the default; the scope option chooses the per-project band, or both. A run with no attended terminal prints the plan and applies nothing unless the run is confirmed.",
     examples: [
       { cmd: `${BIN_NAME} setup` },
       {
         cmd: `${BIN_NAME} setup --dry-run`,
-        note: "preview every step's effects",
+        note: "print the plan, write nothing",
       },
       {
-        cmd: `${BIN_NAME} setup --global`,
-        note: "configure only the user/home band",
+        cmd: `${BIN_NAME} setup --local`,
+        note: "configure the project band instead",
       },
       {
         cmd: `${BIN_NAME} setup mcp`,
@@ -225,12 +368,18 @@ const setupAllVerb = setupVerb(
   },
 );
 
+const configVerb = setupVerb(
+  ["setup", "config"],
+  "Create the global config file with its defaults.",
+  "config",
+  SUB_CAPABILITY,
+);
+
 const mcpVerb = setupVerb(
   ["setup", "mcp"],
   `Register the ${BIN_NAME} MCP server in detected AI harnesses.`,
   "mcp",
   SUB_CAPABILITY,
-  { params: SCOPE_PARAMS },
 );
 
 const completionsVerb = setupVerb(
@@ -245,7 +394,6 @@ const skillsVerb = setupVerb(
   "Symlink discovered skills into each AI harness.",
   "skills",
   SUB_CAPABILITY,
-  { params: SCOPE_PARAMS },
 );
 
 const lspVerb = setupVerb(
@@ -255,14 +403,18 @@ const lspVerb = setupVerb(
   SUB_CAPABILITY,
 );
 
-/** The `setup` capability module (run-all self-verb + four CLI-only sub-verbs). */
+/** The `setup` capability module (run-all self-verb + five CLI-only sub-verbs). */
 export const setupModule: CapabilityModule = {
   name: "setup",
   verbs: [
     asVerb(setupAllVerb),
-    asVerb(mcpVerb),
+    asVerb(configVerb),
     asVerb(completionsVerb),
-    asVerb(skillsVerb),
     asVerb(lspVerb),
+    asVerb(mcpVerb),
+    asVerb(skillsVerb),
   ],
 };
+
+/** Re-exported so the covenant emitter and tests can name the target set. */
+export { TARGET_IDS };

package/src/capabilities/setup/shell.test.ts

@@ -0,0 +1,86 @@
+/**
+ * Shell detection — the shell the user is RUNNING, not the one `/etc/passwd`
+ * records.
+ *
+ * The defect these pin: `$SHELL` is the LOGIN shell. It does not change when
+ * you start a different shell, so a user whose account says bash but who works
+ * in zsh was handed a bash completion script — and doctor then reported it
+ * green, for a shell they never open, while zsh had nothing. The failure is
+ * invisible until TAB does nothing months later, which is exactly why an
+ * unresolved shell must be reported rather than guessed.
+ */
+
+import { afterEach, describe, expect, it } from "vitest";
+import { detectShell, type ProcessEntry } from "./shell.js";
+
+/** A fake process tree: pid → entry, walked exactly as /proc would be. */
+const tree = (entries: Record<number, ProcessEntry>) => (pid: number) =>
+  entries[pid];
+
+const prevShell = process.env.SHELL;
+afterEach(() => {
+  process.env.SHELL = prevShell;
+});
+
+describe("the running shell wins over $SHELL", () => {
+  it("reports the shell that actually started this process", () => {
+    // The case from a real machine: login shell bash, working shell zsh.
+    process.env.SHELL = "/bin/bash";
+    const read = tree({
+      [process.ppid]: { name: "zsh", ppid: 100 },
+      100: { name: "systemd", ppid: 1 },
+    });
+    expect(detectShell(read)).toEqual({ kind: "detected", shell: "zsh" });
+  });
+
+  it("walks past the wrappers a CLI is usually reached through", () => {
+    // `npm run` / `bunx` / a shim script put node or sh between the shell and
+    // us, so the immediate parent is almost never the answer.
+    process.env.SHELL = "/bin/bash";
+    const read = tree({
+      [process.ppid]: { name: "node", ppid: 200 },
+      200: { name: "npm", ppid: 300 },
+      300: { name: "fish", ppid: 400 },
+    });
+    expect(detectShell(read)).toEqual({ kind: "detected", shell: "fish" });
+  });
+
+  it("strips the login dash and any path", () => {
+    const read = tree({ [process.ppid]: { name: "-zsh", ppid: 1 } });
+    expect(detectShell(read)).toEqual({ kind: "detected", shell: "zsh" });
+    const path = tree({ [process.ppid]: { name: "/usr/bin/bash", ppid: 1 } });
+    expect(detectShell(path)).toEqual({ kind: "detected", shell: "bash" });
+  });
+});
+
+describe("an unresolved shell is reported, never guessed", () => {
+  it("is ambiguous when only $SHELL has an opinion", () => {
+    // No shell in the ancestry — a CI runner, an editor task, a daemon. The
+    // login shell names a session that may not exist, so it is not an answer.
+    process.env.SHELL = "/bin/bash";
+    const read = tree({
+      [process.ppid]: { name: "node", ppid: 900 },
+      900: { name: "containerd", ppid: 1 },
+    });
+    expect(detectShell(read)).toEqual({ kind: "ambiguous", login: "bash" });
+  });
+
+  it("is unknown when nothing names a supported shell", () => {
+    process.env.SHELL = "/usr/bin/nu";
+    const read = tree({ [process.ppid]: { name: "init", ppid: 1 } });
+    expect(detectShell(read)).toEqual({ kind: "unknown" });
+  });
+
+  it("is unknown when $SHELL is unset and the tree is silent", () => {
+    process.env.SHELL = "";
+    const read = tree({ [process.ppid]: { name: "init", ppid: 1 } });
+    expect(detectShell(read)).toEqual({ kind: "unknown" });
+  });
+
+  it("gives up rather than walking an unbounded tree", () => {
+    // A cycle (or a very deep tree) must terminate.
+    process.env.SHELL = "";
+    const read = (pid: number): ProcessEntry => ({ name: "node", ppid: pid });
+    expect(detectShell(read)).toEqual({ kind: "unknown" });
+  });
+});