@bli-cockpit/cli 0.2.28 → 0.2.29

package/dist/commands/install-update.js

@@ -0,0 +1,305 @@
+/**
+ * Getting Cockpit onto this machine and keeping it current: `cockpit install`,
+ * `cockpit update`, the self-update the scheduled sync calls, and the
+ * maintainer-only `cockpit release`.
+ *
+ * `release` rides along because it is the same subject from the other end — the
+ * npm package everything here installs. Split out of commands/local.ts
+ * (BLI-3104); moved verbatim, including every install-event step name.
+ */
+import os from "node:os";
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+import { defaultExec, defaultInteractiveExec, writeExecOutput, writeLine } from "./cli-io.js";
+import { assertCollectionRootPersisted } from "./collection-roots.js";
+import { addInstallEvent, reportInstallEventsBestEffort } from "./install-receipts.js";
+import { installLocalCollector, LOCAL_COLLECTOR_VERSION, } from "../local-state.js";
+import { COLLECTION_ROOT_REQUIRED, missingCollectionRootMessage, normalizeRootsDetailed, rootRejectionExplanation, } from "../onboarding-roots.js";
+export class SelfUpdateError extends Error {
+    result;
+    eacces;
+    constructor(result) {
+        super("npm install failed; Cockpit CLI was not refreshed.");
+        this.name = "SelfUpdateError";
+        this.result = result;
+        this.eacces = isNpmEaccesFailure(result.stderr);
+    }
+}
+export async function runInstall(command, io) {
+    const installEvents = [];
+    const finish = async (code) => {
+        await reportInstallEventsBestEffort({
+            homeDir: command.homeDir,
+            dashboardUrl: command.dashboardUrl,
+            command: "install",
+            events: installEvents,
+            json: command.json,
+            io,
+        });
+        return code;
+    };
+    const resolved = resolveInstallCommandRoots(command);
+    if (resolved.homeRootOptIn) {
+        addInstallEvent(installEvents, "home_root_optin", "ok");
+    }
+    const result = await installLocalCollector(resolved.command);
+    // Same invariant as the onboarding path: never report a successful install
+    // over a config that saved no usable collection root.
+    await assertCollectionRootPersisted(resolved.command.homeDir);
+    addInstallEvent(installEvents, "install", "ok");
+    if (command.json) {
+        writeLine(io.stdout, JSON.stringify(result, null, 2));
+        return finish(0);
+    }
+    writeLine(io.stdout, "Cockpit local collector installed.");
+    writeLine(io.stdout, `Config: ${result.paths.config_file}`);
+    writeLine(io.stdout, `Session: ${result.paths.session_file}`);
+    writeLine(io.stdout, "Auth: missing; upload stays local-only until pairing/login.");
+    writeLine(io.stdout, "Next: run `cockpit login`, then `cockpit start` inside the repo; add `--ticket <id>` only when ticket work begins.");
+    return finish(0);
+}
+function resolveInstallCommandRoots(command) {
+    const detailed = normalizeRootsDetailed([command.repoRoot ?? process.cwd()], {
+        homeDir: command.homeDir,
+        allowHomeRoot: command.allowHomeRoot,
+    });
+    if (detailed.roots.length > 0) {
+        const root = detailed.roots[0];
+        return {
+            command: {
+                ...command,
+                repoRoot: root,
+            },
+            homeRootOptIn: Boolean(command.allowHomeRoot) &&
+                path.resolve(root) === path.resolve(command.homeDir ?? os.homedir()),
+        };
+    }
+    if (detailed.rejected.length > 0) {
+        throw new Error(`${COLLECTION_ROOT_REQUIRED}: ${rootRejectionExplanation(detailed.rejected[0], command)}`);
+    }
+    throw new Error(`${COLLECTION_ROOT_REQUIRED}: ${missingCollectionRootMessage(command)}`);
+}
+export async function runUpdate(command, io) {
+    const installEvents = [];
+    const finish = async (code) => {
+        await reportInstallEventsBestEffort({
+            homeDir: command.homeDir,
+            dashboardUrl: command.dashboardUrl,
+            command: "update",
+            events: installEvents,
+            json: command.json,
+            io,
+        });
+        return code;
+    };
+    const exec = io.exec ?? defaultExec();
+    try {
+        await runSelfUpdate(io, { json: command.json });
+    }
+    catch (error) {
+        if (!(error instanceof SelfUpdateError))
+            throw error;
+        addInstallEvent(installEvents, "npm_install", "fail", error.eacces
+            ? "npm_install_eacces"
+            : "npm_install_failed");
+        if (command.json) {
+            writeLine(io.stdout, JSON.stringify({
+                status: "blocked",
+                step: "npm_install",
+                command: `npm ${selfUpdateInstallArgs().join(" ")}`,
+                exit_code: error.result.code,
+            }, null, 2));
+        }
+        else {
+            writeLine(io.stderr, "BLOCKED: npm install failed; Cockpit CLI was not refreshed.");
+            if (error.eacces) {
+                writeLine(io.stderr, "Fix Homebrew npm ownership once: sudo chown -R $(whoami) /opt/homebrew/lib/node_modules/@bli-cockpit /opt/homebrew/bin/cockpit");
+                writeLine(io.stderr, "Do not use `sudo npm i -g`; it makes the ownership problem come back.");
+            }
+        }
+        return finish(error.result.code || 1);
+    }
+    addInstallEvent(installEvents, "npm_install", "ok");
+    if (!command.json) {
+        writeLine(io.stdout, "Cockpit CLI updated. Rechecking onboarding...");
+    }
+    const onboard = await exec("cockpit", [
+        "onboard",
+        ...updateOnboardArgs(command),
+    ]);
+    writeExecOutput(io, onboard, { stdout: true, stderr: true });
+    addInstallEvent(installEvents, "onboard_rerun", onboard.code === 0 ? "ok" : "fail", onboard.code === 0 ? undefined : updateOnboardFailureCode(onboard));
+    return finish(onboard.code);
+}
+export async function runSelfUpdate(io, options = {}) {
+    const exec = io.exec ?? defaultExec();
+    const tag = options.tag ?? "latest";
+    if (!options.json) {
+        writeLine(io.stdout, `Updating Cockpit CLI from npm (${tag})...`);
+    }
+    const install = await exec("npm", selfUpdateInstallArgs(tag));
+    writeExecOutput(io, install, { stdout: !options.json, stderr: true });
+    if (install.code !== 0) {
+        throw new SelfUpdateError(install);
+    }
+    return { updated: true, version: LOCAL_COLLECTOR_VERSION };
+}
+function selfUpdateInstallArgs(tag = "latest") {
+    return [
+        "install",
+        "-g",
+        `@bli-cockpit/cli@${tag}`,
+        "--prefer-online",
+    ];
+}
+/** Re-runs `cockpit onboard` with the same setup flags the update carried. */
+function updateOnboardArgs(command) {
+    const args = [];
+    if (command.homeDir)
+        args.push("--home", command.homeDir);
+    for (const root of updateCollectionRoots(command)) {
+        args.push("--workspace", root);
+    }
+    if (command.dashboardUrlExplicit) {
+        args.push("--dashboard-url", command.dashboardUrl);
+    }
+    if (command.claimedOwnerEmail)
+        args.push("--email", command.claimedOwnerEmail);
+    if (command.noAuth)
+        args.push("--no-auth");
+    if (command.deviceName)
+        args.push("--device-name", command.deviceName);
+    if (command.activeTicketId)
+        args.push("--ticket", command.activeTicketId);
+    if (command.branch)
+        args.push("--branch", command.branch);
+    if (command.pollIntervalMs !== undefined) {
+        args.push("--poll-interval-ms", String(command.pollIntervalMs));
+    }
+    if (command.timeoutMs !== undefined) {
+        args.push("--timeout-ms", String(command.timeoutMs));
+    }
+    if (command.maxDepth !== undefined)
+        args.push("--max-depth", String(command.maxDepth));
+    if (command.maxRepos !== undefined)
+        args.push("--max-repos", String(command.maxRepos));
+    if (command.allowHomeRoot)
+        args.push("--allow-home-root");
+    if (command.json)
+        args.push("--json");
+    return args;
+}
+function isNpmEaccesFailure(stderr) {
+    return /EACCES|permission denied/i.test(stderr);
+}
+function updateOnboardFailureCode(result) {
+    const output = `${result.stdout}\n${result.stderr}`;
+    if (output.includes(COLLECTION_ROOT_REQUIRED))
+        return COLLECTION_ROOT_REQUIRED;
+    if (/pairing|approval|device_pairing/i.test(output))
+        return "pairing_timeout";
+    if (/sync_blocked|spooled|upload failed|network_or_ingest/i.test(output)) {
+        return "sync_blocked";
+    }
+    return "onboard_rerun_failed";
+}
+function updateCollectionRoots(command) {
+    const roots = command.collectionRoots?.length
+        ? command.collectionRoots
+        : command.repoRoot
+            ? [command.repoRoot]
+            : [];
+    const seen = new Set();
+    const deduped = [];
+    for (const root of roots) {
+        if (seen.has(root))
+            continue;
+        seen.add(root);
+        deduped.push(root);
+    }
+    return deduped;
+}
+export async function runRelease(command, io) {
+    const releaseRoot = await findPublicReleaseRoot(process.cwd());
+    if (!releaseRoot) {
+        writeLine(io.stderr, "cockpit release must be run inside the bli-cockpit repo checkout (missing publish:public script).");
+        return 1;
+    }
+    const exec = io.exec ?? defaultExec();
+    const gitReady = await prepareReleaseMainBranch(releaseRoot, exec, io);
+    if (!gitReady)
+        return 1;
+    writeLine(io.stdout, "Running Cockpit public package release...");
+    const npmArgs = ["--prefix", releaseRoot, "run", "publish:public"];
+    if (command.args.length > 0)
+        npmArgs.push("--", ...command.args);
+    const releaseExec = io.interactiveExec ?? defaultInteractiveExec();
+    const result = await releaseExec("npm", npmArgs);
+    writeExecOutput(io, result, { stdout: true, stderr: true });
+    return result.code;
+}
+/** Publishing happens from a clean, current `main` or it does not happen. */
+async function prepareReleaseMainBranch(releaseRoot, exec, io) {
+    const branch = await exec("git", [
+        "-C",
+        releaseRoot,
+        "rev-parse",
+        "--abbrev-ref",
+        "HEAD",
+    ]);
+    writeExecOutput(io, branch, { stdout: false, stderr: true });
+    if (branch.code !== 0) {
+        writeLine(io.stderr, "BLOCKED: cockpit release could not read the current git branch.");
+        return false;
+    }
+    const currentBranch = branch.stdout.trim();
+    if (currentBranch !== "main") {
+        writeLine(io.stderr, `BLOCKED: cockpit release only publishes from main. Current branch is ${currentBranch || "unknown"}.`);
+        writeLine(io.stderr, "Merge the release changes, switch to main, then rerun `cockpit release`.");
+        return false;
+    }
+    const status = await exec("git", [
+        "-C",
+        releaseRoot,
+        "status",
+        "--porcelain",
+    ]);
+    writeExecOutput(io, status, { stdout: false, stderr: true });
+    if (status.code !== 0) {
+        writeLine(io.stderr, "BLOCKED: cockpit release could not inspect git status.");
+        return false;
+    }
+    if (status.stdout.trim()) {
+        writeLine(io.stderr, "BLOCKED: cockpit release requires a clean main checkout.");
+        writeLine(io.stderr, "Commit or discard local changes, then rerun `cockpit release`.");
+        return false;
+    }
+    writeLine(io.stdout, "Syncing main with git pull --ff-only...");
+    const pull = await exec("git", ["-C", releaseRoot, "pull", "--ff-only"]);
+    writeExecOutput(io, pull, { stdout: true, stderr: true });
+    if (pull.code !== 0) {
+        writeLine(io.stderr, "BLOCKED: git pull --ff-only failed; main is not safely current.");
+        return false;
+    }
+    return true;
+}
+/** Walks up for the checkout that owns the `publish:public` script. */
+async function findPublicReleaseRoot(startDir) {
+    let current = path.resolve(startDir);
+    while (true) {
+        const packageJsonPath = path.join(current, "package.json");
+        try {
+            const packageJson = JSON.parse(await readFile(packageJsonPath, "utf8"));
+            if (packageJson.scripts?.["publish:public"] !== undefined)
+                return current;
+        }
+        catch {
+            // Keep walking: nested packages may be missing package.json or have one
+            // without the release script.
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}

package/dist/commands/local-auth.js

@@ -0,0 +1,268 @@
+/**
+ * Signing this machine in: which email to pair as, the email-OTP exchange that
+ * gets a short-lived access token, and pairing itself with a manual-approval
+ * fallback when the authenticated route is refused.
+ *
+ * Every failure here degrades to manual dashboard approval rather than
+ * stopping — a person who cannot receive the code must still be able to
+ * onboard. Split out of commands/local.ts (BLI-3104); moved verbatim.
+ */
+import { execFile } from "node:child_process";
+import { errorMessage, isInteractiveStdin, readLine, writeLine, yesByDefault, } from "./cli-io.js";
+import { normalizeUrl } from "./local-args.js";
+import { getCollectorRuntimePaths, pairLocalCollector, readLocalCollectorSessionFile, readLocalSessionReference, } from "../local-state.js";
+const OTP_CODE_PROMPT = [
+    "Email code needed:",
+    "  Check your latest Cockpit email for a 6- to 10-digit code.",
+    "What you can do:",
+    "  1) Paste the code here.",
+    "  2) No code yet: wait for the resend window, then rerun this command.",
+    "  3) Can't use email: rerun with --no-auth for manual approval.",
+    "Code: ",
+].join("\n");
+const OTP_INVALID_MESSAGE = [
+    "Email code was not accepted:",
+    "  Cockpit expects digits only, length 6 to 10.",
+    "What you can do:",
+    "  1) Rerun and paste the latest email code.",
+    "  2) Use manual approval: rerun this command with --no-auth --email <you@buildlaunchiterate.ca>",
+].join("\n");
+/**
+ * Asks for the dashboard email so `cockpit onboard` (no flags) need not force a
+ * `--email`. Only called when stdin is a TTY and not in --json mode. An empty
+ * answer or a non-email skips rather than failing, matching `optionalEmail`'s
+ * leniency (the approving admin's account then owns the device).
+ */
+export async function promptOnboardEmail(io) {
+    const raw = await readLine(io, "What's your @buildlaunchiterate.ca email? (press enter to skip): ");
+    const answer = raw.trim().toLowerCase();
+    if (!answer)
+        return undefined;
+    if (!answer.includes("@")) {
+        writeLine(io.stderr, `"${answer}" is not an email; continuing without one — the approving admin's account will own this device.`);
+        return undefined;
+    }
+    return answer;
+}
+export async function resolveOnboardEmail(command, roots, config, io) {
+    if (command.claimedOwnerEmail)
+        return command.claimedOwnerEmail;
+    const inferred = await inferOnboardEmail(command.homeDir, roots, config);
+    const interactive = !command.json && isInteractiveStdin(io);
+    if (!inferred) {
+        return interactive ? promptOnboardEmail(io) : undefined;
+    }
+    if (inferred.source === "session") {
+        if (!command.json)
+            writeLine(io.stdout, `Dashboard email: ${inferred.email}`);
+        return inferred.email;
+    }
+    if (!interactive)
+        return inferred.email;
+    const answer = (await readLine(io, `Use ${inferred.email} for Cockpit pairing? [Y/n] `)).trim().toLowerCase();
+    const typedEmail = answer.split(/\s+/u).find((part) => part.includes("@"));
+    if (typedEmail)
+        return typedEmail;
+    if (yesByDefault(answer)) {
+        return inferred.email;
+    }
+    return promptOnboardEmail(io);
+}
+export async function resolveInteractiveLoginEmail(command, io) {
+    if (command.claimedOwnerEmail)
+        return command.claimedOwnerEmail;
+    if (command.noAuth || command.json || !isInteractiveStdin(io)) {
+        return undefined;
+    }
+    return promptOnboardEmail(io);
+}
+export async function requestPairingAccessToken(input, io) {
+    return (await requestPairingAccessTokenDetailed(input, io)).accessToken;
+}
+export async function requestPairingAccessTokenDetailed(input, io) {
+    if (!input.email ||
+        input.noAuth ||
+        input.json ||
+        !isInteractiveStdin(io)) {
+        return {
+            status: "skipped",
+            errorCode: authSkippedReason(input, io),
+        };
+    }
+    try {
+        const fetchImpl = io.fetch;
+        writeLine(io.stdout, `Signing in as ${input.email}.`);
+        const start = await postOtpStart(fetchImpl, input.dashboardUrl, input.email);
+        const resendAfter = typeof start.resend_after_seconds === "number"
+            ? start.resend_after_seconds
+            : 60;
+        writeLine(io.stdout, `Code sent; valid 1h, resend in ${resendAfter}s by rerunning this command.`);
+        const code = (await readLine(io, OTP_CODE_PROMPT)).trim();
+        if (!/^\d{6,10}$/.test(code)) {
+            throw new Error(OTP_INVALID_MESSAGE);
+        }
+        const verified = await postOtpVerify(fetchImpl, input.dashboardUrl, input.email, code);
+        if (typeof verified.access_token !== "string" || !verified.access_token) {
+            throw new Error("OTP verified but dashboard returned no access token.");
+        }
+        writeLine(io.stdout, `Signed in as ${input.email}.`);
+        return { status: "ok", accessToken: verified.access_token };
+    }
+    catch (error) {
+        writeLine(io.stderr, `Auth step skipped: ${errorMessage(error)}`);
+        writeLine(io.stderr, "Continuing with manual dashboard approval.");
+        return { status: "fail", errorCode: classifyAuthError(error) };
+    }
+}
+function authSkippedReason(input, io) {
+    if (!input.email)
+        return "email_missing";
+    if (input.noAuth)
+        return "no_auth";
+    if (input.json)
+        return "json_mode";
+    if (!isInteractiveStdin(io))
+        return "non_interactive";
+    return "auth_skipped";
+}
+function classifyAuthError(error) {
+    const message = errorMessage(error);
+    if (/\b(otp|code|digit|invalid)\b/i.test(message))
+        return "otp_invalid";
+    if (/fetch|network|ENOTFOUND|ECONNREFUSED|HTTP/i.test(message)) {
+        return "network_or_auth";
+    }
+    return "auth_failed";
+}
+export async function pairLocalCollectorWithAuthFallback(options, io) {
+    try {
+        return await pairLocalCollector(options);
+    }
+    catch (error) {
+        if (!options.pairingAccessToken || !isPairingAuthFailure(error)) {
+            throw error;
+        }
+        writeLine(io.stderr, `Authenticated pairing failed: ${errorMessage(error)}`);
+        writeLine(io.stderr, "Continuing with manual dashboard approval.");
+        return pairLocalCollector({
+            ...options,
+            pairingAccessToken: undefined,
+        });
+    }
+}
+function isPairingAuthFailure(error) {
+    return /\b(auth|authorization|bearer|token|jwt|otp)\b/i.test(errorMessage(error));
+}
+async function postOtpStart(fetchImpl, dashboardUrl, email) {
+    const response = await fetchImpl(`${dashboardUrl}/api/auth/otp/start`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ email }),
+    });
+    const parsed = await readJsonResponse(response);
+    if (!response.ok) {
+        throw new Error(responseErrorMessage(parsed, "OTP start failed"));
+    }
+    return parsed;
+}
+async function postOtpVerify(fetchImpl, dashboardUrl, email, code) {
+    const response = await fetchImpl(`${dashboardUrl}/api/auth/otp/verify`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ email, code }),
+    });
+    const parsed = await readJsonResponse(response);
+    if (!response.ok) {
+        throw new Error(responseErrorMessage(parsed, "OTP verify failed"));
+    }
+    return parsed;
+}
+async function readJsonResponse(response) {
+    const text = await response.text();
+    if (!text)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function responseErrorMessage(parsed, fallback) {
+    if (parsed && typeof parsed === "object") {
+        const record = parsed;
+        if (typeof record["message"] === "string" && record["message"].trim()) {
+            return record["message"];
+        }
+        if (typeof record["error"] === "string" && record["error"].trim()) {
+            return record["error"];
+        }
+    }
+    return fallback;
+}
+/** Best guess at who this machine belongs to: paired session, then saved config, then git. */
+async function inferOnboardEmail(homeDir, roots, config) {
+    const session = await readOnboardSessionReuseCandidate(homeDir).catch(() => null);
+    const sessionEmail = normalizeEmailForComparison(session?.email);
+    if (session?.session_state === "valid" && sessionEmail) {
+        return { email: sessionEmail, source: "session" };
+    }
+    const configEmail = normalizeEmailForComparison(config?.claimed_owner_email);
+    if (configEmail)
+        return { email: configEmail, source: "config" };
+    const gitEmail = await inferUniqueGitEmail(roots);
+    return gitEmail ? { email: gitEmail, source: "git" } : null;
+}
+/** Two roots disagreeing about `user.email` is no answer at all, so neither is used. */
+async function inferUniqueGitEmail(roots) {
+    const emails = new Set();
+    for (const root of roots) {
+        const email = await readGitConfigEmail(root);
+        if (email)
+            emails.add(email);
+    }
+    return emails.size === 1 ? [...emails][0] ?? null : null;
+}
+async function readGitConfigEmail(root) {
+    return new Promise((resolve) => {
+        execFile("git", ["config", "user.email"], { cwd: root, encoding: "utf8" }, (error, stdout) => {
+            if (error) {
+                resolve(null);
+                return;
+            }
+            const email = normalizeEmailForComparison(stdout);
+            resolve(email?.includes("@") ? email : null);
+        });
+    });
+}
+/** Reuse the paired session only when it is the same person on the same dashboard. */
+export function canReuseOnboardSession(session, claimedOwnerEmail, dashboardUrl) {
+    if (session.session_state !== "valid")
+        return false;
+    const expectedEmail = normalizeEmailForComparison(claimedOwnerEmail);
+    if (expectedEmail && normalizeEmailForComparison(session.email) !== expectedEmail) {
+        return false;
+    }
+    const expectedDashboardUrl = normalizeUrlForComparison(dashboardUrl);
+    if (expectedDashboardUrl &&
+        normalizeUrlForComparison(session.dashboard_url) !== expectedDashboardUrl) {
+        return false;
+    }
+    return true;
+}
+function normalizeEmailForComparison(value) {
+    const normalized = value?.trim().toLowerCase();
+    return normalized ? normalized : null;
+}
+export async function readOnboardSessionReuseCandidate(homeDir) {
+    const paths = getCollectorRuntimePaths(homeDir);
+    try {
+        return await readLocalCollectorSessionFile(paths);
+    }
+    catch {
+        return readLocalSessionReference(paths);
+    }
+}
+function normalizeUrlForComparison(value) {
+    return value ? normalizeUrl(value) : null;
+}

package/dist/commands/local-discovery.js

@@ -0,0 +1,100 @@
+import { writeLine } from "./cli-io.js";
+import { resolveDiscoveryLimits, saveDiscoveryLimits, } from "../discovery-limits.js";
+import { discoverGitWorktreesInRootsWithStatus, } from "../repo-identity.js";
+export async function discoverCommandWorktrees(repoRoot, discovery = {}, io) {
+    // What the operator typed this run, else what they typed some previous run,
+    // else the built-in defaults (BLI-2362).
+    const limits = await resolveDiscoveryLimits(discovery, discovery.homeDir);
+    const maxWorktrees = limits.maxRepos;
+    const roots = Array.isArray(repoRoot)
+        ? repoRoot
+        : [repoRoot ?? process.cwd()];
+    const result = await discoverGitWorktreesInRootsWithStatus(roots, {
+        maxDepth: limits.maxDepth,
+        maxWorktrees,
+    });
+    if (io && result.unreadable_dirs.length > 0) {
+        // Never silently dropped: anything under these folders is missing from the
+        // scan, so say so even when the run otherwise succeeds.
+        writeLine(io.stderr, unreadableDirectoriesMessage(result.unreadable_dirs));
+    }
+    const worktrees = result.worktrees;
+    if (!result.complete) {
+        // Sync fails closed here ON PURPOSE, and that is not the bug. Advancing a
+        // cursor after a partial scan would mark the run as covering repos it
+        // never saw, permanently skipping their sessions — backfill can tolerate
+        // partial only because it keeps per-scope completion markers, and sync
+        // does not. The bug (BLI-2362) was that the refusal named no roots and
+        // gave no runnable command, so a big workspace just stayed red forever.
+        const message = incompleteDiscoveryMessage({
+            result,
+            roots,
+            maxDepth: limits.maxDepth,
+            maxRepos: maxWorktrees,
+            found: worktrees.length,
+        });
+        if (io)
+            writeLine(io.stderr, message);
+        throw new Error(message);
+    }
+    if (worktrees.length === 0 && !discovery.allowEmpty) {
+        throw new Error("No git repos found. Run from a git repo, or from a parent folder containing git repos.");
+    }
+    return worktrees;
+}
+/**
+ * Persists `--max-depth` / `--max-repos` when a command carried them, so the
+ * number survives into the background sync and the doctor's own sync — neither
+ * of which has anywhere to type one (BLI-2362). Best-effort: failing to record
+ * a preference must never fail the command the operator actually asked for.
+ */
+export async function rememberDiscoveryLimits(command) {
+    const limits = command;
+    if (limits.maxDepth === undefined && limits.maxRepos === undefined)
+        return;
+    await saveDiscoveryLimits({ maxDepth: limits.maxDepth, maxRepos: limits.maxRepos }, limits.homeDir).catch(() => undefined);
+}
+/**
+ * Says which folders could not be opened, and therefore what the scan could not
+ * see. Reported without failing the run — an unreadable folder cannot be fixed
+ * by retrying, so blocking on one would strand the machine (BLI-2362).
+ */
+function unreadableDirectoriesMessage(unreadable) {
+    return [
+        `WARNING: ${unreadable.length} folder(s) could not be opened, so anything inside them was not scanned:`,
+        ...unreadable.map((dir) => `  ${dir.path} (${dir.code})`),
+        "Collection continued for everything else. If a repo is missing from Cockpit,",
+        "check the permissions on the folders above.",
+    ].join("\n");
+}
+/**
+ * Names the roots that could not be covered and hands back a command that
+ * actually fixes it, with this machine's numbers already filled in.
+ */
+function incompleteDiscoveryMessage(input) {
+    const { result, roots, maxDepth, maxRepos, found } = input;
+    const blocked = result.incomplete_roots.length > 0 ? result.incomplete_roots : roots;
+    const hitRepoCap = result.incomplete_reasons.includes("max_worktrees_reached");
+    const nextDepth = maxDepth + 3;
+    const nextRepos = Math.max(maxRepos * 2, found + 50);
+    const retry = [
+        "cockpit do-everything",
+        ...roots.map((root) => `--workspace ${root}`),
+        `--max-depth ${hitRepoCap ? maxDepth : nextDepth}`,
+        `--max-repos ${nextRepos}`,
+    ].join(" ");
+    return [
+        `Cockpit could not finish scanning for repos, so it stopped instead of collecting a partial picture (${result.incomplete_reasons.join(", ")}).`,
+        "It stops rather than continuing because a partial scan would mark these repos as already checked and skip them from now on.",
+        "",
+        "Could not fully scan:",
+        ...blocked.map((root) => `  ${root}`),
+        "",
+        `Found ${found} repo(s) before stopping, with --max-depth ${maxDepth} and --max-repos ${maxRepos}.`,
+        "",
+        "Run this to raise the limits and try again:",
+        `  ${retry}`,
+        "",
+        "If that still stops, the folder is deeper or larger than expected — raise the numbers again, or point --workspace at the specific project folders instead of a parent.",
+    ].join("\n");
+}