superpowers-manager 0.1.6 → 0.3.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,293 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { runAdapter } from "./adapter.js";
+import { oneLine } from "./cli-arguments.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 COMMAND_REQUIREMENTS = {
+    pin: ["git"],
+    "track-latest": [],
+    unpin: [],
+    prepare: ["git"],
+    probe: ["git", "codex"],
+    install: ["git", "codex"],
+    update: ["git", "codex"],
+    uninstall: ["codex"],
+};
+// 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 commandRequirements(env) {
+    if (!env.SUPERPOWERS_VALIDATOR)
+        return COMMAND_REQUIREMENTS;
+    return {
+        ...COMMAND_REQUIREMENTS,
+        prepare: [...COMMAND_REQUIREMENTS.prepare, "python3"],
+    };
+}
+// 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 preflight(cmd, env, platform) {
+    const errors = [...configurationErrors(cmd, env)];
+    for (const tool of commandRequirements(env)[cmd]) {
+        if (tool === "codex") {
+            const codexBin = env.SUPERPOWERS_CODEX || "codex";
+            // An explicit override may be a path rather than a PATH-resolvable name.
+            const found = codexBin.includes(path.sep)
+                ? fs.existsSync(codexBin)
+                : Boolean(findTool(codexBin, env, platform));
+            if (!found) {
+                errors.push(`required command not found: ${codexBin} — install the Codex CLI or set SUPERPOWERS_CODEX`);
+            }
+        }
+        else if (!findTool(tool, env, platform)) {
+            errors.push(`required command not found: ${tool} — install ${tool} and re-run`);
+        }
+    }
+    if (errors.length)
+        return { ok: false, errors };
+    return { ok: true };
+}
+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 place runAdapter is bound to a context. Every command module
+        // reaches the adapter through this field; none imports runAdapter
+        // itself. tests/unit/ctx-adapter-provenance.test.js gates both halves.
+        adapter: runAdapter,
+    };
+    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, preflight, usage, main, };
+if (isMain(import.meta.filename, process.argv[1])) {
+    main().catch((cause) => {
+        console.error(`error: ${oneLine(cause)}`);
+        process.exit(1);
+    });
+}

package/dist/codex-json.js

@@ -0,0 +1,89 @@
+import { SafetyError } from "./safety-error.js";
+import { parseStrictJson, } from "./strict-json.js";
+const ACCEPT_CONSTANTS = {
+    duplicateKeys: "last-wins",
+    nonStandardConstants: "accept",
+};
+const REJECT_CONSTANTS = {
+    duplicateKeys: "last-wins",
+    nonStandardConstants: "reject",
+};
+function fail(message, cause) {
+    throw new SafetyError("codex-json", message, { cause });
+}
+function object(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function parseObject(raw, profile) {
+    let parsed;
+    try {
+        parsed = parseStrictJson(raw, profile);
+    }
+    catch (cause) {
+        fail("cannot parse Codex JSON", cause);
+    }
+    const result = object(parsed);
+    if (result === undefined)
+        fail("Codex JSON must be an object");
+    return result;
+}
+function checkedItems(raw, profile, arrayKey, field) {
+    const items = parseObject(raw, profile)[arrayKey];
+    if (!Array.isArray(items))
+        fail(`Codex JSON ${arrayKey} must be an array`);
+    return items.map((item) => {
+        const candidate = object(item);
+        if (candidate === undefined) {
+            fail(`Codex JSON ${arrayKey} item must be an object`);
+        }
+        const fieldValue = candidate[field];
+        if (typeof fieldValue !== "string" || fieldValue.length === 0) {
+            fail(`Codex JSON ${arrayKey} item needs non-empty ${field}`);
+        }
+        return candidate;
+    });
+}
+function hasTerminalControl(value) {
+    for (const character of value) {
+        const code = character.codePointAt(0);
+        if (code < 0x20 ||
+            (code >= 0x7f && code <= 0x9f) ||
+            (code >= 0xd800 && code <= 0xdfff)) {
+            return true;
+        }
+    }
+    return false;
+}
+export function installedListingHas(raw, arrayKey, field, value) {
+    return checkedItems(raw, ACCEPT_CONSTANTS, arrayKey, field).some((item) => item[field] === value);
+}
+export function marketplaceRootFromJson(raw, marketplaceName) {
+    const items = checkedItems(raw, ACCEPT_CONSTANTS, "marketplaces", "name");
+    const match = items.find((item) => item.name === marketplaceName);
+    if (match === undefined)
+        return "";
+    if (typeof match.root !== "string" || match.root.length === 0) {
+        fail("matching marketplace needs a non-empty root");
+    }
+    return match.root;
+}
+export function activePluginVersionFromJson(raw, pluginId) {
+    const matches = checkedItems(raw, REJECT_CONSTANTS, "installed", "pluginId").filter((item) => item.pluginId === pluginId);
+    if (matches.length > 1)
+        fail("active plugin appears more than once");
+    if (matches.length === 0)
+        return "";
+    const version = matches[0].version;
+    if (typeof version !== "string" ||
+        version.length === 0 ||
+        version === "." ||
+        version === ".." ||
+        version.includes("/") ||
+        version.includes("\\") ||
+        hasTerminalControl(version)) {
+        fail("active plugin version is invalid");
+    }
+    return version;
+}

package/dist/codex-state.js

@@ -0,0 +1,78 @@
+import { readFile, realpath } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { COMMIT_INPUT_RE } from "./domain/refs.js";
+import { SafetyError } from "./safety-error.js";
+import { parseStrictJson, } from "./strict-json.js";
+const INSTALLED_PROFILE = {
+    duplicateKeys: "last-wins",
+    nonStandardConstants: "reject",
+    maxDepth: 256,
+};
+function fail(message, cause) {
+    throw new SafetyError("codex-state", message, { cause });
+}
+function object(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+async function jsonStringField(path, key) {
+    let parsed;
+    try {
+        parsed = parseStrictJson(await readFile(path), INSTALLED_PROFILE);
+    }
+    catch (cause) {
+        fail(`cannot read installed Codex JSON ${path}`, cause);
+    }
+    const record = object(parsed);
+    if (record === undefined)
+        fail(`invalid installed Codex JSON ${path}`);
+    const value = record[key];
+    if (value === undefined || value === null)
+        return "";
+    if (typeof value !== "string")
+        fail(`invalid installed Codex JSON ${path}`);
+    return value;
+}
+export function installedRootForVersion(searchRoot, marketplace, plugin, version) {
+    return join(searchRoot, "plugins", "cache", marketplace, plugin, version);
+}
+export async function codexMetadataCommit(path) {
+    const commit = await jsonStringField(path, "commit");
+    if (!COMMIT_INPUT_RE.test(commit) && !/^[0-9a-fA-F]{7}$/.test(commit)) {
+        fail(`invalid installed Codex commit in ${path}`);
+    }
+    return commit;
+}
+export async function manifestShortSha(path) {
+    const version = await jsonStringField(path, "version");
+    if (!version.includes("+manager."))
+        return "";
+    const short = version.slice(version.lastIndexOf(".") + 1);
+    return /^[0-9a-fA-F]{7}$/.test(short) ? short : "";
+}
+export async function installedCommitFromRoot(activeRoot) {
+    try {
+        return await codexMetadataCommit(join(activeRoot, ".superpowers-upstream.json"));
+    }
+    catch {
+        // The shell predecessor deliberately fell back to the generated manifest.
+    }
+    try {
+        return await manifestShortSha(join(activeRoot, ".codex-plugin", "plugin.json"));
+    }
+    catch {
+        return "";
+    }
+}
+async function comparablePath(path) {
+    try {
+        return await realpath(path);
+    }
+    catch {
+        return resolve(path);
+    }
+}
+export async function pathsEqual(a, b) {
+    return (await comparablePath(a)) === (await comparablePath(b));
+}

package/dist/commands/context.js

@@ -0,0 +1 @@
+export {};