superpowers-manager 0.3.0 → 0.5.0

package/dist/adapter.js

@@ -6,6 +6,7 @@ import { tmpdir } from "node:os";
 import { delimiter, isAbsolute, join } from "node:path";
 import { AdapterMessageLog, failureResult, successResult, } from "./adapter-result.js";
 import { activePluginVersionFromJson, installedListingHas, marketplaceRootFromJson, } from "./codex-json.js";
+import { CODEX_LEGACY_PLUGIN_ID, CODEX_MANAGER_PLUGIN_ID, inspectCodexConflicts, } from "./codex-conflicts.js";
 import { oneLine } from "./cli-arguments.js";
 import { installedCommitFromRoot, installedRootForVersion, pathsEqual, } from "./codex-state.js";
 import { validateGeneratedPlugin } from "./generated-plugin.js";
@@ -14,9 +15,9 @@ import { applyManifestOverlay } from "./manifest-overlay.js";
 import { readCodexBuildSource } from "./provenance.js";
 import { isAcceptedSplitValue } from "./validate-generated-plugin-cli.js";
 import { withWorkspace, workspaceRemovalFailure } from "./workspace.js";
-const PLUGIN_ID = "superpowers@superpowers-manager";
+const PLUGIN_ID = CODEX_MANAGER_PLUGIN_ID;
 const MARKETPLACE_NAME = "superpowers-manager";
-const LEGACY_PLUGIN_ID = "superpowers@superpowers-wrapper";
+const LEGACY_PLUGIN_ID = CODEX_LEGACY_PLUGIN_ID;
 const LEGACY_MARKETPLACE_NAME = "superpowers-wrapper";
 class AdapterFailure extends Error {
     code;
@@ -197,11 +198,8 @@ async function fileExists(path) {
         return false;
     }
 }
-async function runBuild(argv, root, env, log) {
-    const flags = parseFlags(argv, BUILD_FLAGS);
-    const upstreamRoot = flags["--upstream-root"];
-    const candidateRoot = flags["--candidate-root"];
-    const fallbackManifest = flags["--fallback-manifest"];
+async function runBuild(input, env, log) {
+    const { upstreamRoot, candidateRoot, fallbackManifest } = input;
     if (!isAbsolute(upstreamRoot)) {
         fail("invalid-arguments", "--upstream-root must be an absolute path");
     }
@@ -276,7 +274,7 @@ async function runBuild(argv, root, env, log) {
             }
             let overlaid;
             try {
-                overlaid = applyManifestOverlay(source, flags["--manager-version"], candidateManifest);
+                overlaid = applyManifestOverlay(source, input.managerVersion, candidateManifest);
             }
             catch (cause) {
                 // applyManifestOverlay's own messages already name the manifest
@@ -321,13 +319,13 @@ async function runBuild(argv, root, env, log) {
             // on the adapter's surface.
             const splitValues = [
                 { value: candidateRoot, name: "--plugin-root" },
-                { value: flags["--requested-ref"], name: "--requested-ref" },
-                { value: flags["--resolved-ref"], name: "--resolved-ref" },
-                { value: flags["--commit"], name: "--commit" },
-                { value: flags["--manager-version"], name: "--manager-version" },
+                { value: input.requestedRef, name: "--requested-ref" },
+                { value: input.resolvedRef, name: "--resolved-ref" },
+                { value: input.commit, name: "--commit" },
+                { value: input.managerVersion, name: "--manager-version" },
                 { value: manifestSource, name: "--manifest-source" },
                 {
-                    value: flags["--upstream-manifest-version"],
+                    value: input.upstreamManifestVersion,
                     name: "--upstream-manifest-version",
                 },
             ];
@@ -347,12 +345,12 @@ async function runBuild(argv, root, env, log) {
                 errors = await validateGeneratedPlugin({
                     pluginRoot: candidateRoot,
                     source: upstreamSource,
-                    requestedRef: flags["--requested-ref"],
-                    resolvedRef: flags["--resolved-ref"],
-                    commit: flags["--commit"],
-                    manifestVersion: flags["--manager-version"],
+                    requestedRef: input.requestedRef,
+                    resolvedRef: input.resolvedRef,
+                    commit: input.commit,
+                    manifestVersion: input.managerVersion,
                     manifestSource,
-                    upstreamManifestVersion: flags["--upstream-manifest-version"],
+                    upstreamManifestVersion: input.upstreamManifestVersion,
                 });
             }
             catch {
@@ -377,9 +375,7 @@ async function runBuild(argv, root, env, log) {
         throw cause;
     }
 }
-async function runInstall(argv, env, log) {
-    const flags = parseFlags(argv, ["--package-root"]);
-    const packageRoot = flags["--package-root"];
+async function runInstall(packageRoot, env, log) {
     if (!isAbsolute(packageRoot)) {
         fail("invalid-arguments", "--package-root must be an absolute path");
     }
@@ -453,23 +449,15 @@ async function runInstall(argv, env, log) {
         throw cause;
     }
 }
-async function runUninstall(argv, env, log) {
-    const flags = parseFlags(argv, ["--plugin-present", "--marketplace-present"]);
-    const pluginPresent = flags["--plugin-present"];
-    const marketplacePresent = flags["--marketplace-present"];
-    if (pluginPresent !== "true" && pluginPresent !== "false") {
-        fail("invalid-arguments", "--plugin-present must be true or false");
-    }
-    if (marketplacePresent !== "true" && marketplacePresent !== "false") {
-        fail("invalid-arguments", "--marketplace-present must be true or false");
-    }
+async function runUninstall(input, env, log) {
+    const { pluginPresent, marketplacePresent } = input;
     const codexBin = env.SUPERPOWERS_CODEX || "codex";
     await requireCodex(codexBin, env);
     let entered = false;
     try {
         return await withWorkspace(tmpdir(), "superpowers-manager.adapter-uninstall.", async () => {
             entered = true;
-            if (pluginPresent === "true") {
+            if (pluginPresent) {
                 const result = await mutationCommand(log, codexBin, ["plugin", "remove", PLUGIN_ID], env);
                 if (commandFailed(result)) {
                     fail("uninstall-failed", `codex plugin remove failed for ${PLUGIN_ID}`);
@@ -479,7 +467,7 @@ async function runUninstall(argv, env, log) {
             else {
                 log.appendText("stdout", "plugin not installed; skipping");
             }
-            if (marketplacePresent === "true") {
+            if (marketplacePresent) {
                 const result = await mutationCommand(log, codexBin, ["plugin", "marketplace", "remove", MARKETPLACE_NAME], env);
                 if (commandFailed(result)) {
                     fail("uninstall-failed", `codex plugin marketplace remove failed for ${MARKETPLACE_NAME}`);
@@ -499,9 +487,7 @@ async function runUninstall(argv, env, log) {
         throw cause;
     }
 }
-async function runInspect(argv, env, log) {
-    const flags = parseFlags(argv, ["--view"]);
-    const view = flags["--view"];
+async function runInspect(view, context, env, log) {
     if (view === "update-control") {
         return { view: "update-control", update_control: "managed" };
     }
@@ -567,9 +553,11 @@ async function runInspect(argv, env, log) {
                 let legacyPlugin;
                 let managerMarketplace;
                 let legacyMarketplace;
+                let conflicts;
                 try {
                     managerPlugin = installedListingHas(plugins.stdout, "installed", "pluginId", PLUGIN_ID);
                     legacyPlugin = installedListingHas(plugins.stdout, "installed", "pluginId", LEGACY_PLUGIN_ID);
+                    conflicts = await inspectCodexConflicts({ root: context.root, env }, plugins.stdout.toString("utf8"));
                 }
                 catch {
                     fail("inspect-failed", `cannot parse output of '${codexBin} plugin list --json'`);
@@ -600,6 +588,7 @@ async function runInspect(argv, env, log) {
                         : legacyPresent
                             ? "legacy"
                             : "neither",
+                    conflicts: [...conflicts],
                 };
             }, { onCleanupFailure: reportOrphanedWorkspace(log) });
         }
@@ -610,39 +599,95 @@ async function runInspect(argv, env, log) {
             throw cause;
         }
     }
-    fail("invalid-arguments", `unsupported inspect view: ${view}`);
+    const unsupportedView = view;
+    fail("invalid-arguments", `unsupported inspect view: ${unsupportedView}`);
+}
+async function runCodexOperation(operation, context, execute) {
+    const env = { ...process.env, ...context.env };
+    const log = new AdapterMessageLog();
+    try {
+        const result = await execute(env, log);
+        return successResult(operation, result, log.snapshot());
+    }
+    catch (cause) {
+        if (cause instanceof AdapterFailure) {
+            return failureResult(operation, cause.code, cause.message, cause.hints, log.snapshot());
+        }
+        throw cause;
+    }
+}
+export function codexBuild(input, context) {
+    return runCodexOperation("build", context, (env, log) => runBuild(input, env, log));
+}
+export function codexInstall(packageRoot, context) {
+    return runCodexOperation("install", context, (env, log) => runInstall(packageRoot, env, log));
+}
+export function codexRemove(input, context) {
+    return runCodexOperation("uninstall", context, (env, log) => runUninstall(input, env, log));
+}
+export function codexInspect(view, context) {
+    return runCodexOperation("inspect", context, (env, log) => runInspect(view, context, env, log));
 }
 export async function runAdapter(argv, context) {
     const rawOperation = argv[0];
     const operation = rawOperation || "adapter";
     const args = argv.slice(1);
-    const env = { ...process.env, ...context.env };
-    const log = new AdapterMessageLog();
     try {
-        let result;
         if (rawOperation === undefined || rawOperation.length === 0) {
             fail("invalid-arguments", "missing adapter operation");
         }
         else if (operation === "build") {
-            result = await runBuild(args, context.root, env, log);
+            const flags = parseFlags(args, BUILD_FLAGS);
+            return codexBuild({
+                upstreamRoot: flags["--upstream-root"],
+                candidateRoot: flags["--candidate-root"],
+                requestedRef: flags["--requested-ref"],
+                resolvedRef: flags["--resolved-ref"],
+                commit: flags["--commit"],
+                managerVersion: flags["--manager-version"],
+                upstreamManifestVersion: flags["--upstream-manifest-version"],
+                fallbackManifest: flags["--fallback-manifest"],
+            }, context);
         }
         else if (operation === "install") {
-            result = await runInstall(args, env, log);
+            const flags = parseFlags(args, ["--package-root"]);
+            return codexInstall(flags["--package-root"], context);
         }
         else if (operation === "uninstall") {
-            result = await runUninstall(args, env, log);
+            const flags = parseFlags(args, [
+                "--plugin-present",
+                "--marketplace-present",
+            ]);
+            const pluginPresent = flags["--plugin-present"];
+            const marketplacePresent = flags["--marketplace-present"];
+            if (pluginPresent !== "true" && pluginPresent !== "false") {
+                fail("invalid-arguments", "--plugin-present must be true or false");
+            }
+            if (marketplacePresent !== "true" && marketplacePresent !== "false") {
+                fail("invalid-arguments", "--marketplace-present must be true or false");
+            }
+            return codexRemove({
+                pluginPresent: pluginPresent === "true",
+                marketplacePresent: marketplacePresent === "true",
+            }, context);
         }
         else if (operation === "inspect") {
-            result = await runInspect(args, env, log);
+            const flags = parseFlags(args, ["--view"]);
+            const view = flags["--view"];
+            if (view !== "ownership" &&
+                view !== "update-control" &&
+                view !== "fingerprint") {
+                fail("invalid-arguments", `unsupported inspect view: ${view}`);
+            }
+            return codexInspect(view, context);
         }
         else {
             fail("unsupported-operation", `unsupported adapter operation: ${operation}`);
         }
-        return successResult(operation, result, log.snapshot());
     }
     catch (cause) {
         if (cause instanceof AdapterFailure) {
-            return failureResult(operation, cause.code, cause.message, cause.hints, log.snapshot());
+            return failureResult(operation, cause.code, cause.message, cause.hints, []);
         }
         throw cause;
     }

package/dist/artifact-tree.js

@@ -0,0 +1,110 @@
+import { createHash } from "node:crypto";
+import { lstat, readdir, readFile, readlink } from "node:fs/promises";
+import { join } from "node:path";
+import { assertExistingContained, assertNoFollowType, assertSymlinkTargetContained, } from "./safe-path.js";
+import { SafetyError } from "./safety-error.js";
+import { parseStrictJson } from "./strict-json.js";
+import { compareByCodePoint, DEFAULT_FS_DEPS, validateSkillFrontmatter, } from "./generated-plugin.js";
+export const ARTIFACT_RECEIPT = ".superpowers-manager.json";
+export const ARTIFACT_DIGEST_RE = /^[a-f0-9]{64}$/;
+const DECODER = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+export function addArtifactHashField(hash, bytes) {
+    const length = Buffer.alloc(8);
+    length.writeBigUInt64BE(BigInt(bytes.byteLength));
+    hash.update(length);
+    hash.update(bytes);
+}
+export async function readArtifactFile(root, path, limit = 1024 * 1024) {
+    try {
+        await assertExistingContained(root, path);
+        await assertNoFollowType(path, ["regular-file"]);
+        if ((await lstat(path)).size > limit)
+            throw new Error("size");
+        const bytes = await readFile(path);
+        if (bytes.length > limit)
+            throw new Error("size");
+        return bytes;
+    }
+    catch (cause) {
+        throw new SafetyError("artifact", `cannot read bounded artifact file: ${path}`, { cause });
+    }
+}
+export async function readArtifactObject(root, path) {
+    try {
+        const value = parseStrictJson(await readArtifactFile(root, path), {
+            duplicateKeys: "reject",
+            nonStandardConstants: "reject",
+            maxDepth: 64,
+        });
+        if (value === null || typeof value !== "object" || Array.isArray(value))
+            throw new Error("object");
+        return value;
+    }
+    catch (cause) {
+        throw new SafetyError("artifact", `invalid artifact JSON object: ${path}`, {
+            cause,
+        });
+    }
+}
+export async function validateNativeSkill(root) {
+    const path = join(root, "skills", "using-superpowers", "SKILL.md");
+    await readArtifactFile(root, path);
+    const errors = [];
+    await validateSkillFrontmatter(path, "using-superpowers", errors, DEFAULT_FS_DEPS);
+    if (errors.length)
+        throw new SafetyError("artifact", `invalid native bootstrap skill: ${path}`);
+}
+export async function digestArtifactTree(root) {
+    try {
+        await assertNoFollowType(root, ["directory"]);
+        const paths = [];
+        async function visit(relative) {
+            for (const bytes of await readdir(join(root, relative), {
+                encoding: "buffer",
+            })) {
+                const name = DECODER.decode(bytes);
+                const path = relative ? `${relative}/${name}` : name;
+                if (path === ARTIFACT_RECEIPT)
+                    continue;
+                paths.push(path);
+                if ((await lstat(join(root, path))).isDirectory())
+                    await visit(path);
+            }
+        }
+        await visit("");
+        const hash = createHash("sha256");
+        for (const path of paths.sort(compareByCodePoint)) {
+            const absolute = join(root, path), info = await lstat(absolute);
+            let kind, contents;
+            if (info.isDirectory()) {
+                kind = "directory";
+                contents = Buffer.alloc(0);
+            }
+            else if (info.isFile()) {
+                kind = "file";
+                contents = await readFile(absolute);
+            }
+            else if (info.isSymbolicLink()) {
+                await assertSymlinkTargetContained(root, absolute);
+                kind = "link";
+                contents = await readlink(absolute, { encoding: "buffer" });
+                DECODER.decode(contents);
+            }
+            else
+                throw new Error("entry type");
+            for (const bytes of [
+                Buffer.from(kind),
+                Buffer.from(path),
+                Buffer.from(String(info.isFile() ? info.mode & 0o111 : 0)),
+                contents,
+            ])
+                addArtifactHashField(hash, bytes);
+        }
+        return hash.digest("hex");
+    }
+    catch (cause) {
+        throw new SafetyError("artifact", `cannot digest artifact tree: ${root}`, {
+            cause,
+        });
+    }
+}

package/dist/atomic.js

@@ -1,6 +1,6 @@
 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 { basename, dirname, join, resolve } from "node:path";
 import { SafetyError } from "./safety-error.js";
 export async function atomicWriteFile(path, bytes, options) {
     const renamePath = options.hooks?.rename ?? rename;
@@ -92,18 +92,52 @@ async function chooseBackup(live) {
     }
     throw new SafetyError("atomic", "cannot choose unique backup path");
 }
-export async function atomicReplaceDir(candidate, live, options = {}) {
+async function validateRequestedBackup(backup, candidate, live) {
+    const resolvedBackup = resolve(backup);
+    const resolvedCandidate = resolve(candidate);
+    const resolvedLive = resolve(live);
+    const prefix = `.${basename(resolvedLive)}.bak.`;
+    if (dirname(resolvedBackup) !== dirname(resolvedLive) ||
+        !basename(resolvedBackup).startsWith(prefix) ||
+        basename(resolvedBackup).length === prefix.length ||
+        resolvedBackup === resolvedCandidate ||
+        resolvedBackup === resolvedLive ||
+        (await exists(backup))) {
+        throw new Error("invalid directory backup path");
+    }
+}
+async function directoryIdentity(path) {
+    const details = await lstat(path);
+    return { dev: details.dev, ino: details.ino };
+}
+function sameIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+function publicationFailure(message, cause) {
+    return new SafetyError("atomic", message, {
+        cause,
+        details: { phase: "post-replacement" },
+    });
+}
+export async function beginDirectoryPublication(candidate, live, options = {}) {
     const renamePath = options.hooks?.rename ?? rename;
     const removePath = options.hooks?.rm ?? rm;
     let backupCreated = false;
+    let backupIdentity = null;
     let phase = "pre-replacement";
     try {
-        const backup = await chooseBackup(live);
+        const backup = options.backupPath ?? (await chooseBackup(live));
+        if (options.backupPath !== undefined) {
+            await validateRequestedBackup(backup, candidate, live);
+        }
         if (await exists(live)) {
+            backupIdentity = await directoryIdentity(live);
             await renamePath(live, backup);
             backupCreated = true;
         }
+        let publishedIdentity;
         try {
+            publishedIdentity = await directoryIdentity(candidate);
             await renamePath(candidate, live);
             phase = "post-replacement";
         }
@@ -125,14 +159,72 @@ export async function atomicReplaceDir(candidate, live, options = {}) {
             await removePath(candidate, { recursive: true, force: true });
             throw new SafetyError("atomic", "directory activation failed; previous tree restored", { cause, details: { phase: "pre-replacement" } });
         }
-        if (backupCreated) {
+        const retainedBackup = backupCreated ? backup : null;
+        const retainedBackupIdentity = backupCreated ? backupIdentity : null;
+        let settled = false;
+        const claimSettlement = () => {
+            if (settled) {
+                throw publicationFailure("directory publication already settled", new Error("publication already settled"));
+            }
+            settled = true;
+        };
+        const requireRetainedBackup = async (action) => {
+            if (retainedBackup === null)
+                return;
+            let currentIdentity;
             try {
-                await removePath(backup, { recursive: true, force: true });
+                currentIdentity = await directoryIdentity(retainedBackup);
             }
             catch (cause) {
-                throw new SafetyError("atomic", `directory replacement succeeded but backup cleanup failed at ${backup}`, { cause, details: { phase: "post-replacement" } });
+                throw publicationFailure(`directory ${action} refused because backup changed unexpectedly at ${retainedBackup}`, cause);
             }
-        }
+            if (retainedBackupIdentity === null ||
+                !sameIdentity(currentIdentity, retainedBackupIdentity)) {
+                throw publicationFailure(`directory ${action} refused because backup changed unexpectedly at ${retainedBackup}`, new Error("retained backup directory identity changed"));
+            }
+        };
+        return {
+            live,
+            backup: retainedBackup,
+            async finalize() {
+                claimSettlement();
+                if (retainedBackup === null)
+                    return;
+                await requireRetainedBackup("finalization");
+                try {
+                    await removePath(retainedBackup, { recursive: true, force: true });
+                }
+                catch (cause) {
+                    throw publicationFailure(`directory replacement succeeded but backup cleanup failed at ${retainedBackup}`, cause);
+                }
+            },
+            async rollback() {
+                claimSettlement();
+                await requireRetainedBackup("rollback");
+                let currentIdentity;
+                try {
+                    currentIdentity = await directoryIdentity(live);
+                }
+                catch (cause) {
+                    throw publicationFailure(`directory rollback refused because live tree changed unexpectedly at ${live}`, cause);
+                }
+                if (!sameIdentity(currentIdentity, publishedIdentity)) {
+                    throw publicationFailure(`directory rollback refused because live tree changed unexpectedly at ${live}`, new Error("published directory identity changed"));
+                }
+                try {
+                    await removePath(live, { recursive: true, force: true });
+                    if (retainedBackup !== null) {
+                        await renamePath(retainedBackup, live);
+                    }
+                }
+                catch (cause) {
+                    const message = retainedBackup === null
+                        ? "directory rollback failed with no prior tree"
+                        : `directory rollback failed; backup preserved at ${retainedBackup}`;
+                    throw publicationFailure(message, cause);
+                }
+            },
+        };
     }
     catch (cause) {
         if (cause instanceof SafetyError)
@@ -140,3 +232,7 @@ export async function atomicReplaceDir(candidate, live, options = {}) {
         throw new SafetyError("atomic", "directory replacement failed", { cause, details: { phase } });
     }
 }
+export async function atomicReplaceDir(candidate, live, options = {}) {
+    const pending = await beginDirectoryPublication(candidate, live, options);
+    await pending.finalize();
+}

package/dist/cli-arguments.js

@@ -1,5 +1,42 @@
 export class UsageError extends Error {
 }
+export function extractHarnessOptions(command, argv) {
+    let harness = "codex";
+    let targeted = false;
+    let allowExperimental = false;
+    const args = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === "--harness" || token.startsWith("--harness=")) {
+            if (command === "pin" ||
+                command === "unpin" ||
+                command === "track-latest")
+                throw new UsageError("harness targeting is not available for shared selection commands");
+            if (targeted)
+                throw new UsageError("duplicate option: --harness");
+            targeted = true;
+            const value = token === "--harness"
+                ? argv[++index]
+                : token.slice("--harness=".length);
+            if (!value || value.startsWith("--"))
+                throw new UsageError("option --harness requires a value");
+            if (value !== "codex" && value !== "pi")
+                throw new UsageError(`unknown harness: ${value}`);
+            harness = value;
+        }
+        else if (token === "--allow-experimental") {
+            if (command !== "install" && command !== "update")
+                throw new UsageError("--allow-experimental is only available for install or update");
+            if (allowExperimental)
+                throw new UsageError("duplicate option: --allow-experimental");
+            allowExperimental = true;
+        }
+        else {
+            args.push(token);
+        }
+    }
+    return { options: { harness, allowExperimental }, args };
+}
 export function parseFlags(argv, names) {
     const allowed = new Set(names);
     const result = {};