superpowers-manager 0.2.0 → 0.3.0

package/dist/provenance.js

@@ -0,0 +1,111 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { COMMIT_INPUT_RE } from "./domain/refs.js";
+import { escapePythonJsonString } from "./python-json.js";
+import { SafetyError } from "./safety-error.js";
+import { parseStrictJson, } from "./strict-json.js";
+export const PROVENANCE_STRICT_PROFILE = {
+    duplicateKeys: "last-wins",
+    nonStandardConstants: "reject",
+    maxDepth: 256,
+};
+export const PROVENANCE_LENIENT_PROFILE = {
+    duplicateKeys: "last-wins",
+    nonStandardConstants: "reject",
+};
+export const PROVENANCE_CODEX_SOURCE_PROFILE = {
+    duplicateKeys: "last-wins",
+    nonStandardConstants: "accept",
+};
+function asObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+export async function readStrictProvenanceField(path, dottedKey) {
+    try {
+        const parsed = parseStrictJson(await readFile(path), PROVENANCE_STRICT_PROFILE);
+        let current = parsed;
+        if (asObject(current) === undefined) {
+            throw new SafetyError("provenance", `provenance value must be an object: ${path}`);
+        }
+        for (const part of dottedKey.split(".")) {
+            const object = current === undefined ? undefined : asObject(current);
+            if (object === undefined || !Object.hasOwn(object, part))
+                return undefined;
+            current = object[part];
+        }
+        return current === null ? undefined : current;
+    }
+    catch (cause) {
+        if (cause instanceof SafetyError && cause.module === "provenance") {
+            throw cause;
+        }
+        throw new SafetyError("provenance", `cannot read strict provenance field from ${path}`, { cause });
+    }
+}
+export async function readGeneratedCommitLenient(path) {
+    try {
+        const parsed = parseStrictJson(await readFile(path), PROVENANCE_LENIENT_PROFILE);
+        const object = asObject(parsed);
+        const commit = object?.commit;
+        return typeof commit === "string" && COMMIT_INPUT_RE.test(commit)
+            ? commit
+            : "";
+    }
+    catch {
+        return "";
+    }
+}
+// Ported from
+// `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/lifecycle.sh:28-31::spw_generated_metadata_path(`.
+// The path the generated tree's provenance lives at, relative to a package
+// root.
+export function generatedMetadataPath(root) {
+    return join(root, "plugins", "superpowers", ".superpowers-upstream.json");
+}
+// Ported from
+// `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/lifecycle.sh:33-37::spw_generated_commit_or_empty`.
+// Lenient by design: a missing or malformed generated provenance file yields
+// "", which `statusForCommits` reads as "needs prepare". Aborting here would
+// deny the operator the remediation path.
+export async function generatedCommitOrEmpty(root) {
+    return readGeneratedCommitLenient(generatedMetadataPath(root));
+}
+export async function readCodexBuildSource(path) {
+    try {
+        const parsed = parseStrictJson(await readFile(path), PROVENANCE_CODEX_SOURCE_PROFILE);
+        const source = asObject(parsed)?.source;
+        if (typeof source !== "string" || source.length === 0) {
+            throw new SafetyError("provenance", `invalid Codex source in ${path}`);
+        }
+        return source;
+    }
+    catch (cause) {
+        if (cause instanceof SafetyError && cause.module === "provenance") {
+            throw cause;
+        }
+        throw new SafetyError("provenance", `cannot read Codex source from ${path}`, { cause });
+    }
+}
+const PROVENANCE_KEYS = [
+    "source",
+    "requested_ref",
+    "resolved_ref",
+    "commit",
+    "upstream_manifest_version",
+];
+export function serializeProvenance(record) {
+    const lines = PROVENANCE_KEYS.map((key) => `  "${key}": "${escapePythonJsonString(record[key])}"`);
+    return `{\n${lines.join(",\n")}\n}\n`;
+}
+export async function writeProvenance(path, record) {
+    try {
+        await writeFile(path, serializeProvenance(record), "utf8");
+    }
+    catch (cause) {
+        throw new SafetyError("provenance", `cannot write provenance ${path}`, {
+            cause,
+        });
+    }
+}

package/dist/python-json-format.js

@@ -0,0 +1,83 @@
+import { SafetyError } from "./safety-error.js";
+/**
+ * Render a JSON number token the way CPython's `json.dump` does.
+ *
+ * Classification is by source text, matching CPython's own: a token containing
+ * `.` or `e`/`E` parses as a float, anything else as an arbitrary-width int.
+ * Integers are emitted verbatim so widths above 2^53 survive; `-0` is the only
+ * normalization JSON's grammar leaves room for, since leading zeros and a
+ * leading `+` are already forbidden.
+ */
+export function formatPythonNumber(raw) {
+    if (!/[.eE]/.test(raw)) {
+        // NaN/Infinity/-Infinity contain no `.` or `e`/`E`, so they would
+        // otherwise fall into the "emit verbatim" integer branch and echo back
+        // as invalid JSON. A reader running a non-standard-constants accept
+        // profile (see src/strict-json.ts) can hand this function exactly these
+        // three tokens as a raw number source, so this function must reject them
+        // itself rather than assume its caller already did. CPython's
+        // `json.dump(..., allow_nan=False)` raises ValueError for all three.
+        if (raw === "NaN" || raw === "Infinity" || raw === "-Infinity") {
+            throw new SafetyError("manifest-overlay", `JSON number out of range: ${raw}`);
+        }
+        return raw === "-0" ? "0" : raw;
+    }
+    const value = Number(raw);
+    if (!Number.isFinite(value)) {
+        throw new SafetyError("manifest-overlay", `JSON number out of range: ${raw}`);
+    }
+    return formatPythonFloat(value);
+}
+function formatPythonFloat(value) {
+    // toExponential() drops the sign of negative zero; CPython's repr keeps it.
+    // Note this differs from the integer -0, which normalizes to 0 — consistent,
+    // because -0 has no `.` or `e` and so classifies as an integer.
+    if (Object.is(value, -0))
+        return "-0.0";
+    // Called with no argument, toExponential() yields the shortest digit string
+    // that uniquely identifies the double — the same guarantee CPython's repr
+    // relies on. Taking digits and exponent separately is what lets us apply
+    // CPython's notation threshold instead of JavaScript's.
+    const [mantissa, exponentText] = value.toExponential().split("e");
+    const exponent = Number(exponentText);
+    const negative = mantissa.startsWith("-");
+    const digits = mantissa.replace("-", "").replace(".", "");
+    let body;
+    if (exponent >= -4 && exponent < 16) {
+        // Fixed notation, built by MOVING the decimal point through the digit
+        // string above. Do NOT route this through value.toFixed(): toExponential()
+        // has already produced the shortest digits that identify this double, and
+        // toFixed performs a second, independent rounding of the full decimal
+        // expansion. The two disagree — 1888570120608320.2 formats as
+        // ...320.3 via toFixed and ...320.2 in CPython. Measured 2026-07-31.
+        if (exponent >= digits.length - 1) {
+            body = `${digits}${"0".repeat(exponent - (digits.length - 1))}.0`;
+        }
+        else if (exponent >= 0) {
+            body = `${digits.slice(0, exponent + 1)}.${digits.slice(exponent + 1)}`;
+        }
+        else {
+            body = `0.${"0".repeat(-exponent - 1)}${digits}`;
+        }
+    }
+    else {
+        const sign = exponent < 0 ? "-" : "+";
+        const magnitude = String(Math.abs(exponent)).padStart(2, "0");
+        body = `${mantissa.replace("-", "")}e${sign}${magnitude}`;
+    }
+    return negative ? `-${body}` : body;
+}
+/**
+ * Apply CPython's `ensure_ascii=True` to an already-JSON-encoded string. Input
+ * must be the output of JSON.stringify, which has already escaped quotes,
+ * backslashes, and control characters; this only replaces the remainder.
+ * Astral characters are already surrogate pairs in a JavaScript string, so the
+ * per-code-unit replacement emits the pair CPython emits.
+ *
+ * The range starts at U+007F, not U+0080: CPython escapes DEL while
+ * JSON.stringify leaves it literal, and U+007E is "~" in both. Below U+0020
+ * the two already agree. Measured 2026-07-31.
+ */
+export function escapeNonAscii(text) {
+    return text.replace(/[\u007f-\uffff]/g, (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}

package/dist/python-json.js

@@ -0,0 +1,29 @@
+export function escapePythonJsonString(value) {
+    let escaped = "";
+    const shortEscapes = {
+        0x08: "\\b",
+        0x09: "\\t",
+        0x0a: "\\n",
+        0x0c: "\\f",
+        0x0d: "\\r",
+    };
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code === 0x22) {
+            escaped += '\\"';
+        }
+        else if (code === 0x5c) {
+            escaped += "\\\\";
+        }
+        else if (Object.hasOwn(shortEscapes, code)) {
+            escaped += shortEscapes[code];
+        }
+        else if (code < 0x20 || code >= 0x7f) {
+            escaped += `\\u${code.toString(16).padStart(4, "0")}`;
+        }
+        else {
+            escaped += value[index];
+        }
+    }
+    return escaped;
+}

package/dist/python-text.js

@@ -0,0 +1,74 @@
+// CPython `str.strip()` whitespace, from Unicode's Bidi/White_Space tables as
+// CPython applies them. Deliberately excludes U+FEFF, which JavaScript's
+// `trim()` removes and Python's `strip()` does not.
+const PYTHON_WHITESPACE = new Set([
+    "\t",
+    "\n",
+    "\v",
+    "\f",
+    "\r",
+    " ",
+    "\x1c",
+    "\x1d",
+    "\x1e",
+    "\x1f",
+    "\x85",
+    " ",
+    " ",
+    " ",
+    " ",
+    " ",
+    " ",
+    " ",
+    " ",
+    " ",
+    " ",
+    " ",
+    " ",
+    " ",
+    "
",
+    "
",
+    " ",
+    " ",
+    "　",
+]);
+// CPython `str.splitlines()` boundaries. `\r\n` is handled as a pair below.
+const PYTHON_LINE_BOUNDARIES = new Set([
+    "\n",
+    "\r",
+    "\v",
+    "\f",
+    "\x1c",
+    "\x1d",
+    "\x1e",
+    "\x85",
+    "
",
+    "
",
+]);
+export function pythonStrip(value) {
+    let start = 0;
+    let end = value.length;
+    while (start < end && PYTHON_WHITESPACE.has(value[start]))
+        start += 1;
+    while (end > start && PYTHON_WHITESPACE.has(value[end - 1]))
+        end -= 1;
+    return value.slice(start, end);
+}
+export function pythonSplitlines(value) {
+    const lines = [];
+    let start = 0;
+    let index = 0;
+    while (index < value.length) {
+        const character = value[index];
+        if (!PYTHON_LINE_BOUNDARIES.has(character)) {
+            index += 1;
+            continue;
+        }
+        lines.push(value.slice(start, index));
+        index += character === "\r" && value[index + 1] === "\n" ? 2 : 1;
+        start = index;
+    }
+    if (start < value.length)
+        lines.push(value.slice(start));
+    return lines;
+}

package/dist/safe-path.js

@@ -0,0 +1,137 @@
+import { lstat, readlink, realpath } from "node:fs/promises";
+import { basename, dirname, isAbsolute, relative, resolve, sep, } from "node:path";
+import { SafetyError } from "./safety-error.js";
+function isErrno(value, code) {
+    return (value instanceof Error &&
+        "code" in value &&
+        value.code === code);
+}
+function isContained(root, candidate) {
+    const suffix = relative(root, candidate);
+    return (suffix === "" ||
+        (!isAbsolute(suffix) && suffix !== ".." && !suffix.startsWith(`..${sep}`)));
+}
+function requireContained(root, candidate) {
+    if (!isContained(root, candidate)) {
+        throw new SafetyError("safe-path", `path escapes containment root: ${candidate}`);
+    }
+}
+export async function classifyPathNoFollow(path) {
+    try {
+        const info = await lstat(path);
+        if (info.isSymbolicLink())
+            return "symlink";
+        if (info.isFile())
+            return "regular-file";
+        if (info.isDirectory())
+            return "directory";
+        return "other";
+    }
+    catch (cause) {
+        if (isErrno(cause, "ENOENT"))
+            return "missing";
+        throw new SafetyError("safe-path", `cannot inspect path: ${path}`, {
+            cause,
+        });
+    }
+}
+export async function assertNoFollowType(path, allowed) {
+    const actual = await classifyPathNoFollow(path);
+    if (!allowed.includes(actual)) {
+        throw new SafetyError("safe-path", `path has disallowed type ${actual}: ${path}`);
+    }
+    return actual;
+}
+export async function assertDesignatedParentDirectory(target) {
+    const parent = dirname(resolve(target));
+    const actual = await classifyPathNoFollow(parent);
+    if (actual !== "missing" && actual !== "directory") {
+        throw new SafetyError("safe-path", `designated parent must be a directory without following symlinks: ${parent}`);
+    }
+}
+export async function assertExistingContained(root, candidate) {
+    const lexicalRoot = resolve(root);
+    const lexicalCandidate = resolve(candidate);
+    requireContained(lexicalRoot, lexicalCandidate);
+    try {
+        const [resolvedRoot, resolvedCandidate] = await Promise.all([
+            realpath(lexicalRoot),
+            realpath(lexicalCandidate),
+        ]);
+        requireContained(resolvedRoot, resolvedCandidate);
+        return lexicalCandidate;
+    }
+    catch (cause) {
+        if (cause instanceof SafetyError)
+            throw cause;
+        throw new SafetyError("safe-path", `cannot resolve existing path: ${lexicalCandidate}`, { cause });
+    }
+}
+export async function assertProspectiveContained(root, candidate) {
+    const lexicalRoot = resolve(root);
+    const lexicalCandidate = resolve(candidate);
+    requireContained(lexicalRoot, lexicalCandidate);
+    try {
+        const resolvedRoot = await realpath(lexicalRoot);
+        const missing = [];
+        const visitedCursors = new Set();
+        let cursor = lexicalCandidate;
+        let resolvedAncestor;
+        for (;;) {
+            if (visitedCursors.has(cursor)) {
+                throw new SafetyError("safe-path", `prospective path resolution repeats cursor: ${cursor}`);
+            }
+            visitedCursors.add(cursor);
+            try {
+                resolvedAncestor = await realpath(cursor);
+                break;
+            }
+            catch (cause) {
+                if (!isErrno(cause, "ENOENT"))
+                    throw cause;
+                let symlinkTarget;
+                try {
+                    if ((await lstat(cursor)).isSymbolicLink()) {
+                        symlinkTarget = await readlink(cursor);
+                    }
+                }
+                catch (inspectionCause) {
+                    if (!isErrno(inspectionCause, "ENOENT"))
+                        throw inspectionCause;
+                }
+                if (symlinkTarget !== undefined) {
+                    cursor = resolve(await realpath(dirname(cursor)), symlinkTarget);
+                    continue;
+                }
+                const parent = dirname(cursor);
+                if (parent === cursor)
+                    throw cause;
+                missing.unshift(basename(cursor));
+                cursor = parent;
+            }
+        }
+        const resolvedCandidate = resolve(resolvedAncestor, ...missing);
+        requireContained(resolvedRoot, resolvedCandidate);
+        return lexicalCandidate;
+    }
+    catch (cause) {
+        if (cause instanceof SafetyError)
+            throw cause;
+        throw new SafetyError("safe-path", `cannot resolve prospective path: ${lexicalCandidate}`, { cause });
+    }
+}
+export async function assertSymlinkTargetContained(root, candidate) {
+    await assertNoFollowType(candidate, ["symlink"]);
+    try {
+        const [resolvedRoot, resolvedTarget] = await Promise.all([
+            realpath(resolve(root)),
+            realpath(resolve(candidate)),
+        ]);
+        requireContained(resolvedRoot, resolvedTarget);
+    }
+    catch (cause) {
+        if (cause instanceof SafetyError)
+            throw cause;
+        throw new SafetyError("safe-path", `cannot resolve symlink target: ${candidate}`, { cause });
+    }
+}

package/dist/safety-error.js

@@ -0,0 +1,10 @@
+export class SafetyError extends Error {
+    module;
+    details;
+    constructor(module, message, options = {}) {
+        super(message, { cause: options.cause });
+        this.name = "SafetyError";
+        this.module = module;
+        this.details = options.details;
+    }
+}

package/dist/selection-state-cli.js

@@ -0,0 +1,85 @@
+import { realpathSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { displaySource, normalizePinnedArguments, normalizeSaved, validateSource, } from "./selection.js";
+import { readSelectionState, writeSelectionState } from "./selection-store.js";
+import { oneLine, parseFlags, UsageError } from "./cli-arguments.js";
+const COMMAND_FLAGS = {
+    read: ["path", "output"],
+    "write-pinned": ["path", "source", "requested-ref", "resolved-ref", "commit"],
+    "write-track-latest": ["path", "source"],
+    "validate-source": ["source"],
+    "display-source": ["source"],
+};
+function parseCommand(argv) {
+    const [name, ...rest] = argv;
+    if (name === undefined)
+        throw new UsageError("a subcommand is required");
+    if (!Object.hasOwn(COMMAND_FLAGS, name)) {
+        throw new UsageError(`unknown subcommand: ${name}`);
+    }
+    const command = name;
+    return { name: command, flags: parseFlags(rest, COMMAND_FLAGS[command]) };
+}
+async function dispatch({ name, flags }) {
+    if (name === "read") {
+        const normalized = normalizeSaved(await readSelectionState(flags.path));
+        try {
+            await writeFile(flags.output, `${JSON.stringify(normalized, null, 2)}\n`, "utf8");
+        }
+        catch (cause) {
+            const message = cause instanceof Error ? cause.message : String(cause);
+            throw new Error(`cannot write normalized selection output ${flags.output}: ${message}`, { cause });
+        }
+        return;
+    }
+    if (name === "write-pinned") {
+        await writeSelectionState(flags.path, normalizePinnedArguments({
+            source: flags.source,
+            requestedRef: flags["requested-ref"],
+            resolvedRef: flags["resolved-ref"],
+            commit: flags.commit,
+        }));
+        return;
+    }
+    if (name === "write-track-latest") {
+        await writeSelectionState(flags.path, {
+            schema_version: 1,
+            mode: "track-latest",
+            source: flags.source,
+        });
+        return;
+    }
+    if (name === "validate-source") {
+        validateSource(flags.source);
+        return;
+    }
+    if (name === "display-source") {
+        process.stdout.write(`${displaySource(flags.source)}\n`);
+        return;
+    }
+    const unreachable = name;
+    throw new Error(`unhandled subcommand: ${String(unreachable)}`);
+}
+export async function runSelectionStateCli(argv) {
+    let command;
+    try {
+        command = parseCommand(argv);
+    }
+    catch (cause) {
+        process.stderr.write(`usage: selection-state-cli <subcommand> [options]\n`);
+        process.stderr.write(`error: ${oneLine(cause)}\n`);
+        return 2;
+    }
+    try {
+        await dispatch(command);
+        return 0;
+    }
+    catch (cause) {
+        process.stderr.write(`error: ${oneLine(cause)}\n`);
+        return 1;
+    }
+}
+const entry = process.argv[1];
+if (entry !== undefined && import.meta.filename === realpathSync(entry)) {
+    process.exitCode = await runSelectionStateCli(process.argv.slice(2));
+}