rastack 0.0.55 → 0.0.57

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

@@ -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.
  */
@@ -21,39 +25,36 @@ import { execFileSync, spawnSync } from "child_process";
 import * as fs from "fs";
 import * as http from "http";
 import * as path from "path";
+import { runCompile } from "./compile";
 import {
+  APP_ENTRY,
   WASM_ENTRY,
+  appRootCandidates,
   contentType,
   parseDevArgs,
-  renderShell,
+  renderWelcome,
   wasmBundleCandidates,
 } from "./dev/harness";
 
 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;
   }
 }
 
+/** 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,9 +131,9 @@ 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)) {
+  if (!runCompile(args.resourcesDir, args.outDir)) {
     console.error("  ✗ compile failed — fix the resource graph and re-run.");
     process.exit(1);
   }
@@ -149,13 +150,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 +159,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 +170,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

@@ -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
@@ -65,6 +67,17 @@ 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":
@@ -72,8 +85,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":
@@ -134,12 +148,11 @@ switch (command) {
     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/test/deploy.spec.ts

@@ -419,12 +419,15 @@ describe("repo variables + lambda env", () => {
 });
 
 describe("ci plan — check", () => {
-  it("validates then compiles, honouring the resources dir + bin", () => {
+  it("validates then compiles in-process, honouring the resources dir + bin", () => {
     const steps = checkSteps(base({ resourcesDir: "res" }), "npx rastack");
     expect(steps.map((s) => s.run)).toEqual([
       "npx rastack check res",
-      "npx rastack compile res .rastack",
+      "compile res .rastack (in-process)",
     ]);
+    // The compile step runs in-process (no shell command), so the CLI can drop
+    // the standalone `compile` command entirely.
+    expect(steps[1].action).toBe("compile");
     expect(ciPlan("check", base(), { bin: "rastack" })).toEqual(
       checkSteps(base(), "rastack"),
     );

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. */