@robodev-ai/runtime 0.4.0 → 0.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robodev-ai/runtime",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Robodev project runtime — deploy-file classification, esbuild compile, module loading, schema push, route matching, OpenAPI, handler invocation, Robodev Auth, the socket engine, and local file storage. Shared by hosted Starbase and `robodev dev`.",
   "type": "module",
   "license": "MIT",
@@ -32,7 +32,7 @@
     "pg": "^8.16.3",
     "zod": "^3.25.76",
     "zod-to-json-schema": "^3.24.6",
-    "@robodev-ai/sdk": "0.11.0"
+    "@robodev-ai/sdk": "0.11.1"
   },
   "devDependencies": {
     "@types/busboy": "^1.5.4",

package/src/email-templates.test.ts

@@ -0,0 +1,105 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import {
+  escapeEmailHtml,
+  extractTemplateVars,
+  htmlToPlainText,
+  isCustomEmailSlug,
+  loadLocalEmailTemplate,
+  mergeCustomTemplateVariables,
+  renderEmailFields,
+  renderEmailTemplate,
+  resolveEmailSendInput,
+} from "./email-templates.js";
+
+test("renderEmailTemplate replaces whitespace-tolerant vars", () => {
+  assert.equal(renderEmailTemplate("Hi {{ name }}", { name: "Ada" }), "Hi Ada");
+  assert.equal(renderEmailTemplate("Hi {{name}}", { name: "Ada" }), "Hi Ada");
+  assert.equal(renderEmailTemplate("Hi {{ missing }}", {}), "Hi ");
+  assert.equal(renderEmailTemplate("Hi {{1bad}}", { "1bad": "x" }), "Hi {{1bad}}");
+});
+
+test("renderEmailTemplate HTML-escapes only in html mode", () => {
+  assert.equal(
+    renderEmailTemplate("<p>{{name}}</p>", { name: `<a>"'` }, { html: true }),
+    `<p>${escapeEmailHtml(`<a>"'`)}</p>`,
+  );
+  assert.equal(renderEmailTemplate("{{name}}", { name: "<x>" }), "<x>");
+});
+
+test("extractTemplateVars unions unique names in order", () => {
+  assert.deepEqual(extractTemplateVars("{{email}} {{name}}", "{{email}} {{link}}"), [
+    "email",
+    "name",
+    "link",
+  ]);
+});
+
+test("htmlToPlainText strips tags", () => {
+  assert.equal(htmlToPlainText("<p>Your reset code is <code>123</code>.</p>"), "Your reset code is 123 .");
+});
+
+test("resolveEmailSendInput renders catalog then applies overrides", () => {
+  const resolved = resolveEmailSendInput(
+    {
+      to: "a@b.com",
+      template: "welcome",
+      vars: { name: "Ada" },
+      subject: "Override",
+    },
+    { subject: "Hi {{name}}", html: "<p>Hello {{name}}</p>", text: "Hello {{name}}" },
+  );
+  assert.equal(resolved.subject, "Override");
+  assert.equal(resolved.html, "<p>Hello Ada</p>");
+  assert.equal(resolved.text, "Hello Ada");
+});
+
+test("resolveEmailSendInput throws template_not_found without catalog or body", () => {
+  assert.throws(
+    () => resolveEmailSendInput({ to: "a@b.com", template: "missing" }, null),
+    (error: unknown) => error instanceof Error && error.message === "template_not_found",
+  );
+});
+
+test("loadLocalEmailTemplate reads html plus optional json", async () => {
+  const root = await mkdtemp(join(tmpdir(), "robodev-emails-"));
+  await mkdir(join(root, "robodev", "emails"), { recursive: true });
+  await writeFile(join(root, "robodev", "emails", "welcome.html"), "<p>Hi {{name}}</p>", "utf8");
+  await writeFile(
+    join(root, "robodev", "emails", "welcome.json"),
+    JSON.stringify({ subject: "Hello", text: "Hi {{name}}" }),
+    "utf8",
+  );
+  const loaded = await loadLocalEmailTemplate(root, "welcome");
+  assert.deepEqual(loaded, {
+    slug: "welcome",
+    subject: "Hello",
+    html: "<p>Hi {{name}}</p>",
+    text: "Hi {{name}}",
+  });
+  assert.equal(await loadLocalEmailTemplate(root, "missing"), null);
+});
+
+test("custom slug and variable merge rules", () => {
+  assert.equal(isCustomEmailSlug("welcome"), true);
+  assert.equal(isCustomEmailSlug("auth.welcome"), false);
+  assert.equal(isCustomEmailSlug("Welcome"), false);
+  assert.deepEqual(mergeCustomTemplateVariables(["email", "name"], ["extra", "email", "1bad"]), [
+    "email",
+    "name",
+    "extra",
+  ]);
+});
+
+test("renderEmailFields derives plaintext when text is empty", () => {
+  const rendered = renderEmailFields(
+    { subject: "Hi {{name}}", html: "<p>Hello {{name}}</p>", text: "" },
+    { name: "Ada" },
+  );
+  assert.equal(rendered.subject, "Hi Ada");
+  assert.equal(rendered.html, "<p>Hello Ada</p>");
+  assert.equal(rendered.text, "Hello Ada");
+});

package/src/email-templates.ts

@@ -0,0 +1,169 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { EmailSendInput } from "@robodev-ai/sdk";
+
+export const EMAIL_TEMPLATE_VAR_RE = /\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g;
+export const EMAIL_TEMPLATE_VAR_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+export const EMAIL_TEMPLATE_MAX_VARS = 32;
+export const EMAIL_TEMPLATE_MAX_VAR_NAME = 40;
+export const EMAIL_TEMPLATE_MAX_BYTES = 200 * 1024;
+export const EMAIL_TEMPLATE_MAX_SUBJECT = 200;
+export const EMAIL_TEMPLATE_MAX_CUSTOM = 40;
+export const CUSTOM_EMAIL_SLUG_RE = /^[a-z][a-z0-9-]{0,62}$/;
+
+export const SYSTEM_EMAIL_SLUGS = ["auth.welcome", "auth.magic-link", "auth.forgot-password"] as const;
+export type SystemEmailSlug = (typeof SYSTEM_EMAIL_SLUGS)[number];
+
+export type EmailTemplateKind = "system" | "custom";
+
+export type LocalEmailTemplate = {
+  slug: string;
+  subject: string;
+  html: string;
+  text: string;
+};
+
+export type EmailTemplateVars = Record<string, string | number | boolean>;
+
+export function isSystemEmailSlug(slug: string): slug is SystemEmailSlug {
+  return (SYSTEM_EMAIL_SLUGS as readonly string[]).includes(slug);
+}
+
+export function isCustomEmailSlug(slug: string): boolean {
+  return CUSTOM_EMAIL_SLUG_RE.test(slug) && !slug.startsWith("auth.");
+}
+
+export function escapeEmailHtml(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+}
+
+export function htmlToPlainText(html: string): string {
+  return html
+    .replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, " ")
+    .replace(/<style\b[^<]*(?:(?!<\/style>)<[^<]*)*<\/style>/gi, " ")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/&nbsp;/gi, " ")
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+export function extractTemplateVars(...parts: Array<string | null | undefined>): string[] {
+  const names: string[] = [];
+  const seen = new Set<string>();
+  for (const part of parts) {
+    if (!part) continue;
+    const re = new RegExp(EMAIL_TEMPLATE_VAR_RE.source, "g");
+    for (const match of part.matchAll(re)) {
+      const name = match[1] ?? "";
+      if (!name || seen.has(name)) continue;
+      seen.add(name);
+      names.push(name);
+    }
+  }
+  return names;
+}
+
+export function renderEmailTemplate(
+  template: string,
+  vars: EmailTemplateVars = {},
+  options: { html?: boolean } = {},
+): string {
+  return template.replace(EMAIL_TEMPLATE_VAR_RE, (token, name: string) => {
+    if (!Object.prototype.hasOwnProperty.call(vars, name)) return "";
+    const raw = vars[name];
+    const value = raw == null ? "" : String(raw);
+    return options.html ? escapeEmailHtml(value) : value;
+  });
+}
+
+export function renderEmailFields(
+  input: { subject: string; html: string; text?: string },
+  vars: EmailTemplateVars = {},
+): { subject: string; html: string; text: string } {
+  const html = renderEmailTemplate(input.html, vars, { html: true });
+  const textSource = input.text?.trim()
+    ? renderEmailTemplate(input.text, vars)
+    : htmlToPlainText(html);
+  return {
+    subject: renderEmailTemplate(input.subject, vars),
+    html,
+    text: textSource,
+  };
+}
+
+export function localEmailTemplatePaths(slug: string): { html: string; json: string } {
+  return {
+    html: `robodev/emails/${slug}.html`,
+    json: `robodev/emails/${slug}.json`,
+  };
+}
+
+export async function loadLocalEmailTemplate(
+  projectRoot: string,
+  slug: string,
+): Promise<LocalEmailTemplate | null> {
+  const paths = localEmailTemplatePaths(slug);
+  let html: string;
+  try {
+    html = await readFile(join(projectRoot, paths.html), "utf8");
+  } catch {
+    return null;
+  }
+  let subject = "";
+  let text = "";
+  try {
+    const raw = await readFile(join(projectRoot, paths.json), "utf8");
+    const parsed = JSON.parse(raw) as { subject?: unknown; text?: unknown };
+    if (typeof parsed.subject === "string") subject = parsed.subject;
+    if (typeof parsed.text === "string") text = parsed.text;
+  } catch {
+    /* html-only catalog row */
+  }
+  return { slug, subject, html, text };
+}
+
+export function resolveEmailSendInput(
+  input: EmailSendInput,
+  catalog: { subject: string; html: string; text?: string } | null,
+): EmailSendInput {
+  if (!input.template) return input;
+  if (!catalog) {
+    if (input.html || input.text) return input;
+    throw Object.assign(new Error("template_not_found"), { code: "template_not_found" });
+  }
+  const rendered = renderEmailFields(catalog, input.vars ?? {});
+  return {
+    ...input,
+    subject: input.subject ?? rendered.subject,
+    html: input.html ?? rendered.html,
+    text: input.text ?? rendered.text,
+  };
+}
+
+export function mergeCustomTemplateVariables(
+  extracted: readonly string[],
+  extras: readonly string[] = [],
+): string[] {
+  const names: string[] = [];
+  const seen = new Set<string>();
+  for (const name of [...extracted, ...extras]) {
+    if (!EMAIL_TEMPLATE_VAR_NAME_RE.test(name) || name.length > EMAIL_TEMPLATE_MAX_VAR_NAME) {
+      continue;
+    }
+    if (seen.has(name)) continue;
+    seen.add(name);
+    names.push(name);
+    if (names.length >= EMAIL_TEMPLATE_MAX_VARS) break;
+  }
+  return names;
+}

package/src/index.ts

@@ -2,7 +2,8 @@
  * `@robodev-ai/runtime` — the project runtime shared by hosted Starbase deploys and the
  * offline `robodev dev` loop: deploy-file classification, the esbuild compile, module
  * loading, schema push, route matching, OpenAPI, handler invocation, Robodev Auth,
- * the socket engine, local file storage, and the offline `robodev dev` jobs engine.
+ * the socket engine, local file storage, the offline `robodev dev` jobs engine,
+ * and email template rendering.
  */
 
 export {
@@ -218,6 +219,7 @@ export {
   ensureJobsSchema,
   type JobsQueryable,
   type LocalCronRow,
+  type LocalJobFinishedEvent,
   type LocalJobRow,
   type LocalJobStatus,
   type LocalJobsEngine,
@@ -278,6 +280,33 @@ export {
   type StorageQueryable,
 } from "./local-storage.js";
 
+export {
+  CUSTOM_EMAIL_SLUG_RE,
+  EMAIL_TEMPLATE_MAX_BYTES,
+  EMAIL_TEMPLATE_MAX_CUSTOM,
+  EMAIL_TEMPLATE_MAX_SUBJECT,
+  EMAIL_TEMPLATE_MAX_VAR_NAME,
+  EMAIL_TEMPLATE_MAX_VARS,
+  EMAIL_TEMPLATE_VAR_NAME_RE,
+  EMAIL_TEMPLATE_VAR_RE,
+  SYSTEM_EMAIL_SLUGS,
+  escapeEmailHtml,
+  extractTemplateVars,
+  htmlToPlainText,
+  isCustomEmailSlug,
+  isSystemEmailSlug,
+  loadLocalEmailTemplate,
+  localEmailTemplatePaths,
+  mergeCustomTemplateVariables,
+  renderEmailFields,
+  renderEmailTemplate,
+  resolveEmailSendInput,
+  type EmailTemplateKind,
+  type EmailTemplateVars,
+  type LocalEmailTemplate,
+  type SystemEmailSlug,
+} from "./email-templates.js";
+
 export {
   LOCAL_DEV_IDENTITY_AUD,
   LOCAL_DEV_IDENTITY_TYP,

package/src/local-jobs.test.ts

@@ -10,7 +10,9 @@ import {
   ensureJobsSchema,
   type JobsQueryable,
   type LocalCronRow,
+  type LocalJobFinishedEvent,
   type LocalJobRow,
+  type LocalJobsEngineOptions,
   type LocalJobsGeneration,
 } from "./local-jobs.js";
 
@@ -208,6 +210,7 @@ function engineFor(
   store: ReturnType<typeof memoryJobs>,
   jobs: LocalJobsGeneration["jobs"],
   logs: string[] = [],
+  onJobFinished?: LocalJobsEngineOptions["onJobFinished"],
 ) {
   const generation: LocalJobsGeneration = { db: {} as RobodevDb, jobs };
   return createLocalJobsEngine({
@@ -215,6 +218,7 @@ function engineFor(
     getGeneration: () => generation,
     log: (line) => logs.push(line),
     clients: mockClients,
+    onJobFinished,
   });
 }
 
@@ -465,3 +469,73 @@ test("start resets running rows; stop clears timers", async () => {
   assert.equal(engine.running, false);
   await engine.stop();
 });
+
+test("onJobFinished fires once per finishJob for succeeded, failed-retry, and dead", async () => {
+  const succeeded: LocalJobFinishedEvent[] = [];
+  const okStore = memoryJobs();
+  const ok = engineFor(okStore, [{ name: "digest", def: jobDef(() => undefined) }], [], (event) =>
+    succeeded.push(event),
+  );
+  await ok.enqueue({ name: "digest", payload: { n: 1 } });
+  await ok.tickJobs();
+  await waitUntil(() => succeeded.length === 1);
+  assert.equal(succeeded.length, 1);
+  assert.equal(succeeded[0]?.outcome, "succeeded");
+  assert.equal(succeeded[0]?.engineStatus, "succeeded");
+  assert.equal(succeeded[0]?.error, null);
+  assert.equal(succeeded[0]?.name, "digest");
+  assert.deepEqual(succeeded[0]?.payload, { n: 1 });
+
+  const retried: LocalJobFinishedEvent[] = [];
+  const retryStore = memoryJobs();
+  const retry = engineFor(
+    retryStore,
+    [
+      {
+        name: "digest",
+        def: jobDef(() => {
+          throw new Error("boom");
+        }),
+      },
+    ],
+    [],
+    (event) => retried.push(event),
+  );
+  await retry.enqueue({ name: "digest", payload: { n: 2 } });
+  await retry.tickJobs();
+  await waitUntil(() => retried.length === 1);
+  assert.equal(retried.length, 1);
+  assert.equal(retried[0]?.outcome, "failed");
+  assert.equal(retried[0]?.engineStatus, "queued");
+  assert.equal(retried[0]?.error, "boom");
+  assert.equal(retried[0]?.attempts, 1);
+  assert.deepEqual(retried[0]?.payload, { n: 2 });
+
+  const finished: LocalJobFinishedEvent[] = [];
+  const deadStore = memoryJobs();
+  const dying = engineFor(
+    deadStore,
+    [
+      {
+        name: "digest",
+        def: jobDef(() => {
+          throw new Error("boom");
+        }),
+      },
+    ],
+    [],
+    (event) => finished.push(event),
+  );
+  await dying.enqueue({ name: "digest" });
+  for (let attempt = 1; attempt <= JOB_MAX_ATTEMPTS; attempt++) {
+    deadStore.jobs[0]!.run_at = new Date(0);
+    deadStore.jobs[0]!.status = "queued";
+    await dying.tickJobs();
+    await waitUntil(() => finished.length === attempt);
+  }
+  assert.equal(finished.length, JOB_MAX_ATTEMPTS);
+  assert.equal(finished.at(-1)?.outcome, "failed");
+  assert.equal(finished.at(-1)?.engineStatus, "dead");
+  assert.equal(finished.at(-1)?.attempts, JOB_MAX_ATTEMPTS);
+  assert.equal(finished.at(-1)?.error, "boom");
+});

package/src/local-jobs.ts

@@ -49,11 +49,23 @@ export type LocalJobsGeneration = {
   jobs: readonly { name: string; file?: string; def: JobDefinition }[];
 };
 
+export type LocalJobFinishedEvent = {
+  id: string;
+  name: string;
+  payload: unknown;
+  outcome: "succeeded" | "failed";
+  engineStatus: "succeeded" | "queued" | "dead";
+  attempts: number;
+  error: string | null;
+};
+
 export type LocalJobsEngineOptions = {
   query: JobsQueryable["query"];
   getGeneration: () => LocalJobsGeneration | null;
   log?: (line: string) => void;
   clients: () => RouteClients;
+  /** Invoked after the job row UPDATE. Failed-retry (`queued`) and `dead` both report `failed`. */
+  onJobFinished?: (event: LocalJobFinishedEvent) => void;
 };
 
 export type LocalJobsEngine = {
@@ -221,6 +233,8 @@ export function createLocalJobsEngine(options: LocalJobsEngineOptions): LocalJob
   }
 
   async function finishJob(row: LocalJobRow, error: string | null): Promise<void> {
+    let engineStatus: LocalJobFinishedEvent["engineStatus"];
+    let attempts = row.attempts;
     if (!error) {
       await query(
         `UPDATE robodev_jobs.jobs
@@ -229,21 +243,38 @@ export function createLocalJobsEngine(options: LocalJobsEngineOptions): LocalJob
         [row.id],
       );
       log(`  ${row.name} succeeded`);
-      return;
-    }
-    const attempts = row.attempts + 1;
-    const next = nextJobFailureState(attempts);
-    await query(
-      `UPDATE robodev_jobs.jobs
-       SET status = $2, attempts = $3, last_error = $4, run_at = COALESCE($5, run_at), updated_at = now()
-       WHERE id = $1`,
-      [row.id, next.status, attempts, error, next.runAt],
-    );
-    if (next.status === "dead") {
-      log(`  ${row.name} dead: ${shortError(error)}`);
+      engineStatus = "succeeded";
     } else {
-      log(`  ${row.name} failed attempt ${attempts}/${JOB_MAX_ATTEMPTS}: ${shortError(error)}`);
+      attempts = row.attempts + 1;
+      const next = nextJobFailureState(attempts);
+      await query(
+        `UPDATE robodev_jobs.jobs
+         SET status = $2, attempts = $3, last_error = $4, run_at = COALESCE($5, run_at), updated_at = now()
+         WHERE id = $1`,
+        [row.id, next.status, attempts, error, next.runAt],
+      );
+      engineStatus = next.status;
+      if (next.status === "dead") {
+        log(`  ${row.name} dead: ${shortError(error)}`);
+      } else {
+        log(`  ${row.name} failed attempt ${attempts}/${JOB_MAX_ATTEMPTS}: ${shortError(error)}`);
+      }
+    }
+    let payload: unknown = null;
+    try {
+      payload = JSON.parse(row.payload_json) as unknown;
+    } catch {
+      payload = null;
     }
+    options.onJobFinished?.({
+      id: row.id,
+      name: row.name,
+      payload,
+      outcome: error ? "failed" : "succeeded",
+      engineStatus,
+      attempts,
+      error,
+    });
   }
 
   async function runClaimedJob(