robodev 0.45.1 → 0.46.0

package/package.json

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

package/src/api.ts

@@ -67,3 +67,16 @@ export async function authed<T>(path: string, init: RequestInit = {}): Promise<T
 export async function publicRequest<T>(path: string, init: RequestInit = {}): Promise<T> {
   return request<T>(path, init, null, false);
 }
+
+/**
+ * Starbase request authenticated by a project deploy key. Deploy keys ride the same bearer header
+ * as a user token and are told apart by their prefix, so this is the headless path for an agent
+ * runner that has no browser to complete `robodev auth` with.
+ */
+export async function deployKeyRequest<T>(
+  path: string,
+  deployKey: string,
+  init: RequestInit = {},
+): Promise<T> {
+  return request<T>(path, init, { accessToken: deployKey, refreshToken: "" }, false);
+}

package/src/collect-files.ts

@@ -72,6 +72,13 @@ const CONFIG_FILES = new Set([
   "vite.config.js",
   "vite.config.mts",
   "vite.config.mjs",
+  "orval.config.ts",
+  "orval.config.js",
+  "components.json",
+  "tailwind.config.ts",
+  "tailwind.config.js",
+  "postcss.config.js",
+  "postcss.config.cjs",
   "README.md",
   ".gitignore",
 ]);

package/src/config.ts

@@ -10,6 +10,7 @@ export type Credentials = {
 export type FrontendConfig = {
   root: string;
   script?: string;
+  preview?: string;
   outDir: string;
 };
 

package/src/emit-starter.test.ts

@@ -154,6 +154,64 @@ test("collectFiles for empty starter includes hosted Welcome source", async () =
   assert.ok(files.length < 200);
 });
 
+test("emitStarter shadcn includes hosted Welcome plus orval and shadcn files", async () => {
+  const dest = await mkdtemp(join(tmpdir(), "rd-emit-"));
+  try {
+    await emitStarter(join(cliRoot(), "..", "starters", "shadcn"), dest, {
+      name: "Kit",
+      packageName: "kit-app",
+      title: "Shadcn",
+      versions,
+    });
+    const index = await readFile(join(dest, "index.html"), "utf8");
+    assert.match(index, /<title>Kit<\/title>/);
+    assert.match(index, /src\/main\.tsx/);
+    const app = await readFile(join(dest, "src/App.tsx"), "utf8");
+    assert.match(app, /<h1>Welcome<\/h1>/);
+    assert.doesNotMatch(app, /<h1>Kit<\/h1>/);
+    assert.match(app, /getHealth/);
+    const endpoints = await readFile(join(dest, "src/api/generated/endpoints.ts"), "utf8");
+    assert.match(endpoints, /export const getHealth/);
+    assert.doesNotMatch(endpoints, /axios|@tanstack\/react-query/);
+    const pkg = JSON.parse(await readFile(join(dest, "package.json"), "utf8")) as {
+      name: string;
+      scripts?: Record<string, string>;
+      dependencies?: Record<string, string>;
+      devDependencies?: Record<string, string>;
+    };
+    assert.equal(pkg.name, "kit-app");
+    assert.equal(pkg.scripts?.dev, "robodev dev");
+    assert.equal(pkg.scripts?.["dev:fe"], "vite");
+    assert.equal(pkg.scripts?.["generate:api"], "orval");
+    assert.equal(pkg.dependencies?.["@robodev-ai/client"], "^0.12.0");
+    assert.match(pkg.devDependencies?.orval ?? "", /^\^/);
+    const readme = await readFile(join(dest, "README.md"), "utf8");
+    assert.match(readme, /^# Kit/m);
+    assert.doesNotMatch(readme, /frontend block in `robodev\/\.robodev` is required/);
+  } finally {
+    await rm(dest, { recursive: true, force: true });
+  }
+});
+
+test("collectFiles for shadcn starter includes hosted Welcome and tooling configs", async () => {
+  const files = await collectFiles(join(cliRoot(), "..", "starters", "shadcn"));
+  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("src/components/ui/button.tsx"));
+  assert.ok(paths.has("src/api/generated/endpoints.ts"));
+  assert.ok(paths.has("src/api/openapi.json"));
+  assert.ok(paths.has("orval.config.ts"));
+  assert.ok(paths.has("components.json"));
+  assert.ok(paths.has("tailwind.config.ts"));
+  assert.ok(paths.has("postcss.config.js"));
+  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/index.ts

@@ -46,6 +46,7 @@ import { parseCreateArgs } from "./parse-create-args.js";
 import { parseDeployArgs } from "./parse-deploy-args.js";
 import { ensureDeployLink } from "./ensure-deploy-link.js";
 import { runLoad } from "./load.js";
+import { runMcp } from "./mcp.js";
 import { printLiveUrl } from "./print-live-url.js";
 
 const execFileAsync = promisify(execFile);
@@ -65,6 +66,7 @@ Commands:
   deploy [--force] [--name <name>] [--org <id>]  Deploy schema, APIs, jobs, and frontend (creates and links if unlinked)
   load                 Download the project source onto this folder
   dev [options]        Run this project's APIs locally on an embedded Postgres, no Starbase needed
+  mcp [--project <id>] Serve this project's backend over MCP on stdio, for an external coding agent
 
 dev options:
   --port <n>           API port (default 4000)
@@ -682,6 +684,9 @@ async function runCreate(args: string[]): Promise<void> {
     console.log("  Edit index.html and src/, then robodev deploy (or Code + Save).");
     console.log("  robodev dev          # local APIs");
     console.log("  pnpm run dev:fe      # optional local Vite");
+    if (starter.id === "shadcn") {
+      console.log("  pnpm run generate:api  # regenerate the orval client");
+    }
   }
   if (liveUrl) {
     printLiveUrl(liveUrl);
@@ -723,6 +728,9 @@ async function main(): Promise<void> {
       await runDev(args);
       break;
     }
+    case "mcp":
+      await runMcp(args);
+      break;
     default:
       usage();
   }

package/src/mcp-protocol.ts

@@ -0,0 +1,120 @@
+/**
+ * The MCP stdio wire format, hand-rolled.
+ *
+ * `robodev` is installed globally by people who just want a CLI, so the surface it needs from MCP
+ * — `initialize`, `tools/list`, `tools/call`, `ping` over newline-delimited JSON-RPC 2.0 on
+ * stdio — is not worth a dependency on the SDK in a published package. Everything here is pure so
+ * the protocol can be tested without a transport.
+ */
+
+export const MCP_PROTOCOL_VERSION = "2025-06-18";
+export const SUPPORTED_PROTOCOL_VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"] as const;
+
+export const JSON_RPC_VERSION = "2.0";
+export const PARSE_ERROR = -32700;
+export const INVALID_REQUEST = -32600;
+export const METHOD_NOT_FOUND = -32601;
+export const INVALID_PARAMS = -32602;
+export const INTERNAL_ERROR = -32603;
+
+export type JsonRpcId = string | number;
+
+export type JsonRpcRequest = {
+  jsonrpc: string;
+  id?: JsonRpcId;
+  method: string;
+  params?: Record<string, unknown>;
+};
+
+export type JsonRpcResponse = {
+  jsonrpc: string;
+  id: JsonRpcId;
+  result?: unknown;
+  error?: { code: number; message: string; data?: unknown };
+};
+
+export type McpToolSchema = {
+  name: string;
+  title: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+};
+
+export function parseMessage(line: string): JsonRpcRequest | null {
+  const trimmed = line.trim();
+  if (!trimmed) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+  const record = parsed as Record<string, unknown>;
+  if (typeof record.method !== "string") return null;
+  const request: JsonRpcRequest = {
+    jsonrpc: typeof record.jsonrpc === "string" ? record.jsonrpc : JSON_RPC_VERSION,
+    method: record.method,
+  };
+  if (typeof record.id === "string" || typeof record.id === "number") request.id = record.id;
+  if (record.params && typeof record.params === "object" && !Array.isArray(record.params)) {
+    request.params = record.params as Record<string, unknown>;
+  }
+  return request;
+}
+
+export function success(id: JsonRpcId, result: unknown): JsonRpcResponse {
+  return { jsonrpc: JSON_RPC_VERSION, id, result };
+}
+
+export function failure(
+  id: JsonRpcId,
+  code: number,
+  message: string,
+  data?: unknown,
+): JsonRpcResponse {
+  return { jsonrpc: JSON_RPC_VERSION, id, error: { code, message, ...(data ? { data } : {}) } };
+}
+
+/** Echo a version the client asked for when it is one we speak; otherwise offer ours. */
+export function negotiateProtocolVersion(requested: unknown): string {
+  if (typeof requested !== "string") return MCP_PROTOCOL_VERSION;
+  return (SUPPORTED_PROTOCOL_VERSIONS as readonly string[]).includes(requested)
+    ? requested
+    : MCP_PROTOCOL_VERSION;
+}
+
+export function initializeResult(input: {
+  requestedProtocolVersion?: unknown;
+  serverName: string;
+  serverVersion: string;
+  instructions?: string;
+}): Record<string, unknown> {
+  return {
+    protocolVersion: negotiateProtocolVersion(input.requestedProtocolVersion),
+    capabilities: { tools: { listChanged: false } },
+    serverInfo: { name: input.serverName, version: input.serverVersion },
+    ...(input.instructions ? { instructions: input.instructions } : {}),
+  };
+}
+
+/** A tools/call result. MCP reports tool-level failure in the payload, not as a JSON-RPC error. */
+export function toolResult(text: string, isError = false): Record<string, unknown> {
+  return { content: [{ type: "text", text }], isError };
+}
+
+/** A notification carries no id and must never be answered. */
+export function isNotification(request: JsonRpcRequest): boolean {
+  return request.id === undefined;
+}
+
+/** Splits a stdin chunk into complete lines, returning the incomplete remainder. */
+export function takeCompleteLines(
+  buffer: string,
+  chunk: string,
+): { lines: string[]; buffer: string } {
+  const combined = `${buffer}${chunk}`;
+  const parts = combined.split("\n");
+  const remainder = parts.pop() ?? "";
+  return { lines: parts.filter((line) => line.trim().length > 0), buffer: remainder };
+}

package/src/mcp-tools.ts

@@ -0,0 +1,178 @@
+import { mapPackagesBePath, normalizeDeployPath } from "@robodev-ai/runtime";
+import type { McpToolSchema } from "./mcp-protocol.js";
+
+/**
+ * The tool surface an external coding agent needs to work on a Robodev backend: see what is live,
+ * read one file, and push a file it just wrote. Frontend files are out of scope here — a hosted
+ * frontend is a built artifact, so it goes through `robodev deploy`.
+ */
+export const MCP_SERVER_INSTRUCTIONS = `Publish backend files to a live Robodev project.
+
+Write a file locally, then call publish_backend_file with its path and content — it merges over the
+live deployment and redeploys, so the route is live when the call returns. Only backend paths are
+accepted: database.ts, api/**, jobs/**, hooks/**, sockets/** and backend config such as
+package.json. Adding or changing a table means publishing database.ts too; the schema is
+reconciled on publish, and a destructive change needs force: true.
+
+Use list_backend_files and read_backend_file to see what is already deployed before overwriting it.
+Frontend files are not publishable here — run \`robodev deploy\` for those.`;
+
+const FILE_PROPERTIES = {
+  path: {
+    type: "string",
+    description:
+      "Project-relative backend path. Either layout works: a Tiny workspace path such as packages/be/api/todos.ts, or the deployed path api/todos.ts.",
+  },
+  content: { type: "string", description: "Full file content. This replaces the live file." },
+} as const;
+
+export const MCP_TOOLS: McpToolSchema[] = [
+  {
+    name: "publish_backend_file",
+    title: "Publish one backend file",
+    description:
+      "Write one backend file to the live project and redeploy. The rest of the live tree is kept, so only the file being changed has to be sent. Returns the live API and docs URLs.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        ...FILE_PROPERTIES,
+        force: {
+          type: "boolean",
+          description:
+            "Allow a destructive schema change (a dropped table or column). Off by default.",
+        },
+      },
+      required: ["path", "content"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "publish_backend_files",
+    title: "Publish several backend files",
+    description:
+      "Same as publish_backend_file for a batch — one deploy for the whole set, which is what you want when a route and database.ts change together. At most 50 files.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        files: {
+          type: "array",
+          minItems: 1,
+          maxItems: 50,
+          items: {
+            type: "object",
+            properties: FILE_PROPERTIES,
+            required: ["path", "content"],
+            additionalProperties: false,
+          },
+        },
+        force: {
+          type: "boolean",
+          description:
+            "Allow a destructive schema change (a dropped table or column). Off by default.",
+        },
+      },
+      required: ["files"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "list_backend_files",
+    title: "List live backend files",
+    description:
+      "The backend files currently deployed, with their sizes. Use it before overwriting a file you have not read.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  },
+  {
+    name: "read_backend_file",
+    title: "Read a live backend file",
+    description: "The current content of one deployed backend file.",
+    inputSchema: {
+      type: "object",
+      properties: { path: FILE_PROPERTIES.path },
+      required: ["path"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "project_info",
+    title: "Project info",
+    description:
+      "The linked project's id and its live API, app and docs URLs, plus how this server authenticated.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  },
+];
+
+export type PublishFile = { path: string; content: string };
+
+export function parsePublishFile(value: unknown): PublishFile | string {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return "Each file must be an object with `path` and `content`.";
+  }
+  const record = value as Record<string, unknown>;
+  const path = typeof record.path === "string" ? record.path.trim() : "";
+  if (!path) return "`path` is required and must be a non-empty string.";
+  if (typeof record.content !== "string") return `\`content\` is required for ${path}.`;
+  return { path: normalizeDeployPath(path), content: record.content };
+}
+
+export function parsePublishFiles(value: unknown): PublishFile[] | string {
+  if (!Array.isArray(value)) return "`files` must be an array.";
+  if (value.length === 0) return "`files` must contain at least one file.";
+  if (value.length > 50) return "`files` accepts at most 50 files per publish.";
+  const files: PublishFile[] = [];
+  for (const entry of value) {
+    const parsed = parsePublishFile(entry);
+    if (typeof parsed === "string") return parsed;
+    files.push(parsed);
+  }
+  return files;
+}
+
+/**
+ * The deploy path a workspace path lands on. A Tiny project keeps its backend under
+ * `packages/be/`, and the deployed tree does not, so `packages/be/api/todos.ts` and the live
+ * `api/todos.ts` are the same file. Mirrors the server's mapping so reads line up with publishes.
+ */
+export function deployPathFor(path: string): string {
+  return mapPackagesBePath(path) ?? normalizeDeployPath(path);
+}
+
+/** Backend paths only. Mirrors the server's own check so an agent gets the reason locally. */
+export function backendPathError(path: string): string | null {
+  const normalized = normalizeDeployPath(path);
+  if (normalized.startsWith("apps/") || normalized === "apps") {
+    return `${normalized} is frontend source. Publish the frontend with \`robodev deploy\`.`;
+  }
+  if (normalized.startsWith("src/") || normalized === "index.html") {
+    return `${normalized} is a hosted frontend file. Publish the frontend with \`robodev deploy\`.`;
+  }
+  if (normalized.startsWith("public/")) {
+    return `${normalized} is a static asset. Publish it with \`robodev deploy\`.`;
+  }
+  return null;
+}
+
+export function formatFileList(files: readonly PublishFile[]): string {
+  if (files.length === 0) {
+    return "No backend files are deployed yet. Run `robodev deploy` once to create the project's first deployment.";
+  }
+  const rows = files
+    .slice()
+    .sort((a, b) => a.path.localeCompare(b.path))
+    .map((file) => `${file.path} (${Buffer.byteLength(file.content, "utf8")} bytes)`);
+  return `${files.length} backend file${files.length === 1 ? "" : "s"} live:\n${rows.join("\n")}`;
+}
+
+export function formatPublishResult(input: {
+  published: readonly string[];
+  apiUrl?: string;
+  docsUrl?: string;
+}): string {
+  const lines = [
+    `Published ${input.published.length} file${input.published.length === 1 ? "" : "s"} and redeployed:`,
+    ...input.published.map((path) => `  ${path}`),
+  ];
+  if (input.apiUrl) lines.push(`Live API: ${input.apiUrl}`);
+  if (input.docsUrl) lines.push(`Swagger: ${input.docsUrl}`);
+  return lines.join("\n");
+}