trekoon 0.2.0 → 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|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 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:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trekoon",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "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);
+}

package/src/commands/dep.ts

@@ -1,43 +1,172 @@
-import { parseArgs } from "./arg-parser";
+import {
+  findUnknownOption,
+  isValidCompactTempKey,
+  parseArgs,
+  parseCompactEntityRef,
+  parseCompactFields,
+  readMissingOptionValue,
+  readOptions,
+  readUnexpectedPositionals,
+  suggestOptions,
+} from "./arg-parser";
+import { unexpectedFailureResult } from "./error-utils";
 
 import { MutationService } from "../domain/mutation-service";
 import { TrackerDomain } from "../domain/tracker-domain";
-import { DomainError } from "../domain/types";
+import {
+  COMPACT_TEMP_KEY_PREFIX,
+  type CompactBatchResultContract,
+  type CompactDependencySpec,
+  type CompactEntityRef,
+} from "../domain/types";
 import { failResult, okResult } from "../io/output";
 import { type CliContext, type CliResult } from "../runtime/command-types";
-import { openTrekoonDatabase } from "../storage/database";
+import { openTrekoonDatabase, type TrekoonDatabase } from "../storage/database";
 
 function failFromError(error: unknown): CliResult {
-  if (error instanceof DomainError) {
-    return failResult({
-      command: "dep",
-      human: error.message,
-      data: {
-        code: error.code,
-        ...(error.details ?? {}),
-      },
-      error: {
-        code: error.code,
-        message: error.message,
-      },
-    });
-  }
-
-  return failResult({
+  return unexpectedFailureResult(error, {
     command: "dep",
     human: "Unexpected dep command failure",
-    data: {},
+  });
+}
+
+const ADD_MANY_OPTIONS = ["dep"] as const;
+
+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: allowedOptions.map((allowedOption) => `--${allowedOption}`),
+      suggestions,
+    },
+    error: {
+      code: "unknown_option",
+      message: `Unknown option --${option}`,
+    },
+  });
+}
+
+function failMissingOptionValue(command: string, option: string): CliResult {
+  return failResult({
+    command,
+    human: `Option --${option} requires a value.`,
+    data: {
+      code: "invalid_input",
+      option,
+    },
+    error: {
+      code: "invalid_input",
+      message: `Option --${option} requires a value`,
+    },
+  });
+}
+
+function failBatchSpec(command: string, human: string, data: Record<string, unknown>): CliResult {
+  return failResult({
+    command,
+    human,
+    data,
     error: {
-      code: "internal_error",
-      message: "Unexpected dep command failure",
+      code: "invalid_input",
+      message: human,
     },
   });
 }
 
+function failUnexpectedPositionals(command: string, unexpected: readonly string[]): CliResult {
+  return failBatchSpec(command, `Unexpected positional arguments: ${unexpected.join(", ")}.`, {
+    unexpectedPositionals: unexpected,
+  });
+}
+
+function validateCompactEntityRef(index: number, rawSpec: string, label: string, reference: CompactEntityRef): CliResult | undefined {
+  if (reference.kind === "temp_key" && !isValidCompactTempKey(reference.tempKey)) {
+    return failBatchSpec("dep.add-many", `${label} in --dep spec ${index + 1} must use ${COMPACT_TEMP_KEY_PREFIX}<temp-key> with letters, numbers, dot, dash, or underscore.`, {
+      option: "dep",
+      index,
+      rawSpec,
+      reference,
+    });
+  }
+
+  if (reference.kind === "id" && reference.id.trim().length === 0) {
+    return failBatchSpec("dep.add-many", `${label} in --dep spec ${index + 1} is required.`, {
+      option: "dep",
+      index,
+      rawSpec,
+      reference,
+    });
+  }
+
+  return undefined;
+}
+
+function parseDependencySpecs(rawSpecs: readonly string[]): { specs: CompactDependencySpec[]; error?: CliResult } {
+  const specs: CompactDependencySpec[] = [];
+
+  for (const [index, rawSpec] of rawSpecs.entries()) {
+    const parsed = parseCompactFields(rawSpec);
+    if (parsed.invalidEscape !== null) {
+      return {
+        specs: [],
+        error: failBatchSpec("dep.add-many", `Invalid escape sequence ${parsed.invalidEscape} in --dep spec ${index + 1}.`, {
+          option: "dep",
+          index,
+          rawSpec,
+        }),
+      };
+    }
+
+    if (parsed.hasDanglingEscape) {
+      return {
+        specs: [],
+        error: failBatchSpec("dep.add-many", `Trailing escape in --dep spec ${index + 1}.`, {
+          option: "dep",
+          index,
+          rawSpec,
+        }),
+      };
+    }
+
+    if (parsed.fields.length !== 2) {
+      return {
+        specs: [],
+        error: failBatchSpec("dep.add-many", `Dependency specs must use <source-ref>|<depends-on-ref> in --dep spec ${index + 1}.`, {
+          option: "dep",
+          index,
+          rawSpec,
+          fields: parsed.fields,
+        }),
+      };
+    }
+
+    const source = parseCompactEntityRef(parsed.fields[0] ?? "");
+    const sourceError = validateCompactEntityRef(index, rawSpec, "Source ref", source);
+    if (sourceError !== undefined) {
+      return { specs: [], error: sourceError };
+    }
+
+    const dependsOn = parseCompactEntityRef(parsed.fields[1] ?? "");
+    const dependsOnError = validateCompactEntityRef(index, rawSpec, "Depends-on ref", dependsOn);
+    if (dependsOnError !== undefined) {
+      return { specs: [], error: dependsOnError };
+    }
+
+    specs.push({ source, dependsOn });
+  }
+
+  return { specs };
+}
+
 export async function runDep(context: CliContext): Promise<CliResult> {
-  const database = openTrekoonDatabase(context.cwd);
+  let database: TrekoonDatabase | undefined;
 
   try {
+    database = openTrekoonDatabase(context.cwd);
     const parsed = parseArgs(context.args);
     const subcommand: string | undefined = parsed.positional[0];
     const sourceId: string = parsed.positional[1] ?? "";
@@ -55,6 +184,49 @@ export async function runDep(context: CliContext): Promise<CliResult> {
           data: { dependency },
         });
       }
+      case "add-many": {
+        const addManyUnknownOption = findUnknownOption(parsed, ADD_MANY_OPTIONS);
+        if (addManyUnknownOption !== undefined) {
+          return unknownOption("dep.add-many", addManyUnknownOption, ADD_MANY_OPTIONS);
+        }
+
+        const missingAddManyOption = readMissingOptionValue(parsed.missingOptionValues, "dep");
+        if (missingAddManyOption !== undefined) {
+          return failMissingOptionValue("dep.add-many", missingAddManyOption);
+        }
+
+        const unexpectedPositionals = readUnexpectedPositionals(parsed, 1);
+        if (unexpectedPositionals.length > 0) {
+          return failUnexpectedPositionals("dep.add-many", unexpectedPositionals);
+        }
+
+        const rawSpecs = readOptions(parsed.optionEntries, "dep");
+        if (rawSpecs.length === 0) {
+          return failBatchSpec("dep.add-many", "Provide at least one --dep spec.", {
+            option: "dep",
+          });
+        }
+
+        const specResult = parseDependencySpecs(rawSpecs);
+        if (specResult.error !== undefined) {
+          return specResult.error;
+        }
+
+        const created = mutations.addDependencyBatch({
+          specs: specResult.specs,
+        });
+        const result: CompactBatchResultContract = created.result;
+        return okResult({
+          command: "dep.add-many",
+          human: `Added ${created.dependencies.length} dependenc${created.dependencies.length === 1 ? "y" : "ies"}: ${created.dependencies
+            .map((dependency) => `${dependency.sourceId} -> ${dependency.dependsOnId}`)
+            .join("\n")}`,
+          data: {
+            dependencies: created.dependencies,
+            result,
+          },
+        });
+      }
       case "remove": {
         const removed: number = mutations.removeDependency(sourceId, dependsOnId);
 
@@ -108,7 +280,7 @@ export async function runDep(context: CliContext): Promise<CliResult> {
       default:
         return failResult({
           command: "dep",
-          human: "Usage: trekoon dep <add|remove|list|reverse>",
+          human: "Usage: trekoon dep <add|add-many|remove|list|reverse>",
           data: {
             args: context.args,
           },
@@ -121,6 +293,6 @@ export async function runDep(context: CliContext): Promise<CliResult> {
   } catch (error: unknown) {
     return failFromError(error);
   } finally {
-    database.close();
+    database?.close();
   }
 }