superpowers-manager 0.2.0 → 0.4.0

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-json.js

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

package/dist/codex-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 }, []);
+}