robodev 0.30.0 → 0.32.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "robodev",
-  "version": "0.30.0",
-  "description": "CLI for Robodev Starbase — create, auth, link, and deploy hosted apps",
+  "version": "0.32.0",
+  "description": "CLI for Robodev Starbase — create, auth, link, deploy, and run a project locally with robodev dev",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -20,17 +20,21 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "robodev": "tsx src/index.ts",
-    "generate:templates": "tsx src/generate-templates.ts",
-    "prepack": "tsx src/generate-templates.ts",
-    "test": "tsx --test src/**/*.test.ts"
-  },
   "dependencies": {
-    "tsx": "^4.20.5"
+    "@fastify/cors": "^11.3.0",
+    "embedded-postgres": "17.10.0-beta.17",
+    "fastify": "^5.12.1",
+    "tsx": "^4.20.5",
+    "@robodev-ai/runtime": "0.2.0",
+    "@robodev-ai/sdk": "0.11.0"
   },
   "devDependencies": {
     "@types/node": "^24.3.0",
     "typescript": "^5.9.2"
+  },
+  "scripts": {
+    "robodev": "tsx src/index.ts",
+    "generate:templates": "tsx src/generate-templates.ts",
+    "test": "tsx --test src/**/*.test.ts"
   }
-}
+}

package/src/collect-files.test.ts

@@ -4,7 +4,7 @@ import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { test } from "node:test";
-import { collectFiles, mergeCollectedFiles } from "./collect-files.js";
+import { collectFiles, mergeCollectedFiles, shouldCollectPath } from "./collect-files.js";
 
 test("collectFiles includes hosted sources and skips denied paths", async () => {
   const root = await mkdtemp(join(tmpdir(), "rd-cli-"));
@@ -162,3 +162,12 @@ test("collectFiles rejects mixed backend layouts", async () => {
     await rm(root, { recursive: true, force: true });
   }
 });
+
+test("backend tests are not collected for deploy", () => {
+  assert.equal(shouldCollectPath("robodev/api/_lib.seed.test.ts"), false);
+  assert.equal(shouldCollectPath("robodev/jobs/resize.spec.ts"), false);
+  assert.equal(shouldCollectPath("robodev/sockets/chat.test.ts"), false);
+  assert.equal(shouldCollectPath("api/health.test.ts"), false);
+  assert.equal(shouldCollectPath("robodev/api/_lib.ts"), true);
+  assert.equal(shouldCollectPath("robodev/api/latest.ts"), true);
+});

package/src/collect-files.ts

@@ -123,6 +123,11 @@ export function isPublicBinaryCollectedPath(path: string): boolean {
   return normalized.startsWith("public/") && PUBLIC_BINARY_EXTENSIONS.has(extname(normalized));
 }
 
+/** Project tests live beside the handlers they cover; they are not part of the deployed tree. */
+function isBackendTestPath(path: string): boolean {
+  return /\.(test|spec)\.ts$/.test(path);
+}
+
 function isBackendPath(path: string): boolean {
   const inner = path.startsWith("robodev/") ? path.slice("robodev/".length) : path;
   if (inner === "database.ts" && (path === "database.ts" || path === "robodev/database.ts")) {
@@ -134,7 +139,7 @@ function isBackendPath(path: string): boolean {
     inner.startsWith("hooks/") ||
     inner.startsWith("sockets/")
   ) {
-    return inner.endsWith(".ts");
+    return inner.endsWith(".ts") && !isBackendTestPath(inner);
   }
   return path === "robodev/package.json";
 }

package/src/dev-clients.ts

@@ -0,0 +1,66 @@
+import type { RouteClients } from "@robodev-ai/runtime";
+import type { EmailClient, JobEnqueueInput, LlmClient } from "@robodev-ai/sdk";
+
+/**
+ * The `ctx.*` clients `robodev dev` can offer offline. `email` prints to the terminal;
+ * `jobs` enqueues onto the local engine; everything else that needs Starbase
+ * infrastructure fails with a message that says so rather than silently doing nothing.
+ */
+
+function unavailable(feature: string): never {
+  throw Object.assign(
+    new Error(`ctx.${feature} needs hosted Starbase. Run robodev deploy to use it.`),
+    { statusCode: 501 },
+  );
+}
+
+/** Prints mail to stdout so local signup and reset flows are followable. */
+export function consoleEmailClient(log: (line: string) => void): EmailClient {
+  return {
+    async send(input) {
+      const to = Array.isArray(input.to) ? input.to.join(", ") : input.to;
+      log(`email → ${to}: ${input.subject}`);
+      if (input.text) log(`  ${input.text}`);
+      return { id: `local_${Date.now().toString(36)}`, status: "sent" };
+    },
+  };
+}
+
+function offlineLlmClient(): LlmClient {
+  return {
+    complete: () => unavailable("llm"),
+    stream: () => unavailable("llm"),
+  };
+}
+
+export function devRouteClients(input: {
+  env: Record<string, string>;
+  log: (line: string) => void;
+  enqueue: (job: JobEnqueueInput) => Promise<{ id: string }>;
+}): RouteClients {
+  return {
+    email: consoleEmailClient(input.log),
+    llm: offlineLlmClient(),
+    agent: {
+      createSession: () => unavailable("agent"),
+      start: () => unavailable("agent"),
+      events: () => unavailable("agent"),
+      subscribe: () => unavailable("agent"),
+      destroy: () => unavailable("agent"),
+    },
+    storage: {
+      upload: () => unavailable("storage"),
+      get: () => unavailable("storage"),
+      getUrl: () => unavailable("storage"),
+      delete: () => unavailable("storage"),
+      list: () => unavailable("storage"),
+    },
+    push: { send: () => unavailable("push") },
+    jobs: { enqueue: input.enqueue },
+    sockets: {
+      send: () => unavailable("sockets"),
+      broadcast: () => unavailable("sockets"),
+    },
+    env: input.env,
+  };
+}

package/src/dev-postgres.ts

@@ -0,0 +1,161 @@
+import { createServer } from "node:net";
+import { lstat, mkdir, readdir, readFile, symlink } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { dirname, join, relative } from "node:path";
+import { arch, platform } from "node:os";
+
+export type DevPostgres = {
+  host: string;
+  port: number;
+  dataDir: string;
+  database: string;
+  connectionString: string;
+  stop: () => Promise<void>;
+};
+
+const DEV_USER = "robodev";
+const DEV_PASSWORD = "robodev";
+const DEV_DATABASE = "robodev";
+
+/** Asks the OS for a free TCP port so parallel projects never collide. */
+export async function freePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.unref();
+    server.on("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      if (!address || typeof address === "string") {
+        server.close();
+        reject(new Error("Could not reserve a port for Postgres"));
+        return;
+      }
+      const { port } = address;
+      server.close(() => resolve(port));
+    });
+  });
+}
+
+export function devConnectionString(input: { port: number; database?: string }): string {
+  return `postgres://${DEV_USER}:${DEV_PASSWORD}@127.0.0.1:${input.port}/${
+    input.database ?? DEV_DATABASE
+  }`;
+}
+
+async function isInitialised(dataDir: string): Promise<boolean> {
+  try {
+    return (await readdir(dataDir)).includes("PG_VERSION");
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The `@embedded-postgres/*` tarballs ship dylibs/shared objects without their version
+ * symlinks (npm tarballs cannot carry symlinks) and rebuild them from `pg-symlinks.json`
+ * in a `postinstall`. Package managers that skip install scripts leave the cluster
+ * unlaunchable with a cryptic loader error, so hydrate any missing links ourselves.
+ */
+export async function hydratePostgresSymlinks(): Promise<void> {
+  const pkg = `@embedded-postgres/${platform() === "win32" ? "windows" : platform()}-${arch()}`;
+  let pkgRoot: string;
+  try {
+    // The package only exports its entry point, so derive the root from `dist/index.js`.
+    pkgRoot = dirname(dirname(createRequire(import.meta.url).resolve(pkg)));
+  } catch {
+    return;
+  }
+
+  let entries: { source: string; target: string }[];
+  try {
+    entries = JSON.parse(
+      await readFile(join(pkgRoot, "native", "pg-symlinks.json"), "utf8"),
+    ) as typeof entries;
+  } catch {
+    return;
+  }
+
+  for (const entry of entries) {
+    const target = join(pkgRoot, entry.target);
+    try {
+      await lstat(target);
+      continue;
+    } catch {
+      /* missing, create it below */
+    }
+    try {
+      await symlink(relative(dirname(target), join(pkgRoot, entry.source)), target);
+    } catch {
+      /* another process won the race, or the tree is read-only */
+    }
+  }
+}
+
+async function loadEmbeddedPostgres() {
+  try {
+    const mod = await import("embedded-postgres");
+    return mod.default;
+  } catch (error) {
+    throw new Error(
+      `Could not load the embedded Postgres binaries (${
+        error instanceof Error ? error.message : String(error)
+      }). Reinstall dependencies, or point robodev dev at your own server with --database-url.`,
+    );
+  }
+}
+
+/**
+ * Starts a real Postgres on a free port with its cluster under `dataDir`, so rows survive
+ * restarts. `initdb` only runs the first time.
+ */
+export async function startDevPostgres(input: {
+  dataDir: string;
+  port?: number;
+  quiet?: boolean;
+}): Promise<DevPostgres> {
+  await hydratePostgresSymlinks();
+  const EmbeddedPostgres = await loadEmbeddedPostgres();
+  const port = input.port && input.port > 0 ? input.port : await freePort();
+  await mkdir(input.dataDir, { recursive: true });
+  const fresh = !(await isInitialised(input.dataDir));
+
+  const postgres = new EmbeddedPostgres({
+    databaseDir: input.dataDir,
+    port,
+    user: DEV_USER,
+    password: DEV_PASSWORD,
+    persistent: true,
+    onLog: input.quiet ? () => undefined : (message) => process.stderr.write(`${message}\n`),
+    onError: input.quiet ? () => undefined : (message) => process.stderr.write(`${message}\n`),
+  });
+
+  if (fresh) {
+    await postgres.initialise();
+  }
+  await postgres.start();
+  if (fresh) {
+    await postgres.createDatabase(DEV_DATABASE);
+  }
+
+  return {
+    host: "127.0.0.1",
+    port,
+    dataDir: input.dataDir,
+    database: DEV_DATABASE,
+    connectionString: devConnectionString({ port }),
+    stop: () => postgres.stop(),
+  };
+}
+
+/** Wraps a Postgres the user already runs, so `--database-url` behaves like the embedded one. */
+export function externalDevPostgres(connectionString: string): DevPostgres {
+  const url = new URL(connectionString);
+  return {
+    host: url.hostname,
+    port: Number(url.port || 5432),
+    dataDir: "",
+    database: url.pathname.replace(/^\//, "") || "postgres",
+    connectionString,
+    stop: async () => undefined,
+  };
+}

package/src/dev-project.test.ts

@@ -0,0 +1,168 @@
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import {
+  backendCandidates,
+  collectBackendFiles,
+  devDirFor,
+  findDevProject,
+  isBackendDevPath,
+} from "./dev-project.js";
+import { parseDevArgs, parseEnvFile } from "./dev.js";
+import { devConnectionString } from "./dev-postgres.js";
+
+async function tempProject(): Promise<string> {
+  return mkdtemp(join(tmpdir(), "robodev-dev-"));
+}
+
+const DATABASE_TS = `import { defineDatabase, pgTable, text } from "@robodev-ai/sdk";
+export const notes = pgTable("notes", { id: text("id").primaryKey() });
+export default defineDatabase({ name: "app", tables: { notes } });
+`;
+
+test("backendCandidates prefers robodev/ then the root then packages/be", () => {
+  assert.deepEqual(
+    backendCandidates("/p").map((entry) => entry.layout),
+    ["robodev", "root", "packages/be"],
+  );
+});
+
+test("findDevProject finds a robodev/ backend", async () => {
+  const root = await tempProject();
+  await mkdir(join(root, "robodev"), { recursive: true });
+  await writeFile(join(root, "robodev", "database.ts"), DATABASE_TS);
+
+  const project = await findDevProject(root);
+  assert.equal(project.root, root);
+  assert.equal(project.backendDir, join(root, "robodev"));
+  assert.equal(project.layout, "robodev");
+});
+
+test("findDevProject finds Tiny's packages/be and walks up from a subdirectory", async () => {
+  const root = await tempProject();
+  await mkdir(join(root, "packages", "be"), { recursive: true });
+  await mkdir(join(root, "apps", "fe"), { recursive: true });
+  await writeFile(join(root, "packages", "be", "database.ts"), DATABASE_TS);
+
+  const project = await findDevProject(join(root, "apps", "fe"));
+  assert.equal(project.root, root);
+  assert.equal(project.backendDir, join(root, "packages", "be"));
+  assert.equal(project.layout, "packages/be");
+});
+
+test("findDevProject explains itself when there is no project", async () => {
+  const root = await mkdtemp(join(tmpdir(), "robodev-empty-"));
+  await assert.rejects(() => findDevProject(root), /No database\.ts found/);
+});
+
+test("isBackendDevPath accepts backend sources only", () => {
+  assert.equal(isBackendDevPath("database.ts"), true);
+  assert.equal(isBackendDevPath("api/planets.ts"), true);
+  assert.equal(isBackendDevPath("api/planets/[id].ts"), true);
+  assert.equal(isBackendDevPath("jobs/digest.ts"), true);
+  assert.equal(isBackendDevPath("hooks/auth.ts"), true);
+  assert.equal(isBackendDevPath("sockets/chat.ts"), true);
+  assert.equal(isBackendDevPath("src/main.tsx"), false);
+  assert.equal(isBackendDevPath("api/planets.js"), false);
+  assert.equal(isBackendDevPath("package.json"), false);
+  assert.equal(isBackendDevPath("../secrets.ts"), false);
+  // Project tests stay out of the dev tree, exactly as deploy excludes them.
+  assert.equal(isBackendDevPath("api/_lib.seed.test.ts"), false);
+  assert.equal(isBackendDevPath("api/planets.spec.ts"), false);
+});
+
+test("collectBackendFiles reads deploy-shaped paths and skips the rest", async () => {
+  const root = await tempProject();
+  const backend = join(root, "robodev");
+  await mkdir(join(backend, "api", "planets"), { recursive: true });
+  await mkdir(join(backend, "jobs"), { recursive: true });
+  await mkdir(join(backend, "node_modules"), { recursive: true });
+  await writeFile(join(backend, "database.ts"), DATABASE_TS);
+  await writeFile(join(backend, "api", "planets.ts"), "export const get = 1;");
+  await writeFile(join(backend, "api", "planets", "[id].ts"), "export const get = 1;");
+  await writeFile(join(backend, "api", "notes.md"), "ignored");
+  await writeFile(join(backend, "api", "_lib.seed.test.ts"), "ignored");
+  await writeFile(join(backend, "jobs", "digest.ts"), "export default 1;");
+  await writeFile(join(backend, "node_modules", "x.ts"), "ignored");
+  await writeFile(join(backend, "package.json"), "{}");
+
+  const files = await collectBackendFiles(backend);
+  assert.deepEqual(files.map((file) => file.path).sort(), [
+    "api/planets.ts",
+    "api/planets/[id].ts",
+    "database.ts",
+    "jobs/digest.ts",
+  ]);
+});
+
+test("collectBackendFiles requires database.ts", async () => {
+  const root = await tempProject();
+  await mkdir(join(root, "api"), { recursive: true });
+  await writeFile(join(root, "api", "planets.ts"), "export const get = 1;");
+  await assert.rejects(() => collectBackendFiles(root), /database\.ts not found/);
+});
+
+test("devDirFor sidesteps a legacy .robodev link file", async () => {
+  const withDir = await tempProject();
+  assert.equal(await devDirFor(withDir), join(withDir, ".robodev", "dev"));
+
+  const withFile = await tempProject();
+  await writeFile(join(withFile, ".robodev"), "{}");
+  assert.equal(await devDirFor(withFile), join(withFile, ".robodev-dev"));
+});
+
+test("parseDevArgs defaults to :4000, an ephemeral db port, and watching", () => {
+  assert.deepEqual(parseDevArgs([]), {
+    port: 4000,
+    dbPort: 0,
+    force: false,
+    watch: true,
+    withFe: false,
+    databaseUrl: undefined,
+  });
+});
+
+test("parseDevArgs reads every flag", () => {
+  const parsed = parseDevArgs([
+    "--port",
+    "4500",
+    "--db-port",
+    "55433",
+    "--force",
+    "--no-watch",
+    "--with-fe",
+    "--database-url",
+    "postgres://u:p@localhost:5432/app",
+  ]);
+  assert.deepEqual(parsed, {
+    port: 4500,
+    dbPort: 55433,
+    force: true,
+    watch: false,
+    withFe: true,
+    databaseUrl: "postgres://u:p@localhost:5432/app",
+  });
+});
+
+test("parseDevArgs rejects malformed flag values", () => {
+  assert.throws(() => parseDevArgs(["--port", "abc"]), /--port needs/);
+  assert.throws(() => parseDevArgs(["--port", "-1"]), /--port needs/);
+  assert.throws(() => parseDevArgs(["--database-url"]), /--database-url needs/);
+  assert.throws(() => parseDevArgs(["--database-url", "--force"]), /--database-url needs/);
+});
+
+test("parseEnvFile handles comments, blanks, quotes, and values with =", () => {
+  assert.deepEqual(
+    parseEnvFile(["# comment", "", "A=1", 'B="two"', "C='three'", "D=a=b", "  E = 5 "].join("\n")),
+    { A: "1", B: "two", C: "three", D: "a=b", E: "5" },
+  );
+});
+
+test("devConnectionString points at loopback", () => {
+  assert.equal(
+    devConnectionString({ port: 55433 }),
+    "postgres://robodev:robodev@127.0.0.1:55433/robodev",
+  );
+});

package/src/dev-project.ts

@@ -0,0 +1,147 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
+import { isBackendTestPath } from "@robodev-ai/runtime";
+
+export type DevFile = { path: string; content: string };
+
+export type DevProject = {
+  /** Where `.robodev/dev/` and the root `package.json` live. */
+  root: string;
+  /** Absolute directory holding `database.ts` plus `api/`, `jobs/`, `hooks/`, `sockets/`. */
+  backendDir: string;
+  /** Backend layout that was matched, for the startup banner. */
+  layout: "root" | "robodev" | "packages/be";
+};
+
+/** Directories under the backend root that hold compilable project code. */
+export const BACKEND_DIRS = ["api", "jobs", "hooks", "sockets"] as const;
+
+const SKIP_DIRS = new Set(["node_modules", "dist", ".git", ".robodev"]);
+const MAX_BACKEND_FILES = 400;
+
+async function isFile(path: string): Promise<boolean> {
+  try {
+    return (await stat(path)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Candidate backend roots for one directory, in the order `robodev deploy` prefers:
+ * `robodev/` first, then the project root, then Tiny's `packages/be`.
+ */
+export function backendCandidates(dir: string): { dir: string; layout: DevProject["layout"] }[] {
+  return [
+    { dir: join(dir, "robodev"), layout: "robodev" },
+    { dir, layout: "root" },
+    { dir: join(dir, "packages", "be"), layout: "packages/be" },
+  ];
+}
+
+/**
+ * Walks up from `cwd` looking for a created project: `database.ts` in `robodev/`, at the
+ * root, or in `packages/be` (Tiny). Walking up means `robodev dev` also works from
+ * `apps/fe`.
+ */
+export async function findDevProject(cwd: string): Promise<DevProject> {
+  let dir = cwd;
+  for (;;) {
+    for (const candidate of backendCandidates(dir)) {
+      if (await isFile(join(candidate.dir, "database.ts"))) {
+        return { root: dir, backendDir: candidate.dir, layout: candidate.layout };
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error(
+    "No database.ts found. Run robodev dev from a created project (database.ts, robodev/database.ts, or packages/be/database.ts).",
+  );
+}
+
+/**
+ * True for a path the runtime compiles: `database.ts` or a `.ts` file under a backend dir.
+ * Project tests are excluded, exactly as `robodev deploy` excludes them.
+ */
+export function isBackendDevPath(path: string): boolean {
+  const normalized = path.replaceAll("\\", "/");
+  if (normalized.includes("..")) return false;
+  if (isBackendTestPath(normalized)) return false;
+  if (normalized === "database.ts") return true;
+  if (!normalized.endsWith(".ts")) return false;
+  const top = normalized.split("/")[0] ?? "";
+  return (BACKEND_DIRS as readonly string[]).includes(top);
+}
+
+/**
+ * Reads the backend tree off disk as deploy files. Paths are the same ones hosted deploy
+ * uses (`database.ts`, `api/planets.ts`), so route mapping is identical.
+ */
+export async function collectBackendFiles(backendDir: string): Promise<DevFile[]> {
+  const files: DevFile[] = [];
+
+  async function walk(dir: string): Promise<void> {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const abs = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name)) continue;
+        await walk(abs);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      const path = relative(backendDir, abs).replaceAll("\\", "/");
+      if (!isBackendDevPath(path)) continue;
+      files.push({ path, content: await readFile(abs, "utf8") });
+      if (files.length > MAX_BACKEND_FILES) {
+        throw new Error(`Backend may include at most ${MAX_BACKEND_FILES} files`);
+      }
+    }
+  }
+
+  if (await isFile(join(backendDir, "database.ts"))) {
+    files.push({
+      path: "database.ts",
+      content: await readFile(join(backendDir, "database.ts"), "utf8"),
+    });
+  }
+  for (const name of BACKEND_DIRS) {
+    await walk(join(backendDir, name));
+  }
+
+  if (!files.some((file) => file.path === "database.ts")) {
+    throw new Error(`database.ts not found in ${backendDir}`);
+  }
+  return files;
+}
+
+/**
+ * Where the local Postgres cluster and build output live. Legacy-layout projects keep
+ * `.robodev` as a link *file* at the root, so fall back beside it rather than failing.
+ */
+export async function devDirFor(root: string): Promise<string> {
+  const dotRobodev = join(root, ".robodev");
+  try {
+    if (!(await stat(dotRobodev)).isDirectory()) {
+      return join(root, ".robodev-dev");
+    }
+  } catch {
+    /* absent: safe to create as a directory */
+  }
+  return join(dotRobodev, "dev");
+}
+
+export async function hasAppsFe(root: string): Promise<boolean> {
+  try {
+    return (await stat(join(root, "apps/fe/package.json"))).isFile();
+  } catch {
+    return false;
+  }
+}

package/src/dev-server.ts

@@ -0,0 +1,205 @@
+import { Readable } from "node:stream";
+import cors from "@fastify/cors";
+import Fastify, { type FastifyInstance, type FastifyRequest } from "fastify";
+import {
+  buildOpenApi,
+  handleLocalAuth,
+  isLocalAuthPath,
+  matchProjectRoute,
+  resolveLocalUser,
+  runRoute,
+  scalarHtml,
+  swaggerHtml,
+  type AuthQueryable,
+  type RuntimeRoute,
+} from "@robodev-ai/runtime";
+import type { JobEnqueueInput, RobodevDb } from "@robodev-ai/sdk";
+import type { RuntimeJob } from "@robodev-ai/runtime";
+import { devRouteClients } from "./dev-clients.js";
+
+/** One compiled generation of the project. Swapped wholesale on reload. */
+export type DevRuntime = {
+  db: RobodevDb;
+  pool: AuthQueryable & { end: () => Promise<void> };
+  routes: RuntimeRoute[];
+  jobs: RuntimeJob[];
+  openapi: Record<string, unknown>;
+};
+
+export type DevServerOptions = {
+  port: number;
+  projectId: string;
+  jwtSecret: string;
+  env: Record<string, string>;
+  log: (line: string) => void;
+  enqueue: (job: JobEnqueueInput) => Promise<{ id: string }>;
+};
+
+const SWAGGER_PATHS = new Set(["/_robodev/docs", "/_robodev/swagger", "/docs", "/swagger"]);
+const SCALAR_PATHS = new Set(["/_robodev/scalar", "/scalar"]);
+
+export function buildDevOpenApi(projectName: string, routes: RuntimeRoute[]) {
+  return buildOpenApi({ title: `${projectName} APIs`, projectId: "local", routes });
+}
+
+function pathnameOf(url: string): string {
+  const raw = decodeURIComponent(url.split("?")[0] ?? "/").replace(/\\/g, "/");
+  return raw.replace(/\/$/, "") || "/";
+}
+
+function rawBodyOf(request: FastifyRequest): Buffer | undefined {
+  return (request as FastifyRequest & { rawBody?: Buffer }).rawBody;
+}
+
+/**
+ * A single-project HTTP host. Unlike the hosted project host there is no `Host` lookup,
+ * no static SPA serving (local Vite does that), and no request logging — the routes,
+ * validation, and OpenAPI all come from `@robodev-ai/runtime`.
+ */
+export async function startDevServer(
+  options: DevServerOptions,
+  getRuntime: () => DevRuntime | null,
+): Promise<{ app: FastifyInstance; close: () => Promise<void> }> {
+  const app = Fastify({ logger: false, bodyLimit: 25 * 1024 * 1024 });
+
+  await app.register(cors, {
+    origin: true,
+    credentials: true,
+    methods: ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
+  });
+
+  app.addContentTypeParser("application/json", { parseAs: "string" }, (_request, body, done) => {
+    if (!body) {
+      done(null, {});
+      return;
+    }
+    try {
+      done(null, JSON.parse(body as string));
+    } catch (error) {
+      done(error as Error, undefined);
+    }
+  });
+  app.addContentTypeParser(
+    "application/x-www-form-urlencoded",
+    { parseAs: "string" },
+    (_request, body, done) => {
+      done(null, Object.fromEntries(new URLSearchParams(String(body ?? "")).entries()));
+    },
+  );
+  app.addContentTypeParser(
+    "application/octet-stream",
+    { parseAs: "buffer" },
+    (_request, body, done) => done(null, body),
+  );
+  app.addContentTypeParser("multipart/form-data", { parseAs: "buffer" }, (_request, body, done) =>
+    done(null, body),
+  );
+
+  // `rawBody` handlers and multipart parsing need the untouched bytes.
+  app.addHook("preParsing", async (_request, _reply, payload) => {
+    const chunks: Buffer[] = [];
+    for await (const chunk of payload) {
+      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    const raw = Buffer.concat(chunks);
+    (_request as FastifyRequest & { rawBody?: Buffer }).rawBody = raw;
+    return Readable.from(raw);
+  });
+
+  // The catch-all lives in the not-found handler: `@fastify/cors` already owns `OPTIONS /*`,
+  // and every project route is resolved by the runtime rather than registered with Fastify.
+  app.setNotFoundHandler(async (request, reply) => {
+    const pathname = pathnameOf(request.url);
+    const method = request.method.toLowerCase();
+
+    if (pathname === "/_robodev/ready") {
+      const runtime = getRuntime();
+      if (!runtime) return reply.code(503).send({ error: "not_ready" });
+      try {
+        await runtime.pool.query("SELECT 1");
+        return reply.send({ ok: true });
+      } catch {
+        return reply.code(503).send({ error: "not_ready" });
+      }
+    }
+
+    if (SWAGGER_PATHS.has(pathname)) {
+      return reply.type("text/html; charset=utf-8").send(swaggerHtml("/openapi.json"));
+    }
+    if (SCALAR_PATHS.has(pathname)) {
+      return reply.type("text/html; charset=utf-8").send(scalarHtml("/openapi.json"));
+    }
+
+    const runtime = getRuntime();
+    if (!runtime) {
+      return reply.code(503).send({
+        error: "not_ready",
+        message: "The project is still compiling. Retry in a moment.",
+      });
+    }
+
+    if (pathname === "/openapi.json") {
+      return reply.send(runtime.openapi);
+    }
+
+    if (isLocalAuthPath(pathname)) {
+      const result = await handleLocalAuth(
+        {
+          method: request.method,
+          pathname,
+          body: request.body,
+          query: request.query,
+          authorization: request.headers.authorization,
+        },
+        {
+          db: runtime.pool,
+          projectId: options.projectId,
+          jwtSecret: options.jwtSecret,
+          deliverCode: ({ to, type, code }) => options.log(`${type} code for ${to}: ${code}`),
+        },
+      );
+      return reply.code(result.status).send(result.body);
+    }
+
+    if (!matchProjectRoute(pathname, method, runtime.routes)) {
+      return reply.code(404).send({
+        error: "not_found",
+        message: `${request.method} ${pathname} is not defined`,
+        routes: runtime.routes.map((route) => `${route.method.toUpperCase()} ${route.path}`),
+      });
+    }
+
+    const outcome = await runRoute({
+      db: runtime.db,
+      routes: runtime.routes,
+      method,
+      pathname,
+      query: request.query ?? {},
+      body: request.body,
+      rawBody: rawBodyOf(request),
+      headers: request.headers as Record<string, string | string[] | undefined>,
+      authorization: request.headers.authorization,
+      resolveUser: (authorization) =>
+        resolveLocalUser(
+          { projectId: options.projectId, jwtSecret: options.jwtSecret },
+          authorization,
+        ),
+      clients: () =>
+        devRouteClients({ env: options.env, log: options.log, enqueue: options.enqueue }),
+    });
+
+    if (outcome.kind === "error") {
+      return reply.code(outcome.status).send(outcome.body);
+    }
+    for (const [name, value] of Object.entries(outcome.encoded.headers)) {
+      reply.header(name, value);
+    }
+    return reply
+      .code(outcome.encoded.status)
+      .type(outcome.encoded.contentType)
+      .send(outcome.encoded.payload);
+  });
+
+  await app.listen({ port: options.port, host: "0.0.0.0" });
+  return { app, close: () => app.close() };
+}

package/src/dev.ts

@@ -0,0 +1,376 @@
+import { watch, type FSWatcher } from "node:fs";
+import { mkdir, readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { join, relative } from "node:path";
+import { spawn, type ChildProcess } from "node:child_process";
+import {
+  apiBundleExternals,
+  applyPlan,
+  assertJobCrons,
+  buildPlan,
+  compileApiTree,
+  createLocalJobsEngine,
+  ensureAuthSchema,
+  ensureJobsSchema,
+  isEsbuildFailure,
+  loadModules,
+  mapEsbuildErrors,
+  writeDeploySources,
+  type SchemaPlan,
+} from "@robodev-ai/runtime";
+import { createDb as fallbackCreateDb, type DatabaseDef } from "@robodev-ai/sdk";
+import { commandAvailable } from "./frontend-build.js";
+import {
+  collectBackendFiles,
+  devDirFor,
+  findDevProject,
+  hasAppsFe,
+  isBackendDevPath,
+  type DevProject,
+} from "./dev-project.js";
+import { externalDevPostgres, startDevPostgres, type DevPostgres } from "./dev-postgres.js";
+import { devRouteClients } from "./dev-clients.js";
+import { buildDevOpenApi, startDevServer, type DevRuntime } from "./dev-server.js";
+
+export type DevArgs = {
+  port: number;
+  dbPort: number;
+  force: boolean;
+  watch: boolean;
+  withFe: boolean;
+  databaseUrl?: string;
+};
+
+const DEFAULT_PORT = 4000;
+const RELOAD_DEBOUNCE_MS = 150;
+/** Local-only signing key. Tokens never leave the machine. */
+const DEV_JWT_SECRET = "robodev-dev-local-secret";
+const DEV_PROJECT_ID = "prj-local";
+
+function numberFlag(args: string[], name: string, fallback: number): number {
+  const index = args.indexOf(name);
+  if (index === -1) return fallback;
+  const raw = args[index + 1];
+  const value = Number(raw);
+  if (raw === undefined || !Number.isInteger(value) || value < 0) {
+    throw new Error(`${name} needs a non-negative integer`);
+  }
+  return value;
+}
+
+function stringFlag(args: string[], name: string): string | undefined {
+  const index = args.indexOf(name);
+  if (index === -1) return undefined;
+  const value = args[index + 1];
+  if (!value || value.startsWith("--")) {
+    throw new Error(`${name} needs a value`);
+  }
+  return value;
+}
+
+export function parseDevArgs(args: string[]): DevArgs {
+  return {
+    port: numberFlag(args, "--port", DEFAULT_PORT),
+    dbPort: numberFlag(args, "--db-port", 0),
+    force: args.includes("--force"),
+    watch: !args.includes("--no-watch"),
+    withFe: args.includes("--with-fe"),
+    databaseUrl: stringFlag(args, "--database-url"),
+  };
+}
+
+/** Minimal `.env` reader for `ctx.env`. Hosted projects get this from project secrets. */
+export function parseEnvFile(content: string): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eq = trimmed.indexOf("=");
+    if (eq <= 0) continue;
+    const key = trimmed.slice(0, eq).trim();
+    let value = trimmed.slice(eq + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    env[key] = value;
+  }
+  return env;
+}
+
+async function loadProjectEnv(root: string): Promise<Record<string, string>> {
+  try {
+    return parseEnvFile(await readFile(join(root, ".env"), "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Uses the project's own `@robodev-ai/sdk` when it has one, so `ctx.db` and the Drizzle
+ * tables from `database.ts` come from the same drizzle-orm copy — the way hosted deploy
+ * compiles them.
+ */
+async function resolveCreateDb(backendDir: string, root: string): Promise<typeof fallbackCreateDb> {
+  for (const base of [backendDir, root]) {
+    try {
+      const require = createRequire(join(base, "package.json"));
+      const entry = require.resolve("@robodev-ai/sdk");
+      const mod = (await import(entry)) as { createDb?: typeof fallbackCreateDb };
+      if (mod.createDb) return mod.createDb;
+    } catch {
+      /* fall through to the CLI's own copy */
+    }
+  }
+  return fallbackCreateDb;
+}
+
+function printPlan(plan: SchemaPlan): void {
+  for (const op of plan.operations) {
+    const mark = op.destructive ? "!" : " ";
+    console.log(` ${mark} ${op.type} ${op.table}${op.column ? `.${op.column}` : ""}`);
+  }
+}
+
+export type DevCompileResult = {
+  database: DatabaseDef;
+  runtime: DevRuntime;
+};
+
+export async function main(args: string[]): Promise<void> {
+  const parsed = parseDevArgs(args);
+  const project = await findDevProject(process.cwd());
+  const devDir = await devDirFor(project.root);
+  const buildDir = join(devDir, "build");
+  await mkdir(buildDir, { recursive: true });
+
+  const createDb = await resolveCreateDb(project.backendDir, project.root);
+  const env = await loadProjectEnv(project.root);
+
+  const postgres: DevPostgres = parsed.databaseUrl
+    ? externalDevPostgres(parsed.databaseUrl)
+    : await startDevPostgres({ dataDir: join(devDir, "pg"), port: parsed.dbPort, quiet: true });
+
+  let current: DevRuntime | null = null;
+  let lastSchemaSource = "";
+  let closing = false;
+
+  const log = (line: string) => console.log(line);
+  const engine = createLocalJobsEngine({
+    query: (sql, values) => {
+      if (!current) throw new Error("jobs engine not ready");
+      return current.pool.query(sql, values);
+    },
+    getGeneration: () => current,
+    log,
+    clients: () => devRouteClients({ env, log, enqueue: (input) => engine.enqueue(input) }),
+  });
+
+  async function compileAndActivate(input: { syncSchema: boolean }): Promise<void> {
+    const files = await collectBackendFiles(project.backendDir);
+    await writeDeploySources(join(buildDir, "src"), files);
+
+    let distDir: string;
+    try {
+      distDir = await compileApiTree({
+        dir: buildDir,
+        files,
+        external: apiBundleExternals(),
+        nodePaths: [join(project.backendDir, "node_modules"), join(project.root, "node_modules")],
+      });
+    } catch (error) {
+      if (isEsbuildFailure(error)) {
+        for (const issue of mapEsbuildErrors(error.errors, join(buildDir, "src"))) {
+          const where = issue.path ? `${issue.path}${issue.line ? `:${issue.line}` : ""}: ` : "";
+          console.error(`  ${where}${issue.text}`);
+        }
+        throw new Error("Compile failed");
+      }
+      throw error;
+    }
+
+    const loaded = await loadModules(distDir, files);
+    assertJobCrons(loaded.jobs);
+    // Any edit to database.ts can change columns, not just tables, so compare its source.
+    const schemaSource = files.find((file) => file.path === "database.ts")?.content ?? "";
+
+    if (input.syncSchema || schemaSource !== lastSchemaSource) {
+      const plan = await buildPlan(postgres.connectionString, loaded.database);
+      if (plan.destructive && !parsed.force) {
+        console.log("Destructive schema changes (skipped, rerun with --force):");
+        printPlan(plan);
+      } else {
+        if (plan.operations.length > 0) {
+          console.log("Schema changes:");
+          printPlan(plan);
+        }
+        await applyPlan(postgres.connectionString, plan);
+        lastSchemaSource = schemaSource;
+      }
+    }
+
+    const { db, pool } = createDb(postgres.connectionString, loaded.database.tables);
+    await pool.query("SELECT 1");
+    await ensureAuthSchema(pool);
+    await ensureJobsSchema(pool);
+
+    const previous = current;
+    current = {
+      db,
+      pool,
+      routes: loaded.routes,
+      jobs: loaded.jobs,
+      openapi: buildDevOpenApi(loaded.database.name, loaded.routes),
+    };
+    await engine.reconcile(loaded.jobs);
+
+    for (const route of loaded.routes) {
+      console.log(`  ${route.method.toUpperCase()} ${route.path}`);
+    }
+    for (const job of loaded.jobs) {
+      if (job.def.cron) {
+        console.log(`  job ${job.name} (cron ${job.def.cron})`);
+      } else {
+        console.log(`  job ${job.name}`);
+      }
+    }
+    if (loaded.sockets.length > 0) {
+      console.log(
+        `  ${loaded.sockets.length} socket(s) compiled but not served — sockets need hosted Starbase.`,
+      );
+    }
+    if (previous) {
+      await previous.pool.end().catch(() => undefined);
+    }
+  }
+
+  async function releaseDatabase(): Promise<void> {
+    await current?.pool.end().catch(() => undefined);
+    await postgres.stop().catch(() => undefined);
+  }
+
+  let server: Awaited<ReturnType<typeof startDevServer>>;
+  try {
+    await compileAndActivate({ syncSchema: true });
+    await engine.start();
+    server = await startDevServer(
+      {
+        port: parsed.port,
+        projectId: DEV_PROJECT_ID,
+        jwtSecret: DEV_JWT_SECRET,
+        env,
+        log,
+        enqueue: (input) => engine.enqueue(input),
+      },
+      () => current,
+    );
+  } catch (error) {
+    // Nothing is watching yet, so shut the cluster down instead of orphaning it.
+    await releaseDatabase();
+    throw error;
+  }
+
+  const apiUrl = `http://localhost:${parsed.port}`;
+  console.log("");
+  if (postgres.dataDir) {
+    console.log(
+      `Postgres  localhost:${postgres.port}  (data: ${relative(project.root, postgres.dataDir) || postgres.dataDir})`,
+    );
+  } else {
+    console.log(
+      `Postgres  ${postgres.host}:${postgres.port}/${postgres.database}  (--database-url)`,
+    );
+  }
+  console.log(`API       ${apiUrl}`);
+  console.log(`Swagger   ${apiUrl}/_robodev/docs`);
+  console.log(
+    `Project   ${relative(process.cwd(), project.backendDir) || "."} (${project.layout})`,
+  );
+  console.log("");
+
+  const fe = parsed.withFe ? await startFrontend(project, apiUrl) : null;
+  const watchers = parsed.watch ? startWatch() : [];
+
+  function startWatch(): FSWatcher[] {
+    let timer: NodeJS.Timeout | undefined;
+    let running = false;
+    let pending = false;
+
+    async function reload(): Promise<void> {
+      if (running) {
+        pending = true;
+        return;
+      }
+      running = true;
+      try {
+        console.log("Change detected, reloading…");
+        await compileAndActivate({ syncSchema: false });
+      } catch (error) {
+        console.error(error instanceof Error ? error.message : error);
+        console.error("Keeping the previous build. Fix the error and save again.");
+      } finally {
+        running = false;
+        if (pending) {
+          pending = false;
+          void reload();
+        }
+      }
+    }
+
+    try {
+      return [
+        watch(project.backendDir, { recursive: true }, (_event, filename) => {
+          // Ignore editor scratch files and anything the runtime would not compile.
+          if (filename && !isBackendDevPath(String(filename))) return;
+          if (timer) clearTimeout(timer);
+          timer = setTimeout(() => void reload(), RELOAD_DEBOUNCE_MS);
+        }),
+      ];
+    } catch (error) {
+      console.error(
+        `Could not watch ${project.backendDir} (${error instanceof Error ? error.message : error}). Restart after edits, or pass --no-watch.`,
+      );
+      return [];
+    }
+  }
+
+  async function shutdown(code: number): Promise<void> {
+    if (closing) return;
+    closing = true;
+    await engine.stop();
+    for (const watcher of watchers) watcher.close();
+    fe?.kill("SIGTERM");
+    await server.close().catch(() => undefined);
+    await releaseDatabase();
+    process.exit(code);
+  }
+
+  process.on("SIGINT", () => void shutdown(0));
+  process.on("SIGTERM", () => void shutdown(0));
+}
+
+/** Runs the starter's `apps/fe` dev server with the local API pre-wired. */
+async function startFrontend(project: DevProject, apiUrl: string): Promise<ChildProcess | null> {
+  if (!(await hasAppsFe(project.root))) {
+    console.log("--with-fe: no apps/fe/package.json, serving APIs only.");
+    return null;
+  }
+  const command = (await commandAvailable("bun")) ? "bun" : "npm";
+  const args = command === "bun" ? ["run", "dev"] : ["run", "dev"];
+  const child = spawn(command, args, {
+    cwd: join(project.root, "apps", "fe"),
+    stdio: "inherit",
+    env: {
+      ...process.env,
+      VITE_API_URL: apiUrl,
+      VITE_PUBLIC_API_URL: apiUrl,
+      APP_PUBLIC_API_URL: apiUrl,
+    },
+  });
+  child.on("error", (error) => {
+    console.error(`Could not start apps/fe with ${command}: ${error.message}`);
+  });
+  return child;
+}

package/src/index.ts

@@ -53,6 +53,15 @@ Commands:
   create [path] [--starter <id>] [--empty] [--org <id>]  Create a project, scaffold a starter, and deploy
   link [projectId]     Write robodev/.robodev in the current folder
   deploy [--force]     Deploy schema, APIs, jobs, and frontend (local Vite build when .robodev frontend is set)
+  dev [options]        Run this project's APIs locally on an embedded Postgres, no Starbase needed
+
+dev options:
+  --port <n>           API port (default 4000)
+  --db-port <n>        Postgres port (default 0 = pick a free one)
+  --database-url <url> Use an existing Postgres instead of the embedded one
+  --force              Apply destructive schema changes
+  --no-watch           Compile once and serve, without watching files
+  --with-fe            Also start apps/fe with VITE_API_URL pointed at the local API
 `);
   process.exit(1);
 }
@@ -625,6 +634,11 @@ async function main(): Promise<void> {
     case "deploy":
       await runDeploy(args.includes("--force"));
       break;
+    case "dev": {
+      const { main: runDev } = await import("./dev.js");
+      await runDev(args);
+      break;
+    }
     default:
       usage();
   }

package/templates/auth-chat/package.json

@@ -4,14 +4,15 @@
   "private": true,
   "type": "module",
   "scripts": {
+    "dev": "robodev dev --with-fe",
     "deploy": "robodev deploy",
     "rules:gen": "rulesync generate"
   },
   "dependencies": {
-    "@robodev-ai/sdk": "^0.10.0"
+    "@robodev-ai/sdk": "^0.11.0"
   },
   "devDependencies": {
-    "robodev": "^0.30.0",
+    "robodev": "^0.32.0",
     "rulesync": "^8.18.0",
     "typescript": "^5.9.2"
   }

package/templates/backend/package.json

@@ -4,13 +4,14 @@
   "private": true,
   "type": "module",
   "scripts": {
+    "dev": "robodev dev",
     "deploy": "robodev deploy"
   },
   "dependencies": {
-    "@robodev-ai/sdk": "^0.10.0"
+    "@robodev-ai/sdk": "^0.11.0"
   },
   "devDependencies": {
-    "robodev": "^0.30.0",
+    "robodev": "^0.32.0",
     "typescript": "^5.9.2"
   }
 }

package/templates/empty/package.json

@@ -4,13 +4,14 @@
   "private": true,
   "type": "module",
   "scripts": {
+    "dev": "robodev dev",
     "deploy": "robodev deploy"
   },
   "dependencies": {
-    "@robodev-ai/sdk": "^0.10.0"
+    "@robodev-ai/sdk": "^0.11.0"
   },
   "devDependencies": {
-    "robodev": "^0.30.0",
+    "robodev": "^0.32.0",
     "typescript": "^5.9.2"
   }
 }

package/templates/marketplace/package.json

@@ -4,14 +4,15 @@
   "private": true,
   "type": "module",
   "scripts": {
+    "dev": "robodev dev --with-fe",
     "deploy": "robodev deploy",
     "rules:gen": "rulesync generate"
   },
   "dependencies": {
-    "@robodev-ai/sdk": "^0.10.0"
+    "@robodev-ai/sdk": "^0.11.0"
   },
   "devDependencies": {
-    "robodev": "^0.30.0",
+    "robodev": "^0.32.0",
     "rulesync": "^8.18.0",
     "typescript": "^5.9.2"
   }

package/templates/space/package.json

@@ -4,14 +4,15 @@
   "private": true,
   "type": "module",
   "scripts": {
+    "dev": "robodev dev --with-fe",
     "deploy": "robodev deploy",
     "rules:gen": "rulesync generate"
   },
   "dependencies": {
-    "@robodev-ai/sdk": "^0.10.0"
+    "@robodev-ai/sdk": "^0.11.0"
   },
   "devDependencies": {
-    "robodev": "^0.30.0",
+    "robodev": "^0.32.0",
     "rulesync": "^8.18.0",
     "typescript": "^5.9.2"
   }