@0xdevabir/enhance 0.1.0 → 0.1.1

package/README.md

@@ -23,12 +23,31 @@ Instead of sending `build login page` directly to Claude/Codex/OpenCode:
 - Node.js 20+
 - At least one AI coding tool: [Claude Code](https://claude.ai/code), [OpenCode](https://opencode.ai), or [Codex CLI](https://github.com/openai/codex)
 
-### Step 1 — Install globally
+### Option A — No install (npx)
+
+```bash
+npx @0xdevabir/enhance@latest "build a login page"
+```
+
+Runs directly without installing anything globally. Great for trying it out or if you hit permission errors.
+
+### Option B — Global install
 
 ```bash
 npm install -g @0xdevabir/enhance
 ```
 
+> **Permission error (EACCES)?** Fix npm's global prefix first, then retry:
+> ```bash
+> mkdir -p ~/.npm-global
+> npm config set prefix '~/.npm-global'
+> echo 'export PATH=$HOME/.npm-global/bin:$PATH' >> ~/.zshrc
+> source ~/.zshrc
+> npm install -g @0xdevabir/enhance
+> ```
+
+### Step 2 — Run setup
+
 ### Step 2 — Run setup
 
 ```bash

package/dist/index.js

@@ -2,7 +2,9 @@
 
 // src/cli/index.ts
 import { Command } from "commander";
+import { createInterface } from "readline";
 import ora from "ora";
+import chalk3 from "chalk";
 
 // src/cli/logger.ts
 import chalk from "chalk";
@@ -28,7 +30,7 @@ import { cosmiconfig } from "cosmiconfig";
 var DEFAULT_CONFIG = {
   provider: "claude",
   model: "claude-sonnet-4-6",
-  maxContextTokens: 3e3
+  maxContextTokens: 8e3
 };
 async function loadConfig(root) {
   const explorer = cosmiconfig("enhance", {
@@ -243,69 +245,178 @@ async function setCached(root, result) {
 
 // src/analyzer/intent.ts
 var ACTION_KEYWORDS = {
-  create: ["build", "create", "make", "add", "implement", "write", "generate", "scaffold", "set up", "setup", "new"],
   fix: ["fix", "debug", "resolve", "repair", "broken", "failing", "crash", "error", "bug", "issue", "problem"],
-  refactor: ["refactor", "clean", "improve", "optimize", "restructure", "simplify", "rewrite", "reorganize"],
-  explain: ["explain", "describe", "what", "how does", "why", "show me", "understand", "walkthrough"],
-  add: ["add", "integrate", "install", "include", "plug in", "connect"],
-  delete: ["delete", "remove", "drop", "clean up", "uninstall", "get rid"],
+  create: ["create", "build", "make", "generate", "scaffold", "new", "write"],
+  add: ["add", "implement", "integrate", "include", "append", "enable"],
+  refactor: ["refactor", "restructure", "reorganize", "clean up", "cleanup", "simplify", "rewrite", "move", "extract"],
+  explain: ["explain", "describe", "how does", "what is", "why does", "understand", "document", "walkthrough"],
+  delete: ["delete", "remove", "drop", "destroy", "uninstall", "clean"],
   unknown: []
 };
 var ENTITY_KEYWORDS = {
   page: ["page", "route", "view", "screen", "layout"],
-  component: ["component", "widget", "element", "button", "form", "modal", "card", "dialog", "input", "dropdown", "table", "list", "nav", "navbar", "sidebar", "header", "footer", "menu"],
+  component: ["component", "widget", "card", "modal", "dialog", "dropdown", "button", "input", "form"],
   api: ["api", "endpoint", "route handler", "server action", "action", "mutation", "query", "rest", "graphql"],
-  hook: ["hook", "usecallback", "useeffect", "usestate", "usememo", "custom hook"],
-  util: ["util", "utility", "helper", "function", "service", "lib", "library"],
-  config: ["config", "configuration", "setting", "env", "environment"],
-  style: ["style", "css", "theme", "design", "color", "spacing", "typography"],
+  hook: ["hook", "use", "custom hook"],
+  util: ["util", "helper", "function", "service", "lib", "library", "module"],
+  config: ["config", "configuration", "settings", "env", "environment"],
+  style: ["style", "css", "theme", "color", "design", "ui", "ux", "animation"],
   unknown: []
 };
 var FEATURE_KEYWORDS = {
-  auth: ["auth", "authentication", "login", "logout", "signup", "sign up", "sign in", "register", "password", "session", "oauth", "jwt", "credentials"],
-  dashboard: ["dashboard", "admin", "panel", "overview", "analytics", "stats", "metrics"],
+  auth: ["auth", "login", "logout", "signup", "register", "session", "jwt", "token", "oauth", "credential", "password", "permission", "role"],
+  dashboard: ["dashboard", "admin", "overview", "analytics", "metrics", "stats"],
   payment: ["payment", "checkout", "billing", "stripe", "invoice", "subscription", "pricing"],
-  user: ["user", "profile", "account", "avatar", "settings", "preferences"],
-  search: ["search", "filter", "query", "find", "lookup"],
-  upload: ["upload", "file", "image", "media", "attachment", "storage"],
-  notification: ["notification", "alert", "email", "push", "toast", "banner"],
-  navigation: ["nav", "navbar", "navigation", "menu", "breadcrumb", "sidebar", "header"],
-  table: ["table", "grid", "list", "data table", "datagrid"],
-  form: ["form", "input", "field", "validation", "submit"],
-  chart: ["chart", "graph", "visualization", "plot", "diagram"]
+  user: ["user", "profile", "account", "avatar", "member"],
+  upload: ["upload", "file", "image", "storage", "media", "s3", "cdn"],
+  notification: ["notification", "alert", "email", "toast", "push", "sms"],
+  navigation: ["nav", "navbar", "sidebar", "header", "menu", "breadcrumb"],
+  table: ["table", "grid", "list", "pagination", "sort", "filter"],
+  form: ["form", "field", "input", "validation", "submit"],
+  search: ["search", "filter", "query", "autocomplete"]
 };
+var SYSTEM_SCOPE_SIGNALS = [
+  "entire",
+  "whole",
+  "all",
+  "system",
+  "everywhere",
+  "global",
+  "across",
+  "throughout",
+  "full",
+  "complete",
+  "migrate",
+  "overhaul"
+];
+var SIMPLE_SCOPE_SIGNALS = [
+  "this file",
+  "this component",
+  "this function",
+  "line",
+  "typo",
+  "typos",
+  "small",
+  "quick",
+  "minor",
+  "just change",
+  "rename"
+];
 function analyzeIntent(rawPrompt) {
   const lower = rawPrompt.toLowerCase();
+  const words = lower.split(/\s+/);
   let action = "unknown";
+  let actionMatchCount = 0;
   for (const [act, keywords] of Object.entries(ACTION_KEYWORDS)) {
     if (act === "unknown") continue;
-    if (keywords.some((k) => lower.includes(k))) {
+    const matches = keywords.filter((k) => lower.includes(k)).length;
+    if (matches > actionMatchCount) {
       action = act;
-      break;
+      actionMatchCount = matches;
     }
   }
   let entity = "unknown";
+  let entityMatchCount = 0;
   for (const [ent, keywords] of Object.entries(ENTITY_KEYWORDS)) {
     if (ent === "unknown") continue;
-    if (keywords.some((k) => lower.includes(k))) {
+    const matches = keywords.filter((k) => lower.includes(k)).length;
+    if (matches > entityMatchCount) {
       entity = ent;
-      break;
+      entityMatchCount = matches;
     }
   }
   let feature = "general";
+  let featureMatchCount = 0;
   for (const [feat, keywords] of Object.entries(FEATURE_KEYWORDS)) {
-    if (keywords.some((k) => lower.includes(k))) {
+    const matches = keywords.filter((k) => lower.includes(k)).length;
+    if (matches > featureMatchCount) {
       feature = feat;
-      break;
+      featureMatchCount = matches;
     }
   }
-  return { action, entity, feature, rawPrompt };
+  let scope = "feature";
+  if (SYSTEM_SCOPE_SIGNALS.some((s) => lower.includes(s))) {
+    scope = "system";
+  } else if (SIMPLE_SCOPE_SIGNALS.some((s) => lower.includes(s))) {
+    scope = "file";
+  } else if (action === "fix" && words.length <= 8) {
+    scope = "file";
+  }
+  let complexity = "feature";
+  if (scope === "system" || action === "refactor" && scope !== "file") {
+    complexity = "system";
+  } else if (scope === "file" || action === "fix" || action === "explain") {
+    complexity = "simple";
+  }
+  const totalMatches = actionMatchCount + entityMatchCount + featureMatchCount;
+  const confidence = Math.min(1, totalMatches / Math.max(words.length * 0.3, 1));
+  return { action, entity, feature, scope, complexity, confidence, rawPrompt };
 }
 
 // src/analyzer/context.ts
 import { readFile as readFile4 } from "fs/promises";
-import { join as join6 } from "path";
+import { join as join6, dirname } from "path";
+import { exec } from "child_process";
+import { promisify } from "util";
 import fg from "fast-glob";
+var execAsync = promisify(exec);
+var PROJECT_INSTRUCTION_FILES = [
+  ".claude/CLAUDE.md",
+  "CLAUDE.md",
+  "AGENTS.md",
+  ".cursorrules"
+];
+async function findProjectInstructions(root) {
+  const parts = [];
+  const searchRoots = [root, dirname(root)];
+  for (const searchRoot of searchRoots) {
+    for (const fileName of PROJECT_INSTRUCTION_FILES) {
+      const content = await tryRead(join6(searchRoot, fileName));
+      if (content) {
+        const relPath = fileName;
+        parts.push(`<!-- Source: ${relPath} -->
+${truncateLines(content, 300)}`);
+        break;
+      }
+    }
+  }
+  return parts.join("\n\n");
+}
+async function findGitContext(root, charBudget) {
+  const parts = [];
+  let used = 0;
+  try {
+    const { stdout: diffOutput } = await execAsync("git diff HEAD", { cwd: root, timeout: 5e3 });
+    if (diffOutput.trim()) {
+      const truncated = diffOutput.slice(0, Math.min(3e3, charBudget * 0.4));
+      const section = `// GIT: uncommitted changes
+${truncated}${diffOutput.length > truncated.length ? "\n// ... (diff truncated)" : ""}`;
+      parts.push(section);
+      used += section.length;
+    }
+    if (used < charBudget * 0.6) {
+      const { stdout: logOutput } = await execAsync(
+        "git diff HEAD~3..HEAD --name-only 2>/dev/null || git diff HEAD~1..HEAD --name-only",
+        { cwd: root, timeout: 5e3 }
+      );
+      const changedFiles = logOutput.trim().split("\n").filter(Boolean).slice(0, 8);
+      for (const relPath of changedFiles) {
+        if (used >= charBudget * 0.7) break;
+        const content = await tryRead(join6(root, relPath));
+        if (!content) continue;
+        const snippet = truncateLines(content, 100);
+        const section = `// FILE (recently changed): ${relPath}
+${snippet}`;
+        if (used + section.length < charBudget * 0.7) {
+          parts.push(section);
+          used += section.length;
+        }
+      }
+    }
+  } catch {
+  }
+  return { content: parts.join("\n\n"), charsUsed: used };
+}
 var FEATURE_PATTERNS = {
   auth: ["*auth*", "*login*", "*logout*", "*session*", "*jwt*", "*token*", "*credential*", "*middleware*", "*guard*"],
   dashboard: ["*dashboard*", "*admin*", "*overview*", "*analytics*"],
@@ -326,25 +437,57 @@ var ALWAYS_INCLUDE_PATTERNS = [
   "pages/_app.ts",
   "src/pages/_app.tsx"
 ];
-var MAX_CHARS = 12e3;
-var MAX_FILE_LINES = 250;
-async function findRelevantFiles(root, intent, structure) {
+var DEFAULT_TOKEN_BUDGET = 8e3;
+var CHARS_PER_TOKEN = 4;
+function estimateTokens(text) {
+  return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+function smartTruncate(content, maxTokens) {
+  const maxChars = maxTokens * CHARS_PER_TOKEN;
+  if (content.length <= maxChars) return content;
+  const lines = content.split("\n");
+  const result = [];
+  let chars = 0;
+  for (const line of lines) {
+    if (chars + line.length + 1 > maxChars) {
+      result.push(`// ... (truncated, ${lines.length - result.length} lines omitted)`);
+      break;
+    }
+    result.push(line);
+    chars += line.length + 1;
+  }
+  return result.join("\n");
+}
+async function findRelevantFiles(root, intent, structure, maxTokens = DEFAULT_TOKEN_BUDGET, alwaysInclude = []) {
   const sections = [];
-  let charBudget = MAX_CHARS;
+  let tokenBudget = maxTokens;
+  const { content: gitContent, charsUsed: gitUsed } = await findGitContext(root, Math.floor(tokenBudget * 0.35) * CHARS_PER_TOKEN);
+  tokenBudget -= Math.ceil(gitUsed / CHARS_PER_TOKEN);
+  for (const relPath of alwaysInclude) {
+    if (tokenBudget <= 100) break;
+    const content = await tryRead(join6(root, relPath));
+    if (!content) continue;
+    const allowedTokens = Math.min(estimateTokens(content), Math.floor(tokenBudget * 0.2));
+    const snippet = smartTruncate(content, allowedTokens);
+    const section = `// FILE: ${relPath} (pinned)
+${snippet}`;
+    sections.push(section);
+    tokenBudget -= estimateTokens(section);
+  }
   for (const pattern of ALWAYS_INCLUDE_PATTERNS) {
+    if (tokenBudget <= 100) break;
     const content = await tryRead(join6(root, pattern));
-    if (content) {
-      const snippet = truncateLines(content, MAX_FILE_LINES);
-      const section = `// FILE: ${pattern}
+    if (!content) continue;
+    const fileTokens = estimateTokens(content);
+    const allowedTokens = Math.min(fileTokens, Math.floor(tokenBudget * 0.25));
+    const snippet = smartTruncate(content, allowedTokens);
+    const section = `// FILE: ${pattern}
 ${snippet}`;
-      if (section.length < charBudget) {
-        sections.push(section);
-        charBudget -= section.length;
-      }
-    }
+    sections.push(section);
+    tokenBudget -= estimateTokens(section);
   }
   const featurePatterns = FEATURE_PATTERNS[intent.feature] ?? [];
-  if (featurePatterns.length > 0) {
+  if (featurePatterns.length > 0 && tokenBudget > 200) {
     const searchBase = structure.hasSrcDir ? join6(root, "src") : root;
     const globs = featurePatterns.flatMap((p) => [
       `**/${p}.{ts,tsx,js,jsx}`,
@@ -360,21 +503,38 @@ ${snippet}`;
       });
     } catch {
     }
-    for (const file of files.slice(0, 5)) {
-      if (charBudget <= 0) break;
+    const foundFeatureFiles = [];
+    for (const file of files.slice(0, 6)) {
+      if (tokenBudget <= 100) break;
       const content = await tryRead(file);
       if (!content) continue;
       const relPath = file.replace(root + "/", "");
-      const snippet = truncateLines(content, MAX_FILE_LINES);
+      const allowedTokens = Math.min(estimateTokens(content), Math.floor(tokenBudget * 0.4));
+      const snippet = smartTruncate(content, allowedTokens);
       const section = `// FILE: ${relPath}
 ${snippet}`;
-      if (section.length < charBudget) {
+      sections.push(section);
+      tokenBudget -= estimateTokens(section);
+      foundFeatureFiles.push(file);
+    }
+    if (foundFeatureFiles.length > 0 && tokenBudget > 200) {
+      const importedFiles = await crawlImports(foundFeatureFiles, root);
+      const alreadyIncluded = new Set(foundFeatureFiles.map((f) => f));
+      for (const file of importedFiles.filter((f) => !alreadyIncluded.has(f)).slice(0, 4)) {
+        if (tokenBudget <= 150) break;
+        const content = await tryRead(file);
+        if (!content) continue;
+        const relPath = file.replace(root + "/", "");
+        const allowedTokens = Math.min(estimateTokens(content), Math.floor(tokenBudget * 0.2));
+        const snippet = smartTruncate(content, allowedTokens);
+        const section = `// FILE: ${relPath} (imported)
+${snippet}`;
         sections.push(section);
-        charBudget -= section.length;
+        tokenBudget -= estimateTokens(section);
       }
     }
   }
-  if (["component", "page"].includes(intent.entity) && charBudget > 1e3) {
+  if (["component", "page"].includes(intent.entity) && tokenBudget > 300) {
     const componentDir = structure.hasSrcDir ? join6(root, "src", "components") : join6(root, "components");
     let sampleFiles = [];
     try {
@@ -388,20 +548,44 @@ ${snippet}`;
     } catch {
     }
     for (const file of sampleFiles.slice(0, 2)) {
-      if (charBudget <= 500) break;
+      if (tokenBudget <= 150) break;
       const content = await tryRead(file);
       if (!content) continue;
       const relPath = file.replace(root + "/", "");
-      const snippet = truncateLines(content, 80);
+      const snippet = smartTruncate(content, Math.min(200, tokenBudget - 50));
       const section = `// FILE: ${relPath} (pattern reference)
 ${snippet}`;
-      if (section.length < charBudget) {
-        sections.push(section);
-        charBudget -= section.length;
+      sections.push(section);
+      tokenBudget -= estimateTokens(section);
+    }
+  }
+  return { contextFiles: sections.join("\n\n"), gitContext: gitContent };
+}
+async function crawlImports(filePaths, root) {
+  const IMPORT_RE = /(?:import|from)\s+['"](\.[^'"]+)['"]/g;
+  const TS_EXTS = [".ts", ".tsx", ".js", ".jsx"];
+  const found = /* @__PURE__ */ new Set();
+  for (const filePath of filePaths) {
+    const content = await tryRead(filePath);
+    if (!content) continue;
+    const dir = filePath.replace(/\/[^/]+$/, "");
+    let match;
+    IMPORT_RE.lastIndex = 0;
+    while ((match = IMPORT_RE.exec(content)) !== null) {
+      const importPath = match[1];
+      if (!importPath) continue;
+      const base = join6(dir, importPath);
+      for (const ext of TS_EXTS) {
+        const candidate = base.endsWith(ext) ? base : `${base}${ext}`;
+        if (candidate.includes("node_modules") || candidate.includes(".next")) continue;
+        if (candidate.startsWith(root)) {
+          found.add(candidate);
+          break;
+        }
       }
     }
   }
-  return sections.join("\n\n");
+  return [...found];
 }
 async function tryRead(path) {
   try {
@@ -418,7 +602,7 @@ function truncateLines(content, maxLines) {
 }
 
 // src/enhancer/injectors.ts
-function getInjections(stack, intent) {
+function getInjections(stack, intent, config) {
   const rules = [];
   if (stack.language === "typescript") {
     rules.push("Use TypeScript throughout \u2014 no `any`, prefer `unknown` with type guards");
@@ -487,75 +671,160 @@ function getInjections(stack, intent) {
   rules.push("Match the existing code style and file naming conventions");
   rules.push("List every file you create or modify at the end of your response");
   rules.push("Prefer reusing existing utilities over creating new ones");
+  if (config?.customRules?.length) {
+    rules.unshift(...config.customRules);
+  }
+  if (config?.featureRules?.[intent.feature]?.length) {
+    rules.unshift(...config.featureRules[intent.feature]);
+  }
   return rules;
 }
 
 // src/enhancer/template.ts
 function buildEnhancedPrompt(opts) {
-  const { stack, structure, intent, contextFiles, injections } = opts;
-  const stackLabel = formatStack(stack);
-  const structureLabel = formatStructure(structure);
-  const taskDescription = buildTaskDescription(intent);
-  const requirementsList = injections.map((r) => `- ${r}`).join("\n");
-  const contextSection = contextFiles ? `
-## Existing Code Context
-
-${contextFiles}` : "";
-  return `You are working inside a ${stackLabel} project.
-
-## Project Stack
-${formatStackDetails(stack)}
+  const { intent } = opts;
+  switch (intent.complexity) {
+    case "simple":
+      return buildSimplePrompt(opts);
+    case "system":
+      return buildSystemPrompt(opts);
+    default:
+      return buildFeaturePrompt(opts);
+  }
+}
+function buildSimplePrompt(opts) {
+  const { stack, intent, contextFiles, gitContext, injections, projectInstructions } = opts;
+  const sections = [];
+  if (projectInstructions) {
+    sections.push(`## Project Instructions
 
-## Project Structure
-${structureLabel}
+${projectInstructions}`);
+  }
+  sections.push(`## Context
+**Stack**: ${formatStack(stack)}
+${formatStackDetails(stack)}`);
+  sections.push(`## Task
 
-## Task
-${taskDescription}
+${buildTaskDescription(intent)}`);
+  const rules = [...injections.slice(0, 3), ...injections.slice(-3)];
+  sections.push(`## Requirements
 
-## Requirements
-${requirementsList}
-${contextSection}
+${rules.map((r) => `- ${r}`).join("\n")}`);
+  if (gitContext) {
+    sections.push(`## Recent Changes
 
----
-Complete the task above. Follow every requirement. At the end, list every file you created or modified.`;
-}
-function formatStack(stack) {
-  const primary = stack.frameworks[0] ?? "Node.js";
-  const lang = stack.language === "typescript" ? "TypeScript" : "JavaScript";
-  return `${capitalize(primary)} ${lang}`;
-}
-function formatStackDetails(stack) {
-  const lines = [];
-  lines.push(`- **Language**: ${stack.language === "typescript" ? "TypeScript" : "JavaScript"}`);
-  if (stack.frameworks.length > 0) {
-    lines.push(`- **Frameworks**: ${stack.frameworks.map(capitalize).join(", ")}`);
+${gitContext}`);
   }
-  if (stack.uiLibrary) {
-    lines.push(`- **UI Library**: ${capitalize(stack.uiLibrary)}`);
+  if (contextFiles) {
+    sections.push(`## Code
+
+${contextFiles}`);
   }
-  if (stack.orm) {
-    lines.push(`- **ORM**: ${capitalize(stack.orm)}`);
+  sections.push(`## Expected Output
+
+${buildOutputFormat(intent)}`);
+  return sections.join("\n\n---\n\n");
+}
+function buildFeaturePrompt(opts) {
+  const { stack, structure, intent, contextFiles, gitContext, injections, projectInstructions } = opts;
+  const sections = [];
+  if (projectInstructions) {
+    sections.push(`## Project Instructions
+
+${projectInstructions}`);
   }
-  if (stack.testing) {
-    lines.push(`- **Testing**: ${capitalize(stack.testing)}`);
+  sections.push(`## Project Context
+
+**Stack**: ${formatStack(stack)}
+${formatStackDetails(stack)}
+
+**Structure**: ${formatStructure(structure)}`);
+  sections.push(`## Task
+
+${buildTaskDescription(intent)}`);
+  const specific = injections.slice(0, -3);
+  const universal = injections.slice(-3);
+  const requirementLines = [
+    ...specific.map((r) => `- ${r}`),
+    ...specific.length > 0 ? ["", "**Always:**"] : ["**Always:**"],
+    ...universal.map((r) => `- ${r}`)
+  ].join("\n");
+  sections.push(`## Requirements
+
+${requirementLines}`);
+  if (gitContext) {
+    sections.push(`## Recent Changes
+
+${gitContext}`);
   }
-  if (stack.nextRouterType) {
-    lines.push(`- **Next.js Router**: ${stack.nextRouterType === "app" ? "App Router" : "Pages Router"}`);
+  if (contextFiles) {
+    sections.push(`## Relevant Code
+
+${contextFiles}`);
   }
-  lines.push(`- **Package Manager**: ${stack.packageManager}`);
-  return lines.join("\n");
+  sections.push(`## Expected Output
+
+${buildOutputFormat(intent)}`);
+  return sections.join("\n\n---\n\n");
 }
-function formatStructure(structure) {
-  const lines = [];
-  if (structure.dirs.length > 0) {
-    lines.push(`Top-level directories: \`${structure.dirs.join("/")}\``);
+function buildSystemPrompt(opts) {
+  const { stack, structure, intent, contextFiles, gitContext, injections, projectInstructions } = opts;
+  const sections = [];
+  if (projectInstructions) {
+    sections.push(`## Project Instructions
+
+${projectInstructions}`);
   }
-  if (structure.hasSrcDir && structure.srcDirs.length > 0) {
-    lines.push(`Inside src/: \`${structure.srcDirs.join("/")}\``);
+  sections.push(`## Project Context
+
+**Stack**: ${formatStack(stack)}
+${formatStackDetails(stack)}
+
+**Structure**: ${formatStructure(structure)}`);
+  sections.push(`## Task
+
+${buildTaskDescription(intent)}
+
+> This is a system-level change. Before writing any code:
+> 1. Analyze the current state and identify all affected areas
+> 2. Define your implementation plan step by step
+> 3. Highlight any breaking changes or migration steps
+> 4. Then implement each step`);
+  const requirementLines = injections.map((r) => `- ${r}`).join("\n");
+  sections.push(`## Requirements
+
+${requirementLines}`);
+  if (gitContext) {
+    sections.push(`## Recent Changes
+
+${gitContext}`);
+  }
+  if (contextFiles) {
+    sections.push(`## Relevant Code
+
+${contextFiles}`);
+  }
+  sections.push(`## Expected Output
+
+Start with a numbered implementation plan. Then implement each step. Mark breaking changes with \u26A0\uFE0F. List every file created or modified at the end.`);
+  return sections.join("\n\n---\n\n");
+}
+function buildOutputFormat(intent) {
+  switch (intent.action) {
+    case "fix":
+      return "Show exactly what changed. Explain in one sentence why it was broken. Provide the corrected code. List every file modified at the end.";
+    case "create":
+    case "add":
+      return "First list every file you will create or modify and why. Then implement each file completely. End with a summary list of all created/modified files.";
+    case "refactor":
+      return "For each change, show before and after. Explain the improvement in one line. Do not change behavior \u2014 only structure. List every file modified at the end.";
+    case "explain":
+      return "Walk through step by step. Reference specific function names, line numbers, or variable names from the existing code. Use concrete examples.";
+    case "delete":
+      return "List exactly what you will remove and why. Show the cleaned-up result. Confirm nothing else depends on the removed code.";
+    default:
+      return "Be thorough and precise. Show all changes. List every file created or modified at the end of your response.";
   }
-  if (structure.hasAppDir) lines.push("Uses Next.js App Router (`app/` directory)");
-  if (structure.hasPagesDir) lines.push("Uses Next.js Pages Router (`pages/` directory)");
-  return lines.join("\n") || "Standard project structure";
 }
 function buildTaskDescription(intent) {
   const actionMap = {
@@ -568,7 +837,36 @@ function buildTaskDescription(intent) {
     unknown: "Handle"
   };
   const action = actionMap[intent.action] ?? "Handle";
-  return `${action}: ${intent.rawPrompt}`;
+  return `**${action}**: ${intent.rawPrompt}`;
+}
+function formatStack(stack) {
+  const primary = stack.frameworks[0] ?? "Node.js";
+  const lang = stack.language === "typescript" ? "TypeScript" : "JavaScript";
+  return `${capitalize(primary)} / ${lang}`;
+}
+function formatStackDetails(stack) {
+  const lines = [];
+  if (stack.frameworks.length > 0) {
+    lines.push(`- **Frameworks**: ${stack.frameworks.map(capitalize).join(", ")}`);
+  }
+  if (stack.uiLibrary) lines.push(`- **UI**: ${capitalize(stack.uiLibrary)}`);
+  if (stack.orm) lines.push(`- **ORM**: ${capitalize(stack.orm)}`);
+  if (stack.testing) lines.push(`- **Testing**: ${capitalize(stack.testing)}`);
+  if (stack.nextRouterType) {
+    lines.push(`- **Router**: ${stack.nextRouterType === "app" ? "App Router" : "Pages Router"}`);
+  }
+  lines.push(`- **Package Manager**: ${stack.packageManager}`);
+  return lines.join("\n");
+}
+function formatStructure(structure) {
+  const parts = [];
+  if (structure.dirs.length > 0) parts.push(`dirs: \`${structure.dirs.join(", ")}\``);
+  if (structure.hasSrcDir && structure.srcDirs.length > 0) {
+    parts.push(`src/: \`${structure.srcDirs.join(", ")}\``);
+  }
+  if (structure.hasAppDir) parts.push("App Router (`app/`)");
+  if (structure.hasPagesDir) parts.push("Pages Router (`pages/`)");
+  return parts.join(" | ") || "Standard layout";
 }
 function capitalize(s) {
   if (!s) return s;
@@ -589,21 +887,77 @@ function capitalize(s) {
 }
 
 // src/enhancer/index.ts
-function enhance(rawPrompt, scan, contextFiles) {
-  const intent = analyzeIntent(rawPrompt);
-  const injections = getInjections(scan.stack, intent);
+function enhance(rawPrompt, scan, contextFiles, projectInstructions = "", gitContext = "", intentOverride, config) {
+  const intent = intentOverride ?? analyzeIntent(rawPrompt);
+  const injections = getInjections(scan.stack, intent, config);
   const enhanced = buildEnhancedPrompt({
     stack: scan.stack,
     structure: scan.structure,
     intent,
     contextFiles,
-    injections
+    injections,
+    projectInstructions,
+    gitContext
   });
   return { original: rawPrompt, enhanced, intent, stack: scan.stack };
 }
 
-// src/providers/claude.ts
+// src/enhancer/planner.ts
 import Anthropic from "@anthropic-ai/sdk";
+async function decomposeToPlan(rawPrompt, intent, stack, apiKey) {
+  const client = new Anthropic({ apiKey });
+  const stackSummary = `${stack.frameworks.join(", ")} / ${stack.language}`;
+  const systemPrompt = `You are a software architect. Break complex development tasks into sequential, focused implementation steps.
+Each step should be small enough to implement in a single AI session.
+Return valid JSON only \u2014 no prose, no markdown fences.`;
+  const userPrompt = `Task: "${rawPrompt}"
+Stack: ${stackSummary}
+
+Break this into ordered implementation steps. Each step must be self-contained and reference the previous step's outputs when needed.
+
+Return JSON with this exact shape:
+{
+  "steps": [
+    {
+      "step": 1,
+      "title": "short title",
+      "prompt": "the full focused prompt for this step, including what was done in previous steps",
+      "dependsOn": []
+    }
+  ]
+}
+
+Rules:
+- 2\u20136 steps maximum
+- Each prompt should be specific and actionable
+- Later steps must mention what the earlier steps created
+- Do not include setup/install steps unless strictly necessary`;
+  const response = await client.messages.create({
+    model: "claude-haiku-4-5-20251001",
+    max_tokens: 2048,
+    system: systemPrompt,
+    messages: [{ role: "user", content: userPrompt }]
+  });
+  const text = response.content[0]?.type === "text" ? response.content[0].text : "{}";
+  try {
+    const parsed = JSON.parse(text);
+    return parsed;
+  } catch {
+    const jsonMatch = text.match(/\{[\s\S]*\}/);
+    if (jsonMatch) {
+      return JSON.parse(jsonMatch[0]);
+    }
+    throw new Error("Failed to parse plan JSON from AI response");
+  }
+}
+
+// src/providers/claude.ts
+import Anthropic2 from "@anthropic-ai/sdk";
+var MODEL_BY_COMPLEXITY = {
+  simple: "claude-haiku-4-5-20251001",
+  feature: "claude-sonnet-4-6",
+  system: "claude-opus-4-7"
+};
 var ClaudeProvider = class {
   name = "Claude";
   client;
@@ -615,10 +969,16 @@ var ClaudeProvider = class {
         "ANTHROPIC_API_KEY environment variable is not set."
       );
     }
-    this.client = new Anthropic({ apiKey: config.apiKey });
+    this.client = new Anthropic2({ apiKey: config.apiKey });
     this.model = config.model;
   }
-  async send(prompt) {
+  async send(prompt, options) {
+    const complexity = options?.["complexity"];
+    if (complexity && MODEL_BY_COMPLEXITY[complexity] && this.model === "claude-sonnet-4-6") {
+      this.model = MODEL_BY_COMPLEXITY[complexity];
+    }
+    console.log(`  Model: ${this.model}
+`);
     const stream = await this.client.messages.create({
       model: this.model,
       max_tokens: 8192,
@@ -626,12 +986,22 @@ var ClaudeProvider = class {
       messages: [{ role: "user", content: prompt }],
       stream: true
     });
+    let inputTokens = 0;
+    let outputTokens = 0;
     for await (const event of stream) {
       if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
         process.stdout.write(event.delta.text);
       }
+      if (event.type === "message_start" && event.message.usage) {
+        inputTokens = event.message.usage.input_tokens;
+      }
+      if (event.type === "message_delta" && event.usage) {
+        outputTokens = event.usage.output_tokens;
+      }
     }
     process.stdout.write("\n");
+    const onUsage = options?.["onUsage"];
+    onUsage?.({ inputTokens, outputTokens, model: this.model });
   }
 };
 
@@ -858,8 +1228,9 @@ program.command("<prompt>", { isDefault: true }).description("Enhance a prompt a
 Examples:
   enhance "build a login page"
   enhance "fix the auth bug" --dry-run
-  enhance "create dashboard" --print-prompt --verbose
-  enhance "refactor user service" --provider codex`).option("-p, --provider <name>", "AI provider: claude | codex | opencode").option("--dry-run", "Print enhanced prompt without sending to AI").option("--print-prompt", "Print enhanced prompt before sending to AI").option("--verbose", "Show detected stack and intent").action(async (rawPrompt, opts) => {
+  enhance "create dashboard" --confirm --verbose
+  enhance "refactor user service" --provider codex
+  enhance "add auth" --action add --feature auth`).option("-p, --provider <name>", "AI provider: claude | codex | opencode").option("--dry-run", "Print enhanced prompt without sending to AI").option("--print-prompt", "Print enhanced prompt before sending to AI").option("--preview", "Color-coded prompt preview with per-section token counts").option("--verbose", "Show detected stack, intent, and context stats").option("--confirm", "Show detected intent and ask for approval before enhancing").option("--plan", "Decompose complex task into sequential sub-prompts (uses AI)").option("--action <action>", "Override detected action (create|fix|refactor|explain|add|delete)").option("--entity <entity>", "Override detected entity (page|component|api|hook|util|config|style)").option("--feature <feature>", "Override detected feature (auth|payment|user|upload|...)").action(async (rawPrompt, opts) => {
   if (!rawPrompt) {
     program.help();
     return;
@@ -877,7 +1248,41 @@ Examples:
       await setCached(cwd, scan);
     }
     spinner.text = "Analyzing intent...";
-    const intent = analyzeIntent(rawPrompt);
+    let intent = analyzeIntent(rawPrompt);
+    if (opts.action) intent = { ...intent, action: opts.action };
+    if (opts.entity) intent = { ...intent, entity: opts.entity };
+    if (opts.feature) intent = { ...intent, feature: opts.feature };
+    if (opts.plan) {
+      if (!config.apiKey) {
+        error("ANTHROPIC_API_KEY required for --plan");
+        process.exit(1);
+      }
+      spinner.text = "Decomposing task into steps...";
+      const plan = await decomposeToPlan(rawPrompt, intent, scan.stack, config.apiKey);
+      spinner.stop();
+      console.log("\n" + chalk3.bold(`Implementation Plan (${plan.steps.length} steps)
+`));
+      for (const step of plan.steps) {
+        console.log(chalk3.cyan(`Step ${step.step}: ${step.title}`));
+        if (step.dependsOn.length > 0) {
+          console.log(chalk3.dim(`  Depends on: Step ${step.dependsOn.join(", ")}`));
+        }
+        console.log(chalk3.dim("\u2500".repeat(60)));
+        console.log(step.prompt);
+        console.log();
+      }
+      process.exit(0);
+    }
+    if (opts.confirm) {
+      spinner.stop();
+      printIntentSummary(intent);
+      const approved = await confirmPrompt("Proceed with this intent? [Y/n] ");
+      if (!approved) {
+        console.log(chalk3.yellow("\nAborted. Use --action / --entity / --feature to override detection.\n"));
+        process.exit(0);
+      }
+      spinner.start("Optimizing context...");
+    }
     if (opts.verbose) {
       spinner.stop();
       console.log("\nStack detected:", JSON.stringify(scan.stack, null, 2));
@@ -885,11 +1290,26 @@ Examples:
       spinner.start("Optimizing context...");
     }
     spinner.text = "Optimizing context...";
-    const contextFiles = await findRelevantFiles(cwd, intent, scan.structure);
+    const [{ contextFiles, gitContext }, projectInstructions] = await Promise.all([
+      findRelevantFiles(cwd, intent, scan.structure, config.maxContextTokens, config.alwaysInclude ?? []),
+      findProjectInstructions(cwd)
+    ]);
+    if (opts.verbose) {
+      spinner.stop();
+      if (projectInstructions) console.log(chalk3.dim("  Project instructions: found (CLAUDE.md / AGENTS.md)"));
+      if (gitContext) console.log(chalk3.dim("  Git context: recent changes detected"));
+      spinner.start("Enhancing prompt...");
+    }
     spinner.text = "Enhancing prompt...";
-    const enhanced = enhance(rawPrompt, scan, contextFiles);
+    const enhanced = enhance(rawPrompt, scan, contextFiles, projectInstructions, gitContext, intent, config);
     spinner.stop();
-    if (opts.dryRun || opts.printPrompt) {
+    if (opts.preview) {
+      printColoredPreview(enhanced.enhanced);
+      if (opts.dryRun) process.exit(0);
+      const go = await confirmPrompt("Send to AI? [Y/n] ");
+      if (!go) process.exit(0);
+      spinner.start(`Sending to AI...`);
+    } else if (opts.dryRun || opts.printPrompt) {
       console.log("\n\u2500\u2500\u2500 Enhanced Prompt \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n");
       console.log(enhanced.enhanced);
       console.log("\n\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n");
@@ -901,7 +1321,14 @@ Examples:
     console.log(`
 [${provider.name}]
 `);
-    await provider.send(enhanced.enhanced);
+    await provider.send(enhanced.enhanced, {
+      complexity: enhanced.intent.complexity,
+      onUsage: (usage) => {
+        const cost = estimateCost(usage.model, usage.inputTokens, usage.outputTokens);
+        console.log(chalk3.dim(`
+  Tokens: ${usage.inputTokens} in / ${usage.outputTokens} out \xB7 ~$${cost}`));
+      }
+    });
   } catch (err) {
     spinner.stop();
     if (err instanceof EnhanceError) {
@@ -916,3 +1343,69 @@ Examples:
   }
 });
 program.parse();
+function printIntentSummary(intent) {
+  const confidencePct = Math.round(intent.confidence * 100);
+  const confidenceColor = intent.confidence >= 0.6 ? chalk3.green : intent.confidence >= 0.3 ? chalk3.yellow : chalk3.red;
+  console.log("\n" + chalk3.bold("Detected Intent:"));
+  console.log(`  ${chalk3.cyan("Action")}:     ${intent.action}`);
+  console.log(`  ${chalk3.cyan("Entity")}:     ${intent.entity}`);
+  console.log(`  ${chalk3.cyan("Feature")}:    ${intent.feature}`);
+  console.log(`  ${chalk3.cyan("Scope")}:      ${intent.scope}`);
+  console.log(`  ${chalk3.cyan("Complexity")}: ${intent.complexity}`);
+  console.log(`  ${chalk3.cyan("Confidence")}: ${confidenceColor(`${confidencePct}%`)}`);
+  console.log();
+}
+async function confirmPrompt(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve2) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve2(answer.toLowerCase() !== "n" && answer.toLowerCase() !== "no");
+    });
+  });
+}
+function printColoredPreview(prompt) {
+  const SECTION_COLORS = {
+    "Project Instructions": chalk3.magenta,
+    "Project Context": chalk3.blue,
+    "Task": chalk3.yellow,
+    "Requirements": chalk3.green,
+    "Recent Changes": chalk3.cyan,
+    "Relevant Code": chalk3.dim,
+    "Code": chalk3.dim,
+    "Expected Output": chalk3.white
+  };
+  const CHARS_PER_TOKEN2 = 4;
+  const sections = prompt.split(/\n---\n/);
+  const totalTokens = Math.ceil(prompt.length / CHARS_PER_TOKEN2);
+  console.log("\n" + chalk3.bold("\u2500\u2500\u2500 Enhanced Prompt Preview \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
+  console.log(chalk3.dim(`Total: ~${totalTokens} tokens
+`));
+  for (const section of sections) {
+    const headerMatch = section.match(/^## (.+)/m);
+    const headerName = headerMatch?.[1]?.trim() ?? "Section";
+    const colorFn = SECTION_COLORS[headerName] ?? chalk3.white;
+    const sectionTokens = Math.ceil(section.length / CHARS_PER_TOKEN2);
+    console.log(colorFn(chalk3.bold(`## ${headerName}`)) + chalk3.dim(` (~${sectionTokens} tok)`));
+    const body = section.replace(/^## .+\n?/, "").trim();
+    if (body) {
+      const lines = body.split("\n");
+      const preview = lines.slice(0, 8).join("\n");
+      const rest = lines.length > 8 ? chalk3.dim(`
+  ... (${lines.length - 8} more lines)`) : "";
+      console.log(colorFn(preview) + rest);
+    }
+    console.log();
+  }
+  console.log(chalk3.bold("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n"));
+}
+var MODEL_PRICING = {
+  "claude-haiku-4-5-20251001": { input: 0.8, output: 4 },
+  "claude-sonnet-4-6": { input: 3, output: 15 },
+  "claude-opus-4-7": { input: 15, output: 75 }
+};
+function estimateCost(model, inputTokens, outputTokens) {
+  const pricing = MODEL_PRICING[model] ?? MODEL_PRICING["claude-sonnet-4-6"];
+  const cost = (inputTokens * pricing.input + outputTokens * pricing.output) / 1e6;
+  return cost < 1e-3 ? "<0.001" : cost.toFixed(4);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@0xdevabir/enhance",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "AI prompt middleware — intelligently rewrites developer prompts before sending to coding agents",
   "bin": {
     "enhance": "./bin/enhance.js"