agent-handoff 0.4.0 → 0.5.0

package/dist/index.js

@@ -2,7 +2,7 @@
 
 // src/index.ts
 import { createRequire } from "module";
-import { Command as Command9 } from "commander";
+import { Command as Command13 } from "commander";
 
 // src/cli/commands/init.ts
 import { Command } from "commander";
@@ -178,6 +178,14 @@ async function detectStepOutputs(workspacePath, workflow) {
   }
   return outputs;
 }
+async function fileExists(filePath) {
+  try {
+    await fs3.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
 
 // src/core/state-machine.ts
 function computeState(workflow, stepOutputs) {
@@ -1777,10 +1785,892 @@ var exportCommand = new Command8("export").description("\u5BFC\u51FA\u9759\u6001
   }
 );
 
+// src/cli/commands/index.ts
+import { Command as Command9 } from "commander";
+import fs14 from "fs/promises";
+import path16 from "path";
+
+// src/core/index/indexer.ts
+import fs12 from "fs/promises";
+import path14 from "path";
+async function readPreview(filePath, maxChars) {
+  try {
+    const content = await fs12.readFile(filePath, "utf-8");
+    const sliced = content.slice(0, maxChars);
+    return sliced;
+  } catch {
+    return void 0;
+  }
+}
+async function statInfo(filePath) {
+  try {
+    const st = await fs12.stat(filePath);
+    return { bytes: st.size, updatedAt: st.mtime.toISOString() };
+  } catch {
+    return {};
+  }
+}
+async function addArtifact(workspacePath, relPath, kind) {
+  const full = path14.join(workspacePath, relPath);
+  const exists = await fileExists(full);
+  if (!exists) {
+    return { path: relPath, kind };
+  }
+  const { bytes, updatedAt } = await statInfo(full);
+  const preview = await readPreview(full, 2e3);
+  return { path: relPath, kind, bytes, updatedAt, ...preview !== void 0 && { preview } };
+}
+async function buildWorkspaceIndex(workspacePath) {
+  const info = await loadWorkspace(workspacePath);
+  if (!info.exists) {
+    throw new Error(`workspace not found: ${path14.resolve(workspacePath)}`);
+  }
+  if (!info.hasWorkflow || !info.workflow) {
+    throw new Error(`workflow.yaml not found in ${path14.resolve(workspacePath)}`);
+  }
+  const abs = info.path;
+  const indexedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const workspaceName = path14.basename(abs);
+  const steps = await Promise.all(
+    info.workflow.steps.map(async (step, i) => {
+      const outputRel = step.output;
+      const outputFull = path14.join(abs, outputRel);
+      const outputExists = await fileExists(outputFull);
+      return { id: step.id, index: i + 1, outputPath: outputRel, outputExists };
+    })
+  );
+  const artifacts = [];
+  const briefRel = "brief.md";
+  if (await fileExists(path14.join(abs, briefRel))) {
+    artifacts.push(await addArtifact(abs, briefRel, "brief"));
+  }
+  for (const step of info.workflow.steps) {
+    const rel = step.output;
+    artifacts.push(await addArtifact(abs, rel, "step.output"));
+  }
+  const { events } = await readEventsJsonl({ workspacePath: abs });
+  const items = toTimelineItems(events);
+  const indexedEvents = items.map((item) => ({
+    ts: item.ts,
+    stepId: item.stepId,
+    stepIndex: item.stepIndex,
+    type: item.type,
+    summary: item.summary,
+    ...item.workItemId && { workItemId: item.workItemId },
+    ...item.links && item.links.length > 0 && { links: item.links }
+  }));
+  return {
+    version: 1,
+    workspacePath: abs,
+    workspaceName,
+    indexedAt,
+    workflowName: info.workflow.name,
+    steps,
+    artifacts,
+    events: indexedEvents
+  };
+}
+
+// src/core/index/registry.ts
+import fs13 from "fs/promises";
+import os3 from "os";
+import path15 from "path";
+function getHomeDir() {
+  try {
+    const envHome = process.env.HOME;
+    if (envHome && envHome.trim()) return envHome;
+    const home = os3.homedir();
+    if (home && home.trim()) return home;
+    return null;
+  } catch {
+    return null;
+  }
+}
+function defaultRegistryFilePath() {
+  const home = getHomeDir();
+  const base = home ? home : process.cwd();
+  return path15.join(base, ".agenthandoff", "registry.json");
+}
+async function ensureParentDir(filePath) {
+  await fs13.mkdir(path15.dirname(filePath), { recursive: true });
+}
+function normalizeRegistry(registry) {
+  if (typeof registry === "object" && registry !== null && "version" in registry && registry.version === 1 && "items" in registry && Array.isArray(registry.items)) {
+    const items = registry.items.map((item) => {
+      if (typeof item !== "object" || item === null) return null;
+      const obj = item;
+      const name = typeof obj.name === "string" ? obj.name : "";
+      const itemPath = typeof obj.path === "string" ? obj.path : "";
+      const addedAt = typeof obj.addedAt === "string" ? obj.addedAt : "";
+      const updatedAt = typeof obj.updatedAt === "string" ? obj.updatedAt : "";
+      if (!name || !itemPath) return null;
+      return { name, path: itemPath, addedAt, updatedAt };
+    }).filter((x) => Boolean(x));
+    return { version: 1, items };
+  }
+  return { version: 1, items: [] };
+}
+function createDefaultRegistryStore() {
+  const filePath = defaultRegistryFilePath();
+  return {
+    async load() {
+      try {
+        const raw = await fs13.readFile(filePath, "utf-8");
+        const parsed = JSON.parse(raw);
+        return normalizeRegistry(parsed);
+      } catch {
+        return { version: 1, items: [] };
+      }
+    },
+    async save(registry) {
+      await ensureParentDir(filePath);
+      const normalized = normalizeRegistry(registry);
+      await fs13.writeFile(filePath, JSON.stringify(normalized, null, 2) + "\n", "utf-8");
+    }
+  };
+}
+function defaultNameForPath(workspacePath) {
+  const abs = path15.resolve(workspacePath);
+  return path15.basename(abs) || abs;
+}
+async function registerWorkspace(workspacePath, name) {
+  const store = createDefaultRegistryStore();
+  const registry = await store.load();
+  const absPath = path15.resolve(workspacePath);
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const itemName = name && name.trim() ? name.trim() : defaultNameForPath(absPath);
+  const existingIndex = registry.items.findIndex((i) => path15.resolve(i.path) === absPath);
+  if (existingIndex >= 0) {
+    const existing = registry.items[existingIndex];
+    registry.items[existingIndex] = {
+      ...existing,
+      name: itemName,
+      updatedAt: now,
+      addedAt: existing.addedAt || now,
+      path: absPath
+    };
+  } else {
+    registry.items.push({
+      name: itemName,
+      path: absPath,
+      addedAt: now,
+      updatedAt: now
+    });
+  }
+  await store.save(registry);
+}
+async function unregisterWorkspace(pathOrName) {
+  const store = createDefaultRegistryStore();
+  const registry = await store.load();
+  const token = String(pathOrName).trim();
+  if (!token) return;
+  const abs = path15.resolve(token);
+  registry.items = registry.items.filter((item) => {
+    const itemAbs = path15.resolve(item.path);
+    return itemAbs !== abs && item.name !== token;
+  });
+  await store.save(registry);
+}
+async function listWorkspaces() {
+  const store = createDefaultRegistryStore();
+  const registry = await store.load();
+  return [...registry.items].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+// src/cli/commands/index.ts
+async function ensureDir2(dir) {
+  await fs14.mkdir(dir, { recursive: true });
+}
+var indexCommand = new Command9("index").description("\u751F\u6210 workspace \u7D22\u5F15\uFF0C\u5E76\u652F\u6301 registry \u7BA1\u7406").argument("[workspace]", "workspace \u8DEF\u5F84", ".").option("--add", "\u5C06 workspace \u52A0\u5165 registry").option("--list", "\u5217\u51FA registry \u4E2D\u7684 workspaces").option("--remove <pathOrName>", "\u4ECE registry \u5220\u9664 workspace\uFF08path \u6216 name\uFF09").option("--output <file>", "\u8F93\u51FA\u7D22\u5F15\u6587\u4EF6\u8DEF\u5F84\uFF08\u9ED8\u8BA4 <workspace>/.agenthandoff/index.json\uFF09").option("--json", "\u4EE5 JSON \u8F93\u51FA\u7ED3\u679C\u5230 stdout").action(
+  async (workspace, options) => {
+    try {
+      if (options.list) {
+        const items = await listWorkspaces();
+        if (options.json) {
+          console.log(JSON.stringify(items, null, 2));
+          return;
+        }
+        if (items.length === 0) {
+          console.log("Registry is empty");
+          return;
+        }
+        for (const item of items) {
+          console.log(`${item.name}	${item.path}`);
+        }
+        return;
+      }
+      if (options.remove) {
+        await unregisterWorkspace(options.remove);
+        console.log(`\u2705 Removed from registry: ${options.remove}`);
+        return;
+      }
+      const workspacePath = path16.resolve(workspace);
+      const info = await loadWorkspace(workspacePath);
+      if (!info.exists) {
+        console.error(`Error: workspace not found: ${workspacePath}`);
+        process.exit(1);
+      }
+      if (!info.hasWorkflow || !info.workflow) {
+        console.error(`Error: workflow.yaml not found in ${workspacePath}`);
+        process.exit(1);
+      }
+      if (options.add) {
+        await registerWorkspace(workspacePath, info.workflow.name);
+      }
+      const index = await buildWorkspaceIndex(workspacePath);
+      const outputFile = options.output ? path16.resolve(options.output) : path16.join(workspacePath, ".agenthandoff", "index.json");
+      await ensureDir2(path16.dirname(outputFile));
+      await fs14.writeFile(outputFile, JSON.stringify(index, null, 2) + "\n", "utf-8");
+      if (options.json) {
+        console.log(JSON.stringify(index, null, 2));
+        return;
+      }
+      console.log(`\u2705 Indexed: ${workspacePath}`);
+      console.log(`  output: ${outputFile}`);
+      console.log(`  steps: ${index.steps.length}`);
+      console.log(`  artifacts: ${index.artifacts.length}`);
+      console.log(`  events: ${index.events.length}`);
+    } catch (error) {
+      console.error(`Error: ${error}`);
+      process.exit(1);
+    }
+  }
+);
+
+// src/cli/commands/search.ts
+import { Command as Command10 } from "commander";
+
+// src/core/search/search.ts
+import fs15 from "fs/promises";
+import path17 from "path";
+async function readIndexFile(workspacePath, indexDir) {
+  const indexFile = indexDir ? path17.join(indexDir, "index.json") : path17.join(workspacePath, ".agenthandoff", "index.json");
+  try {
+    const raw = await fs15.readFile(indexFile, "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function toLower(input) {
+  return input.toLowerCase();
+}
+function normalizeList(values) {
+  if (!values || values.length === 0) return void 0;
+  return values.map((v) => v.trim()).filter((v) => v.length > 0);
+}
+function textIncludes(haystack, needle) {
+  return toLower(haystack).includes(needle);
+}
+function matchOptional(value, filter) {
+  if (!filter || filter.length === 0) return true;
+  if (!value) return false;
+  return filter.includes(value);
+}
+function makeSnippet(text, q) {
+  const lower = toLower(text);
+  const idx = lower.indexOf(q);
+  if (idx < 0) {
+    return text.length > 160 ? text.slice(0, 160) : text;
+  }
+  const start = Math.max(0, idx - 40);
+  const end = Math.min(text.length, idx + q.length + 80);
+  return text.slice(start, end);
+}
+function scoreHit(hit) {
+  return hit.score;
+}
+async function resolveTargets(query, options) {
+  const workspaceFilters = normalizeList(query.workspace);
+  const registryItems = options.registryOnly ? await listWorkspaces() : [];
+  const targets = [];
+  if (registryItems.length > 0) {
+    for (const item of registryItems) {
+      if (!workspaceFilters || workspaceFilters.includes(item.name) || workspaceFilters.includes(item.path)) {
+        targets.push({ name: item.name, path: item.path });
+      }
+    }
+  }
+  if (!options.registryOnly && workspaceFilters && workspaceFilters.length > 0) {
+    for (const token of workspaceFilters) {
+      const exists = targets.some((t) => t.path === token || t.name === token);
+      if (!exists) {
+        targets.push({ name: path17.basename(token), path: token });
+      }
+    }
+  }
+  return targets;
+}
+async function search(query, options) {
+  const q = query.q.trim();
+  const qLower = toLower(q);
+  const stepFilter = normalizeList(query.stepId);
+  const typeFilter = normalizeList(query.type);
+  const workItemFilter = normalizeList(query.workItemId);
+  const limit = query.limit && query.limit > 0 ? query.limit : void 0;
+  const targets = await resolveTargets(query, options);
+  const hits = [];
+  for (const target of targets) {
+    const index = await readIndexFile(target.path, options.indexDir);
+    if (!index) {
+      continue;
+    }
+    const workspaceName = index.workspaceName || target.name;
+    const workspacePath = index.workspacePath || target.path;
+    if (options.targets === "events" || options.targets === "all") {
+      const events = index.events || [];
+      for (const event of events) {
+        if (!matchOptional(event.stepId, stepFilter)) continue;
+        if (!matchOptional(event.type, typeFilter)) continue;
+        if (!matchOptional(event.workItemId, workItemFilter)) continue;
+        if (!textIncludes(event.summary || "", qLower)) continue;
+        hits.push({
+          workspaceName,
+          workspacePath,
+          kind: "event",
+          score: 1,
+          title: `${event.type} \xB7 ${event.stepId}`,
+          snippet: makeSnippet(event.summary || "", qLower),
+          meta: {
+            ts: event.ts,
+            stepId: event.stepId,
+            stepIndex: event.stepIndex,
+            type: event.type,
+            workItemId: event.workItemId
+          }
+        });
+      }
+    }
+    if (options.targets === "artifacts" || options.targets === "all") {
+      const artifacts = index.artifacts || [];
+      for (const artifact of artifacts) {
+        const preview = artifact.preview || "";
+        if (!textIncludes(preview, qLower)) continue;
+        hits.push({
+          workspaceName,
+          workspacePath,
+          kind: "artifact",
+          score: 1,
+          title: artifact.path,
+          snippet: makeSnippet(preview, qLower),
+          link: artifact.path,
+          meta: {
+            path: artifact.path,
+            kind: artifact.kind
+          }
+        });
+      }
+    }
+  }
+  hits.sort((a, b) => {
+    const scoreDiff = scoreHit(b) - scoreHit(a);
+    if (scoreDiff !== 0) return scoreDiff;
+    const aTs = typeof a.meta.ts === "string" ? a.meta.ts : "";
+    const bTs = typeof b.meta.ts === "string" ? b.meta.ts : "";
+    return bTs.localeCompare(aTs);
+  });
+  return limit ? hits.slice(0, limit) : hits;
+}
+
+// src/cli/commands/search.ts
+function collect(value, previous = []) {
+  return previous.concat([value]);
+}
+var searchCommand = new Command10("search").description("\u5728 workspace \u7D22\u5F15\u4E0A\u6267\u884C\u641C\u7D22").argument("<query>", "\u641C\u7D22\u5173\u952E\u8BCD").option("--workspace <pathOrName>", "\u6307\u5B9A workspace\uFF08\u53EF\u91CD\u590D\uFF09", collect, []).option("--step <id>", "\u7B5B\u9009 stepId\uFF08\u53EF\u91CD\u590D\uFF09", collect, []).option("--type <type>", "\u7B5B\u9009\u4E8B\u4EF6\u7C7B\u578B\uFF08\u53EF\u91CD\u590D\uFF09", collect, []).option("--work-item <id>", "\u7B5B\u9009 workItemId\uFF08\u53EF\u91CD\u590D\uFF09", collect, []).option("--limit <n>", "\u9650\u5236\u7ED3\u679C\u6570\u91CF", (v) => parseInt(v, 10)).option("--json", "\u4EE5 JSON \u8F93\u51FA\u7ED3\u679C").action(
+  async (query, options) => {
+    try {
+      const registryItems = await listWorkspaces();
+      const workspaces = options.workspace || [];
+      const registryOnly = workspaces.length === 0;
+      const results = await search(
+        {
+          q: query,
+          workspace: workspaces,
+          stepId: options.step,
+          type: options.type,
+          workItemId: options.workItem,
+          limit: options.limit
+        },
+        { targets: "all", registryOnly }
+      );
+      if (options.json) {
+        console.log(JSON.stringify(results, null, 2));
+        return;
+      }
+      if (!registryOnly && registryItems.length === 0) {
+        console.log("\u26A0\uFE0F  registry \u4E3A\u7A7A\uFF0C\u4F7F\u7528\u547D\u4EE4\u884C\u6307\u5B9A\u7684 workspace");
+      }
+      if (results.length === 0) {
+        console.log("\u672A\u627E\u5230\u5339\u914D\u7ED3\u679C");
+        if (registryItems.length === 0 && registryOnly) {
+          console.log("\u63D0\u793A\uFF1A\u8BF7\u5148\u8FD0\u884C agent-handoff index --add \u6CE8\u518C workspace");
+        }
+        return;
+      }
+      for (const hit of results) {
+        console.log(`${hit.workspaceName}	${hit.kind}	${hit.title}`);
+        if (hit.snippet) {
+          console.log(`  ${hit.snippet}`);
+        }
+      }
+    } catch (error) {
+      console.error(`Error: ${error}`);
+      process.exit(1);
+    }
+  }
+);
+
+// src/cli/commands/diff.ts
+import { Command as Command11 } from "commander";
+import path19 from "path";
+
+// src/core/diff/diff.ts
+import fs16 from "fs/promises";
+import path18 from "path";
+async function readIndex(workspacePath) {
+  const abs = path18.resolve(workspacePath);
+  const indexPath = path18.join(abs, ".agenthandoff", "index.json");
+  try {
+    const raw = await fs16.readFile(indexPath, "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    throw new Error(`index not found: ${indexPath}. \u8BF7\u5148\u8FD0\u884C agent-handoff index`);
+  }
+}
+async function readTextFile(filePath) {
+  try {
+    return await fs16.readFile(filePath, "utf-8");
+  } catch {
+    return null;
+  }
+}
+function uniqueSorted(values) {
+  return Array.from(new Set(values)).sort((a, b) => a.localeCompare(b));
+}
+function defaultArtifactPaths(index) {
+  const artifacts = index.artifacts || [];
+  const paths = artifacts.map((a) => a.path);
+  return paths.filter((p) => p === "brief.md" || /^steps\/[^/]+\/output\.md$/.test(p));
+}
+function buildLcsOps(a, b) {
+  const n = a.length;
+  const m = b.length;
+  const dp = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+  for (let i2 = n - 1; i2 >= 0; i2--) {
+    for (let j2 = m - 1; j2 >= 0; j2--) {
+      dp[i2][j2] = a[i2] === b[j2] ? dp[i2 + 1][j2 + 1] + 1 : Math.max(dp[i2 + 1][j2], dp[i2][j2 + 1]);
+    }
+  }
+  const ops = [];
+  let i = 0;
+  let j = 0;
+  while (i < n && j < m) {
+    if (a[i] === b[j]) {
+      ops.push({ t: "equal", line: a[i] });
+      i++;
+      j++;
+    } else if (dp[i + 1][j] >= dp[i][j + 1]) {
+      ops.push({ t: "del", line: a[i] });
+      i++;
+    } else {
+      ops.push({ t: "add", line: b[j] });
+      j++;
+    }
+  }
+  while (i < n) {
+    ops.push({ t: "del", line: a[i] });
+    i++;
+  }
+  while (j < m) {
+    ops.push({ t: "add", line: b[j] });
+    j++;
+  }
+  return ops;
+}
+function formatUnifiedDiff(filePath, left, right, contextLines) {
+  const leftLines = (left ?? "").split("\n");
+  const rightLines = (right ?? "").split("\n");
+  const ops = buildLcsOps(leftLines, rightLines);
+  const lines = [];
+  lines.push(`--- a/${filePath}`);
+  lines.push(`+++ b/${filePath}`);
+  let aLine = 1;
+  let bLine = 1;
+  let i = 0;
+  const consumeEqual = (count) => {
+    for (let k = 0; k < count && i < ops.length; k++) {
+      const op = ops[i];
+      if (op.t !== "equal") break;
+      aLine++;
+      bLine++;
+      i++;
+    }
+  };
+  while (i < ops.length) {
+    while (i < ops.length && ops[i].t === "equal") {
+      i++;
+      aLine++;
+      bLine++;
+    }
+    if (i >= ops.length) break;
+    const hunkStart = Math.max(0, i - contextLines);
+    let hunkEnd = i;
+    let trailingContext = 0;
+    while (hunkEnd < ops.length) {
+      if (ops[hunkEnd].t === "equal") {
+        trailingContext++;
+        if (trailingContext > contextLines) break;
+      } else {
+        trailingContext = 0;
+      }
+      hunkEnd++;
+    }
+    let aStart = aLine;
+    let bStart = bLine;
+    for (let k = i - 1; k >= hunkStart; k--) {
+      const op = ops[k];
+      if (op.t === "equal" || op.t === "del") aStart--;
+      if (op.t === "equal" || op.t === "add") bStart--;
+    }
+    let aLen = 0;
+    let bLen = 0;
+    for (let k = hunkStart; k < hunkEnd; k++) {
+      const op = ops[k];
+      if (op.t === "equal" || op.t === "del") aLen++;
+      if (op.t === "equal" || op.t === "add") bLen++;
+    }
+    lines.push(`@@ -${aStart},${aLen} +${bStart},${bLen} @@`);
+    for (let k = hunkStart; k < hunkEnd; k++) {
+      const op = ops[k];
+      if (op.t === "equal") lines.push(` ${op.line}`);
+      if (op.t === "del") lines.push(`-${op.line}`);
+      if (op.t === "add") lines.push(`+${op.line}`);
+    }
+    i = hunkEnd;
+    consumeEqual(contextLines);
+  }
+  return lines.join("\n");
+}
+function diffWorkflow(left, right) {
+  const leftSteps = left.steps || [];
+  const rightSteps = right.steps || [];
+  const leftIds = leftSteps.map((s) => s.id);
+  const rightIds = rightSteps.map((s) => s.id);
+  const leftSet = new Set(leftIds);
+  const rightSet = new Set(rightIds);
+  const added = rightIds.filter((id) => !leftSet.has(id));
+  const removed = leftIds.filter((id) => !rightSet.has(id));
+  let changedSteps = 0;
+  const maxLen = Math.max(leftIds.length, rightIds.length);
+  for (let i = 0; i < maxLen; i++) {
+    if (leftIds[i] !== rightIds[i]) changedSteps++;
+  }
+  const orderChanged = added.length === 0 && removed.length === 0 && leftIds.join("|") !== rightIds.join("|");
+  const changed = added.length > 0 || removed.length > 0 || orderChanged;
+  if (!changed) {
+    return { changed: false, changedSteps: 0 };
+  }
+  const parts = [];
+  if (added.length > 0) parts.push(`added: ${added.join(", ")}`);
+  if (removed.length > 0) parts.push(`removed: ${removed.join(", ")}`);
+  if (orderChanged) parts.push("order: changed");
+  return { changed: true, details: parts.join("\n"), changedSteps };
+}
+function diffEvents(left, right) {
+  const leftEvents = left.events || [];
+  const rightEvents = right.events || [];
+  const leftCount = leftEvents.length;
+  const rightCount = rightEvents.length;
+  const added = rightCount > leftCount ? rightCount - leftCount : 0;
+  const latest = rightEvents[rightEvents.length - 1];
+  return {
+    leftCount,
+    rightCount,
+    added,
+    ...latest ? { latestRight: { ts: latest.ts, summary: latest.summary } } : {}
+  };
+}
+async function diffWorkspaces(options) {
+  const leftWs = path18.resolve(options.leftWorkspace);
+  const rightWs = path18.resolve(options.rightWorkspace);
+  const leftIndex = await readIndex(leftWs);
+  const rightIndex = await readIndex(rightWs);
+  const contextLines = typeof options.contextLines === "number" && options.contextLines >= 0 ? options.contextLines : 3;
+  const requestedPaths = options.paths && options.paths.length > 0 ? options.paths : void 0;
+  const leftPaths = requestedPaths ? requestedPaths : defaultArtifactPaths(leftIndex);
+  const rightPaths = requestedPaths ? requestedPaths : defaultArtifactPaths(rightIndex);
+  const paths = uniqueSorted([...leftPaths, ...rightPaths]);
+  const results = [];
+  let addedArtifacts = 0;
+  let removedArtifacts = 0;
+  let changedArtifacts = 0;
+  for (const rel of paths) {
+    const leftText = await readTextFile(path18.join(leftWs, rel));
+    const rightText = await readTextFile(path18.join(rightWs, rel));
+    if (leftText === null && rightText === null) {
+      continue;
+    }
+    if (leftText === null && rightText !== null) {
+      addedArtifacts++;
+      const diff = formatUnifiedDiff(rel, "", rightText, contextLines);
+      results.push({ path: rel, status: "added", diff });
+      continue;
+    }
+    if (leftText !== null && rightText === null) {
+      removedArtifacts++;
+      const diff = formatUnifiedDiff(rel, leftText, "", contextLines);
+      results.push({ path: rel, status: "removed", diff });
+      continue;
+    }
+    if (leftText !== rightText) {
+      changedArtifacts++;
+      const diff = formatUnifiedDiff(rel, leftText, rightText, contextLines);
+      results.push({ path: rel, status: "changed", diff });
+      continue;
+    }
+    results.push({ path: rel, status: "unchanged" });
+  }
+  const wf = diffWorkflow(leftIndex, rightIndex);
+  const summary = {
+    left: { name: leftIndex.workspaceName, path: leftWs },
+    right: { name: rightIndex.workspaceName, path: rightWs },
+    changedArtifacts,
+    addedArtifacts,
+    removedArtifacts,
+    changedSteps: wf.changedSteps
+  };
+  return {
+    summary,
+    artifacts: results.sort((a, b) => a.path.localeCompare(b.path)),
+    workflow: wf.changed ? { changed: true, details: wf.details } : { changed: false },
+    events: diffEvents(leftIndex, rightIndex)
+  };
+}
+function formatDiffResult(result, format) {
+  const lines = [];
+  const s = result.summary;
+  lines.push(`left:  ${s.left.name}	${s.left.path}`);
+  lines.push(`right: ${s.right.name}	${s.right.path}`);
+  lines.push(
+    `artifacts: changed=${s.changedArtifacts} added=${s.addedArtifacts} removed=${s.removedArtifacts} stepsChanged=${s.changedSteps}`
+  );
+  if (result.workflow?.changed) {
+    lines.push("");
+    lines.push("workflow: changed");
+    if (result.workflow.details) lines.push(result.workflow.details);
+  }
+  if (result.events) {
+    lines.push("");
+    lines.push(`events: left=${result.events.leftCount} right=${result.events.rightCount} added=${result.events.added}`);
+    if (result.events.latestRight) {
+      lines.push(`latest: ${result.events.latestRight.ts}	${result.events.latestRight.summary}`);
+    }
+  }
+  for (const a of result.artifacts) {
+    if (a.status === "unchanged") continue;
+    lines.push("");
+    lines.push(`${a.status}: ${a.path}`);
+    if (a.diff) {
+      if (format === "markdown") {
+        lines.push("```diff");
+        lines.push(a.diff);
+        lines.push("```");
+      } else {
+        lines.push(a.diff);
+      }
+    }
+  }
+  return lines.join("\n");
+}
+
+// src/cli/commands/diff.ts
+function collect2(value, previous = []) {
+  return previous.concat([value]);
+}
+async function resolveWorkspaceToken(token) {
+  const resolved = path19.resolve(token);
+  const items = await listWorkspaces().catch(() => []);
+  const byName = items.find((i) => i.name === token);
+  if (byName) return byName.path;
+  return resolved;
+}
+var diffCommand = new Command11("diff").description("\u5BF9\u4E24\u4E2A workspace \u8FDB\u884C diff\uFF08\u57FA\u4E8E index.json\uFF09").argument("<left>", "\u5DE6\u4FA7 workspace\uFF08path \u6216 registry name\uFF09").argument("<right>", "\u53F3\u4FA7 workspace\uFF08path \u6216 registry name\uFF09").option("--format <format>", "\u8F93\u51FA\u683C\u5F0F\uFF1Atext|markdown|json", "text").option("--path <path>", "\u4EC5\u5BF9\u6307\u5B9A\u6587\u4EF6\u505A diff\uFF08\u53EF\u91CD\u590D\uFF09", collect2, []).option("--context <n>", "diff context \u884C\u6570", (v) => parseInt(v, 10)).action(
+  async (left, right, options) => {
+    try {
+      const leftPath = await resolveWorkspaceToken(left);
+      const rightPath = await resolveWorkspaceToken(right);
+      const format = options.format === "markdown" || options.format === "json" ? options.format : "text";
+      const paths = options.path && options.path.length > 0 ? options.path : void 0;
+      const result = await diffWorkspaces({
+        leftWorkspace: leftPath,
+        rightWorkspace: rightPath,
+        format,
+        paths,
+        contextLines: options.context
+      });
+      if (format === "json") {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
+      console.log(formatDiffResult(result, format));
+    } catch (error) {
+      console.error(`Error: ${error}`);
+      process.exit(1);
+    }
+  }
+);
+
+// src/cli/commands/stats.ts
+import { Command as Command12 } from "commander";
+import path21 from "path";
+
+// src/core/stats/stats.ts
+import fs17 from "fs/promises";
+import path20 from "path";
+async function readIndex2(workspacePath) {
+  const abs = path20.resolve(workspacePath);
+  const indexPath = path20.join(abs, ".agenthandoff", "index.json");
+  try {
+    const raw = await fs17.readFile(indexPath, "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function countEventsByType(events) {
+  const counts = {};
+  for (const ev of events) {
+    const type = ev.type || "unknown";
+    counts[type] = (counts[type] || 0) + 1;
+  }
+  return counts;
+}
+function buildDurations(events) {
+  const map = /* @__PURE__ */ new Map();
+  for (const ev of events) {
+    if (!ev.stepId || !ev.type || !ev.ts) continue;
+    const key = ev.stepId;
+    const current = map.get(key) || {};
+    if (ev.type === "step.started") {
+      if (!current.startedAt || ev.ts < current.startedAt) current.startedAt = ev.ts;
+    }
+    if (ev.type === "step.done") {
+      if (!current.doneAt || ev.ts > current.doneAt) current.doneAt = ev.ts;
+    }
+    map.set(key, current);
+  }
+  const items = [];
+  for (const [stepId, v] of map.entries()) {
+    let durationMs;
+    if (v.startedAt && v.doneAt) {
+      const start = new Date(v.startedAt).getTime();
+      const end = new Date(v.doneAt).getTime();
+      if (!Number.isNaN(start) && !Number.isNaN(end) && end >= start) {
+        durationMs = end - start;
+      }
+    }
+    items.push({ stepId, startedAt: v.startedAt, doneAt: v.doneAt, ...durationMs !== void 0 && { durationMs } });
+  }
+  return items.sort((a, b) => a.stepId.localeCompare(b.stepId));
+}
+function buildWorkspaceStats(index, mode) {
+  const steps = index.steps || [];
+  const stepsTotal = steps.length;
+  const stepsDone = steps.filter((s) => Boolean(s.outputExists)).length;
+  const events = index.events || [];
+  const eventsTotal = events.length;
+  const eventsByType = countEventsByType(events);
+  const automationSessions = events.filter((e) => e.type === "automation.session").length;
+  const stats = {
+    workspaceName: index.workspaceName,
+    workspacePath: index.workspacePath,
+    indexedAt: index.indexedAt,
+    stepsTotal,
+    stepsDone,
+    eventsTotal,
+    eventsByType,
+    automation: {
+      sessions: automationSessions,
+      summary: {}
+    }
+  };
+  if (mode === "full") {
+    stats.durations = buildDurations(events);
+  }
+  return stats;
+}
+async function buildStats(query) {
+  const workspaces = query.workspaces || [];
+  const results = [];
+  for (const ws of workspaces) {
+    const index = await readIndex2(ws);
+    if (!index) continue;
+    results.push(buildWorkspaceStats(index, query.mode));
+  }
+  return {
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    workspaces: results
+  };
+}
+
+// src/cli/commands/stats.ts
+function isValidFormat(value) {
+  return value === "json" || value === "markdown";
+}
+async function resolveWorkspaceToken2(token) {
+  const resolved = path21.resolve(token);
+  const items = await listWorkspaces().catch(() => []);
+  const byName = items.find((i) => i.name === token);
+  return byName ? byName.path : resolved;
+}
+function formatMarkdown(result) {
+  const lines = [];
+  lines.push("| Workspace | Steps | Events | Automation |");
+  lines.push("|---|---|---|---|");
+  for (const ws of result.workspaces) {
+    const steps = `${ws.stepsDone}/${ws.stepsTotal}`;
+    const events = `${ws.eventsTotal}`;
+    const automation = `${ws.automation?.sessions ?? 0}`;
+    lines.push(`| ${ws.workspaceName} | ${steps} | ${events} | ${automation} |`);
+  }
+  if (result.workspaces.length === 0) {
+    lines.push("| - | - | - | - |");
+  }
+  return lines.join("\n");
+}
+var statsCommand = new Command12("stats").description("\u8F93\u51FA workspace \u7EDF\u8BA1\u4FE1\u606F").argument("[workspaces...]", "workspace \u8DEF\u5F84\u6216 registry name").option("--registry", "\u7EDF\u8BA1 registry \u4E2D\u6240\u6709 workspace").option("--mode <mode>", "summary|full", "summary").option("--format <format>", "json|markdown", "markdown").action(
+  async (workspaces, options) => {
+    try {
+      const mode = options.mode === "full" ? "full" : "summary";
+      const format = isValidFormat(options.format) ? options.format : "markdown";
+      let targets = [];
+      if (options.registry) {
+        const items = await listWorkspaces();
+        targets = items.map((i) => i.path);
+      } else if (workspaces.length > 0) {
+        targets = await Promise.all(workspaces.map(resolveWorkspaceToken2));
+      }
+      if (targets.length === 0) {
+        console.log("\u672A\u627E\u5230\u53EF\u7EDF\u8BA1\u7684 workspace");
+        return;
+      }
+      const result = await buildStats({ workspaces: targets, mode });
+      if (format === "json") {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
+      console.log(formatMarkdown(result));
+    } catch (error) {
+      console.error(`Error: ${error}`);
+      process.exit(1);
+    }
+  }
+);
+
 // src/index.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
-var program = new Command9();
+var program = new Command13();
 program.name("agent-handoff").description("\u8F7B\u91CF\u7EA7\u591A Agent \u534F\u4F5C\u63A5\u529B\u5DE5\u5177").version(version);
 program.addCommand(initCommand);
 program.addCommand(statusCommand);
@@ -1790,5 +2680,9 @@ program.addCommand(advanceCommand);
 program.addCommand(configCommand);
 program.addCommand(reportCommand);
 program.addCommand(exportCommand);
+program.addCommand(indexCommand);
+program.addCommand(searchCommand);
+program.addCommand(diffCommand);
+program.addCommand(statsCommand);
 program.parse();
 //# sourceMappingURL=index.js.map