superpowers-manager 0.8.0 → 0.9.0

package/README.md

@@ -1,6 +1,6 @@
 # Superpowers Manager
 
-Install [`obra/superpowers`](https://github.com/obra/superpowers) directly from upstream for Codex, the Pi coding agent, and OpenCode. Stay on a known-good release or commit, try a branch, and upgrade when you choose—without waiting for a marketplace copy to catch up.
+Install [`obra/superpowers`](https://github.com/obra/superpowers) directly from upstream for Codex, the Pi coding agent, OpenCode, and Claude Code. Stay on a known-good release or commit, try a branch, and upgrade when you choose—without waiting for a marketplace copy to catch up.
 
 > Unofficial community integration. Not affiliated with the `obra/superpowers` maintainers.
 
@@ -21,7 +21,7 @@ npx superpowers-manager pin v6.1.1
 npx superpowers-manager install --harness codex
 ```
 
-Use `--harness pi` for Pi or `--harness opencode` for OpenCode. The pin is shared by all harnesses, but each installation changes only when you run its `install` or `update` command. A saved pin keeps subsequent installs and updates on that version unless you change or override the selection.
+Use `--harness pi` for Pi, `--harness opencode` for OpenCode, or `--harness claude-code` for Claude Code. The pin is shared by all harnesses, but each installation changes only when you run its `install` or `update` command. A saved pin keeps subsequent installs and updates on that version unless you change or override the selection.
 
 To try a branch, replace `feature/foo` with an existing upstream branch:
 
@@ -42,7 +42,7 @@ See [version selection](https://github.com/j7an/superpowers-manager/blob/main/do
 
 ## Start with your agent
 
-The three harnesses share upstream selection, while each has independent prepared and installed state. Omitting `--harness` selects Codex.
+The four harnesses share upstream selection, while each has independent prepared and installed state. Omitting `--harness` selects Codex.
 
 ### Codex
 
@@ -84,6 +84,19 @@ OpenCode after a successful install, activating update, or removal. See the
 [OpenCode reference](https://github.com/j7an/superpowers-manager/blob/main/docs/opencode.md)
 for global configuration, conflicts, and recovery behavior.
 
+### Claude Code
+
+```sh
+npx superpowers-manager install --harness claude-code
+npx superpowers-manager probe --harness claude-code
+npx superpowers-manager update --harness claude-code
+```
+
+Claude Code installs a validated, Manager-owned local marketplace snapshot.
+Restart Claude Code or run `/reload-plugins` after an install, activating update,
+or removal. See the [Claude Code reference](https://github.com/j7an/superpowers-manager/blob/main/docs/claude-code.md)
+for conflicts, hooks, and recovery.
+
 To remove a Manager-owned installation, choose one harness explicitly:
 
 ### Uninstall Codex
@@ -104,23 +117,30 @@ npx superpowers-manager uninstall --harness pi
 npx superpowers-manager uninstall --harness opencode
 ```
 
+### Uninstall Claude Code
+
+```sh
+npx superpowers-manager uninstall --harness claude-code
+```
+
 The manager never removes another Superpowers provider. See the [ownership guidance](https://github.com/j7an/superpowers-manager/blob/main/docs/usage.md#provider-ownership) before switching providers.
 
 ## Shared selection and lifecycle
 
-The [selection commands above](#choose-what-you-run) save shared upstream intent. They do not activate Codex, Pi, or OpenCode; run the selected harness's `install` or `update` to apply that choice. `unpin` restores the packaged fallback policy.
+The [selection commands above](#choose-what-you-run) save shared upstream intent. They do not activate Codex, Pi, OpenCode, or Claude Code; run the selected harness's `install` or `update` to apply that choice. `unpin` restores the packaged fallback policy.
 
 See [targeted lifecycle commands](https://github.com/j7an/superpowers-manager/blob/main/docs/usage.md#targeted-lifecycle) for preparation, inspection, installation, updates, and removal.
 
-Use `--harness codex`, `--harness pi`, or `--harness opencode` with each targeted lifecycle command.
+Use `--harness codex`, `--harness pi`, `--harness opencode`, or `--harness claude-code` with each targeted lifecycle command.
 
 ```text
 shared selection -> prepare / inspect / activate Codex
                  -> prepare / inspect / activate Pi
                  -> prepare / inspect / activate OpenCode
+                 -> prepare / inspect / activate Claude Code
 ```
 
-The [usage reference](https://github.com/j7an/superpowers-manager/blob/main/docs/usage.md) covers version selection, precedence, offline behavior, `prepare`, validators, and every lifecycle command. The harness references cover [Codex registration and hooks](https://github.com/j7an/superpowers-manager/blob/main/docs/codex.md) and [Pi snapshots and recovery](https://github.com/j7an/superpowers-manager/blob/main/docs/pi.md).
+The [usage reference](https://github.com/j7an/superpowers-manager/blob/main/docs/usage.md) covers version selection, precedence, offline behavior, `prepare`, validators, and every lifecycle command. The harness references cover [Codex registration and hooks](https://github.com/j7an/superpowers-manager/blob/main/docs/codex.md), [Pi snapshots and recovery](https://github.com/j7an/superpowers-manager/blob/main/docs/pi.md), [OpenCode snapshots](https://github.com/j7an/superpowers-manager/blob/main/docs/opencode.md), and [Claude Code marketplace registration](https://github.com/j7an/superpowers-manager/blob/main/docs/claude-code.md).
 
 ## Requirements and platforms
 
@@ -128,16 +148,16 @@ The installed package requires Node >=24. Native source, tests, and packaging to
 
 <!-- requirements:begin -->
 
-| Command        | git | Codex CLI (default) | Pi CLI (`--harness pi`) | OpenCode CLI (`--harness opencode`) |
-| -------------- | --- | ------------------- | ----------------------- | ----------------------------------- |
-| `pin`          | yes | no                  | no                      | no                                  |
-| `track-latest` | no  | no                  | no                      | no                                  |
-| `unpin`        | no  | no                  | no                      | no                                  |
-| `prepare`      | yes | no                  | no                      | no                                  |
-| `probe`        | yes | yes                 | no                      | no                                  |
-| `install`      | yes | yes                 | yes                     | yes                                 |
-| `update`       | yes | yes                 | yes                     | yes                                 |
-| `uninstall`    | no  | yes                 | yes                     | no                                  |
+| Command        | git | Codex CLI (default) | Pi CLI (`--harness pi`) | OpenCode CLI (`--harness opencode`) | Claude Code CLI (`--harness claude-code`) |
+| -------------- | --- | ------------------- | ----------------------- | ----------------------------------- | ----------------------------------------- |
+| `pin`          | yes | no                  | no                      | no                                  | no                                        |
+| `track-latest` | no  | no                  | no                      | no                                  | no                                        |
+| `unpin`        | no  | no                  | no                      | no                                  | no                                        |
+| `prepare`      | yes | no                  | no                      | no                                  | no                                        |
+| `probe`        | yes | yes                 | no                      | no                                  | yes                                       |
+| `install`      | yes | yes                 | yes                     | yes                                 | yes                                       |
+| `update`       | yes | yes                 | yes                     | yes                                 | yes                                       |
+| `uninstall`    | no  | yes                 | yes                     | no                                  | yes                                       |
 
 <!-- requirements:end -->
 

package/dist/atomic.js

@@ -17,9 +17,7 @@ export async function atomicWriteFile(path, bytes, options) {
                 break;
             }
             catch (cause) {
-                if (cause instanceof Error &&
-                    "code" in cause &&
-                    cause.code === "EEXIST") {
+                if (isErrno(cause, "EEXIST")) {
                     continue;
                 }
                 throw cause;

package/dist/cli-arguments.js

@@ -20,7 +20,10 @@ export function extractHarnessOptions(command, argv) {
                 : token.slice("--harness=".length);
             if (!value || value.startsWith("--"))
                 throw new UsageError("option --harness requires a value");
-            if (value !== "codex" && value !== "pi" && value !== "opencode")
+            if (value !== "codex" &&
+                value !== "pi" &&
+                value !== "opencode" &&
+                value !== "claude-code")
                 throw new UsageError(`unknown harness: ${value}`);
             harness = value;
         }

package/dist/cli.js

@@ -3,6 +3,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { extractHarnessOptions, oneLine, UsageError } from "./cli-arguments.js";
 import { codexHarness } from "./harnesses/codex/harness.js";
+import { claudeCodeHarness } from "./harnesses/claude-code/harness.js";
 import { piHarness } from "./harnesses/pi/harness.js";
 import { openCodeHarness } from "./harnesses/opencode/harness.js";
 import { createResourceCoordinator } from "./resource-lock.js";
@@ -16,23 +17,8 @@ import { runUnpin } from "./commands/unpin.js";
 import { runUpdate } from "./commands/update.js";
 import { COMMIT_INPUT_RE, TAG_RE } from "./domain/refs.js";
 import { configurationErrors } from "./validator.js";
-const SUBCOMMANDS = [
-    "pin",
-    "track-latest",
-    "unpin",
-    "prepare",
-    "probe",
-    "install",
-    "update",
-    "uninstall",
-];
-// Keyed by Subcommand itself. Until slice 6 this was keyed by a mapped type
-// that filtered Subcommand through a DISPATCH table of "spawn" | "in-process"
-// literals; with every command in-process that filter was the identity, so the
-// table, its mode union and the mapped type were one indirection with nothing
-// left to discriminate. The guarantee is unchanged and is the whole protection
-// — tests/bin/bin-dispatch.test.js records that decision: a Subcommand added
-// without a handler registered here is a compile error, not a runtime surprise.
+// Keyed by HarnessCommand: a command added to that type without a handler
+// here is a compile error, not a runtime surprise.
 const IN_PROCESS_HANDLERS = {
     pin: runPin,
     "track-latest": runTrackLatest,
@@ -98,7 +84,7 @@ function parseArgs(argv) {
         return { kind: "help" };
     if (first === "--version")
         return { kind: "version" };
-    if (first && SUBCOMMANDS.includes(first)) {
+    if (first && Object.hasOwn(IN_PROCESS_HANDLERS, first)) {
         const command = first;
         let extracted;
         try {
@@ -228,7 +214,7 @@ function usage() {
         "  install --harness opencode [--allow-experimental]",
         "  update --harness opencode [--allow-experimental]",
         "  uninstall --harness opencode",
-        "  --harness=codex, --harness=pi, and --harness=opencode are also accepted after the command.",
+        "  --harness=codex, --harness=pi, --harness=opencode, and --harness=claude-code are also accepted after the command.",
         "",
         "Environment overrides (used by in-process commands): SUPERPOWERS_REF,",
         "SUPERPOWERS_UPSTREAM_URL, SUPERPOWERS_CODEX, SUPERPOWERS_CACHE_DIR,",
@@ -236,7 +222,7 @@ function usage() {
         "SUPERPOWERS_PLUGIN_ROOT, SUPERPOWERS_MANIFEST_TEMPLATE,",
         "SUPERPOWERS_VALIDATOR_EXECUTABLE,",
         "SUPERPOWERS_INSTALLED_SEARCH_ROOT, SUPERPOWERS_INSTALL_REFRESH_MODE,",
-        "SUPERPOWERS_OPENCODE",
+        "SUPERPOWERS_OPENCODE, SUPERPOWERS_CLAUDE_CODE, CLAUDE_CONFIG_DIR",
         "",
         "SUPERPOWERS_VALIDATOR is removed; unset it and use",
         "SUPERPOWERS_VALIDATOR_EXECUTABLE with an executable validator.",
@@ -266,38 +252,23 @@ async function main() {
         console.error(usage());
         process.exit(2);
     }
-    const status = parsed.options.harness === "opencode"
-        ? await dispatch(openCodeHarness, parsed)
-        : parsed.options.harness === "pi"
-            ? await dispatch(piHarness, parsed)
-            : await dispatch(codexHarness, parsed);
+    const status = parsed.options.harness === "claude-code"
+        ? await dispatch(claudeCodeHarness, parsed, root)
+        : parsed.options.harness === "opencode"
+            ? await dispatch(openCodeHarness, parsed, root)
+            : parsed.options.harness === "pi"
+                ? await dispatch(piHarness, parsed, root)
+                : await dispatch(codexHarness, parsed, root);
     process.exit(status);
 }
-async function dispatch(adapter, parsed) {
-    const root = resolvePackageRoot(import.meta.filename);
-    if (!root) {
-        console.error("error: cannot resolve the superpowers-manager package root");
-        return 1;
-    }
+async function dispatch(adapter, parsed, root) {
     const pf = preflight(parsed.cmd, process.env, process.platform, adapter);
     if (!pf.ok) {
         for (const e of pf.errors)
             console.error(`error: ${e}`);
         return 1;
     }
-    // Dispatch is no longer a branch: slice 4b flipped the last spawned command,
-    // so every subcommand runs here, and slice 6 deleted the DISPATCH table whose
-    // only remaining job was narrowing this registry's key type. `parsed.cmd` is
-    // a Subcommand and the registry is keyed by Subcommand, so no cast is needed.
-    // The exhaustiveness check on IN_PROCESS_HANDLERS makes an unregistered
-    // handler a compile error; the `!handler` guard below is the runtime backstop
-    // for that guarantee. It is unreachable through production code, and no
-    // fixture reaches it either.
     const handler = IN_PROCESS_HANDLERS[parsed.cmd];
-    if (!handler) {
-        console.error(`error: no in-process handler registered for: ${parsed.cmd}`);
-        return 1;
-    }
     const ctx = {
         root,
         env: process.env,

package/dist/commands/adapter-call.js

@@ -26,3 +26,27 @@ export class GatherFailure extends Error {
         this.outcomes = outcomes;
     }
 }
+export function writeOutput(output, ctx) {
+    for (const line of output.stdout)
+        ctx.stdout.write(`${line}\n`);
+    for (const line of output.stderr)
+        ctx.stderr.write(`${line}\n`);
+}
+// callAdapter plus outcome collection: every returned result's outcome is
+// recorded for replay. acceptValue turns a successful value it rejects into an
+// invalid status without recording that outcome.
+export async function invoke(call, failure, outcomes, acceptValue) {
+    let result = await callAdapter(call, failure);
+    if (result.ok && acceptValue !== undefined) {
+        try {
+            if (!acceptValue(result.result.outcome.result))
+                result = { ok: false, result: null, message: failure.invalidStatus };
+        }
+        catch {
+            result = { ok: false, result: null, message: failure.invalidStatus };
+        }
+    }
+    if (result.result !== null)
+        outcomes.push(result.result.outcome);
+    return result;
+}

package/dist/commands/install.js

@@ -1,40 +1,21 @@
 import { tmpdir } from "node:os";
 import { oneLine } from "../cli-arguments.js";
-import { withWorkspace, workspaceRemovalFailure } from "../workspace.js";
-import { GatherFailure, callAdapter, } from "./adapter-call.js";
-import { gatherProbe, replayOutcome } from "./probe.js";
+import { withWorkspaceReporting, } from "../workspace.js";
+import { GatherFailure, invoke, writeOutput } from "./adapter-call.js";
+import { probeFacts, replayOutcome } from "./probe.js";
 import { runPrepare } from "./prepare.js";
 import { runWithMutation } from "./mutation.js";
 import { activationBlock } from "../harness-compatibility.js";
-export function writeOutput(output, ctx) {
-    for (const line of output.stdout)
-        ctx.stdout.write(`${line}\n`);
-    for (const line of output.stderr)
-        ctx.stderr.write(`${line}\n`);
-}
-async function invoke(call, failure, outcomes, acceptValue) {
-    let result = await callAdapter(call, failure);
-    if (result.ok && acceptValue !== undefined) {
-        try {
-            if (!acceptValue(result.result.outcome.result))
-                result = { ok: false, result: null, message: failure.invalidStatus };
-        }
-        catch {
-            result = { ok: false, result: null, message: failure.invalidStatus };
-        }
-    }
-    if (result.result !== null)
-        outcomes.push(result.result.outcome);
-    return result;
-}
 // Collect outcomes without writing so output failures cannot be classified as
 // inspection failures. Replay collected outcomes after gathering completes.
+// The callback never throws: invoke() catches every ctx.adapter failure and
+// every predicate here is pure, so a post-success cleanup failure is the only
+// case withWorkspaceReporting's cleanupWarning has to carry.
 async function gatherInstallStages(ctx, selection, artifact) {
     const parent = ctx.env.TMPDIR ?? tmpdir();
     const outcomes = [];
-    let cleanupWarning = null;
     try {
-        const outcome = await withWorkspace(parent, "superpowers-manager.install.", async (workspace) => {
+        return await withWorkspaceReporting(parent, "superpowers-manager.install.", async (workspace) => {
             const env = { ...ctx.env, TMPDIR: workspace };
             const failed = (message) => ({
                 kind: "failed",
@@ -187,53 +168,25 @@ async function gatherInstallStages(ctx, selection, artifact) {
                 stdout: output.stdout,
                 stderr: output.stderr,
             };
-        }, {
-            // Suppresses withWorkspace's throw on a POST-SUCCESS cleanup failure,
-            // so the StageOutcome the callback already computed still comes back
-            // as `outcome` below instead of being discarded. `report` runs
-            // synchronously, as the option requires (src/workspace.ts).
-            onCleanupFailure: (path) => {
-                cleanupWarning = workspaceRemovalFailure(path);
-            },
         });
-        return { outcome, cleanupWarning };
     }
     catch (cause) {
-        // Reachable only for mkdtemp failure (nothing collected yet) -- the
-        // callback above never throws, so a post-success cleanup failure is
-        // already handled by onCleanupFailure and cannot reach here.
+        // Reachable only for mkdtemp failure (nothing collected yet): the
+        // callback never throws, and a post-success cleanup failure comes back
+        // as cleanupWarning.
         throw new GatherFailure("install gather failed", cause, outcomes);
     }
 }
 export async function runInstall(argv, ctx) {
     if (ctx.adapter.presentation.installNotice !== "")
         ctx.stdout.write(`${ctx.adapter.presentation.installNotice}\n`);
-    return await runWithMutation("install", ctx, async (scoped) => performInstall(argv, scoped));
+    // argv is ignored: scripts/install never reads "$@".
+    return await runWithMutation("install", ctx, async (scoped) => performInstall(scoped));
 }
-async function performInstall(argv, ctx) {
-    // scripts/install never reads "$@", so extra arguments are silently
-    // ignored -- the same asymmetry runPrepare and runUninstall document.
-    void argv;
-    let probe;
-    try {
-        probe = await gatherProbe(ctx);
-    }
-    catch (cause) {
-        // Gathering does not write, so this catch cannot misclassify an output
-        // failure. oneLine() bounds any inherited diagnostic to one line.
-        ctx.stderr.write(`error: ${oneLine(cause)}\n`);
-        return 1;
-    }
-    // Replay first, on both paths, before any decision -- clause 1.
-    for (const outcome of probe.outcomes)
-        replayOutcome(outcome, ctx);
-    if (probe.status === 1) {
-        if (probe.message !== null) {
-            ctx.stderr.write(`error: ${probe.message}\n`);
-        }
+async function performInstall(ctx) {
+    const facts = await probeFacts(ctx);
+    if (facts === null)
         return 1;
-    }
-    const facts = probe.facts;
     if (facts.ownership.installEligibility.kind === "blocked") {
         writeOutput(facts.ownership.installEligibility.output, ctx);
         return 1;
@@ -282,7 +235,7 @@ async function performInstall(argv, ctx) {
         ctx.stderr.write(`error: ${oneLine(inner)}\n`);
         return 1;
     }
-    const { outcome, cleanupWarning } = stage;
+    const { value: outcome, cleanupWarning } = stage;
     for (const each of outcome.outcomes)
         replayOutcome(each, ctx);
     let status;

package/dist/commands/mutation.js

@@ -1,5 +1,5 @@
 import { computeEffectiveSelection } from "../effective-selection.js";
-import { upstreamCacheRoot } from "../upstream-workspace.js";
+import { upstreamCacheRoot } from "../upstream.js";
 import { SafetyError } from "../safety-error.js";
 import { isAbsolute } from "node:path";
 import { oneLine } from "../cli-arguments.js";
@@ -42,13 +42,13 @@ export async function withMutation(command, ctx, action) {
     }
     const resources = [location.destinationRoot, ...mutationRoots];
     if (command === "prepare") {
-        resources.push(upstreamCacheRoot(ctx.root, ctx.env, process.cwd()));
+        resources.push(upstreamCacheRoot(ctx.root, ctx.env));
     }
     // The coordinator sorts each acquisition and refuses conflicts immediately.
     // A nested prepare may add a cache lock that sorts before an outer target;
     // it cannot deadlock because no acquisition waits, while already-held roots
     // are reentrant for this invocation.
-    return await ctx.coordination.withResources(resources, async () => action(scoped));
+    return await ctx.coordination.withResources(resources, async () => action(scoped, location));
 }
 export async function runWithMutation(command, ctx, action) {
     const errors = configurationErrors(command, ctx.env);
@@ -59,9 +59,9 @@ export async function runWithMutation(command, ctx, action) {
     }
     let actionThrew = false;
     try {
-        return await withMutation(command, ctx, async (scoped) => {
+        return await withMutation(command, ctx, async (scoped, location) => {
             try {
-                return await action(scoped);
+                return await action(scoped, location);
             }
             catch (cause) {
                 actionThrew = true;

package/dist/commands/pin.js

@@ -2,7 +2,7 @@ import { tmpdir } from "node:os";
 import { oneLine } from "../cli-arguments.js";
 import { isTagRef, normalizeCommitInput } from "../domain/refs.js";
 import { loadSavedSelection, selectionStatePath, UPSTREAM_URL_DEFAULT, } from "../effective-selection.js";
-import { normalizePinnedArguments, validateSource } from "../selection.js";
+import { validateSource } from "../selection.js";
 import { writeSelectionState } from "../selection-store.js";
 import { resolveExactTag, verifyRawCommit } from "../upstream.js";
 // Runs every step that can throw, and performs no writes of its own: that is
@@ -36,12 +36,17 @@ async function attemptPin(requested, ctx) {
         resolvedRef = normalizeCommitInput(requested);
         commit = await verifyRawCommit(source, resolvedRef, tmpdir());
     }
-    await writeSelectionState(selectionStatePath(ctx.env), normalizePinnedArguments({
+    // resolvedRef is already normalized (lowercase for a raw commit; a v-tag is
+    // unchanged), and commit comes lowercase from verifyRawCommit or git
+    // ls-remote. validateRecord still rejects anything else.
+    await writeSelectionState(selectionStatePath(ctx.env), {
+        schema_version: 1,
+        mode: "pinned",
         source,
-        requestedRef: resolvedRef,
-        resolvedRef,
+        requested_ref: resolvedRef,
+        resolved_ref: resolvedRef,
         commit,
-    }));
+    });
     return { resolvedRef, commit };
 }
 export async function runPin(argv, ctx) {