@jsleekr/graft 5.7.2 → 5.8.0

package/README.md

@@ -231,6 +231,8 @@ 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
 ```
 
 ## Programmatic API

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.2",
+  "version": "5.8.0",
   "description": "Graft compiler — compile .gft graph DSL to Claude Code harness structures",
   "type": "module",
   "license": "MIT",