@jsleekr/graft 5.7.1 → 5.8.0

package/README.md

@@ -1,71 +1,88 @@
-[![npm version](https://img.shields.io/npm/v/@graft-lang/graft.svg)](https://www.npmjs.com/package/@graft-lang/graft)
-[![CI](https://github.com/JSLEEKR/graft/actions/workflows/ci.yml/badge.svg)](https://github.com/JSLEEKR/graft/actions/workflows/ci.yml)
-[![Node.js](https://img.shields.io/node/v/@graft-lang/graft.svg)](https://nodejs.org)
+[![npm version](https://img.shields.io/npm/v/@jsleekr/graft.svg)](https://www.npmjs.com/package/@jsleekr/graft)
+[![Node.js](https://img.shields.io/node/v/@jsleekr/graft.svg)](https://nodejs.org)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 
 # Graft
 
-**A graph-native language for AI agent pipelines.**
+**Define multi-agent pipelines in 10 lines. Compile to Claude Code in 1 second.**
 
-Graft compiles `.gft` files into [Claude Code](https://docs.anthropic.com/en/docs/claude-code) harness structures. Define your multi-agent pipeline declaratively, and the compiler generates the agents, hooks, orchestration, and settings — with compile-time token budget analysis.
+Graft is a graph-native language that compiles `.gft` files into [Claude Code](https://docs.anthropic.com/en/docs/claude-code) harness structures — agents, hooks, orchestration, and settings — with compile-time token budget analysis.
 
-## Quick Start
+## 10-Minute Getting Started
+
+### 1. Install
 
 ```bash
-npm install -g @graft-lang/graft
+npm install -g @jsleekr/graft
 ```
 
-Write a pipeline (`hello.gft`):
+Requires Node.js 20+.
 
-```graft
-context UserRequest(max_tokens: 500) {
-  question: String
-}
+### 2. Create a project
 
-node Researcher(model: sonnet, budget: 2k/1k) {
-  reads: [UserRequest]
-  produces Research {
-    findings: List<String>
-    confidence: Float(0..1)
-  }
-}
+```bash
+graft init my-pipeline
+cd my-pipeline
+```
 
-node Writer(model: haiku, budget: 1500/800) {
-  reads: [Research.findings]
-  produces Answer { response: String }
-}
+This creates `pipeline.gft` — a simple two-node pipeline ready to compile.
 
-edge Researcher -> Writer | select(findings) | compact
+### 3. Compile
 
-graph SimpleQA(input: UserRequest, output: Answer, budget: 6k) {
-  Researcher -> Writer -> done
-}
+```bash
+graft compile pipeline.gft
 ```
 
-Compile it:
+Output:
 
 ```
-$ graft compile hello.gft
-
 ✓ Parse OK
 ✓ Scope check OK
 ✓ Type check OK
 ✓ Token analysis:
-    Researcher           in ~   500  out ~ 1,000
-    Writer               in ~    63  out ~   800
-    Best path:     2,363 tokens ✓ within budget (6,000)
+    Analyst              in ~   500  out ~ 2,000
+    Reviewer             in ~   840  out ~ 1,000
+    Best path:     4,340 tokens ✓ within budget (10,000)
 
 Generated:
-  .claude/agents/researcher.md     ← agent definition
-  .claude/agents/writer.md         ← agent definition
-  .claude/hooks/researcher-to-writer.js  ← edge transform (Node.js)
-  .claude/CLAUDE.md                ← orchestration plan
-  .claude/settings.json            ← model routing + hooks
+  .claude/agents/analyst.md          ← agent definition
+  .claude/agents/reviewer.md         ← agent definition
+  .claude/hooks/analyst-to-reviewer.js  ← edge transform
+  .claude/CLAUDE.md                  ← orchestration plan
+  .claude/settings.json              ← model routing + hooks
+```
+
+### 4. Run in Claude Code
+
+```bash
+# Create input
+echo '{"question": "What is Graft?"}' > .graft/session/input.json
+
+# Open in Claude Code
+claude
+```
+
+Then tell Claude Code:
+
+> `.claude/CLAUDE.md`의 실행 계획을 따라서 파이프라인을 실행해줘. 입력은 `.graft/session/input.json`에 있어.
+
+Claude Code reads the generated `.claude/` structure and runs the pipeline automatically.
+
+### 5. Check the results
+
+```bash
+cat .graft/session/node_outputs/reviewer.json
 ```
 
-Open the project directory in Claude Code — it picks up the generated `.claude/` structure and runs the pipeline.
+That's it. You have a working multi-agent pipeline.
 
-## What Does Graft Generate?
+---
+
+## How It Works
+
+```
+.gft Source  →  Graft Compiler  →  .claude/ output  →  Claude Code runs it
+```
 
 | Graft Source | Generated Output | Purpose |
 |-------------|-----------------|---------|
@@ -81,9 +98,53 @@ Multi-agent systems waste tokens passing full context between agents. Graft fixe
 
 - **Edge transforms** extract only what the next agent needs (`select`, `drop`, `compact`, `filter`)
 - **Compile-time token analysis** catches budget overruns before you spend API credits
-- **Typed output schemas** enforce structured JSON communication between agents
+- **Typed output schemas** enforce structured JSON between agents
 - **Explicit `reads`** declarations prevent context leaks — the compiler verifies scope
 
+## Example: Code Review Pipeline
+
+```graft
+context PullRequest(max_tokens: 2k) {
+  diff: String
+  description: String
+}
+
+node SecurityReviewer(model: sonnet, budget: 4k/2k) {
+  reads: [PullRequest]
+  produces SecurityAnalysis {
+    vulnerabilities: List<String>
+    risk_level: enum(low, medium, high, critical)
+  }
+}
+
+node LogicReviewer(model: sonnet, budget: 4k/2k) {
+  reads: [PullRequest]
+  produces LogicAnalysis {
+    issues: List<String>
+    complexity: Int
+  }
+}
+
+node SeniorReviewer(model: opus, budget: 6k/3k) {
+  reads: [SecurityAnalysis, LogicAnalysis, PullRequest]
+  produces FinalReview {
+    approved: Bool
+    summary: String
+    action_items: List<String>
+  }
+}
+
+edge SecurityReviewer -> SeniorReviewer | select(vulnerabilities, risk_level) | compact
+edge LogicReviewer -> SeniorReviewer | select(issues) | compact
+
+graph CodeReview(input: PullRequest, output: FinalReview, budget: 25k) {
+  parallel { SecurityReviewer  LogicReviewer }
+  -> SeniorReviewer -> done
+}
+```
+
+This compiles to 3 agents running in parallel, with edge transforms that strip unnecessary data before the senior review.
+
 ## Language Features
 
 ### Contexts and Nodes
@@ -153,8 +214,6 @@ A -> let score = A.risk_score * 2
    -> B -> done
 ```
 
-Supported: arithmetic (`+`, `-`, `*`, `/`, `%`), comparison (`>`, `>=`, `==`, `!=`), logical (`&&`, `||`), null coalescing (`??`), string interpolation, builtins (`len`, `max`, `min`, `abs`, `round`, `keys`, `str`).
-
 ### Type System
 
 ```
@@ -172,63 +231,35 @@ graft compile <file.gft> [--out-dir <dir>]   # Compile to .claude/ structure
 graft check <file.gft>                       # Parse + analyze only
 graft run <file.gft> --input <json> [--dry-run] [--verbose]  # Compile and execute
 graft init <name>                            # Scaffold a new project
+graft watch <file.gft> [--out-dir <dir>]     # Watch and recompile on changes
+graft visualize <file.gft>                   # Output pipeline DAG as Mermaid diagram
 ```
 
-## Editor Support
-
-### VS Code
-
-The [Graft VS Code extension](editors/vscode/) provides:
-- Syntax highlighting (TextMate grammar)
-- Real-time diagnostics
-- Hover information (types, token budgets)
-- Go-to-definition, find references, rename
-- Completions (keywords, declarations, imports)
-- Code actions (auto-import)
-- Document symbols
-
 ## Programmatic API
 
 ```typescript
-import { compileToProgram, compile } from '@graft-lang/graft/compiler';
-import { Executor } from '@graft-lang/graft/runtime';
-import type { Program, GraftErrorCode } from '@graft-lang/graft/types';
+import { compile } from '@jsleekr/graft/compiler';
+import { Executor } from '@jsleekr/graft/runtime';
+import type { Program } from '@jsleekr/graft/types';
 
-const result = compileToProgram(source, 'pipeline.gft');
+const result = compile(source, 'pipeline.gft');
 if (result.success) {
   console.log(`Parsed ${result.program.nodes.length} nodes`);
 }
 ```
 
+## Editor Support
+
+The [Graft VS Code extension](editors/vscode/) provides syntax highlighting, real-time diagnostics, hover, go-to-definition, find references, rename, completions, and code actions.
+
 ## Development
 
 ```bash
 git clone https://github.com/JSLEEKR/graft.git
 cd graft && npm install
 npm run build         # Compile TypeScript
-npm test              # Run all 1,344 tests
-```
-
-## Version History
-
-| Version | Highlights |
-|---------|-----------|
-| **v5.3** | Parallel codegen test coverage, hook entry merging |
-| **v5.2** | Parallel→sequential edge transforms, agent input overrides, graceful hooks |
-| **v5.1** | Claude Code compatibility, `graft init`, CI/CD, README rewrite |
-| **v5.0** | Condition-to-Expr AST unification, strict equality, codegen expression display |
-| **v4.9** | Codegen expression display |
-| **v4.8** | LSP expression intelligence — hover, go-to-def, completions |
-| **v4.7** | Null coalescing (`??`), runtime expression hardening |
-| **v4.6** | Logical operators (`&&`, `||`), conditional type warnings |
-| **v4.5** | Comparison operators, conditional expressions |
-| **v4.4** | String interpolation, expression extraction |
-| **v4.0** | Variables, expressions, graph parameters, graph calls |
-| **v3.0** | Pluggable codegen backends, field-level writes, failure strategies |
-| **v2.0** | Import system, persistent memory |
-| **v1.0** | Full compiler pipeline, CLI |
-
-See [CHANGELOG.md](CHANGELOG.md) for full details.
+npm test              # Run all 1,574 tests
+```
 
 ## License
 

package/dist/analyzer/scope.js

@@ -1,4 +1,4 @@
-import { GraftError } from '../errors/diagnostics.js';
+import { GraftError, didYouMean } from '../errors/diagnostics.js';
 import { ProgramIndex } from '../program-index.js';
 import { checkVarCollision, checkExprSources, checkGraphCallArgs, checkGraphRecursion, } from './graph-checker.js';
 export class ScopeChecker {
@@ -56,17 +56,28 @@ export class ScopeChecker {
                 const isProduces = this.index.producesFieldsMap.has(ref.context);
                 const isMemory = this.index.memoryMap.has(ref.context);
                 if (!isContext && !isProduces && !isMemory) {
-                    errors.push(new GraftError(`'${ref.context}' is not declared as a context, produces output, or memory`, ref.location, 'error', 'SCOPE_UNDEFINED_REF'));
+                    const allNames = [
+                        ...this.index.contextMap.keys(),
+                        ...this.index.producesFieldsMap.keys(),
+                        ...this.index.memoryMap.keys(),
+                    ];
+                    const suggestion = didYouMean(ref.context, allNames);
+                    const help = suggestion
+                        ? `did you mean '${suggestion}'?`
+                        : undefined;
+                    errors.push(new GraftError(`'${ref.context}' is not declared as a context, produces output, or memory`, ref.location, 'error', 'SCOPE_UNDEFINED_REF', help));
                     continue;
                 }
                 // Check partial reference fields
                 if (ref.field) {
                     if (isContext) {
                         const ctx = this.index.contextMap.get(ref.context);
-                        const fieldNames = new Set(ctx.fields.map(f => f.name));
+                        const fieldNames = ctx.fields.map(f => f.name);
+                        const fieldSet = new Set(fieldNames);
                         for (const f of ref.field) {
-                            if (!fieldNames.has(f)) {
-                                errors.push(new GraftError(`Field '${f}' does not exist in context '${ref.context}'`, ref.location, 'error', 'SCOPE_FIELD_NOT_FOUND'));
+                            if (!fieldSet.has(f)) {
+                                const suggestion = didYouMean(f, fieldNames);
+                                errors.push(new GraftError(`Field '${f}' does not exist in context '${ref.context}'`, ref.location, 'error', 'SCOPE_FIELD_NOT_FOUND', suggestion ? `did you mean '${suggestion}'?` : undefined));
                             }
                         }
                     }
@@ -74,7 +85,8 @@ export class ScopeChecker {
                         const fields = this.index.producesFieldsMap.get(ref.context);
                         for (const f of ref.field) {
                             if (!fields.has(f)) {
-                                errors.push(new GraftError(`Field '${f}' does not exist in produces '${ref.context}'`, ref.location, 'error', 'SCOPE_FIELD_NOT_FOUND'));
+                                const suggestion = didYouMean(f, [...fields.keys()]);
+                                errors.push(new GraftError(`Field '${f}' does not exist in produces '${ref.context}'`, ref.location, 'error', 'SCOPE_FIELD_NOT_FOUND', suggestion ? `did you mean '${suggestion}'?` : undefined));
                             }
                         }
                     }

package/dist/codegen/backend.d.ts

@@ -11,6 +11,7 @@ export interface CodegenBackend {
     readonly name: string;
     generateAgent(node: NodeDecl, memoryNames: Set<string>, ctx: CodegenContext): string;
     generateHook(edge: EdgeDecl, ctx: CodegenContext): string | null;
+    generateConditionalHook?(edge: EdgeDecl, ctx: CodegenContext): string | null;
     generateOrchestration(ctx: CodegenContext): string;
     generateSettings(ctx: CodegenContext): Record<string, unknown>;
 }

package/dist/codegen/claude-backend.d.ts

@@ -4,6 +4,7 @@ export declare class ClaudeCodeBackend implements CodegenBackend {
     readonly name = "claude";
     generateAgent(node: NodeDecl, memoryNames: Set<string>, ctx: CodegenContext): string;
     generateHook(edge: EdgeDecl, _ctx: CodegenContext): string | null;
+    generateConditionalHook(edge: EdgeDecl, _ctx: CodegenContext): string | null;
     generateOrchestration(ctx: CodegenContext): string;
     generateSettings(ctx: CodegenContext): Record<string, unknown>;
 }

package/dist/codegen/claude-backend.js

@@ -1,5 +1,5 @@
 import { generateAgent } from './agents.js';
-import { generateHook } from './hooks.js';
+import { generateHook, generateConditionalHook } from './hooks.js';
 import { generateOrchestration } from './orchestration.js';
 import { generateSettings } from './settings.js';
 export class ClaudeCodeBackend {
@@ -7,8 +7,9 @@ export class ClaudeCodeBackend {
     generateAgent(node, memoryNames, ctx) {
         // Compute input overrides: map produces names to actual file paths
         const inputOverrides = new Map();
-        // 1. For edges with transforms: use the transformed output path
-        // 2. For edges without transforms: use the source's raw output path
+        // 1. For direct edges with transforms: use the transformed output path
+        // 2. For direct edges without transforms: use the source's raw output path
+        // 3. For conditional edges targeting this node: use the source's raw output path
         for (const edge of ctx.program.edges) {
             if (edge.target.kind === 'direct' && edge.target.node === node.name) {
                 const sourceNode = ctx.program.nodes.find(n => n.name === edge.source);
@@ -22,6 +23,18 @@ export class ClaudeCodeBackend {
                     }
                 }
             }
+            else if (edge.target.kind === 'conditional') {
+                const isTarget = edge.target.branches.some(b => b.target === node.name);
+                if (isTarget) {
+                    const sourceNode = ctx.program.nodes.find(n => n.name === edge.source);
+                    if (sourceNode) {
+                        const producesName = sourceNode.produces.name;
+                        if (!inputOverrides.has(producesName)) {
+                            inputOverrides.set(producesName, `.graft/session/node_outputs/${edge.source.toLowerCase()}.json`);
+                        }
+                    }
+                }
+            }
         }
         // 3. For produces reads with no corresponding edge: resolve to producer's raw output
         for (const ref of node.reads) {
@@ -38,6 +51,9 @@ export class ClaudeCodeBackend {
     generateHook(edge, _ctx) {
         return generateHook(edge);
     }
+    generateConditionalHook(edge, _ctx) {
+        return generateConditionalHook(edge);
+    }
     generateOrchestration(ctx) {
         return generateOrchestration(ctx.program, ctx.report);
     }

package/dist/codegen/codegen.js

@@ -18,14 +18,27 @@ export function generate(program, report, sourceFile, index, backend) {
     }
     // Hooks
     for (const edge of program.edges) {
-        const hook = be.generateHook(edge, ctx);
-        if (hook && edge.target.kind === 'direct') {
-            const source = edge.source.toLowerCase();
-            const target = edge.target.node.toLowerCase();
-            files.push({
-                path: `.claude/hooks/${source}-to-${target}.js`,
-                content: hook,
-            });
+        if (edge.target.kind === 'conditional') {
+            // Conditional edge → router hook
+            const hook = be.generateConditionalHook?.(edge, ctx);
+            if (hook) {
+                files.push({
+                    path: `.claude/hooks/${edge.source.toLowerCase()}-router.js`,
+                    content: hook,
+                });
+            }
+        }
+        else {
+            // Direct edge → transform hook
+            const hook = be.generateHook(edge, ctx);
+            if (hook && edge.target.kind === 'direct') {
+                const source = edge.source.toLowerCase();
+                const target = edge.target.node.toLowerCase();
+                files.push({
+                    path: `.claude/hooks/${source}-to-${target}.js`,
+                    content: hook,
+                });
+            }
         }
     }
     // Orchestration
@@ -42,6 +55,11 @@ export function generate(program, report, sourceFile, index, backend) {
     // Runtime scaffold
     files.push({ path: '.graft/session/node_outputs/.gitkeep', content: '' });
     files.push({ path: '.graft/token_log.txt', content: '' });
+    // Routing scaffold (only when conditional edges exist)
+    const hasConditionalEdges = program.edges.some(e => e.target.kind === 'conditional');
+    if (hasConditionalEdges) {
+        files.push({ path: '.graft/session/routing/.gitkeep', content: '' });
+    }
     // Memory scaffold — conditional
     if (program.memories.length > 0) {
         files.push({ path: '.graft/memory/.gitkeep', content: '' });

package/dist/codegen/hooks.d.ts

@@ -1,2 +1,7 @@
 import { EdgeDecl } from '../parser/ast.js';
 export declare function generateHook(edge: EdgeDecl): string | null;
+/**
+ * Generate a router hook for conditional edges.
+ * Evaluates branch conditions and writes routing decision.
+ */
+export declare function generateConditionalHook(edge: EdgeDecl): string | null;

package/dist/codegen/hooks.js

@@ -163,3 +163,86 @@ function filterToJs(t) {
     const op = condition.op === '==' ? '===' : condition.op === '!=' ? '!==' : condition.op;
     return `result[${JSON.stringify(field)}] = (result[${JSON.stringify(field)}] || []).filter(item => item[${JSON.stringify(fieldName)}] ${op} ${valueStr});`;
 }
+/**
+ * Generate a router hook for conditional edges.
+ * Evaluates branch conditions and writes routing decision.
+ */
+export function generateConditionalHook(edge) {
+    if (edge.target.kind !== 'conditional')
+        return null;
+    const source = edge.source.toLowerCase();
+    const branches = edge.target.branches;
+    const targets = branches.map(b => b.target).filter(t => t !== 'done');
+    const conditionCode = branchesToJs(branches);
+    return `#!/usr/bin/env node
+// Auto-generated by Graft Compiler
+// Conditional routing: ${edge.source} -> {${branches.map(b => b.target).join(', ')}}
+
+const fs = require('fs');
+const path = require('path');
+
+const INPUT = path.resolve('.graft/session/node_outputs/${source}.json');
+const ROUTE = path.resolve('.graft/session/routing/${source}_route.json');
+
+if (!fs.existsSync(INPUT)) {
+  process.exit(0);
+}
+
+const data = JSON.parse(fs.readFileSync(INPUT, 'utf-8'));
+
+${conditionCode}
+
+fs.mkdirSync(path.dirname(ROUTE), { recursive: true });
+fs.writeFileSync(ROUTE, JSON.stringify({ target, from: ${JSON.stringify(edge.source)} }, null, 2));
+`;
+}
+function branchesToJs(branches) {
+    const lines = [];
+    let first = true;
+    for (const branch of branches) {
+        if (!branch.condition) {
+            // else branch
+            if (first) {
+                lines.push(`let target = ${JSON.stringify(branch.target)};`);
+            }
+            else {
+                lines.push(`} else {`);
+                lines.push(`  target = ${JSON.stringify(branch.target)};`);
+                lines.push(`}`);
+            }
+        }
+        else {
+            const jsCondition = exprToJs(branch.condition);
+            if (first) {
+                lines.push(`let target = null;`);
+                lines.push(`if (${jsCondition}) {`);
+                lines.push(`  target = ${JSON.stringify(branch.target)};`);
+                first = false;
+            }
+            else {
+                lines.push(`} else if (${jsCondition}) {`);
+                lines.push(`  target = ${JSON.stringify(branch.target)};`);
+            }
+        }
+    }
+    // Close the if chain if we have conditions but no else
+    if (!first && !branches.some(b => !b.condition)) {
+        lines.push(`}`);
+    }
+    return lines.join('\n');
+}
+function exprToJs(expr) {
+    if (expr.kind === 'binary') {
+        const left = exprToJs(expr.left);
+        const right = exprToJs(expr.right);
+        const op = expr.op === '==' ? '===' : expr.op === '!=' ? '!==' : expr.op;
+        return `${left} ${op} ${right}`;
+    }
+    if (expr.kind === 'field_access') {
+        return `data[${JSON.stringify(expr.segments[0])}]`;
+    }
+    if (expr.kind === 'literal') {
+        return JSON.stringify(expr.value);
+    }
+    return formatExpr(expr);
+}

package/dist/codegen/orchestration.js

@@ -7,12 +7,16 @@ export function generateOrchestration(program, report) {
     const index = new ProgramIndex(program);
     const memoryNames = new Set(program.memories.map(m => m.name));
     const edgeMap = new Map();
+    const conditionalEdgeMap = new Map();
     for (const edge of program.edges) {
         if (edge.target.kind === 'direct' && edge.transforms.length > 0) {
             edgeMap.set(`${edge.source}->${edge.target.node}`, { transforms: edge.transforms });
         }
+        else if (edge.target.kind === 'conditional') {
+            conditionalEdgeMap.set(edge.source, edge);
+        }
     }
-    const { text: steps } = generateSteps(graph.flow, report, edgeMap, 1, null, index.nodeMap, memoryNames);
+    const { text: steps } = generateSteps(graph.flow, report, edgeMap, conditionalEdgeMap, 1, null, index.nodeMap, memoryNames);
     // Memory preamble
     const memorySection = program.memories.length > 0
         ? `
@@ -70,7 +74,42 @@ function describeTransforms(transforms) {
     }
     return parts.join(', then ');
 }
-function generateSteps(flow, report, edgeMap, startStep, prevNode, nodeMap, memoryNames) {
+function describeCondition(expr) {
+    if (expr.kind === 'binary') {
+        const left = expr.left.kind === 'field_access' ? `\`${expr.left.segments[0]}\`` : formatExpr(expr.left);
+        const right = expr.right.kind === 'literal' ? `\`${expr.right.value}\`` : formatExpr(expr.right);
+        return `${left} ${expr.op} ${right}`;
+    }
+    return formatExpr(expr);
+}
+function generateConditionalRoutingStep(stepNum, edge, nodeMap, report) {
+    if (edge.target.kind !== 'conditional')
+        return '';
+    const source = edge.source.toLowerCase();
+    const branches = edge.target.branches;
+    let text = `
+### Step ${stepNum}: Conditional routing from ${edge.source}
+- **Automatic**: Router hook evaluates conditions on ${edge.source}'s output
+- Routing file: \`.graft/session/routing/${source}_route.json\`
+- Read the \`target\` field and proceed accordingly:
+`;
+    for (const branch of branches) {
+        const label = branch.condition ? describeCondition(branch.condition) : 'else (default)';
+        if (branch.target === 'done') {
+            text += `  - If ${label}: **pipeline complete**\n`;
+        }
+        else {
+            const nodeReport = report.nodes.find(n => n.name === branch.target);
+            const tokenInfo = nodeReport
+                ? ` (tokens: input ~${nodeReport.estimatedIn.toLocaleString('en-US')} / output ~${nodeReport.estimatedOut.toLocaleString('en-US')})`
+                : '';
+            text += `  - If ${label}: run **${branch.target}** agent${tokenInfo}\n`;
+        }
+    }
+    text += `- Each branch agent reads from \`.graft/session/node_outputs/${source}.json\`\n`;
+    return text;
+}
+function generateSteps(flow, report, edgeMap, conditionalEdgeMap, startStep, prevNode, nodeMap, memoryNames) {
     let text = '';
     let stepNum = startStep;
     let prev = prevNode;
@@ -154,9 +193,15 @@ function generateSteps(flow, report, edgeMap, startStep, prevNode, nodeMap, memo
 - Completion: \`===NODE_COMPLETE:${lowerName}===\`
 - Output: \`.graft/session/node_outputs/${lowerName}.json\`
 `;
+                stepNum++;
+                // Conditional routing after this node
+                const condEdge = conditionalEdgeMap.get(step.name);
+                if (condEdge && condEdge.target.kind === 'conditional') {
+                    text += generateConditionalRoutingStep(stepNum, condEdge, nodeMap, report);
+                    stepNum++;
+                }
                 prev = step.name;
                 prevParallelBranches = [];
-                stepNum++;
                 break;
             }
             case 'parallel': {

package/dist/codegen/settings.js

@@ -42,17 +42,25 @@ export function generateSettings(program, sourceFile, index) {
     // Collect all hook commands, then merge into a single "Write" matcher entry
     const hookCommands = [];
     for (const edge of program.edges) {
-        if (edge.transforms.length === 0)
-            continue;
-        if (edge.target.kind !== 'direct')
-            continue;
-        const source = edge.source.toLowerCase();
-        const target = edge.target.node.toLowerCase();
-        hookCommands.push({
-            type: 'command',
-            command: `node .claude/hooks/${source}-to-${target}.js`,
-            if: `Write(.graft/session/node_outputs/${source}.json)`,
-        });
+        if (edge.target.kind === 'conditional') {
+            // Conditional edge → router hook
+            const source = edge.source.toLowerCase();
+            hookCommands.push({
+                type: 'command',
+                command: `node .claude/hooks/${source}-router.js`,
+                if: `Write(.graft/session/node_outputs/${source}.json)`,
+            });
+        }
+        else if (edge.target.kind === 'direct' && edge.transforms.length > 0) {
+            // Direct edge with transforms → transform hook
+            const source = edge.source.toLowerCase();
+            const target = edge.target.node.toLowerCase();
+            hookCommands.push({
+                type: 'command',
+                command: `node .claude/hooks/${source}-to-${target}.js`,
+                if: `Write(.graft/session/node_outputs/${source}.json)`,
+            });
+        }
     }
     const hookEntries = [];
     if (hookCommands.length > 0) {

package/dist/errors/diagnostics.d.ts

@@ -16,6 +16,12 @@ export declare class GraftError extends Error {
     readonly location: SourceLocation;
     readonly severity: 'error' | 'warning';
     readonly code?: GraftErrorCode | undefined;
-    constructor(message: string, location: SourceLocation, severity?: 'error' | 'warning', code?: GraftErrorCode | undefined);
-    format(source: string): string;
+    readonly help?: string | undefined;
+    constructor(message: string, location: SourceLocation, severity?: 'error' | 'warning', code?: GraftErrorCode | undefined, help?: string | undefined);
+    format(source: string, filename?: string): string;
 }
+/**
+ * Find the closest match to `name` from `candidates` using Levenshtein distance.
+ * Returns the best match if distance <= maxDistance, otherwise undefined.
+ */
+export declare function didYouMean(name: string, candidates: string[], maxDistance?: number): string | undefined;

package/dist/errors/diagnostics.js

@@ -2,24 +2,81 @@ export class GraftError extends Error {
     location;
     severity;
     code;
-    constructor(message, location, severity = 'error', code) {
+    help;
+    constructor(message, location, severity = 'error', code, help) {
         super(message);
         this.location = location;
         this.severity = severity;
         this.code = code;
+        this.help = help;
         this.name = 'GraftError';
     }
-    format(source) {
+    format(source, filename) {
         const lines = source.split('\n');
         const lineIdx = this.location.line - 1;
         const line = (lineIdx >= 0 && lineIdx < lines.length) ? lines[lineIdx] : '';
         const col = Math.max(0, this.location.column - 1);
-        const pointer = ' '.repeat(col) + '^';
-        return [
-            `Error at line ${this.location.line}:${this.location.column}:`,
-            `    ${line}`,
-            `    ${pointer}`,
-            `    ${this.message}`,
-        ].join('\n');
+        const lineNumStr = String(this.location.line);
+        const gutter = ' '.repeat(lineNumStr.length);
+        // Underline: use length if available, otherwise single caret
+        const underlineLen = this.location.length && this.location.length > 0
+            ? this.location.length
+            : 1;
+        const underline = '^'.repeat(underlineLen);
+        const label = this.severity === 'warning' ? 'warning' : 'error';
+        const codeStr = this.code ? `[${this.code}]` : '';
+        const file = filename || '<source>';
+        const result = [
+            `${label}${codeStr}: ${this.message}`,
+            ` ${gutter}--> ${file}:${this.location.line}:${this.location.column}`,
+            ` ${gutter} |`,
+            ` ${lineNumStr} | ${line}`,
+            ` ${gutter} | ${' '.repeat(col)}${underline}`,
+        ];
+        if (this.help) {
+            result.push(` ${gutter} |`);
+            result.push(` ${gutter} = help: ${this.help}`);
+        }
+        return result.join('\n');
     }
 }
+/**
+ * Find the closest match to `name` from `candidates` using Levenshtein distance.
+ * Returns the best match if distance <= maxDistance, otherwise undefined.
+ */
+export function didYouMean(name, candidates, maxDistance = 3) {
+    let best;
+    let bestDist = maxDistance + 1;
+    for (const candidate of candidates) {
+        const dist = levenshtein(name.toLowerCase(), candidate.toLowerCase());
+        if (dist < bestDist) {
+            bestDist = dist;
+            best = candidate;
+        }
+    }
+    return bestDist <= maxDistance ? best : undefined;
+}
+function levenshtein(a, b) {
+    const m = a.length;
+    const n = b.length;
+    if (m === 0)
+        return n;
+    if (n === 0)
+        return m;
+    // Single-row DP
+    let prev = new Array(n + 1);
+    let curr = new Array(n + 1);
+    for (let j = 0; j <= n; j++)
+        prev[j] = j;
+    for (let i = 1; i <= m; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= n; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            curr[j] = Math.min(curr[j - 1] + 1, // insert
+            prev[j] + 1, // delete
+            prev[j - 1] + cost);
+        }
+        [prev, curr] = [curr, prev];
+    }
+    return prev[n];
+}

package/dist/index.js

@@ -2,7 +2,7 @@
 import { Command } from 'commander';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { compile, compileAndWrite } from './compiler.js';
+import { compile, compileAndWrite, compileToProgram } from './compiler.js';
 import { VERSION } from './version.js';
 import { formatTokenReport } from './format.js';
 const KNOWN_BACKENDS = new Set(['claude']);
@@ -34,7 +34,7 @@ program
     if (!result.success) {
         console.error('\n✗ Compilation failed:\n');
         for (const err of result.errors) {
-            console.error(err.format(source));
+            console.error(err.format(source, file));
             console.error('');
         }
         process.exit(1);
@@ -67,7 +67,7 @@ program
     if (!result.success) {
         console.error('\n✗ Check failed:\n');
         for (const err of result.errors) {
-            console.error(err.format(source));
+            console.error(err.format(source, file));
             console.error('');
         }
         process.exit(1);
@@ -170,6 +170,134 @@ graph ${safeName}(input: Input, output: Output, budget: 10k) {
     console.log(`  # Open in Claude Code to run the pipeline`);
     console.log('');
 });
+program
+    .command('watch')
+    .description('Watch .gft file and recompile on changes')
+    .argument('<file>', '.gft source file')
+    .option('--out-dir <dir>', 'output directory', '.')
+    .action((file, opts) => {
+    const resolved = path.resolve(file);
+    if (!fs.existsSync(resolved)) {
+        console.error(`Error: file not found: ${resolved}`);
+        process.exit(1);
+    }
+    function doCompile() {
+        const source = fs.readFileSync(resolved, 'utf-8');
+        try {
+            const result = compileAndWrite(source, resolved, path.resolve(opts.outDir));
+            if (!result.success) {
+                console.error('\n✗ Compilation failed:\n');
+                for (const err of result.errors) {
+                    console.error(err.format(source, file));
+                    console.error('');
+                }
+            }
+            else {
+                const timestamp = new Date().toLocaleTimeString();
+                const fileCount = result.files?.length || 0;
+                console.log(`[${timestamp}] ✓ Compiled ${file} → ${fileCount} files`);
+                for (const w of result.warnings) {
+                    console.log(`  ⚠ ${w.message}`);
+                }
+            }
+        }
+        catch (e) {
+            console.error(`Error: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    // Initial compile
+    doCompile();
+    console.log(`\nWatching ${file} for changes... (Ctrl+C to stop)\n`);
+    // Watch for changes
+    let debounceTimer = null;
+    fs.watch(resolved, () => {
+        if (debounceTimer)
+            clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(doCompile, 100);
+    });
+    // Also watch imported files in the same directory
+    const dir = path.dirname(resolved);
+    try {
+        fs.watch(dir, { recursive: false }, (_, filename) => {
+            if (filename && filename.endsWith('.gft') && filename !== path.basename(resolved)) {
+                if (debounceTimer)
+                    clearTimeout(debounceTimer);
+                debounceTimer = setTimeout(doCompile, 100);
+            }
+        });
+    }
+    catch {
+        // Ignore if directory watch fails
+    }
+});
+program
+    .command('visualize')
+    .description('Output pipeline DAG as a Mermaid diagram')
+    .argument('<file>', '.gft source file')
+    .option('--format <fmt>', 'output format: mermaid', 'mermaid')
+    .action((file) => {
+    const source = readSource(file);
+    const result = compileToProgram(source, path.resolve(file));
+    if (!result.success || !result.program) {
+        console.error('\n✗ Compilation failed:\n');
+        for (const err of result.errors) {
+            console.error(err.format(source, file));
+            console.error('');
+        }
+        process.exit(1);
+    }
+    const { program: prog } = result;
+    const lines = ['graph TD'];
+    // Nodes
+    for (const node of prog.nodes) {
+        const model = node.model;
+        lines.push(`    ${node.name}["${node.name}<br/><small>${model}</small>"]`);
+    }
+    // Direct edges
+    for (const edge of prog.edges) {
+        if (edge.target.kind === 'direct') {
+            const label = edge.transforms.length > 0
+                ? edge.transforms.map(t => t.type).join(' → ')
+                : '';
+            if (label) {
+                lines.push(`    ${edge.source} -->|${label}| ${edge.target.node}`);
+            }
+            else {
+                lines.push(`    ${edge.source} --> ${edge.target.node}`);
+            }
+        }
+        else if (edge.target.kind === 'conditional') {
+            for (const branch of edge.target.branches) {
+                const target = branch.target === 'done' ? 'done((done))' : branch.target;
+                const label = branch.condition
+                    ? formatExprForMermaid(branch.condition)
+                    : 'else';
+                lines.push(`    ${edge.source} -->|${label}| ${target}`);
+            }
+        }
+    }
+    // Graph flow (parallel blocks)
+    if (prog.graphs[0]) {
+        for (const step of prog.graphs[0].flow) {
+            if (step.kind === 'parallel') {
+                lines.push(`    subgraph parallel["parallel"]`);
+                for (const b of step.branches) {
+                    lines.push(`        ${b}`);
+                }
+                lines.push(`    end`);
+            }
+        }
+    }
+    console.log(lines.join('\n'));
+});
+function formatExprForMermaid(expr) {
+    if (expr.kind === 'binary') {
+        const left = expr.left.kind === 'field_access' ? expr.left.segments[0] : '?';
+        const right = expr.right.kind === 'literal' ? String(expr.right.value) : '?';
+        return `${left} ${expr.op} ${right}`;
+    }
+    return '?';
+}
 function readSource(file) {
     const resolved = path.resolve(file);
     if (!fs.existsSync(resolved)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsleekr/graft",
-  "version": "5.7.1",
+  "version": "5.8.0",
   "description": "Graft compiler — compile .gft graph DSL to Claude Code harness structures",
   "type": "module",
   "license": "MIT",