rastack 0.0.48 → 0.0.50

package/src/import/tabular.ts

@@ -18,6 +18,7 @@ import {
   type FieldState,
   type RecordRun,
   type SpecRelation,
+  type TransitionsModel,
 } from "../validate";
 
 /** A parsed tabular source: one header row + string cell rows. */
@@ -36,7 +37,7 @@ export interface ColumnMapping {
 export interface ImportIssue {
   row: number;
   field: string;
-  gate: FieldState;
+  gate: FieldState | "transition";
   constraint: string;
   message: string;
 }
@@ -94,6 +95,12 @@ export interface ValidateDatasetOptions {
   relatedIds?: Record<string, Set<string>>;
   /** Custom FK resolver (wins over `relatedIds`). */
   resolveRelation?: (relation: SpecRelation, value: unknown) => boolean;
+  /**
+   * The resource's state machine (`schema.rastack.json` `transitions`).
+   * Imported rows are creates, so the record-level `transition` gate rejects
+   * rows born mid-machine (a state other than the initial one).
+   */
+  transitions?: TransitionsModel;
 }
 
 /**
@@ -108,7 +115,7 @@ export function validateDataset(
   options: ValidateDatasetOptions = {},
 ): ImportReport {
   const { columns, missingFields } = mapHeaders(data.headers, specs);
-  const machine = compileRecordMachine(specs);
+  const machine = compileRecordMachine(specs, options.transitions);
   const ctx = createDatasetContext(machine, options);
 
   const rows: RecordRun[] = [];

package/src/rastack-admin.ts

@@ -1,22 +1,36 @@
 #!/usr/bin/env node
 
 /**
- * `rastack admin` — the full, Django-admin-style console, served by the native
- * `rastack-server` against the real Iceberg warehouse.
+ * `rastack admin` — the full, Django-admin-style console, served **in the
+ * browser over the prebuilt WebAssembly engine** (exactly like `rastack dev`).
  *
  *   rastack admin [resourcesDir] [--warehouse <dir>] [--port <n>] [--out <dir>] [--no-open]
  *
- * Unlike the old server-rendered `/admin`, the console is React API Stack's own
- * React admin (`tools/admin`, built from `rastack/components` + `rastack/theme`)
- * — this command compiles the resources, points the server at the prebuilt
- * bundle (`RASTACK_ADMIN_ASSETS`), and boots it. The bundle talks back to the
- * same server's `/api` over HTTP, so edits persist to the real warehouse.
+ * The console is React API Stack's own React admin (`tools/admin`, built from
+ * `rastack/components` + `rastack/theme`). This command compiles the resources,
+ * then boots a dependency-free static server that hands the browser everything
+ * it needs to run the admin locally over WASM — no native server, no cargo:
+ *   • the bundled React admin (`/dev/admin.js`), which defaults to `mode:"local"`,
+ *   • 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.
+ *
+ * The engine is the single prebuilt `.wasm` bundle shipped in the npm package;
+ * if it is missing the command errors and points at `rastack update` — it never
+ * falls back to a from-source cargo build.
  */
 
-import { execFileSync, spawn, spawnSync } from "child_process";
+import { execFileSync, spawnSync } from "child_process";
 import * as fs from "fs";
+import * as http from "http";
 import * as path from "path";
-import { parseAdminArgs } from "./dev/harness";
+import {
+  WASM_ENTRY,
+  contentType,
+  parseAdminArgs,
+  renderShell,
+  wasmBundleCandidates,
+} from "./dev/harness";
 
 const HERE = __dirname; // dist/ when installed — the bundle lives beside us.
 
@@ -32,6 +46,48 @@ function compile(resourcesDir: string, outDir: string): boolean {
   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)) {
+    if (fs.existsSync(path.join(dir, WASM_ENTRY))) return dir;
+  }
+  return null;
+}
+
+/** Serve one file if it exists and stays within `root`; else 404/403. */
+function serveUnder(
+  res: http.ServerResponse,
+  root: string,
+  relPath: string,
+): void {
+  const safeRoot = path.resolve(root);
+  const rel = decodeURIComponent(relPath).replace(/^\/+/, "");
+  const target = path.resolve(safeRoot, rel);
+  // Path-traversal guard: the resolved target must stay inside the root.
+  if (target !== safeRoot && !target.startsWith(safeRoot + path.sep)) {
+    res.writeHead(403).end("Forbidden");
+    return;
+  }
+  fs.readFile(target, (err, data) => {
+    if (err) {
+      res.writeHead(404).end("Not found");
+      return;
+    }
+    res.writeHead(200, { "Content-Type": contentType(target) }).end(data);
+  });
+}
+
+/** Serve an exact file (no traversal concern — a fixed internal artifact). */
+function serveFile(res: http.ServerResponse, file: string): void {
+  fs.readFile(file, (err, data) => {
+    if (err) {
+      res.writeHead(404).end("Not found");
+      return;
+    }
+    res.writeHead(200, { "Content-Type": contentType(file) }).end(data);
+  });
+}
+
 /** Best-effort open the default browser at `url`. */
 function openBrowser(url: string): void {
   const cmd =
@@ -57,54 +113,57 @@ function main(argv: string[]): void {
     process.exit(1);
   }
 
-  const bundle = path.join(HERE, "admin.js");
-  if (!fs.existsSync(bundle)) {
-    console.error("  ✗ admin bundle (dist/admin.js) not found — reinstall rastack.");
+  const wasmDir = resolveWasmDir();
+  if (!wasmDir) {
+    console.error(
+      "\n  ✗ No prebuilt WASM engine found in this rastack install.\n" +
+        "    Update rastack to pull the prebuilt bundle:\n" +
+        "      rastack update\n",
+    );
     process.exit(1);
   }
 
-  const repoRoot = path.resolve(HERE, "..", "..");
-  const binary =
-    process.env.RASTACK_SERVER_BIN ||
-    path.join(repoRoot, "rust", "target", "release", "rastack-server");
-
-  const manifest = path.join(args.outDir, "schema.rastack.json");
-  const serverArgs = [
-    "admin",
-    "--manifest",
-    manifest,
-    "--warehouse",
-    args.warehouseDir,
-    "--addr",
-    `127.0.0.1:${args.port}`,
-    // Local dev context: the admin runs unauthenticated, exactly like the old
-    // native admin. Production admins run the server with --jwks/--admin-group.
-    "--insecure-dev-auth",
-  ];
-
-  const url = `http://127.0.0.1:${args.port}/admin/`;
-  // The server serves the React bundle from here; hand the path via env so the
-  // Rust side stays free of JS-toolchain knowledge.
-  const child = spawn(binary, serverArgs, {
-    stdio: "inherit",
-    env: { ...process.env, RASTACK_ADMIN_ASSETS: HERE },
-  });
-
-  child.on("error", () => {
+  const adminBundle = path.join(HERE, "admin.js");
+  if (!fs.existsSync(adminBundle)) {
     console.error(
-      `  ✗ Could not run the Rust server (${binary}). Build it first:\n` +
-        `      cd rust && cargo build --release\n`,
+      "  ✗ admin bundle (dist/admin.js) not found — reinstall rastack.",
     );
     process.exit(1);
+  }
+
+  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(renderShell("React API Stack — admin"));
+      return;
+    }
+    if (url === "/dev/admin.js") return serveFile(res, adminBundle);
+    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");
   });
-  child.on("exit", (code) => process.exit(code ?? 0));
 
-  // Give the server a moment to bind, then print + open.
-  setTimeout(() => {
+  server.listen(args.port, () => {
+    const url = `http://localhost:${args.port}`;
+    console.log(`  ✓ WASM engine: ${path.relative(process.cwd(), wasmDir)}`);
     console.log(`\n  ▸ ${url}\n`);
     console.log("  Press Ctrl+C to stop.\n");
     if (args.open) openBrowser(url);
-  }, 700);
+  });
 }
 
 if (require.main === module) {

package/src/rastack-import.ts

@@ -148,7 +148,10 @@ function main(): void {
       `[${data.headers.length} column(s), ${data.rows.length} row(s)]\n`,
   );
 
-  const report = validateDataset(specs, data, { relatedIds });
+  const report = validateDataset(specs, data, {
+    relatedIds,
+    transitions: resource.transitions,
+  });
   printReport(report);
 
   const outPath = getArg("--out");

package/src/validate/adapters.ts

@@ -33,6 +33,7 @@ export function specFromManifestField(field: FieldModel): FieldSpec {
   };
   if (field.maxLength !== undefined) spec.maxLength = field.maxLength;
   if (field.unique) spec.unique = true;
+  if (field.options && field.options.length > 0) spec.options = field.options;
   if (field.default !== undefined) spec.default = field.default;
   if (field.type === "fk" && field.relation) spec.relation = field.relation;
   return spec;

package/src/validate/index.ts

@@ -1,2 +1,3 @@
 export * from "./machine";
 export * from "./adapters";
+export * from "./transitions";

package/src/validate/machine.ts

@@ -34,8 +34,18 @@
  * single keystroke — passes through them untouched, exactly like the server,
  * where uniqueness and FK existence are checked against the table, not the
  * payload.
+ *
+ * Record machines add one **record-level** gate on top of the per-field
+ * chains: `transition`. A resource that declares a `transitions` block gets
+ * its state-field writes guarded against the declared edges (with the
+ * persisted row supplied via `ctx.previous`), so an illegal state jump fails
+ * a form, an import row, and a server write with the same message — see
+ * `./transitions.ts`.
  */
 
+import type { TransitionsModel } from "../compile/model";
+import { describeTransitions, transitionGuard } from "./transitions";
+
 // ---------------------------------------------------------------------------
 // The field spec — the normalised constraint set a machine is compiled from
 // ---------------------------------------------------------------------------
@@ -143,6 +153,12 @@ export interface ValidationContext {
   seen?: Map<string, Set<string>>;
   /** Resolve whether a FK value exists on the target resource (the `resolved` gate). */
   resolveRelation?: (relation: SpecRelation, value: unknown) => boolean;
+  /**
+   * The persisted row this record updates (the record-level `transition`
+   * guard). Absent = create semantics: the state field must hold the initial
+   * state. Only consulted by record machines compiled with a transitions block.
+   */
+  previous?: Record<string, unknown>;
 }
 
 /** The result of running a value through a field machine. */
@@ -442,12 +458,19 @@ export function runFieldMachine(
 /** A record machine is the composition of its fields' machines. */
 export interface RecordMachine {
   fields: FieldMachine[];
+  /**
+   * The resource's declarative state machine, when it declares one. Runs as a
+   * record-level gate after the per-field gates: a write that moves the state
+   * field without a declared edge fails at the `transition` gate.
+   */
+  transitions?: TransitionsModel;
 }
 
 /** One field's failure inside a record run. */
 export interface RecordError {
   field: string;
-  gate: FieldState;
+  /** The gate that rejected the value — a field gate, or the record-level `transition` gate. */
+  gate: FieldState | "transition";
   constraint: string;
   message: string;
 }
@@ -462,8 +485,13 @@ export interface RecordRun {
   errors: RecordError[];
 }
 
-export function compileRecordMachine(specs: FieldSpec[]): RecordMachine {
-  return { fields: specs.map(compileFieldMachine) };
+export function compileRecordMachine(
+  specs: FieldSpec[],
+  transitions?: TransitionsModel,
+): RecordMachine {
+  const machine: RecordMachine = { fields: specs.map(compileFieldMachine) };
+  if (transitions) machine.transitions = transitions;
+  return machine;
 }
 
 export function runRecordMachine(
@@ -485,6 +513,30 @@ export function runRecordMachine(
     }
   }
 
+  // The record-level `transition` gate: with the per-field gates passed, a
+  // state-field change must follow a declared edge (against `ctx.previous`;
+  // no previous row = create semantics). A field-level failure on the state
+  // field already explains itself, so the gate only runs when that field is
+  // clean — one error per cause, like every other gate.
+  const transitions = machine.transitions;
+  if (transitions && !fields[transitions.field]?.failed) {
+    // Guard against what was actually submitted: an absent state field is not
+    // a transition, but the field machine defaults it in `values`.
+    const submitted =
+      record[transitions.field] === undefined
+        ? {}
+        : { [transitions.field]: values[transitions.field] };
+    const guard = transitionGuard(transitions, ctx.previous, submitted);
+    if (!guard.ok) {
+      errors.push({
+        field: transitions.field,
+        gate: "transition",
+        constraint: `transitions: ${describeTransitions(transitions).join("; ")}`,
+        message: guard.message,
+      });
+    }
+  }
+
   return {
     state: errors.length === 0 ? "valid" : "invalid",
     values,

package/src/validate/transitions.ts

@@ -0,0 +1,232 @@
+/**
+ * Declarative state transitions — the record-level layer of the constraint
+ * state machine.
+ *
+ * A resource opts in with a `transitions` block (on `resource()` options, or a
+ * `static transitions` on an entity class):
+ *
+ * ```ts
+ * transitions: {
+ *   field: "status",
+ *   states: ["scheduled", "boarding", "departed", "cancelled"],
+ *   initial: "scheduled",
+ *   on: {
+ *     board:  { from: "scheduled", to: "boarding" },
+ *     depart: { from: "boarding",  to: "departed" },
+ *     cancel: { from: ["scheduled", "boarding"], to: "cancelled",
+ *               set: { gate: null } },
+ *   },
+ * }
+ * ```
+ *
+ * The block compiles into the manifest verbatim (with `from` normalised to a
+ * list), and this module is the *shared executable form* of it: the same pure
+ * functions guard a form submit (`useForm(...).transition("board")`), the
+ * record machine (`runRecordMachine` with a `previous` row in context), and —
+ * re-implemented 1:1 in `rastack-api-core` — every server/WASM write. A write
+ * that jumps between states without a declared edge is rejected on every
+ * surface, which is what makes a transition "a backend function that is
+ * state-machine safe": the only way to move a record between states is a
+ * named edge, and the edge's `set` patches are applied by the engine.
+ */
+
+import type { TransitionEdgeModel, TransitionsModel } from "../compile/model";
+
+export type { TransitionEdgeModel, TransitionsModel } from "../compile/model";
+
+/** A transition available from a given state, ready for a UI action list. */
+export interface AvailableTransition {
+  name: string;
+  to: string;
+  set?: Record<string, unknown>;
+}
+
+/** The outcome of a transition guard or application. */
+export type TransitionResult =
+  | { ok: true; patch: Record<string, unknown> }
+  | { ok: false; message: string };
+
+/**
+ * Normalise a raw (authored) transitions block into the canonical model shape:
+ * `from` becomes a string list, non-string states are dropped, and anything
+ * structurally broken yields `undefined` (the compiler then reports it).
+ */
+export function normalizeTransitions(raw: unknown): TransitionsModel | undefined {
+  if (!raw || typeof raw !== "object") return undefined;
+  const block = raw as Record<string, unknown>;
+  if (typeof block.field !== "string" || !block.field) return undefined;
+  if (!Array.isArray(block.states)) return undefined;
+  const states = block.states.filter((s): s is string => typeof s === "string");
+  if (!states.length) return undefined;
+  if (!block.on || typeof block.on !== "object") return undefined;
+
+  const on: Record<string, TransitionEdgeModel> = {};
+  for (const [name, rawEdge] of Object.entries(block.on as Record<string, unknown>)) {
+    if (!rawEdge || typeof rawEdge !== "object") continue;
+    const edge = rawEdge as Record<string, unknown>;
+    const from = (Array.isArray(edge.from) ? edge.from : [edge.from]).filter(
+      (s): s is string => typeof s === "string",
+    );
+    if (!from.length || typeof edge.to !== "string") continue;
+    const model: TransitionEdgeModel = { from, to: edge.to };
+    if (edge.set && typeof edge.set === "object" && !Array.isArray(edge.set)) {
+      model.set = edge.set as Record<string, unknown>;
+    }
+    on[name] = model;
+  }
+
+  const model: TransitionsModel = { field: block.field, states, on };
+  if (typeof block.initial === "string") model.initial = block.initial;
+  return model;
+}
+
+/**
+ * Sanity-check a transitions block against its resource's fields. Returns
+ * human-readable problems (empty = valid); the compiler surfaces each as an
+ * error diagnostic, mirroring the circular-dependency check.
+ */
+export function transitionProblems(
+  transitions: TransitionsModel,
+  fields: Array<{ name: string }>,
+): string[] {
+  const problems: string[] = [];
+  const fieldNames = new Set(fields.map((f) => f.name));
+  const states = new Set(transitions.states);
+
+  if (!fieldNames.has(transitions.field)) {
+    problems.push(`transitions.field "${transitions.field}" is not a field`);
+  }
+  if (transitions.initial !== undefined && !states.has(transitions.initial)) {
+    problems.push(`initial state "${transitions.initial}" is not in states`);
+  }
+  for (const [name, edge] of Object.entries(transitions.on)) {
+    for (const from of edge.from) {
+      if (!states.has(from)) {
+        problems.push(`transition "${name}": from-state "${from}" is not in states`);
+      }
+    }
+    if (!states.has(edge.to)) {
+      problems.push(`transition "${name}": to-state "${edge.to}" is not in states`);
+    }
+    for (const key of Object.keys(edge.set ?? {})) {
+      if (key === transitions.field) {
+        problems.push(
+          `transition "${name}": set must not patch the state field itself`,
+        );
+      } else if (!fieldNames.has(key)) {
+        problems.push(`transition "${name}": set targets unknown field "${key}"`);
+      }
+    }
+  }
+  return problems;
+}
+
+/** The state a record is in — its state-field value, else the initial state. */
+export function currentState(
+  transitions: TransitionsModel,
+  record: Record<string, unknown> | undefined,
+): string | undefined {
+  const value = record?.[transitions.field];
+  if (value !== undefined && value !== null && value !== "") return String(value);
+  return transitions.initial;
+}
+
+/** Every transition that may fire from `state` — the form's action list. */
+export function allowedTransitions(
+  transitions: TransitionsModel,
+  state: unknown,
+): AvailableTransition[] {
+  const from = state === undefined || state === null ? transitions.initial : String(state);
+  if (from === undefined) return [];
+  return Object.entries(transitions.on)
+    .filter(([, edge]) => edge.from.includes(from))
+    .map(([name, edge]) => ({ name, to: edge.to, set: edge.set }));
+}
+
+/** The declared edge covering `from → to`, if any. */
+export function findTransition(
+  transitions: TransitionsModel,
+  from: string,
+  to: string,
+): { name: string; edge: TransitionEdgeModel } | undefined {
+  for (const [name, edge] of Object.entries(transitions.on)) {
+    if (edge.to === to && edge.from.includes(from)) return { name, edge };
+  }
+  return undefined;
+}
+
+/**
+ * Guard one write. `previous` is the persisted row (`undefined` = create).
+ * A create must start at the initial state; an update that changes the state
+ * field must follow a declared edge. Anything else passes untouched — the
+ * guard constrains only the state field.
+ */
+export function transitionGuard(
+  transitions: TransitionsModel,
+  previous: Record<string, unknown> | undefined,
+  next: Record<string, unknown>,
+): TransitionResult {
+  const value = next[transitions.field];
+
+  if (previous === undefined) {
+    // Create: absent state falls back to the initial default; a supplied state
+    // must *be* the initial state — records cannot be born mid-machine.
+    if (value === undefined || value === null || value === "") {
+      return { ok: true, patch: {} };
+    }
+    if (transitions.initial !== undefined && String(value) !== transitions.initial) {
+      return {
+        ok: false,
+        message: `${transitions.field}: new records start at "${transitions.initial}", not "${String(value)}"`,
+      };
+    }
+    return { ok: true, patch: {} };
+  }
+
+  // Update: an untouched (or unchanged) state field is not a transition.
+  if (value === undefined) return { ok: true, patch: {} };
+  const from = currentState(transitions, previous);
+  const to = String(value);
+  if (from === to) return { ok: true, patch: {} };
+
+  const match = from !== undefined && findTransition(transitions, from, to);
+  if (!match) {
+    return {
+      ok: false,
+      message: `${transitions.field}: no transition from "${String(from)}" to "${to}"`,
+    };
+  }
+  return { ok: true, patch: { ...match.edge.set } };
+}
+
+/**
+ * Fire a *named* transition from a record's current state: validates the edge
+ * is available and returns the full patch to write — the state change plus the
+ * edge's `set` effects. This is the client half of the backend function; the
+ * server re-derives the same patch from the same manifest.
+ */
+export function applyTransition(
+  transitions: TransitionsModel,
+  name: string,
+  record: Record<string, unknown> | undefined,
+): TransitionResult {
+  const edge = transitions.on[name];
+  if (!edge) {
+    return { ok: false, message: `unknown transition "${name}"` };
+  }
+  const state = currentState(transitions, record);
+  if (state === undefined || !edge.from.includes(state)) {
+    return {
+      ok: false,
+      message: `"${name}" is not available from "${String(state)}" (needs ${edge.from.join(" | ")})`,
+    };
+  }
+  return { ok: true, patch: { [transitions.field]: edge.to, ...edge.set } };
+}
+
+/** Human-readable edge list — `"board: scheduled → boarding"` — for UI hints. */
+export function describeTransitions(transitions: TransitionsModel): string[] {
+  return Object.entries(transitions.on).map(
+    ([name, edge]) => `${name}: ${edge.from.join(" | ")} → ${edge.to}`,
+  );
+}

package/test/components.spec.ts

@@ -383,4 +383,26 @@ describe("buildAutoFormModel — wiring a form hook into field descriptors", ()
     const model = buildAutoFormModel(form, { exclude: ["status"] });
     expect(model.fields.map((f) => f.name)).toEqual(["code", "active"]);
   });
+
+  it("feature-detects state-machine transitions off a useForm(Entity) result", () => {
+    // A form without transitions renders no actions.
+    expect(buildAutoFormModel(form).transitions).toEqual([]);
+
+    const transition = jest.fn();
+    const machineForm: AutoFormLike = {
+      ...form,
+      transitions: [
+        { name: "board", label: "Board", to: "boarding" },
+        { name: "cancel", to: "cancelled" }, // no label — humanised
+      ],
+      transition,
+    };
+    const model = buildAutoFormModel(machineForm);
+    expect(model.transitions.map((t) => [t.name, t.label, t.to])).toEqual([
+      ["board", "Board", "boarding"],
+      ["cancel", "Cancel", "cancelled"],
+    ]);
+    model.transitions[0].fire();
+    expect(transition).toHaveBeenCalledWith("board");
+  });
 });