blokctl 1.3.0 → 1.4.0

package/dist/scaffold-repo/triggers/sse/src/index.ts

@@ -0,0 +1,38 @@
+/**
+ * @blokjs/trigger-sse
+ *
+ * Server-Sent Events trigger for Blok workflows. Mounts on the shared
+ * Hono server alongside HTTP and WebSocket routes — same port, same
+ * middleware chain, same Studio tracing.
+ *
+ * v0.7+ usage (just add the trigger to your workflow):
+ *
+ * ```json
+ * {
+ *   "name": "live-clock",
+ *   "trigger": {
+ *     "sse": {
+ *       "path": "/sse/clock",
+ *       "heartbeatInterval": 15000,
+ *       "retryInterval": 3000
+ *     }
+ *   },
+ *   "steps": [
+ *     { "id": "sub",    "use": "@blokjs/sse-subscribe", "inputs": { "channels": ["clock-ticks"] } },
+ *     { "id": "stream", "use": "@blokjs/sse-stream",    "inputs": { "source": "$.state.sub", "eventName": "tick" } }
+ *   ]
+ * }
+ * ```
+ *
+ * See [additional-triggers-plan.mdx](../../../docs/c/devtools/additional-triggers-plan.mdx#sse-trigger)
+ * for the full design.
+ */
+
+import SSETrigger, { _getActiveSSETrigger, _setActiveSSETrigger } from "./SSETrigger";
+
+export default SSETrigger;
+export { SSETrigger, _getActiveSSETrigger, _setActiveSSETrigger };
+export { getBus as _getSSEBus, _resetBusForTests } from "./bus";
+export type { BusEvent } from "./bus";
+export type { StreamContext } from "@blokjs/shared";
+export type { SSETriggerOpts } from "@blokjs/helper";

package/dist/scaffold-repo/triggers/sse/src/workflows/events/README.md

@@ -0,0 +1,129 @@
+# SSE workflow templates
+
+Two workflows that demonstrate the SSE trigger's pub/sub pattern.
+Both are scaffolded into new projects whenever `--triggers sse` is
+selected.
+
+## Files
+
+| File | Trigger | Purpose |
+|---|---|---|
+| [`stream-demo.ts`](stream-demo.ts) | `sse` — `GET /sse/demo` | Subscribes the open stream to the in-process bus channel `sse-demo` and pumps events out as SSE frames. |
+| [`publish-demo.ts`](publish-demo.ts) | `http` — `POST /v07-sse-publish` | Publishes one event to the `sse-demo` channel via `@blokjs/sse-publish`. Only registered when the project also has an HTTP trigger. |
+
+## Test the pair end-to-end
+
+When the scaffold includes BOTH `http` and `sse`, `blokctl dev` runs a
+single Node process — the HTTP entry mounts SSE on the shared Hono app
+via `SSETrigger(httpTrigger.getApp(), httpTrigger)`. Same process →
+same in-process bus → events flow from publisher to subscribers in real
+time.
+
+```bash
+# Terminal 1 — open an SSE stream
+curl -N http://localhost:4000/sse/demo
+# data:
+# retry: 3000
+#
+# (waiting…)
+
+# Terminal 2 — publish three events
+curl -X POST http://localhost:4000/v07-sse-publish \
+    -H 'Content-Type: application/json' \
+    -d '{"event":"counter","data":{"n":1}}'
+curl -X POST http://localhost:4000/v07-sse-publish \
+    -H 'Content-Type: application/json' \
+    -d '{"event":"counter","data":{"n":2}}'
+curl -X POST http://localhost:4000/v07-sse-publish \
+    -H 'Content-Type: application/json' \
+    -d '{"event":"counter","data":{"n":3}}'
+
+# Terminal 1 receives:
+# event: counter
+# data: {"n":1}
+# id: 1
+#
+# event: counter
+# data: {"n":2}
+# id: 2
+#
+# event: counter
+# data: {"n":3}
+# id: 3
+```
+
+## Test the stream alone (SSE-only scaffold)
+
+In `--triggers sse` (without HTTP), the SSE process listens on its own
+port (4001 by default). The publisher workflow isn't registered (no
+HTTP trigger). You can still verify connectivity:
+
+```bash
+curl -N http://localhost:4001/sse/demo
+```
+
+To push events from an SSE-only project, write your own publisher —
+any trigger kind works (cron, worker, manual), or call the bus
+singleton directly via `import { _getSSEBus } from "@blokjs/trigger-sse"`.
+
+## How SSE routes mount on HTTP
+
+SSE is fundamentally HTTP: a `Content-Type: text/event-stream` response
+that stays open. Every framework worth mentioning mounts SSE on the
+HTTP server — Express, Fastify, FastAPI, Rails, Spring Boot, Phoenix,
+ASP.NET. Blok follows the same pattern.
+
+`SSETrigger`'s constructor takes the existing Hono app + HttpTrigger
+handle:
+
+```ts
+constructor(app: Hono, httpTrigger?: HttpTriggerLike)
+```
+
+In multi-trigger scaffolds, the HTTP entry constructs SSE this way and
+SSE registers routes via `httpTrigger.addPreCatchAllHook(...)`. Routes
+land BEFORE Hono's legacy workflow catch-all (`/:workflow{.+}`), so
+`/sse/<path>` upgrade requests reach the SSE handler instead of being
+dispatched as a workflow name.
+
+In SSE-only scaffolds, the generated `SSEServer.ts` builds its own
+Hono app + calls `serve()` directly. Same trigger code, different
+hosting surface.
+
+## Cross-process bus backplane (advanced)
+
+The default SSE bus is in-process — `@blokjs/sse-publish` only fans
+out to subscribers on the SAME Node process. That's fine for the
+default scaffold layout (HTTP+SSE share one process). For
+horizontally-scaled deployments where clients connect to different
+replicas, swap in a Redis Streams or NATS JetStream backplane.
+Tracked as a v0.7 follow-up in [BACKLOG.md](../../../../../BACKLOG.md).
+
+## Helper nodes available
+
+`@blokjs/helpers` exports three SSE-aware helpers, all spread into the
+shared Nodes record when `--triggers sse` is selected:
+
+| Node | Purpose |
+|---|---|
+| `@blokjs/sse-subscribe` | Subscribe the current SSE stream to channels on the bus. Returns an iterator handle. |
+| `@blokjs/sse-stream` | Pump events from a subscribed iterator out to the client as SSE frames. |
+| `@blokjs/sse-publish` | Publish one event to a bus channel — works from ANY workflow kind (HTTP, Worker, Cron, WS). |
+
+## LLM training pattern
+
+This template reads top-to-bottom as a canonical SSE pattern. A coding-
+assistant LLM seeing this directory should learn:
+
+- The `trigger.sse` config shape (`path`, `heartbeatInterval`,
+  `retryInterval`, `maxConnections`, `channels`)
+- The `@blokjs/sse-subscribe` → `@blokjs/sse-stream` step pair as the
+  stream-side primitive
+- `@blokjs/sse-publish` as the publisher-side primitive (usable from
+  any trigger kind)
+- `$.state.<id>` (unquoted, TS proxy) for piping `sse-subscribe`'s
+  output into `sse-stream`. Quoted strings like `"$.state.sub"`
+  don't work — the Mapper only recognizes `js/ctx....` strings or
+  the `$` proxy.
+- Why the publisher is decoupled from the subscriber (one HTTP POST
+  can fan out to N connected SSE clients via the bus)

package/dist/scaffold-repo/triggers/sse/src/workflows/events/publish-demo.ts

@@ -0,0 +1,40 @@
+import { http, node, step, workflow } from "@blokjs/core";
+import type { Handle } from "@blokjs/core";
+
+/**
+ * SSE publish demo — companion to `stream-demo`. Accepts an HTTP POST
+ * with `{ event, data }` and publishes the event to the in-process bus
+ * channel `sse-demo`. Every SSE client connected to `/sse/demo` receives
+ * the event via its open stream.
+ *
+ * Only registers when the project has an HTTP trigger (the CLI omits
+ * this file from SSE-only scaffolds). To publish from an SSE-only
+ * project, swap the HTTP trigger here for a `worker` or `cron` trigger
+ * — the `@blokjs/sse-publish` helper node works from any workflow kind.
+ *
+ * Demonstrates the in-process pub/sub model: publishers (HTTP, Cron,
+ * Worker, WebSocket) and subscribers (SSE) decouple through the bus.
+ *
+ * Verify end-to-end:
+ *   1. Open the stream:  curl -N http://localhost:4001/sse/demo
+ *   2. Publish events:   curl -X POST http://localhost:4000/v07-sse-publish \
+ *                            -H 'Content-Type: application/json' \
+ *                            -d '{"event":"tick","data":{"count":1}}'
+ *   3. The first terminal prints `event: tick\ndata: {"count":1}` instantly.
+ */
+export default workflow(
+	"SSE Publish Demo",
+	{
+		version: "1.0.0",
+		description: "Publish one event to the SSE bus channel `sse-demo`. Every connected `/sse/demo` client receives it.",
+		trigger: http.post("/v07-sse-publish", { accept: "application/json" }),
+	},
+	(req) => {
+		const body = req.body as Handle<{ event: string; data: unknown }>;
+		step("publish", node("@blokjs/sse-publish"), {
+			channel: "sse-demo",
+			event: body.event,
+			data: body.data,
+		});
+	},
+);

package/dist/scaffold-repo/triggers/sse/src/workflows/events/stream-demo.ts

@@ -0,0 +1,43 @@
+import { node, step, workflow } from "@blokjs/core";
+
+/**
+ * SSE stream demo — open `GET /sse/demo` from any EventSource-style
+ * client and the workflow subscribes the stream to the in-process
+ * bus channel `sse-demo`, pumping events out as SSE frames.
+ *
+ * Pair with the companion `publish-demo` HTTP workflow: `POST /v07-sse-publish`
+ * with `{ "event": "<name>", "data": <payload> }` pushes an event into
+ * the same channel and every connected SSE client receives it in real time.
+ *
+ * The stream runs until the client disconnects.
+ *
+ * Verify end-to-end:
+ *   1. In one terminal:  curl -N http://localhost:4001/sse/demo
+ *   2. In another:       curl -X POST http://localhost:4000/v07-sse-publish \
+ *                            -H 'Content-Type: application/json' \
+ *                            -d '{"event":"hello","data":{"msg":"world"}}'
+ *   3. Watch the first terminal — `event: hello` arrives instantly.
+ *
+ * v0.6 reliability knobs available on `trigger.sse`:
+ *   heartbeatInterval — ms between `:heartbeat\n\n` keepalive frames (default 15000)
+ *   retryInterval     — ms emitted as the SSE `retry:` field (default 3000)
+ *   maxConnections    — hard cap on concurrent streams per process (default 10000)
+ */
+export default workflow(
+	"SSE Stream Demo",
+	{
+		version: "1.0.0",
+		description: "Subscribe an SSE stream to the in-process bus channel `sse-demo` and pump events as SSE frames.",
+		trigger: {
+			sse: {
+				path: "/sse/demo",
+				heartbeatInterval: 15000,
+				retryInterval: 3000,
+			},
+		},
+	},
+	() => {
+		const sub = step("sub", node("@blokjs/sse-subscribe"), { channels: ["sse-demo"] });
+		step("stream", node("@blokjs/sse-stream"), { source: sub, eventName: "message" });
+	},
+);

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

@@ -0,0 +1,22 @@
+{
+	"ts-node": {
+		"transpileOnly": true
+	},
+	"compilerOptions": {
+		"target": "ES2022",
+		"module": "es2022",
+		"moduleResolution": "bundler",
+		"declaration": true,
+		"declarationMap": true,
+		"sourceMap": true,
+		"outDir": "./dist",
+		"rootDir": "./src",
+		"strict": true,
+		"esModuleInterop": true,
+		"skipLibCheck": true,
+		"forceConsistentCasingInFileNames": true,
+		"resolveJsonModule": true
+	},
+	"include": ["src/**/*"],
+	"exclude": ["node_modules", "dist", "**/*.test.ts"]
+}

package/dist/scaffold-repo/triggers/sse/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: 82,
+				functions: 69,
+				branches: 66,
+				statements: 80,
+			},
+		},
+		include: ["__tests__/**/*.test.ts", "src/**/*.test.ts"],
+		exclude: ["node_modules", "dist"],
+		testTimeout: 10000,
+		hookTimeout: 10000,
+	},
+	resolve: {
+		alias: {
+			"@": path.resolve(__dirname, "./src"),
+		},
+	},
+});

package/dist/scaffold-repo/triggers/webhook/CHANGELOG.md

@@ -0,0 +1,22 @@
+# @blokjs/trigger-webhook
+
+## 0.2.0
+
+### Minor Changes
+
+- Initial public release of Blok packages.
+
+  This release includes:
+
+  - Core packages: @blokjs/shared, @blokjs/helper, @blokjs/runner
+  - Node packages: @blokjs/api-call, @blokjs/if-else, @blokjs/react
+  - Trigger packages: pubsub, queue, webhook, websocket, worker, cron, grpc
+  - CLI tool: blokctl
+  - Editor support: @blokjs/lsp-server, @blokjs/syntax
+
+### Patch Changes
+
+- Updated dependencies
+  - @blokjs/shared@0.2.0
+  - @blokjs/helper@0.2.0
+  - @blokjs/runner@0.2.0

package/dist/scaffold-repo/triggers/webhook/package.json

@@ -0,0 +1,36 @@
+{
+	"name": "@blokjs/trigger-webhook",
+	"version": "1.4.0",
+	"files": ["dist"],
+	"description": "Webhook trigger for Blok workflows - supports GitHub, Stripe, Shopify, and custom webhooks",
+	"type": "module",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"scripts": {
+		"build": "rm -rf dist && bun run tsc",
+		"build:dev": "tsc --watch",
+		"test": "vitest run",
+		"test:dev": "vitest"
+	},
+	"author": "Deskree Technologies Inc.",
+	"license": "Apache-2.0",
+	"dependencies": {
+		"@blokjs/helper": "^1.4.0",
+		"@blokjs/runner": "^1.4.0",
+		"@blokjs/shared": "^1.4.0",
+		"@opentelemetry/api": "^1.9.0",
+		"hono": "^4.11.7",
+		"uuid": "^11.1.0"
+	},
+	"devDependencies": {
+		"@hono/node-server": "^1.19.9",
+		"@types/node": "^22.15.21",
+		"@types/uuid": "^11.0.0",
+		"typescript": "^5.8.3",
+		"vitest": "^4.0.18"
+	},
+	"private": false,
+	"publishConfig": {
+		"access": "public"
+	}
+}