@bli-cockpit/cli 0.1.6 → 0.1.8

package/dist/adapters/claude-attribution.js

@@ -0,0 +1,535 @@
+import { SECRET_FILE_SEGMENT_PATTERN, containsSecretLikeContent, } from "@bli-cockpit/telemetry-core";
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import { createReadStream } from "node:fs";
+import path from "node:path";
+import { StringDecoder } from "node:string_decoder";
+import { SESSION_FILE_UUID_PATTERN, isPathWithin, sanitizeSessionId, scoreSignalsAgainstWorktrees, sessionIdFromFileName, shortHash, } from "./attribution-core.js";
+/**
+ * Deterministic Claude Code session JSONL -> repo/worktree attribution.
+ *
+ * Mirrors the Codex adapter, built on the shared attribution-core. Only
+ * allowlisted envelope fields are ever read from a transcript — `type`, `cwd`,
+ * `gitBranch`, `sessionId`, and `prRepository` on pr-link records. Message
+ * bodies, prompts, AI titles, tool results, attachments, and snapshots are
+ * never extracted, printed, or summarized.
+ *
+ * Transcript layout (verified):
+ *   ~/.claude/projects/<path-slug>/
+ *     <session-uuid>.jsonl                       main transcript
+ *     <session-uuid>/subagents/agent-*.jsonl     subagent transcripts (D3)
+ * `tool-results/`, `workflows/`, `memory/`, and `*.meta.json` are never walked.
+ */
+export const CLAUDE_ATTRIBUTION_DEFAULT_SINCE_MINUTES = 24 * 60;
+export const CLAUDE_ATTRIBUTION_DEFAULT_SESSION_LIMIT = 50;
+// Upload cap, NOT an attribution cap (D7): an oversized main file is still
+// scored and attributed via a streamed read; only the file's bytes stay local.
+export const CLAUDE_SESSION_MAX_FILE_BYTES = 10 * 1024 * 1024;
+export const CLAUDE_SESSION_MAX_SIDECAR_FILES = 40;
+// JSONL lines holding a large tool result can be multi-MiB; a streamed read of
+// an oversized main caps the per-line buffer so one giant line cannot blow
+// memory. Lines over the cap are skipped + counted; the head is still guarded.
+const MAX_LINE_BUFFER_BYTES = 2 * 1024 * 1024;
+const SCHEMA_DRIFT_MIN_RECORDS = 20;
+const SCHEMA_DRIFT_MIN_HIT_RATE = 0.5;
+const CONTENT_RECORD_TYPES = new Set([
+    "user",
+    "assistant",
+    "system",
+    "attachment",
+]);
+export async function scanAndAttributeClaudeSessions(options) {
+    const sinceMinutes = options.sinceMinutes ?? CLAUDE_ATTRIBUTION_DEFAULT_SINCE_MINUTES;
+    const limit = options.limit ?? CLAUDE_ATTRIBUTION_DEFAULT_SESSION_LIMIT;
+    const cutoffMs = options.now.getTime() - sinceMinutes * 60 * 1000;
+    const discovery = await discoverClaudeSessions(options.projectsDir, cutoffMs);
+    const sessions = discovery.sessions
+        .sort((a, b) => b.recencyMs - a.recencyMs)
+        .slice(0, limit);
+    const results = [];
+    for (const session of sessions) {
+        results.push(await attributeOneSession(session, options.worktrees));
+    }
+    const sumBy = (pick) => results.reduce((total, result) => total + pick(result), 0);
+    const countState = (state) => results.filter((result) => result.state === state).length;
+    return {
+        results,
+        scanned_session_count: sessions.length,
+        project_dirs_skipped: discovery.projectDirsSkipped,
+        counts: {
+            attributed: countState("attributed"),
+            ambiguous: countState("ambiguous"),
+            unattributed: countState("unattributed"),
+            skipped: countState("skipped"),
+            mains_oversized: results.filter((result) => result.main_file_oversized)
+                .length,
+            oversized_lines_skipped: sumBy((result) => result.oversized_lines_skipped),
+            sessions_schema_drift: results.filter((result) => result.signals.includes("schema_drift_suspected")).length,
+            sidecars_capped: sumBy((result) => result.sidecars_capped),
+        },
+    };
+}
+async function discoverClaudeSessions(projectsDir, cutoffMs) {
+    const sessions = [];
+    let projectDirsSkipped = 0;
+    let projectEntries;
+    try {
+        projectEntries = await fs.readdir(projectsDir, { withFileTypes: true });
+    }
+    catch {
+        return { sessions, projectDirsSkipped };
+    }
+    for (const projectEntry of projectEntries) {
+        if (!projectEntry.isDirectory())
+            continue;
+        // A project slug encodes the full cwd, so a repo named e.g.
+        // `credentials-service` poisons its slug. Never read inside such a dir, but
+        // count the skip so a whole repo silently missing is visible (D12). The
+        // slug itself is a local path encoding and never printed.
+        if (isSecretLikePath(projectEntry.name)) {
+            projectDirsSkipped += 1;
+            continue;
+        }
+        const projectDir = path.join(projectsDir, projectEntry.name);
+        let sessionEntries;
+        try {
+            sessionEntries = await fs.readdir(projectDir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const sessionEntry of sessionEntries) {
+            if (!sessionEntry.isFile())
+                continue;
+            if (!SESSION_FILE_UUID_PATTERN.test(sessionEntry.name))
+                continue;
+            const mainFile = path.join(projectDir, sessionEntry.name);
+            let mainStat;
+            try {
+                mainStat = await fs.stat(mainFile);
+            }
+            catch {
+                continue;
+            }
+            const sessionUuid = sessionEntry.name.replace(/\.jsonl$/i, "");
+            const { sidecars, sidecarsCapped } = await discoverSidecars(path.join(projectDir, sessionUuid, "subagents"));
+            const recencyMs = Math.max(mainStat.mtimeMs, ...sidecars.map((sidecar) => sidecar.mtimeMs));
+            // D10: a session is recent if its main file OR any sidecar is in window.
+            if (recencyMs < cutoffMs)
+                continue;
+            sessions.push({
+                mainFile,
+                mainMtimeMs: mainStat.mtimeMs,
+                mainByteSize: mainStat.size,
+                recencyMs,
+                sidecars,
+                sidecarsCapped,
+            });
+        }
+    }
+    return { sessions, projectDirsSkipped };
+}
+async function discoverSidecars(subagentsDir) {
+    let entries;
+    try {
+        entries = await fs.readdir(subagentsDir, { withFileTypes: true });
+    }
+    catch {
+        return { sidecars: [], sidecarsCapped: 0 };
+    }
+    const discovered = [];
+    for (const entry of entries) {
+        // Only agent transcripts. `*.meta.json` carry operator-authored
+        // descriptions and are never harvested (D3).
+        if (!entry.isFile())
+            continue;
+        if (!entry.name.startsWith("agent-") || !entry.name.endsWith(".jsonl")) {
+            continue;
+        }
+        const local_path = path.join(subagentsDir, entry.name);
+        let stat;
+        try {
+            stat = await fs.stat(local_path);
+        }
+        catch {
+            continue;
+        }
+        discovered.push({
+            local_path,
+            file_name: entry.name,
+            mtimeMs: stat.mtimeMs,
+            byteSize: stat.size,
+        });
+    }
+    discovered.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    const capped = Math.max(0, discovered.length - CLAUDE_SESSION_MAX_SIDECAR_FILES);
+    return {
+        sidecars: discovered.slice(0, CLAUDE_SESSION_MAX_SIDECAR_FILES),
+        sidecarsCapped: capped,
+    };
+}
+async function attributeOneSession(session, worktrees) {
+    const fileName = path.basename(session.mainFile);
+    const base = {
+        file_path: session.mainFile,
+        file_name: fileName,
+        claude_session_id: sessionIdFromFileName(fileName) ?? shortHash(session.mainFile),
+        cwd_basename: null,
+        cwd_hash: null,
+        session_file_mtime: new Date(session.mainMtimeMs).toISOString(),
+        session_file_mtime_ms: session.mainMtimeMs,
+        session_recency_ms: session.recencyMs,
+        byte_size: session.mainByteSize,
+        content_hash_sha256: null,
+        main_file_oversized: false,
+        oversized_lines_skipped: 0,
+        sidecars_capped: session.sidecarsCapped,
+        sidecar_files: [],
+    };
+    if (isSecretLikePath(fileName)) {
+        return skippedResult(base, "secret_like_file_name");
+    }
+    if (session.mainByteSize === 0) {
+        return skippedResult(base, "empty_file");
+    }
+    let signals;
+    let secretLike;
+    const oversized = session.mainByteSize > CLAUDE_SESSION_MAX_FILE_BYTES;
+    if (oversized) {
+        // D7: stream the oversized main so signals + secret guard still run, but the
+        // bytes themselves are never uploaded (collection skips it as file_too_large).
+        let streamed;
+        try {
+            streamed = await streamMainSignals(session.mainFile);
+        }
+        catch {
+            // A read race on one oversized main must not abort the whole scan; honor
+            // the per-file skip contract.
+            return skippedResult(base, "file_read_failed");
+        }
+        signals = streamed.signals;
+        secretLike = streamed.secretLike;
+        base.content_hash_sha256 = streamed.contentHash;
+        base.byte_size = streamed.byteSize;
+        base.main_file_oversized = true;
+        base.oversized_lines_skipped = streamed.oversizedLinesSkipped;
+    }
+    else {
+        let raw;
+        try {
+            raw = await fs.readFile(session.mainFile);
+        }
+        catch {
+            return skippedResult(base, "file_read_failed");
+        }
+        const content = raw.toString("utf8");
+        base.content_hash_sha256 = sha256(raw);
+        base.byte_size = raw.byteLength;
+        if (content.trim() === "") {
+            return skippedResult(base, "empty_file");
+        }
+        signals = extractClaudeSessionSignals(content);
+        secretLike = containsSecretLikeContent(content);
+    }
+    if (secretLike) {
+        return skippedResult(base, "secret_like_content_guard");
+    }
+    const metaSessionId = sanitizeSessionId(signals.session_ids[0]);
+    if (metaSessionId) {
+        base.claude_session_id = metaSessionId;
+    }
+    const primaryCwd = signals.cwds[0] ?? null;
+    if (primaryCwd) {
+        base.cwd_basename = path.basename(primaryCwd) || null;
+        base.cwd_hash = shortHash(primaryCwd);
+    }
+    if (signals.line_count === 0 || signals.parse_error_count === signals.line_count) {
+        return {
+            ...base,
+            state: "unattributed",
+            reason: "jsonl_parse_failed",
+            signals: [],
+            attribution_score: 0,
+            path_score: 0,
+            worktree: null,
+        };
+    }
+    const outcome = scoreSignalsAgainstWorktrees({
+        cwds: signals.cwds,
+        workspaceRoots: [],
+        originUrls: signals.repository_urls,
+        branches: signals.branches,
+        headShas: [],
+    }, worktrees, { originLabel: "pr_repo_match" });
+    const extraSignals = [];
+    if (base.main_file_oversized)
+        extraSignals.push("main_file_oversized");
+    if (isSchemaDriftSuspected(signals))
+        extraSignals.push("schema_drift_suspected");
+    const sidecarFiles = outcome.state === "attributed" && outcome.worktree
+        ? await collectSidecarDiagnostics(session.sidecars, outcome.worktree)
+        : session.sidecars.map((sidecar) => ({
+            local_path: sidecar.local_path,
+            file_name: sidecar.file_name,
+            byte_size: sidecar.byteSize,
+            content_hash_sha256: null,
+            skipped_reason: null,
+        }));
+    return {
+        ...base,
+        state: outcome.state,
+        reason: outcome.reason,
+        signals: [...outcome.signals, ...extraSignals],
+        attribution_score: outcome.attribution_score,
+        path_score: outcome.path_score,
+        worktree: outcome.worktree,
+        sidecar_files: sidecarFiles,
+    };
+}
+/**
+ * Validates and content-addresses an attributed session's sidecars. Each
+ * sidecar's envelope cwd must resolve within the attributed worktree root, or
+ * it is skipped `sidecar_cwd_mismatch` rather than uploaded under the wrong
+ * work context. The secret guard and size cap run here too; a guarded or
+ * oversized sidecar is recorded with a reason and the session stays
+ * harvestable.
+ */
+async function collectSidecarDiagnostics(sidecars, worktree) {
+    const out = [];
+    for (const sidecar of sidecars) {
+        const entry = {
+            local_path: sidecar.local_path,
+            file_name: sidecar.file_name,
+            byte_size: sidecar.byteSize,
+            content_hash_sha256: null,
+            skipped_reason: null,
+        };
+        if (isSecretLikePath(sidecar.file_name)) {
+            out.push({ ...entry, skipped_reason: "secret_like_file_name" });
+            continue;
+        }
+        if (sidecar.byteSize > CLAUDE_SESSION_MAX_FILE_BYTES) {
+            out.push({ ...entry, skipped_reason: "file_too_large" });
+            continue;
+        }
+        let raw;
+        try {
+            raw = await fs.readFile(sidecar.local_path);
+        }
+        catch {
+            out.push({ ...entry, skipped_reason: "file_read_failed" });
+            continue;
+        }
+        const content = raw.toString("utf8");
+        if (containsSecretLikeContent(content)) {
+            out.push({ ...entry, skipped_reason: "secret_like_content_guard" });
+            continue;
+        }
+        const sidecarCwds = extractClaudeSessionSignals(content).cwds;
+        if (sidecarCwds.length > 0 &&
+            !sidecarCwds.some((cwd) => isPathWithin(cwd, worktree.repo_root))) {
+            out.push({ ...entry, skipped_reason: "sidecar_cwd_mismatch" });
+            continue;
+        }
+        out.push({
+            ...entry,
+            byte_size: raw.byteLength,
+            content_hash_sha256: sha256(raw),
+        });
+    }
+    return out;
+}
+/**
+ * Allowlisted signal extraction. Reads only `type`, `cwd`, `gitBranch`,
+ * `sessionId`, and `prRepository` (pr-link records). Structurally identical to
+ * the Codex extractor, with the allowlist enforced by construction — no generic
+ * record walk that could surface message bodies.
+ */
+export function extractClaudeSessionSignals(content) {
+    const accumulator = createSignalAccumulator();
+    for (const line of content.split("\n")) {
+        accumulator.processLine(line);
+    }
+    return accumulator.finalize();
+}
+function createSignalAccumulator() {
+    const sessionIds = new Set();
+    const cwds = new Set();
+    const branches = new Set();
+    const repositoryUrls = new Set();
+    let lineCount = 0;
+    let parseErrorCount = 0;
+    let contentRecordCount = 0;
+    let contentRecordsWithEnvelope = 0;
+    return {
+        processLine(line) {
+            if (!line.trim())
+                return;
+            lineCount += 1;
+            let record;
+            try {
+                record = JSON.parse(line);
+            }
+            catch {
+                parseErrorCount += 1;
+                return;
+            }
+            if (!record || typeof record !== "object")
+                return;
+            const entry = record;
+            const type = typeof entry["type"] === "string" ? entry["type"] : "";
+            const cwd = stringOrNull(entry["cwd"]);
+            const sessionId = stringOrNull(entry["sessionId"]);
+            if (cwd)
+                cwds.add(cwd);
+            if (sessionId)
+                sessionIds.add(sessionId);
+            const branch = stringOrNull(entry["gitBranch"]);
+            if (branch)
+                branches.add(branch);
+            if (type === "pr-link") {
+                const repository = stringOrNull(entry["prRepository"]);
+                if (repository)
+                    repositoryUrls.add(normalizePrRepository(repository));
+            }
+            // D11 canary input: among content records, how many carry both cwd and
+            // sessionId. gitBranch is intentionally excluded — it is legitimately
+            // absent in non-git directories and would false-positive desktop sessions.
+            if (CONTENT_RECORD_TYPES.has(type)) {
+                contentRecordCount += 1;
+                if (cwd && sessionId)
+                    contentRecordsWithEnvelope += 1;
+            }
+        },
+        finalize() {
+            return {
+                session_ids: [...sessionIds],
+                cwds: [...cwds],
+                branches: [...branches],
+                repository_urls: [...repositoryUrls],
+                line_count: lineCount,
+                parse_error_count: parseErrorCount,
+                content_record_count: contentRecordCount,
+                envelope_field_hit_rate: contentRecordCount === 0
+                    ? 1
+                    : contentRecordsWithEnvelope / contentRecordCount,
+            };
+        },
+    };
+}
+function isSchemaDriftSuspected(signals) {
+    // Only meaningful with enough records to be a signal, not noise.
+    if (signals.line_count < SCHEMA_DRIFT_MIN_RECORDS)
+        return false;
+    // A `type`-field rename yields zero recognized content records, which would
+    // otherwise leave the hit-rate defaulted to 1 and hide the most structural
+    // drift the canary exists to catch — flag a record-heavy file with no
+    // recognizable content records too.
+    if (signals.content_record_count === 0)
+        return true;
+    return signals.envelope_field_hit_rate < SCHEMA_DRIFT_MIN_HIT_RATE;
+}
+async function streamMainSignals(filePath) {
+    const accumulator = createSignalAccumulator();
+    const hash = crypto.createHash("sha256");
+    let secretLike = false;
+    let oversizedLinesSkipped = 0;
+    let byteSize = 0;
+    let pending = "";
+    let pendingTruncated = false;
+    const flushCompletedLine = (lineText) => {
+        if (pendingTruncated) {
+            // The line exceeded the buffer; guard the head we retained, count it, drop.
+            oversizedLinesSkipped += 1;
+            if (containsSecretLikeContent(pending))
+                secretLike = true;
+            pending = "";
+            pendingTruncated = false;
+            return;
+        }
+        const full = pending + lineText;
+        pending = "";
+        if (containsSecretLikeContent(full))
+            secretLike = true;
+        accumulator.processLine(full);
+    };
+    // StringDecoder buffers an incomplete multibyte char across chunk boundaries
+    // so a UTF-8 character split by the read boundary never decodes to a fragment
+    // that could weaken the secret guard or corrupt a cwd signal. The content
+    // hash is over raw bytes (below) and is unaffected either way.
+    const decoder = new StringDecoder("utf8");
+    const consumeText = (text) => {
+        let remaining = text;
+        let newlineIndex = remaining.indexOf("\n");
+        while (newlineIndex !== -1) {
+            flushCompletedLine(remaining.slice(0, newlineIndex));
+            remaining = remaining.slice(newlineIndex + 1);
+            newlineIndex = remaining.indexOf("\n");
+        }
+        if (pendingTruncated)
+            return; // already over buffer; ignore until newline
+        if (pending.length + remaining.length > MAX_LINE_BUFFER_BYTES) {
+            pending = (pending + remaining).slice(0, MAX_LINE_BUFFER_BYTES);
+            pendingTruncated = true;
+        }
+        else {
+            pending += remaining;
+        }
+    };
+    await new Promise((resolve, reject) => {
+        const stream = createReadStream(filePath);
+        stream.on("data", (chunk) => {
+            const buffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+            hash.update(buffer);
+            byteSize += buffer.byteLength;
+            consumeText(decoder.write(buffer));
+        });
+        stream.on("end", () => {
+            const tail = decoder.end();
+            if (tail)
+                consumeText(tail);
+            if (pending.length > 0 || pendingTruncated)
+                flushCompletedLine("");
+            resolve();
+        });
+        stream.on("error", reject);
+    });
+    return {
+        signals: accumulator.finalize(),
+        secretLike,
+        oversizedLinesSkipped,
+        contentHash: hash.digest("hex"),
+        byteSize,
+    };
+}
+function normalizePrRepository(repository) {
+    const trimmed = repository
+        .trim()
+        .replace(/\.git$/i, "")
+        .replace(/^https?:\/\//i, "")
+        .replace(/^github\.com\//i, "")
+        .replace(/^\/+|\/+$/g, "")
+        .toLowerCase();
+    // GitHub-only by construction (D5); a non-GitHub origin simply never matches.
+    return `github.com/${trimmed}`;
+}
+function skippedResult(base, reason) {
+    return {
+        ...base,
+        state: "skipped",
+        reason,
+        signals: [],
+        attribution_score: 0,
+        path_score: 0,
+        worktree: null,
+    };
+}
+function stringOrNull(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function isSecretLikePath(value) {
+    return SECRET_FILE_SEGMENT_PATTERN.test(value);
+}
+function sha256(value) {
+    return crypto.createHash("sha256").update(value).digest("hex");
+}