blokctl 1.2.0 → 1.4.0

package/dist/scaffold-repo/triggers/worker/template/src/runner/types/Workflows.ts

@@ -0,0 +1,7 @@
+import type { WorkflowV2Builder } from "@blokjs/helper";
+
+type Workflows = {
+	[key: string]: WorkflowV2Builder;
+};
+
+export default Workflows;

package/dist/scaffold-repo/triggers/worker/template/src/workflows/jobs/process-job.ts

@@ -0,0 +1,40 @@
+import { node, step, workflow } from "@blokjs/core";
+
+/**
+ * Example Worker workflow — fires when a job is received from the queue.
+ *
+ * The `job` entry handle is the job payload + metadata:
+ *   - job.body              — the job payload as posted
+ *   - job.headers           — job headers
+ *   - job.params.queue      — queue name
+ *   - job.params.jobId      — unique job ID
+ *   - job.params.attempt    — retry attempt (0-based)
+ *
+ * v2 reliability knobs available as step()'s 4th arg (uncomment to use):
+ *   { idempotencyKey: job.params.jobId }  — skip re-runs of the same job
+ *   { retry: { maxAttempts: 3 } }          — retry on transient failures
+ *   { maxDuration: "30s" }                 — fail the step if it hangs
+ *
+ * Trigger-level reliability (on the `worker` block):
+ *   concurrencyKey: "$.req.body.tenantId"  — per-tenant fairness
+ *   onLimit: "queue"                        — defer instead of reject
+ */
+export default workflow(
+	"Process Background Job",
+	{
+		version: "1.0.0",
+		trigger: { worker: { queue: "background-jobs" } },
+	},
+	(job) => {
+		step("process-job", node("@blokjs/api-call"), {
+			url: "https://httpbin.org/post",
+			method: "POST",
+			body: {
+				job: job.body,
+				queue: job.params.queue,
+				jobId: job.params.jobId,
+				attempt: job.params.attempt,
+			},
+		});
+	},
+);

package/dist/scaffold-repo/triggers/worker/template/tsconfig.json

@@ -0,0 +1,31 @@
+{
+	"ts-node": {
+		"transpileOnly": true
+	},
+	"compilerOptions": {
+		"target": "ES2022",
+		"module": "es2022",
+		"moduleResolution": "bundler",
+		"rootDir": "./src",
+		"baseUrl": ".",
+		"paths": {
+			"@nodes/*": ["./src/nodes/*"],
+			"@src/*": ["src/*"]
+		},
+		"allowJs": true,
+		"declaration": true,
+		"declarationMap": true,
+		"sourceMap": true,
+		"outDir": "./dist",
+		"esModuleInterop": true,
+		"forceConsistentCasingInFileNames": true,
+		"strict": true,
+		"noUnusedLocals": true,
+		"noImplicitReturns": true,
+		"skipLibCheck": true,
+		"resolveJsonModule": true
+	},
+	"compileOnSave": true,
+	"include": ["./src", "./src/nodes/**/*.json", "./src/nodes/**/*.md"],
+	"exclude": ["src/nodes/**/test/*.ts", "**/*.test.ts", "node_modules", "dist"]
+}

package/dist/scaffold-repo/triggers/worker/template/vitest.config.ts

@@ -0,0 +1,39 @@
+import path from "node:path";
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+	test: {
+		globals: true,
+		environment: "node",
+		coverage: {
+			provider: "istanbul",
+			reporter: ["text", "json", "html", "lcov"],
+			exclude: [
+				"node_modules/",
+				"dist/",
+				"**/*.d.ts",
+				"**/*.config.ts",
+				"__tests__/",
+				"src/nodes/",
+				"src/workflows/",
+				"src/runner/types/",
+				"src/runner/metrics/",
+			],
+			thresholds: {
+				lines: 90,
+				functions: 90,
+				branches: 85,
+				statements: 90,
+			},
+		},
+		include: ["__tests__/**/*.test.ts"],
+		exclude: ["node_modules", "dist"],
+		testTimeout: 10000,
+		hookTimeout: 10000,
+	},
+	resolve: {
+		alias: {
+			"@": path.resolve(__dirname, "./src"),
+		},
+	},
+});

package/dist/scaffold-repo/triggers/worker/tsconfig.json

@@ -0,0 +1,32 @@
+{
+	"ts-node": {
+		"transpileOnly": true
+	},
+	"compilerOptions": {
+		"target": "ES2022",
+		"module": "es2022",
+		"lib": ["ES2022"],
+		"declaration": true,
+		"strict": true,
+		"noImplicitAny": true,
+		"strictNullChecks": true,
+		"noImplicitThis": true,
+		"alwaysStrict": true,
+		"noUnusedLocals": false,
+		"noUnusedParameters": false,
+		"noImplicitReturns": true,
+		"noFallthroughCasesInSwitch": false,
+		"inlineSourceMap": true,
+		"inlineSources": true,
+		"experimentalDecorators": true,
+		"emitDecoratorMetadata": true,
+		"skipLibCheck": true,
+		"esModuleInterop": true,
+		"resolveJsonModule": true,
+		"outDir": "./dist",
+		"rootDir": "./src",
+		"moduleResolution": "bundler"
+	},
+	"include": ["src/**/*"],
+	"exclude": ["node_modules", "dist", "**/*.test.ts"]
+}

package/dist/scaffold-repo/workflows/json/agent-message.json

@@ -0,0 +1,87 @@
+{
+	"name": "Agent Message",
+	"version": "1.0.0",
+	"description": "v0.6.10 — POST handler for the agentic chat. Loads prior conversation from Redis, runs the OpenAI tool-calling loop via @blokjs/llm-agent with two demo tools (weather + calculator), persists the new turn back to Redis with a 24h TTL. The agent loop streams `token`, `tool_call`, and `tool_result` events to the SSE bus channel `agent:<sid>`; the agent-stream workflow fans them out to the browser. Set OPENROUTER_API_KEY and have Redis reachable at REDIS_URL before exercising. Tool endpoints assume the deployment is reachable at http://localhost:4000 — change to a public URL or BLOK_SELF_BASE_URL interpolation when deploying.",
+	"trigger": {
+		"http": {
+			"method": "POST",
+			"path": "/agent/:sessionId/message",
+			"accept": "application/json"
+		}
+	},
+	"steps": [
+		{
+			"id": "load-history",
+			"use": "@blokjs/redis-kv",
+			"type": "module",
+			"inputs": {
+				"action": "get",
+				"key": "js/`agent:${ctx.request.params.sessionId}:history`"
+			}
+		},
+		{
+			"id": "agent",
+			"use": "@blokjs/llm-agent",
+			"type": "module",
+			"inputs": {
+				"channel": "js/`agent:${ctx.request.params.sessionId}`",
+				"apiKey": "js/process.env.OPENROUTER_API_KEY",
+				"model": "js/process.env.OPENROUTER_MODEL || 'openai/gpt-4o-mini'",
+				"messages": "js/[{ role: 'system', content: 'You are a helpful agent with two tools: get_weather(city) returns current weather; calculate(expression) evaluates arithmetic. Use them when the user asks weather or math questions. Be concise.' }, ...(ctx.state['load-history']?.value || []), { role: 'user', content: ctx.request.body.message }]",
+				"tools": [
+					{
+						"name": "get_weather",
+						"description": "Returns the current weather for a given city.",
+						"parameters": {
+							"type": "object",
+							"properties": {
+								"city": {
+									"type": "string",
+									"description": "City name, e.g. 'San Francisco'"
+								}
+							},
+							"required": ["city"]
+						},
+						"endpoint": "http://localhost:4000/tools/weather"
+					},
+					{
+						"name": "calculate",
+						"description": "Evaluates a JavaScript arithmetic expression and returns the numeric result.",
+						"parameters": {
+							"type": "object",
+							"properties": {
+								"expression": {
+									"type": "string",
+									"description": "Arithmetic expression, e.g. '17 * 23' or '(120 + 45) / 3'"
+								}
+							},
+							"required": ["expression"]
+						},
+						"endpoint": "http://localhost:4000/tools/calculator"
+					}
+				],
+				"maxIterations": 10
+			}
+		},
+		{
+			"id": "save-history",
+			"use": "@blokjs/redis-kv",
+			"type": "module",
+			"inputs": {
+				"action": "set",
+				"key": "js/`agent:${ctx.request.params.sessionId}:history`",
+				"value": "js/[...(ctx.state['load-history']?.value || []), { role: 'user', content: ctx.request.body.message }, { role: 'assistant', content: ctx.state.agent.fullText }]",
+				"ttlMs": 86400000
+			},
+			"ephemeral": true
+		},
+		{
+			"id": "respond",
+			"use": "@blokjs/expr",
+			"type": "module",
+			"inputs": {
+				"expression": "({ ok: true, fullText: ctx.state.agent.fullText, finishReason: ctx.state.agent.finishReason, iterations: ctx.state.agent.iterations, toolCalls: ctx.state.agent.toolCalls })"
+			}
+		}
+	]
+}

package/dist/scaffold-repo/workflows/json/agent-page.json

@@ -0,0 +1,25 @@
+{
+	"name": "Agent Page",
+	"version": "1.0.0",
+	"description": "v0.6.10 — Renders the agentic-chat HTML page. Same chat-ui node as /chat, parameterized for the /agent endpoint family. The agent variant streams not just text tokens but also `tool_call` and `tool_result` events via SSE — the same vanilla EventSource UI handles all three. Pair with agent-message + agent-stream + the two demo tool workflows (tools/weather, tools/calculator).",
+	"trigger": {
+		"http": {
+			"method": "GET",
+			"path": "/agent",
+			"accept": "text/html"
+		}
+	},
+	"steps": [
+		{
+			"id": "render",
+			"use": "chat-ui",
+			"type": "module",
+			"inputs": {
+				"endpointBase": "/agent",
+				"title": "Blok Agent (tool calls)",
+				"persistSession": true,
+				"bodyMode": "message"
+			}
+		}
+	]
+}

package/dist/scaffold-repo/workflows/json/agent-stream.json

@@ -0,0 +1,30 @@
+{
+	"name": "Agent Stream",
+	"version": "1.0.0",
+	"description": "v0.6.10 — SSE subscriber for the agentic chat. Subscribes to bus channel `agent:<sessionId>` and pumps `token`, `tool_call`, `tool_result`, and `done` events to the browser. The chat-ui EventSource handles all four event names.",
+	"trigger": {
+		"sse": {
+			"path": "/sse/agent/:sessionId",
+			"heartbeatInterval": 15000,
+			"retryInterval": 3000
+		}
+	},
+	"steps": [
+		{
+			"id": "sub",
+			"use": "@blokjs/sse-subscribe",
+			"type": "module",
+			"inputs": {
+				"channels": ["agent:{sessionId}"]
+			}
+		},
+		{
+			"id": "stream",
+			"use": "@blokjs/sse-stream",
+			"type": "module",
+			"inputs": {
+				"source": "js/ctx.state.sub"
+			}
+		}
+	]
+}

package/dist/scaffold-repo/workflows/json/agent-tool-calculator.json

@@ -0,0 +1,22 @@
+{
+	"name": "agent-tool-calculator",
+	"version": "1.0.0",
+	"description": "v0.6.10 — Demo tool endpoint: arithmetic evaluator. The agent POSTs `{ args: { expression: '17 * 23' } }`; we eval it and return the numeric result. SAFETY: this evals user-supplied input in a server-side `new Function` sandbox — fine for a localhost demo, but DO NOT expose this URL to untrusted callers in production. Real deployments should plumb the expression through a safe arithmetic parser (e.g. mathjs).",
+	"trigger": {
+		"http": {
+			"method": "POST",
+			"path": "/tools/calculator",
+			"accept": "application/json"
+		}
+	},
+	"steps": [
+		{
+			"id": "calc",
+			"use": "@blokjs/expr",
+			"type": "module",
+			"inputs": {
+				"expression": "(() => { const expr = (ctx.request.body && ctx.request.body.args && ctx.request.body.args.expression) || '0'; try { const result = Function('\"use strict\"; return (' + expr + ')')(); return { expression: expr, result: result, ok: true }; } catch (err) { return { expression: expr, error: String(err), ok: false }; } })()"
+			}
+		}
+	]
+}

package/dist/scaffold-repo/workflows/json/agent-tool-weather.json

@@ -0,0 +1,22 @@
+{
+	"name": "agent-tool-weather",
+	"version": "1.0.0",
+	"description": "v0.6.10 — Demo tool endpoint for the agentic chat (see agent-message.json). The agent POSTs `{ args: { city: '...' } }`; we return a fake weather payload. In production this would call OpenWeatherMap / WeatherAPI / etc. Showcased pattern: an agent tool is just an HTTP endpoint — could be ANY URL, internal or external.",
+	"trigger": {
+		"http": {
+			"method": "POST",
+			"path": "/tools/weather",
+			"accept": "application/json"
+		}
+	},
+	"steps": [
+		{
+			"id": "respond",
+			"use": "@blokjs/expr",
+			"type": "module",
+			"inputs": {
+				"expression": "(() => { const city = (ctx.request.body && ctx.request.body.args && ctx.request.body.args.city) || 'unknown'; const seeded = (city.charCodeAt(0) * 31 + city.length) % 25; return { city: city, temperatureF: 50 + seeded, conditions: ['sunny','cloudy','rainy','windy'][seeded % 4], humidity: 30 + (seeded * 2) % 50 }; })()"
+			}
+		}
+	]
+}

package/dist/scaffold-repo/workflows/json/chat-memory-message.json

@@ -0,0 +1,54 @@
+{
+	"name": "Chat (Redis Memory) Message",
+	"version": "1.0.0",
+	"description": "v0.6.8 — POST handler for the Redis-memory chat. Loads prior conversation from Redis (key `chat-memory:<sid>:history`), prepends a system prompt, calls @blokjs/llm-stream with the full reconstructed message list, then writes the new user+assistant turns back to Redis with a 24h TTL. Demonstrates: redis-kv get/set, multi-step state composition via `js/` mapper expressions, llm-stream chained with persistence.",
+	"trigger": {
+		"http": {
+			"method": "POST",
+			"path": "/chat-memory/:sessionId/message",
+			"accept": "application/json"
+		}
+	},
+	"steps": [
+		{
+			"id": "load-history",
+			"use": "@blokjs/redis-kv",
+			"type": "module",
+			"inputs": {
+				"action": "get",
+				"key": "js/`chat-memory:${ctx.request.params.sessionId}:history`"
+			}
+		},
+		{
+			"id": "stream",
+			"use": "@blokjs/llm-stream",
+			"type": "module",
+			"inputs": {
+				"channel": "js/`chat-memory:${ctx.request.params.sessionId}`",
+				"apiKey": "js/process.env.OPENROUTER_API_KEY",
+				"model": "js/process.env.OPENROUTER_MODEL || 'openai/gpt-4o-mini'",
+				"messages": "js/[{ role: 'system', content: 'You are a helpful assistant chatting with the user. The conversation may span many turns — earlier messages were stored in Redis and are included below. Be concise.' }, ...(ctx.state['load-history']?.value || []), { role: 'user', content: ctx.request.body.message }]"
+			}
+		},
+		{
+			"id": "save-history",
+			"use": "@blokjs/redis-kv",
+			"type": "module",
+			"inputs": {
+				"action": "set",
+				"key": "js/`chat-memory:${ctx.request.params.sessionId}:history`",
+				"value": "js/[...(ctx.state['load-history']?.value || []), { role: 'user', content: ctx.request.body.message }, { role: 'assistant', content: ctx.state.stream.fullText }]",
+				"ttlMs": 86400000
+			},
+			"ephemeral": true
+		},
+		{
+			"id": "respond",
+			"use": "@blokjs/expr",
+			"type": "module",
+			"inputs": {
+				"expression": "({ ok: true, fullText: ctx.state.stream.fullText, finishReason: ctx.state.stream.finishReason, turn: ((ctx.state['load-history']?.value?.length || 0) / 2) + 1 })"
+			}
+		}
+	]
+}

package/dist/scaffold-repo/workflows/json/chat-memory-page.json

@@ -0,0 +1,25 @@
+{
+	"name": "Chat (Redis Memory) Page",
+	"version": "1.0.0",
+	"description": "v0.6.8 — Renders the Redis-memory chat HTML page. Same chat-ui node as /chat, parameterized for the /chat-memory endpoint family. persistSession=true keeps sessionId in localStorage across reloads so the server-side Redis history stays attached. bodyMode=message tells the client to POST only the latest user turn (server reconstructs history from Redis). Pair with chat-memory-message + chat-memory-stream.",
+	"trigger": {
+		"http": {
+			"method": "GET",
+			"path": "/chat-memory",
+			"accept": "text/html"
+		}
+	},
+	"steps": [
+		{
+			"id": "render",
+			"use": "chat-ui",
+			"type": "module",
+			"inputs": {
+				"endpointBase": "/chat-memory",
+				"title": "Blok Chat (Redis memory)",
+				"persistSession": true,
+				"bodyMode": "message"
+			}
+		}
+	]
+}

package/dist/scaffold-repo/workflows/json/chat-memory-stream.json

@@ -0,0 +1,30 @@
+{
+	"name": "Chat (Redis Memory) Stream",
+	"version": "1.0.0",
+	"description": "v0.6.8 — SSE subscriber for the Redis-memory chat. Mirrors chat-stream.json but on the `chat-memory:<sessionId>` bus channel so the two chat variants run side-by-side without crosstalk. Mounts on the HTTP server's Hono app (same process as chat-memory-message).",
+	"trigger": {
+		"sse": {
+			"path": "/sse/chat-memory/:sessionId",
+			"heartbeatInterval": 15000,
+			"retryInterval": 3000
+		}
+	},
+	"steps": [
+		{
+			"id": "sub",
+			"use": "@blokjs/sse-subscribe",
+			"type": "module",
+			"inputs": {
+				"channels": ["chat-memory:{sessionId}"]
+			}
+		},
+		{
+			"id": "stream",
+			"use": "@blokjs/sse-stream",
+			"type": "module",
+			"inputs": {
+				"source": "js/ctx.state.sub"
+			}
+		}
+	]
+}

package/dist/scaffold-repo/workflows/json/chat-message.json

@@ -0,0 +1,25 @@
+{
+	"name": "Chat Message",
+	"version": "1.0.0",
+	"description": "HTTP POST handler for the chat demo. Calls @blokjs/llm-stream which streams the LLM response chunk-by-chunk to the in-process SSE bus channel `chat:<sessionId>`. The companion chat-stream workflow's SSE subscriber pumps those frames to the connected browser.",
+	"trigger": {
+		"http": {
+			"method": "POST",
+			"path": "/chat/:sessionId/message",
+			"accept": "application/json"
+		}
+	},
+	"steps": [
+		{
+			"id": "stream",
+			"use": "@blokjs/llm-stream",
+			"type": "module",
+			"inputs": {
+				"channel": "js/`chat:${ctx.request.params.sessionId}`",
+				"apiKey": "js/process.env.OPENROUTER_API_KEY",
+				"model": "js/process.env.OPENROUTER_MODEL || 'openai/gpt-4o-mini'",
+				"messages": "js/ctx.request.body.messages"
+			}
+		}
+	]
+}

package/dist/scaffold-repo/workflows/json/chat-page.json

@@ -0,0 +1,20 @@
+{
+	"name": "Chat Page",
+	"version": "1.0.0",
+	"description": "Renders the Blok chat demo HTML page. Pair with chat-message (HTTP POST handler) + chat-stream (SSE subscriber) to get a working LLM chat backed by the SSE bus.",
+	"trigger": {
+		"http": {
+			"method": "GET",
+			"path": "/chat",
+			"accept": "text/html"
+		}
+	},
+	"steps": [
+		{
+			"id": "render",
+			"use": "chat-ui",
+			"type": "module",
+			"inputs": {}
+		}
+	]
+}

package/dist/scaffold-repo/workflows/json/chat-stream.json

@@ -0,0 +1,30 @@
+{
+	"name": "Chat Stream",
+	"version": "1.0.0",
+	"description": "SSE subscriber for the chat demo. Mounts on the HTTP server's Hono app (same process as chat-message), subscribes to bus channel `chat:<sessionId>`, and pumps `token` + `done` events as SSE frames to the connected browser.",
+	"trigger": {
+		"sse": {
+			"path": "/sse/chat/:sessionId",
+			"heartbeatInterval": 15000,
+			"retryInterval": 3000
+		}
+	},
+	"steps": [
+		{
+			"id": "sub",
+			"use": "@blokjs/sse-subscribe",
+			"type": "module",
+			"inputs": {
+				"channels": ["chat:{sessionId}"]
+			}
+		},
+		{
+			"id": "stream",
+			"use": "@blokjs/sse-stream",
+			"type": "module",
+			"inputs": {
+				"source": "js/ctx.state.sub"
+			}
+		}
+	]
+}

package/dist/scaffold-repo/workflows/json/countries-vs-facts.json

@@ -0,0 +1,50 @@
+{
+	"name": "Movies or Countries",
+	"version": "1.0.0",
+	"description": "Branches on a query param: with ?countries=true returns countries; otherwise returns a random cat fact.",
+	"trigger": {
+		"http": {
+			"method": "GET",
+			"path": "/countries-vs-facts",
+			"accept": "application/json"
+		}
+	},
+	"steps": [
+		{
+			"id": "filter-request",
+			"branch": {
+				"when": "ctx.request.query.countries === \"true\"",
+				"then": [
+					{
+						"id": "get-countries",
+						"use": "@blokjs/api-call",
+						"type": "module",
+						"inputs": {
+							"url": "https://countriesnow.space/api/v0.1/countries/capital",
+							"method": "GET",
+							"headers": {
+								"Content-Type": "application/json"
+							},
+							"responseType": "application/json"
+						}
+					}
+				],
+				"else": [
+					{
+						"id": "get-facts",
+						"use": "@blokjs/api-call",
+						"type": "module",
+						"inputs": {
+							"url": "https://catfact.ninja/fact",
+							"method": "GET",
+							"headers": {
+								"Content-Type": "application/json"
+							},
+							"responseType": "application/json"
+						}
+					}
+				]
+			}
+		}
+	]
+}

package/dist/scaffold-repo/workflows/json/countries.json

@@ -0,0 +1,27 @@
+{
+	"name": "countries.listRoot",
+	"version": "1.0.0",
+	"description": "Returns a list of world countries from the public CountriesNow API.",
+	"trigger": {
+		"http": {
+			"method": "GET",
+			"path": "/countries",
+			"accept": "application/json"
+		}
+	},
+	"steps": [
+		{
+			"id": "get-countries-api",
+			"use": "@blokjs/api-call",
+			"type": "module",
+			"inputs": {
+				"url": "https://countriesnow.space/api/v0.1/countries/capital",
+				"method": "GET",
+				"headers": {
+					"Content-Type": "application/json"
+				},
+				"responseType": "application/json"
+			}
+		}
+	]
+}

package/dist/scaffold-repo/workflows/json/cron-heartbeat.json

@@ -0,0 +1,15 @@
+{
+	"name": "Cron Heartbeat",
+	"version": "1.0.0",
+	"description": "Runs on a schedule (every 5 minutes) — NOT on an HTTP request. Example of the `cron` trigger: nothing calls this; the schedule fires it. ctx.request.body is {}; fire metadata is on ctx.request.params.{schedule,firedAt}.",
+	"trigger": {
+		"cron": { "schedule": "*/5 * * * *", "timezone": "UTC" }
+	},
+	"steps": [
+		{
+			"id": "heartbeat",
+			"use": "@blokjs/api-call",
+			"inputs": { "url": "https://httpbin.org/get", "method": "GET" }
+		}
+	]
+}