blokctl 1.3.0 → 1.4.0

package/dist/scaffold-repo/triggers/http/workflows/json/cross-runtime-chain.json

@@ -0,0 +1,89 @@
+{
+	"name": "Cross-Runtime Chain Test",
+	"version": "1.2.0",
+	"description": "Tests all 8 language runtimes by chaining nodes via ctx.vars. Each SDK node appends its language to the chain array. A final verify node confirms all runtimes executed correctly.",
+	"trigger": {
+		"http": {
+			"method": "POST",
+			"path": "/cross-runtime-chain",
+			"accept": "application/json"
+		}
+	},
+	"steps": [
+		{
+			"id": "init",
+			"use": "chain-init",
+			"type": "module",
+			"inputs": {}
+		},
+		{
+			"id": "go",
+			"use": "chain-test",
+			"type": "runtime.go",
+			"inputs": {
+				"chain": "js/ctx.state['init'].chain",
+				"origin": "js/ctx.state['init'].origin"
+			}
+		},
+		{
+			"id": "rust",
+			"use": "chain-test",
+			"type": "runtime.rust",
+			"inputs": {
+				"chain": "js/ctx.state['go'].chain",
+				"origin": "js/ctx.state['go'].origin"
+			}
+		},
+		{
+			"id": "java",
+			"use": "chain-test",
+			"type": "runtime.java",
+			"inputs": {
+				"chain": "js/ctx.state['rust'].chain",
+				"origin": "js/ctx.state['rust'].origin"
+			}
+		},
+		{
+			"id": "csharp",
+			"use": "chain-test",
+			"type": "runtime.csharp",
+			"inputs": {
+				"chain": "js/ctx.state['java'].chain",
+				"origin": "js/ctx.state['java'].origin"
+			}
+		},
+		{
+			"id": "php",
+			"use": "chain-test",
+			"type": "runtime.php",
+			"inputs": {
+				"chain": "js/ctx.state['csharp'].chain",
+				"origin": "js/ctx.state['csharp'].origin"
+			}
+		},
+		{
+			"id": "ruby",
+			"use": "chain-test",
+			"type": "runtime.ruby",
+			"inputs": {
+				"chain": "js/ctx.state['php'].chain",
+				"origin": "js/ctx.state['php'].origin"
+			}
+		},
+		{
+			"id": "python",
+			"use": "chain-test",
+			"type": "runtime.python3",
+			"inputs": {
+				"chain": "js/ctx.state['ruby'].chain",
+				"origin": "js/ctx.state['ruby'].origin"
+			}
+		},
+		{
+			"id": "verify",
+			"use": "chain-verify",
+			"type": "module",
+			"inputs": {}
+		}
+	]
+}

package/dist/scaffold-repo/triggers/http/workflows/json/dashboard-gen.json

@@ -0,0 +1,34 @@
+{
+	"name": "Dashboard Charts Generator",
+	"version": "1.0.0",
+	"description": "This workflow generates multiple dashboard charts based using a postgreSQL database and AI prompts.",
+	"trigger": {
+		"http": {
+			"method": "ANY",
+			"path": "/dashboard-gen/:function?/:id?",
+			"accept": "application/json"
+		}
+	},
+	"steps": [
+		{
+			"id": "filter-request",
+			"branch": {
+				"when": "ctx.request.method.toLowerCase() === \"get\" && ctx.request.params.function === ''",
+				"then": [
+					{
+						"id": "dashboard-ui",
+						"use": "dashboard-ui",
+						"type": "module"
+					}
+				],
+				"else": [
+					{
+						"id": "method-not-allowed",
+						"use": "error",
+						"type": "module"
+					}
+				]
+			}
+		}
+	]
+}

package/dist/scaffold-repo/triggers/http/workflows/json/db-manager.json

@@ -0,0 +1,34 @@
+{
+	"name": "Database Manager",
+	"version": "1.0.0",
+	"description": "This workflow is used to query a database using an AI Prompt UI",
+	"trigger": {
+		"http": {
+			"method": "ANY",
+			"path": "/db-manager/:function?",
+			"accept": "application/json"
+		}
+	},
+	"steps": [
+		{
+			"id": "filter-request",
+			"branch": {
+				"when": "ctx.request.method.toLowerCase() === \"get\" && ctx.request.params.function === undefined",
+				"then": [
+					{
+						"id": "database-ui",
+						"use": "database-ui",
+						"type": "module"
+					}
+				],
+				"else": [
+					{
+						"id": "method-not-allowed",
+						"use": "error",
+						"type": "module"
+					}
+				]
+			}
+		}
+	]
+}

package/dist/scaffold-repo/triggers/http/workflows/json/empty.json

@@ -0,0 +1,13 @@
+{
+	"name": "Empty",
+	"version": "1.0.0",
+	"description": "Load test empty workflow",
+	"trigger": {
+		"http": {
+			"method": "GET",
+			"path": "/empty",
+			"accept": "application/json"
+		}
+	},
+	"steps": []
+}

package/dist/scaffold-repo/triggers/http/workflows/json/fanout-enqueue.json

@@ -0,0 +1,48 @@
+{
+	"name": "fanout-enqueue",
+	"version": "1.0.0",
+	"description": "v0.6.10 — Fan-out producer. POST `{items:[...], tenantId?: '...'}` and each item gets enqueued as a separate worker job on queue `fanout-jobs`. The forEach uses `mode: parallel + concurrency: 5` so 1000 items don't serialize 1000 RPCs. Each enqueue uses `dedupId: <tenantId>:<itemId>` so accidental re-submission of the same set is a no-op (BullMQ/NATS/SQS-level dedup, NOT workflow-step idempotency). Set BLOK_WORKER_ADAPTER=nats/redis/bullmq + the matching connection env vars when deploying; in-memory adapter works for single-process dev. Needs --triggers http,worker --examples at scaffold time.",
+	"trigger": {
+		"http": {
+			"method": "POST",
+			"path": "/fanout/jobs",
+			"accept": "application/json"
+		}
+	},
+	"steps": [
+		{
+			"id": "fan-out",
+			"forEach": {
+				"in": "js/Array.isArray(ctx.request.body.items) ? ctx.request.body.items : []",
+				"as": "item",
+				"mode": "parallel",
+				"concurrency": 5,
+				"do": [
+					{
+						"id": "enqueue",
+						"use": "@blokjs/worker-publish",
+						"type": "module",
+						"inputs": {
+							"queue": "fanout-jobs",
+							"payload": {
+								"item": "js/ctx.state.item",
+								"index": "js/ctx.state.itemIndex",
+								"tenantId": "js/ctx.request.body.tenantId || 'default'",
+								"enqueuedAt": "js/Date.now()"
+							},
+							"dedupId": "js/`${ctx.request.body.tenantId || 'default'}:${ctx.state.item && ctx.state.item.id ? ctx.state.item.id : ctx.state.itemIndex}`"
+						}
+					}
+				]
+			}
+		},
+		{
+			"id": "respond",
+			"use": "@blokjs/expr",
+			"type": "module",
+			"inputs": {
+				"expression": "({ ok: true, queued: (ctx.state['fan-out'] || []).length, tenantId: ctx.request.body.tenantId || 'default', jobIds: (ctx.state['fan-out'] || []).map(r => r && r.data && r.data.jobId).filter(Boolean) })"
+			}
+		}
+	]
+}

package/dist/scaffold-repo/triggers/http/workflows/json/fanout-worker.json

@@ -0,0 +1,41 @@
+{
+	"name": "fanout-worker",
+	"version": "1.0.0",
+	"description": "v0.6.10 — Fan-out consumer. Worker trigger subscribes to queue `fanout-jobs` and processes each item enqueued by fanout-enqueue. Demonstrates two reliability knobs together: (1) `concurrencyKey: $.req.body.tenantId` on the trigger limits in-flight processing to 3 jobs per tenant — keeps a noisy tenant from starving others; (2) `idempotencyKey: $.req.params.jobId` on the process step caches the result by job id so retry attempts on the same job are no-ops. Logs each processed item via @blokjs/audit-log so the run is visible in Studio. Real handlers would do the actual work (image resize, email send, ETL row, etc.) inside the `process-item` step.",
+	"trigger": {
+		"worker": {
+			"queue": "fanout-jobs",
+			"concurrency": 10,
+			"concurrencyKey": "js/ctx.request.body.tenantId || 'default'",
+			"concurrencyLimit": 3
+		}
+	},
+	"steps": [
+		{
+			"id": "process-item",
+			"use": "@blokjs/audit-log",
+			"type": "module",
+			"inputs": {
+				"event": "fanout-job-processed",
+				"attrs": {
+					"jobId": "js/ctx.request.params.jobId",
+					"queue": "js/ctx.request.params.queue",
+					"attempt": "js/ctx.request.params.attempt",
+					"tenantId": "js/ctx.request.body.tenantId",
+					"itemIndex": "js/ctx.request.body.index",
+					"item": "js/ctx.request.body.item"
+				}
+			},
+			"idempotencyKey": "js/ctx.request.params.jobId",
+			"retry": { "maxAttempts": 3, "minTimeoutInMs": 500 }
+		},
+		{
+			"id": "summary",
+			"use": "@blokjs/expr",
+			"type": "module",
+			"inputs": {
+				"expression": "({ jobId: ctx.request.params.jobId, tenantId: ctx.request.body.tenantId || 'default', itemIndex: ctx.request.body.index, processedAt: Date.now() })"
+			}
+		}
+	]
+}

package/dist/scaffold-repo/triggers/http/workflows/json/feedback.json

@@ -0,0 +1,34 @@
+{
+	"name": "feedback",
+	"version": "1.0.0",
+	"description": "",
+	"trigger": {
+		"http": {
+			"method": "ANY",
+			"path": "/feedback/:function?/:id?",
+			"accept": "application/json"
+		}
+	},
+	"steps": [
+		{
+			"id": "filter-request",
+			"branch": {
+				"when": "ctx.request.method.toLowerCase() === \"get\" && ctx.request.params.function === ''",
+				"then": [
+					{
+						"id": "feedback-ui",
+						"use": "feedback-ui",
+						"type": "module"
+					}
+				],
+				"else": [
+					{
+						"id": "method-not-allowed",
+						"use": "error",
+						"type": "module"
+					}
+				]
+			}
+		}
+	]
+}

package/dist/scaffold-repo/triggers/http/workflows/json/films.json

@@ -0,0 +1,27 @@
+{
+	"name": "Films Workflow",
+	"version": "1.0.0",
+	"description": "This workflow returns a list of films from Postgres",
+	"trigger": {
+		"http": {
+			"method": "GET",
+			"path": "/films",
+			"accept": "application/json"
+		}
+	},
+	"steps": [
+		{
+			"id": "get-films",
+			"use": "postgres-query",
+			"type": "module",
+			"inputs": {
+				"host": "localhost",
+				"port": 5432,
+				"database": "dvdrental",
+				"user": "postgres",
+				"password": "example",
+				"query": "SELECT * FROM \"film\" ORDER BY \"title\" LIMIT 50"
+			}
+		}
+	]
+}

package/dist/scaffold-repo/triggers/http/workflows/json/image-capture.json

@@ -0,0 +1,34 @@
+{
+	"name": "Image Capture & Search",
+	"version": "1.0.0",
+	"description": "This workflow captures an image and searches for it in a database.",
+	"trigger": {
+		"http": {
+			"method": "ANY",
+			"path": "/image-capture/:function?",
+			"accept": "application/json"
+		}
+	},
+	"steps": [
+		{
+			"id": "filter-request",
+			"branch": {
+				"when": "ctx.request.method.toLowerCase() === \"get\" && ctx.request.params.function === undefined",
+				"then": [
+					{
+						"id": "image-capture-ui",
+						"use": "image-capture-ui",
+						"type": "module"
+					}
+				],
+				"else": [
+					{
+						"id": "method-not-allowed",
+						"use": "error",
+						"type": "module"
+					}
+				]
+			}
+		}
+	]
+}

package/dist/scaffold-repo/triggers/http/workflows/json/launches-by-year.json

@@ -0,0 +1,27 @@
+{
+	"name": "launches-by-year",
+	"version": "1.0.0",
+	"description": "Get launches by year",
+	"trigger": {
+		"http": {
+			"method": "GET",
+			"path": "/launches-by-year",
+			"accept": "application/json"
+		}
+	},
+	"steps": [
+		{
+			"id": "api",
+			"use": "@blokjs/api-call",
+			"type": "module",
+			"inputs": {
+				"url": "https://ll.thespacedevs.com/2.3.0/launches/?format=json&year=${ctx.request.query.dob ? new Date(ctx.request.query.dob).getYear() : new Date('2000-01-01').getYear()}",
+				"method": "GET",
+				"headers": {
+					"Content-Type": "application/json"
+				},
+				"responseType": "application/json"
+			}
+		}
+	]
+}

package/dist/scaffold-repo/triggers/http/workflows/json/loadtest.json

@@ -0,0 +1,24 @@
+{
+	"name": "Load test workflow",
+	"version": "1.0.0",
+	"description": "This workflow is used to test the load on the runner.",
+	"trigger": {
+		"http": {
+			"method": "GET",
+			"path": "/loadtest",
+			"accept": "application/json"
+		}
+	},
+	"steps": [
+		{
+			"id": "mapper",
+			"use": "mapper",
+			"type": "module",
+			"inputs": {
+				"model": {
+					"success": true
+				}
+			}
+		}
+	]
+}

package/dist/scaffold-repo/triggers/http/workflows/json/middleware/admin-only.json

@@ -0,0 +1,31 @@
+{
+	"name": "admin-only",
+	"version": "1.0.0",
+	"description": "Authorization middleware that gates access on the JWT claim `role === 'admin'`. Expects a prior auth middleware (typically `jwt-auth`) to have populated `ctx.state.identity.claims`. On match, falls through; on mismatch (or missing identity), throws GlobalError(403) with a structured body. Pair with `jwt-auth` to build a complete authn+authz chain — the trigger declares both, in order, and downstream steps see the verified admin identity at ctx.state.identity.",
+	"middleware": true,
+	"steps": [
+		{
+			"id": "check-role",
+			"branch": {
+				"when": "!ctx.state.identity || !ctx.state.identity.claims || ctx.state.identity.claims.role !== 'admin'",
+				"then": [
+					{
+						"id": "respond-403",
+						"use": "@blokjs/throw",
+						"type": "module",
+						"inputs": {
+							"message": "Forbidden — admin role required",
+							"code": 403,
+							"name": "ForbiddenError",
+							"body": {
+								"error": "Forbidden",
+								"reason": "admin_role_required",
+								"hint": "JWT must carry `role: 'admin'` claim. Current role: see ctx.state.identity.claims.role"
+							}
+						}
+					}
+				]
+			}
+		}
+	]
+}

package/dist/scaffold-repo/triggers/http/workflows/json/middleware/auth-check.json

@@ -0,0 +1,59 @@
+{
+	"name": "auth-check",
+	"version": "1.0.0",
+	"description": "v0.5 middleware — header-based bearer-token check. Reads `Authorization: Bearer <token>`, asserts the token equals the literal value the workflow caller embeds in `X-Expected-Token` (demo only — real deployments swap this for JWT verify). On mismatch, throws a GlobalError with code 401 and a structured body that the trigger emits as the HTTP 401 response. On success, stashes the token at `ctx.state.identity` for downstream middleware/steps to read.",
+	"middleware": true,
+	"steps": [
+		{
+			"id": "extract-token",
+			"use": "@blokjs/expr",
+			"type": "module",
+			"inputs": {
+				"expression": "(ctx.request.headers.authorization || '').replace(/^Bearer\\s+/i, '')"
+			}
+		},
+		{
+			"id": "expected",
+			"use": "@blokjs/expr",
+			"type": "module",
+			"inputs": {
+				"expression": "ctx.request.headers['x-expected-token'] || ''"
+			}
+		},
+		{
+			"id": "deny-if-mismatch",
+			"branch": {
+				"when": "ctx.state['extract-token'] === '' || ctx.state['extract-token'] !== ctx.state.expected",
+				"then": [
+					{
+						"id": "respond-401",
+						"use": "@blokjs/throw",
+						"type": "module",
+						"inputs": {
+							"message": "Unauthorized",
+							"code": 401,
+							"name": "UnauthorizedError",
+							"body": {
+								"error": "Unauthorized",
+								"reason": "missing or invalid bearer token",
+								"hint": "set Authorization: Bearer <token> matching the X-Expected-Token header"
+							}
+						}
+					}
+				]
+			}
+		},
+		{
+			"id": "stash-identity",
+			"use": "@blokjs/ctx-publish",
+			"type": "module",
+			"inputs": {
+				"name": "identity",
+				"value": {
+					"token": "js/ctx.state['extract-token']",
+					"via": "auth-check"
+				}
+			}
+		}
+	]
+}

package/dist/scaffold-repo/triggers/http/workflows/json/middleware/github-webhook-verify.json

@@ -0,0 +1,34 @@
+{
+	"name": "github-webhook-verify",
+	"version": "1.0.0",
+	"description": "Verify a GitHub webhook signature. Reads the X-Hub-Signature-256 header and HMAC-verifies it against `ctx.request.rawBody` using the GITHUB_WEBHOOK_SECRET env var. v0.6 — verifies against the BYTES GitHub signed (`ctx.request.rawBody` is captured by HttpTrigger before JSON parsing). Pre-v0.6 used `JSON.stringify(ctx.request.body)` — a fragile round-trip that broke on whitespace + key-order differences; worked for GitHub's canonical JSON encoding but failed Stripe / Slack / any provider that signs the wire bytes. Same middleware shape now handles all three: point `payload` at `ctx.request.rawBody`. On match, falls through; on mismatch (or missing signature), throws GlobalError(401) with a structured `reason` discriminator that the catch arm / Studio can branch on.",
+	"middleware": true,
+	"steps": [
+		{
+			"id": "verify-signature",
+			"use": "@blokjs/hmac-verify",
+			"type": "module",
+			"inputs": {
+				"signature": "js/ctx.request.headers['x-hub-signature-256'] || ''",
+				"payload": "js/ctx.request.rawBody || ''",
+				"secret": "js/ctx.env.GITHUB_WEBHOOK_SECRET || ''",
+				"algorithm": "sha256",
+				"prefix": "sha256="
+			}
+		},
+		{
+			"id": "stash-event",
+			"use": "@blokjs/ctx-publish",
+			"type": "module",
+			"inputs": {
+				"name": "githubEvent",
+				"value": {
+					"type": "js/ctx.request.headers['x-github-event'] || 'unknown'",
+					"deliveryId": "js/ctx.request.headers['x-github-delivery'] || null",
+					"verified": true,
+					"via": "github-webhook-verify"
+				}
+			}
+		}
+	]
+}

package/dist/scaffold-repo/triggers/http/workflows/json/middleware/jwt-auth.json

@@ -0,0 +1,46 @@
+{
+	"name": "jwt-auth",
+	"version": "1.0.0",
+	"description": "Production JWT verification middleware. Reads `Authorization: Bearer <token>`, verifies the token with `@blokjs/jwt-verify` against an HMAC secret (HS256 default) or a JWKS endpoint (asymmetric, production case). On success, stashes the decoded JWT claims at `ctx.state.identity` for downstream middleware/steps to read. On failure, throws GlobalError(401) with a structured body — the trigger emits an actual 401 response. Configuration is sourced from env vars at run time so deploy-time secrets never live in workflow JSON: set JWT_SECRET (HS256, dev/test), JWT_JWKS_URI (RS256/ES256, production), JWT_ISSUER (expected `iss`, recommended), JWT_AUDIENCE (expected `aud`, recommended). When JWT_JWKS_URI is set, it takes precedence over JWT_SECRET. Replace this with `auth-check` only if you need the simpler header-token-equality demo for tests.",
+	"middleware": true,
+	"steps": [
+		{
+			"id": "extract-token",
+			"use": "@blokjs/expr",
+			"type": "module",
+			"inputs": {
+				"expression": "(ctx.request.headers.authorization || '').replace(/^Bearer\\s+/i, '')"
+			}
+		},
+		{
+			"id": "verify",
+			"use": "@blokjs/jwt-verify",
+			"type": "module",
+			"inputs": {
+				"token": "js/ctx.state['extract-token']",
+				"secret": "js/ctx.env.JWT_JWKS_URI ? undefined : ctx.env.JWT_SECRET",
+				"jwksUri": "js/ctx.env.JWT_JWKS_URI || undefined",
+				"issuer": "js/ctx.env.JWT_ISSUER || undefined",
+				"audience": "js/ctx.env.JWT_AUDIENCE || undefined",
+				"algorithms": "js/ctx.env.JWT_ALGORITHMS ? ctx.env.JWT_ALGORITHMS.split(',').map(s => s.trim()).filter(Boolean) : undefined",
+				"clockToleranceSeconds": "js/ctx.env.JWT_CLOCK_TOLERANCE_SECONDS ? Number(ctx.env.JWT_CLOCK_TOLERANCE_SECONDS) : undefined"
+			}
+		},
+		{
+			"id": "stash-identity",
+			"use": "@blokjs/ctx-publish",
+			"type": "module",
+			"inputs": {
+				"name": "identity",
+				"value": {
+					"sub": "js/ctx.state.verify.subject",
+					"iss": "js/ctx.state.verify.issuer",
+					"aud": "js/ctx.state.verify.audience",
+					"exp": "js/ctx.state.verify.expiresAt",
+					"claims": "js/ctx.state.verify.claims",
+					"via": "jwt-auth"
+				}
+			}
+		}
+	]
+}

package/dist/scaffold-repo/triggers/http/workflows/json/middleware/rate-limit.json

@@ -0,0 +1,70 @@
+{
+	"name": "rate-limit",
+	"version": "1.0.0",
+	"description": "v0.5 middleware — fixed-window rate limiter using @blokjs/in-memory-kv. The bucket key is `ctx.state.identity.token` if auth-check ran first, falling back to the X-Forwarded-For header. Each request reads the current bucket counter, increments it, and rejects with 429 + Retry-After when the counter exceeds the per-window limit. Demo defaults: 5 requests per 60-second window. The bucket auto-resets when the window's `expiresAt` timestamp passes — checked on every request via the same expr step, no background reaper needed.",
+	"middleware": true,
+	"steps": [
+		{
+			"id": "compute-key",
+			"use": "@blokjs/expr",
+			"type": "module",
+			"inputs": {
+				"expression": "(ctx.state.identity && ctx.state.identity.token) ? `user:${ctx.state.identity.token}` : `ip:${ctx.request.headers['x-forwarded-for'] || ctx.request.headers['x-real-ip'] || 'unknown'}`"
+			}
+		},
+		{
+			"id": "load-bucket",
+			"use": "@blokjs/in-memory-kv",
+			"type": "module",
+			"inputs": {
+				"action": "get",
+				"key": "js/`bucket:${ctx.state['compute-key']}`"
+			}
+		},
+		{
+			"id": "next-state",
+			"use": "@blokjs/expr",
+			"type": "module",
+			"inputs": {
+				"expression": "((b) => { const now = Date.now(); const limit = 5; const windowMs = 60000; if (!b || typeof b.expiresAt !== 'number' || b.expiresAt <= now) { return { count: 1, expiresAt: now + windowMs, exceeded: false, retryAfterSec: 0 }; } if (b.count + 1 > limit) { return { count: b.count, expiresAt: b.expiresAt, exceeded: true, retryAfterSec: Math.max(1, Math.ceil((b.expiresAt - now) / 1000)) }; } return { count: b.count + 1, expiresAt: b.expiresAt, exceeded: false, retryAfterSec: 0 }; })((ctx.state['load-bucket'] && ctx.state['load-bucket'].value) || null)"
+			}
+		},
+		{
+			"id": "save-bucket",
+			"use": "@blokjs/in-memory-kv",
+			"type": "module",
+			"inputs": {
+				"action": "set",
+				"key": "js/`bucket:${ctx.state['compute-key']}`",
+				"value": {
+					"count": "js/ctx.state['next-state'].count",
+					"expiresAt": "js/ctx.state['next-state'].expiresAt"
+				}
+			}
+		},
+		{
+			"id": "deny-if-exceeded",
+			"branch": {
+				"when": "ctx.state['next-state'].exceeded",
+				"then": [
+					{
+						"id": "respond-429",
+						"use": "@blokjs/throw",
+						"type": "module",
+						"inputs": {
+							"message": "Rate limit exceeded",
+							"code": 429,
+							"name": "RateLimitExceededError",
+							"body": {
+								"error": "Rate limit exceeded",
+								"limit": 5,
+								"windowSeconds": 60,
+								"retryAfterSec": "js/ctx.state['next-state'].retryAfterSec"
+							}
+						}
+					}
+				]
+			}
+		}
+	]
+}