blokctl 1.2.0 → 1.4.0

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

@@ -0,0 +1,50 @@
+/**
+ * @blokjs/trigger-websocket
+ *
+ * WebSocket trigger for Blok workflows — real-time bidirectional
+ * communication on the same Hono server that hosts HTTP routes.
+ *
+ * v0.7+ usage (just add it to your workflow):
+ *
+ * ```json
+ * {
+ *   "name": "chat-handler",
+ *   "trigger": {
+ *     "websocket": {
+ *       "path": "/ws/chat/:roomId",
+ *       "events": ["message", "typing", "leave"],
+ *       "middleware": ["jwt-auth"]
+ *     }
+ *   },
+ *   "steps": [
+ *     {
+ *       "id": "broadcast",
+ *       "use": "@blokjs/ws-broadcast",
+ *       "inputs": {
+ *         "room": "$.req.params.roomId",
+ *         "event": "message",
+ *         "payload": { "from": "$.state.identity.userId", "text": "$.req.body.data.text" }
+ *       }
+ *     }
+ *   ]
+ * }
+ * ```
+ *
+ * Authors construct the trigger with the shared Hono app (typically
+ * from `HttpTrigger`) and optionally a reference to that HttpTrigger
+ * so WebSocketTrigger can hook `injectWebSocket(server)` into the
+ * post-`serve()` callback. See
+ * [additional-triggers-plan.mdx](../../../docs/c/devtools/additional-triggers-plan.mdx#websocket-trigger)
+ * for the full design.
+ */
+
+import WebSocketTrigger, { _getActiveWebSocketTrigger, _setActiveWebSocketTrigger } from "./WebSocketTrigger";
+
+// Re-export under both default AND named names. Consumer code that does
+// `import WebSocketTrigger from "@blokjs/trigger-websocket"` (HTTP
+// trigger's `src/index.ts`) gets the default; `import { WebSocketTrigger }`
+// gets the named alias.
+export default WebSocketTrigger;
+export { WebSocketTrigger, _getActiveWebSocketTrigger, _setActiveWebSocketTrigger };
+export type { ConnectionContext } from "@blokjs/shared";
+export type { WebSocketTriggerOpts } from "@blokjs/helper";

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

@@ -0,0 +1,93 @@
+# WebSocket workflow templates
+
+One workflow that demonstrates the WebSocket trigger's `connect` +
+`message` lifecycle. Scaffolded into new projects whenever
+`--triggers websocket` is selected.
+
+## Files
+
+| File | Trigger | Purpose |
+|---|---|---|
+| [`echo-demo.ts`](echo-demo.ts) | `websocket` — `GET /ws/echo` | On `connect`, replies with `{event:"connected"}`. On each subsequent message frame, replies with `{event:"echo", payload:{original:<msg>}}` via `@blokjs/ws-reply`. |
+
+## Test the echo
+
+```bash
+# Install a simple WS client
+npm install -g wscat
+
+# Open the connection (HTTP port 4000 when mounted; 4002 when standalone)
+wscat -c ws://localhost:4000/ws/echo
+# < {"event":"connected","payload":{"ok":true}}
+
+# Send a frame
+> {"event":"hello","data":{"hi":"there"}}
+# < {"event":"echo","payload":{"original":{"event":"hello","data":{"hi":"there"}}}}
+```
+
+The `events: ["hello", "ping"]` field in the trigger config is the
+event-name allowlist — only frames whose `event` matches dispatch the
+workflow. The lifecycle events `connect` and `disconnect` dispatch
+implicitly regardless of the allowlist.
+
+## How WebSocket routes mount on HTTP
+
+WebSocketTrigger is designed to share the HTTP server's Hono app (same
+as SSE — every framework worth mentioning does it this way; the WS
+upgrade is itself an HTTP request). When the scaffold has both `http`
+and `websocket` selected, `blokctl dev` runs ONE process. The HTTP
+entry constructs `WebSocketTrigger(httpTrigger.getApp(), httpTrigger)`
+which:
+
+1. **Routes**: registers WS routes via `addPreCatchAllHook` (same
+   pre-catch-all integration SSE uses), so `/ws/<path>` upgrade
+   requests hit the WS handler before Hono's legacy `/:workflow`
+   catch-all.
+2. **Upgrade listener**: hooks `injectWebSocket(server)` via
+   `addServerHook`, so the WS upgrade handler attaches to the
+   `http.Server` immediately after HttpTrigger calls `serve()`.
+
+The result is `/ws/echo` available on the HTTP port (4000), same as
+all other HTTP routes — clients only need one base URL.
+
+In `--triggers websocket` (without HTTP), the scaffolded `WSServer.ts`
+spins up its own Hono app on port 4002 and attaches `injectWebSocket`
+to its own `http.Server` manually. Same trigger code, different
+hosting surface.
+
+## Helper nodes available
+
+`@blokjs/helpers` exports three WS-aware helpers, all spread into the
+shared Nodes record when `--triggers websocket` is selected:
+
+| Node | Purpose |
+|---|---|
+| `@blokjs/ws-reply` | Send a frame to the connection that received the current message. Used by `echo-demo`. |
+| `@blokjs/ws-broadcast` | Fan out a frame to every connection on the trigger (optionally filtered by room/event). |
+| `@blokjs/ws-close` | Close the current connection. Optional `code` + `reason`. |
+
+Reach for these from any WebSocket-triggered step.
+
+## Cross-process broadcast (advanced)
+
+The default WS bus is in-process — `@blokjs/ws-broadcast` only fans
+out to connections on the SAME Node process. For multi-instance
+deployments where clients connect to different replicas, set
+`BLOK_WS_BACKPLANE=<provider>` (NATS / Redis / Kafka). The trigger
+auto-loads the backplane adapter and broadcasts cross-process. See
+[`@blokjs/trigger-websocket`'s Backplane](../../Backplane.ts) source
+for the env vars and provider matrix.
+
+## LLM training pattern
+
+This template is designed to read top-to-bottom as a canonical WS
+pattern. A coding-assistant LLM seeing this directory should learn:
+
+- `trigger.websocket` config shape (`path`, `events`, `mode`,
+  `heartbeatInterval`, `maxConnections`, `messageRateLimit`)
+- The `connect` → `message` dispatch model (each frame runs the
+  workflow once; `ctx.request.body.event` discriminates which path)
+- `branch({when, then, else})` for routing connect vs. data messages
+- `@blokjs/ws-reply` as the connection-scoped reply primitive
+- That WS lives on the same port as HTTP via Blok's `addPreCatchAllHook`
+  + `addServerHook` integration points

package/dist/scaffold-repo/triggers/websocket/src/workflows/events/echo-demo.ts

@@ -0,0 +1,56 @@
+import { branch, eq, node, step, workflow } from "@blokjs/core";
+import type { Handle } from "@blokjs/core";
+
+/**
+ * WebSocket echo demo — open `ws://localhost:4000/ws/echo` (or 4002 if
+ * standalone WS scaffold) and:
+ *
+ *   1. On `connect` the workflow sends a greeting frame
+ *      `{event: "connected", data: {ok: true}}`.
+ *   2. On each subsequent message, the workflow replies with
+ *      `{event: "echo", data: {original: <whatever-you-sent>}}`.
+ *
+ * The handler runs once per WebSocket frame — the trigger parses the
+ * client's JSON envelope, dispatches the workflow through the same
+ * runner pipeline as HTTP triggers (middleware chain, ctx.connection
+ * API, full Studio tracing), and routes the reply via
+ * `@blokjs/ws-reply` (helper that calls `ctx.connection.send(...)`).
+ *
+ * Test with any WebSocket client:
+ *   $ wscat -c ws://localhost:4000/ws/echo
+ *   < {"event":"connected","data":{"ok":true}}
+ *   > {"event":"hello","data":{"hi":"there"}}
+ *   < {"event":"echo","data":{"original":{"event":"hello","data":{"hi":"there"}}}}
+ *
+ * `events: ["hello", "ping"]` in the trigger config is the event-name
+ * allowlist — only frames whose `event` field matches dispatch the
+ * workflow (plus the implicit `connect` / `disconnect` lifecycle
+ * events). Omit the field to accept any event name.
+ */
+export default workflow(
+	"WebSocket Echo Demo",
+	{
+		version: "1.0.0",
+		description: "Echoes received WebSocket messages back to the sender. Demonstrates the connect + message lifecycle.",
+		trigger: {
+			websocket: {
+				path: "/ws/echo",
+				events: ["hello", "ping"],
+			},
+		},
+	},
+	(conn) => {
+		const msg = conn.body as Handle<{ event: string }>;
+		branch("route", eq(msg.event, "connect"), {
+			then: () => {
+				step("greet", node("@blokjs/ws-reply"), { event: "connected", payload: { ok: true } });
+			},
+			else: () => {
+				step("echo", node("@blokjs/ws-reply"), {
+					event: "echo",
+					payload: { original: conn.body },
+				});
+			},
+		});
+	},
+);

package/dist/scaffold-repo/triggers/websocket/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/websocket/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: 60,
+				functions: 63,
+				branches: 48,
+				statements: 58,
+			},
+		},
+		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/worker/CHANGELOG.md

@@ -0,0 +1,22 @@
+# @blokjs/trigger-worker
+
+## 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/worker/package.json

@@ -0,0 +1,68 @@
+{
+	"name": "@blokjs/trigger-worker",
+	"version": "1.4.0",
+	"files": ["dist"],
+	"description": "Worker-based trigger for Blok workflows - supports background job processing with concurrency, retries, and scheduling",
+	"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",
+		"uuid": "^11.1.0"
+	},
+	"devDependencies": {
+		"@types/amqplib": "^0.10.8",
+		"@types/node": "^22.15.21",
+		"@types/uuid": "^11.0.0",
+		"pg-boss": "^10.0.0",
+		"typescript": "^5.8.3",
+		"vitest": "^4.0.18"
+	},
+	"peerDependencies": {
+		"@aws-sdk/client-sqs": "^3.0.0",
+		"amqplib": "^0.10.0",
+		"bullmq": "^5.67.2",
+		"ioredis": "^5.9.2",
+		"kafkajs": "^2.2.0",
+		"nats": "",
+		"pg-boss": ""
+	},
+	"peerDependenciesMeta": {
+		"@aws-sdk/client-sqs": {
+			"optional": true
+		},
+		"amqplib": {
+			"optional": true
+		},
+		"bullmq": {
+			"optional": true
+		},
+		"ioredis": {
+			"optional": true
+		},
+		"kafkajs": {
+			"optional": true
+		},
+		"nats": {
+			"optional": true
+		},
+		"pg-boss": {
+			"optional": true
+		}
+	},
+	"private": false,
+	"publishConfig": {
+		"access": "public"
+	}
+}