trekoon 0.2.6 → 0.2.8

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/epic.ts

@@ -30,6 +30,7 @@ import {
   type CompactTaskSpec,
   type EpicRecord,
   type SearchEntityMatch,
+  type StatusCascadePlan,
 } from "../domain/types";
 import { formatHumanTable } from "../io/human-table";
 import { failResult, okResult } from "../io/output";
@@ -45,9 +46,13 @@ const LIST_VIEW_MODES = ["table", "compact"] as const;
 const DEFAULT_LIST_LIMIT = 10;
 const DEFAULT_OPEN_STATUSES = ["in_progress", "in-progress", "todo"] as const;
 const CREATE_OPTIONS = ["title", "t", "description", "d", "status", "s", "task", "subtask", "dep"] as const;
+const LIST_OPTIONS = ["status", "s", "limit", "l", "cursor", "all", "view"] as const;
+const SHOW_OPTIONS = ["view", "all"] as const;
 const SEARCH_OPTIONS = ["fields", "preview"] as const;
 const REPLACE_OPTIONS = ["search", "replace", "fields", "preview", "apply"] as const;
 const EXPAND_OPTIONS = ["task", "subtask", "dep"] as const;
+const UPDATE_OPTIONS = ["all", "ids", "append", "description", "d", "status", "s", "title", "t"] as const;
+const STATUS_CASCADE_UPDATE_STATUSES = ["done", "todo"] as const;
 
 function parseStatusCsv(rawStatuses: string | undefined): string[] | undefined {
   if (rawStatuses === undefined) {
@@ -218,6 +223,44 @@ function appendLine(existing: string, line: string): string {
   return existing.length > 0 ? `${existing}\n${line}` : line;
 }
 
+function isStatusCascadeUpdateStatus(status: string | undefined): status is (typeof STATUS_CASCADE_UPDATE_STATUSES)[number] {
+  return status === "done" || status === "todo";
+}
+
+function buildStatusCascadeData(plan: StatusCascadePlan): Record<string, unknown> {
+  return {
+    mode: "descendants",
+    root: {
+      kind: plan.rootKind,
+      id: plan.rootId,
+    },
+    targetStatus: plan.targetStatus,
+    atomic: plan.atomic,
+    changedIds: plan.changedIds,
+    unchangedIds: plan.unchangedIds,
+    counts: plan.counts,
+  };
+}
+
+function formatStatusCascadeHuman(entityLabel: string, plan: StatusCascadePlan): string {
+  return `Cascade updated ${entityLabel} ${plan.rootId} to ${plan.targetStatus} (${plan.counts.changed} changed, ${plan.counts.unchanged} unchanged; epics=${plan.counts.changedEpics}, tasks=${plan.counts.changedTasks}, subtasks=${plan.counts.changedSubtasks})`;
+}
+
+function failCascadeStatusUpdate(command: string, entityLabel: string, data: Record<string, unknown>): CliResult {
+  return failResult({
+    command,
+    human: `${entityLabel} descendant cascade requires --status done or --status todo and does not support --append, --description, or --title.`,
+    data: {
+      code: "invalid_input",
+      ...data,
+    },
+    error: {
+      code: "invalid_input",
+      message: `${entityLabel} descendant cascade requires status-only done/todo mode`,
+    },
+  });
+}
+
 function formatEpicListTable(epics: readonly EpicRecord[]): string {
   const rows = epics.map((epic) => [epic.id, epic.title, epic.status]);
   return formatHumanTable(["ID", "TITLE", "STATUS"], rows, { wrapColumns: [1] });
@@ -826,6 +869,16 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
         });
       }
       case "list": {
+        const listUnknownOption = findUnknownOption(parsed, LIST_OPTIONS);
+        if (listUnknownOption !== undefined) {
+          return unknownOption("epic.list", listUnknownOption, LIST_OPTIONS);
+        }
+
+        const unexpectedListPositionals = readUnexpectedPositionals(parsed, 1);
+        if (unexpectedListPositionals.length > 0) {
+          return failUnexpectedPositionals("epic.list", unexpectedListPositionals);
+        }
+
         const missingListOption =
           readMissingOptionValue(parsed.missingOptionValues, "status", "s") ??
           readMissingOptionValue(parsed.missingOptionValues, "limit", "l") ??
@@ -836,8 +889,8 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
         }
 
         const includeAll: boolean = hasFlag(parsed.flags, "all");
-        const rawStatuses: string | undefined = readOption(parsed.options, "status");
-        const rawLimit: string | undefined = readOption(parsed.options, "limit");
+        const rawStatuses: string | undefined = readOption(parsed.options, "status", "s");
+        const rawLimit: string | undefined = readOption(parsed.options, "limit", "l");
         const rawCursor: string | undefined = readOption(parsed.options, "cursor");
         const rawView: string | undefined = readOption(parsed.options, "view");
         const view = readEnumOption(parsed.options, VIEW_MODES, "view");
@@ -939,6 +992,16 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
         });
       }
       case "show": {
+        const showUnknownOption = findUnknownOption(parsed, SHOW_OPTIONS);
+        if (showUnknownOption !== undefined) {
+          return unknownOption("epic.show", showUnknownOption, SHOW_OPTIONS);
+        }
+
+        const unexpectedShowPositionals = readUnexpectedPositionals(parsed, 2);
+        if (unexpectedShowPositionals.length > 0) {
+          return failUnexpectedPositionals("epic.show", unexpectedShowPositionals);
+        }
+
         const missingShowOption = readMissingOptionValue(parsed.missingOptionValues, "view");
         if (missingShowOption !== undefined) {
           return failMissingOptionValue("epic.show", missingShowOption);
@@ -1167,6 +1230,16 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
         });
       }
       case "update": {
+        const updateUnknownOption = findUnknownOption(parsed, UPDATE_OPTIONS);
+        if (updateUnknownOption !== undefined) {
+          return unknownOption("epic.update", updateUnknownOption, UPDATE_OPTIONS);
+        }
+
+        const unexpectedUpdatePositionals = readUnexpectedPositionals(parsed, 2);
+        if (unexpectedUpdatePositionals.length > 0) {
+          return failUnexpectedPositionals("epic.update", unexpectedUpdatePositionals);
+        }
+
         const missingUpdateOption =
           readMissingOptionValue(parsed.missingOptionValues, "ids") ??
           readMissingOptionValue(parsed.missingOptionValues, "append") ??
@@ -1209,7 +1282,35 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
           });
         }
 
-        const hasBulkTarget = updateAll || ids.length > 0;
+        const cascadeMode = updateAll && epicId.length > 0;
+        if (cascadeMode) {
+          if (title !== undefined || description !== undefined || append !== undefined || !isStatusCascadeUpdateStatus(status)) {
+            return failCascadeStatusUpdate("epic.update", "Epic", {
+              id: epicId,
+              status,
+              allowedStatuses: [...STATUS_CASCADE_UPDATE_STATUSES],
+              fields: {
+                title: title !== undefined,
+                description: description !== undefined,
+                append: append !== undefined,
+              },
+            });
+          }
+
+          const cascade = mutations.updateEpicStatusCascade(epicId, status);
+          const epic = domain.getEpicOrThrow(epicId);
+
+          return okResult({
+            command: "epic.update",
+            human: formatStatusCascadeHuman("epic", cascade),
+            data: {
+              epic,
+              cascade: buildStatusCascadeData(cascade),
+            },
+          });
+        }
+
+        const hasBulkTarget = (updateAll && epicId.length === 0) || ids.length > 0;
         if (hasBulkTarget) {
           if (epicId.length > 0) {
             return failResult({