@phuc1403/musketeer 0.5.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/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 };

package/manifest.json

@@ -59,6 +59,7 @@
         "hooks/validate-cml-hook.js",
         "hooks/validate-characteristics-hook.cjs",
         "hooks/lib/characteristics/**",
+        "hooks/lib/adr/**",
         "hooks/sync-adr-toc.cjs",
         "hooks/warn-missing-characteristics.cjs",
         "hooks/block-unsafe-adr-title.cjs",
@@ -267,6 +268,7 @@
     },
     "adr-tools": {
       "detect": "adr config",
+      "detectShell": "bash",
       "kind": "package",
       "needs": ["git"],
       "install": {

package/package.json

@@ -1,46 +1,46 @@
-{
-  "name": "@phuc1403/musketeer",
-  "version": "0.5.0",
-  "description": "Distributable custom Claude Code harness — one declarative command scaffolds a curated company of musketeers (skills/agents/hooks) into any project's .claude/.",
-  "type": "commonjs",
-  "bin": {
-    "musketeer": "bin/musketeer.js"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "scripts": {
-    "test": "node --test"
-  },
-  "files": [
-    "bin",
-    "src",
-    "manifest.json",
-    "template",
-    "README.md",
-    "INSTALLATION.md",
-    "LICENSE"
-  ],
-  "keywords": [
-    "claude",
-    "claude-code",
-    "harness",
-    "scaffolder",
-    "cli",
-    "skills",
-    "agents",
-    "hooks"
-  ],
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/phamhongphuc1403/musketeer.git"
-  },
-  "bugs": {
-    "url": "https://github.com/phamhongphuc1403/musketeer/issues"
-  },
-  "homepage": "https://github.com/phamhongphuc1403/musketeer#readme",
-  "dependencies": {
-    "@clack/prompts": "^0.7.0"
-  }
-}
+{
+  "name": "@phuc1403/musketeer",
+  "version": "0.6.0",
+  "description": "Distributable custom Claude Code harness — one declarative command scaffolds a curated company of musketeers (skills/agents/hooks) into any project's .claude/.",
+  "type": "commonjs",
+  "bin": {
+    "musketeer": "bin/musketeer.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "files": [
+    "bin",
+    "src",
+    "manifest.json",
+    "template",
+    "README.md",
+    "INSTALLATION.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "harness",
+    "scaffolder",
+    "cli",
+    "skills",
+    "agents",
+    "hooks"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/phamhongphuc1403/musketeer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/phamhongphuc1403/musketeer/issues"
+  },
+  "homepage": "https://github.com/phamhongphuc1403/musketeer#readme",
+  "dependencies": {
+    "@clack/prompts": "^0.7.0"
+  }
+}

package/src/dotnet-scaffold-copier.js

@@ -1,72 +1,72 @@
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-
-function containedPath(root, candidate) {
-  const resolvedRoot = path.resolve(root);
-  const resolved = path.resolve(candidate);
-  if (resolved !== resolvedRoot && !resolved.startsWith(resolvedRoot + path.sep)) return null;
-  return resolved;
-}
-
-function substitute(text, token, replacement) {
-  return text.split(token).join(replacement);
-}
-
-/**
- * Recursively copy every file under srcDir into stagingDir, substituting
- * `token` with `replacement` in both path segments and file contents. Every
- * computed destination path is validated to stay under `stagingDir` — rejects
- * (throws) rather than writing outside it.
- * @param {string} srcDir
- * @param {string} stagingDir
- * @param {string} token
- * @param {string} replacement
- */
-function copyTemplateWithTokenSubstitution(srcDir, stagingDir, token, replacement) {
-  walk(srcDir, stagingDir, stagingDir, token, replacement);
-}
-
-function walk(currentSrc, currentDest, stagingRoot, token, replacement) {
-  const entries = fs.readdirSync(currentSrc, { withFileTypes: true });
-  for (const entry of entries) {
-    const substitutedName = substitute(entry.name, token, replacement);
-    const srcPath = path.join(currentSrc, entry.name);
-    const destPath = containedPath(stagingRoot, path.join(currentDest, substitutedName));
-    if (!destPath) {
-      throw new Error(`copyTemplateWithTokenSubstitution: computed path escapes staging dir: "${substitutedName}"`);
-    }
-
-    if (entry.isDirectory()) {
-      fs.mkdirSync(destPath, { recursive: true });
-      walk(srcPath, destPath, stagingRoot, token, replacement);
-    } else if (entry.isFile()) {
-      fs.mkdirSync(path.dirname(destPath), { recursive: true });
-      const content = fs.readFileSync(srcPath, 'utf8');
-      fs.writeFileSync(destPath, substitute(content, token, replacement), 'utf8');
-    }
-  }
-}
-
-/**
- * Move every top-level entry from stagingDir into projectDir. Pre-checks all
- * names for collisions before moving any of them, then moves each via
- * fs.renameSync (atomic per entry on the same filesystem). Throws instead of
- * silently overwriting if a destination name already exists.
- * @param {string} stagingDir
- * @param {string} projectDir
- */
-function promoteStagedScaffold(stagingDir, projectDir) {
-  const entries = fs.readdirSync(stagingDir, { withFileTypes: true });
-  for (const entry of entries) {
-    if (fs.existsSync(path.join(projectDir, entry.name))) {
-      throw new Error(`promoteStagedScaffold: "${entry.name}" already exists at destination`);
-    }
-  }
-  for (const entry of entries) {
-    fs.renameSync(path.join(stagingDir, entry.name), path.join(projectDir, entry.name));
-  }
-}
-
-module.exports = { copyTemplateWithTokenSubstitution, promoteStagedScaffold };
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function containedPath(root, candidate) {
+  const resolvedRoot = path.resolve(root);
+  const resolved = path.resolve(candidate);
+  if (resolved !== resolvedRoot && !resolved.startsWith(resolvedRoot + path.sep)) return null;
+  return resolved;
+}
+
+function substitute(text, token, replacement) {
+  return text.split(token).join(replacement);
+}
+
+/**
+ * Recursively copy every file under srcDir into stagingDir, substituting
+ * `token` with `replacement` in both path segments and file contents. Every
+ * computed destination path is validated to stay under `stagingDir` — rejects
+ * (throws) rather than writing outside it.
+ * @param {string} srcDir
+ * @param {string} stagingDir
+ * @param {string} token
+ * @param {string} replacement
+ */
+function copyTemplateWithTokenSubstitution(srcDir, stagingDir, token, replacement) {
+  walk(srcDir, stagingDir, stagingDir, token, replacement);
+}
+
+function walk(currentSrc, currentDest, stagingRoot, token, replacement) {
+  const entries = fs.readdirSync(currentSrc, { withFileTypes: true });
+  for (const entry of entries) {
+    const substitutedName = substitute(entry.name, token, replacement);
+    const srcPath = path.join(currentSrc, entry.name);
+    const destPath = containedPath(stagingRoot, path.join(currentDest, substitutedName));
+    if (!destPath) {
+      throw new Error(`copyTemplateWithTokenSubstitution: computed path escapes staging dir: "${substitutedName}"`);
+    }
+
+    if (entry.isDirectory()) {
+      fs.mkdirSync(destPath, { recursive: true });
+      walk(srcPath, destPath, stagingRoot, token, replacement);
+    } else if (entry.isFile()) {
+      fs.mkdirSync(path.dirname(destPath), { recursive: true });
+      const content = fs.readFileSync(srcPath, 'utf8');
+      fs.writeFileSync(destPath, substitute(content, token, replacement), 'utf8');
+    }
+  }
+}
+
+/**
+ * Move every top-level entry from stagingDir into projectDir. Pre-checks all
+ * names for collisions before moving any of them, then moves each via
+ * fs.renameSync (atomic per entry on the same filesystem). Throws instead of
+ * silently overwriting if a destination name already exists.
+ * @param {string} stagingDir
+ * @param {string} projectDir
+ */
+function promoteStagedScaffold(stagingDir, projectDir) {
+  const entries = fs.readdirSync(stagingDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (fs.existsSync(path.join(projectDir, entry.name))) {
+      throw new Error(`promoteStagedScaffold: "${entry.name}" already exists at destination`);
+    }
+  }
+  for (const entry of entries) {
+    fs.renameSync(path.join(stagingDir, entry.name), path.join(projectDir, entry.name));
+  }
+}
+
+module.exports = { copyTemplateWithTokenSubstitution, promoteStagedScaffold };