@sapporta/server 0.0.1

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

@@ -0,0 +1,186 @@
+import { z } from "zod";
+import type { SqlClient, OperationResult } from "../introspect/types.js";
+import { OperationError, ErrorCode } from "../introspect/types.js";
+import { rejectDangerousSQL } from "../introspect/sql-safety.js";
+import { buildInsertQuery, assertTableExists, getTableColumns } from "../introspect/db-helpers.js";
+import { formatTable } from "./format.js";
+import { validateTableName, validateColumnNames, rejectControlChars } from "../introspect/sql-safety.js";
+
+export const rowsInsertMasterDetailInput = z.object({
+  masterTable: z.string().describe("Master table name"),
+  masterData: z.string().describe("JSON object for master record"),
+  detailTable: z.string().describe("Detail table name"),
+  detailData: z.string().describe("JSON array of detail records"),
+  detailFk: z.string().describe("FK column name on detail table (e.g. 'order_id')"),
+  dryRun: z.boolean().optional().describe("Validate without executing"),
+});
+
+/**
+ * Insert a master record and its detail records atomically.
+ * The master record's ID is backfilled into each detail record's FK column.
+ *
+ * Flags:
+ *   --master-table    Master table name
+ *   --master-data     JSON object for master record
+ *   --detail-table    Detail table name
+ *   --detail-data     JSON array of detail records (without FK column)
+ *   --detail-fk       FK column name on detail table (e.g. "order_id")
+ *   --dry-run         Validate without executing
+ *
+ * Returns detail rows as primary data, with the master row in meta.
+ * Both master and detail inserts happen inside a single transaction.
+ */
+export async function rowsInsertMasterDetail(
+  sql: SqlClient,
+  flags: Record<string, string>,
+): Promise<OperationResult> {
+  const masterTable = flags["master-table"];
+  const masterDataJson = flags["master-data"];
+  const detailTable = flags["detail-table"];
+  const detailDataJson = flags["detail-data"];
+  const detailFk = flags["detail-fk"];
+  const dryRun = flags["dry-run"] === "true";
+
+  if (!masterTable || !masterDataJson || !detailTable || !detailDataJson || !detailFk) {
+    throw new OperationError(
+      "Usage: sapporta rows insert-master-detail " +
+      "--master-table T --master-data '{}' " +
+      "--detail-table T --detail-data '[{}]' " +
+      "--detail-fk column_name",
+      ErrorCode.MISSING_ARGUMENT,
+    );
+  }
+
+  // Validate table names and FK column using shared identifier checks.
+  // validateTableName/validateColumnNames throw OperationError on invalid input.
+  validateTableName(masterTable);
+  validateTableName(detailTable);
+  validateColumnNames([detailFk]);
+
+  // Reject control characters before parsing -- agents sometimes produce
+  // invisible chars that would silently corrupt data in the database.
+  rejectControlChars(masterDataJson);
+  rejectControlChars(detailDataJson);
+
+  const masterData = JSON.parse(masterDataJson);
+  const detailRows = JSON.parse(detailDataJson);
+
+  if (!Array.isArray(detailRows)) {
+    throw new OperationError("--detail-data must be a JSON array", ErrorCode.INVALID_JSON);
+  }
+
+  // Validate all column names upfront
+  validateColumnNames(Object.keys(masterData));
+  for (const detail of detailRows) {
+    validateColumnNames(Object.keys(detail));
+  }
+
+  if (dryRun) {
+    return dryRunValidation(sql, masterTable, masterData, detailTable, detailRows, detailFk);
+  }
+
+  // All inserts happen in a single transaction.
+  // The master row's id is backfilled into each detail row's FK column.
+  const { masterRow, detailResults } = await sql.begin(async (tx) => {
+    // 1. Insert master record
+    const { query: masterQuery, values: masterValues } = buildInsertQuery(masterTable, masterData);
+    rejectDangerousSQL(masterQuery);
+    const [masterRow] = await tx.unsafe(masterQuery, masterValues);
+    const masterId = masterRow.id;
+
+    // 2. Insert detail records with FK backfill
+    const detailResults: any[] = [];
+    for (const detail of detailRows) {
+      const row = { ...detail, [detailFk]: masterId };
+      const { query, values } = buildInsertQuery(detailTable, row);
+      rejectDangerousSQL(query);
+      const inserted = await tx.unsafe(query, values);
+      detailResults.push(...inserted);
+    }
+
+    return { masterRow, detailResults };
+  });
+
+  // Build table-mode output that matches the original two-section format
+  const additionalOutput =
+    `\nInserted ${detailResults.length} detail row(s) into ${detailTable}:\n` +
+    formatTable(detailResults);
+
+  return {
+    ok: true,
+    data: [masterRow],
+    meta: {
+      message: `Inserted master row into ${masterTable} (id: ${masterRow.id}):`,
+      masterTable,
+      detailTable,
+      detailRows: detailResults,
+      detailCount: detailResults.length,
+      additionalOutput,
+    },
+  };
+}
+
+/**
+ * Dry-run validation for master-detail insert.
+ * Checks that both tables exist and all columns in the payloads are valid.
+ * Does NOT execute any inserts.
+ *
+ * Delegates to shared primitives (assertTableExists, getTableColumns)
+ * from cli-utils.ts. The FK column is validated separately since it's not
+ * in the detail payload but must exist in the detail table.
+ */
+async function dryRunValidation(
+  sql: SqlClient,
+  masterTable: string,
+  masterData: Record<string, unknown>,
+  detailTable: string,
+  detailRows: Record<string, unknown>[],
+  detailFk: string,
+): Promise<OperationResult> {
+  // Validate both tables exist
+  await assertTableExists(sql as any, masterTable);
+  await assertTableExists(sql as any, detailTable);
+
+  // Validate master columns against actual schema
+  const masterDbCols = await getTableColumns(sql as any, masterTable);
+  const unknownMasterCols = Object.keys(masterData).filter((c) => !masterDbCols.has(c));
+  if (unknownMasterCols.length > 0) {
+    throw new OperationError(
+      `Unknown column(s) in '${masterTable}': ${unknownMasterCols.join(", ")}`,
+      ErrorCode.INVALID_COLUMN_NAME,
+    );
+  }
+
+  // Validate detail columns (including FK column which isn't in the payload
+  // but must exist in the table for the backfill to work)
+  const detailDbCols = await getTableColumns(sql as any, detailTable);
+  if (!detailDbCols.has(detailFk)) {
+    throw new OperationError(
+      `FK column '${detailFk}' not found in '${detailTable}'`,
+      ErrorCode.INVALID_COLUMN_NAME,
+    );
+  }
+  const allDetailPayloadCols = [...new Set(detailRows.flatMap((r) => Object.keys(r)))];
+  const unknownDetailCols = allDetailPayloadCols.filter((c) => !detailDbCols.has(c));
+  if (unknownDetailCols.length > 0) {
+    throw new OperationError(
+      `Unknown column(s) in '${detailTable}': ${unknownDetailCols.join(", ")}`,
+      ErrorCode.INVALID_COLUMN_NAME,
+    );
+  }
+
+  return {
+    ok: true,
+    data: [masterData as Record<string, unknown>],
+    meta: {
+      message: `Dry run: 1 master row + ${detailRows.length} detail row(s) would be inserted`,
+      dryRun: true,
+      masterTable,
+      detailTable,
+      detailRows,
+      detailCount: detailRows.length,
+      validationPassed: true,
+      tableOutputHandled: true,
+    },
+  };
+}

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

@@ -0,0 +1,137 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import Database from "better-sqlite3";
+import { rowsInsert } from "./rows-insert.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 rowsInsert's type signature)
+ * and a Database.Database proxy (for the `sql as any` casts inside
+ * rowsInsert that pass it to synchronous db-helpers functions like
+ * validatePayloadColumns, assertTableExists, etc.).
+ *
+ * We achieve this by adding SqlClient methods directly onto the sqlite handle.
+ */
+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 () => {
+    throw new Error("Not implemented");
+  };
+  extended.end = async () => {};
+  return extended;
+}
+
+describe("rows insert", () => {
+  let sqlite: Database.Database;
+  let sql: SqlClient;
+
+  beforeEach(() => {
+    sqlite = new Database(":memory:");
+    sqlite.pragma("foreign_keys = ON");
+    sql = createTestSql(sqlite);
+    sqlite.exec(`
+      CREATE TABLE accounts (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        name TEXT NOT NULL,
+        type TEXT NOT NULL
+      )
+    `);
+  });
+
+  afterEach(() => {
+    sqlite.close();
+  });
+
+  it("inserts a single row", async () => {
+    const result = await rowsInsert(sql, "accounts", '{"name":"Cash","type":"asset"}');
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.data).toHaveLength(1);
+    expect(result.data[0].name).toBe("Cash");
+    expect(result.data[0].type).toBe("asset");
+
+    // Verify in DB
+    const rows = sqlite.prepare("SELECT * FROM accounts").all();
+    expect(rows).toHaveLength(1);
+  });
+
+  it("inserts multiple rows from array", async () => {
+    const result = await rowsInsert(
+      sql,
+      "accounts",
+      '[{"name":"Cash","type":"asset"},{"name":"Revenue","type":"revenue"}]',
+    );
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.data).toHaveLength(2);
+
+    const rows = sqlite.prepare("SELECT * FROM accounts").all();
+    expect(rows).toHaveLength(2);
+  });
+
+  it("returns inserted row data", async () => {
+    const result = await rowsInsert(sql, "accounts", '{"name":"Cash","type":"asset"}');
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.meta?.message).toContain("Inserted 1 row(s)");
+    expect(result.data[0].name).toBe("Cash");
+  });
+
+  it("rejects invalid table names", async () => {
+    await expect(
+      rowsInsert(sql, "'; DROP TABLE accounts; --", '{"name":"x"}'),
+    ).rejects.toThrow("Invalid table name");
+  });
+
+  it("rejects invalid JSON", async () => {
+    await expect(
+      rowsInsert(sql, "accounts", "not json"),
+    ).rejects.toThrow();
+  });
+
+  it("rejects column names with injection characters", async () => {
+    await expect(
+      rowsInsert(sql, "accounts", '{"name; DROP TABLE accounts":"Cash","type":"asset"}'),
+    ).rejects.toThrow("Invalid column name");
+  });
+
+  it("rejects data containing control characters", async () => {
+    await expect(
+      rowsInsert(sql, "accounts", '{"name":"Cash\x00","type":"asset"}'),
+    ).rejects.toThrow("control characters");
+  });
+
+  // -- Dry-run tests --
+
+  it("dry-run validates successfully without inserting", async () => {
+    const result = await rowsInsert(sql, "accounts", '{"name":"Cash","type":"asset"}', true);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.meta?.dryRun).toBe(true);
+    expect(result.meta?.validationPassed).toBe(true);
+
+    // Verify nothing was actually inserted
+    const rows = sqlite.prepare("SELECT * FROM accounts").all();
+    expect(rows).toHaveLength(0);
+  });
+
+  it("dry-run catches nonexistent table", async () => {
+    await expect(
+      rowsInsert(sql, "nonexistent", '{"name":"Cash"}', true),
+    ).rejects.toThrow("not found");
+  });
+
+  it("dry-run catches unknown columns", async () => {
+    await expect(
+      rowsInsert(sql, "accounts", '{"name":"Cash","bogus_column":"x"}', true),
+    ).rejects.toThrow("Unknown column");
+  });
+});

package/src/cli/rows-insert.ts

@@ -0,0 +1,97 @@
+import { z } from "zod";
+import type { SqlClient, OperationResult } from "../introspect/types.js";
+import { rejectDangerousSQL } from "../introspect/sql-safety.js";
+import { buildInsertQuery, validatePayloadColumns } from "../introspect/db-helpers.js";
+import { validateTableName, validateColumnNames, rejectControlChars } from "../introspect/sql-safety.js";
+
+export const rowsInsertInput = z.object({
+  table: z.string().describe("Target table name"),
+  data: z.string().describe("JSON string: single object or array of objects"),
+  dryRun: z.boolean().optional().describe("Validate without executing"),
+});
+
+/**
+ * Insert one or more rows into a table.
+ * Data is provided as a JSON string (single object or array of objects).
+ * Returns the inserted rows (via RETURNING *).
+ *
+ * When dryRun is true, validates everything (table exists, columns exist,
+ * types are compatible) without executing the insert.
+ */
+export async function rowsInsert(
+  sql: SqlClient,
+  tableName: string,
+  dataJson: string,
+  dryRun: boolean = false,
+): Promise<OperationResult> {
+  // Validate table name (delegates to shared identifier check in cli-utils)
+  validateTableName(tableName);
+
+  // Reject control characters before parsing -- agents sometimes produce
+  // invisible chars that would silently corrupt data in the database.
+  rejectControlChars(dataJson);
+
+  const data = JSON.parse(dataJson);
+  const rows = Array.isArray(data) ? data : [data];
+
+  if (rows.length === 0) {
+    return { ok: true, data: [], meta: { message: "No data to insert." } };
+  }
+
+  // Validate all column names upfront
+  for (const row of rows) {
+    validateColumnNames(Object.keys(row));
+  }
+
+  if (dryRun) {
+    return dryRunValidation(sql, tableName, rows);
+  }
+
+  const results: any[] = [];
+  for (const row of rows) {
+    const { query, values } = buildInsertQuery(tableName, row);
+    rejectDangerousSQL(query);
+    const inserted = await sql.unsafe(query, values);
+    results.push(...inserted);
+  }
+
+  return {
+    ok: true,
+    data: results,
+    meta: {
+      message: `Inserted ${results.length} row(s) into ${tableName}:`,
+      rowCount: results.length,
+      tableName,
+    },
+  };
+}
+
+/**
+ * Dry-run validation: checks that the table exists and all columns
+ * in the payload exist in the target table. Does NOT execute the insert.
+ *
+ * Delegates to shared primitives (assertTableExists, getTableColumns)
+ * via validatePayloadColumns in cli-utils.ts.
+ */
+async function dryRunValidation(
+  sql: SqlClient,
+  tableName: string,
+  rows: Record<string, unknown>[],
+): Promise<OperationResult> {
+  // Collect all unique column names across all rows, then validate them
+  // against the actual table schema in one call.
+  const allPayloadColumns = [...new Set(rows.flatMap((r) => Object.keys(r)))];
+  await validatePayloadColumns(sql as any, tableName, allPayloadColumns);
+
+  return {
+    ok: true,
+    data: rows as Record<string, unknown>[],
+    meta: {
+      message: `Dry run: ${rows.length} row(s) would be inserted into ${tableName}`,
+      dryRun: true,
+      tableName,
+      rowCount: rows.length,
+      validationPassed: true,
+    },
+  };
+}

package/src/cli/serve-single.ts

@@ -0,0 +1,49 @@
+import { serve } from "@hono/node-server";
+import { bootProject } from "../boot.js";
+import { createApp } from "../api/server.js";
+import { connectProject } from "../db/sqlite-connection.js";
+import { parseFlags } from "./format.js";
+import { logger } from "../db/logger.js";
+
+const log = logger.child({ module: "serve" });
+
+/**
+ * Single-project server.
+ *
+ * Boots one project from a directory layout:
+ *   projectDir/data/sqlite.db
+ *   projectDir/code/src/{schema,actions,reports,views}/
+ *
+ * Routes are mounted at the root (no /p/:slug prefix).
+ */
+export async function serveSingle(args: string[]): Promise<void> {
+  const flags = parseFlags(args);
+  const port = flags.port ? parseInt(flags.port, 10) : undefined;
+
+  const projectDir = flags["sapporta-project-dir"] ?? process.env.SAPPORTA_PROJECT_DIR;
+  if (!projectDir) {
+    throw new Error(
+      "SAPPORTA_PROJECT_DIR is required — set it to the project root directory",
+    );
+  }
+
+  const projectId = flags["project-id"] ?? process.env.PROJECT_ID ?? projectDir.split("/").pop()!;
+  const dataDir = flags["data-dir"] ?? process.env.SAPPORTA_DATA_DIR ?? `${projectDir}/data`;
+  const codeDir = flags["code-dir"] ?? process.env.SAPPORTA_CODE_DIR ?? `${projectDir}/code`;
+  const srcDir = `${codeDir}/src`;
+  const databasePath = flags["database-path"] ?? `${dataDir}/sqlite.db`;
+
+  const conn = connectProject(databasePath);
+  const projectCtx = await bootProject(
+    { slug: projectId, databasePath, dir: srcDir },
+    conn,
+  );
+
+  const app = createApp();
+  app.route("/", projectCtx.subApp);
+
+  const finalPort = port ?? parseInt(process.env.PORT ?? "3000", 10);
+  serve({ fetch: app.fetch, port: finalPort }, (info: { port: number }) => {
+    log.info(`Sapporta running at http://localhost:${info.port}`, { port: info.port, project: projectId });
+  });
+}

package/src/create-project.ts

@@ -0,0 +1,81 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { execSync } from "node:child_process";
+import { createRequire } from "node:module";
+
+export interface CreateProjectOptions {
+  /** Absolute path to the directory where package.json will be created. */
+  dir: string;
+  /** Project name for package.json. Defaults to the directory name. */
+  name?: string;
+}
+
+export interface CreateProjectResult {
+  dir: string;
+  name: string;
+  packageJson: Record<string, unknown>;
+}
+
+/**
+ * Create a Sapporta code project: writes package.json and installs dependencies.
+ *
+ * This is the SDK function — no CLI arg parsing, no OperationResult wrapping.
+ * The CLI and control-plane API both call this.
+ *
+ * Throws if package.json already exists in the target directory.
+ */
+export function createProject(opts: CreateProjectOptions): CreateProjectResult {
+  const { dir } = opts;
+  const projectName = opts.name ?? dir.split("/").pop() ?? "sapporta-project";
+
+  const pkgPath = join(dir, "package.json");
+  if (existsSync(pkgPath)) {
+    throw new Error(`package.json already exists in ${dir}`);
+  }
+
+  // Resolve @sapporta/server dependency specifier:
+  // - SAPPORTA_ROOT set (dev/source tree) → file: link
+  // - SAPPORTA_ROOT absent (published CLI) → use version from own package.json
+  const sapportaRoot = process.env.SAPPORTA_ROOT;
+
+  let coreSpec: string;
+  let corePkg: { dependencies: Record<string, string>; version?: string };
+
+  if (sapportaRoot) {
+    const corePkgPath = join(sapportaRoot, "packages", "core", "package.json");
+    corePkg = JSON.parse(readFileSync(corePkgPath, "utf-8"));
+    coreSpec = `file://${join(sapportaRoot, "packages", "core")}`;
+  } else {
+    const _require = createRequire(import.meta.url);
+    const corePkgPath = _require.resolve("@sapporta/server/package.json");
+    corePkg = JSON.parse(readFileSync(corePkgPath, "utf-8"));
+    coreSpec = `^${corePkg.version}`;
+  }
+
+  const drizzleVersion = corePkg.dependencies["drizzle-orm"];
+  const zodVersion = corePkg.dependencies["zod"];
+
+  const pkg = {
+    name: projectName,
+    private: true,
+    type: "module",
+    dependencies: {
+      "@sapporta/server": coreSpec,
+      "drizzle-orm": drizzleVersion,
+      "zod": zodVersion,
+    },
+  };
+
+  writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+
+  // Prefer pnpm, fall back to npm
+  let pm = "npm";
+  try {
+    execSync("pnpm --version", { stdio: "ignore" });
+    pm = "pnpm";
+  } catch {}
+
+  execSync(`${pm} install`, { cwd: dir, stdio: "inherit" });
+
+  return { dir, name: projectName, packageJson: pkg };
+}

package/src/data/count.ts

@@ -0,0 +1,62 @@
+import { Hono } from "hono";
+import type { Context } from "hono";
+import { sql, inArray } from "drizzle-orm";
+import { getTableConfig } from "drizzle-orm/sqlite-core";
+import type { TableDef } from "../schema/table.js";
+
+/**
+ * Handle a count request: GET /?group_by=fk_col&ids=1,2,3
+ * Returns grouped counts: { data: { "1": 3, "2": 5 } }
+ * Used by the UI to show child record counts in parent grids.
+ */
+export async function handleCount(schema: TableDef, db: any, c: Context): Promise<Response> {
+  const groupBy = c.req.query("group_by");
+  const idsParam = c.req.query("ids");
+
+  if (!groupBy || !idsParam) {
+    return c.json({ data: {} });
+  }
+
+  // Validate that the groupBy column exists
+  const config = getTableConfig(schema.drizzle);
+  const col = config.columns.find((col) => col.name === groupBy);
+  if (!col) {
+    return c.json({ error: `Column "${groupBy}" not found` }, 400);
+  }
+
+  const ids = idsParam
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .map(Number)
+    .filter((n) => !isNaN(n));
+
+  if (ids.length === 0) {
+    return c.json({ data: {} });
+  }
+
+  const drizzleCol = (schema.drizzle as any)[groupBy];
+
+  const rows = await db
+    .select({
+      groupKey: drizzleCol,
+      count: sql<number>`count(*)`,
+    })
+    .from(schema.drizzle)
+    .where(inArray(drizzleCol, ids))
+    .groupBy(drizzleCol);
+
+  const result: Record<string, number> = {};
+  for (const row of rows) {
+    result[String(row.groupKey)] = row.count;
+  }
+
+  return c.json({ data: result });
+}
+
+/** Create a count sub-app (convenience wrapper for tests). */
+export function countEndpoint(schema: TableDef, db: any) {
+  const app = new Hono();
+  app.get("/", (c) => handleCount(schema, db, c));
+  return app;
+}