@canonical/pragma-cli 0.34.0 → 0.35.0

package/src/capabilities/setup/buildPlan.ts

@@ -0,0 +1,236 @@
+/**
+ * Build the plan: run the target table's detections, then project them into
+ * {@link SetupPlan} rows.
+ *
+ * This is the ONE place a plan comes from. The dry-run, the wizard, the apply
+ * phase, the recap and `--format json` all read what this produces, so a row
+ * that is missing here is missing everywhere — which is the point: the run-all
+ * used to build its choices only from DETECTABLE steps, so a target that could
+ * not be offered vanished from the recap and "Setup complete" papered over it.
+ * Every selected target is a visible row here, including the ones that skip.
+ */
+
+import type { PragmaRuntime } from "../../kernel/runtime/index.js";
+import {
+  defaultSelected,
+  type PlanRow,
+  type SetupPlan,
+  type TargetId,
+} from "./plan.js";
+import {
+  type AnyTarget,
+  supportsBand,
+  TARGETS,
+  type TargetDraft,
+} from "./targets.js";
+import type { ScopeBand, ScopeSelection } from "./types.js";
+
+/** One detection, kept beside the row that produced it (and can read it back). */
+export interface DetectedRow {
+  readonly target: AnyTarget;
+  readonly band: ScopeBand;
+  readonly detection: never;
+  /**
+   * Why this row's detection did not settle, when it threw. `detection` is then
+   * meaningless and no reader may touch it — {@link detectionFailure} is the
+   * only question to ask of such a row.
+   */
+  readonly failure?: string;
+}
+
+/** The failure a row's detection ended in, or `undefined` when it settled. */
+export const detectionFailure = (row: DetectedRow): string | undefined =>
+  row.failure;
+
+/** A plan plus the detections behind it — what the apply phase needs. */
+export interface DetectedPlan {
+  readonly plan: SetupPlan;
+  readonly detected: readonly DetectedRow[];
+}
+
+/** The bands a `--scope` selection runs, global before project. */
+export const bandsForScope = (scope: ScopeSelection): readonly ScopeBand[] =>
+  scope === "both" ? ["global", "project"] : [scope];
+
+/**
+ * The two named roots. The global root is the user's home directory (rendered
+ * `~`), the project root is the directory the invocation resolves against.
+ *
+ * @param rt - The per-invocation runtime.
+ * @returns The roots every row path renders relative to.
+ * @note Impure — reads the platform environment.
+ */
+export async function resolveRoots(
+  rt: PragmaRuntime,
+): Promise<SetupPlan["roots"]> {
+  const { readPlatformEnv, userHome } = await import("@canonical/harnesses");
+  return { global: userHome(readPlatformEnv()), project: rt.cwd };
+}
+
+/** The cause a rejected detection carries, as one line of copy. */
+const messageOf = (reason: unknown): string =>
+  reason instanceof Error ? reason.message : String(reason);
+
+/**
+ * Detect every requested target in every band the scope runs.
+ *
+ * Detections are started together and SETTLED INDEPENDENTLY: they are
+ * independent reads, and a run-all that probed five targets serially paid for
+ * it on every invocation.
+ *
+ * Independence is the whole premise, so one detection that throws — an
+ * unreadable config, a permission-denied directory — takes only its own row
+ * down. Awaiting them as one `Promise.all` meant the first rejection prevented
+ * a run from being built at all: none of the other targets ran, and doctor
+ * rendered no banded rows whatsoever. The failed row carries its cause and is
+ * reported as a row, which is the same shape a failed COMPOSE already has.
+ *
+ * @param rt - The per-invocation runtime.
+ * @param ids - The targets to plan (all five for the run-all).
+ * @param scope - The resolved band selection.
+ * @returns One entry per (target, band) the scope actually runs.
+ * @note Impure — every target's `detect` reads the real filesystem.
+ */
+export async function detectTargets(
+  rt: PragmaRuntime,
+  ids: readonly TargetId[],
+  scope: ScopeSelection,
+): Promise<DetectedRow[]> {
+  const wanted = TARGETS.filter((target) => ids.includes(target.id));
+  const pairs = bandsForScope(scope).flatMap((band) =>
+    wanted
+      .filter((target) => supportsBand(target, band))
+      .map((target) => ({
+        target,
+        band,
+      })),
+  );
+  const settled = await Promise.allSettled(
+    pairs.map(({ target, band }) => target.detect(rt, band)),
+  );
+  return pairs.map(({ target, band }, index) => {
+    const outcome = settled[index] as PromiseSettledResult<unknown>;
+    if (outcome.status === "fulfilled") {
+      return { target, band, detection: outcome.value as never };
+    }
+    return {
+      target,
+      band,
+      detection: undefined as never,
+      failure: messageOf(outcome.reason),
+    };
+  });
+}
+
+/**
+ * The dim row a target gets when the SELECTED band cannot hold it — `setup
+ * --local` still shows `completions`, saying why it is not in this run. A band
+ * merely filters the run-all: the user asked for a band, not for that target, so
+ * nothing errors, but nothing is silently absent either. (Asking for the
+ * impossible band on the SUB-VERB is a different thing entirely — a typed
+ * contradiction, and a usage error.)
+ */
+const outOfBandRow = (target: AnyTarget, band: ScopeBand): PlanRow => ({
+  target: target.id,
+  band,
+  action: "skip",
+  detail: "not in this band",
+  reason:
+    band === "project"
+      ? "user-level only — it has no project band"
+      : "project-level only — it has no global band",
+  selected: false,
+});
+
+/**
+ * The row a target gets when its own detection threw. It is a `skip` in the
+ * PLAN — nothing can be composed from a detection that does not exist — but it
+ * is not a quiet one: the reason is the cause, and the apply phase turns it
+ * into a `failed` outcome, so the run exits non-zero naming this target rather
+ * than reporting a clean sweep over the targets that did settle.
+ */
+const failedDetectionRow = (
+  target: AnyTarget,
+  band: ScopeBand,
+  failure: string,
+): PlanRow => ({
+  target: target.id,
+  band,
+  action: "skip",
+  detail: "detection did not complete",
+  reason: failure,
+  selected: false,
+});
+
+/**
+ * The draft a detected row produces — the forward plan, or the removal plan.
+ * Re-derivable from the detection at any time, which is why the plan row itself
+ * stores no remedy: a remedy belongs to an OUTCOME, and the apply phase reads it
+ * back from here when it fills one in.
+ *
+ * @param hit - The detected row.
+ * @param roots - The two named roots.
+ * @param removal - Whether this invocation removes rather than installs.
+ * @returns The target's draft.
+ */
+export function draftFor(
+  hit: DetectedRow,
+  roots: SetupPlan["roots"],
+  removal: boolean,
+): TargetDraft {
+  return removal
+    ? hit.target.removalPlan(hit.detection, hit.band, roots)
+    : hit.target.plan(hit.detection, hit.band, roots);
+}
+
+/**
+ * Project detections into plan rows.
+ *
+ * @param scope - The resolved band selection (named in the header).
+ * @param roots - The two named roots every path renders relative to.
+ * @param detected - The detections, in table order per band.
+ * @param ids - The targets that were REQUESTED, so an out-of-band one still
+ *   gets a visible row.
+ * @param removal - Build the removal plan (`--undo`) instead of the forward one.
+ * @returns The plan.
+ */
+export function buildPlan(
+  scope: ScopeSelection,
+  roots: SetupPlan["roots"],
+  detected: readonly DetectedRow[],
+  ids: readonly TargetId[],
+  removal = false,
+): SetupPlan {
+  const rows: PlanRow[] = [];
+  for (const band of bandsForScope(scope)) {
+    for (const target of TARGETS) {
+      if (!ids.includes(target.id)) continue;
+      const hit = detected.find(
+        (d) => d.target.id === target.id && d.band === band,
+      );
+      if (hit === undefined) {
+        // Only worth a line when the target has no row in ANY selected band —
+        // under `--scope both` a global-only target already appears above.
+        const elsewhere = detected.some((d) => d.target.id === target.id);
+        if (!elsewhere) rows.push(outOfBandRow(target, band));
+        continue;
+      }
+      const failure = detectionFailure(hit);
+      if (failure !== undefined) {
+        rows.push(failedDetectionRow(target, band, failure));
+        continue;
+      }
+      const draft = draftFor(hit, roots, removal);
+      rows.push({
+        target: target.id,
+        band,
+        action: draft.action,
+        detail: draft.detail,
+        ...(draft.reason === undefined ? {} : { reason: draft.reason }),
+        ...(draft.children === undefined ? {} : { children: draft.children }),
+        selected: defaultSelected(draft.action),
+      });
+    }
+  }
+  return { scope, roots, rows };
+}

package/src/capabilities/setup/index.ts

@@ -2,11 +2,11 @@
  * The `setup` capability barrel.
  */
 
-export { setupModule } from "./setup.verb.js";
 export type {
-  ConfiguredTarget,
-  ScopeSelection,
-  SetupResult,
-  SetupSkillsResult,
-  SymlinkAction,
-} from "./types.js";
+  PlanChildRow,
+  PlanRow,
+  SetupPlan,
+  TargetId,
+} from "./plan.js";
+export { setupModule } from "./setup.verb.js";
+export type { ScopeBand, ScopeSelection } from "./types.js";

package/src/capabilities/setup/mode.ts

@@ -0,0 +1,74 @@
+/**
+ * Setup's interaction decision — the SAME `decideInteraction` `create`'s mount
+ * calls, against the same TTY gate, with two declared adaptations.
+ *
+ * (a) `explicitComplete` is constantly `false`. Setup's prompts are
+ * PLAN-SHAPING (which rows, which files), not data-bearing; none has or should
+ * grow a flag form, so no invocation can be "explicitly complete" in `create`'s
+ * sense. Feeding the prompts honestly would be worse than the constant:
+ * `explicitAnswersComplete([], {})` is vacuously true, so the promptless
+ * sub-verbs would silently MUTATE on a bare piped invocation — which is the
+ * exact trap this design closes. The constant degenerates the table to
+ * `dry-run > undo > yes > wizard > preview`.
+ *
+ * (b) The `refuse` mode renders the preview. `create` refuses because
+ * scaffolding from defaults without complete input is dangerous AND it can name
+ * the missing flags. Setup has no missing flags to name — the refusal body would
+ * be empty advice — and the genuinely useful artifact is the plan itself. So
+ * setup's refusal IS the dry-run plan plus one hint line, at exit 0: the
+ * invocation completed a meaningful read-only unit of work, and a script author
+ * who forgot `--yes` reads the hint on the very output they are capturing.
+ *
+ * An MCP tool call is programmatic consent: `transport === "mcp"` resolves as if
+ * `--yes` were passed. The band default applies there too — the tool writes the
+ * global band unless told otherwise.
+ */
+
+import type { InteractionMode } from "@canonical/summon-core/projection";
+import type { PragmaRuntime } from "../../kernel/runtime/index.js";
+
+/** The inputs the decision reads, lifted off the runtime. */
+export interface SetupModeInput {
+  readonly dryRun: boolean;
+  readonly undo: boolean;
+  readonly yes: boolean;
+  readonly isTTY: boolean;
+}
+
+/**
+ * Lift the decision inputs off a runtime. A tool call over MCP counts as `yes`.
+ *
+ * @param rt - The per-invocation runtime.
+ * @returns The four inputs.
+ */
+export function setupModeInput(rt: PragmaRuntime): SetupModeInput {
+  const interaction = rt.interaction;
+  return {
+    dryRun: rt.mutation?.preview === true,
+    undo: rt.mutation?.undo === true,
+    yes: interaction?.yes === true || interaction?.transport === "mcp",
+    isTTY: interaction?.isTTY === true,
+  };
+}
+
+/**
+ * Resolve the interaction mode, mirroring `create`'s `resolveCreateMode` so the
+ * cross-CLI test style can pin both against the one shared decision.
+ *
+ * @param input - The four inputs.
+ * @param decide - The shared decision, injected so this module needs no value
+ *   import of summon-core (it stays behind the verb's lazy import).
+ * @returns The resolved mode.
+ */
+export function resolveSetupMode(
+  input: SetupModeInput,
+  decide: (arg: {
+    dryRun: boolean;
+    undo: boolean;
+    yes: boolean;
+    isTTY: boolean;
+    explicitComplete: boolean;
+  }) => { mode: InteractionMode },
+): InteractionMode {
+  return decide({ ...input, explicitComplete: false }).mode;
+}

package/src/capabilities/setup/operations/index.ts

@@ -0,0 +1,74 @@
+/**
+ * The setup operations — one module per installable target, each answering the
+ * same three questions about it.
+ *
+ * `setup` and `doctor` are two projections of ONE target table, and this is
+ * where that table's cells live. Every target module exports the same trio: a
+ * `detect*` that reads the machine and returns that target's detection record,
+ * a `compose*` that turns a detection into the Task which installs it, and a
+ * `compose*Removal` that turns the same detection into the Task which undoes
+ * it. Nothing here decides WHICH targets run or in what order — `targets.ts`
+ * owns that — so a new target is a new module plus a row, and neither surface
+ * has to learn about it twice.
+ *
+ * The detection types are part of the surface, not an implementation leak: a
+ * detection is the value passed from the read half to the compose half and on
+ * to the plan rows, so `doctor`'s banded checks name the same records `setup`
+ * acts on. The presentation helpers travel with them for the same reason — a
+ * skip reason or an uninstall remedy is derived from one detection, and
+ * deriving it twice is how the two surfaces start disagreeing about the same
+ * machine.
+ *
+ * `buildSetupRun` sits apart: it is the run assembler that drives every
+ * selected target's detection and projects the result into a plan and a summon
+ * generator. It is reached through a DYNAMIC import from `setup.verb.ts` so
+ * the wizard's React/Ink dependency stays off the `--help`/`__complete` fast
+ * path — a consumer that routes it through this barrel statically would undo
+ * that, and the setup guard test would say so.
+ *
+ * Deliberately internal: the config seed literal, the per-target message
+ * builders, and the MCP entry writer. They are inputs to the composers above,
+ * not operations a caller performs.
+ */
+
+export type { CompletionsDetection } from "./setupCompletions.js";
+export {
+  composeCompletions,
+  composeCompletionsRemoval,
+  detectCompletions,
+} from "./setupCompletions.js";
+export type { ConfigDetection } from "./setupConfig.js";
+export {
+  composeConfigFile,
+  composeConfigRemoval,
+  detectConfigFile,
+} from "./setupConfig.js";
+export type { SetupRun } from "./setupGenerator.js";
+export { buildSetupRun } from "./setupGenerator.js";
+export type { LspDetection } from "./setupLsp.js";
+export {
+  composeLsp,
+  composeLspRemoval,
+  detectLsp,
+  LSP_SKIP_REMEDY,
+  lspEditorNames,
+  lspSkipReason,
+  lspUninstallRemedy,
+} from "./setupLsp.js";
+export type { McpDetection } from "./setupMcp.js";
+export {
+  composeMcp,
+  composeMcpRemoval,
+  detectMcp,
+  mcpGroupState,
+  ownedMcpGroups,
+  selectedGroups,
+} from "./setupMcp.js";
+export type { SkillsDetection, SymlinkAction } from "./setupSkills.js";
+export {
+  composeSkills,
+  composeSkillsRemoval,
+  detectSkills,
+  ownedSkillLinks,
+  skillsSkipReason,
+} from "./setupSkills.js";

package/src/capabilities/setup/operations/setupCompletions.ts

@@ -12,19 +12,19 @@
 
 import { existsSync, readFileSync } from "node:fs";
 import { dirname } from "node:path";
+import type { PlatformEnv } from "@canonical/harnesses";
 import {
   deleteFile,
-  info,
   mkdir,
   sequence_,
   type Task,
-  warn,
   writeFile,
 } from "@canonical/task";
+import { BIN_NAME } from "../../../constants.js";
 import {
-  activationHint,
   completionScriptPath,
   detectShell,
+  type ShellDetection,
   type ShellId,
 } from "../shell.js";
 import type { CompletionsState } from "../types.js";
@@ -41,6 +41,45 @@ export interface CompletionsDetection {
   readonly path: string | null;
   readonly script: string | null;
   readonly state: CompletionsState;
+  /** What detection concluded — `ambiguous` is reported, never resolved. */
+  readonly detection: ShellDetection;
+  /**
+   * Whether the binary the installed script SHELLS OUT TO resolves on PATH.
+   *
+   * Every emitted script delegates its name contexts to `<bin> __complete`. If
+   * the binary is not reachable from the shell, the script installs cleanly,
+   * doctor goes green, and TAB does nothing — the script is inert. Checked here
+   * so the plan row and the doctor row read the same one answer.
+   */
+  readonly binOnPath: boolean;
+}
+
+/**
+ * Whether the host would resolve a bare command name — the same probe the `mcp`
+ * row uses for its entry's command, asked here of the binary the installed
+ * completion script spawns.
+ *
+ * The candidate paths come from `@canonical/harnesses`' `executableCandidates`,
+ * which owns the PATH split and the win32 `PATHEXT` rules in one place. Joining
+ * the bare name onto each PATH directory found NOTHING on Windows, where npm
+ * installs this CLI as a `.cmd` shim: `setup completions` skipped with "not on
+ * PATH" on a machine where typing the command works.
+ *
+ * @param command - The bare binary name.
+ * @param platform - The captured host (injected by the tests).
+ * @returns Whether the host holds an executable under that name.
+ * @note Impure — tests each candidate path on the filesystem.
+ */
+async function binaryOnPath(
+  command: string,
+  platform?: PlatformEnv,
+): Promise<boolean> {
+  const { executableCandidates, readPlatformEnv } = await import(
+    "@canonical/harnesses"
+  );
+  return executableCandidates(command, platform ?? readPlatformEnv()).some(
+    (candidate) => existsSync(candidate),
+  );
 }
 
 /**
@@ -70,14 +109,29 @@ function classifyCompletions(path: string, script: string): CompletionsState {
  * path.
  *
  * @param cwd - Directory the `completion` config layers are resolved from.
+ * @param injected - A detection to use instead of probing (tests).
+ * @param platform - A captured host to use instead of reading this one (tests).
  * @returns The install target, or an all-`null` shape when `$SHELL` is unset.
  * @note Impure — reads `$SHELL`, the capability registry, and the config layers.
  */
 export async function detectCompletions(
   cwd: string,
+  injected?: ShellDetection,
+  platform?: PlatformEnv,
 ): Promise<CompletionsDetection> {
-  const shell = detectShell();
-  if (!shell) return { shell: null, path: null, script: null, state: "absent" };
+  const detection = injected ?? detectShell();
+  const binOnPath = await binaryOnPath(BIN_NAME, platform);
+  if (detection.kind !== "detected") {
+    return {
+      shell: null,
+      path: null,
+      script: null,
+      state: "absent",
+      detection,
+      binOnPath,
+    };
+  }
+  const shell = detection.shell;
 
   const [{ capabilities }, { emitScripts }, { readConfig }] = await Promise.all(
     [
@@ -102,7 +156,14 @@ export async function detectCompletions(
       ? { disabledFamilies }
       : {}),
   })[shell];
-  return { shell, path, script, state: classifyCompletions(path, script) };
+  return {
+    shell,
+    path,
+    script,
+    state: classifyCompletions(path, script),
+    detection,
+    binOnPath,
+  };
 }
 
 /**
@@ -112,30 +173,42 @@ export async function detectCompletions(
  * interprets a generator's task TWICE — once for the confirm-gate preview and
  * once to perform it — so the composed task must survive a second drive.
  *
- * The prior `state` drives the MESSAGE only ("already up to date" / "Updating" /
- * "Installing"), NOT whether the write happens: the (idempotent) write is always
- * composed so it carries its `undo` — `--undo` reverses the SAME task and must
- * find the reversible effect, and `execute` interprets the task twice. A
- * byte-identical rewrite in the `installed` case is harmless.
+ * An `installed` (byte-identical) script composes NOTHING. The write used to
+ * happen anyway so that `--undo` had a reversible effect to find; removal is
+ * now composed from detection instead ({@link composeCompletionsRemoval}), so
+ * the forward path is free to be quiet: a converged re-run leaves the file's
+ * mtime alone.
+ *
+ * The task carries no log effects. What a run says about this target is the
+ * plan row's business — one structure, rendered the same way in the preview,
+ * the progress line and the recap.
  *
  * @param d - The detection gathered up front.
- * @returns A Task that writes the script (with an undo), or warns if no shell.
+ * @returns A Task that installs the script, or an empty Task when it is current.
  */
 export function composeCompletions(d: CompletionsDetection): Task<void> {
   if (d.shell === null || d.path === null || d.script === null) {
-    return warn(
-      "Could not detect your shell — set $SHELL to zsh, bash, or fish.",
-    );
+    return sequence_([]);
   }
-  const { path, script, shell, state } = d;
-  const opening =
-    state === "installed"
-      ? `${shell} completions already up to date at ${path}.`
-      : `${state === "stale" ? "Updating" : "Installing"} ${shell} completions to ${path}...`;
+  if (d.state === "installed") return sequence_([]);
   return sequence_([
-    info(opening),
-    mkdir(dirname(path), true),
-    writeFile(path, script, { undo: deleteFile(path) }),
-    info(activationHint(shell)),
+    mkdir(dirname(d.path), true),
+    writeFile(d.path, d.script, { undo: deleteFile(d.path) }),
   ]);
 }
+
+/**
+ * Compose the removal of an installed script: the forward effect re-asserts the
+ * script (idempotent) and carries its deletion as `undo`, which is what the undo
+ * interpreter executes. An absent script composes nothing, so `--undo` on a
+ * machine that never installed one reverses zero steps and says so.
+ *
+ * @param d - The detection gathered up front.
+ * @returns A Task whose undo deletes the installed script.
+ */
+export function composeCompletionsRemoval(d: CompletionsDetection): Task<void> {
+  if (d.path === null || d.script === null || d.state === "absent") {
+    return sequence_([]);
+  }
+  return sequence_([writeFile(d.path, d.script, { undo: deleteFile(d.path) })]);
+}