superpowers-manager 0.3.0 → 0.4.0

package/dist/cli.js

@@ -1,7 +1,8 @@
+#!/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 { codexHarness } from "./codex-harness.js";
 import { runInstall } from "./commands/install.js";
 import { runPin } from "./commands/pin.js";
 import { runPrepare } from "./commands/prepare.js";
@@ -46,15 +47,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
@@ -160,40 +161,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 {
-        ...COMMAND_REQUIREMENTS,
-        prepare: [...COMMAND_REQUIREMENTS.prepare, "python3"],
+        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 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...]",
@@ -266,10 +288,8 @@ async function main() {
         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,
+        // The ONLY production binding of a concrete harness implementation.
+        adapter: codexHarness,
     };
     let status;
     try {
@@ -284,7 +304,7 @@ async function main() {
     }
     process.exit(status);
 }
-export { resolvePackageRoot, isMain, parseArgs, findTool, commandRequirements, preflight, usage, main, };
+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)}`);

package/dist/codex-harness.js

@@ -0,0 +1,271 @@
+import { failureResult, hasTerminalControl, successResult, } from "./adapter-result.js";
+import { codexInspect, codexInstall, codexRemove, } from "./adapter.js";
+import { codexPreparationLocation, inspectCodexPrepared, prepareCodexCandidate, readCodexPrepared, validateCodexPreparationBeforeFetch, } from "./codex-prepare.js";
+import { codexInstallReceipt, codexPresentation, } from "./codex-presentation.js";
+import { reportLegacyState, requireManagedUpdateControl, requireNoLegacyState, verifyUninstalledResources, } from "./lifecycle.js";
+import { commitMatches } from "./status.js";
+function preserveFailure(result) {
+    if (result.outcome.ok) {
+        throw new Error("cannot preserve a successful adapter result as failure");
+    }
+    return { status: result.status, outcome: result.outcome };
+}
+function malformed(result, message) {
+    return failureResult(result.outcome.operation, "malformed-result", message, [], result.outcome.messages);
+}
+function invalidStatus(result, message) {
+    return failureResult(result.outcome.operation, "invalid-status", message, [], result.outcome.messages);
+}
+function resultRecord(result) {
+    const value = result.outcome.ok ? result.outcome.result : null;
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+function stringField(result, key) {
+    const raw = result[key];
+    if (raw === null || raw === undefined)
+        return { ok: true, value: "" };
+    if (typeof raw === "string")
+        return { ok: true, value: raw };
+    return { ok: false };
+}
+function resourceFlag(result, key) {
+    const resources = result.resources;
+    const bag = typeof resources === "object" &&
+        resources !== null &&
+        !Array.isArray(resources)
+        ? resources
+        : {};
+    const value = bag[key];
+    return typeof value === "boolean" ? value : null;
+}
+function installDecision(legacy) {
+    switch (legacy.kind) {
+        case "ok":
+            return { kind: "allowed" };
+        case "blocked":
+            return {
+                kind: "blocked",
+                output: { stdout: [], stderr: legacy.lines },
+            };
+        case "unknown":
+            return {
+                kind: "blocked",
+                output: { stdout: [], stderr: [`error: ${legacy.message}`] },
+            };
+        case "report":
+            return {
+                kind: "blocked",
+                output: {
+                    stdout: [],
+                    stderr: ["error: unexpected legacy report during installation"],
+                },
+            };
+    }
+}
+export function normalizeCodexOwnership(result) {
+    if (!result.outcome.ok)
+        return preserveFailure(result);
+    if (result.status !== 0) {
+        return invalidStatus(result, "adapter reported a failure status for inspect --view ownership");
+    }
+    const record = resultRecord(result);
+    if (record === null) {
+        return malformed(result, "adapter returned a non-object result for inspect --view ownership");
+    }
+    const pluginPresent = resourceFlag(record, "plugin");
+    if (pluginPresent === null) {
+        return malformed(result, "expected a Boolean adapter result at resources.plugin");
+    }
+    const marketplacePresent = resourceFlag(record, "marketplace");
+    if (marketplacePresent === null) {
+        return malformed(result, "expected a Boolean adapter result at resources.marketplace");
+    }
+    const identity = stringField(record, "identity_state");
+    if (!identity.ok) {
+        return malformed(result, "adapter returned a non-string identity_state for inspect --view ownership");
+    }
+    const identityState = identity.value;
+    const installEligibility = identityState.length === 0
+        ? {
+            kind: "blocked",
+            output: {
+                stdout: [],
+                stderr: ["error: probe did not report adapter identity state"],
+            },
+        }
+        : installDecision(requireNoLegacyState(identityState));
+    const verification = verifyUninstalledResources(result);
+    const legacyReport = reportLegacyState(identityState);
+    let removalVerification;
+    if (!verification.ok) {
+        removalVerification = {
+            kind: "blocked",
+            output: { stdout: [], stderr: [`error: ${verification.message}`] },
+        };
+    }
+    else if (legacyReport.kind === "unknown") {
+        removalVerification = {
+            kind: "blocked",
+            output: { stdout: [], stderr: [`error: ${legacyReport.message}`] },
+        };
+    }
+    else if (legacyReport.kind === "blocked") {
+        removalVerification = {
+            kind: "blocked",
+            output: {
+                stdout: [],
+                stderr: ["error: unexpected legacy block after removal"],
+            },
+        };
+    }
+    else {
+        removalVerification = { kind: "allowed" };
+    }
+    const postRemovalOutput = legacyReport.kind === "report"
+        ? { stdout: legacyReport.lines, stderr: [] }
+        : { stdout: [], stderr: [] };
+    return successResult(result.outcome.operation, {
+        installEligibility,
+        removalInput: { pluginPresent, marketplacePresent },
+        removalVerification,
+        postRemovalOutput,
+        presentationValue: identityState,
+    }, result.outcome.messages);
+}
+export function normalizeCodexControl(result) {
+    if (!result.outcome.ok)
+        return preserveFailure(result);
+    if (result.status !== 0) {
+        return invalidStatus(result, "adapter reported a failure status for inspect --view update-control");
+    }
+    const record = resultRecord(result);
+    if (record === null) {
+        return malformed(result, "adapter returned a non-object result for inspect --view update-control");
+    }
+    const control = stringField(record, "update_control");
+    if (!control.ok) {
+        return malformed(result, "adapter returned a non-string update_control for inspect --view update-control");
+    }
+    const updateControl = control.value;
+    const probeEligibility = updateControl.length === 0
+        ? {
+            kind: "blocked",
+            output: {
+                stdout: [],
+                stderr: [
+                    "error: probe did not report adapter update-control capability",
+                ],
+            },
+        }
+        : { kind: "allowed" };
+    const managed = requireManagedUpdateControl(updateControl);
+    const mutationEligibility = probeEligibility.kind === "blocked"
+        ? probeEligibility
+        : managed.ok
+            ? { kind: "allowed" }
+            : {
+                kind: "blocked",
+                output: {
+                    stdout: [],
+                    stderr: [`error: ${managed.message}`],
+                },
+            };
+    return successResult(result.outcome.operation, { probeEligibility, mutationEligibility, presentationValue: updateControl }, result.outcome.messages);
+}
+export function normalizeCodexInstalled(result, desiredCommit) {
+    if (!result.outcome.ok)
+        return preserveFailure(result);
+    if (result.status !== 0) {
+        return invalidStatus(result, "adapter reported a failure status for inspect --view fingerprint");
+    }
+    const record = resultRecord(result);
+    if (record === null) {
+        return malformed(result, "adapter returned a non-object result for inspect --view fingerprint");
+    }
+    const fingerprint = stringField(record, "fingerprint");
+    if (!fingerprint.ok) {
+        return malformed(result, "adapter returned a non-string fingerprint for inspect --view fingerprint");
+    }
+    const observedIdentity = fingerprint.value;
+    const installed = observedIdentity.length === 0
+        ? { kind: "absent", observedIdentity: "" }
+        : commitMatches(desiredCommit, observedIdentity)
+            ? { kind: "current", observedIdentity }
+            : { kind: "mismatch", observedIdentity };
+    return successResult(result.outcome.operation, installed, result.outcome.messages);
+}
+function safeHint(value) {
+    return typeof value === "string" && !hasTerminalControl(value) ? value : "";
+}
+export function normalizeCodexInstall(result) {
+    if (!result.outcome.ok)
+        return preserveFailure(result);
+    if (result.status !== 0) {
+        return invalidStatus(result, "adapter reported a failure status for install");
+    }
+    const record = resultRecord(result);
+    if (record === null) {
+        return malformed(result, "adapter returned a non-object result for install");
+    }
+    const hints = record.verification_hints;
+    const bag = typeof hints === "object" && hints !== null && !Array.isArray(hints)
+        ? hints
+        : {};
+    return successResult(result.outcome.operation, codexInstallReceipt(safeHint(bag.missing), safeHint(bag.mismatch)), result.outcome.messages);
+}
+// The canonical payload normalizer has no context parameter. Keep the native
+// call's defensive success/nonzero-status guard beside the concrete adapter,
+// where the exact legacy diagnostic can still name ctx.root.
+export function normalizeCodexInstallForContext(result, ctx) {
+    if (!result.outcome.ok)
+        return preserveFailure(result);
+    if (result.status !== 0) {
+        return invalidStatus(result, codexPresentation.callFailure("install", ctx).invalidStatus);
+    }
+    return normalizeCodexInstall(result);
+}
+function requirements(command, env) {
+    if (command !== "probe" &&
+        command !== "install" &&
+        command !== "update" &&
+        command !== "uninstall") {
+        return [];
+    }
+    const executable = env.SUPERPOWERS_CODEX || "codex";
+    return [
+        {
+            name: "codex",
+            executable,
+            lookup: "explicit-path-or-path",
+            missingMessage: `required command not found: ${executable} — install the Codex CLI or set SUPERPOWERS_CODEX`,
+        },
+    ];
+}
+export const codexHarness = {
+    preparationLocation: codexPreparationLocation,
+    validatePreparationBeforeFetch: validateCodexPreparationBeforeFetch,
+    prepareCandidate: prepareCodexCandidate,
+    inspectPrepared: inspectCodexPrepared,
+    readPrepared: readCodexPrepared,
+    inspectOwnership: async (ctx) => normalizeCodexOwnership(await codexInspect("ownership", ctx)),
+    inspectUpdateControl: async (ctx) => normalizeCodexControl(await codexInspect("update-control", ctx)),
+    inspectInstalled: async (selection, ctx) => normalizeCodexInstalled(await codexInspect("fingerprint", ctx), selection.desiredCommit),
+    install: async (_artifact, ctx) => {
+        return normalizeCodexInstallForContext(await codexInstall(ctx.root, ctx), ctx);
+    },
+    remove: async (input, ctx) => {
+        const result = await codexRemove(input, ctx);
+        if (!result.outcome.ok)
+            return preserveFailure(result);
+        if (result.status !== 0) {
+            return invalidStatus(result, codexPresentation.callFailure("remove", ctx, input).invalidStatus);
+        }
+        return successResult(result.outcome.operation, null, result.outcome.messages);
+    },
+    requirements,
+    get presentation() {
+        return codexPresentation;
+    },
+};

package/dist/codex-prepare.js

@@ -0,0 +1,199 @@
+import { cp, mkdir, rm, stat } from "node:fs/promises";
+import { isAbsolute, join, resolve } from "node:path";
+import { failureResult, successResult, } from "./adapter-result.js";
+import { codexBuild } from "./adapter.js";
+import { commitMatches } from "./domain/fingerprint.js";
+import { readManifest } from "./hooks.js";
+import { generatedCommitOrEmpty, generatedMetadataPath, readStrictProvenanceField, writeProvenance, } from "./provenance.js";
+import { SafetyError } from "./safety-error.js";
+import { manifestVersionForRef } from "./upstream-version.js";
+// Order is inherited from the original prepare command; the first miss wins.
+const REQUIRED_UPSTREAM = [
+    { path: "skills", label: "skills/" },
+    { path: "LICENSE", label: "LICENSE" },
+    { path: "README.md", label: "README.md" },
+    { path: "CODE_OF_CONDUCT.md", label: "CODE_OF_CONDUCT.md" },
+];
+const COPY_PATHS = [
+    "skills",
+    "assets",
+    "LICENSE",
+    "README.md",
+    "CODE_OF_CONDUCT.md",
+];
+const RESOLUTION_KINDS = [
+    "latest-release",
+    "tag",
+    "ref",
+    "raw-commit",
+];
+function prepareError(message, cause) {
+    return new SafetyError("prepare", message, { cause });
+}
+function isControlledPreparationError(cause) {
+    return (cause instanceof SafetyError &&
+        (cause.module === "prepare" ||
+            cause.module === "hooks" ||
+            cause.module === "provenance"));
+}
+async function pathExists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function regularFileExists(path) {
+    try {
+        return (await stat(path)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function owned(message, fn) {
+    try {
+        return await fn();
+    }
+    catch (cause) {
+        throw prepareError(message, cause);
+    }
+}
+async function copyPathIfPresent(source, destination) {
+    if (!(await pathExists(source)))
+        return;
+    await owned(`cannot clear candidate path: ${destination}`, () => rm(destination, { recursive: true, force: true }));
+    await owned(`cannot copy upstream path into candidate: ${source}`, () => cp(source, destination, { recursive: true, verbatimSymlinks: true }));
+}
+export function resolveFromCwd(value, cwd) {
+    return isAbsolute(value) ? value : resolve(cwd, value);
+}
+function manifestTemplate(ctx) {
+    const env = ctx.env ?? {};
+    return (env.SUPERPOWERS_MANIFEST_TEMPLATE ||
+        join(ctx.root, "plugins", "superpowers", ".codex-plugin", "plugin.template.json"));
+}
+export function codexPreparationLocation(ctx) {
+    const env = ctx.env ?? {};
+    return {
+        destinationRoot: resolveFromCwd(env.SUPERPOWERS_PLUGIN_ROOT || join(ctx.root, "plugins", "superpowers"), process.cwd()),
+        stagingLeaf: "superpowers",
+    };
+}
+export async function validateCodexPreparationBeforeFetch(ctx) {
+    const template = manifestTemplate(ctx);
+    if (!(await regularFileExists(template))) {
+        return failureResult("prepare", "missing-template", `missing fallback manifest template: ${template}`, [], []);
+    }
+    return successResult("prepare", null, []);
+}
+export async function readUpstreamManifestVersion(path) {
+    const manifest = await readManifest(path);
+    const value = manifest.version;
+    if (value === undefined || value === null)
+        return "";
+    if (typeof value !== "string") {
+        throw prepareError(`upstream manifest version is not a string: ${path}`);
+    }
+    return value;
+}
+function asResolutionKind(value) {
+    for (const kind of RESOLUTION_KINDS) {
+        if (kind === value)
+            return kind;
+    }
+    throw prepareError(`unknown upstream resolution kind: ${value}`);
+}
+export async function prepareCodexCandidate(input, ctx) {
+    let upstreamManifestVersion = "";
+    let managerVersion = "";
+    try {
+        for (const required of REQUIRED_UPSTREAM) {
+            if (!(await pathExists(join(input.upstreamRoot, required.path)))) {
+                return failureResult("prepare", "missing-upstream-path", `required upstream path missing: ${required.label}`, [], []);
+            }
+        }
+        await owned(`cannot clear candidate root: ${input.candidateRoot}`, () => rm(input.candidateRoot, { recursive: true, force: true }));
+        await owned(`cannot create candidate root: ${input.candidateRoot}`, () => mkdir(join(input.candidateRoot, ".codex-plugin"), { recursive: true }));
+        for (const name of COPY_PATHS) {
+            await copyPathIfPresent(join(input.upstreamRoot, name), join(input.candidateRoot, name));
+        }
+        const upstreamManifest = join(input.upstreamRoot, ".codex-plugin", "plugin.json");
+        if (await regularFileExists(upstreamManifest)) {
+            upstreamManifestVersion =
+                await readUpstreamManifestVersion(upstreamManifest);
+        }
+        await writeProvenance(join(input.candidateRoot, ".superpowers-upstream.json"), {
+            source: input.selection.effectiveSource,
+            requested_ref: input.selection.requestedRef,
+            resolved_ref: input.selection.resolvedRef,
+            commit: input.selection.desiredCommit,
+            upstream_manifest_version: upstreamManifestVersion,
+        });
+        managerVersion = manifestVersionForRef({
+            requestedRef: input.selection.requestedRef,
+            resolutionKind: asResolutionKind(input.selection.resolutionKind),
+            resolvedRef: input.selection.resolvedRef,
+            commit: input.selection.desiredCommit,
+        });
+    }
+    catch (cause) {
+        // owned()/asResolutionKind(), readManifest(), and writeProvenance replace
+        // every subordinate failure with controlled preparation, hook, or
+        // provenance text. Re-emitting those owned diagnostics is therefore safe.
+        // codexBuild stays below this catch because it deliberately rethrows
+        // exceptions its native operation does not own; the shared command must
+        // hide those.
+        if (!isControlledPreparationError(cause))
+            throw cause;
+        return failureResult("prepare", "prepare-failed", cause.message, [], []);
+    }
+    const built = await codexBuild({
+        upstreamRoot: input.upstreamRoot,
+        candidateRoot: input.candidateRoot,
+        requestedRef: input.selection.requestedRef,
+        resolvedRef: input.selection.resolvedRef,
+        commit: input.selection.desiredCommit,
+        managerVersion,
+        upstreamManifestVersion,
+        fallbackManifest: manifestTemplate(ctx),
+    }, ctx);
+    if (!built.outcome.ok) {
+        return { status: built.status, outcome: built.outcome };
+    }
+    if (built.status !== 0) {
+        return failureResult("build", "invalid-status", "adapter reported failure without an error outcome", [], built.outcome.messages);
+    }
+    return successResult(built.outcome.operation, { root: input.candidateRoot, commit: input.selection.desiredCommit }, built.outcome.messages);
+}
+export async function inspectCodexPrepared(selection, ctx) {
+    const observedIdentity = await generatedCommitOrEmpty(ctx.root);
+    if (!commitMatches(selection.desiredCommit, observedIdentity)) {
+        return successResult("inspect-prepared", { kind: "needs-prepare", observedIdentity }, []);
+    }
+    return successResult("inspect-prepared", {
+        kind: "current",
+        artifact: {
+            root: join(ctx.root, "plugins", "superpowers"),
+            commit: observedIdentity,
+        },
+        observedIdentity,
+    }, []);
+}
+export async function readCodexPrepared(ctx) {
+    let commit = "";
+    try {
+        const value = await readStrictProvenanceField(generatedMetadataPath(ctx.root), "commit");
+        if (typeof value === "string")
+            commit = value;
+    }
+    catch {
+        // The install path treats malformed metadata as an absent commit.
+    }
+    if (commit.length === 0) {
+        return failureResult("read-prepared", "missing-commit", "generated metadata missing desired commit after prepare", [], []);
+    }
+    return successResult("read-prepared", { root: join(ctx.root, "plugins", "superpowers"), commit }, []);
+}