@sapporta/server 0.0.1

package/src/cli/request.ts

@@ -0,0 +1,146 @@
+/**
+ * Request building and response rendering for CLI → API bridge.
+ *
+ * Side-effect-free — safe to import from other packages (e.g. control-plane CLI).
+ */
+import type { CliRoute } from "./routes.js";
+import { formatTable, type OutputFormat } from "./format.js";
+
+// ---------------------------------------------------------------------------
+// System flags — excluded from body/query param building
+// ---------------------------------------------------------------------------
+
+/** Flags consumed by the CLI framework, never forwarded to the API. */
+const SYSTEM_FLAGS = new Set(["_", "output", "project", "json", "api-url", "token"]);
+
+// ---------------------------------------------------------------------------
+// Request building (pure, testable)
+// ---------------------------------------------------------------------------
+
+export interface RequestSpec {
+  method: string;
+  urlPath: string;
+  body?: unknown;
+  queryParams?: Record<string, string>;
+}
+
+/**
+ * Build an HTTP request spec from a matched route and parsed flags.
+ * Pure function — no I/O, fully testable.
+ */
+export function buildRequest(
+  route: CliRoute,
+  params: Record<string, string>,
+  allFlags: Record<string, any>,
+): RequestSpec {
+  let urlPath = route.path;
+  for (const [key, value] of Object.entries(params)) {
+    urlPath = urlPath.replace(`:${key}`, encodeURIComponent(value));
+  }
+
+  let body: unknown | undefined;
+  if (route.method === "POST" || route.method === "PUT" || route.method === "PATCH") {
+    if (allFlags.json) {
+      body = JSON.parse(allFlags.json);
+      if (route.inputSchema) {
+        body = route.inputSchema.parse(body);
+      }
+    } else if (route.bodyField && allFlags[route.bodyField]) {
+      body = JSON.parse(allFlags[route.bodyField]);
+    } else if (route.inputSchema) {
+      const schemaBody: Record<string, unknown> = {};
+      if (route.positionalArgs) {
+        const positionals = allFlags._ as unknown as string[];
+        if (positionals) {
+          for (let i = 0; i < route.positionalArgs.length && i < positionals.length; i++) {
+            schemaBody[route.positionalArgs[i].field] = positionals[i];
+          }
+        }
+      }
+      for (const [key, value] of Object.entries(allFlags)) {
+        if (SYSTEM_FLAGS.has(key) || key === "dry-run") continue;
+        schemaBody[key] = value;
+      }
+      if (allFlags["dry-run"]) {
+        schemaBody.dryRun = true;
+      }
+      if (route.flagMap) {
+        for (const [cliKey, bodyKey] of Object.entries(route.flagMap)) {
+          if (cliKey in schemaBody) {
+            schemaBody[bodyKey] = schemaBody[cliKey];
+            delete schemaBody[cliKey];
+          }
+        }
+      }
+      if (Object.keys(schemaBody).length > 0) {
+        body = route.inputSchema.parse(schemaBody);
+      }
+    }
+  }
+
+  const queryParams: Record<string, string> = {};
+  if (route.queryFlags) {
+    if (route.queryFlags.includes("*")) {
+      for (const [key, value] of Object.entries(allFlags)) {
+        if (SYSTEM_FLAGS.has(key)) continue;
+        queryParams[key] = value;
+      }
+    } else {
+      for (const flag of route.queryFlags) {
+        if (allFlags[flag]) queryParams[flag] = allFlags[flag];
+      }
+    }
+  }
+
+  return {
+    method: route.method,
+    urlPath,
+    body,
+    queryParams: Object.keys(queryParams).length > 0 ? queryParams : undefined,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Response rendering (I/O shell)
+// ---------------------------------------------------------------------------
+
+/**
+ * Render an HTTP result to stdout/stderr.
+ * Returns the exit code (0 for success, 1 for error).
+ */
+export function renderResult(
+  route: CliRoute,
+  params: Record<string, string>,
+  result: { status: number; data: any },
+  format: OutputFormat,
+): number {
+  if (result.status >= 400) {
+    const errMsg = result.data?.error ?? `HTTP ${result.status}`;
+    if (format === "json") {
+      console.log(JSON.stringify(result.data));
+    } else {
+      console.error(`Error: ${errMsg}`);
+      if (result.data?.details) {
+        console.error(JSON.stringify(result.data.details, null, 2));
+      }
+    }
+    return 1;
+  }
+
+  if (format === "json") {
+    console.log(JSON.stringify(result.data));
+  } else {
+    if (route.formatHeader) {
+      const header = route.formatHeader(result.data, params);
+      if (header) console.log(header);
+    }
+    const rows = route.extractData(result.data);
+    if (rows.length > 0) {
+      console.log(formatTable(rows));
+    } else {
+      console.log("(empty)");
+    }
+  }
+
+  return 0;
+}

package/src/cli/routes.ts

@@ -0,0 +1,418 @@
+/**
+ * CLI Route Table — maps CLI command patterns to HTTP API endpoints.
+ *
+ * Each route defines:
+ * - The CLI segments users type (verb-first: fixed keywords before positional params)
+ * - The HTTP method + path template
+ * - How to build the request body / query params from CLI flags
+ * - How to extract tabular data from the API response for --output table
+ *
+ * Commander.js registers these routes as a command hierarchy.
+ * The action handler substitutes positional params into the URL and calls httpRequest().
+ */
+import { z } from "zod";
+import { Command } from "commander";
+
+// ── Route Definition ────────────────────────────────────────────────────────
+
+export interface CliRoute {
+  /** CLI segments in verb-first order.
+   *  Fixed keywords come before positional params (tokens starting with ":"). */
+  pattern: string[];
+  description: string;
+  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+  /** URL path template, e.g. "/meta/tables/:name/indexes" */
+  path: string;
+  /** Names of positional params in pattern order */
+  params: string[];
+  /** Zod schema for --json input validation (optional) */
+  inputSchema?: z.ZodType;
+  /** Flag name whose value is parsed as JSON and used as POST body */
+  bodyField?: string;
+  /** Flags that become URL query params (for GET requests) */
+  queryFlags?: string[];
+  /** Map positional args (after the pattern) to body fields. */
+  positionalArgs?: { field: string }[];
+  /** Whether this command mutates data */
+  mutating?: boolean;
+
+  /**
+   * Maps CLI flag names to request body field names.
+   *
+   * CLI users type --db <url>, but the API schema may expect
+   * database_path. The flagMap bridges this: { db: "database_path" } renames
+   * the flag before the body is assembled.
+   */
+  flagMap?: Record<string, string>;
+
+  /** Extract rows from the API response for --output table rendering */
+  extractData: (res: any) => Record<string, unknown>[];
+  /** Optional header text printed before the table in --output table mode */
+  formatHeader?: (res: any, params: Record<string, string>) => string | undefined;
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+/** Flatten a TableSchema into a summary row for the table listing. */
+function tableListRow(t: any) {
+  return {
+    name: t.name,
+    label: t.label,
+    columns: t.columns?.length ?? 0,
+    source: t.source,
+    rowCount: t.rowCount ?? "",
+  };
+}
+
+/** Flatten columns for single-table describe output. */
+function tableDescribeRows(res: any) {
+  if (!res.columns) return [res];
+  return res.columns.map((col: any) => ({
+    column: col.name,
+    type: col.dataType ?? "",
+    notNull: col.notNull ? "YES" : "",
+    pk: col.primary ? "YES" : "",
+    fk: col.foreignKey ? `→ ${col.foreignKey.table}.${col.foreignKey.column}` : "",
+    default: col.hasDefault ? "YES" : "",
+  }));
+}
+
+// ── Route Table ─────────────────────────────────────────────────────────────
+//
+// Patterns are verb-first: all fixed keywords precede positional params.
+// This lets Commander.js build a static command hierarchy for routing,
+// help generation, and missing-argument validation.
+
+export const ROUTES: CliRoute[] = [
+  // ── /meta ──────────────────────────────────────────────────────────────
+  {
+    pattern: ["meta", "tables"],
+    description: "List all tables with schema metadata and row counts",
+    method: "GET",
+    path: "/meta/tables",
+    params: [],
+    extractData: (res) => (res.tables ?? []).map(tableListRow),
+  },
+  {
+    pattern: ["meta", "tables", "show", ":name"],
+    description: "Describe single table schema",
+    method: "GET",
+    path: "/meta/tables/:name",
+    params: ["name"],
+    extractData: tableDescribeRows,
+    formatHeader: (res) => res.name ? `Table: ${res.name} (${res.label})` : undefined,
+  },
+  {
+    pattern: ["meta", "tables", "indexes", ":name"],
+    description: "Show indexes on a table",
+    method: "GET",
+    path: "/meta/tables/:name/indexes",
+    params: ["name"],
+    extractData: (res) => res.data ?? res ?? [],
+  },
+  {
+    pattern: ["meta", "tables", "sample", ":name"],
+    description: "Show sample rows from a table",
+    method: "GET",
+    path: "/meta/tables/:name/sample",
+    params: ["name"],
+    queryFlags: ["limit", "fields"],
+    extractData: (res) => res.data ?? res ?? [],
+  },
+  {
+    pattern: ["meta", "tables", "update", ":name"],
+    description: "Update table properties (label, display_column, immutable, name)",
+    method: "PATCH",
+    path: "/meta/tables/:name",
+    params: ["name"],
+    bodyField: "data",
+    mutating: true,
+    inputSchema: z.object({
+      name: z.string().optional().describe("New table name (rename)"),
+      label: z.string().optional().describe("Display label"),
+      display_column: z.string().optional().describe("Column used for FK display values"),
+      immutable: z.boolean().optional().describe("Prevent updates and deletes"),
+      position: z.number().optional().describe("Sort position in sidebar"),
+    }),
+    extractData: (res) => [res],
+  },
+  {
+    pattern: ["meta", "tables", "drop", ":name"],
+    description: "Drop a UI-managed table",
+    method: "DELETE",
+    path: "/meta/tables/:name",
+    params: ["name"],
+    queryFlags: ["confirm"],
+    mutating: true,
+    extractData: (res) => [res],
+  },
+  {
+    pattern: ["meta", "enums"],
+    description: "List all Postgres enums and their allowed values",
+    method: "GET",
+    path: "/meta/enums",
+    params: [],
+    extractData: (res) => res.data ?? res ?? [],
+  },
+  {
+    pattern: ["meta", "sql", "query"],
+    description: "Run a read-only SQL query (SELECT/WITH only)",
+    method: "POST",
+    path: "/meta/sql/query",
+    params: [],
+    positionalArgs: [{ field: "sql" }],
+    inputSchema: z.object({
+      sql: z.string().describe("SQL query to run"),
+      limit: z.number().optional().describe("Max rows to return"),
+    }),
+    extractData: (res) => Array.isArray(res) ? res : (res.data ?? []),
+  },
+  {
+    pattern: ["meta", "sql", "exec"],
+    description: "Run any SQL statement (INSERT, UPDATE, DELETE, etc.)",
+    method: "POST",
+    path: "/meta/sql/exec",
+    params: [],
+    positionalArgs: [{ field: "sql" }],
+    mutating: true,
+    inputSchema: z.object({
+      sql: z.string().describe("SQL statement to execute"),
+      dryRun: z.boolean().optional().describe("Validate without executing"),
+    }),
+    extractData: (res) => Array.isArray(res) ? res : (res.data ?? [res]),
+  },
+  {
+    pattern: ["meta", "schema", "sync"],
+    description: "Sync schema files to database (apply migrations)",
+    method: "POST",
+    path: "/meta/schema/sync",
+    params: [],
+    mutating: true,
+    extractData: (res) => [res],
+  },
+  // ── /tables ────────────────────────────────────────────────────────────
+  {
+    pattern: ["tables", "list", ":table"],
+    description: "List rows from a table (with filters, sort, pagination)",
+    method: "GET",
+    path: "/tables/:table",
+    params: ["table"],
+    queryFlags: ["limit", "page", "sort", "order"],
+    extractData: (res) => res.data ?? [],
+    formatHeader: (res) => {
+      const m = res.meta;
+      return m ? `Page ${m.page}/${m.pages} (${m.total} total rows)` : undefined;
+    },
+  },
+  {
+    pattern: ["tables", "get", ":table", ":id"],
+    description: "Get a single row by ID",
+    method: "GET",
+    path: "/tables/:table/:id",
+    params: ["table", "id"],
+    extractData: (res) => res.data ? [res.data] : [],
+  },
+  {
+    pattern: ["tables", "create", ":table"],
+    description: "Insert one or more rows into a table",
+    method: "POST",
+    path: "/tables/:table",
+    params: ["table"],
+    bodyField: "data",
+    mutating: true,
+    extractData: (res) => {
+      const d = res.data;
+      return Array.isArray(d) ? d : d ? [d] : [];
+    },
+  },
+  {
+    pattern: ["tables", "update", ":table", ":id"],
+    description: "Update a row by ID",
+    method: "PUT",
+    path: "/tables/:table/:id",
+    params: ["table", "id"],
+    bodyField: "data",
+    mutating: true,
+    extractData: (res) => res.data ? [res.data] : [],
+  },
+  {
+    pattern: ["tables", "delete", ":table", ":id"],
+    description: "Delete a row by ID",
+    method: "DELETE",
+    path: "/tables/:table/:id",
+    params: ["table", "id"],
+    mutating: true,
+    extractData: (res) => res.data ? [res.data] : [],
+  },
+
+  // ── /reports ───────────────────────────────────────────────────────────
+  {
+    pattern: ["reports"],
+    description: "List all report definitions",
+    method: "GET",
+    path: "/reports",
+    params: [],
+    extractData: (res) =>
+      (res.reports ?? []).map((r: any) => ({
+        name: r.name,
+        label: r.label ?? r.name,
+        params: (r.params ?? []).map((p: any) => p.name).join(", "),
+      })),
+  },
+  {
+    pattern: ["reports", "show", ":name"],
+    description: "Get report metadata and parameters",
+    method: "GET",
+    path: "/reports/:name",
+    params: ["name"],
+    extractData: (res) => [res],
+  },
+  {
+    pattern: ["reports", "run", ":name"],
+    description: "Execute a report with parameters",
+    method: "GET",
+    path: "/reports/:name/results",
+    params: ["name"],
+    queryFlags: ["*"],
+    extractData: (res) => {
+      if (res.nodes) return res.nodes;
+      if (Array.isArray(res)) return res;
+      return [res];
+    },
+  },
+
+  // ── /actions ───────────────────────────────────────────────────────────
+  {
+    pattern: ["actions"],
+    description: "List all available actions with input schemas",
+    method: "GET",
+    path: "/actions",
+    params: [],
+    extractData: (res) =>
+      (res.actions ?? res ?? []).map((a: any) => ({
+        name: a.name,
+        label: a.label ?? a.name,
+      })),
+  },
+  {
+    pattern: ["actions", "run", ":name"],
+    description: "Execute an action",
+    method: "POST",
+    path: "/actions/:name",
+    params: ["name"],
+    bodyField: "data",
+    mutating: true,
+    extractData: (res) => {
+      const d = res.data;
+      return Array.isArray(d) ? d : d ? [d] : [res];
+    },
+  },
+
+  // ── /views ─────────────────────────────────────────────────────────────
+  {
+    pattern: ["views"],
+    description: "List all custom views with metadata",
+    method: "GET",
+    path: "/views",
+    params: [],
+    extractData: (res) =>
+      (res.views ?? res ?? []).map((v: any) => ({
+        name: v.name,
+        label: v.label ?? v.name,
+        icon: v.icon ?? "",
+      })),
+  },
+];
+
+// ── Commander registration ──────────────────────────────────────────────────
+
+export type RouteActionHandler = (
+  route: CliRoute,
+  params: Record<string, string>,
+  extraPositionals: string[],
+) => Promise<void>;
+
+/**
+ * Register all CLI routes as Commander subcommands.
+ *
+ * Builds a command hierarchy from each route's fixed segments, adds
+ * positional arguments for URL params and positionalArgs, then wires
+ * the action callback through the provided handler.
+ *
+ * Commander handles routing, required-argument validation, and help
+ * generation. The handler receives the matched route, extracted URL
+ * params, and any extra positional values (for positionalArgs fields).
+ */
+export function registerRoutes(
+  program: Command,
+  routes: CliRoute[],
+  handler: RouteActionHandler,
+): void {
+  for (const route of routes) {
+    const fixed: string[] = [];
+    const params: string[] = [];
+    for (const token of route.pattern) {
+      if (token.startsWith(":")) params.push(token.slice(1));
+      else fixed.push(token);
+    }
+
+    if (fixed.length === 0) continue;
+
+    // Navigate/create command hierarchy for fixed[0..len-2]
+    let parent: Command = program;
+    for (let i = 0; i < fixed.length - 1; i++) {
+      let existing = parent.commands.find((c) => c.name() === fixed[i]);
+      if (!existing) {
+        existing = parent.command(fixed[i]);
+        existing.allowUnknownOption();
+        existing.allowExcessArguments(true);
+      }
+      parent = existing;
+    }
+
+    // Create or reuse the leaf command
+    const leafName = fixed[fixed.length - 1];
+    let cmd = parent.commands.find((c) => c.name() === leafName);
+    if (!cmd) {
+      cmd = parent.command(leafName);
+    }
+
+    cmd.description(route.description);
+
+    // URL params become required arguments
+    for (const p of params) {
+      cmd.argument(`<${p}>`);
+    }
+
+    // positionalArgs become optional arguments (e.g. [sql] for "meta sql query")
+    if (route.positionalArgs) {
+      for (const pa of route.positionalArgs) {
+        cmd.argument(`[${pa.field}]`);
+      }
+    }
+
+    cmd.allowUnknownOption();
+    cmd.allowExcessArguments(true);
+
+    // Capture route and params list in closure
+    const routeRef = route;
+    const paramNames = params;
+
+    cmd.action(async (...actionArgs: any[]) => {
+      actionArgs.pop(); // Command instance
+      actionArgs.pop(); // Commander-parsed options (unused — we parse flags ourselves)
+      const positionalValues = actionArgs as string[];
+
+      // Map declared positional values to route URL params
+      const routeParams: Record<string, string> = {};
+      for (let i = 0; i < paramNames.length; i++) {
+        routeParams[paramNames[i]] = positionalValues[i];
+      }
+
+      // Remaining positionals go to positionalArgs mapping in buildRequest
+      const extraPositionals = positionalValues.slice(paramNames.length);
+
+      await handler(routeRef, routeParams, extraPositionals);
+    });
+  }
+}

package/src/cli/rows-insert-master-detail.test.ts

@@ -0,0 +1,124 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import Database from "better-sqlite3";
+import { rowsInsertMasterDetail } from "./rows-insert-master-detail.js";
+import type { SqlClient } from "../introspect/types.js";
+
+/**
+ * Create a SqlClient adapter from a better-sqlite3 Database.
+ *
+ * The returned object is both a SqlClient (for rowsInsertMasterDetail's type
+ * signature) and a Database.Database proxy (for the `sql as any` casts inside
+ * rowsInsertMasterDetail that pass it to synchronous db-helpers functions).
+ *
+ * begin() wraps the callback in a SQLite transaction using SAVEPOINT for
+ * nested transaction semantics. The transaction SqlClient passed to the
+ * callback also carries the sqlite handle's native methods.
+ */
+function createTestSql(sqlite: Database.Database): SqlClient & Database.Database {
+  const extended = sqlite as any;
+  extended.unsafe = (query: string, params?: any[]) => {
+    return Promise.resolve(sqlite.prepare(query).all(...(params ?? [])));
+  };
+  extended.begin = async (fn: (tx: SqlClient) => Promise<any>) => {
+    sqlite.exec("BEGIN");
+    try {
+      const txExtended = sqlite as any;
+      // tx.unsafe is already on the sqlite handle from the outer assignment
+      const result = await fn(txExtended);
+      sqlite.exec("COMMIT");
+      return result;
+    } catch (err) {
+      sqlite.exec("ROLLBACK");
+      throw err;
+    }
+  };
+  extended.end = async () => {};
+  return extended;
+}
+
+describe("rows insert-master-detail", () => {
+  let sqlite: Database.Database;
+  let sql: SqlClient;
+
+  beforeEach(() => {
+    sqlite = new Database(":memory:");
+    sqlite.pragma("foreign_keys = ON");
+    sql = createTestSql(sqlite);
+    sqlite.exec(`
+      CREATE TABLE orders (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        customer TEXT NOT NULL
+      );
+      CREATE TABLE order_items (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        order_id INTEGER NOT NULL REFERENCES orders(id),
+        product TEXT NOT NULL,
+        quantity INTEGER NOT NULL
+      );
+    `);
+  });
+
+  afterEach(() => {
+    sqlite.close();
+  });
+
+  it("inserts master and detail rows atomically", async () => {
+    const log = vi.spyOn(console, "log").mockImplementation(() => {});
+
+    await rowsInsertMasterDetail(sql, {
+      "master-table": "orders",
+      "master-data": '{"customer":"Alice"}',
+      "detail-table": "order_items",
+      "detail-data": '[{"product":"Widget","quantity":3},{"product":"Gadget","quantity":1}]',
+      "detail-fk": "order_id",
+    });
+
+    const orders = sqlite.prepare("SELECT * FROM orders").all() as any[];
+    expect(orders).toHaveLength(1);
+    expect(orders[0].customer).toBe("Alice");
+
+    const items = sqlite.prepare("SELECT * FROM order_items ORDER BY id").all() as any[];
+    expect(items).toHaveLength(2);
+    expect(items[0].order_id).toBe(1);
+    expect(items[0].product).toBe("Widget");
+    expect(items[1].order_id).toBe(1);
+    expect(items[1].product).toBe("Gadget");
+
+    log.mockRestore();
+  });
+
+  it("backfills FK column from master ID", async () => {
+    const log = vi.spyOn(console, "log").mockImplementation(() => {});
+
+    await rowsInsertMasterDetail(sql, {
+      "master-table": "orders",
+      "master-data": '{"customer":"Bob"}',
+      "detail-table": "order_items",
+      "detail-data": '[{"product":"Thing","quantity":5}]',
+      "detail-fk": "order_id",
+    });
+
+    const items = sqlite.prepare("SELECT * FROM order_items").all() as any[];
+    expect(items[0].order_id).toBe(1);
+
+    log.mockRestore();
+  });
+
+  it("throws when required flags are missing", async () => {
+    await expect(
+      rowsInsertMasterDetail(sql, { "master-table": "orders" }),
+    ).rejects.toThrow("Usage:");
+  });
+
+  it("rejects invalid table names", async () => {
+    await expect(
+      rowsInsertMasterDetail(sql, {
+        "master-table": "orders; DROP TABLE orders;--",
+        "master-data": '{"customer":"x"}',
+        "detail-table": "order_items",
+        "detail-data": "[{}]",
+        "detail-fk": "order_id",
+      }),
+    ).rejects.toThrow("Invalid table name");
+  });
+});