@omg-dev/server 0.4.24

package/src/web-push.d.ts

@@ -0,0 +1,18 @@
+declare module "web-push" {
+  export interface PushSubscription {
+    endpoint: string
+    keys: {
+      p256dh: string
+      auth: string
+    }
+  }
+
+  export function setVapidDetails(subject: string, publicKey: string, privateKey: string): void
+  export function sendNotification(subscription: PushSubscription, payload?: string): Promise<unknown>
+
+  const webPush: {
+    setVapidDetails: typeof setVapidDetails
+    sendNotification: typeof sendNotification
+  }
+  export default webPush
+}

package/src/workflows.test.ts

@@ -0,0 +1,127 @@
+import { describe, it, expect, beforeAll } from "vitest"
+import {
+  registerWorkflows,
+  clearWorkflows,
+  startWorkflow,
+  listWorkflows,
+  devInspectWorkflowRuns,
+  workflowServiceName,
+  type StepContext,
+} from "./workflows.ts"
+
+// Force dev mode before the module's first mode check.
+beforeAll(() => {
+  process.env.VIBES_MODE = "dev"
+})
+
+function entry(name: string, fn: (...args: any[]) => any) {
+  return {
+    name,
+    handler: `test.${name}`,
+    module: "/virtual/test.ts",
+    exportName: name,
+    mod: { [name]: fn },
+  }
+}
+
+async function waitFor(pred: () => boolean, ms = 2000): Promise<void> {
+  const start = Date.now()
+  while (!pred()) {
+    if (Date.now() - start > ms) throw new Error("waitFor timeout")
+    await new Promise((r) => setTimeout(r, 10))
+  }
+}
+
+describe("dev workflow engine", () => {
+  it("runs steps in order and records the run", async () => {
+    clearWorkflows()
+    const order: string[] = []
+    await registerWorkflows([
+      entry("happy", async (step: StepContext, payload: { n: number }) => {
+        const a = await step.run("double", () => payload.n * 2)
+        order.push("after-double")
+        await step.sleep("tiny-nap", 5)
+        const b = await step.run("add-one", () => a + 1)
+        return b
+      }),
+    ])
+
+    const { runId } = await startWorkflow("happy", { n: 20 })
+    expect(runId).toMatch(/^run_dev_/)
+
+    await waitFor(() => {
+      const run = devInspectWorkflowRuns().find((r) => r.id === runId)
+      return run?.status === "done"
+    })
+    const run = devInspectWorkflowRuns().find((r) => r.id === runId)!
+    expect(run.result).toBe(41)
+    expect(run.steps.map((s) => s.name)).toEqual(["double", "tiny-nap", "add-one"])
+    expect(run.steps.every((s) => s.status === "done")).toBe(true)
+    expect(order).toEqual(["after-double"])
+  })
+
+  it("marks the run failed when a step throws", async () => {
+    clearWorkflows()
+    await registerWorkflows([
+      entry("boom", async (step: StepContext) => {
+        await step.run("explode", () => {
+          throw new Error("kaboom")
+        })
+      }),
+    ])
+    const { runId } = await startWorkflow("boom")
+    await waitFor(() => devInspectWorkflowRuns().find((r) => r.id === runId)?.status === "failed")
+    const run = devInspectWorkflowRuns().find((r) => r.id === runId)!
+    expect(run.error).toContain("kaboom")
+    expect(run.steps[0]!.status).toBe("failed")
+  })
+
+  it("dedupes starts with the same idempotency id", async () => {
+    clearWorkflows()
+    let calls = 0
+    await registerWorkflows([
+      entry("once", async (step: StepContext) => {
+        await step.run("count", () => {
+          calls++
+        })
+      }),
+    ])
+    const a = await startWorkflow("once", null, { id: "same-key" })
+    const b = await startWorkflow("once", null, { id: "same-key" })
+    expect(b.runId).toBe(a.runId)
+    await waitFor(() => devInspectWorkflowRuns().find((r) => r.id === a.runId)?.status === "done")
+    expect(calls).toBe(1)
+  })
+
+  it("throws on unknown workflow names", async () => {
+    clearWorkflows()
+    await registerWorkflows([])
+    await expect(startWorkflow("nope")).rejects.toThrow(/unknown workflow/)
+  })
+
+  it("throws on duplicate workflow names at registration", async () => {
+    clearWorkflows()
+    await expect(
+      registerWorkflows([entry("dup", async () => {}), { ...entry("dup", async () => {}), handler: "other.dup" }]),
+    ).rejects.toThrow(/duplicate workflow name/)
+  })
+
+  it("rejects oversized payloads", async () => {
+    clearWorkflows()
+    await registerWorkflows([entry("big", async () => {})])
+    await expect(startWorkflow("big", { blob: "x".repeat(70 * 1024) })).rejects.toThrow(/exceeds/)
+  })
+
+  it("lists registered workflows", async () => {
+    clearWorkflows()
+    await registerWorkflows([entry("wf-one", async () => {})])
+    expect(listWorkflows()).toEqual([{ name: "wf-one", handler: "test.wf-one" }])
+  })
+})
+
+describe("workflowServiceName", () => {
+  it("slug-scopes and underscores dashes (injective on the slug alphabet)", () => {
+    expect(workflowServiceName("my-cool-app")).toBe("wf_my_cool_app")
+    expect(workflowServiceName("plain")).toBe("wf_plain")
+  })
+})

package/src/workflows.ts

@@ -0,0 +1,438 @@
+// Durable workflows for vibes apps.
+//
+// User-facing API:
+//   import { workflow, startWorkflow } from "@omg-dev/server"
+//
+//   export const onboarding = workflow("onboarding", async (step, payload) => {
+//     const profile = await step.run("create-profile", async () => { ... })
+//     await step.sleep("welcome-delay", 24 * 60 * 60 * 1000)
+//     await step.run("send-welcome", async () => { ... })
+//     return { profileId: profile.id }
+//   })
+//
+//   const { runId } = await startWorkflow("onboarding", { userId }, { id: `onb-${userId}` })
+//
+// The determinism contract taught to app authors is exactly one rule:
+// SIDE EFFECTS GO INSIDE step.run(). Code between steps may re-execute on
+// replay and must be cheap + idempotent-by-construction.
+//
+// Runtime modes (same selector as triggers.ts):
+//   - VIBES_MODE=dev: in-process engine. step.run executes immediately,
+//     step.sleep is a setTimeout. NO durability — a dev-server restart loses
+//     in-flight runs. Runs are recorded in a bounded ring surfaced via
+//     /_vibes/inspect/workflows for the dashboard's draft-mode Inspect.
+//   - prod: the Restate engine. Workflow fns are exposed as handlers of a
+//     slug-scoped Restate service mounted at POST /_vibes/workflow/* on this
+//     server; the self-hosted Restate server (control-plane box) journals
+//     every step/sleep and re-invokes through DeployProxy (which wakes a
+//     slept sandbox) until the run completes. step.run/step.sleep map to
+//     ctx.run/ctx.sleep — results are replayed from the journal, never
+//     re-executed. startWorkflow() POSTs to the in-VM agent's
+//     /_workflow/start, which forwards to the orchestrator → Restate
+//     ingress (apps never hold Restate addresses or credentials).
+//
+// The engine boundary is deliberately tiny (see WorkflowEngine in
+// apps/infra/WORKFLOWS.md): a Temporal or own-sqld engine can replace
+// Restate behind the same workflow()/step API without user-code changes.
+
+import path from "node:path"
+import fs from "node:fs"
+import { ctxStore, type VibesCtx } from "./ctx.ts"
+
+// ── Public API ───────────────────────────────────────────────────────────────
+
+export interface StepContext {
+  /**
+   * Execute a side-effecting step durably. The result is journaled: on
+   * replay the recorded result is returned without re-executing `fn`.
+   * `name` must be a stable string (it keys the journal entry on some
+   * engines and labels the step everywhere).
+   */
+  run<T>(name: string, fn: () => T | Promise<T>): Promise<T>
+  /**
+   * Durable sleep. In prod the VM can be reaped while sleeping; the engine
+   * re-invokes (and wakes) the app when the timer fires. `name` labels the
+   * wait for observability.
+   */
+  sleep(name: string, ms: number): Promise<void>
+}
+
+export type WorkflowFn<P = any, R = unknown> = (
+  step: StepContext,
+  payload: P,
+) => Promise<R>
+
+/**
+ * Declare a durable workflow. `name` must be a string literal — the
+ * build-time scanner persists it so the orchestrator can register the
+ * workflow endpoint with the engine. Returns the function unchanged so it
+ * can be invoked directly in tests.
+ */
+export function workflow<P = any, R = unknown>(name: string, fn: WorkflowFn<P, R>): WorkflowFn<P, R> {
+  void name // registration happens at boot from .vibes/workflows.json
+  return fn
+}
+
+export interface StartWorkflowOptions {
+  /**
+   * Idempotency key. Two starts with the same id never create two runs —
+   * the second returns the first run's id. Omit for fire-every-time.
+   */
+  id?: string
+}
+
+/**
+ * Start a workflow run by name. Fire-and-forget: resolves with the run id
+ * as soon as the engine has durably accepted the start, not when the run
+ * completes. Payload is JSON-serialized, capped at 64 KB (same as emit()).
+ */
+export async function startWorkflow(
+  name: string,
+  payload: unknown = null,
+  opts: StartWorkflowOptions = {},
+): Promise<{ runId: string }> {
+  if (!name || typeof name !== "string") {
+    throw new Error("startWorkflow: name required")
+  }
+  const payloadStr = JSON.stringify(payload ?? null)
+  if (payloadStr.length > MAX_WORKFLOW_PAYLOAD_BYTES) {
+    throw new Error(`startWorkflow("${name}"): payload exceeds ${MAX_WORKFLOW_PAYLOAD_BYTES} bytes`)
+  }
+  if (workflowMode() === "dev") {
+    return startInProcess(name, payload, opts)
+  }
+  return startViaAgent(name, payloadStr, opts)
+}
+
+// ── Registry ─────────────────────────────────────────────────────────────────
+
+export interface WorkflowEntry {
+  /** Workflow name — the literal first arg of workflow(). */
+  name: string
+  /** Dispatch identifier "<file-basename>.<exportName>" (parity with triggers). */
+  handler: string
+  module: string
+  exportName: string
+  mod?: Record<string, unknown> // preloaded for prod bundles
+}
+
+interface ResolvedWorkflow {
+  entry: WorkflowEntry
+  fn: WorkflowFn
+}
+
+const workflowRegistry = new Map<string, ResolvedWorkflow>() // name → resolved
+
+export function clearWorkflows(): void {
+  workflowRegistry.clear()
+}
+
+/** Load workflow entries from .vibes/workflows.json (dev boot path). */
+export async function loadWorkflowsFromFile(root: string): Promise<WorkflowEntry[]> {
+  const p = path.join(root, ".vibes", "workflows.json")
+  if (!fs.existsSync(p)) return []
+  try {
+    const parsed = JSON.parse(fs.readFileSync(p, "utf-8")) as WorkflowEntry[]
+    return Array.isArray(parsed) ? parsed : []
+  } catch (err) {
+    console.error("[vibes:workflows] failed to read workflows.json:", err)
+    return []
+  }
+}
+
+/**
+ * Populate the registry. Resolves each workflow fn from the preloaded `mod`
+ * (prod bundle) or via dynamic import (dev). Idempotent — called at boot
+ * and on HMR reload.
+ */
+export async function registerWorkflows(entries: WorkflowEntry[]): Promise<void> {
+  clearWorkflows()
+  for (const e of entries) {
+    let fn: any
+    if (e.mod) {
+      fn = e.mod[e.exportName]
+    } else {
+      try {
+        const mod = await import(e.module)
+        fn = mod[e.exportName]
+      } catch (err) {
+        console.error(`[vibes:workflows] import ${e.module}#${e.exportName} failed:`, err)
+        continue
+      }
+    }
+    if (typeof fn !== "function") {
+      console.error(`[vibes:workflows] ${e.module}#${e.exportName} is not a function — skipping`)
+      continue
+    }
+    if (workflowRegistry.has(e.name)) {
+      // Duplicate workflow names would silently shadow each other in the
+      // engine — fail loud (matches the repo's no-silent-fallback rule).
+      throw new Error(
+        `[vibes:workflows] duplicate workflow name "${e.name}" (${e.handler} vs ${workflowRegistry.get(e.name)!.entry.handler})`,
+      )
+    }
+    workflowRegistry.set(e.name, { entry: e, fn })
+  }
+  if (entries.length > 0) {
+    console.log(`[vibes:workflows] registered ${workflowRegistry.size} workflow(s) — mode=${workflowMode()}`)
+  }
+}
+
+export function listWorkflows(): Array<{ name: string; handler: string }> {
+  return Array.from(workflowRegistry.values()).map(({ entry }) => ({
+    name: entry.name,
+    handler: entry.handler,
+  }))
+}
+
+const MAX_WORKFLOW_PAYLOAD_BYTES = 64 * 1024
+
+// ── Mode detection ───────────────────────────────────────────────────────────
+// Separate copy of vibesMode() (triggers.ts keeps its own private) — same
+// contract: VIBES_MODE=dev set by the vite-plugin, anything else is prod.
+
+let _mode: "dev" | "prod" | null = null
+function workflowMode(): "dev" | "prod" {
+  if (_mode) return _mode
+  const env = (typeof process !== "undefined" ? process.env?.VIBES_MODE : undefined) ?? ""
+  _mode = env === "dev" ? "dev" : "prod"
+  return _mode
+}
+
+// ── Dev engine ───────────────────────────────────────────────────────────────
+// Immediate in-process execution with run/step bookkeeping for Inspect.
+// Deliberately NOT durable: dev sandboxes are ephemeral and HMR reloads
+// would invalidate any journal anyway. The contract (side effects in steps)
+// is still exercised because the same fn runs unchanged in prod.
+
+interface DevWorkflowRun {
+  id: string
+  name: string
+  status: "running" | "done" | "failed"
+  payload: unknown
+  result?: unknown
+  error?: string
+  steps: Array<{
+    name: string
+    kind: "run" | "sleep"
+    status: "running" | "done" | "failed"
+    startedAt: number
+    doneAt?: number
+  }>
+  createdAt: number
+  doneAt?: number
+}
+
+const DEV_RUN_RING = 200
+const recentDevRuns: DevWorkflowRun[] = []
+// Idempotency: id → runId for the dev engine.
+const devIdempotency = new Map<string, string>()
+
+function pushBoundedRun(run: DevWorkflowRun): void {
+  recentDevRuns.unshift(run)
+  if (recentDevRuns.length > DEV_RUN_RING) recentDevRuns.length = DEV_RUN_RING
+}
+
+function devId(): string {
+  return `run_dev_${Date.now()}_${Math.floor(Math.random() * 4096).toString(16)}`
+}
+
+function startInProcess(
+  name: string,
+  payload: unknown,
+  opts: StartWorkflowOptions,
+): { runId: string } {
+  const resolved = workflowRegistry.get(name)
+  if (!resolved) {
+    throw new Error(
+      `startWorkflow("${name}"): unknown workflow — declare it as ` +
+        `\`export const x = workflow("${name}", async (step, payload) => …)\` in functions/`,
+    )
+  }
+  if (opts.id) {
+    const existing = devIdempotency.get(opts.id)
+    if (existing) return { runId: existing }
+  }
+  const run: DevWorkflowRun = {
+    id: devId(),
+    name,
+    status: "running",
+    payload,
+    steps: [],
+    createdAt: Date.now(),
+  }
+  if (opts.id) devIdempotency.set(opts.id, run.id)
+  pushBoundedRun(run)
+
+  const step: StepContext = {
+    async run<T>(stepName: string, fn: () => T | Promise<T>): Promise<T> {
+      const s = { name: stepName, kind: "run" as const, status: "running" as const, startedAt: Date.now() }
+      run.steps.push(s)
+      try {
+        const out = await fn()
+        Object.assign(s, { status: "done", doneAt: Date.now() })
+        return out
+      } catch (err) {
+        Object.assign(s, { status: "failed", doneAt: Date.now() })
+        throw err
+      }
+    },
+    async sleep(stepName: string, ms: number): Promise<void> {
+      const s = { name: stepName, kind: "sleep" as const, status: "running" as const, startedAt: Date.now() }
+      run.steps.push(s)
+      await new Promise<void>((resolve) => setTimeout(resolve, Math.max(0, ms)))
+      Object.assign(s, { status: "done", doneAt: Date.now() })
+    },
+  }
+
+  // Fire-and-forget like prod: startWorkflow resolves immediately; the run
+  // continues in the background under a system ctx (no user identity, same
+  // posture as trigger dispatch).
+  void ctxStore.run({ userId: null, system: true } as VibesCtx, async () => {
+    try {
+      const result = await resolved.fn(step, payload)
+      run.status = "done"
+      run.result = result
+      run.doneAt = Date.now()
+    } catch (err) {
+      run.status = "failed"
+      run.error = err instanceof Error ? err.message : String(err)
+      run.doneAt = Date.now()
+      console.error(`[vibes:workflows] dev run ${name} (${run.id}) failed:`, err)
+    }
+  })
+
+  return { runId: run.id }
+}
+
+/** Dev Inspect accessor — mirrors devInspectDeliveries() in triggers.ts. */
+export function devInspectWorkflowRuns(): DevWorkflowRun[] {
+  return recentDevRuns
+}
+
+// ── Prod engine: Restate ─────────────────────────────────────────────────────
+//
+// The app side is a Restate SDK *fetch* endpoint (request-response mode —
+// works over HTTP/1.1 through CF/DeployProxy, no h2c anywhere) serving one
+// slug-scoped service whose handlers are the registered workflows. The
+// Restate server signs every request with our control-plane identity key;
+// unsigned/foreign requests are rejected, which matters because this is
+// mounted on the app's PUBLIC url.
+//
+// Service naming: `wf_` + slug with `-` → `_`. Slugs are [a-z0-9-] so the
+// mapping is injective; the orchestrator computes the same name when
+// registering the deployment and when starting runs.
+
+// Production public key of the control-plane Restate server (derived from
+// /etc/restate/request-identity.pem — see apps/infra/WORKFLOWS.md). Non-
+// secret. Override with VIBES_WORKFLOW_IDENTITY_KEYS (comma-separated) for
+// self-host installs; set to "insecure" to disable verification entirely
+// (local testing only — never in a deployed app).
+const DEFAULT_IDENTITY_KEYS = ["publickeyv1_9w1Za94FAEiJ2LzArToAt7mCw6B8UnZYS4EQJkqJ1uZM"]
+
+export function workflowServiceName(slug: string): string {
+  return `wf_${slug.replace(/-/g, "_")}`
+}
+
+let restateFetchHandler: ((req: Request) => Promise<Response>) | null = null
+
+/**
+ * Build the Restate endpoint fetch handler for the registered workflows.
+ * Called once at createVibesServer boot in prod when the app declares
+ * workflows. Resolves the slug from VIBES_APP_SLUG (injected by the
+ * orchestrator's startDeployServer) — fails loud when missing, because a
+ * silently mis-named service would strand every run.
+ */
+export async function buildWorkflowEndpoint(): Promise<void> {
+  if (workflowMode() === "dev") return
+  if (workflowRegistry.size === 0) return
+
+  const slug = process.env.VIBES_APP_SLUG ?? ""
+  if (!slug) {
+    throw new Error(
+      "[vibes:workflows] VIBES_APP_SLUG not set but this deploy declares workflows — " +
+        "orchestrator must inject it (startDeployServer). Refusing to boot with a mis-named service.",
+    )
+  }
+
+  const [{ service }, { createEndpointHandler }] = await Promise.all([
+    import("@restatedev/restate-sdk"),
+    import("@restatedev/restate-sdk/fetch"),
+  ])
+
+  const handlers: Record<string, (ctx: any, payload: unknown) => Promise<unknown>> = {}
+  for (const { entry, fn } of workflowRegistry.values()) {
+    handlers[entry.name] = (ctx: any, payload: unknown) =>
+      // Same system ctx posture as trigger dispatch — no user identity.
+      ctxStore.run({ userId: null, system: true } as VibesCtx, () =>
+        fn(makeRestateStepContext(ctx), payload),
+      )
+  }
+
+  const keysEnv = process.env.VIBES_WORKFLOW_IDENTITY_KEYS
+  const identityKeys = keysEnv === "insecure"
+    ? undefined
+    : keysEnv
+      ? keysEnv.split(",").map((s) => s.trim()).filter(Boolean)
+      : DEFAULT_IDENTITY_KEYS
+
+  restateFetchHandler = createEndpointHandler({
+    services: [service({ name: workflowServiceName(slug), handlers })],
+    ...(identityKeys ? { identityKeys } : {}),
+  })
+  console.log(
+    `[vibes:workflows] Restate endpoint ready — service=${workflowServiceName(slug)} ` +
+      `workflows=${workflowRegistry.size} identity=${identityKeys ? "verified" : "INSECURE"}`,
+  )
+}
+
+function makeRestateStepContext(ctx: any): StepContext {
+  return {
+    run<T>(name: string, fn: () => T | Promise<T>): Promise<T> {
+      return ctx.run(name, fn)
+    },
+    sleep(name: string, ms: number): Promise<void> {
+      return ctx.sleep(ms, name)
+    },
+  }
+}
+
+/**
+ * Serve a request under /_vibes/workflow/*. Returns null when no endpoint
+ * is mounted (no workflows, or dev mode — dev runs never go through
+ * Restate). index.ts turns null into a 404.
+ */
+export function handleWorkflowRequest(req: Request): Promise<Response> | null {
+  if (!restateFetchHandler) return null
+  return restateFetchHandler(req)
+}
+
+// ── startWorkflow prod path ──────────────────────────────────────────────────
+// POST to the in-VM agent, which forwards to the orchestrator's
+// /v1/workflows/start (svc-token authed) → Restate ingress. The agent route
+// mirrors /_emit (triggers.ts emitToOrchestrator).
+
+async function startViaAgent(
+  name: string,
+  payloadStr: string,
+  opts: StartWorkflowOptions,
+): Promise<{ runId: string }> {
+  const res = await fetch("http://localhost:8080/_workflow/start", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      workflow: name,
+      payload: JSON.parse(payloadStr),
+      ...(opts.id ? { idempotencyKey: opts.id } : {}),
+    }),
+  })
+  if (!res.ok) {
+    const text = await res.text().catch(() => "")
+    throw new Error(`startWorkflow("${name}") agent ${res.status}: ${text.slice(0, 200)}`)
+  }
+  const body = (await res.json()) as { runId?: string }
+  if (!body.runId) {
+    throw new Error(`startWorkflow("${name}"): agent returned no runId`)
+  }
+  return { runId: body.runId }
+}