@sapporta/server 0.0.1

package/src/data/query-parser.ts

@@ -0,0 +1,106 @@
+import { eq, gt, gte, lt, lte, like, ilike, asc, desc, and, type SQL } from "drizzle-orm";
+import type { TableDef } from "../schema/table.js";
+
+export interface ParsedQuery {
+  where: SQL | undefined;
+  orderBy: SQL[];
+  limit: number;
+  offset: number;
+}
+
+/**
+ * Parse query string parameters into Drizzle query parts.
+ *
+ * Supported params:
+ * - filter[column]=value          → eq(column, value)
+ * - filter[column][gt]=value      → gt(column, value)
+ * - filter[column][gte]=value     → gte(column, value)
+ * - filter[column][lt]=value      → lt(column, value)
+ * - filter[column][lte]=value     → lte(column, value)
+ * - filter[column][like]=value    → like(column, %value%)
+ * - filter[column][ilike]=value   → ilike(column, %value%)
+ * - sort=-column                  → desc(column)
+ * - sort=column                   → asc(column)
+ * - page=1&limit=50               → offset + limit
+ */
+export function parseQuery(
+  params: Record<string, string>,
+  schema: TableDef,
+): ParsedQuery {
+  const conditions: SQL[] = [];
+  const orderClauses: SQL[] = [];
+
+  // Parse limit and page
+  const limit = Math.min(Math.max(parseInt(params.limit ?? "50", 10) || 50, 1), 1000);
+  const page = Math.max(parseInt(params.page ?? "1", 10) || 1, 1);
+  const offset = (page - 1) * limit;
+
+  // Parse filters
+  for (const [key, value] of Object.entries(params)) {
+    // filter[column]=value
+    const simpleMatch = key.match(/^filter\[(\w+)\]$/);
+    if (simpleMatch) {
+      const colName = simpleMatch[1];
+      const col = findColumn(schema, colName);
+      if (col) {
+        conditions.push(eq(col, value));
+      }
+      continue;
+    }
+
+    // filter[column][operator]=value
+    const opMatch = key.match(/^filter\[(\w+)\]\[(\w+)\]$/);
+    if (opMatch) {
+      const colName = opMatch[1];
+      const op = opMatch[2];
+      const col = findColumn(schema, colName);
+      if (col) {
+        switch (op) {
+          case "gt":
+            conditions.push(gt(col, value));
+            break;
+          case "gte":
+            conditions.push(gte(col, value));
+            break;
+          case "lt":
+            conditions.push(lt(col, value));
+            break;
+          case "lte":
+            conditions.push(lte(col, value));
+            break;
+          case "like":
+            conditions.push(like(col, `%${value}%`));
+            break;
+          case "ilike":
+            conditions.push(ilike(col, `%${value}%`));
+            break;
+        }
+      }
+      continue;
+    }
+  }
+
+  // Parse sort
+  if (params.sort) {
+    const sortFields = params.sort.split(",");
+    for (const field of sortFields) {
+      const descending = field.startsWith("-");
+      const colName = descending ? field.slice(1) : field;
+      const col = findColumn(schema, colName);
+      if (col) {
+        orderClauses.push(descending ? desc(col) : asc(col));
+      }
+    }
+  }
+
+  return {
+    where: conditions.length > 0 ? and(...conditions) : undefined,
+    orderBy: orderClauses,
+    limit,
+    offset,
+  };
+}
+
+function findColumn(schema: TableDef, name: string) {
+  return (schema.drizzle as any)[name] ?? null;
+}

package/src/data/sanitize.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect } from "vitest";
+import { rejectControlChars, isSafeIdentifier } from "./sanitize.js";
+
+describe("rejectControlChars", () => {
+  it("accepts normal text", () => {
+    expect(() => rejectControlChars('{"name":"Cash","amount":100}')).not.toThrow();
+  });
+
+  it("accepts whitespace characters (tab, newline, carriage return)", () => {
+    expect(() => rejectControlChars('{\n\t"name": "Cash"\r\n}')).not.toThrow();
+  });
+
+  it("rejects null byte", () => {
+    expect(() => rejectControlChars('{"name":"Cash\x00"}')).toThrow("control characters");
+  });
+
+  it("rejects bell character", () => {
+    expect(() => rejectControlChars('{"name":"Cash\x07"}')).toThrow("control characters");
+  });
+
+  it("rejects backspace", () => {
+    expect(() => rejectControlChars('{"name":"Cash\x08"}')).toThrow("control characters");
+  });
+
+  it("rejects form feed within restricted range", () => {
+    expect(() => rejectControlChars('{"name":"Cash\x0e"}')).toThrow("control characters");
+  });
+
+  it("throws ValidationError", () => {
+    expect(() => rejectControlChars("bad\x00")).toThrow("Validation failed");
+  });
+});
+
+describe("isSafeIdentifier", () => {
+  it("accepts valid identifiers", () => {
+    expect(isSafeIdentifier("accounts")).toBe(true);
+    expect(isSafeIdentifier("_private")).toBe(true);
+    expect(isSafeIdentifier("order_items")).toBe(true);
+    expect(isSafeIdentifier("AccountType")).toBe(true);
+  });
+
+  it("rejects names with special characters", () => {
+    expect(isSafeIdentifier("users; DROP TABLE")).toBe(false);
+    expect(isSafeIdentifier("my-table")).toBe(false);
+    expect(isSafeIdentifier("my table")).toBe(false);
+    expect(isSafeIdentifier("name?")).toBe(false);
+    expect(isSafeIdentifier("col'name")).toBe(false);
+  });
+
+  it("rejects names starting with numbers", () => {
+    expect(isSafeIdentifier("1table")).toBe(false);
+  });
+
+  it("rejects empty string", () => {
+    expect(isSafeIdentifier("")).toBe(false);
+  });
+});

package/src/data/sanitize.ts

@@ -0,0 +1,25 @@
+import { ValidationError } from "../db/errors.js";
+
+/**
+ * Reject strings containing control characters (below ASCII 0x20)
+ * except for the whitespace characters that JSON legitimately uses:
+ * \t (0x09), \n (0x0a), \r (0x0d).
+ *
+ * AI agents sometimes produce invisible control characters in output.
+ * These can cause subtle data corruption when inserted into the database.
+ */
+export function rejectControlChars(text: string): void {
+  if (/[\x00-\x08\x0b\x0c\x0e-\x1f]/.test(text)) {
+    throw new ValidationError([
+      { field: "", message: "Value contains control characters" },
+    ]);
+  }
+}
+
+/**
+ * Check whether a name is a safe SQL identifier:
+ * starts with a letter or underscore, followed by alphanumeric or underscores.
+ */
+export function isSafeIdentifier(name: string): boolean {
+  return /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name);
+}

package/src/data/save-pipeline.test.ts

@@ -0,0 +1,115 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
+import { table } from "../schema/table.js";
+import { savePipeline, insertRow, updateRow } from "./save-pipeline.js";
+import { ValidationError } from "../db/errors.js";
+import { createTestDb } from "../testing/test-utils.js";
+
+const accountsTable = sqliteTable("accounts", {
+  id: integer("id").primaryKey({ autoIncrement: true }),
+  name: text("name").notNull(),
+  type: text("type").notNull(),
+  balance: integer("balance"),
+});
+
+const accounts = table({
+  drizzle: accountsTable,
+  meta: {
+    selects: [
+      {
+        type: "select",
+        column: "type",
+        options: ["asset", "liability", "equity", "revenue", "expense"],
+      },
+    ],
+  },
+});
+
+describe("save-pipeline (integration)", () => {
+  let db: any;
+
+  beforeEach(async () => {
+    const testDb = createTestDb();
+    db = testDb.db;
+    // Create the accounts table
+    testDb.sqlite.exec(`
+      CREATE TABLE IF NOT EXISTS accounts (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        name TEXT NOT NULL,
+        type TEXT NOT NULL,
+        balance INTEGER
+      )
+    `);
+  });
+
+  it("inserts a valid record", async () => {
+    const result = await savePipeline(accounts, db, {
+      name: "Cash",
+      type: "asset",
+    });
+
+    expect(result.id).toBe(1);
+    expect(result.name).toBe("Cash");
+    expect(result.type).toBe("asset");
+  });
+
+  it("rejects invalid records", async () => {
+    await expect(
+      savePipeline(accounts, db, { name: "Bad", type: "invalid_type" }),
+    ).rejects.toThrow(ValidationError);
+  });
+
+  it("updates an existing record", async () => {
+    const inserted = await insertRow(accounts, db, {
+      name: "Cash",
+      type: "asset",
+    });
+
+    const updated = await savePipeline(
+      accounts,
+      db,
+      { name: "Cash on Hand", type: "asset" },
+      inserted.id as number,
+    );
+
+    expect(updated.name).toBe("Cash on Hand");
+    expect(updated.id).toBe(inserted.id);
+  });
+
+  it("rejects control characters in string values", async () => {
+    await expect(
+      savePipeline(accounts, db, { name: "Cash\x00", type: "asset" }),
+    ).rejects.toThrow(ValidationError);
+
+    try {
+      await savePipeline(accounts, db, { name: "Cash\x07", type: "asset" });
+    } catch (e: any) {
+      expect(e).toBeInstanceOf(ValidationError);
+      expect(e.errors[0].field).toBe("name");
+      expect(e.errors[0].message).toContain("control characters");
+    }
+  });
+
+  it("rejects unknown columns", async () => {
+    await expect(
+      savePipeline(accounts, db, {
+        name: "Cash",
+        type: "asset",
+        bogus: "should fail",
+      }),
+    ).rejects.toThrow(ValidationError);
+  });
+
+  it("insertRow and updateRow work directly", async () => {
+    const row = await insertRow(accounts, db, {
+      name: "Revenue",
+      type: "revenue",
+    });
+    expect(row.id).toBeDefined();
+
+    const updated = await updateRow(accounts, db, row.id as number, {
+      name: "Sales Revenue",
+    });
+    expect(updated.name).toBe("Sales Revenue");
+  });
+});

package/src/data/save-pipeline.ts

@@ -0,0 +1,93 @@
+import { eq } from "drizzle-orm";
+import { getTableConfig } from "drizzle-orm/sqlite-core";
+import type { BetterSQLite3Database } from "drizzle-orm/better-sqlite3";
+import type { TableDef } from "../schema/table.js";
+import { validate } from "./validate.js";
+import { ValidationError } from "../db/errors.js";
+import { rejectControlChars } from "./sanitize.js";
+
+/**
+ * Insert a new row using Drizzle's table API.
+ */
+export async function insertRow(
+  schema: TableDef,
+  db: BetterSQLite3Database,
+  record: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+  const result = await db
+    .insert(schema.drizzle)
+    .values(record as any)
+    .returning();
+
+  return result[0] as Record<string, unknown>;
+}
+
+/**
+ * Update an existing row using Drizzle's table API.
+ */
+export async function updateRow(
+  schema: TableDef,
+  db: BetterSQLite3Database,
+  id: number | string,
+  record: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+  const config = getTableConfig(schema.drizzle);
+  const pkCol = config.columns.find((c) => c.primary);
+  if (!pkCol) throw new Error(`No primary key found on table ${config.name}`);
+
+  const drizzleCol = (schema.drizzle as any)[pkCol.name];
+
+  const result = await db
+    .update(schema.drizzle)
+    .set(record as any)
+    .where(eq(drizzleCol, id))
+    .returning();
+
+  if (result.length === 0) {
+    throw new Error(`Record with id ${id} not found`);
+  }
+
+  return result[0] as Record<string, unknown>;
+}
+
+/**
+ * The save pipeline: validate → insert or update.
+ * If `id` is provided, it updates; otherwise it inserts.
+ * Respects `schema.meta.save` custom override if provided.
+ */
+export async function savePipeline(
+  schema: TableDef,
+  db: BetterSQLite3Database,
+  record: Record<string, unknown>,
+  id?: number | string,
+): Promise<Record<string, unknown>> {
+  // Step 0: Reject control characters in string values
+  for (const [key, value] of Object.entries(record)) {
+    if (typeof value === "string") {
+      try {
+        rejectControlChars(value);
+      } catch {
+        throw new ValidationError([
+          { field: key, message: "Value contains control characters" },
+        ]);
+      }
+    }
+  }
+
+  // Step 1: Validate
+  const errors = validate(schema, record);
+  if (errors.length > 0) {
+    throw new ValidationError(errors);
+  }
+
+  // Step 2: Custom save or default insert/update
+  if (schema.meta.save) {
+    return schema.meta.save(record, db);
+  }
+
+  if (id != null) {
+    return updateRow(schema, db, id, record);
+  } else {
+    return insertRow(schema, db, record);
+  }
+}

package/src/data/validate.test.ts

@@ -0,0 +1,110 @@
+import { describe, it, expect } from "vitest";
+import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
+import { z } from "zod";
+import { table, timestamp } from "../schema/table.js";
+import { validate, buildZodSchema } from "./validate.js";
+
+describe("buildZodSchema()", () => {
+  it("infers string fields as required", () => {
+    const schema = table({
+      drizzle: sqliteTable("test_strings", {
+        id: integer("id").primaryKey({ autoIncrement: true }),
+        name: text("name").notNull(),
+      }),
+    });
+
+    const zodSchema = buildZodSchema(schema);
+    expect(zodSchema.safeParse({ name: "hello" }).success).toBe(true);
+    expect(zodSchema.safeParse({}).success).toBe(false);
+    expect(zodSchema.safeParse({ name: 123 }).success).toBe(false);
+  });
+
+  it("makes nullable columns nullable", () => {
+    const schema = table({
+      drizzle: sqliteTable("test_nullable", {
+        id: integer("id").primaryKey({ autoIncrement: true }),
+        notes: text("notes"),
+      }),
+    });
+
+    const zodSchema = buildZodSchema(schema);
+    expect(zodSchema.safeParse({ notes: null }).success).toBe(true);
+    expect(zodSchema.safeParse({ notes: "hello" }).success).toBe(true);
+  });
+
+  it("makes columns with defaults optional", () => {
+    const schema = table({
+      drizzle: sqliteTable("test_defaults", {
+        id: integer("id").primaryKey({ autoIncrement: true }),
+        created_at: timestamp("created_at").notNull().$defaultFn(() => new Date().toISOString()),
+      }),
+    });
+
+    const zodSchema = buildZodSchema(schema);
+    // created_at has a default, so it should be optional
+    expect(zodSchema.safeParse({}).success).toBe(true);
+  });
+
+  it("validates select options", () => {
+    const schema = table({
+      drizzle: sqliteTable("test_selects", {
+        id: integer("id").primaryKey({ autoIncrement: true }),
+        status: text("status").notNull(),
+      }),
+      meta: {
+        selects: [
+          { type: "select", column: "status", options: ["active", "inactive"] },
+        ],
+      },
+    });
+
+    const zodSchema = buildZodSchema(schema);
+    expect(zodSchema.safeParse({ status: "active" }).success).toBe(true);
+    expect(zodSchema.safeParse({ status: "invalid" }).success).toBe(false);
+  });
+
+  it("uses user-provided validation schema", () => {
+    const customSchema = z.object({
+      name: z.string().min(3),
+    });
+
+    const schema = table({
+      drizzle: sqliteTable("test_custom", {
+        id: integer("id").primaryKey({ autoIncrement: true }),
+        name: text("name").notNull(),
+      }),
+      meta: { validation: customSchema },
+    });
+
+    const zodSchema = buildZodSchema(schema);
+    expect(zodSchema.safeParse({ name: "ab" }).success).toBe(false);
+    expect(zodSchema.safeParse({ name: "abc" }).success).toBe(true);
+  });
+});
+
+describe("validate()", () => {
+  it("returns empty array for valid records", () => {
+    const schema = table({
+      drizzle: sqliteTable("test_valid", {
+        id: integer("id").primaryKey({ autoIncrement: true }),
+        name: text("name").notNull(),
+      }),
+    });
+
+    expect(validate(schema, { name: "hello" })).toEqual([]);
+  });
+
+  it("returns field errors for invalid records", () => {
+    const schema = table({
+      drizzle: sqliteTable("test_invalid", {
+        id: integer("id").primaryKey({ autoIncrement: true }),
+        name: text("name").notNull(),
+        count: integer("count").notNull(),
+      }),
+    });
+
+    const errors = validate(schema, {});
+    expect(errors.length).toBeGreaterThan(0);
+    expect(errors.some((e) => e.field === "name")).toBe(true);
+  });
+});

package/src/data/validate.ts

@@ -0,0 +1,98 @@
+import { z } from "zod";
+import { getTableConfig } from "drizzle-orm/sqlite-core";
+import { normalizeDataType } from "../schema/normalize-datatype.js";
+import type { TableDef } from "../schema/table.js";
+
+/**
+ * Build a Zod schema from a Drizzle table definition.
+ * Infers types from column metadata. User-provided validation overrides this.
+ */
+export function buildZodSchema(
+  schema: TableDef,
+): z.ZodObject<Record<string, z.ZodTypeAny>> {
+  // If user provided a custom validation schema, use it
+  if (schema.meta.validation) {
+    return schema.meta.validation;
+  }
+
+  const config = getTableConfig(schema.drizzle);
+  const shape: Record<string, z.ZodTypeAny> = {};
+
+  for (const col of config.columns) {
+    // Skip auto-generated columns (serial/identity primary keys, defaults)
+    if (col.primary && col.hasDefault) continue;
+    // Skip columns with defaults for building the "create" schema
+    // They become optional
+    const hasDefault = col.hasDefault;
+
+    // Drizzle's internal dataType varies by dialect (e.g. Pg string-mode timestamps
+    // report "string"). normalizeDataType() provides a stable value for validation.
+    const effectiveDataType = normalizeDataType(col);
+
+    let fieldSchema: z.ZodTypeAny;
+
+    switch (effectiveDataType) {
+      case "number":
+        fieldSchema = z.number();
+        break;
+      case "boolean":
+        fieldSchema = z.boolean();
+        break;
+      case "date":
+        fieldSchema = z.union([z.date(), z.string().datetime({ offset: true })]);
+        break;
+      case "string":
+      default:
+        fieldSchema = z.string();
+        break;
+    }
+
+    // Validate select options if defined
+    if (schema.meta.selects) {
+      const selectMeta = schema.meta.selects.find(
+        (s) => s.column === col.name,
+      );
+      if (selectMeta) {
+        fieldSchema = z.enum(selectMeta.options as [string, ...string[]]);
+      }
+    }
+
+    // Make nullable + optional if column allows null
+    if (!col.notNull) {
+      fieldSchema = fieldSchema.nullable().optional();
+    }
+
+    // Make optional if column has a default
+    if (hasDefault && col.notNull) {
+      fieldSchema = fieldSchema.optional();
+    }
+
+    shape[col.name] = fieldSchema;
+  }
+
+  return z.object(shape).strict();
+}
+
+export interface ValidationErrorDetail {
+  field: string;
+  message: string;
+}
+
+/**
+ * Validate a record against a table schema.
+ * Returns an array of errors (empty if valid).
+ */
+export function validate(
+  schema: TableDef,
+  record: Record<string, unknown>,
+): ValidationErrorDetail[] {
+  const zodSchema = buildZodSchema(schema);
+  const result = zodSchema.safeParse(record);
+
+  if (result.success) return [];
+
+  return result.error.issues.map((issue) => ({
+    field: issue.path.join("."),
+    message: issue.message,
+  }));
+}

package/src/db/errors.ts

@@ -0,0 +1,20 @@
+export class ValidationError extends Error {
+  public readonly errors: Array<{ field: string; message: string }>;
+
+  constructor(errors: Array<{ field: string; message: string }>) {
+    const msg = errors.map((e) => `${e.field}: ${e.message}`).join(", ");
+    super(`Validation failed: ${msg}`);
+    this.name = "ValidationError";
+    this.errors = errors;
+  }
+}
+
+export class ActionError extends Error {
+  public readonly code: string;
+
+  constructor(message: string, code = "ACTION_ERROR") {
+    super(message);
+    this.name = "ActionError";
+    this.code = code;
+  }
+}

package/src/db/logger.ts

@@ -0,0 +1,63 @@
+import winston from "winston";
+import type { MiddlewareHandler } from "hono";
+
+const { combine, timestamp, printf, json } = winston.format;
+
+/**
+ * Human-readable format for development.
+ *
+ * Output: `2026-03-11 14:32:01 info [runtime] Booting project project=playground`
+ */
+const devFormat = printf(({ level, message, module, timestamp, ...rest }) => {
+  const mod = module ? ` [${module}]` : "";
+  const extras = Object.keys(rest).length > 0
+    ? " " + Object.entries(rest).map(([k, v]) => `${k}=${typeof v === "object" ? JSON.stringify(v) : v}`).join(" ")
+    : "";
+  return `${timestamp} ${level}${mod} ${message}${extras}`;
+});
+
+/**
+ * Create a Winston logger instance.
+ *
+ * Reads from environment:
+ * - `LOG_FORMAT` — `"json"` for structured JSON, anything else for human-readable (default)
+ * - `LOG_LEVEL` — Winston level threshold. Default: `"debug"`
+ */
+export function createLogger() {
+  const isJson = process.env.LOG_FORMAT === "json";
+  const level = process.env.LOG_LEVEL ?? "debug";
+
+  return winston.createLogger({
+    level,
+    format: combine(
+      timestamp({ format: "YYYY-MM-DD HH:mm:ss" }),
+      isJson ? json() : devFormat,
+    ),
+    transports: [new winston.transports.Console()],
+  });
+}
+
+/** Singleton logger instance. Modules use `logger.child({ module: "name" })`. */
+export const logger = createLogger();
+
+/**
+ * Hono middleware that replaces `hono/logger`.
+ *
+ * Logs each request/response at the `http` level with method, path, status, and duration.
+ * Does NOT read the request body — that's the handler's job.
+ */
+export function requestLogger(): MiddlewareHandler {
+  const log = logger.child({ module: "http" });
+
+  return async (c, next) => {
+    const start = Date.now();
+    await next();
+    const duration = Date.now() - start;
+    log.http("request", {
+      method: c.req.method,
+      path: c.req.path,
+      status: c.res.status,
+      duration: `${duration}ms`,
+    });
+  };
+}