@boardwalk-labs/engine 0.1.4 → 0.1.6

package/dist/engine.d.ts

@@ -65,7 +65,7 @@ export declare class Engine {
     /** Subscribe to every stamped run event (feeds SSE, the CLI renderer, the log UI). */
     onEvent(listener: (row: EventRow) => void): () => void;
     /**
-     * Deploy (or redeploy, by manifest name) a workflow from its bundled program source. The
+     * Deploy (or redeploy, by manifest slug) a workflow from its bundled program source. The
      * manifest is DERIVED from the program's pure-literal `meta` — the program file is the
      * author's source of truth, manifest drift is impossible by construction.
      */
@@ -74,7 +74,7 @@ export declare class Engine {
      * Queue a run and dispatch it through the concurrency gate. Returns the queued row
      * immediately; `waitForRun` for the terminal row.
      */
-    startRun(workflowName: string, opts?: {
+    startRun(slug: string, opts?: {
         input?: JsonValue;
         triggerKind?: TriggerKind;
     }): RunRow;

package/dist/engine.js

@@ -75,7 +75,7 @@ export class Engine {
         return this.supervisor.onEvent(listener);
     }
     /**
-     * Deploy (or redeploy, by manifest name) a workflow from its bundled program source. The
+     * Deploy (or redeploy, by manifest slug) a workflow from its bundled program source. The
      * manifest is DERIVED from the program's pure-literal `meta` — the program file is the
      * author's source of truth, manifest drift is impossible by construction.
      */
@@ -83,7 +83,7 @@ export class Engine {
         this.assertOpen();
         const manifest = extractManifest(args.program, { fileName: "index.mjs" });
         const workflow = this.store.upsertWorkflow({
-            name: manifest.slug,
+            slug: manifest.slug,
             manifest,
             program: args.program,
             ...(args.config !== undefined ? { config: args.config } : {}),
@@ -106,11 +106,11 @@ export class Engine {
      * Queue a run and dispatch it through the concurrency gate. Returns the queued row
      * immediately; `waitForRun` for the terminal row.
      */
-    startRun(workflowName, opts = {}) {
+    startRun(slug, opts = {}) {
         this.assertOpen();
-        const workflow = this.store.getWorkflow(workflowName);
+        const workflow = this.store.getWorkflow(slug);
         if (workflow === null) {
-            throw new EngineError("NOT_FOUND", `Workflow "${workflowName}" is not deployed on this engine.`);
+            throw new EngineError("NOT_FOUND", `Workflow "${slug}" is not deployed on this engine.`);
         }
         const { run } = this.store.createRun({
             workflowId: workflow.id,
@@ -168,7 +168,7 @@ export class Engine {
      */
     async runOnce(args) {
         const workflow = this.deployWorkflow(args);
-        const run = this.startRun(workflow.name, {
+        const run = this.startRun(workflow.slug, {
             ...(args.input !== undefined ? { input: args.input } : {}),
         });
         return await this.waitForRun(run.id);

package/dist/run/supervisor.js

@@ -510,7 +510,7 @@ export class RunSupervisor {
     startChildRun(parentRunId, slug, input, idempotencyKey) {
         const target = this.store.getWorkflow(slug);
         if (target === null) {
-            throw new EngineError("NOT_FOUND", `workflows.call target "${slug}" is not deployed on this engine.`, `Deploy it first — the engine only runs workflows it knows by name.`);
+            throw new EngineError("NOT_FOUND", `workflows.call target "${slug}" is not deployed on this engine.`, `Deploy it first — the engine only runs workflows it knows by slug.`);
         }
         // Crossed the JSON IPC channel, but narrow instead of assuming — and
         // the canonical default key requires a JSON tree anyway.

package/dist/server/routes/api.d.ts

@@ -3,8 +3,8 @@ import type { RouteContext } from "./router.js";
 export declare function handleListWorkflows(ctx: RouteContext): void;
 /** GET /api/runs?workflow=&status=&limit=&offset= — newest first, full RunRow shape. */
 export declare function handleListRuns(ctx: RouteContext): void;
-/** POST /api/workflows/:name/runs — start a manual run; 201 with the queued row. */
-export declare function handleStartRun(ctx: RouteContext, workflowName: string): Promise<void>;
+/** POST /api/workflows/:slug/runs — start a manual run; 201 with the queued row. */
+export declare function handleStartRun(ctx: RouteContext, slug: string): Promise<void>;
 /** GET /api/runs/:id */
 export declare function handleGetRun(ctx: RouteContext, runId: string): void;
 /**

package/dist/server/routes/api.js

@@ -29,7 +29,7 @@ function isRunStatus(value) {
 /** GET /api/workflows — names + manifest-derived fields, enough to render a picker. */
 export function handleListWorkflows(ctx) {
     const workflows = ctx.engine.store.listWorkflows().map((row) => ({
-        name: row.name,
+        slug: row.slug,
         description: row.manifest.description ?? null,
         triggers: row.manifest.triggers,
         createdAt: row.createdAt,
@@ -43,11 +43,11 @@ export function handleListRuns(ctx) {
         limit: parseNonNegativeInt(ctx.url, "limit", DEFAULT_RUNS_LIMIT),
         offset: parseNonNegativeInt(ctx.url, "offset", 0),
     };
-    const workflowName = ctx.url.searchParams.get("workflow");
-    if (workflowName !== null) {
-        const workflow = ctx.engine.store.getWorkflow(workflowName);
+    const slug = ctx.url.searchParams.get("workflow");
+    if (slug !== null) {
+        const workflow = ctx.engine.store.getWorkflow(slug);
         if (workflow === null) {
-            throw new HttpError(404, "NOT_FOUND", `Workflow "${workflowName}" is not deployed on this engine.`);
+            throw new HttpError(404, "NOT_FOUND", `Workflow "${slug}" is not deployed on this engine.`);
         }
         filter.workflowId = workflow.id;
     }
@@ -60,12 +60,12 @@ export function handleListRuns(ctx) {
     }
     sendJson(ctx.res, 200, { runs: ctx.engine.store.listRuns(filter) });
 }
-/** POST /api/workflows/:name/runs — start a manual run; 201 with the queued row. */
-export async function handleStartRun(ctx, workflowName) {
+/** POST /api/workflows/:slug/runs — start a manual run; 201 with the queued row. */
+export async function handleStartRun(ctx, slug) {
     const raw = await readBody(ctx.req, MAX_BODY_BYTES);
     // An empty body means "no input" — the curl-without-data ergonomics of a run-now button.
     const body = raw.length === 0 ? {} : parseJsonBody(raw, startRunBodySchema, "run-start body");
-    const run = ctx.engine.startRun(workflowName, {
+    const run = ctx.engine.startRun(slug, {
         triggerKind: "manual",
         ...(body.input !== undefined ? { input: body.input } : {}),
     });

package/dist/server/routes/hooks.d.ts

@@ -1,2 +1,2 @@
 import type { RouteContext } from "./router.js";
-export declare function handleWebhook(ctx: RouteContext, workflowName: string, triggerIndexRaw: string): Promise<void>;
+export declare function handleWebhook(ctx: RouteContext, slug: string, triggerIndexRaw: string): Promise<void>;

package/dist/server/routes/hooks.js

@@ -5,19 +5,19 @@
 //   token auth:     BOARDWALK_WEBHOOK_TOKEN__<NAME>   vs  `Authorization: Bearer <token>`
 //   signature auth: BOARDWALK_WEBHOOK_SECRET__<NAME>  vs  `X-Boardwalk-Signature: sha256=<hex>`
 //                   (HMAC-SHA256 over the raw request body)
-// where <NAME> is the workflow name upper-cased with `-` → `_`. Missing variable = 503 (fail
+// where <NAME> is the workflow slug upper-cased with `-` → `_`. Missing variable = 503 (fail
 // closed, hint names the variable); bad credential = 401. These are server config, not
 // workflow secrets, so they resolve from process.env — never from the engine's env map.
 import { createHash, createHmac, timingSafeEqual } from "node:crypto";
 import { HttpError, MAX_BODY_BYTES, jsonValueSchema, parseJsonBody, readBody, sendJson, } from "../http.js";
-export async function handleWebhook(ctx, workflowName, triggerIndexRaw) {
+export async function handleWebhook(ctx, slug, triggerIndexRaw) {
     // The raw body is read up front: signature auth signs the exact bytes on the wire, before
     // any JSON parsing can normalize them away.
     const rawBody = await readBody(ctx.req, MAX_BODY_BYTES);
     // One identical 404 for "no workflow", "no such trigger index", and "not a webhook
     // trigger" — an unauthenticated caller learns nothing about what is deployed here.
-    const notFound = new HttpError(404, "NOT_FOUND", `No webhook trigger at /hooks/${workflowName}/${triggerIndexRaw}.`);
-    const workflow = ctx.engine.store.getWorkflow(workflowName);
+    const notFound = new HttpError(404, "NOT_FOUND", `No webhook trigger at /hooks/${slug}/${triggerIndexRaw}.`);
+    const workflow = ctx.engine.store.getWorkflow(slug);
     if (workflow === null)
         throw notFound;
     if (!/^\d+$/.test(triggerIndexRaw))
@@ -26,27 +26,27 @@ export async function handleWebhook(ctx, workflowName, triggerIndexRaw) {
     if (trigger === undefined || trigger.kind !== "webhook")
         throw notFound;
     if (trigger.auth === "token")
-        authorizeToken(ctx.req, workflowName);
+        authorizeToken(ctx.req, slug);
     else
-        authorizeSignature(ctx.req, workflowName, rawBody);
+        authorizeSignature(ctx.req, slug, rawBody);
     const input = rawBody.length === 0 ? null : parseJsonBody(rawBody, jsonValueSchema, "webhook payload");
-    const run = ctx.engine.startRun(workflowName, { input, triggerKind: "webhook" });
+    const run = ctx.engine.startRun(slug, { input, triggerKind: "webhook" });
     sendJson(ctx.res, 201, { run: { id: run.id, status: run.status } });
 }
-/** `BOARDWALK_WEBHOOK_<kind>__<NAME>`: the workflow name upper-cased, hyphens → underscores. */
-function webhookEnvVarName(kind, workflowName) {
-    return `BOARDWALK_WEBHOOK_${kind}__${workflowName.toUpperCase().replaceAll("-", "_")}`;
+/** `BOARDWALK_WEBHOOK_<kind>__<NAME>`: the workflow slug upper-cased, hyphens → underscores. */
+function webhookEnvVarName(kind, slug) {
+    return `BOARDWALK_WEBHOOK_${kind}__${slug.toUpperCase().replaceAll("-", "_")}`;
 }
 /**
  * Read the trigger's credential from the server environment, failing CLOSED when unset: a
  * webhook that nobody configured must never become an open trigger. Read lazily per request
  * so an operator can fix the environment without redeploying workflows.
  */
-function requiredCredential(kind, workflowName) {
-    const name = webhookEnvVarName(kind, workflowName);
+function requiredCredential(kind, slug) {
+    const name = webhookEnvVarName(kind, slug);
     const value = process.env[name];
     if (value === undefined || value === "") {
-        throw new HttpError(503, "WEBHOOK_UNCONFIGURED", `Webhook auth for workflow "${workflowName}" is not configured on this server.`, `Set the environment variable ${name} and restart the server.`);
+        throw new HttpError(503, "WEBHOOK_UNCONFIGURED", `Webhook auth for workflow "${slug}" is not configured on this server.`, `Set the environment variable ${name} and restart the server.`);
     }
     return value;
 }
@@ -54,16 +54,16 @@ function requiredCredential(kind, workflowName) {
 function unauthorized() {
     return new HttpError(401, "UNAUTHORIZED", "Invalid webhook credentials.");
 }
-function authorizeToken(req, workflowName) {
-    const expected = requiredCredential("TOKEN", workflowName);
+function authorizeToken(req, slug) {
+    const expected = requiredCredential("TOKEN", slug);
     const header = req.headers.authorization;
     if (header === undefined || !header.startsWith("Bearer "))
         throw unauthorized();
     if (!constantTimeEquals(header.slice("Bearer ".length), expected))
         throw unauthorized();
 }
-function authorizeSignature(req, workflowName, rawBody) {
-    const secret = requiredCredential("SECRET", workflowName);
+function authorizeSignature(req, slug, rawBody) {
+    const secret = requiredCredential("SECRET", slug);
     const header = req.headers["x-boardwalk-signature"];
     if (typeof header !== "string")
         throw unauthorized();

package/dist/server/routes/ui.js

@@ -70,7 +70,7 @@ async function loadWorkflows() {
   }
   box.append(rowButton("all workflows", () => { selectedWorkflow = null; loadRuns(); }));
   for (const workflow of workflows) {
-    box.append(rowButton(workflow.name, () => { selectedWorkflow = workflow.name; loadRuns(); }));
+    box.append(rowButton(workflow.slug, () => { selectedWorkflow = workflow.slug; loadRuns(); }));
   }
 }
 

package/dist/server_main.js

@@ -122,7 +122,7 @@ export function loadServerConfig(env) {
 /**
  * Deploy every built workflow in `dir` on boot — the self-host deploy mechanism. Each `.mjs`/`.js`
  * file is one workflow's program (single-file, `@boardwalk-labs/workflow` external — what
- * `boardwalk build` emits). Idempotent by manifest name (re-boot re-syncs the dir into the store);
+ * `boardwalk build` emits). Idempotent by manifest slug (re-boot re-syncs the dir into the store);
  * a removed file leaves its last-deployed workflow in place (no un-deploy in v0). A missing dir is
  * fine (an operator may deploy by other means); a bad file is logged and skipped, never fatal.
  */
@@ -143,7 +143,7 @@ function deployWorkflowsFromDir(engine, dir, log) {
         try {
             const program = readFileSync(join(dir, file), "utf8");
             const workflow = engine.deployWorkflow({ program });
-            log(`deployed "${workflow.name}" from ${file}`);
+            log(`deployed "${workflow.slug}" from ${file}`);
         }
         catch (err) {
             log(`skipped ${file}: ${err instanceof Error ? err.message : String(err)}`);

package/dist/store/migrations.js

@@ -9,7 +9,7 @@ const V1_SQL = `
 -- the per-deploy JSON config object.
 CREATE TABLE workflows (
   id          TEXT PRIMARY KEY,
-  name        TEXT NOT NULL UNIQUE,
+  slug        TEXT NOT NULL UNIQUE,
   manifest    TEXT NOT NULL,
   program     TEXT NOT NULL,
   config      TEXT NOT NULL,

package/dist/store/store.d.ts

@@ -3,7 +3,7 @@ export type { RunStatus };
 /** A deployed workflow: validated manifest + bundled program source + per-deploy config. */
 export interface WorkflowRow {
     id: string;
-    name: string;
+    slug: string;
     manifest: WorkflowManifest;
     program: string;
     config: Record<string, JsonValue>;
@@ -80,17 +80,17 @@ export declare class Store {
      */
     transaction<T>(fn: () => T): T;
     /**
-     * Insert a workflow or update it by name (deploying again is always an update — the name is
+     * Insert a workflow or update it by slug (deploying again is always an update — the slug is
      * the user-facing identity, so the id stays stable across redeploys and existing runs keep
      * their foreign keys). `updated_at` bumps on update; `created_at` and `id` never change.
      */
     upsertWorkflow(args: {
-        name: string;
+        slug: string;
         manifest: WorkflowManifest;
         program: string;
         config?: Record<string, JsonValue>;
     }): WorkflowRow;
-    getWorkflow(name: string): WorkflowRow | null;
+    getWorkflow(slug: string): WorkflowRow | null;
     getWorkflowById(id: string): WorkflowRow | null;
     listWorkflows(): WorkflowRow[];
     /**

package/dist/store/store.js

@@ -113,7 +113,7 @@ function readEnum(row, table, column, schema) {
 function mapWorkflow(row) {
     return {
         id: readText(row, "workflows", "id"),
-        name: readText(row, "workflows", "name"),
+        slug: readText(row, "workflows", "slug"),
         manifest: readJson(row, "workflows", "manifest", workflowManifestSchema),
         program: readText(row, "workflows", "program"),
         config: readJson(row, "workflows", "config", configSchema),
@@ -267,7 +267,7 @@ export class Store {
     // Workflows
     // --------------------------------------------------------------------------
     /**
-     * Insert a workflow or update it by name (deploying again is always an update — the name is
+     * Insert a workflow or update it by slug (deploying again is always an update — the slug is
      * the user-facing identity, so the id stays stable across redeploys and existing runs keep
      * their foreign keys). `updated_at` bumps on update; `created_at` and `id` never change.
      */
@@ -276,29 +276,29 @@ export class Store {
         // caller bug is better rejected here than persisted and discovered as INTERNAL on read.
         const manifest = workflowManifestSchema.safeParse(args.manifest);
         if (!manifest.success) {
-            throw new EngineError("VALIDATION", `manifest for workflow "${args.name}" failed validation: ${manifest.error.message}`);
+            throw new EngineError("VALIDATION", `manifest for workflow "${args.slug}" failed validation: ${manifest.error.message}`);
         }
         const manifestJson = JSON.stringify(manifest.data);
         const configJson = JSON.stringify(args.config ?? {});
         return this.transaction(() => {
             const t = this.now();
-            const existing = this.prepare("SELECT id FROM workflows WHERE name = ?").get(args.name);
+            const existing = this.prepare("SELECT id FROM workflows WHERE slug = ?").get(args.slug);
             if (existing === undefined) {
-                this.prepare(`INSERT INTO workflows (id, name, manifest, program, config, created_at, updated_at)
-           VALUES (?, ?, ?, ?, ?, ?, ?)`).run(ulid(t), args.name, manifestJson, args.program, configJson, t, t);
+                this.prepare(`INSERT INTO workflows (id, slug, manifest, program, config, created_at, updated_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?)`).run(ulid(t), args.slug, manifestJson, args.program, configJson, t, t);
             }
             else {
-                this.prepare("UPDATE workflows SET manifest = ?, program = ?, config = ?, updated_at = ? WHERE name = ?").run(manifestJson, args.program, configJson, t, args.name);
+                this.prepare("UPDATE workflows SET manifest = ?, program = ?, config = ?, updated_at = ? WHERE slug = ?").run(manifestJson, args.program, configJson, t, args.slug);
             }
-            const row = this.getWorkflow(args.name);
+            const row = this.getWorkflow(args.slug);
             if (row === null) {
-                throw new EngineError("INTERNAL", `workflow "${args.name}" vanished mid-upsert`);
+                throw new EngineError("INTERNAL", `workflow "${args.slug}" vanished mid-upsert`);
             }
             return row;
         });
     }
-    getWorkflow(name) {
-        const row = this.prepare("SELECT * FROM workflows WHERE name = ?").get(name);
+    getWorkflow(slug) {
+        const row = this.prepare("SELECT * FROM workflows WHERE slug = ?").get(slug);
         return row === undefined ? null : mapWorkflow(row);
     }
     getWorkflowById(id) {
@@ -306,7 +306,7 @@ export class Store {
         return row === undefined ? null : mapWorkflow(row);
     }
     listWorkflows() {
-        return this.prepare("SELECT * FROM workflows ORDER BY name ASC").all().map(mapWorkflow);
+        return this.prepare("SELECT * FROM workflows ORDER BY slug ASC").all().map(mapWorkflow);
     }
     // --------------------------------------------------------------------------
     // Runs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boardwalk-labs/engine",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "The Boardwalk single-node engine: cron scheduling, run lifecycle, SQLite state, and the local run log. Powers `boardwalk dev` and the self-hosted server.",
   "license": "Apache-2.0",
   "repository": {