blokctl 0.2.0

package/dist/commands/generate/PromptVersioning.test.js

@@ -0,0 +1,120 @@
+import { describe, expect, it } from "vitest";
+import { PROMPT_VERSIONS, computeContentHash, getAllPromptVersions, getPromptVersion, getVersionStamp, registerPromptContent, } from "./PromptVersioning.js";
+describe("PromptVersioning", () => {
+    describe("PROMPT_VERSIONS registry", () => {
+        it("should have entries for all prompt types", () => {
+            expect(PROMPT_VERSIONS["create-fn-node"]).toBeDefined();
+            expect(PROMPT_VERSIONS["create-node"]).toBeDefined();
+            expect(PROMPT_VERSIONS["create-workflow"]).toBeDefined();
+            expect(PROMPT_VERSIONS["create-trigger"]).toBeDefined();
+        });
+        it("should have valid version strings for all entries", () => {
+            for (const [id, version] of Object.entries(PROMPT_VERSIONS)) {
+                expect(version.version).toMatch(/^\d+\.\d+\.\d+$/);
+                expect(version.id).toBe(id);
+                expect(version.changelog).toBeTruthy();
+                expect(version.createdAt).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+            }
+        });
+        it("should have function-first node at v2.0.0 with defineNode pattern", () => {
+            const fnNode = PROMPT_VERSIONS["create-fn-node"];
+            expect(fnNode.version).toBe("2.0.0");
+            expect(fnNode.changelog).toContain("defineNode");
+        });
+        it("should have workflow prompt at v2.0.0 with trigger types", () => {
+            const workflow = PROMPT_VERSIONS["create-workflow"];
+            expect(workflow.version).toBe("2.0.0");
+            expect(workflow.changelog).toContain("trigger");
+        });
+        it("should have trigger prompt at v2.0.0 with TriggerBase", () => {
+            const trigger = PROMPT_VERSIONS["create-trigger"];
+            expect(trigger.version).toBe("2.0.0");
+            expect(trigger.changelog).toContain("TriggerBase");
+        });
+    });
+    describe("getPromptVersion", () => {
+        it("should return version for known prompt ID", () => {
+            const version = getPromptVersion("create-fn-node");
+            expect(version).toBeDefined();
+            expect(version.id).toBe("create-fn-node");
+        });
+        it("should return undefined for unknown prompt ID", () => {
+            const version = getPromptVersion("nonexistent-prompt");
+            expect(version).toBeUndefined();
+        });
+    });
+    describe("getAllPromptVersions", () => {
+        it("should return all registered prompt versions", () => {
+            const versions = getAllPromptVersions();
+            expect(versions.length).toBeGreaterThanOrEqual(4);
+        });
+        it("should include all known prompt IDs", () => {
+            const versions = getAllPromptVersions();
+            const ids = versions.map((v) => v.id);
+            expect(ids).toContain("create-fn-node");
+            expect(ids).toContain("create-node");
+            expect(ids).toContain("create-workflow");
+            expect(ids).toContain("create-trigger");
+        });
+    });
+    describe("getVersionStamp", () => {
+        it("should return formatted version stamp for known prompt", () => {
+            const stamp = getVersionStamp("create-fn-node");
+            expect(stamp).toBe("create-fn-node@2.0.0");
+        });
+        it("should return unknown stamp for unregistered prompt", () => {
+            const stamp = getVersionStamp("unknown-prompt");
+            expect(stamp).toBe("unknown-prompt@unknown");
+        });
+        it("should return stamps in id@version format", () => {
+            for (const [id, version] of Object.entries(PROMPT_VERSIONS)) {
+                const stamp = getVersionStamp(id);
+                expect(stamp).toBe(`${id}@${version.version}`);
+            }
+        });
+    });
+    describe("computeContentHash", () => {
+        it("should return a non-empty string", () => {
+            const hash = computeContentHash("test content");
+            expect(hash).toBeTruthy();
+            expect(typeof hash).toBe("string");
+        });
+        it("should return consistent hash for same content", () => {
+            const hash1 = computeContentHash("hello world");
+            const hash2 = computeContentHash("hello world");
+            expect(hash1).toBe(hash2);
+        });
+        it("should return different hashes for different content", () => {
+            const hash1 = computeContentHash("content A");
+            const hash2 = computeContentHash("content B");
+            expect(hash1).not.toBe(hash2);
+        });
+        it("should handle empty string", () => {
+            const hash = computeContentHash("");
+            expect(hash).toBe("0");
+        });
+        it("should handle long content", () => {
+            const longContent = "a".repeat(10000);
+            const hash = computeContentHash(longContent);
+            expect(hash).toBeTruthy();
+        });
+    });
+    describe("registerPromptContent", () => {
+        it("should compute and store content hash for known prompt", () => {
+            registerPromptContent("create-fn-node", "test prompt content");
+            const version = getPromptVersion("create-fn-node");
+            expect(version.contentHash).toBeTruthy();
+            expect(version.contentHash).toBe(computeContentHash("test prompt content"));
+        });
+        it("should not throw for unknown prompt ID", () => {
+            expect(() => registerPromptContent("nonexistent", "content")).not.toThrow();
+        });
+        it("should update hash when content changes", () => {
+            registerPromptContent("create-node", "content v1");
+            const hash1 = getPromptVersion("create-node").contentHash;
+            registerPromptContent("create-node", "content v2");
+            const hash2 = getPromptVersion("create-node").contentHash;
+            expect(hash1).not.toBe(hash2);
+        });
+    });
+});

package/dist/commands/generate/RegisterNode.d.ts

@@ -0,0 +1,3 @@
+export default class RegisterNode {
+    generateNodesFile(nodeName: string, importPath: string, code: string, apiKey: string): Promise<string>;
+}

package/dist/commands/generate/RegisterNode.js

@@ -0,0 +1,37 @@
+import * as fs from "node:fs";
+import { createOpenAI } from "@ai-sdk/openai";
+import { generateText } from "ai";
+import registerNodeSystemPrompt from "./prompts/register-node.system.js";
+export default class RegisterNode {
+    async generateNodesFile(nodeName, importPath, code, apiKey) {
+        const dirPath = process.cwd();
+        const nodesFile = `${dirPath}/src/Nodes.ts`;
+        if (!fs.existsSync(nodesFile)) {
+            throw new Error("The Nodes.ts file does not exist. Please ensure you are in the correct project directory.");
+        }
+        const fileContent = fs.readFileSync(nodesFile, "utf8");
+        if (fileContent.includes(`"${nodeName}"`)) {
+            console.log(`\nNode "${nodeName}" is already registered in Nodes.ts.`);
+        }
+        const openai = createOpenAI({
+            compatibility: "strict",
+            apiKey: apiKey,
+        });
+        const { text } = await generateText({
+            model: openai("gpt-4o"),
+            system: `${registerNodeSystemPrompt.prompt} \n${fileContent}`,
+            prompt: `Node information:
+
+Name: ${nodeName} (This is the key in the nodes object)
+Import Path: ${importPath}
+Source Code:
+${code}
+
+Take the class name from the source code and use it to register the node in Nodes.ts.`,
+            temperature: 0.2,
+        });
+        const cleaned = text.replace(/^```typescript\s*([\s\S]*?)\s*```$/gm, "$1");
+        fs.writeFileSync(nodesFile, cleaned, "utf8");
+        return nodesFile;
+    }
+}

package/dist/commands/generate/RuntimeGenerator.d.ts

@@ -0,0 +1,40 @@
+export type RuntimeInformation = {
+    language: string;
+    userPrompt: string;
+    files: Array<{
+        path: string;
+        content: string;
+    }>;
+    rawCode: string;
+    validationResult?: {
+        valid: boolean;
+        errors: string[];
+        warnings: string[];
+        attempts: number;
+        promptVersion?: string;
+        durationMs?: number;
+    };
+};
+declare const SUPPORTED_LANGUAGES: readonly ["go", "java", "rust", "python", "csharp", "php", "ruby"];
+export type SupportedLanguage = (typeof SUPPORTED_LANGUAGES)[number];
+export declare function isSupportedLanguage(lang: string): lang is SupportedLanguage;
+export default class RuntimeGenerator {
+    private readonly MAX_VALIDATION_ATTEMPTS;
+    generateRuntime(language: string, userPrompt: string, apiKey: string, update?: boolean, existingPath?: string): Promise<RuntimeInformation>;
+    validateRuntimeStructure(code: string, language: string): {
+        valid: boolean;
+        errors: string[];
+        warnings: string[];
+    };
+    parseFiles(code: string, language: string): Array<{
+        path: string;
+        content: string;
+    }>;
+    private buildEnhancedPrompt;
+    private createFeedbackPrompt;
+    private getSemanticGuidance;
+    private validateLanguageSpecific;
+    private readExistingRuntime;
+    private getFileExtension;
+}
+export {};

package/dist/commands/generate/RuntimeGenerator.js

@@ -0,0 +1,369 @@
+import * as fs from "node:fs";
+import { createOpenAI } from "@ai-sdk/openai";
+import { generateText } from "ai";
+import { GenerationAnalytics } from "./GenerationAnalytics.js";
+import { getVersionStamp, registerPromptContent } from "./PromptVersioning.js";
+import createRuntimeSystemPrompt from "./prompts/create-runtime.system.js";
+const SUPPORTED_LANGUAGES = ["go", "java", "rust", "python", "csharp", "php", "ruby"];
+export function isSupportedLanguage(lang) {
+    return SUPPORTED_LANGUAGES.includes(lang.toLowerCase());
+}
+export default class RuntimeGenerator {
+    MAX_VALIDATION_ATTEMPTS = 3;
+    async generateRuntime(language, userPrompt, apiKey, update = false, existingPath) {
+        const analytics = GenerationAnalytics.getInstance();
+        const getElapsed = analytics.startTimer();
+        const promptVersion = getVersionStamp("create-runtime");
+        const openai = createOpenAI({
+            compatibility: "strict",
+            apiKey: apiKey,
+        });
+        let prompt = createRuntimeSystemPrompt.prompt;
+        registerPromptContent("create-runtime", prompt);
+        if (update && existingPath) {
+            const existingContent = this.readExistingRuntime(existingPath);
+            prompt = `${createRuntimeSystemPrompt.updatePrompt}\n\n${existingContent}`;
+        }
+        const enhancedPrompt = this.buildEnhancedPrompt(userPrompt, language);
+        let attempts = 0;
+        let generatedCode = "";
+        let validationErrors = [];
+        let validationWarnings = [];
+        let isValid = false;
+        const allErrors = [];
+        while (attempts < this.MAX_VALIDATION_ATTEMPTS && !isValid) {
+            attempts++;
+            let finalPrompt = enhancedPrompt;
+            if (attempts > 1 && validationErrors.length > 0) {
+                finalPrompt = this.createFeedbackPrompt(enhancedPrompt, generatedCode, validationErrors);
+            }
+            const { text } = await generateText({
+                model: openai("gpt-4o"),
+                system: prompt,
+                prompt: finalPrompt,
+                temperature: 0.2,
+            });
+            generatedCode = text.replace(/^```(?:\w+)?\s*([\s\S]*?)\s*```$/gm, "$1").trim();
+            const structureResult = this.validateRuntimeStructure(generatedCode, language);
+            validationErrors = structureResult.errors;
+            validationWarnings = structureResult.warnings;
+            isValid = structureResult.valid;
+            allErrors.push(...validationErrors);
+            if (!isValid && attempts < this.MAX_VALIDATION_ATTEMPTS) {
+                console.log(`\u26a0\ufe0f  Runtime validation failed (attempt ${attempts}/${this.MAX_VALIDATION_ATTEMPTS}). Retrying with feedback...`);
+            }
+        }
+        const files = this.parseFiles(generatedCode, language);
+        const durationMs = getElapsed();
+        analytics.recordEvent({
+            type: "node",
+            subtype: `runtime-${language}`,
+            name: `runtime-${language}`,
+            success: isValid,
+            attempts,
+            durationMs,
+            errors: allErrors,
+            promptVersion,
+        });
+        return {
+            language,
+            userPrompt,
+            files,
+            rawCode: generatedCode,
+            validationResult: {
+                valid: isValid,
+                errors: validationErrors,
+                warnings: validationWarnings,
+                attempts,
+                promptVersion,
+                durationMs,
+            },
+        };
+    }
+    validateRuntimeStructure(code, language) {
+        const errors = [];
+        const warnings = [];
+        const fileCount = (code.match(/\/\/ FILE:/gi) || []).length;
+        if (fileCount < 2) {
+            errors.push("Runtime must contain multiple files (use // FILE: <path> markers). Expected at least SDK core + server + Dockerfile.");
+        }
+        if (!code.includes("/execute")) {
+            errors.push("Missing POST /execute endpoint - required by the Blok Runtime Protocol");
+        }
+        if (!code.includes("/health")) {
+            errors.push("Missing GET /health endpoint - required by the Blok Runtime Protocol");
+        }
+        if (!code.toLowerCase().includes("context") && !code.toLowerCase().includes("ctx")) {
+            errors.push("Missing Context type definition - must map to Blok workflow context");
+        }
+        const handlerPatterns = ["NodeHandler", "node_handler", "Handler", "execute", "Execute"];
+        const hasHandler = handlerPatterns.some((p) => code.includes(p));
+        if (!hasHandler) {
+            errors.push("Missing NodeHandler interface/trait - nodes must implement an execute method");
+        }
+        const registryPatterns = ["Registry", "registry", "register", "Register"];
+        const hasRegistry = registryPatterns.some((p) => code.includes(p));
+        if (!hasRegistry) {
+            errors.push("Missing NodeRegistry - must provide node registration and dispatch");
+        }
+        const hasDockerfile = code.toLowerCase().includes("dockerfile") || code.toLowerCase().includes("docker");
+        if (!hasDockerfile) {
+            warnings.push("Missing Dockerfile - recommended for container deployment");
+        }
+        if (!code.includes("success") || !code.includes("data") || !code.includes("errors")) {
+            warnings.push("ExecutionResult should include success, data, and errors fields");
+        }
+        this.validateLanguageSpecific(code, language, errors, warnings);
+        return {
+            valid: errors.length === 0,
+            errors,
+            warnings,
+        };
+    }
+    parseFiles(code, language) {
+        const files = [];
+        const fileRegex = /\/\/\s*FILE:\s*(.+?)(?:\n|\r\n)/gi;
+        const parts = code.split(fileRegex);
+        for (let i = 1; i < parts.length; i += 2) {
+            const filePath = parts[i].trim();
+            const content = (parts[i + 1] || "").trim();
+            if (filePath && content) {
+                files.push({ path: filePath, content });
+            }
+        }
+        if (files.length === 0 && code.trim()) {
+            const ext = this.getFileExtension(language);
+            files.push({ path: `runtime.${ext}`, content: code.trim() });
+        }
+        return files;
+    }
+    buildEnhancedPrompt(userPrompt, language) {
+        const parts = [
+            `Generate a complete Blok Runtime SDK for the "${language}" programming language.`,
+            "",
+            userPrompt,
+            "",
+            `IMPORTANT: Generate a complete, runnable ${language} runtime SDK with:`,
+            "1. Core types (Context, Request, Response, ExecutionRequest, ExecutionResult)",
+            "2. NodeHandler interface/trait",
+            "3. NodeRegistry for node management",
+            "4. HTTP server with POST /execute and GET /health endpoints",
+            '5. Example "hello-world" node',
+            "6. Dockerfile for containerized deployment",
+            "7. Build configuration file (go.mod, pom.xml, Cargo.toml, etc.)",
+            "",
+            "Use // FILE: <relative-path> to separate each file.",
+        ];
+        switch (language.toLowerCase()) {
+            case "go":
+                parts.push("\nGenerate a Go module with:");
+                parts.push("- sdk/blok.go (core types + registry)");
+                parts.push("- server/main.go (HTTP server)");
+                parts.push("- nodes/hello-world/main.go (example node)");
+                parts.push("- go.mod (module definition)");
+                parts.push("- Dockerfile (multi-stage build)");
+                break;
+            case "java":
+                parts.push("\nGenerate a Maven project with:");
+                parts.push("- src/main/java/com/blok/runtime/Blok.java (core types)");
+                parts.push("- src/main/java/com/blok/runtime/NodeRegistry.java (registry)");
+                parts.push("- src/main/java/com/blok/server/RuntimeServer.java (HTTP server)");
+                parts.push("- src/main/java/com/blok/nodes/HelloWorldNode.java (example)");
+                parts.push("- pom.xml (Maven config)");
+                parts.push("- Dockerfile (multi-stage build)");
+                break;
+            case "rust":
+                parts.push("\nGenerate a Cargo project with:");
+                parts.push("- src/lib.rs (core types + NodeHandler trait)");
+                parts.push("- src/registry.rs (NodeRegistry)");
+                parts.push("- src/main.rs (HTTP server with axum or actix-web)");
+                parts.push("- src/nodes/hello_world.rs (example node)");
+                parts.push("- Cargo.toml (dependencies)");
+                parts.push("- Dockerfile (multi-stage build)");
+                break;
+            case "python":
+                parts.push("\nGenerate a Python package with:");
+                parts.push("- blok/__init__.py (core types)");
+                parts.push("- blok/registry.py (NodeRegistry)");
+                parts.push("- server.py (HTTP server with Flask or FastAPI)");
+                parts.push("- nodes/hello_world.py (example node)");
+                parts.push("- requirements.txt or pyproject.toml");
+                parts.push("- Dockerfile");
+                break;
+            case "csharp":
+                parts.push("\nGenerate a .NET project with:");
+                parts.push("- Runtime/BlokContext.cs (core types)");
+                parts.push("- Runtime/NodeRegistry.cs (registry)");
+                parts.push("- Program.cs (minimal API server)");
+                parts.push("- Nodes/HelloWorldNode.cs (example)");
+                parts.push("- BlokRuntime.csproj");
+                parts.push("- Dockerfile");
+                break;
+            case "php":
+                parts.push("\nGenerate a PHP project with:");
+                parts.push("- src/Runtime/Context.php (core types)");
+                parts.push("- src/Runtime/NodeRegistry.php (registry)");
+                parts.push("- src/Nodes/HelloWorldNode.php (example)");
+                parts.push("- server.php (HTTP server)");
+                parts.push("- composer.json");
+                parts.push("- Dockerfile");
+                break;
+            case "ruby":
+                parts.push("\nGenerate a Ruby project with:");
+                parts.push("- lib/blok/context.rb (core types)");
+                parts.push("- lib/blok/registry.rb (NodeRegistry)");
+                parts.push("- lib/blok/nodes/hello_world.rb (example)");
+                parts.push("- server.rb (Sinatra or Rack HTTP server)");
+                parts.push("- Gemfile");
+                parts.push("- Dockerfile");
+                break;
+        }
+        return parts.join("\n");
+    }
+    createFeedbackPrompt(originalPrompt, previousCode, errors) {
+        const analyzedErrors = errors.map((err, i) => {
+            const guidance = this.getSemanticGuidance(err);
+            return `${i + 1}. ${err}${guidance ? `\n   Fix: ${guidance}` : ""}`;
+        });
+        return [
+            originalPrompt,
+            "",
+            "\u274c The previous generation had validation errors:",
+            "",
+            ...analyzedErrors,
+            "",
+            "Previous code:",
+            "```",
+            previousCode.substring(0, 2000),
+            previousCode.length > 2000 ? "\n... (truncated)" : "",
+            "```",
+            "",
+            "Please fix ALL errors and regenerate the complete runtime SDK.",
+            "Make sure to:",
+            "- Use // FILE: <path> markers to separate each file",
+            "- Include POST /execute and GET /health HTTP endpoints",
+            "- Define Context, Request, Response, ExecutionRequest, ExecutionResult types",
+            "- Implement NodeHandler interface and NodeRegistry",
+            "- Include a hello-world example node",
+            "- Include a Dockerfile",
+        ].join("\n");
+    }
+    getSemanticGuidance(error) {
+        const errorLower = error.toLowerCase();
+        if (errorLower.includes("file") && errorLower.includes("marker")) {
+            return "Separate files with '// FILE: <relative-path>' on its own line before each file's content";
+        }
+        if (errorLower.includes("/execute")) {
+            return "Add an HTTP POST /execute endpoint that receives ExecutionRequest JSON and returns ExecutionResult JSON";
+        }
+        if (errorLower.includes("/health")) {
+            return "Add an HTTP GET /health endpoint that returns {status, version, runtime, nodes[]}";
+        }
+        if (errorLower.includes("context")) {
+            return "Define a Context struct/class with: id, workflow_name, workflow_path, request, response, vars, env";
+        }
+        if (errorLower.includes("nodehandler") || errorLower.includes("handler")) {
+            return "Define an interface/trait with an execute method: execute(context, config) -> result/error";
+        }
+        if (errorLower.includes("registry")) {
+            return "Implement a NodeRegistry with register(name, handler), get(name), execute(request) methods";
+        }
+        if (errorLower.includes("dockerfile")) {
+            return "Add a multi-stage Dockerfile that builds and runs the runtime on port 8080";
+        }
+        return null;
+    }
+    validateLanguageSpecific(code, language, errors, warnings) {
+        switch (language.toLowerCase()) {
+            case "go":
+                if (!code.includes("go.mod") && !code.includes("module")) {
+                    warnings.push("Missing go.mod - Go module definition recommended");
+                }
+                if (!code.includes("package")) {
+                    errors.push("Go code must declare a package");
+                }
+                break;
+            case "java":
+                if (!code.includes("pom.xml") && !code.includes("build.gradle")) {
+                    warnings.push("Missing build configuration (pom.xml or build.gradle)");
+                }
+                if (!code.includes("class")) {
+                    errors.push("Java code must define at least one class");
+                }
+                break;
+            case "rust":
+                if (!code.includes("Cargo.toml") && !code.includes("[package]")) {
+                    warnings.push("Missing Cargo.toml - Rust project configuration recommended");
+                }
+                if (!code.includes("fn ") && !code.includes("fn main")) {
+                    errors.push("Rust code must define functions");
+                }
+                break;
+            case "python":
+                if (!code.includes("requirements.txt") && !code.includes("pyproject.toml")) {
+                    warnings.push("Missing dependency file (requirements.txt or pyproject.toml)");
+                }
+                if (!code.includes("def ")) {
+                    errors.push("Python code must define functions");
+                }
+                break;
+            case "csharp":
+                if (!code.includes(".csproj")) {
+                    warnings.push("Missing .csproj project file");
+                }
+                break;
+            case "php":
+                if (!code.includes("composer.json")) {
+                    warnings.push("Missing composer.json");
+                }
+                break;
+            case "ruby":
+                if (!code.includes("Gemfile")) {
+                    warnings.push("Missing Gemfile");
+                }
+                break;
+        }
+    }
+    readExistingRuntime(dirPath) {
+        if (!fs.existsSync(dirPath)) {
+            return "";
+        }
+        const parts = [];
+        const readDir = (dir) => {
+            const entries = fs.readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                const fullPath = `${dir}/${entry.name}`;
+                if (entry.isDirectory() &&
+                    !entry.name.startsWith(".") &&
+                    entry.name !== "node_modules" &&
+                    entry.name !== "target" &&
+                    entry.name !== "build") {
+                    readDir(fullPath);
+                }
+                else if (entry.isFile()) {
+                    try {
+                        const content = fs.readFileSync(fullPath, "utf8");
+                        const relativePath = fullPath.replace(dirPath, "").replace(/^\//, "");
+                        parts.push(`// FILE: ${relativePath}\n${content}`);
+                    }
+                    catch {
+                    }
+                }
+            }
+        };
+        readDir(dirPath);
+        return parts.join("\n\n");
+    }
+    getFileExtension(language) {
+        const extensions = {
+            go: "go",
+            java: "java",
+            rust: "rs",
+            python: "py",
+            csharp: "cs",
+            php: "php",
+            ruby: "rb",
+        };
+        return extensions[language.toLowerCase()] || "txt";
+    }
+}

package/dist/commands/generate/RuntimeGenerator.test.d.ts

@@ -0,0 +1 @@
+export {};