@bli-cockpit/cli 0.2.49 → 0.2.51

package/dist/local-state-attributed-target.js

@@ -0,0 +1,75 @@
+import path from "node:path";
+import { normalizeGitOrigin, repoFingerprintFromLocalRoot, repoFingerprintFromOrigin, repoLabelFromOrigin, stableWorktreeFingerprint, stableWorktreeRoot, } from "./repo-identity.js";
+import { isSamePath } from "./root-normalization.js";
+/**
+ * A transcript-attributed target is an identity a CALLER built — for a wrapper
+ * folder or a repo that no longer exists on disk — so every field of it is
+ * re-derived here before a single byte of context state is written. Nothing
+ * downstream can tell an invented fingerprint from a real one.
+ *
+ * The checks run in a fixed order and each throws its own sentence, so the
+ * first thing wrong is the thing the operator is told about.
+ */
+export async function validateAttributedTargetIdentity(requestedRepoRoot, identity) {
+    const canonicalRoot = await stableWorktreeRoot(requestedRepoRoot);
+    const identityRoot = await stableWorktreeRoot(identity.repo_root);
+    const identityRequestedPath = await stableWorktreeRoot(identity.requested_path);
+    if (!isSamePath(canonicalRoot, identityRoot) ||
+        !isSamePath(canonicalRoot, identityRequestedPath)) {
+        throw new Error("Attributed target identity paths do not match the requested repo root.");
+    }
+    const expectedWorktreeFingerprint = stableWorktreeFingerprint(canonicalRoot);
+    if (identity.worktree_fingerprint !== expectedWorktreeFingerprint) {
+        throw new Error("Attributed target worktree fingerprint does not match its repo root.");
+    }
+    const expectedWorktreeLabel = path.basename(canonicalRoot) || "workspace";
+    if (identity.worktree_label !== expectedWorktreeLabel) {
+        throw new Error("Attributed target worktree label does not match its repo root.");
+    }
+    if (identity.repo_origin_url) {
+        assertRepoFieldsMatchOrigin(identity, identity.repo_origin_url);
+    }
+    else {
+        assertRepoFieldsMatchLocalRoot(identity, canonicalRoot, expectedWorktreeLabel);
+    }
+    return {
+        ...identity,
+        requested_path: canonicalRoot,
+        repo_root: canonicalRoot,
+    };
+}
+/**
+ * An origin-derived target is a repo reconstructed from transcript
+ * provenance, so it may not claim to be the live primary worktree of anything.
+ */
+function assertRepoFieldsMatchOrigin(identity, repoOriginUrl) {
+    const normalizedOrigin = normalizeGitOrigin(repoOriginUrl);
+    if (normalizedOrigin !== repoOriginUrl) {
+        throw new Error("Attributed target repo origin is not normalized.");
+    }
+    if (identity.repo_fingerprint !== repoFingerprintFromOrigin(normalizedOrigin)) {
+        throw new Error("Attributed target repo fingerprint does not match its origin.");
+    }
+    if (identity.repo_label !== repoLabelFromOrigin(normalizedOrigin)) {
+        throw new Error("Attributed target repo label does not match its origin.");
+    }
+    if (identity.worktree_is_primary) {
+        throw new Error("Origin-derived attributed targets cannot claim a primary live worktree.");
+    }
+}
+/**
+ * Without an origin the only thing an identity can honestly be derived from is
+ * the local root, so the fingerprint, the label and primacy all follow from it.
+ */
+function assertRepoFieldsMatchLocalRoot(identity, canonicalRoot, expectedWorktreeLabel) {
+    if (identity.repo_fingerprint !==
+        repoFingerprintFromLocalRoot(canonicalRoot)) {
+        throw new Error("Attributed target repo fingerprint does not match its local root.");
+    }
+    if (identity.repo_label !== expectedWorktreeLabel) {
+        throw new Error("Attributed target repo label does not match its local root.");
+    }
+    if (!identity.worktree_is_primary) {
+        throw new Error("Local attributed targets must use their primary local identity.");
+    }
+}

package/dist/local-state-config.js

@@ -0,0 +1,147 @@
+import { LocalCollectorConfigSchema, } from "@bli-cockpit/telemetry-core";
+import crypto from "node:crypto";
+import { readFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { normalizeCollectionRoots } from "./root-normalization.js";
+import { ensureRuntimeDirectories, getCollectorRuntimePaths, } from "./local-state-paths.js";
+import { isMissingFileError, readJsonFile, writeJsonFile, } from "./local-state-files.js";
+const localCollectorPackage = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+export const LOCAL_COLLECTOR_VERSION = typeof localCollectorPackage.version === "string"
+    ? localCollectorPackage.version
+    : "0.0.0";
+export const DEFAULT_DASHBOARD_URL = "https://bli-cockpit-dashboard.vercel.app";
+/**
+ * `cockpit install` — the one write that registers collection roots, because
+ * widening an operator's boundary is a consent decision and nothing else may
+ * make it.
+ */
+export async function installLocalCollector(options = {}) {
+    const homeDir = options.homeDir ?? os.homedir();
+    const repoRoots = normalizeRepoRoots(options.repoRoots);
+    const repoRoot = path.resolve(options.repoRoot ?? repoRoots[0] ?? process.cwd());
+    const paths = getCollectorRuntimePaths(homeDir);
+    await ensureRuntimeDirectories(paths);
+    const existingConfig = await readLocalCollectorConfig(paths).catch(() => null);
+    const defaultRepoPaths = normalizeRepoRoots([
+        ...(options.replaceRepoRoots ? [] : (existingConfig?.default_repo_paths ?? [])),
+        ...(repoRoots.length > 0 ? repoRoots : [repoRoot]),
+    ]);
+    const rawEvidenceUpload = migrateRawEvidenceUploadChoice(existingConfig);
+    const config = LocalCollectorConfigSchema.parse({
+        schema_version: "telemetry-core.v1",
+        dashboard_url: options.dashboardUrl ?? existingConfig?.dashboard_url ?? DEFAULT_DASHBOARD_URL,
+        supabase_url: options.supabaseUrl ?? existingConfig?.supabase_url,
+        collector_version: LOCAL_COLLECTOR_VERSION,
+        device_id: existingConfig?.device_id ?? `device-${crypto.randomUUID()}`,
+        device_name: normalizeDeviceName(options.deviceName) ??
+            existingConfig?.device_name ??
+            defaultDeviceName(),
+        claimed_owner_email: existingConfig?.claimed_owner_email,
+        operator_id: existingConfig?.operator_id,
+        default_repo_paths: defaultRepoPaths,
+        raw_evidence_upload: rawEvidenceUpload,
+        session_file_path: paths.session_file,
+        state_dir_path: paths.state_dir,
+    });
+    await writeJsonFile(paths.config_file, config);
+    return {
+        config,
+        paths,
+        auth_pairing_state: "missing",
+        message: "Local collector installed. Pair/login is still required before remote upload.",
+    };
+}
+/**
+ * The one on-disk migration this file performs: both retired raw-evidence
+ * choices become the durable one, so a machine installed before durable
+ * evidence existed stops holding the old answer forever.
+ */
+function migrateRawEvidenceUploadChoice(existingConfig) {
+    return existingConfig?.raw_evidence_upload === "disabled" ||
+        existingConfig?.raw_evidence_upload === "remote_short_retention_opt_in"
+        ? "remote_durable_opt_in"
+        : (existingConfig?.raw_evidence_upload ?? "remote_durable_opt_in");
+}
+function normalizeRepoRoots(repoRoots) {
+    if (!repoRoots)
+        return [];
+    const seen = new Set();
+    const candidates = [];
+    for (const root of repoRoots) {
+        const resolved = path.resolve(root);
+        if (seen.has(resolved))
+            continue;
+        seen.add(resolved);
+        candidates.push(resolved);
+    }
+    return normalizeCollectionRoots(candidates);
+}
+/**
+ * Reads the collector config, creating a minimal rootless one when the file
+ * does not exist yet (fresh machine where `cockpit onboard`/`install` has not
+ * run). Never registers collection roots: root consent stays with
+ * onboard/install. A corrupt existing config is never overwritten.
+ */
+export async function ensureLocalCollectorConfig(options = {}) {
+    const homeDir = options.homeDir ?? os.homedir();
+    const paths = getCollectorRuntimePaths(homeDir);
+    await ensureRuntimeDirectories(paths);
+    let existing = null;
+    try {
+        existing = await readLocalCollectorConfig(paths);
+    }
+    catch (error) {
+        if (!isMissingFileError(error)) {
+            const reason = error instanceof Error ? error.message : String(error);
+            throw new Error(`Local collector config at ${paths.config_file} is unreadable (${reason}). ` +
+                "Run `cockpit onboard` to repair it.");
+        }
+    }
+    if (existing)
+        return { config: existing, paths, created: false };
+    const config = LocalCollectorConfigSchema.parse({
+        schema_version: "telemetry-core.v1",
+        dashboard_url: normalizeDashboardUrl(options.dashboardUrl ?? DEFAULT_DASHBOARD_URL),
+        collector_version: LOCAL_COLLECTOR_VERSION,
+        device_id: `device-${crypto.randomUUID()}`,
+        device_name: defaultDeviceName(),
+        default_repo_paths: [],
+        session_file_path: paths.session_file,
+        state_dir_path: paths.state_dir,
+    });
+    await writeJsonFile(paths.config_file, config);
+    return { config, paths, created: true };
+}
+/**
+ * Every caller that needs to know how this machine is configured comes through
+ * here, so a config that exists and will not parse fails the same way for all
+ * of them instead of each inventing a default.
+ */
+export async function readLocalCollectorConfig(paths) {
+    return LocalCollectorConfigSchema.parse(await readJsonFile(paths.config_file));
+}
+/**
+ * A trailing slash in a dashboard URL produces `//api/...` request paths that
+ * some proxies answer differently, so the stored value is normalized once.
+ */
+export function normalizeDashboardUrl(value) {
+    const normalized = value.trim().replace(/\/+$/, "");
+    if (!normalized)
+        throw new Error("Dashboard URL cannot be empty.");
+    return normalized;
+}
+/** The device name an operator sees in the dashboard before they pick one. */
+export function defaultDeviceName() {
+    return normalizeDeviceName(os.hostname()) ?? "Local machine";
+}
+/** Keeps a hand-typed or hostname-derived device name inside what the schema accepts. */
+export function normalizeDeviceName(value) {
+    const trimmed = value?.trim().replace(/\s+/g, " ");
+    return trimmed ? trimmed.slice(0, 120) : undefined;
+}
+/** A claimed owner email is a label a person types, so an unusable one is dropped rather than stored. */
+export function normalizeOptionalEmail(value) {
+    const trimmed = value?.trim().toLowerCase();
+    return trimmed && trimmed.includes("@") ? trimmed : undefined;
+}

package/dist/local-state-files.js

@@ -0,0 +1,59 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { describeError, isMissingFileFailure } from "./health-detail.js";
+/**
+ * The one reader behind the config file, the session file and every work
+ * context — and therefore the one place worth reporting from.
+ *
+ * Roughly twenty call sites swallow this to `null` or a default with
+ * `.catch(() => null)`, each of them asking a reasonable question ("is this
+ * machine set up?") to which "no" is a legitimate answer. What none of them
+ * could distinguish is "no, nothing is there" from "yes, and it is corrupt or
+ * unreadable" — so the distinction is drawn HERE, once, rather than in twenty
+ * places where it would be twenty chances to forget (BLI-3238).
+ *
+ * The error still propagates unchanged; callers keep whatever they decided.
+ */
+export async function readJsonFile(filePath) {
+    try {
+        return JSON.parse(await fs.readFile(filePath, "utf8"));
+    }
+    catch (error) {
+        // Absent is the ordinary pre-onboarding state on every one of these files
+        // and stays quiet; anything else means state exists and cannot be used.
+        if (!isMissingFileFailure(error)) {
+            console.error("[local-state] a collector state file exists but could not be read", JSON.stringify({
+                reason: "state_file_unreadable",
+                // Which file, without the path: the basename of these is a fixed
+                // vocabulary (`config.json`, `session.json`, a work-context
+                // fingerprint) and carries no repo or operator name.
+                state_file: path.basename(filePath),
+                ...describeError(error),
+            }));
+        }
+        throw error;
+    }
+}
+/**
+ * The one writer behind every collector state file, because each of them holds
+ * a device token or an operator's work and must land owner-only on any host.
+ */
+export async function writeJsonFile(filePath, value) {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, {
+        mode: 0o600,
+    });
+    if (process.platform !== "win32") {
+        await fs.chmod(filePath, 0o600).catch(() => undefined);
+    }
+}
+/**
+ * Separate from `isMissingFileFailure`: the two callers here hold a raw `fs`
+ * rejection rather than a wrapped failure, and "the file was never there" is
+ * the one outcome they treat as success rather than an error to report.
+ */
+export function isMissingFileError(error) {
+    return (error instanceof Error &&
+        "code" in error &&
+        error.code === "ENOENT");
+}

package/dist/local-state-identity.js

@@ -0,0 +1,73 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { repoFingerprintFromLocalRoot, resolveRepoWorktreeIdentity, stableWorktreeFingerprint, stableWorktreeRoot, } from "./repo-identity.js";
+import { describeError, isMissingFileFailure } from "./health-detail.js";
+/**
+ * A folder that is not a git repo is a legitimate workspace under the
+ * session-first commandment, so this always answers with an identity: git's
+ * own when there is one, a path-derived one otherwise. Nothing may be withheld
+ * for lack of a repo.
+ */
+export async function resolveIdentityOrFallback(repoRoot, branchOverride) {
+    const resolvedRoot = await stableWorktreeRoot(repoRoot);
+    const identity = await resolveRepoWorktreeIdentity(resolvedRoot).catch(() => null);
+    if (identity) {
+        return branchOverride ? { ...identity, branch: branchOverride } : identity;
+    }
+    const repoLabel = path.basename(resolvedRoot) || "workspace";
+    const repoFingerprint = repoFingerprintFromLocalRoot(resolvedRoot);
+    const worktreeFingerprint = stableWorktreeFingerprint(resolvedRoot);
+    const branch = branchOverride ?? (await resolveGitBranch(resolvedRoot));
+    return {
+        requested_path: resolvedRoot,
+        repo_root: resolvedRoot,
+        repo_label: repoLabel,
+        repo_fingerprint: repoFingerprint,
+        repo_origin_url: null,
+        branch,
+        head_sha: null,
+        worktree_label: repoLabel,
+        worktree_fingerprint: worktreeFingerprint,
+        worktree_is_primary: true,
+    };
+}
+/**
+ * Reads HEAD directly rather than shelling out to git, because this runs on
+ * every sync tick on machines where a spawned process is the expensive part.
+ */
+export async function resolveGitBranch(repoRoot) {
+    try {
+        const gitPath = path.join(repoRoot, ".git");
+        const stat = await fs.stat(gitPath);
+        const headPath = stat.isFile()
+            ? path.join(await resolveWorktreeGitDir(gitPath), "HEAD")
+            : path.join(gitPath, "HEAD");
+        const head = (await fs.readFile(headPath, "utf8")).trim();
+        if (head.startsWith("ref: refs/heads/")) {
+            return head.slice("ref: refs/heads/".length);
+        }
+        return head ? `detached:${head.slice(0, 12)}` : "unknown";
+    }
+    catch (error) {
+        // A folder that is not a git repo is a legitimate workspace under the
+        // session-first commandment, so a missing `.git` stays quiet. A `.git`
+        // that exists and cannot be read is a different thing: every session
+        // collected from this repo gets branch `unknown` and nothing says why.
+        if (!isMissingFileFailure(error)) {
+            console.error("[local-state] could not read HEAD, branch recorded as unknown", JSON.stringify({
+                reason: "git_head_unreadable",
+                ...describeError(error),
+            }));
+        }
+        return "unknown";
+    }
+}
+/** A linked worktree's `.git` is a file pointing elsewhere, so HEAD is not where it looks. */
+async function resolveWorktreeGitDir(gitFile) {
+    const raw = await fs.readFile(gitFile, "utf8");
+    const match = raw.match(/^gitdir:\s*(.+)$/m);
+    if (!match)
+        return path.dirname(gitFile);
+    const gitDir = match[1].trim();
+    return path.isAbsolute(gitDir) ? gitDir : path.resolve(path.dirname(gitFile), gitDir);
+}

package/dist/local-state-pairing.js

@@ -0,0 +1,263 @@
+import { LocalCollectorSessionFileSchema, } from "@bli-cockpit/telemetry-core";
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import { describeError, isMissingFileFailure } from "./health-detail.js";
+import { serverFailureDetail } from "./upload-http.js";
+import { ensureRuntimeDirectories, getCollectorRuntimePaths, } from "./local-state-paths.js";
+import { isMissingFileError, writeJsonFile } from "./local-state-files.js";
+import { defaultDeviceName, LOCAL_COLLECTOR_VERSION, normalizeDashboardUrl, normalizeDeviceName, normalizeOptionalEmail, readLocalCollectorConfig, } from "./local-state-config.js";
+import { toSessionReference } from "./local-state-session.js";
+/**
+ * `cockpit login` — the whole device-pairing handshake, because a machine can
+ * collect locally without it but can never upload until the dashboard has
+ * approved this device.
+ */
+export async function pairLocalCollector(options = {}) {
+    const homeDir = options.homeDir ?? os.homedir();
+    const paths = getCollectorRuntimePaths(homeDir);
+    await ensureRuntimeDirectories(paths);
+    const config = await readConfigOrRefusePairing(paths);
+    const dashboardUrl = normalizeDashboardUrl(options.dashboardUrl ?? config.dashboard_url);
+    const device = resolvePairingDeviceIdentity(config, options);
+    await recordDeviceIdentityWhenChanged(paths, config, device);
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    if (!fetchImpl) {
+        throw new Error("global fetch is unavailable; use Node.js 20 or newer.");
+    }
+    const startResponse = await postPairStart(fetchImpl, dashboardUrl, {
+        device_id: device.deviceId,
+        device_name: device.deviceName,
+        claimed_owner_email: device.claimedOwnerEmail,
+        collector_version: LOCAL_COLLECTOR_VERSION,
+    }, options.pairingAccessToken);
+    options.onPairStarted?.(startResponse);
+    const sessionFile = await pollPairRequest(fetchImpl, dashboardUrl, {
+        paths,
+        startResponse,
+        pollIntervalMs: options.pollIntervalMs,
+        timeoutMs: options.timeoutMs,
+        sleep: options.sleep,
+    });
+    return {
+        status: "paired",
+        session: toSessionReference(sessionFile),
+        session_file: paths.session_file,
+        dashboard_url: dashboardUrl,
+        approve_url: startResponse.approve_url,
+    };
+}
+async function readConfigOrRefusePairing(paths) {
+    return readLocalCollectorConfig(paths).catch((error) => {
+        // "Local config missing" is correct when it is absent. A config that
+        // exists and will not parse gets the same sentence and the same useless
+        // advice — run onboard again, which will not fix it (BLI-3238).
+        if (!isMissingFileFailure(error)) {
+            console.error("[local-state] collector config present but unreadable, reporting it as missing", JSON.stringify({
+                reason: "config_unreadable",
+                ...describeError(error),
+            }));
+        }
+        throw new Error("Local config missing. Run `cockpit onboard` (or `cockpit install`) first, then retry `cockpit login`.");
+    });
+}
+function resolvePairingDeviceIdentity(config, options) {
+    return {
+        deviceId: config.device_id ?? `device-${crypto.randomUUID()}`,
+        deviceName: normalizeDeviceName(options.deviceName) ??
+            config.device_name ??
+            defaultDeviceName(),
+        claimedOwnerEmail: normalizeOptionalEmail(options.claimedOwnerEmail) ??
+            config.claimed_owner_email,
+    };
+}
+/**
+ * The dashboard will approve the identity this request claims, so the config
+ * has to be holding that same identity before the request goes out.
+ */
+async function recordDeviceIdentityWhenChanged(paths, config, device) {
+    if (!config.device_id ||
+        config.device_name !== device.deviceName ||
+        (device.claimedOwnerEmail &&
+            config.claimed_owner_email !== device.claimedOwnerEmail)) {
+        await writeJsonFile(paths.config_file, {
+            ...config,
+            device_id: device.deviceId,
+            device_name: device.deviceName,
+            claimed_owner_email: device.claimedOwnerEmail,
+        });
+    }
+}
+/**
+ * `cockpit logout` — removing the session file is the whole revocation on this
+ * side, and an absent file is success, not a failure to report.
+ */
+export async function logoutLocalCollector(options = {}) {
+    const homeDir = options.homeDir ?? os.homedir();
+    const paths = getCollectorRuntimePaths(homeDir);
+    let removed = false;
+    try {
+        await fs.unlink(paths.session_file);
+        removed = true;
+    }
+    catch (error) {
+        if (!isMissingFileError(error))
+            throw error;
+    }
+    return { removed, session_file: paths.session_file };
+}
+async function postPairStart(fetchImpl, dashboardUrl, body, accessToken) {
+    const response = await fetchImpl(`${dashboardUrl}/api/ambient/pair/start`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            ...(accessToken ? { "Authorization": `Bearer ${accessToken}` } : {}),
+        },
+        body: JSON.stringify(body),
+    });
+    const parsed = await readResponseJson(response);
+    if (!response.ok) {
+        throw new Error(pairFailureMessage("Pair request failed", response, parsed));
+    }
+    return parsePairStartResponse(parsed);
+}
+async function pollPairRequest(fetchImpl, dashboardUrl, options) {
+    const pollIntervalMs = options.pollIntervalMs ?? options.startResponse.poll_after_ms;
+    const timeoutMs = options.timeoutMs ?? 10 * 60 * 1000;
+    const sleepImpl = options.sleep ??
+        ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)));
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() <= deadline) {
+        const response = await fetchImpl(`${dashboardUrl}/api/ambient/pair/poll`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                request_id: options.startResponse.request_id,
+                client_secret: options.startResponse.client_secret,
+            }),
+        });
+        const parsed = await readResponseJson(response);
+        if (!response.ok) {
+            throw new Error(pairFailureMessage("Pair polling failed", response, parsed));
+        }
+        const status = readStringField(parsed, "status");
+        if (status === "approved") {
+            const session = parsePairApprovedSession(parsed, options.paths.session_file);
+            await writeJsonFile(options.paths.session_file, session);
+            return session;
+        }
+        if (status === "expired") {
+            throw new Error("Pair request expired. Run `cockpit login` again.");
+        }
+        if (status === "revoked") {
+            throw new Error("Pair request was revoked. Run `cockpit login` again.");
+        }
+        if (status !== "pending") {
+            throw new Error(`Unexpected pair request status: ${status}`);
+        }
+        await sleepImpl(Math.max(250, pollIntervalMs));
+    }
+    throw new Error("Timed out waiting for dashboard approval. Run `cockpit login` again.");
+}
+/**
+ * What `cockpit login` tells the operator when pairing is refused.
+ *
+ * "Pair request failed" was the whole message — five words, while the status
+ * code sat in hand (BLI-3483). A 401 (this build's token is not accepted), a
+ * 403 (the dashboard knows the device and is refusing it), a 404 (wrong
+ * dashboard URL) and a 502 (something in front of the dashboard answered) are
+ * four different next actions, and the operator could not tell them apart.
+ * `upload.ts` has named its HTTP status since it was written; this is the same
+ * shape. The server's own words come first when it supplied any, and the status
+ * always rides at the end so it is never the thing that got dropped.
+ *
+ * Logged as well as thrown: `cockpit login` failures happen on a machine that
+ * is not collecting yet, so the terminal is the only receipt there is.
+ */
+function pairFailureMessage(fallback, response, body) {
+    const serverWords = responseErrorMessage(body, fallback);
+    console.error("[local-state] pairing request refused", JSON.stringify({
+        reason: fallback === "Pair request failed" ? "pair_start_refused" : "pair_poll_refused",
+        http_status: response.status,
+        server_reason: serverFailureDetail(body) ?? "none",
+    }));
+    return `${serverWords} (HTTP ${response.status})`;
+}
+async function readResponseJson(response) {
+    const text = await response.text();
+    if (!text)
+        return {};
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        // Pairing path. A captive portal or a proxy answering with HTML is the
+        // classic reason `cockpit login` fails on a new machine and the operator
+        // sees only "pair request failed". The body is never logged; its shape is.
+        console.error("[local-state] pairing reply was not JSON", JSON.stringify({
+            reason: "response_body_not_json",
+            http_status: response.status,
+            byte_size: text.length,
+            content_type: response.headers.get("content-type") ?? "none",
+        }));
+        return { message: text };
+    }
+}
+function parsePairStartResponse(value) {
+    if (!value || typeof value !== "object") {
+        throw new Error("Pair request response was not an object.");
+    }
+    const record = value;
+    return {
+        request_id: requiredString(record, "request_id"),
+        user_code: requiredString(record, "user_code"),
+        approve_url: requiredString(record, "approve_url"),
+        expires_at: requiredString(record, "expires_at"),
+        poll_after_ms: requiredNumber(record, "poll_after_ms"),
+        client_secret: requiredString(record, "client_secret"),
+    };
+}
+function parsePairApprovedSession(value, sessionFilePath) {
+    if (!value || typeof value !== "object") {
+        throw new Error("Pair approval response was not an object.");
+    }
+    const session = value["session"];
+    if (!session || typeof session !== "object") {
+        throw new Error("Pair approval response did not include a session.");
+    }
+    return LocalCollectorSessionFileSchema.parse({
+        ...session,
+        session_file_path: sessionFilePath,
+    });
+}
+function responseErrorMessage(value, fallback) {
+    if (value && typeof value === "object") {
+        const record = value;
+        const message = record["message"] ?? record["error"];
+        if (typeof message === "string" && message.trim())
+            return message;
+    }
+    return fallback;
+}
+function readStringField(value, field) {
+    if (value && typeof value === "object") {
+        const entry = value[field];
+        if (typeof entry === "string")
+            return entry;
+    }
+    throw new Error(`Pair response missing ${field}.`);
+}
+function requiredString(record, field) {
+    const value = record[field];
+    if (typeof value !== "string" || !value.trim()) {
+        throw new Error(`Pair response missing ${field}.`);
+    }
+    return value;
+}
+function requiredNumber(record, field) {
+    const value = record[field];
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(`Pair response missing ${field}.`);
+    }
+    return value;
+}

package/dist/local-state-paths.js

@@ -0,0 +1,61 @@
+import { getUserLocalCockpitPaths } from "@bli-cockpit/telemetry-core";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { describeError } from "./health-detail.js";
+/**
+ * The one place a collector file's address is computed, so no caller joins a
+ * state path by hand and drifts from the durable on-disk layout.
+ */
+export function getCollectorRuntimePaths(homeDir = os.homedir()) {
+    const paths = getUserLocalCockpitPaths(homeDir);
+    return {
+        ...paths,
+        active_work_context_file: path.join(paths.state_dir, "active-work-context.json"),
+        work_contexts_dir: path.join(paths.state_dir, "work-contexts"),
+    };
+}
+/**
+ * Every write below assumes its directory exists and is owner-only, so this
+ * runs before the first one on a fresh machine and after every upgrade.
+ */
+export async function ensureRuntimeDirectories(paths) {
+    await fs.mkdir(paths.config_dir, { recursive: true, mode: 0o700 });
+    await fs.mkdir(paths.state_dir, { recursive: true, mode: 0o700 });
+    await fs.mkdir(paths.spool_dir, { recursive: true, mode: 0o700 });
+    await fs.mkdir(paths.cursors_dir, { recursive: true, mode: 0o700 });
+    await fs.mkdir(paths.work_contexts_dir, { recursive: true, mode: 0o700 });
+    if (process.platform !== "win32") {
+        // The `mode` above only applies to directories this call CREATES, so these
+        // chmods are what actually tightens a directory that already existed with
+        // looser bits. Failing means the operator's device token and cursors stay
+        // world-readable — non-fatal, deliberately, but not something to find out
+        // about never (BLI-3238). Reported by directory name only, never a path.
+        const tightened = [
+            ["config_dir", fs.chmod(paths.config_dir, 0o700)],
+            ["state_dir", fs.chmod(paths.state_dir, 0o700)],
+            ["spool_dir", fs.chmod(paths.spool_dir, 0o700)],
+            ["cursors_dir", fs.chmod(paths.cursors_dir, 0o700)],
+            ["work_contexts_dir", fs.chmod(paths.work_contexts_dir, 0o700)],
+        ];
+        await Promise.all(tightened.map(async ([name, work]) => {
+            try {
+                await work;
+            }
+            catch (error) {
+                console.error("[local-state] could not restrict a runtime directory to owner-only", JSON.stringify({
+                    reason: "runtime_dir_chmod_failed",
+                    directory: name,
+                    ...describeError(error),
+                }));
+            }
+        }));
+    }
+}
+/**
+ * One file per worktree fingerprint, so two checkouts of the same repo keep
+ * separate contexts instead of overwriting each other.
+ */
+export function workContextFile(paths, worktreeFingerprint) {
+    return path.join(paths.work_contexts_dir, `${worktreeFingerprint}.json`);
+}