rastack 0.0.22 → 0.0.24

package/src/seed.ts

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
 
 /**
- * rad seed
+ * rastack seed
  *
  * Loads CSV files from a local directory or GCS bucket into the target
  * Iceberg namespace. Performs schema inference, PII check, and idempotent
  * table creation before writing rows.
  *
  * Usage:
- *   rad seed [--env dev|staging] [--source gs://bucket/ | --source ./myapp-dev/]
+ *   rastack seed [--env dev|staging] [--source gs://bucket/ | --source ./myapp-dev/]
  *
  * Environment variables (set via CI secrets or .env):
  *   GCP_PROJECT             GCP project ID
@@ -52,11 +52,11 @@ function resolveFiles(): string[] {
 }
 
 function downloadFromGcs(gcsUri: string): string[] {
-  const tmpDir = path.join(repoRoot, ".rad", "tmp", "seed");
+  const tmpDir = path.join(repoRoot, ".rastack", "tmp", "seed");
   fs.mkdirSync(tmpDir, { recursive: true });
 
   console.log(`Downloading CSVs from ${gcsUri} ...`);
-  // `rad seed` is a local/CI developer tool; `gcsUri` is an operator-supplied
+  // `rastack seed` is a local/CI developer tool; `gcsUri` is an operator-supplied
   // --source argument (a gs:// bucket the operator controls), not untrusted
   // network input, so there is no command-injection surface here.
   try {
@@ -87,7 +87,7 @@ function validateSchema(csvPath: string): TableSchema {
       .join("\n");
     throw new Error(
       `PII detected in ${path.basename(csvPath)}:\n${list}\n` +
-        `Remove PII data before seeding. Run "rad scan" to review.`,
+        `Remove PII data before seeding. Run "rastack scan" to review.`,
     );
   }
 
@@ -138,7 +138,7 @@ function buildCreateTableSql(schema: TableSchema, namespace: string): string {
 // Step 4: write schema fingerprints to registry
 // ---------------------------------------------------------------------------
 function writeFingerprint(schema: TableSchema): void {
-  const registryDir = path.join(repoRoot, ".rad", "registry");
+  const registryDir = path.join(repoRoot, ".rastack", "registry");
   fs.mkdirSync(registryDir, { recursive: true });
   const registryPath = path.join(registryDir, `${schema.tableName}.json`);
 
@@ -257,18 +257,18 @@ async function main() {
   }
 
   // Emit DDL summary
-  const ddlDir = path.join(repoRoot, ".rad", "ddl");
+  const ddlDir = path.join(repoRoot, ".rastack", "ddl");
   fs.mkdirSync(ddlDir, { recursive: true });
   for (const schema of schemas) {
     const ddl = buildCreateTableSql(schema, env);
     fs.writeFileSync(path.join(ddlDir, `${schema.tableName}.sql`), ddl + "\n");
   }
 
-  console.log(`\nDDL written to .rad/ddl/`);
+  console.log(`\nDDL written to .rastack/ddl/`);
 
   // Run Python seed via pyiceberg if available
   const seedScript = buildPythonSeedScript(schemas, files);
-  const scriptPath = path.join(repoRoot, ".rad", "tmp", "seed.py");
+  const scriptPath = path.join(repoRoot, ".rastack", "tmp", "seed.py");
   fs.mkdirSync(path.dirname(scriptPath), { recursive: true });
   fs.writeFileSync(scriptPath, seedScript);
 

package/sync/engine.ts

@@ -58,7 +58,7 @@ export class SyncEngine {
     this.store = new SyncStore();
     this.persistence = createPersistence(
       config.persist !== false,
-      config.databaseName || "rad-sync",
+      config.databaseName || "rastack-sync",
     );
     this.queue = new TransactionQueue({
       api,

package/sync/types.ts

@@ -89,6 +89,6 @@ export interface SyncEngineConfig {
   /** Persist to IndexedDB (default true; falls back to memory when unavailable). */
   persist?: boolean;
   /** Database name for IndexedDB. */
-  databaseName?: string; // default "rad-sync"
+  databaseName?: string; // default "rastack-sync"
   onError?: (error: unknown) => void;
 }

package/test/cache.spec.ts

@@ -41,7 +41,7 @@ class FakeWarehouse implements WarehouseFileSource {
       `${prefix}/metadata/v${version}.metadata.json`,
       encoder.encode(
         JSON.stringify({
-          format: "rad-iceberg-v1",
+          format: "rastack-iceberg-v1",
           data_files: Object.keys(dataFiles),
           next_int_id: 99,
         }),

package/test/compile.spec.ts

@@ -12,7 +12,7 @@ import { removeNonModelPaths } from "../src/schema/remove-non-model-paths";
 
 /**
  * The compiler's fixtures are real `.ts` files that import the DSL by its
- * package name (`rad-tools/define`); `createProgram` maps that to the in-tree
+ * package name (`rastack/define`); `createProgram` maps that to the in-tree
  * source, so the type checker resolves the `Ref`/`Resource` brands exactly as it
  * would in a consumer project.
  */
@@ -21,7 +21,7 @@ const resourcesDir = join(workRoot, "resources");
 const outDir = join(workRoot, "out");
 
 const AIRPORTS_TS = `
-import { resource, s } from "rad-tools/define";
+import { resource, s } from "rastack/define";
 
 export const Airport = resource("airports", "airport", {
   code: s.string({ maxLength: 3, unique: true }),
@@ -65,7 +65,7 @@ function findResource(
   return found;
 }
 
-describe("rad compile — resource analysis & FK inference", () => {
+describe("rastack compile — resource analysis & FK inference", () => {
   beforeAll(() => {
     mkdirSync(resourcesDir, { recursive: true });
     writeFileSync(join(resourcesDir, "airports.ts"), AIRPORTS_TS);
@@ -141,7 +141,7 @@ describe("rad compile — resource analysis & FK inference", () => {
   });
 });
 
-describe("rad compile — OpenAPI emission", () => {
+describe("rastack compile — OpenAPI emission", () => {
   beforeAll(() => {
     mkdirSync(resourcesDir, { recursive: true });
     writeFileSync(join(resourcesDir, "airports.ts"), AIRPORTS_TS);
@@ -151,9 +151,9 @@ describe("rad compile — OpenAPI emission", () => {
     rmSync(workRoot, { recursive: true, force: true });
   });
 
-  it("writes schema.rad.json and openapi.json", () => {
+  it("writes schema.rastack.json and openapi.json", () => {
     const result = compile(resourcesDir, outDir);
-    expect(existsSync(join(outDir, "schema.rad.json"))).toBe(true);
+    expect(existsSync(join(outDir, "schema.rastack.json"))).toBe(true);
     expect(existsSync(join(outDir, "openapi.json"))).toBe(true);
     expect(result.manifest.resources.length).toBe(6);
   });

package/test/csv-schema.spec.ts

@@ -6,7 +6,7 @@ import { parseCsv, inferSchema, discoverCsvFiles } from "../src/csv-schema";
 const REPO_ROOT = path.join(__dirname, "..");
 
 function tmpCsv(content: string): string {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "rad-test-"));
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "rastack-test-"));
   const file = path.join(dir, "test.csv");
   fs.writeFileSync(file, content);
   return file;
@@ -128,7 +128,7 @@ describe("inferSchema — PII detection", () => {
 
 describe("discoverCsvFiles", () => {
   it("finds all csv files in a directory", () => {
-    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "rad-test-"));
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "rastack-test-"));
     fs.writeFileSync(path.join(dir, "a.csv"), "id\n1");
     fs.writeFileSync(path.join(dir, "b.csv"), "id\n2");
     fs.writeFileSync(path.join(dir, "readme.txt"), "not a csv");

package/test/entities.spec.ts

@@ -0,0 +1,381 @@
+import { mkdirSync, rmSync, writeFileSync } from "fs";
+import { join } from "path";
+import {
+  analyzeProject,
+  buildOpenApi,
+  compile,
+  detectCycles,
+  ResourceModel,
+} from "../src/compile";
+
+/**
+ * Interface-driven inference: the app's entities are plain TypeScript
+ * interfaces, discovered from the typed hook calls that consume them. The
+ * fixtures are real `.ts`/`.tsx` files so the TypeChecker resolves the
+ * interfaces exactly as it would in a consumer project.
+ */
+const workRoot = join(__dirname, "entities-fixtures");
+const appDir = join(workRoot, "app");
+const cycleDir = join(workRoot, "cycles");
+const hardCycleDir = join(workRoot, "hard-cycles");
+const mixedDir = join(workRoot, "mixed");
+const outDir = join(workRoot, "out");
+
+const AIRPORTS_TS = `
+/** @rastackSearch code,name */
+export interface Airport {
+  /**
+   * @maxLength 3
+   * @unique
+   */
+  code: string;
+  /** @maxLength 120 */
+  name: string;
+  terminals?: Terminal[]; // reverse side of Terminal.airport — no column
+}
+
+export interface Terminal {
+  airport: Airport; // FK — inferred from the property type
+  /** @maxLength 20 */
+  label: string;
+}
+
+/** Never consumed by a hook and never referenced — not a resource. */
+export interface Runway {
+  heading: number;
+}
+`;
+
+const FLIGHTS_TS = `
+import { Terminal } from "./airports";
+
+export interface Flight {
+  /** @maxLength 8 */
+  number: string;
+  /** @int */
+  seats: number;
+  onTime: boolean;
+  departure: Date;
+  notes?: string;
+  /** @default scheduled */
+  status: string;
+  terminal: Terminal | null; // nullable FK across files
+  tags: string[]; // unsupported — skipped with a warning
+}
+
+/** @rastackResource
+ *  @rastackApp bookings
+ *  @rastackModel booking
+ */
+export interface IBookingRecord {
+  reference: string;
+}
+`;
+
+const PASSENGERS_TS = `
+import {
+  DbConfig,
+  Default,
+  Int,
+  MaxLength,
+  PrimaryKey,
+  Unique,
+  UUID,
+} from "rastack/types";
+import { Terminal } from "./airports";
+
+/** A reusable column config — "extend DbConfig once, use it everywhere". */
+interface SeatCode extends DbConfig<{ maxLength: 4; unique: true }> {}
+
+export interface Passenger {
+  id: UUID & PrimaryKey;
+  seat: string & SeatCode;
+  fullName: string & MaxLength<80>;
+  age: Int;
+  loyaltyPoints: number & Default<0>;
+  status: string & Default<"active">;
+  terminal?: Terminal;
+}
+
+declare function useEntityList<T>(name: string): T[];
+export const p = useEntityList<Passenger>("passengers");
+`;
+
+const SCREENS_TSX = `
+import { Flight } from "./flights";
+
+declare function useEntityList<T>(name: string): T[];
+
+export function FlightsScreen() {
+  // The hook call is what roots the entity graph.
+  return useEntityList<Flight>("flights");
+}
+`;
+
+const SOFT_CYCLE_TS = `
+export interface Employee {
+  name: string;
+  manager?: Employee; // optional self-FK — breakable cycle
+}
+
+declare function useEntity<T>(name: string): T;
+export const e = useEntity<Employee>("employee");
+`;
+
+const HARD_CYCLE_TS = `
+export interface Chicken {
+  egg: Egg;
+}
+export interface Egg {
+  chicken: Chicken;
+}
+
+declare function useEntity<T>(name: string): T;
+export const c = useEntity<Chicken>("chicken");
+`;
+
+const MIXED_TS = `
+import { resource, s } from "rastack/define";
+
+export const AirportResource = resource("mixed", "airport", {
+  code: s.string({ maxLength: 3, unique: true }),
+}, { admin: { listDisplay: ["code"] } });
+
+/** @rastackApp mixed */
+export interface Airport {
+  code: string;
+}
+
+declare function useEntity<T>(name: string): T;
+export const a = useEntity<Airport>("airport");
+`;
+
+function findResource(
+  resources: ResourceModel[],
+  app: string,
+  model: string,
+): ResourceModel {
+  const found = resources.find((r) => r.app === app && r.model === model);
+  if (!found) throw new Error(`missing ${app}.${model}`);
+  return found;
+}
+
+beforeAll(() => {
+  mkdirSync(appDir, { recursive: true });
+  writeFileSync(join(appDir, "airports.ts"), AIRPORTS_TS);
+  writeFileSync(join(appDir, "flights.ts"), FLIGHTS_TS);
+  writeFileSync(join(appDir, "passengers.ts"), PASSENGERS_TS);
+  writeFileSync(join(appDir, "screens.tsx"), SCREENS_TSX);
+  mkdirSync(cycleDir, { recursive: true });
+  writeFileSync(join(cycleDir, "org.ts"), SOFT_CYCLE_TS);
+  mkdirSync(hardCycleDir, { recursive: true });
+  writeFileSync(join(hardCycleDir, "paradox.ts"), HARD_CYCLE_TS);
+  mkdirSync(mixedDir, { recursive: true });
+  writeFileSync(join(mixedDir, "airport.ts"), MIXED_TS);
+});
+
+afterAll(() => {
+  rmSync(workRoot, { recursive: true, force: true });
+});
+
+describe("interface entities — discovery from hooks", () => {
+  it("roots the graph at hook type arguments and closes over FK references", () => {
+    const { resources } = analyzeProject(appDir);
+    const keys = resources.map((r) => `${r.app}.${r.model}`);
+
+    // Flight is the hook root; Terminal and Airport are pulled in through the
+    // FK chain flight → terminal → airport.
+    expect(keys).toContain("flights.flight");
+    expect(keys).toContain("airports.terminal");
+    expect(keys).toContain("airports.airport");
+
+    // Declared but neither hooked nor referenced — not a resource.
+    expect(keys).not.toContain("airports.runway");
+  });
+
+  it("includes @rastackResource interfaces and honours @rastackApp/@rastackModel + I-prefix stripping", () => {
+    const { resources } = analyzeProject(appDir);
+    const booking = findResource(resources, "bookings", "booking");
+    expect(booking.fields).toEqual([{ name: "reference", type: "string" }]);
+  });
+
+  it("names entities from the interface and the defining file", () => {
+    const { resources } = analyzeProject(appDir);
+    // airports.ts → app "airports"; interface Airport → model "airport".
+    const airport = findResource(resources, "airports", "airport");
+    expect(airport.search).toEqual(["code", "name"]);
+  });
+});
+
+describe("interface entities — datatypes from the type system", () => {
+  it("maps property types to manifest scalars with JSDoc refinements", () => {
+    const { resources } = analyzeProject(appDir);
+    const flight = findResource(resources, "flights", "flight");
+    const field = (name: string) => flight.fields.find((f) => f.name === name);
+
+    expect(field("number")).toMatchObject({ type: "string", maxLength: 8 });
+    expect(field("seats")).toMatchObject({ type: "int" }); // number + @int
+    expect(field("onTime")).toMatchObject({ type: "bool" });
+    expect(field("departure")).toMatchObject({ type: "datetime" });
+    expect(field("notes")).toMatchObject({ type: "string", null: true });
+    expect(field("status")).toMatchObject({ type: "string", default: "scheduled" });
+  });
+
+  it("reads constraint tags (@maxLength/@unique) off interface properties", () => {
+    const { resources } = analyzeProject(appDir);
+    const airport = findResource(resources, "airports", "airport");
+    expect(airport.fields.find((f) => f.name === "code")).toMatchObject({
+      type: "string",
+      maxLength: 3,
+      unique: true,
+    });
+  });
+
+  it("reads column config from DbConfig brand types", () => {
+    const { resources } = analyzeProject(appDir);
+    const passenger = findResource(resources, "passengers", "passenger");
+    const field = (name: string) => passenger.fields.find((f) => f.name === name);
+
+    expect(field("id")).toMatchObject({ type: "uuid", primaryKey: true });
+    expect(field("fullName")).toMatchObject({ type: "string", maxLength: 80 });
+    expect(field("age")).toMatchObject({ type: "int" });
+    expect(field("loyaltyPoints")).toMatchObject({ type: "float", default: 0 });
+    expect(field("status")).toMatchObject({ type: "string", default: "active" });
+    expect(field("terminal")).toMatchObject({
+      type: "fk",
+      null: true,
+      relation: { app: "airports", model: "terminal" },
+    });
+  });
+
+  it("supports reusable configs that extend DbConfig", () => {
+    const { resources } = analyzeProject(appDir);
+    const passenger = findResource(resources, "passengers", "passenger");
+    expect(passenger.fields.find((f) => f.name === "seat")).toMatchObject({
+      type: "string",
+      maxLength: 4,
+      unique: true,
+    });
+
+    // The brand interface itself is configuration, not an entity.
+    expect(
+      resources.find((r) => r.model.toLowerCase().includes("seatcode")),
+    ).toBeUndefined();
+  });
+
+  it("skips unsupported property types with a warning", () => {
+    const { resources, diagnostics } = analyzeProject(appDir);
+    const flight = findResource(resources, "flights", "flight");
+    expect(flight.fields.find((f) => f.name === "tags")).toBeUndefined();
+    expect(
+      diagnostics.some(
+        (d) => d.severity === "warning" && d.message.includes("flights.flight.tags"),
+      ),
+    ).toBe(true);
+  });
+});
+
+describe("interface entities — FK inference", () => {
+  it("treats an interface-typed property as a foreign key", () => {
+    const { resources } = analyzeProject(appDir);
+    const terminal = findResource(resources, "airports", "terminal");
+
+    expect(terminal.fields.find((f) => f.name === "airport")).toMatchObject({
+      type: "fk",
+      relation: { app: "airports", model: "airport" },
+    });
+    expect(terminal.relations).toEqual([
+      { field: "airport", target: "airports.airport", kind: "fk" },
+    ]);
+  });
+
+  it("maps `Entity | null` to a nullable foreign key", () => {
+    const { resources } = analyzeProject(appDir);
+    const flight = findResource(resources, "flights", "flight");
+    expect(flight.fields.find((f) => f.name === "terminal")).toMatchObject({
+      type: "fk",
+      null: true,
+      relation: { app: "airports", model: "terminal" },
+    });
+  });
+
+  it("ignores `Entity[]` arrays — the reverse side of the FK", () => {
+    const { resources } = analyzeProject(appDir);
+    const airport = findResource(resources, "airports", "airport");
+    expect(airport.fields.find((f) => f.name === "terminals")).toBeUndefined();
+    expect(airport.relations).toEqual([]);
+  });
+});
+
+describe("interface entities — circular dependencies", () => {
+  it("reports a breakable cycle (optional self-FK) as a warning", () => {
+    const { diagnostics } = analyzeProject(cycleDir);
+    const cycle = diagnostics.find((d) => d.message.includes("Circular dependency"));
+    expect(cycle).toBeDefined();
+    expect(cycle!.severity).toBe("warning");
+    expect(cycle!.message).toContain("org.employee → org.employee");
+    expect(cycle!.message).toContain("org.employee.manager");
+  });
+
+  it("reports an unbreakable cycle (all FKs required) as an error", () => {
+    const { diagnostics } = analyzeProject(hardCycleDir);
+    const cycle = diagnostics.find((d) => d.severity === "error");
+    expect(cycle).toBeDefined();
+    expect(cycle!.message).toContain("Circular dependency");
+    expect(cycle!.message).toMatch(/paradox\.(chicken|egg)/);
+  });
+
+  it("compile() refuses to emit a manifest containing an unbreakable cycle", () => {
+    expect(() => compile(hardCycleDir, outDir)).toThrow(/Circular dependency/);
+  });
+
+  it("detectCycles also covers DSL-authored relations", () => {
+    const resources: ResourceModel[] = [
+      {
+        app: "a",
+        model: "x",
+        fields: [{ name: "y", type: "fk", relation: { app: "a", model: "y" } }],
+        relations: [{ field: "y", target: "a.y", kind: "fk" }],
+      },
+      {
+        app: "a",
+        model: "y",
+        fields: [{ name: "x", type: "fk", relation: { app: "a", model: "x" } }],
+        relations: [{ field: "x", target: "a.x", kind: "fk" }],
+      },
+    ];
+    const diagnostics = detectCycles(resources);
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].severity).toBe("error");
+  });
+});
+
+describe("interface entities — merging with the resource() DSL", () => {
+  it("prefers the explicit DSL definition when both define the same app.model", () => {
+    const { resources } = analyzeProject(mixedDir);
+    const airports = resources.filter(
+      (r) => r.app === "mixed" && r.model === "airport",
+    );
+    expect(airports).toHaveLength(1);
+    // The DSL definition (with admin config) won over the inferred interface.
+    expect(airports[0].admin).toEqual({ listDisplay: ["code"] });
+  });
+});
+
+describe("interface entities — OpenAPI emission", () => {
+  it("inferred resources reproduce the /api/{app}/v1/{model}/ contract", () => {
+    const { resources } = analyzeProject(appDir);
+    const doc = buildOpenApi(resources);
+
+    expect(doc.paths["/api/flights/v1/flight/"]).toBeDefined();
+    expect(doc.paths["/api/flights/v1/flight/{id}/"]).toBeDefined();
+    expect(doc.paths["/api/airports/v1/terminal/"]).toBeDefined();
+
+    // The inferred FK carries the relation extension the admin/codegen follow.
+    const flightSchema = doc.components.schemas.Flight;
+    expect(flightSchema.properties.terminal["x-rastack-relation"]).toEqual({
+      app: "airports",
+      model: "terminal",
+    });
+  });
+});

package/types.ts

@@ -1,3 +1,6 @@
+/** `rastack/types` — type-level column config for interface entities. */
+export * from "./src/define/db";
+
 type Primitive = string | number | boolean | null | undefined;
 
 type FlattenedKeys<T> = T extends Primitive

package/dist/rad-compile.d.ts

@@ -1,11 +0,0 @@
-#!/usr/bin/env node
-/**
- * `rad compile | check | list | urls` — the TypeScript-first replacement for the
- * old Django `manage.py rastack` command.
- *
- *   rad compile [resourcesDir] [outDir]   defs → schema.rad.json + openapi.json
- *   rad check   [resourcesDir]            validate the resource graph (exit != 0 on error)
- *   rad list    [resourcesDir]            print every resource + its fields/relations
- *   rad urls    [resourcesDir]            print the generated /api/{app}/v1/{model}/ routes
- */
-export {};

package/dist/rad.d.ts

@@ -1,17 +0,0 @@
-#!/usr/bin/env node
-/**
- * rad — unified CLI for React API Stack
- *
- * Commands:
- *   rad compile [resourcesDir] [outDir]     TypeScript resources → schema.rad.json + openapi.json
- *   rad check   [resourcesDir]              Validate the resource graph
- *   rad list    [resourcesDir]              Print resources, fields and relations
- *   rad urls    [resourcesDir]              Print the generated /api/{app}/v1/{model}/ routes
- *   rad generate [--schema-only]            Generate typed hooks from OpenAPI
- *   rad serve   [--warehouse dir]           Run the Rust API over an Iceberg warehouse
- *   rad admin   [--warehouse dir]           Run the Rust admin (Django-admin-style DB browser)
- *   rad wasm                                Compile the API to WebAssembly (in-browser local dev)
- *   rad scan   [files...] [--fail-on-pii]   Scan CSVs for PII and schema info
- *   rad seed   [--env dev] [--source gs://] Load CSVs into Iceberg namespace
- */
-export {};