@sapporta/server 0.0.1

package/src/cli/emit-result.test.ts

@@ -0,0 +1,160 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { resolveOutputFormat, emitResult } from "./format.js";
+
+// ---------------------------------------------------------------------------
+// resolveOutputFormat tests
+// ---------------------------------------------------------------------------
+// Resolution priority: --output flag > SAPPORTA_OUTPUT_FORMAT env > TTY detection.
+// This order matters because agents running in pipelines need predictable
+// format selection without needing to pass --output on every call.
+
+describe("resolveOutputFormat", () => {
+  const originalEnv = process.env.SAPPORTA_OUTPUT_FORMAT;
+  const originalIsTTY = process.stdout.isTTY;
+
+  afterEach(() => {
+    // Restore environment to prevent test pollution
+    if (originalEnv === undefined) {
+      delete process.env.SAPPORTA_OUTPUT_FORMAT;
+    } else {
+      process.env.SAPPORTA_OUTPUT_FORMAT = originalEnv;
+    }
+    Object.defineProperty(process.stdout, "isTTY", { value: originalIsTTY, writable: true });
+  });
+
+  it("returns json when --output json is passed", () => {
+    expect(resolveOutputFormat({ output: "json" })).toBe("json");
+  });
+
+  it("returns table when --output table is passed", () => {
+    expect(resolveOutputFormat({ output: "table" })).toBe("table");
+  });
+
+  it("uses SAPPORTA_OUTPUT_FORMAT env when no flag", () => {
+    process.env.SAPPORTA_OUTPUT_FORMAT = "json";
+    expect(resolveOutputFormat({})).toBe("json");
+  });
+
+  it("--output flag takes precedence over env var", () => {
+    process.env.SAPPORTA_OUTPUT_FORMAT = "json";
+    expect(resolveOutputFormat({ output: "table" })).toBe("table");
+  });
+
+  it("defaults to json when stdout is not a TTY (agent/pipe mode)", () => {
+    delete process.env.SAPPORTA_OUTPUT_FORMAT;
+    Object.defineProperty(process.stdout, "isTTY", { value: undefined, writable: true });
+    expect(resolveOutputFormat({})).toBe("json");
+  });
+
+  it("defaults to table when stdout is a TTY (interactive mode)", () => {
+    delete process.env.SAPPORTA_OUTPUT_FORMAT;
+    Object.defineProperty(process.stdout, "isTTY", { value: true, writable: true });
+    expect(resolveOutputFormat({})).toBe("table");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// emitResult tests
+// ---------------------------------------------------------------------------
+// emitResult is the SOLE output point — commands never call console.log
+// directly. These tests verify both JSON and table mode rendering.
+
+describe("emitResult", () => {
+  let logSpy: ReturnType<typeof vi.spyOn>;
+  let errorSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    logSpy.mockRestore();
+    errorSpy.mockRestore();
+  });
+
+  // -- JSON mode --
+
+  it("JSON mode: emits success result as single JSON line", () => {
+    emitResult({ ok: true, data: [{ id: 1 }] }, "json");
+    expect(logSpy).toHaveBeenCalledOnce();
+    const parsed = JSON.parse(logSpy.mock.calls[0][0] as string);
+    expect(parsed.ok).toBe(true);
+    expect(parsed.data).toEqual([{ id: 1 }]);
+  });
+
+  it("JSON mode: emits error result as single JSON line", () => {
+    emitResult({ ok: false, error: "not found", code: "TABLE_NOT_FOUND" }, "json");
+    expect(logSpy).toHaveBeenCalledOnce();
+    const parsed = JSON.parse(logSpy.mock.calls[0][0] as string);
+    expect(parsed.ok).toBe(false);
+    expect(parsed.error).toBe("not found");
+    expect(parsed.code).toBe("TABLE_NOT_FOUND");
+  });
+
+  // -- Table mode --
+
+  it("table mode: prints error to stderr", () => {
+    emitResult({ ok: false, error: "bad input", code: "INVALID_JSON" }, "table");
+    expect(errorSpy).toHaveBeenCalledWith("Error: bad input");
+    expect(logSpy).not.toHaveBeenCalled();
+  });
+
+  it("table mode: prints message from meta", () => {
+    emitResult({ ok: true, data: [], meta: { message: "Done!" } }, "table");
+    expect(logSpy).toHaveBeenCalledWith("Done!");
+  });
+
+  it("table mode: renders data rows as a formatted table", () => {
+    emitResult(
+      { ok: true, data: [{ id: 1, name: "Cash" }] },
+      "table",
+    );
+    // formatTable produces header + separator + data rows
+    const output = logSpy.mock.calls[0][0] as string;
+    expect(output).toContain("id");
+    expect(output).toContain("name");
+    expect(output).toContain("Cash");
+  });
+
+  it("table mode: skips formatTable when tableOutputHandled is true", () => {
+    // Commands like report-execute set tableOutputHandled to indicate they've
+    // already formatted the output into the message/additionalOutput fields.
+    emitResult(
+      {
+        ok: true,
+        data: [{ id: 1 }],
+        meta: { message: "Custom output", tableOutputHandled: true },
+      },
+      "table",
+    );
+    // Only the message should be logged, not the data table
+    expect(logSpy).toHaveBeenCalledTimes(1);
+    expect(logSpy).toHaveBeenCalledWith("Custom output");
+  });
+
+  it("table mode: emits additionalOutput after the main table", () => {
+    emitResult(
+      {
+        ok: true,
+        data: [],
+        meta: { message: "Header", additionalOutput: "Extra section" },
+      },
+      "table",
+    );
+    expect(logSpy).toHaveBeenCalledWith("Header");
+    expect(logSpy).toHaveBeenCalledWith("Extra section");
+  });
+
+  it("table mode: emits errorText to stderr", () => {
+    emitResult(
+      {
+        ok: true,
+        data: [],
+        meta: { errorText: "Warning: something odd" },
+      },
+      "table",
+    );
+    expect(errorSpy).toHaveBeenCalledWith("Warning: something odd");
+  });
+});

package/src/cli/format.ts

@@ -0,0 +1,150 @@
+import type { OperationResult } from "../introspect/types.js";
+
+// ---------------------------------------------------------------------------
+// CLI output formatting and flag parsing.
+//
+// Everything in this file is CLI-specific presentation logic — it converts
+// structured OperationResults into human-readable terminal output or JSON.
+// ---------------------------------------------------------------------------
+
+export type OutputFormat = "table" | "json";
+
+/**
+ * Resolve the output format from flags, environment, and TTY detection.
+ * Priority: --output flag > SAPPORTA_OUTPUT_FORMAT env > TTY detection.
+ *
+ * Non-TTY stdout (e.g. piped to another program or used by an AI agent)
+ * defaults to JSON so agents get structured data without needing to pass flags.
+ */
+export function resolveOutputFormat(
+  flags: Record<string, string>,
+): OutputFormat {
+  const explicit =
+    flags.output ?? process.env.SAPPORTA_OUTPUT_FORMAT;
+  if (explicit === "json") return "json";
+  if (explicit === "table") return "table";
+  // Auto-detect: non-TTY defaults to JSON for agent consumption
+  if (!process.stdout.isTTY) return "json";
+  return "table";
+}
+
+/**
+ * Format and emit an OperationResult to stdout.
+ *
+ * In table mode: reproduces the human-readable output the CLI has always produced.
+ * In JSON mode: emits the full result envelope as a single JSON line.
+ *
+ * This is the ONLY place in the codebase that should call console.log for
+ * command output. Commands themselves must never print directly.
+ */
+export function emitResult(result: OperationResult, format: OutputFormat): void {
+  if (format === "json") {
+    console.log(JSON.stringify(result));
+    return;
+  }
+
+  // Table format: reproduce legacy behavior
+  if (!result.ok) {
+    console.error(`Error: ${result.error}`);
+    return;
+  }
+
+  if (result.meta?.message) {
+    console.log(result.meta.message);
+  }
+
+  // Commands that produce complex multi-section output (e.g. report-execute,
+  // report-describe) set meta.tableOutputHandled = true to signal that the
+  // message and/or additionalOutput already contain the full rendered output.
+  // In that case, skip the default formatTable call to avoid duplicate output.
+  if (!result.meta?.tableOutputHandled && result.data.length > 0) {
+    console.log(formatTable(result.data));
+  }
+
+  if (result.meta?.additionalOutput) {
+    console.log(result.meta.additionalOutput);
+  }
+
+  // Emit error text to stderr (used by report-execute for warnings)
+  if (result.meta?.errorText) {
+    console.error(result.meta.errorText);
+  }
+}
+
+/**
+ * Parse --flag value pairs from argv.
+ * Returns a map of flag → string value.
+ * Positional args (no -- prefix) are collected under "_".
+ *
+ * All values are coerced to strings for a uniform interface —
+ * callers can safely pass values as query params or compare against
+ * string literals without worrying about type inference.
+ */
+export function parseFlags(argv: string[]): Record<string, any> {
+  const result: Record<string, any> = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--") break;
+    if (arg.startsWith("--")) {
+      const eqIndex = arg.indexOf("=", 2);
+      if (eqIndex !== -1) {
+        // --key=value form
+        result[arg.slice(2, eqIndex)] = arg.slice(eqIndex + 1);
+      } else {
+        const key = arg.slice(2);
+        if (i + 1 < argv.length && !argv[i + 1].startsWith("--")) {
+          result[key] = String(argv[i + 1]);
+          i++;
+        } else {
+          result[key] = "true";
+        }
+      }
+    } else {
+      result._.push(arg);
+    }
+  }
+  return result;
+}
+
+/**
+ * Format rows as a readable table for terminal output.
+ */
+export function formatTable(rows: Record<string, unknown>[]): string {
+  if (rows.length === 0) return "(empty)";
+
+  const columns = Object.keys(rows[0]);
+  const widths = columns.map((col) => {
+    const values = rows.map((row) => String(row[col] ?? "NULL"));
+    return Math.max(col.length, ...values.map((v) => v.length));
+  });
+
+  const header = columns.map((col, i) => col.padEnd(widths[i])).join("  ");
+  const separator = widths.map((w) => "-".repeat(w)).join("  ");
+  const body = rows.map((row) =>
+    columns.map((col, i) => String(row[col] ?? "NULL").padEnd(widths[i])).join("  "),
+  );
+
+  return [header, separator, ...body].join("\n");
+}
+
+/**
+ * Truncate long string values in result rows to prevent context window overflow.
+ * Only affects string values longer than maxLen; other types are left as-is.
+ * Returns new row objects (does not mutate the originals).
+ */
+export function truncateValues(
+  rows: Record<string, unknown>[],
+  maxLen: number = 200,
+): Record<string, unknown>[] {
+  return rows.map((row) => {
+    const truncated: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(row)) {
+      if (typeof value === "string" && value.length > maxLen) {
+        truncated[key] = value.slice(0, maxLen) + "...";
+      } else {
+        truncated[key] = value;
+      }
+    }
+    return truncated;
+  });
+}

package/src/cli/http-client.ts

@@ -0,0 +1,55 @@
+/**
+ * Minimal HTTP client for the CLI → API bridge.
+ *
+ * All CLI commands that touch data go through this function.
+ * The server runs at SAPPORTA_API_URL (default http://localhost:3000).
+ */
+
+export interface HttpResult {
+  status: number;
+  data: any;
+}
+
+export async function httpRequest(
+  baseUrl: string,
+  method: string,
+  path: string,
+  opts?: {
+    body?: unknown;
+    queryParams?: Record<string, string>;
+    token?: string;
+  },
+): Promise<HttpResult> {
+  // Strip leading "/" so new URL() treats the path as relative to baseUrl's path.
+  // With a leading slash, new URL("/meta/tables", "http://host/p/playground/")
+  // discards the base path → "http://host/meta/tables" (broken).
+  const relativePath = path.startsWith("/") ? path.slice(1) : path;
+  const url = new URL(relativePath, baseUrl.endsWith("/") ? baseUrl : baseUrl + "/");
+  if (opts?.queryParams) {
+    for (const [k, v] of Object.entries(opts.queryParams)) {
+      if (v !== undefined && v !== "") url.searchParams.set(k, v);
+    }
+  }
+
+  let res: Response;
+  try {
+    res = await fetch(url, {
+      method,
+      headers: {
+        "Content-Type": "application/json",
+        ...(opts?.token ? { Authorization: `Bearer ${opts.token}` } : {}),
+      },
+      ...(opts?.body !== undefined ? { body: JSON.stringify(opts.body) } : {}),
+    });
+  } catch (err: any) {
+    if (err.code === "ECONNREFUSED" || err.cause?.code === "ECONNREFUSED") {
+      throw new Error(
+        `Cannot connect to Sapporta server at ${baseUrl}. Is the server running?`,
+      );
+    }
+    throw err;
+  }
+
+  const data = await res.json();
+  return { status: res.status, data };
+}

package/src/cli/index.ts

@@ -0,0 +1,162 @@
+import { Command } from "commander";
+import { check } from "./check.js";
+import { init } from "./init.js";
+import { serveSingle } from "./serve-single.js";
+import { describeAll, describeOne } from "./describe.js";
+import { ROUTES, registerRoutes } from "./routes.js";
+import { httpRequest } from "./http-client.js";
+import { OperationError, ErrorCode } from "../introspect/types.js";
+import { buildRequest, renderResult } from "./request.js";
+import { parseFlags, emitResult, resolveOutputFormat, type OutputFormat } from "./format.js";
+
+// Re-export for programmatic access
+export { ROUTES } from "./routes.js";
+export type { CliRoute } from "./routes.js";
+export { buildRequest, renderResult } from "./request.js";
+export type { RequestSpec } from "./request.js";
+
+/**
+ * Emit an error and exit. In table mode, prints to stderr like before.
+ * In JSON mode, emits a structured error envelope to stdout.
+ */
+function handleError(err: any, format: OutputFormat): never {
+  const code = err instanceof OperationError ? err.code : ErrorCode.INTERNAL;
+  const result = { ok: false as const, error: err.message, code };
+  emitResult(result, format);
+  process.exit(err instanceof OperationError ? 1 : 2);
+}
+
+// ---------------------------------------------------------------------------
+// Base URL resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the API base URL from flags or environment.
+ */
+function resolveBaseUrl(flags: Record<string, string>): string {
+  const apiUrl = flags["api-url"] ?? process.env.SAPPORTA_API_URL ?? "http://localhost:3000";
+  return apiUrl.replace(/\/+$/, "");
+}
+
+// ---------------------------------------------------------------------------
+// API command runner (thin orchestration)
+// ---------------------------------------------------------------------------
+
+async function runApiCommand(
+  route: Parameters<typeof buildRequest>[0],
+  params: Record<string, string>,
+  allFlags: Record<string, any>,
+): Promise<void> {
+  const format = resolveOutputFormat(allFlags);
+
+  const baseUrl = resolveBaseUrl(allFlags);
+  const token = allFlags.token ?? process.env.SAPPORTA_API_TOKEN;
+
+  const req = buildRequest(route, params, allFlags);
+
+  const result = await httpRequest(baseUrl, req.method, req.urlPath, {
+    body: req.body,
+    queryParams: req.queryParams,
+    token,
+  });
+
+  const exitCode = renderResult(route, params, result, format);
+  if (exitCode !== 0) process.exit(exitCode);
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const rawArgs = process.argv.slice(2);
+  const firstArg = rawArgs[0];
+
+  // ── Local commands (no server needed) ────────────────────────────────
+  // Intercepted before Commander runs — these handle their own flag parsing.
+
+  if (firstArg === "check") {
+    const format: OutputFormat = "table";
+    try {
+      const result = await check(rawArgs.slice(1));
+      emitResult(result, format);
+      if (result.ok && result.meta?.hasIssues) process.exit(1);
+    } catch (err: any) {
+      handleError(err, format);
+    }
+    return;
+  }
+
+  if (firstArg === "init") {
+    const format: OutputFormat = "table";
+    try {
+      const result = await init(rawArgs.slice(1));
+      emitResult(result, format);
+    } catch (err: any) {
+      handleError(err, format);
+    }
+    return;
+  }
+
+  if (firstArg === "serve") {
+    try {
+      await serveSingle(rawArgs.slice(1));
+    } catch (err: any) {
+      handleError(err, "table");
+    }
+    return;
+  }
+
+  if (firstArg === "describe") {
+    const rest = rawArgs.slice(1);
+    const flags = parseFlags(rest);
+    const format = resolveOutputFormat(flags);
+    if (!rawArgs[1] || rawArgs[1].startsWith("--")) {
+      const result = describeAll(ROUTES);
+      emitResult(result, format);
+    } else {
+      const commandName = rest.filter((s) => !s.startsWith("--")).join(" ");
+      const result = describeOne(commandName, ROUTES);
+      emitResult(result, format);
+    }
+    return;
+  }
+
+  // ── Commander program for API commands ──────────────────────────────
+
+  const program = new Command("sapporta")
+    .version("0.1.0")
+    // Declare global options so Commander doesn't confuse their values
+    // with subcommand names
+    .option("--output <format>", "Output format: table (default) or json")
+    .option("--json <data>", "Pass input as JSON object")
+    .option("--api-url <url>", "Server URL")
+    .option("--token <token>", "Auth token");
+
+  registerRoutes(program, ROUTES, async (route, params, extraPositionals) => {
+    const allFlags = parseFlags(process.argv.slice(2));
+    allFlags._ = extraPositionals;
+
+    const format = resolveOutputFormat(allFlags);
+    try {
+      await runApiCommand(route, params, allFlags);
+    } catch (err: any) {
+      handleError(err, format);
+    }
+  });
+
+  program.addHelpText("after", `
+Local commands (no server required):
+  check                                Validate project definitions
+  init [name] [--dir <path>]           Initialize project dependencies
+  serve [--port N]                     Start the server
+  describe [command]                   List commands or describe one`);
+
+  if (!firstArg) {
+    program.help();
+  }
+
+  await program.parseAsync(process.argv);
+}
+
+main();

package/src/cli/init.ts

@@ -0,0 +1,35 @@
+import { resolve, join } from "node:path";
+import { mkdirSync } from "node:fs";
+import type { OperationResult } from "../introspect/types.js";
+import { createProject } from "../create-project.js";
+import { parseFlags } from "./format.js";
+
+export async function init(args: string[]): Promise<OperationResult> {
+  const flags = parseFlags(args);
+  const projectDir = resolve(flags.dir ?? ".");
+  const projectName = flags._?.[0];
+
+  const codeDir = join(projectDir, "code");
+  const dataDir = join(projectDir, "data");
+
+  mkdirSync(codeDir, { recursive: true });
+  mkdirSync(dataDir, { recursive: true });
+
+  try {
+    const result = createProject({ dir: codeDir, name: projectName });
+    return {
+      ok: true,
+      data: [result.packageJson],
+      meta: { message: `Initialized project in ${projectDir}. Dependencies installed.` },
+    };
+  } catch (err: any) {
+    if (err.message.startsWith("package.json already exists")) {
+      return {
+        ok: true,
+        data: [],
+        meta: { message: `${err.message}. Skipping.` },
+      };
+    }
+    throw err;
+  }
+}

package/src/cli/project-context.ts

@@ -0,0 +1,38 @@
+import { OperationError, ErrorCode } from "../introspect/types.js";
+
+/**
+ * Project context resolved from environment/flags.
+ * Directory-based resolution — no Postgres registry dependency.
+ */
+export interface ProjectContext {
+  databasePath: string;
+  dir: string | null;
+}
+
+/**
+ * Resolve project context from CLI flags and environment variables.
+ *
+ * Resolution: SAPPORTA_PROJECT_DIR (or --sapporta-project-dir) is the root.
+ * From it we derive code/src (schema directory) and data/sqlite.db (database).
+ *
+ * Each component is individually overridable via flags/env for flexibility.
+ */
+export async function resolveProjectContext(
+  flags: Record<string, string>,
+): Promise<ProjectContext> {
+  const projectDir = flags["sapporta-project-dir"] ?? process.env.SAPPORTA_PROJECT_DIR;
+
+  if (!projectDir) {
+    throw new OperationError(
+      "No project specified. Set SAPPORTA_PROJECT_DIR or use --sapporta-project-dir",
+      ErrorCode.PROJECT_NOT_FOUND,
+    );
+  }
+
+  const codeDir = flags["code-dir"] ?? process.env.SAPPORTA_CODE_DIR ?? `${projectDir}/code`;
+  const srcDir = `${codeDir}/src`;
+  const dataDir = flags["data-dir"] ?? process.env.SAPPORTA_DATA_DIR ?? `${projectDir}/data`;
+  const databasePath = `${dataDir}/sqlite.db`;
+
+  return { databasePath, dir: srcDir };
+}