trekoon 0.3.7 → 0.3.9

package/src/domain/mutation-service.ts

@@ -1,7 +1,7 @@
 import { type Database } from "bun:sqlite";
 
 import { writeTransaction } from "../storage/database";
-import { appendEventWithGitContext, withTransactionEventContext } from "../sync/event-writes";
+import { appendEventWithGitContext, prepareEventWriteContext, withTransactionEventContext } from "../sync/event-writes";
 import { ENTITY_OPERATIONS } from "./mutation-operations";
 import { TrackerDomain, validateStatusTransition } from "./tracker-domain";
 import {
@@ -49,6 +49,8 @@ type AtomicIdempotentMutationResult =
   | AtomicIdempotencyReplayResult
   | AtomicIdempotencyCompletedResult;
 
+const BOARD_IDEMPOTENCY_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+
 function countMatches(value: string, searchText: string): number {
   if (searchText.length === 0) {
     return 0;
@@ -128,7 +130,49 @@ export class MutationService {
   }
 
   #writeTransaction<T>(fn: () => T): T {
-    return writeTransaction(this.#db, (): T => withTransactionEventContext(this.#db, this.#cwd, fn));
+    const eventContext = prepareEventWriteContext(this.#db, this.#cwd);
+    return writeTransaction(this.#db, (): T => withTransactionEventContext(this.#db, eventContext, fn));
+  }
+
+  #dependencyEventEntityId(input: {
+    sourceId: string;
+    sourceKind: string;
+    dependsOnId: string;
+    dependsOnKind: string;
+  }): string {
+    return `${input.sourceKind}:${input.sourceId}->${input.dependsOnKind}:${input.dependsOnId}`;
+  }
+
+  #dependencyEventFields(input: {
+    dependencyId?: string | undefined;
+    sourceId: string;
+    sourceKind?: string | undefined;
+    dependsOnId: string;
+    dependsOnKind?: string | undefined;
+    sourceEventId?: string | undefined;
+  }): Record<string, string> {
+    const fields: Record<string, string> = {
+      source_id: input.sourceId,
+      depends_on_id: input.dependsOnId,
+    };
+
+    if (input.dependencyId) {
+      fields.dependency_id = input.dependencyId;
+    }
+
+    if (input.sourceKind) {
+      fields.source_kind = input.sourceKind;
+    }
+
+    if (input.dependsOnKind) {
+      fields.depends_on_kind = input.dependsOnKind;
+    }
+
+    if (input.sourceEventId) {
+      fields.source_event_id = input.sourceEventId;
+    }
+
+    return fields;
   }
 
   createEpic(input: { title: string; description: string; status?: string | undefined }): EpicRecord {
@@ -185,12 +229,18 @@ export class MutationService {
       }
 
       for (const dependency of created.dependencies) {
-        this.#appendEntityEvent("dependency", dependency.id, ENTITY_OPERATIONS.dependency.added, {
-          source_id: dependency.sourceId,
-          source_kind: dependency.sourceKind,
-          depends_on_id: dependency.dependsOnId,
-          depends_on_kind: dependency.dependsOnKind,
-        });
+        this.#appendEntityEvent(
+          "dependency",
+          this.#dependencyEventEntityId(dependency),
+          ENTITY_OPERATIONS.dependency.added,
+          this.#dependencyEventFields({
+            dependencyId: dependency.id,
+            sourceId: dependency.sourceId,
+            sourceKind: dependency.sourceKind,
+            dependsOnId: dependency.dependsOnId,
+            dependsOnKind: dependency.dependsOnKind,
+          }),
+        );
       }
 
       return {
@@ -293,12 +343,18 @@ export class MutationService {
       }
 
       for (const dependency of created.dependencies) {
-        this.#appendEntityEvent("dependency", dependency.id, ENTITY_OPERATIONS.dependency.added, {
-          source_id: dependency.sourceId,
-          source_kind: dependency.sourceKind,
-          depends_on_id: dependency.dependsOnId,
-          depends_on_kind: dependency.dependsOnKind,
-        });
+        this.#appendEntityEvent(
+          "dependency",
+          this.#dependencyEventEntityId(dependency),
+          ENTITY_OPERATIONS.dependency.added,
+          this.#dependencyEventFields({
+            dependencyId: dependency.id,
+            sourceId: dependency.sourceId,
+            sourceKind: dependency.sourceKind,
+            dependsOnId: dependency.dependsOnId,
+            dependsOnKind: dependency.dependsOnKind,
+          }),
+        );
       }
 
       return created;
@@ -349,16 +405,19 @@ export class MutationService {
       }
 
       for (const dependency of plan.touchingDependencies) {
-        this.#appendEntityEvent(
-          "dependency",
-          `${dependency.sourceId}->${dependency.dependsOnId}`,
-          ENTITY_OPERATIONS.dependency.removed,
-          {
-            source_id: dependency.sourceId,
-            depends_on_id: dependency.dependsOnId,
-            source_event_id: taskDeleteEventId,
-          },
-        );
+          this.#appendEntityEvent(
+            "dependency",
+            this.#dependencyEventEntityId(dependency),
+            ENTITY_OPERATIONS.dependency.removed,
+            this.#dependencyEventFields({
+              dependencyId: dependency.id,
+              sourceId: dependency.sourceId,
+              sourceKind: dependency.sourceKind,
+              dependsOnId: dependency.dependsOnId,
+              dependsOnKind: dependency.dependsOnKind,
+              sourceEventId: taskDeleteEventId,
+            }),
+          );
       }
 
       return {
@@ -454,13 +513,16 @@ export class MutationService {
       for (const dependency of touchingDependencies) {
         this.#appendEntityEvent(
           "dependency",
-          `${dependency.sourceId}->${dependency.dependsOnId}`,
+          this.#dependencyEventEntityId(dependency),
           ENTITY_OPERATIONS.dependency.removed,
-          {
-            source_id: dependency.sourceId,
-            depends_on_id: dependency.dependsOnId,
-            source_event_id: subtaskDeleteEventId,
-          },
+          this.#dependencyEventFields({
+            dependencyId: dependency.id,
+            sourceId: dependency.sourceId,
+            sourceKind: dependency.sourceKind,
+            dependsOnId: dependency.dependsOnId,
+            dependsOnKind: dependency.dependsOnKind,
+            sourceEventId: subtaskDeleteEventId,
+          }),
         );
       }
       return {
@@ -489,13 +551,16 @@ export class MutationService {
       for (const dependency of touchingDependencies) {
         this.#appendEntityEvent(
           "dependency",
-          `${dependency.sourceId}->${dependency.dependsOnId}`,
+          this.#dependencyEventEntityId(dependency),
           ENTITY_OPERATIONS.dependency.removed,
-          {
-            source_id: dependency.sourceId,
-            depends_on_id: dependency.dependsOnId,
-            source_event_id: subtaskDeleteEventId,
-          },
+          this.#dependencyEventFields({
+            dependencyId: dependency.id,
+            sourceId: dependency.sourceId,
+            sourceKind: dependency.sourceKind,
+            dependsOnId: dependency.dependsOnId,
+            dependsOnKind: dependency.dependsOnKind,
+            sourceEventId: subtaskDeleteEventId,
+          }),
         );
       }
 
@@ -516,12 +581,18 @@ export class MutationService {
   addDependency(sourceId: string, dependsOnId: string): DependencyRecord {
     return this.#writeTransaction((): DependencyRecord => {
       const dependency = this.#domain.addDependency(sourceId, dependsOnId);
-      this.#appendEntityEvent("dependency", dependency.id, ENTITY_OPERATIONS.dependency.added, {
-        source_id: dependency.sourceId,
-        source_kind: dependency.sourceKind,
-        depends_on_id: dependency.dependsOnId,
-        depends_on_kind: dependency.dependsOnKind,
-      });
+      this.#appendEntityEvent(
+        "dependency",
+        this.#dependencyEventEntityId(dependency),
+        ENTITY_OPERATIONS.dependency.added,
+        this.#dependencyEventFields({
+          dependencyId: dependency.id,
+          sourceId: dependency.sourceId,
+          sourceKind: dependency.sourceKind,
+          dependsOnId: dependency.dependsOnId,
+          dependsOnKind: dependency.dependsOnKind,
+        }),
+      );
       return dependency;
     });
   }
@@ -534,12 +605,18 @@ export class MutationService {
   }): AtomicIdempotentMutationResult {
     return this.#completeAtomicIdempotentMutation(input.claim, (): AtomicIdempotencyCompletedResult => {
       const dependency = this.#domain.addDependency(input.sourceId, input.dependsOnId);
-      this.#appendEntityEvent("dependency", dependency.id, ENTITY_OPERATIONS.dependency.added, {
-        source_id: dependency.sourceId,
-        source_kind: dependency.sourceKind,
-        depends_on_id: dependency.dependsOnId,
-        depends_on_kind: dependency.dependsOnKind,
-      });
+      this.#appendEntityEvent(
+        "dependency",
+        this.#dependencyEventEntityId(dependency),
+        ENTITY_OPERATIONS.dependency.added,
+        this.#dependencyEventFields({
+          dependencyId: dependency.id,
+          sourceId: dependency.sourceId,
+          sourceKind: dependency.sourceKind,
+          dependsOnId: dependency.dependsOnId,
+          dependsOnKind: dependency.dependsOnKind,
+        }),
+      );
       return {
         state: "completed",
         status: 201,
@@ -552,12 +629,18 @@ export class MutationService {
     return this.#writeTransaction((): CompactDependencyBatchAddResult => {
       const created = this.#domain.addDependencyBatch(input);
       for (const dependency of created.dependencies) {
-        this.#appendEntityEvent("dependency", dependency.id, ENTITY_OPERATIONS.dependency.added, {
-          source_id: dependency.sourceId,
-          source_kind: dependency.sourceKind,
-          depends_on_id: dependency.dependsOnId,
-          depends_on_kind: dependency.dependsOnKind,
-        });
+        this.#appendEntityEvent(
+          "dependency",
+          this.#dependencyEventEntityId(dependency),
+          ENTITY_OPERATIONS.dependency.added,
+          this.#dependencyEventFields({
+            dependencyId: dependency.id,
+            sourceId: dependency.sourceId,
+            sourceKind: dependency.sourceKind,
+            dependsOnId: dependency.dependsOnId,
+            dependsOnKind: dependency.dependsOnKind,
+          }),
+        );
       }
       return created;
     });
@@ -565,12 +648,22 @@ export class MutationService {
 
   removeDependency(sourceId: string, dependsOnId: string): number {
     return this.#writeTransaction((): number => {
+      const existingDependency = this.#domain.listDependencies(sourceId)
+        .find((dependency) => dependency.dependsOnId === dependsOnId);
       const removed = this.#domain.removeDependency(sourceId, dependsOnId);
       if (removed > 0) {
-        this.#appendEntityEvent("dependency", `${sourceId}->${dependsOnId}`, ENTITY_OPERATIONS.dependency.removed, {
-          source_id: sourceId,
-          depends_on_id: dependsOnId,
-        });
+        this.#appendEntityEvent("dependency", this.#dependencyEventEntityId({
+          sourceId,
+          sourceKind: existingDependency?.sourceKind ?? "task",
+          dependsOnId,
+          dependsOnKind: existingDependency?.dependsOnKind ?? "task",
+        }), ENTITY_OPERATIONS.dependency.removed, this.#dependencyEventFields({
+          dependencyId: existingDependency?.id,
+          sourceId,
+          sourceKind: existingDependency?.sourceKind,
+          dependsOnId,
+          dependsOnKind: existingDependency?.dependsOnKind,
+        }));
       }
       return removed;
     });
@@ -589,9 +682,10 @@ export class MutationService {
     }) => Record<string, unknown>;
   }): AtomicIdempotentMutationResult {
     return this.#completeAtomicIdempotentMutation(input.claim, (): AtomicIdempotencyCompletedResult => {
-      const existingDependencyIds = this.#domain.listDependencies(input.sourceId)
-        .filter((dependency) => dependency.dependsOnId === input.dependsOnId)
-        .map((dependency) => dependency.id);
+      const existingDependencies = this.#domain.listDependencies(input.sourceId)
+        .filter((dependency) => dependency.dependsOnId === input.dependsOnId);
+      const existingDependencyIds = existingDependencies.map((dependency) => dependency.id);
+      const existingDependency = existingDependencies[0];
       const removed = this.#domain.removeDependency(input.sourceId, input.dependsOnId);
       if (removed === 0) {
         throw new DomainError({
@@ -603,10 +697,18 @@ export class MutationService {
           },
         });
       }
-      this.#appendEntityEvent("dependency", `${input.sourceId}->${input.dependsOnId}`, ENTITY_OPERATIONS.dependency.removed, {
-        source_id: input.sourceId,
-        depends_on_id: input.dependsOnId,
-      });
+      this.#appendEntityEvent("dependency", this.#dependencyEventEntityId({
+        sourceId: input.sourceId,
+        sourceKind: existingDependency?.sourceKind ?? "task",
+        dependsOnId: input.dependsOnId,
+        dependsOnKind: existingDependency?.dependsOnKind ?? "task",
+      }), ENTITY_OPERATIONS.dependency.removed, this.#dependencyEventFields({
+        dependencyId: existingDependency?.id,
+        sourceId: input.sourceId,
+        sourceKind: existingDependency?.sourceKind,
+        dependsOnId: input.dependsOnId,
+        dependsOnKind: existingDependency?.dependsOnKind,
+      }));
       return {
         state: "completed",
         status: 200,
@@ -741,6 +843,7 @@ export class MutationService {
     mutate: () => AtomicIdempotencyCompletedResult,
   ): AtomicIdempotentMutationResult {
     return this.#writeTransaction((): AtomicIdempotentMutationResult => {
+      this.#pruneExpiredIdempotencyKeys();
       const inserted = this.#db.query(
         `
         INSERT INTO board_idempotency_keys (
@@ -816,6 +919,17 @@ export class MutationService {
     });
   }
 
+  #pruneExpiredIdempotencyKeys(now: number = Date.now()): void {
+    const cutoff: number = now - BOARD_IDEMPOTENCY_RETENTION_MS;
+    this.#db.query(
+      `
+      DELETE FROM board_idempotency_keys
+      WHERE state = 'completed'
+        AND created_at < ?;
+      `,
+    ).run(cutoff);
+  }
+
   #previewScopeReplacement(
     nodes: readonly SearchNode[],
     searchText: string,

package/src/domain/tracker-domain.ts

@@ -165,6 +165,20 @@ function normalizeSubtaskDescription(value: string | undefined): string {
   return value.trim();
 }
 
+function normalizeOwner(value: string | null | undefined): string | null | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  if (value === null) {
+    return null;
+  }
+
+  const normalized = value.trim()
+  ;
+  return normalized.length > 0 ? normalized : null;
+}
+
 function isValidStatus(status: string): status is ValidStatus {
   return (VALID_STATUSES as readonly string[]).includes(status);
 }
@@ -526,7 +540,7 @@ export class TrackerDomain {
     const nextDescription: string =
       input.description !== undefined ? assertNonEmpty("description", input.description) : existing.description;
     const nextStatus: string = input.status !== undefined ? assertNonEmpty("status", input.status) : existing.status;
-    const nextOwner: string | null = input.owner !== undefined ? input.owner : existing.owner;
+    const nextOwner: string | null = input.owner !== undefined ? normalizeOwner(input.owner) ?? null : existing.owner;
     this.assertNoUnresolvedDependenciesForStatusTransition(id, "task", existing.status, nextStatus);
     const now: number = Date.now();
 
@@ -777,7 +791,7 @@ export class TrackerDomain {
     const nextDescription: string =
       input.description !== undefined ? normalizeSubtaskDescription(input.description) : existing.description;
     const nextStatus: string = input.status !== undefined ? assertNonEmpty("status", input.status) : existing.status;
-    const nextOwner: string | null = input.owner !== undefined ? input.owner : existing.owner;
+    const nextOwner: string | null = input.owner !== undefined ? normalizeOwner(input.owner) ?? null : existing.owner;
     this.assertNoUnresolvedDependenciesForStatusTransition(id, "subtask", existing.status, nextStatus);
     const now: number = Date.now();
 

package/src/export/build-epic-export-bundle.ts

@@ -0,0 +1,178 @@
+import type { TrackerDomain } from "../domain/tracker-domain";
+import type { DependencyRecord, SubtaskRecord, TaskRecord } from "../domain/types";
+
+import {
+  EXPORT_SCHEMA_VERSION,
+  type ExportBundle,
+  type ExportDependencyEdge,
+  type ExportExternalNode,
+  type ExportStatusCounts,
+  type ExportSummary,
+  type ExportWarning,
+} from "./types";
+
+function countStatuses(records: readonly { readonly status: string }[]): ExportStatusCounts {
+  const counts = { total: records.length, todo: 0, inProgress: 0, done: 0, blocked: 0, other: 0 };
+  for (const record of records) {
+    if (record.status === "todo") counts.todo += 1;
+    else if (record.status === "in_progress") counts.inProgress += 1;
+    else if (record.status === "done") counts.done += 1;
+    else if (record.status === "blocked") counts.blocked += 1;
+    else counts.other += 1;
+  }
+  return counts;
+}
+
+export function buildEpicExportBundle(domain: TrackerDomain, epicId: string): ExportBundle {
+  const epic = domain.getEpicOrThrow(epicId);
+  const tasks: readonly TaskRecord[] = domain.listTasks(epicId);
+  const taskIds = new Set(tasks.map((t) => t.id));
+
+  const subtasksByTaskId = domain.listSubtasksByTaskIds(tasks.map((t) => t.id));
+  const allSubtasks: SubtaskRecord[] = [];
+  for (const task of tasks) {
+    for (const subtask of subtasksByTaskId.get(task.id) ?? []) {
+      allSubtasks.push(subtask);
+    }
+  }
+  const subtaskIds = new Set(allSubtasks.map((s) => s.id));
+
+  const inScopeIds = new Set([...taskIds, ...subtaskIds]);
+
+  // Gather all dependencies touching any in-scope node
+  const sourceIds = [...inScopeIds];
+  const dependenciesBySourceId = domain.listDependenciesBySourceIds(sourceIds);
+  const allRawDeps: DependencyRecord[] = [];
+  const seenDepIds = new Set<string>();
+  for (const deps of dependenciesBySourceId.values()) {
+    for (const dep of deps) {
+      if (!seenDepIds.has(dep.id)) {
+        seenDepIds.add(dep.id);
+        allRawDeps.push(dep);
+      }
+    }
+  }
+
+  // Also find dependencies where in-scope nodes are the target (dependsOnId)
+  // by checking each in-scope node with listDependenciesTouchingNode
+  // We use a more efficient approach: query dependencies where dependsOnId is in scope
+  for (const nodeId of inScopeIds) {
+    const touching = domain.listDependenciesTouchingNode(nodeId);
+    for (const dep of touching) {
+      if (!seenDepIds.has(dep.id)) {
+        seenDepIds.add(dep.id);
+        allRawDeps.push(dep);
+      }
+    }
+  }
+
+  // Sort for stable ordering
+  allRawDeps.sort((a, b) => a.createdAt - b.createdAt || a.id.localeCompare(b.id));
+
+  // Classify edges and build dependency indexes
+  const blockedByMap = new Map<string, string[]>();
+  const blocksMap = new Map<string, string[]>();
+  const externalNodeMap = new Map<string, ExportExternalNode>();
+  const warnings: ExportWarning[] = [];
+
+  const edges: ExportDependencyEdge[] = allRawDeps.map((dep) => {
+    const sourceInternal = inScopeIds.has(dep.sourceId);
+    const targetInternal = inScopeIds.has(dep.dependsOnId);
+    const internal = sourceInternal && targetInternal;
+
+    // Build blockedBy: source is blocked by dependsOn
+    if (sourceInternal) {
+      const existing = blockedByMap.get(dep.sourceId) ?? [];
+      existing.push(dep.dependsOnId);
+      blockedByMap.set(dep.sourceId, existing);
+    }
+
+    // Build blocks: dependsOn blocks source
+    if (targetInternal) {
+      const existing = blocksMap.get(dep.dependsOnId) ?? [];
+      existing.push(dep.sourceId);
+      blocksMap.set(dep.dependsOnId, existing);
+    }
+
+    // Resolve external nodes
+    if (!sourceInternal && !externalNodeMap.has(dep.sourceId)) {
+      externalNodeMap.set(dep.sourceId, resolveExternalNode(domain, dep.sourceId, dep.sourceKind));
+    }
+    if (!targetInternal && !externalNodeMap.has(dep.dependsOnId)) {
+      externalNodeMap.set(dep.dependsOnId, resolveExternalNode(domain, dep.dependsOnId, dep.dependsOnKind));
+    }
+
+    return {
+      id: dep.id,
+      sourceId: dep.sourceId,
+      sourceKind: dep.sourceKind,
+      dependsOnId: dep.dependsOnId,
+      dependsOnKind: dep.dependsOnKind,
+      internal,
+    };
+  });
+
+  const externalNodes = [...externalNodeMap.values()].sort((a, b) => a.id.localeCompare(b.id));
+
+  // Check for orphaned dependency references
+  for (const node of externalNodes) {
+    if (node.title === null) {
+      warnings.push({
+        code: "orphaned_external_node",
+        message: `External ${node.kind} ${node.id} referenced by a dependency but not found in the database`,
+        entityId: node.id,
+      });
+    }
+  }
+
+  const summary: ExportSummary = {
+    taskCount: tasks.length,
+    subtaskCount: allSubtasks.length,
+    dependencyCount: edges.length,
+    externalNodeCount: externalNodes.length,
+    warningCount: warnings.length,
+    taskStatuses: countStatuses(tasks),
+    subtaskStatuses: countStatuses(allSubtasks),
+  };
+
+  return {
+    schemaVersion: EXPORT_SCHEMA_VERSION,
+    exportedAt: Date.now(),
+    epic,
+    tasks,
+    subtasks: allSubtasks,
+    dependencies: edges,
+    externalNodes,
+    blockedBy: blockedByMap,
+    blocks: blocksMap,
+    warnings,
+    summary,
+  };
+}
+
+function resolveExternalNode(
+  domain: TrackerDomain,
+  id: string,
+  kind: "task" | "subtask",
+): ExportExternalNode {
+  if (kind === "task") {
+    const task = domain.getTask(id);
+    if (task) {
+      return { id, kind: "task", title: task.title, status: task.status, epicId: task.epicId };
+    }
+  } else {
+    const subtask = domain.getSubtask(id);
+    if (subtask) {
+      const task = domain.getTask(subtask.taskId);
+      return {
+        id,
+        kind: "subtask",
+        title: subtask.title,
+        status: subtask.status,
+        epicId: task?.epicId ?? null,
+      };
+    }
+  }
+
+  return { id, kind, title: null, status: null, epicId: null };
+}

package/src/export/path.ts

@@ -0,0 +1,48 @@
+import { extname, isAbsolute, resolve } from "node:path";
+
+const PLANS_DIRNAME = "plans";
+
+function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, "")
+    .replace(/\s+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "")
+    .slice(0, 80);
+}
+
+function defaultFilename(epicTitle: string, epicId: string): string {
+  const slug = slugify(epicTitle) || epicId;
+  return `${slug}.md`;
+}
+
+function looksLikeFilePath(path: string): boolean {
+  return extname(path) !== "";
+}
+
+export function resolveExportPath(options: {
+  readonly customPath: string | undefined;
+  readonly epicId: string;
+  readonly epicTitle: string;
+  readonly worktreeRoot: string;
+  readonly cwd: string;
+}): string {
+  const filename = defaultFilename(options.epicTitle, options.epicId);
+
+  if (!options.customPath) {
+    return resolve(options.worktreeRoot, PLANS_DIRNAME, filename);
+  }
+
+  const resolved = isAbsolute(options.customPath)
+    ? options.customPath
+    : resolve(options.cwd, options.customPath);
+
+  // If the path has a file extension, treat it as a file path.
+  // Otherwise treat it as a directory and place the default-named file inside.
+  if (looksLikeFilePath(resolved)) {
+    return resolved;
+  }
+
+  return resolve(resolved, filename);
+}