trekoon 0.1.7 → 0.1.9

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

package/src/runtime/cli-shell.ts

@@ -11,9 +11,9 @@ import { runSync } from "../commands/sync";
 import { runTask } from "../commands/task";
 import { runWipe } from "../commands/wipe";
 import { failResult, okResult, renderResult } from "../io/output";
-import { type CliContext, type CliResult, type OutputMode } from "./command-types";
-
-const CLI_VERSION = "0.1.0";
+import { type CliContext, type CliResult, type CompatibilityMode, type OutputMode } from "./command-types";
+import { CLI_VERSION } from "./version";
+import { resolveStoragePaths } from "../storage/path";
 
 const SUPPORTED_ROOT_COMMANDS: readonly string[] = [
   "help",
@@ -32,6 +32,9 @@ const SUPPORTED_ROOT_COMMANDS: readonly string[] = [
 
 export interface ParsedInvocation {
   readonly mode: OutputMode;
+  readonly compatibilityMode: CompatibilityMode | null;
+  readonly compatibilityModeRaw: string | null;
+  readonly compatibilityModeMissingValue: boolean;
   readonly command: string | null;
   readonly args: readonly string[];
   readonly wantsHelp: boolean;
@@ -45,11 +48,18 @@ export interface ParseInvocationOptions {
 export function parseInvocation(argv: readonly string[], options: ParseInvocationOptions = {}): ParsedInvocation {
   const stdoutIsTTY: boolean = options.stdoutIsTTY ?? Boolean(process.stdout.isTTY);
   let explicitMode: OutputMode | null = null;
+  let compatibilityModeRaw: string | null = null;
+  let compatibilityModeMissingValue = false;
   let wantsHelp = false;
   let wantsVersion = false;
   const positionals: string[] = [];
 
-  for (const token of argv) {
+  for (let index = 0; index < argv.length; index += 1) {
+    const token: string | undefined = argv[index];
+    if (!token) {
+      continue;
+    }
+
     if (token === "--json") {
       explicitMode = "json";
       continue;
@@ -70,11 +80,29 @@ export function parseInvocation(argv: readonly string[], options: ParseInvocatio
       continue;
     }
 
+    if (token === "--compat") {
+      const maybeValue: string | undefined = argv[index + 1];
+      if (!maybeValue || maybeValue.startsWith("--")) {
+        compatibilityModeMissingValue = true;
+        continue;
+      }
+
+      compatibilityModeRaw = maybeValue;
+      index += 1;
+      continue;
+    }
+
     positionals.push(token);
   }
 
+  const compatibilityMode: CompatibilityMode | null =
+    compatibilityModeRaw === "legacy-sync-command-ids" ? compatibilityModeRaw : null;
+
   return {
     mode: explicitMode ?? (stdoutIsTTY ? "human" : "json"),
+    compatibilityMode,
+    compatibilityModeRaw,
+    compatibilityModeMissingValue,
     command: positionals[0] ?? null,
     args: positionals.slice(1),
     wantsHelp,
@@ -82,11 +110,96 @@ export function parseInvocation(argv: readonly string[], options: ParseInvocatio
   };
 }
 
-export function renderShellResult(result: CliResult, mode: OutputMode): string {
-  return renderResult(result, mode);
+export function renderShellResult(result: CliResult, mode: OutputMode, compatibilityMode: CompatibilityMode | null = null): string {
+  const effectiveCompatibilityMode: CompatibilityMode | null =
+    compatibilityMode === "legacy-sync-command-ids" && result.command.startsWith("sync.")
+      ? compatibilityMode
+      : null;
+
+  return renderResult(result, mode, { compatibilityMode: effectiveCompatibilityMode });
+}
+
+function withStorageRootDiagnostics(result: CliResult, cwd: string): CliResult {
+  const diagnostics = resolveStoragePaths(cwd).diagnostics;
+  if (diagnostics.warnings.length === 0 && diagnostics.errors.length === 0) {
+    return result;
+  }
+
+  return {
+    ...result,
+    meta: {
+      ...(result.meta ?? {}),
+      storageRootDiagnostics: {
+        invocationCwd: diagnostics.invocationCwd,
+        canonicalRoot: diagnostics.canonicalRoot,
+        warning: diagnostics.warnings[0] ?? null,
+        error: diagnostics.errors[0] ?? null,
+      },
+    },
+  };
 }
 
 export async function executeShell(parsed: ParsedInvocation, cwd: string = process.cwd()): Promise<CliResult> {
+  if (parsed.compatibilityModeMissingValue) {
+    return failResult({
+      command: "shell",
+      human: "--compat requires an explicit mode value.",
+      data: {
+        option: "--compat",
+        allowedModes: ["legacy-sync-command-ids"],
+      },
+      error: {
+        code: "invalid_args",
+        message: "Missing compatibility mode value for --compat.",
+      },
+    });
+  }
+
+  if (parsed.compatibilityModeRaw !== null && parsed.compatibilityMode === null) {
+    return failResult({
+      command: "shell",
+      human: `Unsupported compatibility mode '${parsed.compatibilityModeRaw}'.`,
+      data: {
+        providedMode: parsed.compatibilityModeRaw,
+        allowedModes: ["legacy-sync-command-ids"],
+      },
+      error: {
+        code: "invalid_args",
+        message: `Unsupported compatibility mode '${parsed.compatibilityModeRaw}'.`,
+      },
+    });
+  }
+
+  if (parsed.compatibilityMode !== null && parsed.mode === "human") {
+    return failResult({
+      command: "shell",
+      human: "Compatibility mode is machine-only; use --json or --toon.",
+      data: {
+        mode: parsed.mode,
+        compatibilityMode: parsed.compatibilityMode,
+      },
+      error: {
+        code: "invalid_args",
+        message: "Compatibility mode requires machine output mode.",
+      },
+    });
+  }
+
+  if (parsed.compatibilityMode === "legacy-sync-command-ids" && parsed.command !== "sync") {
+    return failResult({
+      command: "shell",
+      human: "--compat legacy-sync-command-ids only supports sync commands.",
+      data: {
+        compatibilityMode: parsed.compatibilityMode,
+        command: parsed.command,
+      },
+      error: {
+        code: "invalid_args",
+        message: "Compatibility mode can only be used with the sync command.",
+      },
+    });
+  }
+
   if (parsed.wantsVersion) {
     return okResult({
       command: "version",
@@ -102,19 +215,23 @@ export async function executeShell(parsed: ParsedInvocation, cwd: string = proce
       args: parsed.command ? [parsed.command] : [],
     };
 
-    return runHelp(helpContext);
+    return withStorageRootDiagnostics(await runHelp(helpContext), cwd);
   }
 
   if (!parsed.command) {
-    return runHelp({
+    return withStorageRootDiagnostics(
+      await runHelp({
       mode: parsed.mode,
       args: [],
       cwd,
-    });
+      }),
+      cwd,
+    );
   }
 
   if (!SUPPORTED_ROOT_COMMANDS.includes(parsed.command)) {
-    return failResult({
+    return withStorageRootDiagnostics(
+      failResult({
       command: "shell",
       human: `Unknown command: ${parsed.command}\nRun 'trekoon --help' for usage.`,
       data: {
@@ -125,7 +242,9 @@ export async function executeShell(parsed: ParsedInvocation, cwd: string = proce
         code: "unknown_command",
         message: `Unknown command '${parsed.command}'`,
       },
-    });
+      }),
+      cwd,
+    );
   }
 
   const context: CliContext = {
@@ -134,33 +253,47 @@ export async function executeShell(parsed: ParsedInvocation, cwd: string = proce
     cwd,
   };
 
+  let result: CliResult;
+
   switch (parsed.command) {
     case "help":
-      return runHelp(context);
+      result = await runHelp(context);
+      break;
     case "init":
-      return runInit(context);
+      result = await runInit(context);
+      break;
     case "quickstart":
-      return runQuickstart(context);
+      result = await runQuickstart(context);
+      break;
     case "wipe":
-      return runWipe(context);
+      result = await runWipe(context);
+      break;
     case "epic":
-      return runEpic(context);
+      result = await runEpic(context);
+      break;
     case "task":
-      return runTask(context);
+      result = await runTask(context);
+      break;
     case "subtask":
-      return runSubtask(context);
+      result = await runSubtask(context);
+      break;
     case "dep":
-      return runDep(context);
+      result = await runDep(context);
+      break;
     case "events":
-      return runEvents(context);
+      result = await runEvents(context);
+      break;
     case "migrate":
-      return runMigrate(context);
+      result = await runMigrate(context);
+      break;
     case "sync":
-      return runSync(context);
+      result = await runSync(context);
+      break;
     case "skills":
-      return runSkills(context);
+      result = await runSkills(context);
+      break;
     default:
-      return failResult({
+      result = failResult({
         command: "shell",
         human: `Unhandled command: ${parsed.command}`,
         data: { command: parsed.command },
@@ -169,5 +302,8 @@ export async function executeShell(parsed: ParsedInvocation, cwd: string = proce
           message: `No shell handler for '${parsed.command}'`,
         },
       });
+      break;
   }
+
+  return withStorageRootDiagnostics(result, cwd);
 }

package/src/runtime/command-types.ts

@@ -1,4 +1,5 @@
 export type OutputMode = "human" | "json" | "toon";
+export type CompatibilityMode = "legacy-sync-command-ids";
 
 export interface CliContext {
   readonly mode: OutputMode;
@@ -11,10 +12,27 @@ export interface ToonError {
   readonly message: string;
 }
 
+export interface ContractMetadata {
+  readonly contractVersion: string;
+  readonly requestId: string;
+  readonly compatibility?: CompatibilityMetadata;
+}
+
+export interface CompatibilityMetadata {
+  readonly mode: CompatibilityMode;
+  readonly warningCode: "compatibility_mode_deprecated";
+  readonly deprecatedSince: string;
+  readonly removalAfter: string;
+  readonly migration: string;
+  readonly canonicalCommand: string;
+  readonly compatibilityCommand: string;
+}
+
 export interface ToonEnvelope {
   readonly ok: boolean;
   readonly command: string;
   readonly data: unknown;
+  readonly metadata: ContractMetadata;
   readonly error?: ToonError;
   readonly meta?: Record<string, unknown>;
 }

package/src/runtime/version.ts

@@ -0,0 +1,20 @@
+import { readFileSync } from "node:fs";
+
+interface PackageManifest {
+  readonly version?: string;
+}
+
+function readCliVersion(): string {
+  const packageJsonPath = new URL("../../package.json", import.meta.url);
+  const packageJsonContent: string = readFileSync(packageJsonPath, "utf8");
+  const packageManifest: PackageManifest = JSON.parse(packageJsonContent) as PackageManifest;
+  const version: string | undefined = packageManifest.version;
+
+  if (typeof version !== "string" || version.length === 0) {
+    throw new Error("package.json is missing a valid version field.");
+  }
+
+  return version;
+}
+
+export const CLI_VERSION: string = readCliVersion();

package/src/storage/path.ts

@@ -1,22 +1,79 @@
+import { spawnSync } from "node:child_process";
 import { resolve } from "node:path";
 
 const DB_DIRNAME = ".trekoon";
 const DB_FILENAME = "trekoon.db";
 
 export interface StoragePaths {
+  readonly invocationCwd: string;
   readonly worktreeRoot: string;
   readonly storageDir: string;
   readonly databaseFile: string;
+  readonly diagnostics: StoragePathDiagnostics;
+}
+
+export interface StoragePathIssue {
+  readonly code: string;
+  readonly message: string;
+  readonly invocationCwd: string;
+  readonly canonicalRoot: string;
+}
+
+export interface StoragePathDiagnostics {
+  readonly invocationCwd: string;
+  readonly canonicalRoot: string;
+  readonly warnings: readonly StoragePathIssue[];
+  readonly errors: readonly StoragePathIssue[];
+}
+
+function resolveGitTopLevel(workingDirectory: string): string | null {
+  const result = spawnSync("git", ["rev-parse", "--show-toplevel"], {
+    cwd: workingDirectory,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+
+  if (result.status !== 0) {
+    return null;
+  }
+
+  const topLevel: string = result.stdout.trim();
+  if (!topLevel) {
+    return null;
+  }
+
+  return resolve(topLevel);
 }
 
 export function resolveStoragePaths(workingDirectory: string = process.cwd()): StoragePaths {
-  const worktreeRoot: string = resolve(workingDirectory);
+  const invocationCwd: string = resolve(workingDirectory);
+  const canonicalRoot: string = resolveGitTopLevel(invocationCwd) ?? invocationCwd;
+  const worktreeRoot: string = canonicalRoot;
   const storageDir: string = resolve(worktreeRoot, DB_DIRNAME);
   const databaseFile: string = resolve(storageDir, DB_FILENAME);
+  const warnings: StoragePathIssue[] = [];
+
+  if (invocationCwd !== canonicalRoot) {
+    warnings.push({
+      code: "storage_root_diverged_from_cwd",
+      message: "Resolved storage root differs from invocation cwd.",
+      invocationCwd,
+      canonicalRoot,
+    });
+  }
+
+  const diagnostics: StoragePathDiagnostics = {
+    invocationCwd,
+    canonicalRoot,
+    warnings,
+    errors: [],
+  };
 
   return {
+    invocationCwd,
     worktreeRoot,
     storageDir,
     databaseFile,
+    diagnostics,
   };
 }