trekoon 0.2.9 → 0.3.1

package/src/commands/suggest.ts

@@ -0,0 +1,283 @@
+import { parseArgs, readOption } from "./arg-parser";
+import { unexpectedFailureResult } from "./error-utils";
+import { resolveSyncStatus } from "./sync-helpers";
+import { buildTaskReadiness, type TaskReadinessResult } from "./task-readiness";
+
+import { TrackerDomain } from "../domain/tracker-domain";
+import { VALID_TRANSITIONS, type EpicRecord, type ValidStatus } from "../domain/types";
+import { okResult } from "../io/output";
+import { type CliContext, type CliResult } from "../runtime/command-types";
+import { openTrekoonDatabase, type TrekoonDatabase } from "../storage/database";
+import type { SyncStatusSummary } from "../sync/types";
+
+import { DEFAULT_SOURCE_BRANCH } from "./sync-helpers";
+
+const MAX_SUGGESTIONS = 3;
+
+type SuggestionCategory = "recovery" | "sync" | "execution" | "planning";
+
+interface Suggestion {
+  readonly priority: number;
+  readonly action: string;
+  readonly command: string;
+  readonly reason: string;
+  readonly category: SuggestionCategory;
+}
+
+interface SuggestContext {
+  readonly totalEpics: number;
+  readonly activeEpic: string | null;
+  readonly readyTasks: number;
+  readonly blockedTasks: number;
+  readonly inProgressTasks: number;
+  readonly syncBehind: number;
+  readonly pendingConflicts: number;
+}
+
+interface SuggestResult {
+  readonly suggestions: readonly Suggestion[];
+  readonly context: SuggestContext;
+}
+
+function resolveActiveEpic(domain: TrackerDomain, epicId: string | undefined): EpicRecord | null {
+  if (epicId !== undefined) {
+    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;
+}
+
+function findInProgressTasks(readiness: TaskReadinessResult): { count: number; first: { id: string; title: string } | null } {
+  let count = 0;
+  let first: { id: string; title: string } | null = null;
+
+  for (const list of [readiness.candidates, readiness.blocked]) {
+    for (const candidate of list) {
+      if (candidate.task.status === "in_progress") {
+        count += 1;
+        if (first === null) {
+          first = { id: candidate.task.id, title: candidate.task.title };
+        }
+      }
+    }
+  }
+
+  return { count, first };
+}
+
+function buildSuggestions(
+  recoveryRequired: boolean,
+  syncSummary: SyncStatusSummary,
+  readiness: TaskReadinessResult,
+  epics: readonly EpicRecord[],
+  activeEpic: EpicRecord | null,
+): readonly Suggestion[] {
+  const suggestions: Suggestion[] = [];
+
+  // Priority 1: Recovery required
+  if (recoveryRequired) {
+    suggestions.push({
+      priority: suggestions.length + 1,
+      action: "init",
+      command: "trekoon --toon init",
+      reason: "Storage needs repair — run init to recover",
+      category: "recovery",
+    });
+  }
+
+  // Priority 2: Pending conflicts
+  if (suggestions.length < MAX_SUGGESTIONS && syncSummary.pendingConflicts > 0) {
+    suggestions.push({
+      priority: suggestions.length + 1,
+      action: "sync conflicts",
+      command: "trekoon --toon sync conflicts",
+      reason: `${syncSummary.pendingConflicts} unresolved sync conflict${syncSummary.pendingConflicts === 1 ? "" : "s"} blocking accurate state`,
+      category: "sync",
+    });
+  }
+
+  // Priority 3: Sync behind
+  if (suggestions.length < MAX_SUGGESTIONS && syncSummary.behind > 0) {
+    suggestions.push({
+      priority: suggestions.length + 1,
+      action: `sync pull --from ${syncSummary.sourceBranch}`,
+      command: `trekoon --toon sync pull --from ${syncSummary.sourceBranch}`,
+      reason: `${syncSummary.behind} event${syncSummary.behind === 1 ? "" : "s"} behind ${syncSummary.sourceBranch} branch`,
+      category: "sync",
+    });
+  }
+
+  // Priority 4: In-progress tasks exist
+  const { first: inProgressTask } = findInProgressTasks(readiness);
+  if (suggestions.length < MAX_SUGGESTIONS && inProgressTask !== null) {
+    suggestions.push({
+      priority: suggestions.length + 1,
+      action: `continue task ${inProgressTask.id}`,
+      command: `trekoon --toon task show ${inProgressTask.id}`,
+      reason: `In-progress task: ${inProgressTask.title}`,
+      category: "execution",
+    });
+  }
+
+  // Priority 5: Ready tasks available
+  const topReady = readiness.candidates.find((c) => c.task.status !== "in_progress");
+  if (suggestions.length < MAX_SUGGESTIONS && topReady) {
+    suggestions.push({
+      priority: suggestions.length + 1,
+      action: `claim task ${topReady.task.id}`,
+      command: `trekoon --toon task update ${topReady.task.id} --status in_progress`,
+      reason: `Highest priority ready task: ${topReady.task.title}`,
+      category: "execution",
+    });
+  }
+
+  // Priority 6: All tasks blocked
+  if (
+    suggestions.length < MAX_SUGGESTIONS
+    && readiness.summary.totalOpenTasks > 0
+    && readiness.summary.readyCount === 0
+    && inProgressTask === null
+  ) {
+    const blockerCount = readiness.summary.unresolvedDependencyCount;
+    suggestions.push({
+      priority: suggestions.length + 1,
+      action: "review blocked tasks",
+      command: "trekoon --toon task ready",
+      reason: `All ${readiness.summary.blockedCount} open task${readiness.summary.blockedCount === 1 ? " is" : "s are"} blocked by ${blockerCount} unresolved dependenc${blockerCount === 1 ? "y" : "ies"}`,
+      category: "planning",
+    });
+  }
+
+  // Priority 7: All tasks done (epic still open)
+  if (
+    suggestions.length < MAX_SUGGESTIONS
+    && activeEpic !== null
+    && readiness.summary.totalOpenTasks === 0
+    && activeEpic.status !== "done"
+  ) {
+    const epicStatus = activeEpic.status as ValidStatus;
+    const validTargets = VALID_TRANSITIONS.get(epicStatus);
+    const canTransitionToDone = validTargets?.has("done") === true;
+
+    if (canTransitionToDone) {
+      suggestions.push({
+        priority: suggestions.length + 1,
+        action: `mark epic ${activeEpic.id} done`,
+        command: `trekoon --toon epic update ${activeEpic.id} --status done`,
+        reason: `All tasks complete — mark epic "${activeEpic.title}" as done`,
+        category: "planning",
+      });
+    } else if (validTargets?.has("in_progress") === true) {
+      suggestions.push({
+        priority: suggestions.length + 1,
+        action: `advance epic ${activeEpic.id} to in_progress`,
+        command: `trekoon --toon epic update ${activeEpic.id} --status in_progress`,
+        reason: `All tasks complete — advance epic "${activeEpic.title}" to in_progress first (then mark done)`,
+        category: "planning",
+      });
+    }
+  }
+
+  // Priority 8: No epics exist
+  if (suggestions.length < MAX_SUGGESTIONS && epics.length === 0) {
+    suggestions.push({
+      priority: suggestions.length + 1,
+      action: "quickstart",
+      command: "trekoon --toon quickstart",
+      reason: "No epics found — create your first epic with quickstart",
+      category: "planning",
+    });
+  }
+
+  return suggestions.slice(0, MAX_SUGGESTIONS);
+}
+
+function formatSuggestHuman(result: SuggestResult): string {
+  const lines: string[] = [];
+
+  if (result.suggestions.length === 0) {
+    lines.push("No suggestions — tracker state looks good.");
+    return lines.join("\n");
+  }
+
+  lines.push("=== Suggestions ===");
+  for (const suggestion of result.suggestions) {
+    lines.push(`${suggestion.priority}. [${suggestion.category}] ${suggestion.action}`);
+    lines.push(`   Reason: ${suggestion.reason}`);
+    lines.push(`   Command: ${suggestion.command}`);
+  }
+
+  lines.push("");
+  lines.push("=== Context ===");
+  lines.push(`Epics: ${result.context.totalEpics}`);
+  if (result.context.activeEpic !== null) {
+    lines.push(`Active epic: ${result.context.activeEpic}`);
+  }
+  lines.push(`Ready tasks: ${result.context.readyTasks}`);
+  lines.push(`Blocked tasks: ${result.context.blockedTasks}`);
+  lines.push(`In-progress tasks: ${result.context.inProgressTasks}`);
+  lines.push(`Sync behind: ${result.context.syncBehind}`);
+  lines.push(`Pending conflicts: ${result.context.pendingConflicts}`);
+
+  return lines.join("\n");
+}
+
+export async function runSuggest(context: CliContext): Promise<CliResult> {
+  let database: TrekoonDatabase | undefined;
+
+  try {
+    const parsed = parseArgs(context.args);
+    const epicId: string | undefined = readOption(parsed.options, "epic");
+
+    database = openTrekoonDatabase(context.cwd);
+    const diagnostics = database.diagnostics;
+
+    const syncSummary = resolveSyncStatus(database, context.cwd, DEFAULT_SOURCE_BRANCH);
+    const domain = new TrackerDomain(database.db);
+    const epics = domain.listEpics();
+    const activeEpic = resolveActiveEpic(domain, epicId);
+
+    const readiness = buildTaskReadiness(domain, epicId ?? activeEpic?.id);
+
+    const suggestions = buildSuggestions(
+      diagnostics.recoveryRequired,
+      syncSummary,
+      readiness,
+      epics,
+      activeEpic,
+    );
+
+    const result: SuggestResult = {
+      suggestions,
+      context: {
+        totalEpics: epics.length,
+        activeEpic: activeEpic?.id ?? null,
+        readyTasks: readiness.summary.readyCount,
+        blockedTasks: readiness.summary.blockedCount,
+        inProgressTasks: findInProgressTasks(readiness).count,
+        syncBehind: syncSummary.behind,
+        pendingConflicts: syncSummary.pendingConflicts,
+      },
+    };
+
+    return okResult({
+      command: "suggest",
+      human: formatSuggestHuman(result),
+      data: result,
+    });
+  } catch (error: unknown) {
+    return unexpectedFailureResult(error, {
+      command: "suggest",
+      human: "Unexpected suggest command failure",
+    });
+  } finally {
+    database?.close();
+  }
+}

package/src/commands/sync-helpers.ts

@@ -0,0 +1,75 @@
+import type { Database } from "bun:sqlite";
+
+import { countBranchEventsSince } from "../sync/branch-db";
+import { persistGitContext, resolveGitContext } from "../sync/git-context";
+import type { GitContextSnapshot, SyncStatusSummary } from "../sync/types";
+import type { TrekoonDatabase } from "../storage/database";
+
+export const DEFAULT_SOURCE_BRANCH = "main";
+
+export function countAheadLocal(db: Database, currentBranch: string | null, sourceBranch: string): number {
+  if (!currentBranch || currentBranch === sourceBranch) {
+    return 0;
+  }
+
+  const row = db
+    .query(
+      `
+      SELECT COUNT(*) AS count
+      FROM events
+      WHERE git_branch = @branch;
+      `,
+    )
+    .get({ "@branch": currentBranch }) as { count: number } | null;
+
+  return row?.count ?? 0;
+}
+
+export function countPendingConflictsLocal(db: Database): number {
+  const row = db
+    .query("SELECT COUNT(*) AS count FROM sync_conflicts WHERE resolution = 'pending';")
+    .get() as { count: number } | null;
+
+  return row?.count ?? 0;
+}
+
+export function loadCursorLocal(
+  db: Database,
+  worktreePath: string,
+  sourceBranch: string,
+): { cursor_token: string } | null {
+  return db
+    .query(
+      `
+      SELECT cursor_token
+      FROM sync_cursors
+      WHERE owner_scope = 'worktree'
+        AND owner_worktree_path = ?
+        AND source_branch = ?
+      LIMIT 1;
+      `,
+    )
+    .get(worktreePath, sourceBranch) as { cursor_token: string } | null;
+}
+
+export function resolveSyncStatus(
+  database: TrekoonDatabase,
+  cwd: string,
+  sourceBranch: string,
+): SyncStatusSummary {
+  const git: GitContextSnapshot = resolveGitContext(cwd);
+  persistGitContext(database.db, git);
+
+  const cursor = loadCursorLocal(database.db, git.worktreePath, sourceBranch);
+  const cursorToken: string = cursor?.cursor_token ?? "0:";
+  const onSourceBranch: boolean = git.branchName !== null && git.branchName === sourceBranch;
+
+  return {
+    sourceBranch,
+    ahead: countAheadLocal(database.db, git.branchName, sourceBranch),
+    behind: onSourceBranch ? 0 : countBranchEventsSince(database.db, sourceBranch, cursorToken),
+    pendingConflicts: countPendingConflictsLocal(database.db),
+    sameBranch: onSourceBranch,
+    git,
+  };
+}

package/src/commands/task-readiness.ts

@@ -1,7 +1,7 @@
 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 DEFAULT_OPEN_TASK_STATUSES = ["in_progress", "todo"] as const;
 export const READY_REASON_READY = "all_dependencies_done";
 export const READY_REASON_BLOCKED = "blocked_by_dependencies";
 
@@ -49,7 +49,7 @@ export interface TaskReadinessResult {
 }
 
 export function taskStatusPriority(status: string): number {
-  if (status === "in_progress" || status === "in-progress") {
+  if (status === "in_progress") {
     return 0;
   }
 
@@ -63,25 +63,13 @@ export function taskStatusPriority(status: string): number {
 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 taskIds = openTasks.map((task) => task.id);
+  const depMap = domain.batchResolveDependencyStatuses(taskIds);
+
   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 resolved = depMap.get(task.id) ?? { totalDependencies: 0, blockers: [] };
+      const blockers: DependencyBlocker[] = resolved.blockers;
       const blockerCount = blockers.length;
       const readinessReason: ReadyReason = blockerCount === 0 ? READY_REASON_READY : READY_REASON_BLOCKED;
       return {
@@ -91,7 +79,7 @@ export function buildTaskReadiness(domain: TrackerDomain, epicId: string | undef
           reason: readinessReason,
         },
         blockerSummary: {
-          totalDependencies: dependencies.length,
+          totalDependencies: resolved.totalDependencies,
           blockedByCount: blockerCount,
           blockedBy: blockers,
         },

package/src/commands/task.ts

@@ -46,7 +46,7 @@ const SHOW_OPTIONS = ["view", "all"] as const;
 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"] as const;
+const UPDATE_OPTIONS = ["all", "ids", "append", "description", "d", "status", "s", "title", "t", "owner"] as const;
 const STATUS_CASCADE_UPDATE_STATUSES = ["done", "todo"] as const;
 
 function parseIdsOption(rawIds: string | undefined): string[] {
@@ -1071,7 +1071,8 @@ export async function runTask(context: CliContext): Promise<CliResult> {
           readMissingOptionValue(parsed.missingOptionValues, "ids") ??
           readMissingOptionValue(parsed.missingOptionValues, "append") ??
           readMissingOptionValue(parsed.missingOptionValues, "description", "d") ??
-          readMissingOptionValue(parsed.missingOptionValues, "status", "s");
+          readMissingOptionValue(parsed.missingOptionValues, "status", "s") ??
+          readMissingOptionValue(parsed.missingOptionValues, "owner");
         if (missingUpdateOption !== undefined) {
           return failMissingOptionValue("task.update", missingUpdateOption);
         }
@@ -1084,6 +1085,7 @@ export async function runTask(context: CliContext): Promise<CliResult> {
         const description: string | undefined = readOption(parsed.options, "description", "d");
         const append: string | undefined = readOption(parsed.options, "append");
         const status: string | undefined = readOption(parsed.options, "status", "s");
+        const owner: string | undefined = readOption(parsed.options, "owner");
 
         if (updateAll && ids.length > 0) {
           return failResult({
@@ -1210,7 +1212,7 @@ export async function runTask(context: CliContext): Promise<CliResult> {
           append === undefined
             ? description
             : appendLine(domain.getTaskOrThrow(taskId).description, append);
-        const task = mutations.updateTask(taskId, { title, description: nextDescription, status });
+        const task = mutations.updateTask(taskId, { title, description: nextDescription, status, owner });
 
         return okResult({
           command: "task.update",
@@ -1257,10 +1259,50 @@ export async function runTask(context: CliContext): Promise<CliResult> {
           });
         }
 
+        // 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 ?? [];
 
@@ -1269,7 +1311,17 @@ export async function runTask(context: CliContext): Promise<CliResult> {
           blockedCount: readiness.summary.blockedCount,
         };
 
+        const subtaskWarning = openSubtaskCount > 0
+          ? `Warning: ${openSubtaskCount} subtask(s) still open.`
+          : null;
+
         let human = `Task ${completed.title} marked done.`;
+        if (subtaskWarning !== null) {
+          human += `\n${subtaskWarning}`;
+        }
+        if (unblockedTasks.length > 0) {
+          human += `\nUnblocked: ${unblockedTasks.map((t) => t.title).join(", ")}`;
+        }
         if (nextTree !== null && nextCandidate !== null) {
           human += `\nNext: ${formatTask(nextCandidate.task)}`;
         }
@@ -1280,6 +1332,10 @@ export async function runTask(context: CliContext): Promise<CliResult> {
           human,
           data: {
             completed,
+            openSubtaskCount,
+            openSubtaskIds,
+            warning: subtaskWarning,
+            unblocked: unblockedTasks,
             next: nextTree,
             nextDeps,
             readiness: readinessStats,