@canonical/pragma-cli 0.34.0 → 0.36.0

package/src/capabilities/setup/types.ts

@@ -2,50 +2,36 @@
  * 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";
+export type SetupMode =
+  | "all"
+  | "config"
+  | "completions"
+  | "lsp"
+  | "mcp"
+  | "skills";
 
-/**
- * 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 scope types are part of the rendering vocabulary — the one module that
+// owns both the states and the words for them. Re-exported here so setup's
+// type surface stays complete; the definitions (and the structural pin against
+// `@canonical/harnesses`) live with the vocabulary.
+export type {
+  Scope,
+  ScopeSelection,
+} from "../../kernel/render/vocabulary.js";
 
 /**
  * The prior state of an MCP target file, read up front by `detectMcp`:
- * `absent` (no pragma entry yet), `configured` (a matching pragma entry already
+ * `absent` (no pragma entry yet), `registered` (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;
-}
+export type McpTargetState = "absent" | "registered" | "drifted";
 
 /**
  * The prior on-disk state of the shell-completion script, read up front by
@@ -56,44 +42,11 @@ export interface ConfiguredTarget {
 export type CompletionsState = "absent" | "installed" | "stale";
 
 /**
- * The detected state of the Terrazzo LSP VS Code extension, probed up front by
- * `detectLsp`: `installed` (already present — a re-run skips it), `absent` (not
- * present, so the installer runs), or `unknown` (the `code` CLI is not on PATH,
- * so we cannot enumerate and the installer runs regardless).
+ * The detected state of the Terrazzo LSP extension across the VS Code-family
+ * editors on this machine, probed up front by `detectLsp`: `installed` (every
+ * editor whose CLI is on PATH already has it — a re-run skips), `absent` (at
+ * least one detected editor is missing it, so the sideload runs for those), or
+ * `unknown` (NO editor CLI was found on PATH — the step is a named skip, since
+ * there is nothing to install into).
  */
 export type LspState = "installed" | "absent" | "unknown";
-
-/** One symlink create/skip/replace action performed during skill setup. */
-export interface SymlinkAction {
-  readonly skillName: string;
-  readonly target: string;
-  readonly linkPath: string;
-  readonly action: "created" | "skipped" | "replaced";
-  readonly harnessName: string;
-}
-
-/** Aggregate result of `pragma setup skills`. */
-export interface SetupSkillsResult {
-  readonly actions: readonly SymlinkAction[];
-  readonly harnessCount: number;
-  readonly skillCount: number;
-  readonly warnings: readonly string[];
-}
-
-/** The result of one setup verb, tagged by which verb produced it. */
-export type SetupResult =
-  | {
-      readonly kind: "completions";
-      readonly shell: ShellId | null;
-      readonly path: string | null;
-      readonly installed: boolean;
-      readonly state: CompletionsState;
-    }
-  | { readonly kind: "lsp"; readonly state: LspState }
-  | {
-      readonly kind: "mcp";
-      readonly configured: readonly string[];
-      readonly targets: readonly ConfiguredTarget[];
-    }
-  | { readonly kind: "skills"; readonly result: SetupSkillsResult }
-  | { readonly kind: "all"; readonly steps: readonly string[] };

package/src/capabilities/shared/assertExecOk.ts

@@ -13,13 +13,66 @@
  * 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
+ * "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";
+import {
+  type ExecResult,
+  fail,
+  pure,
+  recover,
+  type Task,
+} from "@canonical/task";
+import type { Recovery } from "../../kernel/error/index.js";
+import { PragmaError } from "../../kernel/error/index.js";
+
+/**
+ * Route a {@link PragmaError} through the Task FAILURE CHANNEL (a `Fail` node
+ * carrying the error as `cause`) instead of a synchronous throw.
+ *
+ * The distinction is load-bearing: a synchronous throw from a bind/recover
+ * continuation ESCAPES the interpreter's trampoline entirely — no enclosing
+ * `recover` can see it — whereas a `Fail` node unwinds to the nearest recovery
+ * frame. Setup's run-all isolates each step with `recover` so one failed step
+ * cannot abort the rest (S1-1); that only works if step failures travel the
+ * failure channel. The boundary (`asPragmaError`) unwraps the carried cause,
+ * so a failure that escapes un-recovered still renders with its own code,
+ * message, and recovery — never the INTERNAL_ERROR catch-all.
+ */
+export function failPragma(error: PragmaError): Task<never> {
+  return fail({ code: error.code, message: error.message, cause: error });
+}
+
+/**
+ * The failure-channel sibling of {@link assertExecOk}: yield `pure(undefined)`
+ * on exit 0, otherwise fail with an UNSUPPORTED {@link PragmaError} carrying
+ * the command, exit code, trimmed stderr, and the CALLER'S recovery — the
+ * recovery must name an action that works on this machine now, not the generic
+ * "permissions or network" guess.
+ *
+ * @param command - Human-readable command, surfaced in the error message.
+ * @param result - The {@link ExecResult} the `exec` effect yielded.
+ * @param recovery - The actionable, site-specific recovery.
+ * @returns A Task that succeeds on exit 0 and fails (recoverably) otherwise.
+ */
+export function checkExecOk(
+  command: string,
+  result: ExecResult,
+  recovery: Recovery,
+): Task<void> {
+  if (result.exitCode === 0) return pure(undefined);
+  const stderr = result.stderr.trim();
+  return failPragma(
+    new PragmaError({
+      code: "UNSUPPORTED",
+      message: `\`${command}\` exited with code ${result.exitCode}.${
+        stderr ? `\n${stderr}` : ""
+      }`,
+      recovery,
+    }),
+  );
+}
 
 /**
  * Raise UNSUPPORTED when an `exec` result carries a nonzero exit code.
@@ -40,7 +93,7 @@ export function assertExecOk(command: string, result: ExecResult): void {
     }`,
     recovery: {
       message:
-        "The command failed — often a permissions or network issue. Check the output above and retry (for a global install, try elevated privileges).",
+        "Check the command's output above; a global install may need elevated privileges.",
     },
   });
 }
@@ -93,11 +146,16 @@ export function guardMissingBinary<A>(
 ): Task<A> {
   return recover(task, (error) => {
     if (isMissingBinaryError(error)) {
-      throw new PragmaError({
-        code: "UNSUPPORTED",
-        message: `\`${bin}\` was not found on your PATH.`,
-        recovery,
-      });
+      // Failure CHANNEL, not a synchronous throw: an enclosing recover (the
+      // run-all's per-step isolation, S1-1) must be able to catch this, and
+      // the boundary unwraps the carried PragmaError when nothing does.
+      return failPragma(
+        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).

package/src/capabilities/shared/index.ts

@@ -0,0 +1,43 @@
+/**
+ * The cross-capability shared surface — the few facts more than one capability
+ * needs and none of them owns.
+ *
+ * Everything here earned its place by being needed in two capabilities at
+ * once, and the cohesion principle is that shortness of the list. `shared/` is
+ * not a utility drawer: a helper used by exactly one capability belongs in
+ * that capability, and the moment something here has a single consumer again
+ * it should move back. What survives is the environment the CLI reports on but
+ * does not own — how it was installed, what the registry says about it,
+ * whether a subprocess it ran actually succeeded. (The scope labels that keep
+ * `setup` and `doctor` calling the two config scopes by the same names used
+ * to live here too; they are part of the rendering vocabulary now —
+ * `kernel/render/vocabulary.ts` — beside the statuses and glyphs they are
+ * printed with.)
+ *
+ * The exec guard is exported as the pair a caller needs together: `checkExecOk`
+ * to classify a result inside a Task and `assertExecOk` to throw on one
+ * outside, with `guardMissingBinary` wrapping the absent-binary case that
+ * neither should report as a pragma bug. The predicates they are built from
+ * stay internal — a caller reaching for the predicate instead of the guard is
+ * a caller about to reimplement the classification.
+ */
+
+export {
+  assertExecOk,
+  checkExecOk,
+  guardMissingBinary,
+} from "./assertExecOk.js";
+export type {
+  EphemeralRunner,
+  GlobalInstall,
+  InstallProbe,
+  InstallSource,
+  PackageManager,
+} from "./packageManager.js";
+export {
+  detectInstallSource,
+  pmUpdateCommand,
+  updateGuidance,
+} from "./packageManager.js";
+export type { RegistryCheckResult } from "./registry.js";
+export { checkRegistryVersion, PRAGMA_PACKAGE } from "./registry.js";