superpowers-manager 0.2.0 → 0.4.0

package/dist/commands/update.js

@@ -0,0 +1,79 @@
+// 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 { gatherProbe, replayOutcome } from "./probe.js";
+import { runInstall } from "./install.js";
+import { runPrepare } from "./prepare.js";
+function writeOutput(output, ctx) {
+    for (const line of output.stdout)
+        ctx.stdout.write(`${line}\n`);
+    for (const line of output.stderr)
+        ctx.stderr.write(`${line}\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:251-309::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;
+    if (facts.ownership.installEligibility.kind === "blocked") {
+        writeOutput(facts.ownership.installEligibility.output, ctx);
+        return 1;
+    }
+    if (facts.control.probeEligibility.kind === "blocked") {
+        writeOutput(facts.control.probeEligibility.output, ctx);
+        return 1;
+    }
+    switch (facts.status) {
+        case "current": {
+            if (facts.control.mutationEligibility.kind === "blocked") {
+                writeOutput(facts.control.mutationEligibility.output, ctx);
+                return 1;
+            }
+            const rendered = ctx.adapter.presentation.renderProbe(facts);
+            ctx.stdout.write(rendered.porcelain);
+            ctx.stdout.write(`${ctx.adapter.presentation.currentNotice}\n`);
+            return 0;
+        }
+        case "needs prepare": {
+            const prepareStatus = await runPrepare([], ctx);
+            if (prepareStatus !== 0)
+                return prepareStatus;
+            return await runInstall([], ctx);
+        }
+        case "needs install":
+            return await runInstall([], ctx);
+    }
+}

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;
+}

package/dist/effective-selection.js

@@ -0,0 +1,123 @@
+// `selectionError` already exists at
+// `src/selection.ts:41::export function selectionError` and tags errors with
+// module "selection". Import it rather than defining a second one.
+import { normalizeSaved, selectionError, validateSource, } from "./selection.js";
+import { readSelectionState } from "./selection-store.js";
+import { readConfigRef, resolveRef } from "./upstream.js";
+import { COMMIT_RE } from "./domain/refs.js";
+function requireAbsolute(value, variable) {
+    if (!value.startsWith("/")) {
+        throw selectionError(`${variable} must be absolute`);
+    }
+    return value;
+}
+// Precedence mirrors
+// `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/selection.sh:4-29::spw_selection_config_dir(`.
+// SUPERPOWERS_CONFIG_DIR is selected on *presence*, matching the shell's
+// ${SUPERPOWERS_CONFIG_DIR+x}: an empty value takes this branch and then fails
+// the absolute check, rather than falling through to XDG.
+export function selectionConfigDir(env) {
+    const explicit = env.SUPERPOWERS_CONFIG_DIR;
+    if (explicit !== undefined) {
+        return requireAbsolute(explicit, "SUPERPOWERS_CONFIG_DIR");
+    }
+    const xdg = env.XDG_CONFIG_HOME;
+    if (xdg !== undefined && xdg.length > 0) {
+        return `${requireAbsolute(xdg, "XDG_CONFIG_HOME")}/superpowers-manager`;
+    }
+    const home = env.HOME;
+    if (home === undefined || home.length === 0) {
+        throw selectionError("HOME is required to locate selection state");
+    }
+    return `${requireAbsolute(home, "HOME")}/.config/superpowers-manager`;
+}
+export function selectionStatePath(env) {
+    return `${selectionConfigDir(env)}/selection.json`;
+}
+// Composes exactly what `src/selection-state-cli.ts:39::const normalized`
+// composes. The shell wrote a normalized document to a mktemp file and read
+// five fields back with five python3 invocations; in-process this is one call.
+export async function loadSavedSelection(env) {
+    return normalizeSaved(await readSelectionState(selectionStatePath(env)));
+}
+export const UPSTREAM_URL_DEFAULT = "https://github.com/obra/superpowers";
+// Ports the env > saved > package-default precedence ladder from
+// `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/selection.sh:88-162::spw_compute_effective_selection`.
+// validateSource runs before any ref resolution -- pinned by
+// tests/unit/effective-selection.test.js's "source validation precedes ref
+// resolution": a credential-bearing source must fail before Git is ever
+// invoked.
+export async function computeEffectiveSelection(root, env) {
+    const saved = await loadSavedSelection(env);
+    let upstreamSourceOrigin;
+    let effectiveSource;
+    if (env.SUPERPOWERS_UPSTREAM_URL) {
+        upstreamSourceOrigin = "environment";
+        effectiveSource = env.SUPERPOWERS_UPSTREAM_URL;
+    }
+    else if (saved.saved_mode !== "none") {
+        upstreamSourceOrigin = "user-config";
+        effectiveSource = saved.saved_source;
+    }
+    else {
+        upstreamSourceOrigin = "package-default";
+        effectiveSource = UPSTREAM_URL_DEFAULT;
+    }
+    // Before any Git access. Pinned by tests/unit/effective-selection.test.js's
+    // "source validation precedes ref resolution".
+    validateSource(effectiveSource);
+    let selectionOrigin;
+    let selectionMode;
+    let requestedRef;
+    let usesSavedPin = false;
+    if (env.SUPERPOWERS_REF) {
+        selectionOrigin = "environment";
+        selectionMode = "override";
+        requestedRef = env.SUPERPOWERS_REF;
+    }
+    else if (saved.saved_mode === "pinned") {
+        selectionOrigin = "user-config";
+        selectionMode = "pinned";
+        requestedRef = saved.saved_requested_ref;
+        usesSavedPin = true;
+    }
+    else if (saved.saved_mode === "track-latest") {
+        selectionOrigin = "user-config";
+        selectionMode = "track-latest";
+        requestedRef = "latest-release";
+    }
+    else {
+        selectionOrigin = "package-default";
+        selectionMode = "default";
+        requestedRef = await readConfigRef(root, env);
+    }
+    if (usesSavedPin) {
+        return {
+            selectionOrigin,
+            selectionMode,
+            upstreamSourceOrigin,
+            effectiveSource,
+            requestedRef,
+            resolvedRef: saved.saved_resolved_ref,
+            desiredCommit: saved.saved_commit,
+            resolutionKind: COMMIT_RE.test(saved.saved_requested_ref)
+                ? "raw-commit"
+                : "tag",
+            saved,
+        };
+    }
+    const resolution = await resolveRef(effectiveSource, requestedRef);
+    // `Resolution` (src/upstream.ts) is { kind, ref, commit } — the
+    // resolved ref field is named `ref`, not `resolvedRef`.
+    return {
+        selectionOrigin,
+        selectionMode,
+        upstreamSourceOrigin,
+        effectiveSource,
+        requestedRef,
+        resolvedRef: resolution.ref,
+        desiredCommit: resolution.commit,
+        resolutionKind: resolution.kind,
+        saved,
+    };
+}