superpowers-manager 0.5.2 → 0.7.0

package/dist/python-json.js

@@ -1,29 +1,4 @@
+import { escapeNonAscii } from "./python-json-format.js";
 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;
+    return escapeNonAscii(JSON.stringify(value).slice(1, -1));
 }

package/dist/python-text.js

@@ -1,75 +1,15 @@
-// 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",
-    "
",
-    "
",
-]);
+// Match first through last non-whitespace; avoid suffix retries on internal runs.
 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);
+    return (value.match(
+    // oxlint-disable-next-line no-control-regex -- exact CPython whitespace includes C0 separators.
+    /[^\u0009-\u000d\u001c-\u0020\u0085\u00a0\u1680\u2000-\u200a\u2028-\u2029\u202f\u205f\u3000](?:[\s\S]*[^\u0009-\u000d\u001c-\u0020\u0085\u00a0\u1680\u2000-\u200a\u2028-\u2029\u202f\u205f\u3000])?/)?.[0] ?? "");
 }
+// CRLF is one boundary; a terminating boundary adds no final empty line.
 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));
+    // oxlint-disable-next-line no-control-regex -- CPython boundaries include C0 controls.
+    const lines = value.split(/\r\n|[\n\r\v\f\u001c-\u001e\u0085\u2028\u2029]/);
+    if (lines.at(-1) === "")
+        lines.pop();
     return lines;
 }
 /** Python `sorted()` orders by code point; JavaScript's default sort does not. */

package/dist/safe-path.js

@@ -1,12 +1,12 @@
 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) {
+export function isErrno(value, code) {
     return (value instanceof Error &&
         "code" in value &&
         value.code === code);
 }
-function isContained(root, candidate) {
+export function isContained(root, candidate) {
     const suffix = relative(root, candidate);
     return (suffix === "" ||
         (!isAbsolute(suffix) && suffix !== ".." && !suffix.startsWith(`..${sep}`)));

package/dist/selection-store.js

@@ -1,7 +1,7 @@
 import { constants } from "node:fs";
 import { mkdir, open } from "node:fs/promises";
 import { dirname } from "node:path";
-import { atomicWriteFile, } from "./atomic.js";
+import { atomicWriteFile } from "./atomic.js";
 import { classifyPathNoFollow } from "./safe-path.js";
 import { SafetyError } from "./safety-error.js";
 import { selectionError, serializeRecord, validateRecord, } from "./selection.js";
@@ -132,19 +132,6 @@ async function ensureStateDirectory(path) {
         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.
@@ -160,13 +147,6 @@ export async function writeSelectionState(path, proposed, options = {}) {
         });
     }
     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);
+        throw selectionError(`cannot write selection state: ${causedErrorText(cause)}`, cause);
     }
 }

package/dist/snapshot-package.js

@@ -0,0 +1,78 @@
+import { createHash } from "node:crypto";
+import { lstat } from "node:fs/promises";
+import { join } from "node:path";
+import { addArtifactHashField, digestArtifactTree, readArtifactFile, } from "./artifact-tree.js";
+import { classifyPathNoFollow } from "./safe-path.js";
+import { validateSource } from "./selection.js";
+const OFFICIAL_SOURCES = new Set([
+    "https://github.com/obra/superpowers",
+    "https://github.com/obra/superpowers.git",
+    "ssh://git@github.com/obra/superpowers.git",
+    "git@github.com:obra/superpowers.git",
+]);
+export async function observeSnapshot(root, readReceipt) {
+    const kind = await classifyPathNoFollow(root);
+    if (kind === "missing")
+        return { kind: "absent" };
+    if (kind !== "directory")
+        return { kind: "unverified" };
+    try {
+        const receipt = await readReceipt(root);
+        const digest = await digestArtifactTree(root);
+        return receipt.digest === digest
+            ? { kind: "owned", receipt, digest }
+            : { kind: "unverified" };
+    }
+    catch {
+        return { kind: "unverified" };
+    }
+}
+export function isOfficialSnapshotSource(source) {
+    return OFFICIAL_SOURCES.has(source);
+}
+export function sameSnapshotSource(left, right) {
+    validateSource(left);
+    validateSource(right);
+    return (left === right ||
+        (isOfficialSnapshotSource(left) && isOfficialSnapshotSource(right)));
+}
+// A consistency checksum, not authentication. A coherent manual rewrite of
+// both receipt and bytes remains possible; installed comparison must still use
+// an independently validated candidate.
+export function snapshotReceiptBinding(receipt) {
+    const hash = createHash("sha256");
+    for (const field of [
+        String(receipt.schema),
+        receipt.manager,
+        receipt.harness,
+        receipt.source,
+        receipt.commit,
+        receipt.digest,
+    ])
+        addArtifactHashField(hash, Buffer.from(field));
+    return hash.digest("hex");
+}
+export function requireNoSnapshotDependencies(pkg) {
+    for (const key of [
+        "dependencies",
+        "optionalDependencies",
+        "peerDependencies",
+        "bundleDependencies",
+        "bundledDependencies",
+    ]) {
+        const value = pkg[key];
+        if (value !== undefined &&
+            (value === null ||
+                typeof value !== "object" ||
+                Object.keys(value).length !== 0))
+            throw new Error("runtime dependencies");
+    }
+}
+export async function requireSnapshotBootstrap(root, relativePath, expectedSize, expectedDigest) {
+    const bootstrap = join(root, relativePath);
+    const bytes = await readArtifactFile(root, bootstrap, expectedSize);
+    if ((await lstat(bootstrap)).mode & 0o111 ||
+        bytes.length !== expectedSize ||
+        createHash("sha256").update(bytes).digest("hex") !== expectedDigest)
+        throw new Error("bootstrap implementation");
+}

package/dist/snapshot-prepare.js

@@ -0,0 +1,99 @@
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { failureResult, successResult, } from "./adapter-result.js";
+import { ARTIFACT_RECEIPT, digestArtifactTree } from "./artifact-tree.js";
+import { materializeGitTree } from "./git-tree.js";
+import { classifyPathNoFollow } from "./safe-path.js";
+import { sameSnapshotSource, snapshotReceiptBinding, } from "./snapshot-package.js";
+export function createSnapshotPreparation(b) {
+    const artifactFrom = (root, a) => ({
+        root,
+        commit: a.receipt.commit,
+        identity: a.receipt.digest,
+        compatibility: a.compatibility,
+    });
+    return {
+        async prepareCandidate(input) {
+            try {
+                await materializeGitTree(input.upstreamRoot, input.selection.desiredCommit, input.candidateRoot);
+                const compatibility = await b.assessCompatibility(input.candidateRoot, input.selection);
+                if (compatibility.kind === "unsupported" ||
+                    compatibility.kind === "unknown")
+                    return failureResult("prepare", "unsupported", compatibility.reason, [], []);
+                const digest = await digestArtifactTree(input.candidateRoot);
+                const identity = {
+                    schema: 1,
+                    manager: "superpowers-manager",
+                    harness: b.harness,
+                    source: input.selection.effectiveSource,
+                    commit: input.selection.desiredCommit,
+                    digest,
+                };
+                const receipt = {
+                    ...identity,
+                    binding: snapshotReceiptBinding(identity),
+                    compatibility,
+                };
+                await writeFile(join(input.candidateRoot, ARTIFACT_RECEIPT), JSON.stringify(receipt) + "\n", { flag: "wx" });
+                return successResult("prepare", artifactFrom(input.candidateRoot, { receipt, compatibility }), []);
+            }
+            catch {
+                return failureResult("prepare", "invalid-package", `cannot prepare ${b.label} artifact: ${input.candidateRoot}`, [], []);
+            }
+        },
+        async inspectPrepared(selection, ctx) {
+            const root = b.preparationLocation(ctx).destinationRoot;
+            const unknown = {
+                kind: "unknown",
+                reason: `${b.label} prepared compatibility evidence is missing`,
+            };
+            try {
+                if ((await classifyPathNoFollow(join(root, ARTIFACT_RECEIPT))) ===
+                    "missing")
+                    return successResult("inspect-prepared", {
+                        kind: "needs-prepare",
+                        observedIdentity: "",
+                        compatibility: unknown,
+                    }, []);
+                const assessment = await b.readAssessment(root);
+                const { receipt, compatibility } = assessment;
+                if (receipt.commit !== selection.desiredCommit ||
+                    !sameSnapshotSource(receipt.source, selection.effectiveSource))
+                    return successResult("inspect-prepared", {
+                        kind: "needs-prepare",
+                        observedIdentity: receipt.digest,
+                        compatibility: unknown,
+                    }, []);
+                if (compatibility.kind !== "supported" &&
+                    compatibility.kind !== "experimental")
+                    return successResult("inspect-prepared", {
+                        kind: "needs-prepare",
+                        observedIdentity: receipt.digest,
+                        compatibility,
+                    }, []);
+                return successResult("inspect-prepared", {
+                    kind: "current",
+                    artifact: artifactFrom(root, assessment),
+                    observedIdentity: receipt.digest,
+                    compatibility,
+                }, []);
+            }
+            catch {
+                return failureResult("inspect-prepared", "invalid-package", `cannot inspect ${b.label} prepared artifact: ${root}`, [], []);
+            }
+        },
+        async readPrepared(ctx) {
+            const root = b.preparationLocation(ctx).destinationRoot;
+            try {
+                const assessment = await b.readAssessment(root);
+                if (assessment.compatibility.kind !== "supported" &&
+                    assessment.compatibility.kind !== "experimental")
+                    throw new Error("unsupported profile");
+                return successResult("read-prepared", artifactFrom(root, assessment), []);
+            }
+            catch {
+                return failureResult("read-prepared", "invalid-package", `cannot read ${b.label} prepared artifact: ${root}`, [], []);
+            }
+        },
+    };
+}

package/dist/snapshot-presentation.js

@@ -0,0 +1,44 @@
+export function createSnapshotPresentation(label, renderProbe, wasAbsent) {
+    return {
+        installNotice: "",
+        currentNotice: `The Superpowers ${label} snapshot is current.`,
+        renderProbe,
+        renderInstallVerification(_desired, receipt, inspection) {
+            if (receipt.status !== 0 || !receipt.outcome.ok)
+                return {
+                    stdout: [],
+                    stderr: [
+                        `error: ${label} activation did not return a verified installation receipt`,
+                    ],
+                };
+            if (inspection.status !== 0 || !inspection.outcome.ok)
+                return receipt.outcome.result.missingVerificationOutput;
+            if (inspection.outcome.result.kind === "current")
+                return {
+                    stdout: [
+                        `Installed the frozen Superpowers ${label} snapshot. Restart ${label} to load it.`,
+                    ],
+                    stderr: [],
+                };
+            return inspection.outcome.result.kind === "absent"
+                ? receipt.outcome.result.missingVerificationOutput
+                : receipt.outcome.result.mismatchVerificationOutput;
+        },
+        renderRemovalCompletion(_ownership, input) {
+            return {
+                stdout: [
+                    wasAbsent(input)
+                        ? `No managed Superpowers ${label} installation is present.`
+                        : `Removed the managed Superpowers ${label} installation. Restart ${label} to load the resulting state.`,
+                ],
+                stderr: [],
+            };
+        },
+        callFailure(site) {
+            return {
+                unexpected: `${label} ${site} did not complete`,
+                invalidStatus: `${label} ${site} returned an invalid status`,
+            };
+        },
+    };
+}

package/dist/validator.js

@@ -2,21 +2,16 @@ import { spawn } from "node:child_process";
 import { lstat, realpath, stat } from "node:fs/promises";
 import { sep } from "node:path";
 import { hasTerminalControl, pythonUnicodeEscapeBytes, } from "./adapter-result.js";
-// The legacy SUPERPOWERS_VALIDATOR path. Its behaviour is frozen by parity, so it
-// carries no limits at all; see the spec's D2. Bounding it is PR 12's row.
-export const UNBOUNDED_LEGACY = { kind: "unbounded" };
 // SUPERPOWERS_VALIDATOR_EXECUTABLE. 30s is ~270x a measured realistic validator run
 // (0.11s, dominated by interpreter startup); 64 KiB per stream clears a
 // one-diagnostic-line-per-file report (30 KB on a real tree) with headroom.
 export const BOUNDED_EXECUTABLE = {
-    kind: "bounded",
     timeoutMs: 30_000,
     graceMs: 2_000,
     drainMs: 200,
     maxBytesPerStream: 64 * 1024,
 };
-// Retains the first `limit` bytes and counts the rest. A null limit retains
-// everything, which is the unbounded policy's contract. push() always consumes the
+// Retains the first `limit` bytes and counts the rest. push() always consumes the
 // whole chunk: ceasing to consume would block the child on a full pipe.
 class Sink {
     chunks = [];
@@ -27,10 +22,6 @@ class Sink {
         this.limit = limit;
     }
     push(chunk) {
-        if (this.limit === null) {
-            this.chunks.push(chunk);
-            return;
-        }
         const room = this.limit - this.kept;
         if (room <= 0) {
             this.dropped += chunk.length;
@@ -42,21 +33,15 @@ class Sink {
         this.dropped += chunk.length - take.length;
     }
     done() {
-        // Buffer.toString, NOT TextDecoder: TextDecoder strips a leading BOM and the
-        // legacy path's current string accumulator preserves it. Measured:
-        // decode(<BOM>hi) is "hi" but toString("utf8") is "\ufeffhi". The legacy path
-        // must be byte-identical, so BOTH paths use toString.
+        // Buffer.toString preserves a leading BOM; TextDecoder would strip it.
         return {
             text: Buffer.concat(this.chunks).toString("utf8"),
             droppedBytes: this.dropped,
         };
     }
 }
-// Signal the child's whole process group. Only meaningful for a child spawned
-// under the BOUNDED policy: that spawn passes `detached: true`, so the child
-// leads a group of its own and -pid reaches its descendants. The LEGACY path
-// spawns without `detached`, so its child does not lead a group and this
-// function is not for it. Wrapped because the group is already gone in the
+// Signal the child's whole process group. The child leads a group of its own,
+// so -pid reaches descendants. Wrapped because the group is already gone in
 // ordinary race between SIGTERM and SIGKILL.
 function signalGroup(child, signal) {
     if (child.pid === undefined)
@@ -71,9 +56,8 @@ function signalGroup(child, signal) {
 export function runValidator(argv, policy, env, workspace, cwd) {
     return new Promise((resolveRun) => {
         const [command, ...args] = argv;
-        const limit = policy.kind === "bounded" ? policy.maxBytesPerStream : null;
-        const out = new Sink(limit);
-        const err = new Sink(limit);
+        const out = new Sink(policy.maxBytesPerStream);
+        const err = new Sink(policy.maxBytesPerStream);
         let settled = false;
         // Settlement and termination are independent BY CONSTRUCTION, which is why
         // there is no grace-timer handle to clear here: the timedOut settle is nested
@@ -109,24 +93,22 @@ export function runValidator(argv, policy, env, workspace, cwd) {
         // not an unhandled rejection -- which is what this try/catch prevents.
         let child;
         try {
+            const childEnvironment = policy.inheritEnvironment === false
+                ? { ...env, TMPDIR: workspace }
+                : { ...process.env, ...env, TMPDIR: workspace };
             child = spawn(command, args, {
-                env: { ...process.env, ...env, TMPDIR: workspace },
+                env: childEnvironment,
                 cwd,
                 stdio: ["ignore", "pipe", "pipe"],
-                // D4: under the BOUNDED policy only, the child leads its own process group
-                // so a timeout can signal the GROUP -- signalling the process alone leaves
-                // descendants holding the inherited pipes, and `close` then waits for them
-                // (measured at 5279 ms against a 300 ms timeout). The LEGACY path must not
-                // acquire group leadership: that changes process and session semantics for
-                // a path whose whole contract is that it is unchanged.
-                detached: policy.kind === "bounded",
+                // The child leads its own process group so a timeout can signal the GROUP --
+                // signalling the process alone leaves descendants holding inherited pipes.
+                detached: true,
             });
         }
         catch (cause) {
             settle({
                 kind: "launchFailed",
                 errno: cause.code ?? "UNKNOWN",
-                cause,
             });
             return;
         }
@@ -136,7 +118,7 @@ export function runValidator(argv, policy, env, workspace, cwd) {
         child.stderr.on("data", (chunk) => err.push(chunk));
         // Both error and close fire on a launch failure, so settle() is idempotent.
         child.on("error", (cause) => {
-            settle({ kind: "launchFailed", errno: cause.code ?? "UNKNOWN", cause });
+            settle({ kind: "launchFailed", errno: cause.code ?? "UNKNOWN" });
         });
         child.on("close", (code) => {
             // On the timeout path, settling here would resolve BEFORE SIGKILL and the
@@ -154,12 +136,6 @@ export function runValidator(argv, policy, env, workspace, cwd) {
             // may lag it indefinitely. Capture the code here or a successful validator
             // whose descendant lingers would settle with a null code and be rejected.
             lastCode = code;
-            // BOUNDED ONLY. The legacy path settles on `close`, exactly as it does today:
-            // a validator that backgrounds `(sleep 0.6; echo late) &` has "late" captured
-            // under `close` and lost under a 200 ms drain, and that output is captured
-            // today.
-            if (policy.kind !== "bounded")
-                return;
             // The TIMEOUT path owns its own settlement, after the escalation has run.
             if (timedOut)
                 return;
@@ -186,31 +162,29 @@ export function runValidator(argv, policy, env, workspace, cwd) {
                 });
             }, policy.drainMs);
         });
-        if (policy.kind === "bounded") {
-            timeoutTimer = setTimeout(() => {
-                timedOut = true;
-                // Signal the GROUP, not the process: descendants hold the pipes. SIGTERM
-                // first, because the contract promises stderr carries the reason, and
-                // reading continues through the grace window so the child can print it.
-                signalGroup(child, "SIGTERM");
+        timeoutTimer = setTimeout(() => {
+            timedOut = true;
+            // Signal the GROUP, not the process: descendants hold the pipes. SIGTERM
+            // first, because the contract promises stderr carries the reason, and
+            // reading continues through the grace window so the child can print it.
+            signalGroup(child, "SIGTERM");
+            setTimeout(() => {
+                signalGroup(child, "SIGKILL");
+                // Settle ONLY after SIGKILL has been sent. An earlier revision settled
+                // first and left the escalation on an unref'ed timer, which never fires
+                // because the CLI exits as soon as its handler returns -- measured, the
+                // manager exited at 146 ms and the descendant survived. The wall-clock
+                // bound is therefore timeout + grace + drain, which is still a bound.
                 setTimeout(() => {
-                    signalGroup(child, "SIGKILL");
-                    // Settle ONLY after SIGKILL has been sent. An earlier revision settled
-                    // first and left the escalation on an unref'ed timer, which never fires
-                    // because the CLI exits as soon as its handler returns -- measured, the
-                    // manager exited at 146 ms and the descendant survived. The wall-clock
-                    // bound is therefore timeout + grace + drain, which is still a bound.
-                    setTimeout(() => {
-                        settle({
-                            kind: "timedOut",
-                            afterMs: policy.timeoutMs,
-                            stdout: out.done(),
-                            stderr: err.done(),
-                        });
-                    }, policy.drainMs);
-                }, policy.graceMs);
-            }, policy.timeoutMs);
-        }
+                    settle({
+                        kind: "timedOut",
+                        afterMs: policy.timeoutMs,
+                        stdout: out.done(),
+                        stderr: err.done(),
+                    });
+                }, policy.drainMs);
+            }, policy.graceMs);
+        }, policy.timeoutMs);
     });
 }
 // Every probe below is best-effort BY DESIGN: spawn is the authority on whether the
@@ -297,22 +271,14 @@ const VALIDATOR_COMMANDS = new Set([
     "install",
     "update",
 ]);
-// Legacy emptiness semantics exactly: empty string means unset, whitespace-only
-// counts as set. No trimming — a trim would silently change legacy behaviour.
-export function bothConfigured(env) {
-    return ((env.SUPERPOWERS_VALIDATOR || "").length > 0 &&
-        (env.SUPERPOWERS_VALIDATOR_EXECUTABLE || "").length > 0);
-}
 // The second exported accessor preflight derives its enforcement from. It is an
 // accessor rather than an inline check because an accessor that under-reports what
 // preflight enforces is the blind spot slice 2 closed.
 export function configurationErrors(cmd, env) {
-    if (!VALIDATOR_COMMANDS.has(cmd))
-        return [];
-    if (!bothConfigured(env))
+    if (!VALIDATOR_COMMANDS.has(cmd) || !env.SUPERPOWERS_VALIDATOR)
         return [];
     return [
-        "SUPERPOWERS_VALIDATOR and SUPERPOWERS_VALIDATOR_EXECUTABLE are both set — " +
-            "unset one; the manager never chooses between them silently",
+        "SUPERPOWERS_VALIDATOR has been removed; unset it and configure " +
+            "SUPERPOWERS_VALIDATOR_EXECUTABLE with an executable validator.",
     ];
 }