@sapporta/server 0.0.1

package/src/api/meta.ts

@@ -0,0 +1,222 @@
+/**
+ * Unified /meta namespace — a thin composition layer.
+ *
+ * Mounted at `/p/{slug}/meta` by the runtime. Composes focused modules
+ * into a single Hono sub-app rather than absorbing their code. Each
+ * concern lives in its own module; this file only wires routes to handlers.
+ *
+ * ## Composed modules
+ *
+ * - Schema introspection (GET /tables, GET /tables/:name) — pure reads
+ *   from the SchemaRegistry, no DB I/O. Uses extractSchemas/extractSchema
+ *   from schema-api.ts.
+ *
+ * - DB introspection (GET /enums, GET /tables/:name/indexes, /sample) —
+ *   thin wrappers over operation functions that query sqlite_master / PRAGMA.
+ *
+ * - Schema mutations (POST/PATCH/DELETE on /tables, /columns, /infer) —
+ *   delegated to metadataApi() which owns transactional DDL, registry sync,
+ *   and LLM inference. ~850 lines of internal cohesion, kept as-is.
+ *
+ * - SQL proxy (POST /sql/query, /sql/exec) — passthrough to db-query/db-exec.
+ *
+ * - Schema sync (POST /schema/sync) — reloads file schemas from disk and
+ *   applies Drizzle migrations.
+ *
+ * ## Route method separation
+ *
+ * The schema introspection GETs and the metadataApi mutations (POST/PATCH/DELETE)
+ * both register routes under `/tables/:name`. This is safe because Hono routes
+ * by HTTP method — GET /tables/:name (introspection) and PATCH /tables/:name
+ * (mutation) don't conflict.
+ */
+import { Hono } from "hono";
+import type Database from "better-sqlite3";
+import type { BetterSQLite3Database } from "drizzle-orm/better-sqlite3";
+import type { SchemaRegistry } from "../schema/registry.js";
+import { extractSchemas, extractSchema } from "../schema/extract.js";
+import { metadataApi } from "./meta-mutations.js";
+import { dbQuery } from "../introspect/query.js";
+import { dbExec } from "../introspect/exec.js";
+// SQLite has no native enum type — the /enums endpoint is removed.
+import { dbIndexes } from "../introspect/indexes.js";
+import { dbSample } from "../introspect/sample.js";
+import { dbDescribeAll } from "../introspect/describe-all.js";
+import { loadSchemas } from "../schema/loader.js";
+import { migrateSchemas } from "../schema/migrate.js";
+import { OperationError } from "../introspect/types.js";
+
+// ── Operation → HTTP error mapping ───────────────────────────────────────────
+//
+// Operation functions (db-query, db-exec, db-enums, etc.) return an OperationResult:
+//   { ok: true, data: ... } | { ok: false, error: string, code: string }
+// or throw `OperationError` with a `.code` property.
+//
+// HTTP endpoints need proper status codes, not just 200/500. This map converts
+// structured error codes to the closest HTTP semantics. Unmapped codes
+// default to 500 (internal server error).
+
+const ERROR_CODE_STATUS: Record<string, number> = {
+  TABLE_NOT_FOUND: 404,
+  INVALID_TABLE_NAME: 400,
+  INVALID_COLUMN_NAME: 400,
+  INVALID_JSON: 400,
+  DANGEROUS_SQL: 400,
+  SELECT_ONLY: 400,
+  PROJECT_NOT_FOUND: 404,
+  REPORT_NOT_FOUND: 404,
+  VALIDATION_FAILED: 422,
+  MISSING_ARGUMENT: 400,
+  INTERNAL: 500,
+};
+
+/** Convert an OperationResult ({ok, data} | {ok: false, error, code}) to an HTTP response. */
+function resultToResponse(c: any, result: any) {
+  if (result.ok) return c.json(result.data);
+  const status = ERROR_CODE_STATUS[result.code] ?? 500;
+  return c.json({ error: result.error }, status);
+}
+
+/**
+ * Run an operation function and convert its result to an HTTP response.
+ * Handles both the OperationResult return pattern and the OperationError throw
+ * pattern — some functions use one, some use the other. This normalizes both
+ * into proper HTTP responses so callers don't need to care.
+ */
+// Accepts both sync (SQLite introspection) and async (report execution) operations.
+function withOperationError(c: any, fn: () => any) {
+  try {
+    const result = fn();
+    return resultToResponse(c, result);
+  } catch (err) {
+    if (err instanceof OperationError) {
+      const status = ERROR_CODE_STATUS[err.code] ?? 500;
+      return c.json({ error: err.message, code: err.code }, status);
+    }
+    throw err;
+  }
+}
+
+// ── API Factory ──────────────────────────────────────────────────────────────
+
+export function metaApi(
+  registry: SchemaRegistry,
+  sqlite: Database.Database,
+  db: BetterSQLite3Database,
+  project: { dir: string | null },
+): Hono {
+  const app = new Hono();
+
+  // ── Schema introspection (pure reads) ──────────────────────────────────
+
+  // GET /tables — list all tables (structure + UI metadata)
+  app.get("/tables", async (c) => {
+    const detail = c.req.query("detail");
+    if (detail === "full") {
+      return withOperationError(c, () => dbDescribeAll(sqlite));
+    }
+    const data = extractSchemas(registry);
+
+    // Merge exact row counts from SQLite.
+    // One COUNT(*) per table — acceptable for SQLite's dataset sizes.
+    for (const table of data) {
+      try {
+        const row = sqlite.prepare(`SELECT COUNT(*) AS cnt FROM "${table.name}"`).get() as { cnt: number } | undefined;
+        table.rowCount = row?.cnt ?? 0;
+      } catch {
+        table.rowCount = 0;
+      }
+    }
+
+    return c.json({ tables: data });
+  });
+
+  // GET /tables/:name — describe single table
+  app.get("/tables/:name", (c) => {
+    const schema = extractSchema(registry, c.req.param("name"));
+    if (!schema) return c.notFound();
+    return c.json(schema);
+  });
+
+  // ── DB introspection ───────────────────────────────────────────────────
+
+  // GET /tables/:name/indexes — table indexes
+  app.get("/tables/:name/indexes", (c) => {
+    return withOperationError(c, () =>
+      dbIndexes(sqlite, c.req.param("name")),
+    );
+  });
+
+  // GET /tables/:name/sample — sample rows
+  app.get("/tables/:name/sample", (c) => {
+    const limit = c.req.query("limit") ? parseInt(c.req.query("limit")!) : undefined;
+    const fields = c.req.query("fields")?.split(",");
+    return withOperationError(c, () =>
+      dbSample(sqlite, c.req.param("name"), limit, fields),
+    );
+  });
+
+  // SQLite has no native enum type — enum values are expressed as
+  // text({ enum: [...] }) in column definitions. No /enums endpoint needed.
+
+  // ── Schema mutations ───────────────────────────────────────────────────
+  // Mount the existing metadataApi for POST/PATCH/DELETE on tables & columns,
+  // plus POST /tables/:name/infer (LLM inference). The GET routes were removed
+  // from metadataApi — they're replaced by the introspection routes above.
+  //
+  // Mounting at "/" means metadataApi's routes are relative to /meta.
+  // For example, metadataApi's `POST /tables` becomes `POST /meta/tables`.
+  // This works alongside the GET /tables route above because Hono dispatches
+  // by HTTP method — they share the same path but different methods.
+  app.route("/", metadataApi(sqlite, registry));
+
+  // ── SQL proxy (admin) ──────────────────────────────────────────────────
+
+  // POST /sql/query — read-only SQL
+  app.post("/sql/query", async (c) => {
+    const body = await c.req.json<{ sql: string; limit?: number }>();
+    return withOperationError(c, () => dbQuery(sqlite, body.sql, body.limit));
+  });
+
+  // POST /sql/exec — mutating SQL
+  app.post("/sql/exec", async (c) => {
+    const body = await c.req.json<{ sql: string; dryRun?: boolean }>();
+    return withOperationError(c, () => dbExec(sqlite, body.sql, body.dryRun));
+  });
+
+  // ── Schema sync ────────────────────────────────────────────────────────
+
+  // POST /schema/sync — reload file schemas from disk and apply Drizzle migrations.
+  //
+  // This is the HTTP equivalent of `sapporta schema sync`. The sequence matters:
+  //   1. Load schemas from disk (picks up new/changed .ts files)
+  //   2. Migrate ONLY file-managed tables (UI tables use direct DDL, not pushSchema)
+  //   3. Re-register in the registry so the new tables appear immediately
+  //      in the dynamic router without a server restart.
+  //
+  // Only file-managed tables are migrated here. UI-managed tables were created
+  // via the mutation API (metadataApi) which applies DDL directly. Running
+  // pushSchema on them risks destructive ALTER statements if metadata drifts
+  // from actual DB state.
+  app.post("/schema/sync", async (c) => {
+    if (!project.dir) {
+      return c.json({ error: "Schema sync requires a project directory", code: "NO_PROJECT_DIR" }, 400);
+    }
+    const schemaDir = `${project.dir}/schema`;
+    const { tables } = await loadSchemas(schemaDir);
+    await migrateSchemas(registry.fileManaged(), db, sqlite);
+
+    // Re-register so new tables appear in the router immediately.
+    // SchemaRegistry.register() is idempotent for same-name same-source entries.
+    for (const def of tables) {
+      registry.register(def, "file");
+    }
+
+    return c.json({
+      ok: true,
+      tables: tables.length,
+    });
+  });
+
+  return app;
+}

package/src/api/reports.ts

@@ -0,0 +1,98 @@
+import { Hono } from "hono";
+import type Database from "better-sqlite3";
+import type { ReportDefinition } from "../reports/report.js";
+import type { ReportSqlClient } from "../reports/engine.js";
+import { executeReport } from "../reports/engine.js";
+import { createReportSqlClient } from "../reports/sqlite-sql-client.js";
+
+/**
+ * Create the /reports API sub-app. Mounted at `/p/{slug}/reports` by the runtime.
+ *
+ * Reports are read-only queries — they never mutate data. This makes GET the
+ * semantically correct method for execution (CQS: queries via GET, commands
+ * via POST). The frontend uses GET /:name/results with params in the query string.
+ *
+ * POST /:name/execute is kept as a fallback for cases where query parameters
+ * exceed URL length limits (~2000 chars in some browser/proxy combinations).
+ * Current reports have a few date/filter params and won't hit this limit,
+ * but it future-proofs against complex filter expressions.
+ *
+ * Both endpoints call the same executeReport() engine — they differ only in
+ * where they read the parameters from (query string vs request body).
+ *
+ * The sqlite handle is wrapped via createReportSqlClient() into the
+ * ReportSqlClient interface that executeReport() expects. This adapter
+ * maps better-sqlite3's synchronous .prepare().all() to the async
+ * ReportSqlClient.unsafe() interface.
+ */
+export function reportApi(
+  reports: ReportDefinition[],
+  sqlite: Database.Database,
+): Hono {
+  // Wrap the SQLite handle once at mount time. The adapter is stateless —
+  // it just forwards queries to sqlite.prepare().all() and wraps results
+  // in Promise.resolve(). One adapter per project, not per request.
+  const sql: ReportSqlClient = createReportSqlClient(sqlite);
+  const reportMap = new Map(reports.map((r) => [r.name, r]));
+
+  const app = new Hono();
+
+  // List available reports — consumed by the sidebar to build navigation
+  app.get("/", (c) => {
+    return c.json({
+      reports: reports.map((r) => ({
+        name: r.name,
+        label: r.label,
+        params: r.params,
+      })),
+    });
+  });
+
+  // Get report metadata
+  app.get("/:name", (c) => {
+    const report = reportMap.get(c.req.param("name"));
+    if (!report) return c.json({ error: "Report not found" }, 404);
+    return c.json({
+      name: report.name,
+      label: report.label,
+      params: report.params,
+      columns: report.tree.columns,
+    });
+  });
+
+  // Execute report via GET — primary method. Params come from the query string.
+  // The frontend serializes each param as a simple key=value pair.
+  app.get("/:name/results", async (c) => {
+    const report = reportMap.get(c.req.param("name"));
+    if (!report) return c.json({ error: "Report not found" }, 404);
+
+    const params: Record<string, string> = {};
+    for (const [key, value] of Object.entries(c.req.query())) {
+      params[key] = value;
+    }
+
+    const result = await executeReport(sql, report, params);
+    return c.json(result);
+  });
+
+  // Execute report via POST — fallback for long parameter lists that would
+  // exceed query string length limits. Same engine, params from request body.
+  app.post("/:name/execute", async (c) => {
+    const report = reportMap.get(c.req.param("name"));
+    if (!report) return c.json({ error: "Report not found" }, 404);
+
+    const body = await c.req.json();
+    const result = await executeReport(sql, report, body.params ?? {});
+    return c.json(result);
+  });
+
+  // Catch parameter validation errors and return 400 instead of 500
+  app.onError((err, c) => {
+    if (err.message.startsWith("Required parameter")) {
+      return c.json({ error: err.message }, 400);
+    }
+    throw err;
+  });
+
+  return app;
+}

package/src/api/server.ts

@@ -0,0 +1,24 @@
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+import { requestLogger } from "../db/logger.js";
+
+/**
+ * Create the root Hono app with global middleware and the health endpoint.
+ *
+ * This is the bare app before any project-scoped routes are mounted.
+ * The runtime calls createApp() once, then mounts project namespaces
+ * under /p/{slug}/... and the global /_projects endpoint.
+ *
+ * The /health endpoint is outside all project scopes — it's used by
+ * load balancers and monitoring to check if the server is alive.
+ */
+export function createApp() {
+  const app = new Hono();
+
+  app.use("*", requestLogger());
+  app.use("*", cors());
+
+  app.get("/health", (c) => c.json({ status: "ok" }));
+
+  return app;
+}

package/src/api/tables.ts

@@ -0,0 +1,108 @@
+import { Hono, type Context } from "hono";
+import type { SchemaRegistry } from "../schema/registry.js";
+import type { TableDef } from "../schema/table.js";
+import { handleList, handleGet, handleCreate, handleUpdate, handleDelete } from "../data/crud.js";
+import { handleLookup } from "../data/lookup.js";
+import { handleCount } from "../data/count.js";
+import { logger } from "../db/logger.js";
+
+const log = logger.child({ module: "crud" });
+
+// ---------------------------------------------------------------------------
+// Dynamic parametric routing for table CRUD, lookup, and count endpoints.
+//
+// Mounted at `/p/{slug}/tables` by the runtime.
+//
+// Returns a Hono sub-app with parametric /:tableName/* routes. On each request
+// the handler resolves the table name from the SchemaRegistry — a live,
+// mutable Map. This means tables added at runtime (via the mutation API or
+// schema sync) are immediately accessible without re-mounting routes or
+// restarting the server.
+//
+// Key invariant: the SchemaRegistry is the single source of truth for which
+// tables exist. If a table is in the registry, it's routable. If it's been
+// unregistered (e.g., dropped via DDL), requests return 404/410.
+//
+// No per-table sub-apps, no URL rewriting, no schema caching. Resolution is
+// a single synchronous Map.get() per request.
+// ---------------------------------------------------------------------------
+
+/**
+ * Create the /tables API sub-app for dynamic table routing.
+ *
+ * Handles:
+ *   GET    /:table              list rows (filtered, sorted, paginated)
+ *   GET    /:table/:id          get single row
+ *   POST   /:table              create row(s), master-detail
+ *   PUT    /:table/:id          update row
+ *   DELETE /:table/:id          delete row
+ *   GET    /:table/_lookup      FK display values
+ *   GET    /:table/_count       grouped child counts
+ *
+ * Tables added at runtime via the registry are immediately accessible —
+ * the router reads from the registry on each request.
+ */
+export function tablesApi(registry: SchemaRegistry, db: any): Hono {
+  const app = new Hono();
+
+  /**
+   * Middleware that resolves the :tableName param against the registry.
+   *
+   * Returns 404 if the table isn't registered. If the table IS registered but
+   * the underlying DB table has been dropped externally (e.g., by direct DDL
+   * or a failed migration), SQLite will throw a SqliteError with a message
+   * containing "no such table". In that case we unregister the stale entry
+   * and return 410 Gone — this keeps the registry consistent and prevents
+   * repeated 500s on a dead table.
+   */
+  function withSchema(
+    handler: (schema: TableDef, db: any, c: Context) => Promise<Response>,
+  ) {
+    return async (c: Context) => {
+      const tableName = c.req.param("tableName");
+      const entry = registry.get(tableName);
+      if (!entry) return c.notFound();
+      try {
+        return await handler(entry.def, db, c);
+      } catch (err: any) {
+        // better-sqlite3 throws SqliteError whose message includes "no such table"
+        // when a table has been dropped externally. This replaces the Postgres
+        // error code check (42P01) from the pre-SQLite migration.
+        if (err?.message?.includes("no such table")) {
+          log.warn("Table no longer exists", { table: tableName });
+          registry.unregister(tableName);
+          return c.json(
+            { error: `Table "${tableName}" no longer exists in the database` },
+            { status: 410 },
+          );
+        }
+        throw err;
+      }
+    };
+  }
+
+  // ── Route ordering within this sub-app ───────────────────────────────
+  //
+  // _lookup and _count MUST be registered before the /:tableName/:id route.
+  // Hono matches routes top-to-bottom; /:tableName/:id would capture
+  // "/_lookup" as the :id param if it came first. The underscore prefix is
+  // a naming convention only — it doesn't affect routing priority.
+  //
+  // This ordering constraint is LOCAL to this sub-app. It does NOT affect
+  // the five namespace mounts in runtime.ts (which use distinct prefixes
+  // and are order-independent).
+  app.get("/:tableName/_lookup", withSchema((s, d, c) => handleLookup(s, d, c)));
+  app.get("/:tableName/_count", withSchema((s, d, c) => handleCount(s, d, c)));
+
+  // CRUD — the generic /:tableName/:id comes after the specific sub-paths above.
+  app.get("/:tableName", withSchema((s, d, c) => handleList(s, d, c)));
+  app.get("/:tableName/:id", withSchema((s, d, c) =>
+    handleGet(s, d, c, c.req.param("id"))));
+  app.post("/:tableName", withSchema((s, d, c) => handleCreate(s, d, c)));
+  app.put("/:tableName/:id", withSchema((s, d, c) =>
+    handleUpdate(s, d, c, c.req.param("id"))));
+  app.delete("/:tableName/:id", withSchema((s, d, c) =>
+    handleDelete(s, d, c, c.req.param("id"))));
+
+  return app;
+}

package/src/api/views.ts

@@ -0,0 +1,44 @@
+import { Hono } from "hono";
+import type { ViewMeta } from "../views/view.js";
+
+/**
+ * Hono sub-app for view metadata.
+ * Mounted at `/p/{slug}/views` by the runtime.
+ *
+ * These endpoints serve metadata only (name, label, icon). The actual
+ * React component code is NOT served through this API — it's served by
+ * Vite directly from the project's views/ directory via the sapportaViews
+ * plugin (see packages/ui/vite-plugin-sapporta-views.ts).
+ *
+ * The split is intentional: the backend loads .tsx files with `tsx` to
+ * extract only the `meta` export (lightweight, no React needed on the server).
+ * The frontend uses Vite's virtual module system to lazy-load the full
+ * component with HMR support. This means:
+ *   - Backend: reads meta from .tsx files → serves JSON via this API
+ *   - Frontend: Vite plugin discovers view files → generates dynamic imports
+ *   - The sidebar populates from this API; the component loads from Vite
+ */
+export function viewApi(views: ViewMeta[]): Hono {
+  const viewMap = new Map(views.map((v) => [v.name, v]));
+  const app = new Hono();
+
+  // List available views — consumed by the UI to populate the sidebar
+  app.get("/", (c) => {
+    return c.json({
+      views: views.map((v) => ({
+        name: v.name,
+        label: v.label,
+        icon: v.icon,
+      })),
+    });
+  });
+
+  // Get single view's metadata
+  app.get("/:name", (c) => {
+    const view = viewMap.get(c.req.param("name"));
+    if (!view) return c.json({ error: "View not found" }, 404);
+    return c.json(view);
+  });
+
+  return app;
+}