blokctl 1.3.0 → 1.4.0

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

@@ -0,0 +1,71 @@
+{
+	"name": "redis-rate-limit",
+	"version": "1.0.0",
+	"description": "v0.5.2 middleware — fixed-window rate limiter backed by Redis. Mirrors `rate-limit.json` step-for-step but swaps `@blokjs/in-memory-kv` for `@blokjs/redis-kv`, so counters survive process restarts and synchronize across replicas (the in-memory variant is process-local — fine for single-process dev, wrong for production behind a load balancer). The bucket key is `ctx.state.identity.token` if an auth middleware ran first, falling back to the X-Forwarded-For header. Demo defaults: 5 requests per 60s window. Connects via REDIS_URL env (default redis://127.0.0.1:6379). Per-key TTL is set via Redis SET ... PX <windowMs> so expired buckets evict automatically — no background reaper needed.",
+	"middleware": true,
+	"steps": [
+		{
+			"id": "compute-key",
+			"use": "@blokjs/expr",
+			"type": "module",
+			"inputs": {
+				"expression": "(ctx.state.identity && (ctx.state.identity.sub || ctx.state.identity.token)) ? `user:${ctx.state.identity.sub || ctx.state.identity.token}` : `ip:${ctx.request.headers['x-forwarded-for'] || ctx.request.headers['x-real-ip'] || 'unknown'}`"
+			}
+		},
+		{
+			"id": "load-bucket",
+			"use": "@blokjs/redis-kv",
+			"type": "module",
+			"inputs": {
+				"action": "get",
+				"key": "js/`blok:rate-limit:${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, ttlMs: windowMs }; } if (b.count + 1 > limit) { return { count: b.count, expiresAt: b.expiresAt, exceeded: true, retryAfterSec: Math.max(1, Math.ceil((b.expiresAt - now) / 1000)), ttlMs: Math.max(1, b.expiresAt - now) }; } return { count: b.count + 1, expiresAt: b.expiresAt, exceeded: false, retryAfterSec: 0, ttlMs: Math.max(1, b.expiresAt - now) }; })((ctx.state['load-bucket'] && ctx.state['load-bucket'].value) || null)"
+			}
+		},
+		{
+			"id": "save-bucket",
+			"use": "@blokjs/redis-kv",
+			"type": "module",
+			"inputs": {
+				"action": "set",
+				"key": "js/`blok:rate-limit:${ctx.state['compute-key']}`",
+				"value": {
+					"count": "js/ctx.state['next-state'].count",
+					"expiresAt": "js/ctx.state['next-state'].expiresAt"
+				},
+				"ttlMs": "js/ctx.state['next-state'].ttlMs"
+			}
+		},
+		{
+			"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"
+							}
+						}
+					}
+				]
+			}
+		}
+	]
+}

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

@@ -0,0 +1,24 @@
+{
+	"name": "MongoDB CRUD API",
+	"version": "1.0.0",
+	"description": "Provides a RESTful API to interact dynamically with MongoDB collections.",
+	"trigger": {
+		"http": {
+			"method": "ANY",
+			"path": "/mongo/:collection/:id?",
+			"accept": "application/json"
+		}
+	},
+	"steps": [
+		{
+			"id": "mongodb_query",
+			"use": "mongodb-query",
+			"type": "module",
+			"inputs": {
+				"collection": "${ctx.request.params.collection}",
+				"data": "js/ctx.request.body",
+				"id": "${ctx.request.params.id}"
+			}
+		}
+	]
+}

package/dist/scaffold-repo/triggers/http/workflows/json/rentals-pdf.json

@@ -0,0 +1,65 @@
+{
+	"name": "rentals-pdf",
+	"version": "1.0.0",
+	"description": "Generate a PDF from a rental database",
+	"trigger": {
+		"http": {
+			"method": "GET",
+			"path": "/rentals-pdf",
+			"accept": "application/json"
+		}
+	},
+	"steps": [
+		{
+			"id": "get-rentals",
+			"use": "postgres-query",
+			"type": "module",
+			"inputs": {
+				"host": "localhost",
+				"port": 5432,
+				"database": "dvdrental",
+				"user": "postgres",
+				"password": "example",
+				"query": "SELECT f.title as product, SUM(p.amount) as total, ROUND(SUM(p.amount) / COUNT(*), 2) as price, DATE_TRUNC('month', r.rental_date) AS rental_month, COUNT(*) AS quantity FROM rental r INNER JOIN inventory i ON i.inventory_id = r.inventory_id INNER JOIN film f ON f.film_id = i.film_id INNER JOIN payment p ON p.rental_id = r.rental_id GROUP BY r.inventory_id, rental_month, f.title ORDER BY total DESC LIMIT 20;"
+			}
+		},
+		{
+			"id": "format-data",
+			"use": "array-map",
+			"type": "module",
+			"inputs": {
+				"array": "js/ctx.prev.data.data",
+				"map": "{ product: data.product, quantity: parseInt(data.quantity), total: parseInt(data.total), price: parseInt(data.price), rental_month: data.rental_month }"
+			}
+		},
+		{
+			"id": "generate-pdf",
+			"use": "generate-pdf",
+			"type": "runtime.python3",
+			"inputs": {
+				"title": "Top 20 Films by Revenue",
+				"sales_data": "js/ctx.prev.data"
+			}
+		},
+		{
+			"id": "decode",
+			"use": "base64-pdf",
+			"type": "module",
+			"inputs": {
+				"base64": "${ctx.prev.data.pdf_base64}"
+			}
+		},
+		{
+			"id": "response",
+			"use": "@blokjs/respond",
+			"type": "module",
+			"inputs": {
+				"body": "js/ctx.state.decode",
+				"contentType": "application/pdf",
+				"headers": {
+					"Content-Disposition": "attachment; filename=\"rentals.pdf\""
+				}
+			}
+		}
+	]
+}

package/dist/scaffold-repo/triggers/http/workflows/json/v05-admin-delete-user.json

@@ -0,0 +1,42 @@
+{
+	"name": "v05-admin-delete-user",
+	"version": "1.0.0",
+	"description": "Admin-only endpoint demonstrating a full authn+authz middleware chain at the workflow level. `jwt-auth` verifies the bearer token and stashes identity at ctx.state.identity; `admin-only` then asserts the JWT's `role` claim equals `admin` (else 403); only then does the handler step run. The handler simulates a destructive operation (DELETE user) by POSTing to httpbin so end-to-end tests can curl the failure-response shape without persistence. The same chain composes onto any sensitive endpoint with one line — that's the v0.5.2 win. Replace `jwt-auth` with your provider's JWKS in production by setting JWT_JWKS_URI; the `role` check stays unchanged.",
+	"middleware": ["jwt-auth", "admin-only"],
+	"trigger": {
+		"http": {
+			"method": "POST",
+			"path": "/v05-admin-delete-user",
+			"accept": "application/json"
+		}
+	},
+	"steps": [
+		{
+			"id": "delete-user",
+			"use": "@blokjs/api-call",
+			"type": "module",
+			"inputs": {
+				"url": "https://httpbin.org/post",
+				"method": "POST",
+				"headers": {
+					"Content-Type": "application/json",
+					"X-Op": "delete-user"
+				},
+				"body": {
+					"action": "delete-user",
+					"targetUserId": "js/ctx.request.body.userId",
+					"deletedBy": "js/ctx.state.identity.sub"
+				},
+				"responseType": "application/json"
+			}
+		},
+		{
+			"id": "respond",
+			"use": "@blokjs/expr",
+			"type": "module",
+			"inputs": {
+				"expression": "({ ok: true, action: 'delete-user', targetUserId: ctx.request.body.userId, deletedBy: ctx.state.identity.sub })"
+			}
+		}
+	]
+}

package/dist/scaffold-repo/triggers/http/workflows/json/v05-async-job-poller.json

@@ -0,0 +1,45 @@
+{
+	"name": "v05-async-job-poller",
+	"version": "1.0.0",
+	"description": "v0.6 wait-inside-primitives Phase 2 demo — sequential forEach with a wait inside the iteration body. The handler iterates over a list of job IDs from `req.body.jobs`, simulates polling each job (recording a result), then waits 100ms before the next iteration so an external service isn't hammered. The wait inside the iteration body is the load-bearing test of v0.6 Phase 2: each iteration's wait fires `WaitDispatchRequest` from inside the forEach iteration scope, the runner persists the iteration cursor to `node_runs.iteration_context`, defers the run, then on `dispatchDeferred` re-entry the forEach skips iterations [0..N-1] (using the cached `completedResults`) and resumes iteration N at innerStepIndex 1 (the wait), which flips to satisfied because the timer has fired. Real-world analogue: bulk-notify with a per-recipient throttle, async-job poller cycling through multiple jobs, batch reconciliation with rate-limited inner steps. Each iteration round-trips via dispatchDeferred so 3 jobs ≈ 300ms wall-clock; smoke validates the first 202 + Location header (full round-trip is verified in the vitest integration suite).",
+	"trigger": {
+		"http": {
+			"method": "POST",
+			"path": "/v05-async-job-poller",
+			"accept": "application/json"
+		}
+	},
+	"steps": [
+		{
+			"id": "process-jobs",
+			"forEach": {
+				"in": "js/ctx.request.body.jobs",
+				"as": "job",
+				"do": [
+					{
+						"id": "record-job",
+						"use": "@blokjs/expr",
+						"type": "module",
+						"inputs": {
+							"expression": "({ jobId: ctx.state.job, processedAt: Date.now(), status: 'completed' })"
+						}
+					},
+					{
+						"id": "throttle",
+						"wait": {
+							"for": "100ms"
+						}
+					}
+				]
+			}
+		},
+		{
+			"id": "respond",
+			"use": "@blokjs/expr",
+			"type": "module",
+			"inputs": {
+				"expression": "({ ok: true, totalJobs: ctx.state['process-jobs'].length, results: ctx.state['process-jobs'] })"
+			}
+		}
+	]
+}

package/dist/scaffold-repo/triggers/http/workflows/json/v05-csv-import.json

@@ -0,0 +1,122 @@
+{
+	"name": "v05-csv-import",
+	"version": "1.0.0",
+	"description": "CSV-import pipeline with per-row resilience. Receives an array of rows in the body and processes each through validate → transform → insert. Each row is wrapped in its own tryCatch, so a single bad row doesn't abort the whole import — failed rows go to a per-row DLQ slot the response surfaces. Real deployments swap the inline `inserts` summary for an actual DLQ table or queue. Demonstrates: forEach (sequential — DB inserts shouldn't run wild) + per-iteration tryCatch with $.error.message into the DLQ payload + iter-summary expr that distinguishes ok from failed for the post-loop summary.",
+	"trigger": {
+		"http": {
+			"method": "POST",
+			"path": "/v05-csv-import",
+			"accept": "application/json"
+		}
+	},
+	"steps": [
+		{
+			"id": "validate-body",
+			"use": "@blokjs/json-schema",
+			"type": "module",
+			"inputs": {
+				"schema": {
+					"type": "object",
+					"required": ["rows"],
+					"properties": {
+						"rows": {
+							"type": "array"
+						}
+					}
+				},
+				"data": "js/ctx.request.body"
+			}
+		},
+		{
+			"id": "process-rows",
+			"forEach": {
+				"in": "js/ctx.request.body.rows",
+				"as": "row",
+				"mode": "sequential",
+				"do": [
+					{
+						"id": "row-tryCatch",
+						"tryCatch": {
+							"try": [
+								{
+									"id": "validate-row",
+									"use": "@blokjs/json-schema",
+									"type": "module",
+									"inputs": {
+										"schema": {
+											"type": "object",
+											"required": ["id", "value"],
+											"properties": {
+												"id": {
+													"type": "string"
+												},
+												"value": {
+													"type": "number"
+												}
+											}
+										},
+										"data": "js/ctx.state.row"
+									}
+								},
+								{
+									"id": "insert-row",
+									"use": "@blokjs/api-call",
+									"type": "module",
+									"inputs": {
+										"url": "js/ctx.state.row.insertUrl || 'https://httpbin.org/post'",
+										"method": "POST",
+										"headers": {
+											"Content-Type": "application/json",
+											"X-Op": "insert-row"
+										},
+										"body": {
+											"rowId": "js/ctx.state.row.id",
+											"value": "js/ctx.state.row.value"
+										},
+										"responseType": "application/json"
+									}
+								}
+							],
+							"catch": [
+								{
+									"id": "log-failed-row",
+									"use": "@blokjs/log",
+									"type": "module",
+									"inputs": {
+										"level": "warn",
+										"message": "js/`csv-import: row ${ctx.state.row.id || '<missing-id>'} failed: ${ctx.error.message}`"
+									}
+								},
+								{
+									"id": "capture-row-error",
+									"use": "@blokjs/ctx-publish",
+									"type": "module",
+									"inputs": {
+										"name": "rowError",
+										"value": "js/ctx.error.message"
+									}
+								}
+							]
+						}
+					},
+					{
+						"id": "iter-summary",
+						"use": "@blokjs/expr",
+						"type": "module",
+						"inputs": {
+							"expression": "({ rowId: ctx.state.row.id || null, ok: ctx.state['insert-row'] !== undefined, error: ctx.state.rowError || null })"
+						}
+					}
+				]
+			}
+		},
+		{
+			"id": "respond",
+			"use": "@blokjs/expr",
+			"type": "module",
+			"inputs": {
+				"expression": "((arr) => { const summaries = arr.map(r => (r && r.data && typeof r.data === 'object') ? r.data : r); const ok = summaries.filter(s => s && s.ok === true); const failed = summaries.filter(s => s && s.ok === false); return { totalRows: summaries.length, inserted: ok.length, dlq: failed.map(f => ({ rowId: f.rowId, error: f.error })) }; })(ctx.state['process-rows'] || [])"
+			}
+		}
+	]
+}

package/dist/scaffold-repo/triggers/http/workflows/json/v05-data-export.json

@@ -0,0 +1,105 @@
+{
+	"name": "v05-data-export",
+	"version": "1.0.0",
+	"description": "Paginated data export pipeline with per-page resilience. Receives a page list, fetches each page sequentially (rate-limit friendly), and falls back to a DLQ entry when a page fetch fails after retries. Each page fetch carries `retry: { maxAttempts: 3 }` and a `maxDuration: 5s` cap so transient failures self-heal but pathological hangs don't stall the whole export. Successful pages contribute to a final assemble step that summarizes total rows + DLQ count. Demonstrates: forEach + tryCatch nested with per-step retry + maxDuration, resilient ETL pattern that surfaces failed pages without aborting the run.",
+	"trigger": {
+		"http": {
+			"method": "POST",
+			"path": "/v05-data-export",
+			"accept": "application/json"
+		}
+	},
+	"steps": [
+		{
+			"id": "validate-body",
+			"use": "@blokjs/json-schema",
+			"type": "module",
+			"inputs": {
+				"schema": {
+					"type": "object",
+					"required": ["pages"],
+					"properties": {
+						"pages": {
+							"type": "array"
+						}
+					}
+				},
+				"data": "js/ctx.request.body"
+			}
+		},
+		{
+			"id": "fetch-pages",
+			"forEach": {
+				"in": "js/ctx.request.body.pages",
+				"as": "page",
+				"mode": "sequential",
+				"do": [
+					{
+						"id": "page-tryCatch",
+						"tryCatch": {
+							"try": [
+								{
+									"id": "fetch-page",
+									"use": "@blokjs/api-call",
+									"type": "module",
+									"retry": {
+										"maxAttempts": 3,
+										"minTimeoutInMs": 100,
+										"factor": 2
+									},
+									"maxDuration": "5s",
+									"inputs": {
+										"url": "js/ctx.state.page.url",
+										"method": "GET",
+										"headers": {
+											"Accept": "application/json"
+										},
+										"responseType": "application/json"
+									}
+								}
+							],
+							"catch": [
+								{
+									"id": "audit-page-failure",
+									"use": "@blokjs/audit-log",
+									"type": "module",
+									"inputs": {
+										"event": "data-export-page-failure",
+										"page": "js/ctx.state.page.number",
+										"url": "js/ctx.state.page.url",
+										"reason": "js/ctx.error.message"
+									}
+								},
+								{
+									"id": "capture-page-error",
+									"use": "@blokjs/ctx-publish",
+									"type": "module",
+									"inputs": {
+										"name": "pageError",
+										"value": "js/ctx.error.message"
+									}
+								}
+							]
+						}
+					},
+					{
+						"id": "page-summary",
+						"use": "@blokjs/expr",
+						"type": "module",
+						"inputs": {
+							"expression": "({ page: ctx.state.page.number, ok: ctx.state['fetch-page'] !== undefined, rowCount: ctx.state['fetch-page'] && ctx.state['fetch-page'].args ? Object.keys(ctx.state['fetch-page'].args).length : 0, error: ctx.state.pageError || null })"
+						}
+					}
+				]
+			}
+		},
+		{
+			"id": "assemble",
+			"use": "@blokjs/expr",
+			"type": "module",
+			"inputs": {
+				"expression": "((arr) => { const summaries = arr.map(r => (r && r.data && typeof r.data === 'object') ? r.data : r); const ok = summaries.filter(s => s && s.ok === true); const failed = summaries.filter(s => s && s.ok === false); return { exported: true, totalPages: summaries.length, successfulPages: ok.length, totalRows: ok.reduce((sum, s) => sum + (s.rowCount || 0), 0), dlqPages: failed.map(f => ({ page: f.page, error: f.error })) }; })(ctx.state['fetch-pages'] || [])"
+			}
+		}
+	]
+}

package/dist/scaffold-repo/triggers/http/workflows/json/v05-event-router.json

@@ -0,0 +1,97 @@
+{
+	"name": "v05-event-router",
+	"version": "1.0.0",
+	"description": "v0.5 switch primitive — N-way event router. Receives an event { event, payload } and dispatches to a per-event handler that POSTs a synthesized envelope to httpbin.org/post (which echoes our payload back). Demonstrates: literal `when` (single match), array `when` (group related events), `default` fallback for unknown events, and that case mutations carry forward to subsequent top-level steps.",
+	"trigger": {
+		"http": {
+			"method": "POST",
+			"path": "/v05-event-router",
+			"accept": "application/json"
+		}
+	},
+	"steps": [
+		{
+			"id": "route",
+			"switch": {
+				"on": "js/ctx.request.body.event",
+				"cases": [
+					{
+						"when": "ping",
+						"do": [
+							{
+								"id": "ping-handler",
+								"use": "@blokjs/api-call",
+								"type": "module",
+								"inputs": {
+									"url": "https://httpbin.org/post",
+									"method": "POST",
+									"headers": {
+										"Content-Type": "application/json",
+										"X-Handler": "ping"
+									},
+									"body": {
+										"ack": "pong",
+										"payload": "js/ctx.request.body.payload"
+									},
+									"responseType": "application/json"
+								}
+							}
+						]
+					},
+					{
+						"when": ["order.created", "order.paid", "order.refunded"],
+						"do": [
+							{
+								"id": "order-handler",
+								"use": "@blokjs/api-call",
+								"type": "module",
+								"inputs": {
+									"url": "https://httpbin.org/post",
+									"method": "POST",
+									"headers": {
+										"Content-Type": "application/json",
+										"X-Handler": "order-family"
+									},
+									"body": {
+										"recorded": true,
+										"event": "js/ctx.request.body.event",
+										"payload": "js/ctx.request.body.payload"
+									},
+									"responseType": "application/json"
+								}
+							}
+						]
+					}
+				],
+				"default": [
+					{
+						"id": "default-handler",
+						"use": "@blokjs/api-call",
+						"type": "module",
+						"inputs": {
+							"url": "https://httpbin.org/post",
+							"method": "POST",
+							"headers": {
+								"Content-Type": "application/json",
+								"X-Handler": "unknown"
+							},
+							"body": {
+								"warning": "unknown event",
+								"event": "js/ctx.request.body.event"
+							},
+							"responseType": "application/json"
+						}
+					}
+				]
+			}
+		},
+		{
+			"id": "summary",
+			"use": "@blokjs/expr",
+			"type": "module",
+			"inputs": {
+				"expression": "({ routedAs: (((ctx.state['ping-handler'] && 'ping') || (ctx.state['order-handler'] && 'order-family') || (ctx.state['default-handler'] && 'unknown')) || null), event: ctx.request.body.event, echo: (ctx.state['ping-handler'] || ctx.state['order-handler'] || ctx.state['default-handler']) && (ctx.state['ping-handler'] || ctx.state['order-handler'] || ctx.state['default-handler']).json })"
+			}
+		}
+	]
+}

package/dist/scaffold-repo/triggers/http/workflows/json/v05-github-handler-issues.json

@@ -0,0 +1,22 @@
+{
+	"name": "v05-github-handler-issues",
+	"version": "1.0.0",
+	"description": "Per-event GitHub webhook sub-workflow: handles the issue family (issues, issue_comment). Same grouping pattern as the pull-request handler.",
+	"trigger": {
+		"http": {
+			"method": "POST",
+			"path": "/v05-github-handler-issues",
+			"accept": "application/json"
+		}
+	},
+	"steps": [
+		{
+			"id": "respond",
+			"use": "@blokjs/expr",
+			"type": "module",
+			"inputs": {
+				"expression": "({ handler: 'issues-family', action: ctx.request.body.action || null, issueNumber: (ctx.request.body.issue && ctx.request.body.issue.number) || null, eventType: ctx.request.body._eventType || null })"
+			}
+		}
+	]
+}

package/dist/scaffold-repo/triggers/http/workflows/json/v05-github-handler-pr.json

@@ -0,0 +1,22 @@
+{
+	"name": "v05-github-handler-pr",
+	"version": "1.0.0",
+	"description": "Per-event GitHub webhook sub-workflow: handles the pull-request family (pull_request, pull_request_review, pull_request_review_comment). Real deployments would update review state, post status checks, run lint/preview pipelines. The router groups this whole family via switch-case `when: [...]` so all PR-adjacent events flow through the same sub-workflow.",
+	"trigger": {
+		"http": {
+			"method": "POST",
+			"path": "/v05-github-handler-pr",
+			"accept": "application/json"
+		}
+	},
+	"steps": [
+		{
+			"id": "respond",
+			"use": "@blokjs/expr",
+			"type": "module",
+			"inputs": {
+				"expression": "({ handler: 'pr-family', action: ctx.request.body.action || null, prNumber: (ctx.request.body.pull_request && ctx.request.body.pull_request.number) || null, eventType: ctx.request.body._eventType || null })"
+			}
+		}
+	]
+}

package/dist/scaffold-repo/triggers/http/workflows/json/v05-github-handler-push.json

@@ -0,0 +1,22 @@
+{
+	"name": "v05-github-handler-push",
+	"version": "1.0.0",
+	"description": "Per-event GitHub webhook sub-workflow: handles `push`. Real deployments would update a build queue, kick off CI, post to Slack — this minimal version just summarizes the push for the smoke gate. Invoked from v05-github-webhook-router via the `subworkflow:` step shape.",
+	"trigger": {
+		"http": {
+			"method": "POST",
+			"path": "/v05-github-handler-push",
+			"accept": "application/json"
+		}
+	},
+	"steps": [
+		{
+			"id": "respond",
+			"use": "@blokjs/expr",
+			"type": "module",
+			"inputs": {
+				"expression": "({ handler: 'push', repo: ctx.request.body.repo || null, ref: ctx.request.body.ref || null, commits: Array.isArray(ctx.request.body.commits) ? ctx.request.body.commits.length : 0 })"
+			}
+		}
+	]
+}