feat: local dev agents — project detection, agent team, dev server preview

apps/mesh/src/api/app.ts

@@ -47,6 +47,7 @@ import proxyRoutes from "./routes/proxy";
 import { createKVRoutes } from "./routes/kv";
 import { createTriggerCallbackRoutes } from "./routes/trigger-callback";
 import publicConfigRoutes from "./routes/public-config";
+import projectRoutes from "./routes/project";
 import filesRoutes from "./routes/files";
 import selfRoutes from "./routes/self";
 import { shouldSkipMeshContext, SYSTEM_PATHS } from "./utils/paths";
@@ -566,6 +567,7 @@ export async function createApp(options: CreateAppOptions = {}) {
   // Public Configuration (no auth required)
   // ============================================================================
   app.route("/api/config", publicConfigRoutes);
+  app.route("/api/project", projectRoutes);
 
   // ============================================================================
   // Better Auth Routes

apps/mesh/src/api/routes/project.ts

@@ -0,0 +1,143 @@
+/**
+ * Project API Routes
+ *
+ * Exposes project scan results and dev server control endpoints.
+ * Only available in local mode when a project directory is detected.
+ */
+
+import { Hono } from "hono";
+import { getScanResult } from "@/project/state";
+import {
+  getDevServerState,
+  startProjectDevServer,
+  stopProjectDevServer,
+  restartProjectDevServer,
+} from "@/project/dev-server";
+
+const app = new Hono();
+
+/**
+ * GET /api/project
+ * Returns project scan result and dev server state
+ */
+app.get("/", (c) => {
+  const scan = getScanResult();
+  if (!scan) {
+    return c.json({ success: false, error: "No project detected" }, 404);
+  }
+
+  return c.json({
+    success: true,
+    scan,
+    devServer: getDevServerState(),
+  });
+});
+
+/**
+ * GET /api/project/dev-server
+ * Returns just the dev server state (for lightweight polling)
+ */
+app.get("/dev-server", (c) => {
+  return c.json({
+    success: true,
+    devServer: getDevServerState(),
+  });
+});
+
+/**
+ * POST /api/project/dev-server/start
+ * Starts the project dev server
+ */
+app.post("/dev-server/start", async (c) => {
+  const scan = getScanResult();
+  if (!scan) {
+    return c.json({ success: false, error: "No project detected" }, 404);
+  }
+
+  await startProjectDevServer(scan);
+  return c.json({ success: true, devServer: getDevServerState() });
+});
+
+/**
+ * POST /api/project/dev-server/stop
+ * Stops the project dev server
+ */
+app.post("/dev-server/stop", async (c) => {
+  await stopProjectDevServer();
+  return c.json({ success: true, devServer: getDevServerState() });
+});
+
+/**
+ * POST /api/project/dev-server/restart
+ * Restarts the project dev server
+ */
+app.post("/dev-server/restart", async (c) => {
+  await restartProjectDevServer();
+  return c.json({ success: true, devServer: getDevServerState() });
+});
+
+/**
+ * GET /api/project/dev-server/logs
+ * Returns dev server logs
+ */
+app.get("/dev-server/logs", (c) => {
+  const state = getDevServerState();
+  return c.json({ success: true, logs: state.logs });
+});
+
+/**
+ * Reverse proxy to the project dev server, stripping frame-blocking headers.
+ * This allows the preview iframe to load the dev server content.
+ * Handles both /api/project/preview and /api/project/preview/* paths.
+ */
+app.all("/preview", (c) => handlePreviewProxy(c));
+app.all("/preview/*", (c) => handlePreviewProxy(c));
+
+async function handlePreviewProxy(c: {
+  req: { path: string; url: string; method: string; raw: Request };
+  text: (body: string, status: number) => Response;
+}) {
+  const devServer = getDevServerState();
+  if (!devServer.url) {
+    return c.text("Dev server not running", 503);
+  }
+
+  // Reconstruct the target URL from the wildcard path
+  const path = c.req.path.replace(/^\/api\/project\/preview\/?/, "/");
+  const targetUrl = new URL(path || "/", devServer.url);
+
+  // Forward query string
+  const reqUrl = new URL(c.req.url);
+  targetUrl.search = reqUrl.search;
+
+  try {
+    const headers = new Headers(c.req.raw.headers);
+    // Remove host header to avoid conflicts
+    headers.delete("host");
+
+    const response = await fetch(targetUrl.toString(), {
+      method: c.req.method,
+      headers,
+      body:
+        c.req.method !== "GET" && c.req.method !== "HEAD"
+          ? c.req.raw.body
+          : undefined,
+      redirect: "manual",
+    });
+
+    // Clone response and strip frame-blocking headers
+    const responseHeaders = new Headers(response.headers);
+    responseHeaders.delete("x-frame-options");
+    responseHeaders.delete("content-security-policy");
+
+    return new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: responseHeaders,
+    });
+  } catch {
+    return c.text("Failed to proxy to dev server", 502);
+  }
+}
+
+export default app;

apps/mesh/src/api/routes/public-config.ts

@@ -6,6 +6,7 @@
  */
 
 import { Hono } from "hono";
+import { basename } from "path";
 import { getConfig, getThemeConfig, type ThemeConfig } from "@/core/config";
 import { isLocalMode } from "@/auth/local-mode";
 import { getInternalUrl } from "@/core/server-constants";
@@ -43,6 +44,15 @@ export type PublicConfig = {
    * Requires FIRECRAWL_API_KEY to be configured.
    */
   brandExtractEnabled?: boolean;
+  /**
+   * Absolute path to the user's project directory.
+   * Only set in local mode when running inside a project.
+   */
+  projectDir?: string;
+  /**
+   * Human-readable project name (basename of projectDir).
+   */
+  projectName?: string;
 };
 
 /**
@@ -61,6 +71,11 @@ app.get("/", (c) => {
     ...(isLocalMode() && { internalUrl: getInternalUrl() }),
     ...(getSettings().enableDecoImport && { enableDecoImport: true }),
     brandExtractEnabled: !!getSettings().firecrawlApiKey,
+    ...(isLocalMode() &&
+      getSettings().projectDir != null && {
+        projectDir: getSettings().projectDir as string,
+        projectName: basename(getSettings().projectDir as string),
+      }),
   };
 
   return c.json({ success: true, config });

apps/mesh/src/cli.ts

@@ -15,6 +15,18 @@
 import { parseArgs } from "util";
 import { homedir } from "os";
 import { join } from "path";
+import { existsSync } from "fs";
+
+/** Check if a directory contains a project marker (package.json, deno.json, etc.) */
+function detectProjectDir(dir: string): string | undefined {
+  const markers = ["package.json", "deno.json", "deno.jsonc"];
+  for (const marker of markers) {
+    if (existsSync(join(dir, marker))) {
+      return dir;
+    }
+  }
+  return undefined;
+}
 
 const { values, positionals } = parseArgs({
   args: process.argv.slice(2),
@@ -60,6 +72,9 @@ const { values, positionals } = parseArgs({
       type: "string",
       default: "1",
     },
+    project: {
+      type: "string",
+    },
     vibe: {
       type: "boolean",
       default: false,
@@ -94,6 +109,7 @@ Server Options:
 Dev Options:
   --vite-port <port>    Vite dev server port (default: 4000)
   --base-url <url>      Base URL for the server
+  --project <path>      Project directory to manage (default: auto-detect CWD)
 
 Environment Variables:
   PORT                  Port to listen on (default: 3000)
@@ -203,6 +219,7 @@ if (command === "dev") {
     skipMigrations: values["skip-migrations"] === true,
     noTui,
     localMode: values["no-local-mode"] !== true,
+    projectDir: values.project || detectProjectDir(process.cwd()),
   };
 
   if (noTui) {
@@ -270,6 +287,7 @@ const serveOptions = {
     const n = Number(values["num-threads"]);
     return Number.isInteger(n) && n > 0 ? n : 1;
   })(),
+  projectDir: values.project || detectProjectDir(process.cwd()),
 };
 
 const noTui = values["no-tui"] === true || !process.stdout.isTTY;

apps/mesh/src/cli/commands/dev.ts

@@ -25,6 +25,7 @@ export interface DevOptions {
   skipMigrations: boolean;
   noTui?: boolean;
   localMode: boolean;
+  projectDir?: string;
 }
 
 // Strip ANSI escape codes from a string
@@ -102,6 +103,7 @@ export async function startDevServer(
     skipMigrations: options.skipMigrations,
     noTui: options.noTui,
     vitePort: options.vitePort,
+    projectDir: options.projectDir,
   });
 
   for (const s of services) {
@@ -130,6 +132,9 @@ export async function startDevServer(
       DECOCMS_HOME: settings.dataDir,
       DATA_DIR: settings.dataDir,
       DECO_CLI: "1",
+      ...(settings.projectDir
+        ? { DECOCMS_PROJECT_DIR: settings.projectDir }
+        : {}),
       ...(settings.baseUrl ? { BASE_URL: settings.baseUrl } : {}),
     },
     stdio: [

apps/mesh/src/cli/commands/serve.ts

@@ -25,6 +25,7 @@ export interface ServeOptions {
   localMode: boolean;
   noTui?: boolean;
   numThreads?: number;
+  projectDir?: string;
 }
 
 // Strip ANSI escape codes from a string
@@ -143,6 +144,7 @@ export async function startServer(options: ServeOptions): Promise<void> {
     skipMigrations: options.skipMigrations,
     noTui: options.noTui,
     nodeEnv: "production",
+    projectDir: options.projectDir,
   });
 
   for (const s of services) {

apps/mesh/src/index.ts

@@ -125,6 +125,43 @@ if (settings.localMode && !isWorker) {
       try {
         const seeded = await seedLocalMode();
         void seeded;
+
+        // Bootstrap project agents if running in a project directory
+        if (settings.projectDir) {
+          try {
+            const { getDb } = await import("./database");
+            const { getLocalAdminUser } = await import("./auth/local-mode");
+            const database = getDb();
+            const user = await getLocalAdminUser();
+            if (user) {
+              // Get the user's organization
+              const membership = await database.db
+                .selectFrom("member")
+                .select("organizationId")
+                .where("userId", "=", user.id)
+                .executeTakeFirst();
+
+              if (membership) {
+                const { bootstrapProjectAgents } = await import(
+                  "./project/bootstrap"
+                );
+                const { scan } = await bootstrapProjectAgents(
+                  settings.projectDir,
+                  membership.organizationId,
+                  user.id,
+                );
+
+                // Auto-start the project dev server
+                const { startProjectDevServer } = await import(
+                  "./project/dev-server"
+                );
+                await startProjectDevServer(scan);
+              }
+            }
+          } catch (error) {
+            console.error("[project] Failed to bootstrap project:", error);
+          }
+        }
       } catch (error) {
         console.error("Failed to seed local mode:", error);
       } finally {