trekoon 0.2.7 → 0.2.9

package/src/board/server.ts

@@ -0,0 +1,185 @@
+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",
+  ".woff2": "font/woff2",
+};
+
+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();
+    },
+  };
+}

package/src/board/snapshot.ts

@@ -0,0 +1,277 @@
+import { TrackerDomain } from "../domain/tracker-domain";
+import { type DependencyRecord, type EpicRecord, type SubtaskRecord, type TaskRecord } from "../domain/types";
+
+interface SearchFields {
+  readonly title: string;
+  readonly description: string;
+  readonly text: string;
+}
+
+interface StatusCounts {
+  readonly total: number;
+  readonly todo: number;
+  readonly blocked: number;
+  readonly inProgress: number;
+  readonly done: number;
+  readonly other: number;
+}
+
+export interface BoardSnapshotEpic {
+  readonly id: string;
+  readonly title: string;
+  readonly description: string;
+  readonly status: string;
+  readonly createdAt: number;
+  readonly updatedAt: number;
+  readonly taskIds: readonly string[];
+  readonly counts: {
+    readonly tasks: StatusCounts;
+    readonly subtasks: StatusCounts;
+  };
+  readonly search: SearchFields;
+}
+
+export interface BoardSnapshotTask {
+  readonly id: string;
+  readonly epicId: string;
+  readonly title: string;
+  readonly description: string;
+  readonly status: string;
+  readonly createdAt: number;
+  readonly updatedAt: number;
+  readonly subtaskIds: readonly string[];
+  readonly dependencyIds: readonly string[];
+  readonly dependentIds: readonly string[];
+  readonly counts: {
+    readonly subtasks: StatusCounts;
+    readonly dependencies: number;
+    readonly dependents: number;
+  };
+  readonly search: SearchFields;
+}
+
+export interface BoardSnapshotSubtask {
+  readonly id: string;
+  readonly taskId: string;
+  readonly title: string;
+  readonly description: string;
+  readonly status: string;
+  readonly createdAt: number;
+  readonly updatedAt: number;
+  readonly dependencyIds: readonly string[];
+  readonly dependentIds: readonly string[];
+  readonly counts: {
+    readonly dependencies: number;
+    readonly dependents: number;
+  };
+  readonly search: SearchFields;
+}
+
+export interface BoardSnapshotDependency {
+  readonly id: string;
+  readonly sourceId: string;
+  readonly sourceKind: "task" | "subtask";
+  readonly dependsOnId: string;
+  readonly dependsOnKind: "task" | "subtask";
+  readonly createdAt: number;
+  readonly updatedAt: number;
+}
+
+export interface BoardSnapshot {
+  readonly generatedAt: number;
+  readonly epics: readonly BoardSnapshotEpic[];
+  readonly tasks: readonly BoardSnapshotTask[];
+  readonly subtasks: readonly BoardSnapshotSubtask[];
+  readonly dependencies: readonly BoardSnapshotDependency[];
+  readonly counts: {
+    readonly epics: StatusCounts;
+    readonly tasks: StatusCounts;
+    readonly subtasks: StatusCounts;
+    readonly dependencies: number;
+  };
+}
+
+function normalizeStatusBucket(status: string): keyof Omit<StatusCounts, "total"> {
+  if (status === "todo") {
+    return "todo";
+  }
+
+   if (status === "blocked") {
+    return "blocked";
+  }
+
+  if (status === "in_progress" || status === "in-progress") {
+    return "inProgress";
+  }
+
+  if (status === "done") {
+    return "done";
+  }
+
+  return "other";
+}
+
+function countStatuses(records: readonly { readonly status: string }[]): StatusCounts {
+  const counts: {
+    total: number;
+    todo: number;
+    blocked: number;
+    inProgress: number;
+    done: number;
+    other: number;
+  } = {
+    total: records.length,
+    todo: 0,
+    blocked: 0,
+    inProgress: 0,
+    done: 0,
+    other: 0,
+  };
+
+  for (const record of records) {
+    const bucket = normalizeStatusBucket(record.status);
+    counts[bucket] += 1;
+  }
+
+  return counts;
+}
+
+function buildSearchFields(title: string, description: string): SearchFields {
+  return {
+    title,
+    description,
+    text: `${title}\n${description}`.trim(),
+  };
+}
+
+function mapDependency(record: DependencyRecord): BoardSnapshotDependency {
+  return {
+    id: record.id,
+    sourceId: record.sourceId,
+    sourceKind: record.sourceKind,
+    dependsOnId: record.dependsOnId,
+    dependsOnKind: record.dependsOnKind,
+    createdAt: record.createdAt,
+    updatedAt: record.updatedAt,
+  };
+}
+
+export function buildBoardSnapshot(domain: TrackerDomain): BoardSnapshot {
+  const generatedAt: number = Date.now();
+  const epics: readonly EpicRecord[] = domain.listEpics();
+  const tasks: readonly TaskRecord[] = domain.listTasks();
+  const subtasks: readonly SubtaskRecord[] = domain.listSubtasks();
+  const dependencies: BoardSnapshotDependency[] = [];
+
+  const tasksByEpic = new Map<string, TaskRecord[]>();
+  for (const task of tasks) {
+    const existing = tasksByEpic.get(task.epicId) ?? [];
+    existing.push(task);
+    tasksByEpic.set(task.epicId, existing);
+  }
+
+  const subtasksByTask = new Map<string, SubtaskRecord[]>();
+  for (const subtask of subtasks) {
+    const existing = subtasksByTask.get(subtask.taskId) ?? [];
+    existing.push(subtask);
+    subtasksByTask.set(subtask.taskId, existing);
+  }
+
+  const dependencyIdsBySource = new Map<string, string[]>();
+  const dependentIdsByTarget = new Map<string, string[]>();
+  for (const task of tasks) {
+    for (const dependency of domain.listDependencies(task.id)) {
+      dependencies.push(mapDependency(dependency));
+      const sourceIds = dependencyIdsBySource.get(dependency.sourceId) ?? [];
+      sourceIds.push(dependency.id);
+      dependencyIdsBySource.set(dependency.sourceId, sourceIds);
+      const dependentIds = dependentIdsByTarget.get(dependency.dependsOnId) ?? [];
+      dependentIds.push(dependency.id);
+      dependentIdsByTarget.set(dependency.dependsOnId, dependentIds);
+    }
+  }
+
+  for (const subtask of subtasks) {
+    for (const dependency of domain.listDependencies(subtask.id)) {
+      dependencies.push(mapDependency(dependency));
+      const sourceIds = dependencyIdsBySource.get(dependency.sourceId) ?? [];
+      sourceIds.push(dependency.id);
+      dependencyIdsBySource.set(dependency.sourceId, sourceIds);
+      const dependentIds = dependentIdsByTarget.get(dependency.dependsOnId) ?? [];
+      dependentIds.push(dependency.id);
+      dependentIdsByTarget.set(dependency.dependsOnId, dependentIds);
+    }
+  }
+
+  return {
+    generatedAt,
+    epics: epics.map((epic) => {
+      const epicTasks = tasksByEpic.get(epic.id) ?? [];
+      const epicSubtasks = epicTasks.flatMap((task) => subtasksByTask.get(task.id) ?? []);
+      return {
+        id: epic.id,
+        title: epic.title,
+        description: epic.description,
+        status: epic.status,
+        createdAt: epic.createdAt,
+        updatedAt: epic.updatedAt,
+        taskIds: epicTasks.map((task) => task.id),
+        counts: {
+          tasks: countStatuses(epicTasks),
+          subtasks: countStatuses(epicSubtasks),
+        },
+        search: buildSearchFields(epic.title, epic.description),
+      };
+    }),
+    tasks: tasks.map((task) => {
+      const taskSubtasks = subtasksByTask.get(task.id) ?? [];
+      const dependencyIds = dependencyIdsBySource.get(task.id) ?? [];
+      const dependentIds = dependentIdsByTarget.get(task.id) ?? [];
+      return {
+        id: task.id,
+        epicId: task.epicId,
+        title: task.title,
+        description: task.description,
+        status: task.status,
+        createdAt: task.createdAt,
+        updatedAt: task.updatedAt,
+        subtaskIds: taskSubtasks.map((subtask) => subtask.id),
+        dependencyIds,
+        dependentIds,
+        counts: {
+          subtasks: countStatuses(taskSubtasks),
+          dependencies: dependencyIds.length,
+          dependents: dependentIds.length,
+        },
+        search: buildSearchFields(task.title, task.description),
+      };
+    }),
+    subtasks: subtasks.map((subtask) => {
+      const dependencyIds = dependencyIdsBySource.get(subtask.id) ?? [];
+      const dependentIds = dependentIdsByTarget.get(subtask.id) ?? [];
+      return {
+        id: subtask.id,
+        taskId: subtask.taskId,
+        title: subtask.title,
+        description: subtask.description,
+        status: subtask.status,
+        createdAt: subtask.createdAt,
+        updatedAt: subtask.updatedAt,
+        dependencyIds,
+        dependentIds,
+        counts: {
+          dependencies: dependencyIds.length,
+          dependents: dependentIds.length,
+        },
+        search: buildSearchFields(subtask.title, subtask.description),
+      };
+    }),
+    dependencies,
+    counts: {
+      epics: countStatuses(epics),
+      tasks: countStatuses(tasks),
+      subtasks: countStatuses(subtasks),
+      dependencies: dependencies.length,
+    },
+  };
+}

package/src/board/types.ts

@@ -0,0 +1,43 @@
+export const BOARD_ASSET_CONTRACT_VERSION = "1.0.0";
+export const BOARD_BUNDLED_ASSET_DIRNAME = "assets";
+
+export interface BoardAssetManifest {
+  readonly contractVersion: string;
+  readonly assetVersion: string;
+  readonly entryFile: string;
+  readonly files: readonly string[];
+  readonly assetDigest: string;
+}
+
+export interface BoardAssetPaths {
+  readonly sourceRoot: string;
+  readonly runtimeRoot: string;
+  readonly entryFile: string;
+  readonly manifestFile: string;
+}
+
+export type BoardInstallAction = "installed" | "reinstalled" | "updated" | "unchanged";
+
+export interface BoardInstallResult {
+  readonly action: BoardInstallAction;
+  readonly paths: BoardAssetPaths;
+  readonly manifest: BoardAssetManifest;
+}
+
+export interface EnsureBoardInstalledOptions {
+  readonly workingDirectory?: string;
+  readonly assetVersion?: string;
+  readonly bundledAssetRoot?: string;
+}
+
+export class BoardInstallError extends Error {
+  readonly code: string;
+  readonly details: Record<string, unknown>;
+
+  constructor(code: string, message: string, details: Record<string, unknown> = {}) {
+    super(message);
+    this.name = "BoardInstallError";
+    this.code = code;
+    this.details = details;
+  }
+}

package/src/commands/board.ts

@@ -0,0 +1,158 @@
+import { parseArgs, readUnexpectedPositionals } from "./arg-parser";
+
+import { ensureBoardInstalled, updateBoardInstallation } from "../board/install";
+import { openBoardInBrowser, type OpenBrowserResult } from "../board/open-browser";
+import { startBoardServer, type BoardServerInfo } from "../board/server";
+import { BoardInstallError, type EnsureBoardInstalledOptions } from "../board/types";
+import { failResult, okResult } from "../io/output";
+import { type CliContext, type CliResult } from "../runtime/command-types";
+
+type EnsureBoardInstalledFn = (options: EnsureBoardInstalledOptions) => ReturnType<typeof ensureBoardInstalled>;
+type StartBoardServerFn = (options: { cwd: string }) => BoardServerInfo;
+type OpenBoardInBrowserFn = (url: string) => Promise<OpenBrowserResult> | OpenBrowserResult;
+
+let ensureInstalledImpl: EnsureBoardInstalledFn = ensureBoardInstalled;
+let updateInstalledImpl: EnsureBoardInstalledFn = updateBoardInstallation;
+let startBoardServerImpl: StartBoardServerFn = (options) => startBoardServer(options);
+let openBoardInBrowserImpl: OpenBoardInBrowserFn = openBoardInBrowser;
+
+function usageResult(): CliResult {
+  return failResult({
+    command: "board",
+    human: "Usage: trekoon board <open|update>",
+    data: {},
+    error: {
+      code: "invalid_subcommand",
+      message: "Invalid board subcommand",
+    },
+  });
+}
+
+function boardInstallOptions(context: CliContext): EnsureBoardInstalledOptions {
+  const bundledAssetRoot: string | undefined = process.env.TREKOON_BOARD_ASSET_ROOT;
+  return {
+    workingDirectory: context.cwd,
+    ...(bundledAssetRoot === undefined ? {} : { bundledAssetRoot }),
+  };
+}
+
+function boardInstallFailure(command: string, error: BoardInstallError): CliResult {
+  return failResult({
+    command,
+    human: error.message,
+    data: {
+      code: error.code,
+      ...error.details,
+    },
+    error: {
+      code: error.code,
+      message: error.message,
+    },
+  });
+}
+
+export function setBoardCommandHooksForTests(hooks: {
+  ensureInstalled?: EnsureBoardInstalledFn;
+  updateInstalled?: EnsureBoardInstalledFn;
+  startBoardServer?: StartBoardServerFn;
+  openBoardInBrowser?: OpenBoardInBrowserFn;
+} | null): void {
+  ensureInstalledImpl = hooks?.ensureInstalled ?? ensureBoardInstalled;
+  updateInstalledImpl = hooks?.updateInstalled ?? updateBoardInstallation;
+  startBoardServerImpl = hooks?.startBoardServer ?? ((options) => startBoardServer(options));
+  openBoardInBrowserImpl = hooks?.openBoardInBrowser ?? openBoardInBrowser;
+}
+
+export async function runBoard(context: CliContext): Promise<CliResult> {
+  const parsed = parseArgs(context.args);
+  const subcommand: string | undefined = parsed.positional[0];
+
+  if (parsed.options.size > 0 || parsed.flags.size > 0) {
+    return failResult({
+      command: subcommand ? `board.${subcommand}` : "board",
+      human: "Board commands do not accept options yet.",
+      data: {
+        options: [...parsed.providedOptions].map((option) => `--${option}`),
+      },
+      error: {
+        code: "invalid_input",
+        message: "Board commands do not accept options",
+      },
+    });
+  }
+
+  if (!subcommand) {
+    return usageResult();
+  }
+
+  const unexpectedPositionals = readUnexpectedPositionals(parsed, 1);
+  if (unexpectedPositionals.length > 0) {
+    return failResult({
+      command: `board.${subcommand}`,
+      human: `Unexpected positional arguments: ${unexpectedPositionals.join(", ")}.`,
+      data: {
+        unexpectedPositionals,
+      },
+      error: {
+        code: "invalid_input",
+        message: "Unexpected positional arguments",
+      },
+    });
+  }
+
+  try {
+    switch (subcommand) {
+      case "update": {
+        const install = updateInstalledImpl(boardInstallOptions(context));
+        return okResult({
+          command: "board.update",
+          human: `Board assets ${install.action} at ${install.paths.runtimeRoot}`,
+          data: {
+            action: install.action,
+            paths: install.paths,
+            manifest: install.manifest,
+          },
+        });
+      }
+      case "open": {
+        const install = ensureInstalledImpl(boardInstallOptions(context));
+        const server = startBoardServerImpl({ cwd: context.cwd });
+        const launch = await openBoardInBrowserImpl(server.url);
+        return okResult({
+          command: "board.open",
+          human: [
+            `Board ready at ${server.url}`,
+            launch.launched
+              ? `Browser launched with ${launch.command}`
+              : `Browser launch failed: ${launch.errorMessage ?? "unknown failure"}`,
+            `Open manually if needed: ${server.fallbackUrl}`,
+          ].join("\n"),
+          data: {
+            install: {
+              action: install.action,
+              paths: install.paths,
+              manifest: install.manifest,
+            },
+            server: {
+              origin: server.origin,
+              url: server.url,
+              fallbackUrl: server.fallbackUrl,
+              hostname: server.hostname,
+              port: server.port,
+              token: server.token,
+            },
+            launch,
+          },
+        });
+      }
+      default:
+        return usageResult();
+    }
+  } catch (error: unknown) {
+    if (error instanceof BoardInstallError) {
+      return boardInstallFailure(`board.${subcommand}`, error);
+    }
+
+    throw error;
+  }
+}

package/src/commands/help.ts

@@ -21,6 +21,7 @@ const ROOT_HELP = [
   "  init         Initialize repo-shared .trekoon storage and DB",
   "  quickstart   Show shared-storage bootstrap + AI execution loop",
   "  wipe         Remove repo-shared Trekoon state (requires --yes)",
+  "  board        Local board asset and browser commands",
   "  epic         Epic lifecycle commands",
   "  task         Task lifecycle commands",
   "  subtask      Subtask lifecycle commands",
@@ -83,6 +84,25 @@ const WIPE_HELP = [
   "  trekoon wipe --yes",
 ].join("\n");
 
+const BOARD_HELP = [
+  "Usage: trekoon board <open|update>",
+  "",
+  "Subcommands:",
+  "  open",
+  "      Ensure board assets are installed, start a 127.0.0.1 board server,",
+  "      and launch the browser. Machine output includes server URL, fallback URL,",
+  "      and launch metadata.",
+  "  update",
+  "      Refresh board runtime assets only. Does not start the server or open a browser.",
+  "",
+  "Environment overrides:",
+  "  TREKOON_BOARD_ASSET_ROOT  Optional asset source override for tests and local development.",
+  "",
+  "Examples:",
+  "  trekoon board open",
+  "  trekoon --json board update",
+].join("\n");
+
 const EPIC_HELP = [
   "Usage: trekoon epic <create|expand|list|show|search|replace|update|delete> [options]",
   "",
@@ -394,6 +414,7 @@ const SKILLS_HELP = [
 
 const COMMAND_HELP: Record<string, string> = {
   init: INIT_HELP,
+  board: BOARD_HELP,
   quickstart: QUICKSTART_HELP,
   session: SESSION_HELP,
   wipe: WIPE_HELP,