trekoon 0.1.9 → 0.2.1

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);
+}

package/src/commands/events.ts

@@ -1,8 +1,9 @@
 import { hasFlag, parseArgs, parseStrictPositiveInt, readMissingOptionValue, readOption } from "./arg-parser";
+import { safeErrorMessage, sqliteBusyFailure } from "./error-utils";
 
 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";
 import { DEFAULT_EVENT_RETENTION_DAYS, pruneEvents } from "../storage/events-retention";
 
 const EVENTS_USAGE = "Usage: trekoon events prune [--dry-run] [--archive] [--retention-days <n>]";
@@ -62,9 +63,10 @@ export async function runEvents(context: CliContext): Promise<CliResult> {
   const retentionDays: number = parsedRetentionDays ?? DEFAULT_EVENT_RETENTION_DAYS;
   const dryRun: boolean = hasFlag(parsed.flags, "dry-run");
   const archive: boolean = hasFlag(parsed.flags, "archive");
-  const storage = openTrekoonDatabase(context.cwd);
+  let storage: TrekoonDatabase | undefined;
 
   try {
+    storage = openTrekoonDatabase(context.cwd);
     const summary = pruneEvents(storage.db, {
       retentionDays,
       dryRun,
@@ -82,7 +84,25 @@ export async function runEvents(context: CliContext): Promise<CliResult> {
       ].join("\n"),
       data: summary,
     });
+  } catch (error: unknown) {
+    const busyFailure = sqliteBusyFailure("events.prune", error);
+    if (busyFailure !== null) {
+      return busyFailure;
+    }
+
+    const message = safeErrorMessage(error, "Unknown events prune failure.");
+    return failResult({
+      command: "events.prune",
+      human: message,
+      data: {
+        reason: "events_failed",
+      },
+      error: {
+        code: "events_failed",
+        message,
+      },
+    });
   } finally {
-    storage.close();
+    storage?.close();
   }
 }

package/src/commands/help.ts

@@ -74,7 +74,20 @@ const WIPE_HELP = [
 ].join("\n");
 
 const EPIC_HELP = [
-  "Usage: trekoon epic <create|list|show|update|delete> [options]",
+  "Usage: trekoon epic <create|expand|list|show|search|replace|update|delete> [options]",
+  "",
+  "Create behavior:",
+  "  trekoon epic create --title \"...\" --description \"...\" [--status <status>]",
+  "  trekoon epic create --title \"...\" --description \"...\" [--task <spec>] [--subtask <spec>] [--dep <spec>]",
+  "  Preferred one-shot flow when the full tree is known up front.",
+  "  Uses the same compact spec grammar as epic expand and returns mappings/counts.",
+  "",
+  "Expand behavior:",
+  "  trekoon epic expand <epic-id> [--task <spec>] [--subtask <spec>] [--dep <spec>]",
+  "  --task <temp-key>|<title>|<description>|<status>",
+  `  --subtask <parent-ref>|<temp-key>|<title>|<description>|<status>  (use ${"@"}<temp-key> for newly declared parents)`,
+  `  --dep <source-ref>|<depends-on-ref>  (refs can be ids or ${"@"}<temp-key>)`,
+  "  Escapes inside compact specs: \\| for |, \\\\ for \\, \\n, \\r, \\t",
   "",
   "List behavior:",
   "  Defaults:",
@@ -97,6 +110,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 +128,14 @@ const EPIC_HELP = [
 ].join("\n");
 
 const TASK_HELP = [
-  "Usage: trekoon task <create|list|show|ready|next|update|delete> [options]",
+  "Usage: trekoon task <create|create-many|list|show|ready|next|search|replace|update|delete> [options]",
+  "",
+  "Create-many behavior:",
+  "  trekoon task create-many --epic <epic-id> --task <spec> [--task <spec> ...]",
+  "  --task <temp-key>|<title>|<description>|<status>",
+  "  Rejects unexpected positional arguments and empty required fields.",
+  "  Repeated --task flags are applied in the order provided.",
+  "  Escapes inside compact specs: \\| for |, \\\\ for \\, \\n, \\r, \\t",
   "",
   "List behavior:",
   "  Defaults:",
@@ -137,6 +167,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 +185,15 @@ const TASK_HELP = [
 ].join("\n");
 
 const SUBTASK_HELP = [
-  "Usage: trekoon subtask <create|list|update|delete> [options]",
+  "Usage: trekoon subtask <create|create-many|list|search|replace|update|delete> [options]",
+  "",
+  "Create-many behavior:",
+  "  trekoon subtask create-many [<task-id>] [--task <task-id>] --subtask <spec> [--subtask <spec> ...]",
+  "  --subtask <temp-key>|<title>|<description>|<status>",
+  "  Positional <task-id> and --task may be combined only when equal.",
+  "  Rejects extra positional arguments and empty required fields.",
+  "  Repeated --subtask flags are applied in the order provided.",
+  "  Escapes inside compact specs: \\| for |, \\\\ for \\, \\n, \\r, \\t",
   "",
   "List behavior:",
   "  Defaults:",
@@ -159,6 +207,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>",
@@ -167,11 +225,15 @@ const SUBTASK_HELP = [
 ].join("\n");
 
 const DEP_HELP = [
-  "Usage: trekoon dep <add|remove|list|reverse> [options]",
+  "Usage: trekoon dep <add|add-many|remove|list|reverse> [options]",
   "",
   "Subcommands:",
   "  add <source-id> <depends-on-id>",
   "      Create dependency edge: source depends on depends-on.",
+  "  add-many --dep <source-ref>|<depends-on-ref> [--dep <spec> ...]",
+  "      Create validated dependency edges from compact specs in order.",
+  "      Standalone add-many resolves persisted ids only; @<temp-key>",
+  "      refs are reserved for higher-level compact batch workflows.",
   "  remove <source-id> <depends-on-id>",
   "      Remove one dependency edge if it exists.",
   "  list <source-id>",

package/src/commands/init.ts

@@ -1,11 +1,14 @@
+import { unexpectedFailureResult } from "./error-utils";
+
 import { 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";
 
 export async function runInit(context: CliContext): Promise<CliResult> {
-  const database = openTrekoonDatabase(context.cwd);
+  let database: TrekoonDatabase | undefined;
 
   try {
+    database = openTrekoonDatabase(context.cwd);
     return okResult({
       command: "init",
       human: [
@@ -18,7 +21,12 @@ export async function runInit(context: CliContext): Promise<CliResult> {
         databaseFile: database.paths.databaseFile,
       },
     });
+  } catch (error: unknown) {
+    return unexpectedFailureResult(error, {
+      command: "init",
+      human: "Unexpected init command failure",
+    });
   } finally {
-    database.close();
+    database?.close();
   }
 }

package/src/commands/migrate.ts

@@ -1,8 +1,9 @@
 import { parseArgs, readMissingOptionValue, readOption } from "./arg-parser";
+import { safeErrorMessage, sqliteBusyFailure } from "./error-utils";
 
 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";
 import { describeMigrations, rollbackDatabase } from "../storage/migrations";
 
 const MIGRATE_USAGE = "Usage: trekoon migrate <status|rollback> [--to-version <n>]";
@@ -54,9 +55,10 @@ export async function runMigrate(context: CliContext): Promise<CliResult> {
     });
   }
 
-  const storage = openTrekoonDatabase(context.cwd, { autoMigrate: false });
+  let storage: TrekoonDatabase | undefined;
 
   try {
+    storage = openTrekoonDatabase(context.cwd, { autoMigrate: false });
     if (subcommand === "status") {
       const status = describeMigrations(storage.db);
 
@@ -104,7 +106,12 @@ export async function runMigrate(context: CliContext): Promise<CliResult> {
 
     return usage(`Unknown migrate subcommand '${subcommand}'.`);
   } catch (error: unknown) {
-    const message = error instanceof Error ? error.message : "Unknown migration failure.";
+    const busyFailure = sqliteBusyFailure("migrate", error);
+    if (busyFailure !== null) {
+      return busyFailure;
+    }
+
+    const message = safeErrorMessage(error, "Unknown migration failure.");
 
     return failResult({
       command: "migrate",
@@ -118,6 +125,6 @@ export async function runMigrate(context: CliContext): Promise<CliResult> {
       },
     });
   } finally {
-    storage.close();
+    storage?.close();
   }
 }