kairn-cli 1.11.0 → 1.13.0

package/dist/cli.js

@@ -256,6 +256,113 @@ var ui = {
 `);
   }
 };
+function formatTime(seconds) {
+  if (seconds < 60) return `${seconds}s`;
+  const min = Math.floor(seconds / 60);
+  const sec = seconds % 60;
+  return sec > 0 ? `${min}m ${sec}s` : `${min} min`;
+}
+function estimateTime(model, intent) {
+  const wordCount = intent.split(/\s+/).length;
+  const isComplex = wordCount > 40;
+  const perPass = {
+    "haiku": 5,
+    "sonnet": 20,
+    "opus": 60,
+    "gpt-4.1-mini": 10,
+    "gpt-4.1": 25,
+    "gpt-5": 15,
+    "o4-mini": 12,
+    "gemini-2.5-flash": 8,
+    "gemini-3-flash": 8,
+    "gemini-2.5-pro": 30,
+    "gemini-3.1-pro": 30,
+    "grok-4.1-fast": 10,
+    "grok-4.20": 25,
+    "deepseek": 15,
+    "mistral-large": 20,
+    "codestral": 15,
+    "mistral-small": 10,
+    "llama": 10,
+    "qwen": 10
+  };
+  const basePerPass = Object.entries(perPass).find(([k]) => model.toLowerCase().includes(k))?.[1] ?? 20;
+  const totalBase = basePerPass * 2;
+  if (isComplex) {
+    const low = Math.floor(totalBase * 1.5);
+    const high = Math.floor(totalBase * 4);
+    return `~${formatTime(low)}-${formatTime(high)} (complex workflow)`;
+  }
+  return `~${formatTime(totalBase)}`;
+}
+function createProgressRenderer() {
+  const lines = [];
+  let intervalId = null;
+  let currentPhase = "";
+  let phaseStart = Date.now();
+  let lineCount = 0;
+  function render() {
+    if (lineCount > 0) {
+      process.stdout.write(`\x1B[${lineCount}A`);
+    }
+    for (const line of lines) {
+      process.stdout.write("\x1B[2K" + line + "\n");
+    }
+    lineCount = lines.length;
+  }
+  function updateElapsed() {
+    if (!currentPhase) return;
+    const elapsed = Math.floor((Date.now() - phaseStart) / 1e3);
+    const lastIdx = lines.length - 1;
+    if (lastIdx >= 0) {
+      lines[lastIdx] = lines[lastIdx].replace(/\[\d+s\]/, `[${elapsed}s]`);
+      render();
+    }
+  }
+  return {
+    update(progress) {
+      if (progress.status === "running") {
+        currentPhase = progress.phase;
+        phaseStart = Date.now();
+        lines.push(`  ${warmStone("\u25D0")} ${progress.message} ${chalk.dim("[0s]")}`);
+        if (!intervalId) {
+          intervalId = setInterval(updateElapsed, 1e3);
+        }
+      } else if (progress.status === "success") {
+        const lastIdx = lines.length - 1;
+        const elapsed = progress.elapsed != null ? ` ${chalk.dim("\u2014")} ${chalk.dim(Math.floor(progress.elapsed) + "s")}` : "";
+        const detail = progress.detail ? ` ${chalk.dim("(" + progress.detail + ")")}` : "";
+        if (lastIdx >= 0) {
+          lines[lastIdx] = `  ${chalk.green("\u2714")} ${progress.message}${detail}${elapsed}`;
+        }
+        currentPhase = "";
+      } else if (progress.status === "warning") {
+        const lastIdx = lines.length - 1;
+        if (lastIdx >= 0) {
+          lines[lastIdx] = `  ${chalk.yellow("\u26A0")} ${progress.message}`;
+        }
+        currentPhase = progress.phase;
+        phaseStart = Date.now();
+        lines.push(`  ${warmStone("\u25D0")} Retrying in concise mode... ${chalk.dim("[0s]")}`);
+      }
+      render();
+    },
+    finish() {
+      if (intervalId) clearInterval(intervalId);
+      currentPhase = "";
+      render();
+    },
+    fail(err) {
+      if (intervalId) clearInterval(intervalId);
+      currentPhase = "";
+      const lastIdx = lines.length - 1;
+      if (lastIdx >= 0) {
+        lines[lastIdx] = `  ${chalk.red("\u2716")} Compilation failed`;
+      }
+      render();
+    }
+  };
+}
 
 // src/logo.ts
 import chalk2 from "chalk";
@@ -450,7 +557,6 @@ var initCommand = new Command("init").description("Set up Kairn with your API ke
 import { Command as Command2 } from "commander";
 import { input as input2, confirm, select as select2 } from "@inquirer/prompts";
 import chalk5 from "chalk";
-import ora from "ora";
 
 // src/compiler/compile.ts
 import fs4 from "fs/promises";
@@ -600,6 +706,16 @@ Use subagents for deep investigation to keep main context clean.
 - Do not create abstractions for one-time operations
 - Complete the task fully \u2014 don't gold-plate, but don't leave it half-done
 - Prefer editing existing files over creating new ones
+
+## First Turn Protocol
+
+At the start of every session, before doing ANY work:
+1. Run \`pwd && ls -la && git status --short\` to orient yourself
+2. Check relevant runtimes (e.g. \`node --version\`, \`python3 --version\` \u2014 pick what fits this project)
+3. Read any task-tracking files (docs/SPRINT.md, docs/DECISIONS.md)
+4. Summarize what you see in 2-3 lines, then proceed
+
+This saves 2-5 exploratory turns. Never ask "what files are here?" \u2014 look first.
 \`\`\`
 
 Do not add generic filler. Every line must be specific to the user's workflow.
@@ -621,6 +737,7 @@ Do not add generic filler. Every line must be specific to the user's workflow.
 13. A "Debugging" section in CLAUDE.md (2 lines: paste raw errors, use subagents)
 14. A "Git Workflow" section in CLAUDE.md (3 rules: small commits, conventional format, <200 lines PR)
 15. "Engineering Standards", "Tool Usage Policy", and "Code Philosophy" sections in CLAUDE.md
+16. A "First Turn Protocol" section in CLAUDE.md (orient before working: pwd, ls, git status, check relevant runtimes, read task files)
 
 ## Shell-Integrated Commands
 
@@ -896,6 +1013,16 @@ Use subagents for deep investigation to keep main context clean.
 - Do not create abstractions for one-time operations
 - Complete the task fully \u2014 don't gold-plate, but don't leave it half-done
 - Prefer editing existing files over creating new ones
+
+## First Turn Protocol
+
+At the start of every session, before doing ANY work:
+1. Run \`pwd && ls -la && git status --short\` to orient yourself
+2. Check relevant runtimes (e.g. \`node --version\`, \`python3 --version\` \u2014 pick what fits this project)
+3. Read any task-tracking files (docs/SPRINT.md, docs/DECISIONS.md)
+4. Summarize what you see in 2-3 lines, then proceed
+
+This saves 2-5 exploratory turns. Never ask "what files are here?" \u2014 look first.
 \`\`\`
 
 Do not add generic filler. Every line must be specific to the user's workflow.
@@ -917,6 +1044,7 @@ Do not add generic filler. Every line must be specific to the user's workflow.
 13. A "Debugging" section in CLAUDE.md (2 lines: paste raw errors, use subagents)
 14. A "Git Workflow" section in CLAUDE.md (3 rules: small commits, conventional format, <200 lines PR)
 15. "Engineering Standards", "Tool Usage Policy", and "Code Philosophy" sections in CLAUDE.md
+16. A "First Turn Protocol" section in CLAUDE.md (orient before working: pwd, ls, git status, check relevant runtimes, read task files)
 
 ## Tool Selection Rules
 
@@ -1264,7 +1392,7 @@ function buildMcpConfig(skeleton, registry) {
   }
   return config;
 }
-function validateSpec(spec, onProgress) {
+function validateSpec(spec) {
   const warnings = [];
   if (spec.tools.length > 8) {
     warnings.push(`${spec.tools.length} MCP servers selected (recommended: \u22646)`);
@@ -1278,25 +1406,33 @@ function validateSpec(spec, onProgress) {
   if (spec.harness.skills && Object.keys(spec.harness.skills).length > 5) {
     warnings.push(`${Object.keys(spec.harness.skills).length} skills (recommended: \u22643)`);
   }
-  for (const warning of warnings) {
-    onProgress?.(`\u26A0 ${warning}`);
-  }
+  return warnings;
 }
 async function compile(intent, onProgress) {
+  const startTime = Date.now();
   const config = await loadConfig();
   if (!config) {
     throw new Error("No config found. Run `kairn init` first.");
   }
-  onProgress?.("Loading tool registry...");
+  onProgress?.({ phase: "registry", status: "running", message: "Loading tool registry..." });
   const registry = await loadRegistry();
-  onProgress?.("Analyzing workflow...");
+  onProgress?.({ phase: "registry", status: "success", message: "Tool registry loaded", detail: `${registry.length} tools` });
+  onProgress?.({ phase: "pass1", status: "running", message: "Pass 1: Analyzing workflow & selecting tools..." });
   const skeletonMsg = buildSkeletonMessage(intent, registry);
   const skeletonText = await callLLM(config, skeletonMsg, {
     maxTokens: 2048,
     systemPrompt: SKELETON_PROMPT
   });
   const skeleton = parseSkeletonResponse(skeletonText);
-  onProgress?.("Generating environment...");
+  const toolNames = skeleton.tools.map((t) => t.tool_id).join(", ");
+  onProgress?.({
+    phase: "pass1",
+    status: "success",
+    message: `Pass 1: Selected ${skeleton.tools.length} tools`,
+    detail: toolNames,
+    elapsed: (Date.now() - startTime) / 1e3
+  });
+  onProgress?.({ phase: "pass2", status: "running", message: "Pass 2: Generating CLAUDE.md, commands, agents..." });
   const harnessMsg = buildHarnessMessage(intent, skeleton);
   let harness;
   try {
@@ -1306,7 +1442,7 @@ async function compile(intent, onProgress) {
     });
     harness = parseHarnessResponse(harnessText);
   } catch {
-    onProgress?.("Retrying with concise mode...");
+    onProgress?.({ phase: "pass2-retry", status: "warning", message: "Pass 2: Response too large, retrying in concise mode..." });
     const retryMsg = buildHarnessMessage(intent, skeleton, true);
     const retryText = await callLLM(config, retryMsg, {
       maxTokens: 8192,
@@ -1314,9 +1450,19 @@ async function compile(intent, onProgress) {
     });
     harness = parseHarnessResponse(retryText);
   }
-  onProgress?.("Configuring tools...");
+  const cmdCount = Object.keys(harness.commands).length;
+  const agentCount = Object.keys(harness.agents ?? {}).length;
+  const ruleCount = Object.keys(harness.rules).length;
+  onProgress?.({
+    phase: "pass2",
+    status: "success",
+    message: `Pass 2: Generated ${cmdCount} commands, ${agentCount} agents, ${ruleCount} rules`,
+    elapsed: (Date.now() - startTime) / 1e3
+  });
+  onProgress?.({ phase: "pass3", status: "running", message: "Pass 3: Configuring MCP servers & settings..." });
   const settings = buildSettings(skeleton, registry);
   const mcpConfig = buildMcpConfig(skeleton, registry);
+  onProgress?.({ phase: "pass3", status: "success", message: "Pass 3: Configured MCP servers & settings" });
   const spec = {
     id: `env_${crypto.randomUUID()}`,
     intent,
@@ -1336,7 +1482,12 @@ async function compile(intent, onProgress) {
       docs: harness.docs
     }
   };
-  validateSpec(spec, onProgress);
+  const warnings = validateSpec(spec);
+  for (const w of warnings) {
+    onProgress?.({ phase: "done", status: "warning", message: `\u26A0 ${w}` });
+  }
+  const totalElapsed = ((Date.now() - startTime) / 1e3).toFixed(0);
+  onProgress?.({ phase: "done", status: "success", message: `Environment compiled in ${totalElapsed}s`, elapsed: (Date.now() - startTime) / 1e3 });
   await ensureDirs();
   const envPath = path4.join(getEnvsDir(), `${spec.id}.json`);
   await fs4.writeFile(envPath, JSON.stringify(spec, null, 2), "utf-8");
@@ -1448,6 +1599,61 @@ ${agentList}
 Type \`/project:help\` in Claude Code for a quick reference.
 `;
 }
+var BOOTSTRAP_COMMAND = `# Environment Snapshot
+
+Run this command at the start of any session to gather runtime context.
+This saves 2-5 exploratory turns.
+
+1. Run the following compound command and read the output:
+   \`\`\`bash
+   echo '=== WORKING DIRECTORY ===' && pwd && \\
+   echo '=== PROJECT FILES ===' && ls -la && \\
+   echo '=== GIT STATUS ===' && (git status --short 2>/dev/null || echo 'not a git repo') && \\
+   echo '=== LANGUAGES ===' && \\
+   (node --version 2>&1 || true) && \\
+   (python3 --version 2>&1 || true) && \\
+   (go version 2>&1 || true) && \\
+   (rustc --version 2>&1 || true) && \\
+   echo '=== PACKAGE MANAGERS ===' && \\
+   (npm --version 2>&1 && echo "npm $(npm --version 2>&1)" || true) && \\
+   (pip3 --version 2>&1 || true) && \\
+   (cargo --version 2>&1 || true) && \\
+   echo '=== ENVIRONMENT ===' && \\
+   (cat .env 2>/dev/null | sed 's/=.*/=***/' || echo 'no .env file')
+   \`\`\`
+
+2. Summarize the environment in 3-4 lines:
+   - Runtime: [languages + versions found]
+   - Project: [framework, key deps, file count]
+   - State: [git branch, clean/dirty, .env present]
+
+3. Keep this summary in context for the rest of the session.`;
+function buildBootstrapHookCommand(spec) {
+  const checks = [
+    "echo '--- Environment Snapshot ---'",
+    "pwd",
+    "ls -la --color=never | head -20",
+    "echo '---'",
+    "git status --short 2>/dev/null || true",
+    "echo '---'"
+  ];
+  const md = (spec.harness.claude_md ?? "").toLowerCase();
+  if (md.includes("node") || md.includes("typescript") || md.includes("javascript") || md.includes("react") || md.includes("next")) {
+    checks.push("node --version 2>&1 || true");
+    checks.push("cat package.json 2>/dev/null | head -5 || true");
+  }
+  if (md.includes("python") || md.includes("django") || md.includes("flask") || md.includes("fastapi")) {
+    checks.push("python3 --version 2>&1 || true");
+  }
+  if (md.includes("rust") || md.includes("cargo")) {
+    checks.push("rustc --version 2>&1 || true");
+  }
+  if (md.includes("go ") || md.includes("golang")) {
+    checks.push("go version 2>&1 || true");
+  }
+  checks.push("cat .env 2>/dev/null | sed 's/=.*/=***/' || true");
+  return checks.join(" && ");
+}
 var LOOP_COMMAND_CODE = `# Development Loop
 
 Run an assisted development cycle for the next feature.
@@ -1621,6 +1827,9 @@ function applyAutonomyLevel(spec) {
     settings.hooks = hooks;
   }
   if (level >= 2) {
+    if (!("bootstrap" in commands)) {
+      commands.bootstrap = BOOTSTRAP_COMMAND;
+    }
     if (!("loop" in commands)) {
       commands.loop = isResearchProject(spec) ? LOOP_COMMAND_RESEARCH : LOOP_COMMAND_CODE;
     }
@@ -1632,6 +1841,18 @@ function applyAutonomyLevel(spec) {
     if (!("auto" in commands)) {
       commands.auto = AUTO_COMMAND;
     }
+    const hooks = settings.hooks ?? {};
+    const sessionStart = hooks.SessionStart ?? [];
+    const bootstrapHook = {
+      matcher: "",
+      hooks: [{
+        type: "command",
+        command: buildBootstrapHookCommand(spec)
+      }]
+    };
+    sessionStart.push(bootstrapHook);
+    hooks.SessionStart = sessionStart;
+    settings.hooks = hooks;
   }
   if (level >= 4) {
     if (!("autopilot" in commands)) {
@@ -2112,16 +2333,19 @@ ${clarificationLines}`;
 Autonomy level: ${autonomyLevel} (${autonomyLabel(autonomyLevel)})`;
   }
   console.log(ui.section("Compilation"));
-  const spinner = ora({ text: "Loading tool registry...", indent: 2 }).start();
+  const estimate = estimateTime(config.model, finalIntent);
+  console.log(chalk5.dim(`  Estimated time: ${estimate} (${config.model})`));
+  console.log("");
+  const renderer = createProgressRenderer();
   let spec;
   try {
-    spec = await compile(finalIntent, (msg) => {
-      spinner.text = msg;
+    spec = await compile(finalIntent, (progress) => {
+      renderer.update(progress);
     });
     spec.autonomy_level = autonomyLevel;
-    spinner.succeed("Environment compiled");
+    renderer.finish();
   } catch (err) {
-    spinner.fail("Compilation failed");
+    renderer.fail(err);
     const msg = err instanceof Error ? err.message : String(err);
     console.log(chalk5.red(`
   ${msg}
@@ -2366,7 +2590,7 @@ var updateRegistryCommand = new Command5("update-registry").description("Fetch t
 import { Command as Command6 } from "commander";
 import { confirm as confirm2 } from "@inquirer/prompts";
 import chalk9 from "chalk";
-import ora2 from "ora";
+import ora from "ora";
 import fs12 from "fs/promises";
 import path12 from "path";
 
@@ -2691,7 +2915,7 @@ var optimizeCommand = new Command6("optimize").description("Scan an existing pro
   }
   const targetDir = process.cwd();
   console.log(ui.section("Project Scan"));
-  const scanSpinner = ora2({ text: "Scanning project...", indent: 2 }).start();
+  const scanSpinner = ora({ text: "Scanning project...", indent: 2 }).start();
   const profile = await scanProject(targetDir);
   scanSpinner.stop();
   if (profile.language) console.log(ui.kv("Language:", profile.language));
@@ -2760,10 +2984,10 @@ var optimizeCommand = new Command6("optimize").description("Scan an existing pro
   }
   const intent = buildOptimizeIntent(profile);
   let spec;
-  const spinner = ora2({ text: "Compiling optimized environment...", indent: 2 }).start();
+  const spinner = ora({ text: "Compiling optimized environment...", indent: 2 }).start();
   try {
-    spec = await compile(intent, (msg) => {
-      spinner.text = msg;
+    spec = await compile(intent, (progress) => {
+      spinner.text = progress.message;
     });
     spinner.succeed("Environment compiled");
   } catch (err) {