@jsleekr/graft 5.8.0 → 6.0.0

package/dist/index.js

@@ -5,7 +5,17 @@ import * as path from 'node:path';
 import { compile, compileAndWrite, compileToProgram } from './compiler.js';
 import { VERSION } from './version.js';
 import { formatTokenReport } from './format.js';
-const KNOWN_BACKENDS = new Set(['claude']);
+import { formatProgram } from './formatter.js';
+import { ClaudeCodeBackend } from './codegen/claude-backend.js';
+import { GenericBackend } from './codegen/generic-backend.js';
+const KNOWN_BACKENDS = new Set(['claude', 'generic']);
+function resolveBackend(name) {
+    switch (name) {
+        case 'claude': return new ClaudeCodeBackend();
+        case 'generic': return new GenericBackend();
+        default: throw new Error(`Unknown backend: ${name}`);
+    }
+}
 const program = new Command();
 program
     .name('graft')
@@ -23,9 +33,10 @@ program
         process.exit(1);
     }
     const source = readSource(file);
+    const backend = resolveBackend(opts.backend);
     let result;
     try {
-        result = compileAndWrite(source, path.resolve(file), path.resolve(opts.outDir));
+        result = compileAndWrite(source, path.resolve(file), path.resolve(opts.outDir), backend);
     }
     catch (e) {
         console.error(`Error: ${e instanceof Error ? e.message : String(e)}`);
@@ -91,10 +102,14 @@ program
     .option('--input <file>', 'input JSON file')
     .option('--dry-run', 'simulate execution without spawning subprocesses')
     .option('--verbose', 'print execution details')
+    .option('--json', 'output results as JSON')
     .option('--timeout <seconds>', 'subprocess timeout in seconds', '300')
     .option('--work-dir <dir>', 'working directory for execution')
     .action(async (file, opts) => {
-    const { run } = await import('./runner.js');
+    const { run, getProgram } = await import('./runner.js');
+    const { formatRunResult } = await import('./runtime/result-formatter.js');
+    const { validateResult, formatQualityReport } = await import('./runtime/result-validator.js');
+    const { generateFeedback, formatSuggestions } = await import('./runtime/feedback.js');
     const result = await run({
         sourceFile: file,
         inputFile: opts.input,
@@ -103,29 +118,28 @@ program
         verbose: opts.verbose,
         timeoutMs: parseInt(opts.timeout, 10) * 1000,
     });
+    // Get the program for validation
+    const prog = getProgram();
+    // Format result
+    console.log('\n' + formatRunResult(result, prog, { json: opts.json, verbose: opts.verbose }));
+    // Quality validation + feedback (skip for JSON mode)
+    if (!opts.json && prog) {
+        const report = validateResult(result, prog);
+        console.log('\n' + formatQualityReport(report));
+        const suggestions = generateFeedback(report, prog);
+        if (suggestions.length > 0) {
+            console.log(formatSuggestions(suggestions));
+        }
+    }
     if (!result.success) {
-        console.error('\nExecution failed:');
-        for (const err of result.errors)
-            console.error(`  ${err}`);
         process.exit(1);
     }
-    console.log(`\nGraph '${result.graph}' completed in ${result.totalDurationMs}ms`);
-    console.log(`Nodes executed: ${result.nodeResults.length}`);
-    for (const nr of result.nodeResults) {
-        const status = nr.success ? 'OK' : 'FAILED';
-        console.log(`  ${nr.node.padEnd(20)} ${status.padEnd(8)} ${nr.durationMs}ms`);
-    }
-    if (result.finalOutput !== null) {
-        console.log('\nFinal output:');
-        console.log(JSON.stringify(result.finalOutput, null, 2));
-    }
-    console.log('');
 });
 program
     .command('init')
     .description('Scaffold a new Graft project')
     .argument('<name>', 'project name')
-    .action((name) => {
+    .action(async (name) => {
     const dir = path.resolve(name);
     if (fs.existsSync(dir)) {
         console.error(`Error: directory '${name}' already exists`);
@@ -134,6 +148,7 @@ program
     fs.mkdirSync(dir, { recursive: true });
     const baseName = path.basename(name);
     const safeName = baseName.replace(/[^a-zA-Z0-9]/g, '_').replace(/^_+|_+$/g, '') || 'pipeline';
+    // Generate pipeline.gft starter template
     fs.writeFileSync(path.join(dir, 'pipeline.gft'), `// ${safeName} — a simple two-node pipeline
 
 context Input(max_tokens: 500) {
@@ -161,13 +176,58 @@ edge Analyst -> Reviewer | select(answer, confidence) | compact
 graph ${safeName}(input: Input, output: Output, budget: 10k) {
   Analyst -> Reviewer -> done
 }
+`);
+    // Generate .claude/CLAUDE.md with .gft spec so Claude Code natively understands Graft
+    const claudeDir = path.join(dir, '.claude');
+    fs.mkdirSync(claudeDir, { recursive: true });
+    const { buildSystemPrompt } = await import('./generator.js');
+    const gftSpec = buildSystemPrompt();
+    fs.writeFileSync(path.join(claudeDir, 'CLAUDE.md'), `# ${safeName}
+
+This project uses **Graft** (.gft) for defining multi-agent pipelines.
+
+## Working with .gft files
+
+When the user asks to create, modify, or manage pipelines:
+1. Write or edit \`.gft\` files using the syntax below
+2. Run \`graft compile <file.gft>\` to generate the \`.claude/\` harness structure
+3. Run \`graft check <file.gft>\` to validate without generating files
+
+## CLI Commands
+
+\`\`\`bash
+graft compile <file.gft> [--out-dir <dir>]  # Compile to harness structure
+graft check <file.gft>                      # Parse + analyze only
+graft run <file.gft> --input <json>         # Compile, execute, validate, suggest fixes
+graft fmt <file.gft> [-w]                   # Format .gft source
+graft visualize <file.gft>                  # Output pipeline DAG as Mermaid
+graft watch <file.gft>                      # Watch and recompile on changes
+\`\`\`
+
+## After Pipeline Execution
+
+When a pipeline run completes, \`graft run\` automatically:
+1. Shows a formatted result summary (nodes, tokens, timing)
+2. Validates output against the .gft schema (types, ranges, empty fields)
+3. Suggests .gft modifications if quality issues are found
+
+If the quality report shows issues:
+- Empty fields → suggest increasing node output budget
+- Budget exhaustion → suggest adding edge transforms (select, compact, truncate)
+- Node failures → suggest adding on_failure: retry(N)
+- Type mismatches → check the node's prompt and produces schema
+
+Apply the suggested fixes to the .gft file, then run \`graft compile\` and \`graft run\` again.
+
+${gftSpec}
 `);
     console.log(`\nCreated ${name}/`);
-    console.log(`  pipeline.gft`);
+    console.log(`  pipeline.gft       — starter pipeline template`);
+    console.log(`  .claude/CLAUDE.md  — Graft spec for Claude Code`);
     console.log(`\nNext steps:`);
     console.log(`  cd ${name}`);
     console.log(`  graft compile pipeline.gft`);
-    console.log(`  # Open in Claude Code to run the pipeline`);
+    console.log(`  # Open in Claude Code — it already knows .gft syntax`);
     console.log('');
 });
 program
@@ -290,6 +350,146 @@ program
     }
     console.log(lines.join('\n'));
 });
+program
+    .command('fmt')
+    .description('Format .gft source file')
+    .argument('<file>', '.gft source file')
+    .option('--check', 'check if file is already formatted (exit 1 if not)')
+    .option('-w, --write', 'write formatted output back to the file')
+    .action((file, opts) => {
+    const source = readSource(file);
+    const result = compileToProgram(source, path.resolve(file));
+    if (!result.success || !result.program) {
+        console.error('\n✗ Parse failed:\n');
+        for (const err of result.errors) {
+            console.error(err.format(source, file));
+            console.error('');
+        }
+        process.exit(1);
+    }
+    const formatted = formatProgram(result.program);
+    if (opts.check) {
+        if (source === formatted) {
+            console.log(`✓ ${file} is already formatted`);
+        }
+        else {
+            console.log(`✗ ${file} needs formatting`);
+            process.exit(1);
+        }
+        return;
+    }
+    if (opts.write) {
+        fs.writeFileSync(path.resolve(file), formatted, 'utf-8');
+        console.log(`✓ Formatted ${file}`);
+        return;
+    }
+    // Default: print to stdout
+    process.stdout.write(formatted);
+});
+program
+    .command('test')
+    .description('Test a .gft pipeline with mock data (dry-run + validation)')
+    .argument('<file>', '.gft source file')
+    .option('--input <json>', 'input JSON string or file path')
+    .option('--verbose', 'print detailed node outputs')
+    .action(async (file, opts) => {
+    const { runTest } = await import('./test-runner.js');
+    const source = readSource(file);
+    let input;
+    if (opts.input) {
+        // Try as JSON string first, then as file path
+        try {
+            input = JSON.parse(opts.input);
+        }
+        catch {
+            const inputPath = path.resolve(opts.input);
+            if (fs.existsSync(inputPath)) {
+                try {
+                    input = JSON.parse(fs.readFileSync(inputPath, 'utf-8'));
+                }
+                catch (e) {
+                    console.error(`Error: failed to parse input file: ${e instanceof Error ? e.message : String(e)}`);
+                    process.exit(1);
+                }
+            }
+            else {
+                console.error(`Error: --input is not valid JSON and file not found: ${opts.input}`);
+                process.exit(1);
+            }
+        }
+    }
+    const result = await runTest({
+        source,
+        sourceFile: path.resolve(file),
+        input,
+        verbose: opts.verbose,
+    });
+    if (result.compileErrors.length > 0) {
+        console.error('\nCompilation failed:');
+        for (const err of result.compileErrors)
+            console.error(`  ${err}`);
+        process.exit(1);
+    }
+    console.log(`\nTest input: ${JSON.stringify(result.inputUsed)}`);
+    console.log('');
+    let allPassed = true;
+    for (const nr of result.nodeResults) {
+        const status = nr.passed ? 'PASS' : 'FAIL';
+        const icon = nr.passed ? '+' : 'x';
+        console.log(`  [${icon}] ${nr.node.padEnd(20)} ${status}`);
+        if (!nr.passed) {
+            allPassed = false;
+            for (const err of nr.validationErrors) {
+                console.log(`      ${err}`);
+            }
+        }
+        if (opts.verbose && nr.output) {
+            console.log(`      output: ${JSON.stringify(nr.output)}`);
+        }
+    }
+    console.log('');
+    if (allPassed) {
+        console.log(`All ${result.nodeResults.length} nodes passed validation.`);
+    }
+    else {
+        const failed = result.nodeResults.filter(r => !r.passed).length;
+        console.log(`${failed} of ${result.nodeResults.length} nodes failed validation.`);
+        process.exit(1);
+    }
+    console.log('');
+});
+program
+    .command('generate')
+    .description('Generate .gft from a natural language description (requires Claude Code CLI)')
+    .argument('<description>', 'what the pipeline should do')
+    .option('--output <file>', 'write .gft to file (default: stdout)')
+    .action(async (description, opts) => {
+    const { generateGft } = await import('./generator.js');
+    try {
+        const result = await generateGft(description, { output: opts.output });
+        if (result.errors.length > 0) {
+            console.error('\nGeneration completed with validation errors:\n');
+            for (const err of result.errors) {
+                console.error(err.format(result.source, 'generated.gft'));
+                console.error('');
+            }
+            console.error('--- Raw output (fix manually) ---\n');
+            console.log(result.source);
+            process.exit(1);
+        }
+        if (opts.output) {
+            fs.writeFileSync(path.resolve(opts.output), result.source, 'utf-8');
+            console.error(`✓ Generated ${opts.output}`);
+        }
+        else {
+            process.stdout.write(result.source);
+        }
+    }
+    catch (e) {
+        console.error(`Error: ${e instanceof Error ? e.message : String(e)}`);
+        process.exit(1);
+    }
+});
 function formatExprForMermaid(expr) {
     if (expr.kind === 'binary') {
         const left = expr.left.kind === 'field_access' ? expr.left.segments[0] : '?';

package/dist/runner.d.ts

@@ -1,5 +1,8 @@
 import { RunResult, SpawnerFn } from './runtime/executor.js';
+import { Program } from './parser/ast.js';
 export type { RunResult, RunOptions, SpawnerFn } from './runtime/executor.js';
+/** Get the Program from the last run() call (for validation/feedback). */
+export declare function getProgram(): Program | undefined;
 export interface RunInput {
     sourceFile: string;
     inputFile?: string;

package/dist/runner.js

@@ -2,6 +2,11 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { compile } from './compiler.js';
 import { Executor } from './runtime/executor.js';
+let _lastProgram;
+/** Get the Program from the last run() call (for validation/feedback). */
+export function getProgram() {
+    return _lastProgram;
+}
 export async function run(opts) {
     const sourceFile = path.resolve(opts.sourceFile);
     if (!fs.existsSync(sourceFile)) {
@@ -11,8 +16,10 @@ export async function run(opts) {
     const workDir = opts.workDir ?? path.dirname(sourceFile);
     const compileResult = compile(source, sourceFile);
     if (!compileResult.success || !compileResult.program) {
+        _lastProgram = undefined;
         return { success: false, graph: '', nodeResults: [], finalOutput: null, totalDurationMs: 0, errors: compileResult.errors.map(e => e.message) };
     }
+    _lastProgram = compileResult.program;
     const programIndex = compileResult.index;
     let input;
     if (opts.input) {

package/dist/runtime/feedback.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Feedback generator — produces .gft modification suggestions from quality reports.
+ */
+import { Program } from '../parser/ast.js';
+import { QualityReport } from './result-validator.js';
+export interface Suggestion {
+    type: 'budget' | 'retry' | 'transform' | 'schema';
+    severity: 'info' | 'warning' | 'error';
+    node: string;
+    message: string;
+    fix?: string;
+}
+/**
+ * Generate .gft modification suggestions from a quality report.
+ */
+export declare function generateFeedback(report: QualityReport, program: Program): Suggestion[];
+/**
+ * Format suggestions for human-readable output.
+ */
+export declare function formatSuggestions(suggestions: Suggestion[]): string;

package/dist/runtime/feedback.js

@@ -0,0 +1,152 @@
+import { ProgramIndex } from '../program-index.js';
+/**
+ * Generate .gft modification suggestions from a quality report.
+ */
+export function generateFeedback(report, program) {
+    const suggestions = [];
+    const index = new ProgramIndex(program);
+    for (const check of report.checks) {
+        if (check.status === 'pass')
+            continue;
+        const suggestion = checkToSuggestion(check, index);
+        if (suggestion)
+            suggestions.push(suggestion);
+    }
+    return suggestions;
+}
+function checkToSuggestion(check, index) {
+    switch (check.category) {
+        case 'budget':
+            return budgetSuggestion(check, index);
+        case 'empty':
+            return emptySuggestion(check, index);
+        case 'schema':
+            return schemaSuggestion(check, index);
+        case 'type':
+            return typeSuggestion(check);
+        case 'range':
+            return rangeSuggestion(check);
+        default:
+            return null;
+    }
+}
+function budgetSuggestion(check, index) {
+    if (check.status === 'fail') {
+        // Budget nearly exhausted — suggest adding edge transforms
+        const edges = [...index.edgesBySource.entries()];
+        const edgeHints = edges.length > 0
+            ? `Add edge transforms to reduce token flow. Example:\n  edge ${edges[0][0]} -> ... | truncate(500)`
+            : 'Increase graph budget or reduce node budgets.';
+        return {
+            type: 'transform',
+            severity: 'error',
+            node: '*',
+            message: 'Token budget nearly exhausted.',
+            fix: edgeHints,
+        };
+    }
+    return {
+        type: 'budget',
+        severity: 'warning',
+        node: '*',
+        message: 'Token budget usage is high. Consider adding compact or truncate transforms.',
+    };
+}
+function emptySuggestion(check, index) {
+    const nodeDecl = check.node !== '*' ? index.nodeMap.get(check.node) : undefined;
+    if (nodeDecl) {
+        const currentOut = nodeDecl.budgetOut;
+        const suggestedOut = currentOut * 2;
+        return {
+            type: 'budget',
+            severity: 'warning',
+            node: check.node,
+            message: `Field '${check.field}' is empty. The node may need more output tokens.`,
+            fix: `Increase ${check.node} output budget: budget: ${formatTokens(nodeDecl.budgetIn)}/${formatTokens(suggestedOut)}`,
+        };
+    }
+    return {
+        type: 'budget',
+        severity: 'warning',
+        node: check.node,
+        message: `Field '${check.field}' is empty.`,
+    };
+}
+function schemaSuggestion(check, index) {
+    if (check.message.includes('failed') || check.message.includes('Failed')) {
+        const nodeDecl = check.node !== '*' ? index.nodeMap.get(check.node) : undefined;
+        if (nodeDecl && !nodeDecl.onFailure) {
+            return {
+                type: 'retry',
+                severity: 'error',
+                node: check.node,
+                message: `Node '${check.node}' failed. Add a failure strategy.`,
+                fix: `Add to ${check.node}: on_failure: retry(2)`,
+            };
+        }
+        return {
+            type: 'retry',
+            severity: 'error',
+            node: check.node,
+            message: `Node '${check.node}' failed.`,
+        };
+    }
+    if (check.message.includes('Missing field')) {
+        return {
+            type: 'schema',
+            severity: 'error',
+            node: check.node,
+            message: check.message,
+            fix: `Check that ${check.node}'s prompt clearly requests the '${check.field}' field in its output.`,
+        };
+    }
+    if (check.message.includes('null')) {
+        return {
+            type: 'schema',
+            severity: 'error',
+            node: check.node,
+            message: `Node '${check.node}' produced null output. It may have silently failed.`,
+            fix: `Add to ${check.node}: on_failure: retry(2)`,
+        };
+    }
+    return null;
+}
+function typeSuggestion(check) {
+    return {
+        type: 'schema',
+        severity: 'error',
+        node: check.node,
+        message: `Type mismatch in ${check.node}.${check.field}: ${check.message}`,
+    };
+}
+function rangeSuggestion(check) {
+    return {
+        type: 'schema',
+        severity: 'error',
+        node: check.node,
+        message: `Range violation in ${check.node}.${check.field}: ${check.message}`,
+    };
+}
+function formatTokens(n) {
+    if (n >= 1000)
+        return `${Math.round(n / 1000)}k`;
+    return String(n);
+}
+/**
+ * Format suggestions for human-readable output.
+ */
+export function formatSuggestions(suggestions) {
+    if (suggestions.length === 0)
+        return '';
+    const lines = [];
+    lines.push('\n\u2500\u2500 Suggestions ' + '\u2500'.repeat(35));
+    for (const s of suggestions) {
+        const icon = s.severity === 'error' ? '\u2717' : s.severity === 'warning' ? '\u26a0' : '\u2139';
+        lines.push(`  ${icon} ${s.message}`);
+        if (s.fix) {
+            lines.push(`    \u2192 ${s.fix}`);
+        }
+    }
+    lines.push('\u2500'.repeat(48));
+    return lines.join('\n');
+}

package/dist/runtime/result-formatter.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Result formatter — formats RunResult into human-readable output.
+ */
+import { RunResult } from './executor.js';
+import { Program } from '../parser/ast.js';
+export interface FormatOptions {
+    json?: boolean;
+    verbose?: boolean;
+}
+/**
+ * Format a RunResult for human-readable CLI output.
+ */
+export declare function formatRunResult(result: RunResult, program?: Program, options?: FormatOptions): string;

package/dist/runtime/result-formatter.js

@@ -0,0 +1,142 @@
+import { ProgramIndex } from '../program-index.js';
+/**
+ * Format a RunResult for human-readable CLI output.
+ */
+export function formatRunResult(result, program, options) {
+    if (options?.json) {
+        return JSON.stringify({
+            success: result.success,
+            graph: result.graph,
+            duration_ms: result.totalDurationMs,
+            nodes: result.nodeResults.map(nr => ({
+                node: nr.node,
+                success: nr.success,
+                duration_ms: nr.durationMs,
+                tokens: nr.tokenUsage
+                    ? { input: nr.tokenUsage.inputTokens, output: nr.tokenUsage.outputTokens }
+                    : undefined,
+                error: nr.error,
+            })),
+            token_usage: result.tokenUsage,
+            output: result.finalOutput,
+            errors: result.errors,
+        }, null, 2);
+    }
+    const lines = [];
+    const durationSec = (result.totalDurationMs / 1000).toFixed(1);
+    if (result.success) {
+        lines.push(`Graph '${result.graph}' completed in ${durationSec}s\n`);
+    }
+    else {
+        lines.push(`Graph '${result.graph}' FAILED after ${durationSec}s\n`);
+    }
+    // Node results table
+    const index = program ? new ProgramIndex(program) : undefined;
+    for (const nr of result.nodeResults) {
+        const icon = nr.success ? '\u2713' : '\u2717';
+        const nodeName = nr.node.padEnd(20);
+        const model = getModelShortName(nr.node, index);
+        const modelStr = model.padEnd(8);
+        const duration = `${(nr.durationMs / 1000).toFixed(1)}s`.padStart(6);
+        const tokens = formatNodeTokens(nr);
+        lines.push(`  ${icon} ${nodeName} ${modelStr} ${duration}  ${tokens}`);
+        if (!nr.success && nr.error) {
+            lines.push(`    Error: ${nr.error}`);
+        }
+    }
+    // Token usage summary
+    if (result.tokenUsage) {
+        const { budget, consumed, fraction } = result.tokenUsage;
+        const pct = Math.round(fraction * 100);
+        const bar = renderBar(fraction, 30);
+        lines.push('');
+        lines.push(`Token usage: ${consumed.toLocaleString()} / ${budget.toLocaleString()} (${pct}%)`);
+        lines.push(`  ${bar}`);
+        if (fraction > 0.9) {
+            lines.push('  \u26a0 WARNING: >90% of budget consumed');
+        }
+    }
+    // Final output summary
+    if (result.finalOutput !== null && result.finalOutput !== undefined) {
+        lines.push('');
+        const outputName = getOutputName(result, program);
+        lines.push(`\u2500\u2500 Final Output (${outputName}) ${'─'.repeat(Math.max(0, 40 - outputName.length))}`);
+        lines.push(formatOutput(result.finalOutput, options?.verbose));
+        lines.push('─'.repeat(48));
+    }
+    // Errors
+    if (result.errors.length > 0) {
+        lines.push('');
+        lines.push('Errors:');
+        for (const err of result.errors) {
+            lines.push(`  \u2717 ${err}`);
+        }
+    }
+    return lines.join('\n');
+}
+function getModelShortName(nodeName, index) {
+    if (!index)
+        return '';
+    const node = index.nodeMap.get(nodeName);
+    if (!node)
+        return '';
+    return node.model;
+}
+function formatNodeTokens(nr) {
+    if (!nr.tokenUsage)
+        return '';
+    const total = nr.tokenUsage.inputTokens + nr.tokenUsage.outputTokens;
+    return `${total.toLocaleString()} tok`;
+}
+function renderBar(fraction, width) {
+    const filled = Math.round(fraction * width);
+    const empty = width - filled;
+    const bar = '\u2588'.repeat(filled) + '\u2591'.repeat(empty);
+    return `[${bar}]`;
+}
+function getOutputName(result, program) {
+    if (program && program.graphs.length > 0) {
+        return program.graphs[0].output;
+    }
+    return 'Result';
+}
+function formatOutput(output, verbose) {
+    if (output === null || output === undefined)
+        return '  (empty)';
+    if (typeof output === 'string') {
+        return verbose ? output : truncate(output, 200);
+    }
+    if (typeof output !== 'object') {
+        return String(output);
+    }
+    const lines = [];
+    const obj = output;
+    for (const [key, value] of Object.entries(obj)) {
+        if (Array.isArray(value)) {
+            lines.push(`  ${key}: ${value.length} items`);
+            if (verbose) {
+                for (const item of value.slice(0, 5)) {
+                    lines.push(`    - ${truncate(String(item), 100)}`);
+                }
+                if (value.length > 5)
+                    lines.push(`    ... and ${value.length - 5} more`);
+            }
+        }
+        else if (typeof value === 'object' && value !== null) {
+            const keys = Object.keys(value);
+            lines.push(`  ${key}: {${keys.length} fields}`);
+        }
+        else if (typeof value === 'string') {
+            lines.push(`  ${key}: ${truncate(value, verbose ? 500 : 80)}`);
+        }
+        else {
+            lines.push(`  ${key}: ${value}`);
+        }
+    }
+    return lines.join('\n');
+}
+function truncate(s, max) {
+    if (s.length <= max)
+        return s;
+    return s.slice(0, max - 3) + '...';
+}