superpowers-manager 0.2.0 → 0.3.0

package/dist/commands/uninstall.js

@@ -0,0 +1,308 @@
+// Ports scripts/uninstall. The shell sourced common.sh, provenance.sh,
+// lifecycle.sh and adapter.sh; the predicates now live in src/lifecycle.ts
+// and the adapter arrives through ctx.adapter.
+import { tmpdir } from "node:os";
+import { oneLine } from "../cli-arguments.js";
+import { reportLegacyState, verifyUninstalledResources } from "../lifecycle.js";
+import { withWorkspace, workspaceRemovalFailure } from "../workspace.js";
+import { replayOutcome } from "./probe.js";
+function presenceFlag(result, key) {
+    const outcome = result.outcome;
+    if (result.status !== 0 || !outcome.ok) {
+        return { kind: "call-failed" };
+    }
+    const value = outcome.result;
+    // Mirrors src/lifecycle.ts's verifyUninstalledResources: a missing or
+    // non-object `resources` falls THROUGH to the Boolean check rather than
+    // getting its own message, for parity with
+    // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/adapter.sh:70::expected`'s
+    // single "expected Boolean..." text on {}.
+    const resources = typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value.resources
+        : undefined;
+    const bag = typeof resources === "object" &&
+        resources !== null &&
+        !Array.isArray(resources)
+        ? resources
+        : {};
+    const flag = bag[key];
+    if (typeof flag !== "boolean") {
+        return { kind: "malformed", key };
+    }
+    return { kind: "ok", value: flag };
+}
+async function invoke(ctx, env, argv, outcomes) {
+    let result;
+    try {
+        result = await ctx.adapter(argv, { root: ctx.root, env });
+    }
+    catch {
+        return {
+            ok: false,
+            message: `cannot invoke Codex adapter for ${argv.join(" ")}`,
+        };
+    }
+    // Clause 1: replay every outcome, on both the success and the failure
+    // path, before any decision -- collected here and replayed by the caller
+    // once gatherUninstall's try/catch has resolved, for the same EPIPE reason
+    // gatherProbe carries its outcomes out rather than writing in place
+    // (`src/commands/probe.ts:289::The outcomes are CARRIED OUT rather than replayed in place`).
+    outcomes.push(result.outcome);
+    const outcome = result.outcome;
+    if (result.status !== 0 || !outcome.ok) {
+        return {
+            ok: false,
+            message: outcome.ok
+                ? `adapter reported a failure status for ${argv.join(" ")}`
+                : null,
+        };
+    }
+    return { ok: true, result };
+}
+// withWorkspace throws for mkdtemp failure before the callback ever runs
+// ("cannot create workspace",
+// `src/workspace.ts:120::throw new SafetyError("workspace", "cannot create workspace"`).
+// A bare re-throw would silently drop every outcome collected before that
+// point -- a narrow
+// DIAG-ADAPTER-01 regression the shell never had, since it replayed each
+// adapter response as it went rather than batching replay to the end. This
+// carries the outcomes collected so far alongside the original cause, so
+// runUninstall's catch can still replay them before reporting the cause.
+//
+// The post-success cleanup failure no longer reaches here: onCleanupFailure
+// below suppresses withWorkspace's throw for that case and records the
+// warning as data, so the computed UninstallOutcome survives it. The
+// outcome-carrying is still load-bearing for mkdtemp, and the shape stays
+// identical to src/commands/install.ts's GatherFailure.
+class GatherFailure extends Error {
+    inner;
+    outcomes;
+    constructor(inner, outcomes) {
+        super("uninstall gather failed");
+        this.inner = inner;
+        this.outcomes = outcomes;
+    }
+}
+// Every step that can throw or fail closed, returning the outcome as data and
+// performing NO writes. Same shape as gatherProbe
+// (`src/commands/probe.ts:280-281::readonly status: 0;`) and for the same
+// reason: a write inside this try could raise EPIPE, be caught here, and be
+// relabelled as a domain failure.
+async function gatherUninstall(ctx) {
+    // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/uninstall:20-21::TMPDIR=` exported TMPDIR="$uninstall_workspace" so every
+    // child confined its temporary files to the tree the workspace trap
+    // removed. The AdapterContext passed to ctx.adapter below does the same.
+    const parent = ctx.env.TMPDIR ?? tmpdir();
+    // Declared OUTSIDE the withWorkspace callback (rather than inside, as an
+    // earlier draft had it) so the catch below -- which wraps the ENTIRE
+    // withWorkspace call, not just the callback -- can still see whatever was
+    // collected before a workspace throw. Both `mkdtemp` failure (nothing
+    // collected yet) and a post-success cleanup failure (everything the
+    // callback collected) reach this same array.
+    const outcomes = [];
+    let cleanupWarning = null;
+    try {
+        const outcome = await withWorkspace(parent, "superpowers-manager.uninstall.", async (workspace) => {
+            const env = { ...ctx.env, TMPDIR: workspace };
+            const failed = (message) => ({
+                status: 1,
+                outcomes,
+                message,
+            });
+            // Stage 1: inspect ownership, before removal.
+            const first = await invoke(ctx, env, ["inspect", "--view", "ownership"], outcomes);
+            if (!first.ok)
+                return failed(first.message);
+            const pluginFlag = presenceFlag(first.result, "plugin");
+            if (pluginFlag.kind === "malformed") {
+                return failed(`expected a Boolean adapter result at resources.${pluginFlag.key}`);
+            }
+            if (pluginFlag.kind === "call-failed") {
+                // Unreachable via this call path: `first.ok` above already proved
+                // status === 0 && outcome.ok, the only inputs presenceFlag reads
+                // to decide this arm. Handled anyway so presenceFlag stays total
+                // and this switch stays exhaustive rather than assuming its caller
+                // always gates first.
+                return failed(null);
+            }
+            const marketplaceFlag = presenceFlag(first.result, "marketplace");
+            if (marketplaceFlag.kind === "malformed") {
+                return failed(`expected a Boolean adapter result at resources.${marketplaceFlag.key}`);
+            }
+            if (marketplaceFlag.kind === "call-failed") {
+                return failed(null);
+            }
+            // Stage 2: uninstall, with the two presence Booleans read above.
+            const uninstallStage = await invoke(ctx, env, [
+                "uninstall",
+                "--plugin-present",
+                String(pluginFlag.value),
+                "--marketplace-present",
+                String(marketplaceFlag.value),
+            ], outcomes);
+            if (!uninstallStage.ok)
+                return failed(uninstallStage.message);
+            // Stage 3: inspect ownership AGAIN. This overwrites the first
+            // inspection (`git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/uninstall:29-30::spw_verify_uninstalled_resources`), so everything below reads the
+            // POST-uninstall state, not the pre-uninstall one read above.
+            const second = await invoke(ctx, env, ["inspect", "--view", "ownership"], outcomes);
+            if (!second.ok)
+                return failed(second.message);
+            const verify = verifyUninstalledResources(second.result);
+            if (!verify.ok)
+                return failed(verify.message);
+            // identity_state comes from this SAME second inspection, matching
+            // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/uninstall:31::spw_adapter_result_get`'s spw_adapter_result_get read of the
+            // overwritten inspect_result. `second.ok` already proved this call
+            // succeeded, so outcome.ok is true here; the explicit check below is
+            // for TypeScript's narrowing (a local variable, not a re-derivation
+            // of that fact) rather than a live branch.
+            const secondOutcome = second.result.outcome;
+            if (!secondOutcome.ok)
+                return failed(null);
+            // Mirrors the inspect null/non-string branches
+            // (`src/commands/probe.ts:256-263::if (value === null || value === undefined) {`)
+            // and the fingerprint read
+            // (`src/lifecycle.ts:181-194::const raw = inspected.value.fingerprint;`):
+            // a JSON null or a missing key defaults to "" (the Python reader's own
+            // convention for a JSON null, scripts/core/provenance.sh's
+            // spw_json_get), but a present, non-null, NON-STRING value is a
+            // distinct, fail-closed "malformed" case with its own text -- never
+            // silently stringified.
+            // (A previous draft of this comment claimed parity with the shell's
+            // stringify-and-compare behaviour at
+            // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/provenance.sh:62::print(value`;
+            // that was wrong on inspection, and it cited these same two call sites
+            // as support even though both of them fail closed on a non-string value
+            // rather than stringifying it. AGENTS.md's
+            // fail-closed rule wins over shell parity here.)
+            const parsed = secondOutcome.result;
+            const identityRaw = parsed?.identity_state;
+            let identityState;
+            if (identityRaw === null || identityRaw === undefined) {
+                identityState = "";
+            }
+            else if (typeof identityRaw === "string") {
+                identityState = identityRaw;
+            }
+            else {
+                return failed("adapter returned a non-string identity_state for inspect --view ownership");
+            }
+            const verdict = reportLegacyState(identityState);
+            if (verdict.kind === "unknown")
+                return failed(verdict.message);
+            const lines = [];
+            // verdict.kind is "ok" or "report" here (reportLegacyState never
+            // returns "blocked" -- that arm belongs to requireNoLegacyState --
+            // but LegacyVerdict is one shared union, so this narrows rather than
+            // assumes).
+            if (verdict.kind !== "ok") {
+                lines.push(...verdict.lines);
+            }
+            // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/uninstall:34-35::complete`. The first line ports verbatim; the second
+            // changes scripts/prepare to npx superpowers-manager prepare (spec
+            // §3.6) -- a deliberate, observable divergence, recorded as a
+            // port-only entry in tests/migration-inventory/uninstall-commands.md.
+            lines.push("uninstall complete");
+            lines.push("note: local generated artifacts under plugins/superpowers/ and " +
+                ".cache/upstream/ were left in place; remove them manually or " +
+                "regenerate with npx superpowers-manager prepare.");
+            return { status: 0, outcomes, lines };
+        }, {
+            // Suppresses withWorkspace's throw on a POST-SUCCESS cleanup failure,
+            // so the UninstallOutcome the callback already computed still comes
+            // back as `outcome` instead of being discarded. Runs synchronously,
+            // as the option requires (src/workspace.ts).
+            onCleanupFailure: (path) => {
+                cleanupWarning = workspaceRemovalFailure(path);
+            },
+        });
+        return { outcome, cleanupWarning };
+    }
+    catch (cause) {
+        // Reachable only for mkdtemp failure, with nothing collected yet: this
+        // callback never throws -- every ctx.adapter throw is already caught
+        // inside invoke(), and presenceFlag/verifyUninstalledResources/
+        // reportLegacyState are pure (src/lifecycle.ts's header comment) -- so a
+        // post-success cleanup failure is handled by onCleanupFailure above and
+        // cannot reach here. Wrapping with `outcomes` anyway keeps the class
+        // total over its declared contract rather than assuming the callback's
+        // purity at the throw site.
+        throw new GatherFailure(cause, outcomes);
+    }
+}
+export async function runUninstall(argv, ctx) {
+    // scripts/uninstall never reads "$@", so extra arguments are silently
+    // ignored -- the same asymmetry runPrepare documents at its own
+    // `void argv;`.
+    void argv;
+    let run;
+    try {
+        run = await gatherUninstall(ctx);
+    }
+    catch (cause) {
+        // gatherUninstall throws exactly one shape: GatherFailure, wrapping
+        // withWorkspace's "cannot create workspace" SafetyError
+        // (`src/workspace.ts:120::throw new SafetyError("workspace", "cannot create workspace"`),
+        // alongside whatever outcomes were collected before that throw -- none,
+        // for that cause. Replaying first, before
+        // reporting the cause, keeps the arm honest for any outcome-bearing
+        // throw the class is declared to carry (DIAG-ADAPTER-01). The
+        // post-success cleanup failure no longer arrives here: gatherUninstall's
+        // onCleanupFailure records it as `cleanupWarning` and the computed
+        // outcome survives, which is what `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/uninstall:34-35::complete` did. The
+        // `instanceof` guard is defensive rather than load-bearing --
+        // gatherUninstall's own catch is the only thing that can throw here, and
+        // it always wraps -- but this catch does not assume that invariant
+        // blindly.
+        //
+        // A cause outside ctx.adapter's AdapterFailure guard
+        // (`src/adapter.ts:1001::if (cause instanceof AdapterFailure) {`) does NOT
+        // reach here: invoke() catches it inside gatherUninstall and converts it
+        // to a hand-written message carried as UninstallOutcome data, exactly as
+        // src/commands/probe.ts's inspect() does for the same cause.
+        //
+        // gatherUninstall performs no writes of its own, so this catch cannot
+        // also be reached by an EPIPE from uninstall's own output -- every write
+        // below runs only after this try/catch has resolved.
+        const outcomes = cause instanceof GatherFailure ? cause.outcomes : [];
+        for (const outcome of outcomes)
+            replayOutcome(outcome, ctx);
+        const inner = cause instanceof GatherFailure ? cause.inner : cause;
+        ctx.stderr.write(`error: ${oneLine(inner)}\n`);
+        return 1;
+    }
+    const { outcome, cleanupWarning } = run;
+    // Replay first, on both paths: the shell validator replayed every
+    // response's messages whether or not that response was a failure
+    // (`git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/validate-adapter-response.py:268::replay(messages)`).
+    for (const each of outcome.outcomes)
+        replayOutcome(each, ctx);
+    let status;
+    if (outcome.status === 1) {
+        // null means replayOutcome already emitted the adapter's own error:
+        // and hint: lines for the failing outcome.
+        if (outcome.message !== null) {
+            ctx.stderr.write(`error: ${outcome.message}\n`);
+        }
+        status = 1;
+    }
+    else {
+        for (const line of outcome.lines) {
+            ctx.stdout.write(`${line}\n`);
+        }
+        status = 0;
+    }
+    if (cleanupWarning !== null) {
+        // Mirrors src/commands/install.ts's closing arm. A leaked workspace is
+        // reported even when the domain outcome above was a success: the
+        // uninstall and its verification already completed against the adapter
+        // before cleanup ran, so it is not being reported as unverified -- but
+        // something did still go wrong, and AGENTS.md's fail-closed rule extends
+        // to it. The operator keeps "uninstall complete", which is the one line
+        // telling them whether the removal they asked for happened.
+        ctx.stderr.write(`error: ${cleanupWarning}\n`);
+        return 1;
+    }
+    return status;
+}

package/dist/commands/unpin.js

@@ -0,0 +1,95 @@
+import { lstat, unlink } from "node:fs/promises";
+import { oneLine } from "../cli-arguments.js";
+import { selectionStatePath } from "../effective-selection.js";
+import { selectionError } from "../selection.js";
+import { readConfigRef } from "../upstream.js";
+const NOT_REGULAR = "selection state path is not a regular file; remove it manually after inspecting";
+// Runs every step that can throw or fail closed, returning the outcome as
+// data instead of writing it — see UnpinOutcome above for why.
+async function attemptUnpin(ctx) {
+    const statePath = selectionStatePath(ctx.env);
+    // The packaged fallback ignores an active SUPERPOWERS_REF: `git show 349fe2ed405b371ec2de1347bb3fc50c6bc15dc4:scripts/unpin:12::spw_config_ref`
+    // cleared it deliberately so the reported value is the packaged one.
+    const fallback = await readConfigRef(ctx.root, {
+        ...ctx.env,
+        SUPERPOWERS_REF: "",
+    });
+    // Only a validated ENOENT means "absent". Treating every errno as absence
+    // turns EACCES or ENOTDIR into `no saved upstream selection` and exit 0 —
+    // reporting unverifiable state as success, which the fail-closed rule forbids.
+    // The shell could not draw this distinction ([ -e ] cannot), so this is a
+    // deliberate narrowing beyond parity, recorded as a port-only inventory entry.
+    const inspect = async (path) => {
+        try {
+            return await lstat(path);
+        }
+        catch (cause) {
+            if (cause.code === "ENOENT")
+                return null;
+            throw selectionError(`cannot inspect selection state: ${path}`);
+        }
+    };
+    let removed = false;
+    const info = await inspect(statePath);
+    if (info !== null) {
+        if (!info.isFile()) {
+            return { status: 1, message: `${NOT_REGULAR}: ${statePath}` };
+        }
+        try {
+            await unlink(statePath);
+        }
+        catch {
+            return {
+                status: 1,
+                message: `cannot remove selection state: ${statePath}`,
+            };
+        }
+        removed = true;
+    }
+    // Same classification on the verification read: an EACCES here must not be
+    // read as "successfully absent".
+    if ((await inspect(statePath)) !== null) {
+        return {
+            status: 1,
+            message: `selection state remains after removal attempt: ${statePath}`,
+        };
+    }
+    return { status: 0, removed, fallback };
+}
+export async function runUnpin(argv, ctx) {
+    if (argv.length !== 0) {
+        ctx.stderr.write("error: usage: superpowers-manager unpin\n");
+        return 2;
+    }
+    let outcome;
+    try {
+        outcome = await attemptUnpin(ctx);
+    }
+    catch (cause) {
+        // Every throw reachable here is a hand-written SafetyError from
+        // selectionStatePath, readConfigRef, or inspect() inside attemptUnpin —
+        // re-emitting a subordinate module's own diagnostic is the sanctioned
+        // form of interpolation (see AGENTS.md's diagnostics convention).
+        // attemptUnpin performs no writes of its own (see UnpinOutcome above),
+        // so this catch cannot also be reached by an EPIPE from a write this
+        // function made itself — the write below runs only after this try/catch
+        // has already resolved.
+        ctx.stderr.write(`error: ${oneLine(cause)}\n`);
+        return 1;
+    }
+    if (outcome.status === 1) {
+        ctx.stderr.write(`error: ${outcome.message}\n`);
+        return 1;
+    }
+    const { removed, fallback } = outcome;
+    ctx.stdout.write(removed
+        ? `removed saved upstream selection; packaged fallback is ${fallback}\n`
+        : `no saved upstream selection; packaged fallback is ${fallback}\n`);
+    if (ctx.env.SUPERPOWERS_REF) {
+        ctx.stdout.write("note: active SUPERPOWERS_REF override remains effective\n");
+    }
+    if (ctx.env.SUPERPOWERS_UPSTREAM_URL) {
+        ctx.stdout.write("note: active SUPERPOWERS_UPSTREAM_URL override remains effective\n");
+    }
+    return 0;
+}

package/dist/commands/update.js

@@ -0,0 +1,138 @@
+// Ports scripts/update. The shell sourced common.sh and lifecycle.sh; the
+// predicates now live in src/lifecycle.ts. Unlike install and uninstall,
+// update issues no ctx.adapter call of its own: every adapter interaction
+// this module needs already happens inside gatherProbe, runPrepare or
+// runInstall, each of which owns its own §4.2a-conformant invoke() gate. That
+// is also why update opens no temporary workspace of its own -- there is no
+// mutation here for one to protect.
+import { oneLine } from "../cli-arguments.js";
+import { requireManagedUpdateControl, requireNoLegacyState, } from "../lifecycle.js";
+import { formatPorcelain, gatherProbe, replayOutcome, } from "./probe.js";
+import { runInstall } from "./install.js";
+import { runPrepare } from "./prepare.js";
+// `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/update:29-32::echo "$probe_output`'s `case ... *)` wildcard. Same unreachability shape as
+// src/commands/install.ts's renderUnknownProbeStatus: statusForCommits
+// (src/status.ts) can only ever return "needs prepare", "needs
+// install" or "current", so this branch is NOT reachable through runUpdate's
+// own call to gatherProbe today. ProbeFacts.status is typed `string`, not
+// that three-literal union, so a future caller that builds facts by hand (as
+// this module's own unit test does, directly) must still see it fail closed
+// rather than silently proceed.
+//
+// Exported specifically so a direct test can reach it -- not part of the
+// interface Task 5 or Task 8 consume. A test against this export proves the
+// two writes below are correct for a given `facts`; it does NOT prove that
+// runUpdate's own final `else` branch actually reaches and calls this
+// function, or that runUpdate returns 1 afterward -- those are properties of
+// the call site, not of this function, and need their own coverage there.
+export function renderUnknownProbeStatus(facts, ctx) {
+    // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/update:30-31::echo "$probe_output` -- `echo "$probe_output"` (stdout), then the error
+    // to stderr via an explicit `>&2`. This is a DIFFERENT mechanism from
+    // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/install:30-31::printf`'s `spw_die`, even though both end up writing the
+    // porcelain to stdout and an `error: `-prefixed line to stderr: install's
+    // error text flows through spw_die's own `error: $*` formatting, while
+    // update's is spelled out inline in the shell literal already. The two
+    // command modules therefore each need their own case pinning this arm --
+    // one must not be inferred from the other.
+    ctx.stdout.write(formatPorcelain(facts));
+    ctx.stderr.write(`error: unknown probe status: ${facts.status}\n`);
+}
+export async function runUpdate(argv, ctx) {
+    // scripts/update never reads "$@", so extra arguments are silently
+    // ignored -- the same asymmetry runPrepare and runInstall document.
+    void argv;
+    let probe;
+    try {
+        probe = await gatherProbe(ctx);
+    }
+    catch (cause) {
+        // gatherProbe performs no writes of its own (src/commands/probe.ts), so
+        // this catch cannot also be reached by an EPIPE from update's own
+        // output -- update writes nothing before this call resolves, unlike
+        // install's NOTE line.
+        //
+        // This is a THIRD consumer of gatherProbe's throw channel --
+        // `src/commands/probe.ts:381-433::THREE exceptions, all inherited and none a regression:`'s
+        // runProbe catch is the first and src/commands/install.ts's runInstall catch
+        // is the second. Because all three wrap the identical function, runProbe's
+        // long comment there enumerates exactly what can reach this stream too; not
+        // repeated here.
+        ctx.stderr.write(`error: ${oneLine(cause)}\n`);
+        return 1;
+    }
+    // Replay first, on both paths, before any decision -- clause 1.
+    for (const outcome of probe.outcomes)
+        replayOutcome(outcome, ctx);
+    if (probe.status === 1) {
+        if (probe.message !== null) {
+            ctx.stderr.write(`error: ${probe.message}\n`);
+        }
+        return 1;
+    }
+    const facts = probe.facts;
+    // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/update:9-10::identity_state=`. Guards the PROBE-derived value only, matching
+    // src/commands/install.ts's identical guard at `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/install:19-20::identity_state=$(spw_probe_field`: a
+    // probe that reports no identity state at all is a different failure from
+    // one that reports an unrecognised one, and requireNoLegacyState("") would
+    // otherwise reach its "unknown" arm and print a symptom rather than the
+    // actual cause.
+    if (facts.identityState.length === 0) {
+        ctx.stderr.write("error: probe did not report adapter identity state\n");
+        return 1;
+    }
+    // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/update:11::spw_require_no_legacy_state`.
+    const legacy = requireNoLegacyState(facts.identityState);
+    if (legacy.kind === "blocked") {
+        // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/lifecycle.sh:50-53::'Legacy superpowers-wrapper Codex state is`
+        // is a single printf writing three bare lines to stderr, no `error: `
+        // prefix; :54 is the `return 1` that follows it, reached without spw_die.
+        for (const line of legacy.lines)
+            ctx.stderr.write(`${line}\n`);
+        return 1;
+    }
+    if (legacy.kind === "unknown") {
+        ctx.stderr.write(`error: ${legacy.message}\n`);
+        return 1;
+    }
+    // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/update:13-14::update_control=`. install checks only identity_state
+    // (`git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/install:20::report`); update checks update_control too -- the first of
+    // §4.4's two corrections. Both emptiness checks run before the switch, not
+    // just one.
+    if (facts.updateControl.length === 0) {
+        ctx.stderr.write("error: probe did not report adapter update-control capability\n");
+        return 1;
+    }
+    // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/update:16-34::case`, the four-way switch.
+    if (facts.status === "current") {
+        // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/update:18::spw_require_managed_update_control` -- gated BEFORE printing anything. §4.4's second
+        // correction: an update that printed "manager is current" under an
+        // unsupported adapter would be asserting managed control it had not
+        // verified.
+        const managed = requireManagedUpdateControl(facts.updateControl);
+        if (!managed.ok) {
+            ctx.stderr.write(`error: ${managed.message}\n`);
+            return 1;
+        }
+        // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/update:19-20::printf`. Unlike install, which never lets the porcelain
+        // reach the terminal on a successful run (`git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/install:18::porcelain`'s
+        // probe_output=$(...) capture), update prints it here.
+        ctx.stdout.write(formatPorcelain(facts));
+        ctx.stdout.write("manager is current\n");
+        return 0;
+    }
+    if (facts.status === "needs prepare") {
+        // Called as a FUNCTION: a failure propagates as a status, never through
+        // `set -eu`. runPrepare has already replayed its own outcomes and
+        // written its own diagnostics by the time it returns, so nothing further
+        // is written here on that path.
+        const prepareStatus = await runPrepare([], ctx);
+        if (prepareStatus !== 0)
+            return prepareStatus;
+        return await runInstall([], ctx);
+    }
+    if (facts.status === "needs install") {
+        return await runInstall([], ctx);
+    }
+    renderUnknownProbeStatus(facts, ctx);
+    return 1;
+}

package/dist/domain/fingerprint.js

@@ -0,0 +1,4 @@
+export function commitMatches(desired, observed) {
+    return (observed.length > 0 &&
+        (observed === desired || observed === desired.slice(0, 7)));
+}

package/dist/domain/refs.js

@@ -0,0 +1,37 @@
+const SEMVER_BASE_SOURCE = "(?:0|[1-9][0-9]*)\\.(?:0|[1-9][0-9]*)\\.(?:0|[1-9][0-9]*)" +
+    "(?:-(?:(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)" +
+    "(?:\\.(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*))?";
+export const SEMVER_BASE_RE = new RegExp(`^${SEMVER_BASE_SOURCE}$`);
+export const TAG_RE = new RegExp(`^v${SEMVER_BASE_SOURCE}$`);
+export const COMMIT_RE = /^[0-9a-f]{40}$/;
+export const COMMIT_INPUT_RE = /^[0-9A-Fa-f]{40}$/;
+export function isTagRef(value) {
+    return TAG_RE.test(value);
+}
+export function isCommit(value) {
+    return COMMIT_RE.test(value);
+}
+export function normalizeCommitInput(value) {
+    return COMMIT_INPUT_RE.test(value) ? value.toLowerCase() : null;
+}
+export function parseStableTag(tag) {
+    if (!TAG_RE.test(tag))
+        return null;
+    const core = tag.slice(1);
+    // Prerelease filter. Sound only because TAG_RE already matched: the numeric
+    // components cannot contain "-", so the sole way one reaches `core` is a
+    // prerelease suffix. Stable-tag selection must exclude those.
+    if (core.includes("-"))
+        return null;
+    const [major, minor, patch] = core.split(".");
+    return { major: BigInt(major), minor: BigInt(minor), patch: BigInt(patch) };
+}
+export function compareStable(a, b) {
+    if (a.major !== b.major)
+        return a.major < b.major ? -1 : 1;
+    if (a.minor !== b.minor)
+        return a.minor < b.minor ? -1 : 1;
+    if (a.patch !== b.patch)
+        return a.patch < b.patch ? -1 : 1;
+    return 0;
+}