pan-wizard 2.9.1 → 3.5.0

package/pan-wizard-core/bin/lib/bridge.cjs

@@ -0,0 +1,269 @@
+/**
+ * Bridge — MCP tool discovery + per-phase recommendation (Spec B v2 Y-5, v3.3).
+ *
+ * Discovery-only scope. We discover what MCP tools are reachable from the
+ * host runtime and what their shapes look like, then recommend which tools
+ * a given phase plan might use. We do NOT auto-inject tools into plans or
+ * auto-invoke them — those belong to a future wave once MCP schemas stabilize.
+ *
+ * Data lives at `.planning/bridge/available-tools.json`:
+ *   {
+ *     cached_at: "2026-04-18T...",
+ *     runtime: "claude",
+ *     servers: [
+ *       {
+ *         name: "linear",
+ *         version: "1.2.3",
+ *         tools: [
+ *           { name: "linear.updateTicket", description: "...", schema: {...} },
+ *           ...
+ *         ]
+ *       },
+ *       ...
+ *     ]
+ *   }
+ *
+ * Populating this file is the host runtime's responsibility (Claude Code's
+ * MCP list API, etc.). This module reads the cache and reasons over it.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { output, error, safeReadFile, toPosix, findPhaseInternal } = require('./core.cjs');
+const { PLANNING_DIR } = require('./constants.cjs');
+const { planningPath } = require('./utils.cjs');
+
+const BRIDGE_DIR = 'bridge';
+const TOOLS_FILE = 'available-tools.json';
+
+function bridgeDir(cwd) {
+  return path.join(planningPath(cwd), BRIDGE_DIR);
+}
+
+function toolsCacheFile(cwd) {
+  return path.join(bridgeDir(cwd), TOOLS_FILE);
+}
+
+/**
+ * Load the cached tool list. Returns an empty catalog if the cache is
+ * missing or malformed.
+ *
+ * @param {string} cwd - Project root
+ * @returns {{cached_at: string|null, runtime: string|null, servers: Array, source: 'cache'|'empty'}}
+ */
+function loadToolCache(cwd) {
+  const raw = safeReadFile(toolsCacheFile(cwd));
+  if (!raw) return { cached_at: null, runtime: null, servers: [], source: 'empty' };
+  try {
+    const parsed = JSON.parse(raw);
+    return {
+      cached_at: parsed.cached_at || null,
+      runtime: parsed.runtime || null,
+      servers: Array.isArray(parsed.servers) ? parsed.servers : [],
+      source: 'cache',
+    };
+  } catch {
+    return { cached_at: null, runtime: null, servers: [], source: 'empty' };
+  }
+}
+
+/**
+ * Write the tool cache. Used by the command when the host runtime provides
+ * a fresh tool list (or by tests for fixture setup).
+ *
+ * @param {string} cwd - Project root
+ * @param {{runtime, servers}} data
+ * @returns {{written: true, file: string}|{error: string}}
+ */
+function writeToolCache(cwd, data) {
+  if (!data || typeof data !== 'object') return { error: 'data required' };
+  try {
+    fs.mkdirSync(bridgeDir(cwd), { recursive: true });
+  } catch (e) {
+    return { error: `Failed to create bridge dir: ${e.message}` };
+  }
+  const payload = {
+    cached_at: new Date().toISOString(),
+    runtime: data.runtime || null,
+    servers: Array.isArray(data.servers) ? data.servers : [],
+  };
+  const file = toolsCacheFile(cwd);
+  try {
+    fs.writeFileSync(file, JSON.stringify(payload, null, 2), 'utf-8');
+  } catch (e) {
+    return { error: `Failed to write ${file}: ${e.message}` };
+  }
+  return { written: true, file: toPosix(path.relative(cwd, file)) };
+}
+
+/**
+ * Flatten server → tool hierarchy into a single list for easier reasoning.
+ *
+ * @param {Array} servers - From loadToolCache().servers
+ * @returns {Array<{server, name, description, schema}>}
+ */
+function flattenTools(servers) {
+  const tools = [];
+  for (const server of servers || []) {
+    if (!server || !Array.isArray(server.tools)) continue;
+    for (const tool of server.tools) {
+      if (!tool || !tool.name) continue;
+      tools.push({
+        server: server.name,
+        name: tool.name,
+        description: tool.description || '',
+        schema: tool.schema || null,
+      });
+    }
+  }
+  return tools;
+}
+
+/**
+ * List all available MCP tools, flattened.
+ *
+ * @param {string} cwd - Project root
+ * @returns {Object}
+ */
+function listTools(cwd) {
+  const cache = loadToolCache(cwd);
+  const tools = flattenTools(cache.servers);
+  return {
+    cached_at: cache.cached_at,
+    runtime: cache.runtime,
+    server_count: cache.servers.length,
+    tool_count: tools.length,
+    tools,
+    source: cache.source,
+  };
+}
+
+// ─── Recommendation scoring ────────────────────────────────────────────────
+
+/**
+ * Score a tool's relevance to a phase by matching plan keywords against
+ * tool name + description. Naive frequency-based scoring (no embeddings).
+ *
+ * @param {string} phaseText - Combined plan text
+ * @param {{server, name, description}} tool
+ * @returns {{score: number, hits: Array<string>}}
+ */
+function scoreToolForPhase(phaseText, tool) {
+  if (!phaseText || !tool) return { score: 0, hits: [] };
+  const body = phaseText.toLowerCase();
+  const haystack = `${tool.server || ''} ${tool.name || ''} ${tool.description || ''}`.toLowerCase();
+
+  // Extract keywords from the tool's identity: split on non-word chars, dedupe, keep ≥3 chars.
+  const keywords = [...new Set(haystack.split(/\W+/).filter(w => w.length >= 3))];
+
+  let score = 0;
+  const hits = [];
+  for (const kw of keywords) {
+    const re = new RegExp(`\\b${kw.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'g');
+    const count = (body.match(re) || []).length;
+    if (count > 0) {
+      score += count;
+      hits.push(kw);
+    }
+  }
+  return { score, hits };
+}
+
+/**
+ * Recommend MCP tools for a specific phase based on plan text keyword match.
+ *
+ * @param {string} cwd - Project root
+ * @param {string|number} phaseNum - Phase identifier
+ * @param {Object} [opts] - {max_recommendations, min_score}
+ * @returns {Object}
+ */
+function recommendForPhase(cwd, phaseNum, opts) {
+  const cache = loadToolCache(cwd);
+  const tools = flattenTools(cache.servers);
+  if (tools.length === 0) {
+    return {
+      phase: String(phaseNum),
+      runtime: cache.runtime,
+      recommendations: [],
+      reason: 'no MCP tools cached — run `pan-tools bridge cache` or ensure host runtime populates .planning/bridge/available-tools.json',
+    };
+  }
+
+  const phaseInfo = findPhaseInternal(cwd, phaseNum);
+  if (!phaseInfo || !phaseInfo.found) {
+    return {
+      phase: String(phaseNum),
+      error: `Phase ${phaseNum} not found in .planning/phases/`,
+    };
+  }
+
+  const phaseDir = path.join(cwd, phaseInfo.directory);
+  const planTexts = (phaseInfo.plans || [])
+    .map(f => safeReadFile(path.join(phaseDir, f)) || '')
+    .join('\n');
+
+  const max = Math.max(1, Math.min(50, Number(opts?.max_recommendations) || 10));
+  const minScore = Math.max(0, Number(opts?.min_score) || 1);
+
+  const scored = tools
+    .map(tool => ({
+      ...tool,
+      ...scoreToolForPhase(planTexts, tool),
+    }))
+    .filter(t => t.score >= minScore)
+    .sort((a, b) => b.score - a.score || a.name.localeCompare(b.name))
+    .slice(0, max);
+
+  return {
+    phase: String(phaseNum),
+    phase_name: phaseInfo.name || null,
+    runtime: cache.runtime,
+    total_candidates: tools.length,
+    recommendations: scored.map(t => ({
+      server: t.server,
+      name: t.name,
+      description: t.description,
+      score: t.score,
+      hits: t.hits,
+    })),
+  };
+}
+
+// ─── CLI wrappers ───────────────────────────────────────────────────────────
+
+function cmdBridgeList(cwd, raw) {
+  output(listTools(cwd), raw);
+}
+
+function cmdBridgeRecommend(cwd, phaseNum, opts, raw) {
+  if (!phaseNum) error('Usage: bridge recommend <phase> [--max N] [--min-score N]');
+  output(recommendForPhase(cwd, phaseNum, opts), raw);
+}
+
+function cmdBridgeCache(cwd, serversJson, runtime, raw) {
+  // For scripted cache writes. Normally the host runtime writes the file,
+  // but this CLI path lets users seed it for testing or from external scripts.
+  if (!serversJson) {
+    // No payload — just echo the current cache path/state.
+    output(listTools(cwd), raw);
+    return;
+  }
+  let servers;
+  try { servers = JSON.parse(serversJson); }
+  catch (e) { error(`Invalid --servers JSON: ${e.message}`); }
+  output(writeToolCache(cwd, { runtime, servers }), raw);
+}
+
+module.exports = {
+  loadToolCache,
+  writeToolCache,
+  flattenTools,
+  listTools,
+  scoreToolForPhase,
+  recommendForPhase,
+  cmdBridgeList,
+  cmdBridgeRecommend,
+  cmdBridgeCache,
+  BRIDGE_DIR,
+  TOOLS_FILE,
+};

package/pan-wizard-core/bin/lib/bus.cjs

@@ -0,0 +1,251 @@
+/**
+ * Bus — file-backed message channels for agent-to-agent communication
+ *
+ * Part of Spec B v2 Y-7 infrastructure (v3.0). Enables future hierarchical
+ * agent spawning (exec-phase --hierarchical, Wave 5) and inter-agent
+ * coordination (review-deep, Wave 3) without committing to an in-process
+ * IPC mechanism.
+ *
+ * Storage model:
+ *   .planning/bus/<channel>.jsonl — append-only JSON Lines
+ *   Each line: {ts, source, payload}
+ *
+ * Channels are created on first publish. Readers use cursor-based drain
+ * (read N lines from an offset) or consume-all drain (read + truncate).
+ *
+ * Concurrent-write safety: each publish opens the file with append flag
+ * (`a`) which the OS treats atomically for writes <PIPE_BUF on POSIX and
+ * sub-buffer writes on Windows. Entries are single lines. For parallel
+ * publishers writing large payloads, see the safety note below.
+ *
+ * Agent-name / channel-name validation: restricted to
+ * `^[a-zA-Z0-9_-]+$` to block path traversal.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { output, error } = require('./core.cjs');
+const { PLANNING_DIR } = require('./constants.cjs');
+const { planningPath } = require('./utils.cjs');
+
+const BUS_DIR = 'bus';
+const NAME_RE = /^[a-zA-Z0-9_-]+$/;
+const DEFAULT_DRAIN_LIMIT = 1000;
+
+function busDir(cwd) {
+  return path.join(planningPath(cwd), BUS_DIR);
+}
+
+function channelFile(cwd, channel) {
+  return path.join(busDir(cwd), `${channel}.jsonl`);
+}
+
+function validateName(name, label) {
+  if (typeof name !== 'string' || !NAME_RE.test(name)) {
+    return `Invalid ${label}: ${name}. Must match ${NAME_RE}`;
+  }
+  return null;
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+/**
+ * Publish a message to a channel. Creates channel file + dir if missing.
+ *
+ * @param {string} cwd - Project root
+ * @param {string} channel - Channel name (validated)
+ * @param {*} payload - JSON-serializable payload
+ * @param {Object} [opts] - {source: string} — who sent it (agent name, command name)
+ * @returns {{published: true, ts: string, file: string, size: number}|{error: string}}
+ */
+function publish(cwd, channel, payload, opts) {
+  const chErr = validateName(channel, 'channel');
+  if (chErr) return { error: chErr };
+  const source = opts?.source;
+  // Treat null + undefined + empty string as "no source provided".
+  if (source !== undefined && source !== null && source !== '') {
+    const sErr = validateName(source, 'source');
+    if (sErr) return { error: sErr };
+  }
+
+  const normalizedSource = (source !== undefined && source !== null && source !== '') ? source : null;
+  let line;
+  try {
+    line = JSON.stringify({ ts: nowIso(), source: normalizedSource, payload }) + '\n';
+  } catch (e) {
+    return { error: `payload not JSON-serializable: ${e.message}` };
+  }
+
+  try {
+    fs.mkdirSync(busDir(cwd), { recursive: true });
+  } catch (e) {
+    return { error: `Failed to create bus dir: ${e.message}` };
+  }
+
+  const file = channelFile(cwd, channel);
+  try {
+    fs.appendFileSync(file, line, { encoding: 'utf-8' });
+  } catch (e) {
+    return { error: `Failed to append to channel ${channel}: ${e.message}` };
+  }
+
+  let size = 0;
+  try { size = fs.statSync(file).size; } catch { /* race — ignore */ }
+
+  return { published: true, ts: JSON.parse(line).ts, file, size };
+}
+
+/**
+ * Parse a channel file into an array of entries.
+ * @param {string} cwd - Project root
+ * @param {string} channel - Channel name
+ * @param {Object} [opts] - {offset: number, limit: number}
+ * @returns {{entries: Array, total: number, offset: number, more: boolean}|{error: string}}
+ */
+function readChannel(cwd, channel, opts) {
+  const chErr = validateName(channel, 'channel');
+  if (chErr) return { error: chErr };
+  const offset = Math.max(0, Number(opts?.offset) || 0);
+  const rawLimit = Number(opts?.limit);
+  const limit = Number.isFinite(rawLimit) && rawLimit > 0 ? rawLimit : DEFAULT_DRAIN_LIMIT;
+
+  let raw;
+  try {
+    raw = fs.readFileSync(channelFile(cwd, channel), 'utf-8');
+  } catch {
+    return { entries: [], total: 0, offset: 0, more: false };
+  }
+
+  const lines = raw.split('\n').filter(Boolean);
+  const total = lines.length;
+  const slice = lines.slice(offset, offset + limit);
+  const entries = [];
+  for (let i = 0; i < slice.length; i++) {
+    try {
+      entries.push(JSON.parse(slice[i]));
+    } catch {
+      // Skip malformed lines but don't fail the whole read.
+      entries.push({ ts: null, source: null, payload: null, malformed: true, raw: slice[i] });
+    }
+  }
+
+  return { entries, total, offset, more: offset + entries.length < total };
+}
+
+/**
+ * Drain (read + optionally truncate) messages from a channel.
+ *
+ * Three drain modes:
+ *  - `peek` (default): read entries, leave file untouched
+ *  - `consume`: read entries, truncate file to zero bytes
+ *  - `archive`: read entries, rename file to `<channel>-<ts>.archive.jsonl` so
+ *    historical data is preserved while the channel restarts empty
+ *
+ * @param {string} cwd - Project root
+ * @param {string} channel - Channel name
+ * @param {Object} [opts] - {mode: 'peek'|'consume'|'archive', limit, offset}
+ * @returns {Object} Drain result
+ */
+function drain(cwd, channel, opts) {
+  const mode = opts?.mode || 'peek';
+  const read = readChannel(cwd, channel, opts);
+  if (read.error) return read;
+
+  if (mode === 'peek' || read.total === 0) return { ...read, mode };
+
+  const file = channelFile(cwd, channel);
+  if (mode === 'consume') {
+    try {
+      fs.writeFileSync(file, '', 'utf-8');
+    } catch (e) {
+      return { ...read, mode, drain_error: e.message };
+    }
+  } else if (mode === 'archive') {
+    const stamp = nowIso().replace(/[:.]/g, '-');
+    const archivePath = path.join(busDir(cwd), `${channel}-${stamp}.archive.jsonl`);
+    try {
+      fs.renameSync(file, archivePath);
+    } catch (e) {
+      return { ...read, mode, drain_error: e.message };
+    }
+  } else {
+    return { error: `unknown drain mode: ${mode}` };
+  }
+
+  return { ...read, mode };
+}
+
+/**
+ * List channels + message counts + sizes for observability.
+ * @param {string} cwd - Project root
+ * @returns {{channels: Array<{channel: string, messages: number, bytes: number, archive: boolean}>}}
+ */
+function listChannels(cwd) {
+  let files;
+  try {
+    files = fs.readdirSync(busDir(cwd));
+  } catch {
+    return { channels: [] };
+  }
+
+  const channels = [];
+  for (const f of files) {
+    if (!f.endsWith('.jsonl')) continue;
+    const archive = f.includes('.archive.');
+    const nameBase = f.replace(/\.jsonl$/, '');
+    const channel = archive ? nameBase.replace(/\.archive$/, '') : nameBase;
+    const filePath = path.join(busDir(cwd), f);
+    let bytes = 0;
+    let messages = 0;
+    try {
+      const content = fs.readFileSync(filePath, 'utf-8');
+      bytes = Buffer.byteLength(content, 'utf-8');
+      messages = content.split('\n').filter(Boolean).length;
+    } catch { /* unreadable — skip */ }
+    channels.push({ channel, messages, bytes, archive });
+  }
+  channels.sort((a, b) => a.channel.localeCompare(b.channel) || (a.archive ? 1 : -1));
+  return { channels };
+}
+
+// ─── CLI wrappers ───────────────────────────────────────────────────────────
+
+function cmdBusPublish(cwd, channel, rawPayload, opts, raw) {
+  if (!channel || rawPayload === undefined) {
+    error('Usage: bus publish <channel> <json-payload> [--source <name>]');
+  }
+  let payload;
+  try {
+    payload = JSON.parse(rawPayload);
+  } catch {
+    // Fall back: treat as plain string if not valid JSON.
+    payload = rawPayload;
+  }
+  const result = publish(cwd, channel, payload, opts);
+  output(result, raw);
+}
+
+function cmdBusDrain(cwd, channel, opts, raw) {
+  if (!channel) error('Usage: bus drain <channel> [--mode peek|consume|archive] [--limit N] [--offset N]');
+  const result = drain(cwd, channel, opts);
+  output(result, raw);
+}
+
+function cmdBusList(cwd, raw) {
+  output(listChannels(cwd), raw);
+}
+
+module.exports = {
+  publish,
+  readChannel,
+  drain,
+  listChannels,
+  validateName,
+  cmdBusPublish,
+  cmdBusDrain,
+  cmdBusList,
+  BUS_DIR,
+  DEFAULT_DRAIN_LIMIT,
+};

package/pan-wizard-core/bin/lib/codebase.cjs

@@ -721,6 +721,121 @@ function cmdBestPractices(cwd, raw) {
   output(result, raw);
 }
 
+// ─── E-2: Repo token-size estimation (Opus 4.7 single-shot map-codebase) ────
+
+/**
+ * Estimate total token count of source files in a repository.
+ *
+ * Uses CHARS_PER_TOKEN as a rough approximation (no tokenizer shipped).
+ * Walks source files via walkSourceFiles (respects SKIP_DIRS) plus a curated
+ * set of "planning" files the map-codebase agent actually reads (top-level
+ * README, package.json, CLAUDE.md, docs/ top level).
+ *
+ * Returns enough info for map-codebase to choose between single-shot mode
+ * (all files fit in 1M context) and sharded mode (6-way parallel today).
+ *
+ * @param {string} cwd - Project root
+ * @param {Object} [opts]
+ * @param {number} [opts.threshold=700000] - Single-shot cutoff (tokens)
+ * @param {boolean} [opts.include_docs=true] - Whether to include docs/*.md top level
+ * @returns {{
+ *   total_bytes: number,
+ *   total_tokens: number,
+ *   threshold: number,
+ *   mode: 'single-shot'|'sharded',
+ *   file_count: number,
+ *   languages: Object<string, number>
+ * }}
+ */
+function estimateRepoTokenSize(cwd, opts) {
+  const { CHARS_PER_TOKEN } = require('./constants.cjs');
+  const threshold = (opts && typeof opts.threshold === 'number' && opts.threshold > 0)
+    ? opts.threshold
+    : 700000;
+  const includeDocs = !opts || opts.include_docs !== false;
+
+  let totalBytes = 0;
+  let fileCount = 0;
+  const languages = {};
+
+  // Source files via the existing walker — respects gitignore-like skip list.
+  const walked = walkSourceFiles(cwd, cwd);
+  for (const [lang, files] of Object.entries(walked.files_by_language)) {
+    for (const relPath of files) {
+      const abs = path.join(cwd, relPath);
+      try {
+        const stat = fs.statSync(abs);
+        totalBytes += stat.size;
+        languages[lang] = (languages[lang] || 0) + stat.size;
+        fileCount += 1;
+      } catch { /* file may have been removed between walk and stat — ignore */ }
+    }
+  }
+
+  // Curated top-level planning files the agent actually reads.
+  const planningCandidates = [
+    'README.md',
+    'CLAUDE.md',
+    'AGENTS.md',
+    'package.json',
+    'pyproject.toml',
+    'go.mod',
+    'Cargo.toml',
+  ];
+  for (const rel of planningCandidates) {
+    try {
+      const stat = fs.statSync(path.join(cwd, rel));
+      if (stat.isFile()) {
+        totalBytes += stat.size;
+        languages.docs = (languages.docs || 0) + stat.size;
+        fileCount += 1;
+      }
+    } catch { /* missing — expected */ }
+  }
+
+  // docs/*.md at top level only (avoid recursing into specs/decisions/archive).
+  if (includeDocs) {
+    const docsDir = path.join(cwd, 'docs');
+    try {
+      const entries = fs.readdirSync(docsDir, { withFileTypes: true });
+      for (const e of entries) {
+        if (!e.isFile() || !e.name.endsWith('.md')) continue;
+        try {
+          const stat = fs.statSync(path.join(docsDir, e.name));
+          totalBytes += stat.size;
+          languages.docs = (languages.docs || 0) + stat.size;
+          fileCount += 1;
+        } catch { /* ignore */ }
+      }
+    } catch { /* no docs dir — expected in greenfield */ }
+  }
+
+  const totalTokens = Math.ceil(totalBytes / CHARS_PER_TOKEN);
+  const mode = totalTokens <= threshold ? 'single-shot' : 'sharded';
+
+  return {
+    total_bytes: totalBytes,
+    total_tokens: totalTokens,
+    threshold,
+    mode,
+    file_count: fileCount,
+    languages,
+  };
+}
+
+function cmdEstimateRepoSize(cwd, raw, args) {
+  const thresholdIdx = Array.isArray(args) ? args.indexOf('--threshold') : -1;
+  const threshold = thresholdIdx !== -1 && args[thresholdIdx + 1]
+    ? Number(args[thresholdIdx + 1])
+    : undefined;
+  const noDocs = Array.isArray(args) && args.includes('--no-docs');
+  const opts = {};
+  if (threshold && Number.isFinite(threshold) && threshold > 0) opts.threshold = threshold;
+  if (noDocs) opts.include_docs = false;
+  const result = estimateRepoTokenSize(cwd, opts);
+  output(result, raw);
+}
+
 // ─── Exports ────────────────────────────────────────────────────────────────
 
 module.exports = {
@@ -743,4 +858,7 @@ module.exports = {
   cmdDetectLanguages,
   cmdAnalyzeImports,
   cmdBestPractices,
+  cmdEstimateRepoSize,
+  // E-2
+  estimateRepoTokenSize,
 };

package/pan-wizard-core/bin/lib/commands.cjs

@@ -1453,5 +1453,6 @@ module.exports = {
   cmdLearningsExtract,
   cmdLearningsList,
   cmdLearningsPrune,
+  runCommitSafetyChecks,
   VALID_COMMIT_TYPES,
 };