superpowers-manager 0.2.0 → 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,14 +39,32 @@ 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.
+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.
 
 Network needs depend on the saved policy. `pin` verifies its target;
 `track-latest` and invocation overrides resolve from upstream when applied; and
@@ -60,30 +78,40 @@ updates.
 - 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).
+- `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 +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
 
@@ -218,15 +269,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`.
@@ -256,11 +309,16 @@ updates the official provider or any other provider automatically.
 ## 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.
@@ -273,29 +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, 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                                  # 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,290 +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 {'pin' | 'track-latest' | 'unpin' | '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 = [
-  'pin', 'track-latest', 'unpin', 'prepare', 'probe', 'install', 'update', 'uninstall',
-];
-const PIN_TAG_RE = /^v(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)(?:-(?:(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*))?$/;
-const PIN_COMMIT_RE = /^[0-9A-Fa-f]{40}$/;
-/** @type {Record<Subcommand, string[]>} */
-const COMMAND_REQUIREMENTS = {
-  pin: ['git', 'python3'],
-  'track-latest': ['python3'],
-  unpin: [],
-  prepare: ['git', 'python3'],
-  probe: ['git', 'python3', 'codex'],
-  install: ['git', 'python3', 'codex'],
-  update: ['git', 'python3', 'codex'],
-  uninstall: ['python3', 'codex'],
-};
-// 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);
-}
-
-/**
- * @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)) {
-    const args = argv.slice(1);
-    if (first === 'pin' && args.length !== 1) {
-      return { kind: 'usage-error', message: 'usage: superpowers-manager pin REF' };
-    }
-    if (first === 'pin' && !PIN_TAG_RE.test(args[0]) && !PIN_COMMIT_RE.test(args[0])) {
-      return {
-        kind: 'usage-error',
-        message: 'pin REF must be an exact v-prefixed SemVer tag or full 40-hex commit',
-      };
-    }
-    if ((first === 'track-latest' || first === 'unpin') && args.length !== 0) {
-      return { kind: 'usage-error', message: `usage: superpowers-manager ${first}` };
-    }
-    return { kind: 'run', cmd: /** @type {Subcommand} */ (first), args };
-  }
-  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);
+if (!existsSync(cliUrl)) {
+  console.error(
+    "dist/ not built — run `pnpm install --frozen-lockfile && pnpm run build`",
+  );
+  process.exit(1);
 }
 
-/**
- * @returns {Record<Subcommand, string[]>}
- */
-function commandRequirements() {
-  return COMMAND_REQUIREMENTS;
-}
-
-// Tool preflight; never touches Codex state. Requirements are specific to the
-// selected command, while a POSIX shell remains mandatory for every command.
-/**
- * @param {Subcommand} cmd
- * @param {NodeJS.ProcessEnv} env
- * @param {NodeJS.Platform} platform
- * @returns {PreflightResult}
- */
-function preflight(cmd, env, platform) {
-  const errors = [];
-  for (const tool of COMMAND_REQUIREMENTS[cmd]) {
-    if (tool === 'codex') {
-      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`);
-      }
-    } else 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 (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 [command] [args...]',
-    '',
-    'Selection commands (save intent only; they do not prepare or install it):',
-    '  pin REF       save an exact upstream release tag or commit',
-    '  track-latest  save selection of the latest stable upstream release',
-    '  unpin         remove the saved selection and return to the packaged fallback',
-    '',
-    'Apply and lifecycle commands:',
-    '  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_CONFIG_DIR, XDG_CONFIG_HOME,',
-    'SUPERPOWERS_PLUGIN_ROOT, SUPERPOWERS_MANIFEST_TEMPLATE,',
-    'SUPERPOWERS_VALIDATOR,',
-    'SUPERPOWERS_INSTALLED_SEARCH_ROOT, SUPERPOWERS_INSTALL_REFRESH_MODE',
-    '',
-    'Selection state uses SUPERPOWERS_CONFIG_DIR when set; otherwise it uses',
-    '$XDG_CONFIG_HOME/superpowers-manager, then $HOME/.config/superpowers-manager.',
-  ].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,
-  commandRequirements, preflight, buildSpawn, usage,
-};
-
-if (isMain(import.meta.filename, process.argv[1])) main();
+const { main } = await import(cliUrl.href);
+main();