@phuc1403/musketeer 0.2.1 → 0.2.3

package/README.md

@@ -12,15 +12,19 @@ npm i -g @phuc1403/musketeer
 ## Use
 
 ```bash
-musketeer muster     # open the muster — pick your company (multi-select) → reconcile
+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` 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 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

package/bin/musketeer.js

@@ -6,16 +6,17 @@ const { parseArgs } = require('node:util');
 const USAGE = `musketeer — scaffold a curated company of Claude Code musketeers into ./.claude
 
 Usage:
-  musketeer muster     Open the muster — pick your company (multi-select), then reconcile
+  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.
-  * 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) {
@@ -48,6 +49,14 @@ async function main(argv = process.argv.slice(2)) {
   }
 
   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 });

package/manifest.json

@@ -95,13 +95,14 @@
     },
     "dotnet": {
       "label": "dotnet",
-      "description": ".NET extras: tdd, knowledge-crunching + EF migration-guard hook.",
+      "description": ".NET extras: tdd, knowledge-crunching + EF migration-guard & CONTEXT auto-load hooks.",
       "locked": false,
       "deps": [],
       "files": [
         "skills/tdd/**",
         "skills/knowledge-crunching/**",
-        "hooks/block-migration-edits.cjs"
+        "hooks/block-migration-edits.cjs",
+        "hooks/inject-context.cjs"
       ],
       "settings": [
         {
@@ -110,6 +111,13 @@
           "command": "node \"${CLAUDE_PROJECT_DIR}/.claude/hooks/block-migration-edits.cjs\"",
           "order": 1,
           "statusMessage": "Checking for EF migration edits"
+        },
+        {
+          "event": "SessionStart",
+          "matcher": "startup|resume|clear|compact",
+          "command": "node \"${CLAUDE_PROJECT_DIR}/.claude/hooks/inject-context.cjs\"",
+          "order": 1,
+          "statusMessage": "Loading domain CONTEXT"
         }
       ],
       "prereqs": []

package/package.json

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

@@ -23,6 +23,19 @@ function defaultRun(cmd) {
   };
 }
 
+/**
+ * Look up a package's published `latest` version from the registry.
+ * @param {(cmd:string)=>{code:number,stdout:string,stderr:string}} exec
+ * @param {string} name
+ * @returns {?string} the version, or null if unreachable / unparseable
+ */
+function fetchLatest(exec, name) {
+  const view = exec(`npm view ${name} version`);
+  const latest = (view.stdout || '').trim();
+  if (view.code !== 0 || !/^\d+\.\d+\.\d+/.test(latest)) return null;
+  return latest;
+}
+
 /** 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);
@@ -50,10 +63,9 @@ async function run(overrides = {}) {
   const current = overrides.current || pkg.version;
 
   log(`Checking rank… installed ${current} (${name})`);
-  const view = exec(`npm view ${name} version`);
-  const latest = (view.stdout || '').trim();
+  const latest = fetchLatest(exec, name);
 
-  if (view.code !== 0 || !/^\d+\.\d+\.\d+/.test(latest)) {
+  if (!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 };
@@ -78,4 +90,4 @@ async function run(overrides = {}) {
   return { status: 'promoted', from: current, to: latest };
 }
 
-module.exports = { run, compareVersions, defaultRun };
+module.exports = { run, fetchLatest, compareVersions, defaultRun };

package/src/reconcile.js

@@ -50,7 +50,7 @@ async function run(opts, overrides = {}) {
   const plan = copier.planFiles(prev.files, desired.files);
 
   d.log(`Company: ${desired.ids.join(', ')}`);
-  d.log(`Files: ${plan.copy.length} managed, ${plan.remove.length} to remove.`);
+  d.log(`Files: ${plan.copy.length} refreshed to latest, ${plan.remove.length} removed.`);
 
   copier.apply(plan, d.templateDir, projectDir);
   d.settingsMerger.generate(desired, projectDir);

package/src/self-update.js

@@ -0,0 +1,73 @@
+'use strict';
+
+// Self-update gate for `musketeer muster`. Before the picker applies the bundled
+// template, make sure the CLI is at the latest PUBLISHED version — otherwise
+// "muster" would refresh installed skills to a stale package's template.
+//
+// When behind: promote (npm i -g @latest), then re-exec `musketeer muster` so the
+// picker runs under the freshly-installed template. A running Node process can't
+// reliably hot-swap its own package files mid-run, so re-exec is the safe path.
+//
+// Guards:
+//   MUSKETEER_REEXEC=1        set on the child so it never re-checks (no loop)
+//   MUSKETEER_NO_SELF_UPDATE=1 user opt-out (offline / pinned version)
+
+const { spawnSync } = require('child_process');
+const { fetchLatest, compareVersions, defaultRun } = require('./promote');
+const pkg = require('../package.json');
+
+/**
+ * Decide whether muster should self-update first. Pure — injectable exec/env.
+ * @param {{exec?:Function, current?:string, name?:string, env?:object}} [o]
+ * @returns {{action:'proceed'|'update', latest:?string}}
+ */
+function decide(o = {}) {
+  const exec = o.exec || defaultRun;
+  const current = o.current || pkg.version;
+  const name = o.name || pkg.name;
+  const env = o.env || process.env;
+
+  if (env.MUSKETEER_REEXEC === '1' || env.MUSKETEER_NO_SELF_UPDATE === '1') {
+    return { action: 'proceed', latest: null };
+  }
+  const latest = fetchLatest(exec, name);
+  if (!latest) return { action: 'proceed', latest: null }; // offline / unknown — proceed as-is
+  if (compareVersions(latest, current) <= 0) return { action: 'proceed', latest }; // already latest
+  return { action: 'update', latest };
+}
+
+/**
+ * Ensure the CLI is latest before muster applies the template.
+ * @param {object} [io] injectable { log, exec, spawn, env, name, current } for tests
+ * @returns {?number} an exit code if it re-exec'd a fresh muster (caller should
+ *   exit with it); null to mean "proceed in-process".
+ */
+function ensureLatest(io = {}) {
+  const log = io.log || ((m) => process.stdout.write(m + '\n'));
+  const exec = io.exec || defaultRun;
+  const spawn = io.spawn || spawnSync;
+  const env = io.env || process.env;
+  const name = io.name || pkg.name;
+  const current = io.current || pkg.version;
+
+  const d = decide({ exec, current, name, env });
+  if (d.action === 'proceed') return null;
+
+  log(`Updating musketeer ${current} → ${d.latest} before muster…`);
+  const ins = exec(`npm i -g ${name}@latest`);
+  if (ins.code !== 0) {
+    log('Self-update failed — continuing with the current version.');
+    if (ins.stderr) log(ins.stderr.trim());
+    return null;
+  }
+
+  // Re-exec the now-latest binary's muster, inheriting the TTY for the picker.
+  const r = spawn('musketeer', ['muster'], {
+    stdio: 'inherit',
+    shell: true,
+    env: { ...env, MUSKETEER_REEXEC: '1' },
+  });
+  return typeof r.status === 'number' ? r.status : 0;
+}
+
+module.exports = { decide, ensureLatest };

package/template/.claude/hooks/inject-context.cjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// SessionStart hook (dotnet company): auto-load the repo-root `CONTEXT.md` — the
+// bounded-context model produced by the knowledge-crunching skill — into every
+// session, so the domain's ubiquitous language and invariants "lead the code".
+//
+// If the root CONTEXT.md is missing, ALERT the user (systemMessage) so they
+// create one. Any other error fails open (emits nothing, exit 0) so it can never
+// block a session.
+const fs = require("fs");
+const path = require("path");
+
+const root = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const file = path.join(root, "CONTEXT.md");
+
+try {
+  let content;
+  try {
+    content = fs.readFileSync(file, "utf-8");
+  } catch {
+    // Not found — surface a visible warning to the user, inject nothing.
+    process.stdout.write(
+      JSON.stringify({
+        systemMessage:
+          "musketeer: no CONTEXT.md at the repo root — the bounded-context model is missing. " +
+          "Run the knowledge-crunching skill (/knowledge-crunching) to create one.",
+      })
+    );
+    process.exit(0);
+  }
+
+  const additionalContext =
+    "Bounded-context model (root CONTEXT.md) — injected every session. It is the " +
+    "ubiquitous language and model rules of this bounded context, kept vendor- and " +
+    "decision-neutral. Treat it as canonical for domain naming, concepts, and invariants: " +
+    "name new code after it, and when a concept is renamed update CONTEXT.md and the code in " +
+    "the same turn. It bounds what the DOMAIN model sees, not what infrastructure may do " +
+    "(an ACL can legitimately key on more).\n\n" +
+    "===== CONTEXT.md =====\n" +
+    content.trimEnd();
+
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "SessionStart",
+        additionalContext,
+      },
+    })
+  );
+  process.exit(0);
+} catch {
+  process.exit(0); // fail open
+}

package/template/.claude/skills/knowledge-crunching/SKILL.md

@@ -42,7 +42,7 @@ it's out of scope and offer to hand off afterward.
 
 ### Step 1 — Open the session and name the flow
 
-**First read any prior crunching output for that context** — a `docs/bounded-contexts/<bc>/CONTEXT.md` and read the domain's code; in DDD, document = code. While reading the code, **note the language, idioms, and test framework already in use** — you'll model in those. If the module is a bare scaffold with no language chosen yet, ask the user which language and test framework the context should be modeled in before proposing any code.
+**First read any prior crunching output for that context** — the root-level `CONTEXT.md` and read the domain's code; in DDD, document = code. While reading the code, **note the language, idioms, and test framework already in use** — you'll model in those. If the module is a bare scaffold with no language chosen yet, ask the user which language and test framework the context should be modeled in before proposing any code.
 
 ### Step 2 — Find the first model elements (the "glimmer")
 Listen past the user's solution framing for the **domain nouns and verbs that keep recurring** — Name 2–4 candidate
@@ -105,7 +105,7 @@ that embodies it), then `_Avoid_:` rejected synonyms — grouped under a `###` s
 `CONTEXT.md` identical: rename in code, rename here in the same turn. Distilled-out concepts go under
 `## Deferred`, unresolved ones under `## Flagged ambiguities`.
 
-Edit the context's existing `docs/bounded-contexts/<bc>/CONTEXT.md` directly — it is canonical, and is
+Edit the context's existing root-level `CONTEXT.md` directly — it is canonical, and is
 also your seed (Step 1). If the module is new and has no `CONTEXT.md` yet, create one from
 `assets/context.template.md`.
 

package/template/.claude/skills/knowledge-crunching/assets/context.template.md

@@ -2,8 +2,8 @@
 
 <One line: the slice of the domain this context covers — the flow you crunched, in the expert's words.>
 
-> Starter for a context that has **no `CONTEXT.md` yet**. It lives at
-> `docs/bounded-contexts/<bc>/CONTEXT.md`. If the context already has one, edit that — never a second.
+> Starter for a context that has **no `CONTEXT.md` yet**. It lives at the
+> root folder as `CONTEXT.md`. If the context already has one, edit that — never a second.
 
 ## Language