blokctl 0.2.0

package/dist/commands/generate/index.js

@@ -0,0 +1,418 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import readline from "node:readline";
+import * as p from "@clack/prompts";
+import { Command } from "commander";
+import figlet from "figlet";
+import open from "open";
+import color from "picocolors";
+import { program, trackCommandExecution } from "../../services/commander.js";
+import { isNonInteractive } from "../../services/non-interactive.js";
+import { getPreferredEditor } from "../../services/utils.js";
+import NodeFileWriter from "./NodeFileWriter.js";
+import NodeGenerator from "./NodeGenerator.js";
+import RegisterNode from "./RegisterNode.js";
+import RuntimeGenerator, { isSupportedLanguage } from "./RuntimeGenerator.js";
+import TriggerGenerator from "./TriggerGenerator.js";
+import WorkflowGenerator from "./WorkflowGenerator.js";
+const create = new Command("generate").description("Generate code snippets using AI");
+create
+    .command("ai-node")
+    .description("Generate a Node.js code snippet using AI")
+    .option("-n, --name <value>", "Name of the Node code snippet")
+    .option("-p, --prompt <value>", "Prompt for AI code generation")
+    .option("-t, --type <value>", "Type of code snippet (default: 'class')")
+    .option("-s, --style <value>", "Node style: 'function' (default, defineNode) or 'class' (extends BlokService)")
+    .option("-u, --update", "Update existing Node code snippet")
+    .option("-c, --code <value>", "Code string to use with --update (skip multiline readline)")
+    .option("--code-file <value>", "File path to read code from for --update")
+    .option("-k, --api-key <value>", "OpenAI API key (optional, uses environment variable OPENAI_API_KEY if not provided)")
+    .action(async (options) => {
+    await trackCommandExecution({
+        command: "generate ai-node",
+        args: options,
+        execution: async () => {
+            console.log(figlet.textSync("blok CLI".toUpperCase(), {
+                font: "Digital",
+                horizontalLayout: "default",
+                verticalLayout: "default",
+                width: 100,
+                whitespaceBreak: true,
+            }));
+            console.log("");
+            if (!options.name) {
+                if (!options.update && !options.prompt) {
+                    console.error("Both --name and --prompt options are required.");
+                }
+                else {
+                    console.error("The --name option is required.");
+                }
+                process.exit(1);
+            }
+            if (!options.apiKey && !process.env.OPENAI_API_KEY) {
+                console.error("An OpenAI API key is required. Please provide it using --api-key or set the OPENAI_API_KEY environment variable.");
+                process.exit(1);
+            }
+            p.intro(color.inverse(" Create a New Node Code Snippet "));
+            const s = p.spinner();
+            let node = {};
+            let cleaned = "";
+            let nodeType = "class";
+            const nodeStyle = options.style || "function";
+            if (!options.update) {
+                s.start(`Generating ${nodeStyle === "function" ? "function-first" : "class-based"} Node code snippet...`);
+                const generator = new NodeGenerator();
+                node = await generator.generateNode(options.name.toLowerCase().replace(/\s+/g, "-"), options.prompt, options.apiKey || process.env.OPENAI_API_KEY, false, nodeStyle);
+                cleaned = node.code.replace(/^```typescript\s*([\s\S]*?)\s*```$/gm, "$1");
+                nodeType = options.type || "class";
+            }
+            else {
+                const nodeName = options.name.toLowerCase().replace(/\s+/g, "-");
+                p.intro(color.inverse(`🛠️  Update Existing Node: ${nodeName}`));
+                let multilineInput = "";
+                if (options.code) {
+                    multilineInput = options.code;
+                }
+                else if (options.codeFile) {
+                    if (!fs.existsSync(options.codeFile)) {
+                        console.error(`File not found: ${options.codeFile}`);
+                        process.exit(1);
+                    }
+                    multilineInput = fs.readFileSync(options.codeFile, "utf-8");
+                }
+                else if (isNonInteractive()) {
+                    console.error("Missing required flag --code or --code-file (non-interactive mode). " +
+                        "Provide code via --code or --code-file when using --update in non-interactive mode.");
+                    process.exit(1);
+                }
+                else {
+                    const rl = readline.createInterface({
+                        input: process.stdin,
+                        output: process.stdout,
+                        terminal: true,
+                    });
+                    const lines = [];
+                    console.log("\n   Enter your code below:");
+                    console.log("   - Type 'quit' on a new line to finish");
+                    console.log("   - Press Ctrl+C to cancel");
+                    console.log("   ----------------------------------------\n");
+                    multilineInput = await new Promise((resolve) => {
+                        rl.on("line", (input) => {
+                            if (input.trim().toLocaleLowerCase() === "quit") {
+                                rl.close();
+                                resolve(lines.join("\n"));
+                            }
+                            else {
+                                lines.push(input);
+                                rl.prompt();
+                            }
+                        });
+                        rl.on("SIGINT", () => {
+                            console.log("\nInput cancelled");
+                            rl.close();
+                            resolve("");
+                        });
+                        rl.on("close", () => {
+                            if (lines.length > 0) {
+                                resolve(lines.join("\n"));
+                            }
+                            else {
+                                resolve("");
+                            }
+                        });
+                        rl.prompt();
+                    });
+                }
+                s.start(`Updating ${nodeStyle === "function" ? "function-first" : "class-based"} Node code...`);
+                const generator = new NodeGenerator();
+                node = await generator.generateNode(options.name.toLowerCase().replace(/\s+/g, "-"), multilineInput, options.apiKey || process.env.OPENAI_API_KEY, true, nodeStyle);
+                cleaned = node.code.replace(/^```typescript\s*([\s\S]*?)\s*```$/gm, "$1");
+                nodeType = options.type || "class";
+            }
+            const filePath = await new NodeFileWriter().generateFile(node.nodeName, nodeType, cleaned, options.apiKey || process.env.OPENAI_API_KEY, nodeStyle);
+            s.message(`Registering node "${node.nodeName}" in Nodes.ts...`);
+            const register = new RegisterNode();
+            const nodesFilePath = await register.generateNodesFile(node.nodeName, `./nodes/${node.nodeName}`, node.code, options.apiKey || process.env.OPENAI_API_KEY);
+            const editor = getPreferredEditor();
+            await open(filePath, { app: { name: editor }, wait: false });
+            if (!options.update) {
+                await open(nodesFilePath, { app: { name: editor }, wait: false });
+            }
+            s.stop(`Node code snippet "${node.nodeName}" generated and registered successfully!`);
+            if (nodeStyle === "function") {
+                console.log(color.cyan("\n✨ Function-First Node Generated!"));
+                console.log("  • Type-safe with Zod validation");
+                console.log("  • 60% less boilerplate than class-based");
+                console.log("  • AI-friendly for code generation");
+                console.log("\n📖 Learn more: https://blok.build/docs/nodes/function-first\n");
+            }
+        },
+    });
+});
+create
+    .command("ai-workflow")
+    .description("Generate a workflow JSON configuration using AI")
+    .option("-n, --name <value>", "Name of the workflow")
+    .option("-p, --prompt <value>", "Prompt describing the workflow behavior")
+    .option("-t, --trigger <value>", "Trigger type: http, queue, pubsub, cron, webhook, websocket, sse (default: 'auto')")
+    .option("-u, --update <value>", "Path to existing workflow JSON to update")
+    .option("-k, --api-key <value>", "OpenAI API key (optional, uses environment variable OPENAI_API_KEY if not provided)")
+    .action(async (options) => {
+    await trackCommandExecution({
+        command: "generate ai-workflow",
+        args: options,
+        execution: async () => {
+            console.log(figlet.textSync("BLOK AI".toUpperCase(), {
+                font: "Digital",
+                horizontalLayout: "default",
+                verticalLayout: "default",
+                width: 100,
+                whitespaceBreak: true,
+            }));
+            console.log("");
+            if (!options.name) {
+                console.error("The --name option is required.");
+                process.exit(1);
+            }
+            if (!options.prompt && !options.update) {
+                console.error("The --prompt option is required for new workflows.");
+                process.exit(1);
+            }
+            if (!options.apiKey && !process.env.OPENAI_API_KEY) {
+                console.error("An OpenAI API key is required. Please provide it using --api-key or set the OPENAI_API_KEY environment variable.");
+                process.exit(1);
+            }
+            const isUpdate = !!options.update;
+            p.intro(color.inverse(isUpdate ? " Update Existing Workflow " : " Generate a New Workflow "));
+            const s = p.spinner();
+            const workflowName = options.name.toLowerCase().replace(/\s+/g, "-");
+            const triggerType = options.trigger || "auto";
+            const apiKey = options.apiKey || process.env.OPENAI_API_KEY;
+            s.start(`Generating workflow "${workflowName}" with ${triggerType === "auto" ? "auto-detected" : triggerType} trigger...`);
+            const generator = new WorkflowGenerator();
+            const result = await generator.generateWorkflow(workflowName, options.prompt || "Update this workflow with improvements", apiKey, triggerType, isUpdate, isUpdate ? options.update : undefined);
+            const dirPath = process.cwd();
+            const workflowsDir = path.join(dirPath, "workflows", "json");
+            if (!fs.existsSync(workflowsDir)) {
+                fs.mkdirSync(workflowsDir, { recursive: true });
+            }
+            const filePath = path.join(workflowsDir, `${workflowName}.json`);
+            fs.writeFileSync(filePath, result.json, "utf8");
+            if (result.validationResult) {
+                if (result.validationResult.valid) {
+                    s.stop(`Workflow "${workflowName}" generated successfully!`);
+                }
+                else {
+                    s.stop(`Workflow "${workflowName}" generated with validation warnings.`);
+                    console.log(color.yellow("\n⚠️  Validation Issues:"));
+                    for (const error of result.validationResult.errors) {
+                        console.log(color.red(`  ✗ ${error}`));
+                    }
+                }
+                if (result.validationResult.warnings.length > 0) {
+                    console.log(color.yellow("\n⚠️  Warnings:"));
+                    for (const warning of result.validationResult.warnings) {
+                        console.log(color.yellow(`  ! ${warning}`));
+                    }
+                }
+                console.log(color.dim(`\n  Attempts: ${result.validationResult.attempts}/${3}`));
+            }
+            const editor = getPreferredEditor();
+            await open(filePath, { app: { name: editor }, wait: false });
+            console.log(color.cyan(`\n✨ Workflow Generated: ${filePath}`));
+            console.log(`  Trigger: ${result.triggerType}`);
+            console.log(`  Name: ${workflowName}`);
+            console.log(color.dim("\n  To use this workflow, ensure all referenced nodes are installed or created.\n"));
+        },
+    });
+});
+create
+    .command("ai-trigger")
+    .description("Generate a trigger implementation using AI")
+    .option("-n, --name <value>", "Name of the trigger")
+    .option("-t, --type <value>", "Trigger type: queue, pubsub, cron, webhook, websocket, sse, custom")
+    .option("-p, --prompt <value>", "Prompt describing the trigger behavior")
+    .option("-u, --update <value>", "Path to existing trigger file to update")
+    .option("-k, --api-key <value>", "OpenAI API key (optional, uses environment variable OPENAI_API_KEY if not provided)")
+    .action(async (options) => {
+    await trackCommandExecution({
+        command: "generate ai-trigger",
+        args: options,
+        execution: async () => {
+            console.log(figlet.textSync("BLOK AI".toUpperCase(), {
+                font: "Digital",
+                horizontalLayout: "default",
+                verticalLayout: "default",
+                width: 100,
+                whitespaceBreak: true,
+            }));
+            console.log("");
+            if (!options.name) {
+                console.error("The --name option is required.");
+                process.exit(1);
+            }
+            if (!options.type) {
+                console.error("The --type option is required. Valid types: queue, pubsub, cron, webhook, websocket, sse, custom");
+                process.exit(1);
+            }
+            if (!options.prompt && !options.update) {
+                console.error("The --prompt option is required for new triggers.");
+                process.exit(1);
+            }
+            if (!options.apiKey && !process.env.OPENAI_API_KEY) {
+                console.error("An OpenAI API key is required. Please provide it using --api-key or set the OPENAI_API_KEY environment variable.");
+                process.exit(1);
+            }
+            const isUpdate = !!options.update;
+            p.intro(color.inverse(isUpdate ? " Update Existing Trigger " : " Generate a New Trigger "));
+            const s = p.spinner();
+            const triggerName = options.name.toLowerCase().replace(/\s+/g, "-");
+            const triggerType = options.type.toLowerCase();
+            const apiKey = options.apiKey || process.env.OPENAI_API_KEY;
+            s.start(`Generating ${triggerType} trigger "${triggerName}"...`);
+            const generator = new TriggerGenerator();
+            const result = await generator.generateTrigger(triggerName, triggerType, options.prompt || "Update this trigger with improvements", apiKey, isUpdate, isUpdate ? options.update : undefined);
+            const dirPath = process.cwd();
+            const triggerDir = path.join(dirPath, "triggers", triggerName, "src");
+            if (!fs.existsSync(triggerDir)) {
+                fs.mkdirSync(triggerDir, { recursive: true });
+            }
+            const className = triggerName
+                .split("-")
+                .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+                .join("");
+            const filePath = path.join(triggerDir, `${className}Trigger.ts`);
+            const cleaned = result.code.replace(/^```typescript\s*([\s\S]*?)\s*```$/gm, "$1");
+            fs.writeFileSync(filePath, cleaned, "utf8");
+            const indexPath = path.join(triggerDir, "index.ts");
+            if (!fs.existsSync(indexPath)) {
+                fs.writeFileSync(indexPath, `export { default } from "./${className}Trigger.js";\nexport * from "./${className}Trigger.js";\n`, "utf8");
+            }
+            if (result.validationResult) {
+                if (result.validationResult.valid) {
+                    s.stop(`Trigger "${triggerName}" generated successfully!`);
+                }
+                else {
+                    s.stop(`Trigger "${triggerName}" generated with validation warnings.`);
+                    console.log(color.yellow("\n⚠️  Validation Issues:"));
+                    for (const error of result.validationResult.errors) {
+                        console.log(color.red(`  ✗ ${error}`));
+                    }
+                }
+                if (result.validationResult.warnings.length > 0) {
+                    console.log(color.yellow("\n⚠️  Warnings:"));
+                    for (const warning of result.validationResult.warnings) {
+                        console.log(color.yellow(`  ! ${warning}`));
+                    }
+                }
+                console.log(color.dim(`\n  Attempts: ${result.validationResult.attempts}/${3}`));
+            }
+            const editor = getPreferredEditor();
+            await open(filePath, { app: { name: editor }, wait: false });
+            console.log(color.cyan(`\n✨ Trigger Generated: ${filePath}`));
+            console.log(`  Type: ${triggerType}`);
+            console.log(`  Class: ${className}Trigger`);
+            console.log(color.dim("\n  To use this trigger:"));
+            console.log(color.dim("  1. Install any required dependencies"));
+            console.log(color.dim("  2. Create a server entry point to instantiate and start the trigger"));
+            console.log(color.dim(`  3. Configure workflows with trigger type "${triggerType}"\n`));
+        },
+    });
+});
+create
+    .command("ai-runtime")
+    .description("Generate a runtime SDK for a specific programming language")
+    .option("-l, --language <value>", "Target language: go, java, rust, python, csharp, php, ruby")
+    .option("-p, --prompt <value>", "Additional instructions for the runtime generation")
+    .option("-u, --update <value>", "Path to existing runtime directory to update")
+    .option("-k, --api-key <value>", "OpenAI API key (optional, uses environment variable OPENAI_API_KEY if not provided)")
+    .action(async (options) => {
+    await trackCommandExecution({
+        command: "generate ai-runtime",
+        args: options,
+        execution: async () => {
+            console.log(figlet.textSync("BLOK AI".toUpperCase(), {
+                font: "Digital",
+                horizontalLayout: "default",
+                verticalLayout: "default",
+                width: 100,
+                whitespaceBreak: true,
+            }));
+            console.log("");
+            if (!options.language) {
+                console.error("The --language option is required. Valid languages: go, java, rust, python, csharp, php, ruby");
+                process.exit(1);
+            }
+            const language = options.language.toLowerCase();
+            if (!isSupportedLanguage(language)) {
+                console.error(`Unsupported language: "${language}". Valid languages: go, java, rust, python, csharp, php, ruby`);
+                process.exit(1);
+            }
+            if (!options.prompt && !options.update) {
+                console.error("The --prompt option is required for new runtimes.");
+                process.exit(1);
+            }
+            if (!options.apiKey && !process.env.OPENAI_API_KEY) {
+                console.error("An OpenAI API key is required. Please provide it using --api-key or set the OPENAI_API_KEY environment variable.");
+                process.exit(1);
+            }
+            const isUpdate = !!options.update;
+            p.intro(color.inverse(isUpdate
+                ? ` Update Existing ${language.toUpperCase()} Runtime `
+                : ` Generate ${language.toUpperCase()} Runtime SDK `));
+            const s = p.spinner();
+            const apiKey = options.apiKey || process.env.OPENAI_API_KEY;
+            const userPrompt = options.prompt || "Generate a complete runtime SDK with example nodes";
+            s.start(`Generating ${language} runtime SDK...`);
+            const generator = new RuntimeGenerator();
+            const result = await generator.generateRuntime(language, userPrompt, apiKey, isUpdate, isUpdate ? options.update : undefined);
+            const dirPath = process.cwd();
+            const runtimeDir = path.join(dirPath, "runtimes", language);
+            let filesWritten = 0;
+            for (const file of result.files) {
+                const filePath = path.join(runtimeDir, file.path);
+                const fileDir = path.dirname(filePath);
+                if (!fs.existsSync(fileDir)) {
+                    fs.mkdirSync(fileDir, { recursive: true });
+                }
+                fs.writeFileSync(filePath, file.content, "utf8");
+                filesWritten++;
+            }
+            if (result.validationResult) {
+                if (result.validationResult.valid) {
+                    s.stop(`${language.toUpperCase()} runtime SDK generated successfully!`);
+                }
+                else {
+                    s.stop(`${language.toUpperCase()} runtime SDK generated with validation warnings.`);
+                    console.log(color.yellow("\n\u26a0\ufe0f  Validation Issues:"));
+                    for (const error of result.validationResult.errors) {
+                        console.log(color.red(`  \u2717 ${error}`));
+                    }
+                }
+                if (result.validationResult.warnings.length > 0) {
+                    console.log(color.yellow("\n\u26a0\ufe0f  Warnings:"));
+                    for (const warning of result.validationResult.warnings) {
+                        console.log(color.yellow(`  ! ${warning}`));
+                    }
+                }
+                console.log(color.dim(`\n  Attempts: ${result.validationResult.attempts}/${3}`));
+            }
+            console.log(color.cyan(`\n\u2728 Runtime SDK Generated: ${runtimeDir}`));
+            console.log(`  Language: ${language}`);
+            console.log(`  Files: ${filesWritten}`);
+            if (result.files.length > 0) {
+                console.log(color.dim("\n  Generated files:"));
+                for (const file of result.files) {
+                    console.log(color.dim(`    \u2022 ${file.path}`));
+                }
+            }
+            console.log(color.dim("\n  To use this runtime:"));
+            console.log(color.dim("  1. cd into the generated directory"));
+            console.log(color.dim("  2. Build the runtime (see the generated README or Dockerfile)"));
+            console.log(color.dim(`  3. Run: docker build -t blok-runtime-${language} .`));
+            console.log(color.dim(`  4. Run: docker run -p 8080:8080 blok-runtime-${language}`));
+            console.log(color.dim("  5. Register the Docker adapter in your Blok configuration\n"));
+        },
+    });
+});
+program.addCommand(create);

package/dist/commands/generate/prompts/create-fn-node.system.d.ts

@@ -0,0 +1,5 @@
+declare const createFnNodeSystemPrompt: {
+    prompt: string;
+    updatePrompt: string;
+};
+export default createFnNodeSystemPrompt;

package/dist/commands/generate/prompts/create-fn-node.system.js

@@ -0,0 +1,256 @@
+const createFnNodeSystemPrompt = {
+    prompt: `You are a senior backend engineer specializing in bloks using the \`@blok\` framework. Your task is to generate a fully working **function-first Node file** that performs the described logic using a Zod schema-based API with the \`defineNode\` helper.
+
+What to return:
+
+* Return only a complete \`index.ts\` file, ready to be saved directly into \`src/nodes/<node-name>/index.ts\`.
+* It must include:
+
+  1. Proper imports:
+     * \`z\` from \`zod\`
+     * \`Context\` from \`@blok/shared\`
+     * \`defineNode\` from \`@blok/runner\`
+  2. A clear and structured \`input\` schema using Zod (z.object with proper types).
+  3. A matching \`output\` schema using Zod.
+  4. A single exported node instance created via \`defineNode\` with:
+     * \`name\`: the node key/name (e.g., "fetch-user")
+     * \`description\`: short human-readable description
+     * \`input\`: Zod input schema
+     * \`output\`: Zod output schema
+     * \`execute(ctx, input)\`: the full business logic implementation.
+
+Constraints:
+
+* **Do NOT use classes.** Do not extend \`BlokService\` directly; always use the \`defineNode\` helper. The helper internally takes care of \`BlokService\`, \`handle\`, and \`BlokResponse\` wiring.
+* The Zod \`input\` schema must fully describe the expected input object with proper types.
+* The Zod \`output\` schema must fully describe the object returned by \`execute\`.
+* Inside \`execute(ctx, input)\`:
+  * Use the strongly-typed \`input\`, which is automatically inferred from the Zod schema.
+  * Use \`ctx\` to access request data, configuration, and cross-node state when needed:
+    * \`ctx.request.body\`, \`ctx.request.query\`, \`ctx.request.params\` for HTTP data
+    * \`ctx.vars\` for reading/writing values shared between nodes
+    * \`ctx.logger\` for logging
+    * \`ctx.env\` for environment variables
+  * Do **not** construct or return \`BlokResponse\` here; just return a plain object matching the output schema. The wrapper created by \`defineNode\` will call \`setSuccess\` / \`setError\` and handle \`GlobalError\`.
+* On validation errors or runtime errors, you do NOT manually throw \`GlobalError\`; throw/rethrow normal errors. The \`defineNode\` wrapper will catch them and map them to \`GlobalError\` consistently with proper error codes:
+  * Zod validation errors → 400 Bad Request
+  * Runtime errors → 500 Internal Server Error
+* Node output should be JSON-serializable and match the output schema. Avoid returning functions, class instances, or non-serializable structures.
+* Use Zod's built-in validators (z.string().email(), z.number().positive(), z.string().url(), etc.) for proper validation.
+* Use optional fields with .optional() and defaults with .default() as needed.
+
+Formatting:
+
+* No explanations, comments, or markdown fences outside the TypeScript file.
+* The output must be a single valid TypeScript module.
+* Export the node as default: \`export default defineNode({...})\`
+
+Real-World Examples to Guide You:
+
+**Example 1: API Call Node**
+
+\`\`\`typescript
+import type { Context } from "@blok/shared";
+import { z } from "zod";
+import { defineNode } from "@blok/runner";
+
+export default defineNode({
+	name: "api-call",
+	description: "Makes HTTP API calls with automatic JSON handling",
+
+	input: z.object({
+		url: z.string().url("Must be a valid URL"),
+		method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]).default("GET"),
+		headers: z.record(z.string()).optional(),
+		body: z.any().optional(),
+		timeout: z.number().positive().optional().default(30000),
+	}),
+
+	output: z.object({
+		status: z.number().int().min(100).max(599),
+		statusText: z.string(),
+		data: z.any(),
+		headers: z.record(z.string()),
+		duration: z.number(),
+	}),
+
+	async execute(ctx, input) {
+		const startTime = performance.now();
+
+		ctx.logger.log(\`Making \${input.method} request to \${input.url}\`);
+
+		const response = await fetch(input.url, {
+			method: input.method,
+			headers: {
+				"Content-Type": "application/json",
+				...input.headers,
+			},
+			body: input.body ? JSON.stringify(input.body) : undefined,
+			signal: AbortSignal.timeout(input.timeout),
+		});
+
+		const contentType = response.headers.get("content-type") || "";
+		let data: unknown;
+
+		if (contentType.includes("application/json")) {
+			data = await response.json();
+		} else {
+			data = await response.text();
+		}
+
+		const duration = performance.now() - startTime;
+
+		ctx.logger.log(\`Request completed in \${duration.toFixed(2)}ms with status \${response.status}\`);
+
+		if (ctx.vars) {
+			ctx.vars["api-response"] = { status: response.status, data };
+		}
+
+		return {
+			status: response.status,
+			statusText: response.statusText,
+			data,
+			headers: Object.fromEntries(response.headers.entries()),
+			duration,
+		};
+	},
+});
+\`\`\`
+
+**Example 2: Fetch User Node**
+
+\`\`\`typescript
+import type { Context } from "@blok/shared";
+import { z } from "zod";
+import { defineNode } from "@blok/runner";
+
+export default defineNode({
+	name: "fetch-user",
+	description: "Fetches user profile by ID from database",
+
+	input: z.object({
+		userId: z.string().uuid("userId must be a valid UUID"),
+		includeMetadata: z.boolean().optional().default(false),
+	}),
+
+	output: z.object({
+		user: z.object({
+			id: z.string().uuid(),
+			name: z.string().min(1),
+			email: z.string().email(),
+			createdAt: z.string().datetime(),
+			metadata: z.record(z.unknown()).optional(),
+		}),
+	}),
+
+	async execute(ctx, input) {
+		ctx.logger.log(\`Fetching user: \${input.userId}\`);
+
+		// Simulate database fetch
+		const user = await fetchUserFromDatabase(input.userId, input.includeMetadata);
+
+		// Store in context for downstream nodes
+		if (ctx.vars) {
+			ctx.vars["current-user"] = user;
+		}
+
+		return { user };
+	},
+});
+
+async function fetchUserFromDatabase(userId: string, includeMetadata: boolean) {
+	// Your database logic here
+	return {
+		id: userId,
+		name: "John Doe",
+		email: "john@example.com",
+		createdAt: new Date().toISOString(),
+		...(includeMetadata && {
+			metadata: { lastLogin: new Date().toISOString(), loginCount: 42 },
+		}),
+	};
+}
+\`\`\`
+
+Template to follow (adapt and fill based on the user's request):
+
+import type { Context } from "@blok/shared";
+import { z } from "zod";
+import { defineNode } from "@blok/runner";
+
+/**
+ * [Brief description of what this node does]
+ */
+export default defineNode({
+	name: "[node-key]", // e.g., "fetch-user"
+	description: "[Short description of what this node does]",
+
+	// Input schema using Zod - automatically validated
+	input: z.object({
+		// TODO: Define input fields based on the requested functionality
+		// Example:
+		// userId: z.string().uuid(),
+		// includeProfile: z.boolean().optional().default(false),
+	}),
+
+	// Output schema using Zod - automatically validated
+	output: z.object({
+		// TODO: Define output fields that represent the successful result
+		// Example:
+		// user: z.object({
+		//   id: z.string(),
+		//   name: z.string(),
+		//   email: z.string().email(),
+		// }),
+	}),
+
+	// Execute function - type-safe with inferred types from Zod schemas
+	async execute(ctx, input) {
+		// Implement the core business logic here using ctx + input.
+		//
+		// Common patterns:
+		// - Read HTTP params: const id = ctx.request.params.id;
+		// - Read previous node output: const prev = ctx.vars["previous-node-key"];
+		// - Write for future nodes: ctx.vars["this-node-key"] = someValue;
+		// - Use input.* fields that match the input schema (TypeScript infers the type automatically)
+		// - Log messages: ctx.logger.log("Processing request");
+		// - Access environment: const apiKey = ctx.env.API_KEY;
+
+		// TODO: Implement business logic here
+
+		// The returned value MUST conform to the output schema
+		return {
+			// TODO: Return the final result matching the output schema
+		};
+	},
+});`,
+    updatePrompt: `You are a senior backend engineer specializing in bloks using the \`@blok\` framework. Your task is to update an existing function-first Node file (using \`defineNode\`) with new functionality while preserving its core structure.
+
+Given the existing code below, enhance or modify it according to the user's requirements while maintaining the following:
+
+1. Keep the existing imports and node structure
+2. Preserve the defineNode pattern (no classes)
+3. Maintain Zod schemas for input/output validation
+4. Keep the execute function signature and return pattern
+5. Maintain type safety and proper TypeScript usage
+6. Follow the same code style and formatting
+
+What to return:
+* Return only the full updated Node file
+* Preserve existing functionality unless explicitly asked to change it
+* Add new functionality as requested
+* Ensure all Zod schemas and types remain in sync
+* Keep input/output schemas comprehensive and accurate
+
+Format:
+* No explanations or comments outside the code
+* Return the complete file as it would appear in the .ts file
+* Keep existing JSDoc comments unless they need updating
+* Maintain the function-first pattern with defineNode
+
+The code should seamlessly integrate with the existing blok framework and leverage Zod validation for type safety and runtime validation.
+
+Current Code to be improved:
+`,
+};
+export default createFnNodeSystemPrompt;