trekoon 0.2.6 → 0.2.8

package/src/board/routes.ts

@@ -0,0 +1,299 @@
+import { type Database } from "bun:sqlite";
+
+import { safeErrorMessage } from "../commands/error-utils";
+import { MutationService } from "../domain/mutation-service";
+import { TrackerDomain } from "../domain/tracker-domain";
+import { DomainError } from "../domain/types";
+import { buildBoardSnapshot } from "./snapshot";
+
+interface BoardRouteContext {
+  readonly db: Database;
+  readonly cwd: string;
+  readonly token: string;
+}
+
+interface BoardRouteError {
+  readonly status: number;
+  readonly code: string;
+  readonly message: string;
+  readonly details?: Record<string, unknown>;
+}
+
+function jsonResponse(status: number, data: unknown): Response {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: {
+      "cache-control": "no-store",
+      "content-type": "application/json; charset=utf-8",
+    },
+  });
+}
+
+function extractToken(request: Request, url: URL): string | null {
+  const authorization: string | null = request.headers.get("authorization");
+  if (authorization?.startsWith("Bearer ")) {
+    return authorization.slice("Bearer ".length).trim();
+  }
+
+  const headerToken: string | null = request.headers.get("x-trekoon-token");
+  if (headerToken && headerToken.trim().length > 0) {
+    return headerToken.trim();
+  }
+
+  const queryToken: string | null = url.searchParams.get("token");
+  if (queryToken && queryToken.trim().length > 0) {
+    return queryToken.trim();
+  }
+
+  return null;
+}
+
+function isSqliteBusyMessage(message: string): boolean {
+  const normalized = message.toLowerCase();
+  return normalized.includes("database is locked") || normalized.includes("database schema is locked");
+}
+
+function toBoardRouteError(error: unknown): BoardRouteError {
+  if (error instanceof DomainError) {
+    const status =
+      error.code === "not_found"
+        ? 404
+        : error.code === "invalid_input"
+          ? 400
+          : error.code === "invalid_dependency" || error.code === "dependency_blocked"
+            ? 409
+          : 400;
+    return {
+      status,
+      code: error.code,
+      message: error.message,
+      ...(error.details === undefined ? {} : { details: error.details }),
+    };
+  }
+
+  const message = safeErrorMessage(error, "Unexpected board API failure");
+  if (isSqliteBusyMessage(message)) {
+    return {
+      status: 503,
+      code: "database_busy",
+      message: "Trekoon database is busy",
+      details: {
+        databaseMessage: message,
+      },
+    };
+  }
+
+  return {
+    status: 500,
+    code: "internal_error",
+    message: "Unexpected board API failure",
+    details: {
+      cause: message,
+    },
+  };
+}
+
+function describeBoardError(mutations: MutationService, error: unknown): BoardRouteError {
+  const routeError = toBoardRouteError(error);
+  const readableMessage = mutations.describeError(error);
+  if (readableMessage === undefined) {
+    return routeError;
+  }
+
+  return {
+    ...routeError,
+    message: readableMessage,
+  };
+}
+
+function buildMutationResponse(domain: TrackerDomain, data: Record<string, unknown>, status = 200): Response {
+  return jsonResponse(status, {
+    ok: true,
+    data: {
+      ...data,
+      snapshot: buildBoardSnapshot(domain),
+    },
+  });
+}
+
+async function parseJsonBody(request: Request): Promise<Record<string, unknown>> {
+  const contentType: string = request.headers.get("content-type") ?? "";
+  if (!contentType.includes("application/json")) {
+    throw new DomainError({
+      code: "invalid_input",
+      message: "Expected application/json request body",
+    });
+  }
+
+  let body: unknown;
+  try {
+    body = await request.json();
+  } catch {
+    throw new DomainError({
+      code: "invalid_input",
+      message: "Malformed JSON request body",
+    });
+  }
+
+  if (!body || typeof body !== "object" || Array.isArray(body)) {
+    throw new DomainError({
+      code: "invalid_input",
+      message: "Expected JSON object request body",
+    });
+  }
+
+  return body as Record<string, unknown>;
+}
+
+function readOptionalString(body: Record<string, unknown>, field: string): string | undefined {
+  const value = body[field];
+  if (value === undefined) {
+    return undefined;
+  }
+
+  if (typeof value !== "string") {
+    throw new DomainError({
+      code: "invalid_input",
+      message: `${field} must be a string`,
+      details: { field },
+    });
+  }
+
+  return value;
+}
+
+function readRequiredString(body: Record<string, unknown>, field: string): string {
+  const value = readOptionalString(body, field);
+  if (value === undefined) {
+    throw new DomainError({
+      code: "invalid_input",
+      message: `${field} is required`,
+      details: { field },
+    });
+  }
+
+  return value;
+}
+
+export function createBoardApiHandler(context: BoardRouteContext): (request: Request) => Promise<Response> {
+  return async (request: Request): Promise<Response> => {
+    const url = new URL(request.url);
+    const requestToken = extractToken(request, url);
+    if (requestToken !== context.token) {
+      return jsonResponse(401, {
+        ok: false,
+        error: {
+          code: "unauthorized",
+          message: "Missing or invalid board session token",
+        },
+      });
+    }
+
+    const domain = new TrackerDomain(context.db);
+    const mutations = new MutationService(context.db, context.cwd);
+
+    try {
+      if (request.method === "GET" && url.pathname === "/api/snapshot") {
+        return jsonResponse(200, {
+          ok: true,
+          data: {
+            snapshot: buildBoardSnapshot(domain),
+          },
+        });
+      }
+
+      const epicMatch = request.method === "PATCH" ? url.pathname.match(/^\/api\/epics\/([^/]+)$/u) : null;
+      if (epicMatch) {
+        const body = await parseJsonBody(request);
+        const epic = mutations.updateEpic(epicMatch[1] ?? "", {
+          title: readOptionalString(body, "title"),
+          description: readOptionalString(body, "description"),
+          status: readOptionalString(body, "status"),
+        });
+        return buildMutationResponse(domain, { epic });
+      }
+
+      const taskMatch = request.method === "PATCH" ? url.pathname.match(/^\/api\/tasks\/([^/]+)$/u) : null;
+      if (taskMatch) {
+        const body = await parseJsonBody(request);
+        const task = mutations.updateTask(taskMatch[1] ?? "", {
+          title: readOptionalString(body, "title"),
+          description: readOptionalString(body, "description"),
+          status: readOptionalString(body, "status"),
+        });
+        return buildMutationResponse(domain, { task });
+      }
+
+      const subtaskMatch = request.method === "PATCH" ? url.pathname.match(/^\/api\/subtasks\/([^/]+)$/u) : null;
+      if (subtaskMatch) {
+        const body = await parseJsonBody(request);
+        const subtask = mutations.updateSubtask(subtaskMatch[1] ?? "", {
+          title: readOptionalString(body, "title"),
+          description: readOptionalString(body, "description"),
+          status: readOptionalString(body, "status"),
+        });
+        return buildMutationResponse(domain, { subtask });
+      }
+
+      if (request.method === "POST" && url.pathname === "/api/subtasks") {
+        const body = await parseJsonBody(request);
+        const subtask = mutations.createSubtask({
+          taskId: readRequiredString(body, "taskId"),
+          title: readRequiredString(body, "title"),
+          description: readOptionalString(body, "description"),
+          status: readOptionalString(body, "status"),
+        });
+        return buildMutationResponse(domain, { subtask }, 201);
+      }
+
+      const deleteSubtaskMatch = request.method === "DELETE" ? url.pathname.match(/^\/api\/subtasks\/([^/]+)$/u) : null;
+      if (deleteSubtaskMatch) {
+        const subtaskId = deleteSubtaskMatch[1] ?? "";
+        mutations.deleteSubtask(subtaskId);
+        return buildMutationResponse(domain, { subtaskId, deleted: true });
+      }
+
+      if (request.method === "POST" && url.pathname === "/api/dependencies") {
+        const body = await parseJsonBody(request);
+        const dependency = mutations.addDependency(readRequiredString(body, "sourceId"), readRequiredString(body, "dependsOnId"));
+        return buildMutationResponse(domain, { dependency }, 201);
+      }
+
+      if (request.method === "DELETE" && url.pathname === "/api/dependencies") {
+        const sourceId = url.searchParams.get("sourceId") ?? "";
+        const dependsOnId = url.searchParams.get("dependsOnId") ?? "";
+        const removed = mutations.removeDependency(sourceId, dependsOnId);
+        if (removed === 0) {
+          throw new DomainError({
+            code: "not_found",
+            message: "Dependency edge not found",
+            details: {
+              sourceId,
+              dependsOnId,
+            },
+          });
+        }
+
+        return buildMutationResponse(domain, { sourceId, dependsOnId, removed });
+      }
+
+      return jsonResponse(404, {
+        ok: false,
+        error: {
+          code: "not_found",
+          message: `Unknown board route: ${request.method} ${url.pathname}`,
+        },
+      });
+    } catch (error: unknown) {
+      const routeError = describeBoardError(mutations, error);
+      return jsonResponse(routeError.status, {
+        ok: false,
+        error: {
+          code: routeError.code,
+          message: routeError.message,
+          ...(routeError.details === undefined ? {} : { details: routeError.details }),
+        },
+      });
+    }
+  };
+}

package/src/board/server.ts

@@ -0,0 +1,184 @@
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, extname, resolve } from "node:path";
+
+import { createBoardApiHandler } from "./routes";
+
+import { openTrekoonDatabase, type TrekoonDatabase } from "../storage/database";
+import { resolveStoragePaths } from "../storage/path";
+
+const CONTENT_TYPES: Record<string, string> = {
+  ".css": "text/css; charset=utf-8",
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".txt": "text/plain; charset=utf-8",
+};
+
+const BOARD_SERVER_STATE_FILENAME = "board-server.json";
+
+interface BoardServerState {
+  readonly preferredPort: number;
+}
+
+export interface BoardServerInfo {
+  readonly origin: string;
+  readonly url: string;
+  readonly fallbackUrl: string;
+  readonly token: string;
+  readonly hostname: "127.0.0.1";
+  readonly port: number;
+  stop(): void;
+}
+
+export interface StartBoardServerOptions {
+  readonly cwd?: string;
+  readonly token?: string;
+}
+
+function guessContentType(pathname: string): string {
+  return CONTENT_TYPES[extname(pathname).toLowerCase()] ?? "application/octet-stream";
+}
+
+function readAssetPath(boardRoot: string, pathname: string): string | null {
+  const relativePath = pathname === "/" ? "index.html" : pathname.slice(1);
+  const candidate = resolve(boardRoot, relativePath);
+  if (!candidate.startsWith(resolve(boardRoot))) {
+    return null;
+  }
+
+  return existsSync(candidate) ? candidate : null;
+}
+
+function readPreferredBoardPort(stateFile: string): number | null {
+  if (!existsSync(stateFile)) {
+    return null;
+  }
+
+  try {
+    const rawState: string = readFileSync(stateFile, "utf8");
+    const state = JSON.parse(rawState) as Partial<BoardServerState>;
+    const preferredPort = state.preferredPort;
+
+    if (typeof preferredPort !== "number" || !Number.isInteger(preferredPort) || preferredPort < 1 || preferredPort > 65535) {
+      return null;
+    }
+
+    return preferredPort;
+  } catch {
+    return null;
+  }
+}
+
+function persistPreferredBoardPort(stateFile: string, port: number): void {
+  mkdirSync(dirname(stateFile), { recursive: true });
+  writeFileSync(stateFile, `${JSON.stringify({ preferredPort: port }, null, 2)}\n`, "utf8");
+}
+
+function isUnavailablePortError(error: unknown): boolean {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+
+  const errorWithCode = error as Error & { code?: unknown };
+  const errorCode = typeof errorWithCode.code === "string" ? errorWithCode.code : "";
+  return /^(EADDRINUSE|EACCES)$/i.test(errorCode) || /(EADDRINUSE|EACCES|address already in use|permission denied)/i.test(error.message);
+}
+
+export function startBoardServer(options: StartBoardServerOptions = {}): BoardServerInfo {
+  const cwd: string = options.cwd ?? process.cwd();
+  const database: TrekoonDatabase = openTrekoonDatabase(cwd);
+  const paths = resolveStoragePaths(cwd);
+  const boardRoot: string = paths.boardDir;
+  const stateFile: string = resolve(paths.storageDir, BOARD_SERVER_STATE_FILENAME);
+  const token: string = options.token ?? randomBytes(18).toString("hex");
+  const apiHandler = createBoardApiHandler({
+    db: database.db,
+    cwd,
+    token,
+  });
+
+  const serveBoard = (port: number) =>
+    Bun.serve({
+      hostname: "127.0.0.1",
+      port,
+      fetch(request: Request): Promise<Response> | Response {
+        const url = new URL(request.url);
+        if (url.pathname.startsWith("/api/")) {
+          return apiHandler(request);
+        }
+
+        const assetPath = readAssetPath(boardRoot, url.pathname === "/" ? "/index.html" : url.pathname);
+        if (assetPath === null) {
+          const fallbackPath = readAssetPath(boardRoot, "/index.html");
+          if (fallbackPath === null) {
+            return new Response("Board assets are not installed", { status: 500 });
+          }
+
+          return new Response(readFileSync(fallbackPath), {
+            headers: {
+              "cache-control": "no-store",
+              "content-type": "text/html; charset=utf-8",
+            },
+          });
+        }
+
+        return new Response(readFileSync(assetPath), {
+          headers: {
+            "cache-control": "no-store",
+            "content-type": guessContentType(assetPath),
+          },
+        });
+      },
+      error(error: Error): Response {
+        return new Response(`Board server error: ${error.message}`, { status: 500 });
+      },
+    });
+
+  const preferredPort: number | null = readPreferredBoardPort(stateFile);
+
+  let server;
+  try {
+    server = serveBoard(preferredPort ?? 0);
+  } catch (error) {
+    if (preferredPort === null || !isUnavailablePortError(error)) {
+      database.close();
+      throw error;
+    }
+
+    server = serveBoard(0);
+  }
+
+  const port: number | undefined = server.port;
+  if (port === undefined) {
+    server.stop(true);
+    database.close();
+    throw new Error("Board server did not expose a listening port");
+  }
+
+  try {
+    persistPreferredBoardPort(stateFile, port);
+  } catch (error) {
+    server.stop(true);
+    database.close();
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Board server could not persist preferred port at ${stateFile}: ${message}`);
+  }
+
+  const origin: string = `http://127.0.0.1:${port}`;
+  const url: string = `${origin}/?token=${encodeURIComponent(token)}`;
+
+  return {
+    origin,
+    url,
+    fallbackUrl: url,
+    token,
+    hostname: "127.0.0.1",
+    port,
+    stop(): void {
+      server.stop(true);
+      database.close();
+    },
+  };
+}