@nema-project/nema 0.0.0-stage → 0.1.3

package/dist/report/git.js

@@ -0,0 +1,42 @@
+// report/git.js
+import { execFile } from "node:child_process";
+import { realpath } from "node:fs/promises";
+function git(cwd, args) {
+  return new Promise((resolve, reject) => {
+    execFile("git", ["-C", cwd, ...args], {
+      // A minimal env, so GIT_DIR / GIT_WORK_TREE set by the agent's environment cannot redirect git.
+      env: { PATH: process.env.PATH ?? "", HOME: process.env.HOME ?? "", LANG: process.env.LANG ?? "", GIT_TERMINAL_PROMPT: "0" },
+      shell: false,
+      timeout: 5e3,
+      encoding: "utf8"
+    }, (err, stdout) => err ? reject(err) : resolve(String(stdout).trim()));
+  });
+}
+async function repoInfo(cwd) {
+  let commonDir;
+  let head;
+  try {
+    commonDir = await git(cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
+    head = await git(cwd, ["rev-parse", "HEAD"]);
+  } catch {
+    return null;
+  }
+  if (!/^[0-9a-f]{40}$/.test(head))
+    return null;
+  let branch;
+  try {
+    branch = await git(cwd, ["symbolic-ref", "--short", "-q", "HEAD"]) || null;
+  } catch {
+    branch = null;
+  }
+  let gitCommonDir;
+  try {
+    gitCommonDir = await realpath(commonDir);
+  } catch {
+    return null;
+  }
+  return { gitCommonDir, branch, head };
+}
+export {
+  repoInfo
+};

package/dist/report/install.d.ts

@@ -0,0 +1,22 @@
+import type { Out } from "../direct/authCommands.js";
+export type ReportAgent = "claude" | "codex";
+export declare const REPORT_AGENTS: readonly ReportAgent[];
+export declare function hookCommand(nodeBin: string, cliEntry: string, agent: ReportAgent, platform?: NodeJS.Platform): string;
+export type InstallRun = {
+    agent: ReportAgent;
+    home: string;
+    nemaHome: string;
+    out: Out;
+    nodeBin: string;
+    cliEntry: string;
+};
+export declare function installReport(o: InstallRun): number;
+export type UninstallRun = {
+    agent: ReportAgent;
+    home: string;
+    out: Out;
+};
+/** Removes exactly Nema's hook entries and the nema-report skill dir. The report token stays. */
+export declare function uninstallReport(o: UninstallRun): number;
+/** For `nema doctor`: whether the agent's settings carry a Nema Stop or SessionEnd hook. Never throws. */
+export declare function reportHookInstalled(agent: ReportAgent, home: string): boolean;

package/dist/report/install.js

@@ -0,0 +1,183 @@
+// report/install.js
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { ensureReportToken, reportTokenPath } from "./token.js";
+var REPORT_AGENTS = ["claude", "codex"];
+var EVENTS = ["Stop", "SessionEnd"];
+var MARKER = " report hook --agent ";
+var SKILL_NAME = "nema-report";
+function agentPaths(agent, home) {
+  return agent === "claude" ? { settings: path.join(home, ".claude", "settings.json"), skillDir: path.join(home, ".claude", "skills", SKILL_NAME) } : { settings: path.join(home, ".codex", "hooks.json"), skillDir: path.join(home, ".agents", "skills", SKILL_NAME) };
+}
+var isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var isNema = (h) => {
+  if (!isObj(h) || typeof h.command !== "string")
+    return false;
+  if (h.command.includes(MARKER))
+    return true;
+  const encoded = /^powershell\.exe -NoLogo -NoProfile -NonInteractive -EncodedCommand ([A-Za-z0-9+/=]+)$/.exec(h.command);
+  return encoded !== null && Buffer.from(encoded[1], "base64").toString("utf16le").includes(MARKER);
+};
+function shellQuote(s) {
+  return /^[A-Za-z0-9_\/.,:@%+=-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`;
+}
+function hookCommand(nodeBin, cliEntry, agent, platform = process.platform) {
+  if (platform === "win32") {
+    const psQuote = (value) => `'${value.replaceAll("'", "''")}'`;
+    const script = `& ${psQuote(nodeBin)} ${psQuote(cliEntry)} report hook --agent ${agent}; exit $LASTEXITCODE`;
+    return `powershell.exe -NoLogo -NoProfile -NonInteractive -EncodedCommand ${Buffer.from(script, "utf16le").toString("base64")}`;
+  }
+  return `${shellQuote(nodeBin)} ${shellQuote(cliEntry)} report hook --agent ${agent}`;
+}
+function load(file) {
+  if (!existsSync(file))
+    return { data: {}, indent: "  ", newline: true, existed: false };
+  const raw = readFileSync(file, "utf8");
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!isObj(data) || data.hooks !== void 0 && !isObj(data.hooks))
+    return null;
+  if (isObj(data.hooks) && Object.values(data.hooks).some((v) => !Array.isArray(v)))
+    return null;
+  const indent = /\n([ \t]+)\S/.exec(raw)?.[1] ?? "  ";
+  return { data, indent, newline: raw.endsWith("\n"), existed: true };
+}
+function save(file, l) {
+  const target = l.existed ? realpathSync(file) : file;
+  mkdirSync(path.dirname(target), { recursive: true });
+  const mode = l.existed ? statSync(target).mode & 511 : 420;
+  const tmp = `${target}.${process.pid}.nema.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(l.data, null, l.indent)}${l.newline ? "\n" : ""}`, { mode });
+  renameSync(tmp, target);
+}
+function putHook(hooks, event, command) {
+  const groups = hooks[event] ??= [];
+  let placed = false;
+  const kept = [];
+  for (const g of groups) {
+    if (!isObj(g) || !Array.isArray(g.hooks) || !g.hooks.some(isNema)) {
+      kept.push(g);
+      continue;
+    }
+    const inner = [];
+    for (const h of g.hooks) {
+      if (!isNema(h))
+        inner.push(h);
+      else if (!placed) {
+        placed = true;
+        inner.push({ ...h, type: "command", command });
+      }
+    }
+    if (inner.length > 0)
+      kept.push({ ...g, hooks: inner });
+  }
+  if (!placed)
+    kept.push({ hooks: [{ type: "command", command }] });
+  hooks[event] = kept;
+}
+function stripHooks(data) {
+  if (!isObj(data.hooks))
+    return false;
+  const hooks = data.hooks;
+  let changed = false;
+  for (const [event, groups] of Object.entries(hooks)) {
+    if (!Array.isArray(groups))
+      continue;
+    let touched = false;
+    const kept = [];
+    for (const g of groups) {
+      if (!isObj(g) || !Array.isArray(g.hooks) || !g.hooks.some(isNema)) {
+        kept.push(g);
+        continue;
+      }
+      touched = true;
+      const inner = g.hooks.filter((h) => !isNema(h));
+      if (inner.length > 0)
+        kept.push({ ...g, hooks: inner });
+    }
+    if (!touched)
+      continue;
+    changed = true;
+    if (kept.length > 0)
+      hooks[event] = kept;
+    else
+      delete hooks[event];
+  }
+  if (changed && Object.keys(hooks).length === 0)
+    delete data.hooks;
+  return changed;
+}
+var skillSource = () => readFileSync(new URL("../../src/report/SKILL.md", import.meta.url), "utf8");
+function installReport(o) {
+  const p = agentPaths(o.agent, o.home);
+  const loaded = load(p.settings);
+  if (!loaded) {
+    o.out.error(`\u65E0\u6CD5\u89E3\u6790 ${p.settings}\uFF0C\u672A\u4FEE\u6539`);
+    return 1;
+  }
+  try {
+    ensureReportToken(o.nemaHome);
+  } catch (e) {
+    o.out.error(e instanceof Error ? e.message : String(e));
+    return 1;
+  }
+  mkdirSync(p.skillDir, { recursive: true });
+  const skillFile = path.join(p.skillDir, "SKILL.md");
+  writeFileSync(skillFile, skillSource());
+  o.out.log(`\u5DF2\u5199\u5165\u6280\u80FD\uFF1A${skillFile}`);
+  const before = JSON.stringify(loaded.data);
+  const hooks = loaded.data.hooks ??= {};
+  const command = hookCommand(o.nodeBin, o.cliEntry, o.agent);
+  for (const ev of EVENTS)
+    putHook(hooks, ev, command);
+  if (JSON.stringify(loaded.data) === before) {
+    o.out.log(`${p.settings} \u91CC\u7684 ${EVENTS.join("\u3001")} \u94A9\u5B50\u5DF2\u662F\u6700\u65B0`);
+  } else {
+    save(p.settings, loaded);
+    o.out.log(`\u5DF2\u5728 ${p.settings} \u5199\u5165 ${EVENTS.join("\u3001")} \u94A9\u5B50`);
+  }
+  o.out.log(`\u4E0A\u62A5\u4EE4\u724C\u5DF2\u5C31\u7EEA\uFF1A${reportTokenPath(o.nemaHome)}`);
+  o.out.log("\u8BF7\u91CD\u542F nema daemon\uFF0C\u8BA9\u5B83\u767B\u8BB0\u4E0A\u62A5\u4EE4\u724C");
+  return 0;
+}
+function uninstallReport(o) {
+  const p = agentPaths(o.agent, o.home);
+  const loaded = load(p.settings);
+  if (!loaded) {
+    o.out.error(`\u65E0\u6CD5\u89E3\u6790 ${p.settings}\uFF0C\u672A\u4FEE\u6539`);
+    return 1;
+  }
+  if (loaded.existed && stripHooks(loaded.data)) {
+    save(p.settings, loaded);
+    o.out.log(`\u5DF2\u4ECE ${p.settings} \u79FB\u9664 Nema \u7684\u94A9\u5B50`);
+  } else {
+    o.out.log(`${p.settings} \u91CC\u6CA1\u6709 Nema \u7684\u94A9\u5B50`);
+  }
+  if (existsSync(p.skillDir)) {
+    rmSync(p.skillDir, { recursive: true, force: true });
+    o.out.log(`\u5DF2\u5220\u9664\u6280\u80FD\uFF1A${p.skillDir}`);
+  }
+  return 0;
+}
+function reportHookInstalled(agent, home) {
+  try {
+    const loaded = load(agentPaths(agent, home).settings);
+    if (!loaded || !isObj(loaded.data.hooks))
+      return false;
+    const hooks = loaded.data.hooks;
+    return EVENTS.some((ev) => hooks[ev]?.some((g) => isObj(g) && Array.isArray(g.hooks) && g.hooks.some(isNema)));
+  } catch {
+    return false;
+  }
+}
+export {
+  REPORT_AGENTS,
+  hookCommand,
+  installReport,
+  reportHookInstalled,
+  uninstallReport
+};

package/dist/report/send.d.ts

@@ -0,0 +1,35 @@
+export type HubPath = "/report/hook" | "/report";
+export type SendResult = "ok" | "dropped" | "failed";
+export type SendOpts = {
+    connectMs: number;
+    totalMs: number;
+};
+export declare const HOOK_TIMEOUTS: SendOpts;
+/** POSTs JSON with a bearer token. Never throws: network errors and timeouts are status 0. */
+export declare function postToHub(hubUrl: string, p: HubPath, token: string, body: unknown, opts?: SendOpts): Promise<{
+    status: number;
+    text: string;
+}>;
+/** GETs with a bearer token. Never throws: network errors and timeouts are status 0. */
+export declare function getFromHub(hubUrl: string, p: string, token: string, opts?: SendOpts): Promise<{
+    status: number;
+    text: string;
+}>;
+export declare function classify(status: number): SendResult;
+/** 2xx (204 too: dropped hub-side) is "ok"; 4xx is "dropped"; network failure, timeout or 5xx is "failed". */
+export declare function sendToHub(hubUrl: string, p: HubPath, token: string, body: unknown, opts?: SendOpts): Promise<SendResult>;
+export declare const SPOOL_MAX_BYTES: number;
+export type SpoolLine = {
+    path: HubPath;
+    body: unknown;
+    spooledAt: string;
+};
+export declare const spoolPath: (nemaHome: string) => string;
+/** Appends one line (0600). Returns false, writing nothing, when the spool would grow past 5 MB. */
+export declare function appendSpool(nemaHome: string, line: SpoolLine): boolean;
+/**
+ * Replays the spool oldest first and stops at the first "failed". "ok" and "dropped" lines are removed;
+ * lines older than 7 days or malformed are dropped unsent. The rest is rewritten atomically.
+ * Returns "failed" when something is still waiting, else "ok".
+ */
+export declare function flushSpool(nemaHome: string, send: (line: SpoolLine) => Promise<SendResult>, now?: number): Promise<"ok" | "failed">;

package/dist/report/send.js

@@ -0,0 +1,208 @@
+// report/send.js
+import { randomUUID } from "node:crypto";
+import { closeSync, constants, fchmodSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeSync } from "node:fs";
+import http from "node:http";
+import https from "node:https";
+import path from "node:path";
+import { openPrivateFile, protectPrivatePath } from "../secrets/permissions.js";
+var HOOK_TIMEOUTS = { connectMs: 500, totalMs: 1500 };
+function postToHub(hubUrl, p, token, body, opts = HOOK_TIMEOUTS) {
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = (status, text) => {
+      if (done)
+        return;
+      done = true;
+      clearTimeout(total);
+      clearTimeout(connect);
+      resolve({ status, text });
+    };
+    let url;
+    try {
+      url = new URL(hubUrl.replace(/\/+$/, "") + p);
+    } catch {
+      resolve({ status: 0, text: "" });
+      return;
+    }
+    const data = Buffer.from(JSON.stringify(body));
+    const lib = url.protocol === "https:" ? https : http;
+    const req = lib.request(url, {
+      method: "POST",
+      headers: { "content-type": "application/json", "content-length": String(data.length), authorization: `Bearer ${token}` }
+    });
+    const connect = setTimeout(() => req.destroy(new Error("connect timeout")), opts.connectMs);
+    const total = setTimeout(() => req.destroy(new Error("timeout")), opts.totalMs);
+    req.on("socket", (s) => {
+      if (!s.connecting)
+        clearTimeout(connect);
+      else
+        s.once("connect", () => clearTimeout(connect));
+    });
+    req.on("error", () => finish(0, ""));
+    req.on("response", (res) => {
+      let text = "";
+      res.setEncoding("utf8");
+      res.on("data", (c) => {
+        if (text.length < 4096)
+          text += c;
+      });
+      res.on("end", () => finish(res.statusCode ?? 0, text));
+      res.on("error", () => finish(0, ""));
+    });
+    req.end(data);
+  });
+}
+function getFromHub(hubUrl, p, token, opts = { connectMs: 2e3, totalMs: 15e3 }) {
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = (status, text) => {
+      if (done)
+        return;
+      done = true;
+      clearTimeout(total);
+      clearTimeout(connect);
+      resolve({ status, text });
+    };
+    let url;
+    try {
+      url = new URL(hubUrl.replace(/\/+$/, "") + p);
+    } catch {
+      resolve({ status: 0, text: "" });
+      return;
+    }
+    const lib = url.protocol === "https:" ? https : http;
+    const req = lib.request(url, { method: "GET", headers: { authorization: `Bearer ${token}` } });
+    const connect = setTimeout(() => req.destroy(new Error("connect timeout")), opts.connectMs);
+    const total = setTimeout(() => req.destroy(new Error("timeout")), opts.totalMs);
+    req.on("socket", (s) => {
+      if (!s.connecting)
+        clearTimeout(connect);
+      else
+        s.once("connect", () => clearTimeout(connect));
+    });
+    req.on("error", () => finish(0, ""));
+    req.on("response", (res) => {
+      const chunks = [];
+      res.setEncoding("utf8");
+      res.on("data", (c) => chunks.push(c));
+      res.on("end", () => finish(res.statusCode ?? 0, chunks.join("")));
+      res.on("error", () => finish(0, ""));
+    });
+    req.end();
+  });
+}
+function classify(status) {
+  if (status >= 200 && status < 300)
+    return "ok";
+  if (status >= 400 && status < 500)
+    return "dropped";
+  return "failed";
+}
+async function sendToHub(hubUrl, p, token, body, opts = HOOK_TIMEOUTS) {
+  return classify((await postToHub(hubUrl, p, token, body, opts)).status);
+}
+var SPOOL_MAX_BYTES = 5 * 1024 * 1024;
+var SPOOL_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1e3;
+var spoolPath = (nemaHome) => path.join(nemaHome, "report-spool.jsonl");
+function appendSpool(nemaHome, line) {
+  mkdirSync(nemaHome, { recursive: true, mode: 448 });
+  if (process.platform === "win32")
+    protectPrivatePath(nemaHome, 448);
+  try {
+    if (lstatSync(spoolPath(nemaHome)).isSymbolicLink())
+      throw new Error("\u4E0A\u62A5\u7F13\u5B58\u4E0D\u80FD\u662F\u7B26\u53F7\u94FE\u63A5");
+  } catch (error) {
+    if (error.code !== "ENOENT")
+      throw error;
+  }
+  const text = JSON.stringify(line) + "\n";
+  const fd = openSync(spoolPath(nemaHome), constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW, 384);
+  try {
+    const st = fstatSync(fd);
+    if (!st.isFile())
+      return false;
+    if (process.platform === "win32")
+      protectPrivatePath(spoolPath(nemaHome));
+    if (process.platform !== "win32" && (st.mode & 511) !== 384)
+      fchmodSync(fd, 384);
+    if (st.size + Buffer.byteLength(text) > SPOOL_MAX_BYTES)
+      return false;
+    writeSync(fd, text);
+    return true;
+  } finally {
+    closeSync(fd);
+  }
+}
+function readSpool(nemaHome) {
+  let fd;
+  try {
+    fd = openPrivateFile(spoolPath(nemaHome));
+  } catch (e) {
+    if (e.code === "ENOENT")
+      return null;
+    throw e;
+  }
+  try {
+    if (!fstatSync(fd).isFile())
+      return null;
+    return readFileSync(fd, "utf8");
+  } finally {
+    closeSync(fd);
+  }
+}
+function writeSpool(nemaHome, lines) {
+  const file = spoolPath(nemaHome);
+  if (lines.length === 0) {
+    try {
+      unlinkSync(file);
+    } catch (e) {
+      if (e.code !== "ENOENT")
+        throw e;
+    }
+    return;
+  }
+  const tmp = `${file}.${process.pid}.${randomUUID()}.tmp`;
+  const fd = openSync(tmp, "wx", 384);
+  try {
+    writeSync(fd, lines.map((l) => JSON.stringify(l) + "\n").join(""));
+  } finally {
+    closeSync(fd);
+  }
+  renameSync(tmp, file);
+}
+function parseLine(raw) {
+  try {
+    const v = JSON.parse(raw);
+    if ((v.path === "/report/hook" || v.path === "/report") && typeof v.spooledAt === "string" && v.body !== void 0)
+      return v;
+  } catch {
+  }
+  return null;
+}
+async function flushSpool(nemaHome, send, now = Date.now()) {
+  const raw = readSpool(nemaHome);
+  if (raw === null)
+    return "ok";
+  const lines = raw.split("\n").filter((l) => l !== "").map(parseLine).filter((l) => l !== null && now - Date.parse(l.spooledAt) <= SPOOL_MAX_AGE_MS);
+  let i = 0;
+  let result = "ok";
+  for (; i < lines.length; i++) {
+    if (await send(lines[i]) === "failed") {
+      result = "failed";
+      break;
+    }
+  }
+  writeSpool(nemaHome, lines.slice(i));
+  return result;
+}
+export {
+  HOOK_TIMEOUTS,
+  SPOOL_MAX_BYTES,
+  appendSpool,
+  classify,
+  flushSpool,
+  getFromHub,
+  postToHub,
+  sendToHub,
+  spoolPath
+};

package/dist/report/token.d.ts

@@ -0,0 +1,5 @@
+export declare const reportTokenPath: (nemaHome: string) => string;
+/** Creates the token if missing (0600, atomic, never overwriting a concurrent writer's), else reads and checks it. */
+export declare function ensureReportToken(nemaHome: string): string;
+/** sha256 hex of the token, or null when the token file does not exist. */
+export declare function reportTokenHash(nemaHome: string): string | null;

package/dist/report/token.js

@@ -0,0 +1,86 @@
+// report/token.js
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { closeSync, fstatSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, unlinkSync, writeSync } from "node:fs";
+import path from "node:path";
+import { openPrivateFile, privateModeMatches, protectPrivatePath } from "../secrets/permissions.js";
+var TOKEN_RE = /^[0-9a-f]{64}$/;
+var SYMLINK = "\u4E0A\u62A5\u4EE4\u724C\u6587\u4EF6\u662F\u7B26\u53F7\u94FE\u63A5\uFF0C\u5DF2\u62D2\u7EDD";
+var BAD_MODE = "\u4E0A\u62A5\u4EE4\u724C\u6587\u4EF6\u6743\u9650\u5FC5\u987B\u662F 0600";
+var BAD_TOKEN = "\u4E0A\u62A5\u4EE4\u724C\u6587\u4EF6\u5185\u5BB9\u65E0\u6548";
+var reportTokenPath = (nemaHome) => path.join(nemaHome, "report-token");
+function readReportToken(nemaHome) {
+  let fd;
+  try {
+    fd = openPrivateFile(reportTokenPath(nemaHome));
+  } catch (e) {
+    const code = e.code;
+    if (code === "ENOENT")
+      return null;
+    if (code === "ELOOP")
+      throw new Error(SYMLINK);
+    throw e;
+  }
+  try {
+    const st = fstatSync(fd);
+    if (!st.isFile() || !privateModeMatches(st))
+      throw new Error(BAD_MODE);
+    const token = readFileSync(fd, "utf8").trim();
+    if (!TOKEN_RE.test(token))
+      throw new Error(BAD_TOKEN);
+    return token;
+  } finally {
+    closeSync(fd);
+  }
+}
+function ensureReportToken(nemaHome) {
+  const existing = readReportToken(nemaHome);
+  if (existing !== null)
+    return existing;
+  const file = reportTokenPath(nemaHome);
+  try {
+    if (lstatSync(file).isSymbolicLink())
+      throw new Error(SYMLINK);
+  } catch (e) {
+    if (e.code !== "ENOENT")
+      throw e;
+  }
+  mkdirSync(nemaHome, { recursive: true, mode: 448 });
+  protectPrivatePath(nemaHome, 448);
+  const token = randomBytes(32).toString("hex");
+  const tmp = `${file}.${process.pid}.${randomUUID()}.tmp`;
+  const fd = openSync(tmp, "wx", 384);
+  try {
+    try {
+      writeSync(fd, token);
+      fsyncSync(fd);
+    } finally {
+      closeSync(fd);
+    }
+    protectPrivatePath(tmp, 384);
+    try {
+      linkSync(tmp, file);
+    } catch (e) {
+      if (e.code !== "EEXIST")
+        throw e;
+      const raced = readReportToken(nemaHome);
+      if (raced === null)
+        throw e;
+      return raced;
+    }
+    return token;
+  } finally {
+    try {
+      unlinkSync(tmp);
+    } catch {
+    }
+  }
+}
+function reportTokenHash(nemaHome) {
+  const token = readReportToken(nemaHome);
+  return token === null ? null : createHash("sha256").update(token).digest("hex");
+}
+export {
+  ensureReportToken,
+  reportTokenHash,
+  reportTokenPath
+};

package/dist/repos/git.d.ts

@@ -0,0 +1,48 @@
+import type { OwnedHelperScope } from "@nema/shared/ownedHelper";
+export type RepoInspect = {
+    root: string;
+    gitCommonDir: string;
+    defaultBranch: string;
+    hasOrigin: boolean;
+    remoteUrl: string | null;
+};
+export type FileAtRef = {
+    path: string;
+    startLine: number;
+    endLine: number;
+    totalLines: number;
+    text: string;
+    truncated: boolean;
+};
+export type ChangedFile = {
+    status: string;
+    path: string;
+};
+export declare function commandEnv(): NodeJS.ProcessEnv;
+export declare function gitRaw(repoPath: string, args: string[], timeout?: number, ownedHelpers?: OwnedHelperScope): Promise<Buffer>;
+export declare function gitText(repoPath: string, args: string[], timeout?: number, ownedHelpers?: OwnedHelperScope): Promise<string>;
+/** `nemaHome` is the directory that must not contain `repoPath`, usually `~/.nema`. */
+export declare function inspectRepo(repoPath: string, nemaHome: string, ownedHelpers?: OwnedHelperScope): Promise<RepoInspect>;
+export declare function mainRef(repoPath: string, mainBranch: string, ownedHelpers?: OwnedHelperScope): Promise<string>;
+export declare function fetchMain(repoPath: string, mainBranch: string, ownedHelpers?: OwnedHelperScope): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+}>;
+export declare function revParse(repoPath: string, ref: string, ownedHelpers?: OwnedHelperScope): Promise<string>;
+export declare function readFileAtRef(repoPath: string, ref: string, relPath: string, range?: {
+    startLine?: number;
+    endLine?: number;
+}, ownedHelpers?: OwnedHelperScope): Promise<FileAtRef>;
+/** The paths (normalized) that are not in the tree of `ref`. A path that is absolute or has `..` throws. */
+export declare function missingAtRef(repoPath: string, ref: string, paths: string[], ownedHelpers?: OwnedHelperScope): Promise<string[]>;
+/**
+ * What changed between two commits of the bound main branch. Each of `from`/`to` is either the main ref
+ * itself (`origin/<mainBranch>`, or the local branch without one) or a sha that main already contains, so
+ * a side branch or an unpushed local commit is never read.
+ */
+export declare function changedFiles(repoPath: string, from: string, to: string, mainBranch: string, ownedHelpers?: OwnedHelperScope): Promise<ChangedFile[]>;
+/** The raw diff between two refs, for the daemon's own index sync. Plugin calls go through `changedFiles`. */
+export declare function diffNameStatus(repoPath: string, from: string, to: string, ownedHelpers?: OwnedHelperScope): Promise<ChangedFile[]>;
+export declare function exportSnapshot(repoPath: string, ref: string, destDir: string, ownedHelpers?: OwnedHelperScope): Promise<void>;