trekoon 0.4.1 → 0.4.3

package/src/commands/subtask.ts

@@ -39,6 +39,7 @@ const SEARCH_OPTIONS = ["fields", "preview"] as const;
 const REPLACE_OPTIONS = ["search", "replace", "fields", "preview", "apply"] as const;
 const CREATE_MANY_OPTIONS = ["task", "t", "subtask"] as const;
 const UPDATE_OPTIONS = ["all", "ids", "append", "description", "d", "status", "s", "title", "owner"] as const;
+const CLAIM_OPTIONS = ["owner"] as const;
 const STATUS_CASCADE_UPDATE_STATUSES = ["done", "todo"] as const;
 
 function parseIdsOption(rawIds: string | undefined): string[] {
@@ -892,10 +893,9 @@ export async function runSubtask(context: CliContext): Promise<CliResult> {
 
           const targets = updateAll ? [...domain.listSubtasks()] : ids.map((id) => domain.getSubtaskOrThrow(id));
           const subtasks = targets.map((target) =>
-            mutations.updateSubtask(target.id, {
-              status,
-              description: append === undefined ? undefined : appendLine(target.description, append),
-            }),
+            append !== undefined
+              ? mutations.appendToSubtaskDescription({ subtaskId: target.id, append, status })
+              : mutations.updateSubtask(target.id, { status }),
           );
 
           return okResult({
@@ -921,11 +921,10 @@ export async function runSubtask(context: CliContext): Promise<CliResult> {
           });
         }
 
-        const nextDescription =
-          append === undefined
-            ? description
-            : appendLine(domain.getSubtaskOrThrow(subtaskId).description, append);
-        const subtask = mutations.updateSubtask(subtaskId, { title, description: nextDescription, status, owner });
+        const subtask =
+          append !== undefined
+            ? mutations.appendToSubtaskDescription({ subtaskId, append, status, owner })
+            : mutations.updateSubtask(subtaskId, { title, description, status, owner });
 
         return okResult({
           command: "subtask.update",
@@ -933,6 +932,68 @@ export async function runSubtask(context: CliContext): Promise<CliResult> {
           data: { subtask },
         });
       }
+      case "claim": {
+        const claimUnknownOption = findUnknownOption(parsed, CLAIM_OPTIONS);
+        if (claimUnknownOption !== undefined) {
+          return unknownOption("subtask.claim", claimUnknownOption, CLAIM_OPTIONS);
+        }
+
+        const missingClaimOption = readMissingOptionValue(parsed.missingOptionValues, "owner");
+        if (missingClaimOption !== undefined) {
+          return failMissingOptionValue("subtask.claim", missingClaimOption);
+        }
+
+        const subtaskId: string = parsed.positional[1] ?? "";
+        if (subtaskId.length === 0) {
+          return failResult({
+            command: "subtask.claim",
+            human: "Provide a subtask id. Usage: trekoon subtask claim <id> --owner <owner>",
+            data: { code: "invalid_input" },
+            error: {
+              code: "invalid_input",
+              message: "Missing subtask id",
+            },
+          });
+        }
+
+        const owner: string | undefined = readOption(parsed.options, "owner");
+        if (owner === undefined || owner.trim().length === 0) {
+          return failResult({
+            command: "subtask.claim",
+            human: "--owner is required. Usage: trekoon subtask claim <id> --owner <owner>",
+            data: { code: "invalid_input", option: "owner" },
+            error: {
+              code: "invalid_input",
+              message: "Missing required option --owner",
+            },
+          });
+        }
+
+        const claimResult = mutations.claimSubtask({ subtaskId, owner });
+
+        if (claimResult.claimed) {
+          return okResult({
+            command: "subtask.claim",
+            human: `Claimed subtask ${subtaskId} for ${owner}`,
+            data: {
+              claimed: true,
+              currentOwner: claimResult.currentOwner,
+              currentStatus: claimResult.currentStatus,
+              subtask: claimResult.subtask,
+            },
+          });
+        }
+
+        return okResult({
+          command: "subtask.claim",
+          human: `Subtask ${subtaskId} not claimed: status=${claimResult.currentStatus}, owner=${claimResult.currentOwner ?? "none"}`,
+          data: {
+            claimed: false,
+            currentOwner: claimResult.currentOwner,
+            currentStatus: claimResult.currentStatus,
+          },
+        });
+      }
       case "delete": {
         const subtaskId: string = parsed.positional[1] ?? "";
         const result = mutations.deleteSubtask(subtaskId);
@@ -946,7 +1007,7 @@ export async function runSubtask(context: CliContext): Promise<CliResult> {
       default:
         return failResult({
           command: "subtask",
-          human: "Usage: trekoon subtask <create|create-many|list|search|replace|update|delete>",
+          human: "Usage: trekoon subtask <create|create-many|list|search|replace|update|delete|claim>",
           data: {
             args: context.args,
           },

package/src/commands/suggest.ts

@@ -44,14 +44,7 @@ function resolveActiveEpic(domain: TrackerDomain, epicId: string | undefined): E
     return domain.getEpic(epicId);
   }
 
-  const epics = domain.listEpics();
-  const inProgress = epics.find((epic) => epic.status === "in_progress");
-  if (inProgress) {
-    return inProgress;
-  }
-
-  const todo = epics.find((epic) => epic.status === "todo");
-  return todo ?? epics[0] ?? null;
+  return domain.findActiveEpic();
 }
 
 function findInProgressTasks(readiness: TaskReadinessResult): { count: number; first: { id: string; title: string } | null } {
@@ -76,7 +69,7 @@ function buildSuggestions(
   recoveryRequired: boolean,
   syncSummary: SyncStatusSummary,
   readiness: TaskReadinessResult,
-  epics: readonly EpicRecord[],
+  epicCount: number,
   activeEpic: EpicRecord | null,
 ): readonly Suggestion[] {
   const suggestions: Suggestion[] = [];
@@ -186,7 +179,7 @@ function buildSuggestions(
   }
 
   // Priority 8: No epics exist
-  if (suggestions.length < MAX_SUGGESTIONS && epics.length === 0) {
+  if (suggestions.length < MAX_SUGGESTIONS && epicCount === 0) {
     suggestions.push({
       priority: suggestions.length + 1,
       action: "quickstart",
@@ -241,7 +234,7 @@ export async function runSuggest(context: CliContext): Promise<CliResult> {
 
     const syncSummary = resolveSyncStatus(database, context.cwd, DEFAULT_SOURCE_BRANCH);
     const domain = new TrackerDomain(database.db);
-    const epics = domain.listEpics();
+    const epicCount = domain.countEpics();
     const activeEpic = resolveActiveEpic(domain, epicId);
 
     const readiness = buildTaskReadiness(domain, epicId ?? activeEpic?.id);
@@ -250,14 +243,14 @@ export async function runSuggest(context: CliContext): Promise<CliResult> {
       diagnostics.recoveryRequired,
       syncSummary,
       readiness,
-      epics,
+      epicCount,
       activeEpic,
     );
 
     const result: SuggestResult = {
       suggestions,
       context: {
-        totalEpics: epics.length,
+        totalEpics: epicCount,
         activeEpic: activeEpic?.id ?? null,
         readyTasks: readiness.summary.readyCount,
         blockedTasks: readiness.summary.blockedCount,

package/src/commands/task.ts

@@ -47,6 +47,7 @@ const SEARCH_OPTIONS = ["fields", "preview"] as const;
 const REPLACE_OPTIONS = ["search", "replace", "fields", "preview", "apply"] as const;
 const CREATE_MANY_OPTIONS = ["epic", "e", "task"] as const;
 const UPDATE_OPTIONS = ["all", "ids", "append", "description", "d", "status", "s", "title", "t", "owner"] as const;
+const CLAIM_OPTIONS = ["owner"] as const;
 const STATUS_CASCADE_UPDATE_STATUSES = ["done", "todo"] as const;
 
 function parseIdsOption(rawIds: string | undefined): string[] {
@@ -1179,10 +1180,9 @@ export async function runTask(context: CliContext): Promise<CliResult> {
 
           const targets = updateAll ? [...domain.listTasks()] : ids.map((id) => domain.getTaskOrThrow(id));
           const tasks = targets.map((target) =>
-            mutations.updateTask(target.id, {
-              status,
-              description: append === undefined ? undefined : appendLine(target.description, append),
-            }),
+            append !== undefined
+              ? mutations.appendToTaskDescription({ taskId: target.id, append, status })
+              : mutations.updateTask(target.id, { status }),
           );
 
           return okResult({
@@ -1208,11 +1208,10 @@ export async function runTask(context: CliContext): Promise<CliResult> {
           });
         }
 
-        const nextDescription =
-          append === undefined
-            ? description
-            : appendLine(domain.getTaskOrThrow(taskId).description, append);
-        const task = mutations.updateTask(taskId, { title, description: nextDescription, status, owner });
+        const task =
+          append !== undefined
+            ? mutations.appendToTaskDescription({ taskId, append, status, owner })
+            : mutations.updateTask(taskId, { title, description, status, owner });
 
         return okResult({
           command: "task.update",
@@ -1247,98 +1246,148 @@ export async function runTask(context: CliContext): Promise<CliResult> {
           });
         }
 
-        if (existingTask.status === "done") {
-          return failResult({
-            command: "task.done",
-            human: "Task is already done",
-            data: { code: "already_done", id: taskId },
-            error: {
-              code: "already_done",
-              message: "Task is already done",
-            },
-          });
-        }
-
-        // Check for open subtasks (lenient: warn but allow completion)
-        const openSubtasks = domain.getOpenSubtasks(taskId);
-        const openSubtaskCount = openSubtasks.length;
-        const openSubtaskIds = openSubtasks.map((s) => s.id);
-
-        // Snapshot blocked reverse deps before marking done (lightweight: no full readiness rebuild).
-        // Only direct task-level reverse deps are tracked here; subtask reverse deps are excluded
-        // because subtasks are children within a task, not independent workflow items.
-        const reverseDeps = domain.listReverseDependencies(taskId);
-        const directRevDepTaskIds = reverseDeps
-          .filter((rd) => rd.isDirect && rd.kind === "task")
-          .map((rd) => rd.id);
-        const preDepStatuses = domain.batchResolveDependencyStatuses(directRevDepTaskIds);
-        const preBlockedIds = new Set(
-          directRevDepTaskIds.filter((id) => {
-            const resolved = preDepStatuses.get(id);
-            return resolved !== undefined && resolved.blockers.length > 0;
-          }),
-        );
-
-        // Auto-transition through in_progress when current status is todo or blocked.
-        // Note: this emits two sync events (→in_progress, →done) because each
-        // updateTask call appends its own event.  This is intentional — the status
-        // machine requires the intermediate step, and event consumers should treat
-        // a rapid in_progress→done pair from `task done` as a single logical completion.
-        if (existingTask.status === "todo" || existingTask.status === "blocked") {
-          mutations.updateTask(taskId, { status: "in_progress" });
-        }
-
-        const completed = mutations.updateTask(taskId, { status: "done" });
-        const readiness = buildTaskReadiness(domain, completed.epicId);
-        const nextCandidate = readiness.candidates[0] ?? null;
-
-        // Diff: tasks that were blocked before but are now ready
-        const unblockedTasks = readiness.candidates
-          .filter((item) => preBlockedIds.has(item.task.id))
-          .map((item) => ({
-            id: item.task.id,
-            kind: "task" as const,
-            title: item.task.title,
-            status: item.task.status,
-            wasBlockedBy: [taskId],
-          }));
-
-        const nextTree = nextCandidate !== null ? domain.buildTaskTreeDetailed(nextCandidate.task.id) : null;
-        const nextDeps = nextCandidate?.blockerSummary.blockedBy ?? [];
-
-        const readinessStats = {
-          readyCount: readiness.summary.readyCount,
-          blockedCount: readiness.summary.blockedCount,
-        };
+        // Note: the redundant `if (existingTask.status === "done")` pre-check
+        // was removed in the cr-expert hardening pass — `markTaskDoneAtomically`
+        // raises `already_done` itself inside the same transaction that would
+        // perform the flip, eliminating a race window between this read and
+        // the atomic write. The thrown DomainError propagates to the outer
+        // catch and is rendered with the same `code: "already_done"` payload
+        // by `unexpectedFailureResult`.
+
+        // Single-transaction atomic completion: the entire flow (status flip,
+        // event emission, unblocked-diff snapshot) runs inside ONE
+        // `BEGIN IMMEDIATE`/`COMMIT` pair. Bypasses the public transition
+        // checker — this is the documented allowed exception (see
+        // MutationService.markTaskDoneAtomically and docs/machine-contracts.md).
+        // A crash mid-flight rolls the row back to its original status; the
+        // task is never observable in a phantom `in_progress` state.
+        const snapshot = mutations.markTaskDoneAtomically({
+          taskId,
+          computeSnapshot: ({ domain: txDomain, completed, preBlockedReverseDepIds }) => {
+            const openSubtasks = txDomain.getOpenSubtasks(taskId);
+            const readiness = buildTaskReadiness(txDomain, completed.epicId);
+            const nextCandidate = readiness.candidates[0] ?? null;
+
+            const preBlockedIds = new Set<string>(preBlockedReverseDepIds);
+            const unblockedTasks = readiness.candidates
+              .filter((item) => preBlockedIds.has(item.task.id))
+              .map((item) => ({
+                id: item.task.id,
+                kind: "task" as const,
+                title: item.task.title,
+                status: item.task.status,
+                wasBlockedBy: [taskId],
+              }));
+
+            const nextTree = nextCandidate !== null ? txDomain.buildTaskTreeDetailed(nextCandidate.task.id) : null;
+            const nextDeps = nextCandidate?.blockerSummary.blockedBy ?? [];
+
+            return {
+              completed,
+              openSubtaskCount: openSubtasks.length,
+              openSubtaskIds: openSubtasks.map((s) => s.id),
+              unblocked: unblockedTasks,
+              next: nextTree,
+              nextCandidate,
+              nextDeps,
+              readiness: {
+                readyCount: readiness.summary.readyCount,
+                blockedCount: readiness.summary.blockedCount,
+              },
+            };
+          },
+        });
 
-        const subtaskWarning = openSubtaskCount > 0
-          ? `Warning: ${openSubtaskCount} subtask(s) still open.`
+        const subtaskWarning = snapshot.openSubtaskCount > 0
+          ? `Warning: ${snapshot.openSubtaskCount} subtask(s) still open.`
           : null;
 
-        let human = `Task ${completed.title} marked done.`;
+        let human = `Task ${snapshot.completed.title} marked done.`;
         if (subtaskWarning !== null) {
           human += `\n${subtaskWarning}`;
         }
-        if (unblockedTasks.length > 0) {
-          human += `\nUnblocked: ${unblockedTasks.map((t) => t.title).join(", ")}`;
+        if (snapshot.unblocked.length > 0) {
+          human += `\nUnblocked: ${snapshot.unblocked.map((t) => t.title).join(", ")}`;
         }
-        if (nextTree !== null && nextCandidate !== null) {
-          human += `\nNext: ${formatTask(nextCandidate.task)}`;
+        if (snapshot.next !== null && snapshot.nextCandidate !== null) {
+          human += `\nNext: ${formatTask(snapshot.nextCandidate.task)}`;
         }
-        human += `\nReadiness: ready=${readinessStats.readyCount}, blocked=${readinessStats.blockedCount}.`;
+        human += `\nReadiness: ready=${snapshot.readiness.readyCount}, blocked=${snapshot.readiness.blockedCount}.`;
 
         return okResult({
           command: "task.done",
           human,
           data: {
-            completed,
-            openSubtaskCount,
-            openSubtaskIds,
+            completed: snapshot.completed,
+            openSubtaskCount: snapshot.openSubtaskCount,
+            openSubtaskIds: snapshot.openSubtaskIds,
             warning: subtaskWarning,
-            unblocked: unblockedTasks,
-            next: nextTree,
-            nextDeps,
-            readiness: readinessStats,
+            unblocked: snapshot.unblocked,
+            next: snapshot.next,
+            nextDeps: snapshot.nextDeps,
+            readiness: snapshot.readiness,
+          },
+        });
+      }
+      case "claim": {
+        const claimUnknownOption = findUnknownOption(parsed, CLAIM_OPTIONS);
+        if (claimUnknownOption !== undefined) {
+          return unknownOption("task.claim", claimUnknownOption, CLAIM_OPTIONS);
+        }
+
+        const missingClaimOption = readMissingOptionValue(parsed.missingOptionValues, "owner");
+        if (missingClaimOption !== undefined) {
+          return failMissingOptionValue("task.claim", missingClaimOption);
+        }
+
+        const taskId: string = parsed.positional[1] ?? "";
+        if (taskId.length === 0) {
+          return failResult({
+            command: "task.claim",
+            human: "Provide a task id. Usage: trekoon task claim <id> --owner <owner>",
+            data: { code: "invalid_input" },
+            error: {
+              code: "invalid_input",
+              message: "Missing task id",
+            },
+          });
+        }
+
+        const owner: string | undefined = readOption(parsed.options, "owner");
+        if (owner === undefined || owner.trim().length === 0) {
+          return failResult({
+            command: "task.claim",
+            human: "--owner is required. Usage: trekoon task claim <id> --owner <owner>",
+            data: { code: "invalid_input", option: "owner" },
+            error: {
+              code: "invalid_input",
+              message: "Missing required option --owner",
+            },
+          });
+        }
+
+        const claimResult = mutations.claimTask({ taskId, owner });
+
+        if (claimResult.claimed) {
+          return okResult({
+            command: "task.claim",
+            human: `Claimed task ${taskId} for ${owner}`,
+            data: {
+              claimed: true,
+              currentOwner: claimResult.currentOwner,
+              currentStatus: claimResult.currentStatus,
+              task: claimResult.task,
+            },
+          });
+        }
+
+        return okResult({
+          command: "task.claim",
+          human: `Task ${taskId} not claimed: status=${claimResult.currentStatus}, owner=${claimResult.currentOwner ?? "none"}`,
+          data: {
+            claimed: false,
+            currentOwner: claimResult.currentOwner,
+            currentStatus: claimResult.currentStatus,
           },
         });
       }
@@ -1355,7 +1404,7 @@ export async function runTask(context: CliContext): Promise<CliResult> {
       default:
         return failResult({
           command: "task",
-          human: "Usage: trekoon task <create|create-many|list|show|ready|next|done|search|replace|update|delete>",
+          human: "Usage: trekoon task <create|create-many|list|show|ready|next|done|search|replace|update|delete|claim>",
           data: {
             args: context.args,
           },