rastack 0.0.56 → 0.0.58

package/dist/rastack.js

@@ -3,8 +3,10 @@
 /**
  * rastack — unified CLI for React API Stack
  *
+ * Compilation is not a command of its own: it runs in-process inside the two
+ * modalities of use — `rastack dev`/`admin` (local) and `rastack ci` (deploy).
+ *
  * Commands:
- *   rastack compile [resourcesDir] [outDir]     TypeScript resources → schema.rastack.json + openapi.json
  *   rastack check   [resourcesDir]              Validate the resource graph
  *   rastack list    [resourcesDir]              Print resources, fields and relations
  *   rastack urls    [resourcesDir]              Print the generated /api/{app}/v1/{model}/ routes
@@ -64,6 +66,15 @@ switch (command) {
         printVersion();
         break;
     case "compile":
+        // Compilation is no longer a standalone command — it runs in-process as
+        // part of the two modalities of use. Point the way rather than 404.
+        console.error("`rastack compile` has been removed — compilation now runs automatically\n" +
+            "inside the two modalities of use:\n" +
+            "  • rastack dev    local development (compiles, then serves over WASM)\n" +
+            "  • rastack ci     the deploy pipeline (compiles the manifest + OpenAPI)\n\n" +
+            "Introspect the resource graph with: rastack check | list | urls\n");
+        process.exit(1);
+        break;
     case "check":
     case "list":
     case "urls":
@@ -133,7 +144,6 @@ switch (command) {
     default:
         console.error(`Unknown command: "${command}"\n\n` +
             `Usage:\n` +
-            `  rastack compile [resourcesDir] [outDir]\n` +
             `  rastack check | list | urls [resourcesDir]\n` +
             `  rastack generate [--schema-only]\n` +
             `  rastack tokens  [input] [outDir] [--prefix p]  Compile design tokens → CSS vars + typed theme\n` +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rastack",
-  "version": "0.0.56",
+  "version": "0.0.58",
   "description": "",
   "main": "runtime.ts",
   "types": "runtime.ts",
@@ -14,6 +14,7 @@
   "scripts": {
     "format": "prettier --write \"**/*.{ts,tsx,md}\"",
     "build": "tsc && cp src/.prettierrc dist/.prettierrc && node scripts/copy-templates.js && node scripts/build-admin.js && node scripts/copy-wasm.js",
+    "dev:install": "node scripts/dev-install.mjs",
     "start": "node dist/index.js",
     "test": "jest"
   },

package/src/compile/index.ts

@@ -21,6 +21,7 @@ export type {
   EntityTypeExport,
 } from "./entities";
 export { buildManifest } from "./manifest";
+export { runCompile } from "./run";
 export { buildOpenApi, writeSchema } from "./openapi";
 export * from "./model";
 
@@ -60,7 +61,10 @@ export function resolveResourceFiles(input: string): string[] {
       for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
         if (entry.isDirectory()) {
           if (!IGNORE_DIRS.has(entry.name)) walk(path.join(dir, entry.name));
-        } else if (/\.tsx?$/.test(entry.name) && !entry.name.endsWith(".d.ts")) {
+        } else if (
+          /\.tsx?$/.test(entry.name) &&
+          !entry.name.endsWith(".d.ts")
+        ) {
           files.push(path.resolve(dir, entry.name));
         }
       }
@@ -96,10 +100,14 @@ export function analyzeProject(input: string): ProjectAnalysis {
   const defined = new Set(fromDsl.resources.map((r) => `${r.app}.${r.model}`));
   const resources = [
     ...fromDsl.resources,
-    ...fromInterfaces.resources.filter((r) => !defined.has(`${r.app}.${r.model}`)),
+    ...fromInterfaces.resources.filter(
+      (r) => !defined.has(`${r.app}.${r.model}`),
+    ),
   ];
   resources.sort((a, b) =>
-    a.app === b.app ? a.model.localeCompare(b.model) : a.app.localeCompare(b.app),
+    a.app === b.app
+      ? a.model.localeCompare(b.model)
+      : a.app.localeCompare(b.app),
   );
 
   // Registry entries follow the same merge rule as the resources: the DSL
@@ -237,7 +245,8 @@ export function collisions(resources: ResourceModel[]): string[] {
     }
   }
   for (const [key, count] of seen) {
-    if (count > 1) errors.push(`Duplicate resource ${key} defined ${count} times.`);
+    if (count > 1)
+      errors.push(`Duplicate resource ${key} defined ${count} times.`);
   }
   return errors;
 }

package/src/compile/run.ts

@@ -0,0 +1,26 @@
+import * as fs from "fs";
+import * as path from "path";
+import { compile } from "./index";
+
+/**
+ * Run the compiler **in-process**, writing `schema.rastack.json` +
+ * `openapi.json` (and `rastack-env.d.ts`) into `outDir`. Prints any warnings
+ * and, on failure, the error; returns `true` on success.
+ *
+ * This is the single entry point the two real modalities of use share instead
+ * of shelling out to a standalone `compile` command:
+ *   • `rastack dev` / `rastack admin` — local development (compile, then serve
+ *     the app + admin in the browser over WASM), and
+ *   • `rastack ci` — the deploy pipeline (compile the manifest the Rust backend
+ *     reads + the OpenAPI contract, then build/ship).
+ */
+export function runCompile(resourcesDir: string, outDir: string): boolean {
+  try {
+    const result = compile(resourcesDir, outDir);
+    for (const d of result.diagnostics) console.warn(`  ⚠ ${d.message}`);
+    return fs.existsSync(path.join(outDir, "schema.rastack.json"));
+  } catch (err) {
+    console.error(`  ✗ ${(err as Error).message}`);
+    return false;
+  }
+}

package/src/deploy/ci.ts

@@ -23,10 +23,31 @@ export type CiPhase = "check" | "build" | "deploy";
 export interface CiStep {
   /** Human label, echoed before the step runs. */
   name: string;
-  /** The shell command to execute. */
+  /** The shell command to execute (or, for an in-process step, a description). */
   run: string;
   /** Working directory relative to the repo root (default: repo root). */
   cwd?: string;
+  /**
+   * When set, the step is executed **in-process by the CLI** rather than through
+   * a shell — `run` is then a human-readable description, not a command. Today
+   * the only in-process action is `"compile"`, which the CLI runs via the shared
+   * compiler (`runCompile`) instead of shelling out to a standalone command.
+   */
+  action?: "compile";
+}
+
+/**
+ * The in-process compile step shared by `check` and `build`: it produces
+ * `schema.rastack.json` + `openapi.json` in `cfg.outDir` without a subprocess,
+ * so compilation lives inside the two modalities of use (`dev` and `ci`) rather
+ * than in a separately-invoked `compile` command.
+ */
+function compileStep(cfg: DeployConfig): CiStep {
+  return {
+    name: "Compile manifest + OpenAPI",
+    run: `compile ${cfg.resourcesDir} ${cfg.outDir} (in-process)`,
+    action: "compile",
+  };
 }
 
 export interface CiPlanOptions {
@@ -72,10 +93,7 @@ export function checkSteps(cfg: DeployConfig, bin: string): CiStep[] {
       name: "Validate resource graph",
       run: `${bin} check ${cfg.resourcesDir}`,
     },
-    {
-      name: "Compile manifest + OpenAPI",
-      run: `${bin} compile ${cfg.resourcesDir} ${cfg.outDir}`,
-    },
+    compileStep(cfg),
   ];
 }
 
@@ -88,7 +106,6 @@ export function buildSteps(
   cfg: DeployConfig,
   opts: CiPlanOptions = {},
 ): CiStep[] {
-  const bin = opts.bin ?? "rastack";
   const stage = stageDir(cfg);
   const archFlag = cfg.lambda.arch === "arm64" ? "--arm64" : "--x86-64";
   const jwks = stackOutput(
@@ -97,10 +114,7 @@ export function buildSteps(
     opts.jwksUrl ?? cfg.outputs?.jwksUrl,
   );
   return [
-    {
-      name: "Compile manifest + OpenAPI",
-      run: `${bin} compile ${cfg.resourcesDir} ${cfg.outDir}`,
-    },
+    compileStep(cfg),
     {
       name: "Cross-build the Lambda binary",
       run: `cargo lambda build --release ${archFlag} --bin ${cfg.lambda.bin} --features ${cfg.lambda.features}`,

package/src/dev/harness.ts

@@ -191,13 +191,30 @@ export function renderShell(title = "React API Stack — admin"): string {
 <meta name="viewport" content="width=device-width, initial-scale=1" />
 <title>${title}</title>
 <style>
-  html, body { margin: 0; height: 100%; }
+  html, body { margin: 0; height: 100%; background: #F2F5FB;
+    font-family: "Inter", system-ui, -apple-system, "Segoe UI", Roboto, sans-serif; }
+  @media (prefers-color-scheme: dark) { html, body { background: #06080F; } }
   #root { min-height: 100%; }
-  .rastack-boot { font: 14px system-ui, sans-serif; padding: 2rem; color: #555; }
+  .rastack-boot { min-height: 100vh; display: flex; flex-direction: column;
+    align-items: center; justify-content: center; gap: 20px; }
+  .rastack-boot-logo { width: 60px; height: 60px; border-radius: 18px; background: #4F6BFF;
+    box-shadow: 0 8px 24px rgba(79,107,255,0.30); animation: rastack-boot-bob 3s ease-in-out infinite; }
+  .rastack-boot-track { position: relative; width: 168px; height: 4px; border-radius: 999px;
+    overflow: hidden; background: rgba(11,16,32,0.10); }
+  @media (prefers-color-scheme: dark) { .rastack-boot-track { background: rgba(233,239,255,0.14); } }
+  .rastack-boot-track::after { content: ""; position: absolute; top: 0; left: -42%; height: 100%;
+    width: 40%; border-radius: inherit; background: linear-gradient(90deg, transparent, #4F6BFF);
+    animation: rastack-boot-slide 1.25s cubic-bezier(0.5,0.1,0.3,1) infinite; }
+  @keyframes rastack-boot-bob { 0%,100% { transform: translateY(0); } 50% { transform: translateY(-3px); } }
+  @keyframes rastack-boot-slide { to { left: 100%; } }
+  @media (prefers-reduced-motion: reduce) {
+    .rastack-boot-logo { animation: none; }
+    .rastack-boot-track::after { animation: none; left: 0; width: 100%; }
+  }
 </style>
 </head>
 <body>
-<div id="root"><div class="rastack-boot">Loading the WASM engine…</div></div>
+<div id="root"><div class="rastack-boot"><div class="rastack-boot-logo"></div><div class="rastack-boot-track"></div></div></div>
 <script src="/dev/admin.js"></script>
 </body>
 </html>

package/src/rastack-admin.ts

@@ -20,10 +20,11 @@
  * falls back to a from-source cargo build.
  */
 
-import { execFileSync, spawnSync } from "child_process";
+import { execFileSync } from "child_process";
 import * as fs from "fs";
 import * as http from "http";
 import * as path from "path";
+import { runCompile } from "./compile";
 import {
   WASM_ENTRY,
   contentType,
@@ -34,18 +35,6 @@ import {
 
 const HERE = __dirname; // dist/ when installed — the bundle lives beside us.
 
-/** Compile the resources to schema.rastack.json + openapi.json in outDir. */
-function compile(resourcesDir: string, outDir: string): boolean {
-  const compiler = path.join(HERE, "rastack-compile.js");
-  const result = spawnSync(
-    process.execPath,
-    [compiler, "compile", resourcesDir, outDir],
-    { stdio: "inherit" },
-  );
-  if (result.status !== 0) return false;
-  return fs.existsSync(path.join(outDir, "schema.rastack.json"));
-}
-
 /** Locate the prebuilt wasm bundle dir shipped in the package (no cargo fallback). */
 function resolveWasmDir(): string | null {
   for (const dir of wasmBundleCandidates(HERE)) {
@@ -106,9 +95,11 @@ function openBrowser(url: string): void {
 function main(argv: string[]): void {
   const args = parseAdminArgs(argv);
 
-  console.log(`\n  rastack admin — the database console, built with React API Stack\n`);
+  console.log(
+    `\n  rastack admin — the database console, built with React API Stack\n`,
+  );
   console.log(`▸ Compiling ${args.resourcesDir} → ${args.outDir}`);
-  if (!compile(args.resourcesDir, args.outDir)) {
+  if (!runCompile(args.resourcesDir, args.outDir)) {
     console.error("  ✗ compile failed — fix the resource graph and re-run.");
     process.exit(1);
   }

package/src/rastack-ci.ts

@@ -18,6 +18,8 @@
  */
 
 import { execSync } from "child_process";
+import { runCompile } from "./compile";
+import { DeployConfig } from "./deploy/config";
 import { CiPhase, CiPlanOptions, CiStep, ciPlan } from "./deploy/ci";
 import { loadConfig } from "./deploy/io";
 
@@ -85,13 +87,24 @@ function printPlan(phase: CiPhase, steps: CiStep[]): void {
   steps.forEach((s, i) => {
     const at = s.cwd ? ` (in ${s.cwd}/)` : "";
     console.log(`  ${i + 1}. ${s.name}${at}`);
-    console.log(`     $ ${s.run}\n`);
+    // In-process steps have no shell command; `run` is a description.
+    console.log(`     ${s.action ? "» " : "$ "}${s.run}\n`);
   });
 }
 
-function runSteps(phase: CiPhase, steps: CiStep[]): void {
+function runSteps(phase: CiPhase, steps: CiStep[], cfg: DeployConfig): void {
   for (const step of steps) {
     console.log(`\n▸ ${step.name}${step.cwd ? ` (in ${step.cwd}/)` : ""}`);
+    if (step.action === "compile") {
+      // Compilation runs in-process — it lives inside `ci` (and `dev`), not in a
+      // separately-invoked `compile` command.
+      console.log(`  » ${step.run}`);
+      if (!runCompile(cfg.resourcesDir, cfg.outDir)) {
+        console.error(`\n  ✗ step failed: ${step.name}`);
+        process.exit(1);
+      }
+      continue;
+    }
     console.log(`  $ ${step.run}`);
     try {
       // Runs a CI pipeline step derived from the developer's own deploy config
@@ -123,7 +136,7 @@ function main(argv: string[]): void {
   }
   const steps = ciPlan(phase, cfg, opts);
   if (plan) printPlan(phase, steps);
-  else runSteps(phase, steps);
+  else runSteps(phase, steps, cfg);
 }
 
 if (require.main === module) {

package/src/rastack-compile.ts

@@ -1,40 +1,31 @@
 #!/usr/bin/env node
 
 /**
- * `rastack compile | check | list | urls` — the TypeScript-first replacement for the
- * old Django `manage.py rastack` command.
+ * `rastack check | list | urls` — introspection over the TypeScript-first
+ * resource graph.
  *
- *   rastack compile [resourcesDir] [outDir]   defs → schema.rastack.json + openapi.json
  *   rastack check   [resourcesDir]            validate the resource graph (exit != 0 on error)
  *   rastack list    [resourcesDir]            print every resource + its fields/relations
  *   rastack urls    [resourcesDir]            print the generated /api/{app}/v1/{model}/ routes
+ *
+ * Compilation itself (defs → schema.rastack.json + openapi.json) is no longer a
+ * command here: it runs in-process inside the two modalities of use — `rastack
+ * dev`/`admin` (local) and `rastack ci` (deploy) — via the shared `runCompile`.
  */
 
 import {
   analyzeProject,
   analyzeResources,
   collisions,
-  compile,
   urlsFor,
 } from "./compile";
 
 const DEFAULT_RESOURCES = "resources";
-const DEFAULT_OUT = ".rastack";
 
 function main(argv: string[]): void {
   const [sub, ...rest] = argv;
 
   switch (sub) {
-    case "compile": {
-      const resourcesDir = rest[0] || DEFAULT_RESOURCES;
-      const outDir = rest[1] || DEFAULT_OUT;
-      const result = compile(resourcesDir, outDir);
-      for (const d of result.diagnostics) console.warn(`  ⚠ ${d.message}`);
-      console.log(
-        `✓ compiled ${result.manifest.resources.length} resource(s) → ${result.files.join(", ")}`,
-      );
-      break;
-    }
     case "check": {
       const { resources, diagnostics } = analyzeProject(
         rest[0] || DEFAULT_RESOURCES,
@@ -65,7 +56,9 @@ function main(argv: string[]): void {
       for (const r of resources) {
         console.log(`${r.app}.${r.model}`);
         for (const f of r.fields) {
-          const rel = f.relation ? ` → ${f.relation.app}.${f.relation.model}` : "";
+          const rel = f.relation
+            ? ` → ${f.relation.app}.${f.relation.model}`
+            : "";
           console.log(`  ${f.name}: ${f.type}${rel}`);
         }
         if (r.sync) {
@@ -89,9 +82,8 @@ function main(argv: string[]): void {
     }
     default:
       console.error(
-        `Unknown compile subcommand: "${sub}"\n\n` +
+        `Unknown subcommand: "${sub}"\n\n` +
           `Usage:\n` +
-          `  rastack compile [resourcesDir] [outDir]\n` +
           `  rastack check   [resourcesDir]\n` +
           `  rastack list    [resourcesDir]\n` +
           `  rastack urls    [resourcesDir]\n`,

package/src/rastack-dev.ts

@@ -21,15 +21,18 @@
  * but a Rust + wasm toolchain is, it is built from source as a fallback.
  */
 
-import { execFileSync, spawnSync } from "child_process";
+import { execFileSync, spawn, spawnSync, type ChildProcess } from "child_process";
 import * as fs from "fs";
 import * as http from "http";
+import * as net from "net";
 import * as path from "path";
+import { runCompile } from "./compile";
 import {
   APP_ENTRY,
   WASM_ENTRY,
   appRootCandidates,
   contentType,
+  type DevArgs,
   parseDevArgs,
   renderWelcome,
   wasmBundleCandidates,
@@ -37,24 +40,10 @@ import {
 
 const HERE = __dirname; // dist/ when installed
 
-/** Compile the resources to schema.rastack.json + openapi.json in outDir. */
-function compile(resourcesDir: string, outDir: string): boolean {
-  const compiler = path.join(HERE, "rastack-compile.js");
-  const result = spawnSync(
-    process.execPath,
-    [compiler, "compile", resourcesDir, outDir],
-    { stdio: "inherit" },
-  );
-  if (result.status !== 0) return false;
-  return fs.existsSync(path.join(outDir, "schema.rastack.json"));
-}
-
 /** True when `cargo` is on PATH (the from-source wasm fallback needs it). */
 function cargoAvailable(): boolean {
   try {
-    return (
-      spawnSync("cargo", ["--version"], { stdio: "ignore" }).status === 0
-    );
+    return spawnSync("cargo", ["--version"], { stdio: "ignore" }).status === 0;
   } catch {
     return false;
   }
@@ -141,16 +130,230 @@ function openBrowser(url: string): void {
   }
 }
 
-function main(argv: string[]): void {
+// ---------------------------------------------------------------------------
+// Live-dev mode — `rastack dev` for an Expo / react-native-web app.
+//
+// A React Native (Expo) app has no static `index.html`: its web build is a
+// Metro bundle. Rather than make the developer run a second tool, `dev` starts
+// Expo's Metro dev server itself and reverse-proxies to it, so `rastack dev`
+// stays the single command *and* keeps Metro's fast-refresh. The WASM
+// static-serve path remains the default for apps that ship a built index.html.
+// ---------------------------------------------------------------------------
+
+/** True when the project is an Expo app (so `dev` should drive Metro). */
+function isExpoProject(cwd: string): boolean {
+  try {
+    const appJson = JSON.parse(
+      fs.readFileSync(path.join(cwd, "app.json"), "utf-8"),
+    );
+    if (appJson && appJson.expo) return true;
+  } catch {
+    /* no app.json — fall through to package.json */
+  }
+  try {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(cwd, "package.json"), "utf-8"),
+    );
+    if (pkg?.dependencies?.expo || pkg?.devDependencies?.expo) return true;
+  } catch {
+    /* no package.json */
+  }
+  return false;
+}
+
+/** Locate the prebuilt wasm bundle without the cargo fallback (optional here). */
+function findWasmDir(): string | null {
+  for (const dir of wasmBundleCandidates(HERE)) {
+    if (fs.existsSync(path.join(dir, WASM_ENTRY))) return dir;
+  }
+  return null;
+}
+
+/** Grab an ephemeral free TCP port for Metro (avoids a fixed-port clash). */
+function getFreePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const srv = net.createServer();
+    srv.on("error", reject);
+    srv.listen(0, "127.0.0.1", () => {
+      const addr = srv.address();
+      const port = addr && typeof addr === "object" ? addr.port : 0;
+      srv.close(() => (port ? resolve(port) : reject(new Error("no free port"))));
+    });
+  });
+}
+
+/** Start `expo start --web` on `port`, with a reload-enabled environment. */
+function startMetro(cwd: string, port: number): ChildProcess {
+  // A live dev server needs watch mode, so we must NOT set CI (Expo reads it as
+  // "reloads disabled"). BROWSER=none stops Expo opening its own tab — we front
+  // it on the rastack port. `shell:true` keeps the npx / npx.cmd split portable.
+  const env: NodeJS.ProcessEnv = {
+    ...process.env,
+    BROWSER: "none",
+    EXPO_NO_TELEMETRY: "1",
+  };
+  delete env.CI;
+  // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process
+  const child = spawn(`npx expo start --web --port ${port}`, {
+    cwd,
+    env,
+    stdio: ["ignore", "pipe", "pipe"],
+    shell: true,
+  });
+  // Surface Metro's own errors (bundling failures, port issues) with a prefix.
+  child.stderr?.on("data", (d) => process.stderr.write(`  [metro] ${d}`));
+  return child;
+}
+
+/** Poll Metro's `/status` until it answers `packager-status:running`. */
+function waitForMetro(port: number, timeoutMs = 120_000): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  return new Promise((resolve) => {
+    const retry = () =>
+      Date.now() > deadline ? resolve(false) : setTimeout(tick, 400);
+    const tick = () => {
+      const req = http.get(
+        { host: "127.0.0.1", port, path: "/status", timeout: 2000 },
+        (res) => {
+          let body = "";
+          res.on("data", (c) => (body += c));
+          res.on("end", () =>
+            body.includes("packager-status:running") ? resolve(true) : retry(),
+          );
+        },
+      );
+      req.on("error", retry);
+      req.on("timeout", () => req.destroy());
+    };
+    tick();
+  });
+}
+
+/** Reverse-proxy one HTTP request/response pair to Metro. */
+function proxyToMetro(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  port: number,
+): void {
+  const proxyReq = http.request(
+    { host: "127.0.0.1", port, method: req.method, path: req.url, headers: req.headers },
+    (proxyRes) => {
+      res.writeHead(proxyRes.statusCode || 502, proxyRes.headers);
+      proxyRes.pipe(res);
+    },
+  );
+  proxyReq.on("error", () => {
+    if (!res.headersSent) res.writeHead(502);
+    res.end("Metro is not reachable.");
+  });
+  req.pipe(proxyReq);
+}
+
+/** Reverse-proxy a WebSocket upgrade (Metro HMR / fast-refresh) to Metro. */
+function proxyUpgrade(
+  req: http.IncomingMessage,
+  clientSocket: net.Socket,
+  head: Buffer,
+  port: number,
+): void {
+  const upstream = net.connect(port, "127.0.0.1", () => {
+    const lines = [`${req.method} ${req.url} HTTP/1.1`];
+    for (const [k, v] of Object.entries(req.headers)) {
+      if (Array.isArray(v)) v.forEach((vv) => lines.push(`${k}: ${vv}`));
+      else if (v != null) lines.push(`${k}: ${v}`);
+    }
+    upstream.write(lines.join("\r\n") + "\r\n\r\n");
+    if (head && head.length) upstream.write(head);
+    upstream.pipe(clientSocket);
+    clientSocket.pipe(upstream);
+  });
+  upstream.on("error", () => clientSocket.destroy());
+  clientSocket.on("error", () => upstream.destroy());
+}
+
+/** `rastack dev` for an Expo app: start Metro and reverse-proxy to it. */
+async function runMetroMode(args: DevArgs, cwd: string): Promise<void> {
+  // The wasm engine is optional here — an Expo/RN-web app runs its own engine —
+  // so a missing bundle is fine. When present, the reserved backend routes work.
+  const wasmDir = findWasmDir();
+
+  const metroPort = await getFreePort();
+  console.log(`▸ Starting Metro bundler (Expo) on :${metroPort} …`);
+  const metro = startMetro(cwd, metroPort);
+
+  let shuttingDown = false;
+  const stop = (code = 0) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    try {
+      metro.kill();
+    } catch {
+      /* already gone */
+    }
+    process.exit(code);
+  };
+  process.on("SIGINT", () => stop(0));
+  process.on("SIGTERM", () => stop(0));
+  metro.on("exit", (code) => {
+    if (!shuttingDown) {
+      console.error(`\n  ✗ Metro exited (code ${code ?? "?"}).`);
+      process.exit(code ?? 1);
+    }
+  });
+
+  if (!(await waitForMetro(metroPort))) {
+    console.error("  ✗ Metro did not come up in time.");
+    return stop(1);
+  }
+
+  const server = http.createServer((req, res) => {
+    const url = (req.url || "/").split("?")[0];
+    // Reserved backend routes win when the engine bundle is available.
+    if (wasmDir && url.startsWith("/wasm/"))
+      return serveUnder(res, wasmDir, url.slice("/wasm/".length));
+    if (url === "/schema.rastack.json" || url === "/openapi.json")
+      return serveUnder(res, args.outDir, path.basename(url));
+    if (url.startsWith("/data/warehouse/"))
+      return serveUnder(res, args.warehouseDir, url.slice("/data/warehouse/".length));
+    // Everything else → the live Metro bundle (HTML, JS, assets, HMR polls).
+    return proxyToMetro(req, res, metroPort);
+  });
+  server.on("upgrade", (req, socket, head) =>
+    proxyUpgrade(req, socket as net.Socket, head, metroPort),
+  );
+
+  server.listen(args.port, () => {
+    const url = `http://localhost:${args.port}`;
+    console.log(`  ✓ Metro live on :${metroPort} — fast refresh on`);
+    if (wasmDir)
+      console.log(`  ✓ WASM engine: ${path.relative(cwd, wasmDir)}`);
+    console.log(`\n  ▸ ${url}\n`);
+    console.log(
+      "  Edits reload live. Need the database console? Run `rastack admin`. Ctrl+C to stop.\n",
+    );
+    if (args.open) openBrowser(url);
+  });
+}
+
+async function main(argv: string[]): Promise<void> {
   const args = parseDevArgs(argv);
+  const cwd = process.cwd();
 
   console.log(`\n  rastack dev — your app, in your browser over WASM\n`);
   console.log(`▸ Compiling ${args.resourcesDir} → ${args.outDir}`);
-  if (!compile(args.resourcesDir, args.outDir)) {
+  if (!runCompile(args.resourcesDir, args.outDir)) {
     console.error("  ✗ compile failed — fix the resource graph and re-run.");
     process.exit(1);
   }
 
+  // Serve the developer's own app when there is one; otherwise the welcome page.
+  const appRoot = resolveAppRoot(args.appDir);
+
+  // No static build, but an Expo source tree → drive Metro live (fast refresh).
+  if (!appRoot && isExpoProject(cwd)) {
+    return runMetroMode(args, cwd);
+  }
+
   const wasmDir = resolveWasmDir();
   if (!wasmDir) {
     console.error(
@@ -163,9 +366,6 @@ function main(argv: string[]): void {
     process.exit(1);
   }
 
-  // Serve the developer's own app when there is one; otherwise the welcome page.
-  const appRoot = resolveAppRoot(args.appDir);
-
   const server = http.createServer((req, res) => {
     const url = (req.url || "/").split("?")[0];
     if (req.method !== "GET") {
@@ -225,5 +425,8 @@ function main(argv: string[]): void {
 }
 
 if (require.main === module) {
-  main(process.argv.slice(2));
+  main(process.argv.slice(2)).catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
 }