robodev 0.38.1 → 0.40.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "robodev",
-  "version": "0.38.1",
+  "version": "0.40.0",
   "description": "CLI for Robodev Starbase — create, auth, link, deploy, and run a project locally with robodev dev",
   "type": "module",
   "license": "MIT",
@@ -26,8 +26,8 @@
     "embedded-postgres": "17.10.0-beta.17",
     "fastify": "^5.12.1",
     "tsx": "^4.20.5",
-    "@robodev-ai/runtime": "0.5.1",
-    "@robodev-ai/sdk": "0.13.0"
+    "@robodev-ai/sdk": "0.13.0",
+    "@robodev-ai/runtime": "0.5.1"
   },
   "devDependencies": {
     "@types/node": "^24.3.0",

package/src/emit-starter.test.ts

@@ -114,6 +114,46 @@ test("collectFiles for marketplace starter is Tiny APIs without apps/fe", async
   assert.ok(files.length < 200);
 });
 
+test("emitStarter empty includes hosted Welcome files", async () => {
+  const dest = await mkdtemp(join(tmpdir(), "rd-emit-"));
+  try {
+    await emitStarter(join(cliRoot(), "..", "starters", "empty"), dest, {
+      name: "Blank",
+      packageName: "blank-app",
+      title: "Empty",
+      versions,
+    });
+    const index = await readFile(join(dest, "index.html"), "utf8");
+    assert.match(index, /<title>Blank<\/title>/);
+    assert.match(index, /src\/main\.tsx/);
+    const main = await readFile(join(dest, "src/main.tsx"), "utf8");
+    assert.match(main, /createRoot/);
+    const pkg = JSON.parse(await readFile(join(dest, "package.json"), "utf8")) as {
+      name: string;
+      scripts?: Record<string, string>;
+      dependencies?: Record<string, string>;
+    };
+    assert.equal(pkg.name, "blank-app");
+    assert.equal(pkg.scripts?.dev, "robodev dev");
+    assert.equal(pkg.scripts?.["dev:fe"], "vite");
+    assert.equal(pkg.dependencies?.["@robodev-ai/client"], "^0.12.0");
+  } finally {
+    await rm(dest, { recursive: true, force: true });
+  }
+});
+
+test("collectFiles for empty starter includes hosted Welcome source", async () => {
+  const files = await collectFiles(join(cliRoot(), "..", "starters", "empty"));
+  const paths = new Set(files.map((file) => file.path));
+  assert.ok(paths.has("robodev/database.ts"));
+  assert.ok(paths.has("robodev/api/health.ts"));
+  assert.ok(paths.has("index.html"));
+  assert.ok(paths.has("src/main.tsx"));
+  assert.ok(!paths.has("robodev/api/planets.ts"));
+  assert.ok([...paths].every((path) => !path.startsWith("apps/")));
+  assert.ok(files.length < 200);
+});
+
 test("collectFiles for space starter is Tiny APIs without apps/fe", async () => {
   const files = await collectFiles(join(cliRoot(), "..", "starters", "space"));
   const paths = new Set(files.map((file) => file.path));

package/src/ensure-deploy-link.test.ts

@@ -0,0 +1,228 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+  ensureDeployLink,
+  UNLINKED_NON_TTY_MESSAGE,
+  type EnsureDeployLinkDeps,
+  type EnsureDeployLinkInput,
+} from "./ensure-deploy-link.js";
+import { defaultFrontendConfig, type ProjectLink } from "./config.js";
+
+const linked: ProjectLink = {
+  projectId: "proj_existing",
+  apiUrl: "https://robodev.povio.dev",
+  projectApiUrl: "https://proj_existing.robodev.povio.dev",
+};
+
+function stubDeps(overrides: Partial<EnsureDeployLinkDeps> = {}): EnsureDeployLinkDeps & {
+  calls: {
+    ensureAuth: number;
+    collectFiles: number;
+    resolveOrganization: number;
+    createProject: number;
+    writeLink: number;
+    writeViteApiUrl: number;
+    promptName: number;
+  };
+  createdBodies: { name: string; organizationId?: string }[];
+  writtenLinks: ProjectLink[];
+} {
+  const calls = {
+    ensureAuth: 0,
+    collectFiles: 0,
+    resolveOrganization: 0,
+    createProject: 0,
+    writeLink: 0,
+    writeViteApiUrl: 0,
+    promptName: 0,
+  };
+  const createdBodies: { name: string; organizationId?: string }[] = [];
+  const writtenLinks: ProjectLink[] = [];
+  return {
+    calls,
+    createdBodies,
+    writtenLinks,
+    readLink: async () => null,
+    collectFiles: async () => {
+      calls.collectFiles += 1;
+      return [];
+    },
+    ensureAuth: async () => {
+      calls.ensureAuth += 1;
+    },
+    resolveOrganization: async (flagId) => {
+      calls.resolveOrganization += 1;
+      return flagId;
+    },
+    createProject: async (body) => {
+      calls.createProject += 1;
+      createdBodies.push(body);
+      return { id: "proj_new", name: body.name, apiUrl: "https://proj_new.robodev.povio.dev" };
+    },
+    writeLink: async (link) => {
+      calls.writeLink += 1;
+      writtenLinks.push(link);
+    },
+    writeViteApiUrl: async () => {
+      calls.writeViteApiUrl += 1;
+    },
+    hasAppsFePackageJson: async () => false,
+    starbaseUrl: () => "https://robodev.povio.dev",
+    projectNameFromPath: () => "my-folder",
+    promptName: async () => {
+      calls.promptName += 1;
+      return "";
+    },
+    ...overrides,
+    ...(overrides.collectFiles
+      ? {
+          collectFiles: async (root: string) => {
+            calls.collectFiles += 1;
+            return overrides.collectFiles!(root);
+          },
+        }
+      : {}),
+    ...(overrides.ensureAuth
+      ? {
+          ensureAuth: async () => {
+            calls.ensureAuth += 1;
+            return overrides.ensureAuth!();
+          },
+        }
+      : {}),
+    ...(overrides.resolveOrganization
+      ? {
+          resolveOrganization: async (flagId: string | undefined) => {
+            calls.resolveOrganization += 1;
+            return overrides.resolveOrganization!(flagId);
+          },
+        }
+      : {}),
+    ...(overrides.createProject
+      ? {
+          createProject: async (body: { name: string; organizationId?: string }) => {
+            calls.createProject += 1;
+            createdBodies.push(body);
+            return overrides.createProject!(body);
+          },
+        }
+      : {}),
+    ...(overrides.writeLink
+      ? {
+          writeLink: async (link: ProjectLink, root: string) => {
+            calls.writeLink += 1;
+            writtenLinks.push(link);
+            return overrides.writeLink!(link, root);
+          },
+        }
+      : {}),
+    ...(overrides.writeViteApiUrl
+      ? {
+          writeViteApiUrl: async (url: string, root: string) => {
+            calls.writeViteApiUrl += 1;
+            return overrides.writeViteApiUrl!(url, root);
+          },
+        }
+      : {}),
+    ...(overrides.promptName
+      ? {
+          promptName: async (defaultName: string) => {
+            calls.promptName += 1;
+            return overrides.promptName!(defaultName);
+          },
+        }
+      : {}),
+  };
+}
+
+async function run(input: Partial<EnsureDeployLinkInput>, deps: ReturnType<typeof stubDeps>) {
+  return ensureDeployLink({ root: "/tmp/app", isTty: false, ...input }, deps);
+}
+
+test("ensureDeployLink returns an existing link and does not create again", async () => {
+  const deps = stubDeps({ readLink: async () => linked });
+  const result = await run({ name: "Ignored", orgId: "org_x", isTty: true }, deps);
+  assert.deepEqual(result, linked);
+  assert.equal(deps.calls.ensureAuth, 0);
+  assert.equal(deps.calls.collectFiles, 0);
+  assert.equal(deps.calls.createProject, 0);
+  assert.equal(deps.calls.writeLink, 0);
+  assert.equal(deps.calls.resolveOrganization, 0);
+});
+
+test("ensureDeployLink fails collect before creating a project", async () => {
+  const deps = stubDeps({
+    collectFiles: async () => {
+      throw new Error("database.ts not found (looked in robodev/database.ts and ./database.ts)");
+    },
+  });
+  await assert.rejects(() => run({ name: "Orbit", isTty: false }, deps), /database\.ts not found/);
+  assert.equal(deps.calls.ensureAuth, 1);
+  assert.equal(deps.calls.collectFiles, 1);
+  assert.equal(deps.calls.createProject, 0);
+  assert.equal(deps.calls.writeLink, 0);
+  assert.equal(deps.calls.resolveOrganization, 0);
+});
+
+test("ensureDeployLink non-TTY without --name exits without creating", async () => {
+  const deps = stubDeps();
+  await assert.rejects(() => run({ isTty: false }, deps), new Error(UNLINKED_NON_TTY_MESSAGE));
+  assert.equal(deps.calls.ensureAuth, 1);
+  assert.equal(deps.calls.collectFiles, 1);
+  assert.equal(deps.calls.createProject, 0);
+  assert.equal(deps.calls.writeLink, 0);
+  assert.equal(deps.calls.promptName, 0);
+  assert.equal(deps.calls.resolveOrganization, 0);
+});
+
+test("ensureDeployLink TTY prompts for name and writes the link before returning", async () => {
+  const deps = stubDeps({
+    promptName: async (defaultName) => {
+      assert.equal(defaultName, "my-folder");
+      return "";
+    },
+  });
+  const result = await run({ isTty: true }, deps);
+  assert.equal(deps.calls.promptName, 1);
+  assert.deepEqual(deps.createdBodies, [{ name: "my-folder" }]);
+  assert.equal(deps.calls.writeLink, 1);
+  assert.equal(deps.calls.writeViteApiUrl, 1);
+  assert.equal(deps.calls.createProject, 1);
+  assert.ok(deps.calls.writeLink >= 1);
+  assert.deepEqual(result, deps.writtenLinks[0]);
+  assert.equal(result.projectId, "proj_new");
+  assert.equal(result.frontend, undefined);
+});
+
+test("ensureDeployLink TTY uses a typed name and optional org", async () => {
+  const deps = stubDeps({
+    resolveOrganization: async (flagId) => flagId,
+    promptName: async () => "From prompt",
+  });
+  await run({ isTty: true, orgId: "org_2" }, deps);
+  assert.deepEqual(deps.createdBodies, [{ name: "From prompt", organizationId: "org_2" }]);
+});
+
+test("ensureDeployLink non-TTY with --name creates a name-only project", async () => {
+  const deps = stubDeps({
+    hasAppsFePackageJson: async () => true,
+  });
+  const result = await run({ isTty: false, name: "  Orbit  ", orgId: "org_1" }, deps);
+  assert.equal(deps.calls.promptName, 0);
+  assert.deepEqual(deps.createdBodies, [{ name: "Orbit", organizationId: "org_1" }]);
+  assert.equal("starterId" in deps.createdBodies[0], false);
+  assert.deepEqual(result.frontend, defaultFrontendConfig());
+  assert.equal(deps.calls.writeLink, 1);
+});
+
+test("ensureDeployLink auth failure happens before collect and create", async () => {
+  const deps = stubDeps({
+    ensureAuth: async () => {
+      throw new Error("Not authenticated. Run `robodev auth` first.");
+    },
+  });
+  await assert.rejects(() => run({ name: "Orbit", isTty: false }, deps), /Not authenticated/);
+  assert.equal(deps.calls.ensureAuth, 1);
+  assert.equal(deps.calls.collectFiles, 0);
+  assert.equal(deps.calls.createProject, 0);
+});

package/src/ensure-deploy-link.ts

@@ -0,0 +1,67 @@
+import { defaultFrontendConfig, type ProjectLink } from "./config.js";
+
+export type DeployProject = { id: string; name: string; apiUrl: string };
+
+export const UNLINKED_NON_TTY_MESSAGE =
+  "No robodev/.robodev file. Pass --name / --org or run `robodev link` or `robodev create`.";
+
+export type EnsureDeployLinkInput = {
+  root: string;
+  name?: string;
+  orgId?: string;
+  isTty: boolean;
+};
+
+export type EnsureDeployLinkDeps = {
+  readLink: (root: string) => Promise<ProjectLink | null>;
+  collectFiles: (root: string) => Promise<unknown>;
+  ensureAuth: () => Promise<void>;
+  resolveOrganization: (flagId: string | undefined) => Promise<string | undefined>;
+  createProject: (body: { name: string; organizationId?: string }) => Promise<DeployProject>;
+  writeLink: (link: ProjectLink, root: string) => Promise<void>;
+  writeViteApiUrl: (projectApiUrl: string, root: string) => Promise<void>;
+  hasAppsFePackageJson: (root: string) => Promise<boolean>;
+  starbaseUrl: () => string;
+  projectNameFromPath: (root: string) => string;
+  promptName: (defaultName: string) => Promise<string>;
+};
+
+function resolveProjectName(raw: string | undefined, fallback: string): string {
+  const trimmed = raw?.trim() ?? "";
+  return (trimmed || fallback).slice(0, 80);
+}
+
+/** Creates and writes a project link when the folder is not linked yet. */
+export async function ensureDeployLink(
+  input: EnsureDeployLinkInput,
+  deps: EnsureDeployLinkDeps,
+): Promise<ProjectLink> {
+  const existing = await deps.readLink(input.root);
+  if (existing) return existing;
+
+  await deps.ensureAuth();
+  await deps.collectFiles(input.root);
+
+  const flaggedName = input.name?.trim() ?? "";
+  if (!input.isTty && !flaggedName) {
+    throw new Error(UNLINKED_NON_TTY_MESSAGE);
+  }
+
+  const organizationId = await deps.resolveOrganization(input.orgId);
+  const defaultName = deps.projectNameFromPath(input.root);
+  const name = flaggedName
+    ? resolveProjectName(flaggedName, defaultName)
+    : resolveProjectName(await deps.promptName(defaultName), defaultName);
+
+  const project = await deps.createProject(organizationId ? { name, organizationId } : { name });
+  const wantFrontend = await deps.hasAppsFePackageJson(input.root);
+  const link: ProjectLink = {
+    projectId: project.id,
+    apiUrl: deps.starbaseUrl(),
+    projectApiUrl: project.apiUrl,
+    ...(wantFrontend ? { frontend: defaultFrontendConfig() } : {}),
+  };
+  await deps.writeLink(link, input.root);
+  await deps.writeViteApiUrl(project.apiUrl, input.root);
+  return link;
+}

package/src/index.ts

@@ -36,6 +36,8 @@ import {
   type Starter,
 } from "./emit-starter.js";
 import { parseCreateArgs } from "./parse-create-args.js";
+import { parseDeployArgs } from "./parse-deploy-args.js";
+import { ensureDeployLink } from "./ensure-deploy-link.js";
 import { printLiveUrl } from "./print-live-url.js";
 
 const execFileAsync = promisify(execFile);
@@ -50,9 +52,9 @@ Commands:
   logout               Remove stored credentials
   whoami               Show the signed-in user
   projects             List your projects
-  create [path] [--starter <id>] [--empty] [--org <id>]  Create a project, scaffold a starter, and deploy
+  create [path] [--template <id>] [--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)
+  deploy [--force] [--name <name>] [--org <id>]  Deploy schema, APIs, jobs, and frontend (creates and links if unlinked)
   dev [options]        Run this project's APIs locally on an embedded Postgres, no Starbase needed
 
 dev options:
@@ -247,12 +249,31 @@ async function collectDeployFiles(
 async function runDeploy(
   forceFlag: boolean,
   options: DeployOptions = {},
+  flags: { name?: string; orgId?: string } = {},
 ): Promise<string | undefined> {
   const root = options.root ?? process.cwd();
-  const link = await readLink(root);
-  if (!link) {
-    throw new Error("No robodev/.robodev file. Run `robodev link` or `robodev create` first.");
-  }
+  const link = await ensureDeployLink(
+    { root, name: flags.name, orgId: flags.orgId, isTty: Boolean(stdin.isTTY) },
+    {
+      readLink,
+      collectFiles,
+      ensureAuth: async () => {
+        await authed("/v1/auth/me");
+      },
+      resolveOrganization,
+      createProject: (body) =>
+        authed<Project>("/v1/projects", {
+          method: "POST",
+          body: JSON.stringify(body),
+        }),
+      writeLink,
+      writeViteApiUrl,
+      hasAppsFePackageJson,
+      starbaseUrl,
+      projectNameFromPath,
+      promptName: (defaultName) => prompt(`Project name [${defaultName}]: `),
+    },
+  );
   const files = await collectDeployFiles(root, link, options);
   let force = forceFlag;
 
@@ -376,40 +397,47 @@ async function resolveOrganization(flagId: string | undefined): Promise<string |
   return found.id;
 }
 
-async function resolveStarter(flagId: string | undefined): Promise<Starter> {
+async function resolveStarter(parsed: {
+  starterId?: string;
+  promptTemplate?: boolean;
+}): Promise<Starter> {
   const starters = await loadCatalog();
-  if (flagId !== undefined) {
-    const found = starters.find((starter) => starter.id === flagId);
+  if (parsed.starterId !== undefined) {
+    const found = starters.find((starter) => starter.id === parsed.starterId);
     if (!found) {
-      throw new Error(`Unknown starter "${flagId}". ${validIdsMessage(starters)}`);
+      throw new Error(`Unknown starter "${parsed.starterId}". ${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)}`);
+  if (parsed.promptTemplate) {
+    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;
     }
-    return found;
+    console.log("robodev create --template requires a starter id when stdin is not a TTY.");
+    usage();
   }
-  const space = starters.find((starter) => starter.id === "space");
-  if (!space) {
-    throw new Error(`Unknown starter "space". ${validIdsMessage(starters)}`);
+  const empty = starters.find((starter) => starter.id === "empty");
+  if (!empty) {
+    throw new Error(`Unknown starter "empty". ${validIdsMessage(starters)}`);
   }
-  return space;
+  return empty;
 }
 
 function projectNameFromPath(root: string): string {
@@ -507,7 +535,7 @@ function printFeNextSteps(displayPath: string, hosted: boolean): void {
 /** 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);
+  const starter = await resolveStarter(parsed);
   console.log(`Using starter ${starter.title} (${starter.id})`);
 
   const root = resolve(process.cwd(), parsed.path ?? ".");
@@ -602,7 +630,10 @@ async function runCreate(args: string[]): Promise<void> {
     if (displayPath !== ".") {
       console.log(`  cd ${displayPath}`);
     }
-    console.log("  npm run dev");
+    console.log("  The project App URL serves the hosted Welcome page.");
+    console.log("  Edit index.html and src/, then robodev deploy (or Code + Save).");
+    console.log("  robodev dev          # local APIs");
+    console.log("  npm run dev:fe       # optional local Vite");
   }
   if (liveUrl) {
     printLiveUrl(liveUrl);
@@ -631,9 +662,11 @@ async function main(): Promise<void> {
     case "link":
       await runLink(args[0]);
       break;
-    case "deploy":
-      await runDeploy(args.includes("--force"));
+    case "deploy": {
+      const parsed = parseDeployArgs(args);
+      await runDeploy(parsed.force, {}, { name: parsed.name, orgId: parsed.orgId });
       break;
+    }
     case "dev": {
       const { main: runDev } = await import("./dev.js");
       await runDev(args);

package/src/parse-create-args.test.ts

@@ -2,17 +2,86 @@ import assert from "node:assert/strict";
 import { test } from "node:test";
 import { parseCreateArgs } from "./parse-create-args.js";
 
-test("parseCreateArgs accepts --org with starter flags", () => {
+test("parseCreateArgs defaults to empty without a template flag", () => {
+  assert.deepEqual(parseCreateArgs([]), {
+    path: undefined,
+    starterId: "empty",
+    orgId: undefined,
+  });
+  assert.deepEqual(parseCreateArgs(["my-app"]), {
+    path: "my-app",
+    starterId: "empty",
+    orgId: undefined,
+  });
+});
+
+test("parseCreateArgs accepts --template and --starter with an id", () => {
+  assert.deepEqual(parseCreateArgs(["app", "--template", "space", "--org", "org_1"]), {
+    path: "app",
+    starterId: "space",
+    orgId: "org_1",
+  });
+  assert.deepEqual(parseCreateArgs(["--template=auth-chat"]), {
+    path: undefined,
+    starterId: "auth-chat",
+    orgId: undefined,
+  });
   assert.deepEqual(parseCreateArgs(["app", "--starter", "space", "--org", "org_1"]), {
     path: "app",
     starterId: "space",
     orgId: "org_1",
   });
+  assert.deepEqual(parseCreateArgs(["--starter=backend"]), {
+    path: undefined,
+    starterId: "backend",
+    orgId: undefined,
+  });
+});
+
+test("parseCreateArgs treats bare --template and --starter as a picker request", () => {
+  assert.deepEqual(parseCreateArgs(["--template"]), {
+    path: undefined,
+    starterId: undefined,
+    orgId: undefined,
+    promptTemplate: true,
+  });
+  assert.deepEqual(parseCreateArgs(["--template="]), {
+    path: undefined,
+    starterId: undefined,
+    orgId: undefined,
+    promptTemplate: true,
+  });
+  assert.deepEqual(parseCreateArgs(["my-app", "--template", "--org", "org_1"]), {
+    path: "my-app",
+    starterId: undefined,
+    orgId: "org_1",
+    promptTemplate: true,
+  });
+  assert.deepEqual(parseCreateArgs(["--starter"]), {
+    path: undefined,
+    starterId: undefined,
+    orgId: undefined,
+    promptTemplate: true,
+  });
+  assert.deepEqual(parseCreateArgs(["--starter="]), {
+    path: undefined,
+    starterId: undefined,
+    orgId: undefined,
+    promptTemplate: true,
+  });
+});
+
+test("parseCreateArgs treats --empty as empty", () => {
   assert.deepEqual(parseCreateArgs(["--empty", "--org=org_2"]), {
     path: undefined,
     starterId: "empty",
     orgId: "org_2",
   });
+  assert.deepEqual(parseCreateArgs(["--template", "empty"]), {
+    path: undefined,
+    starterId: "empty",
+    orgId: undefined,
+  });
 });
 
 test("parseCreateArgs rejects a missing --org value", () => {
@@ -21,6 +90,26 @@ test("parseCreateArgs rejects a missing --org value", () => {
   assert.throws(() => parseCreateArgs(["--org", "--empty"]), /Missing value for --org/);
 });
 
-test("parseCreateArgs rejects unknown flags including --organization", () => {
+test("parseCreateArgs rejects unknown flags including --organization and --empty=", () => {
   assert.throws(() => parseCreateArgs(["--organization", "org_1"]), /Unknown flag --organization/);
+  assert.throws(() => parseCreateArgs(["--empty=empty"]), /Unknown flag --empty=empty/);
+});
+
+test("parseCreateArgs rejects two starter selectors", () => {
+  assert.throws(
+    () => parseCreateArgs(["--empty", "--starter", "empty"]),
+    /Use only one of --empty, --template, or --starter\./,
+  );
+  assert.throws(
+    () => parseCreateArgs(["--empty", "--template", "empty"]),
+    /Use only one of --empty, --template, or --starter\./,
+  );
+  assert.throws(
+    () => parseCreateArgs(["--template", "space", "--starter", "space"]),
+    /Use only one of --empty, --template, or --starter\./,
+  );
+  assert.throws(
+    () => parseCreateArgs(["--template", "--empty"]),
+    /Use only one of --empty, --template, or --starter\./,
+  );
 });

package/src/parse-create-args.ts

@@ -1,31 +1,64 @@
-export type CreateArgs = { path?: string; starterId?: string; orgId?: string };
+export type CreateArgs = {
+  path?: string;
+  starterId?: string;
+  orgId?: string;
+  promptTemplate?: boolean;
+};
+
+function takeOptionalId(
+  args: string[],
+  i: number,
+): { value?: string; prompt: boolean; consumed: number } {
+  const next = args[i + 1];
+  if (!next || next.startsWith("-")) {
+    return { prompt: true, consumed: 0 };
+  }
+  return { value: next, prompt: false, consumed: 1 };
+}
 
 export function parseCreateArgs(args: string[]): CreateArgs {
   let path: string | undefined;
   let starterId: string | undefined;
   let orgId: string | undefined;
   let empty = false;
+  let sawTemplate = false;
+  let sawStarter = false;
+  let promptTemplate = false;
+
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     if (arg === "--empty") {
       empty = true;
       continue;
     }
+    if (arg === "--template") {
+      sawTemplate = true;
+      const taken = takeOptionalId(args, i);
+      if (taken.prompt) promptTemplate = true;
+      else starterId = taken.value;
+      i += taken.consumed;
+      continue;
+    }
+    if (arg.startsWith("--template=")) {
+      sawTemplate = true;
+      const value = arg.slice("--template=".length);
+      if (!value) promptTemplate = true;
+      else starterId = value;
+      continue;
+    }
     if (arg === "--starter") {
-      const value = args[i + 1];
-      if (!value || value.startsWith("-")) {
-        throw new Error("Missing value for --starter");
-      }
-      starterId = value;
-      i += 1;
+      sawStarter = true;
+      const taken = takeOptionalId(args, i);
+      if (taken.prompt) promptTemplate = true;
+      else starterId = taken.value;
+      i += taken.consumed;
       continue;
     }
     if (arg.startsWith("--starter=")) {
+      sawStarter = true;
       const value = arg.slice("--starter=".length);
-      if (!value) {
-        throw new Error("Missing value for --starter");
-      }
-      starterId = value;
+      if (!value) promptTemplate = true;
+      else starterId = value;
       continue;
     }
     if (arg === "--org") {
@@ -53,11 +86,15 @@ export function parseCreateArgs(args: string[]): CreateArgs {
     }
     path = arg;
   }
-  if (empty && starterId !== undefined) {
-    throw new Error("Use either --empty or --starter, not both.");
+
+  const selectors = Number(empty) + Number(sawTemplate) + Number(sawStarter);
+  if (selectors > 1) {
+    throw new Error("Use only one of --empty, --template, or --starter.");
   }
   if (empty) {
     starterId = "empty";
+  } else if (!sawTemplate && !sawStarter) {
+    starterId = "empty";
   }
-  return { path, starterId, orgId };
+  return { path, starterId, orgId, ...(promptTemplate ? { promptTemplate: true } : {}) };
 }

package/src/parse-deploy-args.test.ts

@@ -0,0 +1,37 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { parseDeployArgs } from "./parse-deploy-args.js";
+
+test("parseDeployArgs accepts --force --name and --org", () => {
+  assert.deepEqual(parseDeployArgs([]), { force: false, name: undefined, orgId: undefined });
+  assert.deepEqual(parseDeployArgs(["--force"]), {
+    force: true,
+    name: undefined,
+    orgId: undefined,
+  });
+  assert.deepEqual(parseDeployArgs(["--name", "Orbit", "--org", "org_1"]), {
+    force: false,
+    name: "Orbit",
+    orgId: "org_1",
+  });
+  assert.deepEqual(parseDeployArgs(["--name=Orbit", "--org=org_2", "--force"]), {
+    force: true,
+    name: "Orbit",
+    orgId: "org_2",
+  });
+});
+
+test("parseDeployArgs rejects a missing --name or --org value", () => {
+  assert.throws(() => parseDeployArgs(["--name"]), /Missing value for --name/);
+  assert.throws(() => parseDeployArgs(["--name="]), /Missing value for --name/);
+  assert.throws(() => parseDeployArgs(["--name", "--force"]), /Missing value for --name/);
+  assert.throws(() => parseDeployArgs(["--org"]), /Missing value for --org/);
+  assert.throws(() => parseDeployArgs(["--org="]), /Missing value for --org/);
+  assert.throws(() => parseDeployArgs(["--org", "--name", "x"]), /Missing value for --org/);
+});
+
+test("parseDeployArgs rejects unknown flags the same way as create", () => {
+  assert.throws(() => parseDeployArgs(["--organization", "org_1"]), /Unknown flag --organization/);
+  assert.throws(() => parseDeployArgs(["--empty"]), /Unknown flag --empty/);
+  assert.throws(() => parseDeployArgs(["my-app"]), /Unexpected argument my-app/);
+});

package/src/parse-deploy-args.ts

@@ -0,0 +1,53 @@
+export type DeployArgs = { force: boolean; name?: string; orgId?: string };
+
+export function parseDeployArgs(args: string[]): DeployArgs {
+  let force = false;
+  let name: string | undefined;
+  let orgId: string | undefined;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--force") {
+      force = true;
+      continue;
+    }
+    if (arg === "--name") {
+      const value = args[i + 1];
+      if (!value || value.startsWith("-")) {
+        throw new Error("Missing value for --name");
+      }
+      name = value;
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith("--name=")) {
+      const value = arg.slice("--name=".length);
+      if (!value) {
+        throw new Error("Missing value for --name");
+      }
+      name = value;
+      continue;
+    }
+    if (arg === "--org") {
+      const value = args[i + 1];
+      if (!value || value.startsWith("-")) {
+        throw new Error("Missing value for --org");
+      }
+      orgId = value;
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith("--org=")) {
+      const value = arg.slice("--org=".length);
+      if (!value) {
+        throw new Error("Missing value for --org");
+      }
+      orgId = value;
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      throw new Error(`Unknown flag ${arg}`);
+    }
+    throw new Error(`Unexpected argument ${arg}`);
+  }
+  return { force, name, orgId };
+}

package/templates/auth-chat/package.json

@@ -12,7 +12,7 @@
     "@robodev-ai/sdk": "^0.13.0"
   },
   "devDependencies": {
-    "robodev": "^0.38.1",
+    "robodev": "^0.40.0",
     "rulesync": "^8.18.0",
     "typescript": "^5.9.2"
   }

package/templates/backend/package.json

@@ -11,7 +11,7 @@
     "@robodev-ai/sdk": "^0.13.0"
   },
   "devDependencies": {
-    "robodev": "^0.38.1",
+    "robodev": "^0.40.0",
     "typescript": "^5.9.2"
   }
 }

package/templates/catalog.json

@@ -24,8 +24,7 @@
     {
       "id": "empty",
       "title": "Empty",
-      "description": "Blank database.ts and GET /api/health — no sample schema or UI. For Lovable, Bolt, or v0",
-      "kind": "backend"
+      "description": "Blank database.ts and GET /api/health plus a hosted Welcome page. No sample schema."
     }
   ]
 }

package/templates/empty/README.md

@@ -1,15 +1,17 @@
 # {{NAME}}
 
-Blank `robodev/database.ts` and `GET /api/health` — no sample schema or UI. For Lovable, Bolt, or v0.
+Blank `robodev/database.ts` and `GET /api/health` plus a hosted Welcome page. No sample schema.
 
-Deploy `robodev/database.ts` and `robodev/api/` from a real terminal:
+The project App URL serves the hosted Welcome page. Edit `index.html` and `src/`, then `robodev deploy` (or Code + Save).
 
 ```bash
-npx robodev deploy
+robodev create my-app
+robodev dev          # local APIs
+npm run dev:fe       # optional local Vite
 ```
 
-Build the UI elsewhere against `VITE_API_URL` (written to `.env` by `robodev create` / `robodev link`). Paste that URL into the frontend tool.
+`robodev create` (TTY and non-TTY) uses this starter by default. Pass `--template space` for Space. Lovable, Bolt, or v0 should use `--template backend`.
 
-Do not run `npm run dev` or `npm run build` in this folder. Do not run `robodev` (auth, create, deploy) or `npm run build` inside Lovable, Bolt, or v0 — those tools cannot complete loopback OAuth and must not treat this folder as a Vite app.
+Do not write a `frontend` block in `robodev/.robodev` — that block is for Tiny `apps/fe`. Root `index.html` + `src/` deploy as hosted React.
 
-Frontend how-to: https://robodev.povio.dev/docs/frontend
+Docs: https://robodev.povio.dev/docs

package/templates/empty/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{NAME}}</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/empty/package.json

@@ -5,13 +5,19 @@
   "type": "module",
   "scripts": {
     "dev": "robodev dev",
-    "deploy": "robodev deploy"
+    "deploy": "robodev deploy",
+    "dev:fe": "vite",
+    "build": "vite build"
   },
   "dependencies": {
-    "@robodev-ai/sdk": "^0.13.0"
+    "@robodev-ai/sdk": "^0.13.0",
+    "@robodev-ai/client": "^0.5.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
   },
   "devDependencies": {
-    "robodev": "^0.38.1",
-    "typescript": "^5.9.2"
+    "robodev": "^0.40.0",
+    "typescript": "^5.9.2",
+    "vite": "^6.0.0"
   }
 }

package/templates/empty/src/App.tsx

@@ -0,0 +1,8 @@
+export function App() {
+  return (
+    <main>
+      <h1>Welcome</h1>
+      <p>Your app is ready.</p>
+    </main>
+  );
+}

package/templates/empty/src/app.css

@@ -0,0 +1,10 @@
+:root {
+  color: #111;
+  font-family: system-ui, sans-serif;
+}
+body {
+  margin: 0;
+}
+main {
+  padding: 2rem;
+}

package/templates/empty/src/main.tsx

@@ -0,0 +1,5 @@
+import { createRoot } from "react-dom/client";
+import { App } from "./App";
+import "./app.css";
+
+createRoot(document.getElementById("root")!).render(<App />);

package/templates/empty/tsconfig.json

@@ -3,9 +3,10 @@
     "target": "ES2022",
     "module": "ESNext",
     "moduleResolution": "bundler",
+    "jsx": "react-jsx",
     "strict": true,
     "skipLibCheck": true,
     "noEmit": true
   },
-  "include": ["robodev/**/*.ts"]
+  "include": ["robodev/**/*.ts", "src"]
 }

package/templates/empty/vite.config.ts

@@ -0,0 +1,5 @@
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  esbuild: { jsx: "automatic" },
+});

package/templates/marketplace/package.json

@@ -12,7 +12,7 @@
     "@robodev-ai/sdk": "^0.13.0"
   },
   "devDependencies": {
-    "robodev": "^0.38.1",
+    "robodev": "^0.40.0",
     "rulesync": "^8.18.0",
     "typescript": "^5.9.2"
   }

package/templates/space/package.json

@@ -12,7 +12,7 @@
     "@robodev-ai/sdk": "^0.13.0"
   },
   "devDependencies": {
-    "robodev": "^0.38.1",
+    "robodev": "^0.40.0",
     "rulesync": "^8.18.0",
     "typescript": "^5.9.2"
   }