superpowers-manager 0.1.4 → 0.2.0

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.
@@ -41,28 +41,33 @@ It never removes the legacy provider automatically.
 
 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.
+`prepare`, `pin`, `track-latest`, and `unpin` do not require it. Codex is the
+only supported integration today.
 
 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.
 
-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 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 +78,29 @@ 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
-
-`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`.
+## Runtime architecture
 
-Without `SUPERPOWERS_REF`, the manager reads `config/upstream-ref`, which ships
-as `latest-release`. Accepted values include:
+- `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.
+- Codex is the only supported adapter today; no public harness selector ships
+  yet.
 
-- `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.
+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.
 
-```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
 
@@ -123,6 +126,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 |
@@ -130,74 +136,166 @@ 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`:
+Save a tag pin, commit pin, or explicit latest-stable policy for future
+invocations:
+
+```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
+```
 
-- `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.
+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`.
 
-Use `remove-add` only when an add-only refresh fails to take:
+`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:
+
+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_INSTALL_REFRESH_MODE=remove-add npx superpowers-manager update
+SUPERPOWERS_REF=feature/foo npx superpowers-manager probe
 ```
 
-## How generated versions work
+`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.
+- **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, 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)
 ```
 
-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,12 +1,12 @@
 #!/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
+ * @typedef {'pin' | 'track-latest' | 'unpin' | 'prepare' | 'probe' | 'install' | 'update' | 'uninstall'} Subcommand
  */
 
 /**
@@ -27,8 +27,22 @@ const { spawnSync } = require('child_process');
  * @typedef {{ file: string, argv: string[] }} SpawnDescriptor
  */
 
-const SUBCOMMANDS = ['prepare', 'probe', 'install', 'update', 'uninstall'];
-const CODEX_SUBCOMMANDS = ['probe', 'install', 'update', 'uninstall'];
+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',
@@ -57,18 +71,41 @@ 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)) {
-    return { kind: 'run', cmd: /** @type {Subcommand} */ (first), args: argv.slice(1) };
+    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}` };
 }
@@ -117,8 +154,15 @@ 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.
+/**
+ * @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
@@ -127,8 +171,17 @@ function discoverShell(env, platform) {
  */
 function preflight(cmd, env, platform) {
   const errors = [];
-  for (const tool of ['git', 'python3']) {
-    if (!findTool(tool, env, platform)) {
+  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`);
     }
   }
@@ -138,19 +191,8 @@ function preflight(cmd, env, platform) {
       ? '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`);
-    }
-  }
-  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
@@ -174,8 +216,14 @@ function buildSpawn(cmd, args, root, shell, platform) {
 
 function usage() {
   return [
-    'usage: superpowers-manager [prepare|probe|install|update|uninstall] [args...]',
+    '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',
@@ -184,9 +232,13 @@ function usage() {
     '',
     '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');
 }
 
@@ -196,7 +248,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 +282,9 @@ 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,
+  commandRequirements, 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.2.0",
   "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"