@robodev-ai/runtime 0.1.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robodev-ai/runtime",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Robodev project runtime — deploy-file classification, esbuild compile, module loading, schema push, route matching, OpenAPI, handler invocation, and Robodev Auth. 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.10.0"
+    "@robodev-ai/sdk": "0.11.0"
   },
   "devDependencies": {
     "@types/busboy": "^1.5.4",

package/src/auth-core.ts

@@ -267,3 +267,52 @@ export async function revokeRefresh(db: AuthQueryable, refreshToken: string): Pr
     hashToken(refreshToken),
   ]);
 }
+
+export type GoogleUpsertResult =
+  | { user: AuthRow; created: boolean; updated: boolean; previousName?: string | null }
+  | "signup_disabled";
+
+export async function upsertGoogleUser(
+  pool: AuthQueryable,
+  input: { email: string; name: string | null; subject: string },
+  options: { allowSignups: boolean } = { allowSignups: true },
+): Promise<GoogleUpsertResult> {
+  await ensureAuthSchema(pool);
+  const email = input.email.toLowerCase();
+  const existing = await pool.query<AuthRow>(
+    `SELECT id, email, password_hash, name, google_subject FROM robodev_auth.users WHERE email = $1`,
+    [email],
+  );
+  const row = existing.rows[0];
+  if (row) {
+    const previousName = row.name;
+    const nextName = input.name && input.name !== row.name ? input.name : row.name;
+    if (nextName !== row.name || row.google_subject !== input.subject) {
+      await pool.query(
+        `UPDATE robodev_auth.users SET name = $1, google_subject = $2 WHERE id = $3`,
+        [nextName, input.subject, row.id],
+      );
+      return {
+        user: { ...row, name: nextName, google_subject: input.subject },
+        created: false,
+        updated: true,
+        previousName,
+      };
+    }
+    return { user: row, created: false, updated: false };
+  }
+  if (!options.allowSignups) return "signup_disabled";
+  const created: AuthRow = {
+    id: id("usr"),
+    email,
+    password_hash: null,
+    name: input.name,
+    google_subject: input.subject,
+  };
+  await pool.query(
+    `INSERT INTO robodev_auth.users (id, email, password_hash, name, google_subject)
+     VALUES ($1, $2, $3, $4, $5)`,
+    [created.id, created.email, created.password_hash, created.name, created.google_subject],
+  );
+  return { user: created, created: true, updated: false };
+}

package/src/cron.test.ts

@@ -0,0 +1,19 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { nextRunAfter, parseCron } from "./cron.js";
+
+test("* * * * * is the next minute", () => {
+  const from = new Date(Date.UTC(2026, 0, 1, 12, 0, 30));
+  assert.deepEqual(nextRunAfter("* * * * *", from), new Date(Date.UTC(2026, 0, 1, 12, 1, 0)));
+});
+
+test("0 0 * * * is the next midnight", () => {
+  const from = new Date(Date.UTC(2026, 0, 1, 12, 30, 0));
+  assert.deepEqual(nextRunAfter("0 0 * * *", from), new Date(Date.UTC(2026, 0, 2, 0, 0, 0)));
+});
+
+test("rejects 6-field and invalid expressions", () => {
+  assert.throws(() => parseCron("* * * * * *"), /exactly 5 fields/);
+  assert.throws(() => parseCron("not-cron"), /exactly 5 fields/);
+  assert.throws(() => parseCron("60 * * * *"), /invalid cron field/);
+});

package/src/cron.ts

@@ -0,0 +1,86 @@
+const FIELD_RANGES = [
+  { min: 0, max: 59 },
+  { min: 0, max: 23 },
+  { min: 1, max: 31 },
+  { min: 1, max: 12 },
+  { min: 0, max: 7 },
+] as const;
+
+export type CronFields = [Set<number>, Set<number>, Set<number>, Set<number>, Set<number>];
+
+function expandField(field: string, min: number, max: number): Set<number> {
+  const values = new Set<number>();
+  for (const part of field.split(",")) {
+    const [rangePart, stepPart] = part.split("/");
+    const step = stepPart ? Number(stepPart) : 1;
+    if (!Number.isInteger(step) || step < 1) {
+      throw new Error("invalid cron field");
+    }
+    let start = min;
+    let end = max;
+    if (rangePart && rangePart !== "*") {
+      if (rangePart.includes("-")) {
+        const [fromRaw, toRaw] = rangePart.split("-");
+        start = Number(fromRaw);
+        end = Number(toRaw);
+      } else {
+        start = Number(rangePart);
+        end = start;
+      }
+    }
+    if (
+      !Number.isInteger(start) ||
+      !Number.isInteger(end) ||
+      start < min ||
+      end > max ||
+      start > end
+    ) {
+      throw new Error("invalid cron field");
+    }
+    for (let value = start; value <= end; value += step) {
+      values.add(value);
+    }
+  }
+  if (max === 7 && values.has(7)) values.add(0);
+  return values;
+}
+
+export function parseCron(expr: string): CronFields {
+  const fields = expr.trim().split(/\s+/);
+  if (fields.length !== 5) {
+    throw new Error("cron must have exactly 5 fields");
+  }
+  return FIELD_RANGES.map((range, index) =>
+    expandField(fields[index] ?? "", range.min, range.max),
+  ) as CronFields;
+}
+
+function matches(date: Date, fields: CronFields): boolean {
+  const [minutes, hours, days, months, weekdays] = fields;
+  const dow = date.getUTCDay();
+  return (
+    minutes.has(date.getUTCMinutes()) &&
+    hours.has(date.getUTCHours()) &&
+    days.has(date.getUTCDate()) &&
+    months.has(date.getUTCMonth() + 1) &&
+    (weekdays.has(dow) || (dow === 0 && weekdays.has(7)))
+  );
+}
+
+export function nextRunAfter(expr: string, from: Date): Date {
+  const fields = parseCron(expr);
+  const cursor = new Date(from.getTime());
+  cursor.setUTCSeconds(0, 0);
+  cursor.setUTCMinutes(cursor.getUTCMinutes() + 1);
+  const limit = cursor.getTime() + 366 * 24 * 60 * 60 * 1000;
+  while (cursor.getTime() <= limit) {
+    if (matches(cursor, fields)) return new Date(cursor);
+    cursor.setUTCMinutes(cursor.getUTCMinutes() + 1);
+  }
+  throw new Error("could not find next cron run");
+}
+
+export function assertFiveFieldCron(expr: string): string {
+  parseCron(expr);
+  return expr.trim();
+}

package/src/index.ts

@@ -1,7 +1,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, and Robodev Auth.
+ * loading, schema push, route matching, OpenAPI, handler invocation, Robodev Auth,
+ * and the offline `robodev dev` jobs engine.
  */
 
 export {
@@ -165,8 +166,10 @@ export {
   toAuthUser,
   updateUserPassword,
   updateUserProfile,
+  upsertGoogleUser,
   type AuthQueryable,
   type AuthRow,
+  type GoogleUpsertResult,
   type NonceType,
 } from "./auth-core.js";
 
@@ -193,3 +196,48 @@ export {
   type LocalAuthRequest,
   type LocalAuthResult,
 } from "./local-auth.js";
+
+export { assertFiveFieldCron, nextRunAfter, parseCron, type CronFields } from "./cron.js";
+
+export {
+  JOB_CONCURRENCY,
+  JOB_MAX_ATTEMPTS,
+  JOB_PAYLOAD_MAX_BYTES,
+  assertJobCrons,
+  assertKnownJob,
+  jobBackoffMs,
+  nextJobFailureState,
+  serializeJobPayload,
+  type JobCronDefinition,
+} from "./job-queue.js";
+
+export {
+  LOCAL_JOB_CRON_MS,
+  LOCAL_JOB_WORKER_MS,
+  createLocalJobsEngine,
+  ensureJobsSchema,
+  type JobsQueryable,
+  type LocalCronRow,
+  type LocalJobRow,
+  type LocalJobStatus,
+  type LocalJobsEngine,
+  type LocalJobsEngineOptions,
+  type LocalJobsGeneration,
+} from "./local-jobs.js";
+
+export {
+  LOCAL_DEV_IDENTITY_AUD,
+  LOCAL_DEV_IDENTITY_TYP,
+  assertLocalAppRedirectUri,
+  assertLocalBrokerRedirectUri,
+  brokerDevStartUrl,
+  exchangeLocalGoogleCode,
+  localGoogleAuthorizeUrl,
+  localGoogleCallbackUri,
+  projectGoogleOverrideMode,
+  redirectWithQuery,
+  resetLocalDevAssertionReplayForTests,
+  signLocalGoogleState,
+  verifyLocalDevIdentityAssertion,
+  verifyLocalGoogleState,
+} from "./local-google.js";

package/src/invoke.ts

@@ -56,9 +56,6 @@ export type RunRouteInput = {
   resolveUser: (authorization?: string) => Promise<AuthUser | null>;
   /** Built after auth passes, right before the handler runs. */
   clients: () => Promise<RouteClients> | RouteClients;
-  /** True when the request carries a valid schedule signature. */
-  verifySchedule?: (headers: Record<string, string | string[] | undefined>) => boolean;
-  scheduleId?: string;
   /** Lets the host translate its own error types before the generic 500. */
   mapError?: (error: unknown) => MappedError | null;
 };
@@ -145,22 +142,13 @@ export async function runRoute(input: RunRouteInput): Promise<RouteOutcome> {
     body = parsed.data;
   }
 
-  const scheduleValid = input.verifySchedule ? input.verifySchedule(input.headers) : false;
-  const schedule = scheduleValid
-    ? { id: input.scheduleId ?? "schedule" }
-    : input.scheduleId
-      ? { id: input.scheduleId }
-      : null;
-
   let user: AuthUser | null = null;
   const auth = route.def.auth ?? false;
-  if (auth === "schedule") {
-    if (!scheduleValid) {
-      return invalid(401, {
-        error: "unauthorized",
-        message: "missing or invalid schedule signature",
-      });
-    }
+  if (typeof auth === "string" && auth !== "required" && auth !== "optional") {
+    return invalid(401, {
+      error: "unauthorized",
+      message: "legacy schedule auth is no longer supported",
+    });
   } else if (typeof auth === "function") {
     try {
       user = await auth({ headers: input.headers });
@@ -202,7 +190,6 @@ export async function runRoute(input: RunRouteInput): Promise<RouteOutcome> {
       push: clients.push,
       jobs: clients.jobs,
       sockets: clients.sockets,
-      schedule,
     };
     const result = await withHandlerTimeout(
       () => Promise.resolve(route.def.handler(context)),

package/src/job-queue.test.ts

@@ -0,0 +1,68 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+  assertJobCrons,
+  assertKnownJob,
+  JOB_MAX_ATTEMPTS,
+  JOB_PAYLOAD_MAX_BYTES,
+  jobBackoffMs,
+  nextJobFailureState,
+  serializeJobPayload,
+} from "./job-queue.js";
+
+function job(name: string, cron?: string, file = `jobs/${name}.ts`) {
+  return { name, file, def: cron === undefined ? {} : { cron } };
+}
+
+test("enqueue row is queued with serialized payload", () => {
+  assertKnownJob("resize", ["resize", "email"]);
+  const payloadJson = serializeJobPayload({ key: "avatar.png" });
+  assert.equal(JSON.parse(payloadJson).key, "avatar.png");
+  const row = {
+    name: "resize",
+    payload_json: payloadJson,
+    status: "queued" as const,
+    attempts: 0,
+  };
+  assert.equal(row.status, "queued");
+  assert.equal(row.attempts, 0);
+});
+
+test("unknown name throws", () => {
+  assert.throws(() => assertKnownJob("missing", ["resize"]), /Unknown job name: missing/);
+});
+
+test("oversize payload throws", () => {
+  const oversized = "x".repeat(JOB_PAYLOAD_MAX_BYTES);
+  assert.throws(() => serializeJobPayload(oversized), /job payload must be at most 256KB/);
+  assert.equal(serializeJobPayload(undefined), "null");
+});
+
+test("backoff then dead after 5 attempts", () => {
+  assert.equal(jobBackoffMs(1), 1000);
+  assert.equal(jobBackoffMs(2), 4000);
+  let state = nextJobFailureState(1);
+  for (let attempts = 2; attempts < JOB_MAX_ATTEMPTS; attempts++) {
+    assert.equal(state.status, "queued");
+    assert.ok(state.runAt);
+    state = nextJobFailureState(attempts);
+  }
+  state = nextJobFailureState(JOB_MAX_ATTEMPTS);
+  assert.equal(state.status, "dead");
+  assert.equal(state.runAt, null);
+});
+
+test("invalid cron fails with hosted error shape", () => {
+  assert.throws(
+    () => assertJobCrons([job("digest", "not-a-cron")]),
+    (error: unknown) => {
+      const err = error as { statusCode?: number; code?: string; path?: string };
+      return (
+        err.statusCode === 400 && err.code === "invalid_job_cron" && err.path === "jobs/digest.ts"
+      );
+    },
+  );
+  assert.throws(() => assertJobCrons([job("digest", "")]));
+  assert.throws(() => assertJobCrons([job("digest", "   ")]));
+  assert.doesNotThrow(() => assertJobCrons([job("digest"), job("hourly", "0 * * * *")]));
+});

package/src/job-queue.ts

@@ -0,0 +1,58 @@
+import { assertFiveFieldCron } from "./cron.js";
+
+export const JOB_MAX_ATTEMPTS = 5;
+export const JOB_PAYLOAD_MAX_BYTES = 256 * 1024;
+export const JOB_CONCURRENCY = 4;
+
+export type JobCronDefinition = {
+  name: string;
+  file?: string;
+  def: { cron?: string };
+};
+
+export function jobBackoffMs(attempt: number): number {
+  return Math.min(1000 * 4 ** Math.max(attempt - 1, 0), 300_000);
+}
+
+export function nextJobFailureState(attempts: number): {
+  status: "queued" | "dead";
+  runAt: Date | null;
+} {
+  if (attempts >= JOB_MAX_ATTEMPTS) {
+    return { status: "dead", runAt: null };
+  }
+  return { status: "queued", runAt: new Date(Date.now() + jobBackoffMs(attempts)) };
+}
+
+export function serializeJobPayload(payload: unknown): string {
+  const json = JSON.stringify(payload ?? null);
+  if (Buffer.byteLength(json, "utf8") > JOB_PAYLOAD_MAX_BYTES) {
+    throw new Error("job payload must be at most 256KB");
+  }
+  return json;
+}
+
+export function assertKnownJob(name: string, known: Iterable<string>): void {
+  const names = new Set(known);
+  if (!names.has(name)) {
+    throw new Error(`Unknown job name: ${name}`);
+  }
+}
+
+export function assertJobCrons(jobs: readonly JobCronDefinition[]): void {
+  for (const job of jobs) {
+    if (job.def.cron === undefined) continue;
+    try {
+      if (typeof job.def.cron !== "string" || job.def.cron.trim() === "") {
+        throw new Error("cron must be a non-empty 5-field expression");
+      }
+      assertFiveFieldCron(job.def.cron);
+    } catch (error) {
+      throw Object.assign(new Error(error instanceof Error ? error.message : "invalid cron"), {
+        statusCode: 400,
+        code: "invalid_job_cron",
+        path: job.file ?? `jobs/${job.name}.ts`,
+      });
+    }
+  }
+}