@niroai/niro 0.17.0 → 1.0.0

package/src/lib/localBuild.js

@@ -0,0 +1,285 @@
+/**
+ * Keep a locally indexed folder's graph current by rebuilding it after the folder goes
+ * quiet.
+ *
+ * This is the local half of what the watcher does. For a cloud-indexed folder the watcher
+ * uploads each changed file as it sees it. For a locally indexed one there is nothing to
+ * upload: the engine reads the files itself, works out what changed, and rebuilds. So the
+ * shape is different on purpose. One build per quiet period, for the whole folder, rather
+ * than one action per file.
+ *
+ * **Why a settle delay and not a build per event.** Saving a file in an editor can produce
+ * several events, a formatter on save produces more, and a `git checkout` produces one per
+ * file in the tree. A build per event would mean hundreds of builds for one branch switch.
+ * Waiting for the folder to stop changing collapses all of them into the single build that
+ * was actually needed.
+ *
+ * **Why it coalesces instead of queueing.** While a build runs, more edits arrive. Those
+ * edits need A build, not one build each: the engine compares the whole folder against what
+ * it last recorded, so one run picks up everything that happened during the previous run.
+ * So a folder has at most one build running and at most one more wanted, and the wanted one
+ * is started when the running one finishes. The engine's own lock is the backstop for a
+ * build somebody types by hand at the same time, not the plan for this.
+ *
+ * **Nothing here decides what changed.** The engine does, from content hashes, which is why
+ * the watcher does not have to track hashes for a local folder the way it does for an
+ * uploaded one.
+ */
+const localEngine = require("./localEngine");
+const color = require("./color");
+
+/**
+ * How long a folder must be quiet before it is rebuilt. Longer than the watcher's per-file
+ * debounce of 2s, because a build costs more than an upload of one file and a branch switch
+ * takes a moment to finish writing.
+ */
+const SETTLE_MS = Number(process.env.NIRO_LOCAL_BUILD_SETTLE_MS) || 3000;
+
+/**
+ * How often a watched folder is listed again, to catch a change no file event reported (rank 176).
+ * fs.watch drops events (recursive watches especially, some editors and filesystems), and a file
+ * added while an event was lost was not built until some later change arrived. Five minutes:
+ * a listing is a walk and one stat per file, no file is read, so it costs little, and a graph at most
+ * five minutes behind a lost event is the trade. `NIRO_LOCAL_RECHECK_MS` changes it, read when the
+ * watch starts, not when this file loads, so a test or a person can set it at any time.
+ */
+const RECHECK_MS = 5 * 60_000;
+
+/** Per folder: the settle timer, whether a build is running, whether another is wanted. */
+const folders = new Map();
+
+/** Folders already known to be locally indexed or not, so the engine is asked once each. */
+const localities = new Map();
+
+/** Folders we have already complained about not being able to run the engine for. */
+const complained = new Set();
+
+function stateFor(dir) {
+  let state = folders.get(dir);
+  if (!state) {
+    state = { timer: null, running: false, wantedAgain: false, list: null, listed: null, recheckTimer: null };
+    folders.set(dir, state);
+  }
+  return state;
+}
+
+/**
+ * Is this folder indexed by the local engine?
+ *
+ * Asked once per folder and remembered, because the watcher would otherwise spawn a
+ * process per file event. Asked of the engine rather than worked out here: `status --check`
+ * prints nothing and answers in its exit code, so this is a yes or a no and not a string to
+ * match. Matching the engine's prose would break the first time somebody improved it.
+ *
+ * An engine that cannot be run at all answers "not local", so a machine without it keeps
+ * the cloud behaviour instead of losing its watcher.
+ */
+async function isLocallyIndexed(dir) {
+  if (localities.has(dir)) return localities.get(dir);
+  let local = false;
+  try {
+    await localEngine.run(["status", "--path", dir, "--check"]);
+    local = true;
+  } catch {
+    local = false;
+  }
+  localities.set(dir, local);
+  return local;
+}
+
+/** Forget what is remembered about a folder. For tests, and for a folder that is released. */
+function forget(dir) {
+  const state = folders.get(dir);
+  if (state && state.timer) clearTimeout(state.timer);
+  if (state && state.recheckTimer) clearInterval(state.recheckTimer);
+  folders.delete(dir);
+  localities.delete(dir);
+  complained.delete(dir);
+}
+
+/**
+ * Note that something in this folder changed, and rebuild it once the folder is quiet.
+ *
+ * Returns immediately. Deliberately not awaited by the caller: the watcher's event handler
+ * must never be held open by a build, or events arriving during it are delayed behind it.
+ */
+function noteChange(dir, { settleMs = SETTLE_MS, log = console.log, hint } = {}) {
+  const state = stateFor(dir);
+  if (state.running) {
+    // A build is already going. It may not see this edit, since it reads the files once at
+    // the start, so another one is owed. One is enough however many edits land meanwhile.
+    state.wantedAgain = true;
+    return;
+  }
+  if (state.timer) clearTimeout(state.timer);
+  state.timer = setTimeout(() => {
+    state.timer = null;
+    runBuild(dir, { settleMs, log, hint });
+  }, settleMs);
+}
+
+/**
+ * The engine's own prefix when it says something is wrong with its graph's age.
+ *
+ * A cross-repository contract, and the only string this file takes from the engine. The engine
+ * writes two of these on the first tool call of a session, one for a graph that is behind the
+ * files and one for a folder that has never been built
+ * (`niro_local/mcp/freshness.py`, `Staleness.notice`), and a test at each end pins the prefix
+ * so a rewording cannot quietly turn this off.
+ */
+const BEHIND_MARKER = "NOTE FROM niro-local:";
+
+/**
+ * Rebuild in the background when the engine reports its graph is behind the files.
+ *
+ * **Why the bridge does this at all, when the watcher already rebuilds.** The watcher is one
+ * process per machine and it can be absent: not installed yet, stopped, or removed by
+ * something else entirely (on 2026-10-16 this package's own test suite deleted it). When it is
+ * absent, nothing acts on the engine's notice, and a developer gets answers from yesterday's
+ * graph with a warning they did not ask for and cannot act on without stopping their work.
+ * Niraj, 2026-10-16: "yes bridge should kick off a background rebuild when the engine reports
+ * a stale graph".
+ *
+ * **Local folders only, deliberately.** This is reached from the bridge's local answer path,
+ * which exists only for a folder the engine on this machine indexes. A cloud project's
+ * automatic rebuild is its own setting (`niro init --auto-build on|off`, with its own quiet
+ * period) and nothing here touches it.
+ *
+ * Returns true when a build was scheduled. Never throws, never blocks the answer, and writes
+ * through `log`, which the bridge points at stderr: stdout is the JSON-RPC channel and one
+ * stray line on it ends the session.
+ */
+function catchUpIfBehind(dir, result, { log = console.log } = {}) {
+  const content = Array.isArray(result && result.content) ? result.content : [];
+  const said = content.find(
+    (block) => block && typeof block.text === "string" && block.text.includes(BEHIND_MARKER)
+  );
+  if (!said) return false;
+  const state = stateFor(dir);
+  // Once per notice per folder per process. What this guards against is a stream of tool calls in
+  // ONE session each scheduling a build of the same folder: the engine repeats the notice for a
+  // branch with no index until the build has made one. A different notice is a different thing to
+  // catch up on: a session that moves to a second new branch needs a second build.
+  const notice = said.text.split("\n").find((line) => line.includes(BEHIND_MARKER));
+  if (state.caughtUp === notice) return false;
+  state.caughtUp = notice;
+  log(`the local graph is behind the files; rebuilding ${dir} in the background`);
+  noteChange(dir, { settleMs: 0, log });
+  return true;
+}
+
+/** What to do after a failed build, said under the reason. A caller with its own retry passes its own. */
+const FIX_THEN_SAVE = "Edits are not reaching the graph. Fix this, then save a file to retry.";
+
+/**
+ * Why the engine failed, in its own words. niro-local writes a refusal such as "... is not part of
+ * any project" to standard output, and only a crash or a licence refusal to standard error, so a
+ * reason read from standard error alone was blank for every refusal (VP-rel-watch N1).
+ */
+function failureReason(err) {
+  if (!err || err.exitCode === undefined) return (err && err.message) || String(err);
+  const said = err.stderr || err.stdout || "no reason given";
+  return `niro-local exited ${err.exitCode}: ${said}`;
+}
+
+async function runBuild(dir, { settleMs = SETTLE_MS, log = console.log, hint = FIX_THEN_SAVE } = {}) {
+  const state = stateFor(dir);
+  state.running = true;
+  state.wantedAgain = false;
+  // What the folder looked like as this build started, for the periodic re-check: a change after
+  // this point either comes with an event (and another build) or is what the re-check is for.
+  if (state.list) state.listed = listOrNull(state.list);
+  try {
+    // Licensed, because this is the one call here that indexes. A released engine refuses to
+    // build without a lease, so the lease has to travel with the build rather than be fetched
+    // once at startup: a watcher is up for hours and a lease lasts an hour.
+    const out = await localEngine.runLicensed(["build", "--path", dir], { log });
+    // The engine's own report, printed rather than parsed. It is already written to be
+    // read, and a parser here would go stale the next time a line is reworded.
+    for (const line of out.split("\n")) {
+      if (line.trim()) log(`    ${line.trimEnd()}`);
+    }
+  } catch (err) {
+    // Loud but not fatal, and said once per folder: a watcher that cannot build is useless
+    // and the developer has to know, but one message per file event is unreadable.
+    if (!complained.has(dir)) {
+      complained.add(dir);
+      const [first, ...rest] = failureReason(err).split("\n");
+      log(color.red(`    Could not rebuild ${dir}: ${first}`));
+      for (const line of rest) if (line.trim()) log(color.red(`      ${line.trimEnd()}`));
+      log(color.yellow(`    ${hint}`));
+    }
+  } finally {
+    state.running = false;
+  }
+  if (state.wantedAgain) {
+    // Edits arrived while that build was running. Go round once more, after the same quiet
+    // period, so a long stream of edits still settles instead of building back to back.
+    state.wantedAgain = false;
+    noteChange(dir, { settleMs, log, hint });
+  }
+}
+
+function listOrNull(list) {
+  try {
+    return list();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Re-check a watched folder every `intervalMs`, and rebuild it when its listing changed with no file
+ * event to say so (rank 176). `list` returns a digest of the folder's file names, sizes and
+ * modification times, or null when the folder cannot be listed (a renamed or unmounted folder is
+ * unknown, never "changed"). The digest is compared with the one taken when the last build started.
+ *
+ * Never two builds at once: a tick does nothing while a build runs or is due, since that build lists
+ * the folder itself when it starts, and a change goes through `noteChange`, the same settle and
+ * coalescing a file event takes. The engine's own lock still stops a build typed by hand from
+ * overlapping. Returns a function that stops the re-check; `forget` stops it too.
+ */
+function startRecheck(dir, { intervalMs, list, log = console.log } = {}) {
+  const every = usableInterval(intervalMs) || usableInterval(Number(process.env.NIRO_LOCAL_RECHECK_MS)) || RECHECK_MS;
+  const state = stateFor(dir);
+  if (state.recheckTimer) clearInterval(state.recheckTimer);
+  state.list = list;
+  state.recheckTimer = setInterval(() => recheck(dir, { log }), every);
+  // The watch keeps the process up on its own; this timer must not, or a test or a stopped watch hangs.
+  if (state.recheckTimer.unref) state.recheckTimer.unref();
+  return () => {
+    clearInterval(state.recheckTimer);
+    state.recheckTimer = null;
+  };
+}
+
+/**
+ * The interval when it is at least a second, else undefined (the default is used). A negative or tiny
+ * value passed `Number(...) ||` and `setInterval` ran it every millisecond: 187 listings in 200 ms (VP9).
+ */
+const RECHECK_FLOOR_MS = 1000;
+function usableInterval(ms) {
+  return Number.isFinite(ms) && ms >= RECHECK_FLOOR_MS ? ms : undefined;
+}
+
+/** One re-check. Returns true when it asked for a build. */
+function recheck(dir, { log = console.log } = {}) {
+  const state = folders.get(dir);
+  if (!state || !state.list || state.running || state.timer) return false;
+  const now = listOrNull(state.list);
+  if (now === null) return false;
+  if (state.listed === null) {
+    // No build has listed the folder yet (the startup build could not list it): start from here.
+    state.listed = now;
+    return false;
+  }
+  if (now === state.listed) return false;
+  log(`    ${color.yellow("\u21bb")} ${dir} changed with no file event seen; rebuilding`);
+  noteChange(dir, { log });
+  return true;
+}
+
+module.exports = {
+  noteChange, isLocallyIndexed, forget, catchUpIfBehind, failureReason, startRecheck, recheck, BEHIND_MARKER, SETTLE_MS,
+  RECHECK_MS, RECHECK_FLOOR_MS,
+};

package/src/lib/localEngine.js

@@ -0,0 +1,210 @@
+/**
+ * How to run the local engine, in one place.
+ *
+ * Two callers need it now: `audit-send`, which asks the engine for the findings it is
+ * holding, and the watcher, which asks it to rebuild a folder after an edit. Extracted
+ * rather than copied, because the one thing both must agree on is WHERE the engine is: a
+ * second copy of that resolution is a second thing to change when the engine moves, and a
+ * CLI that finds it for one command and not the other is worse than one that finds it for
+ * neither.
+ *
+ * Nothing here knows what the engine does. It spawns it, collects its output, and reports
+ * a non-zero exit as an error naming the command. Deliberately no retry: the two callers
+ * want different answers to a failure (the audit keeps its queue and tries later, the
+ * watcher lets the next file change trigger another build), so retrying here would take
+ * that decision away from both.
+ */
+const { spawn } = require("child_process");
+const lease = require("./lease");
+
+/**
+ * Where the engine is.
+ *
+ * `NIRO_LOCAL_BIN` wins, so somebody working on the engine runs their own build. Then the
+ * download cache, which is where `niro engine install` puts it, because that is where it will
+ * be on a customer's machine. Then the bare name, which finds it on the PATH: that is how a
+ * developer of this repository runs it, and it is the behaviour this had before the cache
+ * existed, so nothing that works today stops working.
+ *
+ * No download from here, deliberately. This is called by the watcher to ask whether a folder
+ * is indexed, which happens on every file event, and a 60 MB download must be something a
+ * person started rather than a side effect of saving a file.
+ */
+function enginePath() {
+  const engine = require("./engine");
+  const found = engine.resolve();
+  // The bare name is still the last resort: `spawn` searches the PATH itself, so an engine
+  // this cannot see a file for (an odd permission, a shim) can still be started by name.
+  return found ? found.path : engine.EXECUTABLE;
+}
+
+/**
+ * Run the engine and collect stdout.
+ *
+ * Rejects with the engine's stderr, which never carries a payload: the engine prints
+ * counts and messages there, and the source it holds only ever leaves through `--emit` on
+ * stdout. That distinction is why a failure can be logged safely.
+ */
+function run(args, stdin, { timeoutMs } = {}) {
+  return spawnEngine(args, { stdin, timeoutMs });
+}
+
+/**
+ * Run the engine with a licence on a pipe of its own.
+ *
+ * Used for anything that indexes. The engine checks its licence before it writes anything, so
+ * without this a released engine refuses the build and says why. Two more pipes are opened and
+ * their numbers are put in the engine's environment; `lease.js` writes the lease down one of
+ * them and renews it while the engine runs, which matters for a build that takes minutes and
+ * will matter more for the MCP server, which runs for hours.
+ *
+ * Not used for the engine's other commands. Asking it whether a folder is indexed, reading
+ * what the audit is holding, and recording what was sent all write nothing to the graph and
+ * need no licence, and a lease request per file event would be a request per keystroke.
+ */
+function runLicensed(args, { stdin, log, onStderrLine, withStderr = false } = {}) {
+  return spawnEngine(args, { stdin, licensed: true, log, onStderrLine, withStderr });
+}
+
+/**
+ * `onStderrLine`, when given, hears each complete stderr line as it arrives, for a caller
+ * that shows progress while the engine runs (`build --progress`, contract C3). stderr is still
+ * collected in full for the error, so a caller that streams loses nothing on failure.
+ *
+ * `withStderr` resolves `{ stdout, stderr }` instead of standard output alone. Added for
+ * `docs-send`, which needs the engine's counts line to know whether any folder is built with
+ * --llm when there is nothing to send; every other caller keeps the plain string.
+ */
+/**
+ * `timeoutMs`, when given, stops the engine (SIGTERM) and rejects once that long has passed. For
+ * a caller on a timer, the watcher's folder list: one call that hangs must not stop every later
+ * round (VP-rel-watch N4), and the process is ended rather than left behind on each round.
+ */
+function spawnEngine(args, { stdin, licensed = false, log, onStderrLine, withStderr = false, timeoutMs } = {}) {
+  return new Promise((resolve, reject) => {
+    // Three pipes as usual, plus the two the licence travels on. The engine is told their
+    // numbers rather than guessing: 3 and 4 are only free because this is where it is started.
+    const stdio = licensed
+      ? ["pipe", "pipe", "pipe", "pipe", "pipe"]
+      : ["pipe", "pipe", "pipe"];
+    const executable = enginePath();
+    const child = require("./engine").startHeld(executable, () =>
+      spawn(executable, args, {
+        stdio,
+        env: licensed ? lease.childEnvironment() : process.env,
+      })
+    );
+    const licence = licensed ? lease.attach(child, log ? { log } : {}) : null;
+    let timedOut = false;
+    const timer = timeoutMs > 0
+      ? setTimeout(() => {
+        timedOut = true;
+        child.kill();
+        reject(new Error(`${enginePath()} ${args.join(" ")} gave no answer in ${timeoutMs} ms, so it was stopped`));
+      }, timeoutMs)
+      : null;
+    if (timer && timer.unref) timer.unref();
+    let out = "";
+    let err = "";
+    child.stdout.on("data", (chunk) => (out += chunk));
+    let partial = "";
+    child.stderr.on("data", (chunk) => {
+      err += chunk;
+      if (!onStderrLine) return;
+      partial += chunk;
+      const lines = partial.split("\n");
+      partial = lines.pop();
+      for (const line of lines) onStderrLine(line);
+    });
+    child.on("error", (problem) => {
+      if (timer) clearTimeout(timer);
+      if (licence) licence.stop();
+      reject(new Error(`cannot run ${enginePath()}: ${problem.message}`));
+    });
+    child.on("close", (code) => {
+      // `lease.attach` also stops itself on close; this is here so the promise cannot settle
+      // while a renewal timer is still pending, whichever listener runs first.
+      if (licence) licence.stop();
+      if (timer) clearTimeout(timer);
+      if (timedOut) return; // already rejected
+      if (code === 0) {
+        resolve(withStderr ? { stdout: out, stderr: err } : out);
+        return;
+      }
+      // The message carries the command, because most callers log it and a log line
+      // without the command is unreadable. The engine's own words are also attached on
+      // their own, for the one caller that shows them to a developer: the engine writes
+      // the platform's install instructions there, and they must not arrive wrapped in
+      // our path and exit code.
+      const failure = new Error(
+        `${enginePath()} ${args.join(" ")} exited ${code}: ${err.trim()}`
+      );
+      failure.exitCode = code;
+      failure.stderr = err.trim();
+      failure.stdout = out.trim();
+      reject(failure);
+    });
+    // An engine that exits before reading what it is given (an old engine refusing an unknown
+    // command, a crash) closes its end of the pipe, and the write then fails with EPIPE. Without a
+    // listener that error crashed niro-cli (the independent check: 4 of 6 runs). The exit code
+    // already says what happened, through "close" above, so the write error itself is dropped.
+    child.stdin.on("error", () => {});
+    if (stdin !== undefined) child.stdin.end(stdin);
+    else child.stdin.end();
+  });
+}
+
+/**
+ * Run the engine attached to this terminal, for an engine command a person typed through niro
+ * (`niro ui`, `niro env list`, `niro ask ...`; src/commands/engineRoutes.js).
+ *
+ * Unlike `spawnEngine`, nothing is collected: the engine reads and writes the person's own
+ * terminal, so a server (`ui`) prints its address and keeps running, a question asked by the
+ * engine reaches the person, and its output can be piped. Resolves `{ code, signal }` when the
+ * engine ends, or `{ error }` when it could not be started; it never rejects.
+ *
+ * `licensed` adds the two lease pipes, the same as `runLicensed`, so a released engine accepts
+ * the command. Only standard input, output and error are inherited; pipes 3 and 4 stay ours.
+ * Renewal warnings go to standard error, so a piped answer (`niro ask ... | jq`) stays clean.
+ *
+ * Ctrl-C: the terminal sends it to the engine and to this process together, so this process
+ * ignores it while the engine runs and lets the engine decide how to stop; quitting first would
+ * hand the prompt back while the engine is still printing. SIGTERM and SIGHUP, which only reach
+ * this process (`kill <pid>`, a closed terminal), are passed on to the engine.
+ */
+function runAttached(args, { licensed = false, spawnFn = spawn, log = (line) => console.error(line) } = {}) {
+  return new Promise((resolve) => {
+    const executable = enginePath();
+    let child;
+    try {
+      child = require("./engine").startHeld(executable, () =>
+        spawnFn(executable, args, {
+          stdio: licensed ? ["inherit", "inherit", "inherit", "pipe", "pipe"] : "inherit",
+          env: licensed ? lease.childEnvironment() : process.env,
+        })
+      );
+    } catch (problem) {
+      resolve({ error: problem });
+      return;
+    }
+    const licence = licensed ? lease.attach(child, { log }) : null;
+    const handlers = {
+      SIGINT: () => {},
+      SIGTERM: () => child.kill("SIGTERM"),
+      SIGHUP: () => child.kill("SIGHUP"),
+    };
+    for (const [signal, handler] of Object.entries(handlers)) process.on(signal, handler);
+    let settled = false;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      for (const [signal, handler] of Object.entries(handlers)) process.removeListener(signal, handler);
+      if (licence) licence.stop();
+      resolve(result);
+    };
+    child.on("error", (problem) => finish({ error: problem }));
+    child.on("close", (code, signal) => finish({ code, signal }));
+  });
+}
+
+module.exports = { enginePath, run, runLicensed, runAttached };

package/src/lib/localOnboard.js

@@ -0,0 +1,124 @@
+/**
+ * Put one folder into the local engine and build its graph, for `niro start` step 4.
+ *
+ * Three engine commands and nothing of its own: `init --progress` adds the folder and builds it, `build --progress`
+ * builds a folder already added, both reporting `progress <done> <total>` on stderr (contract C3), and
+ * `projects --json` says whether a folder is already attached and indexed, which is how a
+ * second run of the wizard knows to skip the step. `status --check` is deliberately not used
+ * for that: it is true as soon as a folder is attached, built or not.
+ */
+const path = require("path");
+
+const git = require("./git");
+const localEngine = require("./localEngine");
+const branchDrift = require("./branchDrift");
+
+/**
+ * Add `dir` to the local engine and build it, in one engine command: the engine's `init` adds the folder and builds
+ * it (Niraj, 2026-11-06: "niro-local init should also build it"), so nothing is built a second time after it.
+ *
+ * Every option of the engine's `init` passes through with the same meaning (Niraj, 2026-11-06: "support all option
+ * of niro-local init to niro init"): `project` joins or starts that project (left out, the engine chooses: a new git
+ * worktree of a repository it holds becomes that project's temporary copy, any other folder a project named after
+ * it; Q6, release finding 3), `branch` names the branch of a folder outside git (left out, git's own branch when
+ * git can name one; the engine reads `.git/HEAD` itself for a folder in git), `baseUrl` the address its service
+ * answers on (left out unless given: an empty one tells the engine to drop the address a temporary copy takes over
+ * from its source), `force` a folder with no build file. Run with the licence, because the engine's `init` builds,
+ * and with `--progress`, so `onProgress(done, total)` hears each `progress <done> <total>` line (contract C3).
+ *
+ * The engine decides whether a folder can be indexed and whether the line limit leaves room for it, and says why
+ * not before it writes anything. Those words are the answer, so a refusal rejects with them as the message, not our
+ * path and exit code (Niraj, 2026-11-06: "niro should ask niro-engine").
+ */
+async function initAndBuild(dir, onProgress, {
+  runLicensed = localEngine.runLicensed, log = console.log, project, branch, baseUrl, force = false,
+  inspect = git.inspect,
+} = {}) {
+  const args = ["init", "--path", dir];
+  const named = branch || inspect(dir).branch;
+  if (named) args.push("--branch", named);
+  if (project) args.push("--project", project);
+  if (baseUrl !== undefined && baseUrl !== null) args.push("--base-url", String(baseUrl));
+  if (force) args.push("--force");
+  args.push("--progress");
+  const startedAt = Date.now();
+  let out;
+  try {
+    out = await runLicensed(args, { log, onStderrLine: progressListener(onProgress) });
+  } catch (err) {
+    const words = [err && err.stdout, withoutProgress(err && err.stderr)].filter(Boolean).join("\n").trim();
+    if (!words) throw err;
+    const refused = new Error(words.replace(/^error:\s*/gm, ""));
+    refused.refused = true;
+    refused.exitCode = err.exitCode;
+    throw refused;
+  }
+  return { ...parseReport(out), seconds: Math.round((Date.now() - startedAt) / 1000), said: saidBeforeReport(out) };
+}
+
+/** A stderr listener passing `progress <done> <total>` lines to `onProgress`. */
+function progressListener(onProgress) {
+  return (line) => {
+    const m = /^progress (\d+) (\d+)\s*$/.exec(line);
+    if (m && onProgress) onProgress(Number(m[1]), Number(m[2]));
+  };
+}
+
+/** Standard error without the progress lines, which are for the bar and say nothing about a failure. */
+function withoutProgress(stderr) {
+  return String(stderr || "").split("\n").filter((line) => !/^progress \d+ \d+\s*$/.test(line)).join("\n").trim();
+}
+
+/**
+ * What the engine's `init` said before its build report: which project the folder went into, a `--branch` it
+ * ignored, the address its service answers on, a folder already added. [] when it said nothing else.
+ */
+function saidBeforeReport(stdout) {
+  const lines = String(stdout || "").split("\n");
+  const report = lines.findIndex((line) => /^(full|incremental) build of /.test(line) || /^Project .+:$/.test(line));
+  return (report === -1 ? lines : lines.slice(0, report)).map((line) => line.trimEnd()).filter(Boolean);
+}
+
+/** Files and lines out of the build report on stdout; null for a number it did not print. */
+function parseReport(stdout) {
+  const files = /files\s+([\d,]+)\s+seen/.exec(stdout || "");
+  const lines = /lines\s+([\d,]+)/.exec(stdout || "");
+  const num = (m) => (m ? Number(m[1].replace(/,/g, "")) : null);
+  return { files: num(files), lines: num(lines) };
+}
+
+/**
+ * Build `dir`, calling `onProgress(done, total)` per progress line. `extraArgs` are engine build options
+ * passed on as they are (`niro build --full --project <name>`).
+ */
+async function build(dir, onProgress, { runLicensed = localEngine.runLicensed, log = console.log, extraArgs = [] } = {}) {
+  const startedAt = Date.now();
+  const out = await runLicensed(["build", "--path", dir, "--progress", ...extraArgs], {
+    log,
+    onStderrLine: progressListener(onProgress),
+  });
+  return { ...parseReport(out), seconds: Math.round((Date.now() - startedAt) / 1000) };
+}
+
+/**
+ * This folder as the engine knows it, `{ project, worktree }`, or null.
+ *
+ * Exact by default: a subfolder of an attached folder is not what the wizard attached.
+ * `inside: true` also accepts a folder below an attached one, which is what `niro status`
+ * run from a subdirectory means.
+ */
+async function worktreeFor(dir, { run = localEngine.run, inside = false } = {}) {
+  const project = await branchDrift.projectHolding(dir, { run });
+  if (!project) return null;
+  const wanted = path.resolve(dir);
+  const holds = (w) => {
+    const folder = path.resolve(String(w.path));
+    return folder === wanted || (inside && wanted.startsWith(folder + path.sep));
+  };
+  const matches = (project.worktrees || []).filter((w) => w && holds(w));
+  // The nearest one when worktrees nest.
+  const worktree = matches.sort((a, b) => String(b.path).length - String(a.path).length)[0];
+  return worktree ? { project, worktree } : null;
+}
+
+module.exports = { initAndBuild, build, parseReport, saidBeforeReport, worktreeFor };