superpowers-manager 0.2.0 → 0.3.0

package/dist/validator.js

@@ -0,0 +1,317 @@
+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
+// whole chunk: ceasing to consume would block the child on a full pipe.
+class Sink {
+    limit;
+    chunks = [];
+    kept = 0;
+    dropped = 0;
+    constructor(limit) {
+        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;
+            return;
+        }
+        const take = chunk.length <= room ? chunk : chunk.subarray(0, room);
+        this.chunks.push(take);
+        this.kept += take.length;
+        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.
+        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
+// ordinary race between SIGTERM and SIGKILL.
+function signalGroup(child, signal) {
+    if (child.pid === undefined)
+        return;
+    try {
+        process.kill(-child.pid, signal);
+    }
+    catch {
+        /* the group exited between the timer firing and this call */
+    }
+}
+export function runValidator(argv, policy, env, workspace) {
+    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);
+        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
+        // inside the SIGKILL callback, so on the timeout path the promise cannot
+        // resolve before the escalation has run. That nesting is the fix for an
+        // earlier revision which settled first and left the SIGKILL on a cancellable
+        // timer -- the historical shape the `survivor.sh` case in the unit suite
+        // exists to catch. Only the timeout timer is cleared here, and that clear is
+        // load-bearing rather than belt-and-braces: on a clean exit the `exit` handler
+        // has already disarmed it, and on the timeout path it has already fired -- but
+        // on the BOUNDED LAUNCH-FAILURE path neither happens. Node emits no `exit`
+        // event for an asynchronously failing spawn (an ENOENT spawn yields `error`
+        // then `close` with -2 and nothing else), so this is the only thing that
+        // disarms the timer for it.
+        const settle = (run) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timeoutTimer !== undefined)
+                clearTimeout(timeoutTimer);
+            resolveRun(run);
+        };
+        let timeoutTimer;
+        let timedOut = false;
+        let lastCode = null;
+        // No timer is unref'ed. The escalation must actually run, and an unref'ed timer
+        // does not keep the event loop alive.
+        // On darwin, ENOEXEC is delivered as a SYNCHRONOUS throw here rather than on
+        // the `error` event, so a handler-only implementation would miss it. On Linux
+        // this branch is not reached for ENOEXEC at all: POSIX execvp falls back to
+        // /bin/sh on ENOEXEC, so the spawn itself succeeds. Because the throw happens
+        // inside this Promise executor, it rejects runValidator's returned promise --
+        // not an unhandled rejection -- which is what this try/catch prevents.
+        let child;
+        try {
+            child = spawn(command, args, {
+                env: { ...process.env, ...env, TMPDIR: workspace },
+                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",
+            });
+        }
+        catch (cause) {
+            settle({
+                kind: "launchFailed",
+                errno: cause.code ?? "UNKNOWN",
+                cause,
+            });
+            return;
+        }
+        // No setEncoding: the cap counts BYTES, and a string accumulator would count
+        // UTF-16 code units instead.
+        child.stdout.on("data", (chunk) => out.push(chunk));
+        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 });
+        });
+        child.on("close", (code) => {
+            // On the timeout path, settling here would resolve BEFORE SIGKILL and the
+            // escalation would never complete. That path settles itself, after the kill.
+            if (timedOut)
+                return;
+            settle({ kind: "exited", code, stdout: out.done(), stderr: err.done() });
+        });
+        // Settling on `close` alone is not a wall-clock bound: `close` fires only when
+        // every writer has released the pipes, and a descendant that outlives the child
+        // holds them. Settle on whichever comes first -- `close`, or the child's `exit`
+        // plus a bounded drain for trailing output.
+        child.on("exit", (code) => {
+            // `exit` carries the status and fires as soon as the CHILD is gone; `close`
+            // 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;
+            // The drain settle below is now the one that will resolve this run, so the
+            // timeout must not fire behind it. A child exiting inside
+            // [timeoutMs - drainMs, timeoutMs) already has its drain settle queued when
+            // the timeout comes due; without this the timeout would SIGTERM the group of
+            // a validator that had ALREADY exited cleanly, then leave the SIGKILL
+            // escalation pending behind a settle that reports `exited`. Race-free rather
+            // than merely unlikely: either the timeout has fired, in which case
+            // `timedOut` is true and we returned above, or it has not, and now it never
+            // will. The bound is unchanged -- settlement is exitTime + drainMs and
+            // exitTime < timeoutMs. Deliberately NOT paired with a `timedOut` re-check
+            // inside the drain callback: with the timer cleared that check is
+            // unreachable, and unfalsifiable defensive code is what this module keeps
+            // being bitten by.
+            clearTimeout(timeoutTimer);
+            setTimeout(() => {
+                settle({
+                    kind: "exited",
+                    code: lastCode,
+                    stdout: out.done(),
+                    stderr: err.done(),
+                });
+            }, 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");
+                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);
+        }
+    });
+}
+// Every probe below is best-effort BY DESIGN: spawn is the authority on whether the
+// path is runnable, and this result exists only for disclosure and for
+// disambiguating EACCES between "a directory" and "not executable". A failed probe
+// therefore degrades the MESSAGE, never the verdict — no probe result can admit a
+// validator that spawn would have rejected.
+export async function resolveValidator(configured) {
+    // Every probe is skipped for a bare name. lstat and stat are CWD-relative, so on
+    // a bare name they would describe a file in the current directory while spawn
+    // runs whatever PATH selects -- the same divergence that makes realpath unsafe
+    // here.
+    const pathLike = configured.includes(sep);
+    let isSymlink = false;
+    if (pathLike) {
+        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
+    // bare name, realpath resolves relative to the CWD while spawn searches PATH:
+    // measured from a directory containing `node`, realpath("node") gave one
+    // 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 */
+        }
+    }
+    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 */
+        }
+    }
+    return { configured, resolved, isSymlink, isDirectory, exists };
+}
+// Escape only when there is something to escape. pythonUnicodeEscape retains only
+// printable ASCII, so escaping unconditionally would render a legitimate non-ASCII
+// path unrecognisable to the operator who configured it. This is a legibility
+// measure, not a security control.
+export function displayPath(value) {
+    return hasTerminalControl(value)
+        ? pythonUnicodeEscapeBytes(Buffer.from(value, "utf8"))
+        : value;
+}
+export function launchFailureMessage(errno, resolution) {
+    const shown = displayPath(resolution.configured);
+    if (errno === "ENOENT" && resolution.exists) {
+        // The validator IS there; spawn's ENOENT came from its interpreter line.
+        // Measured: an executable with `#!/definitely/missing` raises ENOENT, and
+        // reporting "validator not found" would send the operator looking for a file
+        // that is present.
+        return `external plugin validator is present but its interpreter is missing: ${shown}`;
+    }
+    if (errno === "ENOENT")
+        return `external plugin validator not found: ${shown}`;
+    if (errno === "EACCES" && resolution.isDirectory)
+        return `external plugin validator is a directory: ${shown}`;
+    if (errno === "EACCES")
+        return `external plugin validator is not executable: ${shown}`;
+    if (errno === "ENOEXEC")
+        return `external plugin validator is not a runnable program: ${shown}`;
+    return `cannot execute external plugin validator: ${shown} (${errno})`;
+}
+// Only the commands that would actually run a validator. probe stays read-only, and
+// a validator misconfiguration is none of its business.
+const VALIDATOR_COMMANDS = new Set([
+    "prepare",
+    "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))
+        return [];
+    return [
+        "SUPERPOWERS_VALIDATOR and SUPERPOWERS_VALIDATOR_EXECUTABLE are both set — " +
+            "unset one; the manager never chooses between them silently",
+    ];
+}

package/dist/workspace.js

@@ -0,0 +1,139 @@
+import { rmSync } from "node:fs";
+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();
+let exiting = false;
+const handlers = new Map();
+// One phrasing for one condition. The adapter re-emits this for a suppressed
+// failure, so a change here must not leave two wordings for the same event.
+export function workspaceRemovalFailure(path) {
+    return `cannot remove workspace ${path}`;
+}
+async function cleanup(path) {
+    try {
+        await rm(path, { recursive: true, force: true });
+    }
+    catch (cause) {
+        throw new SafetyError("workspace", workspaceRemovalFailure(path), {
+            cause,
+        });
+    }
+}
+// Synchronous by contract. An `await` here would yield to the event loop with
+// the listeners still registered, and every signal arriving during that window
+// would be consumed and discarded — an uninterruptible process, which is worse
+// than the leak the handler exists to prevent. Being synchronous means the
+// handler cannot be re-entered, so the window does not exist.
+function cleanupForSignal(signal) {
+    if (exiting)
+        return;
+    exiting = true;
+    for (const [path, report] 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.
+            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 {
+                // See above: a reporting failure must not block cleanup/re-raise.
+            }
+        }
+    }
+    active.clear();
+    // Remove only the listeners this coordinator registered, then re-raise so the
+    // default disposition terminates the process by the signal.
+    for (const [managed, handler] of handlers)
+        process.off(managed, handler);
+    handlers.clear();
+    process.kill(process.pid, signal);
+}
+function registerCoordinator() {
+    if (handlers.size > 0)
+        return;
+    for (const signal of MANAGED_SIGNALS) {
+        const handler = () => {
+            cleanupForSignal(signal);
+        };
+        handlers.set(signal, handler);
+        process.on(signal, handler);
+    }
+}
+function deregisterCoordinator() {
+    if (active.size > 0)
+        return;
+    for (const [signal, handler] of handlers)
+        process.off(signal, handler);
+    handlers.clear();
+}
+export async function withWorkspace(parent, prefix, fn, options = {}) {
+    const remove = options.cleanup ?? cleanup;
+    let workspace;
+    try {
+        workspace = await mkdtemp(join(parent, prefix));
+    }
+    catch (cause) {
+        throw new SafetyError("workspace", "cannot create workspace", { cause });
+    }
+    active.set(workspace, options.onCleanupFailure);
+    registerCoordinator();
+    try {
+        let result;
+        let failed = false;
+        let callbackError;
+        try {
+            result = await fn(workspace);
+        }
+        catch (error) {
+            failed = true;
+            callbackError = error;
+        }
+        try {
+            await remove(workspace);
+        }
+        catch (cleanupError) {
+            if (failed)
+                throw callbackError;
+            if (options.onCleanupFailure === undefined)
+                throw cleanupError;
+            options.onCleanupFailure(workspace);
+        }
+        if (failed)
+            throw callbackError;
+        return result;
+    }
+    finally {
+        active.delete(workspace);
+        deregisterCoordinator();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superpowers-manager",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Install and update the latest stable obra/superpowers release directly from upstream, without waiting for agent marketplaces to catch up. Codex supported today.",
   "keywords": [
     "superpowers",
@@ -18,6 +18,28 @@
   ],
   "license": "MIT",
   "type": "module",
+  "packageManager": "pnpm@11.22.0",
+  "scripts": {
+    "prebuild": "node --input-type=module -e \"import{rmSync}from'node:fs';rmSync('dist',{recursive:true,force:true})\"",
+    "build": "tsc -p tsconfig.json",
+    "postbuild": "node tests/write-build-id.js",
+    "prepack": "node --input-type=module -e \"import{existsSync}from'node:fs';if(!existsSync('dist/cli.js')){console.error('error: dist/cli.js is missing — run pnpm install --frozen-lockfile && pnpm run build');process.exit(1)}\"",
+    "lint": "oxlint src/ bin/ tests/bin/ tests/unit/ tests/baseline/ tests/lib/ tests/tools/ tests/run-node-suites.js tests/build-id.js tests/write-build-id.js tests/assert-matcher-gate.js",
+    "format": "prettier --write src/ bin/ tests/bin/ tests/unit/ tests/baseline/ tests/lib/ tests/tools/ tests/run-node-suites.js tests/build-id.js tests/write-build-id.js tests/assert-matcher-gate.js",
+    "format:check": "prettier --check src/ bin/ tests/bin/ tests/unit/ tests/baseline/ tests/lib/ tests/tools/ tests/run-node-suites.js tests/build-id.js tests/write-build-id.js tests/assert-matcher-gate.js",
+    "typecheck:js": "tsc -p tests/tsconfig.json",
+    "test": "node tests/run-node-suites.js",
+    "check:static": "pnpm run format:check && pnpm run lint && pnpm run build && pnpm run typecheck:js",
+    "check": "pnpm run check:static && pnpm run test"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "oxlint": "^1.75.0",
+    "oxlint-tsgolint": "7.0.2001",
+    "prettier": "^3.9.6",
+    "typescript": "~7.0.2",
+    "yaml": "^2.9.0"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/j7an/superpowers-manager.git"
@@ -34,7 +56,8 @@
   },
   "files": [
     "bin/",
-    "scripts/",
+    "dist/",
+    "!dist/.build-id",
     "config/upstream-ref",
     ".agents/plugins/marketplace.json",
     "plugins/superpowers/.codex-plugin/plugin.template.json",