trekoon 0.1.9 → 0.2.1

package/README.md

@@ -48,10 +48,10 @@ 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 dep <add|remove|list|reverse>`
+- `trekoon epic <create|expand|list|show|search|replace|update|delete>`
+- `trekoon task <create|create-many|list|show|ready|next|search|replace|update|delete>`
+- `trekoon subtask <create|create-many|list|search|replace|update|delete>`
+- `trekoon dep <add|add-many|remove|list|reverse>`
 - `trekoon events prune [--dry-run] [--archive] [--retention-days <n>]`
 - `trekoon migrate <status|rollback> [--to-version <n>]`
 - `trekoon sync <status|pull|resolve|conflicts>`
@@ -146,6 +146,42 @@ trekoon task list --limit 25
 trekoon task list --all --view compact
 ```
 
+### 2a) Preferred one-shot epic creation
+
+When you already know the epic tree, create the epic, tasks, subtasks, and
+dependencies in one invocation.
+
+```bash
+trekoon epic create \
+  --title "Batch command rollout" \
+  --description "Ship one-shot planning workflows" \
+  --task "task-a|First task|First description|todo" \
+  --task "task-b|Second task|Second description|todo" \
+  --subtask "@task-a|sub-a|First subtask|Subtask description|todo" \
+  --dep "@task-b|@task-a" \
+  --dep "@sub-a|@task-a"
+```
+
+Use this when:
+
+- the epic does not exist yet
+- later records need to reference earlier created records via `@temp-key`
+- you want one atomic create step and one machine response with mappings/counts
+
+Compact machine output adds:
+
+```text
+command: epic.create
+data:
+  epic: created epic row
+  tasks[]: created tasks in input order
+  subtasks[]: created subtasks in input order
+  dependencies[]: created dependencies in input order
+  result:
+    mappings[]: { kind: task|subtask, tempKey, id }
+    counts: { tasks, subtasks, dependencies }
+```
+
 ### 3) Add dependencies
 
 ```bash
@@ -153,6 +189,181 @@ trekoon dep add <task-id> <depends-on-id>
 trekoon dep list <task-id>
 ```
 
+### 3a) Batch planning commands
+
+Use compact batch commands when one invocation needs to create or link multiple
+items atomically. Use the single-item commands when you already have persisted
+UUIDs and only need one mutation.
+
+#### `task create-many`
+
+Create multiple tasks under one epic in declared order.
+
+```bash
+trekoon task create-many \
+  --epic <epic-id> \
+  --task "seed-api|Design API|Define batch grammar|todo" \
+  --task "seed-cli|Wire CLI|Hook parser and output|in_progress"
+```
+
+Compact spec:
+
+- `--task <temp-key>|<title>|<description>|<status>`
+- escape `\|`, `\\`, `\n`, `\r`, `\t`
+- repeated `--task` flags are preserved in the exact order provided
+- temp keys are local mapping labels, not persisted IDs
+
+Rollback semantics:
+
+- Trekoon validates the full batch before inserts
+- duplicate temp keys, empty required fields, or invalid input fail the whole
+  command
+- no partial task rows are kept on failure
+
+Compact machine output:
+
+```text
+command: task.create-many
+data:
+  epicId: <epic-id>
+  tasks[]: created task rows in input order
+  result:
+    mappings[]: { kind: task, tempKey, id }
+```
+
+#### `subtask create-many`
+
+Create multiple subtasks under one existing task.
+
+```bash
+trekoon subtask create-many <task-id> \
+  --subtask "seed-tests|Write tests|Cover happy path|todo" \
+  --subtask "seed-docs|Document flow|Add operator notes|todo"
+```
+
+Equivalent explicit parent form:
+
+```bash
+trekoon subtask create-many \
+  --task <task-id> \
+  --subtask "seed-tests|Write tests|Cover happy path|todo"
+```
+
+Rules:
+
+- positional `<task-id>` or `--task <task-id>` may be used
+- if both are provided, they must be identical or the command fails
+- repeated `--subtask` flags are applied in declared order
+
+Rollback semantics:
+
+- full batch prevalidation happens before inserts
+- duplicate temp keys, conflicting task ids, or invalid specs abort the whole
+  command
+- no partial subtasks are kept on failure
+
+Compact machine output:
+
+```text
+command: subtask.create-many
+data:
+  taskId: <task-id>
+  subtasks[]: created subtask rows in input order
+  result:
+    mappings[]: { kind: subtask, tempKey, id }
+```
+
+#### `dep add-many`
+
+Create multiple dependency edges in one ordered, transactional operation.
+
+```bash
+trekoon dep add-many \
+  --dep "<task-b>|<task-a>" \
+  --dep "<subtask-c>|<task-b>"
+```
+
+Compact spec:
+
+- `--dep <source-ref>|<depends-on-ref>`
+- repeated `--dep` flags are applied in declared order
+- standalone `dep add-many` resolves persisted IDs only
+- `@temp-key` refs are **not** resolved from earlier commands; they are reserved
+  for same-invocation workflows such as `epic expand`
+
+Rollback semantics:
+
+- validation covers the full dependency set before insert
+- missing ids, unresolved `@temp-key` refs, duplicates, or cycles fail the whole
+  batch
+- no partial dependency edges are inserted on failure
+
+Compact machine output:
+
+```text
+command: dep.add-many
+data:
+  dependencies[]: created dependency rows in input order
+  result:
+    mappings[]: []
+```
+
+#### `epic expand`
+
+Expand one existing epic by creating tasks, subtasks, and dependencies in one
+transaction. Use this when the epic already exists and you want to add a linked
+batch later.
+
+```bash
+trekoon epic expand <epic-id> \
+  --task "task-api|Design API|Define compact grammar|todo" \
+  --task "task-cli|Wire CLI|Hook parser and output|todo" \
+  --subtask "@task-api|sub-tests|Write tests|Cover parser cases|todo" \
+  --dep "@task-cli|@task-api" \
+  --dep "@sub-tests|@task-api"
+```
+
+Compact specs:
+
+- `--task <temp-key>|<title>|<description>|<status>`
+- `--subtask <parent-ref>|<temp-key>|<title>|<description>|<status>`
+- `--dep <source-ref>|<depends-on-ref>`
+- `@temp-key` refs may target tasks/subtasks declared earlier in the same
+  `epic expand` invocation
+
+Background phases:
+
+1. validate all compact specs and duplicate temp keys
+2. create tasks transactionally
+3. resolve subtask parent temp keys and create subtasks
+4. resolve dependency refs and link dependencies
+5. append task, subtask, then dependency events
+6. roll back the full expansion if any phase fails
+
+Compact machine output:
+
+```text
+command: epic.expand
+data:
+  epicId: <epic-id>
+  tasks[]: created tasks in input order
+  subtasks[]: created subtasks in input order
+  dependencies[]: created dependencies in input order
+  result:
+    mappings[]: { kind: task|subtask, tempKey, id }
+    counts: { tasks, subtasks, dependencies }
+```
+
+When to choose which command:
+
+- use `task create-many` for sibling tasks under one known epic
+- use `subtask create-many` for sibling subtasks under one known task
+- use `dep add-many` only when every endpoint already has a persisted ID
+- use `epic create` with batch specs when the epic does not exist yet and the
+  whole graph is known up front
+- use `epic expand` when the epic already exists and one batch must add linked
+  tasks/subtasks/dependencies with `@temp-key` references
+
 ### 4) AI execution loop for agents
 
 Run this loop each session to pick next work deterministically:
@@ -186,7 +397,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 +522,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 +584,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.1",
   "description": "AI-first local issue tracker CLI.",
   "license": "MIT",
   "type": "module",

package/src/commands/arg-parser.ts

@@ -1,16 +1,52 @@
+import {
+  COMPACT_TEMP_KEY_PREFIX,
+  type CompactEntityRef,
+  type CompactEntityIdRef,
+  type CompactTempKey,
+  type CompactTempKeyRef,
+} from "../domain/types";
+
 export interface ParsedArgs {
   readonly positional: readonly string[];
   readonly options: ReadonlyMap<string, string>;
+  readonly optionEntries: readonly ParsedOptionEntry[];
   readonly flags: ReadonlySet<string>;
   readonly missingOptionValues: ReadonlySet<string>;
   readonly providedOptions: readonly string[];
 }
 
+export interface ParsedOptionEntry {
+  readonly key: string;
+  readonly value: 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;
+}
+
+export interface ParsedCompactFields {
+  readonly fields: readonly string[];
+  readonly invalidEscape: string | null;
+  readonly hasDanglingEscape: boolean;
+}
+
 const LONG_PREFIX = "--";
 
 export function parseArgs(args: readonly string[]): ParsedArgs {
   const positional: string[] = [];
   const options = new Map<string, string>();
+  const optionEntries: ParsedOptionEntry[] = [];
   const flags = new Set<string>();
   const missingOptionValues = new Set<string>();
   const providedOptions: string[] = [];
@@ -36,12 +72,14 @@ export function parseArgs(args: readonly string[]): ParsedArgs {
     }
 
     options.set(key, value);
+    optionEntries.push({ key, value });
     index += 1;
   }
 
   return {
     positional,
     options,
+    optionEntries,
     flags,
     missingOptionValues,
     providedOptions,
@@ -63,6 +101,11 @@ export function hasFlag(flags: ReadonlySet<string>, ...keys: string[]): boolean
   return keys.some((key) => flags.has(key));
 }
 
+export function readOptions(optionEntries: readonly ParsedOptionEntry[], ...keys: string[]): string[] {
+  const allowedKeys = new Set<string>(keys);
+  return optionEntries.filter((entry) => allowedKeys.has(entry.key)).map((entry) => entry.value);
+}
+
 export function readMissingOptionValue(
   missingOptionValues: ReadonlySet<string>,
   ...keys: string[]
@@ -96,6 +139,157 @@ 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,
+  };
+}
+
+export function isValidCompactTempKey(value: string): value is CompactTempKey {
+  return /^[A-Za-z][A-Za-z0-9._-]{0,63}$/u.test(value);
+}
+
+export function parseCompactFields(rawValue: string): ParsedCompactFields {
+  const fields: string[] = [];
+  let current = "";
+  let escaping = false;
+
+  for (const character of rawValue) {
+    if (escaping) {
+      switch (character) {
+        case "|":
+          current += "|";
+          break;
+        case "\\":
+          current += "\\";
+          break;
+        case "n":
+          current += "\n";
+          break;
+        case "r":
+          current += "\r";
+          break;
+        case "t":
+          current += "\t";
+          break;
+        default:
+          return {
+            fields,
+            invalidEscape: `\\${character}`,
+            hasDanglingEscape: false,
+          };
+      }
+
+      escaping = false;
+      continue;
+    }
+
+    if (character === "\\") {
+      escaping = true;
+      continue;
+    }
+
+    if (character === "|") {
+      fields.push(current);
+      current = "";
+      continue;
+    }
+
+    current += character;
+  }
+
+  if (escaping) {
+    return {
+      fields,
+      invalidEscape: null,
+      hasDanglingEscape: true,
+    };
+  }
+
+  fields.push(current);
+  return {
+    fields,
+    invalidEscape: null,
+    hasDanglingEscape: false,
+  };
+}
+
+export function parseCompactEntityRef(rawValue: string): CompactEntityRef {
+  if (rawValue.startsWith(COMPACT_TEMP_KEY_PREFIX)) {
+    const tempKey = rawValue.slice(COMPACT_TEMP_KEY_PREFIX.length);
+    return {
+      kind: "temp_key",
+      tempKey,
+    } satisfies CompactTempKeyRef;
+  }
+
+  return {
+    kind: "id",
+    id: rawValue,
+  } satisfies CompactEntityIdRef;
+}
+
 function levenshteinDistance(source: string, target: string): number {
   const sourceLength = source.length;
   const targetLength = target.length;
@@ -186,3 +380,7 @@ export function readEnumOption<const T extends readonly string[]>(
 
   return allowed.includes(value) ? value : undefined;
 }
+
+export function readUnexpectedPositionals(parsed: ParsedArgs, expectedCount: number): readonly string[] {
+  return parsed.positional.slice(expectedCount);
+}