superpowers-manager 0.5.1 → 0.6.0

package/dist/harnesses/codex/publication.js

@@ -0,0 +1,520 @@
+import { lstat, rm } from "node:fs/promises";
+import { failureResult, successResult, } from "../../adapter-result.js";
+import { beginDirectoryPublication, } from "../../atomic.js";
+import { digestArtifactTree } from "../../artifact-tree.js";
+import { assertNoFollowType, classifyPathNoFollow } from "../../safe-path.js";
+import { codexInspectControl, codexInspectOwnership, codexInstallRefreshMode, codexRemove, codexReadNativeState, } from "./adapter.js";
+import { readCodexAssessment } from "./compatibility.js";
+import { readCodexMarketplace, stageCodexMarketplace, } from "./marketplace.js";
+import { assertCodexPreparationSeparate, codexPathFailureDetails, codexPaths, } from "./paths.js";
+import { codexPreparationLocation } from "./prepare.js";
+import { beginCodexRecovery, finishCodexRecovery, readCodexRecovery, verifyCodexRecovery, } from "./recovery.js";
+import { hasFilesystemAccessFailure, pathsEqual } from "./state.js";
+const DEFAULTS = {
+    readNative: codexReadNativeState,
+    inspectOwnership: codexInspectOwnership,
+    inspectControl: codexInspectControl,
+    beginPublication: beginDirectoryPublication,
+};
+const REMOVAL_DEFAULTS = {
+    readNative: codexReadNativeState,
+    removeNative: codexRemove,
+};
+function fail(code, message, messages) {
+    return failureResult("install-codex", code, message, [], messages);
+}
+function removalFailure(code, message, messages) {
+    return failureResult("uninstall-codex", code, message, [], messages);
+}
+function acceptedNative(result) {
+    if (result.status !== 0 || !result.outcome.ok) {
+        throw new Error("Codex native observation failed");
+    }
+    const value = result.outcome.result;
+    if (typeof value.marketplaceRoot !== "string" &&
+        value.marketplaceRoot !== null) {
+        throw new Error("Codex native observation is malformed");
+    }
+    if (typeof value.pluginPresent !== "boolean" ||
+        typeof value.pluginEnabled !== "boolean" ||
+        (typeof value.activeVersion !== "string" && value.activeVersion !== null) ||
+        (typeof value.activeRoot !== "string" && value.activeRoot !== null)) {
+        throw new Error("Codex native observation is malformed");
+    }
+    return value;
+}
+function requireOwnership(result) {
+    if (result.status !== 0 || !result.outcome.ok) {
+        throw new Error("Codex inspection failed");
+    }
+    if (result.outcome.result?.installEligibility?.kind !== "allowed") {
+        throw new Error("Codex ownership blocks publication");
+    }
+}
+function requireControl(result) {
+    if (result.status !== 0 || !result.outcome.ok) {
+        throw new Error("Codex inspection failed");
+    }
+    if (result.outcome.result?.mutationEligibility?.kind !== "allowed") {
+        throw new Error("Codex update control blocks publication");
+    }
+}
+function sameNative(left, right) {
+    return (left.marketplaceRoot === right.marketplaceRoot &&
+        left.pluginPresent === right.pluginPresent &&
+        left.pluginEnabled === right.pluginEnabled &&
+        left.activeVersion === right.activeVersion &&
+        left.activeRoot === right.activeRoot);
+}
+function sameIdentity(snapshot, identity) {
+    return snapshot === null
+        ? identity === null
+        : identity !== null &&
+            snapshot.dev === identity.dev &&
+            snapshot.ino === identity.ino;
+}
+function sameMarketplace(left, right) {
+    return left === null
+        ? right === null
+        : right !== null &&
+            left.dev === right.dev &&
+            left.ino === right.ino &&
+            left.digest === right.digest;
+}
+function nativeAbsent(state) {
+    return (state.marketplaceRoot === null &&
+        !state.pluginPresent &&
+        !state.pluginEnabled &&
+        state.activeVersion === null &&
+        state.activeRoot === null);
+}
+async function sameCapturedMarketplace(root, captured) {
+    try {
+        return sameMarketplace(await readCodexMarketplace(root), captured);
+    }
+    catch {
+        return false;
+    }
+}
+export async function removeCodexMarketplace(_input, ctx, dependencies = REMOVAL_DEFAULTS) {
+    const messages = [];
+    const paths = codexPaths(ctx.env ?? {}, process.cwd());
+    let pending;
+    let captured = null;
+    let nativeAttempted = false;
+    try {
+        if ((await readCodexRecovery(paths)) !== null) {
+            return removalFailure("recovery-required", `Codex recovery is required before mutation; preserve material at ${paths.recoveryRoot}`, messages);
+        }
+    }
+    catch {
+        return removalFailure("recovery-required", `cannot inspect Codex recovery state at ${paths.recoveryRoot}; recovery is required before removal`, messages);
+    }
+    try {
+        const priorNative = await observeNative(ctx, dependencies, messages);
+        captured = await readCodexMarketplace(paths.marketplaceRoot);
+        if (captured !== null) {
+            pending = await beginCodexRecovery(paths, {
+                operation: "uninstall",
+                marketplaceRoot: paths.marketplaceRoot,
+                priorNative,
+                oldDigest: captured.digest,
+                oldIdentity: { dev: captured.dev, ino: captured.ino },
+            });
+        }
+        const beforeRemoval = await observeNative(ctx, dependencies, messages);
+        const marketplaceUnchanged = captured === null ||
+            (await sameCapturedMarketplace(paths.marketplaceRoot, captured));
+        if (!sameNative(beforeRemoval, priorNative) || !marketplaceUnchanged) {
+            if (pending !== undefined && marketplaceUnchanged) {
+                await finishCodexRecovery(pending);
+            }
+            return removalFailure("removal-refused", "Codex native or durable marketplace state changed before removal", messages);
+        }
+        const currentInput = {
+            pluginPresent: beforeRemoval.pluginPresent,
+            marketplacePresent: beforeRemoval.marketplaceRoot !== null,
+        };
+        if (pending !== undefined)
+            await verifyCodexRecovery(pending);
+        nativeAttempted = true;
+        let removed;
+        try {
+            removed = await dependencies.removeNative(currentInput, ctx);
+        }
+        catch {
+            removed = failureResult("uninstall", "native-failed", "Codex native removal threw before returning a result", [], []);
+        }
+        messages.push(...removed.outcome.messages);
+        let afterRemoval;
+        try {
+            afterRemoval = await observeNative(ctx, dependencies, messages);
+        }
+        catch {
+            return removalFailure("recovery-required", pending === undefined
+                ? "Codex deregistration could not be verified"
+                : `Codex deregistration could not be verified; preserve the marketplace and recovery material at ${paths.marketplaceRoot} and ${paths.recoveryRoot}`, messages);
+        }
+        if (removed.status !== 0 || !removed.outcome.ok) {
+            if (pending === undefined && !removed.outcome.ok) {
+                return failureResult(removed.outcome.operation, removed.outcome.error.code, removed.outcome.error.message, removed.outcome.error.hints, messages);
+            }
+            return removalFailure("native-failed", pending === undefined
+                ? "Codex native removal failed"
+                : `Codex native removal failed; preserve the marketplace and recovery material at ${paths.marketplaceRoot} and ${paths.recoveryRoot}`, messages);
+        }
+        if (!nativeAbsent(afterRemoval)) {
+            return removalFailure("recovery-required", pending === undefined
+                ? "Codex deregistration could not be verified"
+                : `Codex deregistration could not be verified; preserve the marketplace and recovery material at ${paths.marketplaceRoot} and ${paths.recoveryRoot}`, messages);
+        }
+        if (pending === undefined || captured === null) {
+            return successResult("uninstall", null, messages);
+        }
+        if (!(await sameCapturedMarketplace(paths.marketplaceRoot, captured))) {
+            return removalFailure("recovery-required", `Codex deregistered, but the durable marketplace changed; preserve recovery material at ${paths.recoveryRoot}`, messages);
+        }
+        try {
+            await verifyCodexRecovery(pending);
+            await rm(paths.marketplaceRoot, { recursive: true });
+        }
+        catch {
+            if (await sameCapturedMarketplace(paths.marketplaceRoot, captured)) {
+                try {
+                    await finishCodexRecovery(pending);
+                    return removalFailure("cleanup-failed", `Codex deregistered, but the owned marketplace could not be removed at ${paths.marketplaceRoot}; retry uninstall to clean it`, messages);
+                }
+                catch {
+                    // Fall through to the unresolved-recovery result below.
+                }
+            }
+            return removalFailure("recovery-required", `Codex deregistered, but durable cleanup could not be completed safely; preserve recovery material at ${paths.recoveryRoot}`, messages);
+        }
+        await finishCodexRecovery(pending);
+        return successResult("uninstall", null, messages);
+    }
+    catch {
+        return removalFailure(pending !== undefined && nativeAttempted
+            ? "recovery-required"
+            : "removal-refused", pending !== undefined
+            ? `Codex removal could not be completed safely; preserve the marketplace and recovery material at ${paths.marketplaceRoot} and ${paths.recoveryRoot}`
+            : `cannot remove Codex marketplace; verify native and durable ownership at ${paths.marketplaceRoot}`, messages);
+    }
+}
+async function activeDigest(state) {
+    if (!state.pluginPresent || state.activeRoot === null)
+        return null;
+    let kind;
+    try {
+        kind = await classifyPathNoFollow(state.activeRoot);
+    }
+    catch (cause) {
+        throw new Error("cannot inspect prior active Codex plugin", { cause });
+    }
+    if (kind === "missing")
+        return null;
+    if (kind !== "directory") {
+        throw new Error("cannot inspect prior active Codex plugin");
+    }
+    try {
+        await readCodexAssessment(state.activeRoot);
+        return await digestArtifactTree(state.activeRoot);
+    }
+    catch (cause) {
+        if (hasFilesystemAccessFailure(cause)) {
+            throw new Error("cannot inspect prior active Codex plugin", { cause });
+        }
+        return null;
+    }
+}
+async function verifyPrepared(artifact, expectedRoot) {
+    if (artifact.root !== expectedRoot)
+        throw new Error("unexpected Codex prepared root");
+    const assessed = await readCodexAssessment(artifact.root);
+    if (assessed.root !== artifact.root ||
+        assessed.commit !== artifact.commit ||
+        assessed.compatibility.kind !== "supported") {
+        throw new Error("Codex prepared artifact changed");
+    }
+    return await digestArtifactTree(artifact.root);
+}
+async function observeNative(ctx, dependencies, messages) {
+    const result = await dependencies.readNative(ctx);
+    messages.push(...result.outcome.messages);
+    return acceptedNative(result);
+}
+async function requireEligibility(ctx, dependencies, messages) {
+    const ownership = await dependencies.inspectOwnership(ctx);
+    messages.push(...ownership.outcome.messages);
+    requireOwnership(ownership);
+    const control = await dependencies.inspectControl(ctx);
+    messages.push(...control.outcome.messages);
+    requireControl(control);
+}
+async function verifyPrevious(pending, previous) {
+    const current = await readCodexMarketplace(pending.paths.marketplaceRoot);
+    if (!sameMarketplace(current, previous)) {
+        throw new Error("previous Codex marketplace changed");
+    }
+}
+async function cleanupBeforePublication(pending, previous, priorNative, ctx, dependencies, messages) {
+    try {
+        if (!sameNative(await observeNative(ctx, dependencies, messages), priorNative)) {
+            return false;
+        }
+        await verifyPrevious(pending, previous);
+        if ((await assertNoFollowType(pending.backup, ["directory", "missing"])) !==
+            "missing") {
+            return false;
+        }
+        const stageKind = await assertNoFollowType(pending.stage, [
+            "directory",
+            "missing",
+        ]);
+        if (stageKind === "directory") {
+            const staged = await readCodexMarketplace(pending.stage);
+            if (staged === null ||
+                !sameIdentity(staged, pending.stageIdentity) ||
+                staged.digest !== pending.newDigest) {
+                return false;
+            }
+            await verifyCodexRecovery(pending);
+            await rm(pending.stage, { recursive: true });
+        }
+        await finishCodexRecovery(pending);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function nativeUnchangedAfterAttempt(prior, priorActiveDigest, current) {
+    if (!sameNative(prior, current))
+        return false;
+    if (!prior.pluginPresent)
+        return true;
+    if (prior.activeRoot === null || priorActiveDigest === null)
+        return false;
+    return (await activeDigest(current)) === priorActiveDigest;
+}
+async function rollbackPublication(pending, publication, previous, priorNative, priorActiveDigest, activationAttempted, ctx, dependencies) {
+    if (pending.settled) {
+        return fail("already-settled", "Codex installation transaction has already been settled", []);
+    }
+    const messages = [];
+    try {
+        const currentNative = await observeNative(ctx, dependencies, messages);
+        if (activationAttempted &&
+            !(await nativeUnchangedAfterAttempt(priorNative, priorActiveDigest, currentNative))) {
+            throw new Error("Codex native state may have changed");
+        }
+        if (!activationAttempted && !sameNative(currentNative, priorNative)) {
+            throw new Error("Codex native state changed before activation");
+        }
+        const published = await readCodexMarketplace(pending.paths.marketplaceRoot);
+        if (published === null ||
+            !sameIdentity(published, pending.publishedIdentity) ||
+            published.digest !== pending.newDigest) {
+            throw new Error("published Codex marketplace changed");
+        }
+        const backup = await readCodexMarketplace(pending.backup);
+        if (!sameMarketplace(backup, previous)) {
+            throw new Error("retained Codex marketplace changed");
+        }
+        await verifyCodexRecovery(pending);
+        await publication.rollback();
+        await verifyPrevious(pending, previous);
+        if (!sameNative(await observeNative(ctx, dependencies, messages), priorNative)) {
+            throw new Error("Codex native state changed during rollback");
+        }
+        await finishCodexRecovery(pending);
+        return successResult("rollback-codex", null, messages);
+    }
+    catch {
+        return fail("recovery-required", `Codex restoration could not be verified; preserve the marketplace and recovery material at ${pending.paths.recoveryRoot} and ${pending.backup}`, messages);
+    }
+}
+async function verifyActivated(pending, dependencies, ctx, messages) {
+    const published = await readCodexMarketplace(pending.paths.marketplaceRoot);
+    if (published === null ||
+        !sameIdentity(published, pending.publishedIdentity) ||
+        published.digest !== pending.newDigest) {
+        throw new Error("published Codex marketplace changed");
+    }
+    const native = await observeNative(ctx, dependencies, messages);
+    if (native.marketplaceRoot === null ||
+        !(await pathsEqual(native.marketplaceRoot, pending.paths.marketplaceRoot)) ||
+        !native.pluginPresent ||
+        !native.pluginEnabled ||
+        native.activeRoot === null) {
+        throw new Error("Codex activation changed");
+    }
+    const active = await readCodexAssessment(native.activeRoot);
+    if (active.commit !== published.artifact.commit ||
+        active.compatibility.kind !== "supported" ||
+        (await digestArtifactTree(active.root)) !==
+            (await digestArtifactTree(published.artifact.root))) {
+        throw new Error("active Codex plugin differs from publication");
+    }
+}
+async function finalizePublication(pending, publication, dependencies, ctx) {
+    if (pending.settled) {
+        return fail("already-settled", "Codex installation transaction has already been settled", []);
+    }
+    const messages = [];
+    let verified = false;
+    let backupRemoved = false;
+    try {
+        await verifyActivated(pending, dependencies, ctx, messages);
+        await verifyCodexRecovery(pending);
+        verified = true;
+        await publication.finalize();
+        backupRemoved = true;
+        await finishCodexRecovery(pending);
+        return successResult("finalize-codex", null, messages);
+    }
+    catch {
+        const detail = backupRemoved
+            ? "activation was verified and backup cleanup completed, but journal retirement failed"
+            : verified
+                ? "activation was verified, but backup or journal cleanup failed"
+                : "activation could not be verified";
+        return fail("recovery-required", `Codex ${detail}; preserve recovery material at ${pending.paths.recoveryRoot} and ${pending.backup}`, messages);
+    }
+}
+export async function installCodexMarketplace(artifact, ctx, activate, dependencies = DEFAULTS) {
+    const messages = [];
+    const effectiveEnv = { ...process.env, ...ctx.env };
+    if (codexInstallRefreshMode(effectiveEnv) === null) {
+        return fail("invalid-arguments", `unsupported SUPERPOWERS_INSTALL_REFRESH_MODE: ${effectiveEnv.SUPERPOWERS_INSTALL_REFRESH_MODE}`, messages);
+    }
+    const paths = codexPaths(ctx.env ?? {}, process.cwd());
+    const preparedRoot = codexPreparationLocation(ctx).destinationRoot;
+    try {
+        await assertCodexPreparationSeparate(preparedRoot, paths);
+    }
+    catch (cause) {
+        const failure = codexPathFailureDetails(cause);
+        if (failure?.kind === "inspection") {
+            if (failure.root === "recovery") {
+                return fail("recovery-required", `cannot inspect Codex recovery state at ${paths.recoveryRoot}; recovery is required before mutation`, messages);
+            }
+            return fail("activation-refused", failure.root === "marketplace"
+                ? `cannot inspect Codex marketplace storage at ${paths.marketplaceRoot}`
+                : `cannot inspect Codex preparation root at ${preparedRoot}`, messages);
+        }
+        return fail(failure?.kind === "overlap"
+            ? "preparation-overlap"
+            : "activation-refused", failure?.kind === "overlap"
+            ? `Codex preparation overlaps Codex published or recovery storage: ${preparedRoot}`
+            : `cannot validate Codex preparation storage separation at ${preparedRoot}`, messages);
+    }
+    let pending;
+    let publication;
+    let previous = null;
+    let priorNative;
+    let priorActiveDigest = null;
+    let activationAttempted = false;
+    try {
+        if ((await readCodexRecovery(paths)) !== null) {
+            return fail("recovery-required", `Codex recovery is required before mutation; preserve material at ${paths.recoveryRoot}`, messages);
+        }
+        const preparedDigest = await verifyPrepared(artifact, preparedRoot);
+        previous = await readCodexMarketplace(paths.marketplaceRoot);
+        priorNative = await observeNative(ctx, dependencies, messages);
+        priorActiveDigest = await activeDigest(priorNative);
+        await requireEligibility(ctx, dependencies, messages);
+        pending = await beginCodexRecovery(paths, {
+            operation: "install",
+            marketplaceRoot: paths.marketplaceRoot,
+            priorNative,
+            oldDigest: previous?.digest ?? null,
+            oldIdentity: previous === null ? null : { dev: previous.dev, ino: previous.ino },
+        });
+        const staged = await stageCodexMarketplace(artifact, ctx.root, pending.stage);
+        pending.newDigest = staged.digest;
+        pending.stageIdentity = { dev: staged.dev, ino: staged.ino };
+        await verifyCodexRecovery(pending);
+        if ((await verifyPrepared(artifact, preparedRoot)) !== preparedDigest) {
+            throw new Error("Codex prepared artifact changed");
+        }
+        await verifyPrevious(pending, previous);
+        if (!sameNative(await observeNative(ctx, dependencies, messages), priorNative)) {
+            throw new Error("Codex native state changed");
+        }
+        await verifyCodexRecovery(pending);
+        publication = await dependencies.beginPublication(pending.stage, paths.marketplaceRoot, { backupPath: pending.backup });
+        if (publication.live !== paths.marketplaceRoot ||
+            publication.backup !== (previous === null ? null : pending.backup)) {
+            throw new Error("Codex publication returned inconsistent paths");
+        }
+        const publishedStat = await lstat(paths.marketplaceRoot);
+        pending.publishedIdentity = {
+            dev: publishedStat.dev,
+            ino: publishedStat.ino,
+        };
+        await verifyCodexRecovery(pending);
+        activationAttempted = true;
+        let activated;
+        try {
+            activated = await activate(paths.marketplaceRoot, ctx);
+        }
+        catch {
+            activated = failureResult("install", "native-failed", "Codex native activation threw before returning a receipt", [], []);
+        }
+        messages.push(...activated.outcome.messages);
+        if (activated.status !== 0 || !activated.outcome.ok) {
+            const settled = await rollbackPublication(pending, publication, previous, priorNative, priorActiveDigest, true, ctx, dependencies);
+            messages.push(...settled.outcome.messages);
+            if (settled.outcome.ok) {
+                return fail("activation-failed", "Codex activation failed; the previous marketplace and native state were restored", messages);
+            }
+            return fail("recovery-required", `Codex activation may have changed native state; preserve recovery material at ${paths.recoveryRoot} and ${pending.backup}`, messages);
+        }
+        await verifyCodexRecovery(pending);
+        const owned = pending;
+        const retained = publication;
+        let transactionSettled = false;
+        const settleOnce = async (action) => {
+            if (transactionSettled) {
+                return fail("already-settled", "Codex installation transaction has already been settled", []);
+            }
+            transactionSettled = true;
+            return await action();
+        };
+        return successResult(activated.outcome.operation, {
+            ...activated.outcome.result,
+            transaction: {
+                finalize: () => settleOnce(() => finalizePublication(owned, retained, dependencies, ctx)),
+                rollback: () => settleOnce(() => rollbackPublication(owned, retained, previous, priorNative, priorActiveDigest, activationAttempted, ctx, dependencies)),
+            },
+        }, messages);
+    }
+    catch {
+        if (pending !== undefined && priorNative !== undefined) {
+            let settled = false;
+            if (publication === undefined) {
+                settled = await cleanupBeforePublication(pending, previous, priorNative, ctx, dependencies, messages);
+            }
+            else {
+                const result = await rollbackPublication(pending, publication, previous, priorNative, priorActiveDigest, activationAttempted, ctx, dependencies);
+                messages.push(...result.outcome.messages);
+                settled = result.outcome.ok;
+            }
+            if (settled) {
+                return fail("activation-refused", `cannot activate Codex artifact ${artifact.root}; previous state was preserved`, messages);
+            }
+            return fail("recovery-required", `Codex mutation requires manual recovery; preserve material at ${paths.recoveryRoot} and ${pending.backup}`, messages);
+        }
+        let unresolved = false;
+        try {
+            unresolved = (await readCodexRecovery(paths)) !== null;
+        }
+        catch {
+            unresolved = true;
+        }
+        return fail(unresolved ? "recovery-required" : "activation-refused", unresolved
+            ? `Codex recovery is required before mutation; preserve material at ${paths.recoveryRoot}`
+            : `cannot activate Codex artifact ${artifact.root}; verify prepared content, ownership, and native state`, messages);
+    }
+}