@niroai/niro 0.3.3 → 0.3.5

package/README.md

@@ -23,8 +23,8 @@ niro new-temp-project     # run once in the repo folder
 ```
 
 This creates your own private copy of the project that follows your branch and your
-uncommitted edits, live (keep `niro watch` running). Teammates are not affected and cannot
-see your copy. Switching branches needs nothing: Niro answers from your copy on the new
+uncommitted edits, live (keep `niro watch` running). Your original project is not changed.
+Switching branches needs nothing: Niro answers from your copy on the new
 branch, and from the matching indexed project on branches you already cover. When your branch
 is merged:
 

package/docs/working-on-branches.md

@@ -41,8 +41,8 @@ It creates your own private copy of the project inside Niro.
 
 - The copy follows your branch, including changes you have not committed.
 - Every save updates the copy, as long as "niro watch" is running.
-- Teammates are not affected. They keep using the shared project.
-- Nobody can see your copy. Not even teammates on your account.
+- Your original project is not changed. It keeps its own index.
+- The copy is fully separate and disposable.
 
 From then on, answers come from YOUR code.
 
@@ -72,8 +72,9 @@ of your changes together.
 
 ## Common questions
 
-Can teammates see my unfinished code?
-No. Your copy is private to you.
+Does this change my original project?
+No. The original project and its index stay exactly as they were.
+The copy is separate; deleting it later loses nothing.
 
 Does this work with my AI assistant and my git host?
 Yes. Any assistant that supports MCP (Claude Code, Cursor, Windsurf,

package/package.json

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

package/src/commands/init.js

@@ -171,7 +171,7 @@ async function init(pathArg, opts = {}) {
       }
     } else if (otherBranchOnly.length) {
       // Known repo, but you're on a branch Niro hasn't indexed → the honest answer is "sandbox it",
-      // not "already indexed". A sandbox indexes your branch privately (teammates unaffected).
+      // not "already indexed". A sandbox indexes your branch in a separate copy (original untouched).
       const where = otherBranchOnly
         .map((p) => `"${p.alias || p.project_id}"${p.indexed_branch ? ` (indexed on ${color.cyan(p.indexed_branch)})` : ""}`)
         .join(", ");
@@ -179,7 +179,7 @@ async function init(pathArg, opts = {}) {
       console.log(`\n${color.green("✓")} This repo is part of: ${where}.`);
       console.log(`  But ${yourBranch} isn't indexed by Niro — answers would reflect the indexed branch, not your local work.`);
       console.log(`  ${color.cyan("Run `niro sandbox` here")} to index your branch privately ` +
-        color.dim("(teammates unaffected; `niro discard` to undo)."));
+        color.dim("(original project unchanged; `niro discard` to undo)."));
       if (!opts.addTo) {
         if (prompt.isNonInteractive()) {
           console.log(color.dim(

package/src/commands/takeover.js

@@ -72,7 +72,7 @@ async function takeover(pathArg, opts = {}) {
   }
 
   console.log(`\n  Creating a temporary private project of ${color.bold(source.alias || source.project_id)}...`);
-  console.log(color.dim("  Your teammates' view of the project is not affected."));
+  console.log(color.dim("  Your original project is not changed."));
 
   // 2. Create-or-extend server-side (ADR-016). If you already have a temporary project of this project,
   // the backend EXTENDS it — adds this repo to the same copy — instead of minting a second one, so

package/src/index.js

@@ -157,7 +157,7 @@ function main() {
   program
     .command("new-temp-project [path]")
     .aliases(["sandbox", "takeover"])
-    .description("Create a temporary private project for this folder that reflects your branch + local edits, so Niro's answers match your work (teammates unaffected). Remove it with `niro discard-temp-project`.")
+    .description("Create a temporary private project for this folder that reflects your branch + local edits, so Niro's answers match your work (your original project is unchanged). Remove it with `niro discard-temp-project`.")
     .option("--project <id_or_alias>", "which project to base the temporary project on when the repo maps to several")
     .action((pathArg, opts) => run(async () => {
       const cmd = require("./commands/takeover");

package/src/mcp/setup.js

@@ -116,6 +116,18 @@ function isNiroPreToolUseHook(h) {
   return cmds.some((c) => c.includes("should_create_temp_project") || c.includes("should_sandbox_repo"));
 }
 
+/**
+ * True if `h` is niro's PreToolUse explore-first reminder entry (matcher Grep|Glob|Read). Keyed on the
+ * unique `niro-explore-` marker-file prefix so a foreign PreToolUse hook on the same matcher is never
+ * touched. Shared by installer (upgrade-in-place) and uninstaller (removal).
+ */
+function isNiroExploreHook(h) {
+  const cmds = [];
+  if (h && Array.isArray(h.hooks)) h.hooks.forEach((i) => i && typeof i.command === "string" && cmds.push(i.command));
+  if (h && typeof h.command === "string") cmds.push(h.command);
+  return cmds.some((c) => c.includes("niro-explore-"));
+}
+
 /**
  * Writes a niro-managed skill/rule file, refreshing it when the generated content has
  * changed. These files are GENERATED (not hand-edited), so refresh-on-change is correct:
@@ -541,6 +553,7 @@ async function setupClaudeCode(apiKey, mcpServerUrl) {
   addClaudeCodePostCompactHook();
   addClaudeCodeUserPromptHook();
   addClaudeCodePreToolUseHook();
+  addClaudeCodeExploreHook();
   addClaudeCodeMemory();
   addClaudeCodeSkill();
   addClaudeCodeCliSkill();
@@ -777,6 +790,88 @@ function addClaudeCodePreToolUseHook() {
   }
 }
 
+/**
+ * The niro PreToolUse hook command (matcher Grep|Glob|Read). Prose instructions (CLAUDE.md, the
+ * UserPromptSubmit hook, the niro skill) tell Claude to prefer niro tools for code exploration, but in
+ * practice that only sticks when a task is phrased as a discovery question — a task phrased as "fix X" or
+ * "add Y" skips straight to native search with no interruption. This hook is the deterministic backstop:
+ * once per (session, repo, branch), the first native Grep/Glob/Read call in a niro-indexed repo gets an
+ * advisory reminder to prefer niro's structural tools instead — regardless of how the task was phrased.
+ *
+ * Dependency-free (no jq): reads the PreToolUse JSON on stdin. Read supplies `file_path`; Grep/Glob supply
+ * `path` (often omitted, meaning cwd) — so this tries file_path, then path, then the hook's own `cwd`
+ * field, then falls back to $PWD. Walks up for a `.niro-project` marker (silent outside indexed repos)
+ * and dedupes via a marker file keyed by session_id + repo root + branch, same scheme as the Edit|Write
+ * temp-project hook but under the distinct `niro-explore-` prefix so the two hooks never collide.
+ */
+const NIRO_EXPLORE_COMMAND = [
+  'IN="$(cat)"',
+  // Read gives file_path; Grep/Glob give path (may be absent); fall back to cwd, then $PWD.
+  `f="$(printf '%s' "$IN" | grep -oE '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed -E 's/.*:[[:space:]]*"([^"]*)"/\\1/')"`,
+  `[ -z "$f" ] && f="$(printf '%s' "$IN" | grep -oE '"path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed -E 's/.*:[[:space:]]*"([^"]*)"/\\1/')"`,
+  `[ -z "$f" ] && f="$(printf '%s' "$IN" | grep -oE '"cwd"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed -E 's/.*:[[:space:]]*"([^"]*)"/\\1/')"`,
+  '[ -z "$f" ] && f="$PWD"',
+  'd0="$f"; [ -d "$d0" ] || d0="$(dirname "$f")"',
+  'r="$(git -C "$d0" rev-parse --show-toplevel 2>/dev/null)"',
+  '[ -z "$r" ] && exit 0',
+  // only remind inside a niro-indexed tree
+  'd="$r"; ok=0; while [ -n "$d" ] && [ "$d" != "/" ]; do if [ -f "$d/.niro-project" ]; then ok=1; break; fi; d="$(dirname "$d")"; done',
+  '[ "$ok" = 0 ] && exit 0',
+  `s="$(printf '%s' "$IN" | grep -oE '"session_id"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed -E 's/.*:[[:space:]]*"([^"]*)"/\\1/')"`,
+  // Branch-aware dedup, same rationale as the Edit|Write hook: a stale answer from a different branch must not
+  // silence the reminder after a branch switch.
+  'b="$(git -C "$r" rev-parse --abbrev-ref HEAD 2>/dev/null)"',
+  `k="$(printf '%s\\n%s\\n%s' "$s" "$r" "$b" | cksum | cut -d' ' -f1)"`,
+  'm="${TMPDIR:-/tmp}/niro-explore-$k"',
+  '[ -f "$m" ] && exit 0',
+  'touch "$m"',
+  // Advisory context injection ONLY — no permissionDecision, so it never blocks the read/search.
+  `printf '%s' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":"This is a niro-indexed repo. For code structure/behavior/call-chain/impact/reuse questions - including ones that come up mid-task while implementing or fixing something, not just standalone discovery questions - prefer niro MCP tools (get_source_code, code_grep, get_call_chain, get_blast_radius, get_impact_analysis, find_reusable_code, get_class_structure, etc.) over native Grep/Glob/Read. Fall back to native tools silently for out-of-scope questions (config files, docs, runtime state, non-code content). Shown once per repo per branch per session."}}'`,
+].join('; ');
+
+/**
+ * Adds the PreToolUse (Grep|Glob|Read) explore-first reminder hook to ~/.claude/settings.json. Idempotent:
+ * upgrades a stale niro entry in place, never touches a foreign PreToolUse hook on the same matcher
+ * (matched by the niro-explore- marker via isNiroExploreHook).
+ */
+function addClaudeCodeExploreHook() {
+  const settingsPath = path.join(process.env.HOME || "", ".claude", "settings.json");
+  let settings = {};
+  try {
+    if (fs.existsSync(settingsPath)) settings = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
+  } catch {
+    // Corrupt or missing — start fresh
+  }
+
+  if (!settings.hooks) settings.hooks = {};
+  if (!settings.hooks.PreToolUse) settings.hooks.PreToolUse = [];
+
+  const entry = { matcher: "Grep|Glob|Read", hooks: [{ type: "command", command: NIRO_EXPLORE_COMMAND }] };
+  const alreadyCurrent = settings.hooks.PreToolUse.some(
+    (h) => Array.isArray(h.hooks) && h.hooks.some((i) => i && i.command === NIRO_EXPLORE_COMMAND),
+  );
+  if (alreadyCurrent) {
+    console.log("  PreToolUse explore-first hook already up to date — skipping.\n");
+    return;
+  }
+
+  const hadStale = settings.hooks.PreToolUse.some(isNiroExploreHook);
+  settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter((h) => !isNiroExploreHook(h));
+  settings.hooks.PreToolUse.push(entry);
+
+  try {
+    fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+    console.log(`  PreToolUse explore-first hook ${hadStale ? "upgraded" : "added"} in ~/.claude/settings.json`);
+    console.log("  → Before the first native Grep/Glob/Read in a niro-indexed repo, Claude is reminded once/session/branch");
+    console.log("    to prefer niro tools — even mid-task, not just for standalone discovery questions.\n");
+  } catch (err) {
+    console.warn(`  Could not write ~/.claude/settings.json: ${err.message}`);
+    console.warn("  Add manually to the PreToolUse array in ~/.claude/settings.json:\n");
+    console.warn(JSON.stringify(entry, null, 2) + "\n");
+  }
+}
+
 /** Body of the `niro` skill (long-form tool-routing playbook). */
 const NIRO_SKILL = `---
 name: niro-skill
@@ -840,7 +935,7 @@ lost"). When the target of the question is a repo other than the current one:
 
 Niro indexes a repo at ONE branch (the team's tracked branch). Identity is (git url, branch): a graph
 built on \`main\` does NOT reflect your feature branch or uncommitted edits. A **temporary project** is a private,
-temporary index of your branch (\`niro new-temp-project\` to create, \`niro discard-temp-project\` to remove — teammates unaffected).
+temporary index of your branch (\`niro new-temp-project\` to create, \`niro discard-temp-project\` to remove — the original project is unchanged).
 
 - **Obey \`🔔 Niro ACTION\` notices.** When a tool result appends "the coding assistant should run
   \`niro new-temp-project\` / \`niro discard-temp-project\`", run that command with the Bash tool (cwd = that
@@ -908,6 +1003,7 @@ temporary index of your branch (\`niro new-temp-project\` to create, \`niro disc
 | Full path from A to B (prefer \`to_service\` for cross-service) | \`trace_execution_path\` |
 | HTTP endpoints a service exposes | \`find_api_endpoints\` |
 | Outbound HTTP calls a service makes | \`find_outbound_http_calls\` |
+| Service-to-service call map (who calls whom), as a Mermaid diagram | \`get_service_topology\` |
 | What handles an outgoing HTTP call / event | \`find_handler\` |
 
 **Change safely**
@@ -1207,7 +1303,7 @@ Routing (most specific wins):
 <!-- how_does_x_work temporarily disabled (hidden MCP tool) — re-add "how_does_x_work (forward flow) | " to the understand line below when re-enabled -->
 - understand: explain_code (AI docs) | get_source_code | get_class_structure
 - navigate: get_call_chain (callees) | get_reverse_call_chain (callers) | trace_execution_path (A to B)
-- HTTP: find_api_endpoints | find_outbound_http_calls | find_handler
+- HTTP: find_api_endpoints | find_outbound_http_calls | find_handler | get_service_topology (service-to-service map, Mermaid)
 <!-- why_could_x_happen temporarily disabled (hidden MCP tool) — re-add "why_could_x_happen | " to the debug line below when re-enabled -->
 - debug: find_known_issues | get_state_at_entry
 - data & events: get_data_resource_usage | get_event_producers_and_handlers
@@ -1957,6 +2053,7 @@ module.exports = {
   isNiroPostCompactHook,
   isNiroUserPromptHook,
   isNiroPreToolUseHook,
+  isNiroExploreHook,
   userHome,
   // Exposed for content regression tests (e.g. the cross-project routing guidance).
   NIRO_SKILL,

package/src/mcp/teardown.js

@@ -5,7 +5,8 @@
  *
  * `niro mcp uninstall` removes everything `niro mcp install` wrote, per editor:
  *   - the MCP server registration (claude/codex CLI, or the editor's JSON config)
- *   - the niro hooks in ~/.claude/settings.json (PostCompact + UserPromptSubmit + PreToolUse)
+ *   - the niro hooks in ~/.claude/settings.json (PostCompact + UserPromptSubmit + PreToolUse: both the
+ *     Edit|Write temp-project reminder and the Grep|Glob|Read explore-first reminder)
  *   - the niro section in markdown config (CLAUDE.md / AGENTS.md / Windsurf rules)
  *   - the generated skills (~/.claude/skills, the shared ~/.agents/skills)
  *   - Cursor's "niro:*" allowlist entry and project rule
@@ -38,6 +39,7 @@ const {
   isNiroPostCompactHook,
   isNiroUserPromptHook,
   isNiroPreToolUseHook,
+  isNiroExploreHook,
   userHome,
 } = require("./setup");
 
@@ -122,10 +124,10 @@ function removeMarkerSectionBounded(content, marker) {
 }
 
 /**
- * Strip niro's PostCompact and UserPromptSubmit hook entries from a parsed Claude Code
- * settings object (mutates and returns it). Uses the same matchers install uses. Empty
- * arrays / an empty `hooks` object are pruned so the file stays tidy. Other hooks are
- * untouched. Returns { settings, removed } where `removed` is the count deleted.
+ * Strip niro's PostCompact, UserPromptSubmit, and PreToolUse (temp-project + explore-first) hook
+ * entries from a parsed Claude Code settings object (mutates and returns it). Uses the same matchers
+ * install uses. Empty arrays / an empty `hooks` object are pruned so the file stays tidy. Other hooks
+ * are untouched. Returns { settings, removed } where `removed` is the count deleted.
  */
 function filterNiroHooks(settings) {
   let removed = 0;
@@ -148,7 +150,7 @@ function filterNiroHooks(settings) {
   }
   if (Array.isArray(hooks.PreToolUse)) {
     const before = hooks.PreToolUse.length;
-    hooks.PreToolUse = hooks.PreToolUse.filter((h) => !isNiroPreToolUseHook(h));
+    hooks.PreToolUse = hooks.PreToolUse.filter((h) => !isNiroPreToolUseHook(h) && !isNiroExploreHook(h));
     removed += before - hooks.PreToolUse.length;
     if (hooks.PreToolUse.length === 0) delete hooks.PreToolUse;
   }