trekoon 0.3.3 → 0.3.4

package/src/commands/quickstart.ts

@@ -4,90 +4,73 @@ import { type CliContext, type CliResult } from "../runtime/command-types";
 const QUICKSTART_TEXT = [
   "Trekoon quickstart",
   "",
-  "This quickstart is aligned with .agents/skills/trekoon/SKILL.md.",
-  "For agents: always use --toon for every command.",
+  "Agents: always use --toon on every command.",
+  "Aligned with: .agents/skills/trekoon/SKILL.md",
   "",
-  "1) Shared storage model",
-  "- In git repos and worktrees, Trekoon resolves one repo-scoped .trekoon directory.",
-  "- Every worktree for the same repo points at the same .trekoon/trekoon.db file.",
-  "- Keep .trekoon gitignored: the SQLite DB is live operational state, not source.",
-  "- Committing the DB is the wrong fix for setup drift because it snapshots machine-local state.",
+  "1) Storage model",
+  "  In git repos and worktrees, Trekoon keeps one shared .trekoon directory",
+  "  and one shared .trekoon/trekoon.db database per repository.",
+  "  Keep .trekoon gitignored. The DB is live state, not source code.",
+  "  Don't commit the DB; that snapshots machine-local state and won't help.",
   "",
-  "2) Bootstrap and agent startup (primary)",
-  "- Single call: trekoon --toon session",
-  "- Replaces: init + sync status + task next + dep list + task show in one call.",
-  "- Returns diagnostics, next ready task, its dependencies, and full task payload.",
-  "- If diagnostics show recoveryRequired or a tracked/ignored mismatch, stop and repair setup.",
-  "- Do not continue after storage mismatch, ambiguous recovery, or broken bootstrap warnings.",
-  "- In worktrees, confirm meta.storageRootDiagnostics.sharedStorageRoot matches the repo root.",
+  "2) Agent startup",
+  "  Single call: trekoon --toon session",
+  "  Returns diagnostics, sync status, next ready task, its dependencies,",
+  "  and the full task payload. Replaces init + sync status + task next in one call.",
   "",
-  "2a) Bootstrap (manual/legacy — use session instead)",
-  "- 1. Initialize or verify shared storage: trekoon --toon init",
-  "- 2. Read machine diagnostics: trekoon --toon sync status",
-  "- 3. Select next task: trekoon --toon task next",
-  "- 4. Check dependencies: trekoon --toon dep list <task-id>",
-  "- 5. Show full task: trekoon --toon task show <task-id> --all",
+  "  If diagnostics show recoveryRequired or a tracked/ignored mismatch,",
+  "  stop and fix the setup before continuing.",
   "",
-  "3) AI execution loop (deterministic, dependency-aware)",
-  "- 1. Start or resume session: trekoon --toon session",
-  "- 2. Claim work: trekoon --toon task update <task-id> --status in_progress",
-  "- 3. Complete with context: trekoon --toon task done <task-id> --append \"Completed implementation\"",
-  "  - Replaces: update status done + task next + dep list + task show in one call.",
-  "  - Returns next ready task, its dependencies, and full task payload.",
-  "- 4. Or report block: trekoon --toon task update <task-id> --append \"Blocked by <reason>\" --status blocked",
+  "  Manual bootstrap (step by step):",
+  "    trekoon --toon init",
+  "    trekoon --toon sync status",
+  "    trekoon --toon task next",
   "",
-  "4) Worktree diagnostics and recovery",
-  "- Read machine fields when available: storageMode, repoCommonDir, worktreeRoot, sharedStorageRoot, databaseFile.",
-  "- sharedStorageRoot differs from worktreeRoot in linked worktrees; that is expected and should be visible.",
-  "- If recoveryRequired is true, run trekoon --toon init and follow the reported recovery action before more commands.",
-  "- If tracked and ignored storage disagree, delete the bad fix in Git and re-bootstrap local storage instead.",
+  "3) Execution loop",
+  "  1. Start session:  trekoon --toon session [--epic <epic-id>]",
+  "  2. Claim work:     trekoon --toon task update <task-id> --status in_progress",
+  "  3. Log progress:   trekoon --toon task update <task-id> --append \"Done with implementation\"",
+  "  4. Finish:         trekoon --toon task done <task-id>",
+  "     Returns the next ready task, its deps, and full payload.",
+  "  5. Or report block: trekoon --toon task update <task-id> --append \"Blocked: <reason>\" --status blocked",
   "",
-  "5) Power-user command patterns (aligned with skill)",
-  "- Inspect full epic tree: trekoon --toon epic show <epic-id> --all",
-  "- Inspect full task payload: trekoon --toon task show <task-id> --all",
-  "- Check direct dependencies before starting: trekoon --toon dep list <task-id>",
-  "- Find what this item unblocks: trekoon --toon dep reverse <task-or-subtask-id>",
-  "- Filter list explicitly: trekoon --toon task list --status in_progress,todo --limit 20",
-  "- Paginate deterministically: trekoon --toon task list --cursor <n>",
-  "- Bulk append/status update: trekoon --toon task update --ids id1,id2 --append \"...\" --status in_progress",
+  "4) Orientation and suggestions",
+  "  Next-action suggestions:  trekoon --toon suggest [--epic <epic-id>]",
+  "  Epic progress:            trekoon --toon epic progress <epic-id>",
+  "  Open the board:           trekoon board open",
   "",
-  "6) Task details and description",
-  "- Human list and show views default to table format.",
-  "- Alternate list view: add --view compact.",
-  "- task/epic/subtask list defaults: open work only (in_progress/in-progress, todo), max 10.",
-  "- Filter list by status: --status in_progress,todo (CSV).",
-  "- Change page size: --limit <n>. Show all statuses and all rows with --all.",
-  "- Continue pagination with --cursor <n> (offset-like list position).",
-  "- --all cannot be combined with --status, --limit, or --cursor.",
-  "- Bulk update: use --all or --ids <csv> with --append and/or --status.",
-  "- Bulk update rejects positional id, and --all/--ids cannot be combined.",
-  "- Ready queue: trekoon task ready [--limit <n>] [--epic <id>] (deterministic order).",
-  "- Next execution candidate: trekoon task next [--epic <id>]",
-  "- Full tree + descriptions (canonical): trekoon --toon epic show <epic-id> --all",
-  "- Full task payload (including description): trekoon --toon task show <task-id> --all",
-  "- Optional integration format: trekoon --json task show <task-id> --all",
+  "5) Common commands",
+  "  Full epic tree:        trekoon --toon epic show <epic-id> --all",
+  "  Full task payload:     trekoon --toon task show <task-id> --all",
+  "  Check dependencies:    trekoon --toon dep list <task-id>",
+  "  What does this unblock: trekoon --toon dep reverse <task-or-subtask-id>",
+  "  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",
+  "  Ready queue:           trekoon --toon task ready [--limit <n>] [--epic <id>]",
+  "  Next candidate:        trekoon --toon task next [--epic <id>]",
   "",
-  "7) Pre-merge sync flow",
-  "- Run: trekoon --toon sync status",
-  "- Pull upstream tracker events: trekoon --toon sync pull --from main",
-  "- Resolve conflicts if needed: trekoon --toon sync resolve <id> --use ours",
-  "- Run sync status again before opening or merging a PR.",
+  "6) List and view defaults",
+  "  Default scope: open work (in_progress, todo), limit 10.",
+  "  Filters: --status <csv>, --limit <n>, --cursor <n>, or --all for everything.",
+  "  Views: --view table (default) or --view compact.",
+  "  --all cannot be combined with --status, --limit, or --cursor.",
   "",
-  "8) Shared-storage wipe warning",
-  "- trekoon wipe --yes removes the shared repo-scoped .trekoon directory for every worktree in the repo.",
-  "- Treat wipe as destructive recovery, not routine cleanup.",
-  "- Never use wipe as a substitute for sync, bootstrap, or gitignore fixes.",
+  "7) Pre-merge sync",
+  "  trekoon --toon sync status",
+  "  trekoon --toon sync pull --from main",
+  "  trekoon --toon sync conflicts list",
+  "  trekoon --toon sync conflicts show <id>",
+  "  trekoon --toon sync resolve <id> --use theirs --dry-run",
+  "  trekoon --toon sync resolve <id> --use ours|theirs",
+  "  trekoon --toon sync status",
+  "  Always inspect conflicts before resolving. In human mode, --use theirs",
+  "  prompts for confirmation (30s timeout, defaults to reject).",
   "",
-  "9) Machine output examples",
-  "- trekoon --toon quickstart",
-  "- trekoon --toon session",
-  "- trekoon --toon task done <task-id> --append \"Completed implementation\"",
-  "- trekoon --toon task show <task-id> --all",
-  "- trekoon --toon epic show <epic-id> --all",
-  "- trekoon --toon sync status",
-  "- trekoon --toon task ready --limit 5",
-  "- trekoon --toon task next",
-  "- trekoon --toon dep reverse <task-or-subtask-id>",
+  "8) Wipe (destructive recovery only)",
+  "  trekoon wipe --yes",
+  "  Removes the shared .trekoon directory for every worktree in the repo.",
+  "  Don't use this for routine cleanup, sync fixes, or gitignore issues.",
 ].join("\n");
 
 export async function runQuickstart(_: CliContext): Promise<CliResult> {
@@ -120,13 +103,17 @@ export async function runQuickstart(_: CliContext): Promise<CliResult> {
       preMergeFlow: [
         "trekoon --toon sync status",
         "trekoon --toon sync pull --from main",
-        "trekoon --toon sync resolve <id> --use ours",
+        "trekoon --toon sync conflicts list",
+        "trekoon --toon sync conflicts show <id>",
+        "trekoon --toon sync resolve <id> --use theirs --dry-run",
+        "trekoon --toon sync resolve <id> --use ours|theirs",
         "trekoon --toon sync status",
       ],
       executionLoop: [
         "trekoon --toon session",
         "trekoon --toon task update <task-id> --status in_progress",
-        "trekoon --toon task done <task-id> --append \"Completed implementation\"",
+        "trekoon --toon task update <task-id> --append \"Completed implementation\"",
+        "trekoon --toon task done <task-id>",
       ],
       diagnostics: [
         "storageMode",
@@ -153,7 +140,10 @@ export async function runQuickstart(_: CliContext): Promise<CliResult> {
       machineExamples: [
         "trekoon --toon quickstart",
         "trekoon --toon session",
-        "trekoon --toon task done <task-id> --append \"Completed implementation\"",
+        "trekoon --toon session --epic <epic-id>",
+        "trekoon --toon suggest",
+        "trekoon --toon epic progress <epic-id>",
+        "trekoon --toon task done <task-id>",
         "trekoon --toon task show <task-id> --all",
         "trekoon --toon epic show <epic-id> --all",
         "trekoon --toon sync status",

package/src/commands/skills.ts

@@ -1,4 +1,4 @@
-import { existsSync, lstatSync, mkdirSync, readlinkSync, realpathSync, rmSync, symlinkSync } from "node:fs";
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, realpathSync, rmSync, symlinkSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -262,8 +262,8 @@ function installCanonicalSkill(cwd: string): CliResult | { sourcePath: string; i
   const resolvedSourceDir: string = resolve(sourceDir);
 
   // Self-reference guard: when cwd IS the package dir (e.g. developing Trekoon
-  // itself), the source dir and installed dir are the same path. Do not create
-  // a circular symlink — the directory already contains the bundled files.
+  // itself), the source dir and installed dir are the same path. Do not copy
+  // over itself — the directory already contains the bundled files.
   if (resolve(installedDir) === resolvedSourceDir) {
     return { sourcePath, installedPath, installedDir };
   }
@@ -286,32 +286,30 @@ function installCanonicalSkill(cwd: string): CliResult | { sourcePath: string; i
     }
 
     if (pathOccupied) {
-      if (existingIsSymlink) {
-        // Already a symlink — check whether it points to the correct target.
-        // Use realpathSync so OS-level symlinks (macOS /var → /private/var)
-        // do not cause false mismatches.
+      if (existingIsDir && !existingIsSymlink) {
+        // Real directory — check whether contents are already up to date.
         try {
-          const resolvedExisting: string = realpathSync(installedDir);
-          if (resolvedExisting === realpathSync(resolvedSourceDir)) {
-            // Symlink is already correct; idempotent success.
+          const sourceContents = readFileSync(sourcePath, "utf8");
+          const installedContents = readFileSync(installedPath, "utf8");
+          if (sourceContents === installedContents) {
+            // Already up to date; idempotent success.
             return { sourcePath, installedPath, installedDir };
           }
         } catch {
-          // Broken symlink — fall through to remove and recreate.
+          // Can't read installed file — refresh below.
         }
-        // Stale or broken symlink — remove and recreate.
-        rmSync(installedDir, { force: true });
-      } else if (existingIsDir) {
-        // Legacy directory install (file-copy era) — migrate by removing.
+        // Stale copy — remove and recopy.
         rmSync(installedDir, { recursive: true, force: true });
+      } else if (existingIsSymlink) {
+        // Legacy symlink (pre-copy era) — remove and replace with copy.
+        rmSync(installedDir, { force: true });
       } else {
         // Unexpected file — remove.
         rmSync(installedDir, { force: true });
       }
     }
 
-    const symlinkTarget: string = toRelativeSymlinkTarget(installedDir, resolvedSourceDir);
-    symlinkSync(symlinkTarget, installedDir, "dir");
+    cpSync(resolvedSourceDir, installedDir, { recursive: true });
   } catch (error: unknown) {
     const message = error instanceof Error ? error.message : "Unknown skills install failure";
     return failResult({
@@ -784,6 +782,93 @@ function probeAndRepairIfInstalled(linkPath: string, expectedTarget: string): Re
   return repairSymlink(probe);
 }
 
+/** Probe and repair local anchor using directory copy instead of symlinks. */
+function probeAndRepairLocalAnchor(installedDir: string, sourceDir: string): RepairResult {
+  const resolvedExpected: string = resolve(sourceDir);
+  const sourcePath: string = join(sourceDir, "SKILL.md");
+  const installedPath: string = join(installedDir, "SKILL.md");
+
+  // Self-reference guard: source and install are the same path (dev mode).
+  if (resolve(installedDir) === resolvedExpected) {
+    return {
+      probe: { path: installedDir, expectedTarget: resolvedExpected, status: "ok", currentTarget: resolvedExpected },
+      action: "ok",
+    };
+  }
+
+  let existingIsSymlink = false;
+  let existingIsDir = false;
+  let pathOccupied = false;
+
+  try {
+    const stat = lstatSync(installedDir);
+    pathOccupied = true;
+    existingIsSymlink = stat.isSymbolicLink();
+    existingIsDir = stat.isDirectory();
+  } catch {
+    // Not installed.
+  }
+
+  if (!pathOccupied) {
+    return {
+      probe: { path: installedDir, expectedTarget: resolvedExpected, status: "not_installed", currentTarget: null },
+      action: "skipped",
+    };
+  }
+
+  if (existingIsSymlink) {
+    // Legacy symlink — migrate to directory copy.
+    let currentTarget: string | null = null;
+    try {
+      const rawTarget = readlinkSync(installedDir);
+      currentTarget = resolve(dirname(installedDir), rawTarget);
+    } catch {
+      // Broken symlink.
+    }
+    rmSync(installedDir, { force: true });
+    mkdirSync(dirname(installedDir), { recursive: true });
+    cpSync(resolvedExpected, installedDir, { recursive: true });
+    return {
+      probe: { path: installedDir, expectedTarget: resolvedExpected, status: "legacy", currentTarget },
+      action: "migrated",
+    };
+  }
+
+  if (existingIsDir) {
+    // Real directory — check if contents match.
+    try {
+      const sourceContents = readFileSync(sourcePath, "utf8");
+      const installedContents = readFileSync(installedPath, "utf8");
+      if (sourceContents === installedContents) {
+        return {
+          probe: { path: installedDir, expectedTarget: resolvedExpected, status: "ok", currentTarget: null },
+          action: "ok",
+        };
+      }
+    } catch {
+      // Can't read — treat as stale.
+    }
+
+    // Stale copy — refresh.
+    rmSync(installedDir, { recursive: true, force: true });
+    mkdirSync(dirname(installedDir), { recursive: true });
+    cpSync(resolvedExpected, installedDir, { recursive: true });
+    return {
+      probe: { path: installedDir, expectedTarget: resolvedExpected, status: "stale", currentTarget: null },
+      action: "repointed",
+    };
+  }
+
+  // Unexpected file type — remove and copy.
+  rmSync(installedDir, { force: true });
+  mkdirSync(dirname(installedDir), { recursive: true });
+  cpSync(resolvedExpected, installedDir, { recursive: true });
+  return {
+    probe: { path: installedDir, expectedTarget: resolvedExpected, status: "legacy", currentTarget: null },
+    action: "migrated",
+  };
+}
+
 type UpdateScope = "global" | "local";
 
 interface UpdateEntry {
@@ -847,9 +932,9 @@ function runSkillsUpdate(context: CliContext): CliResult {
       entries.push({ scope: "global", label: editor, repair: probeAndRepairIfInstalled(linkPath, globalAnchorPath) });
     }
 
-    // Local anchor: <cwd>/.agents/skills/trekoon → bundled package dir.
+    // Local anchor: <cwd>/.agents/skills/trekoon — directory copy of bundled source.
     const localAnchorPath: string = join(context.cwd, ".agents", "skills", "trekoon");
-    entries.push({ scope: "local", label: "anchor", repair: probeAndRepairIfInstalled(localAnchorPath, sourceDir) });
+    entries.push({ scope: "local", label: "anchor", repair: probeAndRepairLocalAnchor(localAnchorPath, sourceDir) });
 
     // Local editor links: <cwd>/.<editor>/skills/trekoon → local anchor.
     for (const editor of EDITOR_NAMES) {

package/src/commands/sync.ts

@@ -1,4 +1,6 @@
-import { findUnknownOption, parseArgs, readMissingOptionValue, readOption, suggestOptions } from "./arg-parser";
+import { createInterface } from "node:readline";
+
+import { findUnknownOption, hasFlag, parseArgs, readMissingOptionValue, readOption, suggestOptions } from "./arg-parser";
 import { safeErrorMessage, sqliteBusyFailure } from "./error-utils";
 
 import { DomainError } from "../domain/types";
@@ -6,12 +8,12 @@ import { failResult, okResult } from "../io/output";
 import { type CliContext, type CliResult } from "../runtime/command-types";
 import { resolveStorageResolutionDiagnostics } from "../storage/database";
 import { assertValidSourceRef } from "../sync/branch-db";
-import { getSyncConflict, listSyncConflicts, syncPull, syncResolve, syncStatus } from "../sync/service";
-import { type SyncResolution } from "../sync/types";
+import { getSyncConflict, listSyncConflicts, syncPull, syncResolve, syncResolvePreview, syncStatus } from "../sync/service";
+import { type ResolvePreviewSummary, type SyncResolution } from "../sync/types";
 
 const STATUS_OPTIONS = ["from"] as const;
 const PULL_OPTIONS = ["from"] as const;
-const RESOLVE_OPTIONS = ["use"] as const;
+const RESOLVE_OPTIONS = ["use", "dry-run"] as const;
 const CONFLICTS_LIST_OPTIONS = ["mode"] as const;
 const CONFLICTS_SHOW_OPTIONS: readonly string[] = [];
 
@@ -121,6 +123,36 @@ function isStorageBootstrapError(code: string): boolean {
   return code === "tracked_ignored_mismatch" || code === "ambiguous_legacy_state" || code === "legacy_import_failed";
 }
 
+function formatTheirsConfirmation(preview: ResolvePreviewSummary): string {
+  return [
+    `Resolve conflict ${preview.conflictId} using theirs?`,
+    `  Field: ${preview.fieldName}`,
+    `  Current (ours): ${JSON.stringify(preview.oursValue)}`,
+    `  Incoming (theirs): ${JSON.stringify(preview.theirsValue)}`,
+    "Confirm? [y/N] ",
+  ].join("\n");
+}
+
+function promptConfirmation(message: string, timeoutMs: number = 30_000): Promise<boolean> {
+  return new Promise<boolean>((resolve): void => {
+    let settled = false;
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    const timer = setTimeout((): void => {
+      if (settled) return;
+      settled = true;
+      rl.close();
+      resolve(false);
+    }, timeoutMs);
+    rl.question(message, (answer: string): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      rl.close();
+      resolve(answer.trim().toLowerCase() === "y");
+    });
+  });
+}
+
 export async function runSync(context: CliContext): Promise<CliResult> {
   const parsed = parseArgs(context.args);
   const subcommand: string | undefined = parsed.positional[0];
@@ -221,7 +253,63 @@ export async function runSync(context: CliContext): Promise<CliResult> {
         return usage("sync resolve --use only accepts ours|theirs.", "sync.resolve");
       }
 
-      const summary = syncResolve(context.cwd, conflictId, rawResolution as SyncResolution);
+      const resolution: SyncResolution = rawResolution;
+      const dryRun: boolean = hasFlag(parsed.flags, "dry-run");
+
+      if (dryRun) {
+        const preview = syncResolvePreview(context.cwd, conflictId, resolution);
+
+        return okResult({
+          command: "sync.resolve",
+          human: [
+            `[dry-run] Would resolve ${preview.conflictId} using ${preview.resolution}.`,
+            `Entity: ${preview.entityKind} ${preview.entityId}`,
+            `Field: ${preview.fieldName}`,
+            `Ours: ${JSON.stringify(preview.oursValue)}`,
+            `Theirs: ${JSON.stringify(preview.theirsValue)}`,
+            preview.resolution === "theirs"
+              ? `Would write: ${JSON.stringify(preview.wouldWrite)}`
+              : `Field stays: ${JSON.stringify(preview.wouldWrite)} (no entity write)`,
+          ].join("\n"),
+          data: preview,
+        });
+      }
+
+      if (resolution === "theirs" && context.mode !== "toon") {
+        const preview = syncResolvePreview(context.cwd, conflictId, resolution);
+        const confirmed = await promptConfirmation(formatTheirsConfirmation(preview));
+
+        if (!confirmed) {
+          return failResult({
+            command: "sync.resolve",
+            human: "Resolution cancelled by user.",
+            data: {
+              conflictId,
+              resolution,
+              cancelled: true,
+            },
+            error: {
+              code: "cancelled",
+              message: "Resolution cancelled by user.",
+            },
+          });
+        }
+      }
+
+      let summary;
+      try {
+        summary = syncResolve(context.cwd, conflictId, resolution);
+      } catch (resolveError: unknown) {
+        if (resolveError instanceof Error && resolveError.message.includes("already resolved")) {
+          return failResult({
+            command: "sync.resolve",
+            human: `Conflict '${conflictId}' was resolved by another process while waiting for confirmation.`,
+            data: { conflictId, resolution, reason: "already_resolved" },
+            error: { code: "already_resolved", message: resolveError.message },
+          });
+        }
+        throw resolveError;
+      }
 
       return okResult({
         command: "sync.resolve",