superpowers-manager 0.2.0 → 0.4.0

package/README.md

@@ -16,16 +16,21 @@ npx superpowers-manager probe
 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,
-and explicit install/update/probe/uninstall lifecycle control.
+Use Superpowers Manager to follow the latest stable Superpowers release directly
+from upstream and apply updates with one command. By default, `install` and
+`update` resolve the highest stable `vX.Y.Z` tag when invoked; saved pins and
+invocation overrides take precedence. `probe` reports whether your installation
+matches that selection without changing Codex state. Updates are user-triggered.
 
-| Choose | Best fit |
-|---|---|
-| Official marketplace | Simplest Codex-native installation and marketplace-managed cadence |
-| `superpowers-manager` | Direct stable-upstream freshness when invoked, exact ref selection, provenance, diagnostics, and lifecycle control |
+| Choose | Version source | Best fit |
+|---|---|---|
+| `superpowers-manager` | Latest stable upstream tag by default, or your saved/overridden selection | Follow upstream stable with drift reporting and verified updates |
+| Direct upstream repository | The configured Git ref, or the repository's default branch | Use Codex's native Git marketplace support |
+| `superpowers@openai-curated` | The copy distributed in the curated marketplace | Use the curated integration and its refresh policy |
+
+See [Comparing installation routes](#comparing-installation-routes) for commands
+and update behavior. Use one provider at a time; see
+[Provider ownership](#provider-ownership) before switching.
 
 ### Moving from `superpowers-wrapper`
 
@@ -39,14 +44,33 @@ 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`, `pin`, `track-latest`, and `unpin` do not require it. Codex is the
-only supported integration today.
+The installed Superpowers Manager package requires Node >=24. Native source,
+tests, and packaging tooling require Node >=24.12.0. 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.ts`; 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.
 
 Network needs depend on the saved policy. `pin` verifies its target;
 `track-latest` and invocation overrides resolve from upstream when applied; and
@@ -55,35 +79,119 @@ 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.
 
+## Comparing installation routes
+
+### Getting the latest stable release
+
+The manager selects the highest stable upstream `vX.Y.Z` tag when its effective
+policy is `latest-release`. It does not require the curated marketplace to
+publish that release first. Saved pins and environment overrides can select a
+different version or source; see [Choosing the upstream version](#choosing-the-upstream-version).
+
+The direct repository route uses the Git ref you configure. Adding the repository
+without `--ref` uses its default branch, which is not a latest-stable release
+policy. The curated route uses the
+[copy in `openai/plugins`](https://github.com/openai/plugins/tree/main/plugins/superpowers).
+Refreshing that snapshot does not independently resolve the latest stable tag
+from `obra/superpowers`; curated may match upstream or lag behind it.
+
+The native CLI examples below were checked against Codex `0.153.3`. Upstream's
+[marketplace manifest](https://github.com/obra/superpowers/blob/main/.agents/plugins/marketplace.json)
+names its marketplace `superpowers-dev`.
+
+### First install
+
+These are alternative routes; do not run both to install duplicate providers.
+
+| Step | Superpowers Manager | Direct upstream repository |
+|---|---|---|
+| 1 | `npx superpowers-manager install` | `codex plugin marketplace add https://github.com/obra/superpowers` |
+| 2 | — | `codex plugin add superpowers@superpowers-dev` |
+
+The manager follows upstream stable by default. For a specific release on the
+direct route, choose its tag and add `--ref TAG` to the marketplace-add command.
+
+### Staying current
+
+| Action | Superpowers Manager | Direct upstream repository |
+|---|---|---|
+| Explicit update | `npx superpowers-manager update` | `codex plugin marketplace upgrade superpowers-dev` |
+| Optional inspection | `npx superpowers-manager probe` | `codex plugin list` |
+
+The manager probes first, skips prepare/install when current and update control
+is valid, and verifies the resulting installed state after a refresh. `probe`
+reports requested and resolved refs, desired/generated/installed commits, and
+status. With a saved pin, "current" means matching that pin, not necessarily
+matching the latest upstream release. See [Lifecycle commands](#lifecycle-commands).
+
+Native marketplace upgrade follows its configured ref. In the checked Codex
+version, it can skip unchanged snapshots and refreshes installed plugins when
+the marketplace changes; a second `plugin add` is not required for that refresh.
+Codex also has an automatic refresh path for configured Git marketplaces.
+See the [native upgrade implementation](https://github.com/openai/codex/blob/rust-v0.153.3/codex-rs/core-plugins/src/manager.rs).
+`plugin list` shows installed versions; comparing them with upstream stable is
+separate inspection work, not a prerequisite for running an update.
+
+### Changing the selected version
+
+Replace `TAG` below with the exact release tag you want. For an already registered
+direct marketplace, remove/add is a CLI route to changing its ref:
+
+| Step | Superpowers Manager | Direct upstream repository |
+|---|---|---|
+| 1 | `npx superpowers-manager pin TAG` | `codex plugin marketplace remove superpowers-dev` |
+| 2 | `npx superpowers-manager update` | `codex plugin marketplace add https://github.com/obra/superpowers --ref TAG` |
+| 3 | — | `codex plugin add superpowers@superpowers-dev` |
+
+The manager's `pin` saves verified intent without changing Codex state; `update`
+applies it. To resume following stable releases, run
+`npx superpowers-manager track-latest`, then `npx superpowers-manager update`.
+The native sequence changes marketplace configuration immediately. In the checked
+CLI, `marketplace upgrade` has no `--ref` option, and adding the same marketplace
+name with a different ref is rejected. This sequence does not imply that editing
+native configuration is impossible.
+
 ## 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;
-  see the [version-1 adapter response protocol](https://github.com/j7an/superpowers-manager/blob/main/docs/adapter-protocol.md).
-- `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).
+- Developers extending that runtime should start with the
+  [internal harness interface](https://github.com/j7an/superpowers-manager/blob/main/docs/harness-interface.md).
+- `src/adapter.ts` owns build, inspection, reconciliation, and Codex mutation.
 - Codex is the only supported adapter today; no public harness selector ships
   yet.
 
@@ -97,10 +205,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
 
@@ -218,15 +349,17 @@ updates the official provider or any other provider automatically.
 
 - **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`.
@@ -253,49 +386,190 @@ updates the official provider or any other provider automatically.
   SUPERPOWERS_INSTALL_REFRESH_MODE=remove-add npx superpowers-manager update
   ```
 
+## pnpm updates
+
+A weekly Monday workflow (06:00 UTC), also available through manual dispatch,
+opens or refreshes a dedicated pull request updating only `package.json`'s
+`packageManager` pin. It selects a newer, non-deprecated stable pnpm release
+within the pinned major after five days. If the current pin is deprecated,
+the shared updater bypasses that waiting period and discloses it in the PR.
+Major upgrades remain a manual decision; the lockfile is not updated by this
+workflow.
+
+The caller forwards only `RELEASE_BOT_PRIVATE_KEY` and uses
+`vars.RELEASE_BOT_APP_ID` for App-authored PRs that can trigger CI. Keep both
+configured. After adopting the caller, verify a manual run's App authentication
+and inspect any resulting PR before treating live integration as validated.
+
 ## Tests
 
+Install once, run the static gate before submission, and choose the package
+script that matches the scope you are iterating on:
+
+```sh
+pnpm install --frozen-lockfile
+pnpm run check:static
+pnpm test
+pnpm run test:unit
+pnpm run test:integration
+pnpm run test:harness:codex
+pnpm run test:acceptance
+```
+
+The package scripts above are alternative iteration selectors; do not run every
+row sequentially as a substitute for acceptance. `pnpm test` runs all shared
+suites once, while the unit and integration scripts select one shared group.
+`test:harness:codex` runs only the isolated Docker Codex probe. Complete
+acceptance is `pnpm run check:static` followed by `pnpm run test:acceptance`
+with explicit evidence for the package's minimum Node runtime.
+
+To compare shared-suite scheduling while iterating, use:
+
+```sh
+sh tests/run.sh --concurrency 1
+sh tests/run.sh --concurrency 2
+```
+
+Every normally completed shared run emits both `run-node-suites: complete
+status=<status>` and `tests/run.sh: complete failed=<count>`. Either sentinel
+may report failure; if either is absent, the run was interrupted and is
+incomplete.
+
+Use a Homebrew-managed local pnpm by command name; do not use Corepack.
+`check:static` checks formatting, lints, and typechecks production and tests without
+emitting JavaScript. Run the maintained CLI directly with `node src/cli.ts`.
+Tests and their subprocesses execute TypeScript against `src/` with no checkout
+build. Future production coverage covers `src/`, including `src/cli.ts`; emitted
+distribution files, tests, and packaging tools are outside that source scope.
+No coverage collection is enabled by this migration.
+
+On macOS, reuse an existing exact package-minimum Node executable when one is
+already available:
+
+```sh
+export SPW_PACKAGE_NODE=/absolute/path/to/node-v24.0.0
+export SPW_PACKAGE_NODE_VERSION=24.0.0
+test "$("$SPW_PACKAGE_NODE" -p 'process.versions.node')" = "$SPW_PACKAGE_NODE_VERSION"
+```
+
+Otherwise, run this prerequisite setup from the worktree while a supported
+native Node remains on `PATH`. It downloads an official Node archive into a
+new temporary directory and verifies the selected checksum before extraction:
+
+```sh
+spw_runtime_dir=$(mktemp -d)
+SPW_PACKAGE_NODE_VERSION=$(node -p 'const e=require("./package.json").engines.node; const m=/^>=(\d+)$/.exec(e); if(!m) throw Error("unsupported engines.node"); `${m[1]}.0.0`')
+case "$(uname -m)" in
+  arm64) spw_node_arch=arm64 ;;
+  x86_64) spw_node_arch=x64 ;;
+  *) echo "unsupported macOS architecture" >&2; exit 1 ;;
+esac
+spw_node_archive="node-v${SPW_PACKAGE_NODE_VERSION}-darwin-${spw_node_arch}.tar.gz"
+(
+  set -eu
+  cd "$spw_runtime_dir"
+  curl --fail --location --remote-name "https://nodejs.org/dist/v${SPW_PACKAGE_NODE_VERSION}/${spw_node_archive}"
+  curl --fail --location --remote-name "https://nodejs.org/dist/v${SPW_PACKAGE_NODE_VERSION}/SHASUMS256.txt"
+  rg -F "  ${spw_node_archive}" SHASUMS256.txt > selected-sha256.txt
+  test "$(wc -l < selected-sha256.txt)" -eq 1
+  read -r spw_node_sha spw_selected_archive < selected-sha256.txt
+  test "$spw_selected_archive" = "$spw_node_archive"
+  shasum -a 256 -c selected-sha256.txt
+  tar -xzf "$spw_node_archive"
+) || exit 1
+SPW_PACKAGE_NODE="$spw_runtime_dir/node-v${SPW_PACKAGE_NODE_VERSION}-darwin-${spw_node_arch}/bin/node"
+export SPW_PACKAGE_NODE SPW_PACKAGE_NODE_VERSION
+```
+
+The native runtime on `PATH` remains unchanged. With the package runtime
+variables exported, complete acceptance is:
+
 ```sh
-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 install --frozen-lockfile
+pnpm run check:static
+pnpm run test:acceptance
 ```
 
+After the checks, remove only the temporary directory created by this
+invocation and clear its variables:
+
+```sh
+rm -rf -- "$spw_runtime_dir"
+unset SPW_PACKAGE_NODE SPW_PACKAGE_NODE_VERSION spw_node_arch spw_node_archive spw_runtime_dir
+```
+
+Linux CI provisions the exact package runtime with `actions/setup-node`.
+Downloads happen only during prerequisite setup, never inside the hermetic test
+cases.
+
+Packaging compiles only production source into fresh external temporary staging:
+
+```sh
+node tests/tools/pack.ts --out-dir /absolute/existing/temporary/output
+```
+
+Allocate the existing output directory outside the checkout before running this
+command. It returns npm-compatible JSON for one validated tarball and removes its
+own staging. Bare checkout `npm pack` always fails with this command's guidance,
+even if stale `dist/` exists. Maintained or manager-generated JavaScript must not
+remain in the checkout; dependencies and generated upstream plugin content have
+separate ownership. This developer command does not authorize publication; follow
+`RELEASING.md` for the protected release procedure.
+
 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.
 
-Layer 4 is the Docker acceptance path. It is the required completion command
-because the isolated-container Codex probe graduated from a temporary
-nonblocking spike to a blocking acceptance gate. `sh tests/container.sh` runs
-the inner `sh tests/run.sh` suite and then the real Codex offline probe inside
-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.
+Layer 4 is the Docker acceptance path. `pnpm run test:harness:codex` runs the
+real Codex offline probe inside an isolated container home with networking
+disabled. `pnpm run test:acceptance` composes one host-side shared run with that
+probe. The container may mutate its throwaway container-local Codex state, but
+it performs no mutation of the developer's or runner's real Codex state.
+
+Release validation deliberately retains the combined shared-plus-Codex path at
+both native endpoints:
+
+```sh
+SPW_NATIVE_NODE_VERSION=24.12.0 sh tests/container.sh
+SPW_NATIVE_NODE_VERSION=24 sh tests/container.sh
+```
 
-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`.
+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.
+
+`sh tests/manual/codex-behavior-probe.sh` remains opt-in and covers native-only compatibility residue such as
+path/cache and version-precedence behavior against an intentionally real local
+Codex install. It is not part of acceptance. GitHub Actions runs two focused
+`toolchain` entries and one blocking Codex integration job on pull requests
+and pushes to `main`. The Node 24.12.0 toolchain entry checks native source
+loading, the suite runner/assertion preload, and package-producer success and
+failure. The latest-24 toolchain entry alone runs `pnpm run check:static` and
+the full shared suite with package-minimum evidence. The independent `test` job
+runs only the Codex offline probe on latest Node 24.x. Release acceptance still
+runs the combined shared and Codex paths at both native endpoints, and the
+installed npm executable is tested with Node 24.0.0. These runtime selectors
+are separate from the Homebrew-managed local commands above.
 
 ## 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)
+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, selection, provenance, and status modules
-  pin track-latest unpin                   # persistent-selection entrypoints
-  prepare probe install update uninstall   # lifecycle 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                                  # sole maintained CLI entry, parsing, preflight, dispatch
+  commands/                               # lifecycle and selection command handlers
+  adapter.ts                              # Codex integration
+tests/                                    # hermetic suite and manual Codex probe (tracked)
+  migration-inventory/                     # frozen historical evidence
+  tools/pack.ts                           # external staging and validated package emission
 ```
 
 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.