trekoon 0.3.7 → 0.3.9

package/docs/commands.md

@@ -202,6 +202,24 @@ trekoon epic progress <epic-id>
 Returns status counts (`total`, `doneCount`, `inProgressCount`, `blockedCount`,
 `todoCount`), `readyCount`, and `nextCandidate`.
 
+## Epic export
+
+```bash
+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 output is a point-in-time artifact; the
+database remains the source of truth.
+
+- Default path: `<worktree-root>/plans/<slugified-title>.md`
+- `--path` with a file extension (e.g. `docs/plan.md`) creates that exact file
+- `--path` without an extension (e.g. `docs/plans`) creates the default-named file inside that directory
+- `--overwrite` resaves when the file already exists
+
+Returns `epicId`, `path`, `overwritten`, and `summary` counts in structured
+output.
+
 ## Session scoping
 
 ```bash

package/docs/quickstart.md

@@ -2,6 +2,27 @@
 
 Shortest path from zero to a working Trekoon workflow.
 
+## Recommended human workflow
+
+If you are driving Trekoon with an AI agent, the usual path is:
+
+```bash
+trekoon plan <goal>
+trekoon <epic-id>
+trekoon <epic-id> execute
+```
+
+- Use `plan` after you already have enough context from discussion,
+  brainstorming, or research. Trekoon should turn that context into an
+  execution-ready epic.
+- Use `trekoon <epic-id>` to inspect the created epic, next ready work, and any
+  blockers before starting execution.
+- Use `execute` when you want the agent to keep working through the epic until
+  it is done, all remaining work is blocked, or it needs your input.
+
+The rest of this page is mostly the lower-level command surface that agents and
+power users rely on.
+
 ## How storage works
 
 Trekoon keeps one SQLite database per repository at `.trekoon/trekoon.db`. In
@@ -113,6 +134,20 @@ Cascades atomically through all descendants. If any descendant has an unresolved
 external dependency, the whole update fails with no partial writes. Works with
 `--status done` and `--status todo` only.
 
+## Export an epic to Markdown
+
+```bash
+trekoon epic export <epic-id>
+trekoon epic export <epic-id> --path docs/plan.md        # exact file
+trekoon epic export <epic-id> --path docs/plans           # default name inside dir
+trekoon epic export <epic-id> --overwrite
+```
+
+Writes a readable Markdown snapshot under `plans/` by default. With `--path`,
+a file extension means "write this file"; no extension means "put the default-
+named file in this directory". Use `--overwrite` to resave after the plan state
+changes.
+
 ## Check progress
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trekoon",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "description": "AI-first local issue tracker CLI.",
   "keywords": [
     "ai",

package/src/board/assets/app.js

@@ -13,7 +13,6 @@ import { createConfirmDialog } from "./components/ConfirmDialog.js";
 import { createEpicsOverview } from "./components/EpicsOverview.js";
 import { panelClasses, renderIcon, sectionLabelClasses, escapeHtml } from "./components/helpers.js";
 
-const SESSION_TOKEN_STORAGE_KEY = "trekoon-board-session-token";
 const SEARCH_FOCUS_KEYS = new Set(["/", "s"]);
 const FOCUSABLE_SELECTOR = [
   "a[href]",
@@ -33,30 +32,15 @@ const FOCUSABLE_SELECTOR = [
 // Session token management
 // ---------------------------------------------------------------------------
 
-function readSessionTokenFromStorage() {
-  try {
-    return (sessionStorage.getItem(SESSION_TOKEN_STORAGE_KEY) || "").trim();
-  } catch {
-    return "";
-  }
-}
-
-function persistSessionToken(token) {
-  try {
-    sessionStorage.setItem(SESSION_TOKEN_STORAGE_KEY, token);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 function resolveRuntimeSession() {
   const url = new URL(window.location.href);
   const queryToken = (url.searchParams.get("token") || "").trim();
   if (queryToken.length > 0) {
-    return { token: queryToken, shouldScrubAddressBar: persistSessionToken(queryToken) };
+    return { token: queryToken, shouldScrubAddressBar: true };
   }
-  return { token: readSessionTokenFromStorage(), shouldScrubAddressBar: false };
+  const bootstrap = readJsonScript("trekoon-board-bootstrap") ?? {};
+  const bootstrapToken = typeof bootstrap?.token === "string" ? bootstrap.token.trim() : "";
+  return { token: bootstrapToken, shouldScrubAddressBar: false };
 }
 
 function scrubTokenFromAddressBar() {
@@ -149,11 +133,10 @@ export async function bootLegacyBoard(options = {}) {
     if (runtimeSession.shouldScrubAddressBar) scrubTokenFromAddressBar();
 
     // Fetch snapshot
-    let snapshotPayload = readJsonScript("trekoon-board-snapshot") ?? {};
-    if (runtimeSession.token.length > 0) {
-      const headers = new Headers();
-      headers.set("authorization", `Bearer ${runtimeSession.token}`);
-      const response = await fetch("/api/snapshot", { headers });
+    const bootstrap = readJsonScript("trekoon-board-bootstrap") ?? {};
+    let snapshotPayload = bootstrap?.snapshot ?? readJsonScript("trekoon-board-snapshot") ?? {};
+    if ((!snapshotPayload || typeof snapshotPayload !== "object") && runtimeSession.token.length > 0) {
+      const response = await fetch("/api/snapshot");
       const payload = await response.json();
       if (!payload?.ok) throw new Error(payload?.error?.message || "Board request failed");
       snapshotPayload = payload?.data?.snapshot ?? {};

package/src/board/assets/state/api.js

@@ -124,13 +124,12 @@ export function createMutationQueue(model, rerender) {
         model.store.notice = null;
       }
 
-      // Apply optimistic update
-      if (typeof mutation.optimistic === "function") {
-        model.store.snapshot = mutation.optimistic(cloneSnapshot(model.store.snapshot));
-        rerender();
-      }
-
       try {
+        if (typeof mutation.optimistic === "function") {
+          model.store.snapshot = mutation.optimistic(cloneSnapshot(model.store.snapshot));
+          rerender();
+        }
+
         const data = await mutation.request();
 
         if (data?.snapshot) {

package/src/board/assets/state/utils.js

@@ -27,10 +27,10 @@ function normalizeArray(value) {
 
 /**
  * @param {{ id?: string }} record
- * @returns {string}
+ * @returns {string|null}
  */
 function getId(record) {
-  return typeof record?.id === "string" && record.id.length > 0 ? record.id : crypto.randomUUID();
+  return typeof record?.id === "string" && record.id.length > 0 ? record.id : null;
 }
 
 function normalizeTimestamp(value, fallback) {
@@ -42,6 +42,10 @@ function normalizeText(value, fallback = "") {
   return String(value ?? fallback).replace(/\\n/g, "\n");
 }
 
+function normalizeOwner(value) {
+  return typeof value === "string" ? value : null;
+}
+
 /**
  * @param {any[]} tasks
  * @returns {Record<string, number>}
@@ -68,15 +72,21 @@ export function normalizeSnapshot(rawSnapshot) {
   const taskIndex = new Map();
   const subtaskIndex = new Map();
 
-  const tasks = rawTasks.map((task) => {
+  const tasks = rawTasks.flatMap((task) => {
+    const taskId = getId(task);
+    if (!taskId) {
+      return [];
+    }
+
     const createdAt = normalizeTimestamp(task.createdAt, Date.now());
     const normalizedTask = {
-      id: getId(task),
+      id: taskId,
       kind: "task",
       epicId: task.epicId ?? task.epic?.id ?? null,
       title: normalizeText(task.title, "Untitled task"),
       description: normalizeText(task.description),
       status: normalizeStatus(task.status),
+      owner: normalizeOwner(task.owner),
       createdAt,
       updatedAt: normalizeTimestamp(task.updatedAt, createdAt),
       blockedBy: [],
@@ -88,18 +98,24 @@ export function normalizeSnapshot(rawSnapshot) {
     };
 
     taskIndex.set(normalizedTask.id, normalizedTask);
-    return normalizedTask;
+    return [normalizedTask];
   });
 
-  const subtasks = rawSubtasks.map((subtask) => {
+  const subtasks = rawSubtasks.flatMap((subtask) => {
+    const subtaskId = getId(subtask);
+    if (!subtaskId) {
+      return [];
+    }
+
     const createdAt = normalizeTimestamp(subtask.createdAt, Date.now());
     const normalizedSubtask = {
-      id: getId(subtask),
+      id: subtaskId,
       kind: "subtask",
       taskId: subtask.taskId ?? subtask.task?.id ?? null,
       title: normalizeText(subtask.title, "Untitled subtask"),
       description: normalizeText(subtask.description),
       status: normalizeStatus(subtask.status),
+      owner: normalizeOwner(subtask.owner),
       createdAt,
       updatedAt: normalizeTimestamp(subtask.updatedAt, createdAt),
       blockedBy: [],
@@ -110,7 +126,7 @@ export function normalizeSnapshot(rawSnapshot) {
     };
 
     subtaskIndex.set(normalizedSubtask.id, normalizedSubtask);
-    return normalizedSubtask;
+    return [normalizedSubtask];
   });
 
   for (const subtask of subtasks) {
@@ -120,13 +136,22 @@ export function normalizeSnapshot(rawSnapshot) {
     }
   }
 
-  const dependencies = rawDependencies.map((dependency) => ({
-    id: getId(dependency),
-    sourceId: String(dependency.sourceId ?? ""),
-    sourceKind: dependency.sourceKind === "subtask" ? "subtask" : "task",
-    dependsOnId: String(dependency.dependsOnId ?? ""),
-    dependsOnKind: dependency.dependsOnKind === "subtask" ? "subtask" : "task",
-  }));
+  const dependencies = rawDependencies.flatMap((dependency) => {
+    const dependencyId = getId(dependency);
+    const sourceId = typeof dependency?.sourceId === "string" && dependency.sourceId.length > 0 ? dependency.sourceId : null;
+    const dependsOnId = typeof dependency?.dependsOnId === "string" && dependency.dependsOnId.length > 0 ? dependency.dependsOnId : null;
+    if (!dependencyId || !sourceId || !dependsOnId) {
+      return [];
+    }
+
+    return [{
+      id: dependencyId,
+      sourceId,
+      sourceKind: dependency.sourceKind === "subtask" ? "subtask" : "task",
+      dependsOnId,
+      dependsOnKind: dependency.dependsOnKind === "subtask" ? "subtask" : "task",
+    }];
+  });
 
   const lookupNode = (kind, id) => {
     if (kind === "subtask") {
@@ -148,8 +173,12 @@ export function normalizeSnapshot(rawSnapshot) {
     }
   }
 
-  const epics = rawEpics.map((epic) => {
+  const epics = rawEpics.flatMap((epic) => {
     const epicId = getId(epic);
+    if (!epicId) {
+      return [];
+    }
+
     const epicTasks = tasks.filter((task) => task.epicId === epicId);
     const createdAt = normalizeTimestamp(epic.createdAt, Date.now());
     const normalizedEpic = {
@@ -165,7 +194,7 @@ export function normalizeSnapshot(rawSnapshot) {
     };
 
     normalizedEpic.searchText = [normalizedEpic.title, normalizedEpic.description, ...epicTasks.map((task) => task.title)].join(" ").toLowerCase();
-    return normalizedEpic;
+    return [normalizedEpic];
   });
 
   for (const subtask of subtasks) {
@@ -214,6 +243,10 @@ function mergeRecordsById(existingRecords, incomingRecords, deletedIds = []) {
   const indexById = new Map(nextRecords.map((record, index) => [record.id, index]));
 
   for (const record of incomingRecords) {
+    if (typeof record?.id !== "string" || record.id.length === 0) {
+      continue;
+    }
+
     const existingIndex = indexById.get(record.id);
     if (existingIndex === undefined) {
       indexById.set(record.id, nextRecords.length);

package/src/board/routes.ts

@@ -4,7 +4,7 @@ import { safeErrorMessage } from "../commands/error-utils";
 import { MutationService } from "../domain/mutation-service";
 import { TrackerDomain } from "../domain/tracker-domain";
 import { DomainError } from "../domain/types";
-import { buildBoardSnapshot } from "./snapshot";
+import { buildBoardSnapshot, buildBoardSnapshotDelta } from "./snapshot";
 
 interface SnapshotDeltaSelection {
   readonly epicIds?: readonly string[];
@@ -63,6 +63,25 @@ function jsonResponse(status: number, data: unknown): Response {
   });
 }
 
+function readCookieToken(request: Request): string | null {
+  const rawCookie = request.headers.get("cookie");
+  if (!rawCookie) {
+    return null;
+  }
+
+  for (const part of rawCookie.split(";")) {
+    const [name, ...valueParts] = part.split("=");
+    if (name?.trim() !== "trekoon_board_session") {
+      continue;
+    }
+
+    const value = valueParts.join("=").trim();
+    return value.length > 0 ? decodeURIComponent(value) : null;
+  }
+
+  return null;
+}
+
 function extractToken(request: Request, url: URL): string | null {
   const authorization: string | null = request.headers.get("authorization");
   if (authorization?.startsWith("Bearer ")) {
@@ -79,7 +98,7 @@ function extractToken(request: Request, url: URL): string | null {
     return queryToken.trim();
   }
 
-  return null;
+  return readCookieToken(request);
 }
 
 function isSqliteBusyMessage(message: string): boolean {
@@ -147,23 +166,7 @@ function buildMutationResponse(_domain: TrackerDomain, data: Record<string, unkn
   });
 }
 
-function buildSnapshotDelta(domain: TrackerDomain, selection: SnapshotDeltaSelection): Record<string, unknown> {
-  const snapshot = buildBoardSnapshot(domain);
-  const epicIdSet = new Set(selection.epicIds ?? []);
-  const taskIdSet = new Set(selection.taskIds ?? []);
-  const subtaskIdSet = new Set(selection.subtaskIds ?? []);
-  const dependencyIdSet = new Set(selection.dependencyIds ?? []);
-
-  return {
-    generatedAt: snapshot.generatedAt,
-    epics: snapshot.epics.filter((epic) => epicIdSet.has(epic.id)),
-    tasks: snapshot.tasks.filter((task) => taskIdSet.has(task.id)),
-    subtasks: snapshot.subtasks.filter((subtask) => subtaskIdSet.has(subtask.id)),
-    dependencies: snapshot.dependencies.filter((dependency) => dependencyIdSet.has(dependency.id)),
-    deletedSubtaskIds: [...(selection.deletedSubtaskIds ?? [])],
-    deletedDependencyIds: [...(selection.deletedDependencyIds ?? [])],
-  };
-}
+const buildSnapshotDelta = buildBoardSnapshotDelta;
 
 function buildMutationDeltaResponse(
   domain: TrackerDomain,

package/src/board/server.ts

@@ -3,9 +3,11 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, extname, resolve } from "node:path";
 
 import { createBoardApiHandler } from "./routes";
+import { buildBoardSnapshot } from "./snapshot";
 
 import { openTrekoonDatabase, type TrekoonDatabase } from "../storage/database";
 import { resolveStoragePaths } from "../storage/path";
+import { TrackerDomain } from "../domain/tracker-domain";
 
 const CONTENT_TYPES: Record<string, string> = {
   ".css": "text/css; charset=utf-8",
@@ -87,6 +89,37 @@ function isUnavailablePortError(error: unknown): boolean {
   return /^(EADDRINUSE|EACCES)$/i.test(errorCode) || /(EADDRINUSE|EACCES|address already in use|permission denied)/i.test(error.message);
 }
 
+function buildBoardSessionCookie(token: string): string {
+  return `trekoon_board_session=${encodeURIComponent(token)}; Path=/; SameSite=Strict; HttpOnly`;
+}
+
+function serializeInlineJson(value: unknown): string {
+  return JSON.stringify(value)
+    .replace(/</g, "\\u003c")
+    .replace(/>/g, "\\u003e")
+    .replace(/&/g, "\\u0026")
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029");
+}
+
+function buildBoardBootstrapPayload(database: TrekoonDatabase, token: string): string {
+  const domain = new TrackerDomain(database.db);
+  return serializeInlineJson({
+    token,
+    snapshot: buildBoardSnapshot(domain),
+  });
+}
+
+function injectBoardBootstrap(html: string, bootstrapJson: string): string {
+  const bootstrapTag = `<script id="trekoon-board-bootstrap" type="application/json">${bootstrapJson}</script>`;
+  const closingBodyIndex = html.lastIndexOf("</body>");
+  if (closingBodyIndex === -1) {
+    return `${html}${bootstrapTag}`;
+  }
+
+  return `${html.slice(0, closingBodyIndex)}${bootstrapTag}\n${html.slice(closingBodyIndex)}`;
+}
+
 export function startBoardServer(options: StartBoardServerOptions = {}): BoardServerInfo {
   const cwd: string = options.cwd ?? process.cwd();
   const database: TrekoonDatabase = openTrekoonDatabase(cwd);
@@ -110,6 +143,13 @@ export function startBoardServer(options: StartBoardServerOptions = {}): BoardSe
           return apiHandler(request);
         }
 
+        const responseHeaders: Record<string, string> = {
+          "cache-control": "no-store",
+        };
+        if ((url.searchParams.get("token") ?? "") === token) {
+          responseHeaders["set-cookie"] = buildBoardSessionCookie(token);
+        }
+
         const assetPath = readAssetPath(boardRoot, url.pathname === "/" ? "/index.html" : url.pathname);
         if (assetPath === null) {
           const fallbackPath = readAssetPath(boardRoot, "/index.html");
@@ -117,9 +157,21 @@ export function startBoardServer(options: StartBoardServerOptions = {}): BoardSe
             return new Response("Board assets are not installed", { status: 500 });
           }
 
-          return new Response(readFileSync(fallbackPath), {
+          const html = injectBoardBootstrap(readFileSync(fallbackPath, "utf8"), buildBoardBootstrapPayload(database, token));
+
+          return new Response(html, {
+            headers: {
+              ...responseHeaders,
+              "content-type": "text/html; charset=utf-8",
+            },
+          });
+        }
+
+        if (assetPath.endsWith("/index.html")) {
+          const html = injectBoardBootstrap(readFileSync(assetPath, "utf8"), buildBoardBootstrapPayload(database, token));
+          return new Response(html, {
             headers: {
-              "cache-control": "no-store",
+              ...responseHeaders,
               "content-type": "text/html; charset=utf-8",
             },
           });
@@ -127,7 +179,7 @@ export function startBoardServer(options: StartBoardServerOptions = {}): BoardSe
 
         return new Response(readFileSync(assetPath), {
           headers: {
-            "cache-control": "no-store",
+            ...responseHeaders,
             "content-type": guessContentType(assetPath),
           },
         });
@@ -169,11 +221,12 @@ export function startBoardServer(options: StartBoardServerOptions = {}): BoardSe
 
   const origin: string = `http://127.0.0.1:${port}`;
   const url: string = `${origin}/?token=${encodeURIComponent(token)}`;
+  const fallbackUrl: string = origin;
 
   return {
     origin,
     url,
-    fallbackUrl: url,
+    fallbackUrl,
     token,
     hostname: "127.0.0.1",
     port,