@bli-cockpit/cli 0.2.49 → 0.2.51

package/dist/local-state-session.js

@@ -0,0 +1,68 @@
+import { LocalCollectorSessionFileSchema, LocalUserSessionReferenceSchema, } from "@bli-cockpit/telemetry-core";
+import { describeError, isMissingFileFailure } from "./health-detail.js";
+import { readJsonFile } from "./local-state-files.js";
+/**
+ * Who this machine is signed in as, in the shape every caller wants: a
+ * reference that always exists, so nothing downstream has to handle "there is
+ * no session file yet" as an error.
+ */
+export async function readLocalSessionReference(paths, fallback = {}) {
+    try {
+        const rawSession = await readJsonFile(paths.session_file);
+        const collectorSession = LocalCollectorSessionFileSchema.safeParse(rawSession);
+        if (collectorSession.success) {
+            return toSessionReference(collectorSession.data);
+        }
+        return LocalUserSessionReferenceSchema.parse(rawSession);
+    }
+    catch (error) {
+        // `session_state: "missing"` is correct before login and says so loudly
+        // enough on its own. It is also what a session file that EXISTS but is
+        // corrupt, truncated or unreadable collapses to — a paired machine that
+        // silently reads as never-signed-in, which is indistinguishable in every
+        // downstream receipt (BLI-3238).
+        if (!isMissingFileFailure(error)) {
+            console.error("[local-state] session file present but unusable, reading as missing", JSON.stringify({
+                reason: "session_file_unusable",
+                ...describeError(error),
+            }));
+        }
+        return LocalUserSessionReferenceSchema.parse({
+            operator_id: fallback.operatorId ?? "unknown",
+            auth_subject_id: "unknown",
+            session_id: fallback.sessionId ?? "missing",
+            session_file_path: paths.session_file,
+            session_state: "missing",
+        });
+    }
+}
+/**
+ * The strict read, for the callers that need the device token itself and
+ * cannot proceed on a "missing" reference.
+ */
+export async function readLocalCollectorSessionFile(paths) {
+    return LocalCollectorSessionFileSchema.parse(await readJsonFile(paths.session_file));
+}
+/**
+ * Drops the device token and re-states expiry as a session state, so an
+ * expired session cannot travel as `valid` just because the file says so.
+ */
+export function toSessionReference(session) {
+    const now = Date.now();
+    const expiresAt = Date.parse(session.expires_at ?? "");
+    const sessionState = Number.isFinite(expiresAt) && expiresAt <= now ? "expired" : session.session_state;
+    return LocalUserSessionReferenceSchema.parse({
+        operator_id: session.operator_id,
+        auth_subject_id: session.auth_subject_id,
+        email: session.email,
+        team_id: session.team_id,
+        device_id: session.device_id,
+        device_name: session.device_name,
+        session_id: session.session_id,
+        session_file_path: session.session_file_path,
+        session_state: sessionState,
+        auth_method: session.auth_method,
+        issued_at: session.issued_at,
+        expires_at: session.expires_at,
+    });
+}

package/dist/local-state-status.js

@@ -0,0 +1,163 @@
+import os from "node:os";
+import path from "node:path";
+import { summarizeLocalUploadSpool } from "./spool/local-spool.js";
+import { summarizeInstallEventOutbox } from "./spool/install-event-outbox.js";
+import { readRawEvidenceStagingState, summarizeStuckEvidence, } from "./raw-evidence-staging.js";
+import { getCollectorRuntimePaths, } from "./local-state-paths.js";
+import { LOCAL_COLLECTOR_VERSION, readLocalCollectorConfig, } from "./local-state-config.js";
+import { readLocalSessionReference } from "./local-state-session.js";
+import { resolveIdentityOrFallback } from "./local-state-identity.js";
+import { readLocalWorkContextForRepo, workDisplayLabel, } from "./local-state-work-context.js";
+/**
+ * `cockpit status` — the one answer to "is this machine collecting, and is
+ * anything landing?". A green status must never be able to hide a session that
+ * never arrived, so every queue and every stuck object is reported here.
+ */
+export async function inspectLocalCollectorStatus(options = {}) {
+    const now = options.now ?? new Date();
+    const reading = await readCollectorStatus(options, now);
+    const { paths, config, session, identity, context, branch } = reading;
+    const { uploadSpool, healthOutbox, stuckEvidence } = reading;
+    const freshness = classifyCollectorFreshness(context, uploadSpool.last_upload_success_at, now);
+    const uploadState = classifyUploadState(config, uploadSpool, session);
+    return {
+        installed: Boolean(config),
+        config_file: paths.config_file,
+        session_file: paths.session_file,
+        collector_version: LOCAL_COLLECTOR_VERSION,
+        config_collector_version: config?.collector_version ?? null,
+        session_state: session.session_state,
+        repo: context?.repo ?? identity.repo_root,
+        branch,
+        active_ticket_id: context?.active_ticket_id ?? null,
+        work_label: context ? workDisplayLabel(context) : null,
+        work_id: context?.work_context_id ?? null,
+        work_context_id: context?.work_context_id ?? null,
+        repo_label: context?.repo_label ?? identity.repo_label,
+        repo_fingerprint: context?.repo_fingerprint ?? identity.repo_fingerprint,
+        worktree_label: context?.worktree_label ?? identity.worktree_label,
+        worktree_fingerprint: context?.worktree_fingerprint ?? identity.worktree_fingerprint,
+        worktree_is_primary: context?.worktree_is_primary ?? identity.worktree_is_primary,
+        collector_freshness: freshness,
+        upload_state: uploadState,
+        last_upload_attempt_at: uploadSpool.last_upload_attempt_at,
+        last_upload_success_at: uploadSpool.last_upload_success_at,
+        last_upload_failure_reason: uploadSpool.last_upload_failure_reason,
+        pending_upload_count: uploadSpool.pending_upload_count,
+        upload_retry_command: uploadSpool.retry_command,
+        pending_health_receipt_count: healthOutbox.pending_count,
+        oldest_pending_health_receipt_at: healthOutbox.oldest_created_at,
+        last_health_receipt_failure_reason: healthOutbox.last_failure_reason,
+        stuck_evidence_object_count: stuckEvidence.stuck_object_count,
+        stuck_evidence_held_count: stuckEvidence.held_object_count,
+        stuck_evidence_max_attempts: stuckEvidence.max_attempts,
+        stuck_evidence_oldest_failure_at: stuckEvidence.oldest_first_failed_at,
+        stuck_evidence_reasons: stuckEvidence.reasons,
+        details: describeCollectorStatus(reading),
+    };
+}
+async function readCollectorStatus(options, now) {
+    const homeDir = options.homeDir ?? os.homedir();
+    const repoRoot = path.resolve(options.repoRoot ?? process.cwd());
+    const paths = getCollectorRuntimePaths(homeDir);
+    const config = await readLocalCollectorConfig(paths).catch(() => null);
+    const session = await readLocalSessionReference(paths, {
+        operatorId: options.operatorId,
+        sessionId: options.sessionId,
+    });
+    const identity = await resolveIdentityOrFallback(repoRoot, options.branch);
+    const context = await readLocalWorkContextForRepo(paths, repoRoot).catch(() => null);
+    const branch = options.branch ?? identity.branch;
+    const [uploadSpool, healthOutbox, stagingState] = await Promise.all([
+        summarizeLocalUploadSpool(paths),
+        summarizeInstallEventOutbox(paths),
+        readRawEvidenceStagingState(paths.state_dir),
+    ]);
+    const stuckEvidence = summarizeStuckEvidence(stagingState, now);
+    return {
+        paths,
+        config,
+        session,
+        identity,
+        context,
+        branch,
+        uploadSpool,
+        healthOutbox,
+        stuckEvidence,
+    };
+}
+// Not installed outranks everything, and a pending retry outranks a valid
+// session. The return type is inferred: the four labels are already written
+// once in `LocalCollectorStatus` and once here, and a third copy would be a
+// third place to forget one.
+function classifyUploadState(config, uploadSpool, session) {
+    return !config
+        ? "not_installed"
+        : uploadSpool.pending_upload_count > 0
+            ? "retry_pending"
+            : session.session_state === "valid"
+                ? "ready"
+                : "local_only_missing_auth";
+}
+/**
+ * The sentences an operator actually reads. Each of the first five is stated
+ * either way round, because a line that only appears on failure cannot answer
+ * "did anything land at all today?"; the last four appear only when there is a
+ * queue, and each names its own reason and count.
+ */
+function describeCollectorStatus(reading) {
+    const { paths, config, session, context, uploadSpool, healthOutbox, stuckEvidence } = reading;
+    const details = [];
+    details.push(config
+        ? `Config exists at ${paths.config_file}.`
+        : "Local config missing. Run `cockpit install`.");
+    details.push(session.session_state === "valid"
+        ? "Local user session is valid."
+        : "Local user session missing or not paired; upload remains local-only.");
+    details.push(context
+        ? `Active work ${workDisplayLabel(context)} (${context.work_context_id}) last updated ${context.updated_at ?? context.started_at}.`
+        : "Active work context missing. Run `cockpit start`.");
+    details.push(uploadSpool.last_upload_attempt_at
+        ? `Last upload attempt: ${uploadSpool.last_upload_attempt_at}.`
+        : "No upload has been attempted yet.");
+    details.push(uploadSpool.last_upload_success_at
+        ? `Last upload success: ${uploadSpool.last_upload_success_at}.`
+        : "No successful upload recorded yet.");
+    if (uploadSpool.last_upload_failure_reason) {
+        details.push(`Last upload failure: ${uploadSpool.last_upload_failure_reason}.`);
+    }
+    if (uploadSpool.pending_upload_count > 0) {
+        details.push(`Upload retry pending: ${uploadSpool.pending_upload_count} safe metadata record(s) spooled. Run \`${uploadSpool.retry_command ?? "cockpit sync"}\` to retry.`);
+    }
+    if (healthOutbox.pending_count > 0) {
+        details.push(`Collector health retry pending: ${healthOutbox.pending_count} sanitized receipt(s) queued since ${healthOutbox.oldest_created_at ?? "unknown"}.`);
+    }
+    if (stuckEvidence.stuck_object_count > 0) {
+        details.push(`Raw evidence stuck: ${stuckEvidence.stuck_object_count} object(s) have never been accepted (${stuckEvidence.held_object_count} waiting on backoff, worst ${stuckEvidence.max_attempts} attempt(s) since ${stuckEvidence.oldest_first_failed_at ?? "unknown"}) — reasons: ${stuckEvidence.reasons.join(", ") || "unknown"}.`);
+    }
+    return details;
+}
+/**
+ * Whether this machine looks alive right now. A successful upload counts as
+ * activity as much as a context update does, so a long session that is still
+ * shipping data does not read as stale.
+ */
+export function classifyCollectorFreshness(context, lastUploadSuccessAt, now) {
+    if (!context)
+        return "missing";
+    const latestActivityAt = latestTimestamp([
+        context.updated_at ?? context.started_at,
+        lastUploadSuccessAt,
+    ]);
+    if (latestActivityAt === null)
+        return "stale";
+    return now.getTime() - latestActivityAt <= 5 * 60 * 1000 ? "fresh" : "stale";
+}
+function latestTimestamp(values) {
+    const timestamps = values
+        .map((value) => Date.parse(value ?? ""))
+        .filter((value) => Number.isFinite(value));
+    if (timestamps.length === 0)
+        return null;
+    return Math.max(...timestamps);
+}

package/dist/local-state-work-context.js

@@ -0,0 +1,190 @@
+import { LocalWorkContextSchema, } from "@bli-cockpit/telemetry-core";
+import crypto from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+import { ensureRuntimeDirectories, getCollectorRuntimePaths, workContextFile, } from "./local-state-paths.js";
+import { readJsonFile, writeJsonFile } from "./local-state-files.js";
+import { LOCAL_COLLECTOR_VERSION, readLocalCollectorConfig, } from "./local-state-config.js";
+import { readLocalSessionReference } from "./local-state-session.js";
+import { resolveIdentityOrFallback } from "./local-state-identity.js";
+import { validateAttributedTargetIdentity } from "./local-state-attributed-target.js";
+/** What `cockpit start` binds: the repo, branch and ticket this session's work belongs to. */
+export async function startLocalWorkContext(options = {}) {
+    return writeLocalWorkContext(options);
+}
+/**
+ * Starts a context for a transcript-attributed sync target that does not exist
+ * in the current git inventory, such as an approved wrapper folder or a
+ * deleted repo reconstructed from transcript provenance. This internal path
+ * validates the exact target identity before writing any context state.
+ */
+export async function startLocalWorkContextForAttributedTarget(options, attributedIdentity) {
+    const repoRoot = path.resolve(options.repoRoot ?? process.cwd());
+    const identity = await validateAttributedTargetIdentity(repoRoot, attributedIdentity);
+    return writeLocalWorkContext(options, identity);
+}
+async function writeLocalWorkContext(options, attributedIdentity) {
+    if (options.activeTicketId && options.clearTicket) {
+        throw new Error("--ticket and --clear-ticket cannot be combined.");
+    }
+    const now = options.now ?? new Date();
+    const homeDir = options.homeDir ?? os.homedir();
+    const repoRoot = path.resolve(options.repoRoot ?? process.cwd());
+    const paths = getCollectorRuntimePaths(homeDir);
+    await ensureRuntimeDirectories(paths);
+    const config = await readLocalCollectorConfig(paths).catch(() => null);
+    const session = await readLocalSessionReference(paths, {
+        operatorId: options.operatorId,
+        sessionId: options.sessionId,
+    });
+    const identity = attributedIdentity ??
+        (await resolveIdentityOrFallback(repoRoot, options.branch));
+    const branch = attributedIdentity
+        ? attributedIdentity.branch
+        : (options.branch ?? identity.branch);
+    const sessionId = options.sessionId ??
+        (session.session_state === "missing" ? `local-${crypto.randomUUID()}` : session.session_id);
+    const operatorId = options.operatorId ?? session.operator_id;
+    const deviceId = session.device_id ?? config?.device_id ?? "device-unknown";
+    const workContextId = stableWorkContextId({
+        operatorId,
+        deviceId,
+        repoFingerprint: identity.repo_fingerprint,
+        worktreeFingerprint: identity.worktree_fingerprint,
+    });
+    const existingContext = await readLocalWorkContextByFingerprint(paths, identity.worktree_fingerprint).catch(() => null);
+    const context = buildWorkContext({
+        options,
+        now,
+        identity,
+        branch,
+        operatorId,
+        sessionId,
+        workContextId,
+        existingContext,
+    });
+    await writeJsonFile(workContextFile(paths, identity.worktree_fingerprint), context);
+    await writeJsonFile(paths.active_work_context_file, context);
+    return context;
+}
+/**
+ * The context record itself, kept in one piece because it is a schema: every
+ * field an ambient envelope will later carry as provenance is decided here.
+ */
+function buildWorkContext(input) {
+    const { options, now, identity, branch, operatorId, sessionId, workContextId, existingContext } = input;
+    const { activeTicketId, ticketBindingCandidates } = resolveTicketBinding(options, existingContext);
+    return LocalWorkContextSchema.parse({
+        work_context_id: workContextId,
+        repo: identity.repo_root,
+        branch,
+        repo_label: identity.repo_label,
+        repo_fingerprint: identity.repo_fingerprint,
+        repo_origin_url: identity.repo_origin_url ?? undefined,
+        head_sha: identity.head_sha ?? undefined,
+        worktree_label: identity.worktree_label,
+        worktree_fingerprint: identity.worktree_fingerprint,
+        worktree_is_primary: identity.worktree_is_primary,
+        operator_id: operatorId,
+        session_id: sessionId,
+        started_at: existingContext?.started_at ?? now.toISOString(),
+        updated_at: now.toISOString(),
+        active_ticket_id: activeTicketId,
+        ticket_binding_candidates: ticketBindingCandidates,
+        topic_label: options.topicLabel,
+        topic_summary_redacted: options.topicSummaryRedacted,
+        work_intent: options.workIntent,
+        work_phase: options.workPhase,
+        intent_source: options.intentSource,
+        intent_confidence: options.intentConfidence,
+        pull_request_url: existingContext?.pull_request_url,
+        provenance: {
+            capture_source: "collector_runtime",
+            capture_adapter_version: LOCAL_COLLECTOR_VERSION,
+            collector_version: LOCAL_COLLECTOR_VERSION,
+            repo: identity.repo_root,
+            branch,
+            repo_label: identity.repo_label,
+            repo_fingerprint: identity.repo_fingerprint,
+            repo_origin_url: identity.repo_origin_url ?? undefined,
+            worktree_label: identity.worktree_label,
+            worktree_fingerprint: identity.worktree_fingerprint,
+            worktree_is_primary: identity.worktree_is_primary,
+            operator_id: operatorId,
+            session_id: sessionId,
+            work_context_id: workContextId,
+        },
+    });
+}
+/**
+ * Three answers, not two: a named ticket binds, `--clear-ticket` unbinds, and
+ * saying neither leaves whatever the previous `cockpit start` bound in place.
+ */
+// The return type is inferred deliberately: naming it would mean indexing the
+// context schema by field name, and this module keeps its literals to the ones
+// that reach disk.
+function resolveTicketBinding(options, existingContext) {
+    const activeTicketId = options.clearTicket
+        ? undefined
+        : (options.activeTicketId ?? existingContext?.active_ticket_id);
+    const ticketBindingCandidates = options.activeTicketId
+        ? [
+            {
+                ticket_id: options.activeTicketId,
+                binding_source: "active_work_context",
+                confidence: 1,
+                evidence_labels: ["cockpit_start_ticket"],
+            },
+        ]
+        : options.clearTicket
+            ? []
+            : (existingContext?.ticket_binding_candidates ?? []);
+    return { activeTicketId, ticketBindingCandidates };
+}
+/** The active context: what the last `cockpit start` on this machine bound, whatever the folder. */
+export async function readLocalWorkContext(paths) {
+    return LocalWorkContextSchema.parse(await readJsonFile(paths.active_work_context_file));
+}
+/**
+ * The context for ONE repo, because a machine running two checkouts at once
+ * would otherwise attribute both to whichever was started last.
+ */
+export async function readLocalWorkContextForRepo(paths, repoRoot) {
+    const identity = await resolveIdentityOrFallback(repoRoot);
+    const context = await readLocalWorkContextByFingerprint(paths, identity.worktree_fingerprint).catch(() => null);
+    if (context)
+        return context;
+    const active = await readLocalWorkContext(paths);
+    if (active.worktree_fingerprint === identity.worktree_fingerprint ||
+        path.resolve(active.repo) === identity.repo_root) {
+        return active;
+    }
+    throw new Error(`Active work context missing for ${identity.worktree_label}. Run \`cockpit start --workspace "${identity.repo_root}"\`.`);
+}
+async function readLocalWorkContextByFingerprint(paths, worktreeFingerprint) {
+    return LocalWorkContextSchema.parse(await readJsonFile(workContextFile(paths, worktreeFingerprint)));
+}
+/**
+ * The same operator, device, repo and worktree must produce the same id on
+ * every run, because the ambient envelope joins sessions on it.
+ */
+function stableWorkContextId(input) {
+    return `work-${sha256([
+        input.operatorId,
+        input.deviceId,
+        input.repoFingerprint,
+        input.worktreeFingerprint,
+    ].join(":")).slice(0, 32)}`;
+}
+function sha256(value) {
+    return crypto.createHash("sha256").update(value, "utf8").digest("hex");
+}
+/**
+ * The label a person reads for a work context — repo over worktree, so two
+ * checkouts of one repo are told apart at a glance.
+ */
+export function workDisplayLabel(context) {
+    const repoLabel = (context.repo_label ?? path.basename(context.repo)) || "workspace";
+    const worktreeLabel = context.worktree_label ?? repoLabel;
+    return `${repoLabel}/${worktreeLabel}`;
+}