@omg-dev/server 0.4.24

package/src/test/trigger-scan.test.ts

@@ -0,0 +1,78 @@
+// Trigger scanner (moved from vite-plugin) + cron driver selection.
+
+import { describe, test, expect, afterEach } from "bun:test"
+import fs from "node:fs"
+import os from "node:os"
+import path from "node:path"
+import { extractTriggers, scanTriggers, writeTriggersManifest, TriggerScanError } from "../trigger-scan.ts"
+import { setCronDriver } from "../triggers.ts"
+
+const tmpRoots: string[] = []
+function makeRoot(files: Record<string, string>): string {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "vibes-trigger-scan-"))
+  tmpRoots.push(root)
+  fs.mkdirSync(path.join(root, "functions"), { recursive: true })
+  for (const [name, source] of Object.entries(files)) {
+    fs.writeFileSync(path.join(root, "functions", name), source, "utf-8")
+  }
+  return root
+}
+
+afterEach(() => {
+  for (const root of tmpRoots.splice(0)) {
+    fs.rmSync(root, { recursive: true, force: true })
+  }
+  // Reset to default so driver state doesn't leak across tests.
+  setCronDriver("orchestrator")
+})
+
+describe("extractTriggers", () => {
+  test("detects exported cron() and on() with literal first args", () => {
+    const src = [
+      `export const purge = cron("0 3 * * *", async () => {})`,
+      `export const welcome = on('user.signup', async (_ctx, p) => {})`,
+    ].join("\n")
+    const out = extractTriggers(src, "/x/cleanup.ts", "cleanup")
+    expect(out).toEqual([
+      expect.objectContaining({ handler: "cleanup.purge", kind: "cron", key: "0 3 * * *" }),
+      expect.objectContaining({ handler: "cleanup.welcome", kind: "on", key: "user.signup" }),
+    ])
+  })
+
+  test("throws loudly on a non-literal schedule", () => {
+    expect(() =>
+      extractTriggers(`export const p = cron(SCHEDULE, async () => {})`, "/x/a.ts", "a"),
+    ).toThrow(TriggerScanError)
+  })
+})
+
+describe("writeTriggersManifest", () => {
+  test("scans functions/ and writes .vibes/triggers.json", async () => {
+    const root = makeRoot({
+      "jobs.ts": `import { cron } from "@omg-dev/server"\nexport const tick = cron("*/10 * * * *", async () => {})\n`,
+    })
+    const written = await writeTriggersManifest(root)
+    expect(written.length).toBe(1)
+    const onDisk = JSON.parse(fs.readFileSync(path.join(root, ".vibes", "triggers.json"), "utf-8"))
+    expect(onDisk[0]).toMatchObject({ handler: "jobs.tick", kind: "cron", key: "*/10 * * * *" })
+    // Matches what scanTriggers returns directly.
+    expect(await scanTriggers(root)).toEqual(written)
+  })
+
+  test("no functions/ dir → empty manifest, no throw", async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "vibes-trigger-scan-"))
+    tmpRoots.push(root)
+    expect(await writeTriggersManifest(root)).toEqual([])
+  })
+})
+
+describe("setCronDriver", () => {
+  test("accepts the two known drivers", () => {
+    setCronDriver("in-process")
+    setCronDriver("orchestrator")
+  })
+
+  test("fails loud on anything else", () => {
+    expect(() => setCronDriver("inprocess" as never)).toThrow(/unknown cron driver/)
+  })
+})

package/src/trigger-scan.ts

@@ -0,0 +1,173 @@
+// Trigger scanner — detects `cron("…", fn)` and `on("…", fn)` call sites in
+// functions/*.ts and emits a registry consumed by @omg-dev/server's in-process
+// scheduler (dev) and the orchestrator's cron+event queue (prod).
+//
+// Lives in @omg-dev/server (moved from @omg-dev/vite-plugin) so non-vite hosts —
+// the control-plane container, self-host single-container bundles — can scan
+// + write .vibes/triggers.json at boot; the vite-plugin re-imports it from
+// here for the build-time path. Pure node:fs/path, no vite dependency.
+//
+// Convention: a trigger MUST be declared as a top-level export:
+//
+//   export const purge = cron("0 3 * * *", async (ctx) => { ... })
+//   export const welcome = on("user.signup", async (ctx, payload) => { ... })
+//
+// The first argument must be a *string literal* — dynamic schedules / topics
+// can't be persisted ahead of time. We fail the build loudly when we detect
+// a non-literal first arg so the user can't silently lose a trigger.
+//
+// Scanner shape mirrors scanner.ts (regex + walk). For correctness we use a
+// stricter export-binding regex that also captures the call expression.
+
+import fs from "node:fs"
+import path from "node:path"
+
+export type TriggerKind = "cron" | "on" | "storage:upload" | "storage:delete"
+
+export interface ScannedTrigger {
+  /** Dispatch identifier: "<file-basename>.<exportName>" e.g. "cleanup.purge". */
+  handler: string
+  kind: TriggerKind
+  /** Cron expression (kind=cron) or topic string (kind=on). */
+  key: string
+  /** Absolute file path of the function module (for dev import). */
+  module: string
+  /** Exported binding name inside the module. */
+  exportName: string
+}
+
+/** scanTriggers walks `<root>/functions/` and returns every detected trigger. */
+export async function scanTriggers(root: string): Promise<ScannedTrigger[]> {
+  const fnDir = path.join(root, "functions")
+  if (!fs.existsSync(fnDir)) return []
+
+  const out: ScannedTrigger[] = []
+  walk(fnDir, out)
+  // Also recurse into functions/api/ — same convention as scanner.ts.
+  const apiDir = path.join(fnDir, "api")
+  if (fs.existsSync(apiDir) && fs.statSync(apiDir).isDirectory()) {
+    walk(apiDir, out)
+  }
+  return out
+}
+
+function walk(dir: string, out: ScannedTrigger[]): void {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) continue
+    if (!entry.name.endsWith(".ts") || entry.name.endsWith(".d.ts")) continue
+    const filePath = path.join(dir, entry.name)
+    const source = fs.readFileSync(filePath, "utf-8")
+    const basename = path.basename(entry.name, ".ts")
+    out.push(...extractTriggers(source, filePath, basename))
+  }
+}
+
+// ── Regex extraction ─────────────────────────────────────────────────────────
+//
+// Match either:
+//   export const NAME = cron("SCHEDULE", ...)
+//   export const NAME = on("TOPIC", ...)
+//   export const NAME: SomeType = cron(...)   ← type annotation tolerated
+//
+// We rely on the cron/on call appearing on the same line as the export
+// declaration. Multi-line literal-string-then-call is rare; if we miss it,
+// the orchestrator simply doesn't fire the trigger — the build still
+// succeeds (no silent data corruption). For clearer detection of mis-declared
+// triggers we also scan for the call-site without `export const` prefix and
+// emit a structured error.
+
+const EXPORT_TRIGGER_RE = /^export\s+const\s+(\w+)\s*(?::\s*[^=]+)?\s*=\s*(cron|on)\s*\(\s*(.+?)\s*,/gm
+
+// `storage.onUpload(handler)` / `storage.onDelete(handler)` have no first-arg
+// literal — the "key" is implicit (file uploads vs deletes for this app). We
+// emit them with an empty key string; the dispatcher treats matching by kind
+// rather than (kind, key).
+const EXPORT_STORAGE_HOOK_RE = /^export\s+const\s+(\w+)\s*(?::\s*[^=]+)?\s*=\s*storage\.(onUpload|onDelete)\s*\(/gm
+
+// Detect a `cron(…` or `on(…` call that isn't bound to a top-level export.
+// Used to surface helpful errors ("declare as `export const`...").
+const ORPHAN_TRIGGER_RE = /(?<!export\s+const\s+\w+\s*=\s*)\b(cron|on)\s*\(/g
+
+export class TriggerScanError extends Error {
+  constructor(public file: string, public detail: string) {
+    super(`[vibes:triggers] ${file}: ${detail}`)
+    this.name = "TriggerScanError"
+  }
+}
+
+export function extractTriggers(source: string, filePath: string, basename: string): ScannedTrigger[] {
+  const out: ScannedTrigger[] = []
+  // Strip line + block comments so trigger-shaped strings inside `// cron(...)`
+  // comments don't get picked up. Simple regex pass — good enough for the
+  // patterns we expect.
+  const stripped = source
+    .replace(/\/\/.*$/gm, "")
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+
+  let m: RegExpExecArray | null
+  EXPORT_TRIGGER_RE.lastIndex = 0
+  while ((m = EXPORT_TRIGGER_RE.exec(stripped)) !== null) {
+    const [, exportName, kind, firstArg] = m
+    const lit = parseStringLiteral(firstArg!)
+    if (lit === null) {
+      throw new TriggerScanError(
+        filePath,
+        `${kind}() first arg must be a string literal — got: ${firstArg!.slice(0, 60)}`,
+      )
+    }
+    out.push({
+      handler: `${basename}.${exportName!}`,
+      kind: kind as TriggerKind,
+      key: lit,
+      module: filePath,
+      exportName: exportName!,
+    })
+  }
+  // storage.onUpload(...) / storage.onDelete(...) — no string literal key.
+  EXPORT_STORAGE_HOOK_RE.lastIndex = 0
+  while ((m = EXPORT_STORAGE_HOOK_RE.exec(stripped)) !== null) {
+    const [, exportName, hookName] = m
+    out.push({
+      handler: `${basename}.${exportName!}`,
+      kind: hookName === "onUpload" ? "storage:upload" : "storage:delete",
+      key: "", // not used for storage hooks; dispatcher matches by kind
+      module: filePath,
+      exportName: exportName!,
+    })
+  }
+  return out
+}
+
+/**
+ * Parse a single-line first-arg into a string literal. Returns null when the
+ * input isn't a plain "..." or '...' literal (e.g. it's a template literal, a
+ * variable reference, or a runtime expression).
+ */
+function parseStringLiteral(raw: string): string | null {
+  const trimmed = raw.trim()
+  if (trimmed.length < 2) return null
+  const first = trimmed[0]
+  if ((first === '"' || first === "'") && trimmed.endsWith(first)) {
+    // Disallow embedded interpolation just in case.
+    const inner = trimmed.slice(1, -1)
+    if (inner.includes("${")) return null
+    // Unescape \" and \\ — we don't need full JSON unescaping here.
+    return inner.replace(/\\(.)/g, "$1")
+  }
+  return null
+}
+
+/**
+ * Scan `<root>/functions/` and write the result to `<root>/.vibes/triggers.json`
+ * — the file `createVibesServer` loads at boot when no bundled `triggers`
+ * array is passed. For hosts without a vite build (control-plane container,
+ * self-host bundles): call this before `createVibesServer` so cron()/on()
+ * declarations in functions/*.ts actually register.
+ */
+export async function writeTriggersManifest(root: string): Promise<ScannedTrigger[]> {
+  const triggers = await scanTriggers(root)
+  const vibesDir = path.join(root, ".vibes")
+  fs.mkdirSync(vibesDir, { recursive: true })
+  fs.writeFileSync(path.join(vibesDir, "triggers.json"), JSON.stringify(triggers, null, 2), "utf-8")
+  return triggers
+}