@niroai/niro 0.3.0

package/src/commands/edit.js

@@ -0,0 +1,601 @@
+/**
+ * `niro edit` — mutate an existing Niro project from the terminal.
+ *
+ * Target project resolution (same precedence as status/build/delete):
+ *   explicit --project <alias|id>  >  .niro-project walk-up from cwd.
+ * resolveProjectId THROWS on ambiguity (alias/url maps to >1 project), so we
+ * never silently pick the wrong one.
+ *
+ * Sub-actions (at least one required; multiple may be combined and run in a
+ * stable order):
+ *   --add-repo <gitId>       POST   /api/projects/{projectId}/git-mappings
+ *   --remove-repo <gitId>    DELETE /api/projects/{projectId}/git/{gitId}   (non-destructive unmap)
+ *   --set-env KEY=VALUE...   PUT    /api/projects/{projectId}/git/{gitId}/env-vars
+ *   --list-env               GET    /api/projects/{projectId}/git/{gitId}/env-vars/preview
+ *   --rescan-env             POST   /api/projects/{projectId}/git/{gitId}/env-vars/rescan
+ *   --alias <newAlias>       PUT    /api/projects/{projectId}            (phase-1 rename)
+ *
+ * Env-var sub-actions are per-REPO (the server keys env vars by gitId). The
+ * target repo is --repo <gitId>, or auto-selected when the project has exactly
+ * one repo mapped, or — on a multi-repo project — the repo matching the current
+ * folder's git url+branch (only when it provably belongs to this project).
+ *
+ * SECRETS: --set-env never echoes a VALUE (only the changed key NAMES are
+ * printed). --set-env-from never echoes a VALUE either — it prints "KEY <- file".
+ * --list-env shows non-secret candidate values inline but masks values for
+ * secret-pattern keys via secret.js before printing (terminal AND --json).
+ *
+ * SOURCE-FILE PARITY (web UI): the same KEY can be discovered in MULTIPLE files
+ * (varsByFile) with different values — those are the CANDIDATES. We reconstruct
+ * them client-side (exactly as the UI's EnvVarsRepoSection does) so the user can
+ * see "this var appears in N files" and choose which file drives it. Choosing a
+ * file = setting that var's user_value to the file's value (and source_file to
+ * the chosen file), then PUTting the legacy env-var array. No backend change.
+ */
+const api = require("../lib/api");
+const credentials = require("../lib/credentials");
+const color = require("../lib/color");
+const { resolveProjectId } = require("./_resolveProject");
+const { resolveContext } = require("../lib/resolveContext");
+const { stripSecrets, isSecretKey, looksSecretValue } = require("../lib/secret");
+
+async function edit(opts = {}) {
+  // --active-files may be an empty string (which setActiveFiles rejects with a clear
+  // error) — guard on "was the flag provided" (!== undefined), not truthiness, so the
+  // empty case still runs and reports the error rather than being silently ignored.
+  const hasActiveFiles = opts.activeFiles !== undefined && opts.activeFiles !== null;
+  const actions = [
+    opts.addRepo, opts.removeRepo,
+    opts.setEnv && opts.setEnv.length,
+    opts.setEnvFrom && opts.setEnvFrom.length,
+    hasActiveFiles,
+    opts.listEnv,
+    opts.rescanEnv, opts.alias,
+  ].filter(Boolean);
+  if (actions.length === 0) {
+    printUsage();
+    process.exitCode = 1;
+    return;
+  }
+
+  credentials.requireCreds();
+  const projectId = await resolveProjectId(opts.project, { apiUrl: opts.apiUrl });
+
+  // Run sub-actions in a stable, sensible order: structural mappings first,
+  // then env edits, then a rescan, then read-only listing, then rename last.
+  if (opts.addRepo) await addRepo(projectId, opts.addRepo, opts);
+  if (opts.removeRepo) await removeRepo(projectId, opts.removeRepo, opts);
+  if (opts.setEnv && opts.setEnv.length) await setEnv(projectId, opts.setEnv, opts);
+  if (opts.setEnvFrom && opts.setEnvFrom.length) {
+    const gitId = await resolveRepo(projectId, opts);
+    await setEnvFrom(projectId, gitId, opts.setEnvFrom, opts);
+  }
+  if (hasActiveFiles) await setActiveFiles(projectId, opts.activeFiles, opts);
+  if (opts.rescanEnv) await rescanEnv(projectId, opts);
+  if (opts.listEnv) await listEnv(projectId, opts);
+  if (opts.alias) await setAlias(projectId, opts.alias, opts);
+}
+
+async function addRepo(projectId, gitId, opts) {
+  // The endpoint takes a map of gitId -> GitMappingRequestDto. The DTO carries
+  // no user fields (baseUrl is discovered from env scanning), so an empty
+  // object is the correct body.
+  await api.post(
+    `/api/projects/${encodeURIComponent(projectId)}/git-mappings`,
+    { [gitId]: {} },
+    { apiUrl: opts.apiUrl }
+  );
+  console.log(`${color.green("✓")} Added repo ${color.dim(gitId)} to project ${color.dim(projectId)}.`);
+}
+
+async function removeRepo(projectId, gitId, opts) {
+  await api.del(
+    `/api/projects/${encodeURIComponent(projectId)}/git/${encodeURIComponent(gitId)}`,
+    { apiUrl: opts.apiUrl }
+  );
+  console.log(`${color.green("✓")} Unmapped repo ${color.dim(gitId)} from project ${color.dim(projectId)} (repo itself is kept).`);
+}
+
+async function setAlias(projectId, alias, opts) {
+  const trimmed = String(alias).trim();
+  if (!trimmed) {
+    console.error(`${color.red("✗")} --alias cannot be empty.`);
+    process.exitCode = 1;
+    return;
+  }
+  await api.put(
+    `/api/projects/${encodeURIComponent(projectId)}`,
+    { alias: trimmed },
+    { apiUrl: opts.apiUrl }
+  );
+  console.log(`${color.green("✓")} Renamed project ${color.dim(projectId)} to "${color.bold(trimmed)}".`);
+}
+
+/**
+ * Resolve which repo (gitId) the env sub-actions target:
+ *   - explicit --repo <gitId> wins;
+ *   - else if the project maps exactly one repo, use it;
+ *   - else (multiple repos) try the CURRENT FOLDER: resolve this folder's git
+ *     url+branch to its project+repo (same signal `niro info` uses) and, IF that
+ *     repo is one of THIS project's repos, target it — so a monorepo (ADR-005:
+ *     one project, many repos) just works from inside a repo folder;
+ *   - else fail clearly listing the candidates (never guess).
+ *
+ * SAFETY: we only use the folder-resolved git_id when it belongs to THIS project's
+ * mapped repos. If the folder resolves to a different project, has no git_id, or
+ * resolves to a repo not in this project, we DO NOT guess — writing env vars to the
+ * wrong repo must be impossible — and fall back to the clear --repo error.
+ */
+async function resolveRepo(projectId, opts) {
+  if (opts.repo) return opts.repo;
+  const project = await api.get(`/api/projects/${encodeURIComponent(projectId)}`, { apiUrl: opts.apiUrl });
+  const gitDetails = (project && (project.git_details || project.gitDetails)) || [];
+  if (gitDetails.length === 1) return gitDetails[0].id;
+  if (gitDetails.length === 0) {
+    const e = new Error("This project has no repos mapped. Add one with --add-repo <gitId> first.");
+    throw e;
+  }
+
+  // Multiple repos: try to pick the one matching the current folder, but only if
+  // it is provably one of this project's repos. Never pick arbitrarily.
+  const repoIds = new Set(gitDetails.map((g) => g.id).filter(Boolean));
+  const folderGitId = await folderRepoGitId(projectId, opts);
+  if (folderGitId && repoIds.has(folderGitId)) {
+    return folderGitId;
+  }
+
+  const list = gitDetails.map((g) => `  - ${g.id}${g.repo ? ` (${g.repo})` : ""}`).join("\n");
+  const e = new Error(`This project has multiple repos — pass --repo <gitId> to choose:\n${list}`);
+  throw e;
+}
+
+/**
+ * Resolve the current folder's repo (gitId) WITHIN the given project, or null.
+ *
+ * Asks the server which project(s)+repo this folder's git url+branch maps to, then
+ * returns the git_id only when one of those matches resolves to exactly THIS
+ * project and carries a git_id. Returns null on anything ambiguous, missing, or
+ * pointing at a different project — the caller then refuses to guess.
+ */
+async function folderRepoGitId(projectId, opts) {
+  let ctx;
+  try {
+    ctx = await resolveContext(process.cwd(), { apiUrl: opts.apiUrl });
+  } catch {
+    return null;
+  }
+  if (!ctx || ctx.state !== "resolved" || !Array.isArray(ctx.projects)) return null;
+  const match = ctx.projects.find((p) => p && p.project_id === projectId && p.git_id);
+  return match ? match.git_id : null;
+}
+
+/**
+ * --set-env KEY=VALUE (repeatable). Reads the current env vars (preview), merges
+ * the new user values, and PUTs the full set back. NEVER echoes a value — prints
+ * only the changed key names on success.
+ */
+async function setEnv(projectId, pairs, opts) {
+  // Validate ALL input before any network call, so a malformed KEY=VALUE fails fast with
+  // zero server side effects and the masked parse error is always reachable.
+  const parsed = [];
+  for (const pair of pairs) {
+    const eq = pair.indexOf("=");
+    if (eq <= 0) {
+      console.error(`${color.red("✗")} --set-env expects KEY=VALUE (got "${maskPair(pair)}").`);
+      process.exitCode = 1;
+      return;
+    }
+    parsed.push({ key: pair.slice(0, eq).trim(), value: pair.slice(eq + 1) });
+  }
+
+  const gitId = await resolveRepo(projectId, opts);
+
+  // Start from the project's currently-stored env vars so we don't drop any.
+  const preview = await fetchPreview(projectId, gitId, opts);
+  const current = preview.currentDiscoveredEnvVars;
+
+  // Index by key for an in-place merge; preserve other fields the server sent back.
+  const byKey = new Map();
+  for (const v of current) {
+    if (v && v.key) byKey.set(v.key, { ...v });
+  }
+  const changedKeys = [];
+  for (const { key, value } of parsed) {
+    const existing = byKey.get(key) || { key };
+    existing.user_value = value;
+    byKey.set(key, existing);
+    changedKeys.push(key);
+  }
+
+  const envVars = Array.from(byKey.values());
+  await api.put(
+    `/api/projects/${encodeURIComponent(projectId)}/git/${encodeURIComponent(gitId)}/env-vars`,
+    { env_vars: envVars },
+    { apiUrl: opts.apiUrl }
+  );
+
+  if (opts.json) {
+    console.log(JSON.stringify({ project_id: projectId, git_id: gitId, changed_keys: changedKeys }));
+  } else {
+    console.log(`${color.green("✓")} Updated env var(s) on repo ${color.dim(gitId)}: ${changedKeys.map((k) => color.bold(k)).join(", ")}`);
+    console.log(color.dim("  (values are not shown)"));
+  }
+}
+
+/**
+ * --list-env: show each env var KEY, its current source file, and the per-var
+ * CANDIDATES — i.e. which committed files the same key was discovered in, and the
+ * value each file carries. This mirrors the web UI: the same KEY in multiple files
+ * is a choice of "which file drives this var". Non-secret candidate values are
+ * shown inline; secret-pattern keys have their values masked (terminal AND --json).
+ */
+async function listEnv(projectId, opts) {
+  const gitId = await resolveRepo(projectId, opts);
+  const preview = await fetchPreview(projectId, gitId, opts);
+  const summary = summarizeEnvVars(preview);
+
+  // The discovered PROPERTY FILES are the keys of varsByFile. The ACTIVE set is
+  // activePropertiesFiles; an EMPTY/absent active set means "all files active".
+  const discoveredFiles = Object.keys(preview.varsByFile || {}).sort();
+  const activeSet = toActiveSet(preview.activePropertiesFiles);
+  const isActive = (f) => activeSet == null || activeSet.has(f);
+
+  if (opts.json) {
+    // Secret candidate VALUES are already masked in summarizeEnvVars (primary
+    // defence — when the KEY name looks secret OR the VALUE embeds credentials).
+    // stripSecrets is a belt-and-braces pass over the candidate objects to redact
+    // any secret-NAMED field if the shape ever changes. We DON'T strip the
+    // surrounding metadata: those fields (key, source files, is_secret, appears_in)
+    // are deliberately public and carry no secret values — and field names like
+    // "is_secret" or a file path containing "secret" would otherwise be clobbered.
+    const env = summary.map((s) => ({
+      key: s.key,
+      source: s.chosen_source_file,
+      chosen_source_file: s.chosen_source_file,
+      has_user_value: s.has_user_value,
+      has_resolved_value: s.has_resolved_value,
+      is_secret: s.is_secret,
+      appears_in: s.appears_in,
+      candidates: stripSecrets(s.candidates, { maskValues: false }),
+    }));
+    console.log(JSON.stringify({
+      project_id: projectId,
+      git_id: gitId,
+      // The property files Niro discovered, and which of them are ACTIVE (drive
+      // env-var defaults). active_properties_files is the raw stored selection
+      // (empty array => all files active).
+      active_properties_files: toActiveSet(preview.activePropertiesFiles) == null ? [] : discoveredFiles.filter(isActive),
+      discovered_property_files: discoveredFiles.map((f) => ({ file: f, active: isActive(f) })),
+      env,
+    }));
+    return;
+  }
+
+  // Show the discovered property files and which are active, so the user can decide
+  // whether to ignore any (via `niro edit --active-files`).
+  if (discoveredFiles.length) {
+    const rendered = discoveredFiles
+      .map((f) => `${f} ${isActive(f) ? color.green("[active]") : color.yellow("[ignored]")}`)
+      .join(", ");
+    console.log(`Property files: ${rendered}`);
+  }
+
+  if (summary.length === 0) {
+    console.log(color.dim("No env vars discovered for this repo."));
+    return;
+  }
+  console.log(`Env vars for repo ${color.dim(gitId)}:`);
+  for (const s of summary) {
+    const set = s.has_user_value ? color.green(" [set]") : "";
+    const src = s.chosen_source_file ? color.dim(` from ${s.chosen_source_file}`) : "";
+    const appears = s.appears_in > 1
+      ? color.yellow(` (appears in ${s.appears_in} files)`)
+      : (s.appears_in === 1 ? color.dim(" (1 file)") : "");
+    console.log(`  - ${color.bold(s.key)}${set}${src}${appears}`);
+    if (s.appears_in > 1) {
+      for (const c of s.candidates) {
+        const shown = c.value == null ? color.dim("(empty)") : c.value;
+        const marker = c.is_current ? color.green("  [current]") : "";
+        console.log(`      ${color.dim("•")} ${c.source_file}: ${shown}${marker}`);
+      }
+    }
+  }
+}
+
+/**
+ * --set-env-from KEY=FILE (repeatable). Adopt the value a specific committed file
+ * carries for KEY: set the var's user_value to that file's value and point its
+ * source_file at the chosen file, then PUT the legacy env-var array.
+ *
+ * HARD ERROR (no PUT for ANY key) when KEY is not present in FILE — we validate
+ * every pair against the preview's varsByFile BEFORE mutating anything, so a typo
+ * fails fast with zero server side effects. NEVER echoes a VALUE — prints only
+ * "KEY <- file".
+ */
+async function setEnvFrom(projectId, gitId, pairs, opts) {
+  const parsed = [];
+  for (const pair of pairs) {
+    const eq = pair.indexOf("=");
+    if (eq <= 0) {
+      throw new Error(`--set-env-from expects KEY=FILE (got "${maskPair(pair)}").`);
+    }
+    parsed.push({ key: pair.slice(0, eq).trim(), file: pair.slice(eq + 1).trim() });
+  }
+
+  const preview = await fetchPreview(projectId, gitId, opts);
+  const varsByFile = preview.varsByFile;
+
+  // Validate ALL pairs first — a single missing KEY-in-FILE aborts with NO PUT.
+  const resolved = [];
+  for (const { key, file } of parsed) {
+    const entries = varsByFile[file];
+    if (!Array.isArray(entries)) {
+      const known = Object.keys(varsByFile).sort();
+      const list = known.length ? `\n  Files with discovered vars:\n${known.map((f) => `    - ${f}`).join("\n")}` : "";
+      throw new Error(`--set-env-from: file "${file}" has no discovered env vars for this repo.${list}`);
+    }
+    const match = entries.find((e) => e && e.key === key);
+    if (!match) {
+      throw new Error(`--set-env-from: key "${key}" is not present in "${file}". Pick a file that defines ${key} (see niro edit --list-env).`);
+    }
+    resolved.push({ key, file, value: pickResolved(match) });
+  }
+
+  // Merge over the project's currently-stored env vars so we don't drop any.
+  const byKey = new Map();
+  for (const v of preview.currentDiscoveredEnvVars) {
+    if (v && v.key) byKey.set(v.key, { ...v });
+  }
+  const changed = [];
+  for (const { key, file, value } of resolved) {
+    const existing = byKey.get(key) || { key };
+    existing.user_value = value;
+    existing.source_file = file;
+    byKey.set(key, existing);
+    changed.push({ key, source_file: file });
+  }
+
+  const envVars = Array.from(byKey.values());
+  await api.put(
+    `/api/projects/${encodeURIComponent(projectId)}/git/${encodeURIComponent(gitId)}/env-vars`,
+    envVars,
+    { apiUrl: opts.apiUrl }
+  );
+
+  if (opts.json) {
+    console.log(JSON.stringify({ project_id: projectId, git_id: gitId, changed }));
+  } else {
+    for (const c of changed) {
+      console.log(`${color.green("✓")} ${color.bold(c.key)} ${color.dim("<-")} ${c.source_file}`);
+    }
+  }
+}
+
+/**
+ * --active-files <a,b,c>: choose which discovered PROPERTY FILES Niro considers for
+ * env-var default values (the rest are ignored). Mirrors the web UI's file-selection
+ * step. The server persists the selection via SaveEnvVarsRequest.active_properties_files
+ * (GitProperties.setActivePropertiesFiles).
+ *
+ * Validation: each named file is checked against the discovered property files
+ * (Object.keys(varsByFile)). An UNKNOWN name is WARNed (listing the known files) and
+ * excluded — we proceed with the valid subset. If NONE of the named files match, we
+ * HARD ERROR (no PUT) rather than silently wiping the selection.
+ *
+ * At least one file is REQUIRED. By default all discovered property files are active,
+ * and an empty active set is indistinguishable from that default on the wire (both
+ * serialize to []), so "ignore all" can't be a durable state — an empty list errors.
+ *
+ * Prints only the chosen FILE NAMES — never any value.
+ */
+async function setActiveFiles(projectId, filesCsv, opts) {
+  const gitId = await resolveRepo(projectId, opts);
+  const preview = await fetchPreview(projectId, gitId, opts);
+  const known = Object.keys(preview.varsByFile || {});
+  const knownSet = new Set(known);
+
+  const requested = String(filesCsv == null ? "" : filesCsv)
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+
+  // At least one file is required. An empty active set is indistinguishable from the
+  // server's never-configured default (both serialize to []), so it can't represent a
+  // durable "ignore all" — and by default all property files are active anyway.
+  if (requested.length === 0) {
+    throw new Error("--active-files: name at least one property file to keep active (the others are ignored). By default all are active; see niro edit --list-env.");
+  }
+
+  const valid = [];
+  const unknown = [];
+  for (const f of requested) {
+    if (knownSet.has(f)) valid.push(f);
+    else unknown.push(f);
+  }
+
+  if (unknown.length) {
+    const list = known.length ? known.slice().sort().map((f) => `    - ${f}`).join("\n") : "    (none)";
+    console.error(`${color.yellow("⚠")} Unknown property file(s) ignored: ${unknown.join(", ")}\n  Discovered property files:\n${list}`);
+  }
+
+  if (valid.length === 0) {
+    throw new Error(`--active-files: none of [${requested.join(", ")}] match a discovered property file. See niro edit --list-env.`);
+  }
+
+  // dedup, preserve first-seen order.
+  const active = [...new Set(valid)];
+
+  await api.put(
+    `/api/projects/${encodeURIComponent(projectId)}/git/${encodeURIComponent(gitId)}/env-vars`,
+    { env_vars: preview.currentDiscoveredEnvVars, active_properties_files: active },
+    { apiUrl: opts.apiUrl }
+  );
+
+  if (opts.json) {
+    console.log(JSON.stringify({ project_id: projectId, git_id: gitId, active_properties_files: active }));
+  } else {
+    console.log(`${color.green("✓")} Active property files: ${active.join(", ")}  ${color.dim("(others ignored for env-var defaults)")}`);
+  }
+}
+
+/**
+ * GET the env-var preview and normalise it to a stable, snake/camel-tolerant shape.
+ * Reused by setEnv, setEnvFrom, listEnv, and init's prompt.
+ */
+async function fetchPreview(projectId, gitId, opts = {}) {
+  const preview = await api.get(
+    `/api/projects/${encodeURIComponent(projectId)}/git/${encodeURIComponent(gitId)}/env-vars/preview`,
+    { apiUrl: opts.apiUrl }
+  );
+  const p = preview || {};
+  return {
+    varsByFile: p.vars_by_file || p.varsByFile || {},
+    activePropertiesFiles: p.active_properties_files || p.activePropertiesFiles || [],
+    currentDiscoveredEnvVars: p.current_discovered_env_vars || p.currentDiscoveredEnvVars || [],
+    raw: p,
+  };
+}
+
+/**
+ * Normalise an active-properties-files filter to a Set, or null when there is no
+ * filter (empty/absent => "all files active"). Accepts an array or a Set.
+ */
+function toActiveSet(activeFiles) {
+  if (!activeFiles) return null;
+  const arr = activeFiles instanceof Set ? [...activeFiles] : (Array.isArray(activeFiles) ? activeFiles : []);
+  const cleaned = arr.map((f) => (f == null ? "" : String(f))).filter((f) => f !== "");
+  return cleaned.length ? new Set(cleaned) : null;
+}
+
+/** snake/camel-tolerant resolved-value accessor for a DiscoveredEnvVar. */
+function pickResolved(v) {
+  if (!v) return null;
+  if (v.resolvedValue !== undefined) return v.resolvedValue;
+  if (v.resolved_value !== undefined) return v.resolved_value;
+  return null;
+}
+
+/**
+ * Reconstruct the per-var CANDIDATES from varsByFile — exactly as the UI's
+ * EnvVarsRepoSection does: loop every file, collect each entry that matches `key`,
+ * and record {source_file, value}. Dedup identical (file,value) pairs.
+ *
+ * `current` may be a source-file string OR the current DiscoveredEnvVar object.
+ * is_current marks the candidate whose file matches the var's current source_file;
+ * is_default best-effort marks the candidate whose value matches the var's current
+ * resolved value. We do NOT try to fix Spring-profile precedence here (out of
+ * scope) — these are labels, not a re-resolution.
+ *
+ * `activeFiles` (optional, array or Set): when provided AND non-empty, only files
+ * in that set contribute candidates — this mirrors the web UI's "choose which
+ * property files to consider" selection (ignored files contribute no defaults). An
+ * EMPTY or absent active set means "all files active" (consider everything) — the
+ * original behaviour.
+ */
+function buildCandidates(varsByFile, key, current, activeFiles) {
+  const cur = current && typeof current === "object" ? current : { source_file: current };
+  const curSource = cur.source_file || cur.sourceFile || null;
+  const curResolved = pickResolved(cur);
+
+  // Normalise the active-file filter. Empty/absent = no filter (include all).
+  const activeSet = toActiveSet(activeFiles);
+
+  const seen = new Set();
+  const candidates = [];
+  for (const [file, vars] of Object.entries(varsByFile || {})) {
+    if (activeSet && !activeSet.has(file)) continue;
+    if (!Array.isArray(vars)) continue;
+    for (const v of vars) {
+      if (!v || v.key !== key) continue;
+      const value = pickResolved(v);
+      const sig = `${file}${value == null ? "" : String(value)}`;
+      if (seen.has(sig)) continue;
+      seen.add(sig);
+      candidates.push({ source_file: file, value: value == null ? null : value });
+    }
+  }
+  candidates.sort((a, b) => String(a.source_file).localeCompare(String(b.source_file)));
+  for (const c of candidates) {
+    c.is_current = curSource != null && c.source_file === curSource;
+    c.is_default = curResolved !== null && curResolved !== undefined && c.value === curResolved;
+  }
+  return candidates;
+}
+
+/**
+ * Build a per-var view (key, chosen source file, candidates) for listing. Secret
+ * candidate values are masked via secret.js so no plaintext secret ever reaches
+ * stdout or JSON.
+ */
+function summarizeEnvVars(preview) {
+  const current = preview.currentDiscoveredEnvVars;
+  const varsByFile = preview.varsByFile;
+  // Only the ACTIVE property files drive candidate values — mirrors the web UI's
+  // "choose which property files to consider" selection. Empty/absent = all active.
+  const activeFiles = preview.activePropertiesFiles;
+  return current.map((v) => {
+    const key = v.key;
+    const keySecret = isSecretKey(key);
+    // Mask a candidate value when the KEY name looks secret OR the VALUE itself
+    // embeds credentials (e.g. DATABASE_URL=postgres://u:p@h). Full "****" mask:
+    // unlike a UI there's no correlation benefit to revealing the last few chars.
+    const candidates = buildCandidates(varsByFile, key, v, activeFiles).map((c) => {
+      const hide = keySecret || looksSecretValue(c.value);
+      const hasValue = c.value !== null && c.value !== undefined && c.value !== "";
+      return {
+        source_file: c.source_file,
+        value: hide && hasValue ? "****" : c.value,
+        masked: hide && hasValue,
+        is_current: c.is_current,
+        is_default: c.is_default,
+      };
+    });
+    return {
+      key,
+      chosen_source_file: v.source_file || v.sourceFile || null,
+      has_user_value: Boolean(v.user_value || v.userValue),
+      has_resolved_value: Boolean(v.resolved_value || v.resolvedValue),
+      // secret if the key name is secret OR any candidate value was masked.
+      is_secret: keySecret || candidates.some((c) => c.masked),
+      appears_in: candidates.length,
+      candidates,
+    };
+  });
+}
+
+async function rescanEnv(projectId, opts) {
+  const gitId = await resolveRepo(projectId, opts);
+  const resolved = await api.post(
+    `/api/projects/${encodeURIComponent(projectId)}/git/${encodeURIComponent(gitId)}/env-vars/rescan`,
+    {},
+    { apiUrl: opts.apiUrl }
+  );
+  const count = Array.isArray(resolved) ? resolved.length : 0;
+  console.log(`${color.green("✓")} Rescanned env vars for repo ${color.dim(gitId)} — ${count} discovered (user values preserved).`);
+}
+
+/** Mask the VALUE part of a KEY=VALUE pair when echoing a parse error. */
+function maskPair(pair) {
+  const eq = pair.indexOf("=");
+  if (eq < 0) return pair;
+  return pair.slice(0, eq + 1) + "****";
+}
+
+function printUsage() {
+  console.error("niro edit — change an existing project. At least one action is required:");
+  console.error("  --add-repo <gitId>        map a registered repo to the project");
+  console.error("  --remove-repo <gitId>     unmap a repo (non-destructive)");
+  console.error("  --set-env KEY=VALUE       set an env var (repeatable; value never printed)");
+  console.error("  --set-env-from KEY=FILE   adopt the value FILE carries for KEY (repeatable; value never printed)");
+  console.error("  --active-files <files>    property files to keep active for env-var defaults; the rest are ignored (default: all)");
+  console.error("  --list-env               list env var keys + per-file candidates (secret values masked)");
+  console.error("  --rescan-env             rescan the repo for env vars");
+  console.error("  --alias <newAlias>       rename the project");
+  console.error("Target project: --project <alias|id>, or a .niro-project pin in this folder.");
+  console.error("Env actions target --repo <gitId> (auto-selected when the project has one repo).");
+}
+
+// resolveRepo is exported for unit testing the multi-repo folder-matching logic.
+// fetchPreview/buildCandidates/setEnvFrom are exported for tests and for reuse by
+// init's env-var prompt (source-file parity with the web UI).
+module.exports = { edit, resolveRepo, fetchPreview, buildCandidates, setEnvFrom, setActiveFiles, summarizeEnvVars, listEnv };