blokctl 1.3.0 → 1.4.0

package/dist/scaffold-repo/triggers/http/workflows/json/v05-user-signup-saga.json

@@ -0,0 +1,186 @@
+{
+	"name": "v05-user-signup-saga",
+	"version": "1.0.0",
+	"description": "v0.5 tryCatch with conditional rollback inside the catch arm. Try arm: POST signupUrl (account create), POST httpbin (welcome email), POST profileUrl (profile create). Catch arm: branches on whether `ctx.state['create-account']` exists — only rolls back if the account actually got created. Finally: emits an audit event regardless. Demonstrates: tryCatch with all three arms; branch INSIDE catch to make rollback conditional; @blokjs/throw inside catch to surface a structured 500 with the failure reason. External fixtures: httpbin.org (set signupUrl=/status/500 to fail before account-create — no rollback; set profileUrl=/status/500 to fail AFTER account-create — rollback fires).",
+	"trigger": {
+		"http": {
+			"method": "POST",
+			"path": "/v05-user-signup-saga",
+			"accept": "application/json"
+		}
+	},
+	"steps": [
+		{
+			"id": "validate-input",
+			"use": "@blokjs/json-schema",
+			"type": "module",
+			"inputs": {
+				"schema": {
+					"type": "object",
+					"required": ["email", "password", "displayName", "signupUrl"],
+					"properties": {
+						"email": {
+							"type": "string"
+						},
+						"password": {
+							"type": "string"
+						},
+						"displayName": {
+							"type": "string"
+						},
+						"signupUrl": {
+							"type": "string"
+						}
+					}
+				},
+				"data": "js/ctx.request.body"
+			}
+		},
+		{
+			"id": "signup-saga",
+			"tryCatch": {
+				"try": [
+					{
+						"id": "create-account",
+						"use": "@blokjs/api-call",
+						"type": "module",
+						"inputs": {
+							"url": "js/ctx.request.body.signupUrl",
+							"method": "POST",
+							"headers": {
+								"Content-Type": "application/json",
+								"X-Step": "create-account"
+							},
+							"body": {
+								"email": "js/ctx.request.body.email",
+								"displayName": "js/ctx.request.body.displayName"
+							},
+							"responseType": "application/json"
+						}
+					},
+					{
+						"id": "send-welcome",
+						"use": "@blokjs/api-call",
+						"type": "module",
+						"inputs": {
+							"url": "https://httpbin.org/post",
+							"method": "POST",
+							"headers": {
+								"Content-Type": "application/json",
+								"X-Step": "send-welcome"
+							},
+							"body": {
+								"to": "js/ctx.request.body.email",
+								"template": "welcome"
+							},
+							"responseType": "application/json"
+						}
+					},
+					{
+						"id": "create-profile",
+						"use": "@blokjs/api-call",
+						"type": "module",
+						"inputs": {
+							"url": "js/ctx.request.body.profileUrl || ctx.request.body.signupUrl",
+							"method": "POST",
+							"headers": {
+								"Content-Type": "application/json",
+								"X-Step": "create-profile"
+							},
+							"body": {
+								"email": "js/ctx.request.body.email",
+								"displayName": "js/ctx.request.body.displayName"
+							},
+							"responseType": "application/json"
+						}
+					}
+				],
+				"catch": [
+					{
+						"id": "decide-rollback",
+						"branch": {
+							"when": "ctx.state['create-account'] !== undefined",
+							"then": [
+								{
+									"id": "rollback-account",
+									"use": "@blokjs/api-call",
+									"type": "module",
+									"inputs": {
+										"url": "https://httpbin.org/post",
+										"method": "POST",
+										"headers": {
+											"Content-Type": "application/json",
+											"X-Step": "rollback-account"
+										},
+										"body": {
+											"reason": "signup-saga-rollback",
+											"email": "js/ctx.request.body.email"
+										},
+										"responseType": "application/json"
+									}
+								},
+								{
+									"id": "mark-rolled-back",
+									"use": "@blokjs/ctx-publish",
+									"type": "module",
+									"inputs": {
+										"name": "rolledBack",
+										"value": true
+									}
+								}
+							],
+							"else": [
+								{
+									"id": "mark-no-rollback",
+									"use": "@blokjs/ctx-publish",
+									"type": "module",
+									"inputs": {
+										"name": "rolledBack",
+										"value": false
+									}
+								}
+							]
+						}
+					},
+					{
+						"id": "respond-failed",
+						"use": "@blokjs/throw",
+						"type": "module",
+						"inputs": {
+							"message": "Signup failed",
+							"code": 500,
+							"name": "SignupFailedError",
+							"body": {
+								"outcome": "failed",
+								"rolledBack": "js/ctx.state.rolledBack === true",
+								"reason": "js/ctx.error.message",
+								"errorName": "js/ctx.error.name",
+								"failedAt": "js/ctx.error.stepId",
+								"upstreamCode": "js/ctx.error.code || null"
+							}
+						}
+					}
+				],
+				"finally": [
+					{
+						"id": "metric",
+						"use": "@blokjs/audit-log",
+						"type": "module",
+						"inputs": {
+							"event": "signup-attempt",
+							"email": "js/ctx.request.body.email"
+						}
+					}
+				]
+			}
+		},
+		{
+			"id": "respond-success",
+			"use": "@blokjs/expr",
+			"type": "module",
+			"inputs": {
+				"expression": "({ outcome: 'success', userId: ctx.request.body.email, email: ctx.request.body.email, displayName: ctx.request.body.displayName })"
+			}
+		}
+	]
+}

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

@@ -0,0 +1,49 @@
+{
+	"name": "v05-webhook-fanout",
+	"version": "1.0.0",
+	"description": "v0.5 forEach (parallel, bounded concurrency) primitive — receives an event payload + a list of subscribers, then dispatches the event to every subscriber URL in parallel with concurrency capped at 5. Each iteration is an api-call POST. Returns the per-subscriber dispatch results so callers can inspect which deliveries succeeded.",
+	"trigger": {
+		"http": {
+			"method": "POST",
+			"path": "/v05-webhook-fanout",
+			"accept": "application/json"
+		}
+	},
+	"steps": [
+		{
+			"id": "dispatch-to-each",
+			"forEach": {
+				"in": "js/ctx.request.body.subscribers",
+				"as": "subscriber",
+				"mode": "parallel",
+				"concurrency": 5,
+				"do": [
+					{
+						"id": "post",
+						"use": "@blokjs/api-call",
+						"type": "module",
+						"inputs": {
+							"url": "js/ctx.state.subscriber.url",
+							"method": "POST",
+							"headers": {
+								"Content-Type": "application/json",
+								"X-Webhook-Subscriber": "js/ctx.state.subscriber.id",
+								"X-Event-Id": "js/ctx.request.body.event.id"
+							},
+							"body": "js/ctx.request.body.event",
+							"responseType": "application/json"
+						}
+					}
+				]
+			}
+		},
+		{
+			"id": "summary",
+			"use": "@blokjs/expr",
+			"type": "module",
+			"inputs": {
+				"expression": "({ eventId: ctx.request.body.event.id, dispatched: (ctx.state['dispatch-to-each'] || []).length, subscriberIds: (ctx.request.body.subscribers || []).map(s => s.id) })"
+			}
+		}
+	]
+}

package/dist/scaffold-repo/triggers/http/workflows/json/v06-reliability-showcase.json

@@ -0,0 +1,80 @@
+{
+	"name": "v06-reliability-showcase",
+	"version": "1.0.0",
+	"description": "v0.6 reliability primitives sampler — one workflow exercising idempotencyKey + retry + maxDuration + recordSample + concurrencyKey. POST it once and the empty-state curl in Studio captures the real body via `recordSample: true`; POST it twice with the same `requestId` and the second call short-circuits via the idempotency cache; flood it with the same `tenant` and the concurrency gate caps in-flight to 3. Each step's settings are tunable inline so this is also a 5-minute hands-on tour of the primitives covered in docs/c/migration-guides/v1-to-v2-reliability.mdx.",
+	"trigger": {
+		"http": {
+			"method": "POST",
+			"path": "/v06-reliability-showcase",
+			"accept": "application/json",
+			"recordSample": true,
+			"examples": {
+				"body": {
+					"requestId": "req-demo-001",
+					"tenant": "acme",
+					"order": { "id": "ord-42", "amount": 1999, "currency": "USD" }
+				}
+			},
+			"concurrencyKey": "$.req.body.tenant",
+			"concurrencyLimit": 3
+		}
+	},
+	"steps": [
+		{
+			"id": "fetch-rates",
+			"use": "@blokjs/api-call",
+			"type": "module",
+			"description": "External call exercising retry + maxDuration. Each attempt gets its own 8s budget; up to 3 attempts with capped exponential backoff.",
+			"inputs": {
+				"url": "https://httpbin.org/json",
+				"method": "GET",
+				"headers": {
+					"Accept": "application/json"
+				},
+				"responseType": "application/json"
+			},
+			"retry": {
+				"maxAttempts": 3,
+				"minTimeoutInMs": 500,
+				"maxTimeoutInMs": 5000,
+				"factor": 2
+			},
+			"maxDuration": "8s"
+		},
+		{
+			"id": "process-order",
+			"use": "@blokjs/api-call",
+			"type": "module",
+			"description": "Expensive step gated by idempotencyKey — on retry / replay / duplicate trigger with the same requestId, the cached envelope replays without re-running step.process().",
+			"idempotencyKey": "$.req.body.requestId",
+			"idempotencyKeyTTL": 86400000,
+			"inputs": {
+				"url": "https://httpbin.org/post",
+				"method": "POST",
+				"headers": {
+					"Content-Type": "application/json",
+					"X-Request-Id": "$.req.body.requestId"
+				},
+				"body": {
+					"order": "$.req.body.order",
+					"rates": "$.state.fetch-rates"
+				},
+				"responseType": "application/json"
+			}
+		},
+		{
+			"id": "respond",
+			"use": "@blokjs/respond",
+			"type": "module",
+			"inputs": {
+				"body": {
+					"requestId": "$.req.body.requestId",
+					"tenant": "$.req.body.tenant",
+					"order": "$.req.body.order",
+					"slip": "$.state.process-order"
+				},
+				"status": 200
+			}
+		}
+	]
+}

package/dist/scaffold-repo/triggers/http/workflows/json/v07-sse-publish.json

@@ -0,0 +1,24 @@
+{
+	"name": "v07-sse-publish",
+	"version": "1.0.0",
+	"description": "v0.7 PR 3 demo — companion to v07-sse-stream. POST `{event, data}` to /v07-sse-publish (legacy dispatch URL) and every SSE client connected to /sse/demo receives the event in real time via @blokjs/sse-publish. Demonstrates the in-process pub/sub model: publishers (HTTP, Cron, Worker, WS) and subscribers (SSE) decouple through the bus.",
+	"trigger": {
+		"http": {
+			"method": "POST",
+			"path": "/v07-sse-publish",
+			"accept": "application/json"
+		}
+	},
+	"steps": [
+		{
+			"id": "publish",
+			"use": "@blokjs/sse-publish",
+			"type": "module",
+			"inputs": {
+				"channel": "sse-demo",
+				"event": "js/ctx.request.body.event",
+				"data": "js/ctx.request.body.data"
+			}
+		}
+	]
+}

package/dist/scaffold-repo/triggers/http/workflows/json/v07-sse-stream.json

@@ -0,0 +1,26 @@
+{
+	"name": "v07-sse-stream",
+	"version": "1.0.0",
+	"description": "v0.7 PR 3 demo — SSE trigger. Subscribes the open stream to the in-process bus channel `sse-demo` and pumps events out as SSE frames via @blokjs/sse-stream. Pair with v07-sse-publish (HTTP POST) to push events from another workflow run into the same channel: every connected SSE client receives them in real time. Streams indefinitely until the client disconnects or the publisher stops emitting.",
+	"trigger": {
+		"sse": {
+			"path": "/sse/demo",
+			"heartbeatInterval": 15000,
+			"retryInterval": 3000
+		}
+	},
+	"steps": [
+		{
+			"id": "sub",
+			"use": "@blokjs/sse-subscribe",
+			"type": "module",
+			"inputs": { "channels": ["sse-demo"] }
+		},
+		{
+			"id": "stream",
+			"use": "@blokjs/sse-stream",
+			"type": "module",
+			"inputs": { "source": "js/ctx.state.sub", "eventName": "message" }
+		}
+	]
+}

package/dist/scaffold-repo/triggers/http/workflows/json/v07-ws-echo.json

@@ -0,0 +1,38 @@
+{
+	"name": "v07-ws-echo",
+	"version": "1.0.0",
+	"description": "v0.7 PR 2 demo — WebSocket trigger echo handler. Mounted on the same Hono server as HTTP routes via the shared-app multiplex pattern (PR 1 foundation + PR 2 trigger). On `connect` the workflow sends a greeting; on each `message` it replies with the same payload wrapped in `{event: 'echo', original: <payload>}`. Smoke validates the end-to-end flow: open WS to /ws/echo, send `{event: 'hello', data: {hi: 'there'}}`, expect a 'connected' greeting + an 'echo' response. The trigger handles the upgrade, parses the JSON envelope, and dispatches the workflow once per message via the same runner pipeline as HTTP triggers — middleware chain, ctx.connection API, full Studio tracing.",
+	"trigger": {
+		"websocket": {
+			"path": "/ws/echo",
+			"events": ["hello", "ping"]
+		}
+	},
+	"steps": [
+		{
+			"id": "route",
+			"branch": {
+				"when": "ctx.request.body.event === 'connect'",
+				"then": [
+					{
+						"id": "greet",
+						"use": "@blokjs/ws-reply",
+						"type": "module",
+						"inputs": { "event": "connected", "payload": { "ok": true } }
+					}
+				],
+				"else": [
+					{
+						"id": "echo",
+						"use": "@blokjs/ws-reply",
+						"type": "module",
+						"inputs": {
+							"event": "echo",
+							"payload": { "original": "js/ctx.request.body" }
+						}
+					}
+				]
+			}
+		}
+	]
+}

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

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

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

@@ -0,0 +1,22 @@
+{
+	"name": "webhook-github-pr",
+	"version": "1.0.0",
+	"description": "GitHub pull-request family handler (pull_request, pull_request_review, pull_request_review_comment) — dispatched from webhook-github via sub-workflow. The router groups the whole family under one handler via switch-case array `when`. Real deployments would update review state, post status checks, run lint/preview pipelines.",
+	"trigger": {
+		"http": {
+			"method": "POST",
+			"path": "/webhook-handlers/github-pr",
+			"accept": "application/json"
+		}
+	},
+	"steps": [
+		{
+			"id": "respond",
+			"use": "@blokjs/expr",
+			"type": "module",
+			"inputs": {
+				"expression": "({ handler: 'github-pr', eventType: ctx.request.body.eventType || null, action: ctx.request.body.action || null, prNumber: (ctx.request.body.pull_request && ctx.request.body.pull_request.number) || null, title: (ctx.request.body.pull_request && ctx.request.body.pull_request.title) || null })"
+			}
+		}
+	]
+}

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

@@ -0,0 +1,32 @@
+{
+	"name": "webhook-github-push",
+	"version": "1.0.0",
+	"description": "GitHub push event handler — dispatched from webhook-github via sub-workflow. Real deployments would kick a CI build, post to Slack, update a deployment dashboard; this demo logs + summarizes the push.",
+	"trigger": {
+		"http": {
+			"method": "POST",
+			"path": "/webhook-handlers/github-push",
+			"accept": "application/json"
+		}
+	},
+	"steps": [
+		{
+			"id": "log",
+			"use": "@blokjs/log",
+			"type": "module",
+			"inputs": {
+				"level": "info",
+				"message": "js/`github-push: ${ctx.request.body.repo || '?'} ${ctx.request.body.ref || '?'} (${Array.isArray(ctx.request.body.commits) ? ctx.request.body.commits.length : 0} commits)`"
+			},
+			"ephemeral": true
+		},
+		{
+			"id": "respond",
+			"use": "@blokjs/expr",
+			"type": "module",
+			"inputs": {
+				"expression": "({ handler: 'github-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 })"
+			}
+		}
+	]
+}

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

@@ -0,0 +1,87 @@
+{
+	"name": "webhook-github",
+	"version": "1.0.0",
+	"description": "GitHub webhook receiver. Trigger verifies X-Hub-Signature-256 (HMAC-SHA256 over rawBody) against GITHUB_WEBHOOK_SECRET. Routes by X-GitHub-Event header using a switch step — push events go to webhook-github-push, the pull-request family (pull_request, pull_request_review, pull_request_review_comment) to webhook-github-pr, the issue family (issues, issue_comment) to webhook-github-issues. Unknown events log + return 200 (GitHub retries non-2xx; don't want a retry storm). Needs `--triggers http,webhook --examples` at scaffold time and GITHUB_WEBHOOK_SECRET set in .env.local.",
+	"trigger": {
+		"webhook": {
+			"provider": "github",
+			"path": "/webhooks/github",
+			"secretEnv": "GITHUB_WEBHOOK_SECRET"
+		}
+	},
+	"steps": [
+		{
+			"id": "route-by-event",
+			"switch": {
+				"on": "js/(ctx.request.headers['x-github-event'] || 'unknown').toLowerCase()",
+				"cases": [
+					{
+						"when": "push",
+						"do": [
+							{
+								"id": "dispatch-push",
+								"subworkflow": "webhook-github-push",
+								"inputs": {
+									"repo": "js/(ctx.request.body.repository && ctx.request.body.repository.full_name) || null",
+									"ref": "js/ctx.request.body.ref || null",
+									"commits": "js/ctx.request.body.commits || []"
+								}
+							}
+						]
+					},
+					{
+						"when": [
+							"pull_request",
+							"pull_request_review",
+							"pull_request_review_comment"
+						],
+						"do": [
+							{
+								"id": "dispatch-pr",
+								"subworkflow": "webhook-github-pr",
+								"inputs": {
+									"action": "js/ctx.request.body.action || null",
+									"pull_request": "js/ctx.request.body.pull_request || null",
+									"eventType": "js/ctx.request.headers['x-github-event']"
+								}
+							}
+						]
+					},
+					{
+						"when": ["issues", "issue_comment"],
+						"do": [
+							{
+								"id": "dispatch-issues",
+								"subworkflow": "webhook-github-issues",
+								"inputs": {
+									"action": "js/ctx.request.body.action || null",
+									"issue": "js/ctx.request.body.issue || null",
+									"eventType": "js/ctx.request.headers['x-github-event']"
+								}
+							}
+						]
+					}
+				],
+				"default": [
+					{
+						"id": "log-unknown",
+						"use": "@blokjs/log",
+						"type": "module",
+						"inputs": {
+							"level": "warn",
+							"message": "js/`webhook-github: unknown event '${ctx.request.headers['x-github-event'] || ''}', returning 200`"
+						}
+					}
+				]
+			}
+		},
+		{
+			"id": "respond",
+			"use": "@blokjs/expr",
+			"type": "module",
+			"inputs": {
+				"expression": "((dispatchKey) => { const childResp = dispatchKey ? ctx.state[dispatchKey] : null; const childData = childResp && childResp.data ? childResp.data : childResp; return { received: true, eventType: ctx.request.headers['x-github-event'] || null, deliveryId: ctx.request.headers['x-github-delivery'] || null, dispatchedTo: dispatchKey || 'log-unknown', child: childData }; })(['dispatch-push', 'dispatch-pr', 'dispatch-issues'].find(k => ctx.state[k] !== undefined))"
+			}
+		}
+	]
+}

package/dist/scaffold-repo/triggers/http/workflows/json/webhook-linear-comment.json

@@ -0,0 +1,22 @@
+{
+	"name": "webhook-linear-comment",
+	"version": "1.0.0",
+	"description": "Linear Comment event handler — dispatched from webhook-linear via sub-workflow. Real handlers would forward to Slack threads, sync to a discussion board, trigger AI summarization; this demo summarizes the comment.",
+	"trigger": {
+		"http": {
+			"method": "POST",
+			"path": "/webhook-handlers/linear-comment",
+			"accept": "application/json"
+		}
+	},
+	"steps": [
+		{
+			"id": "respond",
+			"use": "@blokjs/expr",
+			"type": "module",
+			"inputs": {
+				"expression": "({ handler: 'linear-comment', action: ctx.request.body.action || null, commentId: (ctx.request.body.data && ctx.request.body.data.id) || null, body: (ctx.request.body.data && ctx.request.body.data.body) || null, issueId: (ctx.request.body.data && ctx.request.body.data.issue && ctx.request.body.data.issue.id) || null })"
+			}
+		}
+	]
+}

package/dist/scaffold-repo/triggers/http/workflows/json/webhook-linear-issue.json

@@ -0,0 +1,22 @@
+{
+	"name": "webhook-linear-issue",
+	"version": "1.0.0",
+	"description": "Linear Issue event handler — dispatched from webhook-linear via sub-workflow. Linear sends `action: 'create' | 'update' | 'remove'` describing the issue state transition. Real handlers would sync to Jira/Notion, trigger CI on label changes, post to Slack; this demo summarizes the issue change.",
+	"trigger": {
+		"http": {
+			"method": "POST",
+			"path": "/webhook-handlers/linear-issue",
+			"accept": "application/json"
+		}
+	},
+	"steps": [
+		{
+			"id": "respond",
+			"use": "@blokjs/expr",
+			"type": "module",
+			"inputs": {
+				"expression": "({ handler: 'linear-issue', action: ctx.request.body.action || null, issueId: (ctx.request.body.data && ctx.request.body.data.id) || null, title: (ctx.request.body.data && ctx.request.body.data.title) || null, state: (ctx.request.body.data && ctx.request.body.data.state && ctx.request.body.data.state.name) || null, url: ctx.request.body.url || null })"
+			}
+		}
+	]
+}