@bli-cockpit/cli 0.2.54 → 0.2.56

package/dist/spool/local-spool-mutations.js

@@ -0,0 +1,174 @@
+import crypto from "node:crypto";
+import { parseMetadataOnlySessionReportRows } from "./local-spool-parse.js";
+import { readLocalUploadSpoolState, writeUploadSpoolState } from "./local-spool-io.js";
+import { MAX_PENDING_UPLOADS, } from "./local-spool-types.js";
+/**
+ * Every state transition a sync tick can record: a blocked or failed upload
+ * attempt, a success that clears pending entries, a source that needs a
+ * wider re-scan next time, and a required session-attribution report that
+ * could not be delivered yet. Each function reads the current state, applies
+ * one transition, and writes the result back — the read-modify-write pair
+ * always happens together so no caller can race a stale write.
+ */
+export async function recordUploadBlocked(paths, options) {
+    const state = await readLocalUploadSpoolState(paths);
+    const next = {
+        ...state,
+        updated_at: options.attemptedAt,
+        last_upload_attempt_at: options.attemptedAt,
+        last_upload_failure_reason: options.reason,
+    };
+    await writeUploadSpoolState(paths, next);
+    return next;
+}
+export async function recordUploadSuccess(paths, options) {
+    const state = await readLocalUploadSpoolState(paths);
+    const pending = options.clearPendingForContext === false
+        ? state.pending_uploads
+        : state.pending_uploads.filter((entry) => entry.work_context_id !== options.workContextId);
+    const next = {
+        ...state,
+        updated_at: options.attemptedAt,
+        last_upload_attempt_at: options.attemptedAt,
+        last_upload_success_at: options.attemptedAt,
+        last_upload_failure_reason: firstPendingFailureReason({
+            ...state,
+            pending_uploads: pending,
+        }),
+        pending_uploads: pending,
+    };
+    await writeUploadSpoolState(paths, next);
+    return next;
+}
+export async function recordUploadFailure(paths, entry) {
+    const state = await readLocalUploadSpoolState(paths);
+    const createdAt = entry.created_at ?? entry.last_attempt_at;
+    const spoolEntry = {
+        spool_id: `upload-${crypto.randomUUID()}`,
+        created_at: createdAt,
+        ...entry,
+    };
+    const pending = [
+        spoolEntry,
+        ...state.pending_uploads.filter((candidate) => candidate.work_context_id !== spoolEntry.work_context_id ||
+            candidate.ticket_id !== spoolEntry.ticket_id),
+    ].slice(0, MAX_PENDING_UPLOADS);
+    await writeUploadSpoolState(paths, {
+        ...state,
+        updated_at: entry.last_attempt_at,
+        last_upload_attempt_at: entry.last_attempt_at,
+        last_upload_failure_reason: entry.failure_reason,
+        pending_uploads: pending,
+    });
+    return spoolEntry;
+}
+export async function recordSourceRetryFailure(paths, options) {
+    const state = await readLocalUploadSpoolState(paths);
+    const retryEntry = {
+        source: options.source,
+        reason: options.reason,
+        last_attempt_at: options.attemptedAt,
+    };
+    const next = {
+        ...state,
+        updated_at: options.attemptedAt,
+        last_upload_attempt_at: options.attemptedAt,
+        last_upload_failure_reason: options.reason,
+        pending_source_retries: [
+            retryEntry,
+            ...state.pending_source_retries.filter((entry) => entry.source !== options.source),
+        ],
+    };
+    await writeUploadSpoolState(paths, next);
+    return next;
+}
+export async function clearSourceRetryFailure(paths, source, attemptedAt) {
+    const state = await readLocalUploadSpoolState(paths);
+    const next = {
+        ...state,
+        updated_at: attemptedAt,
+        pending_source_retries: state.pending_source_retries.filter((entry) => entry.source !== source),
+    };
+    next.last_upload_failure_reason = firstPendingFailureReason(next);
+    await writeUploadSpoolState(paths, next);
+    return next;
+}
+export async function recordPendingSessionReport(paths, entry) {
+    const state = await readLocalUploadSpoolState(paths);
+    const existing = state.pending_session_reports.find((candidate) => candidate.work_context_id === entry.work_context_id);
+    const safeIncomingSessions = parseMetadataOnlySessionReportRows(entry.sessions, "pending_session_report.sessions");
+    const mergedSessions = mergeSessionReportRows(existing?.sessions ?? [], safeIncomingSessions);
+    const pending = {
+        report_id: existing?.report_id ?? `session-report-${crypto.randomUUID()}`,
+        created_at: existing?.created_at ?? entry.attempted_at,
+        last_attempt_at: entry.attempted_at,
+        dashboard_url: entry.dashboard_url,
+        generated_at: entry.generated_at,
+        work_context_id: entry.work_context_id,
+        repo_label: entry.repo_label,
+        branch: entry.branch,
+        repo_fingerprint: entry.repo_fingerprint,
+        repo_origin_url: entry.repo_origin_url,
+        worktree_label: entry.worktree_label,
+        worktree_fingerprint: entry.worktree_fingerprint,
+        worktree_is_primary: entry.worktree_is_primary,
+        sessions: mergedSessions,
+        failure_reason: entry.failure_reason ?? "session_report_pending",
+    };
+    const next = {
+        ...state,
+        updated_at: entry.attempted_at,
+        last_upload_attempt_at: entry.attempted_at,
+        last_upload_failure_reason: pending.failure_reason,
+        pending_session_reports: [
+            pending,
+            ...state.pending_session_reports.filter((candidate) => candidate.report_id !== pending.report_id),
+        ],
+    };
+    await writeUploadSpoolState(paths, next);
+    return pending;
+}
+export async function recordSessionReportFailure(paths, options) {
+    const state = await readLocalUploadSpoolState(paths);
+    const next = {
+        ...state,
+        updated_at: options.attemptedAt,
+        last_upload_attempt_at: options.attemptedAt,
+        last_upload_failure_reason: options.reason,
+        pending_session_reports: state.pending_session_reports.map((entry) => entry.report_id === options.reportId
+            ? {
+                ...entry,
+                last_attempt_at: options.attemptedAt,
+                failure_reason: options.reason,
+            }
+            : entry),
+    };
+    await writeUploadSpoolState(paths, next);
+    return next;
+}
+export async function recordSessionReportSuccess(paths, options) {
+    const state = await readLocalUploadSpoolState(paths);
+    const next = {
+        ...state,
+        updated_at: options.attemptedAt,
+        last_upload_attempt_at: options.attemptedAt,
+        last_upload_success_at: options.attemptedAt,
+        pending_session_reports: state.pending_session_reports.filter((entry) => entry.report_id !== options.reportId),
+    };
+    next.last_upload_failure_reason = firstPendingFailureReason(next);
+    await writeUploadSpoolState(paths, next);
+    return next;
+}
+function mergeSessionReportRows(existing, incoming) {
+    const bySession = new Map();
+    for (const session of [...existing, ...incoming]) {
+        bySession.set(`${session.source ?? "codex"}:${session.codex_session_id}`, session);
+    }
+    return [...bySession.values()];
+}
+function firstPendingFailureReason(state) {
+    return (state.pending_uploads[0]?.failure_reason ??
+        state.pending_source_retries[0]?.reason ??
+        state.pending_session_reports[0]?.failure_reason ??
+        null);
+}

package/dist/spool/local-spool-parse.js

@@ -0,0 +1,143 @@
+import { CodexSessionAttributionSchema, } from "@bli-cockpit/telemetry-core";
+/**
+ * Validates a JSON-parsed spool file against the schema by hand (no zod
+ * dependency in this package): every field is required or explicitly
+ * nullable/optional, and a malformed field fails closed instead of being
+ * silently discarded — the spool holds delivery state a green sync must not
+ * pretend was empty.
+ */
+export function parseUploadSpoolState(value) {
+    const record = requireRecord(value, "root");
+    if (record["schema_version"] !== "cockpit-upload-spool.v1") {
+        invalidUploadSpoolState("schema_version", 'literal "cockpit-upload-spool.v1"');
+    }
+    return {
+        schema_version: "cockpit-upload-spool.v1",
+        updated_at: requireNullableString(record["updated_at"], "updated_at"),
+        last_upload_attempt_at: requireNullableString(record["last_upload_attempt_at"], "last_upload_attempt_at"),
+        last_upload_success_at: requireNullableString(record["last_upload_success_at"], "last_upload_success_at"),
+        last_upload_failure_reason: requireNullableString(record["last_upload_failure_reason"], "last_upload_failure_reason"),
+        pending_uploads: requireArray(record["pending_uploads"], "pending_uploads").map((entry, index) => parseUploadSpoolEntry(entry, `pending_uploads[${index}]`)),
+        // These fields were added without changing the v1 schema version. Missing
+        // fields are therefore a valid legacy state, while present malformed fields
+        // must fail closed instead of being silently discarded.
+        pending_source_retries: optionalArray(record["pending_source_retries"], "pending_source_retries").map((entry, index) => parseSourceRetryEntry(entry, `pending_source_retries[${index}]`)),
+        pending_session_reports: optionalArray(record["pending_session_reports"], "pending_session_reports").map((entry, index) => parsePendingSessionReport(entry, `pending_session_reports[${index}]`)),
+    };
+}
+function parseUploadSpoolEntry(value, fieldPath) {
+    const record = requireRecord(value, fieldPath);
+    const retryCommand = record["retry_command"] === undefined
+        ? "cockpit sync"
+        : requireString(record["retry_command"], `${fieldPath}.retry_command`);
+    return {
+        spool_id: requireString(record["spool_id"], `${fieldPath}.spool_id`),
+        created_at: requireString(record["created_at"], `${fieldPath}.created_at`),
+        last_attempt_at: requireString(record["last_attempt_at"], `${fieldPath}.last_attempt_at`),
+        dashboard_url: requireString(record["dashboard_url"], `${fieldPath}.dashboard_url`),
+        work_context_id: requireNullableString(record["work_context_id"], `${fieldPath}.work_context_id`),
+        ticket_id: requireNullableString(record["ticket_id"], `${fieldPath}.ticket_id`),
+        repo_label: requireNullableString(record["repo_label"], `${fieldPath}.repo_label`),
+        branch: requireNullableString(record["branch"], `${fieldPath}.branch`),
+        event_count: requireNonNegativeInteger(record["event_count"], `${fieldPath}.event_count`),
+        source_scan_count: requireNonNegativeInteger(record["source_scan_count"], `${fieldPath}.source_scan_count`),
+        risk_flag_count: requireNonNegativeInteger(record["risk_flag_count"], `${fieldPath}.risk_flag_count`),
+        raw_evidence_file_count: requireNonNegativeInteger(record["raw_evidence_file_count"], `${fieldPath}.raw_evidence_file_count`),
+        retry_sources: parseRetrySources(record["retry_sources"], `${fieldPath}.retry_sources`),
+        failure_reason: requireString(record["failure_reason"], `${fieldPath}.failure_reason`),
+        retry_command: retryCommand,
+    };
+}
+function parseRetrySources(value, fieldPath) {
+    if (value === undefined)
+        return [];
+    const values = requireArray(value, fieldPath);
+    return [...new Set(values.map((source) => parseRetrySource(source, fieldPath)))];
+}
+function parseSourceRetryEntry(value, fieldPath) {
+    const record = requireRecord(value, fieldPath);
+    return {
+        source: parseRetrySource(record["source"], `${fieldPath}.source`),
+        reason: requireString(record["reason"], `${fieldPath}.reason`),
+        last_attempt_at: requireString(record["last_attempt_at"], `${fieldPath}.last_attempt_at`),
+    };
+}
+function parsePendingSessionReport(value, fieldPath) {
+    const record = requireRecord(value, fieldPath);
+    const sessions = parseMetadataOnlySessionReportRows(record["sessions"], `${fieldPath}.sessions`);
+    return {
+        report_id: requireString(record["report_id"], `${fieldPath}.report_id`),
+        created_at: requireString(record["created_at"], `${fieldPath}.created_at`),
+        last_attempt_at: requireString(record["last_attempt_at"], `${fieldPath}.last_attempt_at`),
+        dashboard_url: requireString(record["dashboard_url"], `${fieldPath}.dashboard_url`),
+        generated_at: requireString(record["generated_at"], `${fieldPath}.generated_at`),
+        work_context_id: requireString(record["work_context_id"], `${fieldPath}.work_context_id`),
+        repo_label: requireString(record["repo_label"], `${fieldPath}.repo_label`),
+        branch: requireString(record["branch"], `${fieldPath}.branch`),
+        repo_fingerprint: requireString(record["repo_fingerprint"], `${fieldPath}.repo_fingerprint`),
+        repo_origin_url: record["repo_origin_url"] === undefined
+            ? null
+            : requireNullableString(record["repo_origin_url"], `${fieldPath}.repo_origin_url`),
+        worktree_label: requireString(record["worktree_label"], `${fieldPath}.worktree_label`),
+        worktree_fingerprint: requireString(record["worktree_fingerprint"], `${fieldPath}.worktree_fingerprint`),
+        worktree_is_primary: requireBoolean(record["worktree_is_primary"], `${fieldPath}.worktree_is_primary`),
+        sessions,
+        failure_reason: requireString(record["failure_reason"], `${fieldPath}.failure_reason`),
+    };
+}
+export function parseMetadataOnlySessionReportRows(value, fieldPath) {
+    const sessions = requireArray(value, fieldPath).map((session, index) => {
+        const parsed = CodexSessionAttributionSchema.safeParse(session);
+        if (!parsed.success) {
+            invalidUploadSpoolState(`${fieldPath}[${index}]`, "metadata-only Codex session attribution");
+        }
+        return parsed.data;
+    });
+    if (sessions.length === 0) {
+        invalidUploadSpoolState(fieldPath, "non-empty array");
+    }
+    return sessions;
+}
+function parseRetrySource(value, fieldPath) {
+    if (value === "codex" || value === "claude_code")
+        return value;
+    return invalidUploadSpoolState(fieldPath, '"codex" or "claude_code"');
+}
+function requireRecord(value, fieldPath) {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        return value;
+    }
+    return invalidUploadSpoolState(fieldPath, "object");
+}
+function requireArray(value, fieldPath) {
+    if (Array.isArray(value))
+        return value;
+    return invalidUploadSpoolState(fieldPath, "array");
+}
+function optionalArray(value, fieldPath) {
+    return value === undefined ? [] : requireArray(value, fieldPath);
+}
+function requireString(value, fieldPath) {
+    if (typeof value === "string" && value.trim())
+        return value;
+    return invalidUploadSpoolState(fieldPath, "non-empty string");
+}
+function requireNullableString(value, fieldPath) {
+    if (value === null)
+        return null;
+    return requireString(value, fieldPath);
+}
+function requireNonNegativeInteger(value, fieldPath) {
+    if (typeof value === "number" && Number.isInteger(value) && value >= 0) {
+        return value;
+    }
+    return invalidUploadSpoolState(fieldPath, "non-negative integer");
+}
+function requireBoolean(value, fieldPath) {
+    if (typeof value === "boolean")
+        return value;
+    return invalidUploadSpoolState(fieldPath, "boolean");
+}
+function invalidUploadSpoolState(fieldPath, expected) {
+    throw new Error(`Upload spool state schema mismatch at ${fieldPath}; expected ${expected}.`);
+}

package/dist/spool/local-spool-types.js

@@ -0,0 +1,22 @@
+/**
+ * The shapes and tuning constants `local-spool.ts` and its siblings (io,
+ * parse, mutations) all agree on. The spool is deliberately metadata-only —
+ * hashes, ids, reason labels, and durable pointer ids, never transcript
+ * bodies or local file paths — so a later sync can reconstruct provenance
+ * and post the exact rows even after the source transcript has aged out of
+ * the normal scan window.
+ */
+export const SPOOL_STATE_FILENAME = "upload-state.json";
+export const MAX_PENDING_UPLOADS = 20;
+export function emptyUploadSpoolState() {
+    return {
+        schema_version: "cockpit-upload-spool.v1",
+        updated_at: null,
+        last_upload_attempt_at: null,
+        last_upload_success_at: null,
+        last_upload_failure_reason: null,
+        pending_uploads: [],
+        pending_source_retries: [],
+        pending_session_reports: [],
+    };
+}