@iderouter/index-mcp 0.2.0-beta.1

package/scripts/benchmark-single-priority-chunk-embed.mjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { promisify } from "node:util";
+
+import { createBenchmarkSnapshot } from "./lib/benchmark-snapshot.mjs";
+
+const execFileAsync = promisify(execFile);
+const TARGET_PATH = path.resolve(process.argv[2] || process.cwd());
+const MODEL = String(process.env.IDEROUTER_BENCH_SINGLE_CHUNK_MODEL || "openai/text-embedding-3-small").trim();
+const TIMEOUT_MS = Number(process.env.IDEROUTER_BENCH_SINGLE_CHUNK_TIMEOUT_MS || 60000);
+const RELATIVE_PATH = "relay/common/relay_info.go";
+
+function compactAlphaNum(value) {
+  return String(value || "").toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+
+function snippetWindow(content, start, size) {
+  const safeStart = Math.max(0, start);
+  const safeEnd = Math.min(content.length, safeStart + Math.max(1, size));
+  return {
+    start: safeStart,
+    end: safeEnd,
+    content: content.slice(safeStart, safeEnd).trim(),
+  };
+}
+
+function buildLineOffsets(content) {
+  const offsets = [0];
+  for (let i = 0; i < content.length; i += 1) {
+    if (content.charCodeAt(i) === 10) offsets.push(i + 1);
+  }
+  return offsets;
+}
+
+function lineForOffsetFromIndex(lineOffsets, offset) {
+  let low = 0;
+  let high = lineOffsets.length - 1;
+  while (low <= high) {
+    const mid = (low + high) >> 1;
+    if (lineOffsets[mid] <= offset) {
+      low = mid + 1;
+    } else {
+      high = mid - 1;
+    }
+  }
+  return Math.max(1, high + 1);
+}
+
+function extractPrimaryChunk(content, relativePath) {
+  const compactContent = compactAlphaNum(content);
+  const anchorTerm = "streamsupportedchannels";
+  if (!compactContent.includes(anchorTerm)) {
+    throw new Error(`anchor term ${anchorTerm} not found in ${relativePath}`);
+  }
+  const rawLower = String(content || "").toLowerCase();
+  const first = rawLower.indexOf(anchorTerm);
+  const chunkSize = 520;
+  const window = snippetWindow(content, Math.max(0, first), chunkSize);
+  const lineOffsets = buildLineOffsets(content);
+  return {
+    relativePath,
+    startLine: lineForOffsetFromIndex(lineOffsets, window.start),
+    endLine: lineForOffsetFromIndex(lineOffsets, window.end),
+    content: window.content,
+  };
+}
+
+async function postEmbeddingWithCurl({ endpoint, apiKey, model, input, timeoutMs }) {
+  const timeoutSeconds = Math.max(1, Math.ceil(timeoutMs / 1000));
+  const marker = "\n__IDEROUTER_HTTP_STATUS__:";
+  const payload = JSON.stringify({
+    model,
+    input: [input],
+  });
+  const args = [
+    "-sS",
+    "-X", "POST",
+    "--connect-timeout", String(Math.min(15, timeoutSeconds)),
+    "--max-time", String(timeoutSeconds),
+    "-H", "Content-Type: application/json",
+    "-H", `Authorization: Bearer ${apiKey}`,
+    "--data-binary", "@-",
+    "-w", `${marker}%{http_code}`,
+    endpoint,
+  ];
+  const startedAt = Date.now();
+  const { stdout } = await execFileAsync("curl", args, {
+    input: payload,
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  const wallMs = Date.now() - startedAt;
+  const output = String(stdout || "");
+  const markerIndex = output.lastIndexOf(marker);
+  if (markerIndex < 0) {
+    throw new Error("curl did not return HTTP status marker");
+  }
+  const responseBody = output.slice(0, markerIndex);
+  const status = Number(output.slice(markerIndex + marker.length).trim());
+  return {
+    status,
+    wall_ms: wallMs,
+    response_preview: responseBody.slice(0, 500),
+  };
+}
+
+async function main() {
+  const apiKey = process.env.IDEROUTER_API_KEY;
+  if (!apiKey) {
+    throw new Error("IDEROUTER_API_KEY is required");
+  }
+  const baseURL = process.env.IDEROUTER_BASE_URL || "https://cursor.iderouter.com/v1";
+  const endpoint = `${baseURL.replace(/\/+$/, "")}/embeddings`;
+  const snapshot = await createBenchmarkSnapshot(TARGET_PATH, process.env);
+  const filePath = path.join(snapshot.snapshotDir, RELATIVE_PATH);
+  try {
+    const content = await fs.readFile(filePath, "utf8");
+    const chunk = extractPrimaryChunk(content, RELATIVE_PATH);
+    const result = await postEmbeddingWithCurl({
+      endpoint,
+      apiKey,
+      model: MODEL,
+      input: chunk.content,
+      timeoutMs: TIMEOUT_MS,
+    });
+    process.stdout.write(`${JSON.stringify({
+      path: TARGET_PATH,
+      snapshot_path: snapshot.snapshotDir,
+      model: MODEL,
+      timeout_ms: TIMEOUT_MS,
+      chunk,
+      result,
+    }, null, 2)}\n`);
+  } finally {
+    await fs.rm(snapshot.snapshotDir, { recursive: true, force: true });
+  }
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});

package/scripts/benchmark-small-change.mjs

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+
+import fs from "node:fs/promises";
+import { execFile } from "node:child_process";
+import crypto from "node:crypto";
+import path from "node:path";
+import process from "node:process";
+import { promisify } from "node:util";
+import { runIndexBenchmark } from "./lib/mcp-bench.mjs";
+
+const execFileAsync = promisify(execFile);
+const TARGET_PATH = path.resolve(process.argv[2] || process.cwd());
+const TIMEOUT_MS = Number(process.env.IDEROUTER_BENCH_TIMEOUT_MS || 30000);
+const POLL_MS = Number(process.env.IDEROUTER_BENCH_POLL_MS || 500);
+const DEFAULT_EXTENSIONS = new Set([
+  ".c", ".cc", ".cpp", ".cs", ".css", ".go", ".graphql", ".h", ".hpp", ".html",
+  ".java", ".js", ".json", ".jsx", ".kt", ".kts", ".md", ".mjs", ".php", ".proto",
+  ".py", ".rb", ".rs", ".scss", ".sh", ".sql", ".swift", ".toml", ".ts", ".tsx",
+  ".vue", ".xml", ".yaml", ".yml",
+]);
+const PREFERRED_MUTATION_PATHS = [
+  "relay/common/relay_info.go",
+  "relay/compatible_handler.go",
+  "service/user_memory.go",
+  "pkg/billingexpr/run.go",
+  "service/tiered_settle.go",
+  "relay/helper/price.go",
+];
+const EXTENSION_PRIORITY = new Map([
+  [".go", 0],
+  [".ts", 1],
+  [".tsx", 2],
+  [".js", 3],
+  [".jsx", 4],
+  [".json", 5],
+  [".sql", 6],
+  [".yaml", 7],
+  [".yml", 8],
+  [".md", 20],
+]);
+
+function repoId(codebasePath) {
+  return crypto.createHash("sha256").update(path.resolve(codebasePath)).digest("hex").slice(0, 16);
+}
+
+async function loadIndexedFiles() {
+  const metaPath = path.join(process.env.HOME, ".iderouter/index-mcp/indexes", `${repoId(TARGET_PATH)}.meta.json`);
+  const content = await fs.readFile(metaPath, "utf8");
+  const meta = JSON.parse(content);
+  return Array.isArray(meta.files) ? meta.files.map((file) => file.relativePath).filter(Boolean) : [];
+}
+
+async function gitDirtyPaths() {
+  const { stdout } = await execFileAsync(
+    "git",
+    ["-C", TARGET_PATH, "status", "--porcelain=v1", "-z", "--untracked-files=all"],
+    { maxBuffer: 16 * 1024 * 1024 },
+  );
+  return new Set(
+    String(stdout || "")
+      .split("\0")
+      .filter(Boolean)
+      .map((entry) => entry.slice(3).trim())
+      .filter(Boolean),
+  );
+}
+
+async function selectMutationFile() {
+  if (process.env.IDEROUTER_BENCH_MUTATION_FILE) {
+    return path.join(TARGET_PATH, process.env.IDEROUTER_BENCH_MUTATION_FILE);
+  }
+  const indexedFiles = await loadIndexedFiles();
+  const dirtyPaths = await gitDirtyPaths();
+  const preferred = PREFERRED_MUTATION_PATHS.find((relativePath) => indexedFiles.includes(relativePath) && !dirtyPaths.has(relativePath));
+  if (preferred) return path.join(TARGET_PATH, preferred);
+  const candidate = indexedFiles
+    .filter((relativePath) => {
+      const ext = path.extname(relativePath);
+      return DEFAULT_EXTENSIONS.has(ext) && !dirtyPaths.has(relativePath);
+    })
+    .sort((a, b) => candidateScore(a) - candidateScore(b))[0];
+  if (!candidate) {
+    throw new Error("No clean indexed file available for benchmark-small-change");
+  }
+  return path.join(TARGET_PATH, candidate);
+}
+
+function candidateScore(relativePath) {
+  const ext = path.extname(relativePath);
+  let score = EXTENSION_PRIORITY.get(ext) ?? 50;
+  if (relativePath.startsWith(".github/")) score += 100;
+  if (relativePath.includes("/docs/") || relativePath.endsWith(".md")) score += 30;
+  return score;
+}
+
+async function mutateBenchmarkFile(benchFile) {
+  const previous = await fs.readFile(benchFile, "utf8");
+  const next = `${previous}\n<!-- iderouter bench ${new Date().toISOString()} -->\n`;
+  await fs.writeFile(benchFile, next, "utf8");
+  return async () => {
+    await fs.writeFile(benchFile, previous, "utf8");
+  };
+}
+
+async function gitStatusForMutationFile(benchFile) {
+  const relativePath = path.relative(TARGET_PATH, benchFile);
+  const { stdout } = await execFileAsync(
+    "git",
+    ["-C", TARGET_PATH, "status", "--porcelain=v1", "--untracked-files=all", "--", relativePath],
+  );
+  return String(stdout || "").trim();
+}
+
+async function main() {
+  const benchFile = await selectMutationFile();
+  const restore = await mutateBenchmarkFile(benchFile);
+  try {
+    const gitStatus = await gitStatusForMutationFile(benchFile);
+    const result = await runIndexBenchmark({
+      targetPath: TARGET_PATH,
+      timeoutMs: TIMEOUT_MS,
+      pollMs: POLL_MS,
+      startArgs: { path: TARGET_PATH, wait: false, cloud: false },
+    });
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          ...result.parsed,
+          mutation_file: path.relative(TARGET_PATH, benchFile),
+          preflight_git_status: gitStatus,
+          expected_dirty: Boolean(gitStatus),
+          observed_index_change: !/files_changed=0\b/.test(result.finalText),
+        },
+        null,
+        2,
+      )}\n`,
+    );
+  } finally {
+    await restore();
+  }
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});

package/scripts/benchmark-stage-summary.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+
+import { execFile } from "node:child_process";
+import path from "node:path";
+import process from "node:process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const TARGET_PATH = path.resolve(process.argv[2] || process.cwd());
+const SCRIPT_DIR = path.resolve("scripts");
+
+async function runScript(scriptName) {
+  const scriptPath = path.join(SCRIPT_DIR, scriptName);
+  const { stdout } = await execFileAsync(process.execPath, [scriptPath, TARGET_PATH], {
+    cwd: process.cwd(),
+    env: process.env,
+    maxBuffer: 8 * 1024 * 1024,
+  });
+  return JSON.parse(String(stdout || "").trim());
+}
+
+async function main() {
+  const priority = await runScript("benchmark-priority-ready-search.mjs");
+  const resume = await runScript("benchmark-background-fine-resume.mjs");
+  const priorityTop1Hits = Array.isArray(priority?.searches)
+    ? priority.searches.filter((item) => item.top1_hit).length
+    : 0;
+  const priorityTotalQueries = Array.isArray(priority?.searches) ? priority.searches.length : 0;
+  const priorityHitRatio = priorityTotalQueries > 0 ? priorityTop1Hits / priorityTotalQueries : 0;
+  const priorityReadyMs = Number(priority?.priority_ready?.parsed?.priority_ready_ms || 0);
+  const priorityReadyAnchorCoverage = priority?.priority_ready_anchor_coverage || {};
+  const resumeSemanticFiles = Number(resume?.summary?.cumulative_file_count || 0);
+  const resumeRoundsRun = Number(resume?.summary?.rounds_run || 0);
+  const resumeRounds = Array.isArray(resume?.rounds) ? resume.rounds : [];
+  const resumeDeferContinuity = resumeRoundsRun > 1
+    ? resumeRounds.slice(1).filter((round) => Number(round?.fine_semantic_files || 0) > Number(resumeRounds[round.round - 2]?.fine_semantic_files || 0)).length / Math.max(1, resumeRoundsRun - 1)
+    : 0;
+  const priorityScore = Math.max(0, Math.min(1, priorityReadyMs > 0 ? 1 - ((priorityReadyMs - 6000) / 12000) : 0));
+  const coverageScore = Math.max(0, Math.min(1, resumeSemanticFiles / 80));
+  const compositeScore = Number(((priorityHitRatio * 0.4) + (priorityScore * 0.25) + (coverageScore * 0.2) + (resumeDeferContinuity * 0.15)).toFixed(3));
+  const compositeBand = compositeScore >= 0.9
+    ? "strong"
+    : compositeScore >= 0.8
+      ? "good"
+      : compositeScore >= 0.65
+        ? "developing"
+        : "weak";
+
+  process.stdout.write(
+    `${JSON.stringify(
+      {
+        path: TARGET_PATH,
+        priority_ready_ms: priorityReadyMs || null,
+        priority_ready_wall_ms: priority?.priority_ready?.wallMs ?? null,
+        priority_top1_hits: priorityTop1Hits,
+        priority_total_queries: priorityTotalQueries,
+        priority_ready_anchor_completed: Number(priorityReadyAnchorCoverage.completed || 0),
+        priority_ready_anchor_total: Number(priorityReadyAnchorCoverage.total || 0),
+        priority_ready_anchor_completed_paths: Array.isArray(priorityReadyAnchorCoverage.completed_paths) ? priorityReadyAnchorCoverage.completed_paths : [],
+        priority_ready_anchor_pending_paths: Array.isArray(priorityReadyAnchorCoverage.pending_paths) ? priorityReadyAnchorCoverage.pending_paths : [],
+        resume_rounds_run: resumeRoundsRun,
+        resume_cursor_sequence: resume?.summary?.cursor_sequence ?? [],
+        resume_cumulative_semantic_files: resumeSemanticFiles,
+        composite_score: compositeScore,
+        composite_band: compositeBand,
+        resume_rounds: resumeRounds
+          ? resumeRounds.map((round) => ({
+            round: round.round,
+            fine_semantic_files: round.fine_semantic_files,
+            fine_semantic_chunks: round.fine_semantic_chunks,
+            background_bucket_cursor: round.background_bucket_cursor,
+            priority_ready_anchor_coverage: round.priority_ready_anchor_coverage,
+            embedding_requests: round?.diagnostics?.embedding_requests ?? 0,
+            embedding_request_ms_total: round?.diagnostics?.embedding_request_ms_total ?? 0,
+            deferred: round.deferred,
+          }))
+          : [],
+      },
+      null,
+      2,
+    )}\n`,
+  );
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});

package/scripts/lib/auto-continuation-state.mjs

@@ -0,0 +1,34 @@
+export function hasAdvanced(beforeState, afterState) {
+  return (
+    Number(afterState.fine_semantic_files || 0) > Number(beforeState.fine_semantic_files || 0) ||
+    Number(afterState.fine_semantic_chunks || 0) > Number(beforeState.fine_semantic_chunks || 0) ||
+    String(afterState.background_bucket_cursor || "") !== String(beforeState.background_bucket_cursor || "") ||
+    (
+      Number(afterState.total_chunks || 0) > 0 &&
+      String(afterState.job_status || "") === "indexing" &&
+      String(afterState.current_step || "").toLowerCase().includes("embedding batch")
+    )
+  );
+}
+
+export function isFullReadyState(state) {
+  const modes = String(state?.searchable_modes || "");
+  return modes.includes("full_semantic") || /^Indexed\b/.test(String(state?.status_text || ""));
+}
+
+export function isCoarseDeferredReady(state) {
+  const text = String(state?.status_text || "");
+  return /^Coarse lexical index is ready\b/.test(text) &&
+    text.includes("semantic indexing is temporarily deferred");
+}
+
+export function continuationAlreadyMaterialized(firstPhaseState) {
+  return (
+    isFullReadyState(firstPhaseState) ||
+    (
+      Number(firstPhaseState.continuation_pass_count || 0) > 0 &&
+      Number(firstPhaseState.fine_semantic_files || 0) > 3 &&
+      Number(firstPhaseState.fine_semantic_chunks || 0) > 3
+    )
+  );
+}

package/scripts/lib/benchmark-query-packs.mjs

@@ -0,0 +1,123 @@
+const PACKS = {
+  core: [
+    {
+      name: "user_memory_flow",
+      query: "user memory flow",
+      expect_any: [
+        "service/user_memory.go",
+        "relay/compatible_handler.go",
+        "relay/claude_handler.go",
+      ],
+    },
+    {
+      name: "remove_disabled_fields",
+      query: "relay_info compatible_handler remove_disabled_request_fields safety_identifier include_obfuscation",
+      expect_any: [
+        "relay/common/relay_info.go",
+        "relay/compatible_handler.go",
+      ],
+    },
+    {
+      name: "billing_execution_path",
+      query: "billing backend execution path RunExprWithRequest model pricing editor",
+      expect_any: [
+        "pkg/billingexpr/run.go",
+        "relay/helper/price.go",
+        "service/tiered_settle.go",
+      ],
+    },
+    {
+      name: "privacy_request_flow",
+      query: "relay request filtering privacy fields flow",
+      expect_any: [
+        "relay/common/relay_info.go",
+        "relay/compatible_handler.go",
+      ],
+    },
+    {
+      name: "stream_options_support",
+      query: "stream options support handling",
+      expect_any: [
+        "relay/compatible_handler.go",
+        "relay/common/relay_info.go",
+      ],
+    },
+  ],
+  real_user: [
+    {
+      name: "relay_architecture",
+      query: "relay architecture overview request flow controller service model",
+      expect_any: [
+        "controller/relay.go",
+        "relay/compatible_handler.go",
+        "relay/common/relay_info.go",
+      ],
+    },
+    {
+      name: "billing_settlement_chain",
+      query: "how tiered billing settlement works quota pricing chain",
+      expect_any: [
+        "pkg/billingexpr/run.go",
+        "service/tiered_settle.go",
+        "relay/helper/price.go",
+      ],
+    },
+    {
+      name: "user_memory_entrypoints",
+      query: "where user memory gets injected into requests and prompts",
+      expect_any: [
+        "service/user_memory.go",
+        "relay/compatible_handler.go",
+        "controller/user_memory.go",
+      ],
+    },
+    {
+      name: "stream_options_definitions",
+      query: "which files define and force stream options support",
+      expect_any: [
+        "relay/compatible_handler.go",
+        "relay/common/relay_info.go",
+        "relay/channel/ali/adaptor.go",
+      ],
+    },
+    {
+      name: "privacy_field_filtering",
+      query: "how disabled request fields privacy identifiers are filtered before upstream relay",
+      expect_any: [
+        "relay/common/relay_info.go",
+        "relay/compatible_handler.go",
+      ],
+    },
+    {
+      name: "agent_config_path",
+      query: "where agent defaults and model configuration are defined",
+      expect_any: [
+        "setting/iderouter_setting/agent.go",
+        "dto/iderouter_agent.go",
+        "controller/iderouter.go",
+      ],
+    },
+    {
+      name: "index_mcp_config",
+      query: "where index mcp strategy and installation config are built",
+      expect_any: [
+        "service/iderouter_index.go",
+        "iderouter_frontend/lib/iderouter-api.ts",
+        "iderouter_index_mcp/src/index.js",
+      ],
+    },
+  ],
+};
+
+export function listBenchmarkQueryPackNames() {
+  return Object.keys(PACKS);
+}
+
+export function getBenchmarkQueryPack(name = "core") {
+  const key = String(name || "core").trim().toLowerCase();
+  const pack = PACKS[key];
+  if (!pack) {
+    throw new Error(`Unknown benchmark query pack: ${name}`);
+  }
+  return pack.map((item) => ({ ...item, expect_any: [...item.expect_any] }));
+}

package/scripts/lib/benchmark-snapshot.mjs

@@ -0,0 +1,109 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+export function resolveBenchmarkSnapshotMode(env = process.env) {
+  const raw = String(env?.IDEROUTER_BENCH_SNAPSHOT_MODE || "").trim().toLowerCase();
+  if (raw === "head" || raw === "clean_head" || raw === "clean-head") return "head";
+  return "working_tree";
+}
+
+export function createSnapshotPlan(targetPath, env = process.env) {
+  const mode = resolveBenchmarkSnapshotMode(env);
+  return {
+    targetPath,
+    mode,
+    label: mode,
+    tempPrefix: mode === "head" ? "iderouter-bench-head-" : "iderouter-bench-worktree-",
+  };
+}
+
+function splitNullTerminated(stdout) {
+  return String(stdout || "")
+    .split("\0")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+async function gitNullList(sourcePath, args) {
+  const { stdout } = await execFileAsync("git", ["-C", sourcePath, ...args], {
+    maxBuffer: 16 * 1024 * 1024,
+  });
+  return splitNullTerminated(stdout);
+}
+
+async function exportTrackedFilesFromIndex(sourcePath, destinationPath) {
+  await execFileAsync("git", [
+    "-C",
+    sourcePath,
+    "checkout-index",
+    "-a",
+    "-f",
+    `--prefix=${destinationPath}/`,
+  ], {
+    maxBuffer: 16 * 1024 * 1024,
+  });
+}
+
+async function overlayWorkingTreeFiles(sourcePath, destinationPath, relativePaths) {
+  for (const relativePath of relativePaths) {
+    const sourceFile = path.join(sourcePath, relativePath);
+    const destinationFile = path.join(destinationPath, relativePath);
+    await fs.mkdir(path.dirname(destinationFile), { recursive: true });
+    await fs.cp(sourceFile, destinationFile, {
+      force: true,
+      recursive: false,
+      verbatimSymlinks: true,
+    });
+  }
+}
+
+async function removeDeletedWorkingTreeFiles(destinationPath, relativePaths) {
+  for (const relativePath of relativePaths) {
+    await fs.rm(path.join(destinationPath, relativePath), { force: true, recursive: true });
+  }
+}
+
+async function copyWorkingTree(sourcePath, destinationPath) {
+  await exportTrackedFilesFromIndex(sourcePath, destinationPath);
+  const [modifiedTrackedFiles, untrackedFiles, deletedTrackedFiles] = await Promise.all([
+    gitNullList(sourcePath, ["ls-files", "-m", "-z"]),
+    gitNullList(sourcePath, ["ls-files", "-o", "--exclude-standard", "-z"]),
+    gitNullList(sourcePath, ["ls-files", "-d", "-z"]),
+  ]);
+  await overlayWorkingTreeFiles(
+    sourcePath,
+    destinationPath,
+    Array.from(new Set([...modifiedTrackedFiles, ...untrackedFiles])),
+  );
+  await removeDeletedWorkingTreeFiles(destinationPath, deletedTrackedFiles);
+}
+
+async function cloneHeadSnapshot(sourcePath, destinationPath) {
+  await execFileAsync("git", ["clone", "--shared", "--no-checkout", sourcePath, destinationPath], {
+    cwd: sourcePath,
+    maxBuffer: 16 * 1024 * 1024,
+  });
+  await execFileAsync("git", ["-C", destinationPath, "checkout", "-f", "HEAD"], {
+    cwd: sourcePath,
+    maxBuffer: 16 * 1024 * 1024,
+  });
+}
+
+export async function createBenchmarkSnapshot(targetPath, env = process.env) {
+  const plan = createSnapshotPlan(targetPath, env);
+  const snapshotDir = await fs.mkdtemp(path.join(os.tmpdir(), plan.tempPrefix));
+  if (plan.mode === "head") {
+    await cloneHeadSnapshot(targetPath, snapshotDir);
+  } else {
+    await copyWorkingTree(targetPath, snapshotDir);
+  }
+  return {
+    ...plan,
+    snapshotDir,
+  };
+}