@bli-cockpit/cli 0.2.28 → 0.2.30

package/dist/commands/install-receipts.js

@@ -0,0 +1,193 @@
+/**
+ * Receipts: what this machine tells the dashboard about how a command went.
+ *
+ * Every step of `install`, `onboard`, `update` and every `sync` tick records a
+ * named step result here, and the outbox delivers them best-effort. A failure
+ * that names itself is the whole point — "it failed" is not a result, and a
+ * receipt nobody can act on is why BLI-2526 and BLI-2542 exist.
+ *
+ * Split out of commands/local.ts (BLI-3104) — moved verbatim; the step names,
+ * error codes and redaction rules are a server-side contract.
+ */
+import os from "node:os";
+import { errorMessage, writeLine } from "./cli-io.js";
+import { maskLocalIdentifiers, redactedHealthDetail, } from "../health-detail.js";
+import { getCollectorRuntimePaths, readLocalCollectorSessionFile, LOCAL_COLLECTOR_VERSION, } from "../local-state.js";
+import { redactSecretLikeContent } from "@bli-cockpit/telemetry-core";
+import { COLLECTION_ROOT_REQUIRED } from "../onboarding-roots.js";
+import { enqueueInstallEventEntry, readPendingInstallEventEntries, recordInstallEventAttemptFailure, removeInstallEventEntry, } from "../spool/install-event-outbox.js";
+export function addInstallEvent(events, step, status, errorCode, 
+// BLI-2542: the bucket alone cannot be acted on. Callers that hold the reason
+// pass it; it is redacted at this boundary, not at the call site.
+errorMessage) {
+    const detail = errorMessage ? redactedHealthDetail(errorMessage) : "";
+    const code = errorCode ? sanitizeInstallErrorCode(errorCode) : undefined;
+    events.push({
+        step,
+        status,
+        ...(code ? { error_code: code } : {}),
+        ...(detail && detail !== code ? { error_detail: detail } : {}),
+    });
+}
+export function sanitizeInstallErrorCode(value) {
+    const normalized = value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9_]+/gu, "_")
+        .replace(/^_+|_+$/gu, "")
+        .slice(0, 120);
+    return normalized || "unknown";
+}
+/**
+ * Posts pending install events. Also the collector's only per-tick listening
+ * post: the response carries the server-published `min_cli_version` floor
+ * (BLI-2678), so the last one observed is returned for the scheduled
+ * self-update step to act on. Every early-out returns null — no receipt, no
+ * floor.
+ */
+export async function reportInstallEventsBestEffort(options) {
+    if (options.events.length === 0)
+        return null;
+    const paths = getCollectorRuntimePaths(options.homeDir);
+    try {
+        await enqueueInstallEventEntry(paths, {
+            dashboardUrl: options.dashboardUrl,
+            cliVersion: LOCAL_COLLECTOR_VERSION,
+            command: options.command,
+            osPlatform: os.platform(),
+            events: options.events.map((event) => ({
+                step: event.step.trim().slice(0, 120),
+                status: event.status,
+                ...(event.error_code
+                    ? { error_code: sanitizeInstallErrorCode(event.error_code) }
+                    : {}),
+                // Already redacted and capped at the point it was produced; bounded
+                // again here because this mapping is what the server contract sees.
+                ...(event.error_detail
+                    ? {
+                        error_detail: event.error_detail
+                            .trim()
+                            .slice(0, SYNC_ERROR_DETAIL_MAX_CHARS),
+                    }
+                    : {}),
+                ...(event.at ? { at: event.at } : {}),
+            })),
+        });
+    }
+    catch {
+        if (options.json) {
+            writeLine(options.io.stderr, "Install event outbox unavailable: local_write_failed");
+        }
+        return null;
+    }
+    const session = await readLocalCollectorSessionFile(paths).catch(() => null);
+    if (!session ||
+        session.session_state !== "valid" ||
+        typeof session.device_token !== "string" ||
+        !session.device_token) {
+        return null;
+    }
+    const pending = (await readPendingInstallEventEntries(paths)).slice(0, 20);
+    const failures = [];
+    let observedMinCliVersion = null;
+    for (let offset = 0; offset < pending.length; offset += 5) {
+        await Promise.all(pending.slice(offset, offset + 5).map(async (entry) => {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), 5_000);
+            try {
+                const response = await options.io.fetch(`${entry.dashboard_url}/api/ambient/install-events`, {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/json",
+                        Authorization: `Bearer ${session.device_token}`,
+                    },
+                    body: JSON.stringify({
+                        cli_version: entry.cli_version,
+                        command: entry.command,
+                        os_platform: entry.os_platform,
+                        events: entry.events,
+                    }),
+                    signal: controller.signal,
+                });
+                if (!response.ok) {
+                    throw new Error(`http_${response.status}`);
+                }
+                const receipt = (await response
+                    .json()
+                    .catch(() => null));
+                if (typeof receipt?.min_cli_version === "string" &&
+                    receipt.min_cli_version.trim()) {
+                    observedMinCliVersion = receipt.min_cli_version.trim();
+                }
+                await removeInstallEventEntry(paths, entry.outbox_id);
+            }
+            catch (error) {
+                const failureReason = classifyInstallTelemetryError(error);
+                failures.push(failureReason);
+                await recordInstallEventAttemptFailure(paths, entry, {
+                    attemptedAt: new Date().toISOString(),
+                    failureReason,
+                }).catch(() => undefined);
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+        }));
+    }
+    if (options.json && failures.length > 0) {
+        writeLine(options.io.stderr, `Install event telemetry queued for retry: ${[...new Set(failures)].join(",")}`);
+    }
+    return observedMinCliVersion;
+}
+function classifyInstallTelemetryError(error) {
+    if (error instanceof Error && error.name === "AbortError") {
+        return "timeout";
+    }
+    const message = errorMessage(error);
+    const status = message.match(/http_(\d{3})/i)?.[1];
+    if (status)
+        return `http_${status}`;
+    if (/fetch|network|ENOTFOUND|ECONNREFUSED/i.test(message))
+        return "network";
+    return "failed";
+}
+export function classifySyncHealthError(error) {
+    const message = errorMessage(error);
+    if (/auth|token|session|unauthorized|forbidden|401|403/iu.test(message)) {
+        return "auth_failed";
+    }
+    if (/fetch|network|enotfound|econnrefused|timeout/iu.test(message)) {
+        return "network_failed";
+    }
+    // Anchored on the code the collector actually throws rather than on loose
+    // vocabulary. The old test matched /collection.root|workspace|repo|worktree/
+    // against the message, so any failure that merely mentioned a repo was filed
+    // as a collection-root failure and the real reason was lost (BLI-2492).
+    if (message.includes(COLLECTION_ROOT_REQUIRED) ||
+        /collection root/iu.test(message)) {
+        return "collection_root_failed";
+    }
+    return "sync_failed";
+}
+// The bucket above is for aggregation. This is the reason — the actual message,
+// redacted on the machine that produced it, before it ever leaves.
+//
+// Error text can carry absolute paths and, on some auth failures, token-shaped
+// fragments. It goes through the same deterministic redaction the collector
+// already applies to evidence, and is capped so one pathological stack trace
+// cannot dominate a health receipt.
+export const SYNC_ERROR_DETAIL_MAX_CHARS = 600;
+export function redactedSyncErrorDetail(error) {
+    const message = errorMessage(error).replace(/\s+/gu, " ").trim();
+    const { text } = redactSecretLikeContent(message, {
+        appliedBy: "local_collector",
+    });
+    // BLI-2542: the comment above always said this text can carry absolute paths,
+    // and until now nothing removed them — secret redaction matches token shapes,
+    // not filesystem paths. Same masking the doctor receipts use, so one boundary
+    // rule covers every health receipt.
+    const masked = maskLocalIdentifiers(text);
+    return masked.length > SYNC_ERROR_DETAIL_MAX_CHARS
+        ? `${masked.slice(0, SYNC_ERROR_DETAIL_MAX_CHARS - 1)}…`
+        : masked;
+}

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;
+    }
+}