rastack 0.0.55 → 0.0.56

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>
+`;
+}

package/src/rastack-dev.ts

@@ -1,18 +1,22 @@
 #!/usr/bin/env node
 
 /**
- * `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.
  */
@@ -22,10 +26,12 @@ import * as fs from "fs";
 import * as http from "http";
 import * as path from "path";
 import {
+  APP_ENTRY,
   WASM_ENTRY,
+  appRootCandidates,
   contentType,
   parseDevArgs,
-  renderShell,
+  renderWelcome,
   wasmBundleCandidates,
 } from "./dev/harness";
 
@@ -54,6 +60,14 @@ function cargoAvailable(): boolean {
   }
 }
 
+/** First app-root candidate that holds an `index.html`, or null (→ welcome). */
+function resolveAppRoot(appDir: string): string | null {
+  for (const dir of appRootCandidates(appDir)) {
+    if (fs.existsSync(path.join(dir, APP_ENTRY))) return dir;
+  }
+  return null;
+}
+
 /** Locate the prebuilt wasm bundle dir, building from source as a fallback. */
 function resolveWasmDir(): string | null {
   for (const dir of wasmBundleCandidates(HERE)) {
@@ -130,7 +144,7 @@ function openBrowser(url: string): void {
 function main(argv: string[]): void {
   const args = 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)) {
     console.error("  ✗ compile failed — fix the resource graph and re-run.");
@@ -149,13 +163,8 @@ function main(argv: string[]): void {
     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];
@@ -163,13 +172,7 @@ function main(argv: string[]): void {
       res.writeHead(405).end("Method not allowed");
       return;
     }
-    if (url === "/" || url === "/index.html") {
-      res
-        .writeHead(200, { "Content-Type": "text/html; charset=utf-8" })
-        .end(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")
@@ -180,14 +183,43 @@ function main(argv: string[]): void {
         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(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, 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, 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/src/rastack-update.ts

@@ -64,10 +64,17 @@ function runNpm(
   args: string[],
   opts: { stdio: "inherit" | ["ignore", "pipe", "pipe"]; env?: NodeJS.ProcessEnv },
 ): Buffer | null {
-  // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process
-  return NPM_SHELL
-    ? execSync(npmShellCommand(NPM, args), opts)
-    : 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 execSync(npmShellCommand(NPM, args), opts);
+  }
+  return execFileSync(NPM, args, opts);
 }
 
 /** Capture `npm <args>` stdout, or null when npm is absent / the call fails. */

package/src/rastack.ts

@@ -11,7 +11,7 @@
  *   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
@@ -72,8 +72,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":
@@ -139,7 +140,7 @@ switch (command) {
         `  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/test/dev.spec.ts

@@ -1,11 +1,14 @@
 import {
   ADMIN_DEFAULTS,
+  APP_ENTRY,
   DEV_DEFAULTS,
   WASM_ENTRY,
+  appRootCandidates,
   contentType,
   parseAdminArgs,
   parseDevArgs,
   renderShell,
+  renderWelcome,
   wasmBundleCandidates,
 } from "../src/dev/harness";
 import {
@@ -57,6 +60,7 @@ describe("rastack dev — arg parsing", () => {
       resourcesDir: "app/resources",
       outDir: "build",
       warehouseDir: "data/wh",
+      appDir: "",
       port: 5000,
       open: false,
     });
@@ -114,7 +118,7 @@ describe("rastack dev — wasm bundle resolution", () => {
   });
 });
 
-describe("rastack dev — HTML shell", () => {
+describe("rastack admin — HTML shell", () => {
   it("mounts #root and loads the bundled admin", () => {
     const html = renderShell();
     expect(html).toContain('<div id="root">');
@@ -123,6 +127,43 @@ describe("rastack dev — HTML shell", () => {
   });
 });
 
+describe("rastack dev — app resolution", () => {
+  it("defaults appDir to empty (probe the conventional roots)", () => {
+    expect(DEV_DEFAULTS.appDir).toBe("");
+  });
+
+  it("reads --app as an explicit app root", () => {
+    expect(parseDevArgs(["--app", "site"]).appDir).toBe("site");
+  });
+
+  it("probes public/www/app/root when no --app is given", () => {
+    const dirs = appRootCandidates("", "/repo");
+    expect(dirs).toEqual([
+      "/repo/public",
+      "/repo/www",
+      "/repo/app",
+      "/repo",
+    ]);
+    expect(APP_ENTRY).toBe("index.html");
+  });
+
+  it("uses only the explicit --app dir when set", () => {
+    expect(appRootCandidates("site", "/repo")).toEqual(["/repo/site"]);
+  });
+});
+
+describe("rastack dev — welcome page (no app)", () => {
+  it("is a self-contained page pointing at the backend and admin", () => {
+    const html = renderWelcome();
+    expect(html.startsWith("<!doctype html>")).toBe(true);
+    // Django-style "it worked" confirmation, not the admin bundle.
+    expect(html).not.toContain("/dev/admin.js");
+    expect(html).toContain("dev server is running");
+    expect(html).toContain("/schema.rastack.json");
+    expect(html).toContain("rastack admin");
+  });
+});
+
 // -- admin adapters ---------------------------------------------------------
 
 /** The in-repo airline fixtures, in manifest JSON shape. */