@niroai/niro 0.3.0

package/src/lib/folderSync.js

@@ -0,0 +1,503 @@
+/**
+ * Shared folder-upload helpers for the AGENT_UPLOAD onboarding/sync path.
+ *
+ * This is the single source of truth for:
+ *   - the source-file walk (SOURCE_EXTENSIONS + IGNORED_DIRS) used to build a
+ *     manifest of files to offer the server's /filter endpoint;
+ *   - the concurrent, resilient initial uploader (doInitialSync).
+ *
+ * `niro init`, `niro add repo`, and `niro watch` all import from here so there
+ * is exactly one walk definition and one uploader. File content is never logged.
+ *
+ * .gitignore IS honored: after the walk, when the folder is a git work tree, the
+ * candidate paths are batched through `git check-ignore --stdin` and any ignored
+ * path is dropped. This keeps gitignored secret files (raw .env, .env.local,
+ * .env.production) out of the upload and matches REMOTE_GIT, which never sees
+ * gitignored files. (This intentionally REVERSES the ADR-011 Phase-1 "do NOT
+ * honor .gitignore" decision — for secret safety.) Non-git folders and any git
+ * failure degrade gracefully to NO filtering. The IGNORED_DIRS set stays as a
+ * baseline so the walk never descends into node_modules/.git/etc.
+ *
+ * Tunables (env overrides, all optional):
+ *   NIRO_UPLOAD_CONCURRENCY      max batches uploaded in parallel (default 4)
+ *   NIRO_UPLOAD_TIMEOUT_MS       per-batch upload timeout (default 60000; lives in agentApi)
+ *   NIRO_UPLOAD_MAX_TOTAL_BYTES  aggregate-guard byte threshold (default 1 GiB)
+ *   NIRO_UPLOAD_MAX_FILES        aggregate-guard file-count threshold (default 50000)
+ *   NIRO_UPLOAD_BACKOFF_BASE_MS  retry backoff base (default 500 -> 500/1000/2000)
+ */
+const fs = require("fs");
+const path = require("path");
+const git = require("./git");
+const agentApi = require("./agentApi");
+const watchState = require("./watchState");
+const prompt = require("./prompt");
+const color = require("./color");
+
+const BATCH_SIZE = 50;
+const SOURCE_EXTENSIONS = new Set([
+  ".java", ".py", ".go", ".js", ".ts", ".tsx", ".jsx",
+  ".kt", ".scala", ".rs", ".rb", ".php", ".cs", ".swift",
+  ".c", ".cpp", ".h", ".hpp", ".dart",
+]);
+
+// Build/config files the server's project-structure resolver needs to detect
+// projects and resolve source roots, aliases and exports (package.json, pom.xml,
+// go.mod, ...). Without these the server finds zero project indicators and falls
+// back to a degraded bare-root index. Source files alone are NOT enough.
+//
+// MUST stay byte-identical to ai-orchestrator
+// SourceFileFilterService.STRUCTURAL_FILENAMES / STRUCTURAL_EXTENSIONS — derived
+// from the ai-orchestrator ConfigFileParser SUPPORTED_FILES sets + the route
+// detectors. The server's /filter is the authoritative gate; the CLI only OFFERS
+// these, so it must offer a superset or the server never sees the file. Names are
+// stored lowercased because we match against entry.name.toLowerCase() (case-
+// insensitive + symmetric with the server, which also lowercases the filename).
+// Lockfiles (package-lock.json, go.sum, Cargo.lock, Gemfile.lock) are deliberately
+// excluded — no parser reads them. Env/property files (.env, application.yml) are
+// deliberately excluded — they routinely hold secrets.
+const STRUCTURAL_FILENAMES = new Set([
+  "package.json", "tsconfig.json", "jsconfig.json", "pom.xml",
+  "build.gradle", "build.gradle.kts", "settings.gradle", "settings.gradle.kts",
+  "go.mod", "go.work", "setup.py", "pyproject.toml", "requirements.txt",
+  "pipfile", "cargo.toml", "composer.json", "gemfile", "project.clj",
+  "deps.edn", "package.swift", "build.sbt", "build.properties", "plugins.sbt",
+  "stack.yaml", "package.yaml", "setup.hs", "rebar.config", "erlang.mk",
+  "rebar.config.script", "mix.exs", "cmakelists.txt", "cmakecache.txt",
+  "makefile", "gnumakefile", "pubspec.yaml", "pubspec.yml", "dune-project",
+  "shard.yml", "project.toml", "manifest.toml", "description", "namespace",
+  "makefile.pl", "build.pl", "cpanfile", "build.zig", "build.zig.zon",
+  "project.json", "directory.build.props", "next.config.js", "next.config.mjs",
+  "next.config.ts", "vite.config.ts", "vite.config.js", "setupproxy.js",
+  "setupproxy.ts",
+]);
+const STRUCTURAL_EXTENSIONS = new Set([
+  ".csproj", ".fsproj", ".sln", ".gemspec", ".rockspec", ".nimble", ".opam",
+]);
+
+// COMMITTED config/property + .env TEMPLATE files. These are version-controlled
+// (REMOTE_GIT already reads them) and hold the env-var DEFAULT values that
+// PropertyFileService/EnvVarScanService read on the server. Without them the
+// discovered env vars come back with empty defaults. SECRET-bearing files
+// (raw .env, .env.local, .env.production, arbitrary *.properties) are NOT here
+// and never match isConfigName(); gitignored instances of even these committed
+// names are dropped earlier by the .gitignore honor pass (filterIgnored).
+//
+// Names are lowercased (we match entry.name.toLowerCase()). The Spring
+// profile family application-<profile>.{properties,yml,yaml} is matched by the
+// wildcard rule in isConfigName(), not enumerated. Dockerfile / docker-compose.*
+// are scanned for ARG/ENV defaults (EnvVarScanService.INFRA_FILENAMES).
+//
+// MUST stay byte-identical (lists + isConfigName logic) to ai-orchestrator
+// SourceFileFilterService.CONFIG_FILENAMES / isConfigName.
+const CONFIG_FILENAMES = new Set([
+  "application.properties", "application.yml", "application.yaml",
+  "config.properties", "config.yml", "config.yaml",
+  "settings.properties", "settings.yml", "settings.yaml",
+  "config.json", "settings.json",
+  ".env.example", ".env.sample", ".env.template", ".env.dist",
+  "application.properties.example", "application.properties.sample",
+  "application.yml.example", "application.yml.sample",
+  "application.yaml.example", "application.yaml.sample",
+  "dockerfile", "docker-compose.yml", "docker-compose.yaml",
+]);
+
+const CONFIG_WILDCARD_SUFFIXES = [".properties", ".yml", ".yaml"];
+
+// True for committed config/property/template files that carry env-var DEFAULTS,
+// false for secret-bearing files (bare .env, .env.local, .env.production, and
+// arbitrary *.properties). `lower` is the already-lowercased filename.
+function isConfigName(lower) {
+  if (CONFIG_FILENAMES.has(lower)) return true;
+  // Spring profile files: application-<profile>.{properties,yml,yaml}, profile
+  // non-empty (reject "application-.properties").
+  const prefix = "application-";
+  if (lower.startsWith(prefix)) {
+    for (const suffix of CONFIG_WILDCARD_SUFFIXES) {
+      if (lower.endsWith(suffix) && lower.length > prefix.length + suffix.length) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+const IGNORED_DIRS = new Set([
+  "node_modules", ".git", "target", "build", "__pycache__",
+  "dist", ".venv", "vendor", ".idea", ".gradle", "out",
+]);
+
+// Server-side per-file cap (256 KiB). Oversize files are skipped server-side at
+// /filter; we surface them as a warning so missing source is never silent.
+const PER_FILE_CAP_BYTES = 262144;
+
+const DEFAULT_CONCURRENCY = 4;
+const DEFAULT_MAX_TOTAL_BYTES = 1024 * 1024 * 1024; // 1 GiB
+const DEFAULT_MAX_FILES = 50000;
+const MAX_ATTEMPTS = 3;
+
+function positiveIntEnv(name, fallback) {
+  const v = Number.parseInt(process.env[name], 10);
+  return Number.isFinite(v) && v > 0 ? v : fallback;
+}
+
+function uploadConcurrency() {
+  return positiveIntEnv("NIRO_UPLOAD_CONCURRENCY", DEFAULT_CONCURRENCY);
+}
+function maxTotalBytes() {
+  return positiveIntEnv("NIRO_UPLOAD_MAX_TOTAL_BYTES", DEFAULT_MAX_TOTAL_BYTES);
+}
+function maxFiles() {
+  return positiveIntEnv("NIRO_UPLOAD_MAX_FILES", DEFAULT_MAX_FILES);
+}
+function backoffMs(attempt) {
+  // base may legitimately be 0 in tests (instant retry), so accept >= 0.
+  const raw = Number.parseInt(process.env.NIRO_UPLOAD_BACKOFF_BASE_MS, 10);
+  const base = Number.isFinite(raw) && raw >= 0 ? raw : 500;
+  return base * Math.pow(2, attempt - 1); // 500, 1000, 2000
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Walk a directory and build a manifest of source/structural/config files,
+ * then honor VCS exclusions: when rootDir lives in a git work tree, drop any
+ * candidate that git ignores. Pass { honorGitignore: false } to skip the git
+ * pass (used by tests that assert the raw walk).
+ */
+function buildManifest(rootDir, opts = {}) {
+  const manifest = [];
+  walkDir(rootDir, rootDir, manifest);
+  if (opts.honorGitignore === false) return manifest;
+  return filterIgnored(rootDir, manifest);
+}
+
+// A manifest entry whose basename could carry secrets: any committed config name
+// (isConfigName), any .env* file, or any *.properties/*.yml/*.yaml. Used ONLY for
+// the fail-CLOSED path: when .gitignore cannot be honored on a git work tree we
+// drop these (we cannot prove they are not gitignored) but keep ordinary source.
+// `relPath` is a manifest/relative path; we match on its lowercased basename.
+function isSecretRiskCandidate(relPath) {
+  const lower = path.basename(relPath).toLowerCase();
+  if (isConfigName(lower)) return true;
+  if (lower.startsWith(".env")) return true; // .env, .env.local, .env.production, ...
+  for (const suffix of CONFIG_WILDCARD_SUFFIXES) {
+    if (lower.endsWith(suffix)) return true; // *.properties / *.yml / *.yaml
+  }
+  return false;
+}
+
+// The single accept predicate: is this filename eligible for upload at all?
+// SOURCE code, structural build files, or a committed config file. The manifest
+// walk and the watch per-file event share it so they never diverge on what may
+// be uploaded (a changed file outside this set is ignored, even if the server's
+// include patterns are empty). `name` is a basename or relative path.
+function isUploadableName(name) {
+  const lower = path.basename(name).toLowerCase();
+  const ext = path.extname(lower);
+  return (
+    SOURCE_EXTENSIONS.has(ext) ||
+    STRUCTURAL_EXTENSIONS.has(ext) ||
+    STRUCTURAL_FILENAMES.has(lower) ||
+    isConfigName(lower)
+  );
+}
+
+/**
+ * Given paths relative to rootDir, return the Set of paths that must be DROPPED
+ * before upload to honor .gitignore. This is the SINGLE source of truth shared by
+ * the init/add-repo manifest filter AND the watch daemon (delta + per-file), so
+ * the secret-safety rules are identical on every upload path.
+ *
+ * rootDir may be a SUBDIRECTORY of the work tree, so paths are re-expressed
+ * relative to the repo root before the single `git check-ignore --stdin` call.
+ *
+ *   - Non-git folder (no work tree)      -> drop nothing (nothing to honor).
+ *   - git answered                       -> drop exactly the gitignored paths.
+ *   - git could NOT answer on a work tree-> FAIL LOUD + CLOSED-for-config: print a
+ *     one-line WARNING and drop every secret-risk candidate (config/env/property)
+ *     so a possibly-gitignored secret file is never uploaded unverified. Ordinary
+ *     SOURCE files are kept (not the secret risk). File names are never logged.
+ */
+function gitignoreDrops(rootDir, relPaths) {
+  const drop = new Set();
+  if (!relPaths || relPaths.length === 0) return drop;
+
+  let repoRoot = null;
+  try {
+    repoRoot = git.inspect(rootDir).repoRoot;
+  } catch {
+    repoRoot = null;
+  }
+  if (!repoRoot) return drop; // not a work tree -> nothing to honor
+
+  // git check-ignore matches against repo-root-relative POSIX paths.
+  const repoRelByPath = new Map();
+  const repoRelPaths = [];
+  for (const rel of relPaths) {
+    const abs = path.join(rootDir, rel);
+    const repoRel = path.relative(repoRoot, abs).split(path.sep).join("/");
+    repoRelByPath.set(rel, repoRel);
+    repoRelPaths.push(repoRel);
+  }
+
+  const { ok, ignored } = git.checkIgnored(repoRoot, repoRelPaths);
+  if (!ok) {
+    console.log(color.yellow(
+      "  ⚠ WARNING: could not run `git check-ignore`, so .gitignore can't be " +
+      "honored — dropping config/env files from this upload to avoid leaking " +
+      "secrets (source files are still uploaded)."
+    ));
+    for (const rel of relPaths) {
+      if (isSecretRiskCandidate(rel)) drop.add(rel);
+    }
+    return drop;
+  }
+  if (ignored.size === 0) return drop;
+  for (const rel of relPaths) {
+    if (ignored.has(repoRelByPath.get(rel))) drop.add(rel);
+  }
+  return drop;
+}
+
+/**
+ * Drop manifest entries that git ignores (or, on a fail-closed git error, the
+ * secret-risk config/env entries). Thin wrapper over gitignoreDrops so the
+ * manifest walk and the watch daemon share one ignore policy.
+ */
+function filterIgnored(rootDir, manifest) {
+  if (!manifest || manifest.length === 0) return manifest;
+  const drops = gitignoreDrops(rootDir, manifest.map((m) => m.path));
+  if (drops.size === 0) return manifest;
+  return manifest.filter((m) => !drops.has(m.path));
+}
+
+function walkDir(rootDir, currentDir, manifest) {
+  let entries;
+  try {
+    entries = fs.readdirSync(currentDir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      if (!IGNORED_DIRS.has(entry.name) && !entry.name.startsWith(".")) {
+        walkDir(rootDir, path.join(currentDir, entry.name), manifest);
+      }
+    } else if (entry.isFile()) {
+      if (isUploadableName(entry.name)) {
+        const absPath = path.join(currentDir, entry.name);
+        let sizeBytes = 0;
+        try {
+          sizeBytes = fs.statSync(absPath).size;
+        } catch {
+          // skip
+        }
+        manifest.push({
+          path: path.relative(rootDir, absPath).replace(/\\/g, "/"),
+          size_bytes: sizeBytes,
+          mime_type: "text/plain",
+        });
+      }
+    }
+  }
+}
+
+function chunk(arr, size) {
+  const result = [];
+  for (let i = 0; i < arr.length; i += size) {
+    result.push(arr.slice(i, i + size));
+  }
+  return result;
+}
+
+function formatBytes(n) {
+  if (n >= 1024 * 1024 * 1024) return `${(n / (1024 * 1024 * 1024)).toFixed(2)} GiB`;
+  if (n >= 1024 * 1024) return `${(n / (1024 * 1024)).toFixed(1)} MiB`;
+  if (n >= 1024) return `${(n / 1024).toFixed(1)} KiB`;
+  return `${n} B`;
+}
+
+/**
+ * Guard against an accidental enormous upload (a misconfigured walk, a giant
+ * monorepo, a binary directory mislabelled as source). On an interactive TTY we
+ * ask the user to confirm; non-interactively we proceed but print a clear
+ * WARNING (never silently). Throws "Upload cancelled by user." if declined.
+ */
+async function aggregateGuard(targetDir, includedPaths, sizes) {
+  const count = includedPaths.length;
+  const overFiles = count > maxFiles();
+
+  // Sum sizes to test the byte threshold, but bound the work: prefer sizes the
+  // manifest already computed (no re-stat), and stop summing as soon as we pass
+  // the limit. When we are already over the file-count limit we still need a
+  // byte figure for the message, so keep the early-exit either way.
+  const limitBytes = maxTotalBytes();
+  let totalBytes = 0;
+  let overBytes = false;
+  for (const relativePath of includedPaths) {
+    let sz = sizes && typeof sizes[relativePath] === "number" ? sizes[relativePath] : null;
+    if (sz == null) {
+      try {
+        sz = fs.statSync(path.join(targetDir, relativePath)).size;
+      } catch {
+        sz = 0; // unreadable — ignore for the estimate
+      }
+    }
+    totalBytes += sz;
+    if (totalBytes > limitBytes) {
+      overBytes = true;
+      break; // no need to keep summing once over
+    }
+  }
+  if (!overBytes && !overFiles) return;
+
+  const reasons = [];
+  if (overBytes) reasons.push(`> ${formatBytes(limitBytes)}`);
+  if (overFiles) reasons.push(`${count} files (limit ${maxFiles()})`);
+  const msg = `Large upload — ${reasons.join("; ")}.`;
+
+  if (prompt.isNonInteractive()) {
+    console.log(color.yellow(`  ⚠ WARNING: ${msg} Proceeding (non-interactive).`));
+    return;
+  }
+  const proceed = await prompt.confirm(`  ⚠ ${msg} Continue?`, false);
+  if (!proceed) {
+    throw new Error("Upload cancelled by user.");
+  }
+}
+
+/**
+ * Upload a single batch with retry + exponential backoff. Each attempt is
+ * subject to agentApi.uploadFileBatch's own per-call timeout (a timeout aborts
+ * the attempt and surfaces as a thrown error, which counts as a failed attempt
+ * here). Throws the last error after MAX_ATTEMPTS.
+ */
+async function uploadBatchWithRetry(gitId, sessionId, fileBatch) {
+  let lastErr;
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+    try {
+      return await agentApi.uploadFileBatch(gitId, sessionId, fileBatch);
+    } catch (err) {
+      lastErr = err;
+      if (attempt < MAX_ATTEMPTS) {
+        await sleep(backoffMs(attempt));
+      }
+    }
+  }
+  throw lastErr;
+}
+
+/**
+ * Initial sync: upload all included files to one server sync session using a
+ * bounded concurrency pool. Concurrent batches to the SAME session are safe —
+ * each batch writes independent files into a per-session staging dir, and
+ * completeSync atomically moves staging -> projectDir.
+ *
+ * Resilience: each batch is retried up to MAX_ATTEMPTS with exponential
+ * backoff and a per-attempt timeout. If any batch exhausts its retries, we do
+ * NOT call completeSync (the half-uploaded session is discarded server-side) and
+ * we throw loudly. There is no cross-process resume: re-running starts a fresh
+ * upload from scratch.
+ *
+ * On success, fileHashes + lastSyncedAt are recorded via watchState.update.
+ */
+async function doInitialSync(gitId, targetDir, includedPaths, { sizes } = {}) {
+  if (!includedPaths || includedPaths.length === 0) {
+    console.log(`  ${color.yellow("No files to sync.")} Check your include/exclude patterns.`);
+    return;
+  }
+
+  await aggregateGuard(targetDir, includedPaths, sizes);
+
+  const total = includedPaths.length;
+  console.log(`\n  Starting initial sync (${total} files)...`);
+  const sessionId = await agentApi.startSync(gitId);
+
+  const batches = chunk(includedPaths, BATCH_SIZE);
+  let uploaded = 0; // single-threaded event loop -> safe counter across batches
+  let dropped = 0; // files that vanished between manifest build and upload
+  let firstError = null;
+  let nextBatch = 0;
+
+  async function worker() {
+    while (true) {
+      if (firstError) return;
+      const idx = nextBatch++;
+      if (idx >= batches.length) return;
+      const fileBatch = batches[idx]
+        .map((relativePath) => ({
+          relativePath,
+          absolutePath: path.join(targetDir, relativePath),
+        }))
+        .filter((f) => fs.existsSync(f.absolutePath));
+      dropped += batches[idx].length - fileBatch.length;
+
+      try {
+        if (fileBatch.length > 0) await uploadBatchWithRetry(gitId, sessionId, fileBatch);
+      } catch (err) {
+        if (!firstError) firstError = err;
+        return;
+      }
+      uploaded += fileBatch.length;
+      // Denominator excludes files that disappeared, so progress can still reach 100%.
+      const pct = Math.round((uploaded / Math.max(1, total - dropped)) * 100);
+      process.stdout.write(`\r  Uploading... ${pct}% (${uploaded}/${total - dropped})`);
+    }
+  }
+
+  const poolSize = Math.min(uploadConcurrency(), batches.length);
+  const workers = [];
+  for (let i = 0; i < poolSize; i++) workers.push(worker());
+  await Promise.all(workers);
+  process.stdout.write("\n");
+
+  // Never drop files silently — surface the count (no names/content).
+  if (!firstError && dropped > 0) {
+    console.log(color.yellow(`  ⚠ ${dropped} file(s) disappeared during upload and were skipped.`));
+  }
+
+  if (firstError) {
+    // Do NOT completeSync — leave the partial session for the server to discard.
+    throw new Error(
+      `Upload did not complete: ${firstError.message}. ` +
+        "Re-run `niro init` to restart it — the upload starts from scratch " +
+        "(there is no cross-process resume)."
+    );
+  }
+
+  await agentApi.completeSync(gitId, sessionId);
+
+  // Record hashes so the watch daemon can delta-sync from here.
+  const hashes = {};
+  for (const relativePath of includedPaths) {
+    const h = watchState.hashFile(path.join(targetDir, relativePath));
+    if (h) hashes[relativePath] = h;
+  }
+  watchState.update(targetDir, { fileHashes: hashes, lastSyncedAt: new Date().toISOString() });
+
+  console.log(`  ${color.green("✓")} Initial sync complete.`);
+  // Return the computed hashes so a caller that registers its watchState entry AFTER the upload (takeover)
+  // can seed fileHashes directly — watchState.update above no-ops when no entry exists yet, so without this
+  // the daemon would re-upload the whole tree on its first pass.
+  return hashes;
+}
+
+module.exports = {
+  buildManifest,
+  walkDir,
+  filterIgnored,
+  gitignoreDrops,
+  isSecretRiskCandidate,
+  isUploadableName,
+  isConfigName,
+  chunk,
+  doInitialSync,
+  aggregateGuard,
+  SOURCE_EXTENSIONS,
+  STRUCTURAL_FILENAMES,
+  STRUCTURAL_EXTENSIONS,
+  CONFIG_FILENAMES,
+  IGNORED_DIRS,
+  BATCH_SIZE,
+  PER_FILE_CAP_BYTES,
+};

package/src/lib/git.js

@@ -0,0 +1,190 @@
+/**
+ * Best-effort read of local .git metadata — origin URL and current branch.
+ * Returns null for either field when not available (no git, detached HEAD, etc.).
+ * Walks up from the given path to find a .git directory.
+ */
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+
+function findGitDir(startDir) {
+  let dir = path.resolve(startDir);
+  const root = path.parse(dir).root;
+  while (true) {
+    const candidate = path.join(dir, ".git");
+    try {
+      if (fs.existsSync(candidate)) return { gitDir: candidate, repoRoot: dir };
+    } catch {
+      // ignore
+    }
+    if (dir === root) return null;
+    dir = path.dirname(dir);
+  }
+}
+
+function readOriginUrl(gitDir) {
+  try {
+    const configPath = path.join(gitDir, "config");
+    const raw = fs.readFileSync(configPath, "utf8");
+    // Match [remote "origin"] ... url = ...
+    const match = raw.match(/\[remote "origin"\][^[]*?url\s*=\s*(\S+)/);
+    return match ? match[1].trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+function readCurrentBranch(gitDir) {
+  try {
+    const head = fs.readFileSync(path.join(gitDir, "HEAD"), "utf8").trim();
+    const m = head.match(/^ref:\s*refs\/heads\/(.+)$/);
+    return m ? m[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Run a git command in `cwd` and return trimmed stdout, or null on ANY failure
+ * (git absent, not a repo, no `origin` remote, detached HEAD, timeout). Never
+ * throws; stderr is discarded. Bounded so a wedged git can't hang onboarding.
+ */
+function gitOut(cmd, cwd) {
+  try {
+    const out = execSync(cmd, {
+      cwd,
+      encoding: "utf8",
+      timeout: 3000,
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    return out || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Strip embedded credentials from an https remote (https://user:token@host/... -> https://host/...)
+ * and token query params (?token=..., ?access_token=...) before it is stored, logged, or sent. Leaves
+ * scp/ssh form (git@host:org/repo) untouched — the "git@" there is the ssh user, not a secret (the
+ * regex requires "//" before the "@"). Mirrors the @niroai/mcp-server bridge's redactRemoteCreds
+ * (lib/redact.js) so onboarding never persists a token-bearing repository_url, and keeps resolution
+ * consistent (the server matches on the redacted host/org/repo form the bridge also sends).
+ */
+function redactRemoteCreds(url) {
+  if (typeof url !== "string") return url;
+  return url
+    .replace(/\/\/[^@/]*@/, "//")
+    .replace(/([?&](?:access_token|token|api_key|private[-_]?token)=)[^&\s]+/gi, "$1***");
+}
+
+function inspect(startDir) {
+  const found = findGitDir(startDir);
+  if (!found) return { repoRoot: null, originUrl: null, branch: null };
+  let originUrl = redactRemoteCreds(readOriginUrl(found.gitDir));
+  let branch = readCurrentBranch(found.gitDir);
+  // The reads above open `.git/config` and `.git/HEAD` as plain files. That works when
+  // `.git` is a DIRECTORY, but a git WORKTREE or SUBMODULE checkout has `.git` as a FILE
+  // (`gitdir: <path>`), so those reads hit ENOTDIR and return null — and onboarding would
+  // then store a synthetic `local://<name>` URL that the MCP git-remote resolver can never
+  // match (the exact cause of the "no project matched" onboarding→MCP break). Fall back to
+  // the git binary (the same detection the MCP bridge already uses in src/mcp/server.js) so
+  // a worktree checkout still records its real origin/branch. Best-effort: if git is
+  // unavailable the calls return null and behaviour is identical to before.
+  if (originUrl === null) originUrl = redactRemoteCreds(gitOut("git remote get-url origin", found.repoRoot));
+  if (branch === null) {
+    const b = gitOut("git rev-parse --abbrev-ref HEAD", found.repoRoot);
+    branch = b && b !== "HEAD" ? b : null; // "HEAD" = detached; keep null like the file read
+  }
+  return { repoRoot: found.repoRoot, originUrl, branch };
+}
+
+/**
+ * Run ONE `git check-ignore --stdin` in `repoRoot` and report BOTH the matched
+ * paths AND whether the check itself succeeded. Paths must be POSIX-relative to
+ * repoRoot. Returns `{ ok, ignored }`:
+ *   - ok=true  → git ran and answered authoritatively (exit 0 with matches, or
+ *                exit 1 = no path matched). `ignored` is the matched subset.
+ *   - ok=false → git could NOT honor .gitignore (ENOENT / exit 128 / timeout /
+ *                any other error). `ignored` is empty. Callers decide how to fail
+ *                (we fail CLOSED for config files — see folderSync.gitignoreDrops).
+ *
+ * Never throws. File names are passed only via stdin and are NEVER logged;
+ * stderr is discarded.
+ *
+ * git check-ignore exit codes: 0 = at least one path matched (printed to
+ * stdout), 1 = no path matched (execSync throws; stdout empty), 128 = fatal
+ * (not a work tree / no git).
+ */
+function checkIgnored(repoRoot, relativePaths) {
+  const ignored = new Set();
+  if (!repoRoot || !Array.isArray(relativePaths) || relativePaths.length === 0) {
+    // Nothing to check — a successful, empty result.
+    return { ok: true, ignored };
+  }
+  const collect = (out) => {
+    if (typeof out !== "string") return;
+    for (const line of out.split("\n")) {
+      const p = line.trim();
+      if (p) ignored.add(p);
+    }
+  };
+  try {
+    const out = execSync("git check-ignore --stdin", {
+      cwd: repoRoot,
+      input: relativePaths.join("\n"),
+      encoding: "utf8",
+      timeout: 5000,
+      stdio: ["pipe", "pipe", "ignore"],
+      maxBuffer: 64 * 1024 * 1024,
+    });
+    collect(out);
+    return { ok: true, ignored };
+  } catch (err) {
+    // Exit 1 (no matches) is normal and execSync throws on it — the matched
+    // paths (if any) live on err.stdout. That is still an authoritative answer.
+    if (err && err.status === 1) {
+      collect(err.stdout);
+      return { ok: true, ignored };
+    }
+    // Any other status (128 / ENOENT / timeout) means git could NOT answer:
+    // report ok=false so the caller can fail closed for secret-bearing files.
+    return { ok: false, ignored: new Set() };
+  }
+}
+
+/**
+ * Backward-compatible thin wrapper: return just the matched subset as a Set.
+ * Treats a failed check (git unavailable) the same as "no matches" — callers
+ * that need the fail-closed signal should use checkIgnored() directly.
+ */
+function checkIgnoredPaths(repoRoot, relativePaths) {
+  return checkIgnored(repoRoot, relativePaths).ignored;
+}
+
+function deriveRepoName(originUrl, fallbackDir) {
+  if (originUrl) {
+    const match = originUrl.match(/([^/:]+?)(?:\.git)?$/);
+    if (match) return match[1];
+  }
+  return path.basename(path.resolve(fallbackDir));
+}
+
+/** True if `relativePath` is tracked by git in `repoRoot` (committed/staged). Used to warn before
+ *  overwriting a git-TRACKED `.niro-project` with a private temp-project id (which would then show as a
+ *  local modification and could be committed to the shared repo). Best-effort: false on any error. */
+function isTracked(repoRoot, relativePath) {
+  try {
+    execSync(`git ls-files --error-unmatch -- ${JSON.stringify(relativePath)}`, {
+      cwd: repoRoot,
+      encoding: "utf8",
+      timeout: 3000,
+      stdio: ["ignore", "ignore", "ignore"],
+    });
+    return true; // exit 0 => tracked
+  } catch {
+    return false; // non-zero => not tracked (or git unavailable)
+  }
+}
+
+module.exports = { inspect, deriveRepoName, checkIgnored, checkIgnoredPaths, redactRemoteCreds, isTracked };