@phuc1403/musketeer 0.1.0

package/template/.claude/hooks/inject-design-docs.cjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+// SessionStart hook: inject Sololingo's always-on design artifacts into every
+// session so the design-first docs reliably "lead the code" (CLAUDE.md), instead
+// of relying on me to remember to read them.
+//
+// Payload (~7K tokens, mostly the CONTEXT.md): the CML context map, the
+// architecture-characteristics worksheet, the ADR index, and every bounded
+// context's CONTEXT.md (globbed recursively, so new BCs are picked up with no
+// config change). tasks.json / event-storm JSON under bounded-contexts are
+// deliberately excluded — task-tracking and raw walls, not design context.
+//
+// Fails open: any error emits nothing and exits 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();
+
+// Recursively collect CONTEXT.md under a directory (BC ubiquitous-language models).
+function findContextDocs(dir) {
+  const out = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out; // dir missing — skip
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...findContextDocs(full));
+    } else if (entry.isFile() && entry.name === "CONTEXT.md") {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+try {
+  const targets = [
+    path.join(root, "docs", "context-map.cml"),
+    path.join(root, "docs", "architecture-characteristics.md"),
+    path.join(root, "docs", "adr", "README.md"),
+    ...findContextDocs(path.join(root, "docs", "bounded-contexts")),
+  ];
+
+  const sections = [];
+  for (const file of targets) {
+    let content;
+    try {
+      content = fs.readFileSync(file, "utf-8");
+    } catch {
+      continue; // missing/unreadable — skip, don't fail
+    }
+    const rel = path.relative(root, file).split(path.sep).join("/");
+    sections.push(`===== ${rel} =====\n${content.trimEnd()}`);
+  }
+
+  if (sections.length === 0) {
+    process.exit(0); // nothing to inject
+  }
+
+  const additionalContext =
+    "Sololingo design artifacts — injected every session." +
+    "Treat these as the source of truth for the domain model, context boundaries, architecture " +
+    "characteristics, and recorded decisions; consult them before any domain, " +
+    "architecture, or ADR work, and keep changes consistent with them.\n\n" +
+    "Each CONTEXT.md captures the decisions of the DOMAIN only — the ubiquitous " +
+    "language and model rules, kept vendor/decision-neutral. It bounds what the " +
+    "domain model sees, not what infrastructure may do: the ACL/infrastructure can " +
+    "legitimately key on more than the model names. (E.g. the domain only ever sees " +
+    "a learner's Email, never the auth method; the ACL may also match the OIDC `sub`.) " +
+    "That layering is intended, not a contradiction of CONTEXT.md.\n\n" +
+    sections.join("\n\n");
+
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "SessionStart",
+        additionalContext,
+      },
+    })
+  );
+  process.exit(0);
+} catch {
+  process.exit(0); // fail open
+}

package/template/.claude/hooks/lib/colors.cjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * ANSI Terminal Colors - Cross-platform color support for statusline
+ * Supports NO_COLOR, FORCE_COLOR, COLORTERM auto-detection
+ * @module colors
+ */
+
+// ANSI escape codes (8-color basic palette)
+const RESET = '\x1b[0m';
+const DIM = '\x1b[2m';
+const RED = '\x1b[31m';
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const MAGENTA = '\x1b[35m';
+const CYAN = '\x1b[36m';
+
+// Detect color support at module load (cached)
+// Claude Code statusline runs via pipe but output displays in TTY - default to true
+const shouldUseColor = (() => {
+  if (process.env.NO_COLOR) return false;
+  if (process.env.FORCE_COLOR) return true;
+  // Default true for statusline context (Claude Code handles TTY display)
+  return true;
+})();
+
+// Mutable override (set by statusline.cjs from config)
+// null = use env detection, true/false = explicit override
+let _colorOverride = null;
+
+/**
+ * Set explicit color enable/disable override (from config)
+ * Pass null to revert to env-var detection
+ * @param {boolean} enabled
+ */
+function setColorEnabled(enabled) {
+  _colorOverride = enabled;
+}
+
+/**
+ * Determine if colors should be rendered, respecting env vars and config override
+ * NO_COLOR env var always takes precedence over config override
+ * @returns {boolean}
+ */
+function isColorEnabled() {
+  // NO_COLOR env var is a hard override that always wins
+  if (process.env.NO_COLOR) return false;
+  if (_colorOverride !== null) return _colorOverride;
+  return shouldUseColor;
+}
+
+// Detect 256-color support via COLORTERM
+const has256Color = (() => {
+  const ct = process.env.COLORTERM;
+  return ct === 'truecolor' || ct === '24bit' || ct === '256color';
+})();
+
+/**
+ * Wrap text with ANSI color code
+ * @param {string} text - Text to colorize
+ * @param {string} code - ANSI escape code
+ * @returns {string} Colorized text or plain text if colors disabled
+ */
+function colorize(text, code) {
+  if (!isColorEnabled()) return String(text);
+  return `${code}${text}${RESET}`;
+}
+
+function green(text) { return colorize(text, GREEN); }
+function yellow(text) { return colorize(text, YELLOW); }
+function red(text) { return colorize(text, RED); }
+function cyan(text) { return colorize(text, CYAN); }
+function magenta(text) { return colorize(text, MAGENTA); }
+function dim(text) { return colorize(text, DIM); }
+
+/**
+ * Get color code based on context percentage threshold
+ * @param {number} percent - Context usage percentage (0-100)
+ * @returns {string} ANSI color code
+ */
+function getContextColor(percent) {
+  if (percent >= 85) return RED;
+  if (percent >= 70) return YELLOW;
+  return GREEN;
+}
+
+/**
+ * Generate colored progress bar for context window
+ * Uses ▰▱ characters (smooth horizontal rectangles) for consistent rendering
+ * @param {number} percent - Usage percentage (0-100)
+ * @param {number} width - Bar width in characters (default 12)
+ * @returns {string} Unicode progress bar with threshold-based colors
+ */
+function coloredBar(percent, width = 12) {
+  const clamped = Math.max(0, Math.min(100, percent));
+  const filled = Math.round((clamped / 100) * width);
+  const empty = width - filled;
+
+  if (!isColorEnabled()) {
+    return '▰'.repeat(filled) + '▱'.repeat(empty);
+  }
+
+  const color = getContextColor(percent);
+  return `${color}${'▰'.repeat(filled)}${DIM}${'▱'.repeat(empty)}${RESET}`;
+}
+
+module.exports = {
+  RESET,
+  green,
+  yellow,
+  red,
+  cyan,
+  magenta,
+  dim,
+  getContextColor,
+  coloredBar,
+  shouldUseColor,
+  has256Color,
+  setColorEnabled,
+  isColorEnabled
+};

package/template/.claude/hooks/lib/git-info-cache.cjs

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Git Info Cache - Cross-platform git information batching
+ *
+ * Problem: 5-6 git process spawns per statusline render are slow on Windows (CreateProcess overhead)
+ * Solution: Cache git query results for 3 seconds — subsequent renders read cache (zero processes)
+ *
+ * Performance: 5 spawns per render → event-driven refresh + 30s TTL fallback
+ * Cross-platform: No bash-only syntax (no 2>/dev/null), windowsHide on all exec calls
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Cache TTL — long fallback for external changes (git checkout outside Claude)
+// Active invalidation happens via PostToolUse hooks after Edit/Write/Bash
+const CACHE_TTL = 30000;
+const CACHE_MISS = Symbol('cache_miss');
+const CACHE_SKIP = Symbol('cache_skip');
+
+function isTimeoutError(error) {
+  if (!error) return false;
+  if (error.killed) return true;
+  if (error.signal === 'SIGTERM') return true;
+  return /timed out|etimedout/i.test(String(error.message || ''));
+}
+
+function getExecTimeoutMs() {
+  const parsed = Number.parseInt(process.env.CK_GIT_TIMEOUT_MS || '', 10);
+  if (Number.isFinite(parsed) && parsed > 0) return parsed;
+  return 3000;
+}
+
+/**
+ * Safe command execution wrapper with optional cwd
+ * Timeout prevents hangs on slow/network-mounted repos
+ */
+function execIn(cmd, cwd) {
+  try {
+    return {
+      output: execSync(cmd, {
+        encoding: 'utf8',
+        stdio: ['pipe', 'pipe', 'ignore'],
+        windowsHide: true,
+        cwd: cwd || undefined,
+        timeout: getExecTimeoutMs()
+      }).trim(),
+      timedOut: false
+    };
+  } catch (error) {
+    return {
+      output: '',
+      timedOut: isTimeoutError(error)
+    };
+  }
+}
+
+/**
+ * Get cache file path for current working directory
+ */
+function getCachePath(cwd) {
+  const hash = require('crypto')
+    .createHash('md5')
+    .update(cwd)
+    .digest('hex')
+    .slice(0, 8);
+  return path.join(os.tmpdir(), `ck-git-cache-${hash}.json`);
+}
+
+/**
+ * Read cache if valid (not expired). Returns CACHE_MISS on miss.
+ * No existsSync check (TOCTOU race) — just try read and catch.
+ */
+function readCache(cachePath, options = {}) {
+  const { allowStale = false } = options;
+  try {
+    const cache = JSON.parse(fs.readFileSync(cachePath, 'utf8'));
+    if (Date.now() - cache.timestamp < CACHE_TTL || allowStale) {
+      return cache.data; // Can be null (non-git dir) or object (git info)
+    }
+  } catch {
+    // File missing, corrupted, or expired — all treated as cache miss
+  }
+  return CACHE_MISS;
+}
+
+/**
+ * Write cache atomically (temp file + rename to avoid partial reads on Windows)
+ */
+function writeCache(cachePath, data) {
+  const tmpPath = cachePath + '.tmp';
+  try {
+    fs.writeFileSync(tmpPath, JSON.stringify({ timestamp: Date.now(), data }));
+    fs.renameSync(tmpPath, cachePath);
+  } catch {
+    try { fs.unlinkSync(tmpPath); } catch {}
+  }
+}
+
+/**
+ * Count non-empty lines in a newline-delimited string
+ */
+function countLines(str) {
+  if (!str) return 0;
+  return str.split('\n').filter(l => l.trim()).length;
+}
+
+/**
+ * Fetch git info directly in-process
+ * The cache is what eliminates redundant spawns — not subprocess wrapping
+ * @param {string} cwd - Directory to run git commands in
+ * Returns: { branch, unstaged, staged, ahead, behind } or null if not git repo
+ */
+function fetchGitInfo(cwd) {
+  // Check if git repo (fast check) — run in target cwd, not process.cwd()
+  const repoCheck = execIn('git rev-parse --git-dir', cwd);
+  if (repoCheck.timedOut) return CACHE_SKIP;
+  if (!repoCheck.output) {
+    return null;
+  }
+
+  const branchPrimary = execIn('git branch --show-current', cwd);
+  const branchFallback = execIn('git rev-parse --short HEAD', cwd);
+  const unstagedResult = execIn('git diff --name-only', cwd);
+  const stagedResult = execIn('git diff --cached --name-only', cwd);
+  const aheadBehindResult = execIn('git rev-list --left-right --count @{u}...HEAD', cwd);
+
+  if (
+    branchPrimary.timedOut ||
+    branchFallback.timedOut ||
+    unstagedResult.timedOut ||
+    stagedResult.timedOut ||
+    aheadBehindResult.timedOut
+  ) {
+    return CACHE_SKIP;
+  }
+
+  const branch = branchPrimary.output || branchFallback.output;
+  const unstaged = countLines(unstagedResult.output);
+  const staged = countLines(stagedResult.output);
+
+  // Ahead/behind — no 2>/dev/null (invalid on Windows cmd.exe)
+  let ahead = 0;
+  let behind = 0;
+  if (aheadBehindResult.output) {
+    const parts = aheadBehindResult.output.split(/\s+/);
+    behind = parseInt(parts[0], 10) || 0;
+    ahead = parseInt(parts[1], 10) || 0;
+  }
+
+  return { branch, unstaged, staged, ahead, behind };
+}
+
+/**
+ * Get git info with caching
+ * Main export function used by statusline
+ */
+function getGitInfo(cwd = process.cwd()) {
+  const cachePath = getCachePath(cwd);
+
+  // Try cache first (includes cached null for non-git dirs)
+  const cached = readCache(cachePath);
+  if (cached !== CACHE_MISS) return cached;
+
+  // Cache miss or expired, fetch fresh data in target cwd
+  const data = fetchGitInfo(cwd);
+  if (data === CACHE_SKIP) {
+    // Timeout/transient failures should not poison cache as non-git.
+    // Prefer last known value (even stale) if available.
+    const stale = readCache(cachePath, { allowStale: true });
+    return stale === CACHE_MISS ? null : stale;
+  }
+
+  // Cache both positive and null results (avoids re-spawning git in non-git dirs)
+  writeCache(cachePath, data);
+
+  return data;
+}
+
+/**
+ * Invalidate cache for a directory (call after file changes to trigger fresh git query)
+ */
+function invalidateCache(cwd = process.cwd()) {
+  try { fs.unlinkSync(getCachePath(cwd)); } catch {}
+}
+
+module.exports = { getGitInfo, invalidateCache };

package/template/.claude/hooks/lib/transcript-parser.cjs

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Transcript Parser - Extract tool/agent/todo state from session JSONL
+ * @module transcript-parser
+ */
+
+const fs = require('fs');
+const readline = require('readline');
+
+function isNativeTaskTodo(todo) {
+  return Boolean(todo && todo._source === 'native_task');
+}
+
+function normalizeTodo(todo) {
+  if (!todo || typeof todo !== 'object') return null;
+  const normalized = {
+    content: todo.content ?? '',
+    status: todo.status ?? 'pending',
+    activeForm: todo.activeForm ?? null
+  };
+  if (todo.id != null) normalized.id = todo.id;
+  return normalized;
+}
+
+function extractTaskIdFromString(text) {
+  if (!text || typeof text !== 'string') return null;
+  const trimmed = text.trim();
+  if (!trimmed) return null;
+
+  try {
+    const parsed = JSON.parse(trimmed);
+    return extractTaskIdFromValue(parsed);
+  } catch {
+    // Not JSON, continue with regex extraction.
+  }
+
+  const match = trimmed.match(/["']?task[_-]?id["']?\s*[:=]\s*["']([^"']+)["']/i);
+  if (match && match[1]) return match[1];
+  return null;
+}
+
+function extractTaskIdFromValue(value) {
+  if (value == null) return null;
+
+  if (typeof value === 'string') {
+    return extractTaskIdFromString(value);
+  }
+
+  if (typeof value !== 'object') return null;
+
+  if (typeof value.taskId === 'string' || typeof value.taskId === 'number') {
+    return String(value.taskId);
+  }
+  if (typeof value.task_id === 'string' || typeof value.task_id === 'number') {
+    return String(value.task_id);
+  }
+
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      const taskId = extractTaskIdFromValue(item);
+      if (taskId) return taskId;
+    }
+    return null;
+  }
+
+  for (const fieldValue of Object.values(value)) {
+    const taskId = extractTaskIdFromValue(fieldValue);
+    if (taskId) return taskId;
+  }
+  return null;
+}
+
+/**
+ * Parse transcript JSONL file
+ * @param {string} transcriptPath - Path to transcript file
+ * @returns {Promise<TranscriptData>}
+ */
+async function parseTranscript(transcriptPath) {
+  const result = {
+    tools: [],
+    agents: [],
+    todos: [],
+    sessionStart: null
+  };
+
+  if (!transcriptPath || !fs.existsSync(transcriptPath)) {
+    return result;
+  }
+
+  const toolMap = new Map();
+  const agentMap = new Map();
+  let latestTodos = [];
+
+  try {
+    const fileStream = fs.createReadStream(transcriptPath);
+    const rl = readline.createInterface({
+      input: fileStream,
+      crlfDelay: Infinity
+    });
+
+    for await (const line of rl) {
+      if (!line.trim()) continue;
+
+      try {
+        const entry = JSON.parse(line);
+        processEntry(entry, toolMap, agentMap, latestTodos, result);
+      } catch {
+        // Skip malformed lines
+      }
+    }
+  } catch {
+    // Return partial results on error
+  }
+
+  result.tools = Array.from(toolMap.values()).slice(-20);
+  result.agents = Array.from(agentMap.values()).slice(-10);
+  result.todos = latestTodos
+    .map(normalizeTodo)
+    .filter(Boolean);
+
+  return result;
+}
+
+/**
+ * Process single JSONL entry
+ * @param {Object} entry - Parsed JSON line
+ * @param {Map} toolMap - Tool tracking map
+ * @param {Map} agentMap - Agent tracking map
+ * @param {Array} latestTodos - Latest todo array reference
+ * @param {Object} result - Result object
+ */
+function processEntry(entry, toolMap, agentMap, latestTodos, result) {
+  const timestamp = entry.timestamp ? new Date(entry.timestamp) : new Date();
+
+  // Track session start
+  if (!result.sessionStart && entry.timestamp) {
+    result.sessionStart = timestamp;
+  }
+
+  const content = entry.message?.content;
+  if (!content || !Array.isArray(content)) return;
+
+  for (const block of content) {
+    // Handle tool_use blocks
+    if (block.type === 'tool_use' && block.id && block.name) {
+      if (block.name === 'Task') {
+        // Agent spawn
+        agentMap.set(block.id, {
+          id: block.id,
+          type: block.input?.subagent_type ?? 'unknown',
+          model: block.input?.model ?? null,
+          description: block.input?.description ?? null,
+          status: 'running',
+          startTime: timestamp,
+          endTime: null
+        });
+      } else if (block.name === 'TodoWrite') {
+        // Legacy: Replace todo array (deprecated, kept for backwards compatibility)
+        if (block.input?.todos && Array.isArray(block.input.todos)) {
+          latestTodos.length = 0;
+          latestTodos.push(
+            ...block.input.todos.map(todo => ({
+              ...todo,
+              _source: 'legacy_todowrite'
+            }))
+          );
+        }
+      } else if (block.name === 'TaskCreate') {
+        // Native Task API: add new task.
+        // Track by tool_use id first; hydrate real task id from matching tool_result when present.
+        if (block.input?.subject) {
+          latestTodos.push({
+            id: block.id,
+            content: block.input.subject,
+            status: 'pending',
+            activeForm: block.input.activeForm || null,
+            _source: 'native_task',
+            _toolUseId: block.id
+          });
+        }
+      } else if (block.name === 'TaskUpdate') {
+        // Native Task API: Update existing task status
+        // Match by taskId against native-task ids first.
+        // Numeric fallback maps to native-task creation order only (not legacy TodoWrite items).
+        if (block.input?.taskId && block.input?.status) {
+          const taskId = String(block.input.taskId);
+          const nativeTodos = latestTodos.filter(isNativeTaskTodo);
+          let task = nativeTodos.find(t => String(t.id) === taskId);
+          if (!task && /^\d+$/.test(taskId)) {
+            const idx = Number(taskId) - 1;
+            if (idx >= 0 && idx < nativeTodos.length) task = nativeTodos[idx];
+          }
+
+          if (task) {
+            task.status = block.input.status;
+            if (Object.prototype.hasOwnProperty.call(block.input, 'activeForm')) {
+              task.activeForm = block.input.activeForm || null;
+            }
+          }
+        }
+      } else {
+        // Regular tool
+        toolMap.set(block.id, {
+          id: block.id,
+          name: block.name,
+          target: extractTarget(block.name, block.input),
+          status: 'running',
+          startTime: timestamp,
+          endTime: null
+        });
+      }
+    }
+
+    // Handle tool_result blocks
+    if (block.type === 'tool_result' && block.tool_use_id) {
+      const tool = toolMap.get(block.tool_use_id);
+      if (tool) {
+        tool.status = block.is_error ? 'error' : 'completed';
+        tool.endTime = timestamp;
+      }
+
+      const agent = agentMap.get(block.tool_use_id);
+      if (agent) {
+        agent.status = 'completed';
+        agent.endTime = timestamp;
+      }
+
+      const createdTask = latestTodos.find(
+        todo => isNativeTaskTodo(todo) && todo._toolUseId === block.tool_use_id
+      );
+      if (createdTask) {
+        const hydratedId = extractTaskIdFromValue(block.content);
+        if (hydratedId) {
+          createdTask.id = hydratedId;
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Extract target from tool input
+ * @param {string} toolName - Tool name
+ * @param {Object} input - Tool input object
+ * @returns {string|null} - Extracted target
+ */
+function extractTarget(toolName, input) {
+  if (!input) return null;
+
+  switch (toolName) {
+    case 'Read':
+    case 'Write':
+    case 'Edit':
+      return input.file_path ?? input.path ?? null;
+
+    case 'Glob':
+    case 'Grep':
+      return input.pattern ?? null;
+
+    case 'Bash':
+      const cmd = input.command;
+      if (!cmd) return null;
+      return cmd.length > 30 ? cmd.slice(0, 30) + '...' : cmd;
+
+    default:
+      return null;
+  }
+}
+
+module.exports = {
+  parseTranscript,
+  // Export for testing
+  processEntry,
+  extractTarget
+};