kairn-cli 2.4.2 → 2.5.0

package/dist/cli.js

@@ -1464,6 +1464,361 @@ async function callLLM(config, userMessage, options) {
   }
 }
 
+// src/intent/patterns.ts
+var SYNONYM_MAP = {
+  deploy: ["ship", "push\\s+to\\s+prod", "release", "publish"],
+  test: ["run\\s+tests", "check", "verify", "run\\s+test\\s+suite"],
+  lint: ["format", "style\\s+check", "linting"],
+  build: ["compile", "bundle", "make"],
+  dev: ["develop", "start\\s+dev", "run\\s+dev"],
+  start: ["run", "launch", "serve"],
+  migrate: ["migration", "schema\\s+change", "db\\s+update"],
+  seed: ["populate", "seed\\s+data", "load\\s+fixtures"],
+  clean: ["purge", "clear", "reset\\s+cache"],
+  docs: ["document", "documentation", "write\\s+docs"],
+  review: ["code\\s+review", "pr\\s+review", "check\\s+code"],
+  commit: ["save\\s+changes", "check\\s+in", "git\\s+commit"],
+  fix: ["repair", "patch", "debug", "resolve"],
+  refactor: ["restructure", "reorganize", "clean\\s+up"],
+  plan: ["design", "architect", "outline"],
+  status: ["progress", "overview", "summary"]
+};
+function extractDescription(content) {
+  const lines = content.split("\n");
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed && !trimmed.startsWith("#")) {
+      return trimmed;
+    }
+  }
+  return "";
+}
+function extractVerb(commandName) {
+  const parts = commandName.split("-");
+  if (parts.length > 1) {
+    return parts[parts.length - 1];
+  }
+  return parts[0];
+}
+function buildPatternAlternation(commandName) {
+  const verb = extractVerb(commandName);
+  const alternatives = [verb];
+  const synonyms = SYNONYM_MAP[verb];
+  if (synonyms) {
+    alternatives.push(...synonyms);
+  }
+  if (commandName !== verb && !alternatives.includes(commandName)) {
+    alternatives.push(commandName.replace(/-/g, "[\\s-]"));
+  }
+  return `\\b(${alternatives.join("|")})\\b`;
+}
+function generateScriptPatterns(scripts, existingCommands) {
+  const patterns = [];
+  for (const scriptName of Object.keys(scripts)) {
+    const verb = extractVerb(scriptName);
+    if (existingCommands.has(verb) || existingCommands.has(scriptName)) {
+      continue;
+    }
+    const parts = scriptName.split(":");
+    if (parts.length > 1) {
+      const suffix = parts[parts.length - 1];
+      const alternatives = [suffix];
+      if (suffix === "e2e") {
+        alternatives.push("end[\\s.-]to[\\s.-]end");
+      }
+      patterns.push({
+        pattern: `\\b(${alternatives.join("|")})\\b`,
+        command: `/project:${scriptName}`,
+        description: `Run npm script: ${scriptName}`,
+        source: "generated"
+      });
+    }
+  }
+  return patterns;
+}
+function generateIntentPatterns(commands, agents, projectProfile) {
+  const patterns = [];
+  const commandNames = new Set(Object.keys(commands));
+  for (const [name, content] of Object.entries(commands)) {
+    const description = extractDescription(content);
+    const patternStr = buildPatternAlternation(name);
+    patterns.push({
+      pattern: patternStr,
+      command: `/project:${name}`,
+      description: description || `Run ${name} workflow`,
+      source: "generated"
+    });
+  }
+  const scriptPatterns = generateScriptPatterns(
+    projectProfile.scripts,
+    commandNames
+  );
+  patterns.push(...scriptPatterns);
+  patterns.sort((a, b) => b.pattern.length - a.pattern.length);
+  return patterns;
+}
+
+// src/intent/prompt-template.ts
+function extractFirstLine(content) {
+  const lines = content.split("\n");
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed && !trimmed.startsWith("#")) {
+      return trimmed;
+    }
+  }
+  return "";
+}
+function compileIntentPrompt(commands, agents) {
+  const workflowLines = [];
+  for (const [name, content] of Object.entries(commands)) {
+    const desc = extractFirstLine(content);
+    workflowLines.push(`- /project:${name} \u2014 ${desc}`);
+  }
+  const workflowManifest = workflowLines.length > 0 ? workflowLines.join("\n") : "(no workflows defined)";
+  const agentLines = [];
+  for (const [name, content] of Object.entries(agents)) {
+    const desc = extractFirstLine(content);
+    agentLines.push(`- @${name} \u2014 ${desc}`);
+  }
+  const agentManifest = agentLines.length > 0 ? agentLines.join("\n") : "(no agents defined)";
+  return `You are an intent classifier for a software project. The user said something that didn't match any known command keyword.
+
+Available workflows:
+${workflowManifest}
+
+Available agents:
+${agentManifest}
+
+User input: $PROMPT
+
+If this maps to one or more workflows, return JSON:
+{"additionalContext": "[INTENT ROUTED] Based on your request, use: /project:<command> \u2014 <description>"}
+
+If the user is asking a question or making a statement that doesn't need a workflow, return:
+{"ok": true}
+
+Do not activate workflows for questions like 'what does deploy do?' or 'how do I test?'. Only activate for action requests.`;
+}
+
+// src/intent/router-template.ts
+function renderPatternEntry(p) {
+  const escapedPattern = p.pattern.replace(/\\/g, "\\\\");
+  const escapedDesc = p.description.replace(/'/g, "\\'");
+  const escapedCmd = p.command.replace(/'/g, "\\'");
+  return `  { pattern: /${p.pattern}/i,
+    command: '${escapedCmd}',
+    description: '${escapedDesc}' }`;
+}
+function renderIntentRouter(patterns, generationTimestamp) {
+  const patternEntries = patterns.map((p) => renderPatternEntry(p)).join(",\n");
+  return `#!/usr/bin/env node
+/**
+ * Kairn Intent Router \u2014 Tier 1 (Regex)
+ * Generated by kairn describe. Project-specific keyword patterns.
+ *
+ * If a keyword matches, injects a system-reminder pointing Claude
+ * to the right command/workflow. If no match, falls through to
+ * the Tier 2 prompt hook.
+ *
+ * Last updated: ${generationTimestamp}
+ */
+
+import { readFileSync } from 'fs';
+
+// Read prompt from stdin (Claude Code hooks API)
+const input = readFileSync('/dev/stdin', 'utf-8');
+let prompt = '';
+try {
+  const data = JSON.parse(input);
+  prompt = data.prompt || '';
+} catch { process.exit(0); }
+
+if (!prompt.trim()) {
+  console.log(JSON.stringify({ "continue": true, suppressOutput: true }));
+  process.exit(0);
+}
+
+// Sanitize: strip code blocks, URLs, file paths
+const clean = prompt
+  .replace(/\`\`\`[\\s\\S]*?\`\`\`/g, '')
+  .replace(/\`[^\`]+\`/g, '')
+  .replace(/https?:\\/\\/\\S+/g, '')
+  .replace(/(\\/[\\w.-]+){2,}/g, '')
+  .toLowerCase();
+
+// Question filter: don't trigger on informational queries
+const QUESTION_PATTERNS = [
+  /\\b(?:what(?:'s|\\s+is)|how\\s+(?:to|do\\s+i)\\s+use|explain|describe|tell\\s+me\\s+about)\\b/i,
+];
+function isQuestion(text, position, length) {
+  const start = Math.max(0, position - 80);
+  const end = Math.min(text.length, position + length + 80);
+  const ctx = text.slice(start, end);
+  return QUESTION_PATTERNS.some(p => p.test(ctx));
+}
+
+// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
+// PROJECT-SPECIFIC KEYWORD PATTERNS
+// Generated from: kairn describe analysis
+// Last updated: ${generationTimestamp}
+// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
+
+const PATTERNS = [
+${patternEntries}
+];
+
+// Match against patterns
+for (const { pattern, command, description } of PATTERNS) {
+  const match = clean.match(pattern);
+  if (match && !isQuestion(clean, match.index, match[0].length)) {
+    const output = {
+      "continue": true,
+      hookSpecificOutput: {
+        hookEventName: 'UserPromptSubmit',
+        additionalContext: \`[INTENT ROUTED] Based on your request, use: \${command} \u2014 \${description}\\n\\nUser's original request: \${prompt}\\n\\nExecute the command above to fulfill the user's intent.\`
+      }
+    };
+    console.log(JSON.stringify(output));
+    process.exit(0);
+  }
+}
+
+// No match \u2014 fall through to Tier 2 (prompt hook)
+console.log(JSON.stringify({ "continue": true, suppressOutput: true }));
+`;
+}
+
+// src/intent/learner-template.ts
+function renderIntentLearner() {
+  return `#!/usr/bin/env node
+/**
+ * Kairn Intent Learner \u2014 Pattern Promotion (Tier 2 \u2192 Tier 1)
+ * Runs on SessionStart to promote recurring Tier 2 patterns to Tier 1 regexes.
+ * Generated by kairn describe.
+ */
+
+import { readFileSync, writeFileSync, appendFileSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+
+const hooksDir = join(dirname(new URL(import.meta.url).pathname));
+const logPath = join(hooksDir, 'intent-log.jsonl');
+const routerPath = join(hooksDir, 'intent-router.mjs');
+const promotionsPath = join(hooksDir, 'intent-promotions.jsonl');
+
+// Read log entries
+let entries = [];
+try {
+  const raw = readFileSync(logPath, 'utf-8').trim();
+  if (!raw) {
+    console.log(JSON.stringify({ "continue": true, suppressOutput: true }));
+    process.exit(0);
+  }
+  entries = raw.split('\\n').map(line => {
+    try { return JSON.parse(line); }
+    catch { return null; }
+  }).filter(Boolean);
+} catch {
+  // Log file doesn't exist or is unreadable \u2014 nothing to promote
+  console.log(JSON.stringify({ "continue": true, suppressOutput: true }));
+  process.exit(0);
+}
+
+if (entries.length === 0) {
+  console.log(JSON.stringify({ "continue": true, suppressOutput: true }));
+  process.exit(0);
+}
+
+// Group by routed_to command
+const groups = {};
+const remaining = [];
+for (const entry of entries) {
+  if (!entry.routed_to) { remaining.push(entry); continue; }
+  if (!groups[entry.routed_to]) groups[entry.routed_to] = [];
+  groups[entry.routed_to].push(entry);
+}
+
+// For each command with 3+ entries, extract common words and build regex
+const promoted = [];
+for (const [command, cmdEntries] of Object.entries(groups)) {
+  if (cmdEntries.length < 3) {
+    remaining.push(...cmdEntries);
+    continue;
+  }
+
+  // Extract unique words from all prompts
+  const wordFreq = {};
+  for (const entry of cmdEntries) {
+    const words = (entry.prompt || '').toLowerCase()
+      .replace(/[^a-z\\s]/g, '')
+      .split(/\\s+/)
+      .filter(w => w.length > 2);
+    const unique = [...new Set(words)];
+    for (const word of unique) {
+      wordFreq[word] = (wordFreq[word] || 0) + 1;
+    }
+  }
+
+  // Find words that appear in at least half the entries
+  const threshold = Math.ceil(cmdEntries.length / 2);
+  const commonWords = Object.entries(wordFreq)
+    .filter(([, count]) => count >= threshold)
+    .map(([word]) => word)
+    .filter(w => !['the', 'and', 'for', 'this', 'that', 'can', 'you', 'please'].includes(w));
+
+  if (commonWords.length === 0) {
+    remaining.push(...cmdEntries);
+    continue;
+  }
+
+  // Build regex pattern from common words
+  const patternStr = '\\\\b(' + commonWords.join('|') + ')\\\\b';
+
+  // Read current router and check if pattern already exists
+  try {
+    const routerContent = readFileSync(routerPath, 'utf-8');
+    if (commonWords.some(w => routerContent.includes(w + '|') || routerContent.includes('|' + w))) {
+      remaining.push(...cmdEntries);
+      continue;
+    }
+
+    // Append new pattern to PATTERNS array
+    const newEntry = \`  { pattern: /\\\\b(\${commonWords.join('|')})/i,\\n    command: '\${command}',\\n    description: 'Learned from usage patterns' },\`;
+    const insertPoint = routerContent.lastIndexOf('];');
+    if (insertPoint === -1) {
+      remaining.push(...cmdEntries);
+      continue;
+    }
+
+    const updatedRouter = routerContent.slice(0, insertPoint) +
+      newEntry + '\\n' +
+      routerContent.slice(insertPoint);
+    writeFileSync(routerPath, updatedRouter, 'utf-8');
+
+    // Record promotion
+    const promotion = {
+      timestamp: new Date().toISOString(),
+      command,
+      pattern: patternStr,
+      sourcePrompts: cmdEntries.map(e => e.prompt),
+      commonWords,
+    };
+    promoted.push(promotion);
+    appendFileSync(promotionsPath, JSON.stringify(promotion) + '\\n');
+
+  } catch {
+    remaining.push(...cmdEntries);
+    continue;
+  }
+}
+
+// Write back remaining (unprocessed) entries
+writeFileSync(logPath, remaining.map(e => JSON.stringify(e)).join('\\n') + (remaining.length ? '\\n' : ''), 'utf-8');
+
+console.log(JSON.stringify({ "continue": true, suppressOutput: true }));
+`;
+}
+
 // src/compiler/compile.ts
 function buildSkeletonMessage(intent, registry) {
   const registrySummary = registry.map(
@@ -1664,6 +2019,27 @@ async function compile(intent, onProgress) {
   onProgress?.({ phase: "pass3", status: "running", message: "Pass 3: Configuring MCP servers & settings..." });
   const settings = buildSettings(skeleton, registry);
   const mcpConfig = buildMcpConfig(skeleton, registry);
+  const projectProfile = {
+    language: skeleton.outline.tech_stack[0] ?? "unknown",
+    framework: skeleton.outline.tech_stack[1] ?? "none",
+    scripts: {}
+    // scripts come from project scanning, not compilation
+  };
+  const intentPatterns = generateIntentPatterns(
+    harness.commands,
+    harness.agents ?? {},
+    projectProfile
+  );
+  const intentPromptTemplate = compileIntentPrompt(
+    harness.commands,
+    harness.agents ?? {}
+  );
+  const generationTimestamp = (/* @__PURE__ */ new Date()).toISOString();
+  const intentHooks = {};
+  if (intentPatterns.length > 0) {
+    intentHooks["intent-router"] = renderIntentRouter(intentPatterns, generationTimestamp);
+    intentHooks["intent-learner"] = renderIntentLearner();
+  }
   onProgress?.({ phase: "pass3", status: "success", message: "Pass 3: Configured MCP servers & settings" });
   const spec = {
     id: `env_${crypto.randomUUID()}`,
@@ -1681,7 +2057,10 @@ async function compile(intent, onProgress) {
       rules: harness.rules,
       skills: harness.skills ?? {},
       agents: harness.agents ?? {},
-      docs: harness.docs
+      docs: harness.docs,
+      hooks: intentHooks,
+      intent_patterns: intentPatterns,
+      intent_prompt_template: intentPromptTemplate
     }
   };
   const warnings = validateSpec(spec);
@@ -2146,6 +2525,41 @@ function resolveSettings(spec, options) {
     hooks.SessionStart = sessionStart;
     base.hooks = hooks;
   }
+  const hasIntentHooks = spec.harness.hooks && Object.keys(spec.harness.hooks).length > 0;
+  if (hasIntentHooks) {
+    const hooks = base.hooks ?? {};
+    const userPromptSubmit = hooks.UserPromptSubmit ?? [];
+    const intentHookEntry = {
+      matcher: "*",
+      hooks: [
+        {
+          type: "command",
+          command: 'node "$CLAUDE_PROJECT_DIR/.claude/hooks/intent-router.mjs"',
+          timeout: 5
+        }
+      ]
+    };
+    if (spec.harness.intent_prompt_template) {
+      intentHookEntry.hooks.push({
+        type: "prompt",
+        prompt: spec.harness.intent_prompt_template,
+        timeout: 15
+      });
+    }
+    userPromptSubmit.push(intentHookEntry);
+    hooks.UserPromptSubmit = userPromptSubmit;
+    const sessionStart = hooks.SessionStart ?? [];
+    sessionStart.push({
+      matcher: "*",
+      hooks: [{
+        type: "command",
+        command: 'node "$CLAUDE_PROJECT_DIR/.claude/hooks/intent-learner.mjs"',
+        timeout: 10
+      }]
+    });
+    hooks.SessionStart = sessionStart;
+    base.hooks = hooks;
+  }
   if (Object.keys(base).length === 0) return null;
   return base;
 }
@@ -2194,6 +2608,14 @@ function buildFileMap(spec, options) {
       files.set(`.claude/docs/${name}.md`, content);
     }
   }
+  if (spec.harness.hooks) {
+    for (const [name, content] of Object.entries(spec.harness.hooks)) {
+      files.set(`.claude/hooks/${name}.mjs`, content);
+    }
+    if (Object.keys(spec.harness.hooks).length > 0) {
+      files.set(".claude/hooks/intent-log.jsonl", "");
+    }
+  }
   return files;
 }
 async function writeEnvironment(spec, targetDir, options) {
@@ -2252,6 +2674,18 @@ async function writeEnvironment(spec, targetDir, options) {
       written.push(`.claude/docs/${name}.md`);
     }
   }
+  if (spec.harness.hooks) {
+    for (const [name, content] of Object.entries(spec.harness.hooks)) {
+      const p = path5.join(claudeDir, "hooks", `${name}.mjs`);
+      await writeFile(p, content);
+      written.push(`.claude/hooks/${name}.mjs`);
+    }
+    if (Object.keys(spec.harness.hooks).length > 0) {
+      const logPath = path5.join(claudeDir, "hooks", "intent-log.jsonl");
+      await writeFile(logPath, "");
+      written.push(".claude/hooks/intent-log.jsonl");
+    }
+  }
   return written;
 }
 function summarizeSpec(spec, registry) {
@@ -3943,11 +4377,17 @@ var EVAL_TEMPLATES = {
     name: "Rule Compliance",
     description: "Does the agent follow all project rules without violations?",
     bestFor: ["feature-development", "backend", "maintenance", "architecture"]
+  },
+  "intent-routing": {
+    id: "intent-routing",
+    name: "Intent Routing",
+    description: "Test that natural language prompts route to the correct workflow command via intent hooks",
+    bestFor: ["feature-development", "full-stack", "api-building"]
   }
 };
 function selectTemplatesForWorkflow(workflowType) {
   const mapping = {
-    "feature-development": ["add-feature", "test-writing", "convention-adherence", "workflow-compliance"],
+    "feature-development": ["add-feature", "test-writing", "convention-adherence", "workflow-compliance", "intent-routing"],
     "api-building": ["add-feature", "fix-bug", "test-writing", "convention-adherence"],
     "full-stack": ["add-feature", "fix-bug", "test-writing", "convention-adherence"],
     "maintenance": ["fix-bug", "refactor", "test-writing", "rule-compliance"],