rastack 0.0.55 → 0.0.57

package/dist/rastack-dev.js

@@ -1,18 +1,22 @@
 #!/usr/bin/env node
 "use strict";
 /**
- * `rastack dev` — local development, always over the WASM engine.
+ * `rastack dev` — local development of **your app**, always over the WASM engine.
  *
- *   rastack dev [resourcesDir] [--port <n>] [--warehouse <dir>] [--out <dir>] [--no-open]
+ *   rastack dev [resourcesDir] [--port <n>] [--warehouse <dir>] [--out <dir>] [--app <dir>] [--no-open]
  *
  * Compiles the resources, then boots a dependency-free static server (à la
- * `rastack design`) that hands the browser everything it needs to run the app +
- * admin locally over WebAssembly — no native server, no cargo:
- *   • the bundled React admin (`/dev/admin.js`),
+ * `rastack design`) that hands the browser everything it needs to run the
+ * developer's own app locally over WebAssembly — no native server, no cargo:
+ *   • the developer's app (`index.html` from the resolved app root), or a
+ *     Django-style welcome page when the project has no app yet,
  *   • the prebuilt WASM engine (`/wasm/…`) shipped in the package,
  *   • the compiled `schema.rastack.json` / `openapi.json`,
  *   • the committed Iceberg warehouse (`/data/warehouse/…`) to seed from.
  *
+ * It does **not** serve the admin console — that is a separate command,
+ * `rastack admin`.
+ *
  * The engine is resolved from the package's prebuilt bundle; if none is present
  * but a Rust + wasm toolchain is, it is built from source as a fallback.
  */
@@ -54,25 +58,26 @@ const child_process_1 = require("child_process");
 const fs = __importStar(require("fs"));
 const http = __importStar(require("http"));
 const path = __importStar(require("path"));
+const compile_1 = require("./compile");
 const harness_1 = require("./dev/harness");
 const HERE = __dirname; // dist/ when installed
-/** Compile the resources to schema.rastack.json + openapi.json in outDir. */
-function compile(resourcesDir, outDir) {
-    const compiler = path.join(HERE, "rastack-compile.js");
-    const result = (0, child_process_1.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() {
     try {
-        return ((0, child_process_1.spawnSync)("cargo", ["--version"], { stdio: "ignore" }).status === 0);
+        return (0, child_process_1.spawnSync)("cargo", ["--version"], { stdio: "ignore" }).status === 0;
     }
     catch {
         return false;
     }
 }
+/** First app-root candidate that holds an `index.html`, or null (→ welcome). */
+function resolveAppRoot(appDir) {
+    for (const dir of (0, harness_1.appRootCandidates)(appDir)) {
+        if (fs.existsSync(path.join(dir, harness_1.APP_ENTRY)))
+            return dir;
+    }
+    return null;
+}
 /** Locate the prebuilt wasm bundle dir, building from source as a fallback. */
 function resolveWasmDir() {
     for (const dir of (0, harness_1.wasmBundleCandidates)(HERE)) {
@@ -141,9 +146,9 @@ function openBrowser(url) {
 }
 function main(argv) {
     const args = (0, harness_1.parseDevArgs)(argv);
-    console.log(`\n  rastack dev — the app + admin, in your browser over WASM\n`);
+    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 (!(0, compile_1.runCompile)(args.resourcesDir, args.outDir)) {
         console.error("  ✗ compile failed — fix the resource graph and re-run.");
         process.exit(1);
     }
@@ -156,38 +161,53 @@ function main(argv) {
             "      cargo install wasm-bindgen-cli\n");
         process.exit(1);
     }
-    const adminBundle = path.join(HERE, "admin.js");
-    if (!fs.existsSync(adminBundle)) {
-        console.error("  ✗ admin bundle (dist/admin.js) not found — reinstall rastack.");
-        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") {
             res.writeHead(405).end("Method not allowed");
             return;
         }
-        if (url === "/" || url === "/index.html") {
-            res
-                .writeHead(200, { "Content-Type": "text/html; charset=utf-8" })
-                .end((0, harness_1.renderShell)());
-            return;
-        }
-        if (url === "/dev/admin.js")
-            return serveFile(res, adminBundle);
+        // Reserved backend routes always win over the app's static files.
         if (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));
-        res.writeHead(404).end("Not found");
+        // No app → the Django-style welcome page (root only; else 404).
+        if (!appRoot) {
+            if (url === "/" || url === "/index.html") {
+                res
+                    .writeHead(200, { "Content-Type": "text/html; charset=utf-8" })
+                    .end((0, harness_1.renderWelcome)());
+                return;
+            }
+            res.writeHead(404).end("Not found");
+            return;
+        }
+        // Serve the app: its index.html at `/`, an existing file as-is, and any
+        // other route back to index.html (SPA client-side routing).
+        if (url === "/" || url === "/index.html")
+            return serveFile(res, path.join(appRoot, harness_1.APP_ENTRY));
+        const rel = decodeURIComponent(url).replace(/^\/+/, "");
+        const target = path.resolve(appRoot, rel);
+        const safeRoot = path.resolve(appRoot);
+        const inRoot = target === safeRoot || target.startsWith(safeRoot + path.sep);
+        if (inRoot && fs.existsSync(target) && fs.statSync(target).isFile())
+            return serveFile(res, target);
+        return serveFile(res, path.join(appRoot, harness_1.APP_ENTRY));
     });
     server.listen(args.port, () => {
         const url = `http://localhost:${args.port}`;
         console.log(`  ✓ WASM engine: ${path.relative(process.cwd(), wasmDir)}`);
-        console.log(`\n  ▸ ${url}   (admin at ${url}/#/)\n`);
-        console.log("  Press Ctrl+C to stop.\n");
+        if (appRoot)
+            console.log(`  ✓ app: ${path.relative(process.cwd(), appRoot) || "."}`);
+        else
+            console.log(`  ○ no app found — serving the welcome page`);
+        console.log(`\n  ▸ ${url}\n`);
+        console.log("  Need the database console? Run `rastack admin`. Ctrl+C to stop.\n");
         if (args.open)
             openBrowser(url);
     });

package/dist/rastack-update.js

@@ -82,10 +82,17 @@ function readVersion(file) {
  * sanitized (`sanitizeVersion`). POSIX keeps the shell-free `execFile`.
  */
 function runNpm(args, opts) {
-    // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process
-    return NPM_SHELL
-        ? (0, child_process_1.execSync)((0, update_1.npmShellCommand)(NPM, args), opts)
-        : (0, child_process_1.execFileSync)(NPM, args, opts);
+    if (NPM_SHELL) {
+        // Windows: launch the `npm.cmd` shim through a shell (a bare `.cmd` spawn is
+        // rejected with EINVAL since the Node CVE-2024-27980 fix). The only
+        // non-literal token — the version — is sanitized in `parseUpdateFlags`, and
+        // every other arg is a fixed literal, so nothing injectable reaches it. The
+        // nosemgrep must sit on the line directly above the `execSync` call for the
+        // engine to honour it.
+        // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process
+        return (0, child_process_1.execSync)((0, update_1.npmShellCommand)(NPM, args), opts);
+    }
+    return (0, child_process_1.execFileSync)(NPM, args, opts);
 }
 /** Capture `npm <args>` stdout, or null when npm is absent / the call fails. */
 function npmCapture(args) {

package/dist/rastack.d.ts

@@ -2,15 +2,17 @@
 /**
  * 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
  *   rastack generate [--schema-only]            Generate typed hooks from OpenAPI
  *   rastack tokens  [input] [outDir]            Compile design tokens → CSS vars + typed theme
  *   rastack design  [input] [--port n]          Live design-system studio (showcase + edit)
- *   rastack dev     [--port n] [--warehouse d]  Local dev: run the app + admin in-browser over WASM
+ *   rastack dev     [--port n] [--warehouse d]  Local dev: run your app in-browser over WASM
  *   rastack admin   [--warehouse dir] [--port n] Full admin console — React UI (rastack/components) over the native server
  *   rastack import <file> --resource app.model  Load CSV/XLSX/PDF data and validate it (state machine)
  *   rastack scan   [files...] [--fail-on-pii]   Scan CSVs for PII and schema info

package/dist/rastack.js

@@ -3,15 +3,17 @@
 /**
  * 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
  *   rastack generate [--schema-only]            Generate typed hooks from OpenAPI
  *   rastack tokens  [input] [outDir]            Compile design tokens → CSS vars + typed theme
  *   rastack design  [input] [--port n]          Live design-system studio (showcase + edit)
- *   rastack dev     [--port n] [--warehouse d]  Local dev: run the app + admin in-browser over WASM
+ *   rastack dev     [--port n] [--warehouse d]  Local dev: run your app in-browser over WASM
  *   rastack admin   [--warehouse dir] [--port n] Full admin console — React UI (rastack/components) over the native server
  *   rastack import <file> --resource app.model  Load CSV/XLSX/PDF data and validate it (state machine)
  *   rastack scan   [files...] [--fail-on-pii]   Scan CSVs for PII and schema info
@@ -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":
@@ -71,8 +82,9 @@ switch (command) {
         run("rastack-compile.js", [command, ...rest]);
         break;
     case "dev":
-        // Local development: serve the app + admin in the browser over the WASM
-        // engine (no native server, no cargo). Replaces `serve` + `wasm`.
+        // Local development: serve your app in the browser over the WASM engine
+        // (no native server, no cargo). The admin console is a separate command,
+        // `rastack admin`. Replaces `serve` + `wasm`.
         run("rastack-dev.js", rest);
         break;
     case "admin":
@@ -132,12 +144,11 @@ 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` +
             `  rastack design  [input] [--port n]             Live design-system studio (showcase + edit)\n` +
-            `  rastack dev     [--port n] [--warehouse dir] [--no-open]  Run the app + admin in-browser over WASM (local dev)\n` +
+            `  rastack dev     [--port n] [--warehouse dir] [--app dir] [--no-open]  Run your app in-browser over WASM (local dev)\n` +
             `  rastack admin   [--warehouse dir] [--port n] [--no-open]  Full admin console (React UI over the native server; needs a built rastack-server)\n` +
             `  rastack import <file.csv|.xlsx|.pdf> --resource app.model [--related app.model=<file>] [--out cleaned.json]\n` +
             `  rastack scan   [files...] [--fail-on-pii]\n` +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rastack",
-  "version": "0.0.55",
+  "version": "0.0.57",
   "description": "",
   "main": "runtime.ts",
   "types": "runtime.ts",
@@ -21,7 +21,7 @@
   "author": "",
   "license": "ISC",
   "dependencies": {
-    "@apidevtools/json-schema-ref-parser": "^15.4.0",
+    "@apidevtools/json-schema-ref-parser": "^15.5.0",
     "@tanstack/react-query": "^5.101.2",
     "@ts-stack/openapi-spec": "^3.1.5",
     "@types/json-schema": "^7.0.15",
@@ -37,9 +37,9 @@
     "lodash": "^4.18.0",
     "luxon": "^3.7.2",
     "minimatch": "^10.2.5",
-    "prettier": "^3.9.4",
+    "prettier": "^3.9.5",
     "react-query": "^3.39.3",
-    "typescript": "^6.0.3",
+    "typescript": "~5.9.3",
     "usehooks-ts": "^3.1.1"
   },
   "peerDependencies": {
@@ -49,10 +49,10 @@
     "@types/jest": "^30.0.0",
     "@types/js-yaml": "^4.0.9",
     "@types/mocha": "^10.0.6",
-    "@types/node": "^26.1.0",
+    "@types/node": "^26.1.1",
     "@types/react-dom": "^19.2.0",
-    "esbuild": "^0.25.0",
-    "eslint": "^10.6.0",
+    "esbuild": "^0.28.1",
+    "eslint": "^10.7.0",
     "jest": "^30.4.2",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",

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

@@ -1,16 +1,20 @@
 /**
  * Pure core of `rastack dev` — the local, always-WASM development server.
  *
- * `rastack dev` boots the app + admin **in the browser** over the WebAssembly
- * engine (the same app-generic `rastack-api-core` the Lambda runs, fed the app's
+ * `rastack dev` runs **your app** in the browser over the WebAssembly engine
+ * (the same app-generic `rastack-api-core` the Lambda runs, fed the app's
  * compiled manifest). No native server, no cargo: a dependency-free static
- * server hands the browser the prebuilt wasm engine, the compiled schema, and
- * the committed Iceberg warehouse, and a bundled React admin drives it.
+ * server hands the browser the prebuilt wasm engine, the compiled schema, the
+ * committed Iceberg warehouse, and the developer's own app. It does **not**
+ * serve the admin console — that is a separate command, `rastack admin`.
+ *
+ * When the project has no app to serve, `dev` shows a Django-style welcome
+ * page (`renderWelcome`) so a fresh scaffold still boots to something friendly.
  *
  * Everything decidable without IO lives here (arg parsing, MIME types, locating
- * the wasm bundle, the HTML shell) so it is unit-tested without a socket or a
- * filesystem; `rastack-dev.ts` is the thin IO wrapper that compiles, resolves
- * the engine, and serves.
+ * the wasm bundle, resolving the app root, the HTML pages) so it is unit-tested
+ * without a socket or a filesystem; `rastack-dev.ts` is the thin IO wrapper that
+ * compiles, resolves the engine and the app, and serves.
  */
 
 import * as path from "path";
@@ -22,6 +26,12 @@ export interface DevArgs {
   outDir: string;
   /** The committed Iceberg warehouse served to seed the browser engine. */
   warehouseDir: string;
+  /**
+   * Explicit app root to serve at `/` (its `index.html`). Empty when unset —
+   * the IO wrapper then probes `appRootCandidates`, falling back to the welcome
+   * page when none holds an `index.html`.
+   */
+  appDir: string;
   /** Port the dev server listens on. */
   port: number;
   /** Open the browser on start (false with `--no-open`). */
@@ -32,22 +42,25 @@ export const DEV_DEFAULTS: DevArgs = {
   resourcesDir: "resources",
   outDir: ".rastack",
   warehouseDir: "data/warehouse",
+  appDir: "",
   port: 4321,
   open: true,
 };
 
 /**
- * Parse `rastack dev` args: `--port`, `--warehouse`, `--out`, `--no-open`, and a
- * single positional resources dir. Unknown flags are ignored (forgiving CLI).
+ * Parse `rastack dev` args: `--port`, `--warehouse`, `--out`, `--app`,
+ * `--no-open`, and a single positional resources dir. Unknown flags are ignored
+ * (forgiving CLI).
  */
 export function parseDevArgs(argv: string[]): DevArgs {
   const positional: string[] = [];
-  let { resourcesDir, outDir, warehouseDir, port, open } = DEV_DEFAULTS;
+  let { resourcesDir, outDir, warehouseDir, appDir, port, open } = DEV_DEFAULTS;
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--port") port = Number(argv[++i]) || port;
     else if (a === "--warehouse") warehouseDir = argv[++i] ?? warehouseDir;
     else if (a === "--out") outDir = argv[++i] ?? outDir;
+    else if (a === "--app") appDir = argv[++i] ?? appDir;
     else if (a === "--no-open") open = false;
     else if (!a.startsWith("-")) positional.push(a);
   }
@@ -55,11 +68,27 @@ export function parseDevArgs(argv: string[]): DevArgs {
     resourcesDir: positional[0] || resourcesDir,
     outDir,
     warehouseDir,
+    appDir,
     port,
     open,
   };
 }
 
+/** The file that marks a directory as a servable app root. */
+export const APP_ENTRY = "index.html";
+
+/**
+ * Ordered directories to probe for the developer's app (`index.html`). An
+ * explicit `--app <dir>` wins outright; otherwise `dev` looks in the
+ * conventional static roots and finally the project root. The IO wrapper picks
+ * the first candidate that actually holds an `index.html`; if none does, it
+ * serves the welcome page instead.
+ */
+export function appRootCandidates(appDir: string, cwd = process.cwd()): string[] {
+  if (appDir) return [path.resolve(cwd, appDir)];
+  return ["public", "www", "app", "."].map((d) => path.resolve(cwd, d));
+}
+
 /** Args for `rastack admin` — like `DevArgs`, but bound to a real server port. */
 export interface AdminArgs {
   resourcesDir: string;
@@ -147,12 +176,14 @@ export function wasmBundleCandidates(
 export const WASM_ENTRY = "rastack_wasm.js";
 
 /**
- * The HTML shell served at `/`. It loads the bundled React admin
- * (`/dev/admin.js`), which fetches the schema/openapi, boots the wasm engine,
- * seeds it from `/data/warehouse/`, and renders the admin. Deliberately tiny —
- * all logic lives in the bundle — mirroring the `rastack design` studio.
+ * The HTML shell served at `/` by **`rastack admin`**. It loads the bundled
+ * React admin (`/dev/admin.js`), which fetches the schema/openapi, boots the
+ * wasm engine, seeds it from `/data/warehouse/`, and renders the admin console.
+ * Deliberately tiny — all logic lives in the bundle — mirroring the
+ * `rastack design` studio. `rastack dev` does **not** use this: it serves the
+ * developer's own app (or the welcome page below).
  */
-export function renderShell(title = "React API Stack — dev"): string {
+export function renderShell(title = "React API Stack — admin"): string {
   return `<!doctype html>
 <html lang="en">
 <head>
@@ -172,3 +203,78 @@ export function renderShell(title = "React API Stack — dev"): string {
 </html>
 `;
 }
+
+/**
+ * The Django-style welcome page `rastack dev` serves at `/` when the project
+ * has **no app** to serve (no `index.html` in any `appRootCandidates` dir).
+ * It confirms the dev server is up, points at the live backend endpoints the
+ * WASM engine exposes, and tells you how to add an app or open the admin — the
+ * "It worked!" moment of `django-admin runserver`, on brand for the stack.
+ */
+export function renderWelcome(title = "React API Stack — dev"): string {
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>${title}</title>
+<style>
+  :root { color-scheme: light dark; }
+  * { box-sizing: border-box; }
+  html, body { margin: 0; min-height: 100%; }
+  body {
+    font: 15px/1.6 system-ui, -apple-system, "Segoe UI", sans-serif;
+    color: #1f2328; background: #f6f8fa;
+    display: flex; align-items: center; justify-content: center; padding: 2rem;
+  }
+  .card {
+    max-width: 640px; width: 100%; background: #fff; border: 1px solid #d0d7de;
+    border-radius: 14px; padding: 2.5rem; box-shadow: 0 1px 3px rgba(0,0,0,.06);
+  }
+  .rocket { font-size: 2.5rem; line-height: 1; }
+  h1 { font-size: 1.5rem; margin: .75rem 0 .25rem; }
+  p.lead { color: #57606a; margin: 0 0 1.5rem; }
+  code { font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+    background: #eff1f3; padding: .1em .4em; border-radius: 5px; font-size: .9em; }
+  ul { padding-left: 1.1rem; margin: 0; }
+  li { margin: .4rem 0; }
+  a { color: #0969da; text-decoration: none; }
+  a:hover { text-decoration: underline; }
+  .foot { margin-top: 1.75rem; padding-top: 1.25rem; border-top: 1px solid #eaeef2;
+    color: #6e7781; font-size: .85rem; }
+  @media (prefers-color-scheme: dark) {
+    body { color: #e6edf3; background: #0d1117; }
+    .card { background: #161b22; border-color: #30363d; box-shadow: none; }
+    p.lead { color: #8b949e; }
+    code { background: #21262d; }
+    .foot { border-color: #21262d; color: #8b949e; }
+  }
+</style>
+</head>
+<body>
+<div class="card">
+  <div class="rocket">🚀</div>
+  <h1>The dev server is running.</h1>
+  <p class="lead">
+    Congratulations — <strong>rastack dev</strong> is up and your API is running
+    in the browser over WebAssembly. You're seeing this page because there's no
+    app to serve yet.
+  </p>
+  <ul>
+    <li>Add an <code>index.html</code> (in <code>public/</code>, <code>www/</code>,
+      <code>app/</code>, or the project root) and reload — <code>dev</code> will serve it.
+      Point it at a different folder with <code>rastack dev --app &lt;dir&gt;</code>.</li>
+    <li>Wire your app to the local engine with
+      <code>&lt;RAStackProvider mode="local"&gt;</code>.</li>
+    <li>Live backend endpoints:
+      <a href="/schema.rastack.json">/schema.rastack.json</a>,
+      <a href="/openapi.json">/openapi.json</a>,
+      <code>/data/warehouse/…</code>, <code>/wasm/…</code>.</li>
+    <li>Want the database console instead? Run <code>rastack admin</code>.</li>
+  </ul>
+  <div class="foot">React API Stack — a full-stack framework on object storage.</div>
+</div>
+</body>
+</html>
+`;
+}