superpowers-manager 0.2.0 → 0.3.0

package/dist/commands/install.js

@@ -0,0 +1,376 @@
+// Ports scripts/install. The shell sourced common.sh, provenance.sh,
+// status.sh, lifecycle.sh and adapter.sh; the predicates now live in
+// src/lifecycle.ts, the generated-metadata read lives in src/provenance.ts,
+// and the adapter arrives through ctx.adapter.
+import { tmpdir } from "node:os";
+import { oneLine } from "../cli-arguments.js";
+import { requireManagedUpdateControl, requireNoLegacyState, verifyInstalledFingerprint, } from "../lifecycle.js";
+import { generatedMetadataPath, readStrictProvenanceField, } from "../provenance.js";
+import { withWorkspace, workspaceRemovalFailure } from "../workspace.js";
+import { formatPorcelain, gatherProbe, replayOutcome, } from "./probe.js";
+import { runPrepare } from "./prepare.js";
+// `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/install:13::conflicting`, verbatim, and always first: the shell echoed it before
+// even invoking probe.
+const NOTE = "Note: remove or disable conflicting Superpowers providers yourself before" +
+    " relying on manager skills.\n";
+function readStringField(result, key, label) {
+    // Callers only reach this after invoke() has already proven
+    // `result.status === 0 && result.outcome.ok`; the guard below is for
+    // TypeScript's narrowing of `outcome.result`, not a live branch.
+    const outcome = result.outcome;
+    const parsed = outcome.ok
+        ? outcome.result
+        : null;
+    const raw = parsed?.[key];
+    if (raw === null || raw === undefined)
+        return { kind: "ok", value: "" };
+    if (typeof raw === "string")
+        return { kind: "ok", value: raw };
+    return {
+        kind: "malformed",
+        message: `adapter returned a non-string ${key} for ${label}`,
+    };
+}
+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(" ")}`,
+            result: null,
+        };
+    }
+    // Clause 1: replay every outcome, on both the success and the failure
+    // path, before any decision -- collected here and replayed by runInstall
+    // once gatherInstallStages's try/catch has resolved, for the same EPIPE
+    // reason gatherProbe carries its outcomes out rather than writing in place
+    // (src/commands/probe.ts).
+    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,
+            result,
+        };
+    }
+    return { ok: true, result };
+}
+// withWorkspace can throw AFTER its callback has already returned a fully
+// computed StageOutcome: a post-success cleanup failure discards that return
+// value entirely and rejects instead, UNLESS an `onCleanupFailure` reporter is
+// supplied -- which gatherInstallStages below does, precisely so this class
+// stays reserved for mkdtemp failure (nothing collected yet) and the
+// callback's own throw (never reachable here; see gatherInstallStages).
+// Carries the outcomes collected so far so runInstall's catch can still
+// replay them instead of discarding them with a bare re-throw. Same shape as
+// src/commands/uninstall.ts's GatherFailure, duplicated for the same reason
+// invoke() is: no shared dependency between the two modules.
+class GatherFailure extends Error {
+    inner;
+    outcomes;
+    constructor(inner, outcomes) {
+        super("install gather failed");
+        this.inner = inner;
+        this.outcomes = outcomes;
+    }
+}
+// `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/install:44-58::TMPDIR=`, wrapped in the temporary workspace scripts/install
+// created via spw_make_workspace + spw_install_workspace_trap. Performs no
+// writes of its own -- same EPIPE-avoidance shape as gatherProbe and
+// src/commands/uninstall.ts's gatherUninstall.
+async function gatherInstallStages(ctx, desiredCommit) {
+    // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/install:38::tmp_parent=` -- ${TMPDIR:-/tmp}. Matches
+    // src/commands/uninstall.ts's gatherUninstall.
+    const parent = ctx.env.TMPDIR ?? tmpdir();
+    const outcomes = [];
+    let cleanupWarning = null;
+    try {
+        const outcome = await withWorkspace(parent, "superpowers-manager.install.", async (workspace) => {
+            const env = { ...ctx.env, TMPDIR: workspace };
+            const failed = (message) => ({
+                kind: "failed",
+                outcomes,
+                message,
+            });
+            // Stage 1: inspect ownership, re-checked even though gatherProbe just
+            // reported it. Mutation authority requires CURRENT, VALIDATED
+            // evidence -- a probe's answer is neither by the time this runs.
+            const ownership = await invoke(ctx, env, ["inspect", "--view", "ownership"], outcomes);
+            if (!ownership.ok)
+                return failed(ownership.message);
+            const identity = readStringField(ownership.result, "identity_state", "inspect --view ownership");
+            if (identity.kind === "malformed")
+                return failed(identity.message);
+            const legacy = requireNoLegacyState(identity.value);
+            if (legacy.kind === "blocked") {
+                return { kind: "blocked", outcomes, lines: legacy.lines };
+            }
+            if (legacy.kind === "unknown")
+                return failed(legacy.message);
+            // Stage 2: inspect update-control, re-checked for the same reason.
+            const updateControl = await invoke(ctx, env, ["inspect", "--view", "update-control"], outcomes);
+            if (!updateControl.ok)
+                return failed(updateControl.message);
+            const control = readStringField(updateControl.result, "update_control", "inspect --view update-control");
+            if (control.kind === "malformed")
+                return failed(control.message);
+            const managed = requireManagedUpdateControl(control.value);
+            if (!managed.ok)
+                return failed(managed.message);
+            // Stage 3: the mutation itself. Nothing above may have issued this --
+            // that is the whole point of stages 1 and 2 running first.
+            const install = await invoke(ctx, env, ["install", "--package-root", ctx.root], outcomes);
+            if (!install.ok)
+                return failed(install.message);
+            // Stage 4: inspect fingerprint, to verify the mutation actually took.
+            //
+            // Deliberately NOT short-circuited on `!inspected.ok`, unlike stages
+            // 1-3. `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/install:57::spw_verify_installed_fingerprint` handed the inspect result to
+            // spw_verify_installed_fingerprint whatever it contained, and that
+            // function's first guard, from
+            // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/lifecycle.sh:91-94::spw_inspect_fingerprint`,
+            // is what turns a failed inspection into "error: installed manager
+            // fingerprint inspection failed after install."
+            // verifyInstalledFingerprint's "call-failed" arm
+            // (`src/lifecycle.ts:158::if (inspected.kind === "call-failed") {`)
+            // exists for exactly this and is reachable only from here. Returning
+            // failed() instead reported the adapter's own generic diagnostic and
+            // dropped the post-install verification claim -- a mutation had
+            // already been issued at stage 3,
+            // so "the install could not be verified" is the contract, not "an
+            // adapter call failed". A ctx.adapter THROW is the one case with no
+            // result to verify against, and keeps the short-circuit.
+            const inspected = await invoke(ctx, env, ["inspect", "--view", "fingerprint"], outcomes);
+            let inspectResult;
+            if (inspected.ok) {
+                inspectResult = inspected.result;
+            }
+            else {
+                if (inspected.result === null)
+                    return failed(inspected.message);
+                inspectResult = inspected.result;
+            }
+            const verdict = verifyInstalledFingerprint(desiredCommit, install.result, inspectResult);
+            return {
+                kind: "verified",
+                outcomes,
+                status: verdict.ok ? 0 : 1,
+                stdout: verdict.stdout,
+                stderr: verdict.stderr,
+            };
+        }, {
+            // Suppresses withWorkspace's throw on a POST-SUCCESS cleanup failure,
+            // so the StageOutcome the callback already computed still comes back
+            // as `outcome` below instead of being discarded. `report` runs
+            // synchronously, as the option requires (src/workspace.ts).
+            onCleanupFailure: (path) => {
+                cleanupWarning = workspaceRemovalFailure(path);
+            },
+        });
+        return { outcome, cleanupWarning };
+    }
+    catch (cause) {
+        // Reachable only for mkdtemp failure (nothing collected yet) -- the
+        // callback above never throws, so a post-success cleanup failure is
+        // already handled by onCleanupFailure and cannot reach here.
+        throw new GatherFailure(cause, outcomes);
+    }
+}
+// `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/install:29-32::printf` kept its shell `case ... *)` wildcard even though the
+// three inputs the shell's own probe could ever emit were bounded by the same
+// three-way status.sh logic this port's statusForCommits (src/status.ts) now
+// owns exactly. statusForCommits can only ever return "needs prepare",
+// "needs install" or "current" -- so this branch is NOT reachable through
+// runInstall's own call to gatherProbe today. It stays anyway, because
+// ProbeFacts.status is typed `string`, not that three-literal union, and 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. That is ONE STEP
+// FURTHER than
+// `src/commands/probe.ts:367-372::This guard is NOT the production path.`'s own
+// precedent: that comment licenses RETAINING an unreachable branch inside an
+// already-public function (runProbe was public before that comment existed),
+// not EXPORTING a new one. This module does the latter, deliberately, because
+// runInstall
+// itself has no way to construct the unreachable input. 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 runInstall's own `else if` branch
+// actually reaches and calls this function, or that runInstall 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/install:30-31::printf` -- the porcelain reaches the terminal ONLY here.
+    // Every other path swallows it, matching `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/install:18::porcelain`'s
+    // probe_output=$(...) capture.
+    ctx.stdout.write(formatPorcelain(facts));
+    ctx.stderr.write(`error: unknown probe status: ${facts.status}\n`);
+}
+export async function runInstall(argv, ctx) {
+    // scripts/install never reads "$@", so extra arguments are silently
+    // ignored -- the same asymmetry runPrepare and runUninstall document.
+    void argv;
+    ctx.stdout.write(NOTE);
+    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 install's own
+        // output: the NOTE line above already left the try, and everything below
+        // runs only after this try/catch has resolved.
+        //
+        // This is a SECOND consumer of gatherProbe's throw channel --
+        // `src/commands/probe.ts:399-433::THREE exceptions, all inherited and none a regression:`'s
+        // runProbe catch is the first. Because both consumers wrap the identical
+        // function, its long comment there enumerates exactly what can reach THIS
+        // stream too, including the three foreign-text exceptions at :399-433:
+        //   1. :399-410 -- resolveRef splices git's own combined stdout+stderr
+        //      into its text. Reached on probe's DEFAULT path, which that comment
+        //      defines as every invocation NOT resolving a saved pin: a 40-hex
+        //      ref returns a "raw-commit" resolution at
+        //      `src/upstream.ts:162-164::return { kind: "raw-commit"`
+        //      before any git call, so it reaches no splice at all.
+        //   2. :411-423 -- src/selection-store.ts's read path interpolates the
+        //      caught error's own message, so Node errno prose can appear.
+        //      AGENTS.md grandfathers that module's wording.
+        //   3. :424-433 -- a SPAWN-level git failure, a different channel from
+        //      exception 1's exit-status one: on the non-ENOENT arm of
+        //      `src/git.ts:47-52::if (typeof failure.code === "string") {`, runGit
+        //      rejects with "cannot run git: " followed by the Node spawn error's
+        //      own message.
+        // Not repeated in full here; read it there.
+        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/install:19-20::identity_state=$(spw_probe_field`. Guards the PROBE-derived value only -- the
+    // re-inspection at :198 reads through readStringField, which already has
+    // its own "malformed" arm for a non-string value, and an empty string
+    // there is legitimately absent (the JSON-null convention), not an error.
+    // This check exists because a probe that reports no identity state at all
+    // is a different failure than one that reports an unrecognised one:
+    // requireNoLegacyState("") would otherwise reach its "unknown" arm and
+    // print "unknown adapter identity state: " (empty-suffixed), which names a
+    // symptom rather than the actual cause. Do NOT add a second copy of this
+    // check at :198 -- it guards a different value with a different failure
+    // mode.
+    if (facts.identityState.length === 0) {
+        ctx.stderr.write("error: probe did not report adapter identity state\n");
+        return 1;
+    }
+    // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/install:20-21::report`, run BEFORE the workspace is ever created and before
+    // any further adapter call -- a legacy identity is fatal on sight, not
+    // something worth spending a mutation attempt on.
+    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/install:22-33::status=`.
+    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;
+    }
+    else if (facts.status !== "needs install" && facts.status !== "current") {
+        renderUnknownProbeStatus(facts, ctx);
+        return 1;
+    }
+    // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/install:35-36::spw_metadata_commit_or_empty`. The STRICT reader, never the lenient
+    // generatedCommitOrEmpty gatherProbe already used for facts.generatedCommit:
+    // a throw, an absent key, or a non-string value are all treated as absent
+    // here, matching spw_metadata_commit_or_empty's `|| true` plus the
+    // following `[ -n ]` check.
+    let desiredCommit = "";
+    try {
+        const value = await readStrictProvenanceField(generatedMetadataPath(ctx.root), "commit");
+        if (typeof value === "string")
+            desiredCommit = value;
+    }
+    catch {
+        // Absent, same as an undefined or non-string read.
+    }
+    if (desiredCommit.length === 0) {
+        ctx.stderr.write("error: generated metadata missing desired commit after prepare\n");
+        return 1;
+    }
+    let stage;
+    try {
+        stage = await gatherInstallStages(ctx, desiredCommit);
+    }
+    catch (cause) {
+        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 } = stage;
+    for (const each of outcome.outcomes)
+        replayOutcome(each, ctx);
+    let status;
+    if (outcome.kind === "blocked") {
+        for (const line of outcome.lines)
+            ctx.stderr.write(`${line}\n`);
+        status = 1;
+    }
+    else if (outcome.kind === "failed") {
+        if (outcome.message !== null) {
+            ctx.stderr.write(`error: ${outcome.message}\n`);
+        }
+        status = 1;
+    }
+    else {
+        // :99-100 printed both lines BEFORE deciding, on every path that got this
+        // far; verifyInstalledFingerprint already encodes that, so both arrays
+        // are written in order regardless of verdict.ok.
+        for (const line of outcome.stdout)
+            ctx.stdout.write(`${line}\n`);
+        for (const line of outcome.stderr)
+            ctx.stderr.write(`${line}\n`);
+        status = outcome.status;
+    }
+    if (cleanupWarning !== null) {
+        // A leaked workspace is reported even when the domain outcome above was
+        // itself a success: the fingerprint verification that produced that
+        // success 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.
+        ctx.stderr.write(`error: ${cleanupWarning}\n`);
+        return 1;
+    }
+    return status;
+}

package/dist/commands/pin.js

@@ -0,0 +1,79 @@
+import { tmpdir } from "node:os";
+import { oneLine } from "../cli-arguments.js";
+import { isTagRef, normalizeCommitInput } from "../domain/refs.js";
+import { loadSavedSelection, selectionStatePath, UPSTREAM_URL_DEFAULT, } from "../effective-selection.js";
+import { normalizePinnedArguments, validateSource } from "../selection.js";
+import { writeSelectionState } from "../selection-store.js";
+import { resolveExactTag, verifyRawCommit } from "../upstream.js";
+// Runs every step that can throw, and performs no writes of its own: that is
+// the point of this shape (mirrors src/commands/unpin.ts's attemptUnpin) —
+// runPin's try (below) can therefore never itself raise EPIPE, since nothing
+// left inside it writes to a stream.
+async function attemptPin(requested, ctx) {
+    // Read first. This is a deliberate redundant boundary check, not the
+    // enforcing guard: writeSelectionState below already refuses to overwrite
+    // a corrupt existing record on its own (src/selection-store.ts's
+    // writeSelectionState calls readSelectionState on the same path before
+    // writing, under "Invalid existing state must block overwrite" —
+    // readSelectionState's own readOpenedRecord/parseRecordBytes is what
+    // validates an existing record, via validateRecord at
+    // `src/selection-store.ts:103::return validateRecord`). Calling loadSavedSelection here preserves
+    // `git show 349fe2ed405b371ec2de1347bb3fc50c6bc15dc4:scripts/pin:26-27::read`'s read-then-resolve-then-write shape, so this command
+    // stays fail-closed on its own terms rather than solely by depending on the
+    // store's internals.
+    await loadSavedSelection(ctx.env);
+    const source = ctx.env.SUPERPOWERS_UPSTREAM_URL || UPSTREAM_URL_DEFAULT;
+    validateSource(source);
+    let resolvedRef;
+    let commit;
+    if (isTagRef(requested)) {
+        resolvedRef = requested;
+        commit = await resolveExactTag(source, requested);
+    }
+    else {
+        // `git show 349fe2ed405b371ec2de1347bb3fc50c6bc15dc4:scripts/pin:39::upper` lowercases a raw-commit request before use; both
+        // requested_ref and resolved_ref end up equal to the normalized commit.
+        resolvedRef = normalizeCommitInput(requested);
+        commit = await verifyRawCommit(source, resolvedRef, tmpdir());
+    }
+    await writeSelectionState(selectionStatePath(ctx.env), normalizePinnedArguments({
+        source,
+        requestedRef: resolvedRef,
+        resolvedRef,
+        commit,
+    }));
+    return { resolvedRef, commit };
+}
+export async function runPin(argv, ctx) {
+    // Arity and ref syntax are already decided in src/cli.ts's parseArgs (the
+    // TAG_RE / COMMIT_INPUT_RE check ahead of dispatch) and must not be
+    // duplicated here — one source, checked before any tool lookup.
+    const requested = argv[0];
+    let result;
+    try {
+        result = await attemptPin(requested, ctx);
+    }
+    catch (cause) {
+        // Every throw reachable here is a hand-written SafetyError from
+        // loadSavedSelection, validateSource, resolveExactTag, verifyRawCommit,
+        // or writeSelectionState — re-emitting a subordinate module's own
+        // diagnostic is the sanctioned form of interpolation (see AGENTS.md's
+        // diagnostics convention). That does not make every such message clean:
+        // resolveExactTag's and verifyRawCommit's SafetyErrors splice git's own
+        // combined stdout+stderr into their text (src/upstream.ts's `combined()`,
+        // used at :219 for `ls-remote` and :262 for `init`), so raw git output can
+        // reach ctx.stderr through this catch. Not a regression — scripts/pin
+        // piped git's output into its own error text the same way — but `pin` is
+        // the first in-process command able to surface it. oneLine() collapses
+        // that spliced output to one line, containing the harm to one line of
+        // git text rather than the arbitrarily many the shell original allowed.
+        // attemptPin performs no writes of its own (see 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;
+    }
+    ctx.stdout.write(`pinned upstream selection to ${result.resolvedRef} at ${result.commit}\n`);
+    return 0;
+}