@phuc1403/musketeer 0.1.0 → 0.2.1

package/README.md

@@ -12,26 +12,33 @@ npm i -g @phuc1403/musketeer
 ## Use
 
 ```bash
-musketeer                 # open the muster (interactive picker) → reconcile your company
-musketeer --with a,b,c    # non-interactive: set company to EXACTLY {core,a,b,c}
-musketeer --list          # print current company + available musketeers
-musketeer --help          # usage
+musketeer muster     # open the muster — pick your company (multi-select) → reconcile
+musketeer promote    # update the musketeer CLI itself to the latest published version
+musketeer            # show usage
+musketeer --help     # show usage
 ```
 
-`musketeer` is **idempotent**: the picker pre-checks your current company (from `.musketeer.json`),
+`musketeer muster` is **idempotent**: the picker pre-checks your current company (from `.musketeer.json`),
 and confirming applies the diff — install newly-checked, remove newly-unchecked, regenerate
 `settings.json`, and auto-install 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 | What it adds |
-|-----------|---------|--------------|
-| **core** | always (locked) | research, handoff, skill-creator · statusline, usage-context, format-json hooks |
-| **architecture** | checked | adr-writer, architecture-characteristic-writer, context-map · CML validation hook |
-| **hallmark** | checked | hallmark, hallmark-explore, hallmark-loop · auditor/explorer agents |
-| **code-review** | checked | code-review skill + code-reviewer agent |
-| **dotnet** | opt-in | tdd, knowledge-crunching · EF migration guard hook |
-| **design-docs** | opt-in | inject-design-docs SessionStart hook |
+| Musketeer | Default in muster | What it adds |
+|-----------|-------------------|--------------|
+| **core** | always on (locked, hidden) | research, handoff, skill-creator · 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 |
+| **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.
 

package/bin/musketeer.js

@@ -6,25 +6,25 @@ const { parseArgs } = require('node:util');
 const USAGE = `musketeer — scaffold a curated company of Claude Code musketeers into ./.claude
 
 Usage:
-  musketeer                 Open the muster (interactive picker), reconcile your company
-  musketeer --with a,b,c    Non-interactive: set company to EXACTLY {core,a,b,c} (CI/scriptable)
-  musketeer --list          Print current company + all available musketeers
-  musketeer --help          Show this help
+  musketeer muster     Open the muster — pick your company (multi-select), then reconcile
+  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.
   * "core" is always installed and locked — it cannot be removed.
-  * Re-running is idempotent: the picker shows your current state, confirm applies the diff.
+  * The muster is multi-select: check every musketeer you want, then confirm.
+  * Re-running is idempotent: the picker pre-checks your current company; confirm applies the diff.
   * settings.json is GENERATED per-selection; missing prereqs are auto-installed (announced).`;
 
 function parse(argv) {
   return parseArgs({
     args: argv,
     options: {
-      with: { type: 'string' },
-      list: { type: 'boolean', default: false },
       help: { type: 'boolean', short: 'h', default: false },
     },
-    allowPositionals: false,
+    allowPositionals: true,
   });
 }
 
@@ -38,32 +38,30 @@ async function main(argv = process.argv.slice(2)) {
     return;
   }
 
-  const { values } = parsed;
+  const { values, positionals } = parsed;
+  const command = positionals[0];
 
-  if (values.help) {
+  // `musketeer` alone (or --help) → usage.
+  if (values.help || !command) {
     process.stdout.write(`${USAGE}\n`);
     return;
   }
 
-  // Lazy-require so --help never pays the cost of loading the engine/manifest.
-  const reconcile = require('../src/reconcile');
-
-  if (values.list) {
-    await reconcile.list();
+  if (command === 'muster') {
+    // 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 (typeof values.with === 'string') {
-    const ids = values.with
-      .split(',')
-      .map((s) => s.trim())
-      .filter(Boolean);
-    await reconcile.run({ desiredIds: ids, interactive: false });
+  if (command === 'promote') {
+    const promote = require('../src/promote');
+    await promote.run();
     return;
   }
 
-  // No flags → open the muster (interactive).
-  await reconcile.run({ desiredIds: null, interactive: true });
+  process.stderr.write(`Unknown command "${command}".\n\n${USAGE}\n`);
+  process.exitCode = 2;
 }
 
 main().catch((err) => {

package/manifest.json

@@ -5,7 +5,6 @@
       "label": "core",
       "description": "Always-on foundation: research, handoff, skill-creator + statusline, usage-context & format-json hooks.",
       "locked": true,
-      "defaultChecked": true,
       "deps": [],
       "files": [
         "skills/research/**",
@@ -50,7 +49,6 @@
       "label": "architecture",
       "description": "DDD architecture authoring: adr-writer, architecture-characteristic-writer, context-map (CML) + validation hook.",
       "locked": false,
-      "defaultChecked": true,
       "deps": [],
       "files": [
         "skills/adr-writer/**",
@@ -72,7 +70,6 @@
       "label": "hallmark",
       "description": "Hallmark design system: hallmark rubric, hallmark-explore, hallmark-loop + auditor/explorer agents.",
       "locked": false,
-      "defaultChecked": true,
       "deps": [],
       "files": [
         "skills/hallmark/**",
@@ -88,7 +85,6 @@
       "label": "code-review",
       "description": "Adversarial code review skill + code-reviewer agent (commit / pending / PR modes).",
       "locked": false,
-      "defaultChecked": true,
       "deps": [],
       "files": [
         "skills/code-review/**",
@@ -99,9 +95,8 @@
     },
     "dotnet": {
       "label": "dotnet",
-      "description": "Opt-in .NET extras: tdd, knowledge-crunching + EF migration-guard hook.",
+      "description": ".NET extras: tdd, knowledge-crunching + EF migration-guard hook.",
       "locked": false,
-      "defaultChecked": false,
       "deps": [],
       "files": [
         "skills/tdd/**",
@@ -121,9 +116,8 @@
     },
     "design-docs": {
       "label": "design-docs",
-      "description": "Opt-in SessionStart hook that injects architecture/context-map/adr docs/ outputs into context.",
+      "description": "SessionStart hook that injects architecture/context-map/adr docs/ outputs into context.",
       "locked": false,
-      "defaultChecked": false,
       "deps": [],
       "files": [
         "hooks/inject-design-docs.cjs"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phuc1403/musketeer",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "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": {

package/src/muster.js

@@ -1,34 +1,67 @@
 'use strict';
 
 // The muster — the interactive picker. Uses @clack/prompts (ESM-only), loaded
-// via dynamic import() for CommonJS interop. `core` is always re-added after
-// selection (clack has no per-option lock), enforcing the locked-on invariant.
+// via dynamic import() for CommonJS interop. The selection rules live in the pure
+// helpers below (planSelection / withLocked) so they can be unit-tested without a TTY.
 
 /**
+ * Compute the muster's option list and initial selection. Pure — no I/O.
+ *
+ * Rules:
+ *   * Locked musketeers (core) are NOT selectable — always-on, hidden from the
+ *     toggle list so they can't be unchecked. They're force-added by withLocked().
+ *   * Every other musketeer defaults to UNSELECTED. Only musketeers already
+ *     installed (present in the lockfile) start pre-checked, so re-running shows
+ *     the current company and confirming unchanged is a no-op.
+ *
  * @param {object} manifest
  * @param {{musketeers:string[]}} prev current lockfile company
- * @returns {Promise<?string[]>} chosen ids (incl. core), or null if cancelled
+ * @returns {{lockedIds:string[], options:Array<{value:string,label:string,hint:string}>, initialValues:string[]}}
  */
-async function pick(manifest, prev) {
-  const clack = await import('@clack/prompts');
+function planSelection(manifest, prev) {
   const entries = Object.entries(manifest.musketeers);
-  const installed = new Set(prev.musketeers);
-  const hasLock = prev.musketeers.length > 0;
+  const installed = new Set((prev && prev.musketeers) || []);
 
-  // Pre-checked: locked always; else current install (if any) else defaultChecked.
-  const initialValues = entries
-    .filter(([id, m]) => m.locked || (hasLock ? installed.has(id) : m.defaultChecked))
-    .map(([id]) => id);
+  const lockedIds = entries.filter(([, m]) => m.locked).map(([id]) => id);
+  const selectable = entries.filter(([, m]) => !m.locked);
 
-  const options = entries.map(([id, m]) => ({
+  const options = selectable.map(([id, m]) => ({
     value: id,
-    label: m.locked ? `${m.label} (core — always included)` : m.label,
+    label: m.label,
     hint: m.description,
   }));
+  const initialValues = selectable
+    .filter(([id]) => installed.has(id))
+    .map(([id]) => id);
+
+  return { lockedIds, options, initialValues };
+}
+
+/**
+ * Finalize a raw multiselect result: dedupe and force every locked musketeer on
+ * (enforces locked-on — "core can't be removed").
+ * @param {string[]} selectedIds
+ * @param {string[]} lockedIds
+ * @returns {string[]}
+ */
+function withLocked(selectedIds, lockedIds) {
+  const chosen = new Set(Array.isArray(selectedIds) ? selectedIds : []);
+  for (const id of lockedIds || []) chosen.add(id);
+  return [...chosen];
+}
+
+/**
+ * @param {object} manifest
+ * @param {{musketeers:string[]}} prev current lockfile company
+ * @returns {Promise<?string[]>} chosen ids (incl. locked), or null if cancelled
+ */
+async function pick(manifest, prev) {
+  const clack = await import('@clack/prompts');
+  const { lockedIds, options, initialValues } = planSelection(manifest, prev);
 
   clack.intro('musketeer — muster');
   const selected = await clack.multiselect({
-    message: 'Select your company (core is always installed):',
+    message: 'Pick your company — space toggles, enter confirms (core is always included):',
     options,
     initialValues,
     required: false,
@@ -39,10 +72,9 @@ async function pick(manifest, prev) {
     return null;
   }
 
-  const chosen = new Set(Array.isArray(selected) ? selected : []);
-  chosen.add('core'); // enforce locked-on
-  clack.outro(`Company: ${[...chosen].join(', ')}`);
-  return [...chosen];
+  const chosen = withLocked(selected, lockedIds);
+  clack.outro(`Company: ${chosen.join(', ')}`);
+  return chosen;
 }
 
-module.exports = { pick };
+module.exports = { pick, planSelection, withLocked };

package/src/promote.js

@@ -0,0 +1,81 @@
+'use strict';
+
+// `musketeer promote` — advance the installed CLI to the latest published rank
+// (version). Detect-first: query the npm registry, compare, and only install when
+// the running copy is behind. Distinct from `muster` (which picks the company in a
+// project); promote upgrades the musketeer binary itself.
+
+const { spawnSync } = require('child_process');
+const pkg = require('../package.json');
+
+/**
+ * Default command runner — same shape/semantics as the provisioner's runner.
+ * Captures stdout+stderr and never throws; tests inject their own `run`.
+ * @param {string} cmd
+ * @returns {{code:number, stdout:string, stderr:string}}
+ */
+function defaultRun(cmd) {
+  const r = spawnSync(cmd, { shell: true, encoding: 'utf8', windowsHide: true });
+  return {
+    code: typeof r.status === 'number' ? r.status : 1,
+    stdout: r.stdout || '',
+    stderr: r.stderr || '',
+  };
+}
+
+/** Compare dotted numeric versions: 1 if a>b, -1 if a<b, 0 if equal. */
+function compareVersions(a, b) {
+  const pa = String(a).split('.').map(Number);
+  const pb = String(b).split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    const x = pa[i] || 0;
+    const y = pb[i] || 0;
+    if (x > y) return 1;
+    if (x < y) return -1;
+  }
+  return 0;
+}
+
+/**
+ * Run the self-update. Detect latest from the registry, compare to the running
+ * version, install only when behind. Partial-failure tolerant — prints a manual
+ * fallback rather than throwing.
+ * @param {object} [overrides] { run, log, name, current } for hermetic tests
+ * @returns {Promise<{status:'up-to-date'|'promoted'|'failed'|'unknown', from:string, to:?string}>}
+ */
+async function run(overrides = {}) {
+  const exec = overrides.run || defaultRun;
+  const log = overrides.log || ((m) => process.stdout.write(m + '\n'));
+  const name = overrides.name || pkg.name;
+  const current = overrides.current || pkg.version;
+
+  log(`Checking rank… installed ${current} (${name})`);
+  const view = exec(`npm view ${name} version`);
+  const latest = (view.stdout || '').trim();
+
+  if (view.code !== 0 || !/^\d+\.\d+\.\d+/.test(latest)) {
+    log('Could not reach the npm registry to check for a newer version.');
+    log(`Try manually: npm i -g ${name}@latest`);
+    return { status: 'unknown', from: current, to: null };
+  }
+
+  log(`  installed ${current} · latest ${latest}`);
+  if (compareVersions(latest, current) <= 0) {
+    log('Already at the latest rank — no promotion needed.');
+    return { status: 'up-to-date', from: current, to: latest };
+  }
+
+  log(`→ npm i -g ${name}@latest`);
+  const ins = exec(`npm i -g ${name}@latest`);
+  if (ins.code !== 0) {
+    log('Promotion failed. Try manually (you may need elevated permissions):');
+    log(`  npm i -g ${name}@latest`);
+    if (ins.stderr) log(ins.stderr.trim());
+    return { status: 'failed', from: current, to: latest };
+  }
+
+  log(`Promoted: now at ${latest}.`);
+  return { status: 'promoted', from: current, to: latest };
+}
+
+module.exports = { run, compareVersions, defaultRun };

package/src/reconcile.js

@@ -1,7 +1,7 @@
 'use strict';
 
 const { loadManifest, templateClaudeDir } = require('./manifest-loader');
-const { resolveClosure, CORE_ID } = require('./resolver');
+const { resolveClosure } = require('./resolver');
 const { readLockfile, writeLockfile } = require('./lockfile');
 const copier = require('./copier');
 const settingsMerger = require('./settings-merger');
@@ -73,22 +73,4 @@ async function run(opts, overrides = {}) {
   d.log('Done. Your .claude/ company is reconciled.');
 }
 
-/**
- * Print current company + all available musketeers (no UI).
- */
-async function list(opts = {}, overrides = {}) {
-  const projectDir = opts.projectDir || process.cwd();
-  const d = { ...defaultDeps(), ...overrides };
-  const prev = readLockfile(projectDir);
-  const company = new Set(prev.musketeers.length ? prev.musketeers : []);
-
-  d.log(`Current company: ${prev.musketeers.length ? prev.musketeers.join(', ') : '(none installed yet)'}`);
-  d.log('\nAvailable musketeers:');
-  for (const [id, m] of Object.entries(d.manifest.musketeers)) {
-    const mark = company.has(id) || id === CORE_ID ? '[x]' : '[ ]';
-    const lock = m.locked ? ' (locked)' : m.defaultChecked ? '' : ' (opt-in)';
-    d.log(`  ${mark} ${id}${lock} — ${m.description}`);
-  }
-}
-
-module.exports = { run, list, defaultDeps };
+module.exports = { run, defaultDeps };

package/src/schema.js

@@ -10,8 +10,7 @@
  *     "<id>": {
  *       label: string,
  *       description: string,
- *       locked: boolean,
- *       defaultChecked: boolean,
+ *       locked: boolean,            // always-on; hidden from the muster toggle list
  *       files: string[],            // globs relative to template/.claude/
  *       deps: string[],             // other musketeer ids (intra-package edges)
  *       settings: SettingFragment[],
@@ -80,7 +79,6 @@ function validateMusketeer(id, m) {
   if (typeof m.label !== 'string') fail(`${ctx}.label must be a string`);
   if (typeof m.description !== 'string') fail(`${ctx}.description must be a string`);
   if (typeof m.locked !== 'boolean') fail(`${ctx}.locked must be a boolean`);
-  if (typeof m.defaultChecked !== 'boolean') fail(`${ctx}.defaultChecked must be a boolean`);
   if (!isStringArray(m.files)) fail(`${ctx}.files must be a string[]`);
   if (!isStringArray(m.deps)) fail(`${ctx}.deps must be a string[]`);
   if (!isStringArray(m.prereqs)) fail(`${ctx}.prereqs must be a string[]`);