@niroai/niro 0.3.0

package/src/commands/init.js

@@ -0,0 +1,1166 @@
+/**
+ * `niro init [path]` — end-to-end onboarding from a local folder.
+ *
+ * Onboards via AGENT_UPLOAD (ADR-011 Phase 1): the folder's source files are
+ * UPLOADED to the server (no workspace-root constraint, no LOCAL_PATH). The
+ * sequence mirrors `niro add repo` exactly so the two share one code path:
+ *
+ *   1. Ensure credentials (auto-login if missing).
+ *   2. Detect origin URL + branch from .git (branch may be null — detached HEAD
+ *      onboards fine).
+ *   3. Resolve a free project name (probe before any mutation).
+ *   4. Register the repo with NO project_dir → server sets sourceType=AGENT_UPLOAD
+ *      and returns a gitId. Record it in watchState BEFORE uploading (orphan-safe).
+ *      Re-run guard: if this folder already has a stored gitId, reuse it and skip
+ *      registration (but continue the rest of init — no early return).
+ *   5. Offer module-exclude suggestions, then /filter the manifest, then PUT the
+ *      include/exclude module-resolution and upload the included files
+ *      (folderSync.doInitialSync — concurrent + resilient).
+ *   6. POST /api/projects with git_id_to_mapping → project + discovered env vars.
+ *   7. Write .niro-project at the repo root so MCP tools from this repo can
+ *      resolve the project immediately — before the (potentially long) build,
+ *      so a Ctrl-C or build failure still leaves the repo pinned.
+ *   8. Prompt user values for each discovered env var; PUT /env-vars.
+ *   9. Review indexing scope per module (include/exclude globs); PUT /module-resolution.
+ *  10. Prompt auto-build on/off and quiet period; PUT /auto-sync.
+ *  11. Confirm, then POST /api/graph/{pid}/build → watch /status until terminal.
+ */
+const path = require("path");
+const fs = require("fs");
+const api = require("../lib/api");
+const agentApi = require("../lib/agentApi");
+const watchState = require("../lib/watchState");
+const { resolveContext } = require("../lib/resolveContext");
+const folderSync = require("../lib/folderSync");
+const credentials = require("../lib/credentials");
+const prompt = require("../lib/prompt");
+const git = require("../lib/git");
+const niroProjectFile = require("../lib/niroProjectFile");
+const color = require("../lib/color");
+const watchDaemon = require("../lib/watchDaemon");
+const { login } = require("./login");
+const { watchStatus } = require("./build");
+const { fetchPreview, buildCandidates } = require("./edit");
+const { resolveProjectId } = require("./_resolveProject");
+const { projectsToRows } = require("./projects");
+const { isSecretKey, looksSecretValue } = require("../lib/secret");
+
+const step = (n) => color.bold(color.cyan(n));
+const ok = (s) => color.green(s);
+const warn = (s) => color.yellow(s);
+const fail = (s) => color.red(s);
+
+async function init(pathArg, opts = {}) {
+  const targetDir = resolveTargetDir(pathArg);
+  // Validate flag values up-front so a bad --auto-build/--confirm-build/--quiet-period
+  // fails BEFORE any server-side mutation (otherwise a typo leaves an orphan project).
+  parseOnOff(opts.autoBuild);
+  parseYesNo(opts.confirmBuild);
+  parseQuietPeriod(opts.quietPeriod, 30);
+  if (!fs.existsSync(targetDir) || !fs.statSync(targetDir).isDirectory()) {
+    console.error(`Not a directory: ${targetDir}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  let creds = credentials.load();
+  if (!creds || !creds.token) {
+    console.log("Not logged in — starting login flow.");
+    await login({ apiUrl: opts.apiUrl });
+    creds = credentials.load();
+    if (!creds || !creds.token) return;
+  }
+
+  // The backend the CLI is pointed at. watchState entries (cached gitIds) are
+  // scoped to this so a backend switch never reuses a gitId from another stack.
+  const currentApiUrl = api.currentBaseUrl();
+
+  const gitInfo = git.inspect(targetDir);
+  const repoRoot = gitInfo.repoRoot || targetDir;
+  // Detached HEAD or no git → branch is null; AGENT_UPLOAD onboarding is fine
+  // with a null branch (the server defaults it).
+  const defaultBranch = gitInfo.branch || null;
+  const defaultName = git.deriveRepoName(gitInfo.originUrl, repoRoot);
+
+  // Conflicting intent: --add-to (attach to existing) and --project-name (create
+  // new) are mutually exclusive. Fail BEFORE any server-side mutation.
+  if (opts.addTo && opts.projectName) {
+    console.error(fail(
+      "Cannot use --add-to and --project-name together.\n" +
+      "  --add-to attaches this folder to an EXISTING project; --project-name creates a NEW one."
+    ));
+    process.exitCode = 1;
+    return;
+  }
+
+  // Resolve what the server already knows about this folder's git url+branch ONCE,
+  // up front — BEFORE we ask new-vs-existing — so we can lead with "already indexed"
+  // instead of blandly prompting for a folder Niro already knows. Reused by the
+  // per-target dedupe further below.
+  let ctx = { projects: [], state: "error" };
+  let resolveFailed = false;
+  try {
+    ctx = await resolveContext(targetDir, opts);
+  } catch {
+    resolveFailed = true;
+    ctx = { projects: [], state: "error" };
+  }
+  const ctxProjects = Array.isArray(ctx.projects) ? ctx.projects : [];
+
+  // If the folder HAS a git origin but resolution FAILED, the duplicate check is
+  // inconclusive — make the user (or an agent, via --force) confirm rather than proceed.
+  if (gitInfo.originUrl && (resolveFailed || ctx.state === "error")) {
+    console.log(warn(
+      `\n  ⚠ Couldn't verify whether this repo is already registered` +
+      `${ctx.error ? ` (${ctx.error})` : ""}.`
+    ));
+    if (!(await requireProceed("  Proceed without the duplicate check?", opts))) {
+      process.exitCode = 1;
+      return;
+    }
+  }
+
+  // Lead with "already indexed": if this folder's repo is already in one or more
+  // projects, say so first. Unless the user explicitly targets another project
+  // (--add-to) or opts in interactively, do NOTHING — don't ask new-vs-existing for a
+  // folder Niro already knows. (The per-target dedupe below still enforces the rules
+  // once a target is chosen.)
+  //
+  // Identity = url+branch (ADR-017): "already indexed" only counts projects whose INDEXED branch is the
+  // one you're on. A match on a DIFFERENT branch means the repo is known but YOUR branch isn't indexed —
+  // that's a `niro sandbox`, NOT "nothing to do". Split the matches on branch_match.
+  if (ctxProjects.length) {
+    const onIndexedBranch = ctxProjects.filter((p) => p.branch_match !== false);
+    const otherBranchOnly = ctxProjects.filter((p) => p.branch_match === false);
+
+    // Track this folder locally (no sandbox) so Niro's bridge/daemon KNOW it exists — that's what lets a
+    // session in a SIBLING repo of the same project enumerate this one, detect its branch, and nudge a
+    // sandbox (ADR-017 multi-repo detection). Deliberately writes NO gitId, so the watch daemon's
+    // allLocal() skips it and never streams edits to the shared source. Skips a folder that ALREADY has an
+    // entry on ANY backend (peek, not backend-scoped get): the store is path-keyed, so a backend-scoped get
+    // returns null for an entry tagged to a DIFFERENT backend, and writing would then CLOBBER that entry —
+    // destroying a takeover backup / gitId and disabling the other backend's sync (cross-backend data loss).
+    const matchedProjectId = (onIndexedBranch[0] || otherBranchOnly[0]).project_id;
+    if (matchedProjectId && !watchState.peek(repoRoot)) {
+      watchState.set(repoRoot, {
+        folderPath: repoRoot,
+        includePatterns: [], excludePatterns: [], fileHashes: {}, lastSyncedAt: null,
+        projectId: matchedProjectId,
+        branch: defaultBranch || null,
+        tracked: true, // locally-tracked for detection only; no gitId => daemon never syncs it
+      }, currentApiUrl);
+      console.log(color.dim("  Niro is now tracking this folder locally (no sandbox) so cross-repo answers can include it."));
+    }
+
+    if (onIndexedBranch.length) {
+      const where = onIndexedBranch
+        .map((p) => `"${p.alias || p.project_id}"${p.source_type ? ` (${p.source_type})` : ""}`)
+        .join(", ");
+      console.log(`\n${color.green("✓")} This folder is already indexed in: ${where}.`);
+      if (!opts.addTo) {
+        if (prompt.isNonInteractive()) {
+          console.log(color.dim(
+            "  Already indexed — nothing to do. Pass --add-to <project> to also map it elsewhere, or run 'niro build' to re-index."
+          ));
+          return;
+        }
+        if (!(await prompt.confirm("  Add it to a DIFFERENT project too?", false))) {
+          console.log(color.dim("  Nothing to do — use 'niro build' to re-index or 'niro edit' to manage it."));
+          return;
+        }
+      }
+    } 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).
+      const where = otherBranchOnly
+        .map((p) => `"${p.alias || p.project_id}"${p.indexed_branch ? ` (indexed on ${color.cyan(p.indexed_branch)})` : ""}`)
+        .join(", ");
+      const yourBranch = defaultBranch ? `\`${defaultBranch}\`` : "your current branch";
+      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)."));
+      if (!opts.addTo) {
+        if (prompt.isNonInteractive()) {
+          console.log(color.dim(
+            "  Pass --add-to <project> to map this repo into a DIFFERENT project, or run 'niro sandbox' for your branch."
+          ));
+          return;
+        }
+        if (!(await prompt.confirm("  Add this repo to a DIFFERENT project instead?", false))) {
+          return;
+        }
+      }
+    }
+  }
+
+  // Parent-folder overlap: this folder may CONTAIN repos already indexed in Niro (a
+  // monorepo root over several service repos). watchState only knows folders THIS CLI
+  // onboarded, so resolve each immediate git-repo child against the server too — this
+  // catches children indexed via the web UI / as separate repos.
+  const childScan = await scanIndexedChildren(targetDir, opts);
+  if (childScan.indexed.length) {
+    console.error(fail(`\n  This folder contains ${childScan.indexed.length} repo(s) already indexed in Niro:`));
+    for (const c of childScan.indexed) {
+      const where = c.projects.map((p) => `"${p.alias || p.project_id}"`).join(", ");
+      console.error(`      ${c.name} -> ${where}`);
+    }
+    console.error("  A parent of already-indexed repos can't be onboarded — it would upload that content again.");
+    console.error("  Onboard each repo from its own folder instead.");
+    // Hard refuse: there's no legitimate reason to upload a parent over indexed repos.
+    // --force stays as a deliberate escape hatch for scripts/agents that really mean it.
+    if (!opts.force) {
+      process.exitCode = 1;
+      return;
+    }
+    console.log(warn("  --force set — onboarding the parent anyway."));
+  }
+  if (childScan.unverified.length) {
+    console.log(warn(
+      `  ⚠ Couldn't check ${childScan.unverified.length} nested repo(s) ` +
+      `(${childScan.unverified.map((c) => c.name).join(", ")}) — they may also be indexed.`
+    ));
+  }
+  if (childScan.truncated) {
+    console.log(color.dim(`  (Stopped after the first ${CHILD_SCAN_MAX} nested repos; deeper ones weren't checked.)`));
+  }
+  const indexedChildPaths = new Set(childScan.indexed.map((c) => path.resolve(c.path)));
+
+  const target = await resolveTarget({ defaultName, opts });
+  if (!target) {
+    process.exitCode = 1;
+    return;
+  }
+  // EXISTING mode attaches the new repo's gitId to target.projectId; NEW mode
+  // POSTs /api/projects to create it. The repo register/upload steps below are
+  // identical for both — they don't depend on new-vs-existing.
+  const isExisting = target.isExisting;
+  const projectId = target.projectId;
+
+  const cliModuleExcludes = Array.isArray(opts.moduleExclude) ? opts.moduleExclude : [];
+  const cliFileExcludes = Array.isArray(opts.fileExclude) ? opts.fileExclude : [];
+
+  // Per-TARGET dedupe (ctx/ctxProjects were resolved up front, before resolveTarget,
+  // and the resolve-failed/inconclusive case was already handled there):
+  //   - SAME repo already in the TARGET project -> hard refuse (no upload, no attach).
+  //   - SAME repo in ANOTHER project as AGENT_UPLOAD -> reuse its gitId, skip upload.
+  //   - SAME repo in ANOTHER project as REMOTE_GIT -> warn + require confirmation.
+  //   - ancestor/descendant path overlap -> refuse (same project) / confirm (cross).
+
+  // b. SAME repo already in the TARGET project -> hard refuse.
+  const inTarget = ctxProjects.find((p) => p.project_id === projectId);
+  if (inTarget) {
+    console.error(fail(
+      `This repo is already in project "${projectId}"` +
+      `${inTarget.source_type ? ` (as ${inTarget.source_type})` : ""}.\n` +
+      `  Use 'niro build' to re-index or 'niro edit' to manage it.`
+    ));
+    process.exitCode = 1;
+    return;
+  }
+
+  // c. CROSS-PROJECT reuse: the same git url+branch is already registered in
+  //    ANOTHER project. Never re-create the repo — reuse its gitId.
+  let reuseGitId = null;
+  let skipUpload = false;
+  // Note: for a monorepo, resolve returns a CHILD gitId; reusing it attaches that
+  // one child (not all sibling deployables). Acceptable for the common single-repo
+  // case; cross-project reuse of a monorepo child is a known partial behaviour.
+  const crossUpload = ctxProjects.find((p) => p.source_type === "AGENT_UPLOAD" && p.git_id);
+  const crossRemote = ctxProjects.find((p) => p.source_type === "REMOTE_GIT");
+  if (crossUpload) {
+    console.log(warn(
+      `\n  ⚠ This repo is already registered in project "${crossUpload.project_id}"; ` +
+      `reusing that repo, attaching to "${projectId}" without re-uploading.`
+    ));
+    reuseGitId = crossUpload.git_id;
+    skipUpload = true;
+  } else if (crossRemote) {
+    console.log(warn(
+      `\n  ⚠ This repo is already a REMOTE repo in project "${crossRemote.project_id}"; ` +
+      `proceeding uploads a SEPARATE local copy.`
+    ));
+    if (!(await requireProceed("  Proceed and upload a separate local copy?", opts))) {
+      process.exitCode = 1;
+      return;
+    }
+  }
+
+  // d. watchState ancestor/descendant overlap (covers non-git / path-only overlap).
+  for (const o of watchState.findOverlapping(targetDir, currentApiUrl)) {
+    if (indexedChildPaths.has(path.resolve(o.path))) continue; // already surfaced by the parent-scan
+    if (o.projectId === projectId) {
+      console.error(fail(
+        `This folder overlaps "${o.path}", which is already in project "${projectId}".`
+      ));
+      process.exitCode = 1;
+      return;
+    }
+    console.log(warn(
+      `\n  ⚠ This folder overlaps "${o.path}"` +
+      `${o.projectId ? ` (in project "${o.projectId}")` : ""}.`
+    ));
+    if (!(await requireProceed("  Proceed despite the folder overlap?", opts))) {
+      process.exitCode = 1;
+      return;
+    }
+  }
+
+  // Re-run guard: if this folder already has a registered gitId, reuse it and
+  // SKIP registration — but DO NOT early-return; the rest of init still runs so
+  // a partial onboarding can be completed on a second pass.
+  //
+  // reuseGitId precedence: a cross-project AGENT_UPLOAD match (above, skipUpload=true)
+  // takes priority; otherwise the exact-folder re-run guard supplies the gitId.
+  const existing = watchState.get(targetDir, currentApiUrl);
+  let gitId = null;
+  if (reuseGitId) {
+    // Cross-project reuse of an already-onboarded repo: reuse the gitId, never
+    // re-register, and skip the upload (the server already has its files).
+    // reuseGitId came straight from resolveContext (the current backend), so it
+    // is known-good — no existence check needed.
+    gitId = reuseGitId;
+    console.log(`\n  ${step("●")}  Reusing already-registered repo (gitId ${color.dim(gitId)}); skipping re-upload.`);
+  } else if (existing && existing.gitId) {
+    if (ctxProjects.some((p) => p.git_id === existing.gitId)) {
+      // Already mapped to >=1 project on THIS backend -> fully onboarded, and the
+      // server just vouched for it via resolveContext. Reuse, skip the upload.
+      gitId = existing.gitId;
+      skipUpload = true;
+      console.log(`\n  ${step("●")}  Reusing already-registered repo (gitId ${color.dim(gitId)}); skipping re-upload.`);
+    } else if (await agentApi.repoExists(existing.gitId)) {
+      // Registered but not yet in any project (partial onboarding interrupted
+      // before the project POST). The repo still exists on this backend -> finish
+      // it by uploading.
+      gitId = existing.gitId;
+      console.log(`\n  ${step("●")}  Reusing already-registered repo (gitId ${color.dim(gitId)}).`);
+    } else {
+      // Self-heal: the cached gitId does NOT exist on the current backend — the
+      // backend was switched (cached gitId belongs to another stack) or the repo
+      // was deleted. Drop the stale entry and register fresh instead of crashing
+      // on the first call with a dead gitId.
+      console.log(warn(
+        `\n  ⚠ Cached repo (gitId ${existing.gitId}) is not on this backend — ` +
+        `re-registering it here.`
+      ));
+      watchState.remove(targetDir);
+      // gitId stays null -> fresh registration below.
+    }
+  }
+
+  if (!gitId) {
+    // NO project_dir → the server sets sourceType=AGENT_UPLOAD.
+    const repoUrl = gitInfo.originUrl || `local://${defaultName}`;
+    gitId = await agentApi.registerRepo({
+      displayName: defaultName,
+      repositoryUrl: repoUrl,
+      branch: defaultBranch,
+      moduleExcludePatterns: cliModuleExcludes,
+      fileExcludePatterns: cliFileExcludes,
+    });
+    // Record BEFORE upload (mirrors add-repo): if the upload or a later step is
+    // interrupted, the gitId is not orphaned — a re-run reuses it. Tag it with the
+    // backend so a later backend switch won't reuse this gitId where it is invalid.
+    watchState.set(targetDir, {
+      gitId,
+      projectId: null,
+      branch: defaultBranch,
+      includePatterns: [],
+      excludePatterns: [],
+      fileHashes: {},
+      lastSyncedAt: null,
+    }, currentApiUrl);
+    console.log(`\n  ${step("●")}  Registered repo for upload (gitId ${color.dim(gitId)}).`);
+  }
+
+  // UPLOAD STEP — skipped entirely when reusing a repo that is ALREADY mapped to a
+  // project (cross-project AGENT_UPLOAD reuse, or a re-run on an already-onboarded
+  // folder). The server already holds its files, so we go straight to attach/create.
+  if (!skipUpload) {
+    const { offerModuleExcludeSuggestions } = require("../lib/moduleExcludeSuggestions");
+    await offerModuleExcludeSuggestions(gitId, opts, cliModuleExcludes);
+
+    // Build the manifest, surface oversize files (the 256 KiB server cap skips
+    // them), then ask the server which files to include.
+    process.stdout.write(`\n  Scanning ${color.cyan(targetDir)}...`);
+    const manifest = folderSync.buildManifest(targetDir);
+    process.stdout.write(` ${manifest.length} files found.\n`);
+    for (const m of manifest) {
+      if (m.size_bytes > folderSync.PER_FILE_CAP_BYTES) {
+        console.log(warn(
+          `       ⚠ ${m.path} (${Math.round(m.size_bytes / 1024)} KiB) exceeds the ` +
+          `256 KiB per-file cap — it will be skipped and not indexed.`
+        ));
+      }
+    }
+
+    const filterResult = await agentApi.filterManifest(gitId, manifest);
+    const includedPaths = filterResult.included_paths || filterResult.includedPaths || [];
+    const includedCount = filterResult.included_count || filterResult.includedCount || includedPaths.length;
+    const excludedCount = filterResult.excluded_count || filterResult.excludedCount || 0;
+    const includePatterns = filterResult.include_patterns || filterResult.includePatterns || [];
+    const excludePatterns = filterResult.exclude_patterns || filterResult.excludePatterns || [];
+    console.log(`       ${ok("Will sync:")} ${includedCount} files   ${warn("Excluded:")} ${excludedCount} files`);
+
+    // Push include/exclude patterns to the server so the build pipeline respects
+    // them. module_path "" (root) — there is no build-file-detected module yet.
+    if (includePatterns.length > 0 || excludePatterns.length > 0) {
+      try {
+        await api.put(`/api/git/${encodeURIComponent(gitId)}/module-resolution`, {
+          module_path: "",
+          include_dirs: includePatterns,
+          excluded: excludePatterns,
+        });
+      } catch (err) {
+        console.log(warn(`       ⚠ Could not save patterns to server: ${err.message}`));
+      }
+    }
+    watchState.update(targetDir, { includePatterns, excludePatterns });
+
+    console.log(`\n  ${step("1/3")}  Uploading ${includedPaths.length} files (branch ${color.cyan(defaultBranch || "detached HEAD")})...`);
+    // Reuse the sizes the manifest already computed so the aggregate guard does not re-stat every file.
+    const sizes = {};
+    for (const m of manifest) sizes[m.path] = m.size_bytes;
+    await folderSync.doInitialSync(gitId, targetDir, includedPaths, { sizes });
+  } else {
+    console.log(`  ${step("1/3")}  ${ok("Skipping upload — the server already has this repo's files.")}`);
+  }
+
+  let project;
+  if (isExisting) {
+    // EXISTING mode: attach this repo to the already-existing project via the
+    // same git-mappings endpoint `niro edit --add-repo` uses. Do NOT create a
+    // project. The discovered env vars come back via the preview fetch below,
+    // not from this response (POST git-mappings returns the updated project).
+    console.log(`  ${step("2/3")}  Adding repo to existing project "${color.bold(projectId)}" and scanning for environment variables...`);
+    project = await api.post(
+      `/api/projects/${encodeURIComponent(projectId)}/git-mappings`,
+      { [gitId]: {} }
+    );
+  } else {
+    console.log(`  ${step("2/3")}  Creating project "${color.bold(projectId)}" and scanning for environment variables...`);
+    project = await api.post("/api/projects", {
+      project_id: projectId,
+      git_id_to_mapping: { [gitId]: {} },
+    });
+  }
+
+  // If this folder was already onboarded to a different project, note the re-pin so
+  // it isn't silent — the repo is now mapped to both projects, but the pin (and MCP
+  // tools / `niro build` defaults) follow the most recent one.
+  if (existing && existing.projectId && existing.projectId !== projectId) {
+    console.log(warn(
+      `       ⚠ This folder was pinned to "${existing.projectId}"; it stays mapped there, ` +
+      `but is now also attached to "${projectId}" and re-pinned to it.`
+    ));
+  }
+  const { path: pinPath } = niroProjectFile.write(repoRoot, projectId, { overwrite: true });
+  watchState.update(targetDir, { projectId });
+  console.log(`       ${ok("✓")} Pinned project to ${color.dim(pinPath)}`);
+
+  let envVars = extractEnvVars(project, gitId);
+  // EXISTING mode attaches via POST /git-mappings, whose response may not carry the
+  // discovered env vars (a NEW-project POST normally does). When the response has
+  // none, fall back to the authoritative env-var preview so EXISTING mode still
+  // surfaces vars. Capture varsByFile here so the prompt below doesn't re-fetch.
+  let previewVarsByFile = null;
+  let previewActivePropertiesFiles = null;
+  if (envVars.length === 0) {
+    try {
+      const preview = await fetchPreview(projectId, gitId, { apiUrl: opts.apiUrl });
+      previewVarsByFile = preview.varsByFile || {};
+      previewActivePropertiesFiles = preview.activePropertiesFiles || [];
+      if (Array.isArray(preview.currentDiscoveredEnvVars) && preview.currentDiscoveredEnvVars.length) {
+        envVars = preview.currentDiscoveredEnvVars;
+      }
+    } catch {
+      // Could not load the preview — treat as no env vars; they can be set later
+      // with `niro edit --list-env` / `--set-env`.
+    }
+  }
+  let filledVars = envVars;
+  if (envVars.length === 0) {
+    console.log("       No env vars detected in this repo — skipping.");
+  } else if (opts.defaults) {
+    console.log(`       Found ${envVars.length} env var(s); leaving all at defaults (--defaults).`);
+  } else if (prompt.isNonInteractive()) {
+    console.error(fail(
+      `Found ${envVars.length} env var(s) that need values and no terminal is available to prompt.\n` +
+      "  Run with --defaults to accept discovered defaults, or set them later with `niro edit --set-env`."
+    ));
+    process.exitCode = 1;
+    return;
+  } else {
+    console.log(`       Found ${envVars.length} env var(s). When a var appears in several files, pick which file's value to use.`);
+    // Show, per var, the candidate value each committed file carries (source-file
+    // parity with the web UI). Reuse the preview fetched above when available; if a
+    // fresh fetch fails, fall back to a plain prompt rather than blocking onboarding.
+    let varsByFile = previewVarsByFile;
+    let activePropertiesFiles = previewActivePropertiesFiles;
+    if (varsByFile == null) {
+      try {
+        const preview = await fetchPreview(projectId, gitId, { apiUrl: opts.apiUrl });
+        varsByFile = preview.varsByFile;
+        activePropertiesFiles = preview.activePropertiesFiles;
+      } catch (err) {
+        varsByFile = {};
+        console.log(warn(`       ⚠ Could not load env-var source files (${err.message}) — prompting without candidates.`));
+      }
+    }
+
+    // PROPERTY-FILE SELECTION (interactive, web-UI parity): when Niro found >=2
+    // property files, let the user IGNORE some so their values don't drive defaults.
+    // The chosen ACTIVE set then filters the per-var candidate menu AND is persisted
+    // alongside the env values, so the selection sticks. With 0-1 files there is
+    // nothing meaningful to choose, so we skip it (server default unchanged).
+    const activeFiles = await promptActivePropertyFiles(varsByFile, activePropertiesFiles);
+
+    filledVars = await promptEnvVars(envVars, varsByFile, activeFiles);
+    // Persist active_properties_files only for a real RESTRICTION (a non-empty proper
+    // subset). "Keep all" equals the server default, so we leave it alone and send the
+    // bare array — avoids storing a redundant/ambiguous selection.
+    const totalFiles = Object.keys(varsByFile || {}).length;
+    const isRestriction = Array.isArray(activeFiles) && activeFiles.length > 0 && activeFiles.length < totalFiles;
+    const body = isRestriction
+      ? { env_vars: filledVars, active_properties_files: activeFiles }
+      : filledVars;
+    await api.put(
+      `/api/projects/${encodeURIComponent(projectId)}/git/${encodeURIComponent(gitId)}/env-vars`,
+      body
+    );
+  }
+
+  if (opts.defaults) {
+    console.log("       Skipping indexing-scope review (--defaults).");
+  } else if (prompt.isNonInteractive()) {
+    console.log("       Skipping indexing-scope review (no terminal to prompt; using detected defaults).");
+  } else {
+    await reviewIndexingScope(gitId);
+  }
+
+  // Auto-build: an explicit --auto-build flag (or --defaults) skips the prompt.
+  const autoBuildFlag = parseOnOff(opts.autoBuild);
+  if (autoBuildFlag !== null) {
+    const quietPeriodSeconds = parseQuietPeriod(opts.quietPeriod, 30);
+    await saveAutoBuild(projectId, autoBuildFlag, quietPeriodSeconds);
+  } else if (opts.defaults) {
+    console.log("       Leaving auto-build disabled (--defaults).");
+  } else if (prompt.isNonInteractive()) {
+    console.error(fail(
+      "Auto-build setting is required and no terminal is available to prompt.\n" +
+      "  Pass --auto-build <on|off> (and optionally --quiet-period <seconds>), or run with --defaults."
+    ));
+    process.exitCode = 1;
+    return;
+  } else {
+    await promptAutoBuild(projectId);
+  }
+
+  // Trigger-build-now: --confirm-build flag (or --defaults) skips the prompt.
+  const confirmBuildFlag = parseYesNo(opts.confirmBuild);
+  let shouldBuild;
+  if (confirmBuildFlag !== null) {
+    shouldBuild = confirmBuildFlag;
+  } else if (opts.defaults) {
+    shouldBuild = true;
+  } else if (prompt.isNonInteractive()) {
+    console.error(fail(
+      "Build confirmation is required and no terminal is available to prompt.\n" +
+      "  Pass --confirm-build <yes|no>, or run with --defaults."
+    ));
+    process.exitCode = 1;
+    return;
+  } else {
+    shouldBuild = await prompt.confirm("  Trigger a full index build now?", true);
+  }
+  if (!shouldBuild) {
+    console.log(`       ${warn("⚠")} Skipping build. Run ${color.cyan("niro build")} when you're ready.`);
+  } else {
+    console.log(`  ${step("3/3")}  Triggering full index build...`);
+    await api.post(
+      `/api/graph/${encodeURIComponent(projectId)}/build`,
+      {},
+      { query: { force_full_rebuild: "true" } }
+    );
+
+    if (opts.watch === false) {
+      console.log(`       Build triggered. Run ${color.cyan("niro status")} to check progress.`);
+    } else {
+      await watchStatus(projectId);
+    }
+  }
+
+  // --defaults promised "no prompts": never surface the PM2 install offer there.
+  const daemon = await watchDaemon.ensureWatchDaemon({ skipPrompts: !!opts.defaults });
+
+  // The closing banner must not read as an all-clear when auto-sync is dead —
+  // customers were only discovering the missing daemon after a reboot.
+  if (daemon.ok) {
+    console.log(`\n${ok("✓ Done.")} Niro MCP tools launched from this repo will now use this project automatically.`);
+  } else {
+    console.log(`\n${warn("✓ Done, with 1 warning:")} auto-sync is OFF — this folder will not stay in sync (see above for the fix).`);
+    console.log(`Niro MCP tools launched from this repo will still use this project automatically.`);
+  }
+  console.log(`Next: ${color.cyan("niro status")}, or ${color.cyan("niro mcp install")} to configure Claude Code / Cursor / Windsurf.`);
+}
+
+/**
+ * Gate a cross-project / overlap WARNING behind explicit consent.
+ *
+ *   - --force            -> proceed silently (agents / scripts opt in here).
+ *   - interactive shell  -> prompt.confirm(msg, default NO); a "no" means stop.
+ *   - non-interactive     -> refuse with guidance (no terminal to confirm on).
+ *
+ * Returns true to proceed, false to stop (the caller sets exitCode=1 and returns).
+ */
+async function requireProceed(msg, opts = {}) {
+  if (opts.force) return true;
+  if (prompt.isNonInteractive()) {
+    console.error(fail("  Pass --force to proceed past this warning."));
+    return false;
+  }
+  return await prompt.confirm(msg, false);
+}
+
+// Directories we never treat as nested repos / never descend into (build output, deps).
+const CHILD_SCAN_SKIP = new Set([
+  "node_modules", "target", "dist", "build", "out", ".next", "vendor", "__pycache__",
+]);
+const CHILD_SCAN_MAX = 60;       // bound the number of nested repos we resolve
+const CHILD_SCAN_MAX_DEPTH = 2;  // immediate children + one level of grouping dirs (services/, packages/, apps/)
+
+/**
+ * Collect directories under `root` that are their OWN git repo (have a `.git` entry),
+ * scanning immediate children AND one level of NON-git grouping dirs (so `services/foo`,
+ * `packages/foo` are found), but never descending INTO a git repo. Returns absolute
+ * paths plus a `truncated` flag when the CHILD_SCAN_MAX cap is hit.
+ *
+ * NOTE: a `.git` FILE (submodule/worktree pointer) is detected here, but resolving its
+ * origin currently needs a `.git` DIRECTORY — submodule/worktree children are surfaced
+ * as "unverified" by the caller rather than confirmed. Full clones (the common case) work.
+ */
+function collectNestedGitRepos(root) {
+  const repos = [];
+  let truncated = false;
+  const walk = (dir, depth) => {
+    if (repos.length >= CHILD_SCAN_MAX) { truncated = true; return; }
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (!e.isDirectory() || e.name.startsWith(".") || CHILD_SCAN_SKIP.has(e.name)) continue;
+      const child = path.join(dir, e.name);
+      if (fs.existsSync(path.join(child, ".git"))) {
+        repos.push(child); // its own repo — record it, don't descend into it
+        if (repos.length >= CHILD_SCAN_MAX) { truncated = true; return; }
+      } else if (depth < CHILD_SCAN_MAX_DEPTH) {
+        walk(child, depth + 1); // a grouping dir (services/, packages/) — look one level deeper
+      }
+    }
+  };
+  walk(root, 1);
+  return { repos, truncated };
+}
+
+/**
+ * Detect that THIS folder is a PARENT of repos already indexed in Niro — e.g. running
+ * init in a monorepo root containing several service git repos. watchState only knows
+ * folders THIS CLI onboarded, so we resolve each nested git repo against the SERVER
+ * (covers children indexed via the web UI / as separate repos too).
+ *
+ * Returns { indexed:[{path,name,projects}], unverified:[{path,name}], truncated }.
+ *   - indexed:    children that resolve to >=1 project (the overlap we warn about).
+ *   - unverified: children we couldn't check (resolve error / unreadable origin) — they
+ *                 MIGHT also be indexed, so we surface a softer note (no silent drop).
+ * Cheap for a normal repo (no nested git repos => no server calls); only a true parent
+ * pays for the resolves, which run with bounded concurrency.
+ */
+async function scanIndexedChildren(targetDir, opts, resolve = resolveContext) {
+  const { repos: gitChildren, truncated } = collectNestedGitRepos(targetDir);
+  if (!gitChildren.length) return { indexed: [], unverified: [], truncated };
+
+  const indexed = [];
+  const unverified = [];
+  const CONCURRENCY = 8;
+  for (let i = 0; i < gitChildren.length; i += CONCURRENCY) {
+    const batch = gitChildren.slice(i, i + CONCURRENCY);
+    const resolved = await Promise.all(batch.map(async (child) => {
+      const name = path.basename(child);
+      try {
+        const ctx = await resolve(child, opts);
+        const projects = Array.isArray(ctx.projects) ? ctx.projects : [];
+        if (projects.length) return { kind: "indexed", path: child, name, projects };
+        // A server/network hiccup must not be read as "not indexed" — flag it.
+        if (ctx && ctx.state === "error") return { kind: "unverified", path: child, name };
+        return null;
+      } catch {
+        return { kind: "unverified", path: child, name };
+      }
+    }));
+    for (const r of resolved) {
+      if (!r) continue;
+      if (r.kind === "indexed") indexed.push(r);
+      else unverified.push(r);
+    }
+  }
+  return { indexed, unverified, truncated };
+}
+
+/**
+ * Decide the TARGET of this onboarding up front, before any repo registration:
+ *   - --add-to <alias|id> -> EXISTING: resolve to a real projectId (throws on
+ *     ambiguity/not-found via resolveProjectId), attach the new repo to it later.
+ *   - --project-name / --defaults / non-interactive -> NEW: derive a free name
+ *     exactly as before (unchanged behaviour for scripts and the default path).
+ *   - INTERACTIVE with >=1 existing project -> show a numbered menu (new vs each
+ *     existing project) so the user can attach instead of always creating new.
+ *
+ * Returns { projectId, isExisting } or null when the user/flags didn't yield a
+ * usable target (caller sets exitCode=1).
+ */
+async function resolveTarget({ defaultName, opts }) {
+  if (opts.addTo) {
+    let projectId;
+    try {
+      projectId = await resolveProjectId(opts.addTo, { apiUrl: opts.apiUrl });
+    } catch (err) {
+      console.error(fail(`Could not resolve --add-to "${opts.addTo}": ${err.message}`));
+      return null;
+    }
+    return { projectId, isExisting: true };
+  }
+
+  // Explicit name, --defaults, or a non-interactive shell -> NEW (current path).
+  // We only offer the existing-project menu in an interactive shell with at
+  // least one project to pick.
+  if (!opts.projectName && !opts.defaults && !prompt.isNonInteractive()) {
+    const existing = await fetchExistingProjects(opts);
+    if (existing.length > 0) {
+      const chosen = await chooseTarget(existing);
+      if (chosen === null) return null;          // no valid selection
+      if (chosen !== "NEW") return { projectId: chosen, isExisting: true };
+      // fall through to NEW name derivation
+    }
+  }
+
+  const projectId = await resolveAvailableProjectName({ defaultName, opts });
+  if (!projectId) return null;
+  return { projectId, isExisting: false };
+}
+
+/** Fetch the account's projects as sorted rows; empty list on any failure. */
+async function fetchExistingProjects(opts) {
+  try {
+    const data = await api.get("/api/projects", { apiUrl: opts.apiUrl });
+    return projectsToRows(data);
+  } catch (err) {
+    console.log(warn(`  ⚠ Could not load your existing projects (${err.message}) — creating a new project.`));
+    return [];
+  }
+}
+
+/**
+ * Numbered menu: [n] create new, [1..N] attach to an existing project. Returns
+ * "NEW", an existing project_id, or null when the answer is invalid.
+ */
+async function chooseTarget(rows) {
+  console.log(`\n  ${color.bold("New project, or add to an existing one?")}`);
+  console.log(`    [n] create a new project`);
+  rows.forEach((r, i) => {
+    const label = r.alias ? `${r.alias} (${color.dim(r.project_id)})` : color.dim(r.project_id);
+    console.log(`    [${i + 1}] ${label}`);
+  });
+  const answer = (await prompt.ask(`  Choose 'n' for new, or 1-${rows.length} to add to an existing project`, "n")).trim();
+  if (!answer || answer.toLowerCase() === "n") return "NEW";
+  const idx = Number.parseInt(answer, 10) - 1;
+  if (Number.isInteger(idx) && idx >= 0 && idx < rows.length) {
+    return rows[idx].project_id;
+  }
+  console.error(fail(`Invalid choice "${answer}" — pick 'n' or a number between 1 and ${rows.length}.`));
+  return null;
+}
+
+const GLOB_INCLUDE_EXAMPLES = "e.g. src/**/*.py, lib/**/*.ts";
+const GLOB_EXCLUDE_EXAMPLES = "e.g. **/test/**, **/*.generated.*, vendor/**";
+
+/**
+ * Resolve a project name that is guaranteed to be free on this account.
+ *
+ * We probe GET /api/projects/{id} before registering anything — previously
+ * the CLI only discovered a collision after the POST, by which point the
+ * repo had already been registered in step 1 and we left an orphan.
+ *
+ * Two modes:
+ *   - --project-name supplied: check once; if taken, fail fast with guidance.
+ *     Scripts shouldn't be surprised by an interactive loop.
+ *   - Interactive: prompt, check, and loop on conflict. The first proposal
+ *     defaults to the repo basename; subsequent loops keep whatever the user
+ *     just typed as the default so a small tweak is one keystroke away.
+ */
+async function resolveAvailableProjectName({ defaultName, opts }) {
+  if (opts.projectName) {
+    if (await projectNameTaken(opts.projectName)) {
+      console.error(
+        fail(`Project "${opts.projectName}" already exists on this account.`) +
+        ` Pick a different name or delete it first (niro delete ${opts.projectName}).`
+      );
+      return null;
+    }
+    return opts.projectName;
+  }
+
+  // --defaults: accept the derived repo name without prompting (it is checked
+  // for collisions below). Non-interactive without --defaults/--project-name:
+  // fail loudly rather than hang on a prompt.
+  if (opts.defaults) {
+    if (await projectNameTaken(defaultName)) {
+      console.error(
+        fail(`Project "${defaultName}" already exists on this account.`) +
+        ` Pass --project-name <name> or delete it first (niro delete ${defaultName}).`
+      );
+      return null;
+    }
+    return defaultName;
+  }
+  if (prompt.isNonInteractive()) {
+    console.error(fail(
+      "Project name is required and no terminal is available to prompt.\n" +
+      "  Pass --project-name <name>, or run with --defaults to accept the derived name."
+    ));
+    return null;
+  }
+
+  let candidate = defaultName;
+  while (true) {
+    const answer = await prompt.ask("Project name", candidate);
+    if (!answer) {
+      console.error(fail("Project name is required."));
+      return null;
+    }
+    if (!(await projectNameTaken(answer))) return answer;
+    console.log(`  ${warn("⚠")} "${color.bold(answer)}" already exists on this account — pick another.`);
+    candidate = answer;
+  }
+}
+
+async function projectNameTaken(projectId) {
+  try {
+    await api.get(`/api/projects/${encodeURIComponent(projectId)}`);
+    return true;
+  } catch (err) {
+    const body = err && err.body;
+    const msg = (body && (body.error || body.message)) || err.message || "";
+    if (/not found/i.test(String(msg))) return false;
+    // Any other error (network, 401, 500) we surface — don't silently treat
+    // as "available" or we'll create a project we can't manage.
+    throw err;
+  }
+}
+
+/**
+ * Fetch per-module include/exclude resolutions the server detected during repo
+ * registration, display them, and let the user extend either set. We only send
+ * a PUT when the user actually added patterns — an empty answer leaves the
+ * server's detected defaults untouched.
+ *
+ * The server stores these on GitRepoDetails.projectResolutions, keyed by
+ * module_path (e.g. "src/server" for a monorepo subproject). Each resolution
+ * has its own include/exclude set, so we walk the map module by module.
+ */
+async function reviewIndexingScope(gitId) {
+  let details;
+  try {
+    details = await api.get(`/api/git/${encodeURIComponent(gitId)}`);
+  } catch (err) {
+    console.log(`       Could not fetch project resolutions (${err.message}) — skipping scope review.`);
+    return;
+  }
+  const resolutions = (details && (details.project_resolutions || details.projectResolutions)) || {};
+  const modulePaths = Object.keys(resolutions);
+  if (modulePaths.length === 0) {
+    console.log("       No module resolutions detected — skipping scope review.");
+    return;
+  }
+
+  console.log(`\n  ${color.bold("Review indexing scope")} (${modulePaths.length} module(s) detected).`);
+  console.log(color.dim(`       Glob patterns use ** for recursive match. Press Enter to keep the detected set.`));
+
+  for (const modulePath of modulePaths) {
+    const resolution = resolutions[modulePath] || {};
+    const includeDirs = toArray(resolution.include_dirs || resolution.includeDirs);
+    const excluded = toArray(resolution.excluded);
+    const pkg = resolution.package_name || resolution.packageName;
+    const label = pkg ? `${modulePath} (${color.dim(pkg)})` : modulePath;
+
+    console.log(`\n       ${color.bold("[" + label + "]")}`);
+    console.log(`         ${color.green("Included")}: ${formatList(includeDirs)}`);
+    console.log(`         ${color.yellow("Excluded")}: ${formatList(excluded)}`);
+
+    const addedIncludes = await promptGlobList("         Add inclusion patterns", GLOB_INCLUDE_EXAMPLES);
+    const addedExcludes = await promptGlobList("         Add exclusion patterns", GLOB_EXCLUDE_EXAMPLES);
+
+    if (addedIncludes.length === 0 && addedExcludes.length === 0) continue;
+
+    const nextIncludes = uniq([...includeDirs, ...addedIncludes]);
+    const nextExcluded = uniq([...excluded, ...addedExcludes]);
+
+    try {
+      await api.put(`/api/git/${encodeURIComponent(gitId)}/module-resolution`, {
+        module_path: modulePath,
+        include_dirs: nextIncludes,
+        excluded: nextExcluded,
+      });
+      console.log(`         ${ok("✓")} Updated.`);
+    } catch (err) {
+      console.log(`         ${fail("✗")} Failed to update scope: ${err.message}`);
+    }
+  }
+}
+
+async function promptGlobList(label, exampleHint) {
+  const answer = await prompt.ask(`${label} ${color.dim("(" + exampleHint + ")")}`, "");
+  if (!answer) return [];
+  return answer
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+async function promptAutoBuild(projectId) {
+  const enabled = await prompt.confirm("  Enable auto-build when files change?", false);
+  let quietPeriodSeconds = 30;
+  if (enabled) {
+    const raw = await prompt.ask("  Quiet period in seconds before rebuild", "30");
+    const parsed = Number.parseInt(raw, 10);
+    if (Number.isFinite(parsed) && parsed >= 0) quietPeriodSeconds = parsed;
+  }
+  await saveAutoBuild(projectId, enabled, quietPeriodSeconds);
+}
+
+async function saveAutoBuild(projectId, enabled, quietPeriodSeconds) {
+  try {
+    await api.put(`/api/projects/${encodeURIComponent(projectId)}/auto-sync`, {
+      enabled,
+      quiet_period_seconds: quietPeriodSeconds,
+    });
+    const statusLabel = enabled ? ok(`ON (quiet ${quietPeriodSeconds}s)`) : color.dim("off");
+    console.log(`       Auto-build: ${statusLabel}.`);
+  } catch (err) {
+    console.log(`       ${fail("✗")} Failed to save auto-build setting: ${err.message}`);
+  }
+}
+
+/** Parse --auto-build <on|off>. Returns true/false, or null if unset. Throws on garbage. */
+function parseOnOff(v) {
+  if (v === undefined || v === null || v === "") return null;
+  const s = String(v).trim().toLowerCase();
+  if (s === "on" || s === "true" || s === "yes" || s === "1") return true;
+  if (s === "off" || s === "false" || s === "no" || s === "0") return false;
+  throw new Error(`Invalid --auto-build value "${v}". Use "on" or "off".`);
+}
+
+/** Parse --confirm-build <yes|no>. Returns true/false, or null if unset. Throws on garbage. */
+function parseYesNo(v) {
+  if (v === undefined || v === null || v === "") return null;
+  const s = String(v).trim().toLowerCase();
+  if (s === "yes" || s === "y" || s === "true" || s === "1") return true;
+  if (s === "no" || s === "n" || s === "false" || s === "0") return false;
+  throw new Error(`Invalid --confirm-build value "${v}". Use "yes" or "no".`);
+}
+
+/** Parse --quiet-period <seconds>; fall back to the default when unset, throw on garbage. */
+function parseQuietPeriod(v, fallback) {
+  if (v === undefined || v === null || v === "") return fallback;
+  const parsed = Number.parseInt(String(v), 10);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    throw new Error(`Invalid --quiet-period value "${v}". Use a non-negative number of seconds.`);
+  }
+  return parsed;
+}
+
+function toArray(v) {
+  if (!v) return [];
+  if (Array.isArray(v)) return v;
+  if (v instanceof Set) return [...v];
+  if (typeof v === "object") return Object.values(v);
+  return [];
+}
+
+function uniq(list) {
+  return [...new Set(list)];
+}
+
+function formatList(list) {
+  if (!list || list.length === 0) return "(none)";
+  return list.join(", ");
+}
+
+function extractEnvVars(project, gitId) {
+  if (!project) return [];
+  const mapping = (project.git_id_to_mapping || project.gitIdToMapping || {})[gitId];
+  if (!mapping) return [];
+  const props = mapping.git_properties || mapping.gitProperties;
+  if (!props) return [];
+  const list = props.discovered_env_vars || props.discoveredEnvVars;
+  return Array.isArray(list) ? list : [];
+}
+
+/**
+ * PROPERTY-FILE SELECTION (web-UI parity). When Niro discovered >=2 property files,
+ * list them with their current active state and let the user pick which to IGNORE
+ * (Enter = use ALL). Returns the resulting ACTIVE set as an array, or null when there
+ * is nothing to choose (0-1 files) — in which case the caller leaves the server's
+ * stored selection untouched.
+ *
+ * `currentActive` is the preview's activePropertiesFiles (empty/absent => all active).
+ * The user lists FILE NUMBERS to ignore; we drop those, keeping the rest active. The
+ * value of each file is never shown here — this step is purely about file selection.
+ */
+async function promptActivePropertyFiles(varsByFile, currentActive) {
+  const files = Object.keys(varsByFile || {}).sort();
+  if (files.length < 2) return null; // nothing meaningful to choose
+
+  const activeSet = Array.isArray(currentActive) && currentActive.length
+    ? new Set(currentActive)
+    : null; // null => all active
+  const isActive = (f) => activeSet == null || activeSet.has(f);
+
+  console.log(`\n    ${color.bold("Property files Niro found")} (their values become env-var defaults):`);
+  files.forEach((f, i) => {
+    const state = isActive(f) ? ok("[active]") : warn("[ignored]");
+    console.log(`      [${i + 1}] ${f} ${state}`);
+  });
+  const answer = (await prompt.ask(
+    "      Enter to use ALL, or list numbers to IGNORE (e.g. 2,3)",
+    ""
+  )).trim();
+
+  if (!answer) {
+    // Use ALL discovered files (every file active).
+    return files.slice();
+  }
+
+  const ignoreIdx = new Set(
+    answer
+      .split(",")
+      .map((s) => Number.parseInt(s.trim(), 10) - 1)
+      .filter((n) => Number.isInteger(n) && n >= 0 && n < files.length)
+  );
+  const active = files.filter((_f, i) => !ignoreIdx.has(i));
+  if (active.length === files.length) {
+    console.log(color.dim("      No valid numbers recognised — keeping all property files active."));
+    return files.slice();
+  }
+  if (active.length === 0) {
+    // Ignoring every file isn't a durable state (an empty active set reads back as
+    // "all active"). Keep all; the user can still leave values blank and set them
+    // later with `niro edit --set-env`.
+    console.log(warn("      Can't ignore every property file — keeping all active."));
+    return files.slice();
+  }
+  const ignored = files.filter((_f, i) => ignoreIdx.has(i));
+  console.log(`      ${warn("Ignoring")}: ${ignored.join(", ")}`);
+  return active;
+}
+
+/**
+ * Prompt a value for each discovered env var. When the same key was discovered in
+ * SEVERAL files (candidates reconstructed from the preview's varsByFile, exactly as
+ * the web UI does), render a numbered menu so the user can pick which file's value
+ * drives the var — adopting a file sets user_value to that file's value and points
+ * source_file at it. Otherwise fall back to a single prompt.
+ *
+ * `activeFiles` (optional array): when provided, candidate values are restricted to
+ * those property files (web-UI "considered files" selection) — ignored files do not
+ * appear in the menu.
+ *
+ * SECRETS: secret-pattern keys never echo a value. Candidate values are masked in
+ * the menu, and a custom value is typed hidden (askHidden). Non-interactive callers
+ * never reach here (init gates this behind an interactive check); even so, an empty
+ * answer keeps the current value rather than wiping it.
+ */
+async function promptEnvVars(envVars, varsByFile = {}, activeFiles = null) {
+  const out = [];
+  for (const v of envVars) {
+    const key = v.key;
+    const secret = isSecretKey(key);
+    const currentValue = v.user_value || v.resolved_value || "";
+    const currentSource = v.source_file || v.sourceFile || null;
+    // Restrict candidates to the ACTIVE property files when a selection was made
+    // (ignored files contribute no defaults — web-UI parity).
+    const candidates = buildCandidates(varsByFile, key, v, activeFiles);
+
+    if (candidates.length > 1) {
+      console.log(`\n    ${color.bold(key)}${currentSource ? color.dim(` (current: ${currentSource})`) : ""}`);
+      candidates.forEach((c, i) => {
+        // Mask when the key looks secret OR the value embeds credentials.
+        const hide = secret || looksSecretValue(c.value);
+        const shown = c.value == null ? "(empty)" : (hide ? "****" : c.value);
+        const marker = (c.is_current || c.is_default) ? color.green("  [current default]") : "";
+        console.log(`      [${i + 1}] ${shown}   ${color.dim("from " + c.source_file)}${marker}`);
+      });
+      console.log(`      [c] enter a custom value`);
+      const choice = (await prompt.ask(`      Choose 1-${candidates.length}, c, or Enter to keep current`, "")).trim();
+      if (!choice) {
+        out.push({ ...v });
+        continue;
+      }
+      if (choice.toLowerCase() === "c") {
+        const answer = secret
+          ? await prompt.askHidden(`      Value for ${key}`)
+          : await prompt.ask(`      Value for ${key}`, "");
+        out.push({ ...v, user_value: answer || null });
+        continue;
+      }
+      const idx = Number.parseInt(choice, 10) - 1;
+      if (Number.isInteger(idx) && idx >= 0 && idx < candidates.length) {
+        const chosen = candidates[idx];
+        out.push({ ...v, user_value: chosen.value, source_file: chosen.source_file });
+      } else {
+        out.push({ ...v }); // unrecognised -> keep current, never guess
+      }
+      continue;
+    }
+
+    // Single (or no) candidate: one prompt. Tell the user where it came from, and —
+    // when no default value was found in a committed config/property file — that the
+    // value is needed (its value may have lived only in a gitignored .env or inline
+    // in code, which we never scrape).
+    let hint = currentSource ? ` (from ${currentSource})` : "";
+    if (!currentValue) hint += " (no default — please enter a value)";
+    if (secret) {
+      const answer = await prompt.askHidden(`    ${key}${hint} (hidden, Enter to keep current)`);
+      out.push({ ...v, user_value: answer || (v.user_value || null) });
+    } else {
+      const answer = await prompt.ask(`    ${key}${hint}`, currentValue);
+      out.push({ ...v, user_value: answer || null });
+    }
+  }
+  return out;
+}
+
+/**
+ * Return the user-intended target directory, preferring the shell's logical
+ * cwd ($PWD) over process.cwd() when they point at the same inode. This keeps
+ * paths that transit through symlinks (a common Docker-mount setup) in their
+ * logical form rather than collapsing them to the symlink target.
+ */
+function resolveTargetDir(pathArg) {
+  const base = logicalCwd();
+  if (!pathArg) return base;
+  return path.isAbsolute(pathArg) ? path.resolve(pathArg) : path.resolve(base, pathArg);
+}
+
+function logicalCwd() {
+  const pwd = process.env.PWD;
+  if (!pwd) return process.cwd();
+  try {
+    const a = fs.statSync(pwd);
+    const b = fs.statSync(process.cwd());
+    if (a.ino === b.ino && a.dev === b.dev) return pwd;
+  } catch {
+    // $PWD stale or unreadable — fall through
+  }
+  return process.cwd();
+}
+
+module.exports = { init, parseOnOff, parseYesNo, parseQuietPeriod, promptEnvVars, promptActivePropertyFiles, scanIndexedChildren };