trekoon 0.2.7 → 0.2.9

package/src/board/assets/styles/fonts.css

@@ -0,0 +1,22 @@
+/* Inter — variable, Latin subset, weights 400–700 */
+@font-face {
+  font-family: "Inter";
+  font-style: normal;
+  font-weight: 400 700;
+  font-display: swap;
+  src: url("../fonts/inter-latin.woff2") format("woff2");
+  unicode-range: U+0020-007E, U+00A0, U+00A9, U+00AB, U+00AD, U+00AE, U+00B7,
+    U+00BB, U+00C0-00C1, U+00C9, U+00CD, U+00D1, U+00D3, U+00D7, U+00DA,
+    U+00DC, U+00E0-00E1, U+00E9, U+00ED, U+00F1, U+00F3, U+00F7, U+00FA,
+    U+00FC, U+2013-2014, U+2018-2019, U+201C-201D, U+2026, U+2039, U+203A,
+    U+20AC, U+2122, U+2212;
+}
+
+/* Material Symbols Rounded — subset of 16 glyphs used in board UI */
+@font-face {
+  font-family: "Material Symbols Rounded";
+  font-style: normal;
+  font-weight: 400;
+  font-display: block;
+  src: url("../fonts/material-symbols-rounded.woff2") format("woff2");
+}

package/src/board/install.ts

@@ -0,0 +1,196 @@
+import {
+  createHash,
+} from "node:crypto";
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { CLI_VERSION } from "../runtime/version";
+import {
+  resolveStoragePaths,
+  TREKOON_BOARD_ENTRY_FILENAME,
+  TREKOON_BOARD_MANIFEST_FILENAME,
+} from "../storage/path";
+import {
+  BOARD_ASSET_CONTRACT_VERSION,
+  BOARD_BUNDLED_ASSET_DIRNAME,
+  BoardInstallError,
+  type BoardAssetManifest,
+  type BoardInstallAction,
+  type BoardInstallResult,
+  type EnsureBoardInstalledOptions,
+} from "./types";
+
+function resolveBundledBoardAssetRoot(): string {
+  return fileURLToPath(new URL(`./${BOARD_BUNDLED_ASSET_DIRNAME}`, import.meta.url));
+}
+
+function listRelativeFiles(rootPath: string, currentPath: string = rootPath): string[] {
+  const entries = readdirSync(currentPath, { withFileTypes: true });
+  const files: string[] = [];
+
+  for (const entry of entries) {
+    const entryPath: string = join(currentPath, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...listRelativeFiles(rootPath, entryPath));
+      continue;
+    }
+
+    if (entry.isFile()) {
+      files.push(relative(rootPath, entryPath));
+    }
+  }
+
+  return files.sort((left, right) => left.localeCompare(right));
+}
+
+interface ReadManifestResult {
+  readonly manifest: BoardAssetManifest | null;
+  readonly damaged: boolean;
+}
+
+function readManifest(manifestFile: string): ReadManifestResult {
+  if (!existsSync(manifestFile)) {
+    return {
+      manifest: null,
+      damaged: false,
+    };
+  }
+
+  try {
+    const rawManifest: string = readFileSync(manifestFile, "utf8");
+    return {
+      manifest: JSON.parse(rawManifest) as BoardAssetManifest,
+      damaged: false,
+    };
+  } catch {
+    return {
+      manifest: null,
+      damaged: true,
+    };
+  }
+}
+
+function createAssetDigest(sourceRoot: string, files: readonly string[]): string {
+  const hash = createHash("sha256");
+
+  for (const relativeFile of files) {
+    hash.update(relativeFile);
+    hash.update("\0");
+    hash.update(readFileSync(join(sourceRoot, relativeFile)));
+    hash.update("\0");
+  }
+
+  return hash.digest("hex");
+}
+
+function createManifest(sourceRoot: string, assetVersion: string, files: readonly string[]): BoardAssetManifest {
+  return {
+    contractVersion: BOARD_ASSET_CONTRACT_VERSION,
+    assetVersion,
+    entryFile: TREKOON_BOARD_ENTRY_FILENAME,
+    files,
+    assetDigest: createAssetDigest(sourceRoot, files),
+  };
+}
+
+function installBoardFiles(sourceRoot: string, runtimeRoot: string, manifest: BoardAssetManifest): void {
+  rmSync(runtimeRoot, { recursive: true, force: true });
+  mkdirSync(dirname(runtimeRoot), { recursive: true });
+  cpSync(sourceRoot, runtimeRoot, { recursive: true });
+  writeFileSync(join(runtimeRoot, TREKOON_BOARD_MANIFEST_FILENAME), `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+}
+
+function determineAction(
+  runtimeRoot: string,
+  entryFile: string,
+  currentManifest: BoardAssetManifest | null,
+  manifestDamaged: boolean,
+  nextManifest: BoardAssetManifest,
+): BoardInstallAction {
+  if (manifestDamaged) {
+    return "reinstalled";
+  }
+
+  if (!existsSync(runtimeRoot) || !existsSync(entryFile) || currentManifest === null) {
+    return currentManifest === null && !existsSync(runtimeRoot) ? "installed" : "reinstalled";
+  }
+
+  if (
+    currentManifest.contractVersion !== nextManifest.contractVersion ||
+    currentManifest.assetVersion !== nextManifest.assetVersion ||
+    currentManifest.entryFile !== nextManifest.entryFile ||
+    JSON.stringify(currentManifest.files) !== JSON.stringify(nextManifest.files) ||
+    currentManifest.assetDigest !== nextManifest.assetDigest
+  ) {
+    return "updated";
+  }
+
+  for (const relativeFile of nextManifest.files) {
+    if (!existsSync(join(runtimeRoot, relativeFile))) {
+      return "reinstalled";
+    }
+  }
+
+  return "unchanged";
+}
+
+export function ensureBoardInstalled(options: EnsureBoardInstalledOptions = {}): BoardInstallResult {
+  const paths = resolveStoragePaths(options.workingDirectory);
+  const sourceRoot: string = resolve(options.bundledAssetRoot ?? resolveBundledBoardAssetRoot());
+  const runtimeRoot: string = paths.boardDir;
+  const entryFile: string = paths.boardEntryFile;
+  const manifestFile: string = paths.boardManifestFile;
+
+  if (!existsSync(sourceRoot) || !statSync(sourceRoot).isDirectory()) {
+    throw new BoardInstallError("missing_asset", `Bundled board asset directory not found at ${sourceRoot}`, {
+      sourceRoot,
+    });
+  }
+
+  const sourceFiles: string[] = listRelativeFiles(sourceRoot);
+  if (!sourceFiles.includes(TREKOON_BOARD_ENTRY_FILENAME)) {
+    throw new BoardInstallError("missing_asset", `Bundled board entry file not found at ${join(sourceRoot, TREKOON_BOARD_ENTRY_FILENAME)}`, {
+      sourceRoot,
+      missingFile: TREKOON_BOARD_ENTRY_FILENAME,
+    });
+  }
+
+  const manifest: BoardAssetManifest = createManifest(sourceRoot, options.assetVersion ?? CLI_VERSION, sourceFiles);
+  const currentManifestResult: ReadManifestResult = readManifest(manifestFile);
+  const action: BoardInstallAction = determineAction(
+    runtimeRoot,
+    entryFile,
+    currentManifestResult.manifest,
+    currentManifestResult.damaged,
+    manifest,
+  );
+
+  if (action !== "unchanged") {
+    installBoardFiles(sourceRoot, runtimeRoot, manifest);
+  }
+
+  return {
+    action,
+    paths: {
+      sourceRoot,
+      runtimeRoot,
+      entryFile,
+      manifestFile,
+    },
+    manifest,
+  };
+}
+
+export function updateBoardInstallation(options: EnsureBoardInstalledOptions = {}): BoardInstallResult {
+  return ensureBoardInstalled(options);
+}

package/src/board/open-browser.ts

@@ -0,0 +1,131 @@
+import { spawn } from "node:child_process";
+
+export interface OpenBrowserResult {
+  readonly launched: boolean;
+  readonly url: string;
+  readonly command: string | null;
+  readonly args: readonly string[];
+  readonly errorMessage: string | null;
+}
+
+type BrowserLaunchEvent = "error" | "exit" | "spawn";
+type BrowserLaunchListener = (eventData?: Error | number | null) => void;
+
+interface BrowserLaunchHandle {
+  once(event: BrowserLaunchEvent, listener: BrowserLaunchListener): BrowserLaunchHandle;
+  removeListener(event: BrowserLaunchEvent, listener: BrowserLaunchListener): BrowserLaunchHandle;
+  unref(): void;
+}
+
+type BrowserLauncher = (command: string, args: readonly string[]) => BrowserLaunchHandle;
+
+function spawnBrowserProcess(command: string, args: readonly string[]): BrowserLaunchHandle {
+  const child = spawn(command, [...args], {
+    detached: true,
+    stdio: "ignore",
+  });
+  child.unref();
+  return child;
+}
+
+let browserLauncher: BrowserLauncher = spawnBrowserProcess;
+
+function resolveOpenCommand(url: string): { command: string; args: readonly string[] } {
+  if (process.platform === "darwin") {
+    return { command: "open", args: [url] };
+  }
+
+  if (process.platform === "win32") {
+    return { command: "cmd", args: ["/c", "start", "", url] };
+  }
+
+  return { command: "xdg-open", args: [url] };
+}
+
+export function setBrowserLauncherForTests(nextLauncher: BrowserLauncher | null): void {
+  browserLauncher = nextLauncher ?? spawnBrowserProcess;
+}
+
+export async function openBoardInBrowser(url: string): Promise<OpenBrowserResult> {
+  const launch = resolveOpenCommand(url);
+
+  try {
+    const child = browserLauncher(launch.command, launch.args);
+
+    return await new Promise<OpenBrowserResult>((resolve) => {
+      let settled = false;
+      let spawned = false;
+      let launchResultScheduled = false;
+
+      const complete = (result: OpenBrowserResult): void => {
+        if (settled) {
+          return;
+        }
+
+        settled = true;
+        child.removeListener("spawn", handleSpawn);
+        child.removeListener("error", handleError);
+        child.removeListener("exit", handleExit);
+        resolve(result);
+      };
+
+      const resolveLaunchSuccess = (): void => {
+        complete({
+          launched: true,
+          url,
+          command: launch.command,
+          args: launch.args,
+          errorMessage: null,
+        });
+      };
+
+      const handleSpawn = (): void => {
+        spawned = true;
+        if (launchResultScheduled) {
+          return;
+        }
+
+        launchResultScheduled = true;
+        setTimeout(resolveLaunchSuccess, 0);
+      };
+
+      const handleError = (eventData?: Error | number | null): void => {
+        complete({
+          launched: false,
+          url,
+          command: launch.command,
+          args: launch.args,
+          errorMessage: eventData instanceof Error ? eventData.message : "Unknown browser launch failure",
+        });
+      };
+
+      const handleExit = (eventData?: Error | number | null): void => {
+        const exitCode = typeof eventData === "number" ? eventData : Number.NaN;
+
+        if (!spawned || exitCode === 0 || Number.isNaN(exitCode)) {
+          return;
+        }
+
+        complete({
+          launched: false,
+          url,
+          command: launch.command,
+          args: launch.args,
+          errorMessage: `${launch.command} exited with code ${exitCode}`,
+        });
+      };
+
+      child.once("spawn", handleSpawn);
+      child.once("error", handleError);
+      child.once("exit", handleExit);
+    });
+  } catch (error: unknown) {
+    return {
+      launched: false,
+      url,
+      command: launch.command,
+      args: launch.args,
+      errorMessage: error instanceof Error ? error.message : "Unknown browser launch failure",
+    };
+  }
+}

package/src/board/routes.ts

@@ -0,0 +1,308 @@
+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, requestLabel: string): 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: `${requestLabel} failed because the Trekoon database is busy`,
+      details: {
+        databaseMessage: message,
+      },
+    };
+  }
+
+  return {
+    status: 500,
+    code: "internal_error",
+    message: `${requestLabel} failed unexpectedly`,
+    details: {
+      cause: message,
+    },
+  };
+}
+
+function describeBoardError(mutations: MutationService, error: unknown, requestLabel: string): BoardRouteError {
+  const routeError = toBoardRouteError(error, requestLabel);
+  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 requestLabel = `${request.method} ${url.pathname}`;
+    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 epicCascadeMatch = request.method === "PATCH" ? url.pathname.match(/^\/api\/epics\/([^/]+)\/cascade$/u) : null;
+      if (epicCascadeMatch) {
+        const body = await parseJsonBody(request);
+        const status = readRequiredString(body, "status");
+        const plan = mutations.updateEpicStatusCascade(epicCascadeMatch[1] ?? "", status);
+        return buildMutationResponse(domain, { plan });
+      }
+
+      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, requestLabel);
+      return jsonResponse(routeError.status, {
+        ok: false,
+        error: {
+          code: routeError.code,
+          message: routeError.message,
+          ...(routeError.details === undefined ? {} : { details: routeError.details }),
+        },
+      });
+    }
+  };
+}