superpowers-manager 0.2.0 → 0.3.0

package/dist/commands/probe.js

@@ -0,0 +1,392 @@
+import { assertFailureWritable, writeAdapterFailure, } from "../adapter-result.js";
+import { oneLine } from "../cli-arguments.js";
+import { computeEffectiveSelection } from "../effective-selection.js";
+import { generatedCommitOrEmpty } from "../provenance.js";
+import { displaySource } from "../selection.js";
+import { statusForCommits } from "../status.js";
+export const PROBE_USAGE = "error: usage: superpowers-manager probe [--porcelain]\n";
+// One ordered table drives both formats, so the porcelain key order
+// (`git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/probe:43-59::printf 'requested_ref`) and the human label order (`git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/probe:61-77::printf 'requested ref`) cannot
+// drift apart. Two parallel lists could each stay self-consistent while
+// disagreeing with one another.
+function fields(f) {
+    return [
+        { key: "requested_ref", label: "requested ref", value: f.requestedRef },
+        { key: "resolved_ref", label: "resolved ref", value: f.resolvedRef },
+        { key: "desired_commit", label: "desired commit", value: f.desiredCommit },
+        {
+            key: "generated_commit",
+            label: "generated plugin commit",
+            value: f.generatedCommit,
+            absent: "not present",
+        },
+        {
+            key: "installed_commit",
+            label: "installed manager commit or fingerprint",
+            value: f.installedCommit,
+            absent: "not detected",
+        },
+        {
+            key: "identity_state",
+            label: "Codex identity state",
+            value: f.identityState,
+        },
+        { key: "status", label: "status", value: f.status },
+        {
+            key: "selection_origin",
+            label: "selection origin",
+            value: f.selectionOrigin,
+        },
+        { key: "selection_mode", label: "selection mode", value: f.selectionMode },
+        {
+            key: "upstream_source_origin",
+            label: "upstream source origin",
+            value: f.upstreamSourceOrigin,
+        },
+        {
+            key: "effective_source",
+            label: "effective source",
+            value: f.effectiveSource,
+        },
+        { key: "saved_mode", label: "saved mode", value: f.savedMode },
+        { key: "saved_source", label: "saved source", value: f.savedSource },
+        {
+            key: "saved_requested_ref",
+            label: "saved requested ref",
+            value: f.savedRequestedRef,
+        },
+        {
+            key: "saved_resolved_ref",
+            label: "saved resolved ref",
+            value: f.savedResolvedRef,
+        },
+        { key: "saved_commit", label: "saved commit", value: f.savedCommit },
+        { key: "update_control", label: "update control", value: f.updateControl },
+    ];
+}
+// Derived from the same fields() table, so the key list a test asserts and
+// the key list formatPorcelain emits cannot be different lists. The facts
+// argument is irrelevant here — fields() is total over ProbeFacts and the
+// keys do not depend on the values.
+const NO_FACTS = {
+    requestedRef: "",
+    resolvedRef: "",
+    desiredCommit: "",
+    generatedCommit: "",
+    installedCommit: "",
+    identityState: "",
+    status: "",
+    selectionOrigin: "",
+    selectionMode: "",
+    upstreamSourceOrigin: "",
+    effectiveSource: "",
+    savedMode: "",
+    savedSource: "",
+    savedRequestedRef: "",
+    savedResolvedRef: "",
+    savedCommit: "",
+    updateControl: "",
+};
+export const PROBE_PORCELAIN_KEYS = fields(NO_FACTS).map((field) => field.key);
+export function formatPorcelain(f) {
+    return fields(f)
+        .map((field) => `${field.key}=${field.value}\n`)
+        .join("");
+}
+export function formatHuman(f) {
+    let text = fields(f)
+        .map((field) => {
+        const shown = field.value.length === 0 && field.absent !== undefined
+            ? field.absent
+            : field.value;
+        return `${field.label}: ${shown}\n`;
+    })
+        .join("");
+    // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/probe:78-81::if [ "$SPW_SELECTION_ORIGIN`.
+    if (f.selectionOrigin !== f.upstreamSourceOrigin) {
+        text +=
+            "warning: effective ref and source have mixed origins " +
+                `(ref: ${f.selectionOrigin}, source: ${f.upstreamSourceOrigin})\n`;
+    }
+    return text;
+}
+// Ports scripts/core/validate-adapter-response.py's replay (:235-238) and its
+// error/hint block (:269-272). The shell ran that validator on EVERY adapter
+// response, so adapter messages reached the operator on their declared streams
+// in array order, and a controlled failure printed `error:` plus one `hint:`
+// per hint. DIAG-ADAPTER-01 retains that contract
+// (docs/baseline/protocol-disposition.md); dropping it here would be a
+// silent diagnostics regression, not a simplification.
+//
+// Interpolating error.message and each hint is the sanctioned form (AGENTS.md):
+// src/adapter.ts has 52 `fail()` sites and none interpolates a caught error's
+// message, so the callee owns every failure reachable on this path. Those two
+// writes now live in writeAdapterFailure (src/adapter-result.ts), which
+// validates all three strings before the first of them reaches the stream.
+//
+// This writes to ctx, so it MUST NOT be called from inside gatherProbe's try
+// -- see the ProbeOutcome note below.
+export function replayOutcome(outcome, ctx) {
+    // Hoisted ABOVE the message loop, and that ordering is the point: a failure
+    // whose code, message, or a hint carries a terminal control character must
+    // leave both streams untouched, not the context lines followed by nothing.
+    // Returns immediately on a succeeding outcome.
+    assertFailureWritable(outcome);
+    for (const message of outcome.messages) {
+        const stream = message.channel === "stdout" ? ctx.stdout : ctx.stderr;
+        stream.write(`${message.text}\n`);
+    }
+    // The message loop stays unguarded on purpose: D8b scopes the check to code,
+    // message, and hints, and AdapterMessageLog escapes message text before it is
+    // stored, so scanning it here would re-check a population that cannot fail.
+    writeAdapterFailure(ctx, outcome);
+}
+// `runAdapter` reports a CONTROLLED failure by RETURN VALUE, not by throwing
+// (`src/adapter-result.ts:32-35::export interface AdapterResult`). The shell got
+// fail-closed behaviour for free: spw_invoke_adapter returned 1 and
+// scripts/probe ran under `set -eu`.
+// Omitting the status check here would read a failed inspection as absent
+// evidence and report it as success.
+//
+// It does still THROW for a non-AdapterFailure cause (runAdapter's closing
+// `throw cause`, src/adapter.ts). That is caught here rather than in runProbe's
+// outer catch, because the two need different diagnostics -- see spec §3.3a.
+//
+// Reached through ctx.adapter, not a direct module-level dependency on the
+// adapter module: src/commands/prepare.ts and this module are the two the
+// injected double must observe, because install reaches the adapter through
+// gatherProbe and runPrepare. Spec §4.5.
+async function inspect(view, key, ctx) {
+    let result;
+    try {
+        result = await ctx.adapter(["inspect", "--view", view], {
+            root: ctx.root,
+            env: ctx.env,
+        });
+    }
+    catch {
+        // Deliberately does NOT interpolate the cause. A rethrown non-
+        // AdapterFailure is by construction the one failure src/adapter.ts chose
+        // not to own: free-form text of unknown provenance, which AGENTS.md bars
+        // from this stream. `view` is a bounded token -- one of three literals
+        // this function is ever called with -- so naming the input is safe.
+        return {
+            ok: false,
+            outcome: null,
+            message: `cannot inspect Codex adapter state for view ${view}`,
+        };
+    }
+    const outcome = result.outcome;
+    if (result.status !== 0 || !outcome.ok) {
+        // The `outcome.ok && status !== 0` combination cannot arise from
+        // successResult/failureResult, so it gets its own hand-written message
+        // rather than falling through to a replay that would print nothing.
+        return {
+            ok: false,
+            outcome,
+            message: outcome.ok
+                ? `adapter reported a failure status for inspect --view ${view}`
+                : null,
+        };
+    }
+    const value = outcome.result?.[key];
+    // The Python reader printed the empty string for a JSON null
+    // (scripts/core/provenance.sh's spw_json_get), and `fingerprint` is null
+    // whenever no plugin version is active (`src/adapter.ts:820::fingerprint: null`).
+    if (value === null || value === undefined) {
+        return { ok: true, value: "", outcome };
+    }
+    if (typeof value !== "string") {
+        return {
+            ok: false,
+            outcome,
+            message: `adapter returned a non-string ${key} for inspect --view ${view}`,
+        };
+    }
+    return { ok: true, value, outcome };
+}
+// Runs every step that can throw or fail closed, returning the outcome as
+// data. It performs no writes of its own, so nothing inside runProbe's try can
+// raise EPIPE — the same shape as src/commands/unpin.ts's attemptUnpin.
+//
+// The outcomes are CARRIED OUT rather than replayed in place, for that same
+// reason: replayOutcome writes to ctx, and a write inside this try could
+// raise EPIPE and be caught and relabelled as a selection failure. runProbe
+// replays them, in collection order, after the try/catch has resolved. The
+// operator-visible result is identical -- probe emits nothing else until the
+// very end -- and the EPIPE hazard never exists.
+// Exported for src/commands/install.ts and src/commands/update.ts, which need
+// probe's FACTS rather than its rendering. The historical
+// `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/lifecycle.sh:39-41::spw_probe_field`
+// implementation awk-parsed the porcelain back into fields; that round trip is
+// gone.
+export async function gatherProbe(ctx) {
+    // Order mirrors `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/probe:24-40::spw_compute_effective_selection` exactly.
+    const selection = await computeEffectiveSelection(ctx.root, ctx.env);
+    const generatedCommit = await generatedCommitOrEmpty(ctx.root);
+    const outcomes = [];
+    const collect = async (view, key) => {
+        const result = await inspect(view, key, ctx);
+        if (result.outcome !== null)
+            outcomes.push(result.outcome);
+        return result;
+    };
+    const fingerprint = await collect("fingerprint", "fingerprint");
+    if (!fingerprint.ok) {
+        return { status: 1, outcomes, message: fingerprint.message };
+    }
+    const ownership = await collect("ownership", "identity_state");
+    if (!ownership.ok) {
+        return { status: 1, outcomes, message: ownership.message };
+    }
+    const updateControl = await collect("update-control", "update_control");
+    if (!updateControl.ok) {
+        return { status: 1, outcomes, message: updateControl.message };
+    }
+    const saved = selection.saved;
+    return {
+        status: 0,
+        outcomes,
+        facts: {
+            requestedRef: selection.requestedRef,
+            resolvedRef: selection.resolvedRef,
+            desiredCommit: selection.desiredCommit,
+            generatedCommit,
+            installedCommit: fingerprint.value,
+            identityState: ownership.value,
+            status: statusForCommits(selection.desiredCommit, generatedCommit, fingerprint.value),
+            selectionOrigin: selection.selectionOrigin,
+            selectionMode: selection.selectionMode,
+            upstreamSourceOrigin: selection.upstreamSourceOrigin,
+            effectiveSource: displaySource(selection.effectiveSource),
+            savedMode: saved.saved_mode,
+            // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/probe:26-30::if [ -`: an absent saved source stays empty rather than
+            // being run through displaySource, which would render <redacted-source>.
+            savedSource: saved.saved_source.length > 0 ? displaySource(saved.saved_source) : "",
+            savedRequestedRef: saved.saved_requested_ref,
+            savedResolvedRef: saved.saved_resolved_ref,
+            savedCommit: saved.saved_commit,
+            updateControl: updateControl.value,
+        },
+    };
+}
+export async function runProbe(argv, ctx) {
+    // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/probe:42::porcelain` tested only `[ "${1:-}" = "--porcelain" ]`, so a typo'd
+    // flag silently produced human output. Rejecting it is a deliberate
+    // narrowing, recorded as a port-only entry in
+    // tests/migration-inventory/probe.md.
+    //
+    // This guard is NOT the production path. src/cli.ts's parseArgs rejects the
+    // same inputs first, before preflight, with the usage block the CLI's other
+    // usage errors carry — exactly the arrangement track-latest and unpin have,
+    // where the in-module check is an unreachable-from-CLI duplicate. It stays
+    // because runProbe is also called directly by tests and by any future
+    // in-process caller that has not been through parseArgs.
+    const porcelain = argv.length === 1 && argv[0] === "--porcelain";
+    if (!porcelain && argv.length !== 0) {
+        ctx.stderr.write(PROBE_USAGE);
+        return 2;
+    }
+    let outcome;
+    try {
+        outcome = await gatherProbe(ctx);
+    }
+    catch (cause) {
+        // Hand-written messages, per AGENTS.md's reader-diagnostics rule. Reachable
+        // here: the selectionErrors validateSource raises
+        // (`src/selection.ts:137::malformed`, :140, requireSingleLineString at :77),
+        // reached from
+        // computeEffectiveSelection's validateSource call
+        // (src/effective-selection.ts); the ones validateRecord raises
+        // (`src/selection.ts:198::integer`, :219, requireObject at :47, requireExactKeys at
+        // :64, validatePinnedRecord at :170-183), reached from
+        // `src/selection-store.ts:103::return validateRecord` on the read path; the
+        // selectionErrors requireAbsolute and selectionConfigDir
+        // (src/effective-selection.ts) raise
+        // for a non-absolute or missing config directory; readConfigRef's `cannot
+        // read packaged upstream ref <path>` (src/upstream.ts); and resolveRef's own
+        // two no-match diagnostics, `no stable semver tag found for latest-release`
+        // and `cannot resolve upstream ref: <ref>` (src/upstream.ts). normalizeSaved
+        // (`src/selection.ts:222-241::normalizeSaved`) throws nothing at all.
+        //
+        // THREE exceptions, all inherited and none a regression:
+        //   1. resolveRef splices git's combined stdout+stderr into its own text
+        //      (its three `cannot query upstream ...` throws, src/upstream.ts),
+        //      reached via computeEffectiveSelection's resolveRef call
+        //      (src/effective-selection.ts). The packaged ref is `latest-release`,
+        //      which resolveRef answers with an ls-remote, so an ordinary unpinned
+        //      run reaches this rather than only an exotic corner -- though not
+        //      every unpinned run does: resolveRef's COMMIT_INPUT_RE branch returns
+        //      before any runGit call, so a 40-hex requested ref splices nothing.
+        //      Pinned by
+        //      `tests/unit/upstream.test.js:460::void test("resolveRef reports a query failure for latest`,
+        //      :471, and :483.
+        //   2. The
+        //      `src/selection-store.ts:120-124::cause.module === "selection") {`
+        //      site (same shape at :49, :86, :98) is the module AGENTS.md's
+        //      `src/selection-store.ts` bullet grandfathers:
+        //      it interpolates the caught error's own message, so Node errno
+        //      prose can reach this stream. Reached on the READ path only, via
+        //      loadSavedSelection (src/effective-selection.ts) ->
+        //      readSelectionState
+        //      (`src/selection-store.ts:149::export async function readSelectionState`).
+        //      This module's four write-only interpolating sites -- ensureStateDirectory
+        //      (:172), finalStateDiagnostic (:197), and the two in
+        //      writeSelectionState's own catch (:225, :231) -- are all
+        //      unreachable from probe, which never writes.
+        //   3. Every runGit call site inside resolveRef (src/upstream.ts) can
+        //      reject instead of resolving. On the non-ENOENT arm of
+        //      `src/git.ts:47-52::if (typeof`, runGit builds the message
+        //      "cannot run git: " followed by the Node spawn error's own message
+        //      (:51) and rejects with a SafetyError carrying it (:52), so that
+        //      Node spawn-level text reaches ctx.stderr through this catch. The
+        //      ENOENT arm (:50) is hand-written and carries nothing. A non-zero
+        //      *exit status* is handled by exception 1 above; this is the
+        //      *spawn-level* case, where runGit throws rather than returning a
+        //      status.
+        //
+        // oneLine() at this catch collapses each of exceptions 1 and 3 -- the two
+        // carrying git-derived text -- to a single line. It collapses CR/LF only,
+        // so it bounds how much of that text lands, not what it may contain.
+        //
+        // fetchExactCommit is deliberately NOT in this list, unlike prepare's
+        // fetchExactCommit exception, which runPrepare's catch block documents.
+        // Its only callers are `src/upstream-cli.ts:83::await fetchExactCommit` and
+        // gatherPrepare's own call in src/commands/prepare.ts (git grep -n
+        // fetchExactCommit -- src/ is the check that keeps "only" true), so probe
+        // never reaches it and
+        // its splice sites cannot appear on this stream. Do not add it back by
+        // symmetry with prepare.
+        //
+        // generatedCommitOrEmpty is not in this list either: it cannot throw at
+        // all. It (src/provenance.ts) delegates to readGeneratedCommitLenient,
+        // which catches every failure and returns "".
+        //
+        // A non-AdapterFailure re-thrown by runAdapter's closing `throw cause`
+        // (src/adapter.ts) does NOT reach here: inspect() catches it and converts
+        // it to a hand-written message per AGENTS.md's reader-diagnostics rule -- a
+        // rethrown cause is exactly the failure src/adapter.ts declined to own, so
+        // its text must never reach this stream. See §3.3a.
+        //
+        // gatherProbe performs no writes of its own, so this catch cannot also be
+        // reached by an EPIPE from probe's own output — every write below runs
+        // only after this try/catch has resolved.
+        ctx.stderr.write(`error: ${oneLine(cause)}\n`);
+        return 1;
+    }
+    // Replay first, on both paths: the shell validator replayed every response's
+    // messages whether or not that response was a failure at
+    // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/validate-adapter-response.py:268::replay(messages)`.
+    for (const each of outcome.outcomes)
+        replayOutcome(each, ctx);
+    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`);
+        }
+        return 1;
+    }
+    ctx.stdout.write(porcelain ? formatPorcelain(outcome.facts) : formatHuman(outcome.facts));
+    return 0;
+}

package/dist/commands/track-latest.js

@@ -0,0 +1,44 @@
+import { oneLine } from "../cli-arguments.js";
+import { selectionStatePath, loadSavedSelection, UPSTREAM_URL_DEFAULT, } from "../effective-selection.js";
+import { validateSource } from "../selection.js";
+import { writeSelectionState } from "../selection-store.js";
+export async function runTrackLatest(argv, ctx) {
+    if (argv.length !== 0) {
+        ctx.stderr.write("error: usage: superpowers-manager track-latest\n");
+        return 2;
+    }
+    try {
+        // 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/track-latest:20-21::read`'s read-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);
+        await writeSelectionState(selectionStatePath(ctx.env), {
+            schema_version: 1,
+            mode: "track-latest",
+            source,
+        });
+    }
+    catch (cause) {
+        // Every throw reachable here is a hand-written SafetyError from
+        // loadSavedSelection, validateSource, selectionStatePath, or
+        // writeSelectionState — re-emitting a subordinate module's own
+        // diagnostic is the sanctioned form of interpolation (see AGENTS.md's
+        // diagnostics convention). The try ends here, before the stdout write
+        // below: an EPIPE from that write must never be caught and relabelled
+        // as one of those modules' own diagnostics.
+        ctx.stderr.write(`error: ${oneLine(cause)}\n`);
+        return 1;
+    }
+    ctx.stdout.write("saved upstream selection: latest stable release\n");
+    return 0;
+}