blokctl 1.2.0 → 1.4.0

package/dist/scaffold-repo/triggers/http/src/runner/nodeCatalog.ts

@@ -0,0 +1,128 @@
+/**
+ * Node catalog (SPEC-B P1.3) — aggregates every node across all runtimes into a
+ * uniform list for `GET /__blok/nodes` + `blokctl nodes list`.
+ *
+ * Two sources:
+ *  - **Module (in-process) nodes** — read from the trigger's node map; their
+ *    JSON Schema comes from `defineNode`'s `getReflectionSchemas()` (real) or a
+ *    class node's `getSchemas()`.
+ *  - **Runtime nodes** — each connected runtime adapter's `listNodes()` (the
+ *    gRPC `ListNodes` RPC). Schemas are populated per-SDK in SPEC-B P2/P3; until
+ *    then they're `null`.
+ *
+ * Pure + structurally typed so it's unit-testable without booting a server.
+ */
+
+/** One node in the catalog. */
+export interface NodeCatalogEntry {
+	name: string;
+	/**
+	 * The exact resolvable string an author puts in a step's `use:`.
+	 * Module nodes → the registry Map key (e.g. "@blokjs/api-call", NOT the
+	 * display `name`). Runtime nodes → "runtime.<kind>:<name>" (per inferStepType).
+	 */
+	ref: string;
+	/** "module" for in-process nodes, "runtime.<kind>" for SDK runtimes. */
+	runtime: string;
+	description?: string;
+	/** Parsed JSON Schema, or null when the node/SDK doesn't expose one. */
+	inputSchema: unknown | null;
+	outputSchema: unknown | null;
+	tags: string[];
+}
+
+interface ReflectableNode {
+	name?: string;
+	description?: string;
+	getReflectionSchemas?: () => { input: unknown; output: unknown };
+	getSchemas?: () => { input: unknown; output: unknown };
+}
+
+interface RuntimeNode {
+	name: string;
+	description?: string;
+	inputSchema: unknown | null;
+	outputSchema: unknown | null;
+	tags?: string[];
+}
+
+interface ListableAdapter {
+	listNodes?: () => Promise<RuntimeNode[]>;
+}
+
+/** An empty object (`{}`) means "no constraints" — surface it as null in the catalog. */
+function normSchema(schema: unknown): unknown | null {
+	return schema && typeof schema === "object" && Object.keys(schema as object).length > 0 ? schema : null;
+}
+
+/** Extract `{ name, description, inputSchema, outputSchema }` from an in-process node. */
+export function reflectModuleNode(node: unknown): {
+	name?: string;
+	description?: string;
+	inputSchema: unknown | null;
+	outputSchema: unknown | null;
+} {
+	const n = node as ReflectableNode;
+	let input: unknown | null = null;
+	let output: unknown | null = null;
+	if (typeof n.getReflectionSchemas === "function") {
+		const s = n.getReflectionSchemas();
+		input = normSchema(s.input);
+		output = normSchema(s.output);
+	} else if (typeof n.getSchemas === "function") {
+		const s = n.getSchemas();
+		input = normSchema(s.input);
+		output = normSchema(s.output);
+	}
+	return { name: n.name, description: n.description, inputSchema: input, outputSchema: output };
+}
+
+/**
+ * Build the full catalog from the in-process node map + the runtime adapters.
+ * One unreachable runtime can't break the catalog (its `listNodes()` rejection
+ * is swallowed). Sorted by runtime then name for stable output.
+ */
+export async function buildNodeCatalog(
+	moduleNodes: Map<string, unknown> | undefined,
+	runtimes: ReadonlyArray<{ kind: string; adapter: ListableAdapter }>,
+): Promise<NodeCatalogEntry[]> {
+	const out: NodeCatalogEntry[] = [];
+
+	if (moduleNodes) {
+		for (const [key, node] of moduleNodes) {
+			const r = reflectModuleNode(node);
+			out.push({
+				name: r.name ?? key,
+				ref: key, // the registry key is the resolvable `use` ref, not the display name
+				runtime: "module",
+				description: r.description,
+				inputSchema: r.inputSchema,
+				outputSchema: r.outputSchema,
+				tags: [],
+			});
+		}
+	}
+
+	for (const { kind, adapter } of runtimes) {
+		if (typeof adapter.listNodes !== "function") continue;
+		try {
+			const nodes = await adapter.listNodes();
+			for (const n of nodes) {
+				out.push({
+					name: n.name,
+					ref: `runtime.${kind}:${n.name}`, // resolvable `use` ref per inferStepType
+					runtime: `runtime.${kind}`,
+					description: n.description,
+					inputSchema: n.inputSchema,
+					outputSchema: n.outputSchema,
+					tags: n.tags ?? [],
+				});
+			}
+		} catch {
+			/* skip an unreachable runtime — don't fail the whole catalog */
+		}
+	}
+
+	out.sort((a, b) => a.runtime.localeCompare(b.runtime) || a.name.localeCompare(b.name));
+	return out;
+}

package/dist/scaffold-repo/triggers/http/src/runner/responseEmitter.ts

@@ -0,0 +1,138 @@
+import { type RespondEnvelope, isRespondEnvelope } from "@blokjs/shared";
+import type { Context as HonoContext } from "hono";
+
+/**
+ * Turn a finished workflow's `ctx.response` into a Hono `Response`.
+ *
+ * Resolution order:
+ *  1. **Branded {@link RespondEnvelope}** (from the `@blokjs/respond` node) —
+ *     full control: status, arbitrary headers, repeatable `Set-Cookie`,
+ *     Content-Type, and a string / binary / object / empty body.
+ *  2. **Raw binary** (`Uint8Array`/`Buffer`/`ArrayBuffer`) — sent as-is with
+ *     the resolved Content-Type (NOT JSON-stringified).
+ *  3. **String** — written verbatim (status 200).
+ *  4. **Object** — JSON (status 200).
+ *
+ * Cases 2–4 preserve the pre-existing trigger behaviour exactly, so workflows
+ * that don't opt into a respond envelope or binary body are unaffected.
+ *
+ * Extracted from the trigger handler so the emission logic is unit-testable
+ * against a real Hono context (`app.request(...)`).
+ */
+/**
+ * Normalize a finished workflow's `ctx.response` into a `{ data, contentType,
+ * … }` envelope WITHOUT mutating the node's return value.
+ *
+ * Module nodes already hand back a `BlokResponse` wrapper (carrying its own
+ * `data` + `contentType`). Runtime adapter nodes — and any raw `RunnerNode` —
+ * leave their return value verbatim on `ctx.response`. The old trigger code
+ * wrote `ctx.response.contentType = …` straight onto that raw value, which (a)
+ * leaked a spurious `contentType` key into the JSON body of every `runtime.*`
+ * node and (b) threw on a primitive return.
+ *
+ * This wraps raw values instead, so the content-type travels ALONGSIDE the body
+ * (mapped to the `Content-Type` header by {@link emitWorkflowResponse}), never
+ * inside it. `fallbackContentType` is the SDK's proto `content_type` (surfaced
+ * via the `_stepContentType` ctx side-channel), defaulting to JSON.
+ *
+ * Returns the SAME object for an already-wrapped response (defaulting an
+ * empty/missing `contentType` in place); a fresh wrapper otherwise.
+ */
+export function normalizeResponseEnvelope(ctxResponse: unknown, fallbackContentType = "application/json"): unknown {
+	const isWrapper =
+		!!ctxResponse && typeof ctxResponse === "object" && "data" in ctxResponse && "contentType" in ctxResponse;
+
+	if (!isWrapper) {
+		return { data: ctxResponse, contentType: fallbackContentType, success: true, error: null };
+	}
+
+	const wrapper = ctxResponse as { contentType?: string };
+	if (wrapper.contentType === undefined || wrapper.contentType === "") {
+		try {
+			wrapper.contentType = fallbackContentType;
+		} catch {
+			// Non-extensible / readonly `contentType` — emitWorkflowResponse
+			// falls back to JSON, so nothing downstream breaks.
+		}
+	}
+	return ctxResponse;
+}
+
+export function emitWorkflowResponse(c: HonoContext, ctxResponse: unknown): Response {
+	// Module nodes wrap output in a BlokResponse ({ data, contentType, … });
+	// runtime adapter nodes leave raw data on ctx.response.
+	const hasWrapper =
+		!!ctxResponse && typeof ctxResponse === "object" && "data" in ctxResponse && "contentType" in ctxResponse;
+	const data = hasWrapper ? (ctxResponse as { data: unknown }).data : ctxResponse;
+
+	if (isRespondEnvelope(data)) {
+		return emitRespondEnvelope(c, data);
+	}
+
+	const contentType = hasWrapper
+		? ((ctxResponse as { contentType?: string }).contentType ?? "application/json")
+		: "application/json";
+	c.header("Content-Type", contentType);
+	// Raw binary is sent as-is — routing it through c.json would JSON-stringify
+	// the bytes (`{"type":"Buffer","data":[…]}`) and reset the Content-Type.
+	if (isBinaryBody(data)) {
+		return c.body(toArrayBuffer(data), 200);
+	}
+	if (typeof data === "string") {
+		return c.body(data, 200);
+	}
+	return c.json(data as object, 200);
+}
+
+/**
+ * Emit a workflow-controlled response from a {@link RespondEnvelope}. Honors a
+ * custom status, arbitrary headers (incl. `Location`), repeatable `Set-Cookie`
+ * values, a Content-Type override, and a string / binary / object / empty body.
+ */
+export function emitRespondEnvelope(c: HonoContext, env: RespondEnvelope): Response {
+	const status = (env.status ?? 200) as 200;
+	const body = env.body;
+	const binary = isBinaryBody(body);
+	const contentType = env.contentType ?? (binary ? "application/octet-stream" : "application/json");
+
+	if (env.headers) {
+		for (const [key, value] of Object.entries(env.headers)) c.header(key, value);
+	}
+	// `Set-Cookie` legitimately repeats — append each value as its own header.
+	if (env.cookies) {
+		for (const cookie of env.cookies) c.header("Set-Cookie", cookie, { append: true });
+	}
+
+	// Empty body (e.g. a 302 redirect) — don't impose a Content-Type.
+	if (body === undefined || body === null) {
+		return c.body(null, status);
+	}
+	c.header("Content-Type", contentType);
+	if (binary) {
+		return c.body(toArrayBuffer(body as Uint8Array | ArrayBuffer), status);
+	}
+	if (typeof body === "string") {
+		return c.body(body, status);
+	}
+	// Object body → JSON-encode manually (rather than c.json) so an explicit
+	// `contentType` override is honored instead of being forced to JSON.
+	return c.body(JSON.stringify(body), status);
+}
+
+/**
+ * True when `v` is a raw binary body the trigger should send as-is.
+ * `Buffer` is a `Uint8Array` subclass, so the `Uint8Array` check covers it.
+ */
+export function isBinaryBody(v: unknown): v is Uint8Array | ArrayBuffer {
+	return v instanceof Uint8Array || v instanceof ArrayBuffer;
+}
+
+/**
+ * Normalize a binary body to an `ArrayBuffer` (Hono / Web `Response` body).
+ * For a `Uint8Array`/`Buffer` view, copy the exact byte window so a pooled
+ * Buffer's backing store isn't leaked into the response.
+ */
+export function toArrayBuffer(v: Uint8Array | ArrayBuffer): ArrayBuffer {
+	if (v instanceof ArrayBuffer) return v;
+	return v.buffer.slice(v.byteOffset, v.byteOffset + v.byteLength) as ArrayBuffer;
+}

package/dist/scaffold-repo/triggers/http/src/runner/scanWorkflows.ts

@@ -0,0 +1,201 @@
+import { promises as fsp } from "node:fs";
+import * as path from "node:path";
+
+/**
+ * scanWorkflows — recursive directory scanner that discovers HTTP-triggered
+ * workflows on disk and derives a default URL path from each file's location.
+ *
+ * **Path derivation rules** (file path → URL):
+ * ```
+ * workflows/health.ts                      → /health
+ * workflows/index.ts                       → /
+ * workflows/users/list.ts                  → /users/list
+ * workflows/users/index.ts                 → /users
+ * workflows/users/[id].ts                  → /users/:id
+ * workflows/users/[id]/orders.ts           → /users/:id/orders
+ * workflows/json/orders/by-status/[s].json → /orders/by-status/:s
+ *                                            (the `json/` segment is a format
+ *                                             indicator, not a URL segment)
+ * ```
+ *
+ * **Skipped files** (return no scanned entry):
+ * - Files or directories whose name starts with `_` or `.`
+ *   (utilities, drafts, hidden files)
+ * - Files whose extension isn't allowed (only `.ts`, `.js`, `.json` for now)
+ *
+ * **Workflow detection**:
+ * - For TS/JS: dynamic-imports, takes `default` export.
+ * - For JSON: `readFile` + `JSON.parse`.
+ * - Files that don't yield a recognisable workflow shape are skipped with
+ *   a warning (caller decides whether to surface to the operator).
+ */
+
+/** A workflow entry produced by the scanner. */
+export interface ScannedWorkflow {
+	/** Absolute filesystem path. */
+	readonly source: string;
+	/** Source format. */
+	readonly kind: "ts" | "json";
+	/** Default URL path derived from the file's location. */
+	readonly defaultPath: string;
+	/** Parsed workflow object — raw, not normalized. */
+	readonly workflow: unknown;
+	/** Workflow name extracted from the parsed object (best-effort). */
+	readonly name: string | undefined;
+}
+
+/** Configuration for one scan root. */
+export interface ScanRoot {
+	/** Absolute directory to walk recursively. */
+	readonly dir: string;
+	/**
+	 * Number of leading directory segments to strip from the file's
+	 * path-relative-to-`dir` before deriving the URL. Used to elide the
+	 * format-indicator folder (e.g. `json/` for JSON workflows).
+	 */
+	readonly stripLeadingSegments?: number;
+	/** Allowed extensions. Defaults to `[".ts", ".js"]` for TS, `[".json"]` for JSON. */
+	readonly extensions?: readonly string[];
+	/** Source kind reported on each entry. */
+	readonly kind: "ts" | "json";
+}
+
+/**
+ * Walk every root and produce a flat list of scanned workflows.
+ *
+ * Errors loading individual files are caught and surfaced via the
+ * `onLoadError` callback (when supplied). The scanner never throws on
+ * a single bad file — boot continues with the rest.
+ */
+export async function scanWorkflows(
+	roots: readonly ScanRoot[],
+	options: { onLoadError?: (file: string, err: Error) => void } = {},
+): Promise<ScannedWorkflow[]> {
+	const out: ScannedWorkflow[] = [];
+	for (const root of roots) {
+		const exists = await dirExists(root.dir);
+		if (!exists) continue;
+		const allowedExts = root.extensions ?? defaultExtensions(root.kind);
+		await walk(root.dir, root.dir, root, allowedExts, out, options);
+	}
+	return out;
+}
+
+/**
+ * Convert a file path (relative to a scan root) to a URL path.
+ *
+ * **EXPORTED FOR UNIT TESTING.** Pure function with no I/O.
+ *
+ * @param relativePath - file path relative to its scan root, with extension
+ * @param stripLeadingSegments - number of leading dirs to drop (e.g. `1`
+ *   for JSON which lives under `workflows/json/`)
+ * @returns derived URL like `/users/:id`, or `/` for root index
+ */
+export function deriveUrlFromFilePath(relativePath: string, stripLeadingSegments = 0): string {
+	const noExt = relativePath.replace(/\.(ts|js|json)$/i, "");
+	const segments = noExt.split(path.sep).filter((s) => s.length > 0);
+	const stripped = segments.slice(stripLeadingSegments);
+
+	if (stripped.length === 0) return "/";
+
+	// Drop trailing `index` (folder URL convention).
+	if (stripped[stripped.length - 1] === "index") stripped.pop();
+
+	if (stripped.length === 0) return "/";
+
+	// Convert [param] → :param on each segment.
+	const converted = stripped.map((seg) => {
+		const match = seg.match(/^\[(\.{3})?([A-Za-z_][A-Za-z0-9_]*)\]$/);
+		if (!match) return seg;
+		// `[...slug]` catch-all is reserved for a future iteration.
+		// For v1 we only handle `[id]` → `:id`.
+		return `:${match[2]}`;
+	});
+
+	return `/${converted.join("/")}`;
+}
+
+// ---------------------------------------------------------------------------
+
+async function walk(
+	rootDir: string,
+	currentDir: string,
+	root: ScanRoot,
+	allowedExts: readonly string[],
+	out: ScannedWorkflow[],
+	options: { onLoadError?: (file: string, err: Error) => void },
+): Promise<void> {
+	let entries: import("node:fs").Dirent[];
+	try {
+		entries = await fsp.readdir(currentDir, { withFileTypes: true });
+	} catch (err) {
+		options.onLoadError?.(currentDir, err as Error);
+		return;
+	}
+
+	for (const entry of entries) {
+		// Skip hidden and convention-private entries.
+		if (entry.name.startsWith("_") || entry.name.startsWith(".")) continue;
+
+		const fullPath = path.join(currentDir, entry.name);
+		if (entry.isDirectory()) {
+			await walk(rootDir, fullPath, root, allowedExts, out, options);
+			continue;
+		}
+		if (!entry.isFile()) continue;
+		if (!allowedExts.some((ext) => entry.name.endsWith(ext))) continue;
+
+		const relativePath = path.relative(rootDir, fullPath);
+		const defaultPath = deriveUrlFromFilePath(relativePath, root.stripLeadingSegments);
+
+		try {
+			const wf = await loadOne(fullPath, root.kind);
+			if (wf === null) continue;
+			out.push({
+				source: fullPath,
+				kind: root.kind,
+				defaultPath,
+				workflow: wf,
+				name: extractWorkflowName(wf),
+			});
+		} catch (err) {
+			options.onLoadError?.(fullPath, err as Error);
+		}
+	}
+}
+
+async function loadOne(file: string, kind: "ts" | "json"): Promise<unknown> {
+	if (kind === "json") {
+		const text = await fsp.readFile(file, "utf8");
+		return JSON.parse(text);
+	}
+	// TS / JS — dynamic import; default export is the workflow.
+	const mod = (await import(file)) as { default?: unknown };
+	if (mod.default === undefined) return null;
+	return mod.default;
+}
+
+function defaultExtensions(kind: "ts" | "json"): readonly string[] {
+	if (kind === "json") return [".json"];
+	return [".ts", ".js"];
+}
+
+async function dirExists(dir: string): Promise<boolean> {
+	try {
+		const stat = await fsp.stat(dir);
+		return stat.isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+function extractWorkflowName(wf: unknown): string | undefined {
+	if (!wf || typeof wf !== "object") return undefined;
+	const obj = wf as Record<string, unknown>;
+	if (typeof obj.name === "string") return obj.name;
+	const config = obj._config;
+	if (config && typeof config === "object" && typeof (config as Record<string, unknown>).name === "string") {
+		return (config as Record<string, unknown>).name as string;
+	}
+	return undefined;
+}

package/dist/scaffold-repo/triggers/http/src/runner/types/ErrorResponse.ts

@@ -0,0 +1,3 @@
+type ErrorResponse = {
+	error: string;
+};

package/dist/scaffold-repo/triggers/http/src/runner/types/NodeTypes.ts

@@ -0,0 +1,13 @@
+enum NodeTypes {
+	MODULE = "module",
+	LOCAL = "local",
+	PYTHON3 = "runtime.python3",
+	GO = "runtime.go",
+	RUST = "runtime.rust",
+	JAVA = "runtime.java",
+	CSHARP = "runtime.csharp",
+	PHP = "runtime.php",
+	RUBY = "runtime.ruby",
+}
+
+export default NodeTypes;

package/dist/scaffold-repo/triggers/http/src/runner/types/Nodes.ts

@@ -0,0 +1,5 @@
+import type { BlokService } from "@blokjs/runner";
+
+type Nodes = Record<string, BlokService<unknown>>;
+
+export default Nodes;

package/dist/scaffold-repo/triggers/http/src/runner/types/RuntimeWorkflow.ts

@@ -0,0 +1,7 @@
+import type { ParamsDictionary } from "@blokjs/runner";
+
+type RuntimeWorkflow = {
+	workflow: ParamsDictionary;
+};
+
+export default RuntimeWorkflow;

package/dist/scaffold-repo/triggers/http/src/runner/types/WorkflowRequest.ts

@@ -0,0 +1,8 @@
+type WorkflowRequest = {
+	Name: string;
+	Encoding: string;
+	Message: string;
+	Type: string;
+};
+
+export default WorkflowRequest;

package/dist/scaffold-repo/triggers/http/src/runner/types/WorkflowResponse.ts

@@ -0,0 +1,7 @@
+type WorkflowResponse = {
+	Encoding: string;
+	Message: string;
+	Type: string;
+};
+
+export default WorkflowResponse;

package/dist/scaffold-repo/triggers/http/src/runner/types/Workflows.ts

@@ -0,0 +1,14 @@
+import type { WorkflowV2Builder } from "@blokjs/helper";
+
+/**
+ * Manual workflow registry — maps workflow keys to their `WorkflowV2Builder`
+ * instances (from the object-style `workflow({...})` factory) or promises of
+ * instances (from the callback-style `workflow("name", opts, build)` factory).
+ * Once resolved, each exposes a `_config` field and a `.toJson()` method, which
+ * is the contract `LocalStorage.get`'s fallback path consumes.
+ */
+type Workflows = {
+	[key: string]: WorkflowV2Builder | Promise<WorkflowV2Builder>;
+};
+
+export default Workflows;

package/dist/scaffold-repo/triggers/http/src/workflows/countries-cats-helper.ts

@@ -0,0 +1,30 @@
+import { http, branch, eq, node, step, workflow } from "@blokjs/core";
+
+export default workflow(
+	"countries.withCats",
+	{
+		version: "1.0.0",
+		description: "Workflow description",
+		trigger: http.get("/countries-cats-helper", { accept: "application/json" }),
+	},
+	(req) => {
+		branch("filter-request", eq(req.query.countries, "true"), {
+			then: () => {
+				step("get-countries", node("@blokjs/api-call"), {
+					url: "https://countriesnow.space/api/v0.1/countries",
+					method: "GET",
+					headers: { "Content-Type": "application/json" },
+					responseType: "application/json",
+				});
+			},
+			else: () => {
+				step("get-facts", node("@blokjs/api-call"), {
+					url: "https://catfact.ninja/fact",
+					method: "GET",
+					headers: { "Content-Type": "application/json" },
+					responseType: "application/json",
+				});
+			},
+		});
+	},
+);

package/dist/scaffold-repo/triggers/http/src/workflows/countries-handle-dsl.ts

@@ -0,0 +1,25 @@
+/**
+ * The typed-handle DSL from `@blokjs/core` — Blok's canonical TypeScript
+ * authoring surface. This example imports a node's VALUE (`apiCall`,
+ * `RespondNode`) and passes it to `step()`; the sibling `countries-helper` /
+ * `countries-cats-helper` use the name-only `node("@blokjs/api-call")` form.
+ *
+ * `step(id, node, inputs)` runs the node and returns a TYPED handle. Pass that
+ * handle straight into a later step — no `$`, no `js/`, no raw `ctx` strings;
+ * the runner resolves it. Object-style `workflow({ steps: [...] })` from
+ * `@blokjs/helper` and JSON remain supported (same engine, same IR).
+ */
+import apiCall from "@blokjs/api-call";
+import { http, step, workflow } from "@blokjs/core";
+import { RespondNode } from "@blokjs/helpers";
+
+export default workflow("countries.dsl", { version: "1.0.0", trigger: http.get("/countries-dsl") }, () => {
+	const countries = step("fetch", apiCall, {
+		url: "https://countriesnow.space/api/v0.1/countries/capital",
+		method: "GET",
+		headers: { "Content-Type": "application/json" },
+		responseType: "application/json",
+	});
+
+	step("respond", RespondNode, { body: countries }, { ephemeral: true });
+});

package/dist/scaffold-repo/triggers/http/src/workflows/countries-helper.ts

@@ -0,0 +1,18 @@
+import { http, node, step, workflow } from "@blokjs/core";
+
+export default workflow(
+	"countries.list",
+	{
+		version: "1.0.0",
+		description: "Workflow description",
+		trigger: http.get("/countries-helper", { accept: "application/json" }),
+	},
+	() => {
+		step("get-countries-api", node("@blokjs/api-call"), {
+			url: "https://countriesnow.space/api/v0.1/countries/capital",
+			method: "GET",
+			headers: { "Content-Type": "application/json" },
+			responseType: "application/json",
+		});
+	},
+);

package/dist/scaffold-repo/triggers/http/src/workflows/empty.ts

@@ -0,0 +1,16 @@
+import { http, branch, eq, workflow } from "@blokjs/core";
+
+export default workflow(
+	"Empty",
+	{
+		version: "1.0.0",
+		description: "Workflow for load testing",
+		trigger: http.get("/empty-helper", { accept: "application/json" }),
+	},
+	(req) => {
+		branch("filter-request", eq(req.query.countries, "true"), {
+			then: () => {},
+			else: () => {},
+		});
+	},
+);

package/dist/scaffold-repo/triggers/http/src/workflows/eval/eval-retrieve.ts

@@ -0,0 +1,23 @@
+import { http, node, step, workflow } from "@blokjs/core";
+import type { Handle } from "@blokjs/core";
+
+/**
+ * Child workflow dispatched per-item by `eval.run`'s forEach. Mirrors the
+ * tetrix-blok retrieval seam. The parent step's `inputs` become this
+ * workflow's `ctx.request.body` (function-call semantics).
+ *
+ * Last step's output IS the workflow's response — so the parent reads it at
+ * `ctx.state.retrieve.data` (the child's ResponseContext envelope).
+ */
+export default workflow(
+	"eval.retrieve",
+	{
+		version: "1.0.0",
+		description: "Eval harness — retrieve hits for one item's query",
+		trigger: http.post("/eval/retrieve"),
+	},
+	(req) => {
+		const body = req.body as Handle<{ query: string }>;
+		step("search", node("eval-search"), { query: body.query });
+	},
+);