trekoon 0.1.8 → 0.1.9

package/src/commands/sync.ts

@@ -1,22 +1,48 @@
+import { findUnknownOption, parseArgs, readMissingOptionValue, readOption, suggestOptions } from "./arg-parser";
+
 import { failResult, okResult } from "../io/output";
 import { type CliContext, type CliResult } from "../runtime/command-types";
 import { MissingBranchDatabaseError } from "../sync/branch-db";
 import { getSyncConflict, listSyncConflicts, syncPull, syncResolve, syncStatus } from "../sync/service";
-import { type SyncConflictMode, type SyncResolution } from "../sync/types";
+import { type SyncResolution } from "../sync/types";
+
+const STATUS_OPTIONS = ["from"] as const;
+const PULL_OPTIONS = ["from"] as const;
+const RESOLVE_OPTIONS = ["use"] as const;
+const CONFLICTS_LIST_OPTIONS = ["mode"] as const;
+const CONFLICTS_SHOW_OPTIONS: readonly string[] = [];
+
+function resolveSyncCommandId(subcommand: string | undefined, conflictsSubcommand: string | undefined): string {
+  if (subcommand === "status") {
+    return "sync.status";
+  }
+
+  if (subcommand === "pull") {
+    return "sync.pull";
+  }
+
+  if (subcommand === "resolve") {
+    return "sync.resolve";
+  }
+
+  if (subcommand !== "conflicts") {
+    return "sync";
+  }
+
+  if (conflictsSubcommand === "list") {
+    return "sync.conflicts.list";
+  }
 
-function parseOption(args: readonly string[], option: string): string | null {
-  const index: number = args.indexOf(option);
-  if (index < 0) {
-    return null;
+  if (conflictsSubcommand === "show") {
+    return "sync.conflicts.show";
   }
 
-  const value: string | undefined = args[index + 1];
-  return value && !value.startsWith("--") ? value : null;
+  return "sync.conflicts";
 }
 
-function usage(message: string): CliResult {
+function usage(message: string, command = "sync"): CliResult {
   return failResult({
-    command: "sync",
+    command,
     human: `${message}\nUsage: trekoon sync <status|pull|resolve|conflicts> [options]`,
     data: { message },
     error: {
@@ -26,6 +52,28 @@ function usage(message: string): CliResult {
   });
 }
 
+function prefixedOptions(options: readonly string[]): string[] {
+  return options.map((option) => `--${option}`);
+}
+
+function unknownOption(command: string, option: string, allowedOptions: readonly string[]): CliResult {
+  const suggestions = suggestOptions(option, allowedOptions).map((suggestion) => `--${suggestion}`);
+  const suggestionMessage = suggestions.length > 0 ? ` Did you mean ${suggestions.join(" or ")}?` : "";
+  return failResult({
+    command,
+    human: `Unknown option --${option}.${suggestionMessage}`,
+    data: {
+      option: `--${option}`,
+      allowedOptions: prefixedOptions(allowedOptions),
+      suggestions,
+    },
+    error: {
+      code: "unknown_option",
+      message: `Unknown option --${option}`,
+    },
+  });
+}
+
 function statusMessage(sourceBranch: string, ahead: number, behind: number, conflicts: number): string {
   return [
     `Sync status against '${sourceBranch}'`,
@@ -61,26 +109,11 @@ function formatConflictList(
     .join("\n");
 }
 
-function parseConflictMode(args: readonly string[]): SyncConflictMode | null {
-  const modeIndex = args.indexOf("--mode");
-  if (modeIndex < 0) {
-    return "pending";
-  }
-
-  const explicitMode = args[modeIndex + 1];
-  if (!explicitMode || explicitMode.startsWith("--")) {
-    return null;
-  }
-
-  if (explicitMode === "pending" || explicitMode === "all") {
-    return explicitMode;
-  }
-
-  return null;
-}
-
 export async function runSync(context: CliContext): Promise<CliResult> {
-  const subcommand: string | undefined = context.args[0];
+  const parsed = parseArgs(context.args);
+  const subcommand: string | undefined = parsed.positional[0];
+  const conflictsSubcommand: string | undefined = subcommand === "conflicts" ? parsed.positional[1] : undefined;
+  const resolvedCommand: string = resolveSyncCommandId(subcommand, conflictsSubcommand);
 
   if (!subcommand) {
     return usage("Missing sync subcommand.");
@@ -88,26 +121,46 @@ export async function runSync(context: CliContext): Promise<CliResult> {
 
   try {
     if (subcommand === "status") {
-      const sourceBranch: string = parseOption(context.args, "--from") ?? "main";
+      const statusUnknownOption = findUnknownOption(parsed, STATUS_OPTIONS);
+      if (statusUnknownOption !== undefined) {
+        return unknownOption("sync.status", statusUnknownOption, STATUS_OPTIONS);
+      }
+
+      const missingFromOption = readMissingOptionValue(parsed.missingOptionValues, "from");
+      if (missingFromOption !== undefined) {
+        return usage("sync status requires --from <branch> when provided.", "sync.status");
+      }
+
+      const sourceBranch: string = readOption(parsed.options, "from") ?? "main";
       const summary = syncStatus(context.cwd, sourceBranch);
 
       return okResult({
-        command: "sync status",
+        command: "sync.status",
         human: statusMessage(summary.sourceBranch, summary.ahead, summary.behind, summary.pendingConflicts),
         data: summary,
       });
     }
 
     if (subcommand === "pull") {
-      const sourceBranch: string | null = parseOption(context.args, "--from");
-      if (!sourceBranch) {
-        return usage("sync pull requires --from <branch>.");
+      const pullUnknownOption = findUnknownOption(parsed, PULL_OPTIONS);
+      if (pullUnknownOption !== undefined) {
+        return unknownOption("sync.pull", pullUnknownOption, PULL_OPTIONS);
+      }
+
+      const missingFromOption = readMissingOptionValue(parsed.missingOptionValues, "from");
+      if (missingFromOption !== undefined) {
+        return usage("sync pull requires --from <branch>.", "sync.pull");
+      }
+
+      const sourceBranch: string | undefined = readOption(parsed.options, "from");
+      if (sourceBranch === undefined) {
+        return usage("sync pull requires --from <branch>.", "sync.pull");
       }
 
       const summary = syncPull(context.cwd, sourceBranch);
 
       return okResult({
-        command: "sync pull",
+        command: "sync.pull",
         human: [
           `Pulled from '${summary.sourceBranch}'`,
           `Scanned events: ${summary.scannedEvents}`,
@@ -123,42 +176,62 @@ export async function runSync(context: CliContext): Promise<CliResult> {
     }
 
     if (subcommand === "resolve") {
-      const conflictId: string | undefined = context.args[1];
-      const rawResolution: string | null = parseOption(context.args, "--use");
+      const resolveUnknownOption = findUnknownOption(parsed, RESOLVE_OPTIONS);
+      if (resolveUnknownOption !== undefined) {
+        return unknownOption("sync.resolve", resolveUnknownOption, RESOLVE_OPTIONS);
+      }
+
+      const conflictId: string | undefined = parsed.positional[1];
+      const missingResolutionOption = readMissingOptionValue(parsed.missingOptionValues, "use");
+      if (missingResolutionOption !== undefined) {
+        return usage("sync resolve requires <conflict-id> --use ours|theirs.", "sync.resolve");
+      }
+
+      const rawResolution: string | undefined = readOption(parsed.options, "use");
 
       if (!conflictId || !rawResolution) {
-        return usage("sync resolve requires <conflict-id> --use ours|theirs.");
+        return usage("sync resolve requires <conflict-id> --use ours|theirs.", "sync.resolve");
       }
 
       if (rawResolution !== "ours" && rawResolution !== "theirs") {
-        return usage("sync resolve --use only accepts ours|theirs.");
+        return usage("sync resolve --use only accepts ours|theirs.", "sync.resolve");
       }
 
       const summary = syncResolve(context.cwd, conflictId, rawResolution as SyncResolution);
 
       return okResult({
-        command: "sync resolve",
+        command: "sync.resolve",
         human: `Resolved ${summary.conflictId} using ${summary.resolution}.`,
         data: summary,
       });
     }
 
     if (subcommand === "conflicts") {
-      const conflictsCommand: string | undefined = context.args[1];
+      const conflictsCommand: string | undefined = parsed.positional[1];
       if (!conflictsCommand) {
-        return usage("sync conflicts requires list|show.");
+          return usage("sync conflicts requires list|show.", "sync.conflicts");
       }
 
       if (conflictsCommand === "list") {
-        const mode = parseConflictMode(context.args);
-        if (!mode) {
-          return usage("sync conflicts list --mode only accepts pending|all.");
+        const listUnknownOption = findUnknownOption(parsed, CONFLICTS_LIST_OPTIONS);
+        if (listUnknownOption !== undefined) {
+          return unknownOption("sync.conflicts.list", listUnknownOption, CONFLICTS_LIST_OPTIONS);
+        }
+
+        const missingModeOption = readMissingOptionValue(parsed.missingOptionValues, "mode");
+        if (missingModeOption !== undefined) {
+            return usage("sync conflicts list --mode only accepts pending|all.", "sync.conflicts.list");
+        }
+
+        const mode = readOption(parsed.options, "mode") ?? "pending";
+        if (mode !== "pending" && mode !== "all") {
+            return usage("sync conflicts list --mode only accepts pending|all.", "sync.conflicts.list");
         }
 
         const conflicts = listSyncConflicts(context.cwd, mode);
 
         return okResult({
-          command: "sync conflicts list",
+          command: "sync.conflicts.list",
           human: formatConflictList(conflicts),
           data: {
             mode,
@@ -168,15 +241,20 @@ export async function runSync(context: CliContext): Promise<CliResult> {
       }
 
       if (conflictsCommand === "show") {
-        const conflictId: string | undefined = context.args[2];
-        if (!conflictId) {
-          return usage("sync conflicts show requires <conflict-id>.");
+        const showUnknownOption = findUnknownOption(parsed, CONFLICTS_SHOW_OPTIONS);
+        if (showUnknownOption !== undefined) {
+          return unknownOption("sync.conflicts.show", showUnknownOption, CONFLICTS_SHOW_OPTIONS);
         }
 
+        const conflictId: string | undefined = parsed.positional[2];
+          if (!conflictId) {
+            return usage("sync conflicts show requires <conflict-id>.", "sync.conflicts.show");
+          }
+
         const conflict = getSyncConflict(context.cwd, conflictId);
 
         return okResult({
-          command: "sync conflicts show",
+          command: "sync.conflicts.show",
           human: [
             `Conflict: ${conflict.id}`,
             `Entity: ${conflict.entityKind} ${conflict.entityId}`,
@@ -191,14 +269,14 @@ export async function runSync(context: CliContext): Promise<CliResult> {
         });
       }
 
-      return usage(`Unknown sync conflicts subcommand '${conflictsCommand}'.`);
+        return usage(`Unknown sync conflicts subcommand '${conflictsCommand}'.`, "sync.conflicts");
     }
 
     return usage(`Unknown sync subcommand '${subcommand}'.`);
   } catch (error) {
     if (error instanceof MissingBranchDatabaseError) {
       return failResult({
-        command: "sync",
+        command: resolvedCommand,
         human: error.message,
         data: {
           reason: "missing_branch_db",
@@ -213,7 +291,7 @@ export async function runSync(context: CliContext): Promise<CliResult> {
     const message = error instanceof Error ? error.message : "Unknown sync error.";
 
     return failResult({
-      command: "sync",
+      command: resolvedCommand,
       human: message,
       data: {
         reason: "sync_failed",

package/src/commands/task.ts

@@ -537,7 +537,29 @@ export async function runTask(context: CliContext): Promise<CliResult> {
           command: "task.list",
           human,
           data: { tasks },
-          ...(context.mode === "human" ? {} : { meta: { pagination: listed.pagination } }),
+          ...(context.mode === "human"
+            ? {}
+            : {
+                meta: {
+                  pagination: listed.pagination,
+                  defaults: {
+                    statuses: !includeAll && statuses === undefined ? [...DEFAULT_OPEN_TASK_STATUSES] : null,
+                    limit: !includeAll && parsedLimit === undefined ? DEFAULT_TASK_LIST_LIMIT : null,
+                    cursor: parsedCursor === undefined ? 0 : null,
+                    view: view === undefined ? "table" : null,
+                  },
+                  filters: {
+                    epicId: epicId ?? null,
+                    statuses: selectedStatuses ?? null,
+                    includeAll,
+                  },
+                  truncation: {
+                    applied: listed.pagination.hasMore,
+                    returned: tasks.length,
+                    limit: selectedLimit ?? null,
+                  },
+                },
+              }),
         });
       }
       case "show": {
@@ -593,6 +615,22 @@ export async function runTask(context: CliContext): Promise<CliResult> {
             command: "task.show",
             human: formatTask(task),
             data: { task, includeAll: false },
+            ...(context.mode === "human"
+              ? {}
+              : {
+                  meta: {
+                    defaults: {
+                      view: view === undefined ? effectiveView : null,
+                    },
+                    filters: {
+                      includeAll: false,
+                    },
+                    truncation: {
+                      applied: true,
+                      scope: "compact",
+                    },
+                  },
+                }),
           });
         }
 
@@ -603,6 +641,22 @@ export async function runTask(context: CliContext): Promise<CliResult> {
             command: "task.show",
             human: formatTaskShowTree(taskTree),
             data: { task: taskTree, includeAll: true, subtasksCount: taskTree.subtasks.length },
+            ...(context.mode === "human"
+              ? {}
+              : {
+                  meta: {
+                    defaults: {
+                      view: view === undefined ? effectiveView : null,
+                    },
+                    filters: {
+                      includeAll: true,
+                    },
+                    truncation: {
+                      applied: effectiveView === "tree",
+                      scope: "tree",
+                    },
+                  },
+                }),
           });
         }
 
@@ -610,6 +664,22 @@ export async function runTask(context: CliContext): Promise<CliResult> {
           command: "task.show",
           human: effectiveView === "table" ? formatTaskShowTable(taskTree) : formatTaskShowDetail(taskTree),
           data: { task: taskTree, includeAll: true, subtasksCount: taskTree.subtasks.length },
+          ...(context.mode === "human"
+            ? {}
+            : {
+                meta: {
+                  defaults: {
+                    view: view === undefined ? effectiveView : null,
+                  },
+                  filters: {
+                    includeAll: true,
+                  },
+                  truncation: {
+                    applied: false,
+                    scope: "full",
+                  },
+                },
+              }),
         });
       }
       case "ready": {

package/src/index.ts

@@ -5,7 +5,7 @@ import { executeShell, parseInvocation, renderShellResult } from "./runtime/cli-
 export async function run(argv: readonly string[] = process.argv.slice(2)): Promise<void> {
   const parsed = parseInvocation(argv);
   const result = await executeShell(parsed);
-  const rendered: string = renderShellResult(result, parsed.mode);
+  const rendered: string = renderShellResult(result, parsed.mode, parsed.compatibilityMode);
 
   if (result.ok) {
     process.stdout.write(`${rendered}\n`);

package/src/io/output.ts

@@ -1,5 +1,94 @@
 import { encode } from "@toon-format/toon";
-import { type CliResult, type OutputMode, type ToonEnvelope, type ToonError } from "../runtime/command-types";
+import {
+  type CliResult,
+  type CompatibilityMetadata,
+  type CompatibilityMode,
+  type ContractMetadata,
+  type OutputMode,
+  type ToonEnvelope,
+  type ToonError,
+} from "../runtime/command-types";
+
+const CONTRACT_VERSION = "1.0.0";
+const COMPATIBILITY_DEPRECATED_SINCE = "0.1.8";
+const COMPATIBILITY_REMOVAL_AFTER = "2026-09-30";
+
+interface RenderOptions {
+  readonly compatibilityMode?: CompatibilityMode | null;
+}
+
+function toLegacySyncCommandId(command: string): string {
+  const mapping: Record<string, string> = {
+    "sync.status": "sync_status",
+    "sync.pull": "sync_pull",
+    "sync.resolve": "sync_resolve",
+    "sync.conflicts": "sync_conflicts",
+    "sync.conflicts.list": "sync_conflicts_list",
+    "sync.conflicts.show": "sync_conflicts_show",
+  };
+
+  return mapping[command] ?? command;
+}
+
+function resolveCompatibilityCommand(command: string, compatibilityMode: CompatibilityMode | null): string {
+  if (compatibilityMode === "legacy-sync-command-ids") {
+    return toLegacySyncCommandId(command);
+  }
+
+  return command;
+}
+
+function createCompatibilityMetadata(command: string, compatibilityMode: CompatibilityMode | null): CompatibilityMetadata | undefined {
+  if (compatibilityMode !== "legacy-sync-command-ids") {
+    return undefined;
+  }
+
+  const compatibilityCommand: string = toLegacySyncCommandId(command);
+  return {
+    mode: compatibilityMode,
+    warningCode: "compatibility_mode_deprecated",
+    deprecatedSince: COMPATIBILITY_DEPRECATED_SINCE,
+    removalAfter: COMPATIBILITY_REMOVAL_AFTER,
+    migration: "Drop --compat legacy-sync-command-ids and parse canonical dotted command IDs.",
+    canonicalCommand: command,
+    compatibilityCommand,
+  };
+}
+
+function hashString(value: string): string {
+  let hash = 2166136261;
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+
+function createContractMetadata(result: CliResult, compatibilityMode: CompatibilityMode | null): ContractMetadata {
+  const requestSignature = JSON.stringify({
+    ok: result.ok,
+    command: result.command,
+    data: result.data,
+    error: result.error ?? null,
+    meta: result.meta ?? null,
+  });
+
+  const base: ContractMetadata = {
+    contractVersion: CONTRACT_VERSION,
+    requestId: `req-${hashString(requestSignature)}`,
+  };
+
+  const compatibility = createCompatibilityMetadata(result.command, compatibilityMode);
+  if (!compatibility) {
+    return base;
+  }
+
+  return {
+    ...base,
+    compatibility,
+  };
+}
 
 export interface ResultInput {
   readonly command: string;
@@ -45,18 +134,22 @@ export function failResult(input: ResultInput & { readonly error: ToonError }):
   };
 }
 
-export function toToonEnvelope(result: CliResult): ToonEnvelope {
+export function toToonEnvelope(result: CliResult, options: RenderOptions = {}): ToonEnvelope {
+  const compatibilityMode: CompatibilityMode | null = options.compatibilityMode ?? null;
+  const command: string = resolveCompatibilityCommand(result.command, compatibilityMode);
+
   return {
     ok: result.ok,
-    command: result.command,
+    command,
     data: result.data,
+    metadata: createContractMetadata(result, compatibilityMode),
     ...(result.error ? { error: result.error } : {}),
     ...(result.meta ? { meta: result.meta } : {}),
   };
 }
 
-export function renderResult(result: CliResult, mode: OutputMode): string {
-  const envelope: ToonEnvelope = toToonEnvelope(result);
+export function renderResult(result: CliResult, mode: OutputMode, options: RenderOptions = {}): string {
+  const envelope: ToonEnvelope = toToonEnvelope(result, options);
 
   if (mode === "json") {
     return JSON.stringify(envelope);