@nema-project/nema 0.0.0-stage → 0.1.4

package/dist/repos/git.js

@@ -0,0 +1,370 @@
+import {
+  runHelperFile
+} from "../chunks/chunk-WT3XUFWU.js";
+import {
+  isBranchName
+} from "../chunks/chunk-HEIQINX3.js";
+
+// repos/git.js
+import { execFile } from "node:child_process";
+import { lstat, mkdir, mkdtemp, readdir, realpath, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { windowsRuntimeEnv } from "../platform.js";
+var MAX_LINES = 400;
+var MAX_BYTES = 65536;
+var SHA_RE = /^[0-9a-f]{7,40}$/;
+var MAX_BUFFER = 256 * 1024 * 1024;
+function commandEnv() {
+  return {
+    ...windowsRuntimeEnv(process.env),
+    PATH: process.env.PATH ?? "",
+    HOME: process.env.HOME ?? "",
+    LANG: process.env.LANG ?? "",
+    GIT_TERMINAL_PROMPT: "0",
+    GIT_SSH_COMMAND: "ssh -o BatchMode=yes",
+    ...process.env.SSH_AUTH_SOCK ? { SSH_AUTH_SOCK: process.env.SSH_AUTH_SOCK } : {}
+  };
+}
+function stripUserinfo(url) {
+  return url.replace(/^([a-z][a-z0-9+.-]*:\/\/)[^/?#]*@/i, "$1");
+}
+function execBuf(cmd, args, opts) {
+  if (opts?.ownedHelpers) {
+    return runHelperFile(cmd, args, { env: commandEnv(), timeout: opts.timeout ?? 3e4, maxBuffer: MAX_BUFFER, encoding: "buffer" }, opts.ownedHelpers).then((result) => {
+      if (result.error)
+        throw Object.assign(result.error, { stdout: result.stdout, stderr: result.stderr });
+      return { stdout: result.stdout, stderr: result.stderr };
+    });
+  }
+  return new Promise((resolve, reject) => {
+    execFile(cmd, args, {
+      env: commandEnv(),
+      shell: false,
+      timeout: opts?.timeout ?? 3e4,
+      maxBuffer: MAX_BUFFER,
+      encoding: "buffer"
+    }, (err, stdout, stderr) => {
+      const out = Buffer.isBuffer(stdout) ? stdout : Buffer.from(stdout ?? "");
+      const errOut = Buffer.isBuffer(stderr) ? stderr : Buffer.from(stderr ?? "");
+      if (err) {
+        reject(Object.assign(err, { stdout: out, stderr: errOut }));
+        return;
+      }
+      resolve({ stdout: out, stderr: errOut });
+    });
+  });
+}
+function errorText(e) {
+  if (e && typeof e === "object" && "stderr" in e) {
+    const stderr = e.stderr;
+    const text = Buffer.isBuffer(stderr) ? stderr.toString("utf8") : String(stderr ?? "");
+    const trimmed = text.trim();
+    if (trimmed)
+      return trimmed;
+  }
+  return e instanceof Error ? e.message.trim() : String(e);
+}
+async function gitRaw(repoPath, args, timeout, ownedHelpers) {
+  const { stdout } = await execBuf("git", ["-C", repoPath, ...args], { timeout, ownedHelpers });
+  return stdout;
+}
+async function gitText(repoPath, args, timeout, ownedHelpers) {
+  const text = (await gitRaw(repoPath, args, timeout, ownedHelpers)).toString("utf8");
+  return text.endsWith("\n") ? text.slice(0, -1) : text;
+}
+async function canonical(p) {
+  try {
+    return await realpath(p);
+  } catch {
+    return path.resolve(p);
+  }
+}
+function isUnder(child, parent) {
+  const rel = path.relative(parent, child);
+  return rel === "" || rel !== ".." && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel);
+}
+async function originHeadBranch(repoPath, ownedHelpers) {
+  try {
+    const ref = await gitText(repoPath, ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"], void 0, ownedHelpers);
+    if (ref.startsWith("origin/"))
+      return ref.slice("origin/".length) || "main";
+    return ref || "main";
+  } catch {
+    return "main";
+  }
+}
+function normalizeRepoPath(relPath) {
+  if (relPath === "" || path.isAbsolute(relPath))
+    throw new Error("\u8DEF\u5F84\u5FC5\u987B\u662F\u4ED3\u5E93\u5185\u7684\u76F8\u5BF9\u8DEF\u5F84");
+  const normalized = path.posix.normalize(relPath);
+  if (normalized.split("/").includes(".."))
+    throw new Error("\u8DEF\u5F84\u5FC5\u987B\u662F\u4ED3\u5E93\u5185\u7684\u76F8\u5BF9\u8DEF\u5F84");
+  return normalized;
+}
+function splitLines(text) {
+  if (text === "")
+    return [];
+  const parts = text.split("\n");
+  if (text.endsWith("\n"))
+    parts.pop();
+  return parts;
+}
+function cutUtf8(text, maxBytes) {
+  let bytes = 0;
+  let i = 0;
+  for (const ch of text) {
+    const n = Buffer.byteLength(ch);
+    if (bytes + n > maxBytes)
+      break;
+    bytes += n;
+    i += ch.length;
+  }
+  return text.slice(0, i);
+}
+function parseLsTree(buf) {
+  const rows = [];
+  for (const entry of buf.toString("utf8").split("\0")) {
+    if (!entry)
+      continue;
+    const tab = entry.indexOf("	");
+    if (tab < 0)
+      continue;
+    const [mode, type, sha] = entry.slice(0, tab).split(" ");
+    rows.push({ mode: mode ?? "", type: type ?? "", sha: sha ?? "", path: entry.slice(tab + 1) });
+  }
+  return rows;
+}
+function parseNameStatus(buf) {
+  const parts = buf.toString("utf8").split("\0");
+  if (parts.at(-1) === "")
+    parts.pop();
+  const rows = [];
+  for (let i = 0; i < parts.length; ) {
+    const status = parts[i++];
+    if (!status)
+      break;
+    const kind = status[0];
+    if (kind === "R" || kind === "C") {
+      const from = parts[i++] ?? "";
+      if (kind === "R")
+        rows.push({ status: "D", path: from });
+      rows.push({ status, path: parts[i++] ?? "" });
+    } else {
+      rows.push({ status, path: parts[i++] ?? "" });
+    }
+  }
+  return rows;
+}
+var TAR_BLOCK = 512;
+function tarSize(header) {
+  const raw = header.subarray(124, 136).toString("utf8").replace(/\0.*$/, "").trim();
+  if (!raw)
+    return 0;
+  const size = Number.parseInt(raw, 8);
+  return Number.isFinite(size) ? size : 0;
+}
+function tarSpan(buf, offset) {
+  if (offset + TAR_BLOCK > buf.length)
+    return null;
+  const header = buf.subarray(offset, offset + TAR_BLOCK);
+  if (header.every((b) => b === 0))
+    return { type: "\0", next: buf.length };
+  const size = tarSize(header);
+  const data = Math.ceil(size / TAR_BLOCK) * TAR_BLOCK;
+  return { type: String.fromCharCode(header[156] ?? 0), next: offset + TAR_BLOCK + data };
+}
+function stripSymlinkEntries(buf) {
+  const chunks = [];
+  const pending = [];
+  let i = 0;
+  while (i + TAR_BLOCK <= buf.length) {
+    const span = tarSpan(buf, i);
+    if (!span)
+      break;
+    if (span.type === "\0") {
+      chunks.push(buf.subarray(i));
+      break;
+    }
+    const entry = buf.subarray(i, span.next);
+    if (span.type === "x" || span.type === "L" || span.type === "K") {
+      pending.push(entry);
+      i = span.next;
+      continue;
+    }
+    if (span.type === "2") {
+      pending.length = 0;
+      i = span.next;
+      continue;
+    }
+    chunks.push(...pending, entry);
+    pending.length = 0;
+    i = span.next;
+  }
+  chunks.push(...pending);
+  return Buffer.concat(chunks);
+}
+async function emptyDir(destDir) {
+  await mkdir(destDir, { recursive: true });
+  const st = await lstat(destDir);
+  if (st.isSymbolicLink())
+    throw new Error("destDir is a symlink");
+  if (!st.isDirectory())
+    throw new Error("destDir is not a directory");
+  for (const name of await readdir(destDir)) {
+    await rm(path.join(destDir, name), { recursive: true, force: true });
+  }
+}
+async function inspectRepo(repoPath, nemaHome, ownedHelpers) {
+  const real = await canonical(repoPath);
+  const home = await canonical(nemaHome);
+  if (isUnder(real, home))
+    throw new Error("\u4E0D\u80FD\u7ED1\u5B9A ~/.nema \u4E4B\u4E0B\u7684\u76EE\u5F55");
+  if (isUnder(home, real))
+    throw new Error("\u4E0D\u80FD\u7ED1\u5B9A\u5305\u542B ~/.nema \u7684\u76EE\u5F55");
+  let toplevel;
+  try {
+    toplevel = await gitText(repoPath, ["rev-parse", "--show-toplevel"], void 0, ownedHelpers);
+  } catch {
+    throw new Error("\u4E0D\u662F git \u4ED3\u5E93\u7684\u6839\u76EE\u5F55");
+  }
+  const root = await canonical(toplevel);
+  if (root !== real)
+    throw new Error("\u4E0D\u662F git \u4ED3\u5E93\u7684\u6839\u76EE\u5F55");
+  const commonRaw = await gitText(repoPath, ["rev-parse", "--git-common-dir"], void 0, ownedHelpers);
+  const commonAbs = path.isAbsolute(commonRaw) ? commonRaw : path.resolve(root, commonRaw);
+  const gitCommonDir = await canonical(commonAbs);
+  const rawUrl = await gitText(repoPath, ["remote", "get-url", "origin"], void 0, ownedHelpers).catch(() => null);
+  const remoteUrl = rawUrl === null ? null : stripUserinfo(rawUrl);
+  return {
+    root,
+    gitCommonDir,
+    defaultBranch: await originHeadBranch(repoPath, ownedHelpers),
+    hasOrigin: remoteUrl !== null,
+    remoteUrl
+  };
+}
+async function mainRef(repoPath, mainBranch, ownedHelpers) {
+  try {
+    await gitText(repoPath, ["show-ref", "--verify", "--quiet", `refs/remotes/origin/${mainBranch}`], void 0, ownedHelpers);
+    return `origin/${mainBranch}`;
+  } catch {
+    return mainBranch;
+  }
+}
+async function fetchMain(repoPath, mainBranch, ownedHelpers) {
+  if (!isBranchName(mainBranch))
+    return { ok: false, error: "\u4E3B\u5206\u652F\u540D\u79F0\u65E0\u6548" };
+  try {
+    const remotes = await gitText(repoPath, ["remote"], void 0, ownedHelpers);
+    if (!remotes.split("\n").filter(Boolean).includes("origin"))
+      return { ok: false, error: "\u6CA1\u6709 origin" };
+  } catch (e) {
+    return { ok: false, error: errorText(e) };
+  }
+  try {
+    await gitText(repoPath, ["fetch", "--no-tags", "origin", "--", `refs/heads/${mainBranch}:refs/remotes/origin/${mainBranch}`], 6e4, ownedHelpers);
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, error: errorText(e) };
+  }
+}
+async function revParse(repoPath, ref, ownedHelpers) {
+  return gitText(repoPath, ["rev-parse", "--verify", ref], void 0, ownedHelpers);
+}
+async function readFileAtRef(repoPath, ref, relPath, range, ownedHelpers) {
+  const rel = normalizeRepoPath(relPath);
+  const rows = parseLsTree(await gitRaw(repoPath, ["--literal-pathspecs", "ls-tree", "-z", ref, "--", rel], void 0, ownedHelpers));
+  const row = rows.length === 1 && rows[0].path === rel ? rows[0] : void 0;
+  if (!row)
+    throw new Error(`${rel} \u4E0D\u5B58\u5728\u4E8E ${ref}`);
+  if (row.mode === "120000")
+    throw new Error(`${rel} \u662F\u7B26\u53F7\u94FE\u63A5\uFF0C\u5DF2\u62D2\u7EDD`);
+  if (row.type !== "blob")
+    throw new Error(`${rel} \u4E0D\u5B58\u5728\u4E8E ${ref}`);
+  const lines = splitLines((await gitRaw(repoPath, ["cat-file", "blob", row.sha], void 0, ownedHelpers)).toString("utf8"));
+  const startLine = range?.startLine ?? 1;
+  const requestedEnd = range?.endLine ?? lines.length;
+  let selected = startLine > lines.length ? [] : lines.slice(startLine - 1, requestedEnd);
+  let truncated = false;
+  if (selected.length > MAX_LINES) {
+    selected = selected.slice(0, MAX_LINES);
+    truncated = true;
+  }
+  let text = selected.join("\n");
+  if (Buffer.byteLength(text) > MAX_BYTES) {
+    text = cutUtf8(text, MAX_BYTES);
+    truncated = true;
+  }
+  const shown = splitLines(text);
+  const endLine = shown.length === 0 ? startLine : startLine + shown.length - 1;
+  return { path: rel, startLine, endLine, totalLines: lines.length, text, truncated };
+}
+async function missingAtRef(repoPath, ref, paths, ownedHelpers) {
+  const missing = [];
+  for (const p of paths) {
+    const rel = normalizeRepoPath(p);
+    try {
+      await gitRaw(repoPath, ["--literal-pathspecs", "cat-file", "-e", `${ref}:${rel}`], void 0, ownedHelpers);
+    } catch {
+      missing.push(p);
+    }
+  }
+  return missing;
+}
+async function isOnMain(repoPath, sha, ref, ownedHelpers) {
+  try {
+    await gitText(repoPath, ["merge-base", "--is-ancestor", sha, ref], void 0, ownedHelpers);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function changedFiles(repoPath, from, to, mainBranch, ownedHelpers) {
+  if (!isBranchName(mainBranch))
+    throw new Error("\u4E3B\u5206\u652F\u540D\u79F0\u65E0\u6548");
+  const ref = await mainRef(repoPath, mainBranch, ownedHelpers);
+  for (const rev of [from, to]) {
+    if (rev === ref)
+      continue;
+    if (!SHA_RE.test(rev) || !await isOnMain(repoPath, rev, ref, ownedHelpers))
+      throw new Error(`\u63D0\u4EA4 ${rev} \u4E0D\u5728\u4E3B\u5206\u652F\u4E0A`);
+  }
+  return diffNameStatus(repoPath, from, to, ownedHelpers);
+}
+async function diffNameStatus(repoPath, from, to, ownedHelpers) {
+  for (const rev of [from, to]) {
+    if (rev.startsWith("-"))
+      throw new Error(`\u65E0\u6548\u7684\u63D0\u4EA4 ${rev}`);
+  }
+  return parseNameStatus(await gitRaw(repoPath, ["diff", "--name-status", "-M", "-z", from, to, "--"], void 0, ownedHelpers));
+}
+function tarBin() {
+  return process.platform === "win32" ? path.join(process.env.SystemRoot ?? "C:\\Windows", "System32", "tar.exe") : "tar";
+}
+async function exportSnapshot(repoPath, ref, destDir, ownedHelpers) {
+  const archived = await gitRaw(repoPath, ["archive", "--format=tar", "--", ref], 6e4, ownedHelpers);
+  const scratch = await mkdtemp(path.join(tmpdir(), "nema-snapshot-"));
+  const archivePath = path.join(scratch, "tree.tar");
+  try {
+    await writeFile(archivePath, stripSymlinkEntries(archived), { mode: 384 });
+    await emptyDir(destDir);
+    await execBuf(tarBin(), ["-x", "-f", archivePath, "-C", destDir], { timeout: 6e4, ownedHelpers });
+  } finally {
+    await rm(scratch, { recursive: true, force: true });
+  }
+}
+export {
+  changedFiles,
+  commandEnv,
+  diffNameStatus,
+  exportSnapshot,
+  fetchMain,
+  gitRaw,
+  gitText,
+  inspectRepo,
+  mainRef,
+  missingAtRef,
+  readFileAtRef,
+  revParse
+};

package/dist/repos/graphify.d.ts

@@ -0,0 +1,32 @@
+import type { OwnedHelperScope } from "@nema/shared/ownedHelper";
+export declare function graphifyEnv(snapshotRoot: string): NodeJS.ProcessEnv;
+/**
+ * Where graphify is and how long a call may run. Tests pass a fake binary.
+ * An omitted `bin` is the packaged file, never a `PATH` lookup.
+ * Read at call time, so a caller may fill the object in after handing it over.
+ */
+export type GraphifyOpts = {
+    bin?: string;
+    timeoutMs?: number;
+    ownedHelpers?: OwnedHelperScope;
+};
+/**
+ * Full `extract` of a repository. The one-minute cap kills a monorepo mid-build and reports
+ * the same "graphify 已中断" as a cancel. Stays under the hub's 5-minute index RPC so fetch
+ * and the snapshot export still fit.
+ * ponytail: a larger repo needs this and INDEX_RPC_TIMEOUT_MS raised together.
+ */
+export declare const EXTRACT_TIMEOUT_MS = 180000;
+/** `tools/graphify/graphify` under the payload, or `NEMA_GRAPHIFY_BIN` when that is set. */
+export declare function packagedGraphifyBin(env?: NodeJS.ProcessEnv): string;
+export declare function buildIndex(snapshotRoot: string, opts?: GraphifyOpts): Promise<void>;
+export declare function queryIndex(snapshotRoot: string, kind: "query" | "explain" | "path", args: string[], opts?: GraphifyOpts): Promise<string>;
+/** Version text when `graphify --version` runs; the install hint when the binary is missing. */
+export declare function graphifyInstallStatus(opts?: GraphifyOpts): Promise<{
+    installed: boolean;
+    detail: string;
+}>;
+export declare function updateIndex(snapshotRoot: string, changed: {
+    status: string;
+    path: string;
+}[], repoPath: string, ref: string, opts?: GraphifyOpts): Promise<void>;

package/dist/repos/graphify.js

@@ -0,0 +1,292 @@
+import {
+  runHelperFile
+} from "../chunks/chunk-WT3XUFWU.js";
+
+// repos/graphify.js
+import { execFile } from "node:child_process";
+import { lstat, mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { commandSpec, windowsRuntimeEnv } from "../platform.js";
+var MAX_OUT = 65536;
+var MAX_BUFFER = 256 * 1024 * 1024;
+var INSTALL_HINT = "\u968F\u5305\u7684 Graphify \u8FD0\u884C\u73AF\u5883\u7F3A\u5931";
+function graphifyEnv(snapshotRoot) {
+  return {
+    ...windowsRuntimeEnv(process.env),
+    PATH: process.env.PATH ?? "",
+    LANG: process.env.LANG ?? "",
+    HOME: path.join(snapshotRoot, "home"),
+    GRAPHIFY_BACKEND: "none",
+    GRAPHIFY_QUERY_LOG_DISABLE: "1"
+  };
+}
+var DEFAULT_TIMEOUT_MS = 6e4;
+var EXTRACT_TIMEOUT_MS = 18e4;
+function packagedGraphifyBin(env = process.env) {
+  const name = process.platform === "win32" ? "graphify.exe" : "graphify";
+  const fromEnv = env.NEMA_GRAPHIFY_BIN;
+  if (typeof fromEnv === "string" && fromEnv !== "")
+    return fromEnv;
+  const root = typeof env.NEMA_PAYLOAD_ROOT === "string" && env.NEMA_PAYLOAD_ROOT !== "" ? env.NEMA_PAYLOAD_ROOT : path.dirname(process.execPath);
+  return path.join(root, "tools", "graphify", name);
+}
+function graphifyBin(opts) {
+  return opts?.bin || packagedGraphifyBin();
+}
+function graphifyTimeout(opts) {
+  const n = opts?.timeoutMs;
+  return n !== void 0 && Number.isFinite(n) && n > 0 ? n : DEFAULT_TIMEOUT_MS;
+}
+function extractCallOpts(opts) {
+  if (opts?.timeoutMs !== void 0 && Number.isFinite(opts.timeoutMs) && opts.timeoutMs > 0)
+    return opts;
+  return { ...opts, timeoutMs: EXTRACT_TIMEOUT_MS };
+}
+function cutUtf8(text, maxBytes) {
+  let bytes = 0;
+  let index = 0;
+  for (const ch of text) {
+    const size = Buffer.byteLength(ch);
+    if (bytes + size > maxBytes)
+      break;
+    bytes += size;
+    index += ch.length;
+  }
+  return text.slice(0, index);
+}
+function exitCode(error) {
+  if (error.code === "ENOENT")
+    return "missing";
+  if (error.signal || error.killed || error.code == null || error.code === 0)
+    return "killed";
+  if (typeof error.code === "number")
+    return error.code;
+  const parsed = Number(error.code);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : "killed";
+}
+function stopChild(child) {
+  try {
+    child.kill("SIGTERM");
+  } catch {
+    return;
+  }
+  const sigkill = setTimeout(() => {
+    try {
+      child.kill("SIGKILL");
+    } catch {
+    }
+  }, 200);
+  child.once("exit", () => clearTimeout(sigkill));
+}
+function runGraphify(snapshotRoot, args, cwd, opts) {
+  const bin = graphifyBin(opts);
+  const command = commandSpec(bin, args, graphifyEnv(snapshotRoot));
+  if (opts?.ownedHelpers) {
+    return runHelperFile(command.bin, command.args, {
+      cwd,
+      env: graphifyEnv(snapshotRoot),
+      timeout: graphifyTimeout(opts),
+      encoding: "buffer",
+      maxBuffer: 1024 * 1024
+    }, opts.ownedHelpers).then((result) => {
+      if (result.error) {
+        const code = exitCode(result.error);
+        if (code === "missing")
+          throw new Error(INSTALL_HINT);
+        if (code === "killed")
+          throw new Error("graphify \u5DF2\u4E2D\u65AD");
+        return { code, stdout: result.stdout, stderr: result.stderr };
+      }
+      return { code: 0, stdout: result.stdout, stderr: result.stderr };
+    });
+  }
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let timedOut = false;
+    let timer;
+    const child = execFile(command.bin, command.args, { cwd, env: graphifyEnv(snapshotRoot), shell: false, encoding: "buffer", maxBuffer: 1024 * 1024 }, (error, stdout, stderr) => {
+      if (settled)
+        return;
+      settled = true;
+      clearTimeout(timer);
+      const out = Buffer.isBuffer(stdout) ? stdout : Buffer.from(stdout ?? "");
+      const errOut = Buffer.isBuffer(stderr) ? stderr : Buffer.from(stderr ?? "");
+      if (timedOut) {
+        reject(new Error("graphify \u5DF2\u4E2D\u65AD"));
+        return;
+      }
+      if (!error) {
+        resolve({ code: 0, stdout: out, stderr: errOut });
+        return;
+      }
+      const code = exitCode(error);
+      if (code === "missing") {
+        reject(new Error(INSTALL_HINT));
+        return;
+      }
+      if (code === "killed") {
+        reject(new Error("graphify \u5DF2\u4E2D\u65AD"));
+        return;
+      }
+      resolve({ code, stdout: out, stderr: errOut });
+    });
+    timer = setTimeout(() => {
+      if (settled)
+        return;
+      timedOut = true;
+      stopChild(child);
+    }, graphifyTimeout(opts));
+  });
+}
+function finish(result) {
+  if (result.code === 3)
+    throw new Error("\u540D\u79F0\u4E0D\u552F\u4E00");
+  if (result.code === 4)
+    throw new Error("\u6CA1\u6709\u5339\u914D");
+  if (result.code !== 0) {
+    const text = result.stderr.toString("utf8").trim();
+    throw new Error(text || `graphify exited ${result.code}`);
+  }
+  return cutUtf8(result.stdout.toString("utf8"), MAX_OUT);
+}
+async function buildIndex(snapshotRoot, opts) {
+  const src = path.join(snapshotRoot, "src");
+  await mkdir(path.join(snapshotRoot, "home"), { recursive: true });
+  finish(await runGraphify(snapshotRoot, ["extract", src, "--code-only"], snapshotRoot, extractCallOpts(opts)));
+}
+function graphJson(snapshotRoot) {
+  return path.join(snapshotRoot, "src", "graphify-out", "graph.json");
+}
+async function queryIndex(snapshotRoot, kind, args, opts) {
+  for (const arg of args) {
+    if (arg.startsWith("-"))
+      throw new Error(`\u53C2\u6570\u4E0D\u80FD\u4EE5 - \u5F00\u5934\uFF1A${arg}`);
+  }
+  return finish(await runGraphify(snapshotRoot, [kind, ...args, "--graph", graphJson(snapshotRoot)], snapshotRoot, opts));
+}
+async function graphifyInstallStatus(opts) {
+  const dir = await mkdtemp(path.join(tmpdir(), "nema-graphify-version-"));
+  try {
+    await mkdir(path.join(dir, "home"), { recursive: true });
+    const detail = finish(await runGraphify(dir, ["--version"], dir, opts)).trim();
+    return { installed: true, detail };
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    if (message === INSTALL_HINT)
+      return { installed: false, detail: message };
+    throw e;
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+function gitEnv() {
+  return {
+    ...windowsRuntimeEnv(process.env),
+    PATH: process.env.PATH ?? "",
+    HOME: process.env.HOME ?? "",
+    LANG: process.env.LANG ?? "",
+    GIT_TERMINAL_PROMPT: "0"
+  };
+}
+function git(repoPath, args, ownedHelpers) {
+  if (ownedHelpers) {
+    return runHelperFile("git", ["-C", repoPath, ...args], {
+      env: gitEnv(),
+      encoding: "buffer",
+      maxBuffer: MAX_BUFFER
+    }, ownedHelpers).then((result) => {
+      if (result.error) {
+        const text = result.stderr.toString("utf8").trim();
+        throw new Error(text || result.error.message);
+      }
+      return result.stdout;
+    });
+  }
+  return new Promise((resolve, reject) => {
+    execFile("git", ["-C", repoPath, ...args], { env: gitEnv(), shell: false, encoding: "buffer", maxBuffer: MAX_BUFFER }, (error, stdout, stderr) => {
+      const out = Buffer.isBuffer(stdout) ? stdout : Buffer.from(stdout ?? "");
+      if (error) {
+        const text = (Buffer.isBuffer(stderr) ? stderr : Buffer.from(stderr ?? "")).toString("utf8").trim();
+        reject(new Error(text || error.message));
+        return;
+      }
+      resolve(out);
+    });
+  });
+}
+function normalizeRepoPath(relPath) {
+  if (relPath === "" || path.isAbsolute(relPath))
+    throw new Error("\u8DEF\u5F84\u5FC5\u987B\u662F\u4ED3\u5E93\u5185\u7684\u76F8\u5BF9\u8DEF\u5F84");
+  const normalized = path.posix.normalize(relPath);
+  if (normalized.split("/").includes(".."))
+    throw new Error("\u8DEF\u5F84\u5FC5\u987B\u662F\u4ED3\u5E93\u5185\u7684\u76F8\u5BF9\u8DEF\u5F84");
+  return normalized;
+}
+function parseLsTree(buf) {
+  const rows = [];
+  for (const entry of buf.toString("utf8").split("\0")) {
+    if (!entry)
+      continue;
+    const tab = entry.indexOf("	");
+    if (tab < 0)
+      continue;
+    const [mode, type, sha] = entry.slice(0, tab).split(" ");
+    rows.push({ mode: mode ?? "", type: type ?? "", sha: sha ?? "", path: entry.slice(tab + 1) });
+  }
+  return rows;
+}
+async function blobAt(repoPath, ref, relPath, ownedHelpers) {
+  const rel = normalizeRepoPath(relPath);
+  const rows = parseLsTree(await git(repoPath, ["--literal-pathspecs", "ls-tree", "-z", ref, "--", rel], ownedHelpers));
+  const row = rows.length === 1 && rows[0]?.path === rel ? rows[0] : void 0;
+  if (!row || row.type !== "blob")
+    throw new Error(`${rel} \u4E0D\u5B58\u5728\u4E8E ${ref}`);
+  if (row.mode === "120000")
+    return null;
+  return git(repoPath, ["cat-file", "blob", row.sha], ownedHelpers);
+}
+function destination(src, relPath) {
+  const rel = normalizeRepoPath(relPath);
+  const dest = path.resolve(src, rel);
+  const fromSrc = path.relative(src, dest);
+  if (fromSrc === "" || fromSrc === ".." || fromSrc.startsWith(`..${path.sep}`) || path.isAbsolute(fromSrc)) {
+    throw new Error("\u8DEF\u5F84\u5FC5\u987B\u662F\u4ED3\u5E93\u5185\u7684\u76F8\u5BF9\u8DEF\u5F84");
+  }
+  return dest;
+}
+async function writeInside(src, relPath, data) {
+  const dest = destination(src, relPath);
+  await mkdir(path.dirname(dest), { recursive: true });
+  try {
+    if ((await lstat(dest)).isSymbolicLink())
+      await rm(dest);
+  } catch {
+  }
+  await writeFile(dest, data);
+}
+async function updateIndex(snapshotRoot, changed, repoPath, ref, opts) {
+  const src = path.join(snapshotRoot, "src");
+  await mkdir(src, { recursive: true });
+  for (const file of changed) {
+    if (file.status.startsWith("D")) {
+      await rm(destination(src, file.path), { force: true });
+      continue;
+    }
+    const blob = await blobAt(repoPath, ref, file.path, opts?.ownedHelpers);
+    if (blob === null)
+      continue;
+    await writeInside(src, file.path, blob);
+  }
+  await mkdir(path.join(snapshotRoot, "home"), { recursive: true });
+  finish(await runGraphify(snapshotRoot, ["update", src, "--code-only"], snapshotRoot, opts));
+}
+export {
+  EXTRACT_TIMEOUT_MS,
+  buildIndex,
+  graphifyEnv,
+  graphifyInstallStatus,
+  packagedGraphifyBin,
+  queryIndex,
+  updateIndex
+};