@niroai/niro 0.3.0

package/src/lib/moduleExcludeSuggestions.js

@@ -0,0 +1,57 @@
+/**
+ * Post-register helper: fetch module exclude suggestions from the backend
+ * and offer them to the user (one prompt per suggestion). On confirmation
+ * each accepted pattern is appended and PUT back to the backend.
+ *
+ * Skips silently if --defaults is set, the user supplied --module-exclude
+ * flags already, or the backend returns no suggestions.
+ */
+const agentApi = require("./agentApi");
+const prompt = require("./prompt");
+const color = require("./color");
+
+async function offerModuleExcludeSuggestions(gitId, opts = {}, alreadySupplied = []) {
+  if (opts.defaults) return;
+  if (alreadySupplied && alreadySupplied.length > 0) return;
+  if (!process.stdin.isTTY) return;
+
+  let suggestions;
+  try {
+    suggestions = await agentApi.getModuleExcludeSuggestions(gitId);
+  } catch {
+    return;
+  }
+  if (!Array.isArray(suggestions) || suggestions.length === 0) return;
+
+  console.log(`\n  ${color.cyan("Suggested module exclusions")} (modules that are usually noise):`);
+  const accepted = [];
+  for (const s of suggestions) {
+    const count = s.module_count || s.moduleCount || 0;
+    const label = s.label || "";
+    const samples = (s.sample_modules || s.sampleModules || []).slice(0, 3);
+    console.log(
+      `    ${color.dim(s.pattern.padEnd(28))} ${String(count).padStart(3)} module${count === 1 ? "" : "s"}  ${color.dim(label)}`
+    );
+    if (samples.length > 0) {
+      console.log(`      ${color.dim("e.g. " + samples.join(", "))}`);
+    }
+    const yes = await prompt.confirm(`    Apply ${color.cyan(s.pattern)}?`, true);
+    if (yes) accepted.push(s.pattern);
+  }
+
+  if (accepted.length === 0) {
+    console.log(`  ${color.dim("No exclusions applied.")}`);
+    return;
+  }
+
+  try {
+    await agentApi.updateModuleExcludePatterns(gitId, accepted);
+    console.log(
+      `  ${color.green("✓")} Applied ${accepted.length} exclusion${accepted.length === 1 ? "" : "s"}.`
+    );
+  } catch (err) {
+    console.log(`  ${color.yellow("Warning:")} failed to save exclusions: ${err.message || err}`);
+  }
+}
+
+module.exports = { offerModuleExcludeSuggestions };

package/src/lib/niroProjectFile.js

@@ -0,0 +1,76 @@
+/**
+ * The .niro-project file consumed by @niroai/mcp-server and the CLI. A small text
+ * file at a repo root whose first non-comment, non-blank line is the project id.
+ * Lines starting with # are comments. This module is the SINGLE source of truth for
+ * that format — both the writer and every reader (the MCP bridge in src/mcp/server.js
+ * and the CLI's _resolveProject.js) go through here so the read/write contract can
+ * never drift again. (It drifted once: the bridge's hand-rolled reader only looked at
+ * line 0 and bailed on the comment header the writer always emits, so it skipped a
+ * valid pin and walked up to the wrong parent .niro-project.)
+ */
+const fs = require("fs");
+const path = require("path");
+
+function write(repoRoot, projectId, { overwrite = true } = {}) {
+  const target = path.join(repoRoot, ".niro-project");
+  if (!overwrite && fs.existsSync(target)) return { written: false, path: target };
+  const contents = `# Niro project binding — consumed by @niroai/mcp-server\n${projectId}\n`;
+  fs.writeFileSync(target, contents);
+  return { written: true, path: target };
+}
+
+/**
+ * Parse the project id out of .niro-project contents: the first non-comment,
+ * non-blank line, trimmed. Returns null if there is no such line (e.g. a
+ * comment-only file). Mirror of what write() emits.
+ */
+function parse(contents) {
+  const line = String(contents)
+    .split(/\r?\n/)
+    .find((l) => l.trim() && !l.trim().startsWith("#"));
+  return line ? line.trim() : null;
+}
+
+/**
+ * Walk up from startDir looking for a .niro-project that yields a project id.
+ * The nearest file with a parseable id wins; a comment-only file is skipped and
+ * the walk continues upward. Returns { id, source } (source = absolute file path)
+ * or null if none is found up to the filesystem root.
+ */
+function read(startDir) {
+  let dir = path.resolve(startDir);
+  const root = path.parse(dir).root;
+  while (true) {
+    const p = path.join(dir, ".niro-project");
+    try {
+      if (fs.existsSync(p) && fs.statSync(p).isFile()) {
+        const id = parse(fs.readFileSync(p, "utf8"));
+        if (id) return { id, source: p };
+      }
+    } catch {
+      // Unreadable file — ignore and keep walking up.
+    }
+    if (dir === root) return null;
+    dir = path.dirname(dir);
+  }
+}
+
+/**
+ * Delete the .niro-project file at repoRoot, if present. Used by `niro discard-temp-project` to restore a
+ * folder that had NO pin before takeover — writing the source id back would leave a pin file the folder
+ * never had. Best-effort: returns { removed } and never throws on a missing file.
+ */
+function remove(repoRoot) {
+  const target = path.join(repoRoot, ".niro-project");
+  try {
+    if (fs.existsSync(target)) {
+      fs.unlinkSync(target);
+      return { removed: true, path: target };
+    }
+  } catch {
+    // Best-effort — a locked/unreadable file is left as-is.
+  }
+  return { removed: false, path: target };
+}
+
+module.exports = { write, parse, read, remove };

package/src/lib/pendingRequests.js

@@ -0,0 +1,99 @@
+/**
+ * Per-request client-side deadline tracker for the MCP stdio↔SSE bridge.
+ *
+ * The bridge POSTs each JSON-RPC request to the server fire-and-forget and receives the
+ * result LATER as an SSE 'message' event. Without a deadline, a request the server never
+ * answers (a wedged dependency, a dropped result event, a silently half-open stream) leaves
+ * the MCP host waiting forever — the exact "hangs indefinitely" failure the upload path
+ * already guards against with an AbortController (agentApi.js). This tracks in-flight
+ * REQUESTS by JSON-RPC id; if no response arrives within timeoutMs it hands a synthesized
+ * JSON-RPC error to onExpire so the host fails cleanly instead of hanging.
+ *
+ * NOTE: this module is mirrored inline in the standalone npm bridge
+ * (niro-mcp-server-npm/index.js), which ships a `files` whitelist and cannot require it.
+ * Keep the two in sync.
+ *
+ * TRADEOFF: after a request's deadline fires, a genuinely-late server response for the SAME id that
+ * still arrives over SSE is forwarded to stdout as usual — so the host could see two messages for one
+ * id (it ignores the second, already-settled one). This CANNOT happen under defaults: the server-side
+ * deadline (MCP_TOOL_DEADLINE_MS, default 90s) is shorter than this client default (120s), so the
+ * server always answers first and cancels the timer. It only occurs if NIRO_TOOL_TIMEOUT_MS is set
+ * BELOW the server deadline. Keep NIRO_TOOL_TIMEOUT_MS >= the server deadline to avoid it.
+ */
+
+const DEFAULT_TOOL_TIMEOUT_MS = 120000;
+
+/**
+ * A client→server JSON-RPC REQUEST (one that expects a response) has BOTH a method and an id.
+ * A response (id + result/error, no method) and a notification (method, no id) are NOT tracked
+ * — tracking a response would arm a timer that never gets cancelled.
+ */
+function isTrackableRequest(message) {
+  return !!message
+    && typeof message.method === "string"
+    && message.id !== undefined && message.id !== null
+    && message.result === undefined && message.error === undefined;
+}
+
+/**
+ * @param {object} opts
+ * @param {number} opts.timeoutMs                deadline per request (ms)
+ * @param {(errObj:object)=>void} opts.onExpire  invoked with a JSON-RPC error object on timeout
+ * @param {(msg:string)=>void} [opts.onLog]      optional diagnostic sink (stderr)
+ */
+function createPendingTracker({ timeoutMs, onExpire, onLog }) {
+  const pending = new Map(); // JSON-RPC id -> timeout handle
+
+  function clear(id) {
+    const handle = pending.get(id);
+    if (handle !== undefined) {
+      clearTimeout(handle);
+      pending.delete(id);
+    }
+  }
+
+  function arm(id) {
+    clear(id); // defensive: never leak a prior timer for a reused id
+    const handle = setTimeout(() => {
+      pending.delete(id);
+      if (onLog) onLog(`request ${id} timed out after ${timeoutMs}ms; returned JSON-RPC error to client`);
+      onExpire({
+        jsonrpc: "2.0",
+        id,
+        error: {
+          code: -32001,
+          message:
+            `Niro MCP request timed out after ${timeoutMs}ms with no response from the server. ` +
+            `It may be busy indexing/enriching — retry shortly, or use your native tools. ` +
+            `(Adjust the deadline with NIRO_TOOL_TIMEOUT_MS.)`,
+        },
+      });
+    }, timeoutMs);
+    if (typeof handle.unref === "function") handle.unref(); // don't keep the process alive for the timer
+    pending.set(id, handle);
+  }
+
+  /** Cancel the deadline when a RESPONSE (id + result/error) arrives for a tracked request. */
+  function onIncoming(message) {
+    if (message
+        && message.id !== undefined && message.id !== null
+        && (message.result !== undefined || message.error !== undefined)) {
+      clear(message.id);
+    }
+  }
+
+  return { arm, clear, onIncoming, size: () => pending.size };
+}
+
+/** Resolve the per-request deadline from env, falling back to the default. */
+function resolveTimeoutMs(env) {
+  const raw = parseInt((env || {}).NIRO_TOOL_TIMEOUT_MS, 10);
+  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_TOOL_TIMEOUT_MS;
+}
+
+module.exports = {
+  createPendingTracker,
+  isTrackableRequest,
+  resolveTimeoutMs,
+  DEFAULT_TOOL_TIMEOUT_MS,
+};

package/src/lib/prompt.js

@@ -0,0 +1,118 @@
+/**
+ * Readline helpers for the CLI wizard flow. `ask` uses node's built-in
+ * readline. `askHidden` bypasses readline entirely and puts the TTY into
+ * raw mode to mask password input — mixing readline with a `data` listener
+ * for masking is unreliable across platforms.
+ */
+const readline = require("readline");
+const color = require("./color");
+
+function rl() {
+  return readline.createInterface({ input: process.stdin, output: process.stdout });
+}
+
+/**
+ * Single place that decides how a prompt's default value is displayed. A bare
+ * "[value]" reads as noise to first-time users, so the default is labelled
+ * explicitly: `Question (default: value):` — pressing Enter accepts it.
+ * Also shared by the MCP setup/teardown wizards' own ask() helpers.
+ */
+function formatPrompt(question, defaultValue) {
+  return defaultValue != null && defaultValue !== ""
+    ? `${question} ${color.dim(`(default: ${defaultValue})`)}: `
+    : `${question}: `;
+}
+
+function ask(question, defaultValue) {
+  const prompt = formatPrompt(question, defaultValue);
+  return new Promise((resolve) => {
+    const r = rl();
+    r.question(prompt, (answer) => {
+      r.close();
+      resolve(answer.trim() || defaultValue || "");
+    });
+  });
+}
+
+function askHidden(question) {
+  return new Promise((resolve, reject) => {
+    const stdin = process.stdin;
+    const stdout = process.stdout;
+
+    stdout.write(`${question}: `);
+
+    if (!stdin.isTTY) {
+      // Piped / non-TTY — read one line in flowing mode without masking.
+      let buf = "";
+      stdin.setEncoding("utf8");
+      const onData = (chunk) => {
+        buf += chunk;
+        const nl = buf.indexOf("\n");
+        if (nl >= 0) {
+          stdin.removeListener("data", onData);
+          stdin.pause();
+          resolve(buf.slice(0, nl).replace(/\r$/, ""));
+        }
+      };
+      stdin.resume();
+      stdin.on("data", onData);
+      return;
+    }
+
+    const wasRaw = stdin.isRaw === true;
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding("utf8");
+
+    let buffer = "";
+    const onData = (ch) => {
+      if (ch === "\r" || ch === "\n" || ch === "\u0004") {
+        stdin.removeListener("data", onData);
+        if (!wasRaw) stdin.setRawMode(false);
+        stdin.pause();
+        stdout.write("\n");
+        resolve(buffer);
+        return;
+      }
+      if (ch === "\u0003") {
+        // Ctrl-C
+        stdin.removeListener("data", onData);
+        if (!wasRaw) stdin.setRawMode(false);
+        stdout.write("\n");
+        process.exit(130);
+      }
+      if (ch === "\u007f" || ch === "\b") {
+        // Backspace / DEL
+        if (buffer.length > 0) {
+          buffer = buffer.slice(0, -1);
+          stdout.write("\b \b");
+        }
+        return;
+      }
+      // Handle paste or multi-byte chunks by iterating characters.
+      for (const c of ch) {
+        if (c === "\r" || c === "\n") continue;
+        buffer += c;
+        stdout.write("*");
+      }
+    };
+
+    stdin.on("data", onData);
+  });
+}
+
+async function confirm(question, defaultYes = true) {
+  // The capitalised letter in the hint is the default marker; don't pass the
+  // default to ask() or it would redundantly render "(default: y)" as well.
+  const hint = defaultYes ? "Y/n" : "y/N";
+  const raw = await ask(`${question} (${hint})`);
+  const ans = (raw || (defaultYes ? "y" : "n")).toLowerCase();
+  return ans === "y" || ans === "yes";
+}
+
+/** True when there is no interactive terminal to read input from. */
+function isNonInteractive() {
+  return !process.stdin.isTTY;
+}
+
+module.exports = { ask, askHidden, confirm, formatPrompt, isNonInteractive };

package/src/lib/resolveContext.js

@@ -0,0 +1,108 @@
+/**
+ * Resolve the Niro "context" for a working directory: inspect the local git
+ * repo, then ask the server which Niro project(s) map to that git URL/branch.
+ *
+ * This is shared plumbing for the agent commands (info/init/edit/build/remove).
+ * It reuses src/lib/git.js for repo inspection (which walks up to the git root)
+ * and src/lib/api.js for the server call. The server owns URL normalization, so
+ * the raw origin URL is sent as-is — we never normalize it client-side.
+ *
+ * Returned shape:
+ *   {
+ *     gitRoot: string|null,   // repo root, or null when not a git repo
+ *     repoUrl: string|null,   // origin URL, or null when no origin
+ *     branch:  string|null,   // current branch, or null on detached HEAD
+ *     state:   string,        // one of: "not_a_git_repo" | "no_origin" |
+ *                             //         "resolved" | "unresolved" | "error"
+ *     projects: [{ project_id, alias, source_type, git_id }]
+ *   }
+ *
+ * source_type is the matched repo's registration kind (REMOTE_GIT / LOCAL_PATH /
+ * AGENT_UPLOAD) when the server supplies it, else null. Agents use it to warn on
+ * remote-git projects (which auto-build only on commits).
+ *
+ * git_id is the specific repo (gitId) the server matched this folder's git
+ * url+branch to within the project, else null. Lets per-repo commands target the
+ * folder's repo on a multi-repo project without prompting (null on an alias match).
+ *
+ * Never logs secrets. Resolution failures degrade gracefully (state: "error")
+ * rather than throwing, so callers/agents can branch on `state`.
+ */
+const git = require("./git");
+const api = require("./api");
+
+async function resolveContext(startPath = process.cwd(), opts = {}) {
+  const { repoRoot, originUrl, branch } = git.inspect(startPath);
+
+  if (!repoRoot) {
+    return { gitRoot: null, repoUrl: null, branch: null, state: "not_a_git_repo", projects: [] };
+  }
+
+  if (!originUrl) {
+    return { gitRoot: repoRoot, repoUrl: null, branch: branch || null, state: "no_origin", projects: [] };
+  }
+
+  // Omit branch when null (detached HEAD) -> URL-only resolve. Do NOT normalize
+  // the URL here; the server does.
+  const query = { git_url: originUrl };
+  if (branch) query.branch = branch;
+
+  let data;
+  try {
+    data = await api.get("/api/projects/resolve", { query, apiUrl: opts.apiUrl });
+  } catch (err) {
+    return {
+      gitRoot: repoRoot,
+      repoUrl: originUrl,
+      branch: branch || null,
+      state: "error",
+      projects: [],
+      error: err && err.message ? err.message : String(err),
+    };
+  }
+
+  const projects = normalizeProjects(data);
+  return {
+    gitRoot: repoRoot,
+    repoUrl: originUrl,
+    branch: branch || null,
+    state: projects.length ? "resolved" : "unresolved",
+    projects,
+  };
+}
+
+/**
+ * Normalize the server payload into [{ project_id, alias, source_type, git_id }].
+ * Accepts a few shapes defensively: an array of projects, or an object with a
+ * `projects` array, or a single project object. source_type is the matched repo's
+ * registration kind (e.g. REMOTE_GIT), or null when the server doesn't supply it.
+ * git_id is the matched repo's gitId for this folder, or null when not supplied.
+ */
+function normalizeProjects(data) {
+  if (!data) return [];
+  let list = data;
+  if (!Array.isArray(data)) {
+    if (Array.isArray(data.projects)) list = data.projects;
+    else if (data.project_id || data.projectId || data.id) list = [data];
+    else return [];
+  }
+  return list
+    .map((p) => {
+      if (!p || typeof p !== "object") return null;
+      const projectId = p.project_id || p.projectId || p.id || null;
+      if (!projectId) return null;
+      const alias = p.alias || p.name || null;
+      const sourceType = p.source_type || p.sourceType || null;
+      const gitId = p.git_id || p.gitId || null;
+      // Identity = url+branch (ADR-017): the matched repo's INDEXED branch, and whether the caller is
+      // ON it. Default branch_match=true when a server predates this field, so old servers never nag.
+      const indexedBranch = p.branch || p.indexedBranch || null;
+      const rawMatch = p.branch_match !== undefined ? p.branch_match : p.branchMatch;
+      const branchMatch = rawMatch === undefined ? true : !!rawMatch;
+      return { project_id: projectId, alias, source_type: sourceType, git_id: gitId,
+               indexed_branch: indexedBranch, branch_match: branchMatch };
+    })
+    .filter(Boolean);
+}
+
+module.exports = { resolveContext, normalizeProjects };

package/src/lib/secret.js

@@ -0,0 +1,114 @@
+/**
+ * Helpers to keep secret values out of any --json or log output.
+ *
+ * The agent commands emit machine-readable JSON; this module makes sure env-var
+ * VALUES, API keys, tokens and passwords are masked or omitted before printing.
+ * Nothing here ever prints — it only transforms data the caller is about to emit.
+ */
+
+// Field-name patterns that indicate a secret. Matched case-insensitively against
+// object keys when stripping. Kept deliberately broad: env var values, tokens,
+// keys, passwords, secrets, credentials.
+const SECRET_KEY_PATTERN =
+  /(secret|password|passwd|pwd|token|api[_-]?key|apikey|access[_-]?key|private[_-]?key|credential|authorization|auth[_-]?token|bearer|jwt|client[_-]?secret)/i;
+
+/**
+ * Mask a single secret value so its presence is visible but the value is not.
+ * - null/undefined -> returned as-is (nothing to leak).
+ * - empty string   -> "" (nothing to leak).
+ * - short values   -> fully masked.
+ * - longer values  -> keep last 4 chars for correlation, mask the rest.
+ */
+function maskSecret(value) {
+  if (value === null || value === undefined) return value;
+  const s = String(value);
+  if (s.length === 0) return s;
+  // Only reveal the last 4 chars for clearly-long tokens; short secrets (which include
+  // many API keys) are fully masked so we never leak a meaningful fraction.
+  if (s.length < 16) return "****";
+  return "****" + s.slice(-4);
+}
+
+// A VALUE that embeds credentials regardless of its key name: a connection
+// string / URL with userinfo (scheme://user[:pass]@host — covers DATABASE_URL,
+// MONGODB_URI, REDIS_URL, SENTRY_DSN, spring.datasource.url, ...), or a PEM
+// private-key/cert block. The `@` must precede the first `/`, so an `@` in a URL
+// path does not trigger, and a plain URL with no userinfo (a behavioural base
+// URL the user WANTS to see) is not matched.
+const SECRET_VALUE_URLINFO = /:\/\/[^\s/@]+@/;
+
+/**
+ * True when a VALUE looks like it carries a secret even if its key name doesn't
+ * (a credential-bearing connection string, or a PEM key block). Used to decide
+ * masking of env-var values so a password embedded in DATABASE_URL never prints.
+ */
+function looksSecretValue(value) {
+  if (value === null || value === undefined) return false;
+  const s = String(value);
+  if (!s) return false;
+  if (SECRET_VALUE_URLINFO.test(s)) return true;
+  if (s.includes("-----BEGIN ")) return true; // PEM private key / certificate
+  return false;
+}
+
+/** Key names that denote an env-var COLLECTION (name -> value map) whose VALUES are secret. */
+const ENV_COLLECTION_PATTERN = /^(env|envs|env_vars|environment|variables|vars)$/i;
+
+/** True if a key name looks like it holds a secret. */
+function isSecretKey(key) {
+  return typeof key === "string" && SECRET_KEY_PATTERN.test(key);
+}
+
+/** True if a key names an env-var collection whose member values must all be masked. */
+function isEnvCollectionKey(key) {
+  return typeof key === "string" && ENV_COLLECTION_PATTERN.test(key);
+}
+
+/**
+ * Return a deep copy of `obj` with any secret-looking field masked. Use this
+ * before printing an object (e.g. as JSON) so values like api_key or env-var
+ * values never reach stdout/logs in plaintext.
+ *
+ * - Recurses into nested objects and arrays.
+ * - By default secret fields are masked (value replaced with a redacted form).
+ * - Pass { omit: true } to drop secret fields entirely instead of masking.
+ * - Env-var collections (objects of name -> value) are handled too: when the
+ *   key itself isn't obviously a secret but the surrounding key marks an env
+ *   map, callers should pass maskValues:true to mask every value.
+ */
+function stripSecrets(obj, opts = {}) {
+  const { omit = false, maskValues = false } = opts;
+  return _strip(obj, omit, maskValues);
+}
+
+function _strip(value, omit, maskValues) {
+  if (Array.isArray(value)) {
+    return value.map((v) => _strip(v, omit, maskValues));
+  }
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      if (isSecretKey(k)) {
+        if (omit) continue;
+        out[k] = v && typeof v === "object" ? _strip(v, omit, maskValues) : maskSecret(v);
+        continue;
+      }
+      // An env-var collection (e.g. env_vars: {DATABASE_URL: "postgres://u:p@h/db"}): the key
+      // names aren't secret-looking but every VALUE is. Force value-masking for this subtree so
+      // callers can't forget — a connection string with an embedded password won't leak by default.
+      if (isEnvCollectionKey(k) && v && typeof v === "object") {
+        out[k] = _strip(v, omit, true);
+        continue;
+      }
+      if (maskValues && (v === null || typeof v !== "object")) {
+        out[k] = maskSecret(v);
+        continue;
+      }
+      out[k] = _strip(v, omit, maskValues);
+    }
+    return out;
+  }
+  return value;
+}
+
+module.exports = { maskSecret, isSecretKey, looksSecretValue, stripSecrets };