@phuc1403/musketeer 0.4.0 → 0.6.0

package/INSTALLATION.md

@@ -1,32 +1,47 @@
-# 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) | download the [release zip](https://github.com/npryce/adr-tools/releases), copy `src/*` into `C:\Program Files\Git\usr\bin` (Git Bash) | `brew install adr-tools` | `apt install adr-tools` · Arch: AUR `adr-tools` · Fedora/RHEL: clone + add `src/` to `PATH` |
-| gh | code-review (PR mode) | `winget install GitHub.cli` | `brew install gh` | `apt install gh` |
-
-> `adr-tools` is a set of bash scripts. On Windows it runs inside Git Bash (already required by
-> core), so the skill works — but `musketeer muster` cannot detect it from `cmd.exe` and will print
-> a manual-install line every run. Expected; ignore it once `adr config` works in Git Bash.
->
-> Running `musketeer muster` non-interactively (CI, onboarding scripts)? The `apt`/`brew` install
-> commands can prompt for `sudo` or hang waiting for input. Pre-install the prereqs yourself, or
-> set `MUSKETEER_SKIP_INSTALL=1` to print the manual command instead of executing it (red team
-> finding 8).
-
-## 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) | download the [release zip](https://github.com/npryce/adr-tools/releases), copy `src/*` into `C:\Program Files\Git\usr\bin` (Git Bash) | `brew install adr-tools` | `apt install adr-tools` · Arch: AUR `adr-tools` · Fedora/RHEL: clone + add `src/` to `PATH` |
+| gh | code-review (PR mode) | `winget install GitHub.cli` | `brew install gh` | `apt install gh` |
+
+> `adr-tools` is a set of bash scripts. On Windows it runs inside Git Bash (already required by
+> core), which is where muster now probes for it, so a working install is reported as present.
+>
+> On Windows, keep the project on a path with no spaces. `adr-tools` resolves its ADR directory
+> with an unquoted path test, so a space makes it fall back to a `doc/adr` default and write the
+> record where nothing indexes it. Musketeer refuses the call rather than let that happen, but the
+> underlying tool is still wrong.
+
+### 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-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.

package/bin/musketeer.js

@@ -1,79 +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 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).`;
-
-function parse(argv) {
-  return parseArgs({
-    args: argv,
-    options: {
-      help: { type: 'boolean', short: 'h', default: false },
-    },
-    allowPositionals: true,
-  });
-}
-
-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') {
-    // 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();
-    if (reexecCode !== null) {
-      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: null, interactive: true });
-    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;
-}
-
-main().catch((err) => {
-  process.stderr.write(`musketeer: ${err && err.message ? err.message : err}\n`);
-  process.exitCode = 1;
-});
+#!/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 };