superpowers-manager 0.8.0 → 0.9.1

package/dist/harnesses/claude-code/harness.js

@@ -0,0 +1,39 @@
+import { displayPath } from "../../validator.js";
+import { installClaudeCode, removeClaudeCode } from "./install.js";
+import { claudeCodePaths } from "./paths.js";
+import { claudeCodePreparationLocation, inspectClaudeCodePrepared, prepareClaudeCodeCandidate, readClaudeCodePrepared, validateClaudeCodePreparationBeforeFetch, } from "./prepare.js";
+import { claudeCodePresentation } from "./presentation.js";
+import { inspectClaudeCodeControl, inspectClaudeCodeInstalled, inspectClaudeCodeOwnership, } from "./state.js";
+function requirements(command, env) {
+    if (command !== "probe" &&
+        command !== "install" &&
+        command !== "update" &&
+        command !== "uninstall")
+        return [];
+    const executable = env.SUPERPOWERS_CLAUDE_CODE || "claude";
+    return [
+        {
+            name: "claude",
+            executable,
+            lookup: "explicit-path-or-path",
+            missingMessage: `required command not found: ${displayPath(executable)} — install Claude Code or set SUPERPOWERS_CLAUDE_CODE`,
+        },
+    ];
+}
+export const claudeCodeHarness = {
+    preparationLocation: claudeCodePreparationLocation,
+    mutationRoots: async (ctx) => [
+        claudeCodePaths(ctx.env ?? {}, process.cwd()).configRoot,
+    ],
+    validatePreparationBeforeFetch: validateClaudeCodePreparationBeforeFetch,
+    prepareCandidate: prepareClaudeCodeCandidate,
+    inspectPrepared: inspectClaudeCodePrepared,
+    readPrepared: readClaudeCodePrepared,
+    inspectOwnership: inspectClaudeCodeOwnership,
+    inspectUpdateControl: inspectClaudeCodeControl,
+    inspectInstalled: inspectClaudeCodeInstalled,
+    install: installClaudeCode,
+    remove: removeClaudeCode,
+    requirements,
+    presentation: claudeCodePresentation,
+};

package/dist/harnesses/claude-code/install.js

@@ -0,0 +1,380 @@
+import { cp, mkdir, mkdtemp, rm, rmdir, unlink } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { readArtifactFile } from "../../artifact-tree.js";
+import { failureResult, successResult, } from "../../adapter-result.js";
+import { atomicWriteFile, beginDirectoryPublication, } from "../../atomic.js";
+import { assertNoFollowType, classifyPathNoFollow, isErrno, } from "../../safe-path.js";
+import { displayPath } from "../../validator.js";
+import { readClaudeCodeState, runClaude, } from "./native.js";
+import { assertClaudeCodeStorageSafe, claudeCodePaths, } from "./paths.js";
+import { readClaudeCodeManifestVersion, readClaudeCodePackageAssessment, } from "./prepare.js";
+import { CLAUDE_CODE_MARKETPLACE, CLAUDE_CODE_MARKETPLACE_BYTES, CLAUDE_CODE_PLUGIN_ID, inspectClaudeCodeMarketplaceStorage, leftoverPublicationMaterial, managerPlugin, marketplaceRegistration, } from "./state.js";
+const DEFAULTS = {
+    run: runClaude,
+    beginPublication: beginDirectoryPublication,
+};
+// Carries only hand-written text; anything else becomes a generic message.
+class ClaudeCodeStep extends Error {
+}
+async function native(run, args, ctx) {
+    const result = await run(args, ctx);
+    if (!result.outcome.ok || result.status !== 0) {
+        const reported = result.outcome.ok
+            ? undefined
+            : /^Claude Code command exited with status ([0-9]{1,3})$/.exec(result.outcome.error.message)?.[1];
+        const exitStatus = reported !== undefined && Number(reported) <= 255
+            ? ` (exit status ${reported})`
+            : "";
+        throw new ClaudeCodeStep(`claude ${displayPath(args.join(" "))} did not complete${exitStatus}`);
+    }
+}
+const MANIFEST_LIMIT = 64 * 1024;
+async function readMarketplaceManifest(paths) {
+    const kind = await classifyPathNoFollow(paths.marketplaceManifest);
+    if (kind === "missing")
+        return null;
+    if (kind !== "regular-file")
+        throw new Error("unverified Claude Code marketplace manifest");
+    return await readArtifactFile(paths.marketplaceRoot, paths.marketplaceManifest, MANIFEST_LIMIT);
+}
+async function createDirectoryIfMissing(path) {
+    if ((await classifyPathNoFollow(path)) !== "missing")
+        return false;
+    try {
+        await mkdir(path);
+        return true;
+    }
+    catch (cause) {
+        if (isErrno(cause, "EEXIST"))
+            return false;
+        throw cause;
+    }
+}
+async function writeMarketplaceManifest(paths) {
+    const path = paths.marketplaceManifest;
+    if ((await readMarketplaceManifest(paths))?.equals(CLAUDE_CODE_MARKETPLACE_BYTES))
+        return;
+    await atomicWriteFile(path, CLAUDE_CODE_MARKETPLACE_BYTES, {
+        validate: async () => {
+            await assertNoFollowType(path, ["regular-file", "missing"]);
+        },
+    });
+}
+async function removeEmptyDirectory(path) {
+    try {
+        await rmdir(path);
+    }
+    catch (cause) {
+        if (!isErrno(cause, "ENOENT"))
+            throw cause;
+    }
+}
+// Restore only bytes and directories this invocation changed. An unexpected
+// replacement or extra entry remains in place and makes rollback fail closed.
+async function restoreMarketplace(paths, before) {
+    const current = await readMarketplaceManifest(paths);
+    if (before.manifest === null) {
+        if (current !== null) {
+            if (!current.equals(CLAUDE_CODE_MARKETPLACE_BYTES))
+                throw new Error("Claude Code marketplace manifest changed");
+            await unlink(paths.marketplaceManifest);
+        }
+    }
+    else if (current === null) {
+        throw new Error("Claude Code marketplace manifest disappeared");
+    }
+    else if (!current.equals(before.manifest)) {
+        if (!current.equals(CLAUDE_CODE_MARKETPLACE_BYTES))
+            throw new Error("Claude Code marketplace manifest changed");
+        await atomicWriteFile(paths.marketplaceManifest, before.manifest, {
+            validate: async () => {
+                await assertNoFollowType(paths.marketplaceManifest, ["regular-file"]);
+            },
+        });
+    }
+    if (before.createdPlugins)
+        await removeEmptyDirectory(paths.pluginsRoot);
+    if (before.createdMetadata)
+        await removeEmptyDirectory(join(paths.marketplaceRoot, ".claude-plugin"));
+    if (before.createdRoot)
+        await removeEmptyDirectory(paths.marketplaceRoot);
+}
+async function removeVerifiedMarketplace(paths) {
+    const storage = await inspectClaudeCodeMarketplaceStorage(paths);
+    if (storage === "absent")
+        return;
+    if (storage !== "owned")
+        throw new Error("unverified Claude Code marketplace storage");
+    if ((await classifyPathNoFollow(paths.pluginRoot)) === "directory")
+        await rm(paths.pluginRoot, { recursive: true, force: false });
+    if ((await classifyPathNoFollow(paths.marketplaceManifest)) === "regular-file")
+        await unlink(paths.marketplaceManifest);
+    for (const path of [
+        paths.pluginsRoot,
+        join(paths.marketplaceRoot, ".claude-plugin"),
+        paths.marketplaceRoot,
+    ])
+        await removeEmptyDirectory(path);
+}
+// Undo native steps relative to what step 1 observed, after the snapshot has
+// already been restored so a rerun `plugin update` records the restored version.
+async function restoreNative(start, refreshed, paths, run, ctx) {
+    const now = await readClaudeCodeState(ctx, run);
+    const scope = ["--scope", "user"];
+    if (start.registration === "absent") {
+        if ((await marketplaceRegistration(now, paths)) === "owned")
+            await native(run, ["plugin", "marketplace", "remove", CLAUDE_CODE_MARKETPLACE], ctx);
+        return;
+    }
+    const plugin = managerPlugin(now);
+    if (start.plugin === undefined) {
+        if (plugin !== undefined)
+            await native(run, ["plugin", "uninstall", CLAUDE_CODE_PLUGIN_ID, ...scope], ctx);
+        return;
+    }
+    if (!start.plugin.enabled && plugin?.enabled === true)
+        await native(run, ["plugin", "disable", CLAUDE_CODE_PLUGIN_ID, ...scope], ctx);
+    if (refreshed)
+        await native(run, ["plugin", "update", CLAUDE_CODE_PLUGIN_ID, ...scope], ctx);
+}
+async function settle(operation, failure, action) {
+    try {
+        await action();
+        return successResult(operation, null, []);
+    }
+    catch {
+        return failureResult(operation, "settlement-failed", failure, [], []);
+    }
+}
+export async function installClaudeCode(artifact, ctx, deps = DEFAULTS) {
+    const operation = "install-claude-code";
+    const paths = claudeCodePaths(ctx.env ?? {}, process.cwd());
+    const scope = ["--scope", "user"];
+    let start;
+    let stageContainer;
+    let publication;
+    let publicationAttempted = false;
+    let refreshed = false;
+    let marketplaceBefore;
+    try {
+        await assertClaudeCodeStorageSafe(paths);
+        if (artifact.root !== paths.preparedRoot)
+            throw new ClaudeCodeStep("unexpected Claude Code prepared root");
+        const assessment = await readClaudeCodePackageAssessment(artifact.root);
+        if (assessment.receipt.digest !== artifact.identity ||
+            assessment.receipt.commit !== artifact.commit ||
+            assessment.compatibility.kind !== "supported")
+            throw new ClaudeCodeStep("the Claude Code prepared artifact changed before activation");
+        const leftovers = await leftoverPublicationMaterial(paths);
+        if (leftovers.length > 0)
+            throw new ClaudeCodeStep(`Claude Code recovery required; inspect leftover publication material at ${displayPath(leftovers[0])}`);
+        const before = await readClaudeCodeState(ctx, deps.run);
+        const observed = {
+            registration: await marketplaceRegistration(before, paths),
+            plugin: managerPlugin(before),
+        };
+        if (observed.registration === "foreign")
+            throw new ClaudeCodeStep(`a foreign ${CLAUDE_CODE_MARKETPLACE} Claude Code marketplace is registered`);
+        if (observed.registration === "absent") {
+            const storage = await inspectClaudeCodeMarketplaceStorage(paths);
+            if (storage === "recovery")
+                throw new ClaudeCodeStep(`Claude Code recovery required; inspect leftover publication material in ${displayPath(paths.pluginsRoot)}`);
+            if (storage === "unverified")
+                throw new ClaudeCodeStep(`unverified Claude Code marketplace storage at ${displayPath(paths.marketplaceRoot)}`);
+        }
+        const conflicting = before.plugins.find((plugin) => plugin.enabled &&
+            plugin.id.startsWith("superpowers@") &&
+            plugin.id !== CLAUDE_CODE_PLUGIN_ID &&
+            plugin.id !== "superpowers@synced");
+        if (conflicting !== undefined) {
+            const action = /^superpowers@[A-Za-z0-9][A-Za-z0-9._-]{0,200}$/.test(conflicting.id)
+                ? `; run claude plugin disable ${conflicting.id} before retrying`
+                : "; inspect and disable the competing plugin before retrying";
+            throw new ClaudeCodeStep(`another Superpowers Claude Code plugin is enabled${action}`);
+        }
+        start = observed;
+        const storageBefore = {
+            manifest: await readMarketplaceManifest(paths),
+            createdRoot: false,
+            createdMetadata: false,
+            createdPlugins: false,
+        };
+        marketplaceBefore = storageBefore;
+        storageBefore.createdRoot = await createDirectoryIfMissing(paths.marketplaceRoot);
+        storageBefore.createdMetadata = await createDirectoryIfMissing(join(paths.marketplaceRoot, ".claude-plugin"));
+        storageBefore.createdPlugins = await createDirectoryIfMissing(paths.pluginsRoot);
+        await assertClaudeCodeStorageSafe(paths);
+        await writeMarketplaceManifest(paths);
+        stageContainer = await mkdtemp(join(paths.pluginsRoot, `.superpowers.stage.${process.pid}.`));
+        const stage = join(stageContainer, "superpowers");
+        await cp(artifact.root, stage, {
+            recursive: true,
+            verbatimSymlinks: true,
+            force: false,
+            errorOnExist: true,
+        });
+        if ((await readClaudeCodePackageAssessment(stage)).receipt.digest !==
+            assessment.receipt.digest)
+            throw new ClaudeCodeStep("the staged Claude Code artifact changed");
+        publicationAttempted = true;
+        publication = await deps.beginPublication(stage, paths.pluginRoot);
+        await rm(stageContainer, { recursive: true, force: true });
+        stageContainer = undefined;
+        if (start.registration === "absent")
+            await native(deps.run, ["plugin", "marketplace", "add", paths.marketplaceRoot], ctx);
+        if (start.plugin === undefined) {
+            await native(deps.run, ["plugin", "install", CLAUDE_CODE_PLUGIN_ID, ...scope], ctx);
+        }
+        else {
+            if (!start.plugin.enabled)
+                await native(deps.run, ["plugin", "enable", CLAUDE_CODE_PLUGIN_ID, ...scope], ctx);
+            // `plugin list` reports the version recorded at install, so a swapped
+            // snapshot leaves it stale until `plugin update` recomputes it.
+            if (start.plugin.version !==
+                (await readClaudeCodeManifestVersion(paths.pluginRoot))) {
+                refreshed = true;
+                await native(deps.run, ["plugin", "update", CLAUDE_CODE_PLUGIN_ID, ...scope], ctx);
+            }
+        }
+        const published = publication;
+        const begun = start;
+        const wasRefreshed = refreshed;
+        const previousMarketplace = marketplaceBefore;
+        const backup = displayPath(published.backup ?? paths.pluginsRoot);
+        return successResult(operation, {
+            missingVerificationOutput: {
+                stdout: [],
+                stderr: [
+                    "error: the Manager Claude Code plugin is not listed after activation",
+                ],
+            },
+            mismatchVerificationOutput: {
+                stdout: [],
+                stderr: [
+                    "error: the installed Claude Code plugin does not match the prepared artifact; run `claude plugin list` to inspect load errors",
+                ],
+            },
+            transaction: {
+                finalize: () => settle(operation, `Claude Code activation succeeded but backup cleanup failed at ${backup}`, () => published.finalize()),
+                rollback: () => settle(operation, `Claude Code rollback did not complete; the previous snapshot may not be restored — inspect ${backup}`, async () => {
+                    await published.rollback();
+                    await restoreNative(begun, wasRefreshed, paths, deps.run, ctx);
+                    await restoreMarketplace(paths, previousMarketplace);
+                }),
+            },
+        }, []);
+    }
+    catch (cause) {
+        const message = cause instanceof ClaudeCodeStep
+            ? cause.message
+            : "cannot activate the Manager-owned Claude Code installation";
+        let restored = !publicationAttempted || publication !== undefined;
+        if (stageContainer !== undefined) {
+            try {
+                await rm(stageContainer, { recursive: true, force: true });
+            }
+            catch {
+                restored = false;
+            }
+        }
+        let snapshotRestored = !publicationAttempted || publication !== undefined;
+        if (publication !== undefined) {
+            try {
+                await publication.rollback();
+            }
+            catch {
+                restored = false;
+                snapshotRestored = false;
+            }
+        }
+        if (snapshotRestored && publication !== undefined && start !== undefined) {
+            try {
+                await restoreNative(start, refreshed, paths, deps.run, ctx);
+            }
+            catch {
+                restored = false;
+            }
+        }
+        if (restored && marketplaceBefore !== undefined) {
+            try {
+                await restoreMarketplace(paths, marketplaceBefore);
+            }
+            catch {
+                restored = false;
+            }
+        }
+        let recoveryPath = marketplaceBefore?.createdRoot
+            ? paths.marketplaceRoot
+            : paths.pluginsRoot;
+        if (!restored) {
+            try {
+                const leftovers = await leftoverPublicationMaterial(paths);
+                recoveryPath =
+                    leftovers.find((path) => basename(path).startsWith(".superpowers.bak.")) ??
+                        leftovers[0] ??
+                        recoveryPath;
+            }
+            catch {
+                // The parent path still gives the operator a bounded inspection target.
+            }
+        }
+        return failureResult(operation, "install-failed", restored
+            ? message
+            : `${message}; the previous Claude Code state may not be restored — inspect ${displayPath(recoveryPath)}`, [], []);
+    }
+}
+export async function removeClaudeCode(input, ctx, deps = DEFAULTS) {
+    const operation = "remove-claude-code";
+    const paths = claudeCodePaths(ctx.env ?? {}, process.cwd());
+    if (input.registration === "foreign")
+        return failureResult(operation, "foreign-marketplace", `refusing to remove a foreign ${CLAUDE_CODE_MARKETPLACE} Claude Code marketplace; remove it manually`, [], []);
+    try {
+        await assertClaudeCodeStorageSafe(paths);
+        // Shared uninstall never consults update control, and deleting the
+        // marketplace would destroy retained recovery material.
+        if ((await leftoverPublicationMaterial(paths)).length > 0)
+            return failureResult(operation, "recovery-required", `Claude Code recovery required; inspect and remove leftover publication material in ${displayPath(paths.pluginsRoot)} before uninstalling`, [], []);
+        const current = await readClaudeCodeState(ctx, deps.run);
+        const registration = await marketplaceRegistration(current, paths);
+        if (registration === "foreign")
+            return failureResult(operation, "foreign-marketplace", `refusing to remove a foreign ${CLAUDE_CODE_MARKETPLACE} Claude Code marketplace; remove it manually`, [], []);
+        const pluginInstalled = managerPlugin(current) !== undefined;
+        const published = (await classifyPathNoFollow(paths.marketplaceRoot)) !== "missing";
+        if (registration !== input.registration ||
+            pluginInstalled !== input.pluginInstalled ||
+            published !== input.published)
+            return failureResult(operation, "stale-ownership", "Claude Code marketplace or plugin state changed before removal; inspect it and retry", [], []);
+        if (published) {
+            const storage = await inspectClaudeCodeMarketplaceStorage(paths);
+            if (storage !== "owned")
+                return failureResult(operation, storage === "recovery"
+                    ? "recovery-required"
+                    : "unverified-marketplace", storage === "recovery"
+                    ? `Claude Code recovery required; inspect and remove leftover publication material in ${displayPath(paths.pluginsRoot)} before uninstalling`
+                    : `refusing to remove unverified Claude Code marketplace storage at ${displayPath(paths.marketplaceRoot)}`, [], []);
+        }
+        if (input.registration === "owned")
+            await native(deps.run, ["plugin", "marketplace", "remove", CLAUDE_CODE_MARKETPLACE], ctx);
+        else if (input.pluginInstalled)
+            await native(deps.run, ["plugin", "uninstall", CLAUDE_CODE_PLUGIN_ID, "--scope", "user"], ctx);
+        if (input.registration === "owned" || input.pluginInstalled) {
+            const after = await readClaudeCodeState(ctx, deps.run);
+            if ((await marketplaceRegistration(after, paths)) !== "absent" ||
+                managerPlugin(after) !== undefined)
+                return failureResult(operation, "removal-unverified", "Claude Code still lists the Manager marketplace or plugin after removal", [], []);
+        }
+    }
+    catch (cause) {
+        return failureResult(operation, "remove-failed", cause instanceof ClaudeCodeStep
+            ? cause.message
+            : "cannot remove the Manager-owned Claude Code registration", [], []);
+    }
+    try {
+        if (input.published)
+            await removeVerifiedMarketplace(paths);
+    }
+    catch {
+        return failureResult(operation, "cleanup-pending", `removed the Claude Code registration; cleanup pending at ${displayPath(paths.marketplaceRoot)}`, [], []);
+    }
+    return successResult(operation, null, []);
+}

package/dist/harnesses/claude-code/native.js

@@ -0,0 +1,79 @@
+import {} from "../../adapter-result.js";
+import { runIsolatedNative, } from "../../harness-command-result.js";
+import { SafetyError } from "../../safety-error.js";
+import { parseStrictJson } from "../../strict-json.js";
+import { BOUNDED_EXECUTABLE, runValidator as runBoundedCommand, } from "../../validator.js";
+// Native list commands include the caller's project and local scope.
+export async function runClaude(args, ctx, execute = runBoundedCommand) {
+    return await runIsolatedNative("Claude Code", (ctx.env ?? {}).SUPERPOWERS_CLAUDE_CODE || "claude", ctx, async (executable, workspace, env, invocationCwd) => await execute([executable, ...args], BOUNDED_EXECUTABLE, { ...env, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1" }, workspace, invocationCwd));
+}
+function listEntries(stdout, subject) {
+    let value;
+    try {
+        value = parseStrictJson(stdout.trim(), {
+            duplicateKeys: "reject",
+            nonStandardConstants: "reject",
+            maxDepth: 64,
+        });
+    }
+    catch (cause) {
+        throw new SafetyError("claude-code-native", `invalid ${subject}`, {
+            cause,
+        });
+    }
+    if (!Array.isArray(value))
+        throw new SafetyError("claude-code-native", `invalid ${subject}`);
+    return value.map((entry) => {
+        if (entry === null || typeof entry !== "object" || Array.isArray(entry))
+            throw new SafetyError("claude-code-native", `invalid ${subject}`);
+        return entry;
+    });
+}
+export function parsePluginList(stdout) {
+    return listEntries(stdout, "Claude Code plugin list").map((entry) => {
+        const { id, version, scope, enabled, installPath, errors } = entry;
+        if (typeof id !== "string" ||
+            typeof version !== "string" ||
+            typeof scope !== "string" ||
+            typeof enabled !== "boolean" ||
+            typeof installPath !== "string" ||
+            (errors !== undefined && !Array.isArray(errors)))
+            throw new SafetyError("claude-code-native", "invalid Claude Code plugin list");
+        return {
+            id,
+            version,
+            scope,
+            enabled,
+            installPath,
+            errorCount: errors === undefined ? 0 : errors.length,
+        };
+    });
+}
+export function parseMarketplaceList(stdout) {
+    return listEntries(stdout, "Claude Code marketplace list").map((entry) => {
+        const { name, source, path } = entry;
+        if (typeof name !== "string" ||
+            typeof source !== "string" ||
+            (path !== undefined && typeof path !== "string"))
+            throw new SafetyError("claude-code-native", "invalid Claude Code marketplace list");
+        return { name, source, path: path ?? null };
+    });
+}
+export async function readClaudeCodeState(ctx, run = runClaude) {
+    try {
+        const plugins = await run(["plugin", "list", "--json"], ctx);
+        const marketplaces = await run(["plugin", "marketplace", "list", "--json"], ctx);
+        if (!plugins.outcome.ok ||
+            plugins.status !== 0 ||
+            !marketplaces.outcome.ok ||
+            marketplaces.status !== 0)
+            throw new Error("native command");
+        return {
+            plugins: parsePluginList(plugins.outcome.result.stdout),
+            marketplaces: parseMarketplaceList(marketplaces.outcome.result.stdout),
+        };
+    }
+    catch (cause) {
+        throw new SafetyError("claude-code-native", "cannot inspect Claude Code plugin state", { cause });
+    }
+}

package/dist/harnesses/claude-code/paths.js

@@ -0,0 +1,35 @@
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { assertNoFollowType } from "../../safe-path.js";
+export function claudeCodePaths(env, cwd) {
+    const configured = env.CLAUDE_CONFIG_DIR;
+    const home = env.HOME && env.HOME.length > 0 ? env.HOME : homedir();
+    const configRoot = configured !== undefined && configured.length > 0
+        ? resolve(cwd, configured)
+        : join(resolve(cwd, home), ".claude");
+    const managerRoot = join(configRoot, "superpowers-manager");
+    const marketplaceRoot = join(managerRoot, "marketplace");
+    const pluginsRoot = join(marketplaceRoot, "plugins");
+    return {
+        configRoot,
+        managerRoot,
+        preparedRoot: join(managerRoot, "prepared"),
+        marketplaceRoot,
+        marketplaceManifest: join(marketplaceRoot, ".claude-plugin", "marketplace.json"),
+        pluginsRoot,
+        pluginRoot: join(pluginsRoot, "superpowers"),
+    };
+}
+// Each owned directory is a real directory or absent; a symlink anywhere in
+// the chain could redirect publication outside the config root.
+export async function assertClaudeCodeStorageSafe(paths) {
+    for (const path of [
+        paths.configRoot,
+        paths.managerRoot,
+        paths.preparedRoot,
+        paths.marketplaceRoot,
+        join(paths.marketplaceRoot, ".claude-plugin"),
+        paths.pluginsRoot,
+    ])
+        await assertNoFollowType(path, ["directory", "missing"]);
+}

package/dist/harnesses/claude-code/prepare.js

@@ -0,0 +1,117 @@
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { applyEdits, modify } from "jsonc-parser";
+import { failureResult, successResult, } from "../../adapter-result.js";
+import { readArtifactFile, readArtifactObject, validateNativeSkill, } from "../../artifact-tree.js";
+import { SEMVER_RE } from "../../domain/refs.js";
+import { classifyPathNoFollow } from "../../safe-path.js";
+import { SafetyError } from "../../safety-error.js";
+import { validateSource } from "../../selection.js";
+import { createSnapshotReceipts, } from "../../snapshot-package.js";
+import { createSnapshotPreparation } from "../../snapshot-prepare.js";
+import { manifestVersionForRef } from "../../upstream-version.js";
+import { assertClaudeCodeStorageSafe, claudeCodePaths } from "./paths.js";
+const CLAUDE_CODE_MANIFEST = ".claude-plugin/plugin.json";
+const GENERATION = "claude-code-native-plugin-v1";
+async function assessClaudeCodeCompatibility(root, selection) {
+    try {
+        validateSource(selection.effectiveSource);
+        const manifest = await readArtifactObject(root, join(root, CLAUDE_CODE_MANIFEST));
+        if (manifest.name !== "superpowers" ||
+            typeof manifest.version !== "string" ||
+            !SEMVER_RE.test(manifest.version))
+            throw new Error("manifest");
+        await validateNativeSkill(root);
+        const hooks = join(root, "hooks", "hooks.json");
+        if ((await classifyPathNoFollow(hooks)) !== "missing")
+            await readArtifactObject(root, hooks);
+        return {
+            kind: "supported",
+            generation: GENERATION,
+            reason: "native Claude Code plugin",
+        };
+    }
+    catch {
+        return {
+            kind: "unsupported",
+            reason: `Claude Code package does not provide a native Claude Code plugin: ${root}`,
+        };
+    }
+}
+// The ref-aware manifest version for this selection. Two selections of the
+// same commit (for example a tag and the raw SHA) yield different versions.
+export function expectedClaudeCodeVersion(selection) {
+    return manifestVersionForRef({
+        requestedRef: selection.requestedRef,
+        resolutionKind: selection.resolutionKind,
+        resolvedRef: selection.resolvedRef,
+        commit: selection.desiredCommit,
+    });
+}
+// A targeted edit of the one value: every other upstream byte, including
+// formatting and unknown fields, is preserved.
+async function rewriteClaudeCodeVersion(root, selection) {
+    const version = expectedClaudeCodeVersion(selection);
+    const path = join(root, CLAUDE_CODE_MANIFEST);
+    await readArtifactObject(root, path);
+    const text = (await readArtifactFile(root, path)).toString("utf8");
+    await writeFile(path, applyEdits(text, modify(text, ["version"], version, {})));
+}
+const receipts = createSnapshotReceipts({
+    harness: "claude-code",
+    label: "Claude Code",
+    strictGeneration: true,
+    assessCompatibility: assessClaudeCodeCompatibility,
+});
+export const readClaudeCodeReceipt = receipts.readReceipt;
+export const readClaudeCodePackageAssessment = receipts.readAssessment;
+export async function readClaudeCodeManifestVersion(root) {
+    const manifest = await readArtifactObject(root, join(root, CLAUDE_CODE_MANIFEST));
+    if (typeof manifest.version !== "string")
+        throw new SafetyError("claude-code-package", `Claude Code manifest has no version: ${root}`);
+    return manifest.version;
+}
+export async function validateClaudeCodePreparationBeforeFetch(ctx) {
+    try {
+        await assertClaudeCodeStorageSafe(claudeCodePaths(ctx.env ?? {}, process.cwd()));
+        return successResult("prepare", null, []);
+    }
+    catch {
+        return failureResult("prepare", "invalid-package", "cannot validate Claude Code artifact storage", [], []);
+    }
+}
+const preparation = createSnapshotPreparation({
+    harness: "claude-code",
+    label: "Claude Code",
+    paths: claudeCodePaths,
+    assessCompatibility: assessClaudeCodeCompatibility,
+    readAssessment: readClaudeCodePackageAssessment,
+    rewrite: rewriteClaudeCodeVersion,
+});
+export const claudeCodePreparationLocation = preparation.preparationLocation;
+export const prepareClaudeCodeCandidate = preparation.prepareCandidate;
+// The shared check compares only commit and source, so a same-commit ref
+// change would otherwise leave a prepared tree carrying the old version.
+export async function inspectClaudeCodePrepared(selection, ctx) {
+    const result = await preparation.inspectPrepared(selection, ctx);
+    if (!result.outcome.ok || result.outcome.result.kind !== "current")
+        return result;
+    const root = result.outcome.result.artifact.root;
+    try {
+        if ((await readClaudeCodeManifestVersion(root)) ===
+            expectedClaudeCodeVersion(selection))
+            return result;
+    }
+    catch {
+        return failureResult("inspect-prepared", "invalid-package", `cannot inspect Claude Code prepared artifact: ${root}`, [], []);
+    }
+    return successResult("inspect-prepared", {
+        kind: "needs-prepare",
+        observedIdentity: result.outcome.result.observedIdentity,
+        compatibility: {
+            kind: "unknown",
+            reason: "Claude Code prepared version does not match the selection",
+        },
+    }, []);
+}
+export const readClaudeCodePrepared = preparation.readPrepared;