trekoon 0.1.8 → 0.2.0

package/src/commands/epic.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 EpicRecord } from "../domain/types";
+import { DomainError, type EpicRecord, type SearchEntityMatch } from "../domain/types";
 import { formatHumanTable } from "../io/human-table";
 import { failResult, okResult } from "../io/output";
 import { type CliContext, type CliResult } from "../runtime/command-types";
@@ -24,6 +29,8 @@ const VIEW_MODES = ["table", "compact", "tree", "detail"] as const;
 const LIST_VIEW_MODES = ["table", "compact"] as const;
 const DEFAULT_LIST_LIMIT = 10;
 const DEFAULT_OPEN_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 parseStatusCsv(rawStatuses: string | undefined): string[] | undefined {
   if (rawStatuses === undefined) {
@@ -36,6 +43,55 @@ function parseStatusCsv(rawStatuses: string | undefined): string[] | undefined {
     .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 getStatusPriority(status: string): number {
   if (status === "in_progress" || status === "in-progress") {
     return 0;
@@ -396,7 +452,28 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
           command: "epic.list",
           human,
           data: { epics },
-          ...(context.mode === "human" ? {} : { meta: { pagination: listed.pagination } }),
+          ...(context.mode === "human"
+            ? {}
+            : {
+                meta: {
+                  pagination: listed.pagination,
+                  defaults: {
+                    statuses: !includeAll && statuses === undefined ? [...DEFAULT_OPEN_STATUSES] : null,
+                    limit: !includeAll && limit === undefined ? DEFAULT_LIST_LIMIT : null,
+                    cursor: rawCursor === undefined ? 0 : null,
+                    view: view === undefined ? "table" : null,
+                  },
+                  filters: {
+                    statuses: includeAll ? null : (statuses ?? [...DEFAULT_OPEN_STATUSES]),
+                    includeAll,
+                  },
+                  truncation: {
+                    applied: listed.pagination.hasMore,
+                    returned: epics.length,
+                    limit: includeAll ? null : (limit ?? DEFAULT_LIST_LIMIT),
+                  },
+                },
+              }),
         });
       }
       case "show": {
@@ -430,6 +507,22 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
             command: "epic.show",
             human: formatEpic(epic),
             data: { epic, includeAll: false },
+            ...(context.mode === "human"
+              ? {}
+              : {
+                  meta: {
+                    defaults: {
+                      view: view === undefined ? effectiveView : null,
+                    },
+                    filters: {
+                      includeAll: false,
+                    },
+                    truncation: {
+                      applied: true,
+                      scope: "compact",
+                    },
+                  },
+                }),
           });
         }
 
@@ -440,6 +533,22 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
             command: "epic.show",
             human: formatEpicShowCompact(tree),
             data: { tree, includeAll: false },
+            ...(context.mode === "human"
+              ? {}
+              : {
+                  meta: {
+                    defaults: {
+                      view: view === undefined ? effectiveView : null,
+                    },
+                    filters: {
+                      includeAll: false,
+                    },
+                    truncation: {
+                      applied: true,
+                      scope: "tree",
+                    },
+                  },
+                }),
           });
         }
 
@@ -449,6 +558,150 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
           command: "epic.show",
           human: effectiveView === "table" ? formatEpicShowTable(tree) : formatEpicShowDetailed(tree),
           data: { tree, includeAll: true },
+          ...(context.mode === "human"
+            ? {}
+            : {
+                meta: {
+                  defaults: {
+                    view: view === undefined ? effectiveView : null,
+                  },
+                  filters: {
+                    includeAll: true,
+                  },
+                  truncation: {
+                    applied: false,
+                    scope: "full",
+                  },
+                },
+              }),
+        });
+      }
+      case "search": {
+        const searchUnknownOption = findUnknownOption(parsed, SEARCH_OPTIONS);
+        if (searchUnknownOption !== undefined) {
+          return unknownOption("epic.search", searchUnknownOption, SEARCH_OPTIONS);
+        }
+
+        const missingSearchOption = readMissingOptionValue(parsed.missingOptionValues, "fields");
+        if (missingSearchOption !== undefined) {
+          return failMissingOptionValue("epic.search", missingSearchOption);
+        }
+
+        const epicId: string = parsed.positional[1] ?? "";
+        const searchText: string = parsed.positional[2] ?? "";
+        if (epicId.length === 0 || searchText.trim().length === 0) {
+          return invalidSearchInput(
+            "epic.search",
+            "Usage: trekoon epic search <epic-id> \"search text\" [--fields <csv>] [--preview]",
+            "Missing search target",
+            {
+              epicId,
+            },
+          );
+        }
+
+        const parsedFields = parseCsvEnumOption(readOption(parsed.options, "fields"), SEARCH_REPLACE_FIELDS);
+        if (parsedFields.empty || parsedFields.invalidValues.length > 0) {
+          return invalidSearchInput("epic.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.searchEpicScope(epicId, searchText, parsedFields.values);
+
+        return okResult({
+          command: "epic.search",
+          human: formatSearchHuman(matches, "No matches found."),
+          data: {
+            scope: {
+              kind: "epic",
+              id: epicId,
+            },
+            query: {
+              search: searchText,
+              fields: parsedFields.values,
+              mode: "preview",
+            },
+            summary,
+            matches,
+          },
+        });
+      }
+      case "replace": {
+        const replaceUnknownOption = findUnknownOption(parsed, REPLACE_OPTIONS);
+        if (replaceUnknownOption !== undefined) {
+          return unknownOption("epic.replace", replaceUnknownOption, REPLACE_OPTIONS);
+        }
+
+        const missingReplaceOption =
+          readMissingOptionValue(parsed.missingOptionValues, "search") ??
+          readMissingOptionValue(parsed.missingOptionValues, "replace") ??
+          readMissingOptionValue(parsed.missingOptionValues, "fields");
+        if (missingReplaceOption !== undefined) {
+          return failMissingOptionValue("epic.replace", missingReplaceOption);
+        }
+
+        const epicId: string = parsed.positional[1] ?? "";
+        const searchText = readOption(parsed.options, "search") ?? "";
+        const replacementText = readOption(parsed.options, "replace") ?? "";
+        if (epicId.length === 0 || searchText.trim().length === 0) {
+          return invalidSearchInput(
+            "epic.replace",
+            "Usage: trekoon epic replace <epic-id> --search \"text\" --replace \"text\" [--fields <csv>] [--preview|--apply]",
+            "Missing replace target",
+            {
+              epicId,
+              search: searchText,
+            },
+          );
+        }
+
+        const rawFields = readOption(parsed.options, "fields");
+        const parsedFields = parseCsvEnumOption(rawFields, SEARCH_REPLACE_FIELDS);
+        if (parsedFields.empty || parsedFields.invalidValues.length > 0) {
+          return invalidSearchInput("epic.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("epic.replace", "Use either --preview or --apply, not both.", "Conflicting mode flags", {
+            flags: ["preview", "apply"],
+          });
+        }
+
+        const replacementSummary = previewMode.mode === "apply"
+          ? mutations.applyEpicReplacement(epicId, searchText, replacementText, parsedFields.values)
+          : mutations.previewEpicReplacement(epicId, searchText, replacementText, parsedFields.values);
+        const { matches, summary: matchSummary } = replacementSummary;
+
+        const summary = {
+          ...matchSummary,
+          mode: previewMode.mode,
+        };
+
+        return okResult({
+          command: "epic.replace",
+          human: formatSearchHuman(matches, `No ${previewMode.mode === "apply" ? "replacements" : "matches"} found.`),
+          data: {
+            scope: {
+              kind: "epic",
+              id: epicId,
+            },
+            query: {
+              search: searchText,
+              replace: replacementText,
+              fields: parsedFields.values,
+              mode: previewMode.mode,
+            },
+            summary,
+            matches,
+          },
         });
       }
       case "update": {
@@ -588,7 +841,7 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
       default:
         return failResult({
           command: "epic",
-          human: "Usage: trekoon epic <create|list|show|update|delete>",
+          human: "Usage: trekoon epic <create|list|show|search|replace|update|delete>",
           data: {
             args: context.args,
           },

package/src/commands/help.ts

@@ -12,10 +12,12 @@ const ROOT_HELP = [
   "Global options:",
   "  --json       Emit stable JSON machine output",
   "  --toon       Emit true TOON-encoded output",
+  "  --compat <mode>  Enable explicit machine compatibility mode",
   "  --help       Show root or command help",
   "  --version    Print CLI version",
   "",
   "Commands:",
+  "  help         Show root or command help",
   "  init         Initialize .trekoon storage and local DB",
   "  quickstart   Show AI execution loop + task detail workflow",
   "  wipe         Remove local Trekoon state (requires --yes)",
@@ -72,7 +74,7 @@ const WIPE_HELP = [
 ].join("\n");
 
 const EPIC_HELP = [
-  "Usage: trekoon epic <create|list|show|update|delete> [options]",
+  "Usage: trekoon epic <create|list|show|search|replace|update|delete> [options]",
   "",
   "List behavior:",
   "  Defaults:",
@@ -88,12 +90,23 @@ const EPIC_HELP = [
   "",
   "Show behavior:",
   "  Views:",
+  "    - table: default view",
   "    - compact: epic summary",
   "    - tree: hierarchy",
   "    - detail: descriptions",
   "  Machine default:",
   "    - With --all, machine modes default to detail",
   "",
+  "Search/Replace behavior:",
+  "  search:",
+  "    - trekoon epic search <epic-id> \"search text\"",
+  "    - Options: --fields title|description|title,description, --preview",
+  "    - Scope: epic title/description + descendant task/subtask title/description",
+  "  replace:",
+  "    - trekoon epic replace <epic-id> --search \"text\" --replace \"text\"",
+  "    - Preview is default; use --apply to mutate",
+  "    - --preview and --apply are mutually exclusive",
+  "",
   "Update behavior:",
   "  Bulk target flags:",
   "    --all | --ids <csv>",
@@ -102,14 +115,14 @@ const EPIC_HELP = [
 ].join("\n");
 
 const TASK_HELP = [
-  "Usage: trekoon task <create|list|show|ready|next|update|delete> [options]",
+  "Usage: trekoon task <create|list|show|ready|next|search|replace|update|delete> [options]",
   "",
   "List behavior:",
   "  Defaults:",
   "    - Open statuses only: in_progress, in-progress, todo",
   "    - Limit: 10",
   "  Flags:",
-  "    --status <csv> | --limit <n> | --cursor <n> | --all | --view table|compact",
+  "    --epic <id> | --status <csv> | --limit <n> | --cursor <n> | --all | --view table|compact",
   "  Pagination:",
   "    - --cursor is offset-like",
   "    - Machine modes expose meta.pagination.hasMore / nextCursor",
@@ -118,6 +131,7 @@ const TASK_HELP = [
   "",
   "Show behavior:",
   "  Views:",
+  "    - table: default view",
   "    - compact: task summary",
   "    - tree: hierarchy",
   "    - detail: descriptions",
@@ -133,6 +147,16 @@ const TASK_HELP = [
   "    - Returns top ready candidate",
   "    - Option: --epic <id>",
   "",
+  "Search/Replace behavior:",
+  "  search:",
+  "    - trekoon task search <task-id> \"search text\"",
+  "    - Options: --fields title|description|title,description, --preview",
+  "    - Scope: task title/description + descendant subtask title/description",
+  "  replace:",
+  "    - trekoon task replace <task-id> --search \"text\" --replace \"text\"",
+  "    - Preview is default; use --apply to mutate",
+  "    - --preview and --apply are mutually exclusive",
+  "",
   "Update behavior:",
   "  Bulk target flags:",
   "    --all | --ids <csv>",
@@ -141,7 +165,7 @@ const TASK_HELP = [
 ].join("\n");
 
 const SUBTASK_HELP = [
-  "Usage: trekoon subtask <create|list|update|delete> [options]",
+  "Usage: trekoon subtask <create|list|search|replace|update|delete> [options]",
   "",
   "List behavior:",
   "  Defaults:",
@@ -155,6 +179,16 @@ const SUBTASK_HELP = [
   "  Constraints:",
   "    - --all is mutually exclusive with --status, --limit, and --cursor",
   "",
+  "Search/Replace behavior:",
+  "  search:",
+  "    - trekoon subtask search <subtask-id> \"search text\"",
+  "    - Options: --fields title|description|title,description, --preview",
+  "    - Scope: subtask title/description only",
+  "  replace:",
+  "    - trekoon subtask replace <subtask-id> --search \"text\" --replace \"text\"",
+  "    - Preview is default; use --apply to mutate",
+  "    - --preview and --apply are mutually exclusive",
+  "",
   "Update behavior:",
   "  Bulk target flags:",
   "    --all | --ids <csv>",
@@ -229,6 +263,13 @@ const SYNC_HELP = [
   "  resolve <conflict-id> --use ours|theirs",
   "      Resolve a pending conflict by selecting ours or theirs.",
   "",
+  "Compatibility mode:",
+  "  --compat legacy-sync-command-ids",
+  "      Emits legacy sync command IDs (sync_status, sync_pull, ...)",
+  "      in machine output only and includes deprecation metadata.",
+  "      Migration: remove --compat and consume dotted IDs (sync.status).",
+  "      Planned compatibility window closes after 2026-09-30.",
+  "",
   "Examples:",
   "  trekoon sync status",
   "  trekoon sync status --from main",