@sapporta/server 0.0.1

package/src/boot.ts

@@ -0,0 +1,206 @@
+import { Hono } from "hono";
+import type { BetterSQLite3Database } from "drizzle-orm/better-sqlite3";
+import type Database from "better-sqlite3";
+import type { ActionInstance } from "./actions/action.js";
+import type { ReportDefinition } from "./reports/report.js";
+import type { ViewMeta } from "./views/view.js";
+import type { ProjectDbConnection } from "./db/sqlite-connection.js";
+import { loadSchemas } from "./schema/loader.js";
+import { migrateSchemas } from "./schema/migrate.js";
+import { loadActions } from "./actions/loader.js";
+import { actionApi } from "./api/actions.js";
+import { loadReports } from "./reports/loader.js";
+import { reportApi } from "./api/reports.js";
+import { loadViewMeta } from "./views/loader.js";
+import { viewApi } from "./api/views.js";
+import { SchemaRegistry } from "./schema/registry.js";
+import { tablesApi } from "./api/tables.js";
+import { ensureMetadataTables, loadUISchemas, validateUISchemas } from "./schema/metadata-tables.js";
+import { metaApi } from "./api/meta.js";
+import { logger } from "./db/logger.js";
+
+const log = logger.child({ module: "boot" });
+
+export interface ProjectConfig {
+  slug: string;
+  /**
+   * Absolute path to the SQLite database file. Persisted in the registry at
+   * creation time and passed through unchanged at boot time. The storage
+   * layer derives this path once (during create), then it's stored forever.
+   */
+  databasePath: string;
+  /**
+   * Absolute path to the project's filesystem directory (containing schema/,
+   * actions/, reports/, views/ subdirectories). null for API-created projects
+   * that have no filesystem presence — they rely entirely on UI-managed schemas.
+   */
+  dir: string | null;
+}
+
+/** Runtime context for a single booted project. */
+export interface InProcessProject {
+  kind: "in-process";
+  slug: string;
+  dir: string | null;
+  db: BetterSQLite3Database;
+  sqlite: Database.Database;
+  /** Source of truth for table schemas. Use registry.all() for the live list. */
+  registry: SchemaRegistry;
+  actions: ActionInstance<any, any>[];
+  reports: ReportDefinition[];
+  views: ViewMeta[];
+  /**
+   * Per-project Hono sub-app containing all of this project's routes.
+   *
+   * The root app does NOT mount project routes directly (via app.route).
+   * Instead, a single /p/:slug/* catch-all dispatches to the appropriate
+   * project's subApp by looking up projectMap. This is necessary because
+   * Hono compiles its route tree on the first request — any app.route()
+   * call after that throws "Can not add a route since the matcher is
+   * already built". The sub-app pattern sidesteps this: the catch-all is
+   * registered once at startup, and new projects just need to be added
+   * to the Map to become routable.
+   */
+  subApp: Hono;
+}
+
+// ── Boot ──────────────────────────────────────────────────────────────────────
+
+/**
+ * Boot a single project: connect DB, load schemas, migrate, build sub-app.
+ *
+ * The boot sequence has ordering constraints — steps must run in this order:
+ *
+ *   1. ensureMetadataTables — creates _sapporta_tables/_sapporta_columns if
+ *      they don't exist. MUST run before loadUISchemas (step 5) which reads
+ *      from these tables.
+ *
+ *   2. Load file schemas from disk (if dir is set). File schemas are registered
+ *      FIRST so they take precedence over UI schemas.
+ *
+ *   3. loadUISchemas — reads UI-managed table definitions from the metadata
+ *      tables. Needs file schemas already registered so that FK references
+ *      from UI tables to file tables resolve correctly.
+ *
+ *   4. migrateSchemas — applies Drizzle migrations for FILE-managed tables
+ *      only. UI tables use direct DDL from the mutation API. Running
+ *      pushSchema on UI tables risks destructive ALTER statements if
+ *      metadata drifts from actual DB state.
+ *
+ *   5. validateUISchemas — compares UI metadata against actual DB state.
+ *      Runs AFTER migration so file tables exist. Warns on drift but
+ *      doesn't auto-fix.
+ *
+ *   6. Build the per-project Hono sub-app with all five namespaces mounted
+ *      unconditionally: /meta, /tables, /actions, /reports, /views. Routes
+ *      are always present even when there are no resources — this avoids
+ *      the Hono "can't add routes after compilation" constraint.
+ *
+ * Returns a InProcessProject that includes the sub-app. The caller adds
+ * this to projectMap, which makes the project's routes immediately accessible
+ * via the /p/:slug/* dynamic dispatch in runtime().
+ */
+export async function bootProject(
+  project: ProjectConfig,
+  conn: ProjectDbConnection,
+): Promise<InProcessProject> {
+  log.info(`Booting project "${project.slug}"`, { project: project.slug, dir: project.dir });
+
+  const { sqlite, db } = conn;
+  log.info("Database connected", { project: project.slug });
+
+  // Step 1: Create metadata tables. Must happen before loadUISchemas.
+  ensureMetadataTables(sqlite);
+
+  // Steps 2-3: Load schemas. File schemas first (take precedence), then UI schemas.
+  // API-created projects (dir === null) skip file schema loading entirely — they
+  // have no filesystem directory and rely on UI-managed schemas exclusively.
+  const registry = new SchemaRegistry();
+  if (project.dir) {
+    const schemaDir = `${project.dir}/schema`;
+    const { tables } = await loadSchemas(schemaDir);
+    log.info("Loaded schemas", { project: project.slug, tables: tables.length });
+
+    // File schemas registered first — if a UI table has the same name,
+    // it becomes "shadowed" (tracked but not active).
+    for (const def of tables) {
+      registry.register(def, "file");
+    }
+  }
+
+  // UI schemas loaded second. The registry already has file schemas, so FK
+  // resolution from UI tables to file tables works immediately.
+  const uiDefs = loadUISchemas(sqlite, registry);
+  for (const def of uiDefs) {
+    registry.register(def, "ui");
+  }
+  if (uiDefs.length > 0) {
+    const activeUI = registry.uiManaged().length;
+    const shadowed = uiDefs.length - activeUI;
+    log.info("Loaded UI-managed tables", { project: project.slug, total: uiDefs.length, active: activeUI, shadowed });
+  }
+
+  // Step 4: Migrate file-managed tables only.
+  await migrateSchemas(registry.fileManaged(), db, sqlite);
+
+  // Step 5: Validate UI schemas against actual DB state. Warns on drift.
+  validateUISchemas(sqlite, registry, project.slug);
+
+  // Step 6: Load resources and build the per-project Hono sub-app.
+  //
+  // All five namespaces are mounted UNCONDITIONALLY — even when there are
+  // no actions/reports/views. This avoids the Hono route-tree-compilation
+  // constraint: Hono compiles its route tree on first request, so all
+  // routes must exist before then.
+
+  let actions: ActionInstance<any, any>[] = [];
+  let reports: ReportDefinition[] = [];
+  let views: ViewMeta[] = [];
+
+  // File-based resources (actions, reports, views) only exist for filesystem
+  // projects. API-created projects have dir === null and skip this entirely.
+  if (project.dir) {
+    const actionsDir = `${project.dir}/actions`;
+    try {
+      actions = await loadActions(actionsDir);
+      if (actions.length > 0) {
+        log.info("Loaded actions", { project: project.slug, count: actions.length });
+      }
+    } catch {
+      // Actions dir may not exist yet — not an error
+    }
+
+    const reportsDir = `${project.dir}/reports`;
+    try {
+      reports = await loadReports(reportsDir);
+      if (reports.length > 0) {
+        log.info("Loaded reports", { project: project.slug, count: reports.length });
+      }
+    } catch {
+      // Reports dir may not exist yet
+    }
+
+    const viewsDir = `${project.dir}/views`;
+    try {
+      views = await loadViewMeta(viewsDir);
+      if (views.length > 0) {
+        log.info("Loaded views", { project: project.slug, count: views.length });
+      }
+    } catch {
+      // Views dir may not exist yet
+    }
+  }
+
+  // Routes are relative (e.g. /meta, /tables) — the /p/{slug} prefix is
+  // stripped by the dynamic dispatch in runtime() before reaching this sub-app.
+  const subApp = new Hono();
+  subApp.route("/meta", metaApi(registry, sqlite, db, project));
+  subApp.route("/tables", tablesApi(registry, db));
+  subApp.route("/actions", actionApi(actions, db));
+  subApp.route("/reports", reportApi(reports, sqlite));
+  subApp.route("/views", viewApi(views));
+
+  log.info("Project routes mounted", { project: project.slug, tables: registry.all().length });
+
+  return { kind: "in-process" as const, slug: project.slug, dir: project.dir, db, sqlite, registry, actions, reports, views, subApp };
+}

package/src/cli/ai-commands.ts

@@ -0,0 +1,220 @@
+import { z } from "zod";
+import { dbListTables } from "../introspect/list-tables.js";
+import { dbDescribe } from "../introspect/describe.js";
+import { dbDescribeAll } from "../introspect/describe-all.js";
+// SQLite has no native enum type — enums command removed.
+import { dbQuery } from "../introspect/query.js";
+import { dbExec } from "../introspect/exec.js";
+import { dbSample } from "../introspect/sample.js";
+import { dbIndexes } from "../introspect/indexes.js";
+import { rowsInsert } from "./rows-insert.js";
+import { rowsInsertInput } from "./rows-insert.js";
+import { rowsInsertMasterDetail } from "./rows-insert-master-detail.js";
+import { rowsInsertMasterDetailInput } from "./rows-insert-master-detail.js";
+import { tableRename } from "../introspect/table-rename.js";
+import { tableRenameInput } from "../introspect/table-rename.js";
+type AiCommandMeta = {
+  command: string;
+  description: string;
+  mutating?: boolean;
+  inputSchema?: z.ZodType;
+  examples?: string[];
+};
+import type { SqlClient, OperationResult } from "../introspect/types.js";
+import { OperationError, ErrorCode } from "../introspect/types.js";
+import { resolveOutputFormat } from "./format.js";
+
+// ---------------------------------------------------------------------------
+// AiCommand type
+// ---------------------------------------------------------------------------
+
+export type AiCommand = {
+  description: string;
+  inputSchema: z.ZodType;
+  mutating?: boolean;
+  examples?: string[];
+  /** Convert positional args + flags into the input object shape. */
+  parseArgs: (positional: string[], flags: Record<string, string>) => unknown;
+  /** Number of leading positional args to consume before flag parsing. */
+  positionalCount: number;
+  /** Usage string shown when required positional arg is missing (flag mode). */
+  usage?: string;
+  // TODO: PLAN-3 — Change SqlClient to Database.Database once CLI is fully migrated.
+  // For now, the CLI runner casts the connection to the expected type.
+  run: (sql: SqlClient, input: any) => Promise<OperationResult>;
+};
+
+// Zod schemas for introspection commands (these were previously exported from
+// the Postgres introspection modules but are now defined inline since the SQLite
+// versions don't need them for validation — they're only used by the CLI parser).
+const dbListTablesInput = z.object({});
+const dbDescribeInput = z.object({ table: z.string() });
+const dbDescribeAllInput = z.object({});
+const dbQueryInput = z.object({ sql: z.string(), limit: z.number().optional() });
+const dbExecInput = z.object({ sql: z.string(), dryRun: z.boolean().optional() });
+const dbSampleInput = z.object({
+  table: z.string(),
+  limit: z.number().optional(),
+  fields: z.string().optional(),
+});
+const dbIndexesInput = z.object({ table: z.string() });
+
+// ---------------------------------------------------------------------------
+// Command definitions
+// ---------------------------------------------------------------------------
+// Each command uses the SQLite introspection functions which are synchronous.
+// The run() signature expects Promise<OperationResult>, so we wrap sync
+// results with Promise.resolve(). The SqlClient → Database cast is handled
+// by the CLI runner which passes the raw better-sqlite3 handle.
+
+export const AI_COMMANDS: Record<string, AiCommand> = {
+  "meta tables": {
+    description: "List all tables with schema metadata and row counts",
+    inputSchema: dbListTablesInput,
+    positionalCount: 0,
+    parseArgs: () => ({}),
+    run: (sql) => Promise.resolve(dbListTables(sql as any)),
+  },
+  "meta tables describe": {
+    description: "Show table structure (columns, types, constraints, foreign keys)",
+    inputSchema: dbDescribeInput,
+    positionalCount: 1,
+    parseArgs: ([table]) => ({ table }),
+    run: (sql, { table }) =>
+      Promise.resolve(dbDescribe(sql as any, table)),
+  },
+  "meta tables describe-all": {
+    description: "Dump full database schema (all tables, columns, FKs) in one call",
+    inputSchema: dbDescribeAllInput,
+    positionalCount: 0,
+    parseArgs: () => ({}),
+    run: (sql) => Promise.resolve(dbDescribeAll(sql as any)),
+  },
+  // SQLite has no native enum type — enum values are in column definitions.
+  "meta sql query": {
+    description: "Run a read-only SQL query (SELECT/WITH only)",
+    inputSchema: dbQueryInput,
+    positionalCount: 1,
+    usage: 'sapporta meta sql query "<sql>"',
+    examples: ['sapporta meta sql query --json \'{"sql": "SELECT * FROM accounts", "limit": 50}\''],
+    parseArgs: ([sql], flags) => ({
+      sql,
+      limit: flags.limit ? parseInt(flags.limit, 10) : undefined,
+    }),
+    run: (sql, { sql: query, limit }) =>
+      Promise.resolve(dbQuery(sql as any, query, limit)),
+  },
+  "meta sql exec": {
+    description: "Execute a mutating SQL statement (INSERT, UPDATE, DELETE, DDL)",
+    inputSchema: dbExecInput,
+    mutating: true,
+    positionalCount: 1,
+    usage: 'sapporta meta sql exec "<sql>"',
+    parseArgs: ([sql], flags) => ({
+      sql,
+      dryRun: flags.dryRun === "true",
+    }),
+    run: (sql, { sql: query, dryRun }) =>
+      Promise.resolve(dbExec(sql as any, query, dryRun)),
+  },
+  "meta tables sample": {
+    description: "Show sample rows from a table",
+    inputSchema: dbSampleInput,
+    positionalCount: 1,
+    parseArgs: ([table], flags) => ({
+      table,
+      limit: flags.limit ? parseInt(flags.limit, 10) : undefined,
+      fields: flags.fields,
+    }),
+    run: (sql, { table, limit, fields }) =>
+      Promise.resolve(dbSample(sql as any, table, limit, fields?.split(","))),
+  },
+  "meta tables indexes": {
+    description: "Show indexes on a table",
+    inputSchema: dbIndexesInput,
+    positionalCount: 1,
+    parseArgs: ([table]) => ({ table }),
+    run: (sql, { table }) =>
+      Promise.resolve(dbIndexes(sql as any, table)),
+  },
+  "tables insert": {
+    description: "Insert one or more rows into a table",
+    inputSchema: rowsInsertInput,
+    mutating: true,
+    positionalCount: 1,
+    parseArgs: ([table], flags) => ({
+      table,
+      data: flags.data,
+    }),
+    run: (sql, input) => rowsInsert(sql, input.table, input.data, input.dryRun),
+  },
+  "tables insert-master-detail": {
+    description: "Insert master record + detail rows atomically",
+    inputSchema: rowsInsertMasterDetailInput,
+    mutating: true,
+    positionalCount: 1,
+    parseArgs: ([table], flags) => ({
+      table,
+      data: flags.data,
+    }),
+    run: (sql, input) => rowsInsertMasterDetail(sql, input),
+  },
+  "meta tables rename": {
+    description: "Rename a table (updates DDL, metadata, and FK references)",
+    inputSchema: tableRenameInput,
+    mutating: true,
+    positionalCount: 2,
+    parseArgs: ([table, newName]) => ({ table, newName }),
+    run: (sql, input) => tableRename(sql, input.table, input.newName, input.newLabel),
+  },
+};
+
+// ---------------------------------------------------------------------------
+// CLI helper — parse command and dispatch
+// ---------------------------------------------------------------------------
+
+export function parseCommand(args: string[]): { command: string; positional: string[]; flags: Record<string, string> } | null {
+  // Try to match multi-word commands (longest match first)
+  const commandKeys = Object.keys(AI_COMMANDS).sort((a, b) => b.length - a.length);
+  for (const cmd of commandKeys) {
+    const parts = cmd.split(" ");
+    if (parts.every((p, i) => args[i] === p)) {
+      const rest = args.slice(parts.length);
+      const positional: string[] = [];
+      const flags: Record<string, string> = {};
+
+      const cmdDef = AI_COMMANDS[cmd];
+      let i = 0;
+      while (i < rest.length && positional.length < cmdDef.positionalCount) {
+        if (rest[i].startsWith("--")) break;
+        positional.push(rest[i]);
+        i++;
+      }
+      while (i < rest.length) {
+        const arg = rest[i];
+        if (arg.startsWith("--")) {
+          const key = arg.replace(/^--/, "");
+          flags[key] = rest[i + 1] ?? "true";
+          i += 2;
+        } else {
+          i++;
+        }
+      }
+      return { command: cmd, positional, flags };
+    }
+  }
+  return null;
+}
+
+/**
+ * List of commands formatted for `sapporta describe`.
+ */
+export function describeCommands(): AiCommandMeta[] {
+  return Object.entries(AI_COMMANDS).map(([command, def]) => ({
+    command: `sapporta ${command}`,
+    description: def.description,
+    mutating: def.mutating,
+    inputSchema: def.inputSchema,
+    examples: def.examples,
+  }));
+}

package/src/cli/check.ts

@@ -0,0 +1,169 @@
+import { resolve, join } from "node:path";
+import { loadReports } from "../reports/loader.js";
+import { loadSchemas } from "../schema/loader.js";
+import { checkReportDefinition, checkReportSqlColumns, type CheckSql } from "../reports/check.js";
+import { checkSchemaDefinitions } from "../schema/check.js";
+import type { OperationResult } from "../introspect/types.js";
+import { parseFlags } from "./format.js";
+import { connectProject } from "../db/sqlite-connection.js";
+import { resolveProjectContext } from "./project-context.js";
+
+/**
+ * Validate project schemas and reports statically (and optionally with DB).
+ *
+ * Returns structured validation results. The router is responsible for
+ * setting the exit code based on result.meta.hasIssues.
+ *
+ * Note: This command still renders its own text output via meta.message
+ * because the checkmark/cross-mark format doesn't map to a simple table.
+ */
+export async function check(args: string[]): Promise<OperationResult> {
+  const flags = parseFlags(args);
+  const ctx = await resolveProjectContext(flags);
+
+  if (!ctx.dir) {
+    return {
+      ok: false,
+      error: "Cannot check an API-created project — it has no schema directory",
+      code: "VALIDATION_FAILED",
+    };
+  }
+  const projectDir = resolve(ctx.dir);
+  const schemaDir = join(projectDir, "schema");
+  const reportsDir = join(projectDir, "reports");
+
+  let hasIssues = false;
+  const allIssues: Record<string, unknown>[] = [];
+  let textOutput = "";
+
+  // -- Schema checks --
+  let schemas;
+  try {
+    schemas = await loadSchemas(schemaDir);
+  } catch (err: any) {
+    if (err.code !== "ENOENT") {
+      return {
+        ok: false,
+        error: `Error loading schemas from ${schemaDir}: ${err.message}`,
+        code: "INTERNAL",
+      };
+    }
+  }
+
+  if (schemas && schemas.tables.length > 0) {
+    const schemaIssues = checkSchemaDefinitions(schemas.tables);
+
+    textOutput += `\nChecking schemas: ${schemas.tables.length} table(s)\n`;
+    if (schemaIssues.length === 0) {
+      textOutput += "  \u2713 No issues found\n";
+    } else {
+      hasIssues = true;
+      for (const issue of schemaIssues) {
+        textOutput += `  \u2717 ${issue.table}.${issue.column}: ${issue.message}\n`;
+        allIssues.push({
+          type: "schema",
+          table: issue.table,
+          column: issue.column,
+          message: issue.message,
+        });
+      }
+    }
+  }
+
+  // -- Report checks --
+  let reports: Awaited<ReturnType<typeof loadReports>> | undefined = undefined;
+  try {
+    reports = await loadReports(reportsDir);
+  } catch (err: any) {
+    if (err.code !== "ENOENT") {
+      return {
+        ok: false,
+        error: `Error loading reports from ${reportsDir}: ${err.message}`,
+        code: "INTERNAL",
+      };
+    }
+  }
+
+  if (reports && reports.length > 0) {
+    const issuesByReport = new Map<string, { name: string; issues: { path: string; message: string }[] }>();
+    for (const report of reports) {
+      issuesByReport.set(report.name, {
+        name: report.name,
+        issues: checkReportDefinition(report),
+      });
+    }
+
+    // DB-aware checks: discover SQL column metadata via the query planner.
+    // Open a SQLite connection and adapt it to the CheckSql interface that
+    // checkReportSqlColumns expects.
+    let conn: ReturnType<typeof connectProject> | null = null;
+    try {
+      conn = connectProject(ctx.databasePath);
+    } catch {
+      // Database may not exist yet (e.g. `check` run before first serve)
+    }
+
+    if (conn) {
+      try {
+        const checkSql: CheckSql = {
+          async unsafe(query: string, params?: unknown[]) {
+            const stmt = conn!.sqlite.prepare(query);
+            const columns = stmt.columns().map((c: any) => ({ name: c.name }));
+            const rows = params && params.length > 0 ? stmt.all(...params) : stmt.all();
+            (rows as any).columns = columns;
+            return rows as any;
+          },
+        };
+        for (const report of reports) {
+          const dbIssues = await checkReportSqlColumns(checkSql, report);
+          const entry = issuesByReport.get(report.name)!;
+          entry.issues.push(...dbIssues);
+        }
+      } finally {
+        conn.sqlite.close();
+      }
+    }
+
+    let reportsWithIssues = 0;
+
+    for (const report of reports) {
+      textOutput += `\nChecking report: ${report.name}\n`;
+      const { issues } = issuesByReport.get(report.name)!;
+
+      if (issues.length === 0) {
+        textOutput += "  \u2713 No issues found\n";
+      } else {
+        reportsWithIssues++;
+        for (const issue of issues) {
+          textOutput += `  \u2717 ${issue.path}: ${issue.message}\n`;
+          allIssues.push({
+            type: "report",
+            report: report.name,
+            path: issue.path,
+            message: issue.message,
+          });
+        }
+      }
+    }
+
+    textOutput += `\n${reports.length} report(s) checked, ${reportsWithIssues} with issues\n`;
+
+    if (reportsWithIssues > 0) {
+      hasIssues = true;
+    }
+  }
+
+  if (!schemas?.tables.length && !reports?.length) {
+    textOutput += `No schemas or reports found in ${projectDir}\n`;
+  }
+
+  return {
+    ok: true,
+    data: allIssues,
+    meta: {
+      message: textOutput.trimEnd(),
+      hasIssues,
+      tableOutputHandled: true,
+    },
+  };
+}