superpowers-manager 0.1.4

package/.agents/plugins/marketplace.json

@@ -0,0 +1,21 @@
+{
+  "name": "superpowers-manager",
+  "interface": {
+    "displayName": "Superpowers Manager"
+  },
+  "plugins": [
+    {
+      "name": "superpowers",
+      "source": {
+        "source": "local",
+        "path": "./plugins/superpowers"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL",
+        "products": ["CODEX"]
+      },
+      "category": "Developer Tools"
+    }
+  ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jia "Jay" Tan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,203 @@
+# Superpowers Manager
+
+Install and update the latest stable
+[`obra/superpowers`](https://github.com/obra/superpowers) release directly from
+upstream, without waiting for agent marketplaces to catch up.
+Codex supported today.
+
+> Unofficial community integration. Not affiliated with the
+> `obra/superpowers` maintainers.
+
+## Quick start
+
+```sh
+npx superpowers-manager install
+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.
+
+| 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 |
+
+### Moving from `superpowers-wrapper`
+
+```sh
+npx superpowers-wrapper@0.1.1 uninstall
+npx superpowers-manager@0.1.4 install
+```
+
+The manager detects legacy wrapper-owned Codex state and stops before mutation.
+It never removes the legacy provider automatically.
+
+## Requirements and platforms
+
+Superpowers Manager requires Node 24+, `git`, Python 3, and a POSIX `sh`.
+Codex CLI is required for `probe`, `install`, `update`, and `uninstall`;
+`prepare` does not require it.
+
+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.
+
+## 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.
+- 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.
+
+## 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`.
+
+Without `SUPERPOWERS_REF`, the manager reads `config/upstream-ref`, which ships
+as `latest-release`. Accepted values include:
+
+- `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_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.
+
+## Provider ownership
+
+If another `superpowers` provider is installed, remove or disable it yourself
+before installing this one. The manager never removes another provider and
+mutates only `superpowers@superpowers-manager` and the `superpowers-manager`
+marketplace.
+
+For example, if you intentionally want the manager to take over from the
+official provider:
+
+```sh
+codex plugin remove superpowers@openai-curated
+npx superpowers-manager install
+```
+
+Manager install, update, and uninstall commands inspect both current and legacy
+identities and fail closed when Codex state cannot be read or parsed. If legacy
+`superpowers-wrapper` state remains, use the migration commands above; the
+manager will not remove it for you.
+
+## Lifecycle commands
+
+| Command | Codex side effects | Purpose |
+|---|---|---|
+| `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 |
+| `npx superpowers-manager update` | Marketplace and plugin state when stale | Probe, prepare and/or install as needed, then verify the refresh |
+| `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.
+
+### Refresh modes
+
+`install` and `update` accept `SUPERPOWERS_INSTALL_REFRESH_MODE`:
+
+- `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.
+
+Use `remove-add` only when an add-only refresh fails to take:
+
+```sh
+SUPERPOWERS_INSTALL_REFRESH_MODE=remove-add npx superpowers-manager update
+```
+
+## How generated versions work
+
+- 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>`.
+
+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`.
+
+`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.
+
+## 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
+```
+
+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.
+
+## Repository layout
+
+```text
+.agents/plugins/marketplace.json           # local manager marketplace definition
+bin/superpowers-manager.js                 # npm CLI launcher
+config/upstream-ref                        # default upstream ref
+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)
+```
+
+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.

package/bin/superpowers-manager.js

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

package/config/upstream-ref

@@ -0,0 +1 @@
+latest-release

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "superpowers-manager",
+  "version": "0.1.4",
+  "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",
+    "obra-superpowers",
+    "agent-skills",
+    "ai-coding-agent",
+    "coding-agent",
+    "agent-harness",
+    "codex",
+    "codex-plugin",
+    "plugin-manager",
+    "cli",
+    "installer",
+    "updater"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/j7an/superpowers-manager.git"
+  },
+  "homepage": "https://github.com/j7an/superpowers-manager#readme",
+  "bugs": {
+    "url": "https://github.com/j7an/superpowers-manager/issues"
+  },
+  "bin": {
+    "superpowers-manager": "bin/superpowers-manager.js"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "config/upstream-ref",
+    ".agents/plugins/marketplace.json",
+    "plugins/superpowers/.codex-plugin/plugin.template.json",
+    "README.md"
+  ]
+}

package/plugins/superpowers/.codex-plugin/plugin.template.json

@@ -0,0 +1,23 @@
+{
+  "name": "superpowers",
+  "version": "0.0.0+manager.template",
+  "description": "Local manager for upstream Superpowers skills.",
+  "author": {
+    "name": "superpowers-manager"
+  },
+  "repository": "https://github.com/obra/superpowers",
+  "license": "MIT",
+  "keywords": ["superpowers", "skills", "codex"],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Superpowers",
+    "shortDescription": "Upstream Superpowers skills from a local manager.",
+    "longDescription": "A local Codex manager that prepares upstream Superpowers runtime files from the configured Git ref.",
+    "developerName": "superpowers-manager",
+    "category": "Developer Tools",
+    "capabilities": ["skills"],
+    "defaultPrompt": [
+      "Use Superpowers skills when they match the task."
+    ]
+  }
+}

package/scripts/install

@@ -0,0 +1,58 @@
+#!/bin/sh
+set -eu
+
+root=$(CDPATH= cd -- "$(dirname "$0")/.." && pwd)
+. "$root/scripts/lib.sh"
+
+codex_bin="${SUPERPOWERS_CODEX:-codex}"
+refresh_mode="${SUPERPOWERS_INSTALL_REFRESH_MODE:-add-only}"
+
+spw_require_command "$codex_bin"
+spw_require_command python3
+
+case "$refresh_mode" in
+  add-only|remove-add) ;;
+  *) spw_die "unsupported SUPERPOWERS_INSTALL_REFRESH_MODE: $refresh_mode" ;;
+esac
+
+echo "Note: remove or disable conflicting Superpowers providers yourself before relying on manager-provided skills."
+
+# Prepare-before-mutate: probe, and (re)generate the plugin tree if it is
+# missing or stale — including validation — entirely before any Codex
+# marketplace or plugin mutation. A failed prepare leaves Codex untouched.
+probe_output=$(sh "$root/scripts/probe" --porcelain)
+identity_state=$(printf '%s\n' "$probe_output" | awk -F= '$1 == "identity_state" { print $2 }')
+[ -n "$identity_state" ] || spw_die "probe did not report Codex identity state"
+spw_require_no_legacy_state "$identity_state"
+status=$(printf '%s\n' "$probe_output" | awk -F= '$1 == "status" { print $2 }')
+case "$status" in
+  needs\ prepare)
+    sh "$root/scripts/prepare"
+    ;;
+  needs\ install|current)
+    ;;
+  *)
+    printf '%s\n' "$probe_output"
+    spw_die "unknown probe status: $status"
+    ;;
+esac
+
+desired_commit=$(spw_metadata_commit_or_empty "$root/plugins/superpowers/.superpowers-upstream.json" || true)
+[ -n "$desired_commit" ] || spw_die "generated metadata missing desired commit after prepare"
+
+# Reconcile the manager marketplace pointer to this package root, then always
+# run the Codex install step: `install` means "make Codex use this root" and
+# never skips it because the generated tree looks current.
+spw_reconcile_marketplace "$codex_bin" "$root"
+
+case "$refresh_mode" in
+  remove-add)
+    "$codex_bin" plugin remove "$SPW_PLUGIN_ID" || true
+    ;;
+esac
+
+if ! "$codex_bin" plugin add "$SPW_PLUGIN_ID"; then
+  spw_die "codex plugin add failed for $SPW_PLUGIN_ID"
+fi
+
+spw_verify_refresh "$desired_commit"