trekoon 0.1.7 → 0.1.9

package/src/commands/epic.ts

@@ -1,4 +1,12 @@
-import { hasFlag, parseArgs, parseStrictPositiveInt, readEnumOption, readMissingOptionValue, readOption } from "./arg-parser";
+import {
+  hasFlag,
+  parseArgs,
+  parseStrictNonNegativeInt,
+  parseStrictPositiveInt,
+  readEnumOption,
+  readMissingOptionValue,
+  readOption,
+} from "./arg-parser";
 
 import { MutationService } from "../domain/mutation-service";
 import { TrackerDomain } from "../domain/tracker-domain";
@@ -41,21 +49,58 @@ function getStatusPriority(status: string): number {
 }
 
 function sortByStatusPriority(epics: readonly EpicRecord[]): EpicRecord[] {
-  return [...epics].sort((left, right) => getStatusPriority(left.status) - getStatusPriority(right.status));
+  return [...epics].sort((left, right) => {
+    const byStatus = getStatusPriority(left.status) - getStatusPriority(right.status);
+    if (byStatus !== 0) {
+      return byStatus;
+    }
+
+    const byCreatedAt = left.createdAt - right.createdAt;
+    if (byCreatedAt !== 0) {
+      return byCreatedAt;
+    }
+
+    return left.id.localeCompare(right.id);
+  });
 }
 
-function filterSortAndLimitEpics(epics: readonly EpicRecord[], options: { includeAll: boolean; statuses: readonly string[] | undefined; limit: number | undefined }): EpicRecord[] {
-  const { includeAll, statuses, limit } = options;
+interface PaginationMeta {
+  readonly hasMore: boolean;
+  readonly nextCursor: string | null;
+}
+
+function filterSortAndLimitEpics(epics: readonly EpicRecord[], options: {
+  includeAll: boolean;
+  statuses: readonly string[] | undefined;
+  limit: number | undefined;
+  cursor: number;
+}): { epics: EpicRecord[]; pagination: PaginationMeta } {
+  const { includeAll, statuses, limit, cursor } = options;
   const selectedStatuses = includeAll ? undefined : (statuses ?? DEFAULT_OPEN_STATUSES);
   const selectedEpics = selectedStatuses === undefined ? [...epics] : epics.filter((epic) => selectedStatuses.includes(epic.status));
   const sortedEpics = sortByStatusPriority(selectedEpics);
 
   if (includeAll) {
-    return sortedEpics;
+    return {
+      epics: sortedEpics,
+      pagination: {
+        hasMore: false,
+        nextCursor: null,
+      },
+    };
   }
 
   const effectiveLimit = limit ?? DEFAULT_LIST_LIMIT;
-  return sortedEpics.slice(0, effectiveLimit);
+  const pagedEpics = sortedEpics.slice(cursor, cursor + effectiveLimit);
+  const nextIndex = cursor + pagedEpics.length;
+  const hasMore = nextIndex < sortedEpics.length;
+  return {
+    epics: pagedEpics,
+    pagination: {
+      hasMore,
+      nextCursor: hasMore ? `${nextIndex}` : null,
+    },
+  };
 }
 
 function invalidEpicListInput(human: string, message: string, data: Record<string, unknown>): CliResult {
@@ -266,6 +311,7 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
         const missingListOption =
           readMissingOptionValue(parsed.missingOptionValues, "status", "s") ??
           readMissingOptionValue(parsed.missingOptionValues, "limit", "l") ??
+          readMissingOptionValue(parsed.missingOptionValues, "cursor") ??
           readMissingOptionValue(parsed.missingOptionValues, "view");
         if (missingListOption !== undefined) {
           return failMissingOptionValue("epic.list", missingListOption);
@@ -274,6 +320,7 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
         const includeAll: boolean = hasFlag(parsed.flags, "all");
         const rawStatuses: string | undefined = readOption(parsed.options, "status");
         const rawLimit: string | undefined = readOption(parsed.options, "limit");
+        const rawCursor: string | undefined = readOption(parsed.options, "cursor");
         const rawView: string | undefined = readOption(parsed.options, "view");
         const view = readEnumOption(parsed.options, VIEW_MODES, "view");
         if (rawView !== undefined && view === undefined) {
@@ -320,11 +367,28 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
           });
         }
 
-        const epics = filterSortAndLimitEpics(domain.listEpics(), {
+        const cursor = parseStrictNonNegativeInt(rawCursor) ?? 0;
+        if (Number.isNaN(cursor)) {
+          return invalidEpicListInput("Invalid --cursor value. Use an integer >= 0.", "Invalid --cursor value", {
+            code: "invalid_input",
+            cursor: rawCursor,
+          });
+        }
+
+        if (includeAll && rawCursor !== undefined) {
+          return invalidEpicListInput("Use either --all or --cursor, not both.", "--all and --cursor are mutually exclusive", {
+            code: "invalid_input",
+            flags: ["all", "cursor"],
+          });
+        }
+
+        const listed = filterSortAndLimitEpics(domain.listEpics(), {
           includeAll,
           statuses,
           limit,
+          cursor,
         });
+        const epics = listed.epics;
         const listView = view ?? "table";
         const human = epics.length === 0 ? "No epics found." : listView === "compact" ? epics.map(formatEpic).join("\n") : formatEpicListTable(epics);
 
@@ -332,6 +396,28 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
           command: "epic.list",
           human,
           data: { epics },
+          ...(context.mode === "human"
+            ? {}
+            : {
+                meta: {
+                  pagination: listed.pagination,
+                  defaults: {
+                    statuses: !includeAll && statuses === undefined ? [...DEFAULT_OPEN_STATUSES] : null,
+                    limit: !includeAll && limit === undefined ? DEFAULT_LIST_LIMIT : null,
+                    cursor: rawCursor === undefined ? 0 : null,
+                    view: view === undefined ? "table" : null,
+                  },
+                  filters: {
+                    statuses: includeAll ? null : (statuses ?? [...DEFAULT_OPEN_STATUSES]),
+                    includeAll,
+                  },
+                  truncation: {
+                    applied: listed.pagination.hasMore,
+                    returned: epics.length,
+                    limit: includeAll ? null : (limit ?? DEFAULT_LIST_LIMIT),
+                  },
+                },
+              }),
         });
       }
       case "show": {
@@ -365,6 +451,22 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
             command: "epic.show",
             human: formatEpic(epic),
             data: { epic, includeAll: false },
+            ...(context.mode === "human"
+              ? {}
+              : {
+                  meta: {
+                    defaults: {
+                      view: view === undefined ? effectiveView : null,
+                    },
+                    filters: {
+                      includeAll: false,
+                    },
+                    truncation: {
+                      applied: true,
+                      scope: "compact",
+                    },
+                  },
+                }),
           });
         }
 
@@ -375,6 +477,22 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
             command: "epic.show",
             human: formatEpicShowCompact(tree),
             data: { tree, includeAll: false },
+            ...(context.mode === "human"
+              ? {}
+              : {
+                  meta: {
+                    defaults: {
+                      view: view === undefined ? effectiveView : null,
+                    },
+                    filters: {
+                      includeAll: false,
+                    },
+                    truncation: {
+                      applied: true,
+                      scope: "tree",
+                    },
+                  },
+                }),
           });
         }
 
@@ -384,6 +502,22 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
           command: "epic.show",
           human: effectiveView === "table" ? formatEpicShowTable(tree) : formatEpicShowDetailed(tree),
           data: { tree, includeAll: true },
+          ...(context.mode === "human"
+            ? {}
+            : {
+                meta: {
+                  defaults: {
+                    view: view === undefined ? effectiveView : null,
+                  },
+                  filters: {
+                    includeAll: true,
+                  },
+                  truncation: {
+                    applied: false,
+                    scope: "full",
+                  },
+                },
+              }),
         });
       }
       case "update": {

package/src/commands/help.ts

@@ -1,8 +1,10 @@
 import { okResult } from "../io/output";
 import { type CliContext, type CliResult } from "../runtime/command-types";
+import { CLI_VERSION } from "../runtime/version";
 
 const ROOT_HELP = [
   "Trekoon - AI-first local issue tracker",
+  `Version: ${CLI_VERSION}`,
   "",
   "Usage:",
   "  trekoon [global-options] <command> [command-options]",
@@ -10,12 +12,14 @@ const ROOT_HELP = [
   "Global options:",
   "  --json       Emit stable JSON machine output",
   "  --toon       Emit true TOON-encoded output",
+  "  --compat <mode>  Enable explicit machine compatibility mode",
   "  --help       Show root or command help",
   "  --version    Print CLI version",
   "",
   "Commands:",
+  "  help         Show root or command help",
   "  init         Initialize .trekoon storage and local DB",
-  "  quickstart   Show workflow + where to see task descriptions",
+  "  quickstart   Show AI execution loop + task detail workflow",
   "  wipe         Remove local Trekoon state (requires --yes)",
   "  epic         Epic lifecycle commands",
   "  task         Task lifecycle commands",
@@ -24,25 +28,269 @@ const ROOT_HELP = [
   "  events       Event retention and cleanup commands",
   "  migrate      Migration status and rollback commands",
   "  sync         Cross-branch sync commands",
-  "  skills       Project-local skill install/link commands",
+  "  skills       Project-local skill install/update/link",
+].join("\n");
+
+const INIT_HELP = [
+  "Usage: trekoon init [--json|--toon]",
+  "",
+  "Purpose:",
+  "  Initialize local Trekoon storage (.trekoon) and database.",
+  "",
+  "Examples:",
+  "  trekoon init",
+  "  trekoon --json init",
+].join("\n");
+
+const QUICKSTART_HELP = [
+  "Usage: trekoon quickstart [--json|--toon]",
+  "",
+  "Purpose:",
+  "  Show the canonical Trekoon AI execution loop and task-detail workflow.",
+  "",
+  "Flow:",
+  "  1) trekoon --toon sync status",
+  "  2) trekoon --toon task ready --limit 5",
+  "  3) trekoon --toon task next",
+  "  4) trekoon --toon dep reverse <task-or-subtask-id>",
+  "  5) trekoon --toon task update <task-id> --status in_progress",
+  "",
+  "Examples:",
+  "  trekoon quickstart",
+  "  trekoon --toon quickstart",
+].join("\n");
+
+const WIPE_HELP = [
+  "Usage: trekoon wipe --yes [--json|--toon]",
+  "",
+  "Purpose:",
+  "  Remove local Trekoon state for the current repository.",
+  "",
+  "Options:",
+  "  --yes  Required safety confirmation.",
+  "",
+  "Examples:",
+  "  trekoon wipe --yes",
+].join("\n");
+
+const EPIC_HELP = [
+  "Usage: trekoon epic <create|list|show|update|delete> [options]",
+  "",
+  "List behavior:",
+  "  Defaults:",
+  "    - Open statuses only: in_progress, in-progress, todo",
+  "    - Limit: 10",
+  "  Flags:",
+  "    --status <csv> | --limit <n> | --cursor <n> | --all | --view table|compact",
+  "  Pagination:",
+  "    - --cursor is offset-like",
+  "    - Machine modes expose meta.pagination.hasMore / nextCursor",
+  "  Constraints:",
+  "    - --all is mutually exclusive with --status, --limit, and --cursor",
+  "",
+  "Show behavior:",
+  "  Views:",
+  "    - table: default view",
+  "    - compact: epic summary",
+  "    - tree: hierarchy",
+  "    - detail: descriptions",
+  "  Machine default:",
+  "    - With --all, machine modes default to detail",
+  "",
+  "Update behavior:",
+  "  Bulk target flags:",
+  "    --all | --ids <csv>",
+  "  Bulk fields:",
+  "    --append <text> and/or --status <status>",
+].join("\n");
+
+const TASK_HELP = [
+  "Usage: trekoon task <create|list|show|ready|next|update|delete> [options]",
+  "",
+  "List behavior:",
+  "  Defaults:",
+  "    - Open statuses only: in_progress, in-progress, todo",
+  "    - Limit: 10",
+  "  Flags:",
+  "    --epic <id> | --status <csv> | --limit <n> | --cursor <n> | --all | --view table|compact",
+  "  Pagination:",
+  "    - --cursor is offset-like",
+  "    - Machine modes expose meta.pagination.hasMore / nextCursor",
+  "  Constraints:",
+  "    - --all is mutually exclusive with --status, --limit, and --cursor",
+  "",
+  "Show behavior:",
+  "  Views:",
+  "    - table: default view",
+  "    - compact: task summary",
+  "    - tree: hierarchy",
+  "    - detail: descriptions",
+  "  Machine default:",
+  "    - With --all, machine modes default to detail",
+  "",
+  "Ready/Next behavior:",
+  "  ready:",
+  "    - Returns deterministic unblocked candidates",
+  "    - Sort order: status, blockers, createdAt, id",
+  "    - Options: --limit <n>, --epic <id>",
+  "  next:",
+  "    - Returns top ready candidate",
+  "    - Option: --epic <id>",
+  "",
+  "Update behavior:",
+  "  Bulk target flags:",
+  "    --all | --ids <csv>",
+  "  Bulk fields:",
+  "    --append <text> and/or --status <status>",
+].join("\n");
+
+const SUBTASK_HELP = [
+  "Usage: trekoon subtask <create|list|update|delete> [options]",
+  "",
+  "List behavior:",
+  "  Defaults:",
+  "    - Open statuses only: in_progress, in-progress, todo",
+  "    - Limit: 10",
+  "  Flags:",
+  "    --task <id> | --status <csv> | --limit <n> | --cursor <n> | --all | --view table|compact",
+  "  Pagination:",
+  "    - --cursor is offset-like",
+  "    - Machine modes expose meta.pagination.hasMore / nextCursor",
+  "  Constraints:",
+  "    - --all is mutually exclusive with --status, --limit, and --cursor",
+  "",
+  "Update behavior:",
+  "  Bulk target flags:",
+  "    --all | --ids <csv>",
+  "  Bulk fields:",
+  "    --append <text> and/or --status <status>",
+].join("\n");
+
+const DEP_HELP = [
+  "Usage: trekoon dep <add|remove|list|reverse> [options]",
+  "",
+  "Subcommands:",
+  "  add <source-id> <depends-on-id>",
+  "      Create dependency edge: source depends on depends-on.",
+  "  remove <source-id> <depends-on-id>",
+  "      Remove one dependency edge if it exists.",
+  "  list <source-id>",
+  "      Show direct dependencies for a node.",
+  "  reverse <target-id>",
+  "      Show downstream nodes blocked by target (with distance).",
+  "",
+  "Examples:",
+  "  trekoon dep add <task-a> <task-b>",
+  "  trekoon dep remove <task-a> <task-b>",
+  "  trekoon dep list <task-a>",
+  "  trekoon dep reverse <task-b>",
+].join("\n");
+
+const EVENTS_HELP = [
+  "Usage: trekoon events prune [--dry-run] [--archive] [--retention-days <n>]",
+  "",
+  "Purpose:",
+  "  Manage retention for internal sync event log rows.",
+  "",
+  "Options:",
+  "  --dry-run             Preview candidate/archive/delete counts only.",
+  "  --archive             Copy pruned rows to event_archive before delete.",
+  "  --retention-days <n>  Keep last n days (positive integer, default 90).",
+  "",
+  "Examples:",
+  "  trekoon events prune --dry-run",
+  "  trekoon events prune --retention-days 30",
+  "  trekoon events prune --archive",
+].join("\n");
+
+const MIGRATE_HELP = [
+  "Usage: trekoon migrate <status|rollback> [--to-version <n>]",
+  "",
+  "Subcommands:",
+  "  status",
+  "      Show current schema version, latest version, and pending count.",
+  "  rollback [--to-version <n>]",
+  "      Roll back migrations; default target is one version back.",
+  "",
+  "Examples:",
+  "  trekoon migrate status",
+  "  trekoon migrate rollback",
+  "  trekoon migrate rollback --to-version 1",
+].join("\n");
+
+const SYNC_HELP = [
+  "Usage: trekoon sync <status|pull|resolve|conflicts> [options]",
+  "",
+  "Subcommands:",
+  "  status [--from <branch>]",
+  "      Show ahead/behind counts and pending conflicts vs source branch (default: main).",
+  "  pull --from <branch>",
+  "      Pull and apply upstream tracker events from a source branch.",
+  "  conflicts list [--mode pending|all]",
+  "      List sync conflicts (default mode: pending).",
+  "  conflicts show <conflict-id>",
+  "      Show full details for one conflict.",
+  "  resolve <conflict-id> --use ours|theirs",
+  "      Resolve a pending conflict by selecting ours or theirs.",
+  "",
+  "Compatibility mode:",
+  "  --compat legacy-sync-command-ids",
+  "      Emits legacy sync command IDs (sync_status, sync_pull, ...)",
+  "      in machine output only and includes deprecation metadata.",
+  "      Migration: remove --compat and consume dotted IDs (sync.status).",
+  "      Planned compatibility window closes after 2026-09-30.",
+  "",
+  "Examples:",
+  "  trekoon sync status",
+  "  trekoon sync status --from main",
+  "  trekoon sync pull --from main",
+  "  trekoon sync conflicts list",
+  "  trekoon sync conflicts list --mode all",
+  "  trekoon sync conflicts show <conflict-id>",
+  "  trekoon sync resolve <conflict-id> --use ours",
+].join("\n");
+
+const SKILLS_HELP = [
+  "Usage:",
+  "  trekoon skills install [--link --editor opencode|claude|pi] [--to <path>] [--allow-outside-repo]",
+  "  trekoon skills update",
+  "",
+  "Purpose:",
+  "  Install or refresh the project-local Trekoon skill asset.",
+  "",
+  "Install behavior:",
+  "  - Always installs canonical file to:",
+  "      <cwd>/.agents/skills/trekoon/SKILL.md",
+  "  - Use --link to also create an editor symlink named 'trekoon'.",
+  "  - --editor is required when --link is used (opencode|claude|pi).",
+  "  - --to overrides the symlink root for --link only.",
+  "  - Without --allow-outside-repo, link targets must resolve inside repo.",
+  "  - --allow-outside-repo requires --link and disables that boundary check.",
+  "",
+  "Update behavior:",
+  "  - Refreshes canonical SKILL file in the install path above.",
+  "  - Reports default link states for opencode/claude/pi.",
+  "",
+  "Examples:",
+  "  trekoon skills install",
+  "  trekoon skills install --link --editor opencode",
+  "  trekoon skills install --link --editor claude --to .claude/skills",
+  "  trekoon skills install --link --editor pi --to ../shared/skills --allow-outside-repo",
+  "  trekoon skills update",
 ].join("\n");
 
 const COMMAND_HELP: Record<string, string> = {
-  init: "Usage: trekoon init [--json|--toon]",
-  quickstart: "Usage: trekoon quickstart [--json|--toon]",
-  wipe: "Usage: trekoon wipe --yes [--json|--toon]",
-  epic:
-    "Usage: trekoon epic <subcommand> [options] (list defaults: open statuses + limit 10; list flags: --status <csv> | --limit <n> | --all | --view table|compact; show: compact=epic summary, tree=hierarchy, detail=descriptions, and --all defaults to detail in machine modes; update bulk flags: --all | --ids <csv> with --append <text> and/or --status <status>)",
-  task:
-    "Usage: trekoon task <subcommand> [options] (list defaults: open statuses + limit 10; list flags: --status <csv> | --limit <n> | --all | --view table|compact; show: compact=task summary, tree=hierarchy, detail=descriptions, and --all defaults to detail in machine modes; update bulk flags: --all | --ids <csv> with --append <text> and/or --status <status>)",
-  subtask:
-    "Usage: trekoon subtask <subcommand> [options] (list defaults: open statuses + limit 10; list flags: --task <id> | --status <csv> | --limit <n> | --all | --view table|compact; update bulk flags: --all | --ids <csv> with --append <text> and/or --status <status>)",
-  dep: "Usage: trekoon dep <subcommand> [options]",
-  events: "Usage: trekoon events prune [--dry-run] [--archive] [--retention-days <n>]",
-  migrate: "Usage: trekoon migrate <status|rollback> [--to-version <n>]",
-  sync: "Usage: trekoon sync <subcommand> [options]",
-  skills:
-    "Usage: trekoon skills install [--link --editor opencode|claude|pi] [--to <path>] [--allow-outside-repo] | trekoon skills update (--to sets symlink root for --link only; install path always <cwd>/.agents/skills/trekoon/SKILL.md; links must resolve inside repo unless --allow-outside-repo is set; update refreshes canonical SKILL and reports default link states)",
+  init: INIT_HELP,
+  quickstart: QUICKSTART_HELP,
+  wipe: WIPE_HELP,
+  epic: EPIC_HELP,
+  task: TASK_HELP,
+  subtask: SUBTASK_HELP,
+  dep: DEP_HELP,
+  events: EVENTS_HELP,
+  migrate: MIGRATE_HELP,
+  sync: SYNC_HELP,
+  skills: SKILLS_HELP,
   help: "Usage: trekoon help [command] [--json|--toon]",
 };
 
@@ -64,6 +312,7 @@ export async function runHelp(context: CliContext): Promise<CliResult> {
     data: {
       topic,
       text,
+      version: CLI_VERSION,
     },
   });
 }