superpowers-manager 0.3.0 → 0.5.0

package/dist/codex-harness.js

@@ -0,0 +1,321 @@
+import { join, resolve } from "node:path";
+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 { SafetyError } from "./safety-error.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 conflictDescriptions(result) {
+    const raw = result.conflicts;
+    if (raw === null || raw === undefined)
+        return [];
+    if (!Array.isArray(raw))
+        return null;
+    const descriptions = [];
+    for (const item of raw) {
+        if (typeof item !== "string" ||
+            item.length === 0 ||
+            hasTerminalControl(item)) {
+            return null;
+        }
+        descriptions.push(item);
+    }
+    return descriptions;
+}
+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 conflicts = conflictDescriptions(record);
+    if (conflicts === null) {
+        return malformed(result, "expected an array of strings at conflicts");
+    }
+    const legacyEligibility = identityState.length === 0
+        ? {
+            kind: "blocked",
+            output: {
+                stdout: [],
+                stderr: ["error: probe did not report adapter identity state"],
+            },
+        }
+        : installDecision(requireNoLegacyState(identityState));
+    const installEligibility = legacyEligibility.kind === "blocked" || conflicts.length === 0
+        ? legacyEligibility
+        : {
+            kind: "blocked",
+            output: {
+                stdout: [],
+                stderr: [
+                    "Conflicting unmanaged Superpowers Codex resources require manual resolution:",
+                    ...conflicts.map((conflict) => `- ${conflict}`),
+                    "Remove or disable each resource manually, then retry.",
+                ],
+            },
+        };
+    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,
+        presentationConflicts: conflicts,
+    }, 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`,
+        },
+    ];
+}
+async function mutationRoots(ctx) {
+    const env = ctx.env ?? {};
+    const configured = env.CODEX_HOME;
+    if (configured !== undefined && configured.length > 0) {
+        return [resolve(configured)];
+    }
+    const home = env.HOME;
+    if (home === undefined || home.length === 0) {
+        throw new SafetyError("codex-harness", "cannot determine Codex state root without HOME");
+    }
+    return [join(resolve(home), ".codex")];
+}
+export const codexHarness = {
+    preparationLocation: codexPreparationLocation,
+    mutationRoots,
+    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-json.js

@@ -59,6 +59,13 @@ function hasTerminalControl(value) {
 export function installedListingHas(raw, arrayKey, field, value) {
     return checkedItems(raw, ACCEPT_CONSTANTS, arrayKey, field).some((item) => item[field] === value);
 }
+export function codexInstalledPluginsFromJson(raw) {
+    return checkedItems(raw, ACCEPT_CONSTANTS, "installed", "pluginId").map((item) => ({
+        pluginId: item.pluginId,
+        installed: typeof item.installed === "boolean" ? item.installed : null,
+        enabled: typeof item.enabled === "boolean" ? item.enabled : null,
+    }));
+}
 export function marketplaceRootFromJson(raw, marketplaceName) {
     const items = checkedItems(raw, ACCEPT_CONSTANTS, "marketplaces", "name");
     const match = items.find((item) => item.name === marketplaceName);

package/dist/codex-prepare.js

@@ -0,0 +1,255 @@
+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 { ARTIFACT_RECEIPT } from "./artifact-tree.js";
+import { assessCodexCompatibility, readCodexAssessment, writeCodexAssessment, } from "./codex-compatibility.js";
+import { readManifest } from "./hooks.js";
+import { readGeneratedCommitLenient, readStrictProvenanceField, writeProvenance, } from "./provenance.js";
+import { classifyPathNoFollow } from "./safe-path.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 unassessedCompatibility() {
+    return {
+        kind: "unknown",
+        reason: "Codex compatibility assessment is not available",
+    };
+}
+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);
+    }
+    const compatibility = await assessCodexCompatibility(input.upstreamRoot, input.selection);
+    if (compatibility.kind === "supported") {
+        try {
+            await writeCodexAssessment(input.candidateRoot, input.selection, (await regularFileExists(join(input.upstreamRoot, ".codex-plugin/plugin.json")))
+                ? "upstream"
+                : "fallback");
+        }
+        catch {
+            return failureResult("prepare", "assessment-failed", `cannot record Codex compatibility assessment: ${input.candidateRoot}`, [], built.outcome.messages);
+        }
+    }
+    return successResult(built.outcome.operation, {
+        root: input.candidateRoot,
+        commit: input.selection.desiredCommit,
+        compatibility,
+        identity: input.selection.desiredCommit,
+    }, built.outcome.messages);
+}
+export async function inspectCodexPrepared(selection, ctx) {
+    const root = codexPreparationLocation(ctx).destinationRoot;
+    const observedIdentity = await readGeneratedCommitLenient(join(root, ".superpowers-upstream.json"));
+    const compatibility = unassessedCompatibility();
+    try {
+        if ((await classifyPathNoFollow(join(root, ARTIFACT_RECEIPT))) === "missing")
+            return successResult("inspect-prepared", {
+                kind: "needs-prepare",
+                observedIdentity,
+                compatibility,
+            }, []);
+        const artifact = await readCodexAssessment(root);
+        const source = await readStrictProvenanceField(join(artifact.root, ".superpowers-upstream.json"), "source");
+        if (artifact.commit === selection.desiredCommit &&
+            source === selection.effectiveSource) {
+            if (artifact.compatibility.kind === "supported")
+                return successResult("inspect-prepared", {
+                    kind: "current",
+                    artifact,
+                    observedIdentity,
+                    compatibility: artifact.compatibility,
+                }, []);
+            return successResult("inspect-prepared", {
+                kind: "needs-prepare",
+                observedIdentity,
+                compatibility: artifact.compatibility,
+            }, []);
+        }
+    }
+    catch {
+        return failureResult("inspect-prepared", "invalid-assessment", `cannot inspect Codex prepared artifact: ${root}`, [], []);
+    }
+    return successResult("inspect-prepared", {
+        kind: "needs-prepare",
+        observedIdentity,
+        compatibility,
+    }, []);
+}
+export async function readCodexPrepared(ctx) {
+    let commit = "";
+    try {
+        const value = await readStrictProvenanceField(join(codexPreparationLocation(ctx).destinationRoot, ".superpowers-upstream.json"), "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", [], []);
+    }
+    try {
+        const artifact = await readCodexAssessment(codexPreparationLocation(ctx).destinationRoot);
+        if (artifact.compatibility.kind !== "supported")
+            throw new Error("unsupported profile");
+        return successResult("read-prepared", artifact, []);
+    }
+    catch {
+        return failureResult("read-prepared", "invalid-assessment", "generated Codex compatibility assessment is missing or invalid", [], []);
+    }
+}