trekoon 0.1.8 → 0.2.0

package/src/domain/tracker-domain.ts

@@ -10,6 +10,11 @@ import {
   type EpicTree,
   type NodeKind,
   type ReverseDependencyNode,
+  type SearchEntityMatch,
+  type SearchField,
+  type SearchFieldMatch,
+  type SearchNode,
+  type SearchSummary,
   type SubtaskRecord,
   type TaskTreeDetailed,
   type TaskRecord,
@@ -125,6 +130,55 @@ function mapDependency(row: DependencyRow): DependencyRecord {
   };
 }
 
+function countMatches(value: string, searchText: string): number {
+  if (searchText.length === 0) {
+    return 0;
+  }
+
+  let count = 0;
+  let offset = 0;
+  while (offset <= value.length - searchText.length) {
+    const nextIndex = value.indexOf(searchText, offset);
+    if (nextIndex === -1) {
+      return count;
+    }
+
+    count += 1;
+    offset = nextIndex + searchText.length;
+  }
+
+  return count;
+}
+
+function buildMatchSnippet(value: string, searchText: string, contextSize = 24): string {
+  if (searchText.length === 0) {
+    return "";
+  }
+
+  const matchIndex = value.indexOf(searchText);
+  if (matchIndex === -1) {
+    return "";
+  }
+
+  const start = Math.max(0, matchIndex - contextSize);
+  const end = Math.min(value.length, matchIndex + searchText.length + contextSize);
+  const rawSnippet = value.slice(start, end).replace(/\s+/g, " ").trim();
+  const prefix = start > 0 ? "…" : "";
+  const suffix = end < value.length ? "…" : "";
+  return `${prefix}${rawSnippet}${suffix}`;
+}
+
+function summarizeMatches(matches: readonly SearchEntityMatch[]): SearchSummary {
+  return {
+    matchedEntities: matches.length,
+    matchedFields: matches.reduce((total, match) => total + match.fields.length, 0),
+    totalMatches: matches.reduce(
+      (total, match) => total + match.fields.reduce((fieldTotal, field) => fieldTotal + field.count, 0),
+      0,
+    ),
+  };
+}
+
 export class TrackerDomain {
   readonly #db: Database;
 
@@ -433,6 +487,89 @@ export class TrackerDomain {
     };
   }
 
+  collectEpicSearchScope(epicId: string): readonly SearchNode[] {
+    const tree = this.buildEpicTreeDetailed(epicId);
+
+    return [
+      {
+        kind: "epic",
+        id: tree.id,
+        title: tree.title,
+        description: tree.description,
+      },
+      ...tree.tasks.flatMap((task) => [
+        {
+          kind: "task" as const,
+          id: task.id,
+          title: task.title,
+          description: task.description,
+        },
+        ...task.subtasks.map((subtask) => ({
+          kind: "subtask" as const,
+          id: subtask.id,
+          title: subtask.title,
+          description: subtask.description,
+        })),
+      ]),
+    ];
+  }
+
+  collectTaskSearchScope(taskId: string): readonly SearchNode[] {
+    const tree = this.buildTaskTreeDetailed(taskId);
+
+    return [
+      {
+        kind: "task",
+        id: tree.id,
+        title: tree.title,
+        description: tree.description,
+      },
+      ...tree.subtasks.map((subtask) => ({
+        kind: "subtask" as const,
+        id: subtask.id,
+        title: subtask.title,
+        description: subtask.description,
+      })),
+    ];
+  }
+
+  collectSubtaskSearchScope(subtaskId: string): readonly SearchNode[] {
+    const subtask = this.getSubtaskOrThrow(subtaskId);
+
+    return [
+      {
+        kind: "subtask",
+        id: subtask.id,
+        title: subtask.title,
+        description: subtask.description,
+      },
+    ];
+  }
+
+  searchEpicScope(epicId: string, searchText: string, fields: readonly SearchField[]): { readonly matches: readonly SearchEntityMatch[]; readonly summary: SearchSummary } {
+    const matches = this.collectSearchMatches(this.collectEpicSearchScope(epicId), searchText, fields);
+    return {
+      matches,
+      summary: summarizeMatches(matches),
+    };
+  }
+
+  searchTaskScope(taskId: string, searchText: string, fields: readonly SearchField[]): { readonly matches: readonly SearchEntityMatch[]; readonly summary: SearchSummary } {
+    const matches = this.collectSearchMatches(this.collectTaskSearchScope(taskId), searchText, fields);
+    return {
+      matches,
+      summary: summarizeMatches(matches),
+    };
+  }
+
+  searchSubtaskScope(subtaskId: string, searchText: string, fields: readonly SearchField[]): { readonly matches: readonly SearchEntityMatch[]; readonly summary: SearchSummary } {
+    const matches = this.collectSearchMatches(this.collectSubtaskSearchScope(subtaskId), searchText, fields);
+    return {
+      matches,
+      summary: summarizeMatches(matches),
+    };
+  }
+
   resolveNodeKind(id: string): "task" | "subtask" {
     const task = this.getTask(id);
     if (task) {
@@ -570,6 +707,40 @@ export class TrackerDomain {
     return mapDependency(row);
   }
 
+  private collectSearchMatches(
+    nodes: readonly SearchNode[],
+    searchText: string,
+    fields: readonly SearchField[],
+  ): readonly SearchEntityMatch[] {
+    const matches: SearchEntityMatch[] = [];
+
+    for (const node of nodes) {
+      const matchedFields: SearchFieldMatch[] = [];
+      for (const field of fields) {
+        const count = countMatches(node[field], searchText);
+        if (count > 0) {
+          matchedFields.push({
+            field,
+            count,
+            snippet: buildMatchSnippet(node[field], searchText),
+          });
+        }
+      }
+
+      if (matchedFields.length === 0) {
+        continue;
+      }
+
+      matches.push({
+        kind: node.kind,
+        id: node.id,
+        fields: matchedFields,
+      });
+    }
+
+    return matches;
+  }
+
   private wouldCreateCycle(sourceId: string, dependsOnId: string): boolean {
     const row = this.#db
       .query(

package/src/domain/types.ts

@@ -85,6 +85,33 @@ export interface EpicTreeDetailed {
   readonly tasks: ReadonlyArray<TaskTreeDetailed>;
 }
 
+export type SearchField = "title" | "description";
+
+export interface SearchFieldMatch {
+  readonly field: SearchField;
+  readonly count: number;
+  readonly snippet: string;
+}
+
+export interface SearchEntityMatch {
+  readonly kind: NodeKind;
+  readonly id: string;
+  readonly fields: readonly SearchFieldMatch[];
+}
+
+export interface SearchSummary {
+  readonly matchedEntities: number;
+  readonly matchedFields: number;
+  readonly totalMatches: number;
+}
+
+export interface SearchNode {
+  readonly kind: NodeKind;
+  readonly id: string;
+  readonly title: string;
+  readonly description: string;
+}
+
 export interface DomainErrorShape {
   readonly code: string;
   readonly message: string;

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,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>;
 }