@bli-cockpit/cli 0.2.28 → 0.2.30

package/dist/upload-envelope.js

@@ -0,0 +1,407 @@
+/**
+ * What a sync sends: assembling one ambient telemetry envelope.
+ *
+ * Table of contents:
+ *
+ * - `LocalUploadBlockedError` — the four reasons this machine cannot upload at
+ *   all, each carrying the command that fixes it.
+ * - `buildLocalAmbientEnvelope` — the entry point. Five steps: prove the
+ *   collector is installed and paired, find the work context for this repo,
+ *   run the source collectors, sanitize what came back, parse the envelope.
+ * - Work context and provenance — who captured this, on what machine, in which
+ *   repo and worktree.
+ * - The `source_scan_completed` event — the single event every sync sends,
+ *   built from the facts the collectors gathered.
+ * - Sanitizers — the last gate before anything leaves the machine. Local paths,
+ *   long diagnostic strings and nested pointers are stripped here.
+ *
+ * Nothing in this file performs network I/O. `upload.ts` delivers what this
+ * file assembles.
+ */
+import { TelemetryIngestEnvelopeSchema, TelemetryIngestEventDtoSchema, } from "@bli-cockpit/telemetry-core";
+import path from "node:path";
+import { getCollectorRuntimePaths, LOCAL_COLLECTOR_VERSION, readLocalCollectorConfig, readLocalCollectorSessionFile, readLocalSessionReference, readLocalWorkContextForRepo, } from "./local-state.js";
+import { runLocalSourceCollectors } from "./adapters/local-sources.js";
+import { defaultCodexSessionDirs, } from "./adapters/codex-attribution.js";
+import { normalizeDashboardUrl } from "./upload-http.js";
+export class LocalUploadBlockedError extends Error {
+    blocker;
+    retry_hint;
+    constructor(blocker, message, retryHint) {
+        super(message);
+        this.name = "LocalUploadBlockedError";
+        this.blocker = blocker;
+        this.retry_hint = retryHint;
+    }
+}
+export async function buildLocalAmbientEnvelope(options = {}) {
+    const now = options.now ?? new Date();
+    const paths = getCollectorRuntimePaths(options.homeDir);
+    const collector = await readPairedCollector(paths);
+    const { config, sessionFile, session } = collector;
+    const repoRoot = path.resolve(options.repoRoot ?? process.cwd());
+    const activeContext = await readLocalWorkContextForRepo(paths, repoRoot).catch(() => {
+        throw new LocalUploadBlockedError("missing_context", "Active work context missing. Run `cockpit start --workspace \"$PWD\"` before `cockpit sync`.", "cockpit start --workspace \"$PWD\"");
+    });
+    const repoLabel = safeRepoLabel(activeContext.repo_label ?? repoRoot);
+    const uploadContext = makeUploadWorkContext({
+        activeContext,
+        session,
+        repoLabel,
+        now,
+    });
+    const sourceCollection = await runLocalSourceCollectors({
+        repoRoot,
+        branch: uploadContext.branch,
+        operatorId: session.operator_id,
+        operatorLabel: session.email ?? session.auth_subject_id,
+        sessionId: session.session_id,
+        workContextId: uploadContext.work_context_id,
+        activeWorkContext: activeContext,
+        rawEvidenceStateDir: paths.state_dir,
+        rawEvidenceSessionsDirs: defaultCodexSessionDirs(paths.home_dir),
+        claudeProjectsDir: path.join(paths.home_dir, ".claude", "projects"),
+        rawEvidenceIncludeCodexJsonl: options.rawEvidenceIncludeCodexJsonl,
+        rawEvidenceIncludeClaudeJsonl: options.rawEvidenceIncludeClaudeJsonl,
+        rawEvidenceCodexSessionFiles: options.codexSessionFiles,
+        rawEvidenceCodexAttributionScan: options.codexAttributionScan,
+        rawEvidenceClaudeSessionFiles: options.claudeSessionFiles,
+        rawEvidenceClaudeAttributionScan: options.claudeAttributionScan,
+        rawEvidenceSkipContentHashes: reusableContentHashes(options, {
+            operatorId: session.operator_id,
+            workContextId: uploadContext.work_context_id,
+        }),
+        rawEvidenceByteBudget: options.rawEvidenceByteBudget,
+        rawEvidenceObjectBudget: options.rawEvidenceObjectBudget,
+        rawEvidenceBudget: options.rawEvidenceBudget,
+        rawEvidenceDeliveryMode: options.evidenceDeliveryMode,
+        now,
+    });
+    const binding = sourceCollection.binding;
+    const ticketBinding = selectedTicketBindingCandidate(binding);
+    const uploadWorkContext = {
+        ...uploadContext,
+        active_ticket_id: binding.selected_ticket_id ?? undefined,
+        ticket_binding_candidates: ticketBinding ? [ticketBinding] : binding.candidates,
+    };
+    const safeRiskFlags = sourceCollection.risk_flags.map((flag) => sanitizeRiskFlag(flag, repoLabel));
+    const events = [
+        makeSourceScanCompletedEvent({
+            context: uploadWorkContext,
+            generatedAt: now.toISOString(),
+            binding,
+            ticketBinding,
+            scans: sourceCollection.scans,
+            gitChangedFileCount: sourceCollection.facts.git?.changed_file_count ?? 0,
+            gitAddedLines: sourceCollection.facts.git?.added_lines ?? 0,
+            gitDeletedLines: sourceCollection.facts.git?.deleted_lines ?? 0,
+            carOpenTicketCount: sourceCollection.facts.car?.open_ticket_count ?? 0,
+            rawEvidenceFacts: sourceCollection.facts.raw_evidence,
+            riskFlags: safeRiskFlags,
+        }),
+    ];
+    const envelope = TelemetryIngestEnvelopeSchema.parse({
+        envelope_version: "telemetry-ingest.v1",
+        generated_at: now.toISOString(),
+        collector_version: LOCAL_COLLECTOR_VERSION,
+        session_reference: sanitizeSessionReference(session),
+        work_context: uploadWorkContext,
+        worktree_inventory: options.worktreeInventory ?? [],
+        source_scan_results: sanitizeSourceScanResults(sourceCollection.scans, repoLabel),
+        events,
+    });
+    return {
+        envelope,
+        dashboard_url: normalizeDashboardUrl(options.dashboardUrl ?? sessionFile.dashboard_url ?? config.dashboard_url),
+        device_token: sessionFile.device_token,
+        ticket_id: binding.selected_ticket_id ?? null,
+        binding,
+        event_count: envelope.events.length,
+        source_scan_count: envelope.source_scan_results.length,
+        risk_flag_count: safeRiskFlags.length,
+        repo_label: repoLabel,
+        head_sha: uploadContext.head_sha ?? null,
+        raw_evidence_upload_files: sourceCollection.facts.raw_evidence?.upload_files ?? [],
+        raw_evidence_facts: sourceCollection.facts.raw_evidence,
+    };
+}
+/**
+ * Is this machine installed, paired, and holding a session that has not lapsed?
+ *
+ * Three ways to fail, each with its own command to run, because "sync failed"
+ * with no next step is what turns a five-second fix into a support thread.
+ */
+async function readPairedCollector(paths) {
+    const config = await readLocalCollectorConfig(paths).catch(() => {
+        throw new LocalUploadBlockedError("not_installed", "Local collector config missing. Install/update the CLI, then run `cockpit do-everything` before `cockpit sync`.", "npm install -g @bli-cockpit/cli@latest && cockpit do-everything");
+    });
+    const sessionFile = await readLocalCollectorSessionFile(paths).catch(() => {
+        throw new LocalUploadBlockedError("unpaired", "No paired collector session found. Run `cockpit login` or `cockpit pair` before `cockpit sync`.", "cockpit login");
+    });
+    const session = await readLocalSessionReference(paths);
+    if (session.session_state !== "valid") {
+        throw new LocalUploadBlockedError("unpaired", session.session_state === "expired"
+            ? "Collector session expired. Run `cockpit login` or `cockpit pair` again before `cockpit sync`."
+            : "Collector is not paired. Run `cockpit login` or `cockpit pair` before `cockpit sync`.", "cockpit login");
+    }
+    return { config, sessionFile, session };
+}
+/**
+ * Content hashes whose bytes are already durable and may be skipped this sync.
+ *
+ * Object keys embed the work context, so a cursor entry only counts as reuse
+ * when it was committed under THIS operator and context. The same bytes under a
+ * different context still need their own pointer and evidence ref.
+ */
+function reusableContentHashes(options, context) {
+    if (options.skipContentHashes)
+        return options.skipContentHashes;
+    return new Set(Object.entries(options.cursorObjects ?? {})
+        .filter(([, entry]) => rawEvidenceObjectKeyBelongsToWorkContext(entry.object_key, context))
+        .map(([hash]) => hash));
+}
+export function makeUploadWorkContext(options) {
+    const provenance = makeCollectorProvenance({
+        context: options.activeContext,
+        session: options.session,
+        repoLabel: options.repoLabel,
+    });
+    return {
+        ...options.activeContext,
+        repo: options.repoLabel,
+        repo_label: options.activeContext.repo_label ?? options.repoLabel,
+        repo_fingerprint: options.activeContext.repo_fingerprint,
+        repo_origin_url: options.activeContext.repo_origin_url,
+        head_sha: options.activeContext.head_sha,
+        worktree_label: options.activeContext.worktree_label,
+        worktree_fingerprint: options.activeContext.worktree_fingerprint,
+        worktree_is_primary: options.activeContext.worktree_is_primary,
+        operator_id: options.session.operator_id,
+        session_id: options.session.session_id,
+        updated_at: options.now.toISOString(),
+        provenance,
+    };
+}
+export function makeCollectorProvenance(options) {
+    return {
+        capture_source: "collector_runtime",
+        capture_adapter_version: LOCAL_COLLECTOR_VERSION,
+        collector_version: LOCAL_COLLECTOR_VERSION,
+        repo: options.repoLabel,
+        branch: options.context.branch,
+        repo_label: options.context.repo_label ?? options.repoLabel,
+        repo_fingerprint: options.context.repo_fingerprint,
+        repo_origin_url: options.context.repo_origin_url,
+        worktree_label: options.context.worktree_label,
+        worktree_fingerprint: options.context.worktree_fingerprint,
+        worktree_is_primary: options.context.worktree_is_primary,
+        operator_id: options.session.operator_id,
+        session_id: options.session.session_id,
+        work_context_id: options.context.work_context_id,
+    };
+}
+/**
+ * The one event every sync sends.
+ *
+ * Its privacy story turns on a single question — did this sync produce raw
+ * evidence objects? If it did, the bytes went to durable storage separately and
+ * this event carries only references to them; if it did not, the event is pure
+ * metadata. Both the classification and the human-readable summary follow from
+ * that, so it is computed once here and threaded through.
+ */
+function makeSourceScanCompletedEvent(options) {
+    if (!options.context.provenance) {
+        throw new Error("Upload work context is missing provenance.");
+    }
+    const rawEvidencePointers = options.rawEvidenceFacts?.pointers ?? [];
+    const hasRawEvidence = rawEvidencePointers.length > 0;
+    const eventPrivacyClassification = hasRawEvidence
+        ? "redacted_summary"
+        : "metadata";
+    return TelemetryIngestEventDtoSchema.parse({
+        event_id: `ambient-sync:${options.context.work_context_id}:${options.generatedAt}`,
+        event_type: "source_scan_completed",
+        occurred_at: options.generatedAt,
+        provenance: options.context.provenance,
+        privacy_classification: eventPrivacyClassification,
+        redaction: {
+            privacy_classification: eventPrivacyClassification,
+            redaction_status: hasRawEvidence
+                ? "raw_remote_durable"
+                : "metadata_only",
+            redacted_fields: [
+                "prompt_body",
+                "response_body",
+                "diff_body",
+                "transcript_body",
+                "git.changed_paths",
+                "local_file_paths",
+            ],
+            raw_evidence_pointer_ids: rawEvidencePointers.map((pointer) => pointer.raw_evidence_pointer_id),
+            redacted_summary: hasRawEvidence
+                ? "Collector uploaded raw evidence objects separately and sent only references, hashes, source scan, binding, and risk summaries to ingest."
+                : "Collector uploaded metadata-only local work, source scan, binding, and risk summaries.",
+        },
+        redacted_summary: hasRawEvidence
+            ? "Collector uploaded raw evidence objects separately, then sent evidence references and metadata summaries."
+            : "Collector uploaded metadata-only source scan, ticket binding, and risk summaries.",
+        metrics: sourceScanEventMetrics(options),
+        attributes: sourceScanEventAttributes(options, hasRawEvidence),
+        evidence_completeness: options.rawEvidenceFacts?.evidence_completeness,
+        ticket_binding: options.ticketBinding ?? undefined,
+        risk_flags: options.riskFlags,
+        raw_evidence_pointers: rawEvidencePointers,
+    });
+}
+/** Every number this sync counted, all of them safe to publish. */
+function sourceScanEventMetrics(options) {
+    const evidenceCompleteness = options.rawEvidenceFacts?.evidence_completeness;
+    return {
+        git_changed_file_count: options.gitChangedFileCount,
+        git_added_lines: options.gitAddedLines,
+        git_deleted_lines: options.gitDeletedLines,
+        car_open_ticket_count: options.carOpenTicketCount,
+        source_scan_count: options.scans.length,
+        risk_flag_count: options.riskFlags.length,
+        raw_evidence_file_count: options.rawEvidenceFacts?.file_count ?? 0,
+        raw_evidence_byte_size: options.rawEvidenceFacts?.byte_size ?? 0,
+        raw_evidence_skipped_count: options.rawEvidenceFacts?.skipped_count ?? 0,
+        raw_evidence_sanitized_count: options.rawEvidenceFacts?.sanitized_count ?? 0,
+        raw_evidence_reused_count: options.rawEvidenceFacts?.reused_count ?? 0,
+        evidence_scanned_count: evidenceCompleteness?.totals.scanned_count ?? 0,
+        evidence_included_count: evidenceCompleteness?.totals.included_count ?? 0,
+        evidence_skipped_count: evidenceCompleteness?.totals.skipped_count ?? 0,
+        evidence_truncated_count: evidenceCompleteness?.totals.truncated_count ?? 0,
+        evidence_deferred_count: evidenceCompleteness?.totals.deferred_count ?? 0,
+        evidence_reused_count: evidenceCompleteness?.totals.reused_count ?? 0,
+        evidence_failed_count: evidenceCompleteness?.totals.failed_count ?? 0,
+    };
+}
+/**
+ * Where and what this work was, plus the two claims a reader must be able to
+ * check without opening anything: nothing raw is in here, and here is how
+ * complete the evidence behind it actually is. Absent completeness reads as
+ * incomplete on purpose — silence is not a clean bill of health.
+ */
+function sourceScanEventAttributes(options, hasRawEvidence) {
+    const evidenceCompleteness = options.rawEvidenceFacts?.evidence_completeness;
+    return {
+        repo_label: options.context.repo,
+        repo_fingerprint: options.context.repo_fingerprint ?? "unknown",
+        worktree_label: options.context.worktree_label ?? "unknown",
+        worktree_fingerprint: options.context.worktree_fingerprint ?? "unknown",
+        worktree_is_primary: options.context.worktree_is_primary ?? false,
+        branch: options.context.branch,
+        ticket_binding_state: options.binding.state,
+        ticket_binding_source: options.binding.selected_source ?? "none",
+        ticket_id: options.binding.selected_ticket_id ?? "unbound",
+        source_adapters: options.scans.map((scan) => scan.adapter.adapter_name),
+        source_statuses: options.scans.map((scan) => `${scan.adapter.adapter_name}:${scan.status}`),
+        redaction_mode: hasRawEvidence
+            ? "remote_durable_raw_evidence"
+            : "metadata_only",
+        raw_payload_included: false,
+        evidence_completeness_schema_version: evidenceCompleteness?.schema_version ?? "evidence-completeness.v1",
+        evidence_completeness_status: evidenceCompleteness?.status ?? "unknown",
+        evidence_incomplete: evidenceCompleteness
+            ? evidenceCompleteness.status !== "complete"
+            : true,
+        ...(options.context.topic_label
+            ? { topic_label: options.context.topic_label }
+            : {}),
+        ...(options.context.topic_summary_redacted
+            ? { topic_summary_redacted: options.context.topic_summary_redacted }
+            : {}),
+        ...(options.context.work_intent
+            ? { work_intent: options.context.work_intent }
+            : {}),
+        ...(options.context.work_phase
+            ? { work_phase: options.context.work_phase }
+            : {}),
+        ...(options.context.intent_source
+            ? { intent_source: options.context.intent_source }
+            : {}),
+        ...(options.context.intent_confidence !== undefined
+            ? { intent_confidence: options.context.intent_confidence }
+            : {}),
+    };
+}
+function sanitizeSessionReference(session) {
+    return {
+        ...session,
+        session_file_path: "local-session-file",
+    };
+}
+/**
+ * Scan results carry their own nested events, and those events must not smuggle
+ * evidence pointers into the envelope — the top-level event owns the pointers,
+ * and a duplicate ref here would be counted twice by the ingest receipt.
+ */
+function sanitizeSourceScanResults(scans, repoLabel) {
+    return scans.map((scan) => ({
+        ...scan,
+        diagnostic_labels: scan.diagnostic_labels.map(sanitizeDiagnosticLabel),
+        events: scan.events.map((event) => ({
+            ...event,
+            raw_evidence_pointers: [],
+            redaction: {
+                ...event.redaction,
+                raw_evidence_pointer_ids: [],
+            },
+        })),
+        risk_flags: scan.risk_flags.map((flag) => sanitizeRiskFlag(flag, repoLabel)),
+    }));
+}
+/**
+ * A diagnostic label that carries a newline or a path separator is a local path
+ * or a stack trace wearing a label's clothes; keep the prefix, drop the rest.
+ */
+function sanitizeDiagnosticLabel(label) {
+    if (label.includes("\n") || label.includes("/") || label.includes("\\")) {
+        const prefix = label.split(":", 1)[0]?.trim();
+        return prefix ? `${prefix}:redacted` : "diagnostic_redacted";
+    }
+    return label.length > 160 ? `${label.slice(0, 157)}...` : label;
+}
+function sanitizeRiskFlag(flag, repoLabel) {
+    return {
+        ...flag,
+        provenance: {
+            ...flag.provenance,
+            repo: repoLabel,
+        },
+    };
+}
+/**
+ * The candidate the binding actually selected, synthesised when the resolver
+ * chose a ticket that is not in its own candidate list (a `cockpit start`
+ * binding, for instance, which is a decision rather than a guess).
+ */
+function selectedTicketBindingCandidate(binding) {
+    if (!binding.selected_ticket_id || !binding.selected_source)
+        return null;
+    return (binding.candidates.find((candidate) => candidate.ticket_id === binding.selected_ticket_id &&
+        candidate.binding_source === binding.selected_source) ?? {
+        ticket_id: binding.selected_ticket_id,
+        binding_source: binding.selected_source,
+        confidence: 1,
+        evidence_labels: [`bound_by:${binding.selected_source}`],
+    });
+}
+/** The basename of a repo root, never the path that led to it. */
+export function safeRepoLabel(repoRoot) {
+    const basename = path.basename(repoRoot.replace(/[\\/]+$/, ""));
+    return basename || "repo";
+}
+/**
+ * Does this durable object belong to the operator and work context now syncing?
+ *
+ * Two key shapes are live: the original `<operator>/<context>/...` prefix and
+ * the readable `operators/.../ids/<operator>/<context>/...` layout.
+ */
+function rawEvidenceObjectKeyBelongsToWorkContext(objectKey, context) {
+    const legacyPrefix = `${context.operatorId}/${context.workContextId}/`;
+    const readableIdGuard = `/ids/${context.operatorId}/${context.workContextId}/`;
+    return (objectKey.startsWith(legacyPrefix) ||
+        (objectKey.startsWith("operators/") && objectKey.includes(readableIdGuard)));
+}