superpowers-manager 0.7.3 → 0.9.0

package/dist/snapshot-package.js

@@ -1,8 +1,10 @@
 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 { ARTIFACT_DIGEST_RE, ARTIFACT_RECEIPT, addArtifactHashField, digestArtifactTree, readArtifactFile, readArtifactObject, } from "./artifact-tree.js";
+import { COMMIT_RE } from "./domain/refs.js";
 import { classifyPathNoFollow } from "./safe-path.js";
+import { SafetyError } from "./safety-error.js";
 import { validateSource } from "./selection.js";
 const OFFICIAL_SOURCES = new Set([
     "https://github.com/obra/superpowers",
@@ -76,3 +78,62 @@ export async function requireSnapshotBootstrap(root, relativePath, expectedSize,
         createHash("sha256").update(bytes).digest("hex") !== expectedDigest)
         throw new Error("bootstrap implementation");
 }
+// strictGeneration=false admits a generation on unknown/unsupported
+// compatibility. Only Pi passes false: its readers keep that recorded policy
+// (tests/unit/harnesses/pi/package.test.ts, "receipt readers retain their
+// distinct unsupported-generation policy").
+function isReceiptCompatibility(value, strictGeneration) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const compatibility = value;
+    if (typeof compatibility.reason !== "string")
+        return false;
+    if (compatibility.kind === "supported" ||
+        compatibility.kind === "experimental")
+        return typeof compatibility.generation === "string";
+    return ((compatibility.kind === "unknown" ||
+        compatibility.kind === "unsupported") &&
+        (!strictGeneration || compatibility.generation === undefined));
+}
+export function createSnapshotReceipts(rules) {
+    const module = `${rules.harness}-package`;
+    async function readReceipt(root) {
+        const path = join(root, ARTIFACT_RECEIPT);
+        try {
+            const value = await readArtifactObject(root, path);
+            if (value.schema !== 1 ||
+                value.manager !== "superpowers-manager" ||
+                value.harness !== rules.harness ||
+                typeof value.source !== "string" ||
+                typeof value.commit !== "string" ||
+                !COMMIT_RE.test(value.commit) ||
+                typeof value.digest !== "string" ||
+                !ARTIFACT_DIGEST_RE.test(value.digest) ||
+                typeof value.binding !== "string" ||
+                !ARTIFACT_DIGEST_RE.test(value.binding))
+                throw new Error("receipt fields");
+            validateSource(value.source);
+            if (snapshotReceiptBinding(value) !==
+                value.binding)
+                throw new Error("receipt binding");
+            if (!isReceiptCompatibility(value.compatibility, rules.strictGeneration))
+                throw new Error("receipt compatibility");
+            return value;
+        }
+        catch (cause) {
+            throw new SafetyError(module, `invalid ${rules.label} artifact receipt: ${path}`, { cause });
+        }
+    }
+    async function readAssessment(root) {
+        const receipt = await readReceipt(root);
+        if ((await digestArtifactTree(root)) !== receipt.digest)
+            throw new SafetyError(module, `${rules.label} artifact digest mismatch: ${root}`);
+        return {
+            receipt,
+            compatibility: await rules.assessCompatibility(root, {
+                effectiveSource: receipt.source,
+            }),
+        };
+    }
+    return { readReceipt, readAssessment };
+}

package/dist/snapshot-prepare.js

@@ -6,6 +6,10 @@ import { materializeGitTree } from "./git-tree.js";
 import { classifyPathNoFollow } from "./safe-path.js";
 import { sameSnapshotSource, snapshotReceiptBinding, } from "./snapshot-package.js";
 export function createSnapshotPreparation(b) {
+    const preparationLocation = (ctx) => ({
+        destinationRoot: b.paths(ctx.env ?? {}, process.cwd()).preparedRoot,
+        stagingLeaf: "superpowers",
+    });
     const artifactFrom = (root, a) => ({
         root,
         commit: a.receipt.commit,
@@ -13,6 +17,7 @@ export function createSnapshotPreparation(b) {
         compatibility: a.compatibility,
     });
     return {
+        preparationLocation,
         async prepareCandidate(input) {
             try {
                 await materializeGitTree(input.upstreamRoot, input.selection.desiredCommit, input.candidateRoot);
@@ -20,6 +25,8 @@ export function createSnapshotPreparation(b) {
                 if (compatibility.kind === "unsupported" ||
                     compatibility.kind === "unknown")
                     return failureResult("prepare", "unsupported", compatibility.reason, [], []);
+                if (b.rewrite !== undefined)
+                    await b.rewrite(input.candidateRoot, input.selection);
                 const digest = await digestArtifactTree(input.candidateRoot);
                 const identity = {
                     schema: 1,
@@ -42,7 +49,7 @@ export function createSnapshotPreparation(b) {
             }
         },
         async inspectPrepared(selection, ctx) {
-            const root = b.preparationLocation(ctx).destinationRoot;
+            const root = preparationLocation(ctx).destinationRoot;
             const unknown = {
                 kind: "unknown",
                 reason: `${b.label} prepared compatibility evidence is missing`,
@@ -83,7 +90,7 @@ export function createSnapshotPreparation(b) {
             }
         },
         async readPrepared(ctx) {
-            const root = b.preparationLocation(ctx).destinationRoot;
+            const root = preparationLocation(ctx).destinationRoot;
             try {
                 const assessment = await b.readAssessment(root);
                 if (assessment.compatibility.kind !== "supported" &&

package/dist/snapshot-presentation.js

@@ -42,3 +42,12 @@ export function createSnapshotPresentation(label, renderProbe, wasAbsent) {
         },
     };
 }
+// Each harness chooses its fields and applies its own escaping before calling.
+export function probeOutput(fields) {
+    return {
+        human: fields
+            .map(([key, value]) => `${key.replaceAll("_", " ")}: ${value || "not present"}\n`)
+            .join(""),
+        porcelain: fields.map(([key, value]) => `${key}=${value}\n`).join(""),
+    };
+}

package/dist/upstream.js

@@ -1,8 +1,9 @@
-import { readFile, stat } from "node:fs/promises";
-import { join } from "node:path";
+import { readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
 import { COMMIT_INPUT_RE, compareStable, parseStableTag, } from "./domain/refs.js";
 import { runGit } from "./git.js";
 import { SafetyError } from "./safety-error.js";
+import { isDirectory } from "./safe-path.js";
 import { displaySource } from "./selection.js";
 import { withWorkspace } from "./workspace.js";
 const UNAVAILABLE_OBJECT_RE = /not our ref|unadvertised object|couldn't find remote ref/;
@@ -35,16 +36,6 @@ function failed(result) {
 function combined(result) {
     return `${result.stdout}${result.stderr}`.replace(/\n+$/, "");
 }
-// Mirrors `[ -d "$repository/.git" ]`: a regular file, a broken symlink, or
-// an unreadable path is *not* a directory, so the cache is re-initialized.
-async function isDirectory(path) {
-    try {
-        return (await stat(path)).isDirectory();
-    }
-    catch {
-        return false;
-    }
-}
 export function parseLsRemote(output) {
     const entries = [];
     for (const line of output.split("\n")) {
@@ -251,3 +242,8 @@ export async function fetchExactCommit(source, commit, repository, workspacePare
         }
     });
 }
+// An explicit relative SUPERPOWERS_CACHE_DIR resolves against the
+// invocation's working directory.
+export function upstreamCacheRoot(root, env) {
+    return resolve(env.SUPERPOWERS_CACHE_DIR || join(root, ".cache", "upstream"), "superpowers");
+}

package/dist/validator.js

@@ -198,14 +198,21 @@ export async function resolveValidator(configured) {
     // runs whatever PATH selects -- the same divergence that makes realpath unsafe
     // here.
     const pathLike = configured.includes(sep);
+    if (!pathLike) {
+        return {
+            configured,
+            resolved: null,
+            isSymlink: false,
+            isDirectory: false,
+            exists: false,
+        };
+    }
     let isSymlink = false;
-    if (pathLike) {
-        try {
-            isSymlink = (await lstat(configured)).isSymbolicLink();
-        }
-        catch {
-            /* spawn reports the real reason */
-        }
+    try {
+        isSymlink = (await lstat(configured)).isSymbolicLink();
+    }
+    catch {
+        /* spawn reports the real reason */
     }
     // Resolve ONLY when the configured value contains a path separator -- which is
     // exactly when spawn bypasses PATH and the two agree about the target. For a
@@ -214,25 +221,21 @@ export async function resolveValidator(configured) {
     // interpreter and spawn("node") ran another. Resolving a bare name would let the
     // manager confidently disclose a file it is not about to run.
     let resolved = null;
-    if (configured.includes(sep)) {
-        try {
-            resolved = await realpath(configured);
-        }
-        catch {
-            /* unresolvable; stays null and is never claimed */
-        }
+    try {
+        resolved = await realpath(configured);
+    }
+    catch {
+        /* unresolvable; stays null and is never claimed */
     }
     let isDirectory = false;
     let exists = false;
-    if (pathLike) {
-        try {
-            const s = await stat(configured);
-            isDirectory = s.isDirectory();
-            exists = true;
-        }
-        catch {
-            /* spawn reports the real reason */
-        }
+    try {
+        const s = await stat(configured);
+        isDirectory = s.isDirectory();
+        exists = true;
+    }
+    catch {
+        /* spawn reports the real reason */
     }
     return { configured, resolved, isSymlink, isDirectory, exists };
 }

package/dist/workspace.js

@@ -3,17 +3,11 @@ import { mkdtemp, rm } from "node:fs/promises";
 import { join } from "node:path";
 import { SafetyError } from "./safety-error.js";
 const MANAGED_SIGNALS = ["SIGHUP", "SIGINT", "SIGTERM"];
-// Each active workspace carries its caller's failure reporter. The signal
-// path still invokes it, for parity with the normal path, but a signal death
-// never builds a result outcome (see src/adapter-result.ts), so a report
-// that only lands in the adapter's buffered log would never become
-// observable — the signal path therefore also writes the hand-written
-// diagnostic straight to process.stderr, unconditionally; that raw write is
-// the only thing actually visible to a caller. Previously the signal path
-// called the module-private cleanup and swallowed the rejection in
-// Promise.allSettled, so a signal-time failure was silent entirely — this is
-// the state PR 11.4 removed from the normal path.
-const active = new Map();
+// Workspaces the signal path must remove. A signal death never builds a
+// result outcome (see src/adapter-result.ts), so the signal path writes its
+// hand-written diagnostic straight to process.stderr; that write is the only
+// report a caller can observe.
+const active = new Set();
 let exiting = false;
 const handlers = new Map();
 // One phrasing for one condition. The adapter re-emits this for a suppressed
@@ -40,29 +34,18 @@ function cleanupForSignal(signal) {
     if (exiting)
         return;
     exiting = true;
-    for (const [path, report] of active) {
+    for (const path of active) {
         try {
             rmSync(path, { recursive: true, force: true });
         }
         catch {
-            // The reporter is invoked for parity with the normal path, but nothing
-            // ever reads it back here — no outcome is built before the process
-            // dies — so the diagnostic is also written straight to stderr,
-            // unconditionally; that write is the only thing actually observable.
             // The diagnostic is hand-written and names the workspace; the caught
-            // cause is not interpolated.
-            //
-            // Reporting is guarded: if either call throws — plausibly EPIPE after
-            // SIGHUP, when the process on the other end of the pipe is already
-            // gone — the exception must not escape this loop, or the remaining
-            // workspaces' cleanup, deregistration, and the re-raise below never run.
+            // cause is not interpolated. Guarded: if the write throws — plausibly
+            // EPIPE after SIGHUP — the remaining workspaces' cleanup,
+            // deregistration, and the re-raise below must still run. Node documents
+            // pipe writes as asynchronous on some platforms (notably macOS); small
+            // buffers like this one are written inline.
             try {
-                if (report)
-                    report(path);
-                // Node documents pipe writes as asynchronous on some platforms
-                // (notably macOS); a saturated pipe could drop this write. Small
-                // buffers like this one are written inline, which is why the
-                // covering test observes it reliably.
                 process.stderr.write(`${workspaceRemovalFailure(path)}\n`);
             }
             catch {
@@ -96,7 +79,7 @@ function deregisterCoordinator() {
         process.off(signal, handler);
     handlers.clear();
 }
-export async function withWorkspace(parent, prefix, fn, options = {}) {
+async function runInWorkspace(parent, prefix, fn, options, reportCleanupFailure) {
     const remove = options.cleanup ?? cleanup;
     let workspace;
     try {
@@ -105,35 +88,46 @@ export async function withWorkspace(parent, prefix, fn, options = {}) {
     catch (cause) {
         throw new SafetyError("workspace", "cannot create workspace", { cause });
     }
-    active.set(workspace, options.onCleanupFailure);
+    active.add(workspace);
     registerCoordinator();
     try {
-        let result;
+        let value;
         let failed = false;
         let callbackError;
         try {
-            result = await fn(workspace);
+            value = await fn(workspace);
         }
         catch (error) {
             failed = true;
             callbackError = error;
         }
+        let cleanupWarning = null;
         try {
             await remove(workspace);
         }
         catch (cleanupError) {
             if (failed)
                 throw callbackError;
-            if (options.onCleanupFailure === undefined)
+            if (!reportCleanupFailure)
                 throw cleanupError;
-            options.onCleanupFailure(workspace);
+            cleanupWarning = workspaceRemovalFailure(workspace);
         }
         if (failed)
             throw callbackError;
-        return result;
+        return { value, cleanupWarning };
     }
     finally {
         active.delete(workspace);
         deregisterCoordinator();
     }
 }
+export async function withWorkspace(parent, prefix, fn, options = {}) {
+    return (await runInWorkspace(parent, prefix, fn, options, false)).value;
+}
+// Like withWorkspace, except a cleanup failure after a SUCCESSFUL callback is
+// returned as `cleanupWarning` instead of thrown, so the caller keeps the value
+// it already computed and reports the leak itself. A callback throw still
+// propagates, and a cleanup failure never masks it.
+export function withWorkspaceReporting(parent, prefix, fn, options = {}) {
+    return runInWorkspace(parent, prefix, fn, options, true);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "superpowers-manager",
-  "version": "0.7.3",
-  "description": "Install obra/superpowers directly from upstream for Codex, Pi, and OpenCode. Stay on a known-good release or commit, try a branch, and upgrade when you choose.",
+  "version": "0.9.0",
+  "description": "Install obra/superpowers directly from upstream for Codex, Pi, OpenCode, and Claude Code. Stay on a known-good release or commit, try a branch, and upgrade when you choose.",
   "keywords": [
     "superpowers",
     "obra-superpowers",
@@ -18,21 +18,22 @@
     "pi",
     "pi-coding-agent",
     "opencode",
+    "claude-code",
+    "claude-code-plugin",
     "version-pinning"
   ],
   "license": "MIT",
   "type": "module",
-  "packageManager": "pnpm@12.4.0",
+  "packageManager": "pnpm@12.4.2",
   "scripts": {
-    "lint": "oxlint src/ tests/bin/ tests/unit/ tests/baseline/ tests/lib/ tests/tools/ tests/container/ tests/run-node-suites.ts tests/assert-matcher-gate.ts",
-    "format": "prettier --write src/ tests/bin/ tests/unit/ tests/baseline/ tests/lib/ tests/tools/ tests/container/ tests/run-node-suites.ts tests/assert-matcher-gate.ts",
-    "format:check": "prettier --check src/ tests/bin/ tests/unit/ tests/baseline/ tests/lib/ tests/tools/ tests/container/ tests/run-node-suites.ts tests/assert-matcher-gate.ts",
-    "test": "node tests/run-node-suites.ts",
-    "test:unit": "node tests/run-node-suites.ts --group unit",
-    "test:integration": "node tests/run-node-suites.ts --group integration",
+    "lint": "oxlint src/ tests/",
+    "format": "prettier --write src/ tests/",
+    "format:check": "prettier --check src/ tests/",
+    "test": "sh tests/run.sh",
     "test:harness:codex": "sh tests/container.sh harness-codex",
     "test:harness:pi": "sh tests/container.sh harness-pi",
     "test:harness:opencode": "sh tests/container.sh harness-opencode",
+    "test:harness:claude-code": "sh tests/container.sh harness-claude-code",
     "test:acceptance": "sh tests/acceptance.sh",
     "check:static": "pnpm run format:check && pnpm run lint && pnpm run typecheck && pnpm run knip",
     "check": "pnpm run check:static && pnpm run test",

package/dist/python-json.js

@@ -1,4 +0,0 @@
-import { escapeNonAscii } from "./python-json-format.js";
-export function escapePythonJsonString(value) {
-    return escapeNonAscii(JSON.stringify(value).slice(1, -1));
-}

package/dist/upstream-workspace.js

@@ -1,8 +0,0 @@
-import { isAbsolute, join, resolve } from "node:path";
-export function upstreamCacheRoot(root, env, cwd) {
-    const configured = env.SUPERPOWERS_CACHE_DIR || join(root, ".cache", "upstream");
-    const cacheParent = isAbsolute(configured)
-        ? configured
-        : resolve(cwd, configured);
-    return join(cacheParent, "superpowers");
-}