@niroai/niro 0.17.0 → 1.0.0

package/src/lib/shareCode.js

@@ -0,0 +1,367 @@
+/**
+ * Background code sharing: while "Help improve Niro" is on, the watcher sends the code of every
+ * folder Niro indexes on this machine, redacted here first.
+ *
+ * **Why it exists.** Until 2026-11-11 only a typed `niro audit-push-repo` sent code, so the Free
+ * plan's "no line limit while you share" shared nothing unless the user acted. Niraj, 2026-11-11:
+ * "we need the pm2 to share the code as well", then "1. this release 2. no cap but we send what is
+ * indexed with niro, okay? so the files and config files considered by niro when indexing 3. yes"
+ * (3: a user may exclude a folder while sharing stays on). Decision 01M75JHE64PYYNKR2G4JJ4JCZ3.
+ *
+ * **What decides whether anything is sent.** All of these, every round, and any doubt is a no:
+ *
+ * - the licence lease says `share_code: true` and its `expires_at` has not passed. A lease that cannot
+ *   be fetched or read sends nothing, and so does an expired one (independent check of 31ffc5f,
+ *   finding 2: an expired lease saying `share_code: true` sent 7 files). A clock running ahead stops
+ *   sharing, which is the safe direction.
+ *   Switching sharing on in the console is the consent, so nothing is asked on the machine. It is
+ *   asked again before each batch (at most once a minute), so switching sharing off stops a long
+ *   first upload part way, and the next round sends nothing at all;
+ * - the folder is indexed by the engine on this machine and still on disk;
+ * - the folder is not excluded (`niro share exclude`, shareExclusions.js). Also re-read before each
+ *   batch. A file under an excluded folder inside an indexed folder is left out of the list
+ *   (shareFiles.indexedFiles), and is not deleted on the server either: excluding only stops future
+ *   uploads (Niraj, 2026-11-11, decision 01M75MFAMNACNE0W5Q4GMJF05Q, answer 2).
+ *
+ * **Which files, and how they are redacted:** shareFiles.js, the same as `niro audit-push-repo`: the
+ * engine's own list of what it indexes, masked by the engine with llm-gateway's rules, then author
+ * and company names removed by redact.js. Uploads read the masked copies in a private temporary
+ * folder, which is deleted whatever happens. No content is ever logged: counts only.
+ *
+ * **What is sent when.** The first time a folder is shared, its whole indexed file set; after that,
+ * only files whose content changed (sha256 of the file on disk), and a delete for files that left
+ * the set. No size cap: files go in batches (`NIRO_SHARE_BATCH_FILES`, 200), each its own sync
+ * session, which the server merges into the workspace (AgentSyncService.completeSyncSession). An
+ * HTTP 409 (the server already holds it) counts as sent.
+ *
+ * **The record**, `~/.niro/shared-code.json` (0600): per folder, the workspace it went to and, per
+ * file, `[sha256, size, mtimeMs]` of what was last handled (sent, or left out for a reason that only
+ * a change to the file can undo). Written after every batch with a rename, so a restart resumes where
+ * the last completed batch ended and resends nothing that batch held. Bounded: a folder's entry holds
+ * only files in its current set, and the entry of a folder gone from disk, no longer indexed, or
+ * excluded is removed (an excluded folder is sent whole again if it is included later).
+ *
+ * The workspace is the one `niro audit-push-repo` uses for the same folder (repoPush.sharedWorkspace,
+ * registered with the sharing mark), so the server deletes this code too when sharing is switched off.
+ */
+const crypto = require("crypto");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const shareExclusions = require("./shareExclusions");
+const shareFiles = require("./shareFiles");
+
+/** Files per sync session. Small enough that a restart loses little, large enough to be few requests. */
+const DEFAULT_BATCH_FILES = 200;
+
+/** The lease is asked again before a batch when the last answer is older than this. */
+const RECHECK_MS = 60_000;
+
+function batchFiles() {
+  const value = Number.parseInt(process.env.NIRO_SHARE_BATCH_FILES, 10);
+  return Number.isFinite(value) && value > 0 ? value : DEFAULT_BATCH_FILES;
+}
+
+function recordFile() {
+  // Read at call time so a test's scratch HOME is honoured.
+  return path.join(os.homedir(), ".niro", "shared-code.json");
+}
+
+function loadRecord() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(recordFile(), "utf8"));
+    if (parsed && parsed.version === 1 && parsed.folders && typeof parsed.folders === "object" && !Array.isArray(parsed.folders)) {
+      return parsed;
+    }
+  } catch {
+    // None yet, or unreadable: every folder is sent whole again, which resends but loses nothing.
+  }
+  return { version: 1, folders: {} };
+}
+
+function saveRecord(record) {
+  const target = recordFile();
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  const tmp = `${target}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(record) + "\n", { mode: 0o600 });
+  fs.renameSync(tmp, target);
+}
+
+/**
+ * Does this lease allow sending code now? `share_code` must be exactly true and `expires_at` (seconds)
+ * still ahead of `nowMs`. Anything missing or odd is no.
+ */
+function sharingAllowed(claims, nowMs) {
+  if (!claims || claims.share_code !== true) return false;
+  const expiresAt = Number(claims.expires_at);
+  return Number.isFinite(expiresAt) && expiresAt * 1000 > nowMs;
+}
+
+function sha256(file) {
+  return crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+}
+
+/** An HTTP 409: the server already holds what was sent. */
+function isConflict(err) {
+  return Boolean(err) && (err.status === 409 || /\bHTTP 409\b/.test(String(err.message || "")));
+}
+
+/** A delete of something the server does not have is done. */
+function isGone(err) {
+  return Boolean(err) && (err.status === 404 || err.status === 410);
+}
+
+/** The folders the engine indexes on this machine that are still on disk, each once. */
+async function indexedFolders(run) {
+  const parsed = JSON.parse(await run(["projects", "--json"]));
+  const seen = new Set();
+  for (const project of parsed.projects || []) {
+    for (const w of project.worktrees || []) {
+      if (!w || typeof w.path !== "string") continue;
+      const folder = path.resolve(w.path);
+      if (!seen.has(folder) && fs.existsSync(folder)) seen.add(folder);
+    }
+  }
+  return [...seen];
+}
+
+let running = false;
+
+/**
+ * The masked-copy folders' prefix, in the system's temporary folder. It names this user, so on a
+ * machine where several users share `/tmp` one user's leftover is never another's to delete
+ * (independent check of 31ffc5f, finding 3).
+ */
+function copiesPrefix() {
+  let who;
+  try {
+    who = typeof process.getuid === "function" ? String(process.getuid()) : os.userInfo().username;
+  } catch {
+    who = "user";
+  }
+  return `niro-share-masked-${String(who).replace(/[^A-Za-z0-9_.-]/g, "_")}-`;
+}
+
+/**
+ * Remove masked copies an earlier process left behind: a process stopped during an upload (a PM2
+ * restart, a reboot) never reaches the `finally` that deletes them. Only one round runs at a time
+ * on a machine (the watcher's periodic claim and `running`), so none of these is in use. A leftover
+ * that cannot be deleted is skipped with one log line for the round: it holds masked copies only,
+ * and it must not stop sharing for good (finding 3: one undeletable folder failed every round).
+ */
+function sweepLeftCopies(log = console.log) {
+  let names = [];
+  try {
+    names = fs.readdirSync(os.tmpdir());
+  } catch {
+    return;
+  }
+  const prefix = copiesPrefix();
+  const stuck = [];
+  for (const name of names) {
+    if (!name.startsWith(prefix)) continue;
+    try {
+      fs.rmSync(path.join(os.tmpdir(), name), { recursive: true, force: true });
+    } catch (err) {
+      stuck.push(`${name} (${(err && err.code) || "error"})`);
+    }
+  }
+  if (stuck.length) {
+    log(`    Could not delete ${stuck.length} leftover folder(s) of masked copies in ${os.tmpdir()}, skipped: ${stuck[0]}`);
+  }
+}
+
+/**
+ * One round: share what changed in every indexed folder. Returns `{ sent, deleted, off, busy }`.
+ * Throws, after trying every folder, when a folder could not be shared, so the watcher says so.
+ */
+async function shareRound({
+  currentClaims = (...a) => require("./lease").currentClaims(...a),
+  run = (...a) => require("./localEngine").run(...a),
+  redactFiles = shareFiles.engineRedact,
+  now = Date.now,
+  log = console.log,
+} = {}) {
+  if (running) return { sent: 0, deleted: 0, busy: true };
+  running = true;
+  try {
+    // The gate. Unknown is no: a lease that cannot be fetched or read sends nothing.
+    const claims = await currentClaims().catch(() => null);
+    if (!sharingAllowed(claims, now())) return { sent: 0, deleted: 0, off: true };
+
+    const api = require("./api");
+    const agentApi = require("./agentApi");
+    const repoPush = require("./repoPush");
+    await api.ensureFreshToken();
+
+    let checkedAt = now();
+    const stillOn = async () => {
+      if (now() - checkedAt < RECHECK_MS) return true;
+      const again = await currentClaims().catch(() => null);
+      checkedAt = now();
+      return sharingAllowed(again, checkedAt);
+    };
+
+    sweepLeftCopies(log);
+    const folders = await indexedFolders(run);
+    const record = loadRecord();
+    // Bounded: a folder gone from disk, no longer indexed, or excluded loses its entry. An exclusion
+    // list that cannot be read removes nothing here (nothing is sent either), so fixing it does not
+    // send every folder whole again.
+    const indexed = new Set(folders);
+    const excluded = shareExclusions.read();
+    for (const [key, entry] of Object.entries(record.folders)) {
+      if (
+        !entry ||
+        typeof entry.folder !== "string" ||
+        !fs.existsSync(entry.folder) ||
+        !indexed.has(path.resolve(entry.folder)) ||
+        (excluded !== null && shareExclusions.covers(excluded, shareExclusions.canonical(entry.folder)))
+      ) {
+        delete record.folders[key];
+      }
+    }
+
+    const totals = { sent: 0, deleted: 0 };
+    const problems = [];
+    for (const folder of folders) {
+      if (shareExclusions.isExcluded(folder)) continue;
+      try {
+        const stopped = await shareFolder(folder, {
+          record, claims, run, redactFiles, stillOn, totals, api, agentApi, repoPush,
+        });
+        if (stopped) break;
+      } catch (err) {
+        problems.push((err && err.message) || String(err));
+      }
+    }
+    saveRecord(record);
+    if (problems.length) {
+      throw new Error(
+        `${problems.length} folder(s) could not be shared (${totals.sent} file(s) were sent): ${String(problems[0]).split("\n")[0].slice(0, 200)}`
+      );
+    }
+    return { ...totals, off: false };
+  } finally {
+    running = false;
+  }
+}
+
+/** Share one folder's changes. Returns true when sharing was switched off part way. */
+async function shareFolder(folder, { record, claims, run, redactFiles, stillOn, totals, agentApi, repoPush }) {
+  const listing = await shareFiles.indexedFiles(folder, { run });
+  if (!listing.indexed) return false;
+  const key = repoPush.keyFor(folder);
+  const entry = record.folders[key] || { folder, gitId: null, files: {} };
+  record.folders[key] = entry;
+  entry.folder = folder;
+
+  // What is on disk now, and which of it differs from what was last handled.
+  const current = new Map();
+  let changed = [];
+  for (const file of listing.files) {
+    const absolute = path.join(folder, file.path);
+    let stat;
+    try {
+      stat = fs.statSync(absolute);
+    } catch {
+      continue; // gone since the engine listed it
+    }
+    const before = entry.files[file.path];
+    let sha;
+    if (Array.isArray(before) && before[1] === stat.size && before[2] === stat.mtimeMs) sha = before[0];
+    else sha = sha256(absolute);
+    const now = [sha, stat.size, stat.mtimeMs];
+    current.set(file.path, now);
+    if (!Array.isArray(before) || before[0] !== sha) changed.push({ path: file.path, bytes: stat.size });
+    else entry.files[file.path] = now; // same content, newer time: no resend
+  }
+  // A file under an excluded folder is not "removed": excluding stops future uploads and asks the
+  // server to delete nothing (decision 01M75MFAMNACNE0W5Q4GMJF05Q, answer 2). Its entry goes, so it is
+  // sent again if the folder is included later.
+  const held = new Set(listing.held || []);
+  for (const relative of Object.keys(entry.files)) if (held.has(relative)) delete entry.files[relative];
+  const removed = Object.keys(entry.files).filter((relative) => !current.has(relative));
+
+  if (changed.length) {
+    let workspace = await repoPush.sharedWorkspace(folder, claims.account_id, shareFiles.manifestOf(changed));
+    if (workspace.refused) throw new Error(workspace.refused);
+    if (entry.gitId && entry.gitId !== workspace.gitId) {
+      // A new workspace (the server deleted the old one, or another account): it holds nothing yet,
+      // so the whole set goes to it.
+      entry.files = {};
+      changed = [...current.keys()].map((relative) => ({ path: relative, bytes: current.get(relative)[1] }));
+      workspace = { gitId: workspace.gitId, filtered: await agentApi.filterManifest(workspace.gitId, shareFiles.manifestOf(changed)) };
+    }
+    entry.gitId = workspace.gitId;
+    const filtered = workspace.filtered || {};
+    const accepted = new Set(filtered.included_paths || filtered.includedPaths || []);
+    const cap = Number(filtered.max_file_size_bytes || filtered.maxFileSizeBytes) || require("./folderSync").PER_FILE_CAP_BYTES;
+    // A file the server will not take is handled as it is: tried again only when it changes.
+    for (const file of changed) if (!accepted.has(file.path)) entry.files[file.path] = current.get(file.path);
+    const toSend = changed.filter((file) => accepted.has(file.path)).map((file) => file.path);
+
+    const size = batchFiles();
+    const context = shareFiles.redactionContext(folder);
+    for (let start = 0; start < toSend.length; start += size) {
+      if (!(await stillOn())) return true;
+      // Exclusions re-read before each batch: one made during a long upload counts from the next batch,
+      // for the whole folder and for a folder inside it.
+      const excludedNow = shareExclusions.read();
+      if (excludedNow === null || shareExclusions.covers(excludedNow, shareExclusions.canonical(folder))) return false;
+      const base = shareExclusions.canonical(folder);
+      const batch = toSend
+        .slice(start, start + size)
+        .filter((relative) => !shareExclusions.covers(excludedNow, path.join(base, relative)));
+      if (batch.length === 0) continue;
+      totals.sent += await sendBatch(folder, entry.gitId, batch, cap, context, { redactFiles, agentApi });
+      for (const relative of batch) entry.files[relative] = current.get(relative);
+      saveRecord(record);
+    }
+  }
+
+  for (const relative of removed) {
+    if (entry.gitId) {
+      try {
+        await agentApi.deleteFile(entry.gitId, relative);
+        totals.deleted += 1;
+      } catch (err) {
+        if (!isGone(err)) throw err;
+      }
+    }
+    delete entry.files[relative];
+  }
+  if (removed.length) saveRecord(record);
+  return false;
+}
+
+/** Mask, redact and upload one batch as one sync session. Returns how many files were uploaded. */
+async function sendBatch(folder, gitId, relatives, cap, context, { redactFiles, agentApi }) {
+  const folderSync = require("./folderSync");
+  const maskedDir = fs.mkdtempSync(path.join(os.tmpdir(), copiesPrefix()));
+  try {
+    const masked = await shareFiles.maskCopies(folder, maskedDir, relatives, context, { redactFiles });
+    const sending = masked.files.filter((file) => file.bytes <= cap).map((file) => file.path);
+    if (sending.length === 0) return 0;
+    const sessionId = await agentApi.startSync(gitId);
+    for (const part of folderSync.chunk(sending, folderSync.BATCH_SIZE)) {
+      const files = part.map((relativePath) => ({ relativePath, absolutePath: path.join(maskedDir, relativePath) }));
+      try {
+        await folderSync.uploadBatchWithRetry(gitId, sessionId, files);
+      } catch (err) {
+        if (!isConflict(err)) throw err;
+      }
+    }
+    try {
+      await agentApi.completeSync(gitId, sessionId);
+    } catch (err) {
+      if (!isConflict(err)) throw err;
+    }
+    return sending.length;
+  } finally {
+    fs.rmSync(maskedDir, { recursive: true, force: true });
+  }
+}
+
+module.exports = { shareRound, loadRecord, recordFile, indexedFolders, isConflict, sharingAllowed, copiesPrefix, DEFAULT_BATCH_FILES };

package/src/lib/shareExclusions.js

@@ -0,0 +1,114 @@
+/**
+ * Folders this machine never shares, while "Help improve Niro" stays on.
+ *
+ * Niraj, 2026-11-11, asked whether a user may exclude a folder while sharing stays on: "yes". So
+ * `niro share exclude <folder>` writes the folder here, and both ways code leaves the machine read
+ * it: the background sharing (shareCode.js) never sends an excluded folder, and the typed
+ * `niro audit-push-repo` asks "Send it anyway?" and sends it only on a yes (repoPush.js). `niro plan` lists them.
+ *
+ * A folder covers every folder inside it, so excluding a parent excludes each checkout under it.
+ * A folder inside an indexed folder is excluded too: shareFiles.indexedFiles drops every listed file
+ * under it, so the background sharing never sends it and `niro audit-push-repo` sends it only on a yes (independent
+ * check of 31ffc5f, finding 1: `niro share exclude fixA/src` said it worked and `src/app.py` was sent).
+ * It is matched by path only: another checkout of the same repository somewhere else is not
+ * excluded, and `niro share` says so.
+ *
+ * Kept in `~/.niro/share-excluded.json` (0600), read on every use, so an exclusion made while the
+ * watcher runs counts from its next upload. A file that cannot be read is treated as holding no
+ * exclusions only when it does not exist: one that exists and will not parse makes `isExcluded`
+ * answer yes for every folder, because an unknown answer must not send code (the same rule the
+ * lease follows).
+ */
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+/** A folder as the engine names it: links followed when it exists, so `/tmp/x` and its real path match. */
+function canonical(folder) {
+  const resolved = path.resolve(folder);
+  try {
+    return fs.realpathSync(resolved);
+  } catch {
+    return resolved;
+  }
+}
+
+function file() {
+  // Read at call time, not load time, so a test's scratch HOME is honoured.
+  return path.join(os.homedir(), ".niro", "share-excluded.json");
+}
+
+/** The excluded folders, resolved, or null when the file exists and cannot be read. */
+function read() {
+  let text;
+  try {
+    text = fs.readFileSync(file(), "utf8");
+  } catch (err) {
+    if (err && err.code === "ENOENT") return [];
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(text);
+    if (!parsed || !Array.isArray(parsed.folders)) return null;
+    return parsed.folders.filter((f) => typeof f === "string").map(canonical);
+  } catch {
+    return null;
+  }
+}
+
+/** The excluded folders, for showing. An unreadable file shows as none and is said by the caller. */
+function list() {
+  return read() || [];
+}
+
+function write(folders) {
+  const target = file();
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  const tmp = `${target}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify({ folders }, null, 2) + "\n", { mode: 0o600 });
+  fs.renameSync(tmp, target);
+}
+
+/** Does one of `folders` (resolved, from `read`) hold `resolved`, or is it `resolved` itself? */
+function covers(folders, resolved) {
+  return folders.some((f) => resolved === f || resolved.startsWith(f.endsWith(path.sep) ? f : f + path.sep));
+}
+
+/** Is `folder` excluded, itself or through a folder above it? Unknown (an unreadable file) is yes. */
+function isExcluded(folder) {
+  const folders = read();
+  if (folders === null) return true;
+  return covers(folders, canonical(folder));
+}
+
+/**
+ * The list to change. An unreadable file is not overwritten: the folders it held would start being
+ * shared again without anybody choosing that.
+ */
+function readable() {
+  const folders = read();
+  if (folders === null) {
+    throw new Error(`The list of folders not shared (${file()}) cannot be read. Fix it or delete it, then try again. Until then no folder is shared.`);
+  }
+  return folders;
+}
+
+/** Add a folder. Returns false when it was already excluded by name. */
+function exclude(folder) {
+  const resolved = canonical(folder);
+  const folders = readable();
+  if (folders.includes(resolved)) return false;
+  write([...folders, resolved].sort());
+  return true;
+}
+
+/** Remove a folder. Returns false when it was not excluded by that name. */
+function include(folder) {
+  const resolved = canonical(folder);
+  const folders = readable();
+  if (!folders.includes(resolved)) return false;
+  write(folders.filter((f) => f !== resolved));
+  return true;
+}
+
+module.exports = { list, isExcluded, covers, exclude, include, file, read, canonical };

package/src/lib/shareFiles.js

@@ -0,0 +1,129 @@
+/**
+ * Which files of a folder may be shared, and how each one is redacted before it leaves.
+ *
+ * Shared by the two ways a folder's code leaves this machine: the background sharing in the watcher
+ * (shareCode.js) and the typed `niro audit-push-repo` (repoPush.js). One place, so the two can never
+ * send different files or redact them differently.
+ *
+ * **Which files.** Niraj, 2026-11-11: "we send what is indexed with niro, okay? so the files and
+ * config files considered by niro when indexing". The engine says which they are
+ * (`niro-local indexed-files`, niro-local `share_files.py`): the source files it parses and the
+ * config, build and text files it reads, under its own exclusions (`.gitignore`, `node_modules` and
+ * other build output, a real `.env`, keys and key stores, tool token files). niro-cli does not walk
+ * the folder by rules of its own, so the two cannot drift.
+ *
+ * **How each file is redacted.** Exactly what `niro audit-push-repo` and the audit do, nothing new:
+ * the engine writes masked copies with llm-gateway's rules (`niro-local redact-files`, constraint
+ * 01M6RXWT41PTJ9QNFQBQ80HRVB), then redact.js removes author and company names from each copy, as
+ * it does for the audit's flagged methods. A copy whose line count that would change is not sent.
+ * Everything is read from the copies in a private temporary folder, never from the repository.
+ */
+const fs = require("fs");
+const path = require("path");
+
+const { redactSource, linesOf } = require("./redact");
+
+/**
+ * The engine's answer for one folder, less the files under a folder the user excluded:
+ * `{ folder, indexed, files: [{ path, bytes }], held: [path], heldFiles: [{ path, bytes }] }`.
+ *
+ * `held` names the files left out because an excluded folder holds them. `niro share exclude` may
+ * name a folder inside an indexed one (`fixA/src`), and only a check of each file's own path keeps
+ * that folder's code on the machine (independent check of 31ffc5f, finding 1). The list of
+ * exclusions is read once per folder. One that cannot be read holds back every file: unknown is no.
+ *
+ * `heldFiles` is the same files as `held`, with their sizes. Only the typed `niro audit-push-repo`
+ * reads it, and only after the person typing it answered yes to "Send it anyway?" (repoPush.js,
+ * Niraj, 2026-11-11). The background sharing reads `files` and `held` and never sends a held file.
+ */
+async function indexedFiles(folder, { run = (...a) => require("./localEngine").run(...a) } = {}) {
+  const parsed = JSON.parse(await run(["indexed-files", "--path", folder]));
+  if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.files)) {
+    throw new Error("the local engine did not list the folder's files");
+  }
+  const listed = parsed.files.filter(
+    (f) => f && typeof f.path === "string" && f.path && Number.isFinite(Number(f.bytes))
+  );
+  const shareExclusions = require("./shareExclusions");
+  const excluded = shareExclusions.read();
+  const base = shareExclusions.canonical(typeof parsed.folder === "string" && parsed.folder ? parsed.folder : folder);
+  const files = [];
+  const heldFiles = [];
+  for (const file of listed) {
+    if (excluded === null || shareExclusions.covers(excluded, path.join(base, file.path))) heldFiles.push(file);
+    else files.push(file);
+  }
+  const held = heldFiles.map((file) => file.path);
+  return { folder: parsed.folder, indexed: parsed.indexed === true, files, held, heldFiles };
+}
+
+/** The upload manifest the server's file filter reads, for these files. */
+function manifestOf(files) {
+  return files.map((file) => ({ path: file.path, size_bytes: Number(file.bytes), mime_type: "text/plain" }));
+}
+
+/**
+ * Ask the engine for masked copies of `relatives` (paths under `source`) in the empty folder
+ * `target`. Resolves the engine's report: `{ redacted, files: [{ path, bytes, masks }], masks,
+ * not_text, missing, refused }`. Rejects when the engine cannot do it.
+ */
+async function engineRedact(source, target, relatives) {
+  const out = await require("./localEngine").run(
+    ["redact-files", "--from", source, "--to", target],
+    relatives.join("\n") + "\n"
+  );
+  return JSON.parse(out);
+}
+
+/** What redact.js needs to know: the signed-in email and the folder's git remote owner. */
+function redactionContext(folder) {
+  let email = null;
+  try {
+    email = (require("./credentials").load() || {}).email || null;
+  } catch {
+    // No saved sign-in: the copyright holders are still removed.
+  }
+  let remoteOwner = null;
+  try {
+    remoteOwner = require("./auditUpload").remoteOwner(require("./git").inspect(folder).originUrl);
+  } catch {
+    // No remote: the same.
+  }
+  return { email, remoteOwner };
+}
+
+/**
+ * Masked, name-free copies of `relatives` in `target`, an empty private folder.
+ *
+ * Returns the engine's report with `files` narrowed to the copies that are fit to send, each with
+ * its size after both passes, plus `linesMoved`: the copies dropped because removing names would
+ * have changed their line count. Throws when the engine cannot mask, so nothing unmasked is sent.
+ */
+async function maskCopies(source, target, relatives, ctx, { redactFiles = engineRedact } = {}) {
+  const masked = await redactFiles(source, target, relatives);
+  if (!masked || !masked.redacted || !Array.isArray(masked.files)) {
+    throw new Error("the local engine did not say it masked the files");
+  }
+  const files = [];
+  let linesMoved = 0;
+  for (const file of masked.files) {
+    const copy = path.join(target, file.path);
+    if (!path.resolve(copy).startsWith(path.resolve(target) + path.sep)) continue;
+    const text = fs.readFileSync(copy, "utf8");
+    const cleaned = redactSource(text, ctx);
+    if (cleaned === text) {
+      files.push(file);
+      continue;
+    }
+    if (linesOf(cleaned).length !== linesOf(text).length) {
+      fs.rmSync(copy, { force: true });
+      linesMoved += 1;
+      continue;
+    }
+    fs.writeFileSync(copy, cleaned);
+    files.push({ ...file, bytes: Buffer.byteLength(cleaned, "utf8") });
+  }
+  return { ...masked, files, linesMoved };
+}
+
+module.exports = { indexedFiles, manifestOf, engineRedact, redactionContext, maskCopies };

package/src/lib/spinner.js

@@ -31,7 +31,7 @@ const ERASE_LINE = "\r\x1b[2K";
  * of an indented step, which is where they were.
  */
 function pad() {
-  return " ".repeat(require("./nestedOutput").currentIndent());
+  return require("./nestedOutput").currentPad();
 }
 const ANSI_RE = /\x1b\[[0-9;]*m/g;
 
@@ -100,11 +100,15 @@ function start(label, opts = {}) {
     };
   }
 
+  // On the setup rail the frame takes the rail's own column, the way a step marker does,
+  // instead of sitting after it.
+  const onRail = () => pad().startsWith("│");
   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 + pad() + fit(line, (stream.columns || 80) - 1 - pad().length));
+    const frame = color.cyan(FRAMES[i = (i + 1) % FRAMES.length]);
+    const text = `${onRail() ? label.trim() : label} ${color.dim("(" + elapsed() + "s)")}`;
+    const line = onRail() ? `${frame}  ${text}` : `${pad()}${frame} ${text}`;
+    stream.write(ERASE_LINE + fit(line, (stream.columns || 80) - 1));
   };
 
   render();
@@ -122,7 +126,7 @@ function start(label, opts = {}) {
       if (stopped) return;
       stopped = true;
       stream.write(ERASE_LINE);
-      if (finalLine) stream.write(pad() + finalLine + "\n");
+      if (finalLine) stream.write((onRail() ? `│  ${finalLine.trim()}` : pad() + finalLine) + "\n");
     },
   };
 }