@sapporta/server 0.0.1

package/src/introspect/table-rename.ts

@@ -0,0 +1,115 @@
+import { z } from "zod";
+import type { SqlClient, OperationResult } from "./types.js";
+import { OperationError, ErrorCode } from "./types.js";
+import { validateTableName } from "./sql-safety.js";
+
+export const tableRenameInput = z.object({
+  oldName: z.string().describe("Current SQL table name"),
+  newName: z.string().describe("New SQL table name (snake_case)"),
+  newLabel: z.string().optional().describe("New display label (defaults to title-cased newName)"),
+});
+
+/**
+ * Title-case a snake_case name: "sales_targets" → "Sales Targets"
+ */
+function titleCase(name: string): string {
+  return name
+    .split("_")
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(" ");
+}
+
+/**
+ * Rename a UI-managed table atomically.
+ *
+ * Steps inside sql.begin():
+ *   1. Verify oldName exists in _sapporta_tables (reject file-managed tables)
+ *   2. ALTER TABLE "oldName" RENAME TO "newName"
+ *   3. INSERT new row into _sapporta_tables (copy metadata with new name/label)
+ *   4. UPDATE _sapporta_columns SET table_name = newName WHERE table_name = oldName
+ *   5. UPDATE _sapporta_columns SET references_table = newName WHERE references_table = oldName
+ *   6. DELETE old row from _sapporta_tables
+ *
+ * Why insert-then-delete: _sapporta_columns.table_name FK references
+ * _sapporta_tables.name with NO ON UPDATE CASCADE. Can't update PK in place.
+ * Instead: insert new row so FK target exists, move column references, then
+ * delete old row.
+ */
+export async function tableRename(
+  sql: SqlClient,
+  oldName: string,
+  newName: string,
+  newLabel?: string,
+): Promise<OperationResult> {
+  validateTableName(oldName);
+  validateTableName(newName);
+
+  if (oldName === newName) {
+    throw new OperationError("Old and new names are the same", ErrorCode.VALIDATION_FAILED);
+  }
+
+  const label = newLabel ?? titleCase(newName);
+
+  await sql.begin(async (tx) => {
+    // 1. Verify oldName exists in _sapporta_tables
+    const existing = await tx.unsafe(
+      `SELECT name FROM _sapporta_tables WHERE name = $1`,
+      [oldName],
+    );
+    if (existing.length === 0) {
+      throw new OperationError(
+        `Table "${oldName}" not found in _sapporta_tables (only UI-managed tables can be renamed)`,
+        ErrorCode.TABLE_NOT_FOUND,
+      );
+    }
+
+    // Check newName doesn't already exist
+    const conflict = await tx.unsafe(
+      `SELECT name FROM _sapporta_tables WHERE name = $1`,
+      [newName],
+    );
+    if (conflict.length > 0) {
+      throw new OperationError(
+        `Table "${newName}" already exists in _sapporta_tables`,
+        ErrorCode.VALIDATION_FAILED,
+      );
+    }
+
+    // 2. Rename the actual PG table
+    await tx.unsafe(`ALTER TABLE "${oldName}" RENAME TO "${newName}"`);
+
+    // 3. Insert new metadata row (copy from old with new name/label)
+    await tx.unsafe(
+      `INSERT INTO _sapporta_tables (name, label, display_column, immutable, inferred, position)
+       SELECT $1, $2, display_column, immutable, inferred, position
+       FROM _sapporta_tables WHERE name = $3`,
+      [newName, label, oldName],
+    );
+
+    // 4. Move columns to new table name
+    await tx.unsafe(
+      `UPDATE _sapporta_columns SET table_name = $1 WHERE table_name = $2`,
+      [newName, oldName],
+    );
+
+    // 5. Update FK references pointing to the old table
+    await tx.unsafe(
+      `UPDATE _sapporta_columns SET references_table = $1 WHERE references_table = $2`,
+      [newName, oldName],
+    );
+
+    // 6. Delete old metadata row (columns already moved, so no FK violation)
+    await tx.unsafe(
+      `DELETE FROM _sapporta_tables WHERE name = $1`,
+      [oldName],
+    );
+  });
+
+  return {
+    ok: true,
+    data: [{ old_name: oldName, new_name: newName, label }],
+    meta: {
+      message: `Renamed table "${oldName}" → "${newName}" (label: "${label}")`,
+    },
+  };
+}

package/src/introspect/types.ts

@@ -0,0 +1,95 @@
+// ---------------------------------------------------------------------------
+// Operation result envelope — the contract between domain operations and
+// the layers that consume them (API routes, CLI output).
+//
+// These types were originally in cli-utils.ts as CliResult/CliError but have
+// nothing to do with the CLI — they're a structured result pattern used by
+// database introspection functions, SQL proxy, and other operations.
+// ---------------------------------------------------------------------------
+
+/**
+ * Every operation returns an OperationResult instead of printing directly.
+ * This separates data production from presentation, enabling:
+ *   - HTTP API responses (meta-api.ts converts to JSON + status codes)
+ *   - CLI output formatting (emitResult converts to table or JSON)
+ *   - Tests that assert on data, not console output
+ */
+export type OperationResult = OperationSuccess | OperationFailure;
+
+/**
+ * Well-known metadata fields used by the output layer for rendering.
+ * These fields are the contract between operation functions and consumers:
+ *   - message: displayed before the data table (or as the sole output if tableOutputHandled)
+ *   - tableOutputHandled: signals that message/additionalOutput contain the full rendering,
+ *     so the output layer should NOT format data[] as a table
+ *   - additionalOutput: extra text sections printed after the main table
+ *   - errorText: printed to stderr (e.g. warnings from report execution)
+ *   - rowCount, dryRun: informational fields for agents consuming JSON output
+ *
+ * The index signature allows operation-specific extras (e.g. foreignKeys, reportData).
+ */
+export type OperationMeta = {
+  message?: string;
+  tableOutputHandled?: boolean;
+  additionalOutput?: string;
+  errorText?: string;
+  rowCount?: number;
+  dryRun?: boolean;
+  [key: string]: unknown;
+};
+
+export type OperationSuccess = {
+  ok: true;
+  /** Primary result rows. Most operations return a single table of rows. */
+  data: Record<string, unknown>[];
+  /** Optional metadata (row counts, messages, secondary data like foreign keys). */
+  meta?: OperationMeta;
+};
+
+export type OperationFailure = {
+  ok: false;
+  error: string;
+  code: string;
+};
+
+/**
+ * Well-known error codes for structured error output.
+ * Agents can match on these programmatically instead of parsing error messages.
+ */
+export const ErrorCode = {
+  TABLE_NOT_FOUND: "TABLE_NOT_FOUND",
+  INVALID_TABLE_NAME: "INVALID_TABLE_NAME",
+  INVALID_COLUMN_NAME: "INVALID_COLUMN_NAME",
+  INVALID_JSON: "INVALID_JSON",
+  DANGEROUS_SQL: "DANGEROUS_SQL",
+  SELECT_ONLY: "SELECT_ONLY",
+  PROJECT_NOT_FOUND: "PROJECT_NOT_FOUND",
+  REPORT_NOT_FOUND: "REPORT_NOT_FOUND",
+  VALIDATION_FAILED: "VALIDATION_FAILED",
+  MISSING_ARGUMENT: "MISSING_ARGUMENT",
+  INTERNAL: "INTERNAL",
+} as const;
+
+/**
+ * Typed error that carries a machine-readable error code.
+ * Operations throw these; consumers catch and convert to appropriate output.
+ */
+export class OperationError extends Error {
+  constructor(
+    message: string,
+    public code: string,
+  ) {
+    super(message);
+  }
+}
+
+/**
+ * SQL client interface matching the subset of postgres.js used by operations.
+ * In production, a real postgres.js client is passed.
+ * In tests, a PGlite adapter is injected.
+ */
+export interface SqlClient {
+  unsafe: (query: string, params?: any[]) => Promise<any[]>;
+  begin: (fn: (sql: SqlClient) => Promise<any>) => Promise<any>;
+  end: () => Promise<void>;
+}

package/src/reports/check.test.ts

@@ -0,0 +1,499 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import Database from "better-sqlite3";
+import { checkReportDefinition, checkReportSqlColumns } from "./check.js";
+import type { CheckSql } from "./check.js";
+import type { ReportDefinition } from "./report.js";
+
+describe("checkReportDefinition", () => {
+  it("returns no issues for a valid report", () => {
+    const def: ReportDefinition = {
+      name: "valid",
+      label: "Valid Report",
+      params: [],
+      sources: {
+        items: { query: "SELECT name, amount FROM items" },
+      },
+      tree: {
+        source: "items",
+        levelName: "item",
+        columns: [
+          { name: "name", header: "Name" },
+          { name: "amount", header: "Amount" },
+        ],
+      },
+    };
+
+    expect(checkReportDefinition(def)).toEqual([]);
+  });
+
+  it("detects missing source reference", () => {
+    const def: ReportDefinition = {
+      name: "bad-source",
+      label: "Bad Source",
+      params: [],
+      sources: {
+        items: { query: "SELECT 1" },
+      },
+      tree: {
+        source: "nonexistent",
+        levelName: "item",
+        columns: [{ name: "name" }],
+      },
+    };
+
+    const issues = checkReportDefinition(def);
+    expect(issues).toHaveLength(1);
+    expect(issues[0].path).toBe("item");
+    expect(issues[0].message).toContain("nonexistent");
+    expect(issues[0].message).toContain("not found in sources");
+  });
+
+  it("detects missing source in child node", () => {
+    const def: ReportDefinition = {
+      name: "bad-child-source",
+      label: "Bad Child Source",
+      params: [],
+      sources: {
+        parents: { query: "SELECT name FROM groups" },
+      },
+      tree: {
+        source: "parents",
+        levelName: "group",
+        columns: [{ name: "name" }],
+        children: [
+          {
+            source: "missing_source",
+            levelName: "detail",
+            columns: [{ name: "info" }],
+          },
+        ],
+      },
+    };
+
+    const issues = checkReportDefinition(def);
+    expect(issues).toHaveLength(1);
+    expect(issues[0].path).toBe("group.detail");
+    expect(issues[0].message).toContain("missing_source");
+  });
+
+  it("detects rollup keys not declared in columns[]", () => {
+    const def: ReportDefinition = {
+      name: "rollup-warn",
+      label: "Rollup Warn",
+      params: [],
+      sources: {
+        parents: { query: "SELECT name FROM groups" },
+        kids: { query: "SELECT name FROM items" },
+      },
+      tree: {
+        source: "parents",
+        levelName: "group",
+        columns: [{ name: "name" }],
+        rollup: (children) => ({
+          total: children.item.reduce((s) => s + 1, 0),
+          count: children.item.length,
+        }),
+        children: [
+          {
+            source: "kids",
+            levelName: "item",
+            columns: [{ name: "name" }],
+          },
+        ],
+      },
+    };
+
+    const issues = checkReportDefinition(def);
+    expect(issues).toHaveLength(2);
+    expect(issues[0].path).toBe("group.rollup");
+    expect(issues[0].message).toContain('"total"');
+    expect(issues[0].message).toContain('level "group"');
+    expect(issues[1].path).toBe("group.rollup");
+    expect(issues[1].message).toContain('"count"');
+  });
+
+  it("does not warn for rollup keys that are declared", () => {
+    const def: ReportDefinition = {
+      name: "rollup-ok",
+      label: "Rollup OK",
+      params: [],
+      sources: {
+        parents: { query: "SELECT name FROM groups" },
+        kids: { query: "SELECT name FROM items" },
+      },
+      tree: {
+        source: "parents",
+        levelName: "group",
+        columns: [
+          { name: "name" },
+          { name: "total", header: "Total", format: "currency" },
+        ],
+        rollup: (children) => ({
+          total: children.item.reduce((s) => s + 1, 0),
+        }),
+        children: [
+          {
+            source: "kids",
+            levelName: "item",
+            columns: [{ name: "name" }],
+          },
+        ],
+      },
+    };
+
+    expect(checkReportDefinition(def)).toEqual([]);
+  });
+
+  it("detects footer keys not declared in columns[]", () => {
+    const def: ReportDefinition = {
+      name: "footer-warn",
+      label: "Footer Warn",
+      params: [],
+      sources: {
+        items: { query: "SELECT name FROM items" },
+      },
+      tree: {
+        source: "items",
+        levelName: "item",
+        columns: [{ name: "name" }],
+        footer: [
+          {
+            label: "Grand Total",
+            compute: () => ({
+              grand_total: 0,
+              extra: 0,
+            }),
+          },
+        ],
+      },
+    };
+
+    const issues = checkReportDefinition(def);
+    expect(issues).toHaveLength(2);
+    expect(issues[0].path).toBe('item.footer["Grand Total"]');
+    expect(issues[0].message).toContain('"grand_total"');
+    expect(issues[1].message).toContain('"extra"');
+  });
+
+  it("does not warn for footer keys that are declared", () => {
+    const def: ReportDefinition = {
+      name: "footer-ok",
+      label: "Footer OK",
+      params: [],
+      sources: {
+        items: { query: "SELECT name, amount FROM items" },
+      },
+      tree: {
+        source: "items",
+        levelName: "item",
+        columns: [
+          { name: "name" },
+          { name: "amount", header: "Amount" },
+        ],
+        footer: [
+          {
+            label: "Total",
+            compute: () => ({ amount: 0 }),
+          },
+        ],
+      },
+    };
+
+    expect(checkReportDefinition(def)).toEqual([]);
+  });
+
+  it("detects multiple issues across the tree", () => {
+    const def: ReportDefinition = {
+      name: "multi-issue",
+      label: "Multi Issue",
+      params: [],
+      sources: {
+        sections: { query: "SELECT section FROM sections" },
+        // "accounts" source is missing
+      },
+      tree: {
+        source: "sections",
+        levelName: "section",
+        columns: [{ name: "section" }],
+        rollup: (children) => ({
+          section_total: children.accounts?.reduce((s) => s, 0) ?? 0,
+        }),
+        footer: [
+          {
+            label: "Net",
+            compute: () => ({ section_total: 0 }),
+          },
+        ],
+        children: [
+          {
+            source: "accounts",
+            levelName: "accounts",
+            columns: [{ name: "name" }],
+          },
+        ],
+      },
+    };
+
+    const issues = checkReportDefinition(def);
+    // Should have: rollup undeclared key, footer undeclared key, child missing source
+    expect(issues.length).toBe(3);
+
+    const rollupIssue = issues.find((i) => i.path.includes("rollup"));
+    expect(rollupIssue).toBeDefined();
+    expect(rollupIssue!.message).toContain('"section_total"');
+
+    const footerIssue = issues.find((i) => i.path.includes("footer"));
+    expect(footerIssue).toBeDefined();
+    expect(footerIssue!.message).toContain('"section_total"');
+
+    const sourceIssue = issues.find((i) => i.path === "section.accounts");
+    expect(sourceIssue).toBeDefined();
+    expect(sourceIssue!.message).toContain("accounts");
+  });
+
+  it("validates the balance-sheet pattern (valid)", () => {
+    const def: ReportDefinition = {
+      name: "balance-sheet",
+      label: "Balance Sheet",
+      params: [
+        { name: "as_of_date", type: "date", required: true, label: "As of Date" },
+      ],
+      sources: {
+        sections: { query: "SELECT section FROM sections" },
+        section_accounts: { query: "SELECT name, balance FROM accounts WHERE section = $section" },
+      },
+      tree: {
+        source: "sections",
+        levelName: "section",
+        columns: [
+          { name: "section", header: "Section" },
+          { name: "section_total", header: "Total", format: "currency" },
+        ],
+        rollup: (children) => ({
+          section_total: children.accounts.reduce(
+            (s, n) => s + Number(n.columns.balance ?? 0),
+            0,
+          ),
+        }),
+        footer: [
+          {
+            label: "Total",
+            compute: (nodes) => ({
+              section_total: nodes.reduce(
+                (s, n) => s + Number(n.rollup?.section_total ?? 0),
+                0,
+              ),
+            }),
+          },
+        ],
+        children: [
+          {
+            source: "section_accounts",
+            levelName: "accounts",
+            columns: [
+              { name: "name", header: "Account" },
+              { name: "balance", header: "Balance", format: "currency" },
+            ],
+          },
+        ],
+      },
+    };
+
+    expect(checkReportDefinition(def)).toEqual([]);
+  });
+
+  it("handles rollup that throws with empty children gracefully", () => {
+    const def: ReportDefinition = {
+      name: "rollup-throws",
+      label: "Rollup Throws",
+      params: [],
+      sources: {
+        parents: { query: "SELECT name FROM groups" },
+        kids: { query: "SELECT name FROM items" },
+      },
+      tree: {
+        source: "parents",
+        levelName: "group",
+        columns: [{ name: "name" }],
+        rollup: (children) => {
+          // This will throw because children.item[0] is undefined
+          return { total: children.item[0].columns.amount as number };
+        },
+        children: [
+          {
+            source: "kids",
+            levelName: "item",
+            columns: [{ name: "name" }],
+          },
+        ],
+      },
+    };
+
+    // Should not throw — just silently skip the rollup check
+    const issues = checkReportDefinition(def);
+    // Only the items that could be checked are reported; no crash
+    expect(issues).toEqual([]);
+  });
+
+  it("handles footer compute that throws with empty input gracefully", () => {
+    const def: ReportDefinition = {
+      name: "footer-throws",
+      label: "Footer Throws",
+      params: [],
+      sources: {
+        items: { query: "SELECT name FROM items" },
+      },
+      tree: {
+        source: "items",
+        levelName: "item",
+        columns: [{ name: "name" }],
+        footer: [
+          {
+            label: "Problematic",
+            compute: (nodes) => {
+              // This will throw when nodes is empty
+              return { total: nodes[0].columns.amount as number };
+            },
+          },
+        ],
+      },
+    };
+
+    // Should not throw — gracefully skip
+    const issues = checkReportDefinition(def);
+    expect(issues).toEqual([]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// DB-aware column checks (checkReportSqlColumns)
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a CheckSql adapter from better-sqlite3. The CheckSql interface
+ * requires result arrays with a `.columns` property containing column
+ * metadata. We use .prepare().columns() to discover column names, then
+ * attach them to the result array.
+ */
+function createCheckSql(sqlite: Database.Database): CheckSql {
+  return {
+    unsafe: (query: string, params?: unknown[]) => {
+      const stmt = sqlite.prepare(query);
+      const rows = stmt.all(...(params ?? [])) as any;
+      // Attach column metadata matching the CheckSql contract
+      rows.columns = stmt.columns().map((c: any) => ({ name: c.name }));
+      return Promise.resolve(rows);
+    },
+  };
+}
+
+describe("checkReportSqlColumns", () => {
+  let sqlite: Database.Database;
+  let sql: CheckSql;
+
+  beforeEach(() => {
+    sqlite = new Database(":memory:");
+    sqlite.pragma("foreign_keys = ON");
+    sql = createCheckSql(sqlite);
+    sqlite.exec(`
+      CREATE TABLE items (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        name TEXT NOT NULL,
+        amount REAL NOT NULL,
+        category TEXT
+      )
+    `);
+    sqlite.exec(`
+      CREATE TABLE sections (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        section TEXT NOT NULL
+      )
+    `);
+  });
+
+  afterEach(() => {
+    sqlite.close();
+  });
+
+  it("no issues for valid SQL with undeclared columns (no longer flagged)", async () => {
+    const def: ReportDefinition = {
+      name: "undeclared-ok",
+      label: "Undeclared OK",
+      params: [],
+      sources: {
+        items: { query: "SELECT id, name, amount, category FROM items" },
+      },
+      tree: {
+        source: "items",
+        levelName: "item",
+        columns: [{ name: "name" }],
+        transform: (nodes) => nodes,
+      },
+    };
+
+    const issues = await checkReportSqlColumns(sql, def);
+    expect(issues).toEqual([]);
+  });
+
+  it("validates valid SQL passes planning", async () => {
+    const def: ReportDefinition = {
+      name: "valid-sql",
+      label: "Valid SQL",
+      params: [],
+      sources: {
+        items: { query: "SELECT name, amount FROM items" },
+      },
+      tree: {
+        source: "items",
+        levelName: "item",
+        columns: [{ name: "name" }, { name: "amount" }],
+      },
+    };
+
+    const issues = await checkReportSqlColumns(sql, def);
+    expect(issues).toEqual([]);
+  });
+
+  it("catches SQL planning errors", async () => {
+    const def: ReportDefinition = {
+      name: "bad-planning",
+      label: "Bad Planning",
+      params: [],
+      sources: {
+        missing: { query: "SELECT * FROM nonexistent_table" },
+      },
+      tree: {
+        source: "missing",
+        levelName: "item",
+        columns: [{ name: "name" }],
+      },
+    };
+
+    const issues = await checkReportSqlColumns(sql, def);
+    expect(issues).toHaveLength(1);
+    expect(issues[0].message).toContain("SQL planning failed");
+    expect(issues[0].message).toContain("nonexistent_table");
+  });
+
+  it("handles bind variables (replaced with NULLs for planning)", async () => {
+    const def: ReportDefinition = {
+      name: "bind-vars",
+      label: "Bind Vars",
+      params: [],
+      sources: {
+        items: {
+          query: "SELECT name, amount FROM items WHERE category = $cat AND amount > $min",
+        },
+      },
+      tree: {
+        source: "items",
+        levelName: "item",
+        columns: [{ name: "name" }],
+      },
+    };
+
+    // Valid SQL with bind variables should pass planning
+    const issues = await checkReportSqlColumns(sql, def);
+    expect(issues).toEqual([]);
+  });
+});