trekoon 0.1.9 → 0.2.0

package/.agents/skills/trekoon/SKILL.md

@@ -295,7 +295,80 @@ Rules:
 - In bulk mode, do not pass a positional ID.
 - Bulk update supports `--append` and/or `--status`.
 
-## 7) Setup/install/init (if `trekoon` is unavailable)
+## 7) Scoped search/replace recipes for agents
+
+Use scoped search/replace instead of repeated `show` scans when you need to
+locate or migrate repeated text inside one issue tree.
+
+```bash
+trekoon epic search <epic-id> "path/to/somewhere" --toon
+trekoon task search <task-id> "path/to/somewhere" --toon
+trekoon subtask search <subtask-id> "path/to/somewhere" --toon
+
+trekoon epic replace <epic-id> --search "path/to/somewhere" --replace "path/to/new-path" --toon
+trekoon epic replace <epic-id> --search "path/to/somewhere" --replace "path/to/new-path" --apply --toon
+```
+
+Guardrails:
+
+- Use `search` first when you only need to confirm whether the text exists.
+- Use preview `replace` next to confirm the exact candidate set.
+- Use `--apply` only after preview matches the intended scope.
+- Prefer the narrowest root that satisfies the task: `subtask` → `task` →
+  `epic`.
+- Keep prompts deterministic: literal search text, explicit IDs, no regex
+  assumptions.
+
+Agent contract for epic-scoped replace:
+
+- Exact search command:
+  `trekoon epic search <epic-id> "path/to/somewhere" --toon`
+- Exact replace command:
+  `trekoon epic replace <epic-id> --search "path/to/somewhere" --replace "path/to/new-path" --toon`
+- Apply command:
+  `trekoon epic replace <epic-id> --search "path/to/somewhere" --replace "path/to/new-path" --apply --toon`
+- Epic scope includes the epic title/description plus every task and subtask
+  title/description in that epic tree.
+
+Compact TOON fields to expect:
+
+```text
+ok: true
+command: epic.search
+data:
+  scope: epic
+  query: { search, fields[], mode: preview }
+  matches[]: { kind, id, fields[]: { field, count, snippet } }
+  summary: { matchedEntities, matchedFields, totalMatches }
+metadata:
+  contractVersion: 1.0.0
+  requestId: req-<id>
+```
+
+```text
+ok: true
+command: epic.replace
+data:
+  scope: epic
+  query: { search, replace, fields[], mode: preview|apply }
+  matches[]: { kind, id, fields[]: { field, count, snippet } }
+  summary: { matchedEntities, matchedFields, totalMatches, mode }
+metadata:
+  contractVersion: 1.0.0
+  requestId: req-<id>
+```
+
+Background behavior to assume:
+
+- Scope traversal is deterministic: epic first, then descendant tasks, then
+  descendant subtasks.
+- Field traversal is deterministic: `title` before `description`.
+- Preview reads and summarizes candidates without mutation.
+- `--apply` reuses the same scoped traversal, mutates only rows with real text
+  changes, and returns matched rows with `query.mode` and `summary.mode` set
+  to `"apply"`.
+
+## 8) Setup/install/init (if `trekoon` is unavailable)
 
 1. Install Trekoon (or make sure it is on `PATH`).
 2. In the target repository/worktree, initialize tracker state:
@@ -309,7 +382,7 @@ trekoon init --toon
 
 If `.trekoon/trekoon.db` is missing, initialize before any create/update commands.
 
-## 8) Safety
+## 9) Safety
 
 - Never edit `.trekoon/trekoon.db` directly.
 - `trekoon wipe --yes --toon` is prohibited unless the user explicitly confirms they want a destructive wipe.

package/README.md

@@ -48,9 +48,9 @@ npm i -g trekoon
 - `trekoon init`
 - `trekoon help [command]`
 - `trekoon quickstart`
-- `trekoon epic <create|list|show|update|delete>`
-- `trekoon task <create|list|show|ready|next|update|delete>`
-- `trekoon subtask <create|list|update|delete>`
+- `trekoon epic <create|list|show|search|replace|update|delete>`
+- `trekoon task <create|list|show|ready|next|search|replace|update|delete>`
+- `trekoon subtask <create|list|search|replace|update|delete>`
 - `trekoon dep <add|remove|list|reverse>`
 - `trekoon events prune [--dry-run] [--archive] [--retention-days <n>]`
 - `trekoon migrate <status|rollback> [--to-version <n>]`
@@ -186,7 +186,88 @@ trekoon --json epic show <epic-id>
 trekoon --json task show <task-id>
 ```
 
-### 6) Sync workflow for worktrees
+### 6) Scoped search for repeated text
+
+Use scoped search before manual tree reads when you need to locate repeated
+paths, labels, or migration targets.
+
+```bash
+trekoon --toon epic search <epic-id> "path/to/somewhere"
+trekoon --toon task search <task-id> "path/to/somewhere"
+trekoon --toon subtask search <subtask-id> "path/to/somewhere"
+```
+
+Scope rules:
+
+- `epic search` scans the epic title/description plus every task and subtask
+  title/description in that epic tree.
+- `task search` scans the task title/description plus descendant subtask
+  title/description.
+- `subtask search` scans only that subtask's title/description.
+- Add `--fields title`, `--fields description`, or
+  `--fields title,description` when you need a narrower scan.
+
+### 7) Preview first, then apply scoped replace
+
+Use search first to confirm the scope, then run replace in preview mode, and
+only use `--apply` after the preview matches the intended migration.
+
+```bash
+trekoon --toon epic search <epic-id> "path/to/somewhere"
+trekoon --toon epic replace <epic-id> --search "path/to/somewhere" --replace "path/to/new-path"
+trekoon --toon epic replace <epic-id> --search "path/to/somewhere" --replace "path/to/new-path" --apply
+```
+
+Use this loop for low-risk agent workflows:
+
+1. `search` when you need the smallest possible read before deciding whether a
+   migration is needed.
+2. preview `replace` to verify the exact candidate set and changed fields.
+3. `replace --apply` only after the preview output matches the intended scope.
+
+Epic-scoped replace applies across the epic title/description and every task and
+subtask title/description in that epic tree.
+
+Compact TOON expectations for agents:
+
+```text
+ok: true
+command: epic.search
+data:
+  scope: epic
+  query: { search, fields[], mode: preview }
+  matches[]: { kind, id, fields[]: { field, count, snippet } }
+  summary: { matchedEntities, matchedFields, totalMatches }
+metadata:
+  contractVersion: 1.0.0
+  requestId: req-<id>
+```
+
+```text
+ok: true
+command: epic.replace
+data:
+  scope: epic
+  query: { search, replace, fields[], mode: preview|apply }
+  matches[]: { kind, id, fields[]: { field, count, snippet } }
+  summary: { matchedEntities, matchedFields, totalMatches, mode }
+metadata:
+  contractVersion: 1.0.0
+  requestId: req-<id>
+```
+
+Background behavior:
+
+- `epic search` and preview `epic replace` traverse the epic first, then
+  descendant tasks, then descendant subtasks.
+- Within each record, Trekoon checks `title` before `description` so output stays
+  deterministic and low-token.
+- Preview reports the candidate set without mutating records.
+- `--apply` reuses the same scoped traversal, updates only rows with real text
+  changes, and returns the matched rows with `query.mode` and `summary.mode`
+  set to `"apply"`.
+
+### 8) Sync workflow for worktrees
 
 - Run `trekoon sync status` at session start and before PR/merge.
 - Run `trekoon sync pull --from main` before merge to align tracker state.
@@ -230,7 +311,7 @@ Behavior:
 - Migration path: remove `--compat legacy-sync-command-ids` and consume dotted
   command IDs directly.
 
-### 7) Install project-local Trekoon skill for agents
+### 9) Install project-local Trekoon skill for agents
 
 `trekoon skills install` always writes the bundled skill file under the current
 working directory at:
@@ -292,7 +373,7 @@ This produces:
 
 Trekoon does not mutate global editor config directories.
 
-### 8) Pre-merge checklist
+### 10) Pre-merge checklist
 
 - [ ] `trekoon sync status` shows no unresolved conflicts
 - [ ] done tasks/subtasks are marked completed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trekoon",
-  "version": "0.1.9",
+  "version": "0.2.0",
   "description": "AI-first local issue tracker CLI.",
   "license": "MIT",
   "type": "module",

package/src/commands/arg-parser.ts

@@ -6,6 +6,21 @@ export interface ParsedArgs {
   readonly providedOptions: readonly string[];
 }
 
+export const SEARCH_REPLACE_FIELDS = ["title", "description"] as const;
+
+export type SearchReplaceField = (typeof SEARCH_REPLACE_FIELDS)[number];
+
+export interface ParsedCsvEnumOption<T extends string> {
+  readonly values: readonly T[];
+  readonly invalidValues: readonly string[];
+  readonly empty: boolean;
+}
+
+export interface PreviewApplyModeSelection {
+  readonly mode: "preview" | "apply";
+  readonly conflict: boolean;
+}
+
 const LONG_PREFIX = "--";
 
 export function parseArgs(args: readonly string[]): ParsedArgs {
@@ -96,6 +111,73 @@ export function parseStrictNonNegativeInt(rawValue: string | undefined): number
   return parsed;
 }
 
+export function parseCsvOption(rawValue: string | undefined): string[] | undefined {
+  if (rawValue === undefined) {
+    return undefined;
+  }
+
+  return rawValue
+    .split(",")
+    .map((value) => value.trim())
+    .filter((value) => value.length > 0);
+}
+
+export function parseCsvEnumOption<const T extends readonly string[]>(
+  rawValue: string | undefined,
+  allowed: T,
+): ParsedCsvEnumOption<T[number]> {
+  const values = parseCsvOption(rawValue);
+  if (values === undefined) {
+    return {
+      values: [...allowed],
+      invalidValues: [],
+      empty: false,
+    };
+  }
+
+  if (values.length === 0) {
+    return {
+      values: [...allowed],
+      invalidValues: [],
+      empty: true,
+    };
+  }
+
+  const allowedValues = new Set<string>(allowed);
+  const validValues: T[number][] = [];
+  const invalidValues: string[] = [];
+
+  for (const value of values) {
+    if (!allowedValues.has(value)) {
+      invalidValues.push(value);
+      continue;
+    }
+
+    if (!validValues.includes(value as T[number])) {
+      validValues.push(value as T[number]);
+    }
+  }
+
+  return {
+    values: validValues.length > 0 ? validValues : [...allowed],
+    invalidValues,
+    empty: false,
+  };
+}
+
+export function resolvePreviewApplyMode(
+  flags: ReadonlySet<string>,
+  previewKey = "preview",
+  applyKey = "apply",
+): PreviewApplyModeSelection {
+  const preview = flags.has(previewKey);
+  const apply = flags.has(applyKey);
+  return {
+    mode: apply ? "apply" : "preview",
+    conflict: preview && apply,
+  };
+}
+
 function levenshteinDistance(source: string, target: string): number {
   const sourceLength = source.length;
   const targetLength = target.length;

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;
@@ -520,6 +576,134 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
               }),
         });
       }
+      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": {
         const missingUpdateOption =
           readMissingOptionValue(parsed.missingOptionValues, "ids") ??
@@ -657,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

@@ -74,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:",
@@ -97,6 +97,16 @@ const EPIC_HELP = [
   "  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>",
@@ -105,7 +115,7 @@ 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:",
@@ -137,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>",
@@ -145,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:",
@@ -159,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>",