@phuc1403/musketeer 0.8.0 → 0.10.0

package/INSTALLATION.md

@@ -1,52 +1,52 @@
-# Prerequisites & Auto-Install
-
-`musketeer` auto-installs the external prerequisites required by your selected company
-(announced before each install, never silent). When no OS package manager is available — or
-an elevation prompt is refused — it falls back to printing the exact manual command below.
-
-> Filled in detail during Phase 06 (provisioner) / Phase 08 (publish).
-
-## Per-prerequisite matrix
-
-| Prereq | Needed by | Windows | macOS | Linux |
-|--------|-----------|---------|-------|-------|
-| Node 18+ | core | `winget install OpenJS.NodeJS.LTS` | `brew install node` | NodeSource / distro |
-| git | core, code-review | `winget install Git.Git` | `brew install git` | `apt/dnf/pacman install git` |
-| Python 3.8+ | core (skill-creator) | `winget install Python.Python.3.12` | `brew install python@3.12` | `apt install python3 python3-pip` |
-| Java 8+ | architecture (context-map) | `winget install Microsoft.OpenJDK` | `brew install --cask temurin` | `apt install openjdk-17-jdk` |
-| adr-tools | architecture (adr-writer) | `npm i -g @meza/adr-tools@2` | `npm i -g @meza/adr-tools@2` | `npm i -g @meza/adr-tools@2` |
-| gh | code-review (PR mode) | `winget install GitHub.cli` | `brew install gh` | `apt install gh` |
-
-> `adr-tools` is [`@meza/adr-tools`](https://www.npmjs.com/package/@meza/adr-tools) — the maintained
-> Node port of `npryce/adr-tools`. Same `adr` binary, same `.adr-dir`, same `NNNN-slug.md` files, so
-> existing ADRs carry over untouched. One npm command on every platform: no Git Bash, no admin
-> rights, no release zip.
->
-> It is the one prereq that needs **Node >= 22.13.0** (musketeer itself still only needs 18). It is
-> installed as a prereq rather than bundled: it is GPL-3.0 and musketeer is MIT, so musketeer
-> invokes it as a subprocess instead of depending on it.
->
-> Upgrading from `npryce/adr-tools`? Remove the old scripts first. They install as loose files in
-> `~/bin` or Git's `usr/bin`, and if either is earlier on your `PATH` the old `adr` keeps winning —
-> most visibly inside Git Bash.
-
-### Running muster without a terminal
-
-`musketeer muster` opens a picker, which needs a terminal. For CI, onboarding scripts, and agent
-sessions, name the company instead and the picker is skipped:
-
-```bash
-musketeer muster --company architecture,dotnet   # set the company to exactly these
-musketeer muster --keep                          # refresh the company already in .musketeer.json
-```
-
-`--keep` is the one to reach for after upgrading the CLI: it re-applies the latest templates
-without changing which musketeers are installed. Both flags survive the self-update re-exec.
-
-The `apt`/`brew` prereq installs can still prompt for `sudo` or wait on input. Pre-install them, or
-set `MUSKETEER_SKIP_INSTALL=1` to print the manual command instead of running it.
-
-## Secrets (never auto-installed)
-
-- `ANTHROPIC_API_KEY` — needed only by skill-creator's improve/loop scripts. You will be
-  prompted / shown how to set it; musketeer never writes it to the repo.
+# Prerequisites & Auto-Install
+
+`musketeer` auto-installs the external prerequisites required by your selected company
+(announced before each install, never silent). When no OS package manager is available — or
+an elevation prompt is refused — it falls back to printing the exact manual command below.
+
+> Filled in detail during Phase 06 (provisioner) / Phase 08 (publish).
+
+## Per-prerequisite matrix
+
+| Prereq | Needed by | Windows | macOS | Linux |
+|--------|-----------|---------|-------|-------|
+| Node 18+ | core | `winget install OpenJS.NodeJS.LTS` | `brew install node` | NodeSource / distro |
+| git | core, code-review | `winget install Git.Git` | `brew install git` | `apt/dnf/pacman install git` |
+| Python 3.8+ | core (skill-creator) | `winget install Python.Python.3.12` | `brew install python@3.12` | `apt install python3 python3-pip` |
+| Java 8+ | architecture (context-map) | `winget install Microsoft.OpenJDK` | `brew install --cask temurin` | `apt install openjdk-17-jdk` |
+| adr-tools | architecture (adr-writer) | `npm i -g @meza/adr-tools@2` | `npm i -g @meza/adr-tools@2` | `npm i -g @meza/adr-tools@2` |
+| gh | code-review (PR mode) | `winget install GitHub.cli` | `brew install gh` | `apt install gh` |
+
+> `adr-tools` is [`@meza/adr-tools`](https://www.npmjs.com/package/@meza/adr-tools) — the maintained
+> Node port of `npryce/adr-tools`. Same `adr` binary, same `.adr-dir`, same `NNNN-slug.md` files, so
+> existing ADRs carry over untouched. One npm command on every platform: no Git Bash, no admin
+> rights, no release zip.
+>
+> It is the one prereq that needs **Node >= 22.13.0** (musketeer itself still only needs 18). It is
+> installed as a prereq rather than bundled: it is GPL-3.0 and musketeer is MIT, so musketeer
+> invokes it as a subprocess instead of depending on it.
+>
+> Upgrading from `npryce/adr-tools`? Remove the old scripts first. They install as loose files in
+> `~/bin` or Git's `usr/bin`, and if either is earlier on your `PATH` the old `adr` keeps winning —
+> most visibly inside Git Bash.
+
+### Running muster without a terminal
+
+`musketeer muster` opens a picker, which needs a terminal. For CI, onboarding scripts, and agent
+sessions, name the company instead and the picker is skipped:
+
+```bash
+musketeer muster --company architecture,dotnet   # set the company to exactly these
+musketeer muster --keep                          # refresh the company already in .musketeer.json
+```
+
+`--keep` is the one to reach for after upgrading the CLI: it re-applies the latest templates
+without changing which musketeers are installed. Both flags survive the self-update re-exec.
+
+The `apt`/`brew` prereq installs can still prompt for `sudo` or wait on input. Pre-install them, or
+set `MUSKETEER_SKIP_INSTALL=1` to print the manual command instead of running it.
+
+## Secrets (never auto-installed)
+
+- `ANTHROPIC_API_KEY` — needed only by skill-creator's improve/loop scripts. You will be
+  prompted / shown how to set it; musketeer never writes it to the repo.

package/README.md

@@ -1,49 +1,49 @@
-# musketeer
-
-> Distributable custom Claude Code harness. One declarative command scaffolds a curated
-> **company** of **musketeers** (skills + agents + hooks) into any project's `./.claude/`.
-
-## Install
-
-```bash
-npm i -g @phuc1403/musketeer
-```
-
-## Use
-
-```bash
-musketeer muster     # self-update → pick company (multi-select) → refresh all selected skills to latest
-musketeer promote    # update the musketeer CLI itself to the latest published version
-musketeer            # show usage
-musketeer --help     # show usage
-```
-
-`musketeer muster` **self-updates first**: it pulls the latest published version (re-execing when behind),
-so the refresh always applies the newest template. Set `MUSKETEER_NO_SELF_UPDATE=1` to skip (offline / pinned).
-
-It is also **idempotent** and **force-updating**: the picker pre-checks your current company (from
-`.musketeer.json`); on confirm it **re-writes every selected musketeer's files to the latest template**
-(overwriting any local edits), removes newly-unchecked ones, regenerates `settings.json`, and auto-installs
-any missing prerequisites.
-
-`musketeer promote` upgrades the **CLI tool** itself (not your project's company): it checks the npm
-registry, and if a newer version exists, runs `npm i -g @phuc1403/musketeer@latest`. _muster = which
-musketeers are in this project; promote = upgrade the binary._
-
-## Musketeers (v1)
-
-| Musketeer | Default in muster | What it adds |
-|-----------|-------------------|--------------|
-| **core** | always on (locked, hidden) | research, handoff, skill-creator, git (+ git-manager agent) · statusline, usage-context, format-json hooks |
-| **architecture** | off | adr-writer, architecture-characteristic-writer, context-map · CML validation hook |
-| **hallmark** | off | hallmark, hallmark-explore, hallmark-loop · auditor/explorer agents |
-| **code-review** | off | code-review skill + code-reviewer agent |
-| **dotnet** | off | tdd, knowledge-crunching · EF migration guard hook · always merges 4 quality-gate props into root `Directory.Build.props` (`MUSKETEER_SKIP_DOTNET_PROPS=1` to skip) · scaffolds a generic `src`/`tests` Clean Architecture skeleton when the project is blank |
-| **design-docs** | off | inject-design-docs SessionStart hook |
-
-The muster starts every musketeer **unselected**, except ones you already installed (pre-checked from
-`.musketeer.json`). **core** is always included and isn't shown as a toggle — it can't be removed.
-
-Vocabulary: **musketeer** = a selectable unit · **muster** = the picker · **company** = your recruited set.
-
-See [INSTALLATION.md](INSTALLATION.md) for prerequisites and auto-install behavior.
+# musketeer
+
+> Distributable custom Claude Code harness. One declarative command scaffolds a curated
+> **company** of **musketeers** (skills + agents + hooks) into any project's `./.claude/`.
+
+## Install
+
+```bash
+npm i -g @phuc1403/musketeer
+```
+
+## Use
+
+```bash
+musketeer muster     # self-update → pick company (multi-select) → refresh all selected skills to latest
+musketeer promote    # update the musketeer CLI itself to the latest published version
+musketeer            # show usage
+musketeer --help     # show usage
+```
+
+`musketeer muster` **self-updates first**: it pulls the latest published version (re-execing when behind),
+so the refresh always applies the newest template. Set `MUSKETEER_NO_SELF_UPDATE=1` to skip (offline / pinned).
+
+It is also **idempotent** and **force-updating**: the picker pre-checks your current company (from
+`.musketeer.json`); on confirm it **re-writes every selected musketeer's files to the latest template**
+(overwriting any local edits), removes newly-unchecked ones, regenerates `settings.json`, and auto-installs
+any missing prerequisites.
+
+`musketeer promote` upgrades the **CLI tool** itself (not your project's company): it checks the npm
+registry, and if a newer version exists, runs `npm i -g @phuc1403/musketeer@latest`. _muster = which
+musketeers are in this project; promote = upgrade the binary._
+
+## Musketeers (v1)
+
+| Musketeer | Default in muster | What it adds |
+|-----------|-------------------|--------------|
+| **core** | always on (locked, hidden) | research, handoff, skill-creator, git (+ git-manager agent) · statusline, usage-quota, format-json hooks |
+| **architecture** | off | adr-writer, architecture-characteristic-writer, context-map · CML validation hook |
+| **hallmark** | off | hallmark, hallmark-explore, hallmark-loop · auditor/explorer agents |
+| **code-review** | off | code-review skill + code-reviewer agent |
+| **dotnet** | off | tdd, knowledge-crunching · EF migration guard hook · always merges 4 quality-gate props into root `Directory.Build.props` (`MUSKETEER_SKIP_DOTNET_PROPS=1` to skip) · scaffolds a generic `src`/`tests` Clean Architecture skeleton when the project is blank |
+| **design-docs** | off | inject-design-docs SessionStart hook |
+
+The muster starts every musketeer **unselected**, except ones you already installed (pre-checked from
+`.musketeer.json`). **core** is always included and isn't shown as a toggle — it can't be removed.
+
+Vocabulary: **musketeer** = a selectable unit · **muster** = the picker · **company** = your recruited set.
+
+See [INSTALLATION.md](INSTALLATION.md) for prerequisites and auto-install behavior.

package/bin/musketeer.js

@@ -1,168 +1,168 @@
-#!/usr/bin/env node
-'use strict';
-
-const { parseArgs } = require('node:util');
-
-const USAGE = `musketeer — scaffold a curated company of Claude Code musketeers into ./.claude
-
-Usage:
-  musketeer muster     Self-update to latest, then pick your company and refresh all selected skills
-  musketeer muster --keep
-                       Refresh the company already recorded in .musketeer.json, no picker
-  musketeer muster --company a,b
-                       Set the company to exactly these musketeers, no picker
-  musketeer promote    Update the musketeer CLI itself to the latest published version
-  musketeer            Show this help
-  musketeer --help     Show this help
-
-Notes:
-  * "muster" changes which musketeers are in THIS project; "promote" upgrades the CLI itself.
-  * On confirm, muster REFRESHES every selected musketeer's files to the latest template (overwrites local edits).
-  * muster auto-updates the CLI to the latest published version first (set MUSKETEER_NO_SELF_UPDATE=1 to skip).
-  * "core" is always installed and locked — it cannot be removed.
-  * The muster is multi-select: check every musketeer you want, then confirm.
-  * settings.json is GENERATED per-selection; missing prereqs are auto-installed (announced).
-  * --keep and --company skip the picker, so muster runs in CI and other sessions with no terminal.
-  * Without either flag and without a terminal, muster stops and tells you which flag to use.`;
-
-function parse(argv) {
-  return parseArgs({
-    args: argv,
-    options: {
-      help: { type: 'boolean', short: 'h', default: false },
-      company: { type: 'string' },
-      keep: { type: 'boolean', default: false },
-    },
-    allowPositionals: true,
-  });
-}
-
-/**
- * Work out what this muster should do before anything touches the disk.
- *
- * Bare `muster` opens the picker, which needs a terminal. Under CI, or any
- * agent without one, the picker used to die inside its own TTY setup with no
- * hint that a flag could have avoided it. Both flags skip the picker: --company
- * states the company outright, --keep reconciles the one already recorded.
- *
- * `forward` is what the self-update must replay when it re-execs the newer
- * binary, so a scripted run does not land back at the picker.
- *
- * @param {{company?:string, keep:boolean}} values parsed flags
- * @param {{isTTY:boolean, projectDir:string, readLockfile:function}} ctx
- * @returns {{desiredIds:?string[], interactive:boolean, forward:string[]}}
- */
-function resolveMusterPlan(values, ctx) {
-  if (values.company !== undefined && values.keep) {
-    throw new Error('Use either --company or --keep, not both: one sets the company, the other keeps it.');
-  }
-
-  if (values.company !== undefined) {
-    const ids = values.company
-      .split(',')
-      .map((s) => s.trim())
-      .filter(Boolean);
-    if (ids.length === 0) {
-      throw new Error('--company needs at least one musketeer, for example: --company architecture,dotnet');
-    }
-    return { desiredIds: ids, interactive: false, forward: [`--company=${ids.join(',')}`] };
-  }
-
-  if (values.keep) {
-    const prev = ctx.readLockfile(ctx.projectDir);
-    if (!prev.musketeers || prev.musketeers.length === 0) {
-      throw new Error(
-        'No company recorded in .musketeer.json, so there is nothing for --keep to keep. ' +
-          'Name one with --company, for example: --company architecture,dotnet'
-      );
-    }
-    return { desiredIds: prev.musketeers, interactive: false, forward: ['--keep'] };
-  }
-
-  if (!ctx.isTTY) {
-    throw new Error(
-      'muster needs a terminal for its picker, and this session has none. ' +
-        'Refresh the company already recorded with `musketeer muster --keep`, ' +
-        'or state one with `musketeer muster --company architecture,dotnet`.'
-    );
-  }
-
-  return { desiredIds: null, interactive: true, forward: [] };
-}
-
-async function main(argv = process.argv.slice(2)) {
-  let parsed;
-  try {
-    parsed = parse(argv);
-  } catch (err) {
-    process.stderr.write(`${err.message}\n\n${USAGE}\n`);
-    process.exitCode = 2;
-    return;
-  }
-
-  const { values, positionals } = parsed;
-  const command = positionals[0];
-
-  // `musketeer` alone (or --help) → usage.
-  if (values.help || !command) {
-    process.stdout.write(`${USAGE}\n`);
-    return;
-  }
-
-  if (command === 'muster') {
-    const { readLockfile } = require('../src/lockfile');
-    let plan;
-    try {
-      plan = resolveMusterPlan(values, {
-        isTTY: !!process.stdin.isTTY,
-        projectDir: process.cwd(),
-        readLockfile,
-      });
-    } catch (err) {
-      process.stderr.write(`${err.message}\n`);
-      process.exitCode = 2;
-      return;
-    }
-
-    // Pull the latest published version first, so the picker refreshes installed
-    // skills to the newest template (not a stale package's). Re-execs when behind.
-    const { ensureLatest } = require('../src/self-update');
-    const reexecCode = ensureLatest({ args: plan.forward });
-    if (reexecCode !== null) {
-      if (reexecCode !== 0) {
-        // The update landed, the refresh did not. Say so: the CLI is now newer
-        // than the templates in this project, and nothing announced the split.
-        process.stderr.write(
-          'The CLI was updated but this project was not refreshed — nothing in .claude changed. ' +
-            'Re-run `musketeer muster` once the problem above is resolved.\n'
-        );
-      }
-      process.exitCode = reexecCode;
-      return;
-    }
-    // Lazy-require so help never pays the cost of loading the engine/manifest.
-    const reconcile = require('../src/reconcile');
-    await reconcile.run({ desiredIds: plan.desiredIds, interactive: plan.interactive });
-    return;
-  }
-
-  if (command === 'promote') {
-    const promote = require('../src/promote');
-    await promote.run();
-    return;
-  }
-
-  process.stderr.write(`Unknown command "${command}".\n\n${USAGE}\n`);
-  process.exitCode = 2;
-}
-
-// Only run as a command. Requiring this file (the tests do, for
-// resolveMusterPlan) must not start a muster.
-if (require.main === module) {
-  main().catch((err) => {
-    process.stderr.write(`musketeer: ${err && err.message ? err.message : err}\n`);
-    process.exitCode = 1;
-  });
-}
-
-module.exports = { resolveMusterPlan, main };
+#!/usr/bin/env node
+'use strict';
+
+const { parseArgs } = require('node:util');
+
+const USAGE = `musketeer — scaffold a curated company of Claude Code musketeers into ./.claude
+
+Usage:
+  musketeer muster     Self-update to latest, then pick your company and refresh all selected skills
+  musketeer muster --keep
+                       Refresh the company already recorded in .musketeer.json, no picker
+  musketeer muster --company a,b
+                       Set the company to exactly these musketeers, no picker
+  musketeer promote    Update the musketeer CLI itself to the latest published version
+  musketeer            Show this help
+  musketeer --help     Show this help
+
+Notes:
+  * "muster" changes which musketeers are in THIS project; "promote" upgrades the CLI itself.
+  * On confirm, muster REFRESHES every selected musketeer's files to the latest template (overwrites local edits).
+  * muster auto-updates the CLI to the latest published version first (set MUSKETEER_NO_SELF_UPDATE=1 to skip).
+  * "core" is always installed and locked — it cannot be removed.
+  * The muster is multi-select: check every musketeer you want, then confirm.
+  * settings.json is GENERATED per-selection; missing prereqs are auto-installed (announced).
+  * --keep and --company skip the picker, so muster runs in CI and other sessions with no terminal.
+  * Without either flag and without a terminal, muster stops and tells you which flag to use.`;
+
+function parse(argv) {
+  return parseArgs({
+    args: argv,
+    options: {
+      help: { type: 'boolean', short: 'h', default: false },
+      company: { type: 'string' },
+      keep: { type: 'boolean', default: false },
+    },
+    allowPositionals: true,
+  });
+}
+
+/**
+ * Work out what this muster should do before anything touches the disk.
+ *
+ * Bare `muster` opens the picker, which needs a terminal. Under CI, or any
+ * agent without one, the picker used to die inside its own TTY setup with no
+ * hint that a flag could have avoided it. Both flags skip the picker: --company
+ * states the company outright, --keep reconciles the one already recorded.
+ *
+ * `forward` is what the self-update must replay when it re-execs the newer
+ * binary, so a scripted run does not land back at the picker.
+ *
+ * @param {{company?:string, keep:boolean}} values parsed flags
+ * @param {{isTTY:boolean, projectDir:string, readLockfile:function}} ctx
+ * @returns {{desiredIds:?string[], interactive:boolean, forward:string[]}}
+ */
+function resolveMusterPlan(values, ctx) {
+  if (values.company !== undefined && values.keep) {
+    throw new Error('Use either --company or --keep, not both: one sets the company, the other keeps it.');
+  }
+
+  if (values.company !== undefined) {
+    const ids = values.company
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean);
+    if (ids.length === 0) {
+      throw new Error('--company needs at least one musketeer, for example: --company architecture,dotnet');
+    }
+    return { desiredIds: ids, interactive: false, forward: [`--company=${ids.join(',')}`] };
+  }
+
+  if (values.keep) {
+    const prev = ctx.readLockfile(ctx.projectDir);
+    if (!prev.musketeers || prev.musketeers.length === 0) {
+      throw new Error(
+        'No company recorded in .musketeer.json, so there is nothing for --keep to keep. ' +
+          'Name one with --company, for example: --company architecture,dotnet'
+      );
+    }
+    return { desiredIds: prev.musketeers, interactive: false, forward: ['--keep'] };
+  }
+
+  if (!ctx.isTTY) {
+    throw new Error(
+      'muster needs a terminal for its picker, and this session has none. ' +
+        'Refresh the company already recorded with `musketeer muster --keep`, ' +
+        'or state one with `musketeer muster --company architecture,dotnet`.'
+    );
+  }
+
+  return { desiredIds: null, interactive: true, forward: [] };
+}
+
+async function main(argv = process.argv.slice(2)) {
+  let parsed;
+  try {
+    parsed = parse(argv);
+  } catch (err) {
+    process.stderr.write(`${err.message}\n\n${USAGE}\n`);
+    process.exitCode = 2;
+    return;
+  }
+
+  const { values, positionals } = parsed;
+  const command = positionals[0];
+
+  // `musketeer` alone (or --help) → usage.
+  if (values.help || !command) {
+    process.stdout.write(`${USAGE}\n`);
+    return;
+  }
+
+  if (command === 'muster') {
+    const { readLockfile } = require('../src/lockfile');
+    let plan;
+    try {
+      plan = resolveMusterPlan(values, {
+        isTTY: !!process.stdin.isTTY,
+        projectDir: process.cwd(),
+        readLockfile,
+      });
+    } catch (err) {
+      process.stderr.write(`${err.message}\n`);
+      process.exitCode = 2;
+      return;
+    }
+
+    // Pull the latest published version first, so the picker refreshes installed
+    // skills to the newest template (not a stale package's). Re-execs when behind.
+    const { ensureLatest } = require('../src/self-update');
+    const reexecCode = ensureLatest({ args: plan.forward });
+    if (reexecCode !== null) {
+      if (reexecCode !== 0) {
+        // The update landed, the refresh did not. Say so: the CLI is now newer
+        // than the templates in this project, and nothing announced the split.
+        process.stderr.write(
+          'The CLI was updated but this project was not refreshed — nothing in .claude changed. ' +
+            'Re-run `musketeer muster` once the problem above is resolved.\n'
+        );
+      }
+      process.exitCode = reexecCode;
+      return;
+    }
+    // Lazy-require so help never pays the cost of loading the engine/manifest.
+    const reconcile = require('../src/reconcile');
+    await reconcile.run({ desiredIds: plan.desiredIds, interactive: plan.interactive });
+    return;
+  }
+
+  if (command === 'promote') {
+    const promote = require('../src/promote');
+    await promote.run();
+    return;
+  }
+
+  process.stderr.write(`Unknown command "${command}".\n\n${USAGE}\n`);
+  process.exitCode = 2;
+}
+
+// Only run as a command. Requiring this file (the tests do, for
+// resolveMusterPlan) must not start a muster.
+if (require.main === module) {
+  main().catch((err) => {
+    process.stderr.write(`musketeer: ${err && err.message ? err.message : err}\n`);
+    process.exitCode = 1;
+  });
+}
+
+module.exports = { resolveMusterPlan, main };