@sapporta/server 0.0.1

package/src/db/sqlite-connection.test.ts

@@ -0,0 +1,59 @@
+import { describe, it, expect } from "vitest";
+import { connectProject } from "./sqlite-connection.js";
+
+describe("connectProject", () => {
+  it("connects to an in-memory database", () => {
+    const { sqlite, db } = connectProject(":memory:");
+    expect(sqlite).toBeDefined();
+    expect(db).toBeDefined();
+    sqlite.close();
+  });
+
+  it("sets WAL journal mode", () => {
+    const { sqlite } = connectProject(":memory:");
+    // WAL mode returns "memory" for :memory: databases (WAL requires a file),
+    // but the pragma call itself must not throw.
+    const mode = sqlite.pragma("journal_mode") as { journal_mode: string }[];
+    expect(mode[0].journal_mode).toMatch(/wal|memory/);
+    sqlite.close();
+  });
+
+  it("enables foreign keys", () => {
+    const { sqlite } = connectProject(":memory:");
+    const fk = sqlite.pragma("foreign_keys") as { foreign_keys: number }[];
+    expect(fk[0].foreign_keys).toBe(1);
+    sqlite.close();
+  });
+
+  it("enforces foreign key constraints at runtime", () => {
+    const { sqlite } = connectProject(":memory:");
+    sqlite.exec(`CREATE TABLE parent (id INTEGER PRIMARY KEY)`);
+    sqlite.exec(`CREATE TABLE child (id INTEGER PRIMARY KEY, parent_id INTEGER REFERENCES parent(id))`);
+
+    // Inserting a child with a non-existent parent should fail
+    expect(() => {
+      sqlite.prepare("INSERT INTO child (id, parent_id) VALUES (1, 999)").run();
+    }).toThrow(/FOREIGN KEY/);
+
+    sqlite.close();
+  });
+
+  it("closes without error", () => {
+    const { sqlite } = connectProject(":memory:");
+    expect(() => sqlite.close()).not.toThrow();
+  });
+
+  it("returns a working Drizzle instance", () => {
+    const { sqlite, db } = connectProject(":memory:");
+    sqlite.exec("CREATE TABLE test (id INTEGER PRIMARY KEY, name TEXT)");
+    sqlite.prepare("INSERT INTO test (id, name) VALUES (1, 'hello')").run();
+
+    // Verify Drizzle can query via sql.raw
+    const { sql } = require("drizzle-orm");
+    const rows = db.all(sql.raw("SELECT * FROM test"));
+    expect(rows).toHaveLength(1);
+    expect(rows[0]).toMatchObject({ id: 1, name: "hello" });
+
+    sqlite.close();
+  });
+});

package/src/db/sqlite-connection.ts

@@ -0,0 +1,79 @@
+// ============================================================================
+// SQLite Connection — project database connection for SQLite-backed projects
+// ============================================================================
+//
+// Each Sapporta project gets its own SQLite database file. This module creates
+// the connection with optimized PRAGMAs for a multi-reader, single-writer
+// web application workload.
+//
+// Design: No abstraction layer — better-sqlite3's Database type is used
+// directly throughout the codebase. The synchronous API naturally serializes
+// writes, eliminating SQLITE_BUSY contention that plagues async drivers.
+// If a different driver is ever needed, refactor then (YAGNI).
+//
+// The Drizzle ORM wrapper is returned alongside the raw handle because:
+// - Raw handle: PRAGMA introspection, raw SQL, explicit transactions
+// - Drizzle db: typed ORM queries, schema push via drizzle-kit/api
+
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import Database from "better-sqlite3";
+import { drizzle, type BetterSQLite3Database } from "drizzle-orm/better-sqlite3";
+
+export interface ProjectDbConnection {
+  /** Raw better-sqlite3 handle — used for PRAGMAs, raw SQL, transactions */
+  sqlite: Database.Database;
+  /** Drizzle ORM wrapper — used for typed queries and schema push */
+  db: BetterSQLite3Database;
+}
+
+/**
+ * Open a SQLite database and configure it for server workloads.
+ *
+ * PRAGMA ordering matters:
+ * 1. journal_mode=WAL must be set first — it changes the file format and
+ *    affects how subsequent PRAGMAs interact with the database.
+ * 2. foreign_keys=ON must be set per-connection (not persisted in the file),
+ *    so it runs on every open.
+ * 3. The remaining PRAGMAs are performance tuning and order-independent.
+ *
+ * @param filepath Path to the .sqlite file, or ":memory:" for tests.
+ */
+export function connectProject(filepath: string): ProjectDbConnection {
+  if (filepath !== ":memory:") {
+    const dir = dirname(resolve(filepath));
+    if (!existsSync(dir)) {
+      throw new Error(
+        `Cannot open database "${resolve(filepath)}": parent directory "${dir}" does not exist`,
+      );
+    }
+  }
+
+  const sqlite = new Database(filepath);
+
+  // WAL mode: allows concurrent reads while writing. Must be set before
+  // any other operations on the database. Persists across connections
+  // (stored in the file), but setting it is idempotent.
+  sqlite.pragma("journal_mode = WAL");
+
+  // Busy timeout: wait up to 5 seconds for locks instead of failing
+  // immediately. Prevents transient SQLITE_BUSY errors under load.
+  sqlite.pragma("busy_timeout = 5000");
+
+  // NORMAL sync: WAL mode already provides crash safety via the WAL file.
+  // NORMAL skips the extra fsync on each commit, trading a tiny risk of
+  // losing the last transaction on OS crash for ~2x write throughput.
+  sqlite.pragma("synchronous = NORMAL");
+
+  // Foreign keys: OFF by default in SQLite (historical compatibility).
+  // Must be enabled per-connection — not persisted in the database file.
+  sqlite.pragma("foreign_keys = ON");
+
+  // 8MB page cache: SQLite's default is ~2MB. More cache means fewer
+  // disk reads for repeated queries against the same pages.
+  // Negative value = size in KiB (so -8000 ≈ 8MB).
+  sqlite.pragma("cache_size = -8000");
+
+  const db = drizzle(sqlite);
+  return { sqlite, db };
+}

package/src/index.ts

@@ -0,0 +1,111 @@
+// @sapporta/server - public API
+
+// Server
+export { createApp } from "./api/server.js";
+
+// Table definition
+export { table } from "./schema/table.js";
+export type {
+  TableDef,
+  TableOptions,
+  SapportaMeta,
+  SelectMeta,
+  ChildMeta,
+} from "./schema/table.js";
+
+// Schema loader
+export { loadSchemas } from "./schema/loader.js";
+export type { SchemaLoadResult } from "./schema/loader.js";
+
+// Schema diff / migration
+export { migrateSchemas } from "./schema/migrate.js";
+
+// Validation
+export { buildZodSchema, validate } from "./data/validate.js";
+export type { ValidationErrorDetail } from "./data/validate.js";
+
+// Save pipeline
+export { savePipeline, insertRow, updateRow } from "./data/save-pipeline.js";
+
+// Query parser
+export { parseQuery } from "./data/query-parser.js";
+export type { ParsedQuery } from "./data/query-parser.js";
+
+// CRUD
+export { crud, handleList, handleGet, handleCreate, handleUpdate, handleDelete } from "./data/crud.js";
+
+// Schema API
+export { schemaApi, extractSchemas, extractSchema } from "./schema/extract.js";
+export type { TableSchema, ColumnSchema, ChildSchema } from "./schema/extract.js";
+
+// Lookup
+export { lookupEndpoint, handleLookup, findDisplayColumn } from "./data/lookup.js";
+
+// Count
+export { countEndpoint, handleCount } from "./data/count.js";
+
+// Schema registry
+export { SchemaRegistry } from "./schema/registry.js";
+export type { RegistryEntry } from "./schema/registry.js";
+
+// Tables API (dynamic CRUD routing)
+export { tablesApi } from "./api/tables.js";
+
+// Dynamic table builder
+export { buildDrizzleTable, planTable, realizeTable, generateCreateTableDDL, generateAddColumnDDL, sqliteTypeForColumnType, VALID_COLUMN_TYPES } from "./schema/dynamic-builder.js";
+export type { TableMeta, ColumnMetaRow, TableSpec, ColumnSpec } from "./schema/dynamic-builder.js";
+
+// Metadata tables (UI-managed table definitions)
+export { ensureMetadataTables, loadUISchemas, validateUISchemas } from "./schema/metadata-tables.js";
+
+// Metadata mutation API
+export { metadataApi } from "./api/meta-mutations.js";
+
+// Meta API (unified /meta namespace)
+export { metaApi } from "./api/meta.js";
+
+// Name validation
+export { validateTableName, validateColumnName } from "./schema/reserved.js";
+
+// Actions
+export { action } from "./actions/action.js";
+export type { ActionConfig, ActionInstance } from "./actions/action.js";
+export { loadActions } from "./actions/loader.js";
+export { actionApi } from "./api/actions.js";
+
+// Reports
+export { report } from "./reports/report.js";
+export type {
+  ReportDefinition,
+  ReportParam,
+  ReportSource,
+  ReportTreeNode,
+  ReportOutputNode,
+  ReportFooterRow,
+  ReportResult,
+  ReportSort,
+  ReportFooter,
+  TransformContext,
+} from "./reports/report.js";
+export { executeReport } from "./reports/engine.js";
+export { loadReports } from "./reports/loader.js";
+export { reportApi } from "./api/reports.js";
+
+// Views
+export type { ViewMeta } from "./views/view.js";
+export { loadViewMeta } from "./views/loader.js";
+export { viewApi } from "./api/views.js";
+
+// Boot (single-project)
+export { bootProject } from "./boot.js";
+export type { InProcessProject, ProjectConfig } from "./boot.js";
+
+// SQLite connection
+export { connectProject } from "./db/sqlite-connection.js";
+export type { ProjectDbConnection } from "./db/sqlite-connection.js";
+
+// Errors
+export { ValidationError, ActionError } from "./db/errors.js";
+
+// Test utilities
+export { createTestDb } from "./testing/test-utils.js";

package/src/integration/api-actions.test.ts

@@ -0,0 +1,60 @@
+/**
+ * Integration tests for the /actions namespace (single-project mode).
+ */
+import { describe, it, expect, beforeAll } from "vitest";
+import { createIntegrationApp, request, postJson } from "./setup.js";
+
+beforeAll(async () => {
+  await createIntegrationApp();
+});
+
+describe("/actions", () => {
+  it("GET /actions lists actions with name and inputSchema", async () => {
+    const res = await request("/actions");
+    expect(res.status).toBe(200);
+
+    const body = await res.json();
+    expect(body.actions).toHaveLength(1);
+
+    const action = body.actions[0];
+    expect(action.name).toBe("create_account");
+    expect(action.label).toBe("Create Account");
+    expect(action.inputSchema).toBeDefined();
+    expect(action.inputSchema.type).toBe("object");
+    expect(action.inputSchema.properties).toHaveProperty("name");
+    expect(action.inputSchema.properties).toHaveProperty("type");
+  });
+
+  it("POST /actions/create_account with valid input succeeds", async () => {
+    const res = await postJson("/actions/create_account", {
+      name: "Action Cash",
+      type: "asset",
+      balance: 5000,
+    });
+    expect(res.status).toBe(200);
+
+    const body = await res.json();
+    expect(body.data).toBeDefined();
+    expect(body.data.name).toBe("Action Cash");
+    expect(body.data.type).toBe("asset");
+    expect(body.data.balance).toBe(5000);
+    expect(body.data.id).toBeGreaterThan(0);
+  });
+
+  it("POST /actions/create_account with invalid input returns 422", async () => {
+    const res = await postJson("/actions/create_account", {
+      type: "invalid_type",
+    });
+    expect(res.status).toBe(422);
+
+    const body = await res.json();
+    expect(body.error).toBe("Validation failed");
+    expect(body.details).toBeDefined();
+    expect(Array.isArray(body.details)).toBe(true);
+  });
+
+  it("POST /actions/nonexistent returns 404", async () => {
+    const res = await postJson("/actions/nonexistent", {});
+    expect(res.status).toBe(404);
+  });
+});

package/src/integration/api-global.test.ts

@@ -0,0 +1,21 @@
+/**
+ * Integration tests for global (non-project-scoped) endpoints.
+ *
+ * These validate that the entire boot sequence completes successfully
+ * and the health endpoint responds correctly.
+ */
+import { describe, it, expect, beforeAll } from "vitest";
+import { createIntegrationApp, request } from "./setup.js";
+
+beforeAll(async () => {
+  await createIntegrationApp();
+});
+
+describe("GET /health", () => {
+  it("returns 200 with status ok", async () => {
+    const res = await request("/health");
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body).toEqual({ status: "ok" });
+  });
+});

package/src/integration/api-meta.test.ts

@@ -0,0 +1,252 @@
+/**
+ * Integration tests for the /meta namespace (single-project mode).
+ *
+ * The meta namespace composes schema introspection, DB introspection,
+ * schema mutations (UI tables), and a SQL proxy.
+ */
+import { describe, it, expect, beforeAll } from "vitest";
+import { createIntegrationApp, request, postJson, patchJson, del } from "./setup.js";
+
+beforeAll(async () => {
+  await createIntegrationApp();
+});
+
+describe("/meta", () => {
+  // ── Schema introspection ──────────────────────────────────────────
+
+  describe("schema introspection", () => {
+    it("GET /meta/tables lists all tables with structure", async () => {
+      const res = await request("/meta/tables");
+      expect(res.status).toBe(200);
+
+      const body = await res.json();
+      expect(body.tables).toBeDefined();
+      // 3 fixture schemas: accounts, journal_entries, audit_log
+      expect(body.tables).toHaveLength(3);
+
+      const names = body.tables.map((t: any) => t.name).sort();
+      expect(names).toEqual(["accounts", "audit_log", "journal_entries"]);
+
+      const accounts = body.tables.find((t: any) => t.name === "accounts");
+      expect(accounts.label).toBe("Accounts");
+      expect(accounts.source).toBe("file");
+      expect(accounts.columns.length).toBeGreaterThan(0);
+      expect(accounts.rowCount).toBeGreaterThanOrEqual(0);
+    });
+
+    it("GET /meta/tables/accounts returns single table with columns and selects", async () => {
+      const res = await request("/meta/tables/accounts");
+      expect(res.status).toBe(200);
+
+      const body = await res.json();
+      expect(body.name).toBe("accounts");
+      expect(body.label).toBe("Accounts");
+      expect(body.immutable).toBe(false);
+      expect(body.source).toBe("file");
+
+      const colNames = body.columns.map((c: any) => c.name);
+      expect(colNames).toContain("id");
+      expect(colNames).toContain("name");
+      expect(colNames).toContain("type");
+      expect(colNames).toContain("balance");
+
+      const typeCol = body.columns.find((c: any) => c.name === "type");
+      expect(typeCol.select).toBeDefined();
+      expect(typeCol.select.options).toEqual(
+        ["asset", "liability", "equity", "revenue", "expense"],
+      );
+    });
+
+    it("GET /meta/tables/nonexistent returns 404", async () => {
+      const res = await request("/meta/tables/nonexistent");
+      expect(res.status).toBe(404);
+    });
+  });
+
+  // ── DB introspection ──────────────────────────────────────────────
+
+  describe("DB introspection", () => {
+    it("GET /meta/tables/accounts/indexes returns index list", async () => {
+      const res = await request("/meta/tables/accounts/indexes");
+      expect(res.status).toBe(200);
+
+      const body = await res.json();
+      expect(Array.isArray(body)).toBe(true);
+    });
+
+    it("GET /meta/tables/accounts/sample returns sample rows", async () => {
+      await postJson("/tables/accounts", { name: "SampleAccount", type: "asset" });
+
+      const res = await request("/meta/tables/accounts/sample");
+      expect(res.status).toBe(200);
+
+      const body = await res.json();
+      expect(Array.isArray(body)).toBe(true);
+      expect(body.length).toBeGreaterThan(0);
+    });
+
+    it("GET /meta/enums returns 404 (SQLite has no native enum type)", async () => {
+      const res = await request("/meta/enums");
+      expect(res.status).toBe(404);
+    });
+  });
+
+  // ── SQL proxy ─────────────────────────────────────────────────────
+
+  describe("SQL proxy", () => {
+    it("POST /meta/sql/query runs a SELECT", async () => {
+      await postJson("/tables/accounts", { name: "SQLTestAccount", type: "equity" });
+
+      const res = await postJson("/meta/sql/query", {
+        sql: "SELECT name, type FROM accounts WHERE type = 'equity'",
+      });
+      expect(res.status).toBe(200);
+
+      const body = await res.json();
+      expect(Array.isArray(body)).toBe(true);
+      expect(body.length).toBeGreaterThanOrEqual(1);
+      expect(body[0].name).toBe("SQLTestAccount");
+    });
+
+    it("POST /meta/sql/query with INSERT returns 400 SELECT_ONLY", async () => {
+      const res = await postJson("/meta/sql/query", {
+        sql: "INSERT INTO accounts (name, type) VALUES ('hack', 'asset')",
+      });
+      expect(res.status).toBe(400);
+    });
+
+    it("POST /meta/sql/exec runs an INSERT", async () => {
+      const res = await postJson("/meta/sql/exec", {
+        sql: "INSERT INTO accounts (name, type) VALUES ('ExecTest', 'liability')",
+      });
+      expect(res.status).toBe(200);
+
+      const check = await postJson("/meta/sql/query", {
+        sql: "SELECT name FROM accounts WHERE name = 'ExecTest'",
+      });
+      const rows = await check.json();
+      expect(rows.length).toBe(1);
+    });
+  });
+
+  // ── Schema mutations (UI tables) ──────────────────────────────────
+
+  describe("schema mutations (UI tables)", () => {
+    it("POST /meta/tables creates a UI table", async () => {
+      const res = await postJson("/meta/tables", {
+        name: "ui_contacts",
+        label: "Contacts",
+      });
+      expect(res.status).toBe(201);
+
+      const body = await res.json();
+      expect(body.name).toBe("ui_contacts");
+      expect(body.label).toBe("Contacts");
+    });
+
+    it("POST /meta/tables with duplicate name returns 409", async () => {
+      const res = await postJson("/meta/tables", {
+        name: "ui_contacts",
+        label: "Contacts Again",
+      });
+      expect(res.status).toBe(409);
+    });
+
+    it("PATCH /meta/tables/:name updates a UI table label", async () => {
+      const res = await patchJson("/meta/tables/ui_contacts", {
+        label: "My Contacts",
+      });
+      expect(res.status).toBe(200);
+
+      const body = await res.json();
+      expect(body.ok).toBe(true);
+    });
+
+    it("PATCH /meta/tables/accounts (file-managed) returns 409", async () => {
+      const res = await patchJson("/meta/tables/accounts", {
+        label: "Hacked",
+      });
+      expect(res.status).toBe(409);
+    });
+
+    it("POST /meta/tables/:name/columns adds a column to a UI table", async () => {
+      const res = await postJson("/meta/tables/ui_contacts/columns", {
+        column_name: "email",
+        column_type: "email",
+      });
+      expect(res.status).toBe(201);
+
+      const body = await res.json();
+      expect(body.ok).toBe(true);
+      expect(body.column).toBe("email");
+    });
+
+    it("DELETE /meta/tables/:name/columns/:col drops a column", async () => {
+      const res = await del("/meta/tables/ui_contacts/columns/email");
+      expect(res.status).toBe(200);
+
+      const body = await res.json();
+      expect(body.ok).toBe(true);
+      expect(body.dropped).toBe("email");
+    });
+
+    it("DELETE /meta/tables/:name without confirm returns 409 with rowCount", async () => {
+      await postJson("/meta/sql/exec", {
+        sql: "INSERT INTO ui_contacts (id) VALUES (1)",
+      });
+
+      const res = await del("/meta/tables/ui_contacts");
+      expect(res.status).toBe(409);
+
+      const body = await res.json();
+      expect(body.rowCount).toBeGreaterThanOrEqual(1);
+    });
+
+    it("DELETE /meta/tables/:name?confirm=true drops the table", async () => {
+      const res = await del("/meta/tables/ui_contacts", "confirm=true");
+      expect(res.status).toBe(200);
+
+      const body = await res.json();
+      expect(body.ok).toBe(true);
+      expect(body.dropped).toBe("ui_contacts");
+
+      const check = await request("/meta/tables/ui_contacts");
+      expect(check.status).toBe(404);
+    });
+  });
+
+  // ── Cross-namespace test ──────────────────────────────────────────
+
+  describe("cross-namespace", () => {
+    it("create UI table via /meta, CRUD via /tables, query via /meta/sql", async () => {
+      const createRes = await postJson("/meta/tables", {
+        name: "ui_tasks",
+        label: "Tasks",
+        columns: [
+          { column_name: "title", column_type: "text" },
+        ],
+      });
+      expect(createRes.status).toBe(201);
+
+      const insertRes = await postJson("/tables/ui_tasks", {
+        title: "Write integration tests",
+      });
+      expect(insertRes.status).toBe(201);
+      const taskId = (await insertRes.json()).data.id;
+
+      const readRes = await request(`/tables/ui_tasks/${taskId}`);
+      expect(readRes.status).toBe(200);
+      const readBody = await readRes.json();
+      expect(readBody.data.title).toBe("Write integration tests");
+
+      const sqlRes = await postJson("/meta/sql/query", {
+        sql: "SELECT title FROM ui_tasks WHERE id = 1",
+      });
+      expect(sqlRes.status).toBe(200);
+      const sqlRows = await sqlRes.json();
+      expect(sqlRows[0].title).toBe("Write integration tests");
+
+      await del("/meta/tables/ui_tasks", "confirm=true");
+    });
+  });
+});

package/src/integration/api-reports.test.ts

@@ -0,0 +1,77 @@
+/**
+ * Integration tests for the /reports namespace (single-project mode).
+ */
+import { describe, it, expect, beforeAll } from "vitest";
+import { createIntegrationApp, request, postJson } from "./setup.js";
+
+beforeAll(async () => {
+  await createIntegrationApp();
+
+  // Seed accounts data for report tests.
+  await postJson("/tables/accounts", { name: "Cash", type: "asset", balance: 10000 });
+  await postJson("/tables/accounts", { name: "Revenue", type: "revenue", balance: 5000 });
+  await postJson("/tables/accounts", { name: "Equipment", type: "asset", balance: 25000 });
+});
+
+describe("/reports", () => {
+  it("GET /reports lists reports with name, label, params", async () => {
+    const res = await request("/reports");
+    expect(res.status).toBe(200);
+
+    const body = await res.json();
+    expect(body.reports).toHaveLength(1);
+
+    const report = body.reports[0];
+    expect(report.name).toBe("account-list");
+    expect(report.label).toBe("Account List");
+    expect(report.params).toHaveLength(1);
+    expect(report.params[0].name).toBe("type");
+    expect(report.params[0].required).toBe(false);
+  });
+
+  it("GET /reports/account-list returns metadata with columns", async () => {
+    const res = await request("/reports/account-list");
+    expect(res.status).toBe(200);
+
+    const body = await res.json();
+    expect(body.name).toBe("account-list");
+    expect(body.label).toBe("Account List");
+    expect(body.columns).toHaveLength(3);
+
+    const colNames = body.columns.map((c: any) => c.name);
+    expect(colNames).toEqual(["name", "type", "balance"]);
+  });
+
+  it("GET /reports/nonexistent returns 404", async () => {
+    const res = await request("/reports/nonexistent");
+    expect(res.status).toBe(404);
+  });
+
+  it("GET /reports/account-list/results executes the report", async () => {
+    const res = await request("/reports/account-list/results");
+    expect(res.status).toBe(200);
+
+    const body = await res.json();
+    expect(body.data).toBeDefined();
+    expect(body.data).toHaveLength(3);
+
+    const first = body.data[0];
+    expect(first.levelName).toBe("account");
+    expect(first.columns).toBeDefined();
+    expect(first.columns).toHaveProperty("name");
+    expect(first.columns).toHaveProperty("type");
+    expect(first.columns).toHaveProperty("balance");
+  });
+
+  it("GET /reports/account-list/results?type=asset returns filtered results", async () => {
+    const res = await request("/reports/account-list/results?type=asset");
+    expect(res.status).toBe(200);
+
+    const body = await res.json();
+    expect(body.data).toBeDefined();
+    expect(body.data).toHaveLength(2);
+    for (const node of body.data) {
+      expect(node.columns.type).toBe("asset");
+    }
+  });
+});