superpowers-manager 0.2.0 → 0.4.0

package/dist/selection-store.js

@@ -0,0 +1,172 @@
+import { constants } from "node:fs";
+import { mkdir, open } from "node:fs/promises";
+import { dirname } from "node:path";
+import { atomicWriteFile, } from "./atomic.js";
+import { classifyPathNoFollow } from "./safe-path.js";
+import { SafetyError } from "./safety-error.js";
+import { selectionError, serializeRecord, validateRecord, } from "./selection.js";
+import { parseStrictJson } from "./strict-json.js";
+const SELECTION_JSON_PROFILE = {
+    duplicateKeys: "reject",
+    nonStandardConstants: "reject",
+    maxDepth: 256,
+    // integerNumbersOnly owns lexical 1.0/1e0 rejection.
+    integerNumbersOnly: true,
+};
+function errorText(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
+function causedErrorText(cause) {
+    return cause instanceof SafetyError && cause.cause !== undefined
+        ? errorText(cause.cause)
+        : errorText(cause);
+}
+async function classify(path, label) {
+    try {
+        return await classifyPathNoFollow(path);
+    }
+    catch (cause) {
+        throw selectionError(`cannot inspect ${label} ${path}: ${causedErrorText(cause)}`, cause);
+    }
+}
+function translateParseFailure(path, text, cause) {
+    if (cause instanceof SafetyError && cause.module === "selection")
+        throw cause;
+    const message = cause instanceof Error ? cause.message : String(cause);
+    if (message.startsWith("container depth exceeds ")) {
+        throw selectionError(`JSON nesting exceeds limit in ${path}`, cause);
+    }
+    const duplicate = /^duplicate object key (".*") at character \d+$/.exec(message);
+    if (duplicate?.[1] !== undefined) {
+        const key = JSON.parse(duplicate[1]);
+        throw selectionError(`duplicate JSON key: ${key}`, cause);
+    }
+    const objectKey = /^object key must be a string at character (\d+)$/.exec(message);
+    if (objectKey?.[1] !== undefined) {
+        const index = Number(objectKey[1]);
+        const prefix = text.slice(0, index);
+        const lines = prefix.split("\n");
+        const line = lines.length;
+        const column = (lines.at(-1)?.length ?? 0) + 1;
+        throw selectionError(`invalid JSON in ${path}: line ${line} column ${column}: Expecting property name enclosed in double quotes`, cause);
+    }
+    throw selectionError(`invalid JSON in ${path}: ${message}`, cause);
+}
+function parseRecordBytes(path, bytes) {
+    let text;
+    try {
+        text = new TextDecoder("utf-8", {
+            fatal: true,
+            ignoreBOM: true,
+        }).decode(bytes);
+    }
+    catch (cause) {
+        throw selectionError(`cannot read selection state ${path}: ${errorText(cause)}`, cause);
+    }
+    try {
+        return validateRecord(parseStrictJson(text, SELECTION_JSON_PROFILE));
+    }
+    catch (cause) {
+        translateParseFailure(path, text, cause);
+    }
+}
+async function readOpenedRecord(path) {
+    let handle;
+    try {
+        const noFollow = typeof constants.O_NOFOLLOW === "number" ? constants.O_NOFOLLOW : 0;
+        handle = await open(path, constants.O_RDONLY | noFollow);
+        if (!(await handle.stat()).isFile()) {
+            throw selectionError(`selection state must be a regular file: ${path}`);
+        }
+        return parseRecordBytes(path, await handle.readFile());
+    }
+    catch (cause) {
+        if (cause instanceof SafetyError && cause.module === "selection") {
+            throw cause;
+        }
+        throw selectionError(`cannot read selection state ${path}: ${errorText(cause)}`, cause);
+    }
+    finally {
+        await handle?.close().catch(() => { });
+    }
+}
+async function classifyStateDirectory(path) {
+    const current = await classify(path, "selection state directory");
+    if (current === "symlink") {
+        throw selectionError(`selection state directory must not be a symlink: ${path}`);
+    }
+    if (current !== "missing" && current !== "directory") {
+        throw selectionError(`selection state directory must be a directory: ${path}`);
+    }
+    return current;
+}
+export async function readSelectionState(path) {
+    const parent = dirname(path);
+    await classifyStateDirectory(parent);
+    const targetType = await classify(path, "selection state");
+    if (targetType === "missing")
+        return null;
+    if (targetType === "symlink") {
+        throw selectionError(`selection state must not be a symlink: ${path}`);
+    }
+    if (targetType !== "regular-file") {
+        throw selectionError(`selection state must be a regular file: ${path}`);
+    }
+    return readOpenedRecord(path);
+}
+async function ensureStateDirectory(path) {
+    if ((await classifyStateDirectory(path)) !== "missing")
+        return;
+    const previousUmask = process.umask(0o077);
+    try {
+        await mkdir(path, { recursive: true, mode: 0o700 });
+    }
+    catch (cause) {
+        throw selectionError(`cannot create selection state directory ${path}: ${errorText(cause)}`, cause);
+    }
+    finally {
+        process.umask(previousUmask);
+    }
+    const created = await classify(path, "selection state directory");
+    if (created !== "directory") {
+        throw selectionError(`selection state directory is not usable: ${path}`);
+    }
+}
+async function finalStateDiagnostic(path, finalBytes) {
+    try {
+        const record = finalBytes === undefined
+            ? await readSelectionState(path)
+            : parseRecordBytes(path, finalBytes);
+        return record === null
+            ? "selection state is now absent"
+            : `selection state is now ${record.mode}`;
+    }
+    catch (cause) {
+        return `final selection state cannot be validated: ${errorText(cause)}`;
+    }
+}
+export async function writeSelectionState(path, proposed, options = {}) {
+    await ensureStateDirectory(dirname(path));
+    // Invalid existing state must block overwrite.
+    await readSelectionState(path);
+    const record = validateRecord(proposed);
+    const bytes = new TextEncoder().encode(serializeRecord(record));
+    try {
+        await atomicWriteFile(path, bytes, {
+            hooks: options.hooks,
+            validate: async (temporary) => {
+                await readOpenedRecord(temporary);
+            },
+        });
+    }
+    catch (cause) {
+        const details = cause instanceof SafetyError && cause.module === "atomic"
+            ? cause.details
+            : undefined;
+        if (details?.phase !== "post-replacement") {
+            throw selectionError(`cannot write selection state: ${causedErrorText(cause)}`, cause);
+        }
+        const diagnostic = await finalStateDiagnostic(path, details.finalBytes);
+        throw selectionError(`cannot complete selection state write: ${causedErrorText(cause)}; ${diagnostic}`, cause);
+    }
+}

package/dist/selection.js

@@ -0,0 +1,200 @@
+import { isIP } from "node:net";
+import { COMMIT_RE, TAG_RE, normalizeCommitInput } from "./domain/refs.js";
+import { escapePythonJsonString } from "./python-json.js";
+import { SafetyError } from "./safety-error.js";
+export function selectionError(message, cause) {
+    return new SafetyError("selection", message, { cause });
+}
+function requireObject(raw, label) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw selectionError(`${label} must be a JSON object`);
+    }
+    return raw;
+}
+function requireExactKeys(record, expected) {
+    const expectedSet = new Set(expected);
+    const actual = Object.keys(record);
+    const missing = expected.filter((key) => !Object.hasOwn(record, key)).sort();
+    const unknown = actual.filter((key) => !expectedSet.has(key)).sort();
+    if (missing.length === 0 && unknown.length === 0)
+        return;
+    const details = [];
+    if (missing.length > 0)
+        details.push(`missing ${missing.join(", ")}`);
+    if (unknown.length > 0)
+        details.push(`unknown ${unknown.join(", ")}`);
+    throw selectionError(`selection state keys are invalid: ${details.join("; ")}`);
+}
+function requireSingleLineString(value, label) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.includes("\r") ||
+        value.includes("\n") ||
+        value.includes("\0")) {
+        throw selectionError(`${label} must be a non-empty single-line string`);
+    }
+    return value;
+}
+// Bounded CPython urllib.parse bracket/NFKC emulation preserves version compatibility.
+function bracketedHostIsInvalid(host) {
+    if (host.startsWith("v"))
+        return !/^v[0-9A-Fa-f]+\..+$/.test(host);
+    return isIP(host) !== 6;
+}
+function authorityHasMalformedBrackets(authority) {
+    const hasOpening = authority.includes("[");
+    const hasClosing = authority.includes("]");
+    if (hasOpening !== hasClosing)
+        return true;
+    if (!hasOpening)
+        return false;
+    const hostPort = authority.slice(authority.lastIndexOf("@") + 1);
+    const opening = hostPort.indexOf("[");
+    let host;
+    if (opening !== -1) {
+        if (opening !== 0)
+            return true;
+        const bracketed = hostPort.slice(1);
+        const closing = bracketed.indexOf("]");
+        host = closing === -1 ? bracketed : bracketed.slice(0, closing);
+        const suffix = closing === -1 ? "" : bracketed.slice(closing + 1);
+        if (suffix !== "" && !suffix.startsWith(":"))
+            return true;
+    }
+    else {
+        host = hostPort.split(":", 1)[0];
+    }
+    return bracketedHostIsInvalid(host);
+}
+function authorityFailsNfkc(authority) {
+    const checked = authority.replace(/[@:#?]/g, "");
+    const normalized = checked.normalize("NFKC");
+    return normalized !== checked && /[/?#@:]/.test(normalized);
+}
+export function validateSource(raw) {
+    const source = requireSingleLineString(raw, "source");
+    let leadingWhitespaceEnd = 0;
+    while (leadingWhitespaceEnd < source.length &&
+        source.charCodeAt(leadingWhitespaceEnd) <= 0x20) {
+        leadingWhitespaceEnd += 1;
+    }
+    const parsed = source.slice(leadingWhitespaceEnd).replaceAll("\t", "");
+    const schemeMatch = /^([A-Za-z][A-Za-z0-9+.-]*):(.*)$/s.exec(parsed);
+    const scheme = schemeMatch?.[1]?.toLowerCase() ?? "";
+    const remainder = schemeMatch?.[2] ?? parsed;
+    let authority = "";
+    if (remainder.startsWith("//")) {
+        authority = remainder.slice(2).split(/[/?#]/, 1)[0];
+    }
+    if (authorityHasMalformedBrackets(authority) ||
+        authorityFailsNfkc(authority)) {
+        throw selectionError("source URL is malformed");
+    }
+    if ((scheme === "http" || scheme === "https") && authority.includes("@")) {
+        throw selectionError("HTTP(S) source must not include userinfo");
+    }
+    return source;
+}
+export function displaySource(raw) {
+    try {
+        return validateSource(raw);
+    }
+    catch (cause) {
+        if (!(cause instanceof SafetyError) || cause.module !== "selection") {
+            throw cause;
+        }
+        return "<redacted-source>";
+    }
+}
+function validatePinnedRecord(record, source) {
+    const requestedRef = requireSingleLineString(record.requested_ref, "requested_ref");
+    const resolvedRef = requireSingleLineString(record.resolved_ref, "resolved_ref");
+    const commit = requireSingleLineString(record.commit, "commit");
+    if (!COMMIT_RE.test(commit)) {
+        throw selectionError("commit must be a lowercase 40-hex value");
+    }
+    if (TAG_RE.test(requestedRef)) {
+        if (resolvedRef !== requestedRef) {
+            throw selectionError("tag resolved_ref must equal requested_ref");
+        }
+    }
+    else if (COMMIT_RE.test(requestedRef)) {
+        if (resolvedRef !== requestedRef || commit !== requestedRef) {
+            throw selectionError("raw commit requested_ref, resolved_ref, and commit must be equal");
+        }
+    }
+    else {
+        throw selectionError("requested_ref must be an exact tag or full commit");
+    }
+    return {
+        schema_version: 1,
+        mode: "pinned",
+        source,
+        requested_ref: requestedRef,
+        resolved_ref: resolvedRef,
+        commit,
+    };
+}
+export function validateRecord(raw) {
+    const record = requireObject(raw, "selection state");
+    if (record.schema_version !== 1) {
+        throw selectionError("schema_version must equal integer 1");
+    }
+    if (record.mode === "track-latest") {
+        requireExactKeys(record, ["schema_version", "mode", "source"]);
+        return {
+            schema_version: 1,
+            mode: "track-latest",
+            source: validateSource(record.source),
+        };
+    }
+    if (record.mode === "pinned") {
+        requireExactKeys(record, [
+            "schema_version",
+            "mode",
+            "source",
+            "requested_ref",
+            "resolved_ref",
+            "commit",
+        ]);
+        return validatePinnedRecord(record, validateSource(record.source));
+    }
+    throw selectionError("mode must be pinned or track-latest");
+}
+export function normalizeSaved(record) {
+    if (record === null) {
+        return {
+            saved_mode: "none",
+            saved_source: "",
+            saved_requested_ref: "",
+            saved_resolved_ref: "",
+            saved_commit: "",
+        };
+    }
+    return {
+        saved_mode: record.mode,
+        saved_source: record.source,
+        saved_requested_ref: record.mode === "pinned" ? record.requested_ref : "",
+        saved_resolved_ref: record.mode === "pinned" ? record.resolved_ref : "",
+        saved_commit: record.mode === "pinned" ? record.commit : "",
+    };
+}
+export function normalizePinnedArguments(arguments_) {
+    const requestedRef = normalizeCommitInput(arguments_.requestedRef) ?? arguments_.requestedRef;
+    const resolvedRef = normalizeCommitInput(arguments_.resolvedRef) ?? arguments_.resolvedRef;
+    const commit = arguments_.commit.toLowerCase();
+    return {
+        schema_version: 1,
+        mode: "pinned",
+        source: arguments_.source,
+        requested_ref: requestedRef,
+        resolved_ref: resolvedRef,
+        commit,
+    };
+}
+export function serializeRecord(record) {
+    if (record.mode === "track-latest") {
+        return `{\n  "schema_version": 1,\n  "mode": "track-latest",\n  "source": "${escapePythonJsonString(record.source)}"\n}\n`;
+    }
+    return `{\n  "schema_version": 1,\n  "mode": "pinned",\n  "source": "${escapePythonJsonString(record.source)}",\n  "requested_ref": "${escapePythonJsonString(record.requested_ref)}",\n  "resolved_ref": "${escapePythonJsonString(record.resolved_ref)}",\n  "commit": "${escapePythonJsonString(record.commit)}"\n}\n`;
+}

package/dist/status.js

@@ -0,0 +1,24 @@
+// Ports scripts/core/status.sh in full. Both functions are pure: no I/O, no
+// environment. The three status strings are operator-facing and frozen.
+// `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/status.sh:4-9::spw_commit_matches(`.
+// The `[ -n "$observed" ]` guard comes first and is load-bearing: an empty
+// observed commit must never match, or an absent generated tree reads as
+// current.
+export function commitMatches(desired, observed) {
+    if (observed.length === 0)
+        return false;
+    return observed === desired || observed === desired.slice(0, 7);
+}
+// `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/status.sh:11-27::spw_status_for_commits`.
+// Branch order is part of the contract: a stale generated tree outranks a null
+// installed fingerprint, so the operator is told to prepare before being told
+// to install.
+export function statusForCommits(desired, generated, installed) {
+    if (generated.length === 0 || !commitMatches(desired, generated)) {
+        return "needs prepare";
+    }
+    if (installed.length === 0 || !commitMatches(desired, installed)) {
+        return "needs install";
+    }
+    return "current";
+}

package/dist/strict-json.js

@@ -0,0 +1,248 @@
+import { Buffer } from "node:buffer";
+import { SafetyError } from "./safety-error.js";
+// Module-private brands. JSON object keys are always strings, so no parsed
+// input can produce a symbol-keyed property — these are unforgeable by
+// construction rather than by convention. A structural check such as
+// `typeof value.rawNumber === "string"` is NOT equivalent: the ordinary
+// upstream input {"future":{"rawNumber":"123"}} satisfies it and would be
+// re-emitted as a bare number, corrupting a field AGENTS.md requires
+// preserving.
+const RAW_NUMBER = Symbol("strict-json.rawNumber");
+const RAW_OBJECT = Symbol("strict-json.rawObject");
+export function isRawNumber(value) {
+    return typeof value === "object" && value !== null && RAW_NUMBER in value;
+}
+export function isRawObject(value) {
+    return typeof value === "object" && value !== null && RAW_OBJECT in value;
+}
+const VALUE_BUILDER = {
+    number: (token) => Number(token),
+    object: (entries) => Object.fromEntries(entries),
+};
+const RAW_BUILDER = {
+    number: (token) => ({ [RAW_NUMBER]: true, source: token }),
+    object: (entries) => ({ [RAW_OBJECT]: true, entries }),
+};
+export function parseStrictJson(input, profile) {
+    return parseWith(input, profile, VALUE_BUILDER);
+}
+export function parseStrictJsonPreservingNumbers(input, profile) {
+    return parseWith(input, profile, RAW_BUILDER);
+}
+function parseWith(input, profile, builder) {
+    const byteLength = typeof input === "string"
+        ? Buffer.byteLength(input, "utf8")
+        : input.byteLength;
+    if (profile.maxBytes !== undefined && byteLength > profile.maxBytes) {
+        throw new SafetyError("strict-json", `input exceeds ${profile.maxBytes} UTF-8 bytes`);
+    }
+    let text;
+    try {
+        text =
+            typeof input === "string"
+                ? input
+                : new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(input);
+    }
+    catch (cause) {
+        throw new SafetyError("strict-json", "input is not valid UTF-8", { cause });
+    }
+    try {
+        return new Parser(text, profile, builder).parse();
+    }
+    catch (cause) {
+        if (cause instanceof SafetyError)
+            throw cause;
+        throw new SafetyError("strict-json", "JSON parsing failed", { cause });
+    }
+}
+class Parser {
+    index = 0;
+    text;
+    profile;
+    builder;
+    constructor(text, profile, builder) {
+        this.text = text;
+        this.profile = profile;
+        this.builder = builder;
+    }
+    parse() {
+        this.skipWhitespace();
+        const value = this.parseValue(0);
+        this.skipWhitespace();
+        if (this.index !== this.text.length)
+            this.fail("unexpected trailing input");
+        return value;
+    }
+    parseValue(depth) {
+        if (this.text.startsWith("NaN", this.index)) {
+            return this.parseNonStandardConstant("NaN");
+        }
+        if (this.text.startsWith("Infinity", this.index)) {
+            return this.parseNonStandardConstant("Infinity");
+        }
+        if (this.text.startsWith("-Infinity", this.index)) {
+            return this.parseNonStandardConstant("-Infinity");
+        }
+        const token = this.text[this.index];
+        if (token === "{")
+            return this.parseObject(depth + 1);
+        if (token === "[")
+            return this.parseArray(depth + 1);
+        if (token === '"')
+            return this.parseString();
+        if (token === "t")
+            return this.parseLiteral("true", true);
+        if (token === "f")
+            return this.parseLiteral("false", false);
+        if (token === "n")
+            return this.parseLiteral("null", null);
+        return this.parseNumber();
+    }
+    checkDepth(depth) {
+        if (this.profile.maxDepth !== undefined && depth > this.profile.maxDepth) {
+            this.fail(`container depth exceeds ${this.profile.maxDepth}`);
+        }
+    }
+    parseObject(depth) {
+        this.checkDepth(depth);
+        this.index += 1;
+        const entries = [];
+        const seen = new Map();
+        this.skipWhitespace();
+        if (this.take("}"))
+            return this.builder.object(entries);
+        for (;;) {
+            if (this.text[this.index] !== '"')
+                this.fail("object key must be a string");
+            const key = this.parseString();
+            this.skipWhitespace();
+            if (!this.take(":"))
+                this.fail("expected ':' after object key");
+            this.skipWhitespace();
+            const value = this.parseValue(depth);
+            const previous = seen.get(key);
+            if (previous === undefined) {
+                seen.set(key, entries.length);
+                entries.push([key, value]);
+            }
+            else if (this.profile.duplicateKeys === "reject") {
+                this.fail(`duplicate object key ${JSON.stringify(key)}`);
+            }
+            else {
+                // Last value wins AT THE FIRST KEY'S POSITION. Verified against
+                // CPython 2026-07-31: json.loads('{"a":1,"b":2,"a":3}') reserializes
+                // as {"a": 3, "b": 2} — the dict keeps the original slot. Pushing a
+                // new entry instead would satisfy tests/unit/strict-json.test.js's
+                // "last-wins replaces in place, keeping the first key's position"
+                // while silently reordering the output.
+                entries[previous] = [key, value];
+            }
+            this.skipWhitespace();
+            if (this.take("}"))
+                return this.builder.object(entries);
+            if (!this.take(","))
+                this.fail("expected ',' or '}'");
+            this.skipWhitespace();
+        }
+    }
+    parseArray(depth) {
+        this.checkDepth(depth);
+        this.index += 1;
+        const result = [];
+        this.skipWhitespace();
+        if (this.take("]"))
+            return result;
+        for (;;) {
+            result.push(this.parseValue(depth));
+            this.skipWhitespace();
+            if (this.take("]"))
+                return result;
+            if (!this.take(","))
+                this.fail("expected ',' or ']'");
+            this.skipWhitespace();
+        }
+    }
+    parseString() {
+        this.index += 1;
+        let result = "";
+        while (this.index < this.text.length) {
+            const character = this.text[this.index];
+            this.index += 1;
+            if (character === '"')
+                return result;
+            if (character === "\\") {
+                const escape = this.text[this.index];
+                this.index += 1;
+                const short = {
+                    '"': '"',
+                    "\\": "\\",
+                    "/": "/",
+                    b: "\b",
+                    f: "\f",
+                    n: "\n",
+                    r: "\r",
+                    t: "\t",
+                };
+                if (escape !== undefined && Object.hasOwn(short, escape)) {
+                    result += short[escape];
+                    continue;
+                }
+                if (escape === "u") {
+                    const hex = this.text.slice(this.index, this.index + 4);
+                    if (!/^[0-9A-Fa-f]{4}$/.test(hex))
+                        this.fail("invalid Unicode escape");
+                    result += String.fromCharCode(Number.parseInt(hex, 16));
+                    this.index += 4;
+                    continue;
+                }
+                this.fail("invalid string escape");
+            }
+            if (character.charCodeAt(0) < 0x20) {
+                this.fail("unescaped control character in string");
+            }
+            result += character;
+        }
+        this.fail("unterminated string");
+    }
+    parseNumber() {
+        const match = /^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?/.exec(this.text.slice(this.index));
+        if (match === null)
+            this.fail("expected JSON value");
+        const token = match[0];
+        this.index += token.length;
+        if (this.profile.integerNumbersOnly === true && /[.eE]/.test(token)) {
+            this.fail("non-integer JSON number");
+        }
+        return this.builder.number(token);
+    }
+    parseLiteral(literal, value) {
+        if (!this.text.startsWith(literal, this.index))
+            this.fail("invalid literal");
+        this.index += literal.length;
+        return value;
+    }
+    parseNonStandardConstant(token) {
+        if (this.profile.nonStandardConstants === "reject") {
+            this.fail(`non-standard JSON constant ${token}`);
+        }
+        this.index += token.length;
+        return this.builder.number(token);
+    }
+    skipWhitespace() {
+        while (this.text[this.index] === " " ||
+            this.text[this.index] === "\n" ||
+            this.text[this.index] === "\r" ||
+            this.text[this.index] === "\t") {
+            this.index += 1;
+        }
+    }
+    take(character) {
+        if (this.text[this.index] !== character)
+            return false;
+        this.index += 1;
+        return true;
+    }
+    fail(message) {
+        throw new SafetyError("strict-json", `${message} at character ${this.index}`);
+    }
+}