trekoon 0.2.0 → 0.2.4

package/README.md

@@ -40,7 +40,7 @@ npm i -g trekoon
 
 1. Make issue tracking fast enough for daily terminal use.
 2. Make issue data deterministic and machine-readable for AI automation.
-3. Keep branch/worktree-aware state so parallel execution can be coordinated safely.
+3. Keep one repo-scoped state store that every worktree can coordinate through safely.
 4. Stay minimal in code size while preserving robustness and clear boundaries.
 
 ## Command surface
@@ -48,10 +48,11 @@ npm i -g trekoon
 - `trekoon init`
 - `trekoon help [command]`
 - `trekoon quickstart`
-- `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 epic <create|expand|list|show|search|replace|update|delete>`
+- `trekoon session`
+- `trekoon task <create|create-many|list|show|ready|next|done|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>`
@@ -117,15 +118,23 @@ trekoon epic update --ids <epic-1>,<epic-2> --status done
 
 ## Quickstart
 
-Trekoon is local-first: in git repos/worktrees, Trekoon resolves state to one
-canonical repository root (`git rev-parse --show-toplevel`) so nested
-invocations share the same `.trekoon/trekoon.db`.
+Trekoon is local-first, but in git repos and worktrees it is **repo-shared**:
+every worktree for the same repository resolves to one shared `.trekoon`
+directory and one shared `.trekoon/trekoon.db`.
+
+- `worktreeRoot` identifies the current checkout.
+- `sharedStorageRoot` identifies the repository root that owns `.trekoon`.
+- `databaseFile` points at the shared SQLite database.
+- `.trekoon` stays gitignored on purpose because the DB is operational state,
+  not source code.
+- Committing `.trekoon/trekoon.db` is the wrong fix for drift because it bakes
+  machine-local state and stale snapshots into Git.
 
 Outside git repos, Trekoon falls back to the invocation cwd.
 
 When machine output is enabled (`--json`/`--toon`) and a command resolves
 storage from a non-canonical cwd, Trekoon emits
-`meta.storageRootDiagnostics` to make the divergence explicit for automation.
+`meta.storageRootDiagnostics` so automation can verify the storage contract.
 
 ### 1) Initialize
 
@@ -134,6 +143,15 @@ trekoon init
 trekoon --version
 ```
 
+Bootstrap expectations:
+
+- Run `trekoon --toon init` once per repository to create or re-bootstrap the
+  shared storage root.
+- Run `trekoon --toon sync status` before agent work to inspect diagnostics.
+- If diagnostics report `recoveryRequired`, a tracked/ignored mismatch, or an
+  ambiguous recovery path, stop and repair setup before continuing.
+- Do **not** continue with task selection after broken bootstrap warnings.
+
 ### 2) Create epic → task → subtask
 
 ```bash
@@ -146,6 +164,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,25 +207,229 @@ 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:
+The primary loop is: **session → work → task done → repeat**.
+
+Orient with a single call that returns diagnostics, sync status, next ready
+task with subtasks, blocker list, and readiness counts:
+
+```bash
+trekoon --toon session
+```
+
+Claim work, then finish or report a block:
 
 ```bash
-trekoon --toon sync status
-trekoon --toon task ready --limit 5
-trekoon --toon task next
-trekoon --toon dep reverse <task-or-subtask-id>
 trekoon --toon task update <task-id> --status in_progress
+trekoon --toon task done <task-id>
+trekoon --toon task update <task-id> --append "Blocked by <reason>" --status blocked
 ```
 
-When done or blocked, append context and update final status:
+`task done` marks the task done and returns the next ready task with
+dependencies inline, replacing the old multi-step transition.
+
+Fail-fast rules:
+
+- Treat `meta.storageRootDiagnostics` as the source of truth for worktree
+  storage.
+- In linked worktrees, `sharedStorageRoot` may differ from `worktreeRoot`; that
+  is expected.
+- If `recoveryRequired` is `true`, stop and follow the reported bootstrap or
+  recovery action.
+- Do not fall back to a separate per-worktree DB or continue after missing
+  shared storage.
+
+<details>
+<summary>Legacy manual bootstrap (use <code>session</code> instead)</summary>
 
 ```bash
+trekoon --toon init
+trekoon --toon sync status
+trekoon --toon task ready --limit 5
+trekoon --toon task next
+trekoon --toon dep reverse <task-or-subtask-id>
+trekoon --toon task update <task-id> --status in_progress
 trekoon --toon task update <task-id> --append "Completed implementation and checks" --status done
-trekoon --toon task update <task-id> --append "Blocked by <reason>" --status blocked
 ```
 
+</details>
+
 ### 5) Use TOON output for agent workflows
 
 ```bash
@@ -290,6 +548,19 @@ react deterministically:
 - `diagnostics.conflictEvents`
 - `diagnostics.errorHints`
 
+Worktree diagnostics and recovery:
+
+- Inspect `storageMode`, `repoCommonDir`, `worktreeRoot`, `sharedStorageRoot`,
+  and `databaseFile` in machine output when debugging worktree behavior.
+- If a worktree resolves shared storage outside its checkout, that is expected
+  for linked worktrees and should not be “fixed” by committing `.trekoon`.
+- If Git contains a tracked `.trekoon/trekoon.db`, remove it from Git history or
+  the index as appropriate, keep `.trekoon` ignored, and re-run
+  `trekoon --toon init`.
+- Use `trekoon wipe --yes` only for explicit destructive recovery; it deletes
+  the shared storage root for the entire repository, not just the current
+  worktree.
+
 Compatibility mode for legacy sync command IDs:
 
 ```bash
@@ -379,6 +650,7 @@ Trekoon does not mutate global editor config directories.
 - [ ] done tasks/subtasks are marked completed
 - [ ] dependency graph has no stale blockers
 - [ ] final AI check: `trekoon --toon epic show <epic-id>`
+- [ ] no one tried to commit `.trekoon/trekoon.db` as a worktree fix
 
 ## Machine-contract recipes (--toon)
 

package/package.json

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

package/src/commands/arg-parser.ts

@@ -1,11 +1,25 @@
+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];
@@ -21,11 +35,18 @@ export interface PreviewApplyModeSelection {
   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[] = [];
@@ -51,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,
@@ -78,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[]
@@ -178,6 +206,90 @@ export function resolvePreviewApplyMode(
   };
 }
 
+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;
@@ -268,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);
+}