trekoon 0.1.8 → 0.1.9

package/src/runtime/cli-shell.ts

@@ -11,8 +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";
+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",
@@ -31,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;
@@ -44,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;
@@ -69,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,
@@ -81,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",
@@ -101,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: {
@@ -124,7 +242,9 @@ export async function executeShell(parsed: ParsedInvocation, cwd: string = proce
         code: "unknown_command",
         message: `Unknown command '${parsed.command}'`,
       },
-    });
+      }),
+      cwd,
+    );
   }
 
   const context: CliContext = {
@@ -133,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 },
@@ -168,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/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,
   };
 }