@niroai/niro 0.10.1 → 0.12.0

package/CHANGELOG.md

@@ -2,6 +2,170 @@
 
 Notable changes to `@niroai/niro`. Dates are release dates.
 
+## Unreleased
+
+## 0.12.0 — 2026-09-06
+
+### Before an edit to indexed source, Claude is asked to map the method and to verify those flows afterwards
+
+Every instruction file niro writes tells the assistant to map who depends on a method before changing
+it. In practice the assistant finds the file, reads it, and edits; the rule is read early in a session
+and forgotten by the middle of it. And the map was always meant for afterwards: the point is to go back
+to the callers and flows once the edit is made and check they still hold.
+
+Claude Code now gets a third niro hook, on Edit and Write. Before an edit to source in an indexed repo
+it puts a short reminder in front of the assistant: decide whether the change can alter behaviour (a log
+line or a comment cannot, say so and go ahead); if it can, map who depends on the method now with
+get_blast_radius or get_impact_analysis and keep that list as the checklist for after the edit; and do
+not re-query the graph to verify, because it updates only after the edit is synced and rebuilt. If an
+impact call already named the file this session, the reminder instead says to go back to that list
+after the edit. Each reminder appears once per file per session. It is advisory: it never approves or
+refuses an edit. The evidence comes from the bridge, which writes one line per answered impact call
+under `~/.niro/impact/`. New files, tests, config and docs are never mentioned. Off switch:
+`touch ~/.niro/impact-gate-off`. `niro mcp uninstall` removes the hook and the evidence files.
+
+The same three points were added to every instruction surface niro writes: the rule sentence in each
+client's always-on file, the niro skill, the Cursor, Cline and Kiro rules, and the PostCompact and
+prompt hooks. The clients without hooks read them there. Details: `docs/usecases/impact-gate.md`.
+
+### `niro mcp install` now refreshes Claude Code hooks on a machine where niro was already set up
+
+Re-running the install on a machine with an existing registration failed at the first step, because
+`claude mcp add` refuses a name that already exists, and the installer read that refusal as "Claude
+Code is not installed" and stopped before writing any hook or the CLAUDE.md section. So the step the
+out-of-date notice asks for did nothing for anyone who had installed once. The installer now reads the
+existing registration first: same URL, it keeps it; a different `--url`, it replaces it; none, it adds
+it. Hooks and sections are written in every case.
+
+### CommonJS and ES-module files (.cjs, .mjs, .cts, .mts) are now uploaded for indexing
+
+When niro decided which files to upload for indexing, it skipped `.cjs`, `.mjs`, `.cts` and `.mts`,
+so a `build.cjs` or an `index.mjs` was never indexed and never appeared in the graph. Those four
+extensions are now included, matching the server's own file filter.
+
+### The niro rules now name get_exception_flow
+
+The explore-first rule niro writes into each client now mentions `get_exception_flow`, the tool that
+reports which exceptions can escape a method (and who must handle one). It is served by the niro
+backend; this only makes the assistants aware it exists.
+
+## 0.11.0 — 2026-09-03
+
+### The watcher stops pausing and resuming your uploads over and over
+
+The background watcher holds back uploads from a folder whose branch disagrees with the branch its
+private copy is labelled with, so two branches cannot be written into one copy. One developer's log
+carried 306 pauses against 286 resumes. Those counts being nearly equal is the whole story: it was
+toggling, not failing 306 times.
+
+Once a minute the watcher asks which branch the copy is on. A request that failed returned nothing,
+which was read as "everything is fine again": it printed "resuming uploads" and cleared the pause, so
+the next check paused and warned all over again. It also let a folder that genuinely should not be
+uploading start writing again on any slow request. Now a question the server could not answer changes
+nothing at all, in either direction. The same six alternating checks went from 3 warnings and 3 resumes
+down to 1 and 0.
+
+The message was wrong too. When it paused it looked for another folder on the same *project* and blamed
+it. A project can hold several repositories and each folder can have its own, so it regularly named a
+folder that was writing nowhere near yours and told you to discard it. It now matches on the repository
+actually being written to, so it either names the folder that really shares your copy or tells you
+plainly that you switched branch in that folder yourself.
+
+**The pause itself is unchanged, deliberately.** While a folder's branch and its copy's label disagree,
+your assistant's questions are not sent to that copy anyway, so uploading into it would only fill it
+with the wrong branch's files. Run `niro new-temp-project` in that folder to put it back in step.
+
+### Servlet apps declare their endpoints in a file that was never sent
+
+A Java web app written before Spring Boot lists its whole HTTP surface in `WEB-INF/web.xml` rather than
+in annotations. That file was missing from the set the CLI offers, so such a project indexed as a
+servlet application with no endpoints at all. Measured on one repository: 11 real endpoints, 0 detected,
+against an otherwise complete and healthy index.
+
+
+### Stale pointers clean themselves up
+
+Delete a project, or let an unused private copy expire, and your machine is never told. The folder
+carries on naming something that is gone. That is what makes `niro new-temp-project` in another
+worktree say the slot is taken, naming a copy that no longer exists.
+
+That command never shipped: it went in under this same Unreleased section and has been renamed since,
+so `niro doctor sync-registry` is its first public name. It also only helped if you remembered to run
+it. Now the background watcher runs it every six hours by itself, and it covers two more cases:
+
+- **Ordinary registrations**, not just private copies. A folder registered against a deleted project
+  used to sit there for ever: the daemon retried it on every start and nothing could clear it. One
+  developer asked whether they should edit `~/.niro/projects.json` by hand. They were right that there
+  was no supported way.
+- **`.niro-project` files** naming something the server does not recognise. Nothing has ever surfaced
+  these, and they are not inert: that file is read before your git remote, so a stale one keeps
+  answering. They are REPORTED, never deleted — the file can hold a project's name rather than its id,
+  and a renamed project is indistinguishable from a deleted one from the client, so the right repair
+  (update it, or remove it) is yours to choose.
+
+**What it refuses to do matters more than what it does.** A deleted project is not enough to
+unregister a folder, because a project can be deleted while its repos are moved to another one and
+that folder is still syncing fine, so the repo is checked too. On the machine this was built on that
+took the count from 18 folders to 1. And a `.niro-project` may hold an *alias* rather than an id, which
+the direct lookup reports as "not found" for a project that is perfectly alive; the account's project
+list is now the authority. Both of those were caught by dry runs against real data after the unit tests
+were green.
+
+The watcher remembers when it last swept, so restarting it does not re-run the job, and a `niro watch`
+left in a terminal cannot sweep at the same moment as the background one. It stays silent when there
+was nothing to do.
+
+### When you run out of private copies, it says where they are
+
+The server already tells you which branches are holding your copies. It cannot tell you where those
+branches are checked out, because that is a fact about your machine. The CLI now adds the folder next
+to each branch, so you can go straight to one and discard it.
+
+### Multi-line error messages are no longer cut off
+
+Errors printed only their first line, so any message built over several lines lost the rest. Two were
+affected: "Multiple projects match this repo — pass --project:" showed no projects, and the
+working-copy-limit refusal showed no folders. The text was always correct and simply never reached the
+screen. Found by running the real CLI against a real backend until it refused; no unit test could have
+caught it, because both features assert on the message and the message was right.
+
+
+### `niro doctor sync-registry` tidies up copies the server deleted for you
+
+A temporary project can go without this machine ever being told: somebody deletes it in the web
+app, or the sweeper reaps it after two weeks. The folder keeps a registration pointing at an id
+that resolves to nothing. That is not harmless, because it is exactly what makes
+`niro new-temp-project` in a second worktree refuse with "already held by another folder".
+
+`niro discard-temp-project` already repaired one folder in that state. What nothing did was find
+them. On the machine this was built on, 13 of 14 registered copies had gone and every one of the
+14 folders was still pointing at a dead id.
+
+```bash
+niro doctor sync-registry            # check and repair
+niro doctor sync-registry --dry-run  # list, change nothing
+```
+
+It asks the server once per copy and moves the folders whose copy has gone back onto their
+original project. Three things it will not do. It never treats an unreachable server as an
+answer: only a definitive "Project not found" counts, so a 500, a timeout, or a project you are
+simply not allowed to see leaves every entry exactly as it was. It never unregisters a folder,
+because the watch daemon still needs somewhere to sync it. And it never guesses: a copy that no
+folder recorded a source project for is reported and left alone.
+
+`--json` for scripts, `--dry-run` to look first, `-y` to skip the prompt. At a terminal, `--json`
+asks for one of the last two rather than writing without a prompt it cannot show.
+
+Two guards came out of review and apply to `niro discard-temp-project` as well, because both commands
+now share one repair routine. A folder re-registered by another process while the command runs is
+left alone and reported, instead of being overwritten by a stale snapshot. And within a copy that
+covers several folders, the one holding the record of the original project is always written last, so
+a run interrupted half way through can still be finished by running it again.
+
+Folders that had no local registration before the copy was made are now listed separately from the
+ones that keep syncing. They go back to not having one, which is where they started, but calling that
+"repaired" and stopping there implied the daemon was still watching them.
+
 ## 0.10.0 — 2026-08-28
 
 One command to get started, and a way to check what Niro is worth.

package/README.md

@@ -45,7 +45,9 @@ Then restart your assistant and ask it something:
 ```bash
 niro status
 ```
-Is my index up to date?
+Is my index up to date? It answers about the project this folder is synced to **on the branch you
+are on**, so once you have run `niro new-temp-project` it reports that copy rather than the shared
+project. Name one explicitly to ask about a different project: `niro status <project-id>`.
 
 ```bash
 niro start
@@ -65,7 +67,16 @@ Every project in your account.
 ```bash
 niro build
 ```
-Rebuild the index by hand and watch it finish.
+Rebuild the index by hand and watch it finish. Like `niro status`, it picks the project for the
+branch you are on, so on a branch with a temporary project it rebuilds that one. Name a project to
+rebuild a different one.
+
+```bash
+niro doctor
+```
+Check this machine against the server and repair what is safe to repair. Today that is
+`niro doctor sync-registry`, which fixes folders and `.niro-project` files left pointing at projects
+that have gone or been renamed. The background watcher runs it for you every six hours.
 
 ---
 
@@ -85,10 +96,72 @@ niro discard-temp-project
 ```
 Run when the branch is merged. Forgotten copies are cleaned up after two weeks.
 
+If a copy is deleted for you, or a project is renamed, your machine is not told and the folder keeps
+pointing at something that is gone. `niro doctor sync-registry` sorts that out, and the background
+watcher runs it every six hours — see [When a project is deleted](#when-a-project-is-deleted).
+
 Full guide: [docs/working-on-branches.md](https://unpkg.com/@niroai/niro/docs/working-on-branches.md)
 
 ---
 
+## When a project is deleted
+
+Delete a project, or let an unused private copy expire, and your machine is not told. The folder
+carries on pointing at something that is no longer there.
+
+That is not just untidy. It is what makes `niro new-temp-project` in another folder say the slot is
+already taken, naming a copy that no longer exists. And a `.niro-project` file left naming a deleted
+project keeps answering, because it is read before your git remote.
+
+The background watcher checks every six hours and sorts this out for you. `niro
+doctor sync-registry` does the same thing on demand.
+
+What it does depends on what went missing:
+
+| What is gone | What happens to your folder |
+|---|---|
+| A private copy of a project | Goes back to the original project and carries on syncing |
+| The project itself | Left alone if the repo still exists; unregistered only when both are gone |
+| Neither, just a stale `.niro-project` | Repaired if your git remote says which project it should name; removed if it names nothing and is not shared; otherwise you are told |
+
+It never deletes anything on the server, and it never touches a `.niro-project` file. Everything it
+acts on has already gone. It only acts on what it can check, too: a folder git cannot read, or a
+project it could not reach, is left exactly as it is and reported. A bad connection can never cost
+you a working folder.
+
+**How it decides what to do with a stale `.niro-project`.** That file can hold a project's name
+rather than its id, so a renamed project looks exactly like a deleted one. Niro uses a second signal:
+your folder's git remote. If the remote points at exactly one project, the pin is rewritten to that
+project's id, which cannot be broken by a future rename. If the remote points at nothing either, the
+pin identifies nothing and is removed.
+
+**Unless the file is committed.** A `.niro-project` in git is shared with everyone who clones the
+repo, and what looks like a dead project to you may be a colleague's. Niro never changes a committed
+one for you. It tells you, and you decide.
+
+`niro info` also mentions it when you are standing in an affected folder, so you do not have to go
+looking.
+
+## When you run out of private copies
+
+You get a limited number of private copies of each project. If you hit that limit, Niro tells you
+which branches are holding them, and the CLI adds where each one is checked out:
+
+```
+You already have 5 working copies of this project, which is the limit (5).
+They are for: feature/a, feature/b, feature/c, feature/d, feature/e.
+
+    You have 5 working copies of this project on this machine:
+      feature/a    /home/you/work/service
+      feature/b    /home/you/work/service-wt2
+      ...
+```
+
+Run `niro discard-temp-project` in one you have finished with, then try again. Copies nobody has
+touched for a while are also cleared automatically.
+
+---
+
 ## Measure what Niro changes
 
 ```bash
@@ -155,7 +228,10 @@ Detach a repo from a project. Nothing is deleted.
 ```bash
 niro remove --project --confirm-name <name>
 ```
-Delete a whole project. Destructive, hence the confirmation.
+Delete a whole project. Destructive, hence the confirmation. It refuses on a temporary project and
+sends you to `niro discard-temp-project` instead, because that removes the copy **and** points this
+folder back at the shared project; deleting it here would leave the folder aimed at a project that
+no longer exists. `niro delete` refuses for the same reason.
 
 ---
 
@@ -181,7 +257,8 @@ Watch this folder in the foreground instead, for one session.
 ## Reference
 
 Add `--help` to any command for its flags. Add `--json` to `whoami`, `info`, `status`,
-`projects`, `build`, `ab report` and `edit --list-env` for machine-readable output.
+`projects`, `build`, `ab report`, `edit --list-env` and `doctor sync-registry` for machine-readable
+output.
 
 | File | What it holds |
 |---|---|

package/docs/working-on-branches.md

@@ -46,6 +46,14 @@ It creates your own private copy of the project inside Niro.
 
 From then on, answers come from YOUR code.
 
+The commands follow too. `niro status` and `niro build` act on the copy for the branch you are on,
+not on the shared project, so "is my index up to date" and "rebuild it" mean what you expect while
+you are working on a branch. Name a project explicitly if you want a different one.
+
+`niro delete` and `niro remove --project` will not delete a private copy. They send you to
+`niro discard-temp-project`, which removes the copy AND points your folder back at the shared
+project. Deleting it any other way leaves your folder aimed at something that is gone.
+
 ## Switching branches
 
 Nothing to do. Niro checks which branch you are on for every question.
@@ -63,6 +71,61 @@ Run this in the repo folder:
 It deletes your private copy. Your local files are never touched.
 If you forget, Niro deletes unused copies by itself after two weeks.
 
+## Tidying up copies that were deleted for you
+
+When a copy goes after two weeks, or somebody deletes it in the web app,
+your machine is not told. The folder is left pointing at a copy that is
+no longer there. Nothing breaks, but "niro new-temp-project" in another
+worktree of the same repo will say the slot is already taken.
+
+Run this from anywhere to sort it out:
+
+    niro doctor sync-registry
+
+You will rarely need to type it. The background watcher runs the same
+check every six hours by itself.
+
+It sorts out three things, and treats them differently:
+
+- A folder pointing at a private copy that has gone goes back to the
+  original project, and carries on syncing.
+- A folder pointing at a project that has gone is only unregistered when
+  the repo has gone too. A project can be deleted while its repos are
+  moved somewhere else, and that folder is still syncing perfectly well.
+- A ".niro-project" file naming something the server does not know is
+  repaired where possible. That file can hold a project's NAME rather
+  than its id, so a renamed project looks exactly like a deleted one.
+  Niro checks your folder's git remote instead: if that points at one
+  project, the file is rewritten to that project's id, which a future
+  rename cannot break. If the remote points at nothing either, the file
+  names nothing and is removed.
+
+  Not if the file is committed to git, though. Then it is shared with
+  everyone who clones the repo, and a project that means nothing to you
+  may be a colleague's. Niro tells you and leaves the choice to you.
+  "niro info" mentions it too, when you are standing in that folder.
+
+Copies that are still there are left alone, and so is anything it could
+not check, so a dropped connection never costs you a working folder. Add
+"--dry-run" to see the list without changing anything.
+
+## When you run out of private copies
+
+You get a limited number of private copies of each project. When you hit
+the limit, Niro says which branches are holding them, and the CLI adds
+where each one is checked out on this machine:
+
+    You already have 5 working copies of this project, which is
+    the limit (5). They are for: feature/a, feature/b, ...
+
+        You have 5 working copies of this project on this machine:
+          feature/a    /home/you/work/service
+          feature/b    /home/you/work/service-wt2
+
+Run "niro discard-temp-project" in one you have finished with, then try
+again. Copies nobody has touched for a while are cleared automatically,
+so this usually sorts itself out.
+
 ## A feature that spans several repos
 
 Run "niro new-temp-project" in each repo folder you branch.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@niroai/niro",
-  "version": "0.10.1",
+  "version": "0.12.0",
   "description": "Niro — one package: the niro CLI plus the Niro MCP server (code intelligence for AI coding assistants).",
   "keywords": [
     "niro",

package/src/commands/_resolveProject.js

@@ -7,11 +7,16 @@
  *        - an alias or git URL        -> resolved via GET /api/projects/resolve.
  *      If an alias/URL maps to MULTIPLE projects, a clear ambiguity error is
  *      thrown listing the candidates (we never silently pick the first).
- *   2. Walk up from cwd looking for .niro-project (same logic the MCP bridge uses).
+ *   2. The project THIS FOLDER IS CURRENTLY SYNCED TO, when it was recorded for the
+ *      branch that is checked out. See resolveFromSyncedFolder for why this comes
+ *      before the pin.
+ *   3. Walk up from cwd looking for .niro-project (same logic the MCP bridge uses).
  */
 const api = require("../lib/api");
 const prompt = require("../lib/prompt");
 const niroProjectFile = require("../lib/niroProjectFile");
+const git = require("../lib/git");
+const watchState = require("../lib/watchState");
 const { normalizeProjects, resolveContext } = require("../lib/resolveContext");
 
 // A canonical project_id is a UUID. Anything that doesn't look like one and
@@ -119,6 +124,36 @@ async function resolveProjectFromGit(opts = {}) {
   throw e;
 }
 
+/**
+ * The project this folder is actually synced to right now, when the recorded branch is the
+ * one checked out. Null when nothing is recorded, when the branch has moved on, or on any error.
+ *
+ * <p>Why this has to come BEFORE the .niro-project pin. The pin holds the SHARED project's id and
+ * never changes. When a developer runs `niro new-temp-project`, the folder starts syncing to a
+ * private temporary project that indexes their branch, and only ~/.niro/projects.json records it.
+ * Reading the pin therefore answers about a project the developer is not working in. Measured on
+ * 2026-09-08: in a repo on branch feat/shipping-wrap-rethrow, `niro status` reported the shared
+ * project with "Updated 2026-09-06T09:28", two days stale, while the branch's own project had
+ * finished a build four minutes earlier. `niro build` had the same fault and would have rebuilt the
+ * shared project.
+ *
+ * <p>The branch comparison is the safety catch. An entry recorded on another branch must not
+ * redirect the command, so a mismatch falls through to the pin, which is the old behaviour.
+ */
+function resolveFromSyncedFolder(opts = {}) {
+  try {
+    const ctx = git.inspect(process.cwd());
+    if (!ctx || !ctx.repoRoot) return null;
+    const entry = watchState.get(ctx.repoRoot, opts.apiUrl || api.currentBaseUrl());
+    if (!entry || !entry.projectId) return null;
+    if (entry.branch && ctx.branch && entry.branch !== ctx.branch) return null;
+    return entry.projectId;
+  } catch (_) {
+    // Never block a command on this: falling through to the pin is the previous behaviour.
+    return null;
+  }
+}
+
 async function resolveProjectId(explicit, opts = {}) {
   if (explicit) {
     // A UUID is used directly — unchanged behavior. Anything else is an
@@ -126,7 +161,10 @@ async function resolveProjectId(explicit, opts = {}) {
     if (looksLikeProjectId(explicit)) return explicit;
     return resolveAliasOrUrl(explicit, opts);
   }
-  // No explicit arg: prefer a .niro-project pin (walk up from cwd).
+  // No explicit arg: the project this folder is synced to on THIS branch wins over the pin.
+  const fromFolder = resolveFromSyncedFolder(opts);
+  if (fromFolder) return fromFolder;
+  // Then a .niro-project pin (walk up from cwd).
   const fromFile = readNiroProjectFile(process.cwd());
   if (fromFile) {
     // A pin that is already a project_id is used directly. A pin holding an
@@ -139,4 +177,22 @@ async function resolveProjectId(explicit, opts = {}) {
   return resolveProjectFromGit(opts);
 }
 
-module.exports = { resolveProjectId, readNiroProjectFile, resolveAliasOrUrl, looksLikeProjectId };
+/**
+ * The temporary project this id names, or null when it is an ordinary shared project.
+ *
+ * <p>Used by the destructive commands. Deleting a temporary project through `niro delete` leaves
+ * the folder pinned to a project that is gone and skips the local cleanup that
+ * `niro discard-temp-project` does, so those commands send the developer there instead.
+ * Never throws: if the project cannot be fetched, the caller carries on as before.
+ */
+async function tempProjectSourceId(projectId, opts = {}) {
+  try {
+    const project = await api.get(`/api/projects/${encodeURIComponent(projectId)}`, { apiUrl: opts.apiUrl });
+    return (project && (project.cloneOfProjectId || project.clone_of_project_id)) || null;
+  } catch (_) {
+    return null;
+  }
+}
+
+module.exports = { resolveProjectId, readNiroProjectFile, resolveAliasOrUrl, looksLikeProjectId,
+  resolveFromSyncedFolder, tempProjectSourceId };