superpowers-manager 0.1.6 → 0.3.0

package/README.md

@@ -19,7 +19,7 @@ npx superpowers-manager update
 Use the official marketplace for the simplest native Codex installation. Use
 Superpowers Manager when you want immediate stable-upstream freshness after a
 user-triggered install/update, per-invocation release or commit selection,
-recorded upstream provenance, diagnostics, Codex-specific hook-free packaging,
+recorded upstream provenance, diagnostics, upstream-owned Codex hook handling,
 and explicit install/update/probe/uninstall lifecycle control.
 
 | Choose | Best fit |
@@ -39,46 +39,79 @@ It never removes the legacy provider automatically.
 
 ## Requirements and platforms
 
-Superpowers Manager requires Node 24+, `git`, Python 3, and a POSIX `sh`.
-Codex CLI is required for `probe`, `install`, `update`, and `uninstall`;
-`prepare` does not require it.
+Superpowers Manager requires Node 24+, and Codex is the only supported
+integration today. Every other requirement is per command, enforced by
+preflight before any dispatch. This table is checked against production by
+`tests/bin/readme-requirements.test.js`; edit it when a command's requirements
+change, in the same pull request.
+
+<!-- requirements:begin -->
+| Command | git | Python 3 | Codex CLI |
+|---|---|---|---|
+| `pin` | yes | no | no |
+| `track-latest` | no | no | no |
+| `unpin` | no | no | no |
+| `prepare` | yes | only with SUPERPOWERS_VALIDATOR | no |
+| `probe` | yes | no | yes |
+| `install` | yes | no | yes |
+| `update` | yes | no | yes |
+| `uninstall` | no | no | yes |
+<!-- requirements:end -->
+
+See `docs/baseline/behavioral-inventory.md`'s `CLI-PREFLIGHT-01` for the
+behaviour this table describes.
 
 macOS and Linux are tested. WSL2 is supported. The native Windows path is
-untested; the launcher looks for Git Bash, `git`, and `python3`, but path
-handling between MSYS and Codex remains a known risk area.
+untested; the launcher no longer looks for Git Bash at all — every command runs
+in-process, so no POSIX shell is discovered or required — but path handling
+between MSYS and Codex remains a known risk area.
 
-Prepare, install, probe, and update resolve the requested upstream ref over the
-network. Updates are user-triggered and need upstream network access; the
-manager does not run automatic or background updates.
+Network needs depend on the saved policy. `pin` verifies its target;
+`track-latest` and invocation overrides resolve from upstream when applied; and
+`prepare`, `install`, and `update` fetch or verify the effective source. A probe
+of a saved exact pin can reuse its recorded identity without upstream access.
+Updates remain user-triggered; the manager does not run automatic or background
+updates.
 
 ## What it does
 
 - Resolves an upstream ref, defaulting to the latest stable `vX.Y.Z` release
   tag.
 - Clones/fetches upstream at that commit and assembles a Codex plugin tree under
-  `plugins/superpowers/` (skills, assets, license/readme, and manifest;
-  upstream's `hooks/` directory is deliberately excluded).
+  `plugins/superpowers/` (skills, assets, license/readme, manifest, and any
+  hook files that the upstream manifest allows).
 - Stamps the generated manifest with a ref-aware manager version ending in
   `+manager.<short-sha>` and writes the upstream provenance to
   `.superpowers-upstream.json`.
-- Validates the generated tree with the manager's shipped, Python-standard-library
-  contract validator before swapping it into place (a failed run never destroys
-  a previously generated tree).
+- Validates the generated tree with the manager's shipped contract validator
+  before swapping it into place (a failed run never destroys a previously
+  generated tree).
 - Registers the `superpowers-manager` marketplace and installs or refreshes
   `superpowers@superpowers-manager` in Codex.
 
-The generated plugin carries upstream skills, assets, and documentation. The
-manager excludes upstream `hooks/`, removes the manifest `hooks` field, and
-validates that both stay absent. This is a Codex-specific adapter policy, not a
-claim about how Superpowers should be packaged for future or other harnesses.
-Changing the hook-free policy requires a separate design and current
-compatibility evidence.
+The generated plugin carries upstream skills, assets, documentation, and the
+upstream-owned hook policy. When upstream provides a Codex manifest, its
+`hooks` declaration is preserved: exact `{}` suppresses the `hooks/` subtree;
+active declarations conditionally materialize the upstream hook files; and a
+missing `hooks` key or explicit empty array (`[]`) declaration uses Codex's
+default discovery only when upstream ships `hooks/hooks.json`. Manifest-less
+fallback refs use the committed minimal template and generate neither a manifest
+`hooks` key nor a `hooks/` directory.
+The manager never creates its own hooks or mutates Codex trust state.
+
+Review upstream hook command definitions with Codex's `/hooks` flow. Codex
+trust applies to a command definition, not to the contents of scripts that the
+definition references. An explicit update of an older pin can therefore change
+the contents of a trusted referenced script, or reveal a newly untrusted
+upstream definition; review it before trusting or running it. This policy
+eliminates latent hook-policy drift.
 
 ## Runtime architecture
 
-- `scripts/core/` owns the shared lifecycle, status, and protocol validation.
-- `scripts/adapters/codex/` owns build, inspection, reconciliation, and Codex
-  mutation.
+- The in-process TypeScript runtime under `src/` owns lifecycle dispatch,
+  status, and adapter-result handling;
+  see the [in-process adapter result contract](https://github.com/j7an/superpowers-manager/blob/main/docs/adapter-result-contract.md).
+- `src/adapter.ts` owns build, inspection, reconciliation, and Codex mutation.
 - Codex is the only supported adapter today; no public harness selector ships
   yet.
 
@@ -92,10 +125,33 @@ after the built-in check. It receives the candidate plugin root as its only
 argument. It cannot replace or bypass built-in validation, and either check
 failing prevents the tree swap and all Codex mutation.
 
-Direct `scripts/install` keeps harness-specific validation in the Codex adapter:
-phase 1 prepares the exact candidate first, then the adapter performs its Codex
-and refresh-mode preflight before any Codex mutation. The Node dispatcher keeps
-its existing Codex preflight before dispatching to the shell lifecycle.
+`SUPERPOWERS_VALIDATOR_EXECUTABLE=/path/to/validator` adds an optional external
+validator after the built-in check. It names an executable, receiving the
+candidate plugin root as its only argument. The manager constructs no shell
+command string and supplies argv directly. On Linux, `execvp` may hand that
+same argv to `/bin/sh` after `ENOEXEC`, and the values are preserved rather
+than re-parsed, so a candidate path containing spaces or shell metacharacters
+is passed through intact and cannot inject a command — on either platform. A
+file with the exec bit set but no valid executable format is handled by the
+platform's own `execvp` fallback, not by the manager: on Linux, `/bin/sh` runs
+it as shell source; on darwin, it is
+rejected outright as not runnable. Give the validator a shebang line or make
+it a real binary, or its behavior will differ by platform. Exit 0 accepts;
+any nonzero exit rejects and prevents the tree swap. The manager stops
+waiting after 30 seconds and keeps at most 64 KiB of each of its output
+streams. It cannot replace or bypass built-in validation, and it is not a
+security boundary: it runs with the manager's own privileges, by design.
+
+`SUPERPOWERS_VALIDATOR` is deprecated in favor of `SUPERPOWERS_VALIDATOR_EXECUTABLE`
+and continues to work unchanged. The legacy variable requires `python3`; the
+executable hook does not. Setting both is rejected at preflight, before any
+network or Codex access, rather than silently resolved. Removal of the legacy
+variable is deferred to a future major release.
+
+The in-process install command keeps harness-specific validation in the Codex
+adapter: phase 1 prepares the exact candidate first, then the adapter performs
+its Codex and refresh-mode preflight before any Codex mutation. The CLI runs
+its Codex preflight before invoking the lifecycle handler.
 
 ## Provider ownership
 
@@ -121,6 +177,9 @@ manager will not remove it for you.
 
 | Command | Codex side effects | Purpose |
 |---|---|---|
+| `npx superpowers-manager pin REF` | None | Resolve and save an exact upstream release tag or full commit |
+| `npx superpowers-manager track-latest` | None | Save a policy that resolves the latest stable release when applied |
+| `npx superpowers-manager unpin` | None | Remove saved selection and return to the packaged fallback policy |
 | `npx superpowers-manager prepare` | None | Resolve upstream, build a staged plugin tree, validate it, and replace the generated tree only on success |
 | `npx superpowers-manager probe` | None | Report requested and resolved refs, desired/generated/installed commits, identity state, and status |
 | `npx superpowers-manager install` | Marketplace and plugin state | Prepare and validate, register the marketplace, install the plugin, and verify installed state |
@@ -136,43 +195,91 @@ when resulting manager state cannot be verified.
 
 ## Choosing the upstream version
 
-`SUPERPOWERS_REF` selects a stable release tag, full commit SHA, branch, or
-other resolvable upstream ref for that invocation. The stateless npx package
-records the requested ref, resolved ref, and exact commit, but does not persist
-the selection for a later invocation that omits `SUPERPOWERS_REF`.
+Save a tag pin, commit pin, or explicit latest-stable policy for future
+invocations:
 
-Without `SUPERPOWERS_REF`, the manager reads `config/upstream-ref`, which ships
-as `latest-release`. Accepted values include:
+```sh
+npx superpowers-manager pin v6.1.1
+npx superpowers-manager pin 0123456789abcdef0123456789abcdef01234567  # replace with a real upstream commit
+npx superpowers-manager track-latest
+npx superpowers-manager unpin
+```
+
+The selection commands save intent only; they do not prepare generated content
+or change Codex state. Run `npx superpowers-manager install` for a first
+installation or `npx superpowers-manager update` to apply the saved policy to
+an existing installation. There is no background updater: selection changes
+take effect only through a user-triggered `prepare`, `install`, or `update`.
+
+`pin` accepts only an exact `vMAJOR.MINOR.PATCH` tag (optionally with a SemVer
+prerelease suffix) or a full 40-character commit. It resolves and verifies the
+target before saving both the exact commit identity and its source. The saved
+identity is the contract, not the contents of a clone cache: clearing or moving
+`SUPERPOWERS_CACHE_DIR` does not change the selection. `track-latest` saves the
+source and resolves the highest stable `vX.Y.Z` tag each time the policy is
+applied. `unpin` removes only the saved selection and restores the packaged
+`config/upstream-ref` fallback, currently `latest-release`.
+
+The user-wide selection file is `selection.json` under the first configured
+location:
 
-- `latest-release` — highest stable `vX.Y.Z` tag (prereleases are excluded).
-- A specific tag, e.g. `v6.0.3`.
-- A full 40-character commit SHA.
-- Any other ref upstream resolves (e.g. a branch name).
+1. `$SUPERPOWERS_CONFIG_DIR`
+2. `$XDG_CONFIG_HOME/superpowers-manager`
+3. `$HOME/.config/superpowers-manager`
+
+Each location must be absolute. The ref and source precedence chains are
+independent:
+
+- Ref: `SUPERPOWERS_REF`, then saved selection, then `config/upstream-ref`.
+- Source: `SUPERPOWERS_UPSTREAM_URL`, then saved source, then the official
+  `https://github.com/obra/superpowers` source.
+
+`SUPERPOWERS_REF` is an invocation-only override and is not persisted. Unlike
+an exact saved pin, it accepts stable tags, full commit SHAs, branches, and
+other resolvable upstream refs for that invocation:
 
 ```sh
-SUPERPOWERS_REF=v6.0.3 npx superpowers-manager prepare
-SUPERPOWERS_REF=main npx superpowers-manager probe
-SUPERPOWERS_REF=feature/foo npx superpowers-manager install
-SUPERPOWERS_REF=latest-release npx superpowers-manager update
+SUPERPOWERS_REF=feature/foo npx superpowers-manager probe
 ```
 
-`SUPERPOWERS_CACHE_DIR` may point to a persistent upstream clone cache to avoid
-re-cloning between package materializations. It caches Git objects; it does not
-persist ref selection or trigger updates.
+`pin` and `track-latest` bind the current `SUPERPOWERS_UPSTREAM_URL`, or the
+official source when that variable is unset, to the saved intent. An invocation
+may override only the ref or only the source; `probe` exposes
+`selection_origin`, `selection_mode`, `upstream_source_origin`,
+`effective_source`, the saved-selection fields, and a mixed-origin warning in
+human output so that combination remains visible.
+
+A saved exact pin lets `probe` determine the desired upstream identity without
+contacting Git, even when the saved source is temporarily unavailable. This is
+not a general offline installation promise: `pin` verifies the requested
+target, `track-latest` must resolve when applied, and `prepare`/`install`/`update`
+must fetch or verify content from the effective source. Codex inspection is
+still required for lifecycle status.
+
+HTTP(S) upstream URLs containing userinfo are now rejected, including
+token-only userinfo. This is an intentional compatibility break: use a Git
+credential helper for HTTP(S) authentication or an SSH source instead of
+embedding credentials in the URL.
+
+Saved selection does not claim or transfer provider ownership. The manager
+continues to mutate only `superpowers@superpowers-manager` and never removes or
+updates the official provider or any other provider automatically.
 
 ## How versioning works
 
 - **Upstream manifest first:** when upstream provides
   `.codex-plugin/plugin.json`, `prepare` uses it as the generated manifest base
-  so future upstream metadata fields are preserved by default.
+  so future upstream metadata fields, including its hook declaration, are
+  preserved by default.
 - **Fallback template:** `plugins/superpowers/.codex-plugin/plugin.template.json`
   is committed as a minimal fallback for older upstream refs that do not ship a
   Codex manifest. It carries the placeholder version
-  `0.0.0+manager.template`.
+  `0.0.0+manager.template`, declares no hooks, and produces no `hooks/`
+  directory.
 - **Manager overlay:** `prepare` replaces the version with a ref-aware manager
-  version, forces `skills` to `./skills/`, and enforces the manager's current
-  hook-free policy: no manifest `hooks` key and no copied `hooks/` directory.
-  Unknown upstream manifest fields remain preserved.
+  version and forces `skills` to `./skills/`. Unknown upstream manifest fields,
+  including `hooks`, remain preserved; the adapter materializes hook files only
+  according to the upstream declaration.
 - Stable tags generate release-looking versions such as
   `6.0.3+manager.896224c`; explicit prerelease tags generate versions such as
   `6.1.0-beta.1+manager.abc1234`.
@@ -202,11 +309,16 @@ persist ref selection or trigger updates.
 ## Tests
 
 ```sh
+pnpm install --frozen-lockfile
+pnpm run build
 sh tests/run.sh                          # Layers 1-3: host-side hermetic checks while iterating
 sh tests/container.sh                    # Layers 1-4: blocking Docker acceptance command
 sh tests/manual/codex-behavior-probe.sh  # optional native-only compatibility residue
 ```
 
+`pnpm run build` deletes `dist/` before compiling, so every build is a clean
+rebuild and stale artifacts of deleted or renamed modules cannot survive.
+
 Layers 1-3 stay offline and hermetic: they use a fake local upstream repo plus
 host-side fixtures, and they perform no mutation of the developer's or runner's
 real Codex state.
@@ -219,28 +331,36 @@ an isolated container home with networking disabled. That container run may
 mutate the throwaway container-local Codex state, but it still performs no
 mutation of the developer's or runner's real Codex state.
 
+The container probe uses Codex's `hooks/list` only as compatibility evidence
+for the tested Codex build. It is not a stable Superpowers Manager API.
+
 The manual probe is opt-in and covers native-only compatibility residue such as
-path/cache behavior against an intentionally real local Codex install. It is
-not part of acceptance. GitHub Actions runs the blocking container acceptance
-command on pull requests and pushes to `main`.
+path/cache and version-precedence behavior against an intentionally real local
+Codex install. It is not part of acceptance. GitHub Actions runs both the
+toolchain check and the blocking container acceptance command on pull requests
+and pushes to `main`.
 
 ## Repository layout
 
 ```
 .agents/plugins/marketplace.json          # local marketplace definition (tracked)
-config/upstream-ref                        # which upstream ref to track (tracked)
+.github/                                  # CI, security, dependency, and release workflows (tracked)
+bin/superpowers-manager.js                # public thin loader for dist/cli.js
+config/upstream-ref                       # packaged upstream fallback policy (tracked)
+docs/                                     # adapter result contract and baseline evidence (tracked)
+package.json pnpm-lock.yaml tsconfig.json # package contract and locked toolchain (tracked)
 plugins/superpowers/
-  .codex-plugin/plugin.template.json       # fallback manifest template (tracked)
-  .codex-plugin/plugin.json                # generated manifest          (gitignored)
-  skills/ assets/ LICENSE ...              # generated from upstream      (gitignored)
-  .superpowers-upstream.json               # generated provenance         (gitignored)
-scripts/
-  adapters/codex/                          # Codex adapter entrypoint + validator helpers
-  core/                                    # shared lifecycle/provenance/status modules
-  prepare probe install update uninstall   # user-facing shell entrypoints
-tests/                                     # hermetic suite + manual Codex probe
-.cache/upstream/                           # upstream clone cache         (gitignored)
+  .codex-plugin/plugin.template.json      # fallback manifest template (tracked)
+  generated plugin tree                   # prepared from upstream (gitignored)
+src/                                      # in-process TypeScript runtime (tracked)
+  cli.ts                                  # CLI parsing, preflight, and command dispatch
+  commands/                               # lifecycle and selection command handlers
+  adapter.ts                              # Codex integration
+tests/                                    # hermetic suite and manual Codex probe (tracked)
+  migration-inventory/                     # frozen historical evidence
+dist/                                     # generated ESM build tree (gitignored)
 ```
 
 Everything under `plugins/superpowers/` except the fallback manifest template is
-generated by `prepare` and ignored by Git; re-run `prepare` to regenerate it.
+generated by `npx superpowers-manager prepare` and ignored by Git; re-run that
+command to regenerate it.

package/bin/superpowers-manager.js

@@ -1,244 +1,16 @@
 #!/usr/bin/env node
 // @ts-check
 
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import { spawnSync } from 'node:child_process';
+import { existsSync } from "node:fs";
 
-/**
- * @typedef {'prepare' | 'probe' | 'install' | 'update' | 'uninstall'} Subcommand
- */
+const cliUrl = new URL("../dist/cli.js", import.meta.url);
 
-/**
- * @typedef {{ kind: 'run', cmd: Subcommand, args: string[] }} RunParseResult
- * @typedef {{ kind: 'help' }} HelpParseResult
- * @typedef {{ kind: 'version' }} VersionParseResult
- * @typedef {{ kind: 'usage-error', message: string }} UsageErrorParseResult
- * @typedef {RunParseResult | HelpParseResult | VersionParseResult | UsageErrorParseResult} ParseResult
- */
-
-/**
- * @typedef {{ ok: true, shell: string }} PreflightOk
- * @typedef {{ ok: false, errors: string[] }} PreflightError
- * @typedef {PreflightOk | PreflightError} PreflightResult
- */
-
-/**
- * @typedef {{ file: string, argv: string[] }} SpawnDescriptor
- */
-
-const SUBCOMMANDS = ['prepare', 'probe', 'install', 'update', 'uninstall'];
-const CODEX_SUBCOMMANDS = ['probe', 'install', 'update', 'uninstall'];
-// Mirrors upstream Superpowers' hooks/run-hook.cmd discovery order.
-const GIT_BASH_CANDIDATES = [
-  'C:\\Program Files\\Git\\bin\\bash.exe',
-  'C:\\Program Files (x86)\\Git\\bin\\bash.exe',
-];
-
-// Walk upward from the bin's physical location to the directory containing
-// package.json. realpathSync first: npm/npx expose the bin through a symlink
-// or shim outside the package root.
-/**
- * @param {string} scriptPath
- * @returns {string | null}
- */
-function resolvePackageRoot(scriptPath) {
-  let dir;
-  try {
-    dir = path.dirname(fs.realpathSync(scriptPath));
-  } catch (err) {
-    return null;
-  }
-  for (;;) {
-    if (fs.existsSync(path.join(dir, 'package.json'))) return dir;
-    const parent = path.dirname(dir);
-    if (parent === dir) return null;
-    dir = parent;
-  }
-}
-
-/**
- * @param {string} moduleFilename
- * @param {string | undefined} argvPath
- * @returns {boolean}
- */
-function isMain(moduleFilename, argvPath) {
-  if (!argvPath) return false;
-  return moduleFilename === fs.realpathSync(argvPath);
+if (!existsSync(cliUrl)) {
+  console.error(
+    "dist/ not built — run `pnpm install --frozen-lockfile && pnpm run build`",
+  );
+  process.exit(1);
 }
 
-/**
- * @param {string[]} argv
- * @returns {ParseResult}
- */
-function parseArgs(argv) {
-  /** @type {string | undefined} */
-  const first = argv[0];
-  if (argv.length === 0) return { kind: 'run', cmd: 'update', args: [] };
-  if (first === '--help' || first === '-h') return { kind: 'help' };
-  if (first === '--version') return { kind: 'version' };
-  if (first && SUBCOMMANDS.includes(first)) {
-    return { kind: 'run', cmd: /** @type {Subcommand} */ (first), args: argv.slice(1) };
-  }
-  return { kind: 'usage-error', message: `unknown subcommand: ${first}` };
-}
-
-// Search env.PATH for an executable named `name`; on win32 also try PATHEXT
-// extensions. Returns the full path or null.
-/**
- * @param {string} name
- * @param {NodeJS.ProcessEnv} env
- * @param {NodeJS.Platform} platform
- * @returns {string | null}
- */
-function findTool(name, env, platform) {
-  const pathVar = env.PATH || env.Path || '';
-  const dirs = pathVar.split(path.delimiter).filter(Boolean);
-  const exts = platform === 'win32'
-    ? (env.PATHEXT || '.EXE;.CMD;.BAT;.COM').split(';')
-    : [''];
-  for (const dir of dirs) {
-    for (const ext of exts) {
-      const candidate = path.join(dir, name + ext.toLowerCase());
-      try {
-        fs.accessSync(candidate, fs.constants.X_OK);
-        return candidate;
-      } catch (err) { /* keep looking */ }
-    }
-  }
-  return null;
-}
-
-// POSIX: `sh` on PATH. Windows: Git Bash at its standard install paths,
-// then `bash` on PATH.
-/**
- * @param {NodeJS.ProcessEnv} env
- * @param {NodeJS.Platform} platform
- * @returns {string | null}
- */
-function discoverShell(env, platform) {
-  if (platform !== 'win32') return findTool('sh', env, platform);
-  for (const candidate of GIT_BASH_CANDIDATES) {
-    try {
-      fs.accessSync(candidate, fs.constants.X_OK);
-      return candidate;
-    } catch (err) { /* keep looking */ }
-  }
-  return findTool('bash', env, platform);
-}
-
-// Tool preflight; never touches Codex state. codex is required only for the
-// subcommands that mutate or read Codex.
-/**
- * @param {Subcommand} cmd
- * @param {NodeJS.ProcessEnv} env
- * @param {NodeJS.Platform} platform
- * @returns {PreflightResult}
- */
-function preflight(cmd, env, platform) {
-  const errors = [];
-  for (const tool of ['git', 'python3']) {
-    if (!findTool(tool, env, platform)) {
-      errors.push(`required command not found: ${tool} — install ${tool} and re-run`);
-    }
-  }
-  const shell = discoverShell(env, platform);
-  if (!shell) {
-    errors.push(platform === 'win32'
-      ? 'no POSIX shell found — install Git for Windows (provides bash) or use WSL2'
-      : 'required command not found: sh');
-  }
-  if (CODEX_SUBCOMMANDS.includes(cmd)) {
-    const codexBin = env.SUPERPOWERS_CODEX || 'codex';
-    // An explicit override may be a path rather than a PATH-resolvable name.
-    const found = codexBin.includes(path.sep)
-      ? fs.existsSync(codexBin)
-      : Boolean(findTool(codexBin, env, platform));
-    if (!found) {
-      errors.push(`required command not found: ${codexBin} — install the Codex CLI or set SUPERPOWERS_CODEX`);
-    }
-  }
-  if (errors.length) return { ok: false, errors };
-  return { ok: true, shell: /** @type {string} */ (shell) };
-}
-
-// POSIX executes the script directly (#!/bin/sh shebang); Windows cannot
-// spawn extensionless scripts, so the discovered shell runs the script as
-// its first argument.
-/**
- * @param {Subcommand} cmd
- * @param {string[]} args
- * @param {string} root
- * @param {string} shell
- * @param {NodeJS.Platform} platform
- * @returns {SpawnDescriptor}
- */
-function buildSpawn(cmd, args, root, shell, platform) {
-  const script = path.join(root, 'scripts', cmd);
-  if (platform === 'win32') {
-    return { file: shell, argv: [script, ...args] };
-  }
-  return { file: script, argv: args };
-}
-
-function usage() {
-  return [
-    'usage: superpowers-manager [prepare|probe|install|update|uninstall] [args...]',
-    '',
-    '  prepare    fetch the pinned upstream ref and generate the plugin tree',
-    '  probe      report upstream/generated/installed status (accepts --porcelain)',
-    '  install    register this package root as a Codex marketplace and install the plugin',
-    '  update     probe, then prepare/install only if needed (default when no subcommand)',
-    '  uninstall  remove the manager plugin and marketplace from Codex',
-    '',
-    'Environment overrides (passed through to the scripts): SUPERPOWERS_REF,',
-    'SUPERPOWERS_UPSTREAM_URL, SUPERPOWERS_CODEX, SUPERPOWERS_CACHE_DIR,',
-    'SUPERPOWERS_PLUGIN_ROOT, SUPERPOWERS_MANIFEST_TEMPLATE,',
-    'SUPERPOWERS_VALIDATOR,',
-    'SUPERPOWERS_INSTALLED_SEARCH_ROOT, SUPERPOWERS_INSTALL_REFRESH_MODE',
-  ].join('\n');
-}
-
-function main() {
-  const parsed = parseArgs(process.argv.slice(2));
-  if (parsed.kind === 'help') {
-    console.log(usage());
-    process.exit(0);
-  }
-  const root = resolvePackageRoot(import.meta.filename);
-  if (!root) {
-    console.error('error: cannot resolve the superpowers-manager package root');
-    process.exit(1);
-  }
-  if (parsed.kind === 'version') {
-    console.log(JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).version);
-    process.exit(0);
-  }
-  if (parsed.kind === 'usage-error') {
-    console.error(`error: ${parsed.message}`);
-    console.error(usage());
-    process.exit(2);
-  }
-  const pf = preflight(parsed.cmd, process.env, process.platform);
-  if (!pf.ok) {
-    for (const e of pf.errors) console.error(`error: ${e}`);
-    process.exit(1);
-  }
-  const script = path.join(root, 'scripts', parsed.cmd);
-  if (!fs.existsSync(script)) {
-    console.error(`error: missing script: ${script}`);
-    process.exit(1);
-  }
-  const spawn = buildSpawn(parsed.cmd, parsed.args, root, pf.shell, process.platform);
-  // env is inherited wholesale, so every SUPERPOWERS_* override passes through.
-  const res = spawnSync(spawn.file, spawn.argv, { stdio: 'inherit', env: process.env });
-  if (res.error) {
-    console.error(`error: cannot run ${spawn.file}: ${res.error.message}`);
-    process.exit(1);
-  }
-  process.exit(res.status === null ? 1 : res.status);
-}
-
-export { resolvePackageRoot, isMain, parseArgs, findTool, discoverShell, preflight, buildSpawn, usage };
-
-if (isMain(import.meta.filename, process.argv[1])) main();
+const { main } = await import(cliUrl.href);
+main();