trekoon 0.3.7 → 0.3.9

package/src/board/snapshot.ts

@@ -85,6 +85,15 @@ export interface BoardSnapshot {
   };
 }
 
+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";
@@ -125,56 +134,32 @@ function mapDependency(record: DependencyRecord): BoardSnapshotDependency {
   };
 }
 
-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[]>();
+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[] = [];
 
-  for (const task of tasks) {
-    const existing = tasksByEpicId.get(task.epicId) ?? [];
-    existing.push(task);
-    tasksByEpicId.set(task.epicId, existing);
-  }
-
-  for (const subtask of subtasks) {
-    const existing = subtasksByTaskId.get(subtask.taskId) ?? [];
-    existing.push(subtask);
-    subtasksByTaskId.set(subtask.taskId, existing);
-  }
-
   for (const sourceId of sourceIds) {
     for (const dependency of dependenciesBySourceId.get(sourceId) ?? []) {
       dependencies.push(mapDependency(dependency));
-
-      const sourceDependencyIds = dependencyIdsBySource.get(dependency.sourceId) ?? [];
-      sourceDependencyIds.push(dependency.id);
-      dependencyIdsBySource.set(dependency.sourceId, sourceDependencyIds);
-
-      const sourceBlockedBy = blockedByIdsBySource.get(dependency.sourceId) ?? [];
-      sourceBlockedBy.push(dependency.dependsOnId);
-      blockedByIdsBySource.set(dependency.sourceId, sourceBlockedBy);
-
-      const targetDependentIds = dependentIdsByTarget.get(dependency.dependsOnId) ?? [];
-      targetDependentIds.push(dependency.id);
-      dependentIdsByTarget.set(dependency.dependsOnId, targetDependentIds);
-
-      const targetBlocks = blocksByTarget.get(dependency.dependsOnId) ?? [];
-      targetBlocks.push(dependency.sourceId);
-      blocksByTarget.set(dependency.dependsOnId, targetBlocks);
+      (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);
     }
   }
 
-  const snapshotSubtasks: BoardSnapshotSubtask[] = subtasks.map((subtask) => ({
+  return { dependencies, dependencyIdsBySource, blockedByIdsBySource, dependentIdsByTarget, blocksByTarget };
+}
+
+function mapSnapshotSubtask(subtask: SubtaskRecord, indexes: ReturnType<typeof buildDependencyIndexes>): BoardSnapshotSubtask {
+  return {
     id: subtask.id,
     kind: "subtask",
     taskId: subtask.taskId,
@@ -184,12 +169,113 @@ export function buildBoardSnapshot(domain: TrackerDomain): BoardSnapshot {
     owner: subtask.owner ?? null,
     createdAt: subtask.createdAt,
     updatedAt: subtask.updatedAt,
-    blockedBy: blockedByIdsBySource.get(subtask.id) ?? [],
-    blocks: blocksByTarget.get(subtask.id) ?? [],
-    dependencyIds: dependencyIdsBySource.get(subtask.id) ?? [],
-    dependentIds: dependentIdsByTarget.get(subtask.id) ?? [],
+    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 = tasksByEpicId.get(task.epicId) ?? [];
+    existing.push(task);
+    tasksByEpicId.set(task.epicId, existing);
+  }
+
+  for (const subtask of subtasks) {
+    const existing = subtasksByTaskId.get(subtask.taskId) ?? [];
+    existing.push(subtask);
+    subtasksByTaskId.set(subtask.taskId, existing);
+  }
+
+  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) ?? [];
@@ -197,31 +283,7 @@ export function buildBoardSnapshot(domain: TrackerDomain): BoardSnapshot {
     snapshotSubtasksByTaskId.set(subtask.taskId, existing);
   }
 
-  const snapshotTasks: BoardSnapshotTask[] = tasks.map((task) => {
-    const taskSubtasks = snapshotSubtasksByTaskId.get(task.id) ?? [];
-    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: blockedByIdsBySource.get(task.id) ?? [],
-      blocks: blocksByTarget.get(task.id) ?? [],
-      dependencyIds: dependencyIdsBySource.get(task.id) ?? [],
-      dependentIds: dependentIdsByTarget.get(task.id) ?? [],
-      subtasks: taskSubtasks,
-      searchText: [
-        task.title,
-        task.description,
-        task.status,
-        ...taskSubtasks.map((subtask) => `${subtask.title} ${subtask.description} ${subtask.status}`),
-      ].join(" ").toLowerCase(),
-    };
-  });
+  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) ?? [];
@@ -229,32 +291,19 @@ export function buildBoardSnapshot(domain: TrackerDomain): BoardSnapshot {
     taskSearchTextByEpicId.set(task.epicId, existing);
   }
 
-  const snapshotEpics: BoardSnapshotEpic[] = epics.map((epic) => {
-    const epicTasks = tasksByEpicId.get(epic.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: deriveFlatCounts(epicTasks),
-      searchText: [epic.title, epic.description, ...(taskSearchTextByEpicId.get(epic.id) ?? [])].join(" ").toLowerCase(),
-    };
-  });
+  const snapshotEpics: BoardSnapshotEpic[] = epics.map((epic) => mapSnapshotEpic(epic, snapshotTasks.filter((task) => task.epicId === epic.id)));
 
   return {
     generatedAt,
     epics: snapshotEpics,
     tasks: snapshotTasks,
     subtasks: snapshotSubtasks,
-    dependencies,
+    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/epic.ts

@@ -36,7 +36,12 @@ import {
 import { formatHumanTable } from "../io/human-table";
 import { failResult, okResult } from "../io/output";
 import { type CliContext, type CliResult } from "../runtime/command-types";
+import { buildEpicExportBundle } from "../export/build-epic-export-bundle";
+import { resolveExportPath } from "../export/path";
+import { renderMarkdown } from "../export/render-markdown";
+import { atomicWrite, ExportWriteError } from "../export/write";
 import { openTrekoonDatabase, type TrekoonDatabase } from "../storage/database";
+import { resolveStoragePaths } from "../storage/path";
 
 function formatEpic(epic: EpicRecord): string {
   return `${epic.id} | ${epic.title} | ${epic.status}`;
@@ -53,6 +58,7 @@ 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 EXPORT_OPTIONS = ["path", "overwrite"] as const;
 const STATUS_CASCADE_UPDATE_STATUSES = ["done", "todo"] as const;
 
 function parseStatusCsv(rawStatuses: string | undefined): string[] | undefined {
@@ -1472,10 +1478,87 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
           data: { id: epicId },
         });
       }
+      case "export": {
+        const epicId: string = parsed.positional[1] ?? "";
+        const exportUnknown = findUnknownOption(parsed, EXPORT_OPTIONS);
+        if (exportUnknown !== undefined) {
+          return unknownOption("epic.export", exportUnknown, EXPORT_OPTIONS);
+        }
+
+        const missingExportOption = readMissingOptionValue(parsed.missingOptionValues, "path");
+        if (missingExportOption !== undefined) {
+          return failMissingOptionValue("epic.export", missingExportOption);
+        }
+
+        if (!epicId) {
+          return failResult({
+            command: "epic.export",
+            human: "Usage: trekoon epic export <epic-id> [--path <path>] [--overwrite]",
+            data: {},
+            error: { code: "invalid_input", message: "Missing epic ID" },
+          });
+        }
+
+        const bundle = buildEpicExportBundle(domain, epicId);
+        const markdown = renderMarkdown(bundle);
+        const storagePaths = resolveStoragePaths(context.cwd);
+        const customPath = readOption(parsed.options, "path");
+        const overwrite = hasFlag(parsed.flags, "overwrite");
+
+        const exportPath = resolveExportPath({
+          customPath,
+          epicId: bundle.epic.id,
+          epicTitle: bundle.epic.title,
+          worktreeRoot: storagePaths.worktreeRoot,
+          cwd: context.cwd,
+        });
+
+        try {
+          const result = atomicWrite({ path: exportPath, content: markdown, overwrite });
+          const action = result.overwritten ? "Updated" : "Exported";
+          return okResult({
+            command: "epic.export",
+            human: `${action} epic to ${result.path}`,
+            data: {
+              epicId: bundle.epic.id,
+              path: result.path,
+              overwritten: result.overwritten,
+              summary: bundle.summary,
+            },
+          });
+        } catch (error: unknown) {
+          if (error instanceof ExportWriteError) {
+            return failResult({
+              command: "epic.export",
+              human: error.message,
+              data: { path: exportPath, epicId: bundle.epic.id },
+              error: { code: error.code, message: error.message },
+            });
+          }
+          const fsCode = typeof error === "object" && error !== null && "code" in error ? (error as { code: string }).code : null;
+          if (fsCode === "EACCES" || fsCode === "EPERM" || fsCode === "EROFS") {
+            return failResult({
+              command: "epic.export",
+              human: `Permission denied: cannot write to ${exportPath}`,
+              data: { path: exportPath, epicId: bundle.epic.id, fsError: fsCode },
+              error: { code: "permission_denied", message: `Permission denied: ${exportPath}` },
+            });
+          }
+          if (fsCode === "EISDIR") {
+            return failResult({
+              command: "epic.export",
+              human: `Path is a directory, not a file: ${exportPath}`,
+              data: { path: exportPath, epicId: bundle.epic.id, fsError: fsCode },
+              error: { code: "invalid_path", message: `Path is a directory: ${exportPath}` },
+            });
+          }
+          throw error;
+        }
+      }
       default:
         return failResult({
           command: "epic",
-          human: "Usage: trekoon epic <create|expand|list|show|search|replace|update|delete|progress>",
+          human: "Usage: trekoon epic <create|expand|list|show|search|replace|update|delete|progress|export>",
           data: {
             args: context.args,
           },

package/src/commands/help.ts

@@ -103,7 +103,7 @@ const BOARD_HELP = [
 ].join("\n");
 
 const EPIC_HELP = [
-  "Usage: trekoon epic <create|expand|list|show|search|replace|update|delete|progress> [options]",
+  "Usage: trekoon epic <create|expand|list|show|search|replace|update|delete|progress|export> [options]",
   "",
   "Create:",
   "  trekoon epic create --title \"...\" --description \"...\" [--status <status>]",
@@ -149,6 +149,24 @@ const EPIC_HELP = [
   "Progress:",
   "  trekoon epic progress <epic-id>",
   "  Returns done/in_progress/blocked/todo counts, readyCount, and nextCandidate.",
+  "",
+  "Export:",
+  "  trekoon epic export <epic-id> [--path <path>] [--overwrite]",
+  "  Writes a Markdown snapshot of the epic including tasks, subtasks, dependencies,",
+  "  external node stubs, and warnings. The Markdown is a point-in-time artifact;",
+  "  the database remains the source of truth.",
+  "",
+  "  Default path: <worktree-root>/plans/<slugified-title>.md",
+  "  --path <path>  Custom output path (relative or absolute).",
+  "                  With extension (e.g. docs/plan.md): creates that file.",
+  "                  Without extension (e.g. docs/plans): creates the default-named file inside.",
+  "  --overwrite     Resave if the file already exists.",
+  "",
+  "  Examples:",
+  "    trekoon epic export abc-123",
+  "    trekoon epic export abc-123 --path docs/plan.md       # writes docs/plan.md",
+  "    trekoon epic export abc-123 --path docs/plans          # writes docs/plans/<title>.md",
+  "    trekoon epic export abc-123 --overwrite",
 ].join("\n");
 
 const TASK_HELP = [

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",
   "",
@@ -49,6 +59,7 @@ const QUICKSTART_TEXT = [
   "  Bulk update:           trekoon --toon task update --ids id1,id2 --append \"...\" --status in_progress",
   "  Ready queue:           trekoon --toon task ready [--limit <n>] [--epic <id>]",
   "  Next candidate:        trekoon --toon task next [--epic <id>]",
+  "  Export epic to MD:     trekoon --toon epic export <epic-id> [--path <path>] [--overwrite]",
   "",
   "6) List and view defaults",
   "  Default scope: open work (in_progress, todo), limit 10.",
@@ -142,6 +153,7 @@ export async function runQuickstart(_: CliContext): Promise<CliResult> {
         "trekoon --toon task list --status in_progress,todo --limit 20",
         "trekoon --toon task list --cursor <n>",
         "trekoon --toon task update --ids id1,id2 --append \"...\" --status in_progress",
+        "trekoon --toon epic export <epic-id>",
       ],
       machineExamples: [
         "trekoon --toon quickstart",
@@ -156,6 +168,7 @@ export async function runQuickstart(_: CliContext): Promise<CliResult> {
         "trekoon --toon task ready --limit 5",
         "trekoon --toon task next",
         "trekoon --toon dep reverse <task-or-subtask-id>",
+        "trekoon --toon epic export <epic-id>",
       ],
       wipeWarning: {
         command: "trekoon wipe --yes",