superpowers-manager 0.3.0 → 0.5.0

package/dist/cli.js

@@ -1,7 +1,10 @@
+#!/usr/bin/env node
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { runAdapter } from "./adapter.js";
-import { oneLine } from "./cli-arguments.js";
+import { extractHarnessOptions, oneLine, UsageError } from "./cli-arguments.js";
+import { codexHarness } from "./codex-harness.js";
+import { piHarness } from "./pi-harness.js";
+import { createResourceCoordinator } from "./resource-lock.js";
 import { runInstall } from "./commands/install.js";
 import { runPin } from "./commands/pin.js";
 import { runPrepare } from "./commands/prepare.js";
@@ -46,15 +49,15 @@ const IN_PROCESS_HANDLERS = {
 // 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 = {
+const SHARED_COMMAND_REQUIREMENTS = {
     pin: ["git"],
     "track-latest": [],
     unpin: [],
     prepare: ["git"],
-    probe: ["git", "codex"],
-    install: ["git", "codex"],
-    update: ["git", "codex"],
-    uninstall: ["codex"],
+    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
@@ -84,14 +87,28 @@ function isMain(moduleFilename, argvPath) {
 function parseArgs(argv) {
     const first = argv[0];
     if (argv.length === 0)
-        return { kind: "run", cmd: "update", args: [] };
+        return {
+            kind: "run",
+            cmd: "update",
+            args: [],
+            options: { harness: "codex", allowExperimental: false },
+        };
     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);
+        let extracted;
+        try {
+            extracted = extractHarnessOptions(command, argv.slice(1));
+        }
+        catch (cause) {
+            if (cause instanceof UsageError)
+                return { kind: "usage-error", message: cause.message };
+            throw cause;
+        }
+        const { args, options } = extracted;
         if (command === "pin" && args.length !== 1) {
             return {
                 kind: "usage-error",
@@ -127,7 +144,7 @@ function parseArgs(argv) {
                 message: "usage: superpowers-manager probe [--porcelain]",
             };
         }
-        return { kind: "run", cmd: command, args };
+        return { kind: "run", cmd: command, args, options };
     }
     return { kind: "usage-error", message: `unknown subcommand: ${first}` };
 }
@@ -160,40 +177,61 @@ function findTool(name, env, platform) {
 // 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;
+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 {
-        ...COMMAND_REQUIREMENTS,
-        prepare: [...COMMAND_REQUIREMENTS.prepare, "python3"],
+        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 preflight(cmd, env, platform) {
+function preflightFor(cmd, env, platform, adapter) {
     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`);
-        }
+    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...]",
@@ -210,6 +248,14 @@ function usage() {
         "  update     probe, then prepare/install only if needed (default when no subcommand)",
         "  uninstall  remove the manager plugin and marketplace from Codex",
         "",
+        "Target one invocation (default: codex; selection commands are shared):",
+        "  probe --harness pi [--porcelain]",
+        "  prepare --harness pi",
+        "  install --harness pi [--allow-experimental]",
+        "  update --harness pi [--allow-experimental]",
+        "  uninstall --harness pi",
+        "  --harness=codex and --harness=pi are also accepted after the command.",
+        "",
         "Environment overrides (used by in-process commands): SUPERPOWERS_REF,",
         "SUPERPOWERS_UPSTREAM_URL, SUPERPOWERS_CODEX, SUPERPOWERS_CACHE_DIR,",
         "SUPERPOWERS_CONFIG_DIR, XDG_CONFIG_HOME,",
@@ -242,11 +288,22 @@ async function main() {
         console.error(usage());
         process.exit(2);
     }
-    const pf = preflight(parsed.cmd, process.env, process.platform);
+    const status = parsed.options.harness === "pi"
+        ? await dispatch(piHarness, parsed)
+        : await dispatch(codexHarness, parsed);
+    process.exit(status);
+}
+async function dispatch(adapter, parsed) {
+    const root = resolvePackageRoot(import.meta.filename);
+    if (!root) {
+        console.error("error: cannot resolve the superpowers-manager package root");
+        return 1;
+    }
+    const pf = preflightFor(parsed.cmd, process.env, process.platform, adapter);
     if (!pf.ok) {
         for (const e of pf.errors)
             console.error(`error: ${e}`);
-        process.exit(1);
+        return 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
@@ -259,17 +316,17 @@ async function main() {
     const handler = IN_PROCESS_HANDLERS[parsed.cmd];
     if (!handler) {
         console.error(`error: no in-process handler registered for: ${parsed.cmd}`);
-        process.exit(1);
+        return 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,
+        options: parsed.options,
+        coordination: createResourceCoordinator(),
+        // The ONLY production binding of a concrete harness implementation.
+        adapter,
     };
     let status;
     try {
@@ -280,11 +337,11 @@ async function main() {
         // 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);
+        return 1;
     }
-    process.exit(status);
+    return status;
 }
-export { resolvePackageRoot, isMain, parseArgs, findTool, commandRequirements, preflight, usage, main, };
+export { resolvePackageRoot, isMain, parseArgs, findTool, commandRequirements, commandRequirementsFor, preflight, preflightFor, usage, dispatch, main, };
 if (isMain(import.meta.filename, process.argv[1])) {
     main().catch((cause) => {
         console.error(`error: ${oneLine(cause)}`);

package/dist/codex-compatibility.js

@@ -0,0 +1,126 @@
+import { join } from "node:path";
+import { validateNativeSkill } from "./artifact-tree.js";
+import { classifyPathNoFollow, assertExistingContained } from "./safe-path.js";
+import { classifyHooks, readManifest } from "./hooks.js";
+import { SEMVER_RE } from "./generated-plugin.js";
+import { validateSource } from "./selection.js";
+import { writeFile } from "node:fs/promises";
+import { ARTIFACT_DIGEST_RE, ARTIFACT_RECEIPT, digestArtifactTree, readArtifactObject, } from "./artifact-tree.js";
+import { COMMIT_RE } from "./domain/refs.js";
+import { validateGeneratedPlugin } from "./generated-plugin.js";
+import { SafetyError } from "./safety-error.js";
+export async function writeCodexAssessment(root, selection, manifestSource) {
+    const receipt = {
+        schema: 1,
+        manager: "superpowers-manager",
+        harness: "codex",
+        source: selection.effectiveSource,
+        commit: selection.desiredCommit,
+        generation: "codex-native-skills-v1",
+        manifestSource,
+        digest: await digestArtifactTree(root),
+    };
+    await writeFile(join(root, ARTIFACT_RECEIPT), JSON.stringify(receipt) + "\n", { flag: "wx" });
+}
+export async function readCodexAssessment(root) {
+    try {
+        const receipt = await readArtifactObject(root, join(root, ARTIFACT_RECEIPT));
+        const provenance = await readArtifactObject(root, join(root, ".superpowers-upstream.json"));
+        if (receipt.schema !== 1 ||
+            receipt.manager !== "superpowers-manager" ||
+            receipt.harness !== "codex" ||
+            receipt.generation !== "codex-native-skills-v1" ||
+            typeof receipt.source !== "string" ||
+            typeof receipt.commit !== "string" ||
+            !COMMIT_RE.test(receipt.commit) ||
+            typeof receipt.digest !== "string" ||
+            !ARTIFACT_DIGEST_RE.test(receipt.digest) ||
+            (receipt.manifestSource !== "upstream" &&
+                receipt.manifestSource !== "fallback") ||
+            receipt.source !== provenance.source ||
+            receipt.commit !== provenance.commit)
+            throw new Error("assessment fields");
+        validateSource(receipt.source);
+        if ((await digestArtifactTree(root)) !== receipt.digest)
+            throw new Error("assessment digest");
+        const manifest = await readManifest(join(root, ".codex-plugin/plugin.json"));
+        if (typeof manifest.version !== "string" ||
+            typeof provenance.requested_ref !== "string" ||
+            typeof provenance.resolved_ref !== "string" ||
+            typeof provenance.upstream_manifest_version !== "string")
+            throw new Error("provenance fields");
+        const errors = await validateGeneratedPlugin({
+            pluginRoot: root,
+            source: receipt.source,
+            commit: receipt.commit,
+            requestedRef: provenance.requested_ref,
+            resolvedRef: provenance.resolved_ref,
+            upstreamManifestVersion: provenance.upstream_manifest_version,
+            manifestVersion: manifest.version,
+            manifestSource: receipt.manifestSource,
+        });
+        if (errors.length)
+            throw new Error("generated resources");
+        const selection = {
+            effectiveSource: receipt.source,
+            desiredCommit: receipt.commit,
+            requestedRef: provenance.requested_ref,
+            resolvedRef: provenance.resolved_ref,
+            resolutionKind: "raw-commit",
+            selectionOrigin: "package-default",
+            selectionMode: "default",
+            upstreamSourceOrigin: "package-default",
+            saved: {
+                saved_mode: "none",
+                saved_source: "",
+                saved_requested_ref: "",
+                saved_resolved_ref: "",
+                saved_commit: "",
+            },
+        };
+        const compatibility = await assessCodexCompatibility(root, selection);
+        return {
+            root,
+            commit: receipt.commit,
+            identity: receipt.commit,
+            compatibility,
+        };
+    }
+    catch (cause) {
+        throw new SafetyError("codex-compatibility", `invalid Codex prepared assessment: ${root}`, { cause });
+    }
+}
+export async function assessCodexCompatibility(root, selection) {
+    try {
+        validateSource(selection.effectiveSource);
+        await validateNativeSkill(root);
+        for (const path of [
+            ".codex/superpowers-codex",
+            ".codex/superpowers-bootstrap.md",
+        ]) {
+            if ((await classifyPathNoFollow(join(root, path))) !== "missing")
+                throw new Error("legacy bootstrap");
+        }
+        const path = join(root, ".codex-plugin/plugin.json");
+        if ((await classifyPathNoFollow(path)) !== "missing") {
+            await assertExistingContained(root, path);
+            const manifest = await readManifest(path);
+            if (manifest.name !== "superpowers" ||
+                typeof manifest.version !== "string" ||
+                !SEMVER_RE.test(manifest.version))
+                throw new Error("manifest");
+            await classifyHooks(manifest, "upstream", root);
+        }
+        return {
+            kind: "supported",
+            generation: "codex-native-skills-v1",
+            reason: "native Codex skill discovery",
+        };
+    }
+    catch {
+        return {
+            kind: "unsupported",
+            reason: `Codex package does not provide compatible native skill discovery: ${root}`,
+        };
+    }
+}

package/dist/codex-conflicts.js

@@ -0,0 +1,99 @@
+import { lstat, readFile, realpath, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { codexInstalledPluginsFromJson, } from "./codex-json.js";
+export const CODEX_MANAGER_PLUGIN_ID = "superpowers@superpowers-manager";
+export const CODEX_LEGACY_PLUGIN_ID = "superpowers@superpowers-wrapper";
+const SUPERPOWERS_PLUGIN_PREFIX = "superpowers@";
+const DISPLAYABLE_PLUGIN_ID = /^superpowers@[A-Za-z0-9][A-Za-z0-9._-]*/;
+const NATIVE_ROUTE = ".agents/skills/superpowers";
+const NATIVE_ROUTE_CONFLICT = `native Codex skills route ~/${NATIVE_ROUTE} has indeterminate activity`;
+function isMissingPath(cause) {
+    if (cause === null || typeof cause !== "object" || !("code" in cause)) {
+        return false;
+    }
+    return cause.code === "ENOENT" || cause.code === "ENOTDIR";
+}
+function isUnmanagedPluginId(pluginId) {
+    if (pluginId === CODEX_MANAGER_PLUGIN_ID ||
+        pluginId === CODEX_LEGACY_PLUGIN_ID) {
+        return false;
+    }
+    return (pluginId.startsWith(SUPERPOWERS_PLUGIN_PREFIX) &&
+        pluginId.length > SUPERPOWERS_PLUGIN_PREFIX.length);
+}
+function displayablePluginId(pluginId) {
+    return pluginId.length <= 256 &&
+        DISPLAYABLE_PLUGIN_ID.exec(pluginId)?.[0] === pluginId
+        ? pluginId
+        : "";
+}
+function unmanagedPluginConflict(plugin) {
+    if (!isUnmanagedPluginId(plugin.pluginId))
+        return "";
+    const displayId = displayablePluginId(plugin.pluginId);
+    const subject = displayId.length > 0
+        ? `Codex plugin ${displayId}`
+        : "Codex plugin with a non-displayable Superpowers identity";
+    if (plugin.installed === true && plugin.enabled === true) {
+        return `active ${subject}`;
+    }
+    if ((plugin.installed === true && plugin.enabled === false) ||
+        (plugin.installed === false && plugin.enabled === false)) {
+        return "";
+    }
+    return `${subject} has indeterminate activity`;
+}
+async function nativeRouteConflict(ctx) {
+    const home = ctx.env?.HOME;
+    if (home === undefined || home.length === 0)
+        return NATIVE_ROUTE_CONFLICT;
+    const route = join(home, ".agents", "skills", "superpowers");
+    const asset = join(route, "using-superpowers", "SKILL.md");
+    let routeIsSymlink;
+    try {
+        routeIsSymlink = (await lstat(route)).isSymbolicLink();
+    }
+    catch (cause) {
+        return isMissingPath(cause) ? "" : NATIVE_ROUTE_CONFLICT;
+    }
+    if (!routeIsSymlink) {
+        try {
+            await lstat(asset);
+        }
+        catch (cause) {
+            return isMissingPath(cause) ? "" : NATIVE_ROUTE_CONFLICT;
+        }
+    }
+    try {
+        const resolvedAsset = await realpath(asset);
+        if (!(await stat(resolvedAsset)).isFile())
+            return NATIVE_ROUTE_CONFLICT;
+        const contents = await readFile(resolvedAsset, "utf8");
+        const lines = contents.split(/\r?\n/u);
+        if (lines[0] !== "---")
+            return "";
+        const end = lines.indexOf("---", 1);
+        if (end < 0 ||
+            !lines
+                .slice(1, end)
+                .some((line) => /^name:[ \t]+using-superpowers[ \t]*$/u.test(line))) {
+            return "";
+        }
+    }
+    catch {
+        return NATIVE_ROUTE_CONFLICT;
+    }
+    return NATIVE_ROUTE_CONFLICT;
+}
+export async function inspectCodexConflicts(ctx, installedListing) {
+    const conflicts = new Set();
+    for (const plugin of codexInstalledPluginsFromJson(installedListing)) {
+        const conflict = unmanagedPluginConflict(plugin);
+        if (conflict.length > 0)
+            conflicts.add(conflict);
+    }
+    const nativeConflict = await nativeRouteConflict(ctx);
+    if (nativeConflict.length > 0)
+        conflicts.add(nativeConflict);
+    return [...conflicts];
+}