@canonical/pragma-cli 0.31.0 → 0.33.0

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

@@ -0,0 +1,261 @@
+/**
+ * The `setup` verbs — the run-all self-verb plus the four CLI-only sub-verbs
+ * (`mcp`/`completions`/`skills`/`lsp`).
+ *
+ * `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.
+ *
+ * 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.
+ */
+
+import type { GeneratorResult } from "@canonical/summon-core";
+import { $, gen, type Task } from "@canonical/task";
+import type { PragmaRuntime } from "../../kernel/runtime/types.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";
+
+/**
+ * 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.
+ */
+const SCOPE_PARAMS: readonly ParamSpec[] = [
+  {
+    kind: "enum",
+    name: "scope",
+    doc: "Which config band(s) to configure: project, global, or both.",
+    values: ["project", "global", "both"],
+    default: "both",
+  },
+  {
+    kind: "boolean",
+    name: "global",
+    doc: "Shorthand for --scope global (configure the user/home band).",
+  },
+  {
+    kind: "boolean",
+    name: "local",
+    doc: "Shorthand for --scope project (configure the per-project band).",
+  },
+];
+
+/**
+ * Resolve the `--scope`/`--global`/`--local` params into a single selection.
+ * The boolean sugars win over `--scope`; `--global` wins over `--local`.
+ *
+ * @param params - The coerced param bag.
+ * @returns The resolved scope selection (defaults to `both`).
+ */
+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";
+}
+
+/** The exposed-to-MCP capability the run-all self-verb declares. */
+const SELF_CAPABILITY = {
+  needsStore: false,
+  mutates: true,
+  interactive: true,
+  destructive: false,
+  mcp: {
+    expose: true as const,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      openWorldHint: false,
+    },
+  },
+};
+
+/** The CLI-only capability every sub-verb declares (not an MCP tool). */
+const SUB_CAPABILITY = {
+  needsStore: false,
+  mutates: true,
+  interactive: true,
+  destructive: false,
+  mcp: {
+    expose: false as const,
+    reason: "CLI-only environment installer",
+  },
+};
+
+/**
+ * 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}.
+ *
+ * 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.
+ *
+ * @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.
+ */
+async function runSetup(
+  mode: SetupMode,
+  rt: PragmaRuntime,
+  scope: ScopeSelection,
+): Promise<Task<SetupResult>> {
+  // Lazy dynamic imports (R1 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([
+    import("@canonical/summon-core"),
+    import("./operations/setupGenerator.js"),
+  ]);
+
+  const { generator, toResult } = await ops.buildSetupPlan(rt, mode, scope);
+
+  const { isTTY, transport, yes, signal, abort } = rt.interaction ?? {
+    isTTY: false,
+    transport: "cli" as const,
+    yes: true,
+  };
+
+  // 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).
+  let task: Task<GeneratorResult>;
+  if (isTTY && !yes) {
+    const session = summon.inkPrompt(generator, { signal, onCancel: abort });
+    rt.exec = {
+      promptHandler: session.promptHandler,
+      onEffectStart: session.onEffectStart,
+      onEffectComplete: session.onEffectComplete,
+      onLog: session.onLog,
+      dispose: session.dispose,
+      signal,
+    };
+    task = summon.execute(generator, {
+      prompt: session.promptHandler,
+      params: {},
+      signal,
+    });
+  } else {
+    // Non-interactive: MCP → params-or-error; CLI/--yes/CI → defaults.
+    const prompt =
+      transport === "mcp" ? summon.mcpPrompt({}) : summon.autoPrompt({});
+    rt.exec = {
+      promptHandler: prompt,
+      onLog: (_level, message) => process.stderr.write(`${message}\n`),
+      signal,
+    };
+    task = summon.execute(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);
+  });
+}
+
+/** Build a setup verb bound to its {@link SetupMode}. */
+function setupVerb(
+  path: VerbSpec<Record<string, unknown>, SetupResult>["path"],
+  summary: string,
+  mode: SetupMode,
+  capability: typeof SELF_CAPABILITY | typeof SUB_CAPABILITY,
+  extras: Partial<VerbSpec<Record<string, unknown>, SetupResult>> = {},
+): VerbSpec<Record<string, unknown>, SetupResult> {
+  return {
+    path,
+    summary,
+    params: [],
+    output: { formatters: setupFormatters },
+    capability,
+    ...extras,
+    run: (params, rt) =>
+      runSetup(mode, rt, resolveScope(params)) as unknown as Task<SetupResult>,
+  };
+}
+
+const setupAllVerb = setupVerb(
+  ["setup"],
+  "Configure MCP, completions, skills, and the LSP for this project.",
+  "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.",
+    examples: [
+      { cmd: "pragma setup" },
+      { cmd: "pragma setup --dry-run", note: "preview every step's effects" },
+      {
+        cmd: "pragma setup --global",
+        note: "configure only the user/home band",
+      },
+      { cmd: "pragma setup mcp", note: "just the MCP server registration" },
+    ],
+  },
+);
+
+const mcpVerb = setupVerb(
+  ["setup", "mcp"],
+  "Register the pragma MCP server in detected AI harnesses.",
+  "mcp",
+  SUB_CAPABILITY,
+  { params: SCOPE_PARAMS },
+);
+
+const completionsVerb = setupVerb(
+  ["setup", "completions"],
+  "Install the shell-completion script for your shell.",
+  "completions",
+  SUB_CAPABILITY,
+);
+
+const skillsVerb = setupVerb(
+  ["setup", "skills"],
+  "Symlink discovered skills into each AI harness.",
+  "skills",
+  SUB_CAPABILITY,
+  { params: SCOPE_PARAMS },
+);
+
+const lspVerb = setupVerb(
+  ["setup", "lsp"],
+  "Ensure the Terrazzo LSP VS Code extension is installed.",
+  "lsp",
+  SUB_CAPABILITY,
+);
+
+/** The `setup` capability module (run-all self-verb + four CLI-only sub-verbs). */
+export const setupModule: CapabilityModule = {
+  name: "setup",
+  verbs: [
+    asVerb(setupAllVerb),
+    asVerb(mcpVerb),
+    asVerb(completionsVerb),
+    asVerb(skillsVerb),
+    asVerb(lspVerb),
+  ],
+};

package/src/capabilities/setup/shell.ts

@@ -0,0 +1,85 @@
+/**
+ * Shell detection + completion-script install paths (ported from the old
+ * shell's `setup/helpers/detectShell` + `completionScripts` path helpers).
+ *
+ * The covenant `setup completions` sub-verb carries NO flags, so shell selection
+ * is detection-only (the old `--zsh`/`--bash`/`--fish` force-flags are dropped).
+ * `$HOME` is read at call time so tests can isolate it.
+ */
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** The shells `setup completions` can install for. */
+export type ShellId = "zsh" | "bash" | "fish";
+
+const SHELL_MAP: Record<string, ShellId> = {
+  zsh: "zsh",
+  bash: "bash",
+  fish: "fish",
+};
+
+/**
+ * Detect the user's shell from `$SHELL`.
+ *
+ * @returns The detected shell, or `null` when `$SHELL` is unset/unrecognized.
+ * @note Impure — reads `process.env.SHELL`.
+ */
+export function detectShell(): ShellId | null {
+  const shell = process.env.SHELL ?? "";
+  const basename = shell.split("/").pop() ?? "";
+  return SHELL_MAP[basename] ?? null;
+}
+
+/**
+ * The standard install path for a shell's completion script.
+ *
+ * @param shell - The target shell.
+ * @returns The absolute path the completion script is written to.
+ * @note Impure — reads the home directory.
+ */
+export function completionScriptPath(shell: ShellId): string {
+  const home = homedir();
+  switch (shell) {
+    case "zsh":
+      return join(home, ".zfunc", "_pragma");
+    case "bash":
+      return join(
+        home,
+        ".local",
+        "share",
+        "bash-completion",
+        "completions",
+        "pragma",
+      );
+    case "fish":
+      return join(home, ".config", "fish", "completions", "pragma.fish");
+  }
+}
+
+/**
+ * The post-install activation hint for a shell.
+ *
+ * bash and fish install into directories their completion systems auto-load, so
+ * the only step left is a fresh shell. zsh's `~/.zfunc` is NOT auto-loaded: the
+ * script never loads unless `~/.zfunc` is on `$fpath` BEFORE `compinit` runs —
+ * the single trap every zsh user hits, so we spell out the exact `.zshrc` lines.
+ *
+ * @param shell - The shell the script was installed for.
+ * @returns A one-or-more-line activation instruction.
+ */
+export function activationHint(shell: ShellId): string {
+  switch (shell) {
+    case "zsh":
+      return (
+        "To activate, ensure ~/.zfunc is on your fpath BEFORE compinit. Add to ~/.zshrc:\n" +
+        "    fpath=(~/.zfunc $fpath)\n" +
+        "    autoload -Uz compinit && compinit\n" +
+        "Then restart your shell (or run `exec zsh`)."
+      );
+    case "bash":
+      return "To activate, restart your shell (bash-completion auto-loads the script).";
+    case "fish":
+      return "To activate, restart your shell (fish auto-loads the script).";
+  }
+}

package/src/capabilities/setup/types.ts

@@ -0,0 +1,99 @@
+/**
+ * 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";
+
+/**
+ * One of the two config bands: the per-user/home `global` band or the per-repo
+ * `project` band. Mirrors `@canonical/harnesses`' `ScopeBand` structurally, but
+ * is redeclared here so this statically-reachable type module never pulls the
+ * harnesses runtime into the fast-path module graph (the lazy-dispatch invariant).
+ */
+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`.
+ */
+export type ScopeSelection = "project" | "global" | "both";
+
+/**
+ * The prior state of an MCP target file, read up front by `detectMcp`:
+ * `absent` (no pragma entry yet), `configured` (a matching pragma entry already
+ * present in every write — a re-run skips it), or `drifted` (a pragma entry
+ * exists but differs, so a write updates it). Mirrors the skills step's
+ * created/skipped/replaced idempotency at the file grain.
+ */
+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
+ * script is already present — a re-run skips it), or `stale` (a different
+ * script is present, so a write updates it).
+ */
+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).
+ */
+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[] };

package/src/capabilities/shared/assertExecOk.ts

@@ -0,0 +1,106 @@
+/**
+ * Guard an `exec`-composing Task against a silently-swallowed nonzero exit.
+ *
+ * The `@canonical/task` interpreter RESOLVES the `exec` effect on a nonzero exit
+ * code — it only REJECTS on a spawn error (e.g. ENOENT). A consumer that yields
+ * `exec` and ignores `ExecResult.exitCode` therefore reports a failed command
+ * (the common case being an EACCES-denied global `npm i -g`) as a silent
+ * success, discarding the subprocess's own stderr. Every `exec` consumer in
+ * `next/src` (`upgrade`, `setup lsp`) calls this immediately after its `exec`
+ * yield, so a failed subprocess surfaces as UNSUPPORTED (exit 1) carrying the
+ * command and the captured stderr instead of being reported as done.
+ *
+ * A denied `npm i -g` (EACCES), a registry/network failure, or any other
+ * nonzero exit is a fixable ENVIRONMENT condition — NOT a pragma bug — so it is
+ * classified UNSUPPORTED with an actionable recovery, never INTERNAL_ERROR's
+ * "please report this issue". (A spawn error like ENOENT REJECTS the effect
+ * instead of resolving, so it never reaches here.)
+ */
+
+import { type ExecResult, fail, recover, type Task } from "@canonical/task";
+import { PragmaError } from "../../kernel/error/PragmaError.js";
+import type { Recovery } from "../../kernel/error/types.js";
+
+/**
+ * Raise UNSUPPORTED when an `exec` result carries a nonzero exit code.
+ *
+ * @param command - Human-readable command, surfaced in the error message.
+ * @param result - The {@link ExecResult} the `exec` effect yielded.
+ * @throws PragmaError UNSUPPORTED (exit 1) when `result.exitCode !== 0`,
+ *   including the trimmed stderr when the subprocess emitted any, plus an
+ *   actionable recovery (a permissions/network failure the user can retry).
+ */
+export function assertExecOk(command: string, result: ExecResult): void {
+  if (result.exitCode === 0) return;
+  const stderr = result.stderr.trim();
+  throw new PragmaError({
+    code: "UNSUPPORTED",
+    message: `\`${command}\` exited with code ${result.exitCode}.${
+      stderr ? `\n${stderr}` : ""
+    }`,
+    recovery: {
+      message:
+        "The command failed — often a permissions or network issue. Check the output above and retry (for a global install, try elevated privileges).",
+    },
+  });
+}
+
+/**
+ * True when a rejected/normalised `exec` error is a missing-binary spawn failure.
+ *
+ * A spawn `ENOENT` (the command is absent from PATH) REJECTS the `exec` effect —
+ * unlike a nonzero exit, which RESOLVES it (see {@link assertExecOk}). The task
+ * interpreter normalises that reject into a `FILE_NOT_FOUND` TaskError carrying
+ * the raw spawn error as `.cause`, so this unwraps one level to recognise both
+ * the raw and normalised shapes.
+ *
+ * @param error - The thrown/rejected value (raw spawn error or its TaskError).
+ * @returns Whether it denotes a binary missing from PATH.
+ */
+export function isMissingBinaryError(error: unknown): boolean {
+  const codeOf = (value: unknown): unknown =>
+    value && typeof value === "object" && "code" in value
+      ? (value as { code: unknown }).code
+      : undefined;
+  if (codeOf(error) === "ENOENT") return true;
+  const cause = (error as { cause?: unknown } | null | undefined)?.cause;
+  return codeOf(cause) === "ENOENT";
+}
+
+/**
+ * Wrap an `exec`-composing Task so a missing-binary spawn (ENOENT) surfaces as a
+ * named UNSUPPORTED "`<bin>` not found on PATH" error with actionable recovery,
+ * rather than the interpreter's raw reject collapsing to INTERNAL_ERROR ("please
+ * report this issue") at the CLI/MCP boundary. Every spawn site that may hit an
+ * absent binary (`upgrade`'s package manager, `setup lsp`'s `bunx`) wraps its
+ * Task with this so they never reach the catch-all.
+ *
+ * Only real execution can trip it: a dry-run/plan mocks `exec` (exit 0, no
+ * spawn), so the guard is transparent to the preview. A nonzero exit RESOLVES
+ * the effect and is still {@link assertExecOk}'s job (its throw is a synchronous
+ * generator-body throw, not an effect failure, so it bypasses this handler); any
+ * other effect failure re-raises unchanged.
+ *
+ * @param bin - The binary name surfaced in the error message.
+ * @param recovery - The install/PATH recovery hint.
+ * @param task - The Task whose `exec` effect may reject with ENOENT.
+ * @returns The Task, guarded against a missing-binary spawn.
+ */
+export function guardMissingBinary<A>(
+  bin: string,
+  recovery: Recovery,
+  task: Task<A>,
+): Task<A> {
+  return recover(task, (error) => {
+    if (isMissingBinaryError(error)) {
+      throw new PragmaError({
+        code: "UNSUPPORTED",
+        message: `\`${bin}\` was not found on your PATH.`,
+        recovery,
+      });
+    }
+    // Not a missing binary — re-raise unchanged (the interpreter rethrows it as
+    // a TaskExecutionError, exactly as it would with no guard installed).
+    return fail(error);
+  });
+}

package/src/capabilities/shared/bands.ts

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

package/src/capabilities/shared/packageManager.ts

@@ -0,0 +1,62 @@
+/**
+ * Storeless install-source heuristic, shared by `info`, `upgrade`, and
+ * `doctor`'s `pragma version` check.
+ *
+ * Promotes the detector that lived inline in `info/collectInfo.ts`: the package
+ * manager comes from npm's `npm_config_user_agent` (set by npm/pnpm/yarn/bun
+ * when they run a script), the scope from whether the binary sits under
+ * `node_modules`. With no agent we report the honest runtime rather than
+ * guessing. The old shell's full package.json walk (`#package-manager`) is
+ * dropped — only this heuristic and the update-command map survive.
+ */
+
+/** The install source: package manager and a display label. */
+export interface InstallSource {
+  /** Package-manager name (`bun`/`npm`/`pnpm`/`yarn`), else the honest runtime. */
+  readonly pm: string;
+  /** `${pm} (${scope})` — the string `info`/`doctor` display. */
+  readonly label: string;
+}
+
+/** The package manager from npm's user-agent, else the honest runtime. */
+function packageManager(): string {
+  const agent = process.env.npm_config_user_agent;
+  const name = agent?.split("/")[0];
+  if (name) return name;
+  return process.versions.bun ? "bun" : "node";
+}
+
+/**
+ * Detect how the binary was installed — package manager and scope.
+ *
+ * @returns The install source (pm, label).
+ * @note Impure — reads `process.argv`/`process.env`.
+ */
+export function detectInstallSource(): InstallSource {
+  const bin = process.argv[1] ?? "";
+  const scope = bin.includes("node_modules") ? "local" : "global";
+  const pm = packageManager();
+  return { pm, label: `${pm} (${scope})` };
+}
+
+/** The npm global-update command — also the fallback for an unknown manager. */
+const npmUpdateCommand = (pkg: string): string => `npm i -g ${pkg}`;
+
+/** The global-update command per package manager (install-style). */
+const PM_UPDATE_COMMAND: Record<string, (pkg: string) => string> = {
+  bun: (pkg) => `bun add -g ${pkg}`,
+  npm: npmUpdateCommand,
+  pnpm: (pkg) => `pnpm add -g ${pkg}`,
+  yarn: (pkg) => `yarn global add ${pkg}`,
+};
+
+/**
+ * The command that updates `pkg` globally for a package manager.
+ *
+ * @param pm - The package-manager name (`bun`/`npm`/`pnpm`/`yarn`).
+ * @param pkg - The package to update.
+ * @returns The shell command; falls back to npm for an unknown manager.
+ */
+export function pmUpdateCommand(pm: string, pkg: string): string {
+  return (PM_UPDATE_COMMAND[pm] ?? npmUpdateCommand)(pkg);
+}