trekoon 0.2.0 → 0.2.4

package/src/commands/subtask.ts

@@ -2,24 +2,29 @@ import {
   SEARCH_REPLACE_FIELDS,
   findUnknownOption,
   hasFlag,
+  isValidCompactTempKey,
   parseArgs,
+  parseCompactFields,
   parseCsvEnumOption,
   parseStrictNonNegativeInt,
   parseStrictPositiveInt,
   readEnumOption,
   readMissingOptionValue,
   readOption,
+  readOptions,
+  readUnexpectedPositionals,
   resolvePreviewApplyMode,
   suggestOptions,
 } from "./arg-parser";
+import { unexpectedFailureResult } from "./error-utils";
 
 import { MutationService } from "../domain/mutation-service";
 import { TrackerDomain } from "../domain/tracker-domain";
-import { DomainError, type SearchEntityMatch, type SubtaskRecord } from "../domain/types";
+import { type CompactBatchResultContract, type CompactSubtaskSpec, type SearchEntityMatch, type SubtaskRecord } from "../domain/types";
 import { formatHumanTable } from "../io/human-table";
 import { failResult, okResult } from "../io/output";
 import { type CliContext, type CliResult } from "../runtime/command-types";
-import { openTrekoonDatabase } from "../storage/database";
+import { openTrekoonDatabase, type TrekoonDatabase } from "../storage/database";
 
 function formatSubtask(subtask: SubtaskRecord): string {
   return `${subtask.id} | task=${subtask.taskId} | ${subtask.title} | ${subtask.status}`;
@@ -30,6 +35,7 @@ const DEFAULT_SUBTASK_LIST_LIMIT = 10;
 const DEFAULT_OPEN_SUBTASK_STATUSES = ["in_progress", "in-progress", "todo"] as const;
 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;
 
 function parseIdsOption(rawIds: string | undefined): string[] {
   if (rawIds === undefined) {
@@ -171,29 +177,9 @@ function formatSubtaskListTable(subtasks: readonly SubtaskRecord[]): string {
 }
 
 function failFromError(error: unknown): CliResult {
-  if (error instanceof DomainError) {
-    return failResult({
-      command: "subtask",
-      human: error.message,
-      data: {
-        code: error.code,
-        ...(error.details ?? {}),
-      },
-      error: {
-        code: error.code,
-        message: error.message,
-      },
-    });
-  }
-
-  return failResult({
+  return unexpectedFailureResult(error, {
     command: "subtask",
     human: "Unexpected subtask command failure",
-    data: {},
-    error: {
-      code: "internal_error",
-      message: "Unexpected subtask command failure",
-    },
   });
 }
 
@@ -212,10 +198,160 @@ function failMissingOptionValue(command: string, option: string): CliResult {
   });
 }
 
+function failBatchSpec(command: string, human: string, data: Record<string, unknown>): CliResult {
+  return failResult({
+    command,
+    human,
+    data,
+    error: {
+      code: "invalid_input",
+      message: human,
+    },
+  });
+}
+
+function failUnexpectedPositionals(command: string, unexpected: readonly string[]): CliResult {
+  return failBatchSpec(command, `Unexpected positional arguments: ${unexpected.join(", ")}.`, {
+    unexpectedPositionals: unexpected,
+  });
+}
+
+function failConflictingTaskIds(optionTaskId: string, positionalTaskId: string): CliResult {
+  return failBatchSpec("subtask.create-many", "Conflicting task ids for subtask create-many: positional task id must match --task.", {
+    option: "task",
+    optionTaskId,
+    positionalTaskId,
+  });
+}
+
+function failEmptyCompactField(command: string, option: string, index: number, rawSpec: string, field: string): CliResult {
+  return failBatchSpec(command, `${option === "subtask" ? "Subtask" : "Spec"} spec ${index + 1} is missing a ${field}.`, {
+    option,
+    index,
+    rawSpec,
+    field,
+  });
+}
+
+function parseSubtaskCreateManySpecs(parentTaskId: string, rawSpecs: readonly string[]): { specs: CompactSubtaskSpec[]; error?: CliResult } {
+  const specs: CompactSubtaskSpec[] = [];
+  const seenTempKeys = new Set<string>();
+
+  for (const [index, rawSpec] of rawSpecs.entries()) {
+    const parsed = parseCompactFields(rawSpec);
+    if (parsed.invalidEscape !== null) {
+      return {
+        specs: [],
+        error: failBatchSpec("subtask.create-many", `Invalid escape sequence ${parsed.invalidEscape} in --subtask spec ${index + 1}.`, {
+          option: "subtask",
+          index,
+          rawSpec,
+          invalidEscape: parsed.invalidEscape,
+        }),
+      };
+    }
+
+    if (parsed.hasDanglingEscape) {
+      return {
+        specs: [],
+        error: failBatchSpec("subtask.create-many", `Trailing escape in --subtask spec ${index + 1}.`, {
+          option: "subtask",
+          index,
+          rawSpec,
+        }),
+      };
+    }
+
+    if (parsed.fields.length !== 4) {
+      return {
+        specs: [],
+        error: failBatchSpec("subtask.create-many", `Subtask specs must use <temp-key>|<title>|<description>|<status> in --subtask spec ${index + 1}.`, {
+          option: "subtask",
+          index,
+          rawSpec,
+          fields: parsed.fields,
+        }),
+      };
+    }
+
+    const tempKey = parsed.fields[0] ?? "";
+    const title = parsed.fields[1] ?? "";
+    const description = parsed.fields[2] ?? "";
+    const status = parsed.fields[3] ?? "";
+    if (!tempKey || !isValidCompactTempKey(tempKey)) {
+      return {
+        specs: [],
+        error: failBatchSpec("subtask.create-many", `Subtask spec ${index + 1} must start with a temp key like seed-1.`, {
+          option: "subtask",
+          index,
+          rawSpec,
+          tempKey,
+        }),
+      };
+    }
+
+    if (seenTempKeys.has(tempKey)) {
+      return {
+        specs: [],
+        error: failBatchSpec("subtask.create-many", `Duplicate temp key '${tempKey}' in --subtask specs.`, {
+          option: "subtask",
+          index,
+          rawSpec,
+          tempKey,
+        }),
+      };
+    }
+
+    if (!title || title.trim().length === 0) {
+      return {
+        specs: [],
+        error: failBatchSpec("subtask.create-many", `Subtask spec ${index + 1} is missing a title.`, {
+          option: "subtask",
+          index,
+          rawSpec,
+        }),
+      };
+    }
+
+    if (description.trim().length === 0) {
+      return {
+        specs: [],
+        error: failEmptyCompactField("subtask.create-many", "subtask", index, rawSpec, "description"),
+      };
+    }
+
+    seenTempKeys.add(tempKey);
+    const spec: CompactSubtaskSpec = status.length > 0
+      ? {
+          parent: {
+            kind: "id",
+            id: parentTaskId,
+          },
+          tempKey,
+          title,
+          description,
+          status,
+        }
+      : {
+          parent: {
+            kind: "id",
+            id: parentTaskId,
+          },
+          tempKey,
+          title,
+          description,
+        };
+    specs.push(spec);
+  }
+
+  return { specs };
+}
+
 export async function runSubtask(context: CliContext): Promise<CliResult> {
-  const database = openTrekoonDatabase(context.cwd);
+  let database: TrekoonDatabase | undefined;
 
   try {
+    database = openTrekoonDatabase(context.cwd);
     const parsed = parseArgs(context.args);
     const subcommand: string | undefined = parsed.positional[0];
     const domain = new TrackerDomain(database.db);
@@ -248,6 +384,68 @@ export async function runSubtask(context: CliContext): Promise<CliResult> {
           data: { subtask },
         });
       }
+      case "create-many": {
+        const createManyUnknownOption = findUnknownOption(parsed, CREATE_MANY_OPTIONS);
+        if (createManyUnknownOption !== undefined) {
+          return unknownOption("subtask.create-many", createManyUnknownOption, CREATE_MANY_OPTIONS);
+        }
+
+        const missingCreateManyOption = readMissingOptionValue(parsed.missingOptionValues, "task", "t", "subtask");
+        if (missingCreateManyOption !== undefined) {
+          return failMissingOptionValue("subtask.create-many", missingCreateManyOption);
+        }
+
+        const optionTaskId = readOption(parsed.options, "task", "t");
+        const positionalTaskId = parsed.positional[1];
+        const unexpectedPositionals = readUnexpectedPositionals(parsed, positionalTaskId === undefined ? 1 : 2);
+        if (unexpectedPositionals.length > 0) {
+          return failUnexpectedPositionals("subtask.create-many", unexpectedPositionals);
+        }
+
+        if (
+          optionTaskId !== undefined
+          && positionalTaskId !== undefined
+          && optionTaskId.trim().length > 0
+          && positionalTaskId.trim().length > 0
+          && optionTaskId !== positionalTaskId
+        ) {
+          return failConflictingTaskIds(optionTaskId, positionalTaskId);
+        }
+
+        const taskId = optionTaskId ?? positionalTaskId;
+        if (taskId === undefined || taskId.trim().length === 0) {
+          return failBatchSpec("subtask.create-many", "Provide --task (or positional task id) for subtask create-many.", {
+            option: "task",
+          });
+        }
+
+        const rawSpecs = readOptions(parsed.optionEntries, "subtask");
+        if (rawSpecs.length === 0) {
+          return failBatchSpec("subtask.create-many", "Provide at least one --subtask spec.", {
+            option: "subtask",
+          });
+        }
+
+        const specResult = parseSubtaskCreateManySpecs(taskId, rawSpecs);
+        if (specResult.error !== undefined) {
+          return specResult.error;
+        }
+
+        const created = mutations.createSubtaskBatch({
+          taskId,
+          specs: specResult.specs,
+        });
+        const result: CompactBatchResultContract = created.result;
+        return okResult({
+          command: "subtask.create-many",
+          human: `Created ${created.subtasks.length} subtask(s): ${created.subtasks.map(formatSubtask).join("\n")}`,
+          data: {
+            taskId,
+            subtasks: created.subtasks,
+            result,
+          },
+        });
+      }
       case "list": {
         const missingListOption =
           readMissingOptionValue(parsed.missingOptionValues, "view") ??
@@ -669,7 +867,7 @@ export async function runSubtask(context: CliContext): Promise<CliResult> {
       default:
         return failResult({
           command: "subtask",
-          human: "Usage: trekoon subtask <create|list|search|replace|update|delete>",
+          human: "Usage: trekoon subtask <create|create-many|list|search|replace|update|delete>",
           data: {
             args: context.args,
           },
@@ -682,6 +880,6 @@ export async function runSubtask(context: CliContext): Promise<CliResult> {
   } catch (error: unknown) {
     return failFromError(error);
   } finally {
-    database.close();
+    database?.close();
   }
 }

package/src/commands/sync.ts

@@ -1,8 +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";
 
@@ -109,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];
@@ -132,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,
       });
     }
@@ -157,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,
       });
     }
@@ -274,21 +298,44 @@ 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 message = error instanceof Error ? error.message : "Unknown sync error.";
+    const message = safeErrorMessage(error, "Unknown sync error.");
 
     return failResult({
       command: resolvedCommand,

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),
+    },
+  };
+}