trekoon 0.1.8 → 0.2.0

package/src/commands/subtask.ts

@@ -1,16 +1,21 @@
 import {
+  SEARCH_REPLACE_FIELDS,
+  findUnknownOption,
   hasFlag,
   parseArgs,
+  parseCsvEnumOption,
   parseStrictNonNegativeInt,
   parseStrictPositiveInt,
   readEnumOption,
   readMissingOptionValue,
   readOption,
+  resolvePreviewApplyMode,
+  suggestOptions,
 } from "./arg-parser";
 
 import { MutationService } from "../domain/mutation-service";
 import { TrackerDomain } from "../domain/tracker-domain";
-import { DomainError, type SubtaskRecord } from "../domain/types";
+import { DomainError, 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";
@@ -23,6 +28,8 @@ function formatSubtask(subtask: SubtaskRecord): string {
 const VIEW_MODES = ["table", "compact"] as const;
 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;
 
 function parseIdsOption(rawIds: string | undefined): string[] {
   if (rawIds === undefined) {
@@ -35,6 +42,55 @@ function parseIdsOption(rawIds: string | undefined): string[] {
     .filter((value) => value.length > 0);
 }
 
+function prefixedOptions(options: readonly string[]): string[] {
+  return options.map((option) => `--${option}`);
+}
+
+function unknownOption(command: string, option: string, allowedOptions: readonly string[]): CliResult {
+  const suggestions = suggestOptions(option, allowedOptions).map((suggestion) => `--${suggestion}`);
+  const suggestionMessage = suggestions.length > 0 ? ` Did you mean ${suggestions.join(" or ")}?` : "";
+  return failResult({
+    command,
+    human: `Unknown option --${option}.${suggestionMessage}`,
+    data: {
+      option: `--${option}`,
+      allowedOptions: prefixedOptions(allowedOptions),
+      suggestions,
+    },
+    error: {
+      code: "unknown_option",
+      message: `Unknown option --${option}`,
+    },
+  });
+}
+
+function invalidSearchInput(command: string, human: string, message: string, data: Record<string, unknown>): CliResult {
+  return failResult({
+    command,
+    human,
+    data,
+    error: {
+      code: "invalid_input",
+      message,
+    },
+  });
+}
+
+function formatSearchHuman(matches: readonly SearchEntityMatch[], emptyMessage: string): string {
+  if (matches.length === 0) {
+    return emptyMessage;
+  }
+
+  return matches
+    .map(
+      (match) =>
+        `${match.kind} ${match.id}: ${match.fields
+          .map((field) => `${field.field}(${field.count}) "${field.snippet}"`)
+          .join(", ")}`,
+    )
+    .join("\n");
+}
+
 function parseStatusCsv(rawStatuses: string | undefined): string[] | undefined {
   if (rawStatuses === undefined) {
     return undefined;
@@ -323,7 +379,157 @@ export async function runSubtask(context: CliContext): Promise<CliResult> {
           command: "subtask.list",
           human,
           data: { subtasks },
-          ...(context.mode === "human" ? {} : { meta: { pagination: listed.pagination } }),
+          ...(context.mode === "human"
+            ? {}
+            : {
+                meta: {
+                  pagination: listed.pagination,
+                  defaults: {
+                    statuses: !includeAll && statuses === undefined ? [...DEFAULT_OPEN_SUBTASK_STATUSES] : null,
+                    limit: !includeAll && parsedLimit === undefined ? DEFAULT_SUBTASK_LIST_LIMIT : null,
+                    cursor: parsedCursor === undefined ? 0 : null,
+                    view: view === undefined ? "table" : null,
+                  },
+                  filters: {
+                    taskId: taskId ?? null,
+                    statuses: selectedStatuses ?? null,
+                    includeAll,
+                  },
+                  truncation: {
+                    applied: listed.pagination.hasMore,
+                    returned: subtasks.length,
+                    limit: selectedLimit ?? null,
+                  },
+                },
+              }),
+        });
+      }
+      case "search": {
+        const searchUnknownOption = findUnknownOption(parsed, SEARCH_OPTIONS);
+        if (searchUnknownOption !== undefined) {
+          return unknownOption("subtask.search", searchUnknownOption, SEARCH_OPTIONS);
+        }
+
+        const missingSearchOption = readMissingOptionValue(parsed.missingOptionValues, "fields");
+        if (missingSearchOption !== undefined) {
+          return failMissingOptionValue("subtask.search", missingSearchOption);
+        }
+
+        const subtaskId: string = parsed.positional[1] ?? "";
+        const searchText: string = parsed.positional[2] ?? "";
+        if (subtaskId.length === 0 || searchText.trim().length === 0) {
+          return invalidSearchInput(
+            "subtask.search",
+            "Usage: trekoon subtask search <subtask-id> \"search text\" [--fields <csv>] [--preview]",
+            "Missing search target",
+            {
+              subtaskId,
+            },
+          );
+        }
+
+        const parsedFields = parseCsvEnumOption(readOption(parsed.options, "fields"), SEARCH_REPLACE_FIELDS);
+        if (parsedFields.empty || parsedFields.invalidValues.length > 0) {
+          return invalidSearchInput("subtask.search", "Invalid --fields value. Use title, description, or title,description.", "Invalid --fields value", {
+            fields: readOption(parsed.options, "fields"),
+            invalidFields: parsedFields.invalidValues,
+            allowedFields: [...SEARCH_REPLACE_FIELDS],
+          });
+        }
+
+        const { matches, summary } = domain.searchSubtaskScope(subtaskId, searchText, parsedFields.values);
+
+        return okResult({
+          command: "subtask.search",
+          human: formatSearchHuman(matches, "No matches found."),
+          data: {
+            scope: {
+              kind: "subtask",
+              id: subtaskId,
+            },
+            query: {
+              search: searchText,
+              fields: parsedFields.values,
+              mode: "preview",
+            },
+            summary,
+            matches,
+          },
+        });
+      }
+      case "replace": {
+        const replaceUnknownOption = findUnknownOption(parsed, REPLACE_OPTIONS);
+        if (replaceUnknownOption !== undefined) {
+          return unknownOption("subtask.replace", replaceUnknownOption, REPLACE_OPTIONS);
+        }
+
+        const missingReplaceOption =
+          readMissingOptionValue(parsed.missingOptionValues, "search") ??
+          readMissingOptionValue(parsed.missingOptionValues, "replace") ??
+          readMissingOptionValue(parsed.missingOptionValues, "fields");
+        if (missingReplaceOption !== undefined) {
+          return failMissingOptionValue("subtask.replace", missingReplaceOption);
+        }
+
+        const subtaskId: string = parsed.positional[1] ?? "";
+        const searchText = readOption(parsed.options, "search") ?? "";
+        const replacementText = readOption(parsed.options, "replace") ?? "";
+        if (subtaskId.length === 0 || searchText.trim().length === 0) {
+          return invalidSearchInput(
+            "subtask.replace",
+            "Usage: trekoon subtask replace <subtask-id> --search \"text\" --replace \"text\" [--fields <csv>] [--preview|--apply]",
+            "Missing replace target",
+            {
+              subtaskId,
+              search: searchText,
+            },
+          );
+        }
+
+        const rawFields = readOption(parsed.options, "fields");
+        const parsedFields = parseCsvEnumOption(rawFields, SEARCH_REPLACE_FIELDS);
+        if (parsedFields.empty || parsedFields.invalidValues.length > 0) {
+          return invalidSearchInput("subtask.replace", "Invalid --fields value. Use title, description, or title,description.", "Invalid --fields value", {
+            fields: rawFields,
+            invalidFields: parsedFields.invalidValues,
+            allowedFields: [...SEARCH_REPLACE_FIELDS],
+          });
+        }
+
+        const previewMode = resolvePreviewApplyMode(parsed.flags);
+        if (previewMode.conflict) {
+          return invalidSearchInput("subtask.replace", "Use either --preview or --apply, not both.", "Conflicting mode flags", {
+            flags: ["preview", "apply"],
+          });
+        }
+
+        const replacementSummary = previewMode.mode === "apply"
+          ? mutations.applySubtaskReplacement(subtaskId, searchText, replacementText, parsedFields.values)
+          : mutations.previewSubtaskReplacement(subtaskId, searchText, replacementText, parsedFields.values);
+        const { matches, summary: matchSummary } = replacementSummary;
+
+        const summary = {
+          ...matchSummary,
+          mode: previewMode.mode,
+        };
+
+        return okResult({
+          command: "subtask.replace",
+          human: formatSearchHuman(matches, `No ${previewMode.mode === "apply" ? "replacements" : "matches"} found.`),
+          data: {
+            scope: {
+              kind: "subtask",
+              id: subtaskId,
+            },
+            query: {
+              search: searchText,
+              replace: replacementText,
+              fields: parsedFields.values,
+              mode: previewMode.mode,
+            },
+            summary,
+            matches,
+          },
         });
       }
       case "update": {
@@ -463,7 +669,7 @@ export async function runSubtask(context: CliContext): Promise<CliResult> {
       default:
         return failResult({
           command: "subtask",
-          human: "Usage: trekoon subtask <create|list|update|delete>",
+          human: "Usage: trekoon subtask <create|list|search|replace|update|delete>",
           data: {
             args: context.args,
           },

package/src/commands/sync.ts

@@ -1,22 +1,48 @@
+import { findUnknownOption, parseArgs, readMissingOptionValue, readOption, suggestOptions } from "./arg-parser";
+
 import { failResult, okResult } from "../io/output";
 import { type CliContext, type CliResult } from "../runtime/command-types";
 import { MissingBranchDatabaseError } from "../sync/branch-db";
 import { getSyncConflict, listSyncConflicts, syncPull, syncResolve, syncStatus } from "../sync/service";
-import { type SyncConflictMode, type SyncResolution } from "../sync/types";
+import { type SyncResolution } from "../sync/types";
+
+const STATUS_OPTIONS = ["from"] as const;
+const PULL_OPTIONS = ["from"] as const;
+const RESOLVE_OPTIONS = ["use"] as const;
+const CONFLICTS_LIST_OPTIONS = ["mode"] as const;
+const CONFLICTS_SHOW_OPTIONS: readonly string[] = [];
+
+function resolveSyncCommandId(subcommand: string | undefined, conflictsSubcommand: string | undefined): string {
+  if (subcommand === "status") {
+    return "sync.status";
+  }
+
+  if (subcommand === "pull") {
+    return "sync.pull";
+  }
+
+  if (subcommand === "resolve") {
+    return "sync.resolve";
+  }
+
+  if (subcommand !== "conflicts") {
+    return "sync";
+  }
+
+  if (conflictsSubcommand === "list") {
+    return "sync.conflicts.list";
+  }
 
-function parseOption(args: readonly string[], option: string): string | null {
-  const index: number = args.indexOf(option);
-  if (index < 0) {
-    return null;
+  if (conflictsSubcommand === "show") {
+    return "sync.conflicts.show";
   }
 
-  const value: string | undefined = args[index + 1];
-  return value && !value.startsWith("--") ? value : null;
+  return "sync.conflicts";
 }
 
-function usage(message: string): CliResult {
+function usage(message: string, command = "sync"): CliResult {
   return failResult({
-    command: "sync",
+    command,
     human: `${message}\nUsage: trekoon sync <status|pull|resolve|conflicts> [options]`,
     data: { message },
     error: {
@@ -26,6 +52,28 @@ function usage(message: string): CliResult {
   });
 }
 
+function prefixedOptions(options: readonly string[]): string[] {
+  return options.map((option) => `--${option}`);
+}
+
+function unknownOption(command: string, option: string, allowedOptions: readonly string[]): CliResult {
+  const suggestions = suggestOptions(option, allowedOptions).map((suggestion) => `--${suggestion}`);
+  const suggestionMessage = suggestions.length > 0 ? ` Did you mean ${suggestions.join(" or ")}?` : "";
+  return failResult({
+    command,
+    human: `Unknown option --${option}.${suggestionMessage}`,
+    data: {
+      option: `--${option}`,
+      allowedOptions: prefixedOptions(allowedOptions),
+      suggestions,
+    },
+    error: {
+      code: "unknown_option",
+      message: `Unknown option --${option}`,
+    },
+  });
+}
+
 function statusMessage(sourceBranch: string, ahead: number, behind: number, conflicts: number): string {
   return [
     `Sync status against '${sourceBranch}'`,
@@ -61,26 +109,11 @@ function formatConflictList(
     .join("\n");
 }
 
-function parseConflictMode(args: readonly string[]): SyncConflictMode | null {
-  const modeIndex = args.indexOf("--mode");
-  if (modeIndex < 0) {
-    return "pending";
-  }
-
-  const explicitMode = args[modeIndex + 1];
-  if (!explicitMode || explicitMode.startsWith("--")) {
-    return null;
-  }
-
-  if (explicitMode === "pending" || explicitMode === "all") {
-    return explicitMode;
-  }
-
-  return null;
-}
-
 export async function runSync(context: CliContext): Promise<CliResult> {
-  const subcommand: string | undefined = context.args[0];
+  const parsed = parseArgs(context.args);
+  const subcommand: string | undefined = parsed.positional[0];
+  const conflictsSubcommand: string | undefined = subcommand === "conflicts" ? parsed.positional[1] : undefined;
+  const resolvedCommand: string = resolveSyncCommandId(subcommand, conflictsSubcommand);
 
   if (!subcommand) {
     return usage("Missing sync subcommand.");
@@ -88,26 +121,46 @@ export async function runSync(context: CliContext): Promise<CliResult> {
 
   try {
     if (subcommand === "status") {
-      const sourceBranch: string = parseOption(context.args, "--from") ?? "main";
+      const statusUnknownOption = findUnknownOption(parsed, STATUS_OPTIONS);
+      if (statusUnknownOption !== undefined) {
+        return unknownOption("sync.status", statusUnknownOption, STATUS_OPTIONS);
+      }
+
+      const missingFromOption = readMissingOptionValue(parsed.missingOptionValues, "from");
+      if (missingFromOption !== undefined) {
+        return usage("sync status requires --from <branch> when provided.", "sync.status");
+      }
+
+      const sourceBranch: string = readOption(parsed.options, "from") ?? "main";
       const summary = syncStatus(context.cwd, sourceBranch);
 
       return okResult({
-        command: "sync status",
+        command: "sync.status",
         human: statusMessage(summary.sourceBranch, summary.ahead, summary.behind, summary.pendingConflicts),
         data: summary,
       });
     }
 
     if (subcommand === "pull") {
-      const sourceBranch: string | null = parseOption(context.args, "--from");
-      if (!sourceBranch) {
-        return usage("sync pull requires --from <branch>.");
+      const pullUnknownOption = findUnknownOption(parsed, PULL_OPTIONS);
+      if (pullUnknownOption !== undefined) {
+        return unknownOption("sync.pull", pullUnknownOption, PULL_OPTIONS);
+      }
+
+      const missingFromOption = readMissingOptionValue(parsed.missingOptionValues, "from");
+      if (missingFromOption !== undefined) {
+        return usage("sync pull requires --from <branch>.", "sync.pull");
+      }
+
+      const sourceBranch: string | undefined = readOption(parsed.options, "from");
+      if (sourceBranch === undefined) {
+        return usage("sync pull requires --from <branch>.", "sync.pull");
       }
 
       const summary = syncPull(context.cwd, sourceBranch);
 
       return okResult({
-        command: "sync pull",
+        command: "sync.pull",
         human: [
           `Pulled from '${summary.sourceBranch}'`,
           `Scanned events: ${summary.scannedEvents}`,
@@ -123,42 +176,62 @@ export async function runSync(context: CliContext): Promise<CliResult> {
     }
 
     if (subcommand === "resolve") {
-      const conflictId: string | undefined = context.args[1];
-      const rawResolution: string | null = parseOption(context.args, "--use");
+      const resolveUnknownOption = findUnknownOption(parsed, RESOLVE_OPTIONS);
+      if (resolveUnknownOption !== undefined) {
+        return unknownOption("sync.resolve", resolveUnknownOption, RESOLVE_OPTIONS);
+      }
+
+      const conflictId: string | undefined = parsed.positional[1];
+      const missingResolutionOption = readMissingOptionValue(parsed.missingOptionValues, "use");
+      if (missingResolutionOption !== undefined) {
+        return usage("sync resolve requires <conflict-id> --use ours|theirs.", "sync.resolve");
+      }
+
+      const rawResolution: string | undefined = readOption(parsed.options, "use");
 
       if (!conflictId || !rawResolution) {
-        return usage("sync resolve requires <conflict-id> --use ours|theirs.");
+        return usage("sync resolve requires <conflict-id> --use ours|theirs.", "sync.resolve");
       }
 
       if (rawResolution !== "ours" && rawResolution !== "theirs") {
-        return usage("sync resolve --use only accepts ours|theirs.");
+        return usage("sync resolve --use only accepts ours|theirs.", "sync.resolve");
       }
 
       const summary = syncResolve(context.cwd, conflictId, rawResolution as SyncResolution);
 
       return okResult({
-        command: "sync resolve",
+        command: "sync.resolve",
         human: `Resolved ${summary.conflictId} using ${summary.resolution}.`,
         data: summary,
       });
     }
 
     if (subcommand === "conflicts") {
-      const conflictsCommand: string | undefined = context.args[1];
+      const conflictsCommand: string | undefined = parsed.positional[1];
       if (!conflictsCommand) {
-        return usage("sync conflicts requires list|show.");
+          return usage("sync conflicts requires list|show.", "sync.conflicts");
       }
 
       if (conflictsCommand === "list") {
-        const mode = parseConflictMode(context.args);
-        if (!mode) {
-          return usage("sync conflicts list --mode only accepts pending|all.");
+        const listUnknownOption = findUnknownOption(parsed, CONFLICTS_LIST_OPTIONS);
+        if (listUnknownOption !== undefined) {
+          return unknownOption("sync.conflicts.list", listUnknownOption, CONFLICTS_LIST_OPTIONS);
+        }
+
+        const missingModeOption = readMissingOptionValue(parsed.missingOptionValues, "mode");
+        if (missingModeOption !== undefined) {
+            return usage("sync conflicts list --mode only accepts pending|all.", "sync.conflicts.list");
+        }
+
+        const mode = readOption(parsed.options, "mode") ?? "pending";
+        if (mode !== "pending" && mode !== "all") {
+            return usage("sync conflicts list --mode only accepts pending|all.", "sync.conflicts.list");
         }
 
         const conflicts = listSyncConflicts(context.cwd, mode);
 
         return okResult({
-          command: "sync conflicts list",
+          command: "sync.conflicts.list",
           human: formatConflictList(conflicts),
           data: {
             mode,
@@ -168,15 +241,20 @@ export async function runSync(context: CliContext): Promise<CliResult> {
       }
 
       if (conflictsCommand === "show") {
-        const conflictId: string | undefined = context.args[2];
-        if (!conflictId) {
-          return usage("sync conflicts show requires <conflict-id>.");
+        const showUnknownOption = findUnknownOption(parsed, CONFLICTS_SHOW_OPTIONS);
+        if (showUnknownOption !== undefined) {
+          return unknownOption("sync.conflicts.show", showUnknownOption, CONFLICTS_SHOW_OPTIONS);
         }
 
+        const conflictId: string | undefined = parsed.positional[2];
+          if (!conflictId) {
+            return usage("sync conflicts show requires <conflict-id>.", "sync.conflicts.show");
+          }
+
         const conflict = getSyncConflict(context.cwd, conflictId);
 
         return okResult({
-          command: "sync conflicts show",
+          command: "sync.conflicts.show",
           human: [
             `Conflict: ${conflict.id}`,
             `Entity: ${conflict.entityKind} ${conflict.entityId}`,
@@ -191,14 +269,14 @@ export async function runSync(context: CliContext): Promise<CliResult> {
         });
       }
 
-      return usage(`Unknown sync conflicts subcommand '${conflictsCommand}'.`);
+        return usage(`Unknown sync conflicts subcommand '${conflictsCommand}'.`, "sync.conflicts");
     }
 
     return usage(`Unknown sync subcommand '${subcommand}'.`);
   } catch (error) {
     if (error instanceof MissingBranchDatabaseError) {
       return failResult({
-        command: "sync",
+        command: resolvedCommand,
         human: error.message,
         data: {
           reason: "missing_branch_db",
@@ -213,7 +291,7 @@ export async function runSync(context: CliContext): Promise<CliResult> {
     const message = error instanceof Error ? error.message : "Unknown sync error.";
 
     return failResult({
-      command: "sync",
+      command: resolvedCommand,
       human: message,
       data: {
         reason: "sync_failed",