@niroai/niro 0.3.4 → 0.3.6

package/package.json

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

package/src/mcp/setup.js

@@ -41,17 +41,27 @@ const NIRO_MD_MARKER = "<!-- niro-mcp -->";
  * own notes added below the block survive uninstall — see teardown.js removeMarkerSection).
  * Each begins with a leading "\n" because install does `existing + section`.
  */
+/**
+ * Explore-first rule, shared by every client's markdown section. Prose alone is weak, but this is the
+ * one lever some clients (Codex, Copilot CLI, Factory, OpenCode, Windsurf) have — they support no hooks,
+ * so their ONLY always-on nudge is this file. For Claude Code it reinforces the PreToolUse Grep|Glob|Read
+ * hook (NIRO_EXPLORE_COMMAND), which fires once per session/repo/branch; this stays in force for the rest
+ * of the session. Wording is imperative and names concrete tools so the agent knows what to call instead
+ * of native search.
+ */
+const NIRO_EXPLORE_FIRST_SENTENCE = "MUST FOLLOW: before you run grep, find, glob, or open a file to hunt for something, first check whether a Niro tool answers it (code_grep for content search, resolve_fqn and get_source_code for a known symbol, find_handler and find_api_endpoints for entry points). Use the connection tools (get_call_chain, get_reverse_call_chain, get_blast_radius, get_impact_analysis, get_service_topology) to understand how code connects BEFORE deciding which file to read or search next, rather than reading files to rebuild that picture by hand. Native search is the fallback for what Niro does not cover (config files, docs, logs, generated output, non-code text) or when the tools are unavailable.";
+
 const NIRO_MULTI_REPO_SENTENCE = "The temporary project answer is per (repo, BRANCH): after you create/switch a branch in a repo — and before your first edit on that branch — call should_create_temp_project with the repo's git url, its CURRENT branch, and its `.niro-project` id if present, then run `niro new-temp-project` in its folder if needs_temp_project is true. Re-check after every branch change (a `false` from another branch does NOT carry over); this applies to every repo you touch, including when the session started in a parent folder that is not itself a git repo.";
-const NIRO_CLAUDE_MD_SECTION = `\n${NIRO_MD_MARKER}\n## Niro MCP\nNiro MCP tools are available for code intelligence. Use them (call chains, blast radius, impact analysis, source lookup) before falling back to native grep/read for code questions.\nBefore adding/writing any new code, you MUST use the find_reusable_code tool from niro to figure out if there is anything reusable.\n${NIRO_MULTI_REPO_SENTENCE}\n`;
-const NIRO_CODEX_MD_SECTION = `\n${NIRO_MD_MARKER}\n## Niro MCP\nNiro MCP code-intelligence tools and the \`niro-skill\` are available (call chains, blast radius, impact analysis, source lookup). Prefer them over grep/read for questions about this codebase; the niro-skill has the full tool-routing playbook. Before adding or writing any new code, use find_reusable_code to check for reusable code. If the niro tools are not present or the repo is not indexed, use native tools.\n${NIRO_MULTI_REPO_SENTENCE}\n`;
-const NIRO_WINDSURF_MD_SECTION = `\n${NIRO_MD_MARKER}\n## Niro MCP\nNiro MCP code-intelligence tools and the niro-skill are available. Prefer them over grep/read for questions about this codebase (structure, call chains, blast radius, impact, data flows, reuse); the niro-skill has the full routing playbook. Before writing any new code, use find_reusable_code. If the niro tools are not present or the repo is not indexed, use native tools.\n${NIRO_MULTI_REPO_SENTENCE}\n`;
+const NIRO_CLAUDE_MD_SECTION = `\n${NIRO_MD_MARKER}\n## Niro MCP\nNiro MCP tools are available for code intelligence. Use them (call chains, blast radius, impact analysis, source lookup) before falling back to native grep/read for code questions.\nBefore adding/writing any new code, you MUST use the find_reusable_code tool from niro to figure out if there is anything reusable.\n${NIRO_EXPLORE_FIRST_SENTENCE}\n${NIRO_MULTI_REPO_SENTENCE}\n`;
+const NIRO_CODEX_MD_SECTION = `\n${NIRO_MD_MARKER}\n## Niro MCP\nNiro MCP code-intelligence tools and the \`niro-skill\` are available (call chains, blast radius, impact analysis, source lookup). Prefer them over grep/read for questions about this codebase; the niro-skill has the full tool-routing playbook. Before adding or writing any new code, use find_reusable_code to check for reusable code. If the niro tools are not present or the repo is not indexed, use native tools.\n${NIRO_EXPLORE_FIRST_SENTENCE}\n${NIRO_MULTI_REPO_SENTENCE}\n`;
+const NIRO_WINDSURF_MD_SECTION = `\n${NIRO_MD_MARKER}\n## Niro MCP\nNiro MCP code-intelligence tools and the niro-skill are available. Prefer them over grep/read for questions about this codebase (structure, call chains, blast radius, impact, data flows, reuse); the niro-skill has the full routing playbook. Before writing any new code, use find_reusable_code. If the niro tools are not present or the repo is not indexed, use native tools.\n${NIRO_EXPLORE_FIRST_SENTENCE}\n${NIRO_MULTI_REPO_SENTENCE}\n`;
 /**
  * Shared generic section for clients whose "always-on instructions" file has no companion
  * skill mechanism we've verified (Gemini CLI's GEMINI.md, GitHub Copilot CLI's
  * copilot-instructions.md, Factory's AGENTS.md, OpenCode's AGENTS.md) — one wording, reused
  * across those destination files (teardown matches it per-file, so reuse is safe).
  */
-const NIRO_GENERIC_MD_SECTION = `\n${NIRO_MD_MARKER}\n## Niro MCP\nNiro MCP code-intelligence tools are available (call chains, blast radius, impact analysis, source lookup). Prefer them over grep/read for questions about this codebase. Before adding or writing any new code, use find_reusable_code to check for reusable code. If the niro tools are not present or the repo is not indexed, use native tools.\n${NIRO_MULTI_REPO_SENTENCE}\n`;
+const NIRO_GENERIC_MD_SECTION = `\n${NIRO_MD_MARKER}\n## Niro MCP\nNiro MCP code-intelligence tools are available (call chains, blast radius, impact analysis, source lookup). Prefer them over grep/read for questions about this codebase. Before adding or writing any new code, use find_reusable_code to check for reusable code. If the niro tools are not present or the repo is not indexed, use native tools.\n${NIRO_EXPLORE_FIRST_SENTENCE}\n${NIRO_MULTI_REPO_SENTENCE}\n`;
 
 /** All niro markdown sections — the uninstaller tries each for an exact removal. */
 const NIRO_MD_SECTIONS = [NIRO_CLAUDE_MD_SECTION, NIRO_CODEX_MD_SECTION, NIRO_WINDSURF_MD_SECTION, NIRO_GENERIC_MD_SECTION];
@@ -116,6 +126,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 +563,7 @@ async function setupClaudeCode(apiKey, mcpServerUrl) {
   addClaudeCodePostCompactHook();
   addClaudeCodeUserPromptHook();
   addClaudeCodePreToolUseHook();
+  addClaudeCodeExploreHook();
   addClaudeCodeMemory();
   addClaudeCodeSkill();
   addClaudeCodeCliSkill();
@@ -777,6 +800,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
@@ -791,6 +896,16 @@ code — structure, behavior, impact, data/event flows, semantics — prefer the
 native grep/read. For anything outside the indexed code (config files, docs, runtime state),
 use your native tools.
 
+## Explore first — MUST FOLLOW
+
+Before you run grep, find, glob, or open a file to hunt for something, check whether a Niro
+tool answers it: \`code_grep\` for content search, \`resolve_fqn\` + \`get_source_code\` for a known
+symbol, \`find_handler\` / \`find_api_endpoints\` for entry points. Use the connection tools
+(\`get_call_chain\`, \`get_reverse_call_chain\`, \`get_blast_radius\`, \`get_impact_analysis\`,
+\`get_service_topology\`) to understand how the code connects BEFORE you decide which file to
+read or search next, instead of reading files to rebuild that picture by hand. Native search
+stays the fallback for what Niro does not cover, and when the tools are unavailable.
+
 \`project_id\` auto-resolves from a \`.niro-project\` file at the repo root — omit it. If there
 is no such file, call \`list_projects\` and pass the chosen \`project_id\`.
 
@@ -908,6 +1023,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**
@@ -1191,6 +1307,13 @@ alwaysApply: false
 The niro MCP server exposes code-intelligence tools for this codebase. Prefer them over
 grep/read for any question answerable from the indexed code.
 
+MUST FOLLOW — explore first: before you run grep, find, glob, or open a file to hunt for
+something, check whether a niro tool answers it (code_grep, resolve_fqn + get_source_code,
+find_handler, find_api_endpoints). Use the connection tools (get_call_chain,
+get_reverse_call_chain, get_blast_radius, get_impact_analysis, get_service_topology) to see
+how the code connects BEFORE deciding which file to read or search next. Native search is the
+fallback for what niro does not cover, and when the tools are unavailable.
+
 Availability self-check FIRST — if the niro tools are not present in this session, or the
 repo is not indexed (no project resolves / a tool reports "not indexed"), fall back to
 native tools silently and do not mention Niro.
@@ -1207,7 +1330,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
@@ -1478,6 +1601,13 @@ Niro code-intelligence MCP tools are available for the current codebase. Prefer
 grep/read for questions about structure, call chains, blast radius, impact, data flows, and
 reuse. Before writing or adding any new code, use \`find_reusable_code\` first.
 
+MUST FOLLOW — explore first: before you run grep, find, glob, or open a file to hunt for
+something, check whether a niro tool answers it (\`code_grep\`, \`resolve_fqn\` +
+\`get_source_code\`, \`find_handler\`, \`find_api_endpoints\`). Use the connection tools
+(\`get_call_chain\`, \`get_reverse_call_chain\`, \`get_blast_radius\`, \`get_impact_analysis\`,
+\`get_service_topology\`) to see how the code connects BEFORE deciding which file to read or
+search next. Native search is the fallback for what niro does not cover.
+
 If the niro tools are not present in this session, or the repo is not indexed (no project
 resolves), fall back to native tools silently — do not mention Niro's absence.
 `;
@@ -1516,6 +1646,13 @@ Niro code-intelligence MCP tools are available for the current codebase. Prefer
 grep/read for questions about structure, call chains, blast radius, impact, data flows, and
 reuse. Before writing or adding any new code, use \`find_reusable_code\` first.
 
+MUST FOLLOW — explore first: before you run grep, find, glob, or open a file to hunt for
+something, check whether a niro tool answers it (\`code_grep\`, \`resolve_fqn\` +
+\`get_source_code\`, \`find_handler\`, \`find_api_endpoints\`). Use the connection tools
+(\`get_call_chain\`, \`get_reverse_call_chain\`, \`get_blast_radius\`, \`get_impact_analysis\`,
+\`get_service_topology\`) to see how the code connects BEFORE deciding which file to read or
+search next. Native search is the fallback for what niro does not cover.
+
 If the niro tools are not present in this session, or the repo is not indexed (no project
 resolves), fall back to native tools silently — do not mention Niro's absence.
 `;
@@ -1957,10 +2094,17 @@ module.exports = {
   isNiroPostCompactHook,
   isNiroUserPromptHook,
   isNiroPreToolUseHook,
+  isNiroExploreHook,
   userHome,
   // Exposed for content regression tests (e.g. the cross-project routing guidance).
   NIRO_SKILL,
   NIRO_CLI_SKILL,
+  // Exposed for tests: the explore-first rule must reach EVERY client's always-on instruction surface.
+  NIRO_EXPLORE_FIRST_SENTENCE,
+  NIRO_CURSOR_RULE,
+  NIRO_CLINE_RULE,
+  NIRO_KIRO_STEERING,
+  upsertNiroMarkerSection,
   // Exposed for tests: URL resolution replaced the install-time prompt.
   resolveMcpServerUrl,
   SAAS_URL,

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;
   }