@jsleekr/graft 6.0.1 → 6.1.0

package/README.md

@@ -8,7 +8,7 @@
 
 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.
 
-**[Documentation](https://jsleekr.github.io/graft/)** | **[User Guide](docs/guide.md)** | **[Examples](examples/)**
+**[Documentation](https://jsleekr.github.io/graft/)** | **[Playground](https://jsleekr.github.io/graft/playground/)** | **[User Guide](docs/guide.md)** | **[Examples](examples/)**
 
 ---
 
@@ -137,7 +137,7 @@ Claude Code reads the .claude/ structure and runs the pipeline
 ## CLI
 
 ```bash
-graft init <name>                            # Scaffold project + inject CLAUDE.md spec
+graft init [name]                            # New project, or add Graft to current dir
 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

package/dist/codegen/codegen.js

@@ -41,9 +41,9 @@ export function generate(program, report, sourceFile, index, backend) {
             }
         }
     }
-    // Orchestration
+    // Orchestration (separate file — does not overwrite CLAUDE.md)
     files.push({
-        path: '.claude/CLAUDE.md',
+        path: '.claude/orchestration.md',
         content: be.generateOrchestration(ctx),
     });
     // Settings

package/dist/index.js

@@ -137,19 +137,23 @@ program
 });
 program
     .command('init')
-    .description('Scaffold a new Graft project')
-    .argument('<name>', 'project name')
+    .description('Scaffold a new Graft project, or add Graft to an existing project')
+    .argument('[name]', 'project name (omit to set up current directory)')
     .action(async (name) => {
-    const dir = path.resolve(name);
-    if (fs.existsSync(dir)) {
-        console.error(`Error: directory '${name}' already exists`);
-        process.exit(1);
+    const isExisting = !name;
+    const dir = name ? path.resolve(name) : process.cwd();
+    if (name) {
+        if (fs.existsSync(dir)) {
+            console.error(`Error: directory '${name}' already exists`);
+            process.exit(1);
+        }
+        fs.mkdirSync(dir, { recursive: true });
     }
-    fs.mkdirSync(dir, { recursive: true });
-    const baseName = path.basename(name);
+    const baseName = path.basename(dir);
     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
+    // Generate pipeline.gft starter template (only for new projects)
+    if (!isExisting) {
+        fs.writeFileSync(path.join(dir, 'pipeline.gft'), `// ${safeName} — a simple two-node pipeline
 
 context Input(max_tokens: 500) {
   question: String
@@ -177,23 +181,30 @@ graph ${safeName}(input: Input, output: Output, budget: 10k) {
   Analyst -> Reviewer -> done
 }
 `);
-    // Generate .claude/CLAUDE.md with .gft spec so Claude Code natively understands Graft
+    }
+    // Generate .claude/ config files
     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}
+    // 1. Write .gft spec to a separate file (never overwritten by compile)
+    const specPath = path.join(claudeDir, 'graft-spec.md');
+    const specContent = `# Graft — .gft Language Reference
 
-This project uses **Graft** (.gft) for defining multi-agent pipelines.
+> Auto-generated by \`graft init\`. This file is the .gft syntax reference
+> that Claude Code reads to understand the Graft language.
+> Do NOT delete this file — \`graft compile\` does not touch it.
 
-## Working with .gft files
+## Graft — Multi-Agent Pipelines
+
+This project uses **Graft** (.gft) for defining multi-agent pipelines.
 
 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
+### CLI Commands
 
 \`\`\`bash
 graft compile <file.gft> [--out-dir <dir>]  # Compile to harness structure
@@ -204,30 +215,47 @@ graft visualize <file.gft>                  # Output pipeline DAG as Mermaid
 graft watch <file.gft>                      # Watch and recompile on changes
 \`\`\`
 
-## After Pipeline Execution
+### After Pipeline Execution
 
-When a pipeline run completes, \`graft run\` automatically:
+\`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       — 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 — it already knows .gft syntax`);
+`;
+    fs.writeFileSync(specPath, specContent);
+    // 2. Add Graft reference to CLAUDE.md (short pointer, not the full spec)
+    const claudeMdPath = path.join(claudeDir, 'CLAUDE.md');
+    const existingClaudeMd = fs.existsSync(claudeMdPath) ? fs.readFileSync(claudeMdPath, 'utf-8') : '';
+    const graftReference = `## Graft
+
+This project uses Graft for multi-agent pipelines. Read \`.claude/graft-spec.md\` for the full .gft syntax reference. Run \`graft compile <file.gft>\` to generate harness files.`;
+    if (existingClaudeMd && existingClaudeMd.includes('graft-spec.md')) {
+        console.log(`  .claude/CLAUDE.md already references Graft — skipped`);
+    }
+    else if (existingClaudeMd) {
+        fs.writeFileSync(claudeMdPath, existingClaudeMd.trimEnd() + '\n\n' + graftReference + '\n');
+    }
+    else {
+        fs.writeFileSync(claudeMdPath, `# ${safeName}\n\n` + graftReference + '\n');
+    }
+    if (isExisting) {
+        console.log(`\nGraft added to current project.`);
+        console.log(`  .claude/CLAUDE.md  — Graft spec injected`);
+        console.log(`\nNext steps:`);
+        console.log(`  # Write a .gft file, or open Claude Code — it already knows .gft syntax`);
+        console.log(`  graft compile <file.gft>`);
+    }
+    else {
+        console.log(`\nCreated ${name}/`);
+        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 — it already knows .gft syntax`);
+    }
     console.log('');
 });
 program

package/dist/playground-entry.d.ts

@@ -0,0 +1,26 @@
+import { TokenReport } from './analyzer/estimator.js';
+import { Program } from './parser/ast.js';
+import { GeneratedFile } from './codegen/codegen.js';
+export interface PlaygroundResult {
+    success: boolean;
+    program?: Program;
+    report?: TokenReport;
+    files?: GeneratedFile[];
+    errors: Array<{
+        message: string;
+        line: number;
+        column: number;
+        severity: string;
+        code?: string;
+        formatted: string;
+    }>;
+    warnings: Array<{
+        message: string;
+        line: number;
+        column: number;
+        severity: string;
+        code?: string;
+        formatted: string;
+    }>;
+}
+export declare function compilePlayground(source: string, filename?: string): PlaygroundResult;

package/dist/playground-entry.js

@@ -0,0 +1,93 @@
+/**
+ * Browser entry point for the Graft playground.
+ * Exports only the compiler pipeline (no fs, no runtime, no CLI).
+ */
+import { Lexer } from './lexer/lexer.js';
+import { Parser } from './parser/parser.js';
+import { ScopeChecker } from './analyzer/scope.js';
+import { TypeChecker } from './analyzer/types.js';
+import { TokenEstimator } from './analyzer/estimator.js';
+import { GraftError } from './errors/diagnostics.js';
+import { ProgramIndex } from './program-index.js';
+import { generate } from './codegen/codegen.js';
+function serializeDiagnostic(e, source, filename) {
+    return {
+        message: e.message,
+        line: e.location.line,
+        column: e.location.column,
+        severity: e.severity,
+        code: e.code,
+        formatted: e.format(source, filename),
+    };
+}
+export function compilePlayground(source, filename = 'playground.gft') {
+    const errors = [];
+    const warnings = [];
+    // Lex
+    let tokens;
+    try {
+        const lexer = new Lexer(source);
+        tokens = lexer.tokenize();
+    }
+    catch (e) {
+        if (e instanceof GraftError) {
+            return {
+                success: false,
+                errors: [serializeDiagnostic(e, source, filename)],
+                warnings: [],
+            };
+        }
+        throw e;
+    }
+    // Parse
+    const { program, errors: parseErrors } = new Parser(tokens).parse();
+    errors.push(...parseErrors);
+    if (parseErrors.length > 0) {
+        return {
+            success: false,
+            program,
+            errors: errors.map(e => serializeDiagnostic(e, source, filename)),
+            warnings: [],
+        };
+    }
+    // Set sourceFile (no path.resolve — browser-safe)
+    for (const c of program.contexts)
+        c.sourceFile = filename;
+    for (const n of program.nodes)
+        n.sourceFile = filename;
+    // Build ProgramIndex
+    const index = new ProgramIndex(program);
+    // Analyze
+    const scopeDiagnostics = new ScopeChecker(program, index).check();
+    const typeDiagnostics = new TypeChecker(program, index).check();
+    for (const d of [...scopeDiagnostics, ...typeDiagnostics]) {
+        if (d.severity === 'warning')
+            warnings.push(d);
+        else
+            errors.push(d);
+    }
+    if (errors.length > 0) {
+        return {
+            success: false,
+            program,
+            errors: errors.map(e => serializeDiagnostic(e, source, filename)),
+            warnings: warnings.map(w => serializeDiagnostic(w, source, filename)),
+        };
+    }
+    // Token analysis
+    const report = new TokenEstimator(program, index).estimate();
+    warnings.push(...report.warnings);
+    // Generate files (if graph exists)
+    let files;
+    if (program.graphs.length > 0) {
+        files = generate(program, report, filename, index);
+    }
+    return {
+        success: true,
+        program,
+        report,
+        files,
+        errors: [],
+        warnings: warnings.map(w => serializeDiagnostic(w, source, filename)),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsleekr/graft",
-  "version": "6.0.1",
+  "version": "6.1.0",
   "description": "Graft compiler — compile .gft graph DSL to Claude Code harness structures",
   "type": "module",
   "license": "MIT",
@@ -15,7 +15,17 @@
     "dsl",
     "llm",
     "claude",
-    "graph"
+    "claude-code",
+    "multi-agent",
+    "pipeline",
+    "infrastructure-as-code",
+    "ai-agents",
+    "token-optimization",
+    "orchestration",
+    "graph",
+    "code-generation",
+    "developer-tools",
+    "automation"
   ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -59,6 +69,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "check": "tsc --noEmit",
+    "build:playground": "npx esbuild src/playground-entry.ts --bundle --format=iife --global-name=GraftCompiler --outfile=docs/playground/graft-compiler.js --platform=browser --alias:node:path=./scripts/playground-shims/node-path.js --alias:node:fs=./scripts/playground-shims/node-fs.js --alias:node:module=./scripts/playground-shims/node-module.js --alias:node:child_process=./scripts/playground-shims/node-fs.js --alias:node:url=./scripts/playground-shims/node-fs.js --footer:js=\"if(typeof window!=='undefined')window.Graft=GraftCompiler;\"",
     "prepublishOnly": "npm run build && npm test"
   },
   "engines": {