@sapporta/server 0.0.1

package/src/cli/cli-utils.test.ts

@@ -0,0 +1,313 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import Database from "better-sqlite3";
+import { parseFlags, formatTable, truncateValues } from "./format.js";
+import { requireSelect, rejectDangerousSQL, validateTableName, validateColumnNames, rejectControlChars } from "../introspect/sql-safety.js";
+import { buildInsertQuery, assertTableExists, getTableColumns, validatePayloadColumns } from "../introspect/db-helpers.js";
+
+describe("parseFlags", () => {
+  it("parses --key value pairs", () => {
+    const result = parseFlags(["--table", "accounts", "--limit", "10"]);
+    expect(result.table).toBe("accounts");
+    expect(result.limit).toBe("10");
+  });
+
+  it("parses boolean flags (no value)", () => {
+    const result = parseFlags(["--verbose", "--table", "accounts"]);
+    expect(result.verbose).toBe("true");
+    expect(result.table).toBe("accounts");
+  });
+
+  it("collects positional args under _", () => {
+    const result = parseFlags(["accounts", "--limit", "5"]);
+    expect(result._).toEqual(["accounts"]);
+    expect(result.limit).toBe("5");
+  });
+
+  it("returns empty for no args", () => {
+    const result = parseFlags([]);
+    expect(result._).toEqual([]);
+  });
+});
+
+describe("requireSelect", () => {
+  it("allows SELECT queries", () => {
+    expect(() => requireSelect("SELECT * FROM accounts")).not.toThrow();
+  });
+
+  it("allows WITH (CTE) queries", () => {
+    expect(() =>
+      requireSelect("WITH cte AS (SELECT 1) SELECT * FROM cte"),
+    ).not.toThrow();
+  });
+
+  it("allows case-insensitive", () => {
+    expect(() => requireSelect("select * from accounts")).not.toThrow();
+  });
+
+  it("rejects INSERT", () => {
+    expect(() =>
+      requireSelect("INSERT INTO accounts (name) VALUES ('x')"),
+    ).toThrow("Only SELECT");
+  });
+
+  it("rejects UPDATE", () => {
+    expect(() =>
+      requireSelect("UPDATE accounts SET name = 'x'"),
+    ).toThrow("Only SELECT");
+  });
+
+  it("rejects DELETE", () => {
+    expect(() => requireSelect("DELETE FROM accounts")).toThrow("Only SELECT");
+  });
+});
+
+describe("rejectDangerousSQL", () => {
+  it("allows normal SELECT", () => {
+    expect(() => rejectDangerousSQL("SELECT * FROM accounts")).not.toThrow();
+  });
+
+  it("allows normal INSERT", () => {
+    expect(() =>
+      rejectDangerousSQL("INSERT INTO accounts (name) VALUES ('x')"),
+    ).not.toThrow();
+  });
+
+  it("rejects DROP DATABASE", () => {
+    expect(() => rejectDangerousSQL("DROP DATABASE sapporta")).toThrow(
+      "DROP DATABASE",
+    );
+  });
+
+  it("rejects TRUNCATE", () => {
+    expect(() => rejectDangerousSQL("TRUNCATE accounts")).toThrow("TRUNCATE");
+  });
+
+  it("rejects DROP SCHEMA", () => {
+    expect(() => rejectDangerousSQL("DROP SCHEMA public CASCADE")).toThrow(
+      "DROP SCHEMA",
+    );
+  });
+});
+
+describe("validateTableName", () => {
+  it("accepts valid table names", () => {
+    expect(() => validateTableName("accounts")).not.toThrow();
+    expect(() => validateTableName("_private")).not.toThrow();
+    expect(() => validateTableName("order_items")).not.toThrow();
+  });
+
+  it("rejects names with special characters", () => {
+    expect(() => validateTableName("users; DROP TABLE")).toThrow("Invalid table name");
+    expect(() => validateTableName("my-table")).toThrow("Invalid table name");
+    expect(() => validateTableName("my table")).toThrow("Invalid table name");
+  });
+
+  it("rejects names starting with numbers", () => {
+    expect(() => validateTableName("1table")).toThrow("Invalid table name");
+  });
+
+  it("rejects empty string", () => {
+    expect(() => validateTableName("")).toThrow("Invalid table name");
+  });
+});
+
+describe("validateColumnNames", () => {
+  it("accepts valid column names", () => {
+    expect(() => validateColumnNames(["id", "first_name", "AccountType"])).not.toThrow();
+  });
+
+  it("rejects column names with semicolons", () => {
+    expect(() => validateColumnNames(["id; DROP TABLE users"])).toThrow("Invalid column name");
+  });
+
+  it("rejects column names with special characters", () => {
+    expect(() => validateColumnNames(["name?"])).toThrow("Invalid column name");
+    expect(() => validateColumnNames(["col'name"])).toThrow("Invalid column name");
+    expect(() => validateColumnNames(["col name"])).toThrow("Invalid column name");
+  });
+
+  it("rejects column names starting with numbers", () => {
+    expect(() => validateColumnNames(["1column"])).toThrow("Invalid column name");
+  });
+
+  it("accepts empty array", () => {
+    expect(() => validateColumnNames([])).not.toThrow();
+  });
+});
+
+describe("buildInsertQuery", () => {
+  it("builds a parameterized INSERT with RETURNING *", () => {
+    const { query, values } = buildInsertQuery("accounts", { name: "Cash", type: "asset" });
+    expect(query).toBe('INSERT INTO "accounts" ("name", "type") VALUES (?, ?) RETURNING *');
+    expect(values).toEqual(["Cash", "asset"]);
+  });
+
+  it("double-quotes column names to handle reserved words", () => {
+    const { query } = buildInsertQuery("items", { order: 1, group: "a" });
+    expect(query).toContain('"order"');
+    expect(query).toContain('"group"');
+  });
+
+  it("handles single-column insert", () => {
+    const { query, values } = buildInsertQuery("tags", { label: "urgent" });
+    expect(query).toBe('INSERT INTO "tags" ("label") VALUES (?) RETURNING *');
+    expect(values).toEqual(["urgent"]);
+  });
+});
+
+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");
+  });
+});
+
+describe("truncateValues", () => {
+  it("truncates long strings", () => {
+    const rows = [{ id: 1, text: "a".repeat(300) }];
+    const result = truncateValues(rows, 200);
+    expect((result[0].text as string).length).toBe(203); // 200 + "..."
+    expect((result[0].text as string).endsWith("...")).toBe(true);
+  });
+
+  it("leaves short strings untouched", () => {
+    const rows = [{ id: 1, text: "hello" }];
+    const result = truncateValues(rows, 200);
+    expect(result[0].text).toBe("hello");
+  });
+
+  it("leaves non-string values untouched", () => {
+    const rows = [{ id: 1, amount: 99999 }];
+    const result = truncateValues(rows);
+    expect(result[0].amount).toBe(99999);
+  });
+
+  it("does not mutate original rows", () => {
+    const rows = [{ id: 1, text: "a".repeat(300) }];
+    truncateValues(rows, 200);
+    expect((rows[0].text as string).length).toBe(300);
+  });
+});
+
+describe("formatTable", () => {
+  it("formats rows as aligned table", () => {
+    const rows = [
+      { id: 1, name: "Cash" },
+      { id: 2, name: "Revenue" },
+    ];
+    const output = formatTable(rows);
+    expect(output).toContain("id");
+    expect(output).toContain("name");
+    expect(output).toContain("Cash");
+    expect(output).toContain("Revenue");
+    // Check alignment (header + separator + 2 rows = 4 lines)
+    expect(output.split("\n")).toHaveLength(4);
+  });
+
+  it("returns (empty) for no rows", () => {
+    expect(formatTable([])).toBe("(empty)");
+  });
+
+  it("shows NULL for null/undefined values", () => {
+    const rows = [{ id: 1, name: null }];
+    const output = formatTable(rows);
+    expect(output).toContain("NULL");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// SQLite-based validation primitives
+// ---------------------------------------------------------------------------
+// These tests use a real in-memory SQLite database. The db-helpers functions
+// are now synchronous and operate on better-sqlite3 directly.
+
+describe("assertTableExists", () => {
+  let sqlite: Database.Database;
+
+  beforeEach(() => {
+    sqlite = new Database(":memory:");
+    sqlite.pragma("foreign_keys = ON");
+    sqlite.exec(`CREATE TABLE accounts (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, type TEXT)`);
+  });
+
+  afterEach(() => {
+    sqlite.close();
+  });
+
+  it("passes when table exists", () => {
+    expect(() => assertTableExists(sqlite, "accounts")).not.toThrow();
+  });
+
+  it("throws TABLE_NOT_FOUND when table does not exist", () => {
+    expect(() => assertTableExists(sqlite, "missing")).toThrow("not found");
+  });
+});
+
+describe("getTableColumns", () => {
+  let sqlite: Database.Database;
+
+  beforeEach(() => {
+    sqlite = new Database(":memory:");
+    sqlite.pragma("foreign_keys = ON");
+    sqlite.exec(`CREATE TABLE accounts (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, type TEXT)`);
+  });
+
+  afterEach(() => {
+    sqlite.close();
+  });
+
+  it("returns column names as a Set", () => {
+    const cols = getTableColumns(sqlite, "accounts");
+    expect(cols).toEqual(new Set(["id", "name", "type"]));
+  });
+
+  it("returns empty Set for unknown table", () => {
+    const cols = getTableColumns(sqlite, "missing");
+    expect(cols).toEqual(new Set());
+  });
+});
+
+describe("validatePayloadColumns", () => {
+  let sqlite: Database.Database;
+
+  beforeEach(() => {
+    sqlite = new Database(":memory:");
+    sqlite.pragma("foreign_keys = ON");
+    sqlite.exec(`CREATE TABLE accounts (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, type TEXT)`);
+  });
+
+  afterEach(() => {
+    sqlite.close();
+  });
+
+  it("passes when all columns exist", () => {
+    expect(() => validatePayloadColumns(sqlite, "accounts", ["name", "type"])).not.toThrow();
+  });
+
+  it("throws for unknown columns", () => {
+    expect(() => validatePayloadColumns(sqlite, "accounts", ["name", "bogus"])).toThrow("Unknown column");
+  });
+
+  it("throws TABLE_NOT_FOUND if table missing", () => {
+    expect(() => validatePayloadColumns(sqlite, "missing", ["x"])).toThrow("not found");
+  });
+});

package/src/cli/describe.test.ts

@@ -0,0 +1,151 @@
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import { describeAll, describeOne } from "./describe.js";
+import { ROUTES } from "./routes.js";
+import { AI_COMMANDS } from "./ai-commands.js";
+import type { CliRoute } from "./routes.js";
+
+// Minimal route table for focused tests
+const testRoutes: CliRoute[] = [
+  {
+    pattern: ["meta", "sql", "query"],
+    description: "Run a read-only SQL query",
+    method: "POST",
+    path: "/meta/sql/query",
+    params: [],
+    inputSchema: z.object({
+      sql: z.string().describe("The SQL query"),
+      limit: z.number().optional().describe("Max rows"),
+    }),
+    extractData: (res) => res.data ?? [],
+  },
+  {
+    pattern: ["meta", "tables"],
+    description: "List all tables",
+    method: "GET",
+    path: "/meta/tables",
+    params: [],
+    extractData: (res) => res.tables ?? [],
+  },
+  {
+    pattern: ["meta", "schema", "sync"],
+    description: "Sync schema files to database",
+    method: "POST",
+    path: "/meta/schema/sync",
+    params: [],
+    mutating: true,
+    extractData: (res) => [res],
+  },
+];
+
+describe("describeAll", () => {
+  it("returns all routes", () => {
+    const result = describeAll(testRoutes);
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.data).toHaveLength(3);
+    const names = result.data.map((d) => d.command);
+    expect(names).toContain("meta sql query");
+    expect(names).toContain("meta tables");
+    expect(names).toContain("meta schema sync");
+  });
+
+  it("sorts commands alphabetically", () => {
+    const result = describeAll(testRoutes);
+    if (!result.ok) return;
+    const names = result.data.map((d) => d.command);
+    expect(names).toEqual([...names].sort());
+  });
+
+  it("includes HTTP method and path", () => {
+    const result = describeAll(testRoutes);
+    if (!result.ok) return;
+    const sqlCmd = result.data.find((d) => d.command === "meta sql query");
+    expect(sqlCmd?.method).toBe("POST");
+    expect(sqlCmd?.path).toBe("/meta/sql/query");
+  });
+});
+
+describe("describeOne", () => {
+  it("returns details for a route", () => {
+    const result = describeOne("meta sql query", testRoutes);
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.data).toHaveLength(1);
+    const cmd = result.data[0];
+    expect(cmd.command).toBe("meta sql query");
+    expect(cmd.method).toBe("POST");
+    expect(cmd.path).toBe("/meta/sql/query");
+    expect(cmd.inputSchema).toBeDefined();
+    const schema = cmd.inputSchema as any;
+    expect(schema.type).toBe("object");
+    expect(schema.properties).toHaveProperty("sql");
+    expect(schema.properties).toHaveProperty("limit");
+  });
+
+  it("returns mutating flag", () => {
+    const result = describeOne("meta schema sync", testRoutes);
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.data[0].mutating).toBe(true);
+  });
+
+  it("returns error for unknown command", () => {
+    const result = describeOne("nonexistent", testRoutes);
+    expect(result.ok).toBe(false);
+  });
+});
+
+describe("ROUTES integrity", () => {
+  it("every route has a non-empty description", () => {
+    for (const route of ROUTES) {
+      expect(route.description, `${route.pattern.join(" ")} should have a description`).toBeTruthy();
+    }
+  });
+
+  it("every route has a valid method", () => {
+    const validMethods = new Set(["GET", "POST", "PUT", "PATCH", "DELETE"]);
+    for (const route of ROUTES) {
+      expect(validMethods.has(route.method), `${route.pattern.join(" ")} has invalid method ${route.method}`).toBe(true);
+    }
+  });
+
+  it("every route has a path starting with /", () => {
+    for (const route of ROUTES) {
+      expect(route.path.startsWith("/"), `${route.pattern.join(" ")} path should start with /`).toBe(true);
+    }
+  });
+
+  it("route params match path placeholders", () => {
+    for (const route of ROUTES) {
+      const pathParams = (route.path.match(/:\w+/g) ?? []).map((p) => p.slice(1));
+      expect(route.params.sort(), `${route.pattern.join(" ")} params should match path`).toEqual(pathParams.sort());
+    }
+  });
+
+  it("routes with inputSchema produce valid JSON Schema", () => {
+    for (const route of ROUTES) {
+      if (route.inputSchema) {
+        const jsonSchema = z.toJSONSchema(route.inputSchema);
+        expect(jsonSchema, `${route.pattern.join(" ")} should produce valid JSON Schema`).toHaveProperty("type");
+      }
+    }
+  });
+});
+
+// Keep AI_COMMANDS integrity tests — the old registry still exists for server-side use
+describe("AI_COMMANDS registry integrity", () => {
+  it("every command has a non-empty description", () => {
+    for (const [name, cmd] of Object.entries(AI_COMMANDS)) {
+      expect(cmd.description, `${name} should have a description`).toBeTruthy();
+    }
+  });
+
+  it("every command has a valid inputSchema", () => {
+    for (const [name, cmd] of Object.entries(AI_COMMANDS)) {
+      expect(cmd.inputSchema, `${name} should have an inputSchema`).toBeDefined();
+      const jsonSchema = z.toJSONSchema(cmd.inputSchema);
+      expect(jsonSchema, `${name} should produce valid JSON Schema`).toHaveProperty("type");
+    }
+  });
+});

package/src/cli/describe.ts

@@ -0,0 +1,88 @@
+import { z } from "zod";
+import type { OperationResult } from "../introspect/types.js";
+import type { CliRoute } from "./routes.js";
+
+/** Format a route pattern for user-facing display: ":name" → "<name>" */
+function formatCommand(route: CliRoute): string {
+  return route.pattern
+    .map((t) => (t.startsWith(":") ? `<${t.slice(1)}>` : t))
+    .join(" ");
+}
+
+/** Extract only the fixed (non-param) segments as a match key. */
+function fixedKey(route: CliRoute): string {
+  return route.pattern.filter((t) => !t.startsWith(":")).join(" ");
+}
+
+/**
+ * List all commands with summary info (from route table).
+ */
+export function describeAll(routes: CliRoute[]): OperationResult {
+  const commands = routes.map((r) => ({
+    command: formatCommand(r),
+    description: r.description,
+    method: r.method,
+    path: r.path,
+    mutating: r.mutating ?? false,
+  }));
+
+  commands.sort((a, b) => a.command.localeCompare(b.command));
+
+  return {
+    ok: true,
+    data: commands as Record<string, unknown>[],
+    meta: { tableOutputHandled: true, message: formatCommandList(commands) },
+  };
+}
+
+/**
+ * Describe a single command by name (from route table).
+ * Matches against fixed segments (e.g. "tables create" matches
+ * pattern ["tables", "create", ":table"]).
+ */
+export function describeOne(name: string, routes: CliRoute[]): OperationResult {
+  const route = routes.find((r) => fixedKey(r) === name);
+  if (!route) {
+    return { ok: false, error: `Unknown command: ${name}`, code: "MISSING_ARGUMENT" };
+  }
+
+  const inputSchema = route.inputSchema ? z.toJSONSchema(route.inputSchema) : null;
+  const data = [{
+    command: formatCommand(route),
+    description: route.description,
+    method: route.method,
+    path: route.path,
+    mutating: route.mutating ?? false,
+    inputSchema,
+  }];
+
+  return {
+    ok: true,
+    data,
+    meta: {
+      tableOutputHandled: true,
+      message: formatRouteDetail(route, inputSchema),
+    },
+  };
+}
+
+function formatCommandList(commands: { command: string; description: string; method: string; path: string; mutating: boolean }[]): string {
+  const maxCmd = Math.max(...commands.map((c) => c.command.length));
+  const maxMethod = Math.max(...commands.map((c) => c.method.length));
+  return commands
+    .map((c) => `  ${c.command.padEnd(maxCmd)}  ${c.method.padEnd(maxMethod)}  ${c.path.padEnd(30)}  ${c.description}`)
+    .join("\n");
+}
+
+function formatRouteDetail(route: CliRoute, inputSchema: unknown): string {
+  const lines: string[] = [
+    `Command:     ${formatCommand(route)}`,
+    `Description: ${route.description}`,
+    `HTTP:        ${route.method} ${route.path}`,
+    `Mutating:    ${route.mutating ?? false}`,
+  ];
+  if (inputSchema) {
+    lines.push(``, `Input Schema:`, JSON.stringify(inputSchema, null, 2));
+  }
+  return lines.join("\n");
+}