@niroai/niro 0.3.0

package/src/lib/service.js

@@ -0,0 +1,221 @@
+/**
+ * niro-watch daemon management via PM2.
+ *
+ * PM2 is OS-agnostic — it wraps systemd on Linux, launchd on macOS, and
+ * Task Scheduler on Windows. We never write init files ourselves.
+ *
+ * install()  — start niro-watch under PM2, persist it, hook into OS startup
+ * uninstall() — stop and remove from PM2 + OS startup
+ * status()   — print PM2 status for niro-watch
+ */
+const { spawnSync } = require("child_process");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const color = require("./color");
+
+const PROCESS_NAME = "niro-watch";
+
+/**
+ * True when the pm2 binary is on PATH. Deliberately a PATH lookup and NOT
+ * `pm2 --version`: running ANY pm2 command boots PM2's God daemon as a side
+ * effect (1s+ on first run, leaves a background process behind). Probes like
+ * `niro status` must never do that; flows that go on to run pm2 anyway
+ * (install/uninstall) don't care either way.
+ */
+function pm2Available() {
+  const probe = process.platform === "win32" ? "where pm2" : "command -v pm2";
+  const r = spawnSync(probe, { encoding: "utf8", shell: true, stdio: "pipe" });
+  return r.status === 0;
+}
+
+function pm2Home() {
+  return process.env.PM2_HOME || path.join(os.homedir(), ".pm2");
+}
+
+/** True when PM2's God daemon is up (live pid in ~/.pm2/pm2.pid). */
+function pm2DaemonAlive() {
+  try {
+    const pid = parseInt(fs.readFileSync(path.join(pm2Home(), "pm2.pid"), "utf8").trim(), 10);
+    if (!pid) return false;
+    process.kill(pid, 0); // signal 0 = existence check, sends nothing
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** True when PM2's saved process list (pm2 save) includes niro-watch. */
+function dumpHasProcess() {
+  try {
+    return fs.readFileSync(path.join(pm2Home(), "dump.pm2"), "utf8").includes(`"${PROCESS_NAME}"`);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Install and start the niro-watch PM2 process, then wire it into the OS
+ * startup system. Prints an explanation before each privileged step.
+ *
+ * Returns true on success, false if PM2 is not installed.
+ */
+function install() {
+  if (!pm2Available()) return false;
+
+  const niroBin = process.argv[1];
+
+  // Stop any existing instance so we can re-register cleanly
+  spawnSync("pm2", ["delete", PROCESS_NAME], { shell: true, stdio: "pipe" });
+
+  // Start niro-watch under PM2
+  const startResult = spawnSync(
+    "pm2",
+    ["start", niroBin, "--name", PROCESS_NAME, "--", "watch"],
+    { shell: true, stdio: "inherit" }
+  );
+  if (startResult.status !== 0) {
+    throw new Error("pm2 start failed");
+  }
+
+  // Persist the process list so PM2 restores it after a manual `pm2 resurrect`
+  spawnSync("pm2", ["save"], { shell: true, stdio: "inherit" });
+
+  // Wire into OS startup — pm2 startup detects systemd / launchd / etc.
+  // It prints the exact privileged command we need to run.
+  console.log(
+    `\n  ${color.bold("Setting up auto-start on login")} — PM2 will ask for your password to register`
+  );
+  console.log(
+    `  with the system startup manager (${getInitSystem()}). This only needs to happen once.\n`
+  );
+
+  const startupProbe = spawnSync("pm2", ["startup"], {
+    shell: true,
+    encoding: "utf8",
+  });
+
+  const setupCmd = extractSetupCommand(startupProbe.stdout + startupProbe.stderr);
+  if (setupCmd) {
+    console.log(`  Running: ${color.dim(setupCmd)}\n`);
+    const r = spawnSync(setupCmd, {
+      shell: true,
+      stdio: "inherit",
+    });
+    if (r.status !== 0) {
+      console.log(
+        color.yellow(
+          `  ⚠ Startup hook failed (exit ${r.status}). You can run it manually:\n    ${setupCmd}`
+        )
+      );
+    }
+  } else {
+    // PM2 may print nothing if startup is already configured
+    console.log(`  ${color.green("✓")} Startup already configured.`);
+  }
+
+  return true;
+}
+
+/**
+ * Stop niro-watch and remove it from PM2 + OS startup hooks.
+ */
+function uninstall() {
+  if (!pm2Available()) return false;
+
+  spawnSync("pm2", ["delete", PROCESS_NAME], { shell: true, stdio: "inherit" });
+  spawnSync("pm2", ["save"], { shell: true, stdio: "inherit" });
+
+  console.log(
+    `\n  ${color.bold("Removing auto-start hook")} — PM2 may ask for your password.\n`
+  );
+  const unstartupResult = spawnSync("pm2", ["unstartup"], {
+    shell: true,
+    encoding: "utf8",
+  });
+  const setupCmd = extractSetupCommand(
+    unstartupResult.stdout + unstartupResult.stderr
+  );
+  if (setupCmd) {
+    console.log(`  Running: ${color.dim(setupCmd)}\n`);
+    spawnSync(setupCmd, { shell: true, stdio: "inherit" });
+  }
+
+  return true;
+}
+
+/**
+ * Print PM2 process status for niro-watch.
+ */
+function status() {
+  if (!pm2Available()) {
+    console.log(color.yellow("  PM2 is not installed. Run: npm install -g pm2"));
+    return;
+  }
+  spawnSync("pm2", ["show", PROCESS_NAME], { shell: true, stdio: "inherit" });
+}
+
+/**
+ * Read-only probe of the niro-watch PM2 process.
+ * Returns "missing" (never registered), "online", or "stopped".
+ * Callers must check pm2Available() first — without PM2 everything below
+ * also reads as "missing", which conflates two different problems.
+ *
+ * When PM2's God daemon is down, `pm2 show` would BOOT it as a side effect —
+ * so answer from disk instead: a dead daemon means nothing is running, and
+ * the saved dump distinguishes "registered but stopped" from "never
+ * installed". Only a live daemon is asked directly (no boot risk then).
+ */
+function processState() {
+  if (!pm2DaemonAlive()) {
+    return dumpHasProcess() ? "stopped" : "missing";
+  }
+  const r = spawnSync("pm2", ["show", PROCESS_NAME], {
+    shell: true,
+    encoding: "utf8",
+    stdio: "pipe",
+  });
+  if (r.status !== 0) return "missing";
+  return (r.stdout || "").includes("online") ? "online" : "stopped";
+}
+
+/**
+ * Install PM2 globally (`npm install -g pm2`), streaming npm's own output so
+ * the user sees progress and any permission error verbatim. Returns true on
+ * success. shell:true so npm.cmd resolves on Windows.
+ */
+function installPm2() {
+  const r = spawnSync("npm", ["install", "-g", "pm2"], { shell: true, stdio: "inherit" });
+  return r.status === 0;
+}
+
+// ─── helpers ─────────────────────────────────────────────────────────────────
+
+/**
+ * PM2 `startup` / `unstartup` prints a line like:
+ *   [PM2] To setup the Startup Script, copy/paste the following command:
+ *   sudo env PATH=$PATH:/usr/bin /usr/lib/node_modules/pm2/bin/pm2 startup systemd ...
+ *
+ * We extract that command so we can run it directly.
+ */
+function extractSetupCommand(output) {
+  if (!output) return null;
+  const lines = output.split("\n");
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("sudo ") || trimmed.startsWith("& ")) {
+      return trimmed;
+    }
+  }
+  return null;
+}
+
+function getInitSystem() {
+  switch (process.platform) {
+    case "darwin": return "launchd";
+    case "win32":  return "Task Scheduler";
+    default:       return "systemd";
+  }
+}
+
+module.exports = { install, uninstall, status, processState, pm2Available, installPm2 };

package/src/lib/spinner.js

@@ -0,0 +1,109 @@
+/**
+ * Tiny spinner with optional label + elapsed time. No dependencies.
+ *
+ * Two output modes, picked once at start():
+ *
+ *   TTY  — animated Braille spinner, redrawn in place. Every frame erases the
+ *          whole line (`\r` + ESC[2K) and is truncated to the terminal width,
+ *          because a line that wraps can no longer be overwritten by `\r` —
+ *          narrow panes were printing a brand-new line every 120ms frame.
+ *
+ *   non-TTY (piped output, agent panes, TERM=dumb) — no cursor control is
+ *          available, so the label is printed ONCE, followed by a quiet
+ *          heartbeat line every 30s. The old behaviour (print nothing) left
+ *          users waiting in silence with no hint to check their browser.
+ *
+ * `opts.stream` / `opts.heartbeatMs` are injection seams for tests; production
+ * callers pass only the label.
+ */
+const color = require("./color");
+
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const FRAME_MS = 120;
+const HEARTBEAT_MS = 30_000;
+const ERASE_LINE = "\r\x1b[2K";
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+
+/**
+ * Fit `line` (which may contain ANSI color codes) into `width` visible
+ * characters. Returns the line unchanged when it already fits; otherwise
+ * returns a color-stripped, "…"-terminated slice — truncating around escape
+ * codes is not worth the complexity for an overflow case.
+ */
+function fit(line, width) {
+  const plain = line.replace(ANSI_RE, "");
+  if (plain.length <= width) return line;
+  return plain.slice(0, Math.max(0, width - 1)) + "…";
+}
+
+/**
+ * Labels can carry backend text (e.g. build log messages); an embedded
+ * newline would defeat the single-line overwrite, so flatten whitespace.
+ */
+function sanitize(label) {
+  return String(label).replace(/\s+/g, " ").trim();
+}
+
+function start(label, opts = {}) {
+  label = sanitize(label);
+  const stream = opts.stream || process.stderr;
+  const heartbeatMs = opts.heartbeatMs || HEARTBEAT_MS;
+  const startedAt = Date.now();
+  // TERM=dumb terminals ignore \r-overwrite even when isTTY is true.
+  const isTty = Boolean(stream.isTTY) && process.env.TERM !== "dumb";
+  const elapsed = () => Math.floor((Date.now() - startedAt) / 1000);
+
+  // Callers may stop() twice (success path + a finally block); only the first
+  // stop draws anything.
+  let stopped = false;
+
+  if (!isTty) {
+    stream.write(`${label}\n`);
+    const timer = setInterval(() => {
+      stream.write(`${label} ${color.dim(`(still waiting — ${elapsed()}s)`)}\n`);
+    }, heartbeatMs);
+    if (timer.unref) timer.unref();
+    return {
+      update(newLabel) {
+        newLabel = sanitize(newLabel);
+        if (stopped || newLabel === label) return;
+        label = newLabel;
+        stream.write(`${label}\n`);
+      },
+      stop(finalLine) {
+        clearInterval(timer);
+        if (stopped) return;
+        stopped = true;
+        if (finalLine) stream.write(finalLine + "\n");
+      },
+    };
+  }
+
+  let i = 0;
+  const render = () => {
+    const frame = FRAMES[i = (i + 1) % FRAMES.length];
+    const line = `${color.cyan(frame)} ${label} ${color.dim("(" + elapsed() + "s)")}`;
+    stream.write(ERASE_LINE + fit(line, (stream.columns || 80) - 1));
+  };
+
+  render();
+  const timer = setInterval(render, FRAME_MS);
+  if (timer.unref) timer.unref();
+
+  return {
+    update(newLabel) {
+      if (stopped) return;
+      label = sanitize(newLabel);
+      render();
+    },
+    stop(finalLine) {
+      clearInterval(timer);
+      if (stopped) return;
+      stopped = true;
+      stream.write(ERASE_LINE);
+      if (finalLine) stream.write(finalLine + "\n");
+    },
+  };
+}
+
+module.exports = { start };

package/src/lib/watchDaemon.js

@@ -0,0 +1,93 @@
+/**
+ * Shared "make sure the niro-watch daemon is running" flow, used by
+ * `niro init`, `niro add repo`, and `niro service install`.
+ *
+ * Previously init and add-repo each had their own copy that, when PM2 was
+ * missing, printed a small warning and moved on — customers read the final
+ * "✓ Done." and only discovered auto-sync was dead after a reboot. This
+ * helper instead OFFERS to install PM2 on the spot (interactive runs), and
+ * returns a result object so callers can make their closing banner honest.
+ *
+ * All service/prompt collaborators are called through their module objects so
+ * tests can stub them with t.mock.method (same seam the init tests use).
+ */
+const service = require("./service");
+const prompt = require("./prompt");
+const color = require("./color");
+
+/**
+ * Ensure PM2 exists (offering to install it when allowed to ask), then
+ * install/start the niro-watch daemon.
+ *
+ * `skipPrompts` MUST be passed as true by flows that promised not to ask
+ * (`niro init --defaults`, `niro add repo --no-confirm`) — installing global
+ * software needs an explicit yes, so those flows get the warning path, never
+ * a hanging prompt or a consent-by-default-Enter npm install.
+ *
+ * Returns { ok: true } on success, or { ok: false, reason } where reason is:
+ *   "pm2_missing"         — no PM2, and no prompt allowed (non-interactive
+ *                           or skipPrompts)
+ *   "declined"            — user said no to installing PM2
+ *   "pm2_install_failed"  — `npm install -g pm2` exited non-zero
+ *   "daemon_install_failed" — registering niro-watch under PM2 failed
+ */
+async function ensureWatchDaemon({ skipPrompts = false } = {}) {
+  if (!service.pm2Available()) {
+    console.log(`\n  ${color.yellow("⚠")} PM2 is not installed. Niro uses PM2 to keep your synced folders`);
+    console.log(`    up to date in the background, including after a reboot.`);
+
+    if (skipPrompts || prompt.isNonInteractive()) {
+      console.log(`    To enable auto-sync: ${color.cyan("npm install -g pm2")} then ${color.cyan("niro service install")}`);
+      return { ok: false, reason: "pm2_missing" };
+    }
+
+    const yes = await prompt.confirm(`    Install PM2 now? (runs: npm install -g pm2)`, true);
+    if (!yes) {
+      console.log(`    Skipped. Enable auto-sync later with: ${color.cyan("npm install -g pm2")} then ${color.cyan("niro service install")}`);
+      return { ok: false, reason: "declined" };
+    }
+
+    console.log("");
+    if (!service.installPm2()) {
+      console.log(`\n  ${color.yellow("⚠")} PM2 install failed (a permission error is the usual cause).`);
+      console.log(`    Try manually: ${color.cyan("sudo npm install -g pm2")} then ${color.cyan("niro service install")}`);
+      return { ok: false, reason: "pm2_install_failed" };
+    }
+    console.log(`  ${color.green("✓")} PM2 installed.`);
+  }
+
+  console.log(`\n  ${color.cyan("●")}  Installing niro-watch daemon (keeps your synced folders up to date, auto-starts on login)...`);
+  try {
+    // install() returns false when pm2 turns out not to be runnable after
+    // all — e.g. npm installed it into a global bin dir that isn't on PATH
+    // (npm exits 0 for that). Treat it as the failure it is; the old code's
+    // unchecked call here is how "✓ Done." lied to customers.
+    if (!service.install()) {
+      console.log(`       ${color.yellow("⚠")} PM2 was installed but isn't runnable from this shell (its global bin`);
+      console.log(`       directory may not be on your PATH). Open a NEW terminal and run ${color.cyan("niro service install")}.`);
+      return { ok: false, reason: "daemon_install_failed" };
+    }
+    console.log(`       ${color.green("✓")} niro-watch is running and will start automatically on login.`);
+    return { ok: true };
+  } catch (err) {
+    console.log(`       ${color.yellow("⚠")} Could not install the watch daemon: ${err.message}`);
+    console.log(`       Run ${color.cyan("niro service install")} to try again, or ${color.cyan("niro watch")} to sync manually.`);
+    return { ok: false, reason: "daemon_install_failed" };
+  }
+}
+
+/**
+ * Read-only daemon probe for `niro status`:
+ * "pm2_missing" | "not_installed" | "stopped" | "running".
+ *
+ * Must stay side-effect free and fast — status is polled by agents. The
+ * underlying service calls avoid booting PM2's God daemon (see service.js).
+ */
+function watchDaemonState() {
+  if (!service.pm2Available()) return "pm2_missing";
+  const st = service.processState();
+  if (st === "missing") return "not_installed";
+  return st === "online" ? "running" : "stopped";
+}
+
+module.exports = { ensureWatchDaemon, watchDaemonState };

package/src/lib/watchState.js

@@ -0,0 +1,217 @@
+/**
+ * Manages ~/.niro/projects.json — persists per-folder sync state so that
+ * niro watch can resume without re-registering or re-uploading all files.
+ *
+ * Shape of each entry (keyed by absolute folder path):
+ * {
+ *   gitId: string,
+ *   apiUrl: string | undefined,   // backend the gitId was registered against
+ *   projectId: string | null,
+ *   branch: string | null,
+ *   includePatterns: string[],
+ *   excludePatterns: string[],
+ *   fileHashes: { [relativePath]: sha256hex },
+ *   lastSyncedAt: ISO string | null
+ * }
+ *
+ * `apiUrl` scopes an entry to one backend. A gitId is only valid against the
+ * backend that allocated it, so backend-aware reads (`get`, `allLocal`,
+ * `findOverlapping`) take the current backend URL and ignore entries that
+ * belong to a different one. Entries written before this field existed have no
+ * apiUrl and are treated as wildcard (match any backend) — the init self-heal
+ * (repoExists check) backstops a wildcard entry that turns out to be stale.
+ */
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const crypto = require("crypto");
+
+const DIR = path.join(os.homedir(), ".niro");
+const FILE = path.join(DIR, "projects.json");
+
+/**
+ * Canonical backend URL for comparison: trim trailing slash(es) and lowercase
+ * scheme+host. Kept in sync with api.normalizeUrl (duplicated, not imported, to
+ * keep this storage module free of the HTTP/credentials layer). In practice both
+ * sides of a comparison are already produced by api.currentBaseUrl(); this is the
+ * defensive backstop for a caller that passes a raw URL.
+ */
+function normalizeUrl(u) {
+  const s = String(u || "").trim().replace(/\/+$/, "");
+  try {
+    const url = new URL(s);
+    url.protocol = url.protocol.toLowerCase();
+    url.host = url.host.toLowerCase();
+    return url.toString().replace(/\/+$/, "");
+  } catch {
+    return s;
+  }
+}
+
+/**
+ * True if `entry` belongs to the backend at `apiUrl`. When `apiUrl` is omitted
+ * the caller does not care about the backend (legacy/internal reads) → always
+ * true. An entry with no `apiUrl` is wildcard → matches any backend.
+ */
+function matchesBackend(entry, apiUrl) {
+  if (!apiUrl) return true;
+  if (!entry || !entry.apiUrl) return true;
+  return normalizeUrl(entry.apiUrl) === normalizeUrl(apiUrl);
+}
+
+function load() {
+  try {
+    return JSON.parse(fs.readFileSync(FILE, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function save(state) {
+  fs.mkdirSync(DIR, { recursive: true, mode: 0o700 });
+  // Atomic write: a concurrent reader (the niro-watch daemon runs in a SEPARATE
+  // process) must never observe a half-written file. Write to a per-process temp
+  // in the same dir, then rename — rename is atomic on the same filesystem, so a
+  // reader sees either the whole old file or the whole new one, never a torn one.
+  const tmp = `${FILE}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(state, null, 2) + "\n", { mode: 0o600 });
+  fs.renameSync(tmp, FILE);
+}
+
+/**
+ * Look up the entry for a folder. When `apiUrl` is passed, the entry is returned
+ * only if it belongs to that backend (or is a legacy untagged/wildcard entry);
+ * an entry tagged for a different backend returns null so callers never reuse a
+ * foreign gitId.
+ */
+function get(folderPath, apiUrl) {
+  const entry = load()[path.resolve(folderPath)] || null;
+  if (!entry) return null;
+  return matchesBackend(entry, apiUrl) ? entry : null;
+}
+
+/**
+ * Return the RAW entry for a folder regardless of backend, or null. The store is path-keyed (one entry per
+ * folder), so a backend-scoped `get` returns null for an entry tagged to a DIFFERENT backend even though
+ * writing would overwrite it. Callers about to `set` a path use `peek` to avoid clobbering a real
+ * registration / takeover backup that lives on another backend.
+ */
+function peek(folderPath) {
+  return load()[path.resolve(folderPath)] || null;
+}
+
+/**
+ * Persist an entry for a folder. When `apiUrl` is passed it is stamped onto the
+ * entry (normalized) so future reads can scope it to the backend that allocated
+ * the gitId.
+ */
+function set(folderPath, entry, apiUrl) {
+  const state = load();
+  const tagged = apiUrl ? { ...entry, apiUrl: normalizeUrl(apiUrl) } : entry;
+  state[path.resolve(folderPath)] = tagged;
+  save(state);
+}
+
+/**
+ * Merge `patch` into an EXISTING entry. If the entry is absent it is NOT created
+ * — `update` only ever refines an entry that `set` already established. This also
+ * stops a stray daemon update (e.g. a debounced file event landing just after
+ * `init` removed a stale entry, from a separate process) from resurrecting a
+ * partial, gitId-less entry on the now-wrong backend.
+ */
+function update(folderPath, patch) {
+  const state = load();
+  const key = path.resolve(folderPath);
+  if (!state[key]) return;
+  state[key] = { ...state[key], ...patch };
+  save(state);
+}
+
+/**
+ * Remove a folder's entry. When `expectedGitId` is given, only remove if the CURRENT entry still has that
+ * gitId (compare-and-delete): the self-heal path removes a poison entry after an async repoExists round-trip,
+ * during which a concurrent `niro new-temp-project` may have re-pointed the folder to a NEW, valid gitId —
+ * removing it by path alone would silently drop that fresh registration. Mismatch => keep, return false.
+ */
+function remove(folderPath, expectedGitId) {
+  const state = load();
+  const key = path.resolve(folderPath);
+  if (expectedGitId !== undefined && state[key] && state[key].gitId !== expectedGitId) {
+    return false; // re-pointed under us — do not clobber the new registration
+  }
+  delete state[key];
+  save(state);
+  return true;
+}
+
+/**
+ * Return all entries that have a gitId (registered local repos). When `apiUrl`
+ * is passed, only repos belonging to that backend (plus legacy untagged ones)
+ * are returned — so the watch daemon never tries to sync a foreign-backend repo.
+ */
+function allLocal(apiUrl) {
+  const state = load();
+  return Object.entries(state)
+    .filter(([, v]) => v.gitId)
+    .filter(([, v]) => matchesBackend(v, apiUrl))
+    .map(([folderPath, entry]) => ({ folderPath, ...entry }));
+}
+
+/**
+ * Return watchState entries whose resolved folder path is a STRICT ancestor OR
+ * descendant of `targetDir` — i.e. a nesting overlap, not the exact same folder.
+ *
+ * Used by `niro init` to refuse/warn when the folder being onboarded sits inside
+ * (or contains) a folder already tracked by Niro. The exact-path entry is the
+ * normal re-run case (handled by `get`) and is excluded here.
+ *
+ * Overlap is checked on path SEGMENT boundaries, not a bare `startsWith`, so that
+ * `/a/foo` is NOT treated as nested under `/a/foobar` (they only share a string
+ * prefix, not a directory boundary). Both paths are resolved to absolute first.
+ *
+ * Returns [{ path, gitId, projectId }] for each overlapping entry.
+ *
+ * When `apiUrl` is passed, only overlaps tracked on the current backend (plus
+ * legacy untagged entries) are reported — a folder tracked on a different
+ * backend is not a live overlap for this one.
+ */
+function findOverlapping(targetDir, apiUrl) {
+  const target = path.resolve(targetDir);
+  const state = load();
+  const out = [];
+  for (const [folderPath, entry] of Object.entries(state)) {
+    const other = path.resolve(folderPath);
+    if (other === target) continue; // exact match is the re-run case, not an overlap
+    if (!matchesBackend(entry, apiUrl)) continue; // different backend → not a live overlap
+    if (isAncestor(other, target) || isAncestor(target, other)) {
+      out.push({ path: other, gitId: entry.gitId || null, projectId: entry.projectId || null });
+    }
+  }
+  return out;
+}
+
+/**
+ * True when `parent` is a STRICT directory ancestor of `child` (child lives
+ * inside parent). Uses path.relative so the check is on real segment boundaries:
+ * the relative path must be non-empty, must not start with ".." (child is not
+ * outside parent), and must not be absolute (different drive/root).
+ */
+function isAncestor(parent, child) {
+  const rel = path.relative(parent, child);
+  if (!rel) return false; // same path
+  if (rel === ".." || rel.startsWith(".." + path.sep)) return false;
+  if (path.isAbsolute(rel)) return false;
+  return true;
+}
+
+/** Compute SHA-256 of a file's contents. Used for delta detection on resume. */
+function hashFile(filePath) {
+  try {
+    const buf = fs.readFileSync(filePath);
+    return crypto.createHash("sha256").update(buf).digest("hex");
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { get, peek, set, update, remove, allLocal, findOverlapping, matchesBackend, hashFile, FILE };