robodev 0.3.1 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "robodev",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "CLI for Robodev Starbase — create, auth, link, and deploy file-based APIs",
   "type": "module",
   "license": "MIT",
@@ -15,13 +15,15 @@
   "files": [
     "bin",
     "src",
-    "template"
+    "templates"
   ],
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "robodev": "tsx src/index.ts"
+    "robodev": "tsx src/index.ts",
+    "generate:templates": "tsx src/generate-templates.ts",
+    "prepack": "tsx src/generate-templates.ts"
   },
   "dependencies": {
     "tsx": "^4.20.5"

package/src/emit-starter.ts

@@ -0,0 +1,183 @@
+import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export type Starter = { id: string; title: string; description: string };
+
+export type PackageVersions = {
+  robodev: string;
+  sdk: string;
+  client: string;
+};
+
+export type EmitContext = {
+  name: string;
+  packageName: string;
+  title: string;
+  versions: PackageVersions;
+};
+
+const SKIP_DIRS = new Set(["node_modules", ".robodev", ".git"]);
+
+type DepMap = Record<string, string>;
+
+type PackageJson = {
+  name?: string;
+  dependencies?: DepMap;
+  devDependencies?: DepMap;
+  optionalDependencies?: DepMap;
+  [key: string]: unknown;
+};
+
+export function cliRoot(): string {
+  return join(dirname(fileURLToPath(import.meta.url)), "..");
+}
+
+export async function resolveStarterTree(): Promise<{
+  catalogPath: string;
+  treeRoot: string;
+  catalogLabel: string;
+}> {
+  const workspaceCatalog = join(cliRoot(), "..", "starters", "catalog.json");
+  if (await pathExists(workspaceCatalog)) {
+    return {
+      catalogPath: workspaceCatalog,
+      treeRoot: join(cliRoot(), "..", "starters"),
+      catalogLabel: "starters/catalog.json",
+    };
+  }
+  return {
+    catalogPath: join(cliRoot(), "templates", "catalog.json"),
+    treeRoot: join(cliRoot(), "templates"),
+    catalogLabel: "templates/catalog.json",
+  };
+}
+
+export async function loadCatalog(): Promise<Starter[]> {
+  const { catalogPath, treeRoot, catalogLabel } = await resolveStarterTree();
+  return loadCatalogFrom(treeRoot, catalogPath, catalogLabel);
+}
+
+export async function loadCatalogFrom(
+  treeRoot: string,
+  catalogPath: string,
+  catalogLabel: string,
+): Promise<Starter[]> {
+  let raw: { starters?: Starter[] };
+  try {
+    raw = JSON.parse(await readFile(catalogPath, "utf8")) as { starters?: Starter[] };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      throw new Error(`${catalogLabel} is missing`);
+    }
+    throw error;
+  }
+  if (!Array.isArray(raw.starters)) {
+    throw new Error(`${catalogLabel} is missing a starters array`);
+  }
+  const treeLabel = catalogLabel.replace(/\/catalog\.json$/, "");
+  const starters: Starter[] = [];
+  for (const row of raw.starters) {
+    if (!(await isDirectory(join(treeRoot, row.id)))) {
+      throw new Error(`Starter "${row.id}" is missing a ${treeLabel}/${row.id} directory`);
+    }
+    starters.push(row);
+  }
+  return starters;
+}
+
+export async function loadPackageVersions(): Promise<PackageVersions> {
+  const root = cliRoot();
+  const repo = join(root, "..");
+  const robodev = await readPackageVersion(join(root, "package.json"));
+  return {
+    robodev,
+    sdk: await readPackageVersion(join(repo, "robodev-sdk", "package.json"), robodev),
+    client: await readPackageVersion(join(repo, "robodev-client", "package.json"), robodev),
+  };
+}
+
+/** Copies a starter tree and applies package + display rewrites used by create and prepack. */
+export async function emitStarter(src: string, dest: string, ctx: EmitContext): Promise<void> {
+  await mkdir(dest, { recursive: true });
+  const entries = await readdir(src, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      await emitStarter(join(src, entry.name), join(dest, entry.name), ctx);
+      continue;
+    }
+    if (!entry.isFile() || entry.name === ".env") continue;
+    const content = await readFile(join(src, entry.name), "utf8");
+    const next =
+      entry.name === "package.json"
+        ? rewritePackageJson(content, ctx)
+        : rewriteDisplay(content, ctx);
+    await writeFile(join(dest, entry.name), next);
+  }
+}
+
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+async function isDirectory(path: string): Promise<boolean> {
+  try {
+    return (await stat(path)).isDirectory();
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+async function readPackageVersion(path: string, fallback?: string): Promise<string> {
+  try {
+    const pkg = JSON.parse(await readFile(path, "utf8")) as { version?: string };
+    if (typeof pkg.version === "string" && pkg.version) return pkg.version;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT" || fallback === undefined) {
+      throw error;
+    }
+  }
+  if (fallback !== undefined) return fallback;
+  throw new Error(`Missing version in ${path}`);
+}
+
+function rewritePackageJson(raw: string, ctx: EmitContext): string {
+  const pkg = JSON.parse(raw) as PackageJson;
+  pkg.name = ctx.packageName;
+
+  const pins: Record<string, string> = {
+    robodev: `^${ctx.versions.robodev}`,
+    "@robodev-ai/sdk": `^${ctx.versions.sdk}`,
+    "@robodev-ai/client": `^${ctx.versions.client}`,
+  };
+  for (const section of ["dependencies", "devDependencies", "optionalDependencies"] as const) {
+    const deps = pkg[section];
+    if (!deps) continue;
+    for (const [name, pin] of Object.entries(pins)) {
+      if (deps[name] === "workspace:*") deps[name] = pin;
+    }
+  }
+
+  const moved = pkg.dependencies?.robodev;
+  if (pkg.dependencies) delete pkg.dependencies.robodev;
+  pkg.devDependencies = pkg.devDependencies ?? {};
+  pkg.devDependencies.robodev = pkg.devDependencies.robodev ?? moved ?? pins.robodev;
+
+  return `${JSON.stringify(pkg, null, 2)}\n`;
+}
+
+function rewriteDisplay(content: string, ctx: EmitContext): string {
+  let next = content.replace(/<title>[^<]*<\/title>/g, `<title>${ctx.name}</title>`);
+  next = next.replace(/^# .+$/m, `# ${ctx.name}`);
+  next = next.replaceAll(`<h1>{"${ctx.title}"}</h1>`, `<h1>{"${ctx.name}"}</h1>`);
+  next = next.replaceAll(`<h1>${ctx.title}</h1>`, `<h1>${ctx.name}</h1>`);
+  return next.replaceAll("{{NAME}}", ctx.name).replaceAll("{{PACKAGE_NAME}}", ctx.packageName);
+}

package/src/generate-templates.ts

@@ -0,0 +1,31 @@
+import { copyFile, mkdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { emitStarter, loadCatalogFrom, loadPackageVersions, cliRoot } from "./emit-starter.js";
+
+const startersRoot = join(cliRoot(), "..", "starters");
+const templatesRoot = join(cliRoot(), "templates");
+const catalogLabel = "starters/catalog.json";
+
+async function main(): Promise<void> {
+  const catalogPath = join(startersRoot, "catalog.json");
+  const starters = await loadCatalogFrom(startersRoot, catalogPath, catalogLabel);
+  const versions = await loadPackageVersions();
+
+  await rm(templatesRoot, { recursive: true, force: true });
+  await mkdir(templatesRoot, { recursive: true });
+  await copyFile(catalogPath, join(templatesRoot, "catalog.json"));
+
+  for (const starter of starters) {
+    await emitStarter(join(startersRoot, starter.id), join(templatesRoot, starter.id), {
+      name: "{{NAME}}",
+      packageName: "{{PACKAGE_NAME}}",
+      title: starter.title,
+      versions,
+    });
+  }
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exit(1);
+});

package/src/index.ts

@@ -1,12 +1,11 @@
 import { createServer } from "node:http";
 import { randomBytes } from "node:crypto";
-import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { mkdir, readdir, readFile, stat } from "node:fs/promises";
 import { createInterface } from "node:readline/promises";
 import { stdin, stdout } from "node:process";
-import { basename, dirname, join, relative, resolve } from "node:path";
+import { basename, join, relative, resolve } from "node:path";
 import { execFile, spawn } from "node:child_process";
 import { promisify } from "node:util";
-import { fileURLToPath } from "node:url";
 import { ApiError, authed, publicRequest } from "./api.js";
 import {
   clearCredentials,
@@ -18,6 +17,13 @@ import {
   writeViteApiUrl,
 } from "./config.js";
 import { waitUntilLive } from "./wait-until-live.js";
+import {
+  emitStarter,
+  loadCatalog,
+  loadPackageVersions,
+  resolveStarterTree,
+  type Starter,
+} from "./emit-starter.js";
 
 const execFileAsync = promisify(execFile);
 
@@ -31,7 +37,7 @@ Commands:
   logout               Remove stored credentials
   whoami               Show the signed-in user
   projects             List your projects
-  create [path]        Create a project, scaffold the example app, and deploy
+  create [path] [--starter <id>]  Create a project, scaffold a starter, and deploy
   link [projectId]     Write .robodev in the current folder
   deploy [--force]     Deploy database.ts and api/*.ts
 `);
@@ -301,8 +307,77 @@ async function runDeploy(forceFlag: boolean, root = process.cwd()): Promise<void
   }
 }
 
-function templateRoot(): string {
-  return join(dirname(fileURLToPath(import.meta.url)), "..", "template");
+function validIdsMessage(starters: Starter[]): string {
+  return `Valid ids: ${starters.map((starter) => starter.id).join(", ")}`;
+}
+
+function parseCreateArgs(args: string[]): { path?: string; starterId?: string } {
+  let path: string | undefined;
+  let starterId: string | undefined;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--starter") {
+      const value = args[i + 1];
+      if (!value || value.startsWith("-")) {
+        throw new Error("Missing value for --starter");
+      }
+      starterId = value;
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith("--starter=")) {
+      const value = arg.slice("--starter=".length);
+      if (!value) {
+        throw new Error("Missing value for --starter");
+      }
+      starterId = value;
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      throw new Error(`Unknown flag ${arg}`);
+    }
+    if (path !== undefined) {
+      throw new Error(`Unexpected argument ${arg}`);
+    }
+    path = arg;
+  }
+  return { path, starterId };
+}
+
+async function resolveStarter(flagId: string | undefined): Promise<Starter> {
+  const starters = await loadCatalog();
+  if (flagId !== undefined) {
+    const found = starters.find((starter) => starter.id === flagId);
+    if (!found) {
+      throw new Error(`Unknown starter "${flagId}". ${validIdsMessage(starters)}`);
+    }
+    return found;
+  }
+  if (stdin.isTTY) {
+    console.log("Starters:");
+    starters.forEach((starter, i) => {
+      console.log(`  ${i + 1}. ${starter.title} (${starter.id})`);
+      console.log(`     ${starter.description}`);
+    });
+    const answer = (await prompt("Starter number or id: ")).trim();
+    if (!answer) {
+      throw new Error(`Unknown starter "". ${validIdsMessage(starters)}`);
+    }
+    const asIndex = Number(answer);
+    if (Number.isInteger(asIndex) && asIndex >= 1 && asIndex <= starters.length) {
+      return starters[asIndex - 1];
+    }
+    const found = starters.find((starter) => starter.id === answer);
+    if (!found) {
+      throw new Error(`Unknown starter "${answer}". ${validIdsMessage(starters)}`);
+    }
+    return found;
+  }
+  const space = starters.find((starter) => starter.id === "space");
+  if (!space) {
+    throw new Error(`Unknown starter "space". ${validIdsMessage(starters)}`);
+  }
+  return space;
 }
 
 function projectNameFromPath(root: string): string {
@@ -331,24 +406,6 @@ async function assertCreatable(root: string): Promise<void> {
   }
 }
 
-async function copyTemplate(from: string, to: string, vars: Record<string, string>): Promise<void> {
-  await mkdir(to, { recursive: true });
-  const entries = await readdir(from, { withFileTypes: true });
-  for (const entry of entries) {
-    const src = join(from, entry.name);
-    const dest = join(to, entry.name);
-    if (entry.isDirectory()) {
-      await copyTemplate(src, dest, vars);
-      continue;
-    }
-    let content = await readFile(src, "utf8");
-    for (const [key, value] of Object.entries(vars)) {
-      content = content.replaceAll(`{{${key}}}`, value);
-    }
-    await writeFile(dest, content);
-  }
-}
-
 async function npmInstall(root: string): Promise<void> {
   console.log("Installing npm packages…");
   await new Promise<void>((resolve, reject) => {
@@ -361,9 +418,13 @@ async function npmInstall(root: string): Promise<void> {
   });
 }
 
-/** Creates a Starbase project, copies the starter template, links, deploys, and installs deps. */
-async function runCreate(pathArg?: string): Promise<void> {
-  const root = resolve(process.cwd(), pathArg ?? ".");
+/** Creates a Starbase project, copies the chosen starter, links, deploys, and installs deps. */
+async function runCreate(args: string[]): Promise<void> {
+  const parsed = parseCreateArgs(args);
+  const starter = await resolveStarter(parsed.starterId);
+  console.log(`Using starter ${starter.title} (${starter.id})`);
+
+  const root = resolve(process.cwd(), parsed.path ?? ".");
   await mkdir(root, { recursive: true });
   await assertCreatable(root);
 
@@ -373,9 +434,12 @@ async function runCreate(pathArg?: string): Promise<void> {
     body: JSON.stringify({ name }),
   });
 
-  await copyTemplate(templateRoot(), root, {
-    NAME: name,
-    PACKAGE_NAME: packageNameFromPath(root),
+  const { treeRoot } = await resolveStarterTree();
+  await emitStarter(join(treeRoot, starter.id), root, {
+    name,
+    packageName: packageNameFromPath(root),
+    title: starter.title,
+    versions: await loadPackageVersions(),
   });
   await writeLink(
     {
@@ -424,7 +488,7 @@ async function main(): Promise<void> {
       await runProjects();
       break;
     case "create":
-      await runCreate(args.find((arg) => !arg.startsWith("-")));
+      await runCreate(args);
       break;
     case "link":
       await runLink(args[0]);

package/templates/auth-chat/README.md

@@ -0,0 +1,21 @@
+# {{NAME}}
+
+Starter app from `robodev create --starter auth-chat`: email + Google sign-in and a shared chat room (`chat` database, `messages` table).
+
+The backend is already on Starbase. Run the frontend:
+
+```bash
+npm run dev
+```
+
+It reads `VITE_API_URL` from `.env` (written by `robodev create` / `robodev link`).
+
+Docs: https://robodev.povio.dev/docs/starter
+
+`GET /me` and `GET/POST /messages` (`api/me.ts`, `api/messages.ts`) require a Robodev Auth Bearer token. `GET /health` stays public. Email auth works without Google. If Google is not configured on Starbase, the button shows a 503 message.
+
+Add tables in `database.ts` and routes as `api/<name>.ts`, then:
+
+```bash
+npx robodev deploy
+```

package/templates/auth-chat/api/messages.ts

@@ -0,0 +1,41 @@
+/** GET/POST /messages — signed-in users read and post in the shared room. */
+import { messages } from "../database";
+import { defineApi, desc, z } from "@robodev-ai/sdk";
+
+const Message = z.object({
+  id: z.string(),
+  userId: z.string(),
+  authorName: z.string().nullable(),
+  authorEmail: z.string(),
+  body: z.string(),
+  createdAt: z.coerce.string().nullable(),
+});
+
+export const get = defineApi({
+  auth: "required",
+  response: z.array(Message),
+  handler: async ({ db }) => {
+    const rows = await db.select().from(messages).orderBy(desc(messages.createdAt)).limit(100);
+    return Message.array().parse(rows.reverse());
+  },
+});
+
+export const post = defineApi({
+  auth: "required",
+  body: z.object({
+    body: z.string().trim().min(1).max(2000),
+  }),
+  response: Message,
+  handler: async ({ db, user, body }) => {
+    const [row] = await db
+      .insert(messages)
+      .values({
+        userId: user!.id,
+        authorName: user!.name ?? null,
+        authorEmail: user!.email,
+        body: body.body,
+      })
+      .returning();
+    return Message.parse(row);
+  },
+});

package/templates/auth-chat/database.ts

@@ -0,0 +1,19 @@
+/**
+ * Shared chat room. `robodev_auth.users` is platform-owned — store only a
+ * snapshot of the author on each message.
+ */
+import { defineDatabase, pgTable, text, timestamp, uuid } from "@robodev-ai/sdk";
+
+export const messages = pgTable("messages", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  userId: text("userId").notNull(),
+  authorName: text("authorName"),
+  authorEmail: text("authorEmail").notNull(),
+  body: text("body").notNull(),
+  createdAt: timestamp("createdAt", { withTimezone: true }).defaultNow(),
+});
+
+export default defineDatabase({
+  name: "chat",
+  tables: { messages },
+});

package/templates/auth-chat/index.html

@@ -0,0 +1,201 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{NAME}}</title>
+    <style>
+      :root {
+        color-scheme: dark;
+        --bg: #10131a;
+        --panel: #181c26;
+        --line: #2a3140;
+        --text: #f2eee6;
+        --muted: #9aa3b2;
+        --accent: #7ee0c6;
+        --ink: #10221c;
+        --mine: #243f38;
+        --theirs: #222733;
+        --danger: #f0a0a0;
+      }
+      * {
+        box-sizing: border-box;
+      }
+      body {
+        margin: 0;
+        min-height: 100vh;
+        background:
+          radial-gradient(900px 420px at 10% -10%, #1d3a34 0%, transparent 55%), var(--bg);
+        color: var(--text);
+        font:
+          15px/1.5 ui-sans-serif,
+          system-ui,
+          sans-serif;
+      }
+      main {
+        max-width: 720px;
+        margin: 0 auto;
+        padding: 36px 20px 48px;
+      }
+      main.narrow {
+        max-width: 420px;
+      }
+      main.chat {
+        display: flex;
+        flex-direction: column;
+        min-height: 100vh;
+        padding-bottom: 24px;
+      }
+      h1 {
+        font-size: 28px;
+        font-weight: 650;
+        letter-spacing: -0.04em;
+        margin: 0 0 4px;
+      }
+      .eyebrow {
+        margin: 0 0 6px;
+        color: var(--accent);
+        font-size: 12px;
+        letter-spacing: 0.08em;
+        text-transform: uppercase;
+      }
+      .lede {
+        color: var(--muted);
+        margin: 0 0 22px;
+        overflow-wrap: anywhere;
+      }
+      .error {
+        color: var(--danger);
+        margin: 0 0 16px;
+      }
+      .tabs {
+        display: flex;
+        gap: 8px;
+        margin-bottom: 14px;
+      }
+      .tab,
+      .ghost,
+      button {
+        font: inherit;
+        cursor: pointer;
+      }
+      .tab {
+        background: transparent;
+        color: var(--muted);
+        border: 1px solid var(--line);
+        border-radius: 999px;
+        padding: 6px 12px;
+      }
+      .tab.on {
+        color: var(--ink);
+        background: var(--accent);
+        border-color: var(--accent);
+      }
+      form {
+        display: grid;
+        gap: 10px;
+      }
+      label {
+        display: grid;
+        gap: 4px;
+        font-size: 12px;
+        color: var(--muted);
+      }
+      input,
+      button {
+        color: var(--text);
+      }
+      input {
+        background: var(--panel);
+        border: 1px solid var(--line);
+        border-radius: 8px;
+        padding: 10px 12px;
+      }
+      button[type="submit"],
+      .google {
+        background: var(--accent);
+        color: var(--ink);
+        border: 0;
+        border-radius: 8px;
+        padding: 10px 12px;
+        font-weight: 650;
+      }
+      .google {
+        width: 100%;
+        background: #fff;
+        color: #1f1f1f;
+      }
+      .ghost {
+        background: transparent;
+        color: var(--accent);
+        border: 1px solid var(--accent);
+        border-radius: 8px;
+        padding: 8px 12px;
+        height: fit-content;
+      }
+      button:disabled {
+        opacity: 0.5;
+        cursor: default;
+      }
+      .or {
+        text-align: center;
+        color: var(--muted);
+        margin: 16px 0 12px;
+        font-size: 12px;
+      }
+      header {
+        display: flex;
+        justify-content: space-between;
+        align-items: flex-start;
+        gap: 16px;
+        margin-bottom: 16px;
+      }
+      .transcript {
+        flex: 1;
+        min-height: 320px;
+        max-height: calc(100vh - 240px);
+        overflow: auto;
+        display: flex;
+        flex-direction: column;
+        gap: 10px;
+        padding: 12px;
+        background: var(--panel);
+        border: 1px solid var(--line);
+        border-radius: 12px;
+        margin-bottom: 12px;
+      }
+      .empty {
+        color: var(--muted);
+        margin: auto;
+      }
+      .bubble {
+        max-width: 80%;
+        padding: 8px 12px;
+        border-radius: 12px;
+        background: var(--theirs);
+      }
+      .bubble.mine {
+        align-self: flex-end;
+        background: var(--mine);
+      }
+      .bubble p {
+        margin: 0;
+        white-space: pre-wrap;
+      }
+      .meta {
+        color: var(--muted);
+        font-size: 12px;
+        margin-bottom: 2px;
+      }
+      .composer {
+        display: grid;
+        grid-template-columns: 1fr auto;
+        gap: 8px;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/{template → templates/auth-chat}/package.json

@@ -1,5 +1,6 @@
 {
   "name": "{{PACKAGE_NAME}}",
+  "version": "0.1.0",
   "private": true,
   "type": "module",
   "scripts": {
@@ -10,15 +11,15 @@
   "dependencies": {
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
-    "@robodev-ai/sdk": "^0.3.0",
+    "@robodev-ai/sdk": "^0.4.0",
     "@robodev-ai/client": "^0.1.0"
   },
   "devDependencies": {
     "@types/react": "^18.3.24",
     "@types/react-dom": "^18.3.7",
     "@vitejs/plugin-react": "^4.7.0",
-    "robodev": "^0.3.0",
     "typescript": "^5.9.2",
-    "vite": "^6.3.5"
+    "vite": "^6.3.5",
+    "robodev": "^0.5.0"
   }
 }

package/templates/auth-chat/src/main.tsx

@@ -0,0 +1,291 @@
+import { StrictMode, useEffect, useRef, useState, type FormEvent } from "react";
+import { createRoot } from "react-dom/client";
+import { createClient, type AuthUser } from "@robodev-ai/client";
+
+type Message = {
+  id: string;
+  userId: string;
+  authorName: string | null;
+  authorEmail: string;
+  body: string;
+  createdAt: string | null;
+};
+
+const apiUrl = import.meta.env.VITE_API_URL as string | undefined;
+const api = apiUrl ? createClient({ url: apiUrl }) : null;
+
+function authorLabel(user: { name?: string | null; email: string }) {
+  return user.name?.trim() || user.email;
+}
+
+function App() {
+  const [mode, setMode] = useState<"signin" | "signup">("signin");
+  const [user, setUser] = useState<AuthUser | null>(null);
+  const [ready, setReady] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [pending, setPending] = useState(false);
+  const [email, setEmail] = useState("");
+  const [password, setPassword] = useState("");
+  const [name, setName] = useState("");
+  const [messages, setMessages] = useState<Message[]>([]);
+  const [draft, setDraft] = useState("");
+  const [unauthStatus, setUnauthStatus] = useState<string | null>(null);
+  const listRef = useRef<HTMLDivElement>(null);
+
+  async function refreshMessages() {
+    if (!api) return;
+    const res = await api.fetch("/messages");
+    if (!res.ok) throw new Error(await res.text());
+    setMessages((await res.json()) as Message[]);
+  }
+
+  useEffect(() => {
+    if (!api) {
+      setReady(true);
+      return;
+    }
+    api.consumeTokenFromUrl();
+    void api.auth
+      .getUser()
+      .then(({ user: next }) => setUser(next))
+      .catch(() => setUser(null))
+      .finally(() => setReady(true));
+  }, []);
+
+  useEffect(() => {
+    if (!user || !api) return;
+    let cancelled = false;
+    const load = () =>
+      refreshMessages().catch((err: unknown) => {
+        if (!cancelled) setError(err instanceof Error ? err.message : "Failed to load messages");
+      });
+    void load();
+    const timer = window.setInterval(() => void load(), 2500);
+    return () => {
+      cancelled = true;
+      window.clearInterval(timer);
+    };
+  }, [user]);
+
+  useEffect(() => {
+    listRef.current?.scrollTo({ top: listRef.current.scrollHeight });
+  }, [messages]);
+
+  useEffect(() => {
+    if (!apiUrl) return;
+    void fetch(`${apiUrl}/messages`).then((res) => {
+      setUnauthStatus(
+        `${res.status} ${res.status === 401 ? "unauthorized (expected)" : res.statusText}`,
+      );
+    });
+  }, []);
+
+  async function onEmailAuth(event: FormEvent) {
+    event.preventDefault();
+    if (!api) return;
+    setPending(true);
+    setError(null);
+    try {
+      const session =
+        mode === "signup"
+          ? await api.auth.signUp({ email, password, name: name.trim() || undefined })
+          : await api.auth.signIn.email({ email, password });
+      setUser(session.user);
+      setPassword("");
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Auth failed");
+    } finally {
+      setPending(false);
+    }
+  }
+
+  async function onGoogle() {
+    if (!api) return;
+    setPending(true);
+    setError(null);
+    try {
+      const start = new URL(`${api.url}/auth/google/start`);
+      start.searchParams.set("redirect_uri", window.location.href);
+      const probe = await fetch(start.toString(), { redirect: "manual" });
+      if (probe.status === 503) {
+        const body = (await probe.json().catch(() => ({}))) as { error?: string; message?: string };
+        throw new Error(
+          body.message ||
+            `Google sign-in is not configured on Starbase (${body.error ?? "503"}). Set GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, and PUBLIC_URL.`,
+        );
+      }
+      api.auth.signIn.google();
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Google sign-in failed");
+      setPending(false);
+    }
+  }
+
+  async function onSignOut() {
+    if (!api) return;
+    await api.auth.signOut();
+    setUser(null);
+    setMessages([]);
+  }
+
+  async function onSend(event: FormEvent) {
+    event.preventDefault();
+    if (!api || !draft.trim()) return;
+    setPending(true);
+    setError(null);
+    try {
+      const res = await api.fetch("/messages", {
+        method: "POST",
+        body: JSON.stringify({ body: draft.trim() }),
+      });
+      if (!res.ok) throw new Error(await res.text());
+      setDraft("");
+      await refreshMessages();
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Could not send");
+    } finally {
+      setPending(false);
+    }
+  }
+
+  if (!ready) {
+    return (
+      <main>
+        <p className="lede">Loading session…</p>
+      </main>
+    );
+  }
+
+  if (!api) {
+    return (
+      <main>
+        <h1>{{NAME}}</h1>
+        <p className="error">Missing VITE_API_URL. Run `robodev create` or `robodev link`.</p>
+      </main>
+    );
+  }
+
+  if (!user) {
+    return (
+      <main className="narrow">
+        <p className="eyebrow">Robodev Auth</p>
+        <h1>{{NAME}}</h1>
+        <p className="lede">
+          Sign in with email or Google. Protected APIs live at {apiUrl}. Unauthenticated GET
+          /messages: {unauthStatus ?? "checking…"}.
+        </p>
+        {error ? <p className="error">{error}</p> : null}
+
+        <div className="tabs">
+          <button
+            type="button"
+            className={mode === "signin" ? "tab on" : "tab"}
+            onClick={() => setMode("signin")}
+          >
+            Sign in
+          </button>
+          <button
+            type="button"
+            className={mode === "signup" ? "tab on" : "tab"}
+            onClick={() => setMode("signup")}
+          >
+            Sign up
+          </button>
+        </div>
+
+        <form onSubmit={onEmailAuth}>
+          {mode === "signup" ? (
+            <label>
+              Name
+              <input
+                value={name}
+                onChange={(event) => setName(event.target.value)}
+                placeholder="Ada"
+              />
+            </label>
+          ) : null}
+          <label>
+            Email
+            <input
+              type="email"
+              required
+              autoComplete="email"
+              value={email}
+              onChange={(event) => setEmail(event.target.value)}
+            />
+          </label>
+          <label>
+            Password
+            <input
+              type="password"
+              required
+              minLength={8}
+              autoComplete={mode === "signup" ? "new-password" : "current-password"}
+              value={password}
+              onChange={(event) => setPassword(event.target.value)}
+            />
+          </label>
+          <button type="submit" disabled={pending}>
+            {mode === "signup" ? "Create account" : "Sign in"}
+          </button>
+        </form>
+
+        <div className="or">or</div>
+        <button className="google" type="button" onClick={onGoogle} disabled={pending}>
+          Continue with Google
+        </button>
+      </main>
+    );
+  }
+
+  return (
+    <main className="chat">
+      <header>
+        <div>
+          <p className="eyebrow">Signed in</p>
+          <h1>{authorLabel(user)}</h1>
+          <p className="lede">{user.email}</p>
+        </div>
+        <button className="ghost" type="button" onClick={() => void onSignOut()}>
+          Sign out
+        </button>
+      </header>
+      {error ? <p className="error">{error}</p> : null}
+      <div className="transcript" ref={listRef}>
+        {messages.length === 0 ? <p className="empty">No messages yet. Say hello.</p> : null}
+        {messages.map((message) => {
+          const mine = message.userId === user.id;
+          return (
+            <article key={message.id} className={mine ? "bubble mine" : "bubble"}>
+              <div className="meta">
+                {authorLabel({ name: message.authorName, email: message.authorEmail })}
+                {message.createdAt
+                  ? ` · ${new Date(message.createdAt).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" })}`
+                  : ""}
+              </div>
+              <p>{message.body}</p>
+            </article>
+          );
+        })}
+      </div>
+      <form className="composer" onSubmit={onSend}>
+        <input
+          required
+          maxLength={2000}
+          placeholder="Message the room…"
+          value={draft}
+          onChange={(event) => setDraft(event.target.value)}
+        />
+        <button type="submit" disabled={pending || !draft.trim()}>
+          Send
+        </button>
+      </form>
+    </main>
+  );
+}
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);

package/templates/catalog.json

@@ -0,0 +1,14 @@
+{
+  "starters": [
+    {
+      "id": "space",
+      "title": "Space",
+      "description": "Planets, rockets, and a small React UI"
+    },
+    {
+      "id": "auth-chat",
+      "title": "Auth chat",
+      "description": "Email + Google sign-in and a shared chat room"
+    }
+  ]
+}

package/templates/space/api/health.ts

@@ -0,0 +1,7 @@
+/** GET /health — liveness check for the deployed project host. */
+import { defineApi, z } from "@robodev-ai/sdk";
+
+export const get = defineApi({
+  response: z.object({ ok: z.literal(true) }),
+  handler: async () => ({ ok: true as const }),
+});

package/templates/space/api/me.ts

@@ -0,0 +1,14 @@
+/** GET /me — current project user (Robodev Auth required). */
+import { defineApi, z } from "@robodev-ai/sdk";
+
+export const get = defineApi({
+  auth: "required",
+  response: z.object({
+    user: z.object({
+      id: z.string(),
+      email: z.string(),
+      name: z.string().nullable().optional(),
+    }),
+  }),
+  handler: async ({ user }) => ({ user }),
+});

package/templates/space/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "{{PACKAGE_NAME}}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "deploy": "robodev deploy"
+  },
+  "dependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "@robodev-ai/sdk": "^0.4.0",
+    "@robodev-ai/client": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.24",
+    "@types/react-dom": "^18.3.7",
+    "@vitejs/plugin-react": "^4.7.0",
+    "typescript": "^5.9.2",
+    "vite": "^6.3.5",
+    "robodev": "^0.5.0"
+  }
+}

package/templates/space/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": ["vite/client"]
+  },
+  "include": ["./**/*.ts", "./**/*.tsx"]
+}

package/templates/space/vite.config.ts

@@ -0,0 +1,7 @@
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [react()],
+  server: { port: 5173 },
+});