trekoon 0.2.0 → 0.2.1

package/src/commands/epic.ts

@@ -2,24 +2,39 @@ import {
   SEARCH_REPLACE_FIELDS,
   findUnknownOption,
   hasFlag,
+  isValidCompactTempKey,
   parseArgs,
+  parseCompactEntityRef,
+  parseCompactFields,
   parseCsvEnumOption,
   parseStrictNonNegativeInt,
   parseStrictPositiveInt,
   readEnumOption,
   readMissingOptionValue,
   readOption,
+  readOptions,
+  readUnexpectedPositionals,
   resolvePreviewApplyMode,
   suggestOptions,
 } from "./arg-parser";
+import { unexpectedFailureResult } from "./error-utils";
 
 import { MutationService } from "../domain/mutation-service";
 import { TrackerDomain } from "../domain/tracker-domain";
-import { DomainError, type EpicRecord, type SearchEntityMatch } from "../domain/types";
+import {
+  COMPACT_TEMP_KEY_PREFIX,
+  type CompactBatchResultContract,
+  type CompactDependencySpec,
+  type CompactEntityRef,
+  type CompactSubtaskSpec,
+  type CompactTaskSpec,
+  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";
-import { openTrekoonDatabase } from "../storage/database";
+import { openTrekoonDatabase, type TrekoonDatabase } from "../storage/database";
 
 function formatEpic(epic: EpicRecord): string {
   return `${epic.id} | ${epic.title} | ${epic.status}`;
@@ -29,8 +44,10 @@ 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 CREATE_OPTIONS = ["title", "t", "description", "d", "status", "s", "task", "subtask", "dep"] as const;
 const SEARCH_OPTIONS = ["fields", "preview"] as const;
 const REPLACE_OPTIONS = ["search", "replace", "fields", "preview", "apply"] as const;
+const EXPAND_OPTIONS = ["task", "subtask", "dep"] as const;
 
 function parseStatusCsv(rawStatuses: string | undefined): string[] | undefined {
   if (rawStatuses === undefined) {
@@ -304,36 +321,346 @@ function formatEpicShowTable(tree: {
 }
 
 function failFromError(error: unknown, command: string): CliResult {
-  if (error instanceof DomainError) {
-    return failResult({
-      command,
-      human: error.message,
-      data: {
-        code: error.code,
-        ...(error.details ?? {}),
-      },
-      error: {
-        code: error.code,
-        message: error.message,
-      },
-    });
-  }
+  return unexpectedFailureResult(error, {
+    command,
+    human: "Unexpected epic command failure",
+  });
+}
 
+function failBatchSpec(command: string, human: string, data: Record<string, unknown>): CliResult {
   return failResult({
     command,
-    human: "Unexpected epic command failure",
-    data: {},
+    human,
+    data,
     error: {
-      code: "internal_error",
-      message: "Unexpected epic 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 failEmptyCompactField(command: string, option: string, index: number, rawSpec: string, field: string): CliResult {
+  const label = option === "task" ? "Task" : "Subtask";
+  return failBatchSpec(command, `${label} spec ${index + 1} is missing a ${field}.`, {
+    option,
+    index,
+    rawSpec,
+    field,
+  });
+}
+
+function validateCompactEntityRef(
+  command: string,
+  option: string,
+  index: number,
+  rawSpec: string,
+  label: string,
+  reference: CompactEntityRef,
+): CliResult | undefined {
+  if (reference.kind === "temp_key" && !isValidCompactTempKey(reference.tempKey)) {
+    return failBatchSpec(command, `${label} in --${option} spec ${index + 1} must use ${COMPACT_TEMP_KEY_PREFIX}<temp-key> with letters, numbers, dot, dash, or underscore.`, {
+      option,
+      index,
+      rawSpec,
+      reference,
+    });
+  }
+
+  if (reference.kind === "id" && reference.id.trim().length === 0) {
+    return failBatchSpec(command, `${label} in --${option} spec ${index + 1} is required.`, {
+      option,
+      index,
+      rawSpec,
+      reference,
+    });
+  }
+
+  return undefined;
+}
+
+function parseExpandTaskSpecs(rawSpecs: readonly string[]): { specs: CompactTaskSpec[]; error?: CliResult } {
+  const specs: CompactTaskSpec[] = [];
+  const seenTempKeys = new Set<string>();
+
+  for (const [index, rawSpec] of rawSpecs.entries()) {
+    const parsed = parseCompactFields(rawSpec);
+    if (parsed.invalidEscape !== null) {
+      return {
+        specs: [],
+        error: failBatchSpec("epic.expand", `Invalid escape sequence ${parsed.invalidEscape} in --task spec ${index + 1}.`, {
+          option: "task",
+          index,
+          rawSpec,
+        }),
+      };
+    }
+
+    if (parsed.hasDanglingEscape) {
+      return {
+        specs: [],
+        error: failBatchSpec("epic.expand", `Trailing escape in --task spec ${index + 1}.`, {
+          option: "task",
+          index,
+          rawSpec,
+        }),
+      };
+    }
+
+    if (parsed.fields.length !== 4) {
+      return {
+        specs: [],
+        error: failBatchSpec("epic.expand", `Task specs must use <temp-key>|<title>|<description>|<status> in --task spec ${index + 1}.`, {
+          option: "task",
+          index,
+          rawSpec,
+          fields: parsed.fields,
+        }),
+      };
+    }
+
+    const tempKey = parsed.fields[0] ?? "";
+    const title = parsed.fields[1] ?? "";
+    const description = parsed.fields[2] ?? "";
+    const status = parsed.fields[3] ?? "";
+    if (!tempKey || !isValidCompactTempKey(tempKey)) {
+      return {
+        specs: [],
+        error: failBatchSpec("epic.expand", `Task spec ${index + 1} must start with a temp key like seed-1.`, {
+          option: "task",
+          index,
+          rawSpec,
+          tempKey,
+        }),
+      };
+    }
+
+    if (seenTempKeys.has(tempKey)) {
+      return {
+        specs: [],
+        error: failBatchSpec("epic.expand", `Duplicate temp key '${tempKey}' across --task specs.`, {
+          option: "task",
+          index,
+          rawSpec,
+          tempKey,
+        }),
+      };
+    }
+
+    if (!title || title.trim().length === 0) {
+      return {
+        specs: [],
+        error: failBatchSpec("epic.expand", `Task spec ${index + 1} is missing a title.`, {
+          option: "task",
+          index,
+          rawSpec,
+        }),
+      };
+    }
+
+    if (description.trim().length === 0) {
+      return {
+        specs: [],
+        error: failEmptyCompactField("epic.expand", "task", index, rawSpec, "description"),
+      };
+    }
+
+    seenTempKeys.add(tempKey);
+    const spec: CompactTaskSpec = status.length > 0
+      ? { tempKey, title, description, status }
+      : { tempKey, title, description };
+    specs.push(spec);
+  }
+
+  return { specs };
+}
+
+function parseExpandSubtaskSpecs(rawSpecs: readonly string[]): { specs: CompactSubtaskSpec[]; error?: CliResult } {
+  const specs: CompactSubtaskSpec[] = [];
+  const seenTempKeys = new Set<string>();
+
+  for (const [index, rawSpec] of rawSpecs.entries()) {
+    const parsed = parseCompactFields(rawSpec);
+    if (parsed.invalidEscape !== null) {
+      return {
+        specs: [],
+        error: failBatchSpec("epic.expand", `Invalid escape sequence ${parsed.invalidEscape} in --subtask spec ${index + 1}.`, {
+          option: "subtask",
+          index,
+          rawSpec,
+        }),
+      };
+    }
+
+    if (parsed.hasDanglingEscape) {
+      return {
+        specs: [],
+        error: failBatchSpec("epic.expand", `Trailing escape in --subtask spec ${index + 1}.`, {
+          option: "subtask",
+          index,
+          rawSpec,
+        }),
+      };
+    }
+
+    if (parsed.fields.length !== 5) {
+      return {
+        specs: [],
+        error: failBatchSpec("epic.expand", `Subtask specs must use <parent-ref>|<temp-key>|<title>|<description>|<status> in --subtask spec ${index + 1}.`, {
+          option: "subtask",
+          index,
+          rawSpec,
+          fields: parsed.fields,
+        }),
+      };
+    }
+
+    const parent = parseCompactEntityRef(parsed.fields[0] ?? "");
+    const parentError = validateCompactEntityRef("epic.expand", "subtask", index, rawSpec, "Parent ref", parent);
+    if (parentError !== undefined) {
+      return { specs: [], error: parentError };
+    }
+
+    const tempKey = parsed.fields[1] ?? "";
+    const title = parsed.fields[2] ?? "";
+    const description = parsed.fields[3] ?? "";
+    const status = parsed.fields[4] ?? "";
+    if (!tempKey || !isValidCompactTempKey(tempKey)) {
+      return {
+        specs: [],
+        error: failBatchSpec("epic.expand", `Subtask spec ${index + 1} must include a valid temp key.`, {
+          option: "subtask",
+          index,
+          rawSpec,
+          tempKey,
+        }),
+      };
+    }
+
+    if (seenTempKeys.has(tempKey)) {
+      return {
+        specs: [],
+        error: failBatchSpec("epic.expand", `Duplicate temp key '${tempKey}' across --subtask specs.`, {
+          option: "subtask",
+          index,
+          rawSpec,
+          tempKey,
+        }),
+      };
+    }
+
+    if (!title || title.trim().length === 0) {
+      return {
+        specs: [],
+        error: failBatchSpec("epic.expand", `Subtask spec ${index + 1} is missing a title.`, {
+          option: "subtask",
+          index,
+          rawSpec,
+        }),
+      };
+    }
+
+    if (description.trim().length === 0) {
+      return {
+        specs: [],
+        error: failEmptyCompactField("epic.expand", "subtask", index, rawSpec, "description"),
+      };
+    }
+
+    seenTempKeys.add(tempKey);
+    const spec: CompactSubtaskSpec = status.length > 0
+      ? { parent, tempKey, title, description, status }
+      : { parent, tempKey, title, description };
+    specs.push(spec);
+  }
+
+  return { specs };
+}
+
+function parseExpandDependencySpecs(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("epic.expand", `Invalid escape sequence ${parsed.invalidEscape} in --dep spec ${index + 1}.`, {
+          option: "dep",
+          index,
+          rawSpec,
+        }),
+      };
+    }
+
+    if (parsed.hasDanglingEscape) {
+      return {
+        specs: [],
+        error: failBatchSpec("epic.expand", `Trailing escape in --dep spec ${index + 1}.`, {
+          option: "dep",
+          index,
+          rawSpec,
+        }),
+      };
+    }
+
+    if (parsed.fields.length !== 2) {
+      return {
+        specs: [],
+        error: failBatchSpec("epic.expand", `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("epic.expand", "dep", index, rawSpec, "Source ref", source);
+    if (sourceError !== undefined) {
+      return { specs: [], error: sourceError };
+    }
+
+    const dependsOn = parseCompactEntityRef(parsed.fields[1] ?? "");
+    const dependsOnError = validateCompactEntityRef("epic.expand", "dep", index, rawSpec, "Depends-on ref", dependsOn);
+    if (dependsOnError !== undefined) {
+      return { specs: [], error: dependsOnError };
+    }
+
+    specs.push({ source, dependsOn });
+  }
+
+  return { specs };
+}
+
+function findDuplicateExpandTempKey(tasks: readonly CompactTaskSpec[], subtasks: readonly CompactSubtaskSpec[]): string | null {
+  const seen = new Set<string>();
+  for (const task of tasks) {
+    seen.add(task.tempKey);
+  }
+
+  for (const subtask of subtasks) {
+    if (seen.has(subtask.tempKey)) {
+      return subtask.tempKey;
+    }
+
+    seen.add(subtask.tempKey);
+  }
+
+  return null;
+}
+
 export async function runEpic(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 domain = new TrackerDomain(database.db);
@@ -341,26 +668,161 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
 
     switch (subcommand) {
       case "create": {
-        const missingCreateOption =
+      const missingCreateOption =
+          readMissingOptionValue(parsed.missingOptionValues, "title", "t") ??
           readMissingOptionValue(parsed.missingOptionValues, "status", "s") ??
-          readMissingOptionValue(parsed.missingOptionValues, "description", "d");
+          readMissingOptionValue(parsed.missingOptionValues, "description", "d") ??
+          readMissingOptionValue(parsed.missingOptionValues, "task", "subtask", "dep");
         if (missingCreateOption !== undefined) {
           return failMissingOptionValue("epic.create", missingCreateOption);
         }
 
+        const createUnknownOption = findUnknownOption(parsed, CREATE_OPTIONS);
+        if (createUnknownOption !== undefined) {
+          return unknownOption("epic.create", createUnknownOption, CREATE_OPTIONS);
+        }
+
+        const unexpectedPositionals = readUnexpectedPositionals(parsed, 1);
+        if (unexpectedPositionals.length > 0) {
+          return failUnexpectedPositionals("epic.create", unexpectedPositionals);
+        }
+
         const title: string | undefined = readOption(parsed.options, "title", "t");
         const description: string | undefined = readOption(parsed.options, "description", "d");
         const status: string | undefined = readOption(parsed.options, "status", "s");
-        const epic = mutations.createEpic({
+
+        const taskSpecs = readOptions(parsed.optionEntries, "task");
+        const subtaskSpecs = readOptions(parsed.optionEntries, "subtask");
+        const dependencySpecs = readOptions(parsed.optionEntries, "dep");
+
+        if (taskSpecs.length === 0 && subtaskSpecs.length === 0 && dependencySpecs.length === 0) {
+          const epic = mutations.createEpic({
+            title: title ?? "",
+            description: description ?? "",
+            status,
+          });
+
+          return okResult({
+            command: "epic.create",
+            human: `Created epic ${formatEpic(epic)}`,
+            data: { epic },
+          });
+        }
+
+        const parsedTasks = parseExpandTaskSpecs(taskSpecs);
+        if (parsedTasks.error !== undefined) {
+          return parsedTasks.error;
+        }
+
+        const parsedSubtasks = parseExpandSubtaskSpecs(subtaskSpecs);
+        if (parsedSubtasks.error !== undefined) {
+          return parsedSubtasks.error;
+        }
+
+        const parsedDeps = parseExpandDependencySpecs(dependencySpecs);
+        if (parsedDeps.error !== undefined) {
+          return parsedDeps.error;
+        }
+
+        const duplicateTempKey = findDuplicateExpandTempKey(parsedTasks.specs, parsedSubtasks.specs);
+        if (duplicateTempKey !== null) {
+          return failBatchSpec("epic.create", `Duplicate temp key '${duplicateTempKey}' across --task and --subtask specs.`, {
+            tempKey: duplicateTempKey,
+          });
+        }
+
+        const created = mutations.createEpicGraph({
           title: title ?? "",
           description: description ?? "",
           status,
+          taskSpecs: parsedTasks.specs,
+          subtaskSpecs: parsedSubtasks.specs,
+          dependencySpecs: parsedDeps.specs,
         });
 
         return okResult({
           command: "epic.create",
-          human: `Created epic ${formatEpic(epic)}`,
-          data: { epic },
+          human: `Created epic ${formatEpic(created.epic)} with ${created.tasks.length} task(s), ${created.subtasks.length} subtask(s), and ${created.dependencies.length} dependenc${created.dependencies.length === 1 ? "y" : "ies"}.`,
+          data: {
+            epic: created.epic,
+            tasks: created.tasks,
+            subtasks: created.subtasks,
+            dependencies: created.dependencies,
+            result: created.result,
+          },
+        });
+      }
+      case "expand": {
+        const expandUnknownOption = findUnknownOption(parsed, EXPAND_OPTIONS);
+        if (expandUnknownOption !== undefined) {
+          return unknownOption("epic.expand", expandUnknownOption, EXPAND_OPTIONS);
+        }
+
+        const missingExpandOption = readMissingOptionValue(parsed.missingOptionValues, "task", "subtask", "dep");
+        if (missingExpandOption !== undefined) {
+          return failMissingOptionValue("epic.expand", missingExpandOption);
+        }
+
+        const unexpectedPositionals = readUnexpectedPositionals(parsed, 2);
+        if (unexpectedPositionals.length > 0) {
+          return failUnexpectedPositionals("epic.expand", unexpectedPositionals);
+        }
+
+        const epicId: string = parsed.positional[1] ?? "";
+        if (epicId.trim().length === 0) {
+          return failBatchSpec("epic.expand", "Provide an epic id for epic expand.", {
+            id: epicId,
+          });
+        }
+
+        const taskSpecs = readOptions(parsed.optionEntries, "task");
+        const subtaskSpecs = readOptions(parsed.optionEntries, "subtask");
+        const dependencySpecs = readOptions(parsed.optionEntries, "dep");
+        if (taskSpecs.length === 0 && subtaskSpecs.length === 0 && dependencySpecs.length === 0) {
+          return failBatchSpec("epic.expand", "Provide at least one --task, --subtask, or --dep spec.", {});
+        }
+
+        const parsedTasks = parseExpandTaskSpecs(taskSpecs);
+        if (parsedTasks.error !== undefined) {
+          return parsedTasks.error;
+        }
+
+        const parsedSubtasks = parseExpandSubtaskSpecs(subtaskSpecs);
+        if (parsedSubtasks.error !== undefined) {
+          return parsedSubtasks.error;
+        }
+
+        const parsedDeps = parseExpandDependencySpecs(dependencySpecs);
+        if (parsedDeps.error !== undefined) {
+          return parsedDeps.error;
+        }
+
+        const duplicateTempKey = findDuplicateExpandTempKey(parsedTasks.specs, parsedSubtasks.specs);
+        if (duplicateTempKey !== null) {
+          return failBatchSpec("epic.expand", `Duplicate temp key '${duplicateTempKey}' across --task and --subtask specs.`, {
+            tempKey: duplicateTempKey,
+          });
+        }
+
+        const created = mutations.expandEpic({
+          epicId,
+          taskSpecs: parsedTasks.specs,
+          subtaskSpecs: parsedSubtasks.specs,
+          dependencySpecs: parsedDeps.specs,
+        });
+        const result: CompactBatchResultContract & {
+          counts: { tasks: number; subtasks: number; dependencies: number };
+        } = created.result;
+        return okResult({
+          command: "epic.expand",
+          human: `Expanded epic ${epicId} with ${created.tasks.length} task(s), ${created.subtasks.length} subtask(s), and ${created.dependencies.length} dependenc${created.dependencies.length === 1 ? "y" : "ies"}.`,
+          data: {
+            epicId,
+            tasks: created.tasks,
+            subtasks: created.subtasks,
+            dependencies: created.dependencies,
+            result,
+          },
         });
       }
       case "list": {
@@ -841,7 +1303,7 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
       default:
         return failResult({
           command: "epic",
-          human: "Usage: trekoon epic <create|list|show|search|replace|update|delete>",
+          human: "Usage: trekoon epic <create|expand|list|show|search|replace|update|delete>",
           data: {
             args: context.args,
           },
@@ -854,6 +1316,6 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
   } catch (error: unknown) {
     return failFromError(error, "epic");
   } finally {
-    database.close();
+    database?.close();
   }
 }

package/src/commands/error-utils.ts

@@ -0,0 +1,111 @@
+import { DomainError } from "../domain/types";
+import { failResult } from "../io/output";
+import { type CliResult } from "../runtime/command-types";
+
+interface UnexpectedFailureOptions {
+  readonly command: string;
+  readonly human: string;
+  readonly data?: Record<string, unknown>;
+  readonly errorCode?: string;
+  readonly errorMessage?: string;
+}
+
+function readErrorMessage(error: unknown): string | null {
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  if (typeof error === "string") {
+    return error;
+  }
+
+  if (typeof error === "object" && error !== null && "message" in error) {
+    const candidate = (error as { message?: unknown }).message;
+    if (typeof candidate === "string") {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+function sanitizeErrorMessage(message: string): string {
+  const normalized = message.replace(/\s+/gu, " ").trim();
+  if (normalized.length <= 240) {
+    return normalized;
+  }
+
+  return `${normalized.slice(0, 237)}...`;
+}
+
+function isSqliteBusyMessage(message: string): boolean {
+  const normalized = sanitizeErrorMessage(message).toLowerCase();
+  const hasDatabaseContext = normalized.includes("sqlite") || normalized.includes("database");
+  const hasBusySignal =
+    normalized.includes("sqlite_busy") ||
+    normalized.includes("database is locked") ||
+    normalized.includes("database schema is locked") ||
+    normalized.includes("database table is locked") ||
+    normalized.includes("busy");
+
+  return hasDatabaseContext && hasBusySignal;
+}
+
+export function sqliteBusyFailure(command: string, error: unknown): CliResult | null {
+  const message = readErrorMessage(error);
+  if (message === null || !isSqliteBusyMessage(message)) {
+    return null;
+  }
+
+  const safeMessage = sanitizeErrorMessage(message);
+  return failResult({
+    command,
+    human: `Trekoon database is busy. ${safeMessage}`,
+    data: {
+      code: "database_busy",
+      reason: "database_busy",
+      databaseMessage: safeMessage,
+    },
+    error: {
+      code: "database_busy",
+      message: `Trekoon database is busy: ${safeMessage}`,
+    },
+  });
+}
+
+export function unexpectedFailureResult(error: unknown, options: UnexpectedFailureOptions): CliResult {
+  if (error instanceof DomainError) {
+    return failResult({
+      command: options.command,
+      human: error.message,
+      data: {
+        code: error.code,
+        ...(error.details ?? {}),
+      },
+      error: {
+        code: error.code,
+        message: error.message,
+      },
+    });
+  }
+
+  const busyFailure = sqliteBusyFailure(options.command, error);
+  if (busyFailure !== null) {
+    return busyFailure;
+  }
+
+  return failResult({
+    command: options.command,
+    human: options.human,
+    data: options.data ?? {},
+    error: {
+      code: options.errorCode ?? "internal_error",
+      message: options.errorMessage ?? options.human,
+    },
+  });
+}
+
+export function safeErrorMessage(error: unknown, fallback: string): string {
+  const message = readErrorMessage(error);
+  return message === null ? fallback : sanitizeErrorMessage(message);
+}