trekoon 0.4.0 → 0.4.2

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,
           },

package/src/domain/batch-validation.ts

@@ -0,0 +1,329 @@
+import {
+  type CompactDependencySpec,
+  type CompactEntityRef,
+  type CompactSubtaskSpec,
+  type DependencyRecord,
+  DomainError,
+  type SubtaskRecord,
+  type TaskRecord,
+} from "./types";
+
+// ---------------------------------------------------------------------------
+// Shared interfaces
+// ---------------------------------------------------------------------------
+
+export interface ResolvedDependencyBatchSpec {
+  readonly index: number;
+  readonly sourceId: string;
+  readonly sourceKind: "task" | "subtask";
+  readonly dependsOnId: string;
+  readonly dependsOnKind: "task" | "subtask";
+}
+
+export interface DependencyBatchValidationIssue {
+  readonly index: number;
+  readonly type: "missing_id" | "duplicate" | "cycle";
+  readonly sourceId: string;
+  readonly dependsOnId: string;
+  readonly details: Record<string, unknown>;
+}
+
+export interface DependencyBatchResolution {
+  readonly spec?: ResolvedDependencyBatchSpec;
+  readonly issues: readonly DependencyBatchValidationIssue[];
+}
+
+export interface ResolvedCompactEntity {
+  readonly id: string;
+  readonly kind: "task" | "subtask";
+}
+
+// ---------------------------------------------------------------------------
+// Reader interface — the only DB-touching surface the callers must supply
+// ---------------------------------------------------------------------------
+
+export interface BatchValidationReader {
+  getTask(id: string): TaskRecord | null;
+  getSubtask(id: string): SubtaskRecord | null;
+  getDependencyByEdge(sourceId: string, dependsOnId: string): DependencyRecord | null;
+  buildDependencyAdjacency(): Map<string, Set<string>>;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function assertNonEmptyLocal(field: string, value: string | undefined | null): string {
+  const normalized: string = (value ?? "").trim();
+  if (!normalized) {
+    throw new DomainError({
+      code: "invalid_input",
+      message: `${field} must be a non-empty string`,
+      details: { field },
+    });
+  }
+  return normalized;
+}
+
+function resolveNodeKindLocal(id: string, reader: BatchValidationReader): "task" | "subtask" {
+  if (reader.getTask(id)) return "task";
+  if (reader.getSubtask(id)) return "subtask";
+  throw new DomainError({
+    code: "not_found",
+    message: `node not found: ${id}`,
+    details: { id, expectedKinds: ["task", "subtask"] },
+  });
+}
+
+function resolveDependencyBatchId(
+  reference: CompactEntityRef,
+  field: "source" | "dependsOn",
+  index: number,
+  reader: BatchValidationReader,
+): { readonly id?: string; readonly issues: readonly DependencyBatchValidationIssue[] } {
+  if (reference.kind === "temp_key") {
+    return {
+      issues: [
+        {
+          index,
+          type: "missing_id",
+          sourceId: field === "source" ? `@${reference.tempKey}` : "",
+          dependsOnId: field === "dependsOn" ? `@${reference.tempKey}` : "",
+          details: {
+            field,
+            tempKey: reference.tempKey,
+            message: `Unresolved temp key @${reference.tempKey}`,
+          },
+        },
+      ],
+    };
+  }
+
+  const id = assertNonEmptyLocal(field === "source" ? "sourceId" : "dependsOnId", reference.id);
+  const task = reader.getTask(id);
+  const subtask = reader.getSubtask(id);
+  if (!task && !subtask) {
+    return {
+      issues: [
+        {
+          index,
+          type: "missing_id",
+          sourceId: field === "source" ? id : "",
+          dependsOnId: field === "dependsOn" ? id : "",
+          details: {
+            field,
+            id,
+            message: `Node not found: ${id}`,
+          },
+        },
+      ],
+    };
+  }
+
+  return { id, issues: [] };
+}
+
+function wouldCreateCycleInAdjacency(
+  adjacency: ReadonlyMap<string, ReadonlySet<string>>,
+  sourceId: string,
+  dependsOnId: string,
+): boolean {
+  const visited = new Set<string>();
+  const queue: string[] = [dependsOnId];
+
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (current === undefined || visited.has(current)) continue;
+    if (current === sourceId) return true;
+    visited.add(current);
+    const neighbors = adjacency.get(current);
+    if (neighbors === undefined) continue;
+    for (const neighbor of neighbors) {
+      if (!visited.has(neighbor)) queue.push(neighbor);
+    }
+  }
+
+  return false;
+}
+
+function resolveEpicExpandEntityRef(
+  reference: CompactEntityRef,
+  mappings: readonly { tempKey: string; id: string; kind: "task" | "subtask" }[],
+  option: "subtask" | "dep",
+  index: number,
+  field: "parent" | "source" | "dependsOn",
+  reader: BatchValidationReader,
+): ResolvedCompactEntity {
+  if (reference.kind === "temp_key") {
+    const mapping = mappings.find((candidate) => candidate.tempKey === reference.tempKey);
+    if (mapping === undefined) {
+      throw new DomainError({
+        code: "invalid_input",
+        message: `Unknown temp key @${reference.tempKey} in --${option} spec ${index + 1}`,
+        details: { index, field, tempKey: reference.tempKey, option },
+      });
+    }
+    return { id: mapping.id, kind: mapping.kind };
+  }
+
+  const id = assertNonEmptyLocal(field === "parent" ? "taskId" : `${field}Id`, reference.id);
+  return { id, kind: resolveNodeKindLocal(id, reader) };
+}
+
+// ---------------------------------------------------------------------------
+// Exported pure functions
+// ---------------------------------------------------------------------------
+
+export function resolveDependencyBatchSpec(
+  index: number,
+  spec: CompactDependencySpec,
+  reader: BatchValidationReader,
+): DependencyBatchResolution {
+  const sourceResolution = resolveDependencyBatchId(spec.source, "source", index, reader);
+  const dependsOnResolution = resolveDependencyBatchId(spec.dependsOn, "dependsOn", index, reader);
+  const issues = [...sourceResolution.issues, ...dependsOnResolution.issues];
+  const sourceId = sourceResolution.id;
+  const dependsOnId = dependsOnResolution.id;
+
+  if (sourceId === undefined || dependsOnId === undefined) {
+    return { issues };
+  }
+
+  if (sourceId === dependsOnId) {
+    return {
+      issues: [
+        ...issues,
+        {
+          index,
+          type: "cycle",
+          sourceId,
+          dependsOnId,
+          details: { sourceId, dependsOnId, reason: "self_reference" },
+        },
+      ],
+    };
+  }
+
+  return {
+    spec: {
+      index,
+      sourceId,
+      sourceKind: resolveNodeKindLocal(sourceId, reader),
+      dependsOnId,
+      dependsOnKind: resolveNodeKindLocal(dependsOnId, reader),
+    },
+    issues,
+  };
+}
+
+export function resolveEpicExpandSubtaskSpecs(
+  specs: readonly CompactSubtaskSpec[],
+  mappings: readonly { tempKey: string; id: string; kind: "task" | "subtask" }[],
+  reader: BatchValidationReader,
+): CompactSubtaskSpec[] {
+  return specs.map((spec, index) => {
+    const parent = resolveEpicExpandEntityRef(spec.parent, mappings, "subtask", index, "parent", reader);
+    if (parent.kind !== "task") {
+      throw new DomainError({
+        code: "invalid_input",
+        message: `Subtask parent must resolve to a task in --subtask spec ${index + 1}`,
+        details: { index, field: "parent", kind: parent.kind, id: parent.id },
+      });
+    }
+    return { ...spec, parent: { kind: "id", id: parent.id } };
+  });
+}
+
+export function resolveEpicExpandDependencySpecs(
+  specs: readonly CompactDependencySpec[],
+  mappings: readonly { tempKey: string; id: string; kind: "task" | "subtask" }[],
+  reader: BatchValidationReader,
+): CompactDependencySpec[] {
+  return specs.map((spec, index) => ({
+    source: {
+      kind: "id",
+      id: resolveEpicExpandEntityRef(spec.source, mappings, "dep", index, "source", reader).id,
+    },
+    dependsOn: {
+      kind: "id",
+      id: resolveEpicExpandEntityRef(spec.dependsOn, mappings, "dep", index, "dependsOn", reader).id,
+    },
+  }));
+}
+
+export function collectDependencyBatchIssues(
+  specs: readonly ResolvedDependencyBatchSpec[],
+  reader: BatchValidationReader,
+): DependencyBatchValidationIssue[] {
+  const issues: DependencyBatchValidationIssue[] = [];
+  const seenEdges = new Map<string, number>();
+  const adjacency = reader.buildDependencyAdjacency();
+
+  for (const spec of specs) {
+    const edgeKey = `${spec.sourceId}->${spec.dependsOnId}`;
+    const existingIndex = seenEdges.get(edgeKey);
+    if (existingIndex !== undefined) {
+      issues.push({
+        index: spec.index,
+        type: "duplicate",
+        sourceId: spec.sourceId,
+        dependsOnId: spec.dependsOnId,
+        details: {
+          sourceId: spec.sourceId,
+          dependsOnId: spec.dependsOnId,
+          firstIndex: existingIndex,
+          duplicateIndex: spec.index,
+          duplicateKind: "batch",
+        },
+      });
+      continue;
+    }
+
+    if (reader.getDependencyByEdge(spec.sourceId, spec.dependsOnId) !== null) {
+      issues.push({
+        index: spec.index,
+        type: "duplicate",
+        sourceId: spec.sourceId,
+        dependsOnId: spec.dependsOnId,
+        details: {
+          sourceId: spec.sourceId,
+          dependsOnId: spec.dependsOnId,
+          duplicateKind: "existing",
+        },
+      });
+      continue;
+    }
+
+
+
+    if (wouldCreateCycleInAdjacency(adjacency, spec.sourceId, spec.dependsOnId)) {
+      issues.push({
+        index: spec.index,
+        type: "cycle",
+        sourceId: spec.sourceId,
+        dependsOnId: spec.dependsOnId,
+        details: { sourceId: spec.sourceId, dependsOnId: spec.dependsOnId },
+      });
+      continue;
+    }
+
+    const nextNeighbors = adjacency.get(spec.sourceId) ?? new Set<string>();
+    nextNeighbors.add(spec.dependsOnId);
+    adjacency.set(spec.sourceId, nextNeighbors);
+    seenEdges.set(edgeKey, spec.index);
+  }
+
+  return issues.sort((left, right) => left.index - right.index || left.type.localeCompare(right.type));
+}
+
+export function buildDependencyAdjacency(
+  rows: ReadonlyArray<{ source_id: string; depends_on_id: string }>,
+): Map<string, Set<string>> {
+  const adjacency = new Map<string, Set<string>>();
+  for (const row of rows) {
+    const neighbors = adjacency.get(row.source_id) ?? new Set<string>();
+    neighbors.add(row.depends_on_id);
+    adjacency.set(row.source_id, neighbors);
+  }
+  return adjacency;
+}