superpowers-manager 0.1.4 → 0.1.6

package/README.md

@@ -31,7 +31,7 @@ and explicit install/update/probe/uninstall lifecycle control.
 
 ```sh
 npx superpowers-wrapper@0.1.1 uninstall
-npx superpowers-manager@0.1.4 install
+npx superpowers-manager install
 ```
 
 The manager detects legacy wrapper-owned Codex state and stops before mutation.
@@ -55,14 +55,15 @@ manager does not run automatic or background updates.
 
 - Resolves an upstream ref, defaulting to the latest stable `vX.Y.Z` release
   tag.
-- Clones or fetches that exact upstream commit and assembles a Codex plugin tree
-  under `plugins/superpowers/`.
-- Preserves the upstream manifest when available, while applying the
-  manager-owned plugin contract.
-- Records `source`, `requested_ref`, `resolved_ref`, `commit`, and the upstream
-  manifest version in `.superpowers-upstream.json`.
-- Validates the candidate tree before replacing a previous generated tree or
-  mutating Codex state.
+- 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).
+- 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).
 - Registers the `superpowers-manager` marketplace and installs or refreshes
   `superpowers@superpowers-manager` in Codex.
 
@@ -73,31 +74,28 @@ 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.
 
-## Choosing the upstream version
+## Runtime architecture
 
-`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`.
+- `scripts/core/` owns the shared lifecycle, status, and protocol validation.
+- `scripts/adapters/codex/` owns build, inspection, reconciliation, and Codex
+  mutation.
+- Codex is the only supported adapter today; no public harness selector ships
+  yet.
 
-Without `SUPERPOWERS_REF`, the manager reads `config/upstream-ref`, which ships
-as `latest-release`. Accepted values include:
+Validation checks the manager-owned manifest overlay, generated-tree structure,
+skill frontmatter envelope, known local paths, and provenance. It deliberately
+does not implement a general YAML parser or mirror every Codex ingestion rule;
+upstream owns skill semantics and Codex owns its evolving schema.
 
-- `latest-release` — the highest stable `vX.Y.Z` tag; prereleases are excluded.
-- A specific tag, such as `v6.0.3`.
-- A full 40-character commit SHA.
-- Any other ref upstream resolves, such as `main` or a branch name.
-
-```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_VALIDATOR=/path/to/validator.py` adds an optional Python validator
+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.
 
-`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.
+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.
 
 ## Provider ownership
 
@@ -130,74 +128,119 @@ manager will not remove it for you.
 | `npx superpowers-manager uninstall` | Marketplace and plugin state | Remove only manager-owned Codex state and verify removal |
 
 Calling `npx superpowers-manager` without a subcommand is equivalent to
-`update`. `probe` is read-only. Install and update prepare and validate before changing Codex state.
-Uninstall inspects and removes only manager-owned Codex state. Those mutating
-commands fail closed when required state cannot be inspected and refuse to
-report success when the resulting state cannot be verified.
+`update`. `probe` is read-only. Install and update stop before prepare or Codex
+mutation when legacy state is present. Uninstall removes only manager-owned
+state and reports any legacy residue without modifying it. These commands fail
+closed when required state cannot be inspected and refuse to report success
+when resulting manager state cannot be verified.
 
-### Refresh modes
+## Choosing the upstream version
 
-`install` and `update` accept `SUPERPOWERS_INSTALL_REFRESH_MODE`:
+`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`.
 
-- `add-only` (default) asks Codex to add the plugin from the current local
-  marketplace source.
-- `remove-add` removes only the manager-owned plugin before adding it again.
+Without `SUPERPOWERS_REF`, the manager reads `config/upstream-ref`, which ships
+as `latest-release`. Accepted values include:
 
-Use `remove-add` only when an add-only refresh fails to take:
+- `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).
 
 ```sh
-SUPERPOWERS_INSTALL_REFRESH_MODE=remove-add npx superpowers-manager update
+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
 ```
 
-## How generated versions work
+`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.
+
+## 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.
+- **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`.
+- **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.
+- 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`.
+- Branch builds deliberately stay below real releases:
+  `main` generates `0.0.0-main+manager.<short-sha>` and other named refs
+  generate `0.0.0-ref-<sanitized-ref>+manager.<short-sha>`.
+- Raw 40-character commit SHAs generate `0.0.0+manager.<short-sha>`.
+- **`.superpowers-upstream.json`** records the authoritative provenance:
+  `source`, `requested_ref`, `resolved_ref`, `commit`, and the upstream manifest
+  version. The generated manifest version is for human readability and Codex
+  package identity; the upstream `commit` is what `probe`/`update` compare
+  against.
+
+## Refresh modes
 
-- If upstream provides `.codex-plugin/plugin.json`, the manager uses it as the
-  manifest base and preserves unknown upstream fields.
-- The committed fallback template supports older refs without an upstream
-  manifest and uses the placeholder version `0.0.0+manager.template`.
-- Stable tags produce versions such as `6.0.3+manager.896224c`; explicit
-  prereleases produce versions such as `6.1.0-beta.1+manager.abc1234`.
-- `main` produces `0.0.0-main+manager.<short-sha>`; other named refs produce
-  `0.0.0-ref-<sanitized-ref>+manager.<short-sha>`.
-- Full commit SHAs produce `0.0.0+manager.<short-sha>`.
+`install` and `update` accept `SUPERPOWERS_INSTALL_REFRESH_MODE`:
 
-The generated version is for readable Codex package identity. The exact commit
-in `.superpowers-upstream.json` is the authoritative value compared by `probe`
-and `update`.
+- `add-only` (default) — `plugin add` re-reads the local source, which refreshes
+  a mutated tree. Verified sufficient for local marketplaces.
+- `remove-add` — removes the manager's own plugin first, then re-adds it. Use
+  only if a refresh ever fails to take:
 
-`SUPERPOWERS_VALIDATOR=/path/to/validator.py` adds an optional Python validator
-after the built-in generated-tree validation. It receives the candidate plugin
-root as its only argument. It cannot bypass the built-in validator, and either
-check failing prevents replacement and Codex mutation.
+  ```sh
+  SUPERPOWERS_INSTALL_REFRESH_MODE=remove-add npx superpowers-manager update
+  ```
 
 ## Tests
 
 ```sh
-sh tests/run.sh        # Layers 1-3: hermetic, no network or real Codex state
-sh tests/container.sh  # Layer 4: blocking isolated real-Codex CLI check
+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
 ```
 
-The container suite runs with networking disabled and a throwaway home, so it
-may mutate only isolated container state. The optional
-`tests/manual/codex-behavior-probe.sh` is reserved for intentional native-only
-compatibility residue and is not part of acceptance.
+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.
+
+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`.
 
 ## Repository layout
 
-```text
-.agents/plugins/marketplace.json           # local manager marketplace definition
-bin/superpowers-manager.js                 # npm CLI launcher
-config/upstream-ref                        # default upstream ref
+```
+.agents/plugins/marketplace.json          # local marketplace definition (tracked)
+config/upstream-ref                        # which upstream ref to track (tracked)
 plugins/superpowers/
-  .codex-plugin/plugin.template.json       # tracked fallback manifest
-  .codex-plugin/plugin.json                # generated manifest (ignored)
-  skills/ assets/ LICENSE ...              # generated from upstream (ignored)
-  .superpowers-upstream.json               # generated provenance (ignored)
-scripts/                                   # prepare/probe/install/update/uninstall
-tests/                                     # hermetic and isolated-container suites
-.cache/upstream/                           # optional upstream clone cache (ignored)
+  .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)
 ```
 
-Everything under `plugins/superpowers/` except the fallback manifest template
-is generated by `prepare` and ignored by Git. Do not edit generated plugin
-content; regenerate it instead.
+Everything under `plugins/superpowers/` except the fallback manifest template is
+generated by `prepare` and ignored by Git; re-run `prepare` to regenerate it.

package/bin/superpowers-manager.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
-'use strict';
+// @ts-check
 
-const fs = require('fs');
-const path = require('path');
-const { spawnSync } = require('child_process');
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { spawnSync } from 'node:child_process';
 
 /**
  * @typedef {'prepare' | 'probe' | 'install' | 'update' | 'uninstall'} Subcommand
@@ -57,14 +57,24 @@ function resolvePackageRoot(scriptPath) {
   }
 }
 
+/**
+ * @param {string} moduleFilename
+ * @param {string | undefined} argvPath
+ * @returns {boolean}
+ */
+function isMain(moduleFilename, argvPath) {
+  if (!argvPath) return false;
+  return moduleFilename === fs.realpathSync(argvPath);
+}
+
 /**
  * @param {string[]} argv
  * @returns {ParseResult}
  */
 function parseArgs(argv) {
-  if (argv.length === 0) return { kind: 'run', cmd: 'update', args: [] };
   /** @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)) {
@@ -117,8 +127,8 @@ function discoverShell(env, platform) {
   return findTool('bash', env, platform);
 }
 
-// Tool preflight; never touches Codex state. codex is required for subcommands
-// whose scripts read or mutate Codex state.
+// 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
@@ -148,9 +158,8 @@ function preflight(cmd, env, platform) {
       errors.push(`required command not found: ${codexBin} — install the Codex CLI or set SUPERPOWERS_CODEX`);
     }
   }
-  return errors.length
-    ? { ok: false, errors }
-    : { ok: true, shell: /** @type {string} */ (shell) };
+  if (errors.length) return { ok: false, errors };
+  return { ok: true, shell: /** @type {string} */ (shell) };
 }
 
 // POSIX executes the script directly (#!/bin/sh shebang); Windows cannot
@@ -196,7 +205,7 @@ function main() {
     console.log(usage());
     process.exit(0);
   }
-  const root = resolvePackageRoot(__filename);
+  const root = resolvePackageRoot(import.meta.filename);
   if (!root) {
     console.error('error: cannot resolve the superpowers-manager package root');
     process.exit(1);
@@ -230,6 +239,6 @@ function main() {
   process.exit(res.status === null ? 1 : res.status);
 }
 
-module.exports = { resolvePackageRoot, parseArgs, findTool, discoverShell, preflight, buildSpawn, usage };
+export { resolvePackageRoot, isMain, parseArgs, findTool, discoverShell, preflight, buildSpawn, usage };
 
-if (require.main === module) main();
+if (isMain(import.meta.filename, process.argv[1])) main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superpowers-manager",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Install and update the latest stable obra/superpowers release directly from upstream, without waiting for agent marketplaces to catch up. Codex supported today.",
   "keywords": [
     "superpowers",
@@ -17,6 +17,7 @@
     "updater"
   ],
   "license": "MIT",
+  "type": "module",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/j7an/superpowers-manager.git"