kairn-cli 1.1.0 → 1.3.0

package/dist/cli.js

@@ -217,6 +217,37 @@ You must output a JSON object matching the EnvironmentSpec schema.
 - **Concise CLAUDE.md.** Under 100 lines. No generic text like "be helpful." Include build/test commands, reference docs/ and skills/.
 - **Security by default.** Always include deny rules for destructive commands and secret file access.
 
+## CLAUDE.md Template (mandatory structure)
+
+The \`claude_md\` field MUST follow this exact structure (max 100 lines):
+
+\`\`\`
+# {Project Name}
+
+## Purpose
+{one-line description}
+
+## Tech Stack
+{bullet list of frameworks/languages}
+
+## Commands
+{concrete build/test/lint/dev commands}
+
+## Architecture
+{brief folder structure, max 10 lines}
+
+## Conventions
+{3-5 specific coding rules}
+
+## Key Commands
+{list /project: commands with descriptions}
+
+## Output
+{where results go, key files}
+\`\`\`
+
+Do not add generic filler. Every line must be specific to the user's workflow.
+
 ## What You Must Always Include
 
 1. A concise, workflow-specific \`claude_md\` (the CLAUDE.md content)
@@ -228,6 +259,95 @@ You must output a JSON object matching the EnvironmentSpec schema.
 7. A \`rules/continuity.md\` rule encouraging updates to DECISIONS.md and LEARNINGS.md
 8. A \`rules/security.md\` rule with essential security instructions
 9. settings.json with deny rules for \`rm -rf\`, \`curl|sh\`, reading \`.env\` and \`secrets/\`
+10. A \`/project:status\` command for code projects (uses ! for live git/test output)
+11. A \`/project:fix\` command for code projects (uses $ARGUMENTS for issue number)
+
+## Shell-Integrated Commands
+
+Commands that reference live project state should use Claude Code's \`!\` prefix for shell output:
+
+\`\`\`markdown
+# Example: .claude/commands/review.md
+Review the staged changes for quality and security:
+
+!git diff --staged
+
+Run tests and check for failures:
+
+!npm test 2>&1 | tail -20
+
+Focus on: security, error handling, test coverage.
+\`\`\`
+
+Use \`!\` when a command needs: git status, test results, build output, or file listings.
+
+## Path-Scoped Rules
+
+For code projects with multiple domains (API, frontend, tests), generate path-scoped rules using YAML frontmatter:
+
+\`\`\`markdown
+# Example: rules/api.md
+---
+paths:
+  - "src/api/**"
+  - "src/routes/**"
+---
+- All handlers return { data, error } shape
+- Use Zod for request validation
+- Log errors with request ID context
+\`\`\`
+
+\`\`\`markdown
+# Example: rules/testing.md
+---
+paths:
+  - "tests/**"
+  - "**/*.test.*"
+  - "**/*.spec.*"
+---
+- Use AAA pattern: Arrange-Act-Assert
+- One assertion per test when possible
+- Mock external dependencies, never real APIs
+\`\`\`
+
+Keep \`security.md\` and \`continuity.md\` as unconditional (no paths frontmatter).
+Only generate scoped rules when the workflow involves multiple code domains.
+
+## Hooks
+
+Generate hooks in settings.json based on project type:
+
+**All code projects** \u2014 block destructive commands:
+\`\`\`json
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "Bash",
+      "hooks": [{
+        "type": "command",
+        "command": "CMD=$(cat | jq -r '.tool_input.command // empty') && echo \\"$CMD\\" | grep -qiE 'rm\\\\s+-rf\\\\s+/|DROP\\\\s+TABLE|curl.*\\\\|\\\\s*sh' && echo 'Blocked destructive command' >&2 && exit 2 || true"
+      }]
+    }]
+  }
+}
+\`\`\`
+
+**Projects with Prettier/ESLint/Black** \u2014 auto-format on write:
+\`\`\`json
+{
+  "hooks": {
+    "PostToolUse": [{
+      "matcher": "Edit|Write",
+      "hooks": [{
+        "type": "command",
+        "command": "FILE=$(cat | jq -r '.tool_input.file_path // empty') && [ -n \\"$FILE\\" ] && npx prettier --write \\"$FILE\\" 2>/dev/null || true"
+      }]
+    }]
+  }
+}
+\`\`\`
+
+Merge hooks into the \`settings\` object alongside permissions. Choose the formatter hook based on detected dependencies (Prettier \u2192 prettier, ESLint \u2192 eslint, Black \u2192 black).
 
 ## Tool Selection Rules
 
@@ -244,7 +364,13 @@ You must output a JSON object matching the EnvironmentSpec schema.
 - \`/project:review\` command (review changes)
 - \`/project:test\` command (run and fix tests)
 - \`/project:commit\` command (conventional commits)
-- A TDD skill if testing is relevant
+- \`/project:status\` command (live git status, recent commits, TODO overview using ! prefix)
+- \`/project:fix\` command (takes $ARGUMENTS as issue number, plans fix, implements, tests, commits)
+- A TDD skill using the 3-phase isolation pattern (RED \u2192 GREEN \u2192 REFACTOR):
+  - RED: Write failing test only. Verify it FAILS.
+  - GREEN: Write MINIMUM code to pass. Nothing extra.
+  - REFACTOR: Improve while keeping tests green.
+  Rules: never write tests and implementation in same step, AAA pattern, one assertion per test.
 - A reviewer agent (read-only, Sonnet model)
 
 ## For Research Projects, Additionally Include
@@ -284,7 +410,9 @@ Return ONLY valid JSON matching this structure:
     },
     "commands": {
       "help": "markdown content for /project:help",
-      "tasks": "markdown content for /project:tasks"
+      "tasks": "markdown content for /project:tasks",
+      "status": "Show project status:\\n\\n!git status --short\\n\\n!git log --oneline -5\\n\\nRead TODO.md and summarize progress.",
+      "fix": "Fix issue #$ARGUMENTS:\\n\\n1. Read the issue and understand the problem\\n2. Plan the fix\\n3. Implement the fix\\n4. Run tests:\\n\\n!npm test 2>&1 | tail -20\\n\\n5. Commit with: fix: resolve #$ARGUMENTS"
     },
     "rules": {
       "continuity": "markdown content for continuity rule",
@@ -524,11 +652,23 @@ async function writeEnvironment(spec, targetDir) {
 }
 function summarizeSpec(spec, registry) {
   const pluginCommands = [];
+  const envSetup = [];
   for (const selected of spec.tools) {
     const tool = registry.find((t) => t.id === selected.tool_id);
-    if (tool?.install.plugin_command) {
+    if (!tool) continue;
+    if (tool.install.plugin_command) {
       pluginCommands.push(tool.install.plugin_command);
     }
+    if (tool.env_vars) {
+      for (const ev of tool.env_vars) {
+        envSetup.push({
+          toolName: tool.name,
+          envVar: ev.name,
+          description: ev.description,
+          signupUrl: tool.signup_url
+        });
+      }
+    }
   }
   return {
     toolCount: spec.tools.length,
@@ -536,7 +676,8 @@ function summarizeSpec(spec, registry) {
     ruleCount: Object.keys(spec.harness.rules || {}).length,
     skillCount: Object.keys(spec.harness.skills || {}).length,
     agentCount: Object.keys(spec.harness.agents || {}).length,
-    pluginCommands
+    pluginCommands,
+    envSetup
   };
 }
 
@@ -629,8 +770,22 @@ var describeCommand = new Command2("describe").description("Describe your workfl
   for (const file of written) {
     console.log(chalk2.dim(`    ${file}`));
   }
+  if (summary.envSetup.length > 0) {
+    console.log(chalk2.yellow("\n  API keys needed (set these environment variables):\n"));
+    const seen = /* @__PURE__ */ new Set();
+    for (const env of summary.envSetup) {
+      if (seen.has(env.envVar)) continue;
+      seen.add(env.envVar);
+      console.log(chalk2.bold(`    export ${env.envVar}="your-key-here"`));
+      console.log(chalk2.dim(`      ${env.description}`));
+      if (env.signupUrl) {
+        console.log(chalk2.dim(`      Get one at: ${env.signupUrl}`));
+      }
+      console.log("");
+    }
+  }
   if (summary.pluginCommands.length > 0) {
-    console.log(chalk2.yellow("\n  Install plugins by running these in Claude Code:"));
+    console.log(chalk2.yellow("  Install plugins by running these in Claude Code:"));
     for (const cmd of summary.pluginCommands) {
       console.log(chalk2.bold(`    ${cmd}`));
     }
@@ -1053,6 +1208,10 @@ ${profile.existingClaudeMd}`);
     parts.push("- Are security rules present?");
     parts.push("- Is there a continuity rule for session memory?");
     parts.push("- Are there unnecessary MCP servers adding context bloat?");
+    parts.push("- Are hooks configured in settings.json for destructive command blocking?");
+    parts.push("- Are there path-scoped rules for different code domains (api, testing, frontend)?");
+    parts.push("- Does the project have a /project:status command with live git output?");
+    parts.push("- Is there a /project:fix command for issue-driven development?");
     if (profile.claudeMdLineCount > 200) {
       parts.push(`- CLAUDE.md is ${profile.claudeMdLineCount} lines \u2014 needs aggressive trimming`);
     }
@@ -1109,6 +1268,9 @@ var optimizeCommand = new Command6("optimize").description("Scan an existing pro
     if (profile.mcpServerCount === 0 && profile.dependencies.length > 0) issues.push("No MCP servers configured");
     if (profile.hasTests && !profile.existingCommands.includes("test")) issues.push("Has tests but no /project:test command");
     if (!profile.existingCommands.includes("tasks")) issues.push("Missing /project:tasks command");
+    if (!profile.existingSettings?.hooks) issues.push("No hooks configured \u2014 missing destructive command blocking");
+    const scopedRules = profile.existingRules.filter((r) => r !== "security" && r !== "continuity");
+    if (profile.hasSrc && scopedRules.length === 0) issues.push("No path-scoped rules \u2014 consider adding api.md, testing.md, or frontend.md rules");
     if (issues.length > 0) {
       console.log(chalk6.yellow("\n  Issues Found:\n"));
       for (const issue of issues) {
@@ -1188,8 +1350,22 @@ var optimizeCommand = new Command6("optimize").description("Scan an existing pro
   for (const file of written) {
     console.log(chalk6.dim(`    ${file}`));
   }
+  if (summary.envSetup.length > 0) {
+    console.log(chalk6.yellow("\n  API keys needed (set these environment variables):\n"));
+    const seen = /* @__PURE__ */ new Set();
+    for (const env of summary.envSetup) {
+      if (seen.has(env.envVar)) continue;
+      seen.add(env.envVar);
+      console.log(chalk6.bold(`    export ${env.envVar}="your-key-here"`));
+      console.log(chalk6.dim(`      ${env.description}`));
+      if (env.signupUrl) {
+        console.log(chalk6.dim(`      Get one at: ${env.signupUrl}`));
+      }
+      console.log("");
+    }
+  }
   if (summary.pluginCommands.length > 0) {
-    console.log(chalk6.yellow("\n  Install plugins by running these in Claude Code:"));
+    console.log(chalk6.yellow("  Install plugins by running these in Claude Code:"));
     for (const cmd of summary.pluginCommands) {
       console.log(chalk6.bold(`    ${cmd}`));
     }
@@ -1203,7 +1379,7 @@ var optimizeCommand = new Command6("optimize").description("Scan an existing pro
 var program = new Command7();
 program.name("kairn").description(
   "Compile natural language intent into optimized Claude Code environments"
-).version("1.0.0");
+).version("1.3.0");
 program.addCommand(initCommand);
 program.addCommand(describeCommand);
 program.addCommand(optimizeCommand);