trekoon 0.3.7 → 0.3.9

package/src/export/render-markdown.ts

@@ -0,0 +1,256 @@
+import type { ExportBundle, ExportExternalNode, ExportStatusCounts, ExportWarning } from "./types";
+import type { SubtaskRecord, TaskRecord } from "../domain/types";
+
+export function renderMarkdown(bundle: ExportBundle): string {
+  const lines: string[] = [];
+
+  renderFrontmatter(lines, bundle);
+  renderTitle(lines, bundle);
+  renderSummaryTable(lines, bundle);
+  renderDescription(lines, bundle);
+  renderTaskIndex(lines, bundle);
+  renderTaskDetails(lines, bundle);
+  renderDependencies(lines, bundle);
+  renderExternalNodes(lines, bundle);
+  renderWarnings(lines, bundle);
+  renderFooter(lines, bundle);
+
+  return lines.join("\n") + "\n";
+}
+
+// --- Markdown escaping helpers ---
+
+function escapeTableCell(text: string): string {
+  return text.replace(/\|/g, "\\|").replace(/\n/g, " ");
+}
+
+function escapeHeading(text: string): string {
+  return text.replace(/\n/g, " ").replace(/#+\s*/g, "");
+}
+
+function escapeInlineText(text: string): string {
+  return text.replace(/([[\]`*_~])/g, "\\$1").replace(/\n/g, " ");
+}
+
+function escapeBlockText(text: string): string {
+  // Descriptions are rendered as block content; preserve newlines but
+  // ensure lines that start with Markdown structural characters are safe.
+  return text
+    .split("\n")
+    .map((line) => {
+      if (/^#{1,6}\s/.test(line)) return `\\${line}`;
+      if (/^(\s*[-*+]|\s*\d+\.)\s/.test(line)) return line;
+      if (/^\s*\|/.test(line)) return `\\${line}`;
+      return line;
+    })
+    .join("\n");
+}
+
+function formatDescriptionIndented(text: string, indent: string): string {
+  return text
+    .split("\n")
+    .map((line) => `${indent}${line}`)
+    .join("\n");
+}
+
+// --- Render sections ---
+
+function renderFrontmatter(lines: string[], bundle: ExportBundle): void {
+  lines.push("---");
+  lines.push(`epic_id: ${bundle.epic.id}`);
+  lines.push(`schema_version: ${bundle.schemaVersion}`);
+  lines.push(`exported_at: ${new Date(bundle.exportedAt).toISOString()}`);
+  lines.push(`status: ${bundle.epic.status}`);
+  lines.push("---");
+  lines.push("");
+}
+
+function renderTitle(lines: string[], bundle: ExportBundle): void {
+  lines.push(`# ${escapeHeading(bundle.epic.title)}`);
+  lines.push("");
+}
+
+function renderSummaryTable(lines: string[], bundle: ExportBundle): void {
+  lines.push("## Summary");
+  lines.push("");
+  lines.push("| Metric | Count |");
+  lines.push("|--------|-------|");
+  lines.push(`| Tasks | ${bundle.summary.taskCount} |`);
+  lines.push(`| Subtasks | ${bundle.summary.subtaskCount} |`);
+  lines.push(`| Dependencies | ${bundle.summary.dependencyCount} |`);
+  lines.push(`| External nodes | ${bundle.summary.externalNodeCount} |`);
+  lines.push(`| Warnings | ${bundle.summary.warningCount} |`);
+  lines.push("");
+
+  if (bundle.summary.taskCount > 0) {
+    lines.push("### Task status breakdown");
+    lines.push("");
+    renderStatusTable(lines, bundle.summary.taskStatuses);
+    lines.push("");
+  }
+
+  if (bundle.summary.subtaskCount > 0) {
+    lines.push("### Subtask status breakdown");
+    lines.push("");
+    renderStatusTable(lines, bundle.summary.subtaskStatuses);
+    lines.push("");
+  }
+}
+
+function renderStatusTable(lines: string[], counts: ExportStatusCounts): void {
+  lines.push("| Status | Count |");
+  lines.push("|--------|-------|");
+  if (counts.todo > 0) lines.push(`| todo | ${counts.todo} |`);
+  if (counts.inProgress > 0) lines.push(`| in_progress | ${counts.inProgress} |`);
+  if (counts.done > 0) lines.push(`| done | ${counts.done} |`);
+  if (counts.blocked > 0) lines.push(`| blocked | ${counts.blocked} |`);
+  if (counts.other > 0) lines.push(`| other | ${counts.other} |`);
+}
+
+function renderDescription(lines: string[], bundle: ExportBundle): void {
+  if (!bundle.epic.description) return;
+
+  lines.push("## Description");
+  lines.push("");
+  lines.push(escapeBlockText(bundle.epic.description));
+  lines.push("");
+}
+
+function renderTaskIndex(lines: string[], bundle: ExportBundle): void {
+  if (bundle.tasks.length === 0) return;
+
+  lines.push("## Task index");
+  lines.push("");
+  lines.push("| # | Title | Status | Subtasks |");
+  lines.push("|---|-------|--------|----------|");
+
+  for (let i = 0; i < bundle.tasks.length; i++) {
+    const task = bundle.tasks[i];
+    const subtaskCount = bundle.subtasks.filter((s) => s.taskId === task.id).length;
+    const anchor = taskAnchor(task);
+    lines.push(`| ${i + 1} | [${escapeTableCell(escapeInlineText(task.title))}](#${anchor}) | ${task.status} | ${subtaskCount} |`);
+  }
+  lines.push("");
+}
+
+function renderTaskDetails(lines: string[], bundle: ExportBundle): void {
+  if (bundle.tasks.length === 0) return;
+
+  lines.push("## Tasks");
+  lines.push("");
+
+  for (const task of bundle.tasks) {
+    renderSingleTask(lines, task, bundle);
+  }
+}
+
+function renderSingleTask(lines: string[], task: TaskRecord, bundle: ExportBundle): void {
+  lines.push(`### ${escapeHeading(task.title)}`);
+  lines.push("");
+  lines.push(`**ID:** \`${task.id}\`  `);
+  lines.push(`**Status:** ${task.status}  `);
+  if (task.owner) {
+    lines.push(`**Owner:** ${escapeInlineText(task.owner)}  `);
+  }
+  lines.push("");
+
+  if (task.description) {
+    lines.push(escapeBlockText(task.description));
+    lines.push("");
+  }
+
+  const blockedBy = bundle.blockedBy.get(task.id) ?? [];
+  if (blockedBy.length > 0) {
+    lines.push("**Blocked by:**");
+    for (const depId of blockedBy) {
+      lines.push(`- \`${depId}\``);
+    }
+    lines.push("");
+  }
+
+  const blocks = bundle.blocks.get(task.id) ?? [];
+  if (blocks.length > 0) {
+    lines.push("**Blocks:**");
+    for (const depId of blocks) {
+      lines.push(`- \`${depId}\``);
+    }
+    lines.push("");
+  }
+
+  const subtasks = bundle.subtasks.filter((s) => s.taskId === task.id);
+  if (subtasks.length > 0) {
+    lines.push("#### Subtasks");
+    lines.push("");
+    for (const subtask of subtasks) {
+      renderSingleSubtask(lines, subtask, bundle);
+    }
+  }
+}
+
+function renderSingleSubtask(lines: string[], subtask: SubtaskRecord, bundle: ExportBundle): void {
+  const statusIcon = subtask.status === "done" ? "x" : " ";
+  lines.push(`- [${statusIcon}] **${escapeInlineText(subtask.title)}** — \`${subtask.id}\` (${subtask.status})`);
+
+  if (subtask.description) {
+    lines.push(formatDescriptionIndented(escapeBlockText(subtask.description), "  "));
+  }
+
+  const blockedBy = bundle.blockedBy.get(subtask.id) ?? [];
+  if (blockedBy.length > 0) {
+    lines.push(`  Blocked by: ${blockedBy.map((id) => `\`${id}\``).join(", ")}`);
+  }
+}
+
+function renderDependencies(lines: string[], bundle: ExportBundle): void {
+  if (bundle.dependencies.length === 0) return;
+
+  lines.push("");
+  lines.push("## Dependencies");
+  lines.push("");
+  lines.push("| Source | Depends on | Type |");
+  lines.push("|--------|------------|------|");
+
+  for (const dep of bundle.dependencies) {
+    const type = dep.internal ? "internal" : "external";
+    lines.push(`| \`${dep.sourceId}\` (${dep.sourceKind}) | \`${dep.dependsOnId}\` (${dep.dependsOnKind}) | ${type} |`);
+  }
+  lines.push("");
+}
+
+function renderExternalNodes(lines: string[], bundle: ExportBundle): void {
+  if (bundle.externalNodes.length === 0) return;
+
+  lines.push("## External nodes");
+  lines.push("");
+  lines.push("These nodes belong to other epics but are referenced by dependencies in this epic.");
+  lines.push("");
+  lines.push("| ID | Kind | Title | Status | Epic ID |");
+  lines.push("|----|------|-------|--------|---------|");
+
+  for (const node of bundle.externalNodes) {
+    const title = node.title !== null ? escapeTableCell(node.title) : "—";
+    lines.push(`| \`${node.id}\` | ${node.kind} | ${title} | ${node.status ?? "—"} | ${node.epicId ?? "—"} |`);
+  }
+  lines.push("");
+}
+
+function renderWarnings(lines: string[], bundle: ExportBundle): void {
+  if (bundle.warnings.length === 0) return;
+
+  lines.push("## Warnings");
+  lines.push("");
+  for (const warning of bundle.warnings) {
+    lines.push(`- **${escapeInlineText(warning.code)}**: ${escapeInlineText(warning.message)}`);
+  }
+  lines.push("");
+}
+
+function renderFooter(lines: string[], bundle: ExportBundle): void {
+  lines.push("---");
+  lines.push("");
+  lines.push(`*Exported from Trekoon on ${new Date(bundle.exportedAt).toISOString()}. This is a snapshot — the database is the source of truth.*`);
+}
+
+function taskAnchor(task: TaskRecord): string {
+  return `task-${task.id}`;
+}

package/src/export/types.ts

@@ -0,0 +1,61 @@
+import type { DependencyRecord, EpicRecord, SubtaskRecord, TaskRecord } from "../domain/types";
+
+export const EXPORT_SCHEMA_VERSION = 1;
+
+export type ExportNodeKind = "task" | "subtask";
+
+export interface ExportDependencyEdge {
+  readonly id: string;
+  readonly sourceId: string;
+  readonly sourceKind: ExportNodeKind;
+  readonly dependsOnId: string;
+  readonly dependsOnKind: ExportNodeKind;
+  readonly internal: boolean;
+}
+
+export interface ExportExternalNode {
+  readonly id: string;
+  readonly kind: ExportNodeKind;
+  readonly title: string | null;
+  readonly status: string | null;
+  readonly epicId: string | null;
+}
+
+export interface ExportWarning {
+  readonly code: string;
+  readonly message: string;
+  readonly entityId?: string;
+}
+
+export interface ExportStatusCounts {
+  readonly total: number;
+  readonly todo: number;
+  readonly inProgress: number;
+  readonly done: number;
+  readonly blocked: number;
+  readonly other: number;
+}
+
+export interface ExportSummary {
+  readonly taskCount: number;
+  readonly subtaskCount: number;
+  readonly dependencyCount: number;
+  readonly externalNodeCount: number;
+  readonly warningCount: number;
+  readonly taskStatuses: ExportStatusCounts;
+  readonly subtaskStatuses: ExportStatusCounts;
+}
+
+export interface ExportBundle {
+  readonly schemaVersion: number;
+  readonly exportedAt: number;
+  readonly epic: EpicRecord;
+  readonly tasks: readonly TaskRecord[];
+  readonly subtasks: readonly SubtaskRecord[];
+  readonly dependencies: readonly ExportDependencyEdge[];
+  readonly externalNodes: readonly ExportExternalNode[];
+  readonly blockedBy: ReadonlyMap<string, readonly string[]>;
+  readonly blocks: ReadonlyMap<string, readonly string[]>;
+  readonly warnings: readonly ExportWarning[];
+  readonly summary: ExportSummary;
+}

package/src/export/write.ts

@@ -0,0 +1,97 @@
+import { mkdirSync, openSync, renameSync, unlinkSync, writeSync, closeSync, constants } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+
+export interface WriteResult {
+  readonly path: string;
+  readonly overwritten: boolean;
+}
+
+export function atomicWrite(options: {
+  readonly path: string;
+  readonly content: string;
+  readonly overwrite: boolean;
+}): WriteResult {
+  const dir = dirname(options.path);
+  mkdirSync(dir, { recursive: true });
+
+  if (options.overwrite) {
+    return writeViaTempRename(options.path, options.content);
+  }
+
+  return writeExclusive(options.path, options.content);
+}
+
+function writeViaTempRename(targetPath: string, content: string): WriteResult {
+  const dir = dirname(targetPath);
+  const tempPath = resolve(dir, `.export-${randomUUID()}.tmp`);
+  let overwritten = false;
+
+  try {
+    // Probe whether the target already exists by attempting an exclusive open.
+    // If it succeeds, the file didn't exist, so we close and remove that probe
+    // since we'll write via temp+rename anyway for atomicity.
+    try {
+      const probeFd = openSync(targetPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL);
+      closeSync(probeFd);
+      unlinkSync(targetPath);
+      overwritten = false;
+    } catch {
+      overwritten = true;
+    }
+
+    const fd = openSync(tempPath, constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC);
+    try {
+      writeSync(fd, content);
+    } finally {
+      closeSync(fd);
+    }
+    renameSync(tempPath, targetPath);
+  } catch (error) {
+    try { unlinkSync(tempPath); } catch { /* best-effort cleanup */ }
+    throw error;
+  }
+
+  return { path: targetPath, overwritten };
+}
+
+function writeExclusive(targetPath: string, content: string): WriteResult {
+  // O_CREAT | O_EXCL is atomic: the kernel fails if the file already exists.
+  let fd: number;
+  try {
+    fd = openSync(targetPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL);
+  } catch (error: unknown) {
+    if (isFileExistsError(error)) {
+      throw new ExportWriteError(
+        `File already exists: ${targetPath}. Use --overwrite to resave.`,
+        "file_exists",
+      );
+    }
+    throw error;
+  }
+
+  try {
+    writeSync(fd, content);
+  } finally {
+    closeSync(fd);
+  }
+
+  return { path: targetPath, overwritten: false };
+}
+
+function isFileExistsError(error: unknown): boolean {
+  if (typeof error === "object" && error !== null && "code" in error) {
+    return (error as { code: string }).code === "EEXIST";
+  }
+  return false;
+}
+
+export class ExportWriteError extends Error {
+  readonly code: string;
+
+  constructor(message: string, code: string) {
+    super(message);
+    this.name = "ExportWriteError";
+    this.code = code;
+  }
+}

package/src/storage/migrations.ts

@@ -105,6 +105,14 @@ const BOARD_IDEMPOTENCY_MIGRATION_DOWN_STATEMENTS: readonly string[] = [
   "DROP TABLE IF EXISTS board_idempotency_keys;",
 ];
 
+const BOARD_IDEMPOTENCY_RETENTION_INDEX_UP_STATEMENTS: readonly string[] = [
+  "CREATE INDEX IF NOT EXISTS idx_board_idempotency_state_created_at ON board_idempotency_keys(state, created_at);",
+];
+
+const BOARD_IDEMPOTENCY_RETENTION_INDEX_DOWN_STATEMENTS: readonly string[] = [
+  "DROP INDEX IF EXISTS idx_board_idempotency_state_created_at;",
+];
+
 function tableHasColumn(db: Database, tableName: string, columnName: string): boolean {
   const columns = db.query(`PRAGMA table_info(${tableName});`).all() as Array<{ name: string }>;
   return columns.some((column) => column.name === columnName);
@@ -359,6 +367,20 @@ const MIGRATIONS: readonly Migration[] = [
       }
     },
   },
+  {
+    version: 10,
+    name: "0010_board_idempotency_retention_index",
+    up(db: Database): void {
+      for (const statement of BOARD_IDEMPOTENCY_RETENTION_INDEX_UP_STATEMENTS) {
+        db.exec(statement);
+      }
+    },
+    down(db: Database): void {
+      for (const statement of BOARD_IDEMPOTENCY_RETENTION_INDEX_DOWN_STATEMENTS) {
+        db.exec(statement);
+      }
+    },
+  },
 ];
 
 function migrationTableExists(db: Database): boolean {
@@ -557,6 +579,11 @@ export function migrateDatabase(db: Database): void {
     ensureMigrationTable(db);
     ensureMigrationVersionColumn(db);
 
+    // Backfill the legacy board_idempotency_keys.state column before running
+    // any migrations so that later migrations (e.g. 0010's state-scoped index)
+    // can assume the column exists on databases whose 0009 predates it.
+    migrateBoardIdempotencyState(db);
+
     const version: number = currentVersion(db);
 
     for (const migration of MIGRATIONS) {
@@ -567,8 +594,6 @@ export function migrateDatabase(db: Database): void {
       migration.up(db);
       recordMigration(db, migration);
     }
-
-    migrateBoardIdempotencyState(db);
   });
 }
 

package/src/storage/schema.ts

@@ -1,4 +1,4 @@
-export const SCHEMA_VERSION = 2;
+export const SCHEMA_VERSION = 3;
 
 export const BASE_SCHEMA_STATEMENTS: readonly string[] = [
   `PRAGMA foreign_keys = ON;`,
@@ -137,4 +137,5 @@ export const BASE_SCHEMA_STATEMENTS: readonly string[] = [
   `CREATE INDEX IF NOT EXISTS idx_conflicts_resolution ON sync_conflicts(resolution);`,
   `CREATE INDEX IF NOT EXISTS idx_conflicts_resolution_entity_field_id ON sync_conflicts(resolution, entity_id, field_name, id);`,
   `CREATE INDEX IF NOT EXISTS idx_board_idempotency_created_at ON board_idempotency_keys(created_at);`,
+  `CREATE INDEX IF NOT EXISTS idx_board_idempotency_state_created_at ON board_idempotency_keys(state, created_at);`,
 ];

package/src/sync/event-writes.ts

@@ -38,18 +38,22 @@ export function nextEventTimestamp(db: Database): number {
   return Math.max(now, latestEvent.created_at + 1);
 }
 
-export function withTransactionEventContext<T>(db: Database, cwd: string, fn: () => T): T {
-  const existingContext: EventWriteContext | undefined = transactionEventContexts.get(db);
-  if (existingContext) {
-    return fn();
-  }
-
+export function prepareEventWriteContext(db: Database, cwd: string): EventWriteContext {
   const nextTimestamp: number = nextEventTimestamp(db);
   const git: ResolvedGitContext = resolveGitContext(cwd, nextTimestamp);
-  const context: EventWriteContext = {
+
+  return {
     git,
     nextTimestamp,
   };
+}
+
+export function withTransactionEventContext<T>(db: Database, context: EventWriteContext, fn: () => T): T {
+  const existingContext: EventWriteContext | undefined = transactionEventContexts.get(db);
+  if (existingContext) {
+    return fn();
+  }
+
   transactionEventContexts.set(db, context);
 
   try {