@niroai/niro 0.3.0

package/README.md

@@ -0,0 +1,291 @@
+# niro — MCP server + CLI (@niroai/niro)
+
+The command-line tool **and** MCP server for [Niro](https://niroai.dev) — the AI code-intelligence platform.
+
+One package gives you three things:
+
+1. **`niro` CLI** — onboard repos, build the code graph, and manage projects from the terminal.
+2. **A Niro MCP server** — lets an AI assistant answer questions about *your* codebase using Niro's graph. 14 clients supported (Claude Code, Codex, Cursor, VS Code, Windsurf, Gemini CLI, GitHub Copilot CLI, Factory, Goose, OpenCode, Cline, Kiro, Antigravity, Claude Desktop) — see **[docs/connect-your-ai-assistant.md](docs/connect-your-ai-assistant.md)** for the exact command per client.
+3. **Two agent skills** (installed by `niro mcp install`) so you can drive Niro from chat in plain English instead of typing CLI commands:
+   - **`niro-skill`** — answers questions about your code (structure, call chains, blast radius) using the Niro MCP tools.
+   - **`niro-cli`** — runs the CLI for you (onboard, status, rebuild, edit env vars, remove) from a conversation.
+
+> **Two ways to do everything:** every task below shows the **terminal** command *and* how you'd **ask the agent**. Pick whichever you prefer — they call the same code.
+
+> **Working on a feature branch?** Niro indexes one branch per repo, but it follows *your* branch
+> and uncommitted edits through **temporary projects** — see
+> **[docs/working-on-branches.md](docs/working-on-branches.md)** for how that works in plain words.
+
+---
+
+## Install
+
+```bash
+npm install -g @niroai/niro
+niro --version
+```
+
+Requires **Node.js 18+**. Background auto-sync of local folders uses [PM2](https://pm2.keymetrics.io/) — `niro init` offers to install it for you (or run `npm install -g pm2` yourself).
+
+By default the CLI talks to Niro's cloud (`https://aiorchestrator.niroai.dev`) and the MCP server to `https://aiassistant.niroai.dev`. To point at your own instance, set `NIRO_API_URL`, and pass `--url <url>` to `niro mcp install` (or set `NIRO_MCP_SERVER_URL`).
+
+---
+
+## 60-second setup
+
+```bash
+niro login            # opens your browser to approve this device
+cd ~/code/my-service
+niro init             # onboard this folder: create project, upload, build the graph
+niro mcp install      # connect one AI assistant — pick it at the prompt, or pass --client
+```
+
+`niro mcp install` configures **one** assistant per run — pick it at the prompt, or pass `--client <id>`. 14 clients supported; see **[docs/connect-your-ai-assistant.md](docs/connect-your-ai-assistant.md)** for the full list and the exact command for each. Run it once for each assistant you use. The MCP server URL is picked automatically (own instance? pass `--url <url>`). Restart your AI assistant once after, and you're done — ask it about your code, or ask it to run Niro tasks for you.
+
+---
+
+## Scenario 1 — Log in
+
+`niro login` opens a browser, you approve the device, and a long-lived credential is stored at `~/.niro/credentials.json` (mode `0600`). Short-lived tokens refresh automatically.
+
+**Terminal**
+```bash
+niro login                              # browser device flow (default)
+niro whoami                             # who am I logged in as?
+niro logout                             # revoke + remove local credentials
+```
+
+**Ask the agent**
+> "Am I logged in to Niro?" — the agent runs `niro whoami`. If you're not, it will **ask you to run `niro login` yourself** in your terminal (it can't drive a browser sign-in or handle your credentials).
+
+---
+
+## Scenario 2 — Onboard a folder you're working in
+
+`niro init` does the whole thing end-to-end: detect the repo, **upload its source + config files**, create a Niro project, scan for environment variables, build the graph, and (optionally) keep it synced.
+
+**Terminal**
+```bash
+cd ~/code/my-service
+niro init                       # onboard the current folder
+niro init ./api                 # onboard a specific path
+niro init --defaults            # accept discovered defaults, don't prompt
+niro init -X '**/test/**' -F '**/*.spec.ts'   # exclude modules / files
+```
+
+During `init` you'll be asked, **per environment variable**, which value to use — and when a variable is defined in more than one config file you pick which file drives it (see Scenario 6).
+
+**Ask the agent**
+> "Onboard this folder into Niro." The `niro-cli` skill checks auth, runs `niro info` to see if it's already indexed, then runs `niro init` for you and walks you through the env-var values in chat.
+
+**Note for cloud:** Niro indexes your folder by **uploading its files** (it can't read your laptop's disk). Source and committed config files (`package.json`, `pom.xml`, `application.yml`, …) are uploaded; anything in your `.gitignore` (like a real `.env`) is **never** uploaded.
+
+---
+
+## Scenario 3 — "What does Niro know about this folder?"
+
+**Terminal**
+```bash
+niro info                # repo URL, branch, which project(s) map here, index status
+niro info --json         # machine-readable
+niro status              # live build status for the pinned project
+niro status my-service --json
+```
+
+If a folder maps to **more than one** project, `info` lists them and (in the terminal) `build`/`edit`/`remove` ask you to pick one.
+
+**Ask the agent**
+> "What does Niro know about this folder?" / "Is this repo indexed?" — the agent runs `niro info --json` and explains it.
+
+---
+
+## Scenario 4 — See all your projects
+
+**Terminal**
+```bash
+niro projects            # account-wide list (alias: `niro ls`)
+niro projects --json
+```
+
+**Ask the agent**
+> "List my Niro projects." — runs `niro projects --json`.
+
+---
+
+## Scenario 5 — Rebuild the index after changes
+
+**Terminal**
+```bash
+niro build               # full rebuild of the project pinned to this folder
+niro build my-service    # by alias or id
+niro build --no-full-rebuild   # incremental
+niro build --no-watch          # trigger and return immediately
+```
+
+**Ask the agent**
+> "Rebuild the Niro index for this project." — runs `niro build`.
+
+*(If you set up auto-sync in Scenario 8, you rarely need to rebuild by hand.)*
+
+---
+
+## Scenario 6 — Manage environment variables (and pick which file drives each)
+
+Niro discovers env-var **names** from your code and their **default values** from committed config files. When the same variable appears in several files (e.g. `application.yml` vs `application-prod.yml`), you choose which file's value to use — the same as the web UI.
+
+**Terminal**
+```bash
+niro edit --list-env                       # show vars, which file drives each, "appears in N files"
+niro edit --list-env --json                # machine-readable (secret values masked)
+niro edit --set-env PORT=9000              # set a value directly (never printed back)
+niro edit --set-env-from PORT=application-prod.yml   # adopt that file's value for PORT
+niro edit --rescan-env                     # re-scan after adding config files
+```
+
+Secret values are always masked (`****`) — whether the variable *name* looks secret (`DB_PASSWORD`) **or** its *value* embeds credentials (`DATABASE_URL=postgres://user:pass@host`). You pick those by file name; the value is never shown.
+
+**Ask the agent**
+> "Set PORT from application-prod.yml" or "What env vars does this project have?" — the agent runs `niro edit --list-env --json`, shows you the choices, and applies your pick with `--set-env-from`. It chooses **by file name** and never handles raw secret values.
+
+---
+
+## Scenario 7 — Rename a project, or add/remove a repo
+
+**Terminal**
+```bash
+niro edit --alias new-name                 # rename the project
+niro edit --add-repo <gitId>               # map a registered repo into the project
+niro edit --remove-repo <gitId>            # unmap a repo (non-destructive)
+niro edit --project my-service --alias renamed   # target a project explicitly
+```
+
+**Ask the agent**
+> "Rename this Niro project to `payments-api`." / "Remove repo X from this project."
+
+---
+
+## Scenario 8 — Keep a local folder auto-synced
+
+`niro init` and `niro add repo` install a background daemon (via PM2) that re-uploads your changes and keeps the graph fresh — honoring `.gitignore` so secrets never leave your machine.
+
+**Terminal**
+```bash
+niro service install     # install + start the niro-watch daemon (auto-starts on login)
+niro service status
+niro service uninstall
+niro watch               # run a watch in the foreground (debugging / no PM2)
+```
+
+---
+
+## Scenario 9 — Remove a project or detach a repo
+
+**Terminal**
+```bash
+niro remove --unmap-repo <gitId>                         # detach one repo (non-destructive)
+niro remove --project --confirm-name my-service          # delete the WHOLE project (guarded)
+```
+
+`--project` is destructive, so it **requires** `--confirm-name` to exactly match the project's alias or id.
+
+**Ask the agent**
+> "Remove the Niro project `my-service`." — the agent confirms with you, then runs `niro remove --project --confirm-name my-service`.
+
+---
+
+## Scenario 10 — Ask your AI assistant about your code
+
+After `niro mcp install` (and a restart of your assistant), the `niro-skill` routes code questions through Niro's graph instead of grep:
+
+> "What calls `chargeCard()`?"
+> "What breaks if I change the `Invoice` schema?"
+> "Where is the auth middleware wired up?"
+> "Is there existing code that parses webhooks before I write a new one?"
+
+This works in any folder that resolves to a Niro project (via its git remote or a `.niro-project` pin).
+
+**Where does the MCP point?**
+> "Which backend is my Niro MCP connected to?" — the `niro-cli` skill inspects your editor's MCP config and reports the URL + connection status.
+
+---
+
+## Scenario 11 — Disconnect an AI assistant (uninstall the MCP)
+
+`niro mcp uninstall` is the exact inverse of `niro mcp install`: it removes the MCP server registration and everything install added for that editor — the niro hooks in `~/.claude/settings.json`, the `## Niro MCP` section in `CLAUDE.md` / `AGENTS.md`, the generated `niro-skill` / `niro-cli` skills, and Cursor's allowlist entry + project rule. It only touches niro's own entries; your other hooks, MCP servers, and notes are left intact.
+
+**Terminal**
+```bash
+niro mcp uninstall                      # interactive: pick client(s) (or "all")
+niro mcp uninstall --client claude-code # remove from one editor, no prompt
+niro mcp uninstall --client claude-code,codex  # remove from several in one go
+niro mcp uninstall --all -y             # remove from every editor, skip the confirm
+```
+
+It does **not** sign you out — your `niro login` session in `~/.niro/credentials.json` is kept (run `niro logout` to clear it), and the `niro` command itself stays installed (remove it with `npm rm -g @niroai/niro`). The shared `~/.agents/skills` (used by both Codex and Windsurf) is only deleted once the last of those two editors is disconnected, so uninstalling one never breaks the other.
+
+**Ask the agent**
+> "Disconnect Niro from Claude Code." / "Uninstall the Niro MCP from all my editors."
+
+---
+
+## Command reference
+
+| Command | What it does |
+|---|---|
+| `niro login` / `logout` / `whoami` | Authenticate / sign out / show current account |
+| `niro init [path]` | Onboard a folder end-to-end (upload, project, env scan, build, watch) |
+| `niro info [path]` | What Niro knows about this folder (repo, branch, project(s), status) |
+| `niro projects` (`niro ls`) | List all projects in your account |
+| `niro status [project]` | Live build status for a project |
+| `niro build [project]` | Trigger a rebuild and stream progress |
+| `niro edit …` | Rename, map/unmap repos, manage env vars (incl. `--set-env-from`) |
+| `niro remove …` | Delete a project (`--project`, guarded) or detach a repo (`--unmap-repo`) |
+| `niro add repo [path\|url]` | Register a local folder or remote git URL |
+| `niro add project` | Create a project from registered repos |
+| `niro watch [path]` / `niro service …` | Foreground watch / manage the auto-sync daemon |
+| `niro mcp install` | Connect an AI assistant + install the agent skills (one per run; `--client <id>` to skip the prompt, `--url <url>` for your own backend) |
+| `niro mcp uninstall` | Disconnect an AI assistant — reverses `mcp install` (`--client <id>` / `--all`, `-y` to skip confirm) |
+| `niro delete [project]` | Older whole-project delete (prefer `niro remove --project`) |
+
+Add `--json` to `whoami`, `info`, `status`, `projects`, `build`, and `edit --list-env` for machine-readable output. Add `--help` to any command for its full flags.
+
+---
+
+## Config & local state
+
+| Location | Purpose |
+|---|---|
+| `~/.niro/credentials.json` | Auth credential + token (mode `0600`) |
+| `~/.niro/config.json` | `apiUrl` / `mcpServerUrl` saved during setup |
+| `~/.niro/projects.json` | Per-folder sync state (gitId, patterns, file hashes) |
+| `.niro-project` (in a repo) | Pins that folder to a Niro project (single line: project id or alias) |
+
+| Environment variable | Purpose | Default |
+|---|---|---|
+| `NIRO_API_URL` | CLI → ai-orchestrator base URL | `https://aiorchestrator.niroai.dev` |
+| `NIRO_MCP_SERVER_URL` | MCP server (ai-assistant) base URL | `https://aiassistant.niroai.dev` |
+| `NIRO_API_KEY` | Read by the **MCP server** (e.g. headless `niro mcp serve`) — not a CLI-command auth path; for CI use `niro login --api-key` | — |
+| `NIRO_UPLOAD_CONCURRENCY` / `NIRO_UPLOAD_TIMEOUT_MS` / `NIRO_UPLOAD_MAX_TOTAL_BYTES` / `NIRO_UPLOAD_MAX_FILES` | Tune the initial upload | 4 / 60000 / 1 GiB / 50000 |
+
+---
+
+## Security notes
+
+- **Secrets stay on your machine.** Uploads honor `.gitignore` (and `.git/info/exclude` / global excludes), so a gitignored `.env` is never sent. Raw `.env`/`*.properties` files aren't in the upload set; committed config files (`application.yml`, `.env.example`, …) are, because they hold *behavioral* defaults, not secrets.
+- **Secret values are never printed.** `--set-env` / `--set-env-from` never echo a value, and `--list-env` masks any value that looks like a secret — by key name *or* by content (connection strings, keys).
+- **The agent never handles raw secret values.** It picks env sources *by file name*; you type any real secret yourself.
+
+---
+
+## Troubleshooting
+
+- **The agent doesn't run Niro commands** — restart your AI assistant after `niro mcp install` (skills load at startup). Re-running `niro mcp install` refreshes the skills if they've been updated.
+- **`niro` not found** — ensure your global npm bin is on `PATH` (`npm bin -g`).
+- **A folder maps to multiple projects** — pass `--project <alias|id>` (or pick one when prompted).
+- **Auto-sync isn't running** — install PM2 (`npm install -g pm2`) then `niro service install`.
+
+---
+
+## License
+
+MIT

package/bin/niro.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require("../src/index.js");

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@niroai/niro",
+  "version": "0.3.0",
+  "description": "Niro — one package: the niro CLI plus the Niro MCP server (code intelligence for AI coding assistants).",
+  "keywords": [
+    "niro",
+    "mcp",
+    "model-context-protocol",
+    "code-intelligence",
+    "code-graph",
+    "cli",
+    "claude",
+    "claude-code",
+    "ai",
+    "developer-tools"
+  ],
+  "homepage": "https://niroai.dev",
+  "bin": {
+    "niro": "bin/niro.js",
+    "niro-mcp-server": "src/mcp/server.js"
+  },
+  "main": "src/index.js",
+  "scripts": {
+    "test": "node --test"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/commands/_resolveProject.js

@@ -0,0 +1,142 @@
+/**
+ * Resolve a project ID for status/build/delete commands.
+ *
+ * Precedence:
+ *   1. Explicit arg. The arg may be:
+ *        - a project_id (UUID-shaped) -> used directly (unchanged behavior);
+ *        - an alias or git URL        -> resolved via GET /api/projects/resolve.
+ *      If an alias/URL maps to MULTIPLE projects, a clear ambiguity error is
+ *      thrown listing the candidates (we never silently pick the first).
+ *   2. Walk up from cwd looking for .niro-project (same logic the MCP bridge uses).
+ */
+const api = require("../lib/api");
+const prompt = require("../lib/prompt");
+const niroProjectFile = require("../lib/niroProjectFile");
+const { normalizeProjects, resolveContext } = require("../lib/resolveContext");
+
+// A canonical project_id is a UUID. Anything that doesn't look like one and
+// isn't a path is treated as an alias/URL to resolve via the server.
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+function looksLikeProjectId(value) {
+  return UUID_RE.test(String(value).trim());
+}
+
+function looksLikeUrl(value) {
+  return /^(https?:\/\/|git@|ssh:\/\/|git:\/\/)/i.test(value) || /\.git$/i.test(value);
+}
+
+function readNiroProjectFile(startDir) {
+  // Format + walk-up live in lib/niroProjectFile (shared with the MCP bridge).
+  const found = niroProjectFile.read(startDir);
+  return found ? found.id : null;
+}
+
+/**
+ * A repo (or alias/URL) can map to more than one project. Let an interactive user
+ * pick one; in a non-TTY (an agent or a pipe) throw a clear EAMBIGUOUS error that
+ * lists the candidates instead of blocking on a prompt — the agent surfaces them
+ * (e.g. `niro info --json` reports ambiguous + the list) and re-runs with
+ * --project. The candidate list always comes from the account-scoped resolve
+ * endpoint, so it only ever contains the caller's own account's projects.
+ */
+async function chooseAmongProjects(projects, label) {
+  const numbered = projects
+    .map((p, i) => `  [${i + 1}] ${p.alias ? `${p.alias} ` : ""}(${p.project_id})`)
+    .join("\n");
+  if (prompt.isNonInteractive()) {
+    const e = new Error(`${label} — specify the project explicitly (--project / --target):\n${numbered}`);
+    e.code = "EAMBIGUOUS";
+    throw e;
+  }
+  process.stderr.write(`${label}:\n${numbered}\n`);
+  const answer = await prompt.ask(`Choose a project [1-${projects.length}]`);
+  const idx = Number.parseInt(String(answer).trim(), 10) - 1;
+  if (!Number.isInteger(idx) || idx < 0 || idx >= projects.length) {
+    const e = new Error("No valid project selected — re-run and pick a listed number, or pass --project.");
+    e.code = "EAMBIGUOUS";
+    throw e;
+  }
+  return projects[idx].project_id;
+}
+
+/**
+ * Resolve an explicit alias or git URL to a single project_id via the server.
+ * Throws ENOPROJECT when nothing matches; when more than one project matches,
+ * an interactive user is asked to choose, else an ambiguity error is thrown.
+ */
+async function resolveAliasOrUrl(value, opts = {}) {
+  const query = looksLikeUrl(value) ? { git_url: value } : { alias: value };
+  let data;
+  try {
+    data = await api.get("/api/projects/resolve", { query, apiUrl: opts.apiUrl });
+  } catch (err) {
+    const e = new Error(`Could not resolve "${value}": ${err && err.message ? err.message : err}`);
+    e.code = "ENOPROJECT";
+    throw e;
+  }
+
+  const projects = normalizeProjects(data);
+  if (projects.length === 0) {
+    const e = new Error(
+      `No project found matching "${value}". Pass an explicit project_id or run \`niro init\` first.`
+    );
+    e.code = "ENOPROJECT";
+    throw e;
+  }
+  if (projects.length > 1) {
+    return chooseAmongProjects(projects, `"${value}" matches multiple projects`);
+  }
+  return projects[0].project_id;
+}
+
+/**
+ * Resolve the current working directory to a single project_id via git, the same
+ * way `niro info` does (resolveContext -> GET /api/projects/resolve?git_url=...).
+ *   - exactly 1 project -> its project_id
+ *   - more than 1       -> EAMBIGUOUS listing the candidates
+ *   - 0                 -> ENOPROJECT with a reason derived from ctx.state
+ */
+async function resolveProjectFromGit(opts = {}) {
+  const ctx = await resolveContext(process.cwd(), opts);
+  const projects = ctx.projects || [];
+  if (projects.length === 1) return projects[0].project_id;
+  if (projects.length > 1) {
+    return chooseAmongProjects(projects, "This repo belongs to multiple Niro projects");
+  }
+  // No project resolved — explain why based on how far git resolution got.
+  const reasons = {
+    not_a_git_repo: "this directory is not inside a git repository",
+    no_origin: "this git repository has no 'origin' remote",
+    error: `project resolution failed${ctx.error ? `: ${ctx.error}` : ""}`,
+    unresolved: "no Niro project maps this repository in your account",
+  };
+  const reason = reasons[ctx.state] || "no Niro project could be resolved";
+  const e = new Error(
+    `No project_id provided and ${reason}. Pass the project explicitly or run \`niro init\` first.`
+  );
+  e.code = "ENOPROJECT";
+  throw e;
+}
+
+async function resolveProjectId(explicit, opts = {}) {
+  if (explicit) {
+    // A UUID is used directly — unchanged behavior. Anything else is an
+    // alias/URL that we resolve via the server.
+    if (looksLikeProjectId(explicit)) return explicit;
+    return resolveAliasOrUrl(explicit, opts);
+  }
+  // No explicit arg: prefer a .niro-project pin (walk up from cwd).
+  const fromFile = readNiroProjectFile(process.cwd());
+  if (fromFile) {
+    // A pin that is already a project_id is used directly. A pin holding an
+    // alias or git URL is resolved via the server (so an alias pin like "niro"
+    // works instead of being sent raw as a project_id and 403'ing).
+    if (looksLikeProjectId(fromFile)) return fromFile;
+    return resolveAliasOrUrl(fromFile, opts);
+  }
+  // No pin: fall back to git-based resolution, the same as `niro info`.
+  return resolveProjectFromGit(opts);
+}
+
+module.exports = { resolveProjectId, readNiroProjectFile, resolveAliasOrUrl, looksLikeProjectId };

package/src/commands/add-project.js

@@ -0,0 +1,190 @@
+/**
+ * `niro add project` — create a project and map repos to it.
+ *
+ * Shows a numbered list of all registered repos (local and remote).
+ * User selects which to include. Project is created and graph build triggered.
+ */
+const path = require("path");
+const api = require("../lib/api");
+const credentials = require("../lib/credentials");
+const prompt = require("../lib/prompt");
+const color = require("../lib/color");
+const watchState = require("../lib/watchState");
+const niroProjectFile = require("../lib/niroProjectFile");
+const { login } = require("./login");
+const { watchStatus } = require("./build");
+
+async function addProject(opts = {}) {
+  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;
+  }
+
+  // Fetch all repos from server
+  let allRepos = [];
+  try {
+    allRepos = await api.get("/api/git/all");
+  } catch (err) {
+    console.error(color.red(`Failed to fetch repos: ${err.message}`));
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!Array.isArray(allRepos) || allRepos.length === 0) {
+    console.log(color.yellow("No repos registered yet. Run `niro add repo` first."));
+    return;
+  }
+
+  // Enrich with local sync state for display (current backend only — the server
+  // repos above are this backend's, so foreign-backend local entries don't apply).
+  const localState = watchState.allLocal(api.currentBaseUrl());
+  const localByGitId = {};
+  for (const entry of localState) {
+    localByGitId[entry.gitId] = entry;
+  }
+
+  console.log(`\n  ${color.bold("Available repos:")}`);
+  allRepos.forEach((repo, i) => {
+    const gitId = repo.id || repo.gitId;
+    const url = repo.repository_url || repo.repositoryUrl || "";
+    const sourceType = repo.source_type || repo.sourceType || "";
+    const isSynced = sourceType === "AGENT_UPLOAD";
+    const isRemote = repo.remote_repository || repo.remoteRepository;
+
+    const local = localByGitId[gitId];
+
+    // Label: "synced" for CLI-uploaded, "remote" for cloned from git host, "local" for server-side path
+    const label = isSynced
+      ? color.green("synced")
+      : isRemote
+        ? color.dim("remote")
+        : color.cyan("local");
+
+    // Name resolution priority:
+    //   synced repo → local folder path from ~/.niro/projects.json (what the user knows)
+    //   otherwise   → displayName → URL → basename of server projectDir → gitId last resort
+    const serverDir = repo.project_dir || repo.projectDir || "";
+    const displayName =
+      (local && local.folderPath)
+        ? local.folderPath
+        : (repo.display_name || repo.displayName || url ||
+           (serverDir ? path.basename(serverDir) : null) ||
+           color.dim(`id:${gitId}`));
+
+    const syncInfo = local && local.lastSyncedAt
+      ? color.dim("  last synced " + timeSince(local.lastSyncedAt))
+      : "";
+
+    console.log(`  [${i + 1}] ${color.bold(displayName)}  ${label}${syncInfo}`);
+  });
+  console.log(`  [${allRepos.length + 1}] Register a new repo first (niro add repo)`);
+
+  const selectionRaw = await prompt.ask(
+    `\n  Select repos to include (e.g. 1,3)`,
+    ""
+  );
+  if (!selectionRaw.trim()) {
+    console.log("No selection made.");
+    return;
+  }
+
+  const indices = selectionRaw.split(",")
+    .map(s => parseInt(s.trim(), 10) - 1)
+    .filter(i => i >= 0 && i < allRepos.length);
+
+  if (indices.length === 0) {
+    console.log(color.yellow("No valid repos selected."));
+    return;
+  }
+
+  const selectedRepos = indices.map(i => allRepos[i]);
+
+  // Project name
+  const defaultName = selectedRepos[0]
+    ? (selectedRepos[0].display_name || selectedRepos[0].displayName ||
+       deriveNameFromUrl(selectedRepos[0].repository_url || selectedRepos[0].repositoryUrl))
+    : "my-project";
+
+  let projectId;
+  while (true) {
+    const candidate = await prompt.ask("  Project name", defaultName);
+    if (!candidate) { console.error(color.red("Project name is required.")); return; }
+    if (await projectNameTaken(candidate)) {
+      console.log(color.yellow(`  "${candidate}" already exists — pick another.`));
+    } else {
+      projectId = candidate;
+      break;
+    }
+  }
+
+  // Build gitIdToMapping
+  const gitIdToMapping = {};
+  for (const repo of selectedRepos) {
+    gitIdToMapping[repo.id || repo.gitId] = {};
+  }
+
+  console.log(`\n  Creating project "${color.bold(projectId)}"...`);
+  const project = await api.post("/api/projects", {
+    project_id: projectId,
+    git_id_to_mapping: gitIdToMapping,
+  });
+
+  // Update local state with projectId for each local repo
+  for (const repo of selectedRepos) {
+    const gitId = repo.id || repo.gitId;
+    const local = localByGitId[gitId];
+    if (local) {
+      watchState.update(local.folderPath, { projectId });
+    }
+  }
+
+  console.log(`  ${color.green("✓")} Project created: ${color.bold(projectId)}`);
+
+  const shouldBuild = await prompt.confirm("  Trigger a full index build now?", true);
+  if (shouldBuild) {
+    console.log(`  Triggering build...`);
+    await api.post(
+      `/api/graph/${encodeURIComponent(projectId)}/build`,
+      {},
+      { query: { force_full_rebuild: "true" } }
+    );
+    if (opts.watch !== false) {
+      await watchStatus(projectId);
+    } else {
+      console.log(`  Build triggered. Run ${color.cyan("niro status")} to track progress.`);
+    }
+  }
+
+  console.log(`\n${color.green("✓ Done.")} Run ${color.cyan("niro mcp install")} to configure Claude Code / Cursor / Windsurf.`);
+}
+
+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;
+    throw err;
+  }
+}
+
+function deriveNameFromUrl(url) {
+  if (!url) return "my-project";
+  const m = url.match(/([^/:]+?)(?:\.git)?$/);
+  return m ? m[1] : "my-project";
+}
+
+function timeSince(isoString) {
+  if (!isoString) return "";
+  const diff = (Date.now() - new Date(isoString).getTime()) / 1000;
+  if (diff < 60) return `${Math.round(diff)}s ago`;
+  if (diff < 3600) return `${Math.round(diff / 60)}m ago`;
+  return `${Math.round(diff / 3600)}h ago`;
+}
+
+module.exports = { addProject };