@niroai/niro 0.3.0

package/src/commands/login.js

@@ -0,0 +1,214 @@
+/**
+ * `niro login` — acquire credentials and store at ~/.niro/credentials.json.
+ *
+ * Modes:
+ *   1. Device flow (DEFAULT): POST /api/public/auth/device-code → open browser
+ *      → poll /api/public/auth/device-token. On success the returned
+ *      niro_api_key is the durable per-device CLI token, stored as creds.cliToken
+ *      so the short-lived JWT can be refreshed transparently.
+ *   2. --password: email + password → POST /api/auth/access-token.
+ *   3. --api-key: paste a Niro API key → POST /api/public/auth/api-key-login.
+ *
+ * The device-flow path is gated behind a capability probe (checks whether
+ * /api/public/auth/device-code returns 200 vs 404/405). When unavailable, it
+ * falls back to the API key flow.
+ */
+const api = require("../lib/api");
+const credentials = require("../lib/credentials");
+const prompt = require("../lib/prompt");
+const browser = require("../lib/browser");
+const spinner = require("../lib/spinner");
+const color = require("../lib/color");
+
+const DEFAULT_POLL_INTERVAL_SECONDS = 5;
+const DEFAULT_EXPIRY_SECONDS = 600;
+
+async function login(opts = {}) {
+  const apiUrl = (opts.apiUrl || process.env.NIRO_API_URL || api.DEFAULT_API_URL).replace(/\/$/, "");
+
+  if (opts.password) {
+    return loginWithPassword({ apiUrl, email: opts.email });
+  }
+  if (opts.apiKey) {
+    return loginWithApiKey({ apiUrl });
+  }
+
+  const deviceFlowAvailable = await probeDeviceFlow(apiUrl);
+  if (deviceFlowAvailable) {
+    return loginWithDeviceFlow({ apiUrl });
+  }
+
+  console.log("Device flow not available on this server — falling back to API key login.");
+  return loginWithApiKey({ apiUrl });
+}
+
+async function loginWithApiKey({ apiUrl }) {
+  console.log(`Connecting to ${color.cyan(apiUrl)}\n`);
+  console.log(
+    `Enter your Niro API key. You can find it in the Niro dashboard under Settings → API Keys.\n`
+  );
+
+  const apiKey = await prompt.askHidden("API key");
+  if (!apiKey) {
+    console.error("API key is required.");
+    process.exitCode = 1;
+    return;
+  }
+
+  const sp = spinner.start("Authenticating...");
+  try {
+    const data = await api.post(
+      "/api/public/auth/api-key-login",
+      { api_key: apiKey },
+      { apiUrl, noAuth: true, skipRefresh: true }
+    );
+
+    const token = data.token;
+    const niroApiKey = data.niro_api_key || data.niroApiKey || apiKey;
+    if (!token) {
+      sp.stop(color.red("✗") + " Server did not return a token. Check your API key.");
+      process.exitCode = 1;
+      return;
+    }
+
+    credentials.save({
+      apiUrl,
+      token,
+      niroApiKey,
+      email: data.email || null,
+      userId: data.user_id || data.userId || null,
+    });
+
+    sp.stop(`${color.green("✓")} Logged in successfully.`);
+  } catch (err) {
+    if (err.status === 401) {
+      sp.stop(color.red("✗") + " Invalid API key.");
+      process.exitCode = 1;
+      return;
+    }
+    sp.stop(color.red("✗") + " Login failed.");
+    throw err;
+  }
+}
+
+async function loginWithPassword({ apiUrl, email }) {
+  const emailAnswer = email || (await prompt.ask("Email"));
+  if (!emailAnswer) {
+    console.error("Email is required.");
+    process.exitCode = 1;
+    return;
+  }
+  const password = await prompt.askHidden("Password");
+  if (!password) {
+    console.error("Password is required.");
+    process.exitCode = 1;
+    return;
+  }
+
+  const data = await api.post(
+    "/api/auth/access-token",
+    { email_or_phone_number: emailAnswer, password },
+    { apiUrl }
+  );
+
+  const token = data.token || data.access_token;
+  const niroApiKey = data.niro_api_key || data.niroApiKey || null;
+  if (!token) {
+    throw new Error("Server did not return a token. Check your credentials.");
+  }
+
+  credentials.save({
+    apiUrl,
+    token,
+    niroApiKey,
+    email: emailAnswer,
+    userId: data.user_id || data.userId || null,
+  });
+
+  console.log(`${color.green("✓")} Logged in as ${color.bold(emailAnswer)}`);
+}
+
+async function probeDeviceFlow(apiUrl) {
+  try {
+    await api.post("/api/public/auth/device-code", {}, { apiUrl, noAuth: true, skipRefresh: true });
+    return true;
+  } catch (err) {
+    if (err.status === 404 || err.status === 405) return false;
+    // Other 4xx (e.g. a 429 rate limit, or a real body) mean the endpoint IS there.
+    if (err.status && err.status >= 400 && err.status < 500) return true;
+    return false;
+  }
+}
+
+async function loginWithDeviceFlow({ apiUrl }) {
+  const resp = await api.post(
+    "/api/public/auth/device-code",
+    { client_id: "niro-cli" },
+    { apiUrl, noAuth: true, skipRefresh: true }
+  );
+  const userCode = resp.user_code || resp.userCode;
+  const deviceCode = resp.device_code || resp.deviceCode;
+  const verificationUri = resp.verification_uri_complete || resp.verificationUriComplete
+    || resp.verification_uri || resp.verificationUri;
+  const interval = Number(resp.interval || DEFAULT_POLL_INTERVAL_SECONDS);
+  const expiresIn = Number(resp.expires_in || resp.expiresIn || DEFAULT_EXPIRY_SECONDS);
+
+  if (!userCode || !deviceCode || !verificationUri) {
+    throw new Error("Server did not return a complete device-code payload.");
+  }
+
+  console.log(`\n  Your one-time code: ${color.bold(color.cyan(userCode))}`);
+  console.log(`  Open: ${color.cyan(verificationUri)}\n`);
+  browser.open(verificationUri);
+
+  const sp = spinner.start("Waiting for browser approval...");
+  const deadline = Date.now() + expiresIn * 1000;
+  try {
+    while (Date.now() < deadline) {
+      await sleep(interval * 1000);
+      try {
+        const tokenResp = await api.post(
+          "/api/public/auth/device-token",
+          { device_code: deviceCode },
+          { apiUrl, noAuth: true, skipRefresh: true }
+        );
+        const token = tokenResp.token || tokenResp.access_token;
+        if (token) {
+          const email = (tokenResp.user && tokenResp.user.email) || tokenResp.email || null;
+          const cliToken = tokenResp.niro_api_key || tokenResp.niroApiKey || null;
+          sp.stop(`${color.green("✓")} Logged in${email ? ` as ${color.bold(email)}` : ""}.`);
+          credentials.save({
+            apiUrl,
+            token,
+            cliToken,
+            niroApiKey: cliToken,
+            email,
+            userId: (tokenResp.user && tokenResp.user.id) || tokenResp.user_id || tokenResp.userId || null,
+          });
+          return;
+        }
+      } catch (err) {
+        if (isPending(err)) continue;
+        throw err;
+      }
+    }
+    sp.stop(`${color.red("✗")} Login timed out. Run ${color.cyan("niro login")} to try again.`);
+    process.exitCode = 1;
+  } finally {
+    sp.stop();
+  }
+}
+
+function isPending(err) {
+  const body = err.body;
+  if (!body) return false;
+  const code = typeof body === "string" ? body : body.error || body.message;
+  if (typeof code !== "string") return false;
+  return /authorization[_-]?pending/i.test(code) || /slow[_-]?down/i.test(code);
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+module.exports = { login };

package/src/commands/logout.js

@@ -0,0 +1,33 @@
+/**
+ * `niro logout` — revoke the durable CLI token server-side (best-effort) and
+ * remove locally stored credentials.
+ *
+ * The revoke endpoint is public and authenticates via the cli_token in the body,
+ * so it works even after the short-lived JWT has expired. Network errors are
+ * swallowed so the local credential clear always proceeds.
+ */
+const api = require("../lib/api");
+const credentials = require("../lib/credentials");
+
+async function logout() {
+  const creds = credentials.load();
+  const cliToken = creds && (creds.cliToken || creds.niroApiKey);
+  const apiUrl = (creds && creds.apiUrl) || api.DEFAULT_API_URL;
+
+  if (cliToken) {
+    try {
+      await api.post(
+        "/api/public/auth/cli-token/revoke",
+        { cli_token: cliToken },
+        { apiUrl, noAuth: true, skipRefresh: true }
+      );
+    } catch {
+      // Best-effort revoke: never block local logout on a network/server error.
+    }
+  }
+
+  const removed = credentials.clear();
+  console.log(removed ? "Credentials removed." : "No credentials file found.");
+}
+
+module.exports = { logout };

package/src/commands/mcp.js

@@ -0,0 +1,40 @@
+/**
+ * `niro mcp install` / `niro mcp uninstall` / `niro mcp serve` — drive the in-package MCP server.
+ *
+ * install():   spawn the bundled editor-config wizard as a child so it can prompt.
+ * uninstall(): spawn the teardown wizard — the exact inverse of install.
+ * serve():     run the in-package stdio bridge directly in this process so the
+ *              editor's MCP stdio talks straight to it.
+ */
+const path = require("path");
+const { spawn } = require("child_process");
+
+/** Spawn a bundled wizard (setup.js / teardown.js) as a child so it can prompt on the TTY. */
+function runWizard(scriptName, label) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(
+      process.execPath,
+      [path.join(__dirname, "..", "mcp", scriptName), ...process.argv.slice(4)],
+      { stdio: "inherit" }
+    );
+    child.on("error", reject);
+    child.on("exit", (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`MCP ${label} wizard exited with code ${code}`));
+    });
+  });
+}
+
+async function install() {
+  return runWizard("setup.js", "setup");
+}
+
+async function uninstall() {
+  return runWizard("teardown.js", "uninstall");
+}
+
+function serve() {
+  require("../mcp/server");
+}
+
+module.exports = { install, uninstall, serve };

package/src/commands/projects.js

@@ -0,0 +1,76 @@
+/**
+ * `niro projects` — list the projects in the caller's account.
+ *
+ * Backed by GET /api/projects (account-scoped server-side: it returns only the
+ * authenticated user's account's projects). This is the account-wide list, NOT
+ * tied to the current folder — use `niro info` for "which project is THIS repo".
+ * Useful for the agent's "add this repo to an EXISTING project" flow, where it
+ * needs to show the user their projects to pick an alias.
+ *
+ * Never logs secrets.
+ */
+const api = require("../lib/api");
+const credentials = require("../lib/credentials");
+const color = require("../lib/color");
+
+/**
+ * Normalize the GET /api/projects payload into rows and sort them by alias
+ * (case-insensitive), falling back to project_id. Defensive about field-name
+ * shapes (snake_case from the API, camelCase just in case). Pure + testable.
+ */
+function projectsToRows(data) {
+  const list = Array.isArray(data) ? data : (data && Array.isArray(data.projects) ? data.projects : []);
+  return list
+    .map((p) => {
+      if (!p || typeof p !== "object") return null;
+      const projectId = p.project_id || p.projectId || p.id || null;
+      if (!projectId) return null;
+      return {
+        project_id: projectId,
+        alias: p.alias || p.name || null,
+        repo_count: p.repo_count != null ? p.repo_count : (p.repoCount != null ? p.repoCount : 0),
+        created_at: p.created_at != null ? p.created_at : (p.createdAt != null ? p.createdAt : null),
+      };
+    })
+    .filter(Boolean)
+    .sort((a, b) => {
+      const ka = (a.alias || a.project_id).toLowerCase();
+      const kb = (b.alias || b.project_id).toLowerCase();
+      return ka < kb ? -1 : ka > kb ? 1 : 0;
+    });
+}
+
+/** Format an epoch-millis timestamp as a plain YYYY-MM-DD, or "" when absent. */
+function fmtDate(createdAt) {
+  if (createdAt == null) return "";
+  const n = Number(createdAt);
+  if (!Number.isFinite(n) || n <= 0) return "";
+  return new Date(n).toISOString().slice(0, 10);
+}
+
+async function projects(opts = {}) {
+  credentials.requireCreds();
+  const data = await api.get("/api/projects", { apiUrl: opts.apiUrl });
+  const rows = projectsToRows(data);
+
+  if (opts.json) {
+    console.log(JSON.stringify({ projects: rows }));
+    return;
+  }
+
+  if (rows.length === 0) {
+    console.log("No projects in your account yet. Run `niro init` to create one.");
+    return;
+  }
+
+  console.log(color.dim(`${rows.length} project${rows.length === 1 ? "" : "s"} in your account:`));
+  for (const r of rows) {
+    const name = color.bold(r.alias || "(no alias)");
+    const repos = `${r.repo_count} repo${r.repo_count === 1 ? "" : "s"}`;
+    const created = fmtDate(r.created_at);
+    const meta = [repos, created].filter(Boolean).join(", ");
+    console.log(`  ${name}  ${color.dim(r.project_id)}  ${color.dim("— " + meta)}`);
+  }
+}
+
+module.exports = { projects, projectsToRows, fmtDate };

package/src/commands/release.js

@@ -0,0 +1,175 @@
+/**
+ * `niro discard-temp-project [path]` — delete the temporary project created by `niro new-temp-project`
+ * (ADR-013, routing per ADR-018). Run after your local branch is merged: the original project's remote
+ * poller picks up the merged commits by itself, so the temporary project has served its purpose.
+ *
+ * ADR-018: the `.niro-project` pin is normally NOT touched (new-style takeovers never changed it —
+ * server-side routing simply falls back to the source project once the temp project is gone). The ONLY
+ * pin writes left are TRANSITIONAL healing for folders taken over by a pre-ADR-018 CLI, whose pin was
+ * swapped to the temp project and would otherwise dangle at a deleted id.
+ *
+ * Discard guard (ADR-018): a temp project can cover SEVERAL repos (one per feature in flight). Deleting
+ * it kills coverage for ALL of them — so before deleting, every registered folder's CURRENT branch is
+ * compared against its recorded source branch, and still-diverged folders trigger a confirmation
+ * (or a hard refusal when non-interactive without --yes).
+ *
+ * Safety: the server refuses to release anything that is not a temporary project, so this can never delete
+ * a real project even if asked to.
+ */
+const api = require("../lib/api");
+const color = require("../lib/color");
+const git = require("../lib/git");
+const niroProjectFile = require("../lib/niroProjectFile");
+const prompt = require("../lib/prompt");
+const watchState = require("../lib/watchState");
+
+const ok = (s) => color.green(s);
+const warn = (s) => color.yellow(s);
+
+async function release(pathArg, opts = {}) {
+  // See takeover: --api-url isn't threaded through the release POST, so honoring it would act on
+  // the wrong stack. Fail fast rather than silently release against the default backend.
+  if (opts.apiUrl) {
+    throw new Error("`--api-url` is not supported for `niro discard-temp-project` yet. " +
+        "Select the backend with `niro login` / your config first, then run this without --api-url.");
+  }
+  const path = require("path");
+  const fs = require("fs");
+  const targetDir = path.resolve(pathArg || process.cwd());
+  git.inspect(targetDir); // validates the path; repoRoot itself is no longer needed for pinning
+
+  // Resolve WHICH temp project to discard. ADR-018: the pin no longer points at it (it stays on the
+  // source), so the primary lookup is this folder's watchState registration (written by takeover).
+  // Fallbacks: an explicit --project id (escape hatch when the local registration is lost — daemon
+  // reinstalled, second machine, backend switched; review MAJOR: without it discard dead-ended with
+  // a misleading error), then an old-style folder whose pin still holds the temp-project id.
+  const baseUrl = api.currentBaseUrl();
+  const entry = watchState.get(targetDir, baseUrl);
+  let tempProjectId = opts.project || (entry && entry.takeover ? entry.projectId : null);
+  if (!tempProjectId) {
+    const pinned = niroProjectFile.read(targetDir);
+    if (pinned) tempProjectId = pinned.id;
+  }
+  if (!tempProjectId) {
+    throw new Error("No local record of a temporary project for this folder. " +
+        "If you created one elsewhere (another machine, a reinstalled daemon), pass its id explicitly: " +
+        "`niro discard-temp-project --project <temp-project-id>`. The server refuses to delete anything " +
+        "that is not a temporary project, so this is always safe.");
+  }
+  const project = await api.get(`/api/projects/${encodeURIComponent(tempProjectId)}`);
+  const cloneOf = project.clone_of_project_id || project.cloneOfProjectId;
+  if (!cloneOf) {
+    throw new Error(`Project ${tempProjectId} is not a temporary project — refusing. ` +
+        "(discard only deletes projects created by `niro new-temp-project`)");
+  }
+
+  // Every folder registered against this temp project (multi-repo takeover, ADR-016).
+  const currentDir = path.resolve(targetDir);
+  const folders = watchState.allLocal(baseUrl).filter((e) => e.projectId === tempProjectId);
+  if (!folders.some((e) => path.resolve(e.folderPath) === currentDir)) {
+    folders.push({ folderPath: targetDir, ...(entry || {}) });
+  }
+
+  // ADR-018 discard guard: deleting the temp project kills coverage for EVERY repo in it. Check each
+  // folder's CURRENT branch against its recorded source branch; a folder still on a feature branch is
+  // in-flight work whose coverage this discard would destroy. Old entries without sourceBranch can't be
+  // verified client-side (the server-side nudge guard still covers the agent-driven path).
+  const stillDiverged = [];
+  for (const e of folders) {
+    const sourceBranch = e.takeover && e.takeover.sourceBranch;
+    if (!sourceBranch || !fs.existsSync(e.folderPath)) continue;
+    try {
+      const cur = git.inspect(e.folderPath).branch;
+      if (cur && cur !== sourceBranch) {
+        stillDiverged.push({ folder: e.folderPath, branch: cur, sourceBranch });
+      }
+    } catch { /* can't inspect — don't block on it */ }
+  }
+  if (stillDiverged.length) {
+    console.log(warn(`\n  ⚠ This temporary project still covers in-flight work:`));
+    for (const d of stillDiverged) {
+      console.log(warn(`    ${d.folder} is on \`${d.branch}\` (source: \`${d.sourceBranch}\`)`));
+    }
+    console.log(warn("  Discarding deletes the WHOLE temporary project — those repos lose their coverage" +
+        " until you run `niro new-temp-project` there again (local code is untouched)."));
+    if (!opts.yes) {
+      if (!process.stdout.isTTY || prompt.isNonInteractive()) {
+        throw new Error("Refusing to discard: repos listed above are still on feature branches. " +
+            "Re-run with --yes to discard anyway, or discard after they are merged.");
+      }
+      const sure = await prompt.confirm("Discard anyway?");
+      if (!sure) {
+        console.log("Aborted.");
+        return;
+      }
+    }
+  } else if (process.stdout.isTTY && !opts.yes) {
+    const sure = await prompt.confirm(
+      `Discard temporary project ${color.bold(project.alias || tempProjectId)}?`);
+    if (!sure) {
+      console.log("Aborted.");
+      return;
+    }
+  }
+
+  await api.post(`/api/projects/${encodeURIComponent(tempProjectId)}/clone/release`, {});
+
+  // Restore each folder's local registration. ADR-018: the .niro-project file is left ALONE unless it
+  // still carries the OLD-STYLE swapped pin (pre-ADR-018 takeover) — then it points at a now-deleted
+  // project and must be healed: previousPin verbatim when recorded; explicit "no pin existed" → delete
+  // the file; otherwise the source project id. New-style folders (pin untouched) skip all of this.
+  const repinned = [];
+  const healed = [];
+  const failed = [];
+  for (const e of folders) {
+    try {
+      const backup = e.takeover || {};
+      const sourceProjectId = backup.sourceProjectId || cloneOf;
+      const entryDir = path.resolve(e.folderPath);
+
+      if (fs.existsSync(entryDir)) {
+        const pin = niroProjectFile.read(entryDir);
+        const pinIsSwapped = pin && pin.id === tempProjectId
+            && path.dirname(pin.source) === entryDir; // only heal THIS folder's own pin, never a parent's
+        if (pinIsSwapped) {
+          const recordedNoPin = ("previousPin" in backup) && backup.previousPin === null;
+          if (backup.previousPin) {
+            niroProjectFile.write(entryDir, backup.previousPin, { overwrite: true });
+            healed.push({ folder: e.folderPath, to: backup.previousPin });
+          } else if (recordedNoPin) {
+            niroProjectFile.remove(entryDir);
+            healed.push({ folder: e.folderPath, to: "(no pin — removed)" });
+          } else {
+            niroProjectFile.write(entryDir, sourceProjectId, { overwrite: true });
+            healed.push({ folder: e.folderPath, to: sourceProjectId });
+          }
+        }
+      }
+
+      // Watch/daemon registration goes back to the source project regardless of pin style.
+      watchState.set(e.folderPath, {
+        ...e,
+        gitId: backup.previousGitId || null,
+        projectId: sourceProjectId,
+        takeover: undefined,
+      }, e.apiUrl || baseUrl);
+      repinned.push(e.folderPath);
+    } catch (err) {
+      failed.push({ folder: e.folderPath, error: err.message });
+    }
+  }
+
+  console.log(`\n  ${ok("✓")} Temporary project discarded. Niro routes back to the original project automatically.`);
+  if (healed.length) {
+    console.log(color.dim("  Healed old-style pins:"));
+    for (const h of healed) console.log(color.dim(`    ${h.folder} → ${h.to}`));
+  }
+  if (failed.length) {
+    console.log(warn(`\n  ⚠ ${failed.length} folder(s) could not be restored locally (the temporary project` +
+        " is already gone server-side):"));
+    for (const f of failed) console.log(color.dim(`    ${f.folder} — ${f.error}`));
+  }
+  console.log(color.dim("  The original project picks up your merged commits via its normal remote polling."));
+}
+
+module.exports = { release };

package/src/commands/remove.js

@@ -0,0 +1,95 @@
+/**
+ * `niro remove` — remove either a whole project or a single repo mapping.
+ *
+ * Exactly one mode is required:
+ *   --project                delete the WHOLE project (DESTRUCTIVE) and unpin
+ *                            the local .niro-project. Reuses delete.js cleanup.
+ *                            DELETE /api/projects/{projectId}
+ *   --unmap-repo <gitId>     remove THIS repo from the project (non-destructive;
+ *                            the repo registration itself is kept).
+ *                            DELETE /api/projects/{projectId}/git/{gitId}
+ *
+ * Target project resolution: --project flag is a *mode*, not the id selector.
+ * The project is resolved via resolveProjectId from --target <alias|id> or the
+ * .niro-project pin (same precedence as status/build/delete).
+ *
+ * DESTRUCTIVE BACKSTOP (required for --project): --confirm-name <value> MUST
+ * equal the project's alias OR its project_id. If it doesn't match (or is
+ * missing), we refuse and delete nothing. This is a CLI-level guard, independent
+ * of any agent-side confirmation. --unmap-repo does not need the name guard but
+ * still requires the explicit gitId flag.
+ */
+const api = require("../lib/api");
+const credentials = require("../lib/credentials");
+const color = require("../lib/color");
+const { resolveProjectId } = require("./_resolveProject");
+const { unpinIfMatches } = require("./delete");
+
+async function remove(opts = {}) {
+  const wholeProject = Boolean(opts.project);
+  const unmapRepo = opts.unmapRepo || null;
+
+  // Exactly one mode.
+  const modes = [wholeProject, Boolean(unmapRepo)].filter(Boolean);
+  if (modes.length === 0) {
+    printUsage();
+    process.exitCode = 1;
+    return;
+  }
+  if (modes.length > 1) {
+    console.error(`${color.red("✗")} Choose exactly one: --project OR --unmap-repo <gitId>.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  credentials.requireCreds();
+  const projectId = await resolveProjectId(opts.target, { apiUrl: opts.apiUrl });
+
+  if (unmapRepo) {
+    await api.del(
+      `/api/projects/${encodeURIComponent(projectId)}/git/${encodeURIComponent(unmapRepo)}`,
+      { apiUrl: opts.apiUrl }
+    );
+    console.log(`${color.green("✓")} Unmapped repo ${color.dim(unmapRepo)} from project ${color.dim(projectId)} (repo registration kept).`);
+    return;
+  }
+
+  // --project: destructive. Fetch the project so we can match --confirm-name
+  // against either the alias or the project_id.
+  let alias = null;
+  try {
+    const project = await api.get(`/api/projects/${encodeURIComponent(projectId)}`, { apiUrl: opts.apiUrl });
+    alias = (project && (project.alias)) || null;
+  } catch (err) {
+    // If we can't read the project, fall back to matching the id only.
+    alias = null;
+  }
+
+  const confirm = opts.confirmName == null ? null : String(opts.confirmName).trim();
+  const matches = confirm != null && (confirm === projectId || (alias != null && confirm === alias));
+  if (!matches) {
+    const expected = alias ? `"${alias}" or ${projectId}` : projectId;
+    console.error(`${color.red("✗")} Refusing to delete: --confirm-name must equal the project's name (${expected}).`);
+    if (confirm == null) {
+      console.error(color.dim("   Pass --confirm-name <name> to confirm this destructive delete."));
+    } else {
+      console.error(color.dim(`   You passed --confirm-name "${confirm}", which does not match.`));
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  await api.del(`/api/projects/${encodeURIComponent(projectId)}`, { apiUrl: opts.apiUrl });
+  console.log(`${color.green("✓")} Deleted project ${color.dim(projectId)}${alias ? ` ("${alias}")` : ""}.`);
+  unpinIfMatches(projectId);
+}
+
+function printUsage() {
+  console.error("niro remove — remove a project or a repo mapping. Exactly one mode required:");
+  console.error("  --project                  delete the whole project (DESTRUCTIVE)");
+  console.error("                             requires --confirm-name <project alias or id>");
+  console.error("  --unmap-repo <gitId>       remove one repo from the project (non-destructive)");
+  console.error("Target project: --target <alias|id>, or a .niro-project pin in this folder.");
+}
+
+module.exports = { remove };