superpowers-manager 0.2.0 → 0.4.0

package/dist/atomic.js

@@ -0,0 +1,142 @@
+import { randomBytes } from "node:crypto";
+import { constants, lstat, open, readFile, rename, rm, unlink, } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { SafetyError } from "./safety-error.js";
+export async function atomicWriteFile(path, bytes, options) {
+    const renamePath = options.hooks?.rename ?? rename;
+    let handle;
+    let temporary;
+    let phase = "pre-replacement";
+    try {
+        for (let attempt = 0; attempt < 100; attempt += 1) {
+            const suffix = randomBytes(8).toString("hex");
+            const candidate = join(dirname(path), `.${basename(path)}.tmp.${process.pid}.${suffix}`);
+            try {
+                handle = await open(candidate, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+                temporary = candidate;
+                break;
+            }
+            catch (cause) {
+                if (cause instanceof Error &&
+                    "code" in cause &&
+                    cause.code === "EEXIST") {
+                    continue;
+                }
+                throw cause;
+            }
+        }
+        if (handle === undefined || temporary === undefined) {
+            throw new Error("cannot create unique temporary file");
+        }
+        await handle.chmod(0o600);
+        await handle.writeFile(bytes);
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await options.validate(temporary);
+        await renamePath(temporary, path);
+        temporary = undefined;
+        phase = "post-replacement";
+        await options.hooks?.afterReplace?.(path);
+        await fsyncDirectoryBestEffort(dirname(path));
+    }
+    catch (cause) {
+        let finalBytes;
+        if (phase === "post-replacement") {
+            finalBytes = await readFile(path).catch(() => undefined);
+        }
+        const details = finalBytes === undefined ? { phase } : { phase, finalBytes };
+        throw new SafetyError("atomic", `atomic file write failed during ${phase}`, { cause, details });
+    }
+    finally {
+        if (handle !== undefined) {
+            await handle.close().catch(() => { });
+        }
+        if (temporary !== undefined) {
+            await unlink(temporary).catch(() => { });
+        }
+    }
+}
+async function fsyncDirectoryBestEffort(directory) {
+    let handle;
+    try {
+        handle = await open(directory, constants.O_RDONLY);
+        await handle.sync();
+    }
+    catch {
+        // The frozen baseline treats directory fsync as best effort.
+    }
+    finally {
+        await handle?.close().catch(() => { });
+    }
+}
+async function exists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (cause) {
+        if (cause instanceof Error &&
+            "code" in cause &&
+            cause.code === "ENOENT") {
+            return false;
+        }
+        throw cause;
+    }
+}
+async function chooseBackup(live) {
+    for (let attempt = 0; attempt < 100; attempt += 1) {
+        const candidate = join(dirname(live), `.${basename(live)}.bak.${process.pid}.${randomBytes(8).toString("hex")}`);
+        if (!(await exists(candidate)))
+            return candidate;
+    }
+    throw new SafetyError("atomic", "cannot choose unique backup path");
+}
+export async function atomicReplaceDir(candidate, live, options = {}) {
+    const renamePath = options.hooks?.rename ?? rename;
+    const removePath = options.hooks?.rm ?? rm;
+    let backupCreated = false;
+    let phase = "pre-replacement";
+    try {
+        const backup = await chooseBackup(live);
+        if (await exists(live)) {
+            await renamePath(live, backup);
+            backupCreated = true;
+        }
+        try {
+            await renamePath(candidate, live);
+            phase = "post-replacement";
+        }
+        catch (cause) {
+            if (!backupCreated) {
+                await removePath(candidate, { recursive: true, force: true });
+                throw new SafetyError("atomic", "directory activation failed with no prior tree", { cause, details: { phase: "pre-replacement" } });
+            }
+            try {
+                await renamePath(backup, live);
+            }
+            catch (rollbackCause) {
+                await removePath(candidate, { recursive: true, force: true }).catch(() => { });
+                throw new SafetyError("atomic", `directory activation and rollback failed; backup preserved at ${backup}`, {
+                    cause: new AggregateError([cause, rollbackCause]),
+                    details: { phase: "pre-replacement" },
+                });
+            }
+            await removePath(candidate, { recursive: true, force: true });
+            throw new SafetyError("atomic", "directory activation failed; previous tree restored", { cause, details: { phase: "pre-replacement" } });
+        }
+        if (backupCreated) {
+            try {
+                await removePath(backup, { recursive: true, force: true });
+            }
+            catch (cause) {
+                throw new SafetyError("atomic", `directory replacement succeeded but backup cleanup failed at ${backup}`, { cause, details: { phase: "post-replacement" } });
+            }
+        }
+    }
+    catch (cause) {
+        if (cause instanceof SafetyError)
+            throw cause;
+        throw new SafetyError("atomic", "directory replacement failed", { cause, details: { phase } });
+    }
+}

package/dist/cli-arguments.js

@@ -0,0 +1,32 @@
+export class UsageError extends Error {
+}
+export function parseFlags(argv, names) {
+    const allowed = new Set(names);
+    const result = {};
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (!token.startsWith("--"))
+            throw new UsageError(`unexpected argument: ${token}`);
+        const separator = token.indexOf("=");
+        const name = separator === -1 ? token.slice(2) : token.slice(2, separator);
+        if (!allowed.has(name))
+            throw new UsageError(`unknown option: --${name}`);
+        const value = separator === -1 ? argv[index + 1] : token.slice(separator + 1);
+        if (value === undefined || (separator === -1 && value.startsWith("--"))) {
+            throw new UsageError(`option --${name} requires a value`);
+        }
+        result[name] = value;
+        if (separator === -1)
+            index += 1;
+    }
+    for (const name of names) {
+        if (!Object.hasOwn(result, name)) {
+            throw new UsageError(`required option is missing: --${name}`);
+        }
+    }
+    return result;
+}
+export function oneLine(value) {
+    const message = value instanceof Error ? value.message : String(value);
+    return message.replace(/[\r\n]+/g, " ");
+}

package/dist/cli.js

@@ -0,0 +1,313 @@
+#!/usr/bin/env node
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { oneLine } from "./cli-arguments.js";
+import { codexHarness } from "./codex-harness.js";
+import { runInstall } from "./commands/install.js";
+import { runPin } from "./commands/pin.js";
+import { runPrepare } from "./commands/prepare.js";
+import { runProbe } from "./commands/probe.js";
+import { runTrackLatest } from "./commands/track-latest.js";
+import { runUninstall } from "./commands/uninstall.js";
+import { runUnpin } from "./commands/unpin.js";
+import { runUpdate } from "./commands/update.js";
+import { COMMIT_INPUT_RE, TAG_RE } from "./domain/refs.js";
+import { configurationErrors } from "./validator.js";
+const SUBCOMMANDS = [
+    "pin",
+    "track-latest",
+    "unpin",
+    "prepare",
+    "probe",
+    "install",
+    "update",
+    "uninstall",
+];
+// Keyed by Subcommand itself. Until slice 6 this was keyed by a mapped type
+// that filtered Subcommand through a DISPATCH table of "spawn" | "in-process"
+// literals; with every command in-process that filter was the identity, so the
+// table, its mode union and the mapped type were one indirection with nothing
+// left to discriminate. The guarantee is unchanged and is the whole protection
+// — tests/bin/bin-dispatch.test.js records that decision: a Subcommand added
+// without a handler registered here is a compile error, not a runtime surprise.
+const IN_PROCESS_HANDLERS = {
+    pin: runPin,
+    "track-latest": runTrackLatest,
+    unpin: runUnpin,
+    prepare: runPrepare,
+    probe: runProbe,
+    install: runInstall,
+    update: runUpdate,
+    uninstall: runUninstall,
+};
+// `python3` left install, update and uninstall at slice 4b's flip. It was
+// required because `spw_invoke_adapter` ran validate-adapter-response.py once
+// per adapter call
+// (`git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/adapter.sh:37-44::--response "$response_file" --result "$result_file" \`);
+// the in-process path has no validator process. It remains CONDITIONAL for
+// `prepare` through commandRequirements(env) below, unchanged from slice 3.4.
+// No command requires a POSIX shell any more.
+const SHARED_COMMAND_REQUIREMENTS = {
+    pin: ["git"],
+    "track-latest": [],
+    unpin: [],
+    prepare: ["git"],
+    probe: ["git"],
+    install: ["git"],
+    update: ["git"],
+    uninstall: [],
+};
+// Walk upward from the bin's physical location to the directory containing
+// package.json. realpathSync first: npm/npx expose the bin through a symlink
+// or shim outside the package root.
+function resolvePackageRoot(scriptPath) {
+    let dir;
+    try {
+        dir = path.dirname(fs.realpathSync(scriptPath));
+    }
+    catch {
+        return null;
+    }
+    for (;;) {
+        if (fs.existsSync(path.join(dir, "package.json")))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+function isMain(moduleFilename, argvPath) {
+    if (!argvPath)
+        return false;
+    return moduleFilename === fs.realpathSync(argvPath);
+}
+function parseArgs(argv) {
+    const first = argv[0];
+    if (argv.length === 0)
+        return { kind: "run", cmd: "update", args: [] };
+    if (first === "--help" || first === "-h")
+        return { kind: "help" };
+    if (first === "--version")
+        return { kind: "version" };
+    if (first && SUBCOMMANDS.includes(first)) {
+        const command = first;
+        const args = argv.slice(1);
+        if (command === "pin" && args.length !== 1) {
+            return {
+                kind: "usage-error",
+                message: "usage: superpowers-manager pin REF",
+            };
+        }
+        if (command === "pin" &&
+            !TAG_RE.test(args[0]) &&
+            !COMMIT_INPUT_RE.test(args[0])) {
+            return {
+                kind: "usage-error",
+                message: "pin REF must be an exact v-prefixed SemVer tag or full 40-hex commit",
+            };
+        }
+        if ((command === "track-latest" || command === "unpin") &&
+            args.length !== 0) {
+            return {
+                kind: "usage-error",
+                message: `usage: superpowers-manager ${command}`,
+            };
+        }
+        // Arity lives HERE, not only in src/commands/probe.ts, so `probe` gets the
+        // same shape as every other CLI-owned usage error: `error: <msg>` plus the
+        // full usage block, exit 2, decided before preflight. Leaving it to the
+        // handler alone made `probe --porcelaine` print no usage block, and made
+        // the identical input exit 1 on a machine without `codex` because preflight
+        // ran first. `PROBE_USAGE` stays as the same unreachable-from-CLI duplicate
+        // that track-latest and unpin already carry.
+        if (command === "probe" &&
+            !(args.length === 0 || (args.length === 1 && args[0] === "--porcelain"))) {
+            return {
+                kind: "usage-error",
+                message: "usage: superpowers-manager probe [--porcelain]",
+            };
+        }
+        return { kind: "run", cmd: command, args };
+    }
+    return { kind: "usage-error", message: `unknown subcommand: ${first}` };
+}
+// Search env.PATH for an executable named `name`; on win32 also try PATHEXT
+// extensions. Returns the full path or null.
+function findTool(name, env, platform) {
+    const pathVar = env.PATH || env.Path || "";
+    const dirs = pathVar.split(path.delimiter).filter(Boolean);
+    const exts = platform === "win32"
+        ? (env.PATHEXT || ".EXE;.CMD;.BAT;.COM").split(";")
+        : [""];
+    for (const dir of dirs) {
+        for (const ext of exts) {
+            const candidate = path.join(dir, name + ext.toLowerCase());
+            try {
+                fs.accessSync(candidate, fs.constants.X_OK);
+                return candidate;
+            }
+            catch {
+                /* keep looking */
+            }
+        }
+    }
+    return null;
+}
+// python3 is required by `prepare` only when SUPERPOWERS_VALIDATOR names one:
+// after the port, that optional spawn (runValidator, in src/validator.ts,
+// called from src/commands/prepare.ts) is Python's only remaining consumer
+// on the prepare path. The conditional lives here, in the accessor preflight reads,
+// rather than inside preflight — an accessor that under-reports what
+// preflight enforces is the blind spot slice 2 closed when it made
+// CLI-PREFLIGHT-01 derive its map from production.
+function sharedRequirement(name) {
+    return {
+        name,
+        executable: name,
+        lookup: "path",
+        missingMessage: `required command not found: ${name} — install ${name} and re-run`,
+    };
+}
+function commandRequirementsFor(env, adapter) {
+    const forCommand = (command) => {
+        const shared = SHARED_COMMAND_REQUIREMENTS[command].map(sharedRequirement);
+        if (command === "prepare" && env.SUPERPOWERS_VALIDATOR) {
+            shared.push(sharedRequirement("python3"));
+        }
+        return [...shared, ...adapter.requirements(command, env)];
+    };
+    return {
+        pin: forCommand("pin"),
+        "track-latest": forCommand("track-latest"),
+        unpin: forCommand("unpin"),
+        prepare: forCommand("prepare"),
+        probe: forCommand("probe"),
+        install: forCommand("install"),
+        update: forCommand("update"),
+        uninstall: forCommand("uninstall"),
+    };
+}
+function commandRequirements(env) {
+    return Object.fromEntries(SUBCOMMANDS.map((command) => [
+        command,
+        commandRequirementsFor(env, codexHarness)[command].map((requirement) => requirement.name),
+    ]));
+}
+// Preflight; never touches Codex state. It is the union of two exported
+// accessors: configurationErrors (validator configuration) and
+// commandRequirements (tool availability), both specific to the selected
+// command. No command requires a POSIX shell: slice 4b flipped the last
+// spawned command in-process, so there is no shell to discover.
+function preflightFor(cmd, env, platform, adapter) {
+    const errors = [...configurationErrors(cmd, env)];
+    for (const requirement of commandRequirementsFor(env, adapter)[cmd]) {
+        const found = requirement.lookup === "explicit-path-or-path" &&
+            requirement.executable.includes(path.sep)
+            ? fs.existsSync(requirement.executable)
+            : Boolean(findTool(requirement.executable, env, platform));
+        if (!found)
+            errors.push(requirement.missingMessage);
+    }
+    if (errors.length)
+        return { ok: false, errors };
+    return { ok: true };
+}
+function preflight(cmd, env, platform) {
+    return preflightFor(cmd, env, platform, codexHarness);
+}
+function usage() {
+    return [
+        "usage: superpowers-manager [command] [args...]",
+        "",
+        "Selection commands (save intent only; they do not prepare or install it):",
+        "  pin REF       save an exact upstream release tag or commit",
+        "  track-latest  save selection of the latest stable upstream release",
+        "  unpin         remove the saved selection and return to the packaged fallback",
+        "",
+        "Apply and lifecycle commands:",
+        "  prepare    fetch the pinned upstream ref and generate the plugin tree",
+        "  probe      report upstream/generated/installed status (accepts --porcelain)",
+        "  install    register this package root as a Codex marketplace and install the plugin",
+        "  update     probe, then prepare/install only if needed (default when no subcommand)",
+        "  uninstall  remove the manager plugin and marketplace from Codex",
+        "",
+        "Environment overrides (used by in-process commands): SUPERPOWERS_REF,",
+        "SUPERPOWERS_UPSTREAM_URL, SUPERPOWERS_CODEX, SUPERPOWERS_CACHE_DIR,",
+        "SUPERPOWERS_CONFIG_DIR, XDG_CONFIG_HOME,",
+        "SUPERPOWERS_PLUGIN_ROOT, SUPERPOWERS_MANIFEST_TEMPLATE,",
+        "SUPERPOWERS_VALIDATOR, SUPERPOWERS_VALIDATOR_EXECUTABLE,",
+        "SUPERPOWERS_INSTALLED_SEARCH_ROOT, SUPERPOWERS_INSTALL_REFRESH_MODE",
+        "",
+        "Selection state uses SUPERPOWERS_CONFIG_DIR when set; otherwise it uses",
+        "$XDG_CONFIG_HOME/superpowers-manager, then $HOME/.config/superpowers-manager.",
+    ].join("\n");
+}
+async function main() {
+    const parsed = parseArgs(process.argv.slice(2));
+    if (parsed.kind === "help") {
+        console.log(usage());
+        process.exit(0);
+    }
+    const root = resolvePackageRoot(import.meta.filename);
+    if (!root) {
+        console.error("error: cannot resolve the superpowers-manager package root");
+        process.exit(1);
+    }
+    if (parsed.kind === "version") {
+        console.log(JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"))
+            .version);
+        process.exit(0);
+    }
+    if (parsed.kind === "usage-error") {
+        console.error(`error: ${parsed.message}`);
+        console.error(usage());
+        process.exit(2);
+    }
+    const pf = preflight(parsed.cmd, process.env, process.platform);
+    if (!pf.ok) {
+        for (const e of pf.errors)
+            console.error(`error: ${e}`);
+        process.exit(1);
+    }
+    // Dispatch is no longer a branch: slice 4b flipped the last spawned command,
+    // so every subcommand runs here, and slice 6 deleted the DISPATCH table whose
+    // only remaining job was narrowing this registry's key type. `parsed.cmd` is
+    // a Subcommand and the registry is keyed by Subcommand, so no cast is needed.
+    // The exhaustiveness check on IN_PROCESS_HANDLERS makes an unregistered
+    // handler a compile error; the `!handler` guard below is the runtime backstop
+    // for that guarantee. It is unreachable through production code, and no
+    // fixture reaches it either.
+    const handler = IN_PROCESS_HANDLERS[parsed.cmd];
+    if (!handler) {
+        console.error(`error: no in-process handler registered for: ${parsed.cmd}`);
+        process.exit(1);
+    }
+    const ctx = {
+        root,
+        env: process.env,
+        stdout: process.stdout,
+        stderr: process.stderr,
+        // The ONLY production binding of a concrete harness implementation.
+        adapter: codexHarness,
+    };
+    let status;
+    try {
+        status = await handler(parsed.args, ctx);
+    }
+    catch (cause) {
+        // Belt-and-suspenders: every registered handler already catches its own
+        // failures and returns a status code (see src/commands/unpin.ts). This
+        // re-emits a subordinate module's own diagnostic if one somehow escapes.
+        console.error(`error: ${oneLine(cause)}`);
+        process.exit(1);
+    }
+    process.exit(status);
+}
+export { resolvePackageRoot, isMain, parseArgs, findTool, commandRequirements, commandRequirementsFor, preflight, preflightFor, usage, main, };
+if (isMain(import.meta.filename, process.argv[1])) {
+    main().catch((cause) => {
+        console.error(`error: ${oneLine(cause)}`);
+        process.exit(1);
+    });
+}