trekoon 0.2.1 → 0.2.4

package/src/commands/sync.ts

@@ -1,9 +1,11 @@
 import { findUnknownOption, parseArgs, readMissingOptionValue, readOption, suggestOptions } from "./arg-parser";
 import { safeErrorMessage, sqliteBusyFailure } from "./error-utils";
 
+import { DomainError } from "../domain/types";
 import { failResult, okResult } from "../io/output";
 import { type CliContext, type CliResult } from "../runtime/command-types";
-import { MissingBranchDatabaseError } from "../sync/branch-db";
+import { resolveStorageResolutionDiagnostics } from "../storage/database";
+import { assertValidSourceRef } from "../sync/branch-db";
 import { getSyncConflict, listSyncConflicts, syncPull, syncResolve, syncStatus } from "../sync/service";
 import { type SyncResolution } from "../sync/types";
 
@@ -110,6 +112,15 @@ function formatConflictList(
     .join("\n");
 }
 
+function formatDomainErrorHuman(message: string, details: Record<string, unknown> | undefined): string {
+  const operatorAction = typeof details?.operatorAction === "string" ? details.operatorAction : null;
+  return operatorAction ? `${message}\n${operatorAction}` : message;
+}
+
+function isStorageBootstrapError(code: string): boolean {
+  return code === "tracked_ignored_mismatch" || code === "ambiguous_legacy_state" || code === "legacy_import_failed";
+}
+
 export async function runSync(context: CliContext): Promise<CliResult> {
   const parsed = parseArgs(context.args);
   const subcommand: string | undefined = parsed.positional[0];
@@ -133,11 +144,17 @@ export async function runSync(context: CliContext): Promise<CliResult> {
       }
 
       const sourceBranch: string = readOption(parsed.options, "from") ?? "main";
+      assertValidSourceRef(context.cwd, sourceBranch);
       const summary = syncStatus(context.cwd, sourceBranch);
 
+      const humanLines = [statusMessage(summary.sourceBranch, summary.ahead, summary.behind, summary.pendingConflicts)];
+      if (summary.sameBranch) {
+        humanLines.push(`Same-branch mode: already on '${summary.sourceBranch}', no sync needed`);
+      }
+
       return okResult({
         command: "sync.status",
-        human: statusMessage(summary.sourceBranch, summary.ahead, summary.behind, summary.pendingConflicts),
+        human: humanLines.join("\n"),
         data: summary,
       });
     }
@@ -158,20 +175,26 @@ export async function runSync(context: CliContext): Promise<CliResult> {
         return usage("sync pull requires --from <branch>.", "sync.pull");
       }
 
+      assertValidSourceRef(context.cwd, sourceBranch);
       const summary = syncPull(context.cwd, sourceBranch);
 
+      const humanLines = [
+        `Pulled from '${summary.sourceBranch}'`,
+        `Scanned events: ${summary.scannedEvents}`,
+        `Applied events: ${summary.appliedEvents}`,
+        `Created conflicts: ${summary.createdConflicts}`,
+        `Malformed payloads: ${summary.diagnostics.malformedPayloadEvents}`,
+        `Quarantined events: ${summary.diagnostics.quarantinedEvents}`,
+        `Conflict events: ${summary.diagnostics.conflictEvents}`,
+        ...summary.diagnostics.errorHints,
+      ];
+      if (summary.sameBranch) {
+        humanLines.push(`Same-branch mode: already on '${summary.sourceBranch}', no sync needed`);
+      }
+
       return okResult({
         command: "sync.pull",
-        human: [
-          `Pulled from '${summary.sourceBranch}'`,
-          `Scanned events: ${summary.scannedEvents}`,
-          `Applied events: ${summary.appliedEvents}`,
-          `Created conflicts: ${summary.createdConflicts}`,
-          `Malformed payloads: ${summary.diagnostics.malformedPayloadEvents}`,
-          `Quarantined events: ${summary.diagnostics.quarantinedEvents}`,
-          `Conflict events: ${summary.diagnostics.conflictEvents}`,
-          ...summary.diagnostics.errorHints,
-        ].join("\n"),
+        human: humanLines.join("\n"),
         data: summary,
       });
     }
@@ -275,25 +298,43 @@ export async function runSync(context: CliContext): Promise<CliResult> {
 
     return usage(`Unknown sync subcommand '${subcommand}'.`);
   } catch (error) {
-    if (error instanceof MissingBranchDatabaseError) {
+    const busyFailure = sqliteBusyFailure(resolvedCommand, error);
+    if (busyFailure !== null) {
+      return busyFailure;
+    }
+
+    if (error instanceof DomainError) {
+      if (isStorageBootstrapError(error.code)) {
+        const storageDiagnostics = resolveStorageResolutionDiagnostics(context.cwd);
+
+        return failResult({
+          command: resolvedCommand,
+          human: formatDomainErrorHuman(error.message, error.details),
+          data: {
+            reason: "storage_bootstrap_blocked",
+            ...storageDiagnostics,
+          },
+          error: {
+            code: error.code,
+            message: error.message,
+          },
+        });
+      }
+
       return failResult({
         command: resolvedCommand,
-        human: error.message,
+        human: formatDomainErrorHuman(error.message, error.details),
         data: {
-          reason: "missing_branch_db",
+          ...(error.details ?? {}),
+          reason: error.code,
         },
         error: {
-          code: "missing_branch_db",
+          code: error.code,
           message: error.message,
         },
       });
     }
 
-    const busyFailure = sqliteBusyFailure(resolvedCommand, error);
-    if (busyFailure !== null) {
-      return busyFailure;
-    }
-
     const message = safeErrorMessage(error, "Unknown sync error.");
 
     return failResult({

package/src/commands/task-readiness.ts

@@ -0,0 +1,147 @@
+import { TrackerDomain } from "../domain/tracker-domain";
+import { type TaskRecord } from "../domain/types";
+
+export const DEFAULT_OPEN_TASK_STATUSES = ["in_progress", "in-progress", "todo"] as const;
+export const READY_REASON_READY = "all_dependencies_done";
+export const READY_REASON_BLOCKED = "blocked_by_dependencies";
+
+export interface DependencyBlocker {
+  readonly id: string;
+  readonly kind: "task" | "subtask";
+  readonly status: string;
+}
+
+export interface TaskReadyCandidate {
+  readonly task: TaskRecord;
+  readonly readiness: {
+    readonly isReady: boolean;
+    readonly reason: typeof READY_REASON_READY | typeof READY_REASON_BLOCKED;
+  };
+  readonly blockerSummary: {
+    readonly totalDependencies: number;
+    readonly blockedByCount: number;
+    readonly blockedBy: ReadonlyArray<DependencyBlocker>;
+  };
+  readonly ranking: {
+    readonly statusPriority: number;
+    readonly blockerCount: number;
+    readonly createdAt: number;
+    readonly id: string;
+    readonly rank: number;
+  };
+}
+
+export type ReadyReason = typeof READY_REASON_READY | typeof READY_REASON_BLOCKED;
+
+export interface TaskReadinessSummary {
+  readonly totalOpenTasks: number;
+  readonly readyCount: number;
+  readonly returnedCount: number;
+  readonly appliedLimit: number | null;
+  readonly blockedCount: number;
+  readonly unresolvedDependencyCount: number;
+}
+
+export interface TaskReadinessResult {
+  readonly candidates: readonly TaskReadyCandidate[];
+  readonly blocked: readonly TaskReadyCandidate[];
+  readonly summary: TaskReadinessSummary;
+}
+
+export function taskStatusPriority(status: string): number {
+  if (status === "in_progress" || status === "in-progress") {
+    return 0;
+  }
+
+  if (status === "todo") {
+    return 1;
+  }
+
+  return 2;
+}
+
+export function buildTaskReadiness(domain: TrackerDomain, epicId: string | undefined): TaskReadinessResult {
+  const openStatuses = new Set<string>(DEFAULT_OPEN_TASK_STATUSES);
+  const openTasks = domain.listTasks(epicId).filter((task) => openStatuses.has(task.status));
+  const assessed = openTasks
+    .map((task) => {
+      const blockers: DependencyBlocker[] = [];
+      const dependencies = domain.listDependencies(task.id);
+      for (const dependency of dependencies) {
+        const dependencyStatus =
+          dependency.dependsOnKind === "task"
+            ? domain.getTaskOrThrow(dependency.dependsOnId).status
+            : domain.getSubtaskOrThrow(dependency.dependsOnId).status;
+
+        if (dependencyStatus !== "done") {
+          blockers.push({
+            id: dependency.dependsOnId,
+            kind: dependency.dependsOnKind,
+            status: dependencyStatus,
+          });
+        }
+      }
+
+      const blockerCount = blockers.length;
+      const readinessReason: ReadyReason = blockerCount === 0 ? READY_REASON_READY : READY_REASON_BLOCKED;
+      return {
+        task,
+        readiness: {
+          isReady: blockerCount === 0,
+          reason: readinessReason,
+        },
+        blockerSummary: {
+          totalDependencies: dependencies.length,
+          blockedByCount: blockerCount,
+          blockedBy: blockers,
+        },
+        ranking: {
+          statusPriority: taskStatusPriority(task.status),
+          blockerCount,
+          createdAt: task.createdAt,
+          id: task.id,
+          rank: 0,
+        },
+      };
+    })
+    .sort((left, right) => {
+      const byStatus = left.ranking.statusPriority - right.ranking.statusPriority;
+      if (byStatus !== 0) {
+        return byStatus;
+      }
+
+      const byBlockers = left.ranking.blockerCount - right.ranking.blockerCount;
+      if (byBlockers !== 0) {
+        return byBlockers;
+      }
+
+      const byCreatedAt = left.ranking.createdAt - right.ranking.createdAt;
+      if (byCreatedAt !== 0) {
+        return byCreatedAt;
+      }
+
+      return left.ranking.id.localeCompare(right.ranking.id);
+    })
+    .map((item, index) => ({
+      ...item,
+      ranking: {
+        ...item.ranking,
+        rank: index + 1,
+      },
+    }));
+
+  const candidates = assessed.filter((item) => item.readiness.isReady);
+  const blocked = assessed.filter((item) => !item.readiness.isReady);
+  return {
+    candidates,
+    blocked,
+    summary: {
+      totalOpenTasks: assessed.length,
+      readyCount: candidates.length,
+      returnedCount: candidates.length,
+      appliedLimit: null,
+      blockedCount: blocked.length,
+      unresolvedDependencyCount: blocked.reduce((total, item) => total + item.blockerSummary.blockedByCount, 0),
+    },
+  };
+}

package/src/commands/task.ts

@@ -17,6 +17,18 @@ import {
   suggestOptions,
 } from "./arg-parser";
 import { unexpectedFailureResult } from "./error-utils";
+import {
+  buildTaskReadiness,
+  DEFAULT_OPEN_TASK_STATUSES,
+  type DependencyBlocker,
+  READY_REASON_BLOCKED,
+  READY_REASON_READY,
+  type ReadyReason,
+  taskStatusPriority,
+  type TaskReadinessResult,
+  type TaskReadinessSummary,
+  type TaskReadyCandidate,
+} from "./task-readiness";
 
 import { MutationService } from "../domain/mutation-service";
 import { TrackerDomain } from "../domain/tracker-domain";
@@ -33,56 +45,10 @@ function formatTask(task: TaskRecord): string {
 const VIEW_MODES = ["table", "compact", "tree", "detail"] as const;
 const LIST_VIEW_MODES = ["table", "compact"] as const;
 const DEFAULT_TASK_LIST_LIMIT = 10;
-const DEFAULT_OPEN_TASK_STATUSES = ["in_progress", "in-progress", "todo"] as const;
-const READY_REASON_READY = "all_dependencies_done";
-const READY_REASON_BLOCKED = "blocked_by_dependencies";
 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;
 
-interface DependencyBlocker {
-  readonly id: string;
-  readonly kind: "task" | "subtask";
-  readonly status: string;
-}
-
-interface TaskReadyCandidate {
-  readonly task: TaskRecord;
-  readonly readiness: {
-    readonly isReady: boolean;
-    readonly reason: typeof READY_REASON_READY | typeof READY_REASON_BLOCKED;
-  };
-  readonly blockerSummary: {
-    readonly totalDependencies: number;
-    readonly blockedByCount: number;
-    readonly blockedBy: ReadonlyArray<DependencyBlocker>;
-  };
-  readonly ranking: {
-    readonly statusPriority: number;
-    readonly blockerCount: number;
-    readonly createdAt: number;
-    readonly id: string;
-    readonly rank: number;
-  };
-}
-
-type ReadyReason = typeof READY_REASON_READY | typeof READY_REASON_BLOCKED;
-
-interface TaskReadinessSummary {
-  readonly totalOpenTasks: number;
-  readonly readyCount: number;
-  readonly returnedCount: number;
-  readonly appliedLimit: number | null;
-  readonly blockedCount: number;
-  readonly unresolvedDependencyCount: number;
-}
-
-interface TaskReadinessResult {
-  readonly candidates: readonly TaskReadyCandidate[];
-  readonly blocked: readonly TaskReadyCandidate[];
-  readonly summary: TaskReadinessSummary;
-}
-
 function parseIdsOption(rawIds: string | undefined): string[] {
   if (rawIds === undefined) {
     return [];
@@ -154,102 +120,6 @@ function parseStatusCsv(rawStatuses: string | undefined): string[] | undefined {
     .filter((value) => value.length > 0);
 }
 
-function taskStatusPriority(status: string): number {
-  if (status === "in_progress" || status === "in-progress") {
-    return 0;
-  }
-
-  if (status === "todo") {
-    return 1;
-  }
-
-  return 2;
-}
-
-function buildTaskReadiness(domain: TrackerDomain, epicId: string | undefined): TaskReadinessResult {
-  const openStatuses = new Set<string>(DEFAULT_OPEN_TASK_STATUSES);
-  const openTasks = domain.listTasks(epicId).filter((task) => openStatuses.has(task.status));
-  const assessed = openTasks
-    .map((task) => {
-      const blockers: DependencyBlocker[] = [];
-      const dependencies = domain.listDependencies(task.id);
-      for (const dependency of dependencies) {
-        const dependencyStatus =
-          dependency.dependsOnKind === "task"
-            ? domain.getTaskOrThrow(dependency.dependsOnId).status
-            : domain.getSubtaskOrThrow(dependency.dependsOnId).status;
-
-        if (dependencyStatus !== "done") {
-          blockers.push({
-            id: dependency.dependsOnId,
-            kind: dependency.dependsOnKind,
-            status: dependencyStatus,
-          });
-        }
-      }
-
-      const blockerCount = blockers.length;
-      const readinessReason: ReadyReason = blockerCount === 0 ? READY_REASON_READY : READY_REASON_BLOCKED;
-      return {
-        task,
-        readiness: {
-          isReady: blockerCount === 0,
-          reason: readinessReason,
-        },
-        blockerSummary: {
-          totalDependencies: dependencies.length,
-          blockedByCount: blockerCount,
-          blockedBy: blockers,
-        },
-        ranking: {
-          statusPriority: taskStatusPriority(task.status),
-          blockerCount,
-          createdAt: task.createdAt,
-          id: task.id,
-        },
-      };
-    })
-    .sort((left, right) => {
-      const byStatus = left.ranking.statusPriority - right.ranking.statusPriority;
-      if (byStatus !== 0) {
-        return byStatus;
-      }
-
-      const byBlockers = left.ranking.blockerCount - right.ranking.blockerCount;
-      if (byBlockers !== 0) {
-        return byBlockers;
-      }
-
-      const byCreatedAt = left.ranking.createdAt - right.ranking.createdAt;
-      if (byCreatedAt !== 0) {
-        return byCreatedAt;
-      }
-
-      return left.ranking.id.localeCompare(right.ranking.id);
-    })
-    .map((item, index) => ({
-      ...item,
-      ranking: {
-        ...item.ranking,
-        rank: index + 1,
-      },
-    }));
-
-  const candidates = assessed.filter((item) => item.readiness.isReady);
-  const blocked = assessed.filter((item) => !item.readiness.isReady);
-  return {
-    candidates,
-    blocked,
-    summary: {
-      totalOpenTasks: assessed.length,
-      readyCount: candidates.length,
-      returnedCount: candidates.length,
-      appliedLimit: null,
-      blockedCount: blocked.length,
-      unresolvedDependencyCount: blocked.reduce((total, item) => total + item.blockerSummary.blockedByCount, 0),
-    },
-  };
-}
 
 function formatTaskReadyCandidateLine(candidate: TaskReadyCandidate): string {
   return `${candidate.ranking.rank}. ${formatTask(candidate.task)} | reason=${candidate.readiness.reason} | blockers=${candidate.blockerSummary.blockedByCount}/${candidate.blockerSummary.totalDependencies}`;
@@ -1242,6 +1112,74 @@ export async function runTask(context: CliContext): Promise<CliResult> {
           data: { task },
         });
       }
+      case "done": {
+        const taskId: string = parsed.positional[1] ?? "";
+        if (taskId.length === 0) {
+          return failResult({
+            command: "task.done",
+            human: "Provide a task id. Usage: trekoon task done <id>",
+            data: { code: "invalid_input" },
+            error: {
+              code: "invalid_input",
+              message: "Missing task id",
+            },
+          });
+        }
+
+        const existingTask = domain.getTask(taskId);
+        if (!existingTask) {
+          return failResult({
+            command: "task.done",
+            human: `Task not found: ${taskId}`,
+            data: { code: "not_found", id: taskId },
+            error: {
+              code: "not_found",
+              message: `Task not found: ${taskId}`,
+            },
+          });
+        }
+
+        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",
+            },
+          });
+        }
+
+        const completed = mutations.updateTask(taskId, { status: "done" });
+        const readiness = buildTaskReadiness(domain, completed.epicId);
+        const nextCandidate = readiness.candidates[0] ?? null;
+
+        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,
+        };
+
+        let human = `Task ${completed.title} marked done.`;
+        if (nextTree !== null && nextCandidate !== null) {
+          human += `\nNext: ${formatTask(nextCandidate.task)}`;
+        }
+        human += `\nReadiness: ready=${readinessStats.readyCount}, blocked=${readinessStats.blockedCount}.`;
+
+        return okResult({
+          command: "task.done",
+          human,
+          data: {
+            completed,
+            next: nextTree,
+            nextDeps,
+            readiness: readinessStats,
+          },
+        });
+      }
       case "delete": {
         const taskId: string = parsed.positional[1] ?? "";
         mutations.deleteTask(taskId);
@@ -1255,7 +1193,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|search|replace|update|delete>",
+          human: "Usage: trekoon task <create|create-many|list|show|ready|next|done|search|replace|update|delete>",
           data: {
             args: context.args,
           },

package/src/commands/wipe.ts

@@ -6,22 +6,29 @@ import { resolveStoragePaths } from "../storage/path";
 
 export async function runWipe(context: CliContext): Promise<CliResult> {
   const confirmed: boolean = context.args.includes("--yes");
+  const paths = resolveStoragePaths(context.cwd);
+  const repoScoped: boolean = paths.storageMode === "git_common_dir";
+  const sharedAcrossWorktrees: boolean = repoScoped && paths.sharedStorageRoot !== paths.worktreeRoot;
+  const scopeLabel: string = repoScoped ? "repo-wide Trekoon state" : "local Trekoon state";
 
   if (!confirmed) {
     return failResult({
       command: "wipe",
-      human: "Refusing to wipe local state without --yes.",
+      human: `Refusing to wipe ${scopeLabel} without --yes. This deletes ${paths.storageDir}${repoScoped ? " for the entire repository, including any linked worktrees that share this storage" : " for this working directory"}.`,
       data: {
         confirmed,
+        storageDir: paths.storageDir,
+        worktreeRoot: paths.worktreeRoot,
+        sharedStorageRoot: paths.sharedStorageRoot,
+        repoScoped,
       },
       error: {
         code: "confirmation_required",
-        message: "Wipe requires --yes",
+        message: `Wipe requires --yes to remove ${scopeLabel}`,
       },
     });
   }
 
-  const paths = resolveStoragePaths(context.cwd);
   const existed: boolean = existsSync(paths.storageDir);
 
   rmSync(paths.storageDir, { recursive: true, force: true });
@@ -29,10 +36,13 @@ export async function runWipe(context: CliContext): Promise<CliResult> {
   return okResult({
     command: "wipe",
     human: existed
-      ? `Removed local Trekoon state at ${paths.storageDir}`
-      : `No local Trekoon state found at ${paths.storageDir}`,
+      ? `Removed ${scopeLabel} at ${paths.storageDir}${repoScoped ? ` for repository ${paths.sharedStorageRoot}` : ""}${sharedAcrossWorktrees ? ", which is shared with linked worktrees" : ""}.`
+      : `No ${scopeLabel} found at ${paths.storageDir}${repoScoped ? ` for repository ${paths.sharedStorageRoot}` : ""}${sharedAcrossWorktrees ? ", which is shared with linked worktrees" : ""}.`,
     data: {
       storageDir: paths.storageDir,
+      worktreeRoot: paths.worktreeRoot,
+      sharedStorageRoot: paths.sharedStorageRoot,
+      repoScoped,
       wiped: existed,
     },
   });