trekoon 0.4.0 → 0.4.2

package/src/commands/help.ts

@@ -13,6 +13,7 @@ const ROOT_HELP = [
   "  --json       Structured JSON output",
   "  --toon       TOON-encoded output (preferred for agents)",
   "  --compat <mode>  Machine compatibility mode",
+  "  --daemon     (experimental) Route the call through trekoon serve over a Unix socket",
   "  --help       Show help for root or a command",
   "  --version    Print CLI version",
   "",
@@ -27,12 +28,13 @@ const ROOT_HELP = [
   "  subtask      Create, list, update, and search subtasks",
   "  dep          Manage dependency edges between tasks and subtasks",
   "  events       Prune old sync event log rows",
-  "  migrate      Check schema version or roll back migrations",
+  "  migrate      Check schema version, roll back migrations, or snapshot a backup",
   "  session      Agent orientation (diagnostics + sync + next task)",
   "  suggest      Priority-ranked next-action suggestions",
   "  sync         Pull events and resolve conflicts across branches",
   "  skills       Install, link, or update the Trekoon skill",
   "  update       Alias for skills update",
+  "  serve        (experimental) Run a long-lived daemon over a Unix socket",
 ].join("\n");
 
 const INIT_HELP = [
@@ -94,11 +96,18 @@ const BOARD_HELP = [
   "          and open the browser. Returns the board URL and a fallback URL.",
   "  update  Refresh board runtime assets only. No server, no browser.",
   "",
+  "Token visibility:",
+  "  By default the board token is redacted from machine output (shown as ****).",
+  "  Pass --reveal-token to print the raw token value.",
+  "    trekoon board open --reveal-token",
+  "  Treat the token like a password: it grants full board access over loopback.",
+  "",
   "Environment:",
   "  TREKOON_BOARD_ASSET_ROOT  Override the bundled asset source (tests/dev only).",
   "",
   "Examples:",
   "  trekoon board open",
+  "  trekoon board open --reveal-token",
   "  trekoon --json board update",
 ].join("\n");
 
@@ -170,7 +179,7 @@ const EPIC_HELP = [
 ].join("\n");
 
 const TASK_HELP = [
-  "Usage: trekoon task <create|create-many|list|show|ready|next|done|search|replace|update|delete> [options]",
+  "Usage: trekoon task <create|create-many|list|show|ready|next|done|search|replace|update|delete|claim> [options]",
   "",
   "Create-many:",
   "  trekoon task create-many --epic <epic-id> --task <spec> [--task <spec> ...]",
@@ -216,10 +225,18 @@ const TASK_HELP = [
   "  Cascades atomically through descendant subtasks.",
   "  Blocked descendants abort the whole update. Only --status done|todo is supported.",
   "  Don't combine positional ID + --all with --ids, --append, --description, or --title.",
+  "",
+  "Claim:",
+  "  trekoon task claim <task-id> --owner <owner>",
+  "  Atomically claim a task using SQL compare-and-swap.",
+  "  Sets status=in_progress and owner=<owner> only when the task is todo or blocked",
+  "  and the owner field is NULL or already set to <owner>.",
+  "  Returns claimed (true|false), currentOwner, currentStatus, and the full task record on success.",
+  "  Two concurrent claim calls return exactly one claimed=true.",
 ].join("\n");
 
 const SUBTASK_HELP = [
-  "Usage: trekoon subtask <create|create-many|list|search|replace|update|delete> [options]",
+  "Usage: trekoon subtask <create|create-many|list|search|replace|update|delete|claim> [options]",
   "",
   "Create-many:",
   "  trekoon subtask create-many [<task-id>] [--task <task-id>] --subtask <spec> [--subtask <spec> ...]",
@@ -250,6 +267,14 @@ const SUBTASK_HELP = [
   "  trekoon subtask update <subtask-id> --all --status done|todo",
   "  Accepted for consistency, but just updates the one subtask (no descendants).",
   "  Don't combine positional ID + --all with --ids, --append, --description, or --title.",
+  "",
+  "Claim:",
+  "  trekoon subtask claim <subtask-id> --owner <owner>",
+  "  Atomically claim a subtask using SQL compare-and-swap.",
+  "  Sets status=in_progress and owner=<owner> only when the subtask is todo or blocked",
+  "  and the owner field is NULL or already set to <owner>.",
+  "  Returns claimed (true|false), currentOwner, currentStatus, and the full subtask record on success.",
+  "  Two concurrent claim calls return exactly one claimed=true.",
 ].join("\n");
 
 const DEP_HELP = [
@@ -292,16 +317,27 @@ const EVENTS_HELP = [
 ].join("\n");
 
 const MIGRATE_HELP = [
-  "Usage: trekoon migrate <status|rollback> [--to-version <n>]",
+  "Usage: trekoon migrate <status|rollback|backup> [--to-version <n>] [--retain <n>]",
   "",
   "Subcommands:",
   "  status                Show current schema version, latest version, and pending count.",
   "  rollback [--to-version <n>]  Roll back migrations. Defaults to one version back.",
+  "  backup [--retain <n>] Snapshot .trekoon/trekoon.db to a timestamped sibling file",
+  "                        before any manual migration recovery.",
+  "                        --retain keeps the last n timestamped backups",
+  "                        (default 10); older siblings are pruned.",
+  "",
+  "Notes:",
+  "  Migrations 0004, 0005, and 0006 are irreversible (ALTER TABLE / data cleanup).",
+  "  Rolling back below those versions errors with code migration_down_unsupported.",
+  "  Take a backup first; restore by copying the backup over .trekoon/trekoon.db.",
   "",
   "Examples:",
   "  trekoon migrate status",
   "  trekoon migrate rollback",
   "  trekoon migrate rollback --to-version 1",
+  "  trekoon migrate backup",
+  "  trekoon migrate backup --retain 5",
 ].join("\n");
 
 const SYNC_HELP = [
@@ -441,6 +477,34 @@ const SKILLS_HELP = [
   "  trekoon update",
 ].join("\n");
 
+const SERVE_HELP = [
+  "Usage: trekoon serve [--json|--toon]",
+  "",
+  "Status: EXPERIMENTAL spike. Not on by default. The default one-shot CLI",
+  "behavior is unchanged when this command is not running.",
+  "",
+  "Starts a foreground Trekoon daemon on a Unix-domain socket inside the",
+  "shared .trekoon directory. The daemon holds the SQLite connection and the",
+  "CLI shell in memory, so subsequent invocations skip Bun startup, module",
+  "load, and database open.",
+  "",
+  "Activate the client side with one of:",
+  "  TREKOON_DAEMON=1 trekoon session",
+  "  trekoon --daemon session",
+  "If the socket is missing or unreachable, the client transparently falls",
+  "back to the in-process one-shot path.",
+  "",
+  "Security:",
+  "  - Socket file mode is 0o600.",
+  "  - Parent .trekoon directory is forced to 0o700.",
+  "  - Stale sockets from prior crashes are cleaned up on start.",
+  "  - On Ctrl-C / SIGTERM the socket is unlinked.",
+  "",
+  "Examples:",
+  "  trekoon serve",
+  "  trekoon --daemon session",
+].join("\n");
+
 const COMMAND_HELP: Record<string, string> = {
   init: INIT_HELP,
   board: BOARD_HELP,
@@ -457,6 +521,7 @@ const COMMAND_HELP: Record<string, string> = {
   suggest: SUGGEST_HELP,
   skills: SKILLS_HELP,
   update: "Usage: trekoon update [--json|--toon]\n\nAlias for: trekoon skills update\n\nProbes and repairs all installed global and local skill symlinks.",
+  serve: SERVE_HELP,
   help: "Usage: trekoon help [command] [--json|--toon]",
 };
 

package/src/commands/migrate.ts

@@ -1,12 +1,18 @@
-import { parseArgs, readMissingOptionValue, readOption } from "./arg-parser";
+import { findUnknownOption, parseArgs, readMissingOptionValue, readOption } from "./arg-parser";
 import { safeErrorMessage, sqliteBusyFailure } from "./error-utils";
 
+import { DomainError } from "../domain/types";
 import { failResult, okResult } from "../io/output";
 import { type CliContext, type CliResult } from "../runtime/command-types";
+import { createMigrationBackup, DEFAULT_BACKUP_RETENTION } from "../storage/backup";
 import { openTrekoonDatabase, type TrekoonDatabase } from "../storage/database";
 import { describeMigrations, rollbackDatabase } from "../storage/migrations";
 
-const MIGRATE_USAGE = "Usage: trekoon migrate <status|rollback> [--to-version <n>]";
+const MIGRATE_USAGE = "Usage: trekoon migrate <status|rollback|backup> [--to-version <n>] [--retain <n>]";
+
+const STATUS_OPTIONS: readonly string[] = [];
+const ROLLBACK_OPTIONS: readonly string[] = ["to-version"];
+const BACKUP_OPTIONS: readonly string[] = ["retain"];
 
 function usage(message: string): CliResult {
   return failResult({
@@ -20,6 +26,19 @@ function usage(message: string): CliResult {
   });
 }
 
+function unknownOptionResult(command: string, option: string): CliResult {
+  const message = `Unknown option --${option}.`;
+  return failResult({
+    command,
+    human: message,
+    data: { option: `--${option}` },
+    error: {
+      code: "unknown_option",
+      message,
+    },
+  });
+}
+
 function parseVersion(rawValue: string | undefined): number | null {
   if (rawValue === undefined) {
     return null;
@@ -40,19 +59,107 @@ export async function runMigrate(context: CliContext): Promise<CliResult> {
     return usage("Missing migrate subcommand.");
   }
 
-  const missingOption = readMissingOptionValue(parsed.missingOptionValues, "to-version");
-  if (missingOption !== undefined) {
-    return failResult({
-      command: "migrate",
-      human: `Option --${missingOption} requires a value.`,
-      data: {
-        option: missingOption,
-      },
-      error: {
-        code: "invalid_input",
-        message: `Option --${missingOption} requires a value.`,
-      },
-    });
+  for (const optionName of ["to-version", "retain"] as const) {
+    const missingOption = readMissingOptionValue(parsed.missingOptionValues, optionName);
+    if (missingOption !== undefined) {
+      return failResult({
+        command: "migrate",
+        human: `Option --${missingOption} requires a value.`,
+        data: {
+          option: missingOption,
+        },
+        error: {
+          code: "invalid_input",
+          message: `Option --${missingOption} requires a value.`,
+        },
+      });
+    }
+  }
+
+  // The backup subcommand never opens the live DB through the standard
+  // openTrekoonDatabase pathway: backups must work even when the DB is
+  // in a partially-migrated or otherwise diagnostic-blocked state.
+  if (subcommand === "backup") {
+    const unknown = findUnknownOption(parsed, BACKUP_OPTIONS);
+    if (unknown !== undefined) {
+      return unknownOptionResult("migrate.backup", unknown);
+    }
+
+    const retainRaw: string | undefined = readOption(parsed.options, "retain");
+    let retain: number = DEFAULT_BACKUP_RETENTION;
+    if (retainRaw !== undefined) {
+      if (!/^\d+$/.test(retainRaw)) {
+        return failResult({
+          command: "migrate.backup",
+          human: "--retain must be a positive integer.",
+          data: { option: "retain" },
+          error: {
+            code: "invalid_input",
+            message: "--retain must be a positive integer.",
+          },
+        });
+      }
+
+      const parsedRetain: number = Number.parseInt(retainRaw, 10);
+      if (parsedRetain < 1) {
+        return failResult({
+          command: "migrate.backup",
+          human: "--retain must be at least 1 (the new backup itself).",
+          data: { option: "retain" },
+          error: {
+            code: "invalid_input",
+            message: "--retain must be at least 1 (the new backup itself).",
+          },
+        });
+      }
+
+      retain = parsedRetain;
+    }
+
+    try {
+      const result = createMigrationBackup({ cwd: context.cwd, retain });
+      return okResult({
+        command: "migrate.backup",
+        human: [
+          `Backed up Trekoon database to ${result.backupPath}`,
+          `Bytes: ${result.bytes}`,
+          `Schema version at backup: ${result.migrationVersion} of ${result.latestVersion}`,
+          `Retained backups: ${result.retainedCount} (pruned ${result.prunedPaths.length})`,
+        ].join("\n"),
+        data: {
+          backupPath: result.backupPath,
+          bytes: result.bytes,
+          migrationVersion: result.migrationVersion,
+          latestVersion: result.latestVersion,
+          timestamp: result.timestamp,
+          retain,
+          retainedCount: result.retainedCount,
+          prunedPaths: result.prunedPaths,
+        },
+      });
+    } catch (error: unknown) {
+      if (error instanceof DomainError) {
+        return failResult({
+          command: "migrate.backup",
+          human: error.message,
+          data: { code: error.code, ...(error.details ?? {}) },
+          error: { code: error.code, message: error.message },
+        });
+      }
+
+      const busyFailure = sqliteBusyFailure("migrate.backup", error);
+      if (busyFailure !== null) {
+        return busyFailure;
+      }
+
+      const message = safeErrorMessage(error, "Unknown backup failure.");
+      return failResult({
+        command: "migrate.backup",
+        human: message,
+        data: { reason: "backup_failed" },
+        error: { code: "backup_failed", message },
+      });
+    }
   }
 
   let storage: TrekoonDatabase | undefined;
@@ -60,6 +167,11 @@ export async function runMigrate(context: CliContext): Promise<CliResult> {
   try {
     storage = openTrekoonDatabase(context.cwd, { autoMigrate: false });
     if (subcommand === "status") {
+      const unknown = findUnknownOption(parsed, STATUS_OPTIONS);
+      if (unknown !== undefined) {
+        return unknownOptionResult("migrate.status", unknown);
+      }
+
       const status = describeMigrations(storage.db);
 
       return okResult({
@@ -74,6 +186,11 @@ export async function runMigrate(context: CliContext): Promise<CliResult> {
     }
 
     if (subcommand === "rollback") {
+      const unknown = findUnknownOption(parsed, ROLLBACK_OPTIONS);
+      if (unknown !== undefined) {
+        return unknownOptionResult("migrate.rollback", unknown);
+      }
+
       const status = describeMigrations(storage.db);
       const parsedVersion: number | null = parseVersion(readOption(parsed.options, "to-version"));
 
@@ -92,16 +209,28 @@ export async function runMigrate(context: CliContext): Promise<CliResult> {
       }
 
       const targetVersion: number = parsedVersion ?? Math.max(0, status.currentVersion - 1);
-      const summary = rollbackDatabase(storage.db, targetVersion);
+      try {
+        const summary = rollbackDatabase(storage.db, targetVersion);
 
-      return okResult({
-        command: "migrate.rollback",
-        human: [
-          `Rolled back ${summary.rolledBack} migration(s).`,
-          `From version ${summary.fromVersion} to ${summary.toVersion}.`,
-        ].join("\n"),
-        data: summary,
-      });
+        return okResult({
+          command: "migrate.rollback",
+          human: [
+            `Rolled back ${summary.rolledBack} migration(s).`,
+            `From version ${summary.fromVersion} to ${summary.toVersion}.`,
+          ].join("\n"),
+          data: summary,
+        });
+      } catch (error: unknown) {
+        if (error instanceof DomainError) {
+          return failResult({
+            command: "migrate.rollback",
+            human: error.message,
+            data: { code: error.code, ...(error.details ?? {}) },
+            error: { code: error.code, message: error.message },
+          });
+        }
+        throw error;
+      }
     }
 
     return usage(`Unknown migrate subcommand '${subcommand}'.`);

package/src/commands/quickstart.ts

@@ -57,9 +57,11 @@ const QUICKSTART_TEXT = [
   "  Filtered list:         trekoon --toon task list --status in_progress,todo --limit 20",
   "  Paginate:              trekoon --toon task list --cursor <n>",
   "  Bulk update:           trekoon --toon task update --ids id1,id2 --append \"...\" --status in_progress",
+  "  Atomic claim:          trekoon --toon task claim <task-id> --owner <owner>",
   "  Ready queue:           trekoon --toon task ready [--limit <n>] [--epic <id>]",
   "  Next candidate:        trekoon --toon task next [--epic <id>]",
   "  Export epic to MD:     trekoon --toon epic export <epic-id> [--path <path>] [--overwrite]",
+  "  Snapshot the DB:       trekoon --toon migrate backup",
   "",
   "6) List and view defaults",
   "  Default scope: open work (in_progress, todo), limit 10.",
@@ -153,7 +155,9 @@ export async function runQuickstart(_: CliContext): Promise<CliResult> {
         "trekoon --toon task list --status in_progress,todo --limit 20",
         "trekoon --toon task list --cursor <n>",
         "trekoon --toon task update --ids id1,id2 --append \"...\" --status in_progress",
+        "trekoon --toon task claim <task-id> --owner <owner>",
         "trekoon --toon epic export <epic-id>",
+        "trekoon --toon migrate backup",
       ],
       machineExamples: [
         "trekoon --toon quickstart",
@@ -162,6 +166,7 @@ export async function runQuickstart(_: CliContext): Promise<CliResult> {
         "trekoon --toon suggest",
         "trekoon --toon epic progress <epic-id>",
         "trekoon --toon task done <task-id>",
+        "trekoon --toon task claim <task-id> --owner <owner>",
         "trekoon --toon task show <task-id> --all",
         "trekoon --toon epic show <epic-id> --all",
         "trekoon --toon sync status",
@@ -169,6 +174,8 @@ export async function runQuickstart(_: CliContext): Promise<CliResult> {
         "trekoon --toon task next",
         "trekoon --toon dep reverse <task-or-subtask-id>",
         "trekoon --toon epic export <epic-id>",
+        "trekoon --toon migrate status",
+        "trekoon --toon migrate backup",
       ],
       wipeWarning: {
         command: "trekoon wipe --yes",

package/src/commands/subtask.ts

@@ -39,6 +39,7 @@ const SEARCH_OPTIONS = ["fields", "preview"] as const;
 const REPLACE_OPTIONS = ["search", "replace", "fields", "preview", "apply"] as const;
 const CREATE_MANY_OPTIONS = ["task", "t", "subtask"] as const;
 const UPDATE_OPTIONS = ["all", "ids", "append", "description", "d", "status", "s", "title", "owner"] as const;
+const CLAIM_OPTIONS = ["owner"] as const;
 const STATUS_CASCADE_UPDATE_STATUSES = ["done", "todo"] as const;
 
 function parseIdsOption(rawIds: string | undefined): string[] {
@@ -892,10 +893,9 @@ export async function runSubtask(context: CliContext): Promise<CliResult> {
 
           const targets = updateAll ? [...domain.listSubtasks()] : ids.map((id) => domain.getSubtaskOrThrow(id));
           const subtasks = targets.map((target) =>
-            mutations.updateSubtask(target.id, {
-              status,
-              description: append === undefined ? undefined : appendLine(target.description, append),
-            }),
+            append !== undefined
+              ? mutations.appendToSubtaskDescription({ subtaskId: target.id, append, status })
+              : mutations.updateSubtask(target.id, { status }),
           );
 
           return okResult({
@@ -921,11 +921,10 @@ export async function runSubtask(context: CliContext): Promise<CliResult> {
           });
         }
 
-        const nextDescription =
-          append === undefined
-            ? description
-            : appendLine(domain.getSubtaskOrThrow(subtaskId).description, append);
-        const subtask = mutations.updateSubtask(subtaskId, { title, description: nextDescription, status, owner });
+        const subtask =
+          append !== undefined
+            ? mutations.appendToSubtaskDescription({ subtaskId, append, status, owner })
+            : mutations.updateSubtask(subtaskId, { title, description, status, owner });
 
         return okResult({
           command: "subtask.update",
@@ -933,6 +932,68 @@ export async function runSubtask(context: CliContext): Promise<CliResult> {
           data: { subtask },
         });
       }
+      case "claim": {
+        const claimUnknownOption = findUnknownOption(parsed, CLAIM_OPTIONS);
+        if (claimUnknownOption !== undefined) {
+          return unknownOption("subtask.claim", claimUnknownOption, CLAIM_OPTIONS);
+        }
+
+        const missingClaimOption = readMissingOptionValue(parsed.missingOptionValues, "owner");
+        if (missingClaimOption !== undefined) {
+          return failMissingOptionValue("subtask.claim", missingClaimOption);
+        }
+
+        const subtaskId: string = parsed.positional[1] ?? "";
+        if (subtaskId.length === 0) {
+          return failResult({
+            command: "subtask.claim",
+            human: "Provide a subtask id. Usage: trekoon subtask claim <id> --owner <owner>",
+            data: { code: "invalid_input" },
+            error: {
+              code: "invalid_input",
+              message: "Missing subtask id",
+            },
+          });
+        }
+
+        const owner: string | undefined = readOption(parsed.options, "owner");
+        if (owner === undefined || owner.trim().length === 0) {
+          return failResult({
+            command: "subtask.claim",
+            human: "--owner is required. Usage: trekoon subtask claim <id> --owner <owner>",
+            data: { code: "invalid_input", option: "owner" },
+            error: {
+              code: "invalid_input",
+              message: "Missing required option --owner",
+            },
+          });
+        }
+
+        const claimResult = mutations.claimSubtask({ subtaskId, owner });
+
+        if (claimResult.claimed) {
+          return okResult({
+            command: "subtask.claim",
+            human: `Claimed subtask ${subtaskId} for ${owner}`,
+            data: {
+              claimed: true,
+              currentOwner: claimResult.currentOwner,
+              currentStatus: claimResult.currentStatus,
+              subtask: claimResult.subtask,
+            },
+          });
+        }
+
+        return okResult({
+          command: "subtask.claim",
+          human: `Subtask ${subtaskId} not claimed: status=${claimResult.currentStatus}, owner=${claimResult.currentOwner ?? "none"}`,
+          data: {
+            claimed: false,
+            currentOwner: claimResult.currentOwner,
+            currentStatus: claimResult.currentStatus,
+          },
+        });
+      }
       case "delete": {
         const subtaskId: string = parsed.positional[1] ?? "";
         const result = mutations.deleteSubtask(subtaskId);
@@ -946,7 +1007,7 @@ export async function runSubtask(context: CliContext): Promise<CliResult> {
       default:
         return failResult({
           command: "subtask",
-          human: "Usage: trekoon subtask <create|create-many|list|search|replace|update|delete>",
+          human: "Usage: trekoon subtask <create|create-many|list|search|replace|update|delete|claim>",
           data: {
             args: context.args,
           },

package/src/commands/suggest.ts

@@ -44,14 +44,7 @@ function resolveActiveEpic(domain: TrackerDomain, epicId: string | undefined): E
     return domain.getEpic(epicId);
   }
 
-  const epics = domain.listEpics();
-  const inProgress = epics.find((epic) => epic.status === "in_progress");
-  if (inProgress) {
-    return inProgress;
-  }
-
-  const todo = epics.find((epic) => epic.status === "todo");
-  return todo ?? epics[0] ?? null;
+  return domain.findActiveEpic();
 }
 
 function findInProgressTasks(readiness: TaskReadinessResult): { count: number; first: { id: string; title: string } | null } {
@@ -76,7 +69,7 @@ function buildSuggestions(
   recoveryRequired: boolean,
   syncSummary: SyncStatusSummary,
   readiness: TaskReadinessResult,
-  epics: readonly EpicRecord[],
+  epicCount: number,
   activeEpic: EpicRecord | null,
 ): readonly Suggestion[] {
   const suggestions: Suggestion[] = [];
@@ -186,7 +179,7 @@ function buildSuggestions(
   }
 
   // Priority 8: No epics exist
-  if (suggestions.length < MAX_SUGGESTIONS && epics.length === 0) {
+  if (suggestions.length < MAX_SUGGESTIONS && epicCount === 0) {
     suggestions.push({
       priority: suggestions.length + 1,
       action: "quickstart",
@@ -241,7 +234,7 @@ export async function runSuggest(context: CliContext): Promise<CliResult> {
 
     const syncSummary = resolveSyncStatus(database, context.cwd, DEFAULT_SOURCE_BRANCH);
     const domain = new TrackerDomain(database.db);
-    const epics = domain.listEpics();
+    const epicCount = domain.countEpics();
     const activeEpic = resolveActiveEpic(domain, epicId);
 
     const readiness = buildTaskReadiness(domain, epicId ?? activeEpic?.id);
@@ -250,14 +243,14 @@ export async function runSuggest(context: CliContext): Promise<CliResult> {
       diagnostics.recoveryRequired,
       syncSummary,
       readiness,
-      epics,
+      epicCount,
       activeEpic,
     );
 
     const result: SuggestResult = {
       suggestions,
       context: {
-        totalEpics: epics.length,
+        totalEpics: epicCount,
         activeEpic: activeEpic?.id ?? null,
         readyTasks: readiness.summary.readyCount,
         blockedTasks: readiness.summary.blockedCount,