@jsleekr/graft 5.8.0 → 6.0.0

package/README.md

@@ -4,104 +4,54 @@
 
 # Graft
 
-**Define multi-agent pipelines in 10 lines. Compile to Claude Code in 1 second.**
+**Infrastructure as Code for Claude Code multi-agent pipelines.**
 
-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.
+Write `.gft` files to define multi-agent pipelines. The compiler generates `.claude/` harness structures — agents, hooks, orchestration plans, settings — with compile-time token budget analysis.
 
-## 10-Minute Getting Started
+**[Documentation](https://jsleekr.github.io/graft/)** | **[User Guide](docs/guide.md)** | **[Examples](examples/)**
 
-### 1. Install
-
-```bash
-npm install -g @jsleekr/graft
-```
-
-Requires Node.js 20+.
+---
 
-### 2. Create a project
+## Getting Started (5 minutes)
 
-```bash
-graft init my-pipeline
-cd my-pipeline
-```
+### Prerequisites
 
-This creates `pipeline.gft` — a simple two-node pipeline ready to compile.
+- [Node.js 20+](https://nodejs.org)
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated
 
-### 3. Compile
+### Step 1: Install Graft
 
 ```bash
-graft compile pipeline.gft
-```
-
-Output:
-
-```
-✓ Parse OK
-✓ Scope check OK
-✓ Type check OK
-✓ Token analysis:
-    Analyst              in ~   500  out ~ 2,000
-    Reviewer             in ~   840  out ~ 1,000
-    Best path:     4,340 tokens ✓ within budget (10,000)
-
-Generated:
-  .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
+npm install -g @jsleekr/graft
 ```
 
-### 4. Run in Claude Code
+### Step 2: Create a project
 
 ```bash
-# Create input
-echo '{"question": "What is Graft?"}' > .graft/session/input.json
-
-# Open in Claude Code
-claude
+graft init my-pipeline
+cd my-pipeline
 ```
 
-Then tell Claude Code:
-
-> `.claude/CLAUDE.md`의 실행 계획을 따라서 파이프라인을 실행해줘. 입력은 `.graft/session/input.json`에 있어.
-
-Claude Code reads the generated `.claude/` structure and runs the pipeline automatically.
+This creates:
+- `pipeline.gft` — a starter two-node pipeline
+- `.claude/CLAUDE.md` — the .gft language spec, so Claude Code natively understands Graft
 
-### 5. Check the results
+### Step 3: Open Claude Code and just talk
 
 ```bash
-cat .graft/session/node_outputs/reviewer.json
-```
-
-That's it. You have a working multi-agent pipeline.
-
----
-
-## How It Works
-
-```
-.gft Source  →  Graft Compiler  →  .claude/ output  →  Claude Code runs it
+claude
 ```
 
-| Graft Source | Generated Output | Purpose |
-|-------------|-----------------|---------|
-| `node` | `.claude/agents/*.md` | Agent with model, tools, output schema |
-| `edge \| transform` | `.claude/hooks/*.js` | Node.js data transform between nodes |
-| `graph` | `.claude/CLAUDE.md` | Step-by-step orchestration plan |
-| `memory` | `.graft/memory/*.json` | Persistent state across runs |
-| config | `.claude/settings.json` | Model routing, budget, hook registration |
-
-## Why Graft?
+Then say:
 
-Multi-agent systems waste tokens passing full context between agents. Graft fixes this:
+> "I want a code review pipeline where security, logic, and performance reviewers run in parallel, then a senior reviewer synthesizes everything."
 
-- **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 between agents
-- **Explicit `reads`** declarations prevent context leaks — the compiler verifies scope
+**Claude Code already knows .gft syntax** (from `.claude/CLAUDE.md`). It will:
+1. Write a `.gft` file for you
+2. Run `graft compile` to generate the harness
+3. You're done
 
-## Example: Code Review Pipeline
+### Step 4: Or write .gft yourself
 
 ```graft
 context PullRequest(max_tokens: 2k) {
@@ -113,7 +63,7 @@ node SecurityReviewer(model: sonnet, budget: 4k/2k) {
   reads: [PullRequest]
   produces SecurityAnalysis {
     vulnerabilities: List<String>
-    risk_level: enum(low, medium, high, critical)
+    risk_level: String
   }
 }
 
@@ -143,9 +93,62 @@ graph CodeReview(input: PullRequest, output: FinalReview, budget: 25k) {
 }
 ```
 
-This compiles to 3 agents running in parallel, with edge transforms that strip unnecessary data before the senior review.
+Compile it:
 
-## Language Features
+```bash
+graft compile code-review.gft
+```
+
+The compiler generates agents, hooks, orchestration plan, and settings — ready for Claude Code.
+
+---
+
+## How It Works
+
+```
+You describe what you want (natural language or .gft)
+    ↓
+Claude Code writes/edits .gft files (it knows the syntax from CLAUDE.md)
+    ↓
+graft compile → .claude/ output (agents, hooks, settings)
+    ↓
+Claude Code reads the .claude/ structure and runs the pipeline
+```
+
+| Graft Source | Generated Output | Purpose |
+|-------------|-----------------|---------|
+| `node` | `.claude/agents/*.md` | Agent with model, tools, output schema |
+| `edge \| transform` | `.claude/hooks/*.js` | Data transform between nodes |
+| `graph` | `.claude/CLAUDE.md` | Step-by-step orchestration plan |
+| `memory` | `.graft/memory/*.json` | Persistent state across runs |
+| config | `.claude/settings.json` | Model routing, budget, hook registration |
+
+## Why Graft?
+
+**For humans**: Write 72 lines of `.gft` instead of manually maintaining 9 generated files (13KB+). ~8x compression ratio.
+
+**For LLMs**: Claude Code reads 400 tokens of `.gft` instead of 3,300 tokens of scattered config. Modifications are single-file edits with compiler-guaranteed consistency.
+
+- **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 between agents
+- **Scope checking** — the compiler verifies every `reads` reference at compile time
+
+## CLI
+
+```bash
+graft init <name>                            # Scaffold project + inject CLAUDE.md spec
+graft compile <file.gft> [--out-dir <dir>]   # Compile to .claude/ harness
+graft check <file.gft>                       # Parse + analyze only
+graft run <file.gft> --input <json>          # Compile and execute
+graft test <file.gft> [--input <json>]       # Test with mock data
+graft fmt <file.gft> [-w]                    # Format .gft source
+graft generate <desc> [--output <file>]      # Generate .gft via Claude Code CLI
+graft watch <file.gft>                       # Watch and recompile on changes
+graft visualize <file.gft>                   # Pipeline DAG as Mermaid diagram
+```
+
+## Language Reference
 
 ### Contexts and Nodes
 
@@ -175,6 +178,16 @@ edge Analyzer -> Reviewer
   | compact
 ```
 
+### Conditional Routing
+
+```graft
+edge RiskAssessor -> {
+  when risk_score > 0.7 -> DetailedReviewer
+  when risk_score > 0.3 -> StandardReviewer
+  else -> AutoApprove
+}
+```
+
 ### Flow Control
 
 ```graft
@@ -185,72 +198,35 @@ graph Pipeline(input: TaskSpec, output: Report, budget: 35k) {
 }
 ```
 
-Also supports: `foreach`, `let` variables with expressions, parameterized sub-graphs, conditional edge routing.
+Also supports: `foreach`, `let` variables with expressions, parameterized sub-graphs, `import`.
 
-### Imports and Memory
+### Memory
 
 ```graft
-import { UserMessage, SystemConfig } from "./shared.gft"
-
 memory ConversationLog(max_tokens: 2k, storage: file) {
   turns: List<Turn { role: String, content: String }>
   summary: Optional<String>
 }
-
-node Responder(model: sonnet, budget: 4k/2k) {
-  reads: [UserMessage, SystemConfig, ConversationLog]
-  writes: [ConversationLog.turns]
-  produces Response { reply: String }
-}
-```
-
-### Expressions
-
-```graft
-A -> let score = A.risk_score * 2
-   -> let label = "Found ${len(A.items)} items"
-   -> let safe = score >= 50 && score <= 100
-   -> let fallback = A.name ?? "unknown"
-   -> B -> done
 ```
 
-### Type System
+## Execution Model
 
-```
-String, Int, Float, Float(0..1), Bool       // primitives
-List<T>, Map<K, V>, Optional<T>             // collections
-TokenBounded<String, 100>                   // token-bounded types
-enum(low, medium, high)                     // inline enums
-Issue { file: FilePath, severity: ... }     // inline structs
-```
+Graft is a **compiler**, not a runtime orchestrator.
 
-## CLI
+1. **`.claude/CLAUDE.md`** — natural-language execution plan. Claude Code reads it as instructions.
+2. **`.claude/hooks/*.js`** — PostToolUse hooks that fire automatically. Edge transforms run deterministically.
+3. **`.claude/settings.json`** — model routing and hook registration.
 
-```bash
-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
-
-```typescript
-import { compile } from '@jsleekr/graft/compiler';
-import { Executor } from '@jsleekr/graft/runtime';
-import type { Program } from '@jsleekr/graft/types';
+`graft run` spawns Claude Code subprocesses per node. The orchestration depends on Claude Code's instruction-following — unlike LangGraph or CrewAI which use deterministic state machines.
 
-const result = compile(source, 'pipeline.gft');
-if (result.success) {
-  console.log(`Parsed ${result.program.nodes.length} nodes`);
-}
-```
+## Limitations
 
-## Editor Support
+- **Non-deterministic orchestration** — `CLAUDE.md` is an LLM prompt, not a state machine
+- **Claude Code dependency** — generates `.claude/` structures only
+- **Single provider** — Anthropic models only (multi-provider planned)
+- **Memory** — JSON file storage only (other backends planned)
 
-The [Graft VS Code extension](editors/vscode/) provides syntax highlighting, real-time diagnostics, hover, go-to-definition, find references, rename, completions, and code actions.
+See `SPECIFICATION.md` for planned features.
 
 ## Development
 
@@ -258,7 +234,7 @@ The [Graft VS Code extension](editors/vscode/) provides syntax highlighting, rea
 git clone https://github.com/JSLEEKR/graft.git
 cd graft && npm install
 npm run build         # Compile TypeScript
-npm test              # Run all 1,574 tests
+npm test              # Run all 1,712 tests
 ```
 
 ## License

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

@@ -0,0 +1,17 @@
+import { NodeDecl, EdgeDecl } from '../parser/ast.js';
+import { CodegenBackend, CodegenContext } from './backend.js';
+/**
+ * GenericBackend — a tool-agnostic codegen backend.
+ *
+ * Produces markdown agent files, JS hook stubs, and JSON settings
+ * that are not tied to any specific AI coding assistant.
+ * This is groundwork for future Cursor / Windsurf / Copilot support.
+ */
+export declare class GenericBackend implements CodegenBackend {
+    readonly name = "generic";
+    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/generic-backend.js

@@ -0,0 +1,156 @@
+import { fieldsToJsonExample } from '../utils.js';
+import { MODEL_MAP } from '../constants.js';
+import { VERSION } from '../version.js';
+/**
+ * GenericBackend — a tool-agnostic codegen backend.
+ *
+ * Produces markdown agent files, JS hook stubs, and JSON settings
+ * that are not tied to any specific AI coding assistant.
+ * This is groundwork for future Cursor / Windsurf / Copilot support.
+ */
+export class GenericBackend {
+    name = 'generic';
+    generateAgent(node, memoryNames, ctx) {
+        const name = node.name.toLowerCase();
+        const resolvedModel = MODEL_MAP[node.model] || node.model;
+        const jsonSchema = fieldsToJsonExample(node.produces.fields);
+        const readsList = node.reads
+            .map(r => `- ${r.context}${r.field && r.field.length > 0 ? ` (fields: ${r.field.join(', ')})` : ''}`)
+            .join('\n');
+        const toolsList = node.tools.length > 0
+            ? `\n## Tools\n${node.tools.map(t => `- ${t}`).join('\n')}\n`
+            : '';
+        return `# ${node.name} Agent
+
+## Metadata
+- **name**: ${name}
+- **model**: ${resolvedModel}
+- **produces**: ${node.produces.name}
+
+## Reads
+${readsList || '(none)'}
+${toolsList}
+## Output Schema
+\`\`\`json
+${JSON.stringify(jsonSchema, null, 2)}
+\`\`\`
+
+## Instructions
+Execute the ${node.name} step of the pipeline.
+Read the specified inputs, perform your task, and produce output matching the schema above.
+Write your output as JSON to: .graft/session/node_outputs/${name}.json
+`;
+    }
+    generateHook(edge, _ctx) {
+        if (edge.transforms.length === 0)
+            return null;
+        if (edge.target.kind !== 'direct')
+            return null;
+        const source = edge.source.toLowerCase();
+        const target = edge.target.node.toLowerCase();
+        const transformNames = edge.transforms.map(t => t.type).join(', ');
+        return `// Hook: ${edge.source} -> ${edge.target.node}
+// Transforms: ${transformNames}
+// Generated by Graft (generic backend)
+
+import * as fs from 'node:fs';
+
+const inputPath = '.graft/session/node_outputs/${source}.json';
+const outputPath = '.graft/session/node_outputs/${source}_to_${target}.json';
+
+const raw = JSON.parse(fs.readFileSync(inputPath, 'utf-8'));
+
+// TODO: Implement transforms: ${transformNames}
+const result = raw;
+
+fs.writeFileSync(outputPath, JSON.stringify(result, null, 2));
+`;
+    }
+    generateConditionalHook(edge, _ctx) {
+        if (edge.target.kind !== 'conditional')
+            return null;
+        const source = edge.source.toLowerCase();
+        const branches = edge.target.branches;
+        const branchLines = branches.map(b => {
+            const condition = b.condition ? `/* condition */` : `/* else */`;
+            return `  ${condition} '${b.target}'`;
+        }).join(',\n');
+        return `// Router: ${edge.source} -> conditional
+// Generated by Graft (generic backend)
+
+import * as fs from 'node:fs';
+
+const inputPath = '.graft/session/node_outputs/${source}.json';
+const routingPath = '.graft/session/routing/${source}_route.json';
+
+const data = JSON.parse(fs.readFileSync(inputPath, 'utf-8'));
+
+// TODO: Implement conditional routing logic
+const routes = [
+${branchLines}
+];
+
+const selectedRoute = routes[routes.length - 1]; // default: last (else) branch
+fs.writeFileSync(routingPath, JSON.stringify({ route: selectedRoute }, null, 2));
+`;
+    }
+    generateOrchestration(ctx) {
+        const graph = ctx.program.graphs[0];
+        const graphName = graph?.name ?? 'pipeline';
+        const nodes = ctx.program.nodes.map(n => n.name);
+        const flowSteps = graph?.flow.map(step => {
+            if (step.kind === 'node')
+                return `1. Run **${step.name}**`;
+            if (step.kind === 'parallel')
+                return `1. Run in parallel: ${step.branches.join(', ')}`;
+            return '';
+        }).filter(Boolean).join('\n') ?? '';
+        return `# ${graphName} — Orchestration
+
+> Generated by Graft v${VERSION} (generic backend)
+> Source: ${ctx.sourceFile}
+
+## Pipeline Flow
+${flowSteps}
+
+## Nodes
+${nodes.map(n => `- ${n}`).join('\n')}
+
+## Runtime
+This pipeline was compiled with the generic backend.
+To execute, run each node in order according to the flow above,
+passing outputs between nodes via .graft/session/node_outputs/.
+`;
+    }
+    generateSettings(ctx) {
+        const graph = ctx.program.graphs[0];
+        const firstNode = ctx.program.nodes[0];
+        const defaultModel = firstNode
+            ? (MODEL_MAP[firstNode.model] || firstNode.model)
+            : 'default';
+        const overrides = {};
+        for (const node of ctx.program.nodes) {
+            overrides[node.name] = MODEL_MAP[node.model] || node.model;
+        }
+        return {
+            graft: {
+                version: VERSION,
+                backend: 'generic',
+                source: ctx.sourceFile,
+                compiled_at: new Date().toISOString(),
+                budget: {
+                    total: graph?.budget ?? 0,
+                },
+                model_routing: {
+                    default: defaultModel,
+                    overrides,
+                },
+                nodes: ctx.program.nodes.map(n => n.name),
+                edges: ctx.program.edges.map(e => ({
+                    source: e.source,
+                    target: e.target.kind === 'direct' ? e.target.node : 'conditional',
+                })),
+            },
+        };
+    }
+}

package/dist/compiler.d.ts

@@ -3,6 +3,7 @@ import { GeneratedFile } from './codegen/codegen.js';
 import { GraftError } from './errors/diagnostics.js';
 import { Program } from './parser/ast.js';
 import { ProgramIndex } from './program-index.js';
+import { CodegenBackend } from './codegen/backend.js';
 export interface ProgramResult {
     success: boolean;
     program?: Program;
@@ -15,7 +16,7 @@ export interface CompileResult extends ProgramResult {
     files?: GeneratedFile[];
 }
 export declare function compileToProgram(source: string, sourceFile: string): ProgramResult;
-export declare function compileAndGenerate(source: string, sourceFile: string): CompileResult;
+export declare function compileAndGenerate(source: string, sourceFile: string, backend?: CodegenBackend): CompileResult;
 /** Backward-compatible alias for compileAndGenerate */
-export declare function compile(source: string, sourceFile: string): CompileResult;
-export declare function compileAndWrite(source: string, sourceFile: string, outDir: string): CompileResult;
+export declare function compile(source: string, sourceFile: string, backend?: CodegenBackend): CompileResult;
+export declare function compileAndWrite(source: string, sourceFile: string, outDir: string, backend?: CodegenBackend): CompileResult;

package/dist/compiler.js

@@ -68,7 +68,7 @@ export function compileToProgram(source, sourceFile) {
     warnings.push(...report.warnings);
     return { success: true, program, index, report, errors, warnings };
 }
-export function compileAndGenerate(source, sourceFile) {
+export function compileAndGenerate(source, sourceFile, backend) {
     const result = compileToProgram(source, sourceFile);
     if (!result.success || !result.program) {
         return result;
@@ -85,15 +85,15 @@ export function compileAndGenerate(source, sourceFile) {
         };
     }
     // Generate
-    const files = generate(result.program, result.report, sourceFile, result.index);
+    const files = generate(result.program, result.report, sourceFile, result.index, backend);
     return { ...result, files };
 }
 /** Backward-compatible alias for compileAndGenerate */
-export function compile(source, sourceFile) {
-    return compileAndGenerate(source, sourceFile);
+export function compile(source, sourceFile, backend) {
+    return compileAndGenerate(source, sourceFile, backend);
 }
-export function compileAndWrite(source, sourceFile, outDir) {
-    const result = compile(source, sourceFile);
+export function compileAndWrite(source, sourceFile, outDir, backend) {
+    const result = compile(source, sourceFile, backend);
     if (result.success && result.files) {
         writeFiles(result.files, outDir);
     }

package/dist/formatter.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Graft AST pretty-printer — formats a Program back to .gft source.
+ */
+import { Program } from './parser/ast.js';
+export declare function formatProgram(program: Program): string;