trekoon 0.3.6 → 0.3.8

package/src/board/snapshot.ts

@@ -1,11 +1,7 @@
 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;
-}
+type BoardStatus = "todo" | "blocked" | "in_progress" | "done";
 
 interface StatusCounts {
   readonly total: number;
@@ -16,65 +12,63 @@ interface StatusCounts {
   readonly other: number;
 }
 
-export interface BoardSnapshotEpic {
+interface FlatCounts extends Record<BoardStatus, number> {}
+
+export interface BoardSnapshotDependency {
   readonly id: string;
-  readonly title: string;
-  readonly description: string;
-  readonly status: string;
+  readonly sourceId: string;
+  readonly sourceKind: "task" | "subtask";
+  readonly dependsOnId: string;
+  readonly dependsOnKind: "task" | "subtask";
   readonly createdAt: number;
   readonly updatedAt: number;
-  readonly taskIds: readonly string[];
-  readonly counts: {
-    readonly tasks: StatusCounts;
-    readonly subtasks: StatusCounts;
-  };
-  readonly search: SearchFields;
 }
 
-export interface BoardSnapshotTask {
+interface BoardSnapshotSubtask {
   readonly id: string;
-  readonly epicId: string;
+  readonly kind: "subtask";
+  readonly taskId: string;
   readonly title: string;
   readonly description: string;
   readonly status: string;
+  readonly owner: string | null;
   readonly createdAt: number;
   readonly updatedAt: number;
-  readonly subtaskIds: readonly string[];
+  readonly blockedBy: readonly string[];
+  readonly blocks: readonly string[];
   readonly dependencyIds: readonly string[];
   readonly dependentIds: readonly string[];
-  readonly counts: {
-    readonly subtasks: StatusCounts;
-    readonly dependencies: number;
-    readonly dependents: number;
-  };
-  readonly search: SearchFields;
+  readonly searchText: string;
 }
 
-export interface BoardSnapshotSubtask {
+interface BoardSnapshotTask {
   readonly id: string;
-  readonly taskId: string;
+  readonly kind: "task";
+  readonly epicId: string;
   readonly title: string;
   readonly description: string;
   readonly status: string;
+  readonly owner: string | null;
   readonly createdAt: number;
   readonly updatedAt: number;
+  readonly blockedBy: readonly string[];
+  readonly blocks: readonly string[];
   readonly dependencyIds: readonly string[];
   readonly dependentIds: readonly string[];
-  readonly counts: {
-    readonly dependencies: number;
-    readonly dependents: number;
-  };
-  readonly search: SearchFields;
+  readonly subtasks: readonly BoardSnapshotSubtask[];
+  readonly searchText: string;
 }
 
-export interface BoardSnapshotDependency {
+interface BoardSnapshotEpic {
   readonly id: string;
-  readonly sourceId: string;
-  readonly sourceKind: "task" | "subtask";
-  readonly dependsOnId: string;
-  readonly dependsOnKind: "task" | "subtask";
+  readonly title: string;
+  readonly description: string;
+  readonly status: string;
   readonly createdAt: number;
   readonly updatedAt: number;
+  readonly taskIds: readonly string[];
+  readonly counts: FlatCounts;
+  readonly searchText: string;
 }
 
 export interface BoardSnapshot {
@@ -91,57 +85,41 @@ export interface BoardSnapshot {
   };
 }
 
-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";
-  }
+interface SnapshotDeltaSelection {
+  readonly epicIds?: readonly string[];
+  readonly taskIds?: readonly string[];
+  readonly subtaskIds?: readonly string[];
+  readonly dependencyIds?: readonly string[];
+  readonly deletedSubtaskIds?: readonly string[];
+  readonly deletedDependencyIds?: readonly string[];
+}
 
+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,
-  };
-
+  const counts = { 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;
+    counts[normalizeStatusBucket(record.status)] += 1;
   }
-
   return counts;
 }
 
-function buildSearchFields(title: string, description: string): SearchFields {
-  return {
-    title,
-    description,
-    text: `${title}\n${description}`.trim(),
-  };
+function deriveFlatCounts(records: readonly { readonly status: string }[]): FlatCounts {
+  return records.reduce<FlatCounts>(
+    (counts, record) => {
+      if (record.status === "todo" || record.status === "blocked" || record.status === "in_progress" || record.status === "done") {
+        counts[record.status] += 1;
+      }
+      return counts;
+    },
+    { todo: 0, blocked: 0, in_progress: 0, done: 0 },
+  );
 }
 
 function mapDependency(record: DependencyRecord): BoardSnapshotDependency {
@@ -156,122 +134,176 @@ function mapDependency(record: DependencyRecord): BoardSnapshotDependency {
   };
 }
 
-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();
+function uniqueIds(ids: readonly string[]): string[] {
+  return [...new Set(ids.filter((id) => id.length > 0))];
+}
+
+function buildDependencyIndexes(dependenciesBySourceId: Map<string, readonly DependencyRecord[]>, sourceIds: readonly string[]) {
+  const dependencyIdsBySource = new Map<string, string[]>();
+  const blockedByIdsBySource = new Map<string, string[]>();
+  const dependentIdsByTarget = new Map<string, string[]>();
+  const blocksByTarget = new Map<string, string[]>();
   const dependencies: BoardSnapshotDependency[] = [];
 
-  const tasksByEpic = new Map<string, TaskRecord[]>();
+  for (const sourceId of sourceIds) {
+    for (const dependency of dependenciesBySourceId.get(sourceId) ?? []) {
+      dependencies.push(mapDependency(dependency));
+      (dependencyIdsBySource.get(dependency.sourceId) ?? dependencyIdsBySource.set(dependency.sourceId, []).get(dependency.sourceId) ?? []).push(dependency.id);
+      (blockedByIdsBySource.get(dependency.sourceId) ?? blockedByIdsBySource.set(dependency.sourceId, []).get(dependency.sourceId) ?? []).push(dependency.dependsOnId);
+      (dependentIdsByTarget.get(dependency.dependsOnId) ?? dependentIdsByTarget.set(dependency.dependsOnId, []).get(dependency.dependsOnId) ?? []).push(dependency.id);
+      (blocksByTarget.get(dependency.dependsOnId) ?? blocksByTarget.set(dependency.dependsOnId, []).get(dependency.dependsOnId) ?? []).push(dependency.sourceId);
+    }
+  }
+
+  return { dependencies, dependencyIdsBySource, blockedByIdsBySource, dependentIdsByTarget, blocksByTarget };
+}
+
+function mapSnapshotSubtask(subtask: SubtaskRecord, indexes: ReturnType<typeof buildDependencyIndexes>): BoardSnapshotSubtask {
+  return {
+    id: subtask.id,
+    kind: "subtask",
+    taskId: subtask.taskId,
+    title: subtask.title,
+    description: subtask.description,
+    status: subtask.status,
+    owner: subtask.owner ?? null,
+    createdAt: subtask.createdAt,
+    updatedAt: subtask.updatedAt,
+    blockedBy: indexes.blockedByIdsBySource.get(subtask.id) ?? [],
+    blocks: indexes.blocksByTarget.get(subtask.id) ?? [],
+    dependencyIds: indexes.dependencyIdsBySource.get(subtask.id) ?? [],
+    dependentIds: indexes.dependentIdsByTarget.get(subtask.id) ?? [],
+    searchText: [subtask.title, subtask.description, subtask.status].join(" ").toLowerCase(),
+  };
+}
+
+function mapSnapshotTask(task: TaskRecord, taskSubtasks: readonly BoardSnapshotSubtask[], indexes: ReturnType<typeof buildDependencyIndexes>): BoardSnapshotTask {
+  return {
+    id: task.id,
+    kind: "task",
+    epicId: task.epicId,
+    title: task.title,
+    description: task.description,
+    status: task.status,
+    owner: task.owner ?? null,
+    createdAt: task.createdAt,
+    updatedAt: task.updatedAt,
+    blockedBy: indexes.blockedByIdsBySource.get(task.id) ?? [],
+    blocks: indexes.blocksByTarget.get(task.id) ?? [],
+    dependencyIds: indexes.dependencyIdsBySource.get(task.id) ?? [],
+    dependentIds: indexes.dependentIdsByTarget.get(task.id) ?? [],
+    subtasks: taskSubtasks,
+    searchText: [task.title, task.description, task.status, ...taskSubtasks.map((subtask) => `${subtask.title} ${subtask.description} ${subtask.status}`)].join(" ").toLowerCase(),
+  };
+}
+
+function mapSnapshotEpic(epic: EpicRecord, epicTasks: readonly BoardSnapshotTask[]): BoardSnapshotEpic {
+  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: deriveFlatCounts(epicTasks),
+    searchText: [epic.title, epic.description, ...epicTasks.map((task) => task.searchText)].join(" ").toLowerCase(),
+  };
+}
+
+export function buildBoardSnapshotDelta(domain: TrackerDomain, selection: SnapshotDeltaSelection): Record<string, unknown> {
+  const epicIds = uniqueIds(selection.epicIds ?? []);
+  const requestedTaskIds = uniqueIds(selection.taskIds ?? []);
+  const requestedSubtaskIds = uniqueIds(selection.subtaskIds ?? []);
+  const requestedDependencyIds = new Set(selection.dependencyIds ?? []);
+  const relatedTaskIds = uniqueIds([
+    ...requestedTaskIds,
+    ...requestedSubtaskIds.map((subtaskId) => domain.getSubtask(subtaskId)?.taskId ?? ""),
+  ]);
+  const tasks = relatedTaskIds.map((taskId) => domain.getTask(taskId)).filter((task): task is TaskRecord => task !== null);
+  const subtasksByTaskId = new Map<string, readonly SubtaskRecord[]>();
+  for (const task of tasks) {
+    subtasksByTaskId.set(task.id, domain.listSubtasks(task.id));
+  }
+  const allSubtasks = uniqueIds([
+    ...requestedSubtaskIds,
+    ...[...subtasksByTaskId.values()].flatMap((taskSubtasks) => taskSubtasks.map((subtask) => subtask.id)),
+  ]).map((subtaskId) => domain.getSubtask(subtaskId)).filter((subtask): subtask is SubtaskRecord => subtask !== null);
+  const sourceIds = uniqueIds([...tasks.map((task) => task.id), ...allSubtasks.map((subtask) => subtask.id)]);
+  const indexes = buildDependencyIndexes(domain.listDependenciesBySourceIds(sourceIds), sourceIds);
+  const snapshotSubtasksByTaskId = new Map<string, BoardSnapshotSubtask[]>();
+  for (const subtask of allSubtasks) {
+    const mappedSubtask = mapSnapshotSubtask(subtask, indexes);
+    const taskSubtasks = snapshotSubtasksByTaskId.get(subtask.taskId) ?? [];
+    taskSubtasks.push(mappedSubtask);
+    snapshotSubtasksByTaskId.set(subtask.taskId, taskSubtasks);
+  }
+  const snapshotTasks = tasks.map((task) => mapSnapshotTask(task, snapshotSubtasksByTaskId.get(task.id) ?? [], indexes));
+  const snapshotEpics = epicIds.map((epicId) => domain.getEpic(epicId)).filter((epic): epic is EpicRecord => epic !== null).map((epic) => mapSnapshotEpic(epic, snapshotTasks.filter((task) => task.epicId === epic.id)));
+
+  return {
+    generatedAt: Date.now(),
+    epics: snapshotEpics,
+    tasks: snapshotTasks.filter((task) => requestedTaskIds.includes(task.id)),
+    subtasks: allSubtasks.map((subtask) => mapSnapshotSubtask(subtask, indexes)).filter((subtask) => requestedSubtaskIds.includes(subtask.id)),
+    dependencies: indexes.dependencies.filter((dependency) => requestedDependencyIds.has(dependency.id)),
+    deletedSubtaskIds: [...(selection.deletedSubtaskIds ?? [])],
+    deletedDependencyIds: [...(selection.deletedDependencyIds ?? [])],
+  };
+}
+
+export function buildBoardSnapshot(domain: TrackerDomain): BoardSnapshot {
+  const generatedAt = Date.now();
+  const epics = domain.listEpics();
+  const tasks = domain.listTasks();
+  const subtasks = domain.listSubtasks();
+  const sourceIds = [...tasks.map((task) => task.id), ...subtasks.map((subtask) => subtask.id)];
+  const dependenciesBySourceId = domain.listDependenciesBySourceIds(sourceIds);
+  const subtasksByTaskId = new Map<string, SubtaskRecord[]>();
+  const tasksByEpicId = new Map<string, TaskRecord[]>();
+  const indexes = buildDependencyIndexes(dependenciesBySourceId, sourceIds);
+
   for (const task of tasks) {
-    const existing = tasksByEpic.get(task.epicId) ?? [];
+    const existing = tasksByEpicId.get(task.epicId) ?? [];
     existing.push(task);
-    tasksByEpic.set(task.epicId, existing);
+    tasksByEpicId.set(task.epicId, existing);
   }
 
-  const subtasksByTask = new Map<string, SubtaskRecord[]>();
   for (const subtask of subtasks) {
-    const existing = subtasksByTask.get(subtask.taskId) ?? [];
+    const existing = subtasksByTaskId.get(subtask.taskId) ?? [];
     existing.push(subtask);
-    subtasksByTask.set(subtask.taskId, existing);
+    subtasksByTaskId.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);
-    }
+  const snapshotSubtasks: BoardSnapshotSubtask[] = subtasks.map((subtask) => mapSnapshotSubtask(subtask, indexes));
+  const snapshotSubtasksByTaskId = new Map<string, BoardSnapshotSubtask[]>();
+  for (const subtask of snapshotSubtasks) {
+    const existing = snapshotSubtasksByTaskId.get(subtask.taskId) ?? [];
+    existing.push(subtask);
+    snapshotSubtasksByTaskId.set(subtask.taskId, existing);
   }
 
-  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);
-    }
+  const snapshotTasks: BoardSnapshotTask[] = tasks.map((task) => mapSnapshotTask(task, snapshotSubtasksByTaskId.get(task.id) ?? [], indexes));
+  const taskSearchTextByEpicId = new Map<string, string[]>();
+  for (const task of snapshotTasks) {
+    const existing = taskSearchTextByEpicId.get(task.epicId) ?? [];
+    existing.push(task.searchText);
+    taskSearchTextByEpicId.set(task.epicId, existing);
   }
 
+  const snapshotEpics: BoardSnapshotEpic[] = epics.map((epic) => mapSnapshotEpic(epic, snapshotTasks.filter((task) => task.epicId === epic.id)));
+
   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,
+    epics: snapshotEpics,
+    tasks: snapshotTasks,
+    subtasks: snapshotSubtasks,
+    dependencies: indexes.dependencies,
     counts: {
       epics: countStatuses(epics),
       tasks: countStatuses(tasks),
       subtasks: countStatuses(subtasks),
-      dependencies: dependencies.length,
+      dependencies: indexes.dependencies.length,
     },
   };
 }

package/src/commands/board.ts

@@ -121,7 +121,7 @@ export async function runBoard(context: CliContext): Promise<CliResult> {
         return okResult({
           command: "board.open",
           human: [
-            `Board ready at ${server.url}`,
+            `Board ready at ${server.fallbackUrl}`,
             launch.launched
               ? `Browser launched with ${launch.command}`
               : `Browser launch failed: ${launch.errorMessage ?? "unknown failure"}`,

package/src/commands/events.ts

@@ -73,17 +73,23 @@ export async function runEvents(context: CliContext): Promise<CliResult> {
       archive,
     });
 
-    return okResult({
-      command: "events.prune",
-      human: [
-        dryRun ? "Dry run complete." : "Prune complete.",
-        `Retention days: ${summary.retentionDays}`,
-        `Candidates: ${summary.candidateCount}`,
-        `Archived: ${summary.archivedCount}`,
-        `Deleted: ${summary.deletedCount}`,
-      ].join("\n"),
-      data: summary,
-    });
+      return okResult({
+        command: "events.prune",
+        human: [
+          dryRun ? "Dry run complete." : "Prune complete.",
+          `Retention days: ${summary.retentionDays}`,
+          `Candidates: ${summary.candidateCount}`,
+          `Archived: ${summary.archivedCount}`,
+          `Deleted: ${summary.deletedCount}`,
+          summary.staleCursorCount > 0
+            ? `Sync guidance: ${summary.staleCursorCount} cursor(s) reference pruned history. Run 'trekoon sync pull --from <branch>' and rebuild if stale cursor hints persist.`
+            : "Sync guidance: pruning stayed within retained cursor history.",
+          archive
+            ? "Retention automation: archived copies were kept before deletion."
+            : "Retention automation: rerun with --archive to keep retained copies before deletion.",
+        ].join("\n"),
+        data: summary,
+      });
   } catch (error: unknown) {
     const busyFailure = sqliteBusyFailure("events.prune", error);
     if (busyFailure !== null) {

package/src/commands/quickstart.ts

@@ -4,6 +4,16 @@ import { type CliContext, type CliResult } from "../runtime/command-types";
 const QUICKSTART_TEXT = [
   "Trekoon quickstart",
   "",
+  "Human workflow:",
+  "  1. Gather context through discussion, brainstorming, or research.",
+  "  2. Run: trekoon plan <goal>",
+  "     Use this when you want Trekoon to turn the goal into an execution-ready epic.",
+  "  3. Run: trekoon <epic-id>",
+  "     Use this to inspect the epic, next ready work, and blockers before execution.",
+  "  4. Run: trekoon <epic-id> execute",
+  "     Use this when you want the agent to keep working until the epic is done,",
+  "     all remaining work is blocked, or it needs your input.",
+  "",
   "Agents: always use --toon on every command.",
   "Aligned with: .agents/skills/trekoon/SKILL.md",
   "",

package/src/commands/subtask.ts

@@ -935,12 +935,12 @@ export async function runSubtask(context: CliContext): Promise<CliResult> {
       }
       case "delete": {
         const subtaskId: string = parsed.positional[1] ?? "";
-        mutations.deleteSubtask(subtaskId);
+        const result = mutations.deleteSubtask(subtaskId);
 
         return okResult({
           command: "subtask.delete",
           human: `Deleted subtask ${subtaskId}`,
-          data: { id: subtaskId },
+          data: { id: subtaskId, deletedDependencyIds: result.deletedDependencyIds },
         });
       }
       default: