@niroai/niro 0.4.0 → 0.6.0

package/src/lib/onboardTarget.js

@@ -0,0 +1,258 @@
+/**
+ * Is this folder a sane thing to onboard? The check that runs BEFORE
+ * `niro init` / `niro add repo` register anything on the server or upload a byte.
+ *
+ * Two independent rules:
+ *
+ *   1. PROTECTED ROOT — never bypassable. $HOME, the filesystem root, any ancestor
+ *      of $HOME (/home, /Users) and the well-known system dirs are refused outright.
+ *      Onboarding one of these is never intended, and the damage is not the kind
+ *      --force should be able to cause by accident: source from every project on the
+ *      machine uploaded as one blob, a .niro-project pin dropped at $HOME, and a
+ *      watch daemon streaming the whole home tree. Worse, .gitignore is only honoured
+ *      when the onboarded folder is itself a git work tree, so onboarding $HOME
+ *      silently uploads files that each nested repo deliberately ignores.
+ *
+ *   2. PROJECT INDICATOR — bypassable with --force. The folder must LOOK like a
+ *      project: a build descriptor at the folder itself, or in a directory just below
+ *      it. This mirrors ai-orchestrator
+ *      ProjectStructureResolverService.detectProjects(), which marks any directory
+ *      holding a descriptor from the ConfigFileParser SUPPORTED_FILES union as a
+ *      project root. folderSync already carries that union as STRUCTURAL_FILENAMES /
+ *      STRUCTURAL_EXTENSIONS (documented there as byte-identical to the server), so
+ *      this REUSES those sets. There is deliberately no second list to drift.
+ *
+ * Two deliberate differences from the server:
+ *
+ *   - Depth-bounded (INDICATOR_MAX_DEPTH) instead of a full-tree walk. The question
+ *     here is "is THIS folder a project", not "which projects live somewhere inside
+ *     it". A descriptor buried deep is precisely the accident being caught: $HOME
+ *     contains thousands of them.
+ *   - No parser veto. The server asks the owning parser isProjectIndicator(file) to
+ *     reject a false match (a Python module literally named setup.py). The CLI cannot
+ *     parse, so a name match is accepted. That errs toward ALLOWING onboarding, which
+ *     is the safe direction for a guard: the worst case is the behaviour we had before.
+ */
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const color = require("./color");
+const folderSync = require("./folderSync");
+
+// How far below the target we look for a build descriptor. 0 = the folder itself.
+// 2 covers a monorepo root whose deployables sit under a grouping dir
+// (services/foo/pom.xml, packages/foo/package.json) and still refuses a folder whose
+// only descriptors are buried deeper than any real project root would be.
+const INDICATOR_MAX_DEPTH = 2;
+
+// Hard bound on the walk so a pathological tree cannot stall the command.
+const MAX_DIRS_SCANNED = 2000;
+
+// Refused outright, by exact path match. Ancestors of $HOME (/home, /Users) are
+// caught by the ancestor rule below as well; listed here for the case where $HOME
+// lives somewhere unusual.
+const SYSTEM_DIRS = new Set([
+  "/", "/bin", "/boot", "/dev", "/etc", "/home", "/lib", "/lib64", "/media",
+  "/mnt", "/opt", "/proc", "/root", "/run", "/sbin", "/srv", "/sys", "/tmp",
+  "/usr", "/var", "/Applications", "/Library", "/System", "/Users", "/Volumes",
+]);
+
+// Windows paths are case-insensitive; POSIX paths are not.
+function samePath(a, b) {
+  if (process.platform === "win32") return a.toLowerCase() === b.toLowerCase();
+  return a === b;
+}
+
+// Resolve symlinks before comparing, so a symlinked route to a protected path (macOS
+// /tmp -> /private/tmp, an $HOME reached through /mnt/home/<user>) cannot walk past the
+// refusal on a string mismatch. Falls back to the lexical path when the target does not
+// exist or is unreadable — the comparison is then no worse than before.
+function realPath(p) {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    return p;
+  }
+}
+
+/**
+ * Why this folder must never be onboarded, or null when it is fine.
+ * Returns a human phrase that slots into "Refusing to onboard <phrase>".
+ */
+function protectedRootReason(dir) {
+  const target = realPath(path.resolve(dir));
+
+  if (samePath(target, path.parse(target).root)) return "the filesystem root";
+
+  let home = null;
+  try {
+    home = os.homedir() ? realPath(path.resolve(os.homedir())) : null;
+  } catch {
+    home = null; // no home resolvable -> only the root/system rules apply
+  }
+  if (home) {
+    if (samePath(target, home)) return "your home folder";
+    // home lives INSIDE target => target is an ancestor of home (/home, /Users, ...).
+    const rel = path.relative(target, home);
+    if (rel && !rel.startsWith("..") && !path.isAbsolute(rel)) {
+      return "a parent of your home folder";
+    }
+  }
+
+  if (SYSTEM_DIRS.has(target)) return "a system folder";
+  // Also refuse the lexical path when it differs from the resolved one, so a symlink
+  // POINTING AT an ordinary folder cannot be used to name a protected path either way.
+  if (SYSTEM_DIRS.has(path.resolve(dir))) return "a system folder";
+  return null;
+}
+
+/**
+ * The indicator kind this filename represents, or null. Name match wins over
+ * extension match, mirroring the server's parserRegistry-then-extensionRegistry
+ * lookup order. Returned as a display label ("pom.xml", "*.csproj").
+ */
+function indicatorName(fileName) {
+  const lower = path.basename(fileName).toLowerCase();
+  if (folderSync.STRUCTURAL_FILENAMES.has(lower)) return lower;
+  const ext = path.extname(lower);
+  if (ext && folderSync.STRUCTURAL_EXTENSIONS.has(ext)) return `*${ext}`;
+  return null;
+}
+
+/**
+ * Look for project roots at `targetDir` and just below it.
+ *
+ * Stops descending as soon as a directory IS a project root: once a descriptor is
+ * found there is nothing further to prove, and it keeps the common case (a normal
+ * repo with a descriptor at its top) down to a single readdir.
+ *
+ * Returns { roots, indicators: Map(label -> count), truncated }.
+ */
+function findProjectIndicators(targetDir, opts = {}) {
+  const maxDepth = Number.isInteger(opts.maxDepth) ? opts.maxDepth : INDICATOR_MAX_DEPTH;
+  // Injectable so the breadth-first guarantee can be tested without a 2000-directory fixture.
+  const maxDirs = Number.isInteger(opts.maxDirs) ? opts.maxDirs : MAX_DIRS_SCANNED;
+  const indicators = new Map();
+  let roots = 0;
+  let dirsScanned = 0;
+  let truncated = false;
+
+  // Breadth-first, one depth level at a time. Depth-first would let a single wide or
+  // deep subtree spend the whole MAX_DIRS_SCANNED budget before the walk ever looked
+  // at the target's own siblings, so a real project root could go unseen while junk
+  // was scanned. Breadth-first means level 0 is always examined, then all of level 1,
+  // and only the deepest level can ever be cut short.
+  let frontier = [path.resolve(targetDir)];
+  for (let depth = 0; depth <= maxDepth && frontier.length > 0; depth++) {
+    const next = [];
+    for (const dir of frontier) {
+      if (dirsScanned >= maxDirs) { truncated = true; break; }
+      dirsScanned++;
+
+      let entries;
+      try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+      } catch {
+        continue; // unreadable (permissions, vanished) -> nothing to prove here
+      }
+
+      let isRoot = false;
+      for (const entry of entries) {
+        if (!entry.isFile()) continue;
+        const label = indicatorName(entry.name);
+        if (!label) continue;
+        isRoot = true;
+        indicators.set(label, (indicators.get(label) || 0) + 1);
+      }
+      // A project root proves what we came to prove; there is no reason to look inside it.
+      if (isRoot) { roots++; continue; }
+      if (depth >= maxDepth) continue;
+
+      // Sorted so the walk is deterministic: readdir order is filesystem-dependent, and
+      // which directories fall inside the budget must not vary between machines.
+      const children = entries
+        .filter((e) => e.isDirectory() && !e.name.startsWith(".") && !folderSync.IGNORED_DIRS.has(e.name))
+        .map((e) => e.name)
+        .sort();
+      for (const name of children) next.push(path.join(dir, name));
+    }
+    if (truncated) break;
+    frontier = next;
+  }
+
+  return { roots, indicators, truncated };
+}
+
+// "pom.xml x10, package.json x1" — the three commonest kinds, then a tail count.
+function describeIndicators(indicators) {
+  const sorted = [...indicators.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+  const shown = sorted.slice(0, 3).map(([label, n]) => (n > 1 ? `${label} x${n}` : label));
+  const rest = sorted.length - shown.length;
+  return rest > 0 ? `${shown.join(", ")}, and ${rest} more` : shown.join(", ");
+}
+
+/**
+ * The gate itself. Prints the refusal and returns false when this folder must not be
+ * onboarded; returns true when the caller may proceed.
+ *
+ * opts.force bypasses the INDICATOR rule only. It deliberately does not bypass a
+ * protected root: there is no legitimate reason to upload $HOME, and a scripted
+ * --force must not be able to do it by accident.
+ *
+ * opts.alreadyRegistered likewise bypasses the INDICATOR rule only, for a folder this
+ * backend already holds a repo for. Callers pass it from watchState so that adding the
+ * gate never breaks a sync that was already working.
+ */
+function ensureOnboardable(targetDir, opts = {}) {
+  const resolved = path.resolve(targetDir);
+
+  const reason = protectedRootReason(resolved);
+  if (reason) {
+    console.error(color.red(`\n  ✗ Refusing to onboard ${reason} (${resolved}).`));
+    console.error("    That would upload source from every project underneath it, pin this folder");
+    console.error("    with a .niro-project file, and watch the whole tree for changes.");
+    console.error(`    Change into the project folder you meant, then run the command there.`);
+    return false;
+  }
+
+  const { roots, indicators, truncated } = findProjectIndicators(resolved, opts);
+  if (indicators.size === 0) {
+    // A folder this backend ALREADY has a repo for is exempt from the descriptor rule.
+    // That rule gates NEW onboarding; it is not a reason to start failing a re-sync of a
+    // folder onboarded by an earlier CLI, which would strand the user with no way back in.
+    // The protected-root rule above still applied, and still refuses.
+    if (opts.alreadyRegistered) {
+      console.log(color.dim(
+        `  No build file in ${resolved}, but it is already registered here — continuing.`
+      ));
+      return true;
+    }
+    if (opts.force) {
+      console.log(color.yellow(
+        `\n  ⚠ No project found in ${resolved}, but --force was passed. Onboarding it anyway.`
+      ));
+      return true;
+    }
+    console.error(color.red(`\n  ✗ No project found in ${resolved}.`));
+    console.error("    Niro looks for a build file (package.json, pom.xml, go.mod, ...) in this");
+    console.error(`    folder or just below it${truncated ? " (the scan stopped early — the tree is very large)" : ""}. None found.`);
+    console.error("    Pass --force if you really mean to upload this folder.");
+    return false;
+  }
+
+  console.log(
+    `  ${color.green("✓")} Found ${roots} project${roots === 1 ? "" : "s"} ` +
+    `(${describeIndicators(indicators)}).`
+  );
+  return true;
+}
+
+module.exports = {
+  ensureOnboardable,
+  protectedRootReason,
+  findProjectIndicators,
+  indicatorName,
+  describeIndicators,
+  INDICATOR_MAX_DEPTH,
+  MAX_DIRS_SCANNED,
+};

package/src/lib/receiptStore.js

@@ -0,0 +1,85 @@
+/**
+ * The per-developer off switch for the end-of-task receipt line.
+ *
+ * The line itself is composed by the server and travels back inside the mark_task_complete tool
+ * result, which the model prints wrapped in backticks. Nothing is stored locally to display it.
+ *
+ * This file used to be a letterbox: the bridge wrote each receipt to disk and a Claude Code Stop
+ * hook printed it. That worked, but Claude Code prefixes anything a Stop hook prints with
+ * "Stop says: …", which read as a system warning rather than a note from Niro. Printing from the
+ * model reads better and works in all twelve clients instead of one, so the hook, the letterbox and
+ * the terminal colouring all went with it.
+ *
+ * What remains is the switch. It stays local because it is a personal preference: the server serves
+ * a whole account and cannot know that one developer wants the line quiet. The bridge reads it and
+ * strips the receipt from the tool result, so the model never sees it and cannot print it.
+ */
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+/** ~/.niro, resolved the same way as the rest of the CLI (Windows has no HOME). */
+function niroHome() {
+  const home = process.env.HOME || process.env.USERPROFILE || os.homedir() || "";
+  return path.join(home, ".niro");
+}
+
+/**
+ * Presence of this file switches the line off.
+ *
+ * A file rather than a key inside projects.json so that toggling it can never corrupt, or be
+ * corrupted by, the sync state the watch daemon depends on.
+ */
+function disabledFlagPath() {
+  return path.join(niroHome(), "receipts-off");
+}
+
+function isDisabled() {
+  try {
+    return fs.existsSync(disabledFlagPath());
+  } catch {
+    // Cannot read the home directory: treat as ON. Failing to a silent state would make the
+    // feature look broken with nothing to explain why.
+    return false;
+  }
+}
+
+/** Turn the line on or off. Returns true when the state actually changed. */
+function setDisabled(disabled) {
+  const flag = disabledFlagPath();
+  try {
+    if (disabled) {
+      if (fs.existsSync(flag)) return false;
+      fs.mkdirSync(path.dirname(flag), { recursive: true, mode: 0o700 });
+      fs.writeFileSync(flag, "", { mode: 0o600 });
+      return true;
+    }
+    if (!fs.existsSync(flag)) return false;
+    fs.unlinkSync(flag);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Remove the off switch and any leftovers from the retired letterbox.
+ *
+ * Used by `niro mcp uninstall`, and worth keeping past the letterbox itself: anyone who ran a
+ * version that wrote receipts to disk still has that directory, and an uninstall that leaves files
+ * behind is not an uninstall.
+ */
+function purge() {
+  try {
+    fs.rmSync(path.join(niroHome(), "receipts"), { recursive: true, force: true });
+  } catch {
+    /* best effort */
+  }
+  try {
+    fs.rmSync(disabledFlagPath(), { force: true });
+  } catch {
+    /* best effort */
+  }
+}
+
+module.exports = { disabledFlagPath, isDisabled, setDisabled, purge };

package/src/lib/tempProject.js

@@ -0,0 +1,37 @@
+/**
+ * Reading the state of a temporary project.
+ *
+ * A developer gets ONE temporary project per project, and `niro new-temp-project` MOVES it rather than
+ * adding a second. So "which folder does Niro currently reflect?" has exactly one answer, and it lives
+ * on the server: the branch recorded against the temporary project's repo.
+ *
+ * That matters because a folder cannot tell locally whether it still holds the slot. Every folder taken
+ * over for one project shares the SAME repo id, so the server cannot tell them apart either — if two
+ * folders upload, their branches blend into one copy and every answer drawn from it is a mixture. The
+ * only way to know is to ask which branch the copy is on and compare it with your own.
+ */
+const api = require("./api");
+
+/**
+ * The branch a temporary project is currently bound to, or null if it cannot be determined.
+ *
+ * Returns null rather than throwing on a server or network problem: this is used to decide whether to
+ * hold back an upload, and "I could not reach the server" must never be read as "you have lost the
+ * slot" — that would stop a perfectly healthy folder syncing every time the network hiccuped.
+ */
+async function currentBranch(tempProjectId, gitId, opts = {}) {
+  if (!tempProjectId) return null;
+  let project;
+  try {
+    project = await api.get(`/api/projects/${encodeURIComponent(tempProjectId)}`, opts);
+  } catch {
+    return null;
+  }
+  const repos = project.git_details || project.gitDetails || [];
+  // Match the repo by id when we can. Falling back to the first is safe for the single-repo case and
+  // still right for multi-repo: every repo in one temporary project is taken over onto one branch.
+  const match = repos.find((r) => r.id === gitId) || repos[0];
+  return match && match.branch ? match.branch : null;
+}
+
+module.exports = { currentBranch };

package/src/lib/watchState.js

@@ -127,6 +127,34 @@ function update(folderPath, patch) {
   save(state);
 }
 
+/**
+ * Merge per-path hash changes into an entry instead of replacing the whole map.
+ *
+ * `update({ fileHashes })` replaces the map wholesale, so whichever writer saves last wins and every
+ * entry the other writer added in the meantime is silently gone. The delta sync computes a map from
+ * its own walk and writes it at the end, which can take minutes on a large upload; any live per-file
+ * event that landed during that window is erased. Losing a baseline entry is not cosmetic — the file
+ * stops being tracked, so it is never re-sent and the divergence is permanent. That is the difference
+ * between the 27 July incident, which healed itself in 35 minutes, and 31 July, which never did.
+ *
+ * Removals must be explicit rather than implied by absence, so nothing disappears by accident.
+ *
+ * load/save are synchronous and save renames atomically, so this is safe against other writers in
+ * THIS process. The watch daemon is a separate process, so a cross-process interleave is still
+ * possible; this shrinks the window from minutes to microseconds rather than closing it entirely.
+ */
+function mergeFileHashes(folderPath, { set = {}, remove = [], patch = {} } = {}) {
+  const state = load();
+  const key = path.resolve(folderPath);
+  if (!state[key]) return;
+  const merged = { ...(state[key].fileHashes || {}) };
+  for (const rp of remove) delete merged[rp];
+  // Applied after the removals, so a file deleted and re-created within one run keeps its new hash.
+  Object.assign(merged, set);
+  state[key] = { ...state[key], ...patch, fileHashes: merged };
+  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,
@@ -214,4 +242,5 @@ function hashFile(filePath) {
   }
 }
 
-module.exports = { get, peek, set, update, remove, allLocal, findOverlapping, matchesBackend, hashFile, FILE };
+module.exports = { get, peek, set, update, remove, allLocal, findOverlapping, matchesBackend, hashFile,
+  mergeFileHashes, FILE };

package/src/mcp/server.js

@@ -42,6 +42,7 @@ const readline = require("readline");
 const { execSync } = require("child_process");
 const niroProjectFile = require("../lib/niroProjectFile");
 const { redactRemoteCreds } = require("../lib/git");
+const receiptStore = require("../lib/receiptStore");
 
 /** Absolute path to ~/.niro/projects.json. Uses os.homedir() so it also resolves on Windows, where HOME is
  *  normally unset — `process.env.HOME || ""` there produced a relative path that never existed, silently
@@ -507,6 +508,7 @@ function connectSse() {
             // Swallow the response to an internally-replayed initialize (sentinel id) so the host
             // never sees a duplicate initialize result after a transparent reconnect.
             let swallowed = false;
+            let rewritten = null;
             try {
               const msg = JSON.parse(data);
               // ADR-018 handshake: only an initialize result carries capabilities. When the server
@@ -528,9 +530,12 @@ function connectSse() {
               } else {
                 // Cancel the client-side deadline when a delivered result matches an in-flight request.
                 pending.onIncoming(msg);
+                rewritten = captureReceipt(msg);
               }
             } catch (_) { /* not correlatable JSON — forward unchanged */ }
-            if (!swallowed) process.stdout.write(data + "\n");
+            // captureReceipt returns a rewritten payload when it stripped the receipt field so the
+            // Stop hook can print it instead; otherwise the original bytes go through untouched.
+            if (!swallowed) process.stdout.write((rewritten || data) + "\n");
           }
         }
       });
@@ -662,6 +667,56 @@ function sendMessage(message) {
   });
 }
 
+/**
+ * Stash the end-of-task receipt line, if this incoming message carries one.
+ *
+ * The server composes the line and returns it inside the mark_task_complete tool result. The model
+ * is asked to print it, but a model can forget an instruction; the Claude Code Stop hook prints it
+ * whether or not the model cooperates, and this is where it gets the text. See
+ * `docs/usecases/task-receipt.md`.
+ *
+ * Deliberately does NOT filter by tool name: the bridge does not track which request id belonged to
+ * which tool, and a `receipt` string in a result is unambiguous enough on its own. Any future tool
+ * that wants to say something at end of task gets this for free.
+ *
+ * Silent on every failure. This sits on the path that hands results back to the developer's
+ * assistant, so a malformed message, an unwritable home directory, or an unexpected shape must cost
+ * the receipt and nothing else.
+ */
+function captureReceipt(msg) {
+  // Nothing to do unless the developer has switched the line off. The receipt is displayed by the
+  // model printing it from the tool result — there is no local copy and no hook any more.
+  if (!receiptStore.isDisabled()) return null;
+  try {
+    const content = msg && msg.result && msg.result.content;
+    if (!Array.isArray(content)) return null;
+    for (const item of content) {
+      if (!item || typeof item.text !== "string") continue;
+      // Cheap reject before parsing: tool results are frequently large, and almost none of them
+      // are the one message per task that carries a receipt.
+      if (!item.text.includes('"receipt"')) continue;
+      let parsed;
+      try {
+        parsed = JSON.parse(item.text);
+      } catch (_) {
+        continue; // not JSON — some other tool's prose that happens to contain the word
+      }
+      if (parsed && typeof parsed.receipt === "string") {
+        // Strip it here rather than asking the server not to send it. The switch is per developer
+        // and lives on this machine; the server serves a whole account and cannot know that one
+        // person wants it quiet.
+        delete parsed.receipt;
+        item.text = JSON.stringify(parsed);
+        return JSON.stringify(msg);
+      }
+    }
+  } catch (_) {
+    /* never let this disturb the message path */
+  }
+  return null;
+}
+
+
 /**
  * Enrich an outgoing tools/call: send the folder's `.niro-project` pin as `_niroPin` (ADR-018 — a
  * SOURCE binding the server's routing ladder consumes, NOT an explicit project choice), and