@orchestrator-claude/definitions 3.31.1 → 3.31.2

package/hooks/lib/capability-scanner.ts

@@ -0,0 +1,640 @@
+/**
+ * capability-scanner.ts — Plugin/Agent/Vault capability scanner (RFC-027 Sprint 2)
+ *
+ * Scans the local filesystem to build a capability index:
+ * - Installed plugins (from ~/.claude/plugins/installed_plugins.json + cache dirs)
+ * - Agent definitions (from .claude/agents/*.md)
+ * - Vault state (from .vault-config.yaml)
+ *
+ * All functions are fail-open: they return defaults on error, never throw.
+ */
+
+import { readFileSync, readdirSync, existsSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+
+// ─── Types ───────────────────────────────────────────────
+
+export interface PluginCapability {
+  name: string;
+  version: string;
+  skills: string[];
+  agents: string[];
+  commands: string[];
+  hasMcp: boolean;
+  hasHooks: boolean;
+}
+
+export interface VaultSummary {
+  tier: number;
+  stack: string;
+  maturity: number;
+  packs: string[];
+}
+
+export interface CapabilityIndex {
+  lastScanned: string;
+  installedPluginsMtime: string;
+  plugins: PluginCapability[];
+  agents: string[];
+  vault: VaultSummary;
+  routing: Record<string, string>;
+  gaps: string[];
+}
+
+// ─── Plugin Scanning ─────────────────────────────────────
+
+interface InstalledPlugin {
+  scope: string;
+  projectPath: string;
+  installPath: string;
+  version: string;
+}
+
+interface InstalledPluginsFile {
+  version: number;
+  plugins: Record<string, InstalledPlugin[]>;
+}
+
+/**
+ * Extract plugin name from the key format "name@source".
+ */
+function pluginNameFromKey(key: string): string {
+  return key.split('@')[0];
+}
+
+/**
+ * Scan a single plugin install directory for capabilities.
+ */
+function scanSinglePlugin(name: string, installPath: string, version: string): PluginCapability {
+  const cap: PluginCapability = {
+    name,
+    version,
+    skills: [],
+    agents: [],
+    commands: [],
+    hasMcp: false,
+    hasHooks: false,
+  };
+
+  try {
+    const baseDir = installPath;
+    if (!existsSync(baseDir)) return cap;
+
+    // Skills: list subdirectory names under skills/
+    const skillsDir = join(baseDir, 'skills');
+    if (existsSync(skillsDir)) {
+      cap.skills = readdirSync(skillsDir, { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .map((d) => d.name)
+        .sort();
+    }
+
+    // Agents: list .md filenames (sans extension) under agents/
+    const agentsDir = join(baseDir, 'agents');
+    if (existsSync(agentsDir)) {
+      cap.agents = readdirSync(agentsDir)
+        .filter((f) => f.endsWith('.md'))
+        .map((f) => f.replace(/\.md$/, ''))
+        .sort();
+    }
+
+    // Commands: list .md filenames (sans extension) under commands/
+    const commandsDir = join(baseDir, 'commands');
+    if (existsSync(commandsDir)) {
+      cap.commands = readdirSync(commandsDir)
+        .filter((f) => f.endsWith('.md'))
+        .map((f) => f.replace(/\.md$/, ''))
+        .sort();
+    }
+
+    // MCP: check .mcp.json exists
+    cap.hasMcp = existsSync(join(baseDir, '.mcp.json'));
+
+    // Hooks: single statSync to avoid TOCTOU race (IMP-001)
+    try {
+      cap.hasHooks = statSync(join(baseDir, 'hooks')).isDirectory();
+    } catch {
+      cap.hasHooks = false;
+    }
+  } catch {
+    // fail-open: return partial result
+  }
+
+  return cap;
+}
+
+/**
+ * Scan all installed plugins from installed_plugins.json.
+ * Returns empty array on any error (fail-open).
+ */
+export function scanPluginCache(installedPluginsPath: string): PluginCapability[] {
+  try {
+    const raw = readFileSync(installedPluginsPath, 'utf-8');
+    const data = JSON.parse(raw) as InstalledPluginsFile;
+    if (!data.plugins || typeof data.plugins !== 'object') return [];
+
+    const result: PluginCapability[] = [];
+
+    for (const [key, entries] of Object.entries(data.plugins)) {
+      const name = pluginNameFromKey(key);
+      const entry = entries[0];
+      if (!entry) continue;
+
+      result.push(scanSinglePlugin(name, entry.installPath, entry.version));
+    }
+
+    return result.sort((a, b) => a.name.localeCompare(b.name));
+  } catch {
+    return [];
+  }
+}
+
+// ─── Agent Definition Scanning ───────────────────────────
+
+/**
+ * Scan .claude/agents/ directory for agent definition .md files.
+ * Returns sorted list of agent names (filenames without .md extension).
+ */
+export function scanAgentDefinitions(agentsDir: string): string[] {
+  try {
+    if (!existsSync(agentsDir)) return [];
+    return readdirSync(agentsDir)
+      .filter((f) => f.endsWith('.md'))
+      .map((f) => f.replace(/\.md$/, ''))
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+// ─── Vault Summary ───────────────────────────────────────
+
+const DEFAULT_VAULT: VaultSummary = {
+  tier: 1,
+  stack: 'unknown',
+  maturity: 0,
+  packs: [],
+};
+
+/**
+ * Read vault summary from .vault-config.yaml.
+ * Returns defaults on any error (fail-open).
+ */
+export function readVaultSummary(vaultConfigPath: string): VaultSummary {
+  try {
+    if (!existsSync(vaultConfigPath)) return { ...DEFAULT_VAULT };
+    const raw = readFileSync(vaultConfigPath, 'utf-8');
+    const config = parseYaml(raw) as Record<string, unknown>;
+
+    const project = config?.project as Record<string, unknown> | undefined;
+    const constitution = config?.constitution as Record<string, unknown> | undefined;
+    const maturityObj = project?.maturity as Record<string, unknown> | undefined;
+
+    return {
+      tier: (project?.tier as number) ?? 1,
+      stack: (project?.stack as string) ?? 'unknown',
+      maturity: (maturityObj?.current as number) ?? 0,
+      packs: constitution?.pack ? [constitution.pack as string] : [],
+    };
+  } catch {
+    return { ...DEFAULT_VAULT };
+  }
+}
+
+// ─── Invalidation ────────────────────────────────────────
+
+/**
+ * Check if a rescan is needed by comparing installed_plugins.json mtime
+ * against the cached mtime string. Returns true if rescan needed.
+ */
+export function needsRescan(installedPluginsPath: string, cachedMtime: string): boolean {
+  try {
+    if (!existsSync(installedPluginsPath)) return true;
+    const currentMtime = statSync(installedPluginsPath).mtime.toISOString();
+    return currentMtime !== cachedMtime;
+  } catch {
+    return true;
+  }
+}
+
+// ─── Routing Table ───────────────────────────────────────
+
+/** Default routing when no plugins are installed */
+const DEFAULT_ROUTING: Record<string, string> = {
+  analysis: 'researcher (sub-agent)',
+  spec: 'specifier (sub-agent)',
+  plan: 'planner (sub-agent)',
+  tasks: 'task-generator (sub-agent)',
+  implement: 'implementer (sub-agent)',
+  code_review: 'reviewer (sub-agent)',
+  pr_review: 'reviewer (sub-agent)',
+  design: 'brainstorming (native skill)',
+  debug: 'systematic-debugging (native skill)',
+  research: 'researcher (sub-agent)',
+};
+
+/** Plugin-based routing overrides. Checked in order. */
+const PLUGIN_ROUTING_OVERRIDES: {
+  plugin: string;
+  capability?: string;
+  routes: Record<string, string>;
+}[] = [
+  {
+    plugin: 'feature-dev',
+    capability: 'code-explorer',
+    routes: {
+      analysis: 'feature-dev:code-explorer',
+    },
+  },
+  {
+    plugin: 'coderabbit',
+    routes: {
+      pr_review: 'coderabbit:review',
+    },
+  },
+];
+
+/**
+ * Build routing table from installed plugins.
+ * Starts with defaults, applies overrides for installed plugins.
+ */
+export function buildRoutingTable(plugins: PluginCapability[]): Record<string, string> {
+  const routing = { ...DEFAULT_ROUTING };
+  const installedNames = new Set(plugins.map((p) => p.name));
+
+  for (const override of PLUGIN_ROUTING_OVERRIDES) {
+    if (!installedNames.has(override.plugin)) continue;
+
+    if (override.capability) {
+      const plugin = plugins.find((p) => p.name === override.plugin);
+      const hasCapability =
+        plugin?.agents.includes(override.capability) ||
+        plugin?.skills.includes(override.capability);
+      if (!hasCapability) continue;
+    }
+
+    Object.assign(routing, override.routes);
+  }
+
+  return routing;
+}
+
+// ─── Profile Comparison ──────────────────────────────────
+
+interface PluginProfile {
+  core?: string[];
+  recommended?: string[];
+  optional?: string[];
+}
+
+interface PluginProfilesFile {
+  schema: string;
+  stacks: Record<string, PluginProfile>;
+}
+
+/**
+ * Compare installed plugins against stack profile.
+ * Returns gap descriptions (e.g., "MISSING core: serena, superpowers").
+ */
+export function compareWithProfiles(
+  plugins: PluginCapability[],
+  profilesPath: string,
+  stack: string
+): string[] {
+  try {
+    if (!existsSync(profilesPath)) return [];
+    const raw = readFileSync(profilesPath, 'utf-8');
+    const profiles = parseYaml(raw) as PluginProfilesFile;
+
+    const stackProfile = profiles?.stacks?.[stack];
+    if (!stackProfile) return [];
+
+    const installedNames = new Set(plugins.map((p) => p.name));
+    const gaps: string[] = [];
+
+    const missingCore = (stackProfile.core ?? []).filter((p) => !installedNames.has(p));
+    if (missingCore.length > 0) {
+      gaps.push(`MISSING core: ${missingCore.join(', ')}`);
+    }
+
+    const missingRec = (stackProfile.recommended ?? []).filter((p) => !installedNames.has(p));
+    if (missingRec.length > 0) {
+      gaps.push(`MISSING recommended: ${missingRec.join(', ')}`);
+    }
+
+    return gaps;
+  } catch {
+    return [];
+  }
+}
+
+// ─── Full Index Builder ──────────────────────────────────
+
+/**
+ * Build a complete CapabilityIndex by scanning all sources.
+ * This is the main entry point for the session-start hook.
+ */
+export function buildCapabilityIndex(opts: {
+  installedPluginsPath: string;
+  agentsDir: string;
+  vaultConfigPath: string;
+  profilesPath: string;
+}): CapabilityIndex {
+  const plugins = scanPluginCache(opts.installedPluginsPath);
+  const agents = scanAgentDefinitions(opts.agentsDir);
+  const vault = readVaultSummary(opts.vaultConfigPath);
+  const routing = buildRoutingTable(plugins);
+  const gaps = compareWithProfiles(plugins, opts.profilesPath, vault.stack);
+
+  let installedPluginsMtime = '';
+  try {
+    installedPluginsMtime = statSync(opts.installedPluginsPath).mtime.toISOString();
+  } catch {
+    // leave empty
+  }
+
+  return {
+    lastScanned: new Date().toISOString(),
+    installedPluginsMtime,
+    plugins,
+    agents,
+    vault,
+    routing,
+    gaps,
+  };
+}
+
+// ─── Vault Persistence ───────────────────────────────────
+
+/**
+ * Write CapabilityIndex to the `capabilities:` section of vault config YAML.
+ * Performs surgical merge — only touches `capabilities:`, preserves all other sections.
+ * Fails silently on error.
+ */
+export function writeCapabilitiesToVault(vaultConfigPath: string, index: CapabilityIndex): void {
+  try {
+    let config: Record<string, unknown> = {};
+    if (existsSync(vaultConfigPath)) {
+      const raw = readFileSync(vaultConfigPath, 'utf-8');
+      config = (parseYaml(raw) as Record<string, unknown>) ?? {};
+    }
+
+    const pluginEntries = index.plugins.map((p) => {
+      const entry: Record<string, unknown> = { name: p.name };
+      if (p.version !== 'unknown') entry.version = p.version;
+      if (p.skills.length > 0) entry.skills = p.skills;
+      if (p.agents.length > 0) entry.agents = p.agents;
+      if (p.commands.length > 0) entry.commands = p.commands;
+      if (p.hasMcp) entry.mcp = true;
+      if (p.hasHooks) entry.hooks = true;
+      return entry;
+    });
+
+    config.capabilities = {
+      last_scanned: index.lastScanned,
+      installed_plugins_mtime: index.installedPluginsMtime,
+      plugins: pluginEntries,
+      routing: index.routing,
+      gaps: index.gaps,
+    };
+
+    writeFileSync(vaultConfigPath, stringifyYaml(config, { lineWidth: 120 }));
+  } catch {
+    // fail-open
+  }
+}
+
+/**
+ * Read cached CapabilityIndex from vault config's `capabilities:` section.
+ * Returns null if section doesn't exist or on any error.
+ */
+export function readCapabilitiesFromVault(vaultConfigPath: string): CapabilityIndex | null {
+  try {
+    if (!existsSync(vaultConfigPath)) return null;
+    const raw = readFileSync(vaultConfigPath, 'utf-8');
+    const config = parseYaml(raw) as Record<string, unknown>;
+    const caps = config?.capabilities as Record<string, unknown> | undefined;
+    if (!caps) return null;
+
+    // Guard against malformed YAML where plugins is not an array (IMP-002)
+    const rawPlugins = Array.isArray(caps.plugins)
+      ? (caps.plugins as Record<string, unknown>[])
+      : [];
+    const plugins: PluginCapability[] = rawPlugins.map((p) => ({
+      name: (p.name as string) ?? '',
+      version: (p.version as string) ?? 'unknown',
+      skills: (p.skills as string[]) ?? [],
+      agents: (p.agents as string[]) ?? [],
+      commands: (p.commands as string[]) ?? [],
+      hasMcp: (p.mcp as boolean) ?? false,
+      hasHooks: (p.hooks as boolean) ?? false,
+    }));
+
+    return {
+      lastScanned: (caps.last_scanned as string) ?? '',
+      installedPluginsMtime: (caps.installed_plugins_mtime as string) ?? '',
+      plugins,
+      agents: [], // agents are always scanned fresh (fast, <10ms)
+      vault: readVaultSummary(vaultConfigPath),
+      routing: (caps.routing as Record<string, string>) ?? {},
+      gaps: (caps.gaps as string[]) ?? [],
+    };
+  } catch {
+    return null;
+  }
+}
+
+// ─── Formatting ──────────────────────────────────────────
+
+/**
+ * Format a single plugin as a compact string: "name(Nsk,Nag)" or "name(mcp)".
+ */
+function formatPluginCompact(p: PluginCapability): string {
+  const parts: string[] = [];
+  if (p.skills.length > 0) parts.push(`${p.skills.length}sk`);
+  if (p.agents.length > 0) parts.push(`${p.agents.length}ag`);
+  if (p.hasMcp && parts.length === 0) parts.push('mcp');
+  return parts.length > 0 ? `${p.name}(${parts.join(',')})` : p.name;
+}
+
+/**
+ * Format CapabilityIndex as compact multi-line injection (~80 tokens).
+ */
+export function formatCapabilityMatrix(index: CapabilityIndex): string {
+  const pluginCount = index.plugins.length;
+  const pluginSummary = index.plugins
+    .filter((p) => p.skills.length > 0 || p.agents.length > 0 || p.hasMcp)
+    .map(formatPluginCompact)
+    .join(', ');
+
+  const agentList =
+    index.agents.length <= 6
+      ? index.agents.join(',')
+      : `${index.agents.slice(0, 6).join(',')},+${index.agents.length - 6}`;
+
+  const routingPairs = Object.entries(index.routing)
+    .filter(([, v]) => !v.includes('sub-agent') && v !== 'Main inline')
+    .map(([k, v]) => `${k}→${v}`)
+    .join(' | ');
+
+  const gapsLine = index.gaps.length > 0 ? index.gaps.join('; ') : 'none';
+
+  return [
+    '[CAPABILITY-MATRIX]',
+    `plugins(${pluginCount}): ${pluginSummary || 'none with capabilities'}`,
+    `agents(${index.agents.length}): ${agentList || 'none'}`,
+    `vault: tier=${index.vault.tier}, stack=${index.vault.stack}, maturity=${index.vault.maturity}, packs=[${index.vault.packs.join(',')}]`,
+    `routing: ${routingPairs || 'defaults only'}`,
+    `gaps: ${gapsLine}`,
+  ].join('\n');
+}
+
+// ─── Memory Context ──────────────────────────────────────
+
+export interface MemoryEntry {
+  file: string;
+  type: string;
+  tags: string[];
+  last_accessed: string;
+  summary: string;
+}
+
+/**
+ * Format filtered memory entries as compact injection.
+ * Returns empty string if no entries (skip injection).
+ */
+export function formatMemoryContext(entries: MemoryEntry[]): string {
+  if (entries.length === 0) return '';
+
+  const byType: Record<string, number> = {};
+  for (const e of entries) {
+    byType[e.type] = (byType[e.type] ?? 0) + 1;
+  }
+  const typeSummary = Object.entries(byType)
+    .map(([t, n]) => `${n} ${t}`)
+    .join(', ');
+
+  const recentNames = entries
+    .slice(0, 5)
+    .map((e) => e.file.replace(/\.md$/, '').replace(/^(feedback|project|reference|user)_/, ''))
+    .join(', ');
+
+  return [
+    `[MEMORY-CONTEXT] ${entries.length} entries: ${typeSummary}`,
+    `recent: ${recentNames}`,
+  ].join('\n');
+}
+
+// ─── Memory Index Reading ────────────────────────────────
+
+interface MemoryIndex {
+  schema: string;
+  entries: MemoryEntry[];
+}
+
+/**
+ * Read memory-index.yaml and return parsed entries.
+ * Returns null if file missing or corrupt (fail-open).
+ */
+export function readMemoryIndex(indexPath: string): MemoryEntry[] | null {
+  try {
+    if (!existsSync(indexPath)) return null;
+    const raw = readFileSync(indexPath, 'utf-8');
+    const parsed = parseYaml(raw) as MemoryIndex;
+    return parsed?.entries ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Filter memory entries by relevance for session injection.
+ * Keeps: recent (14 days), all feedback, tag matches.
+ * Returns max 20 entries, sorted by type priority then recency.
+ */
+export function filterRelevantMemories(
+  entries: MemoryEntry[],
+  contextTags: string[] = []
+): MemoryEntry[] {
+  const now = Date.now();
+  const fourteenDays = 14 * 24 * 60 * 60 * 1000;
+
+  const relevant = entries.filter((e) => {
+    if (e.type === 'feedback') return true;
+    const accessed = new Date(e.last_accessed).getTime();
+    if (now - accessed < fourteenDays) return true;
+    if (contextTags.length > 0 && e.tags.some((t) => contextTags.includes(t))) return true;
+    return false;
+  });
+
+  const typePriority: Record<string, number> = {
+    feedback: 0,
+    project: 1,
+    reference: 2,
+    user: 3,
+  };
+  relevant.sort((a, b) => {
+    const pa = typePriority[a.type] ?? 9;
+    const pb = typePriority[b.type] ?? 9;
+    if (pa !== pb) return pa - pb;
+    return b.last_accessed.localeCompare(a.last_accessed);
+  });
+
+  return relevant.slice(0, 20);
+}
+
+/**
+ * Find memory entries that are candidates for archiving.
+ * Criteria: last_accessed >90 days ago, OR status: superseded in .md frontmatter.
+ * Fail-open: invalid dates or file read errors → entry skipped.
+ */
+export function findArchiveCandidates(
+  entries: MemoryEntry[],
+  today: Date,
+  memoryDir?: string
+): MemoryEntry[] {
+  const ninetyDays = 90 * 24 * 60 * 60 * 1000;
+  const candidateSet = new Set<string>();
+  const candidates: MemoryEntry[] = [];
+
+  for (const entry of entries) {
+    try {
+      let isCandidate = false;
+
+      // Check age
+      const accessed = new Date(entry.last_accessed).getTime();
+      if (!isNaN(accessed) && today.getTime() - accessed > ninetyDays) {
+        isCandidate = true;
+      }
+
+      // Check superseded status in frontmatter (lazy — only when memoryDir provided)
+      if (!isCandidate && memoryDir) {
+        try {
+          const filePath = join(memoryDir, entry.file);
+          if (existsSync(filePath)) {
+            const content = readFileSync(filePath, 'utf-8');
+            const fmMatch = /^---\n([\s\S]*?)\n---/.exec(content);
+            if (fmMatch) {
+              const fm = parseYaml(fmMatch[1]) as Record<string, unknown>;
+              if (fm?.status === 'superseded') {
+                isCandidate = true;
+              }
+            }
+          }
+        } catch {
+          // file read error → skip this check
+        }
+      }
+
+      if (isCandidate && !candidateSet.has(entry.file)) {
+        candidateSet.add(entry.file);
+        candidates.push(entry);
+      }
+    } catch {
+      // any error for this entry → skip
+    }
+  }
+
+  return candidates;
+}