npm - blokctl - Versions diffs - 1.3.0 → 1.4.1 - Mend

blokctl 1.3.0 → 1.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (689) hide show

package/dist/scaffold-repo/triggers/http/request.http ADDED Viewed

@@ -0,0 +1,7 @@
+GET http://localhost:4000/countries HTTP/1.1
+###
+GET http://localhost:4000/empty HTTP/1.1
+###

package/dist/scaffold-repo/triggers/http/src/AppRoutes.ts ADDED Viewed

@@ -0,0 +1,64 @@
+/**
+ * Hono sub-app used to define application routes.
+ *
+ * @remarks
+ * This app is currently minimal. You can create routes by using methods like `app.get`, `app.post`, etc.
+ * Example:
+ * ```typescript
+ * app.get('/example', (c) => {
+ *   return c.text('Example route');
+ * });
+ * ```
+ *
+ * @module AppRoutes
+ */
+import { Hono } from "hono";
+const app = new Hono();
+app.get("/", (c) => {
+	const html = `
+	<!DOCTYPE html>
+	<html lang="en">
+	<head>
+		<meta charset="UTF-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		<title>Welcome to blok</title>
+		<link href="https://cdn.jsdelivr.net/npm/tailwindcss@2.2.19/dist/tailwind.min.css" rel="stylesheet">
+		<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600&display=swap" rel="stylesheet">
+		<style>
+			body { font-family: 'Inter', sans-serif; }
+		</style>
+	</head>
+	<body class="bg-gray-50 text-gray-800 min-h-screen flex flex-col">
+		<main class="grow flex items-center justify-center px-4">
+			<div class="max-w-3xl bg-white shadow-xl rounded-2xl p-10 border border-gray-200">
+				<h1 class="text-3xl font-semibold mb-6 text-center text-blue-700">🚀 Welcome to <span class="text-black">blok</span></h1>
+				<p class="text-lg mb-4">You're ready to start building fast and modular applications. Here's how to get started:</p>
+				<ol class="list-decimal list-inside mb-6 space-y-2 text-base text-gray-700">
+					<li><strong>Create</strong> a new <strong>node</strong> using <code class="bg-gray-100 px-2 py-1 rounded">npx blokctl@latest create node</code>.</li>
+					<li><strong>Create</strong> a new <strong>workflow</strong> using <code class="bg-gray-100 px-2 py-1 rounded">npx blokctl@latest create workflow</code>.</li>
+					<li><strong>Extend</strong> the routing system in <code class="bg-gray-100 px-2 py-1 rounded">src/AppRoutes.ts</code> to expose new logic.</li>
+					<li><strong>Initialize</strong> the metrics stack with Prometheus using <code class="bg-gray-100 px-2 py-1 rounded">docker compose -f infra/metrics/docker-compose.yml up</code>.</li>
+					<li><strong>Start</strong> the Docker development environment by running <code class="bg-gray-100 px-2 py-1 rounded">npm run infra:dev</code>.</li>
+					<li><strong>Start</strong> the TypeScript watcher to regenerate the dist folder by running <code class="bg-gray-100 px-2 py-1 rounded">npm run infra:build</code>.</li>
+					<li><strong>Monitor</strong> built-in performance metrics with <code class="bg-gray-100 px-2 py-1 rounded">npx blokctl@latest monitor</code>.</li>
+				</ol>
+				<div class="mt-8 text-center">
+					<a href="https://blok.build/" target="_blank" class="inline-block bg-blue-600 text-white px-6 py-2 rounded hover:bg-blue-700 transition">Explore Docs</a>
+				</div>
+			</div>
+		</main>
+		<footer class="text-center text-sm text-gray-500 py-4">
+			<p>Made with ❤️ by the <a href="https://deskree.com/" target="_blank" class="text-blue-600 hover:underline">Deskree</a> team.</p>
+		</footer>
+	</body>
+	</html>
+	`;
+	return c.html(html, 200);
+});
+export default app;

package/dist/scaffold-repo/triggers/http/src/Nodes.ts ADDED Viewed

@@ -0,0 +1,38 @@
+import { fileURLToPath } from "node:url";
+import ApiCall from "@blokjs/api-call";
+import { HELPER_NODES } from "@blokjs/helpers";
+import IfElse from "@blokjs/if-else";
+import { discoverNodes } from "@blokjs/runner";
+import type { BlokService } from "@blokjs/runner";
+import type { NodeBase } from "@blokjs/shared";
+// THIRD-PARTY nodes are npm packages — not locally scannable, so they stay
+// explicitly imported + registered here. Each is keyed by its own `node.name`
+// (the canonical `use:` ref per ADR 0002); the map keys are cosmetic and the
+// `NodeMap.addNode` collision guard catches two nodes claiming one ref.
+const thirdParty: Record<string, BlokService<unknown>> = {
+	"@blokjs/api-call": ApiCall,
+	"@blokjs/if-else": IfElse,
+	// v0.5 generic helpers: expr, ctx-publish, throw, log, audit-log,
+	// in-memory-kv, json-schema, etc. Registered globally so any workflow
+	// can use them via `use: "@blokjs/<name>"`.
+	...(HELPER_NODES as unknown as Record<string, BlokService<unknown>>),
+};
+// LOCAL nodes live under `src/nodes/<name>/index.*` — discovered at module-eval
+// (import = registration, #360/#349, ADR 0002) instead of hand-listed. The
+// `eval/` and `examples/` bundles are map-export barrels, which `discoverNodes`
+// flattens. Resolve the dir relative to THIS file so it's correct regardless of
+// `process.cwd()` (tests, blokctl, deployed app all differ).
+const localNodesDir = fileURLToPath(new URL("./nodes", import.meta.url));
+const local = await discoverNodes(localNodesDir);
+// One flat map keyed by `node.name` — the same shape `HttpTrigger.loadNodes()`
+// + the HMR path consume via `Object.values(nodes)`, and the corpus the
+// node-resolution-regression test loads.
+const nodes: Record<string, BlokService<unknown>> = { ...thirdParty };
+for (const node of local) {
+	nodes[(node as NodeBase).name] = node as unknown as BlokService<unknown>;
+}
+export default nodes;

package/dist/scaffold-repo/triggers/http/src/Workflows.ts ADDED Viewed

@@ -0,0 +1,18 @@
+import type Workflows from "./runner/types/Workflows";
+import countriesFactsHelper from "./workflows/countries-cats-helper";
+import countriesHelper from "./workflows/countries-helper";
+import empty from "./workflows/empty";
+import evalRetrieve from "./workflows/eval/eval-retrieve";
+import evalRun from "./workflows/eval/eval-run";
+import foreignAuth from "./workflows/eval/foreign-auth";
+const workflows: Workflows = {
+	"countries-helper": countriesHelper,
+	"countries-cats-helper": countriesFactsHelper,
+	"empty-helper": empty,
+	"eval-run": evalRun,
+	"eval-retrieve": evalRetrieve,
+	"foreign-auth": foreignAuth,
+};
+export default workflows;

package/dist/scaffold-repo/triggers/http/src/index.ts ADDED Viewed

@@ -0,0 +1,86 @@
+import { DefaultLogger } from "@blokjs/runner";
+import McpTrigger from "@blokjs/trigger-mcp";
+import SSETrigger from "@blokjs/trigger-sse";
+import WebhookTrigger from "@blokjs/trigger-webhook";
+import WebSocketTrigger from "@blokjs/trigger-websocket";
+import { type Span, metrics, trace } from "@opentelemetry/api";
+import { Hono } from "hono";
+import HttpTrigger, { type AppBindings } from "./runner/HttpTrigger";
+export default class App {
+	private httpTrigger: HttpTrigger = <HttpTrigger>{};
+	private wsTrigger: WebSocketTrigger | null = null;
+	private sseTrigger: SSETrigger | null = null;
+	private webhookTrigger: WebhookTrigger | null = null;
+	private mcpTrigger: McpTrigger | null = null;
+	protected trigger_initializer = 0;
+	protected initializer = 0;
+	protected tracer = trace.getTracer(
+		process.env.PROJECT_NAME || "trigger-http-server",
+		process.env.PROJECT_VERSION || "0.0.1",
+	);
+	private logger = new DefaultLogger();
+	protected app_cold_start = metrics.getMeter("default").createGauge("initialization", {
+		description: "Application cold start",
+	});
+	constructor() {
+		this.initializer = performance.now();
+		// v0.7 — share ONE Hono app across HttpTrigger and WebSocketTrigger
+		// so HTTP routes + WS upgrade routes multiplex on port 4000. The
+		// orchestrator pattern documented in
+		// docs/c/devtools/additional-triggers-plan.mdx.
+		const app = new Hono<AppBindings>();
+		this.httpTrigger = new HttpTrigger(app);
+		this.wsTrigger = new WebSocketTrigger(app, this.httpTrigger);
+		this.sseTrigger = new SSETrigger(app, this.httpTrigger);
+		this.webhookTrigger = new WebhookTrigger(app, this.httpTrigger);
+		this.mcpTrigger = new McpTrigger(app, this.httpTrigger);
+		// Share the HTTP trigger's node + workflow registry with the
+		// sibling triggers so per-event / per-stream / per-webhook / per-MCP
+		// workflow runs resolve `branch`, helper nodes, and built-in
+		// helpers through the same NodeMap that HTTP requests use.
+		const nodeMap = this.httpTrigger.getNodeMap();
+		this.wsTrigger.setNodeMap(nodeMap);
+		this.sseTrigger.setNodeMap(nodeMap);
+		this.webhookTrigger.setNodeMap(nodeMap);
+		this.mcpTrigger.setNodeMap(nodeMap);
+	}
+	async run() {
+		await this.tracer.startActiveSpan("initialization", async (span: Span) => {
+			// Wire sibling same-port triggers FIRST — they register pre-
+			// catch-all and server hooks on HttpTrigger that fire during /
+			// after HttpTrigger.listen(). Order:
+			//   1. WS + SSE register their hooks here (no routes mounted yet).
+			//   2. HttpTrigger.listen() scans + registers workflows in
+			//      WorkflowRegistry, fires preCatchAllHooks (WS + SSE
+			//      register their routes), mounts the legacy catch-all,
+			//      then calls serve(). The serve() ready callback fires
+			//      WS's serverHook → injectWebSocket attaches.
+			await this.wsTrigger?.listen();
+			await this.sseTrigger?.listen();
+			await this.webhookTrigger?.listen();
+			await this.mcpTrigger?.listen();
+			await this.httpTrigger.listen();
+			this.initializer = performance.now() - this.initializer;
+			this.logger.log(`Server initialized in ${this.initializer.toFixed(2)}ms`);
+			this.app_cold_start.record(this.initializer, {
+				pid: process.pid,
+				env: process.env.NODE_ENV,
+				app: process.env.APP_NAME,
+			});
+			span.end();
+		});
+	}
+	// Expose the Hono app for hosting with serverless functions like AWS Lambda, GC Functions, etc.
+	getHttpApp() {
+		return this.httpTrigger.getApp();
+	}
+}
+if (process.env.DISABLE_TRIGGER_RUN !== "true") {
+	new App().run();
+}

package/dist/scaffold-repo/triggers/http/src/nodes/chain-init/index.ts ADDED Viewed

@@ -0,0 +1,48 @@
+import { defineNode } from "@blokjs/runner";
+import type { Context } from "@blokjs/shared";
+import { z } from "zod";
+/**
+ * ChainInit node — starts a cross-runtime chain test.
+ *
+ * Initializes the chain data structure with the first entry (nodejs)
+ * so downstream nodes in other languages can append to it.
+ */
+export default defineNode({
+	name: "chain-init",
+	description: "Initializes a cross-runtime chain test with the first entry (nodejs)",
+	input: z.object({}),
+	output: z.object({
+		chain: z.array(
+			z.object({
+				language: z.string(),
+				order: z.number(),
+				timestamp: z.string(),
+			}),
+		),
+		origin: z.string(),
+	}),
+	async execute(ctx: Context, _input) {
+		const entry = {
+			language: "nodejs",
+			order: 1,
+			timestamp: new Date().toISOString(),
+		};
+		const data = {
+			chain: [entry],
+			origin: "blok-cross-runtime-test",
+		};
+		// Store in ctx.vars so downstream nodes can access via ctx.vars['init']
+		if (!ctx.vars) {
+			(ctx as Record<string, unknown>).vars = {};
+		}
+		(ctx.vars as Record<string, unknown>).init = data;
+		return data;
+	},
+});

package/dist/scaffold-repo/triggers/http/src/nodes/chain-verify/index.ts ADDED Viewed

@@ -0,0 +1,123 @@
+import { defineNode } from "@blokjs/runner";
+import type { Context } from "@blokjs/shared";
+import { z } from "zod";
+type ChainEntry = { language: string; order: number; timestamp?: string };
+/**
+ * ChainVerify node — final step of the cross-runtime chain test.
+ *
+ * Reads ctx.vars directly (populated by RuntimeAdapterNode for each SDK step
+ * and by chain-init for the init step) to produce a verification report
+ * confirming all runtimes executed correctly.
+ */
+export default defineNode({
+	name: "chain-verify",
+	description: "Verifies that all runtimes executed correctly in a cross-runtime chain test",
+	input: z.object({}),
+	output: z.object({
+		status: z.enum(["PASS", "FAIL"]),
+		summary: z.object({
+			totalRuntimes: z.number(),
+			chainLength: z.number(),
+			allRuntimesInChain: z.boolean(),
+			allRuntimesInVars: z.boolean(),
+			origin: z.string(),
+		}),
+		chain: z.array(
+			z.object({
+				language: z.string(),
+				order: z.number(),
+				timestamp: z.string().optional(),
+			}),
+		),
+		verification: z.record(
+			z.object({
+				inChain: z.boolean(),
+				inVars: z.boolean(),
+				chainOrder: z.number().nullable(),
+				stepName: z.string(),
+			}),
+		),
+		vars: z.record(z.unknown()),
+	}),
+	async execute(ctx: Context, _input) {
+		const vars = (ctx.vars ?? {}) as Record<string, unknown>;
+		// Step name → runtime language mapping
+		const stepToRuntime: Record<string, string> = {
+			init: "nodejs",
+			go: "go",
+			rust: "rust",
+			java: "java",
+			csharp: "csharp",
+			php: "php",
+			ruby: "ruby",
+			python: "python3",
+		};
+		const expectedRuntimes = Object.values(stepToRuntime);
+		// Find the longest chain from any step's vars (the last step should have all entries)
+		let finalChain: ChainEntry[] = [];
+		let origin = "unknown";
+		for (const stepName of Object.keys(stepToRuntime)) {
+			const stepVars = vars[stepName] as Record<string, unknown> | undefined;
+			if (!stepVars) continue;
+			const stepChain = (stepVars.chain ?? []) as ChainEntry[];
+			if (stepChain.length > finalChain.length) {
+				finalChain = stepChain;
+			}
+			if (stepVars.origin && typeof stepVars.origin === "string") {
+				origin = stepVars.origin;
+			}
+		}
+		// Verify each runtime appears in the chain and in vars
+		const chainLanguages = finalChain.map((entry) => entry.language);
+		const verification: Record<
+			string,
+			{
+				inChain: boolean;
+				inVars: boolean;
+				chainOrder: number | null;
+				stepName: string;
+			}
+		> = {};
+		for (const [stepName, runtime] of Object.entries(stepToRuntime)) {
+			const chainIndex = chainLanguages.indexOf(runtime);
+			const stepVars = vars[stepName] as Record<string, unknown> | undefined;
+			verification[runtime] = {
+				inChain: chainIndex >= 0,
+				inVars: stepVars !== undefined,
+				chainOrder: chainIndex >= 0 ? chainIndex + 1 : null,
+				stepName,
+			};
+		}
+		const allInChain = Object.values(verification).every((v) => v.inChain);
+		const allInVars = Object.values(verification).every((v) => v.inVars);
+		return {
+			status: (allInChain && allInVars ? "PASS" : "FAIL") as "PASS" | "FAIL",
+			summary: {
+				totalRuntimes: expectedRuntimes.length,
+				chainLength: finalChain.length,
+				allRuntimesInChain: allInChain,
+				allRuntimesInVars: allInVars,
+				origin,
+			},
+			chain: finalChain,
+			verification,
+			vars,
+		};
+	},
+});

package/dist/scaffold-repo/triggers/http/src/nodes/eval/index.ts ADDED Viewed

@@ -0,0 +1,69 @@
+/**
+ * Eval-harness nodes — a faithful, minimal version of the tetrix-blok eval
+ * pipeline (load → retrieve → normalize → score → aggregate). In-process
+ * `defineNode`s so the harness runs on the HTTP trigger alone, but the shape
+ * is identical to a `runtime.python3` retrieval setup.
+ *
+ * These nodes also serve as the canonical "correct context usage" example for
+ * the docs: every node RETURNS its output and lets the runner persist it to
+ * `ctx.state[<step-id>]`. None of them writes `ctx.state` directly.
+ */
+import { defineNode } from "@blokjs/runner";
+import { z } from "zod";
+/** Returns the list of items to evaluate. Output lands at `ctx.state.<id>`. */
+export const EvalLoadItems = defineNode({
+	name: "eval-load-items",
+	description: "Eval harness — produce the list of items to evaluate",
+	input: z.object({}),
+	output: z.object({
+		items: z.array(z.object({ id: z.number(), query: z.string() })),
+	}),
+	async execute() {
+		return {
+			items: [
+				{ id: 1, query: "how does context flow between steps" },
+				{ id: 2, query: "what does ephemeral mean" },
+				{ id: 3, query: "how do I share a value across arms" },
+			],
+		};
+	},
+});
+/** Retrieval — given a query, return ranked hits. Pure, deterministic. */
+export const EvalSearch = defineNode({
+	name: "eval-search",
+	description: "Eval harness — retrieve ranked hits for a query",
+	input: z.object({ query: z.string() }),
+	output: z.object({
+		query: z.string(),
+		hits: z.array(z.object({ doc: z.string(), rank: z.number() })),
+	}),
+	async execute(_ctx, input) {
+		const hits = [0, 1, 2].map((i) => ({ doc: `${input.query} :: doc-${i}`, rank: i }));
+		return { query: input.query, hits };
+	},
+});
+/** Score a retrieved+normalized item. */
+export const EvalScore = defineNode({
+	name: "eval-score",
+	description: "Eval harness — score normalized hits",
+	input: z.object({
+		id: z.number(),
+		hitCount: z.number(),
+	}),
+	output: z.object({ id: z.number(), score: z.number() }),
+	async execute(_ctx, input) {
+		return { id: input.id, score: input.hitCount * 10 };
+	},
+});
+const EvalNodes = {
+	"eval-load-items": EvalLoadItems,
+	"eval-search": EvalSearch,
+	"eval-score": EvalScore,
+};
+export default EvalNodes;

package/dist/scaffold-repo/triggers/http/src/nodes/examples/README.md ADDED Viewed

@@ -0,0 +1,14 @@
+# Example nodes
+Nodes backing the `--examples` scaffold workflows. Registered explicitly via
+`index.ts` (a map-export barrel flattened by `discoverNodes`).
+| Node | Used by |
+|------|---------|
+| `chat-ui` | The `/chat`, `/chat-memory`, and `/agent` example pages |
+Keep this bundle in lock-step with the shipped example workflows — a node no
+workflow references is dead weight registered into every scaffold. Earlier
+demo bundles (db-manager, dashboard-generator, workflow-docs, mastra-agent,
+image/PDF utilities) were removed in the 2026-07 purge; resurrect from git
+history only together with a registered workflow that uses them.