rulereceipt 0.1.80 → 0.1.81

package/NOTICE.md

@@ -17,3 +17,16 @@ reader working from a single file rather than the whole repository.
 
 Reading, studying, auditing, and using this code for personal or
 internal purposes remains fully permitted — see LICENSE clauses 2-3.
+
+---
+
+## Third-party format references (credits)
+
+RuleReceipt's agent adapters are our own code. Where an on-disk session FORMAT
+was documented by another MIT-licensed project, we credit it (we read the format,
+we did not copy the code):
+
+- **GitHub Copilot CLI** session format (`~/.copilot/session-state/*/events.jsonl`):
+  documented by **yigitkonur/cli-continues** (MIT), pinned commit
+  `e486cd22a592d89d890cff056624647fbe9cbe80`, which itself reverse-engineered it
+  from **Pilan-AI/mnemo** (MIT). Our reader is `src/adapters/copilot.ts`.

package/dist/adapters/copilot.d.ts

@@ -0,0 +1,7 @@
+import type { TranscriptEvent } from "../types.js";
+/** Copilot CLI session files (events.jsonl) for this cwd, newest first. */
+export declare function listCopilotSessions(cwd: string): string[];
+/** True when the file looks like a Copilot CLI log at all (≥1 known event type). */
+export declare function copilotFormatIsKnown(sessionFile: string): boolean;
+/** Parse a Copilot CLI events.jsonl into neutral events. Tolerant: unknown → skipped. */
+export declare function parseCopilotTranscript(sessionFile: string): TranscriptEvent[];

package/dist/adapters/copilot.js

@@ -0,0 +1,192 @@
+import { existsSync, readFileSync, readdirSync, statSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/**
+ * GitHub Copilot CLI adapter — EXPERIMENTAL (no real-session fixtures yet).
+ *
+ * Reader is OUR OWN code. The on-disk FORMAT is documented by
+ * yigitkonur/cli-continues (MIT, src/parsers/copilot.ts, pinned commit
+ * e486cd22a592d89d890cff056624647fbe9cbe80), which reverse-engineered it; we map
+ * that format to our neutral events ourselves. Credit: see NOTICE.md and REUSE.md.
+ *
+ * Layout: ~/.copilot/session-state/<id>/ with `workspace.yaml` (holds `cwd`) and
+ * `events.jsonl`. `COPILOT_HOME` overrides the root. Event `type`s we map:
+ *   user.message            -> text (role user)        data.content / transformedContent
+ *   assistant.message       -> text (role assistant)   data.content; data.toolRequests[] -> tool_use
+ *   tool.execution_start    -> tool_use                data.toolName / toolCallId / arguments
+ *   tool.execution_complete -> tool_result             data.toolCallId / success / result
+ *
+ * RESILIENCE (a format change must make us quieter, never wrong):
+ *  - depend only on the fields above; ignore every unknown field;
+ *  - a line that doesn't parse, or whose type we don't know, is skipped, never guessed;
+ *  - `copilotFormatIsKnown` reports whether the file looked like a Copilot log at
+ *    all, so a caller can say "format newer than tested" instead of fabricating.
+ */
+const KNOWN_TYPES = new Set([
+    "user.message", "assistant.message", "tool.execution_start", "tool.execution_complete",
+    "session.start", "session.shutdown",
+]);
+function copilotRoot() {
+    const env = process.env.COPILOT_HOME?.trim();
+    return env && env.length > 0 ? env : join(homedir(), ".copilot");
+}
+function realpathOr(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
+/** `cwd:` out of a workspace.yaml, read by a line scan (no YAML dependency). */
+function workspaceCwd(dir) {
+    try {
+        for (const line of readFileSync(join(dir, "workspace.yaml"), "utf-8").split("\n")) {
+            const m = line.match(/^\s*cwd\s*:\s*(.+?)\s*$/);
+            if (m)
+                return m[1].replace(/^["']|["']$/g, "");
+        }
+    }
+    catch { /* unreadable */ }
+    return null;
+}
+/** Copilot CLI session files (events.jsonl) for this cwd, newest first. */
+export function listCopilotSessions(cwd) {
+    const base = join(copilotRoot(), "session-state");
+    if (!existsSync(base))
+        return [];
+    const target = realpathOr(cwd);
+    const hits = [];
+    let entries = [];
+    try {
+        entries = readdirSync(base);
+    }
+    catch {
+        return [];
+    }
+    for (const name of entries) {
+        const dir = join(base, name);
+        const events = join(dir, "events.jsonl");
+        if (!existsSync(events))
+            continue;
+        const wc = workspaceCwd(dir);
+        if (wc && realpathOr(wc) !== target)
+            continue; // belongs to another project
+        try {
+            hits.push({ file: events, mtimeMs: statSync(events).mtimeMs });
+        }
+        catch { /* skip */ }
+    }
+    return hits.sort((a, b) => b.mtimeMs - a.mtimeMs).map((h) => h.file);
+}
+function asRecord(v) {
+    return v && typeof v === "object" && !Array.isArray(v) ? v : {};
+}
+function str(v) {
+    return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+/** Map one tool invocation (name + args) to our canonical tool_use input. */
+function toToolUse(name, args, id, ts) {
+    const command = str(args.command) ?? str(args.cmd);
+    const filePath = str(args.path) ?? str(args.file_path) ?? str(args.filePath);
+    const lower = name.toLowerCase();
+    // A shell command → canonical Bash shape, so the command-scanning checks fire
+    // on Copilot exactly as on Claude Code.
+    if (command && (/(shell|bash|terminal|exec|run|command)/.test(lower) || !filePath)) {
+        return { role: "assistant", kind: "tool_use", toolName: "Bash", toolUseId: id, input: { command }, timestamp: ts };
+    }
+    if (filePath && /(write|create|edit|replace|apply|patch|insert|modif)/.test(lower)) {
+        return { role: "assistant", kind: "tool_use", toolName: lower.includes("edit") || lower.includes("replace") || lower.includes("patch") ? "Edit" : "Write", toolUseId: id, input: { file_path: filePath, ...args }, timestamp: ts };
+    }
+    if (filePath && /(read|view|open|cat|show)/.test(lower)) {
+        return { role: "assistant", kind: "tool_use", toolName: "Read", toolUseId: id, input: { file_path: filePath }, timestamp: ts };
+    }
+    return { role: "assistant", kind: "tool_use", toolName: name, toolUseId: id, input: args, timestamp: ts };
+}
+/** True when the file looks like a Copilot CLI log at all (≥1 known event type). */
+export function copilotFormatIsKnown(sessionFile) {
+    let raw;
+    try {
+        raw = readFileSync(sessionFile, "utf-8");
+    }
+    catch {
+        return false;
+    }
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const t = JSON.parse(line).type;
+            if (typeof t === "string" && KNOWN_TYPES.has(t))
+                return true;
+        }
+        catch { /* skip */ }
+    }
+    return false;
+}
+/** Parse a Copilot CLI events.jsonl into neutral events. Tolerant: unknown → skipped. */
+export function parseCopilotTranscript(sessionFile) {
+    let raw;
+    try {
+        raw = readFileSync(sessionFile, "utf-8");
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    const startNames = new Map(); // toolCallId -> toolName
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        let e;
+        try {
+            e = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const ts = str(e.timestamp) ?? "";
+        const d = e.data ?? {};
+        switch (e.type) {
+            case "user.message": {
+                const text = str(d.content) ?? str(d.transformedContent);
+                if (text)
+                    out.push({ role: "user", kind: "text", text, timestamp: ts });
+                break;
+            }
+            case "assistant.message": {
+                const text = typeof d.content === "string" ? d.content : d.content ? JSON.stringify(d.content) : undefined;
+                if (text)
+                    out.push({ role: "assistant", kind: "text", text, timestamp: ts });
+                for (const [i, tr] of (d.toolRequests ?? []).entries()) {
+                    const name = str(tr?.name);
+                    if (!name)
+                        continue;
+                    out.push(toToolUse(name, { ...asRecord(tr?.args), ...asRecord(tr?.arguments) }, `tr:${i}`, ts));
+                }
+                break;
+            }
+            case "tool.execution_start": {
+                const name = str(d.toolName);
+                if (!name)
+                    break;
+                const id = str(d.toolCallId);
+                if (id)
+                    startNames.set(id, name);
+                out.push(toToolUse(name, asRecord(d.arguments), id, ts));
+                break;
+            }
+            case "tool.execution_complete": {
+                const id = str(d.toolCallId);
+                const name = id ? startNames.get(id) : undefined;
+                const r = d.result;
+                const content = typeof r === "string" ? r : str(asRecord(r).content) ?? str(asRecord(r).detailedContent) ?? (r ? JSON.stringify(r).slice(0, 2000) : "");
+                out.push({ role: "user", kind: "tool_result", toolUseId: id, content, isError: d.success === false, timestamp: ts, ...(name ? { toolName: name } : {}) });
+                break;
+            }
+            default:
+                break; // unknown type: ignore, never fabricate
+        }
+    }
+    return out;
+}

package/dist/adapters/index.d.ts

@@ -18,6 +18,12 @@ export interface SessionAdapter {
     listSessions(cwd: string): string[];
     /** Parse one session file into neutral events. */
     parse(sessionFile: string): TranscriptEvent[];
+    /**
+     * EXPERIMENTAL = reader exists but has no real-session + planted + clean
+     * fixtures yet, so it is NOT auto-detected (it would risk an unverified parse
+     * winning "newest session"). It is used only when the user points at a file.
+     */
+    experimental?: boolean;
 }
 /**
  * Claude Code — the original and reference adapter. Delegates to the existing
@@ -28,8 +34,16 @@ export interface SessionAdapter {
 export declare const claudeCodeAdapter: SessionAdapter;
 /** OpenAI Codex CLI — format verified, parsing tolerant. See adapters/codex.ts. */
 export declare const codexAdapter: SessionAdapter;
-/** Every adapter with a verified, tested-buildable parser. */
+/**
+ * GitHub Copilot CLI — EXPERIMENTAL. Reader is ours; the format is per
+ * cli-continues (MIT, pinned SHA — see REUSE.md/NOTICE). No real-session
+ * fixtures yet, so not auto-detected; reachable via `--transcript <events.jsonl>`.
+ */
+export declare const copilotCliAdapter: SessionAdapter;
+/** Adapters with a verified, tested parser — these auto-detect the newest session. */
 export declare const ADAPTERS: SessionAdapter[];
+/** Experimental adapters: reader exists, awaiting real+planted+clean fixtures. */
+export declare const EXPERIMENTAL_ADAPTERS: SessionAdapter[];
 /**
  * Tools deliberately NOT read yet, with the honest reason. Kept as data (not
  * silence) so the tool — and its docs — can state exactly where the line is

package/dist/adapters/index.js

@@ -2,6 +2,7 @@ import { statSync, readFileSync } from "node:fs";
 import { basename } from "node:path";
 import { listAllSessionFiles, readTranscriptFromFile, findSubagentFiles } from "../parsers/transcriptParser.js";
 import { listCodexSessions, parseCodexTranscript } from "./codex.js";
+import { listCopilotSessions, parseCopilotTranscript, copilotFormatIsKnown } from "./copilot.js";
 /**
  * Claude Code — the original and reference adapter. Delegates to the existing
  * transcriptParser so its behaviour (including subagent transcripts) is
@@ -24,8 +25,21 @@ export const codexAdapter = {
     listSessions: (cwd) => listCodexSessions(cwd),
     parse: (sessionFile) => parseCodexTranscript(sessionFile),
 };
-/** Every adapter with a verified, tested-buildable parser. */
+/**
+ * GitHub Copilot CLI — EXPERIMENTAL. Reader is ours; the format is per
+ * cli-continues (MIT, pinned SHA — see REUSE.md/NOTICE). No real-session
+ * fixtures yet, so not auto-detected; reachable via `--transcript <events.jsonl>`.
+ */
+export const copilotCliAdapter = {
+    tool: "copilot-cli",
+    listSessions: (cwd) => listCopilotSessions(cwd),
+    parse: (sessionFile) => parseCopilotTranscript(sessionFile),
+    experimental: true,
+};
+/** Adapters with a verified, tested parser — these auto-detect the newest session. */
 export const ADAPTERS = [claudeCodeAdapter, codexAdapter];
+/** Experimental adapters: reader exists, awaiting real+planted+clean fixtures. */
+export const EXPERIMENTAL_ADAPTERS = [copilotCliAdapter];
 /**
  * Tools deliberately NOT read yet, with the honest reason. Kept as data (not
  * silence) so the tool — and its docs — can state exactly where the line is
@@ -36,7 +50,6 @@ export const UNSUPPORTED_TOOLS = [
     { tool: "aider", reason: "history is a Markdown transcript (.aider.chat.history.md), not structured events — needs a prose parser, not a field mapping" },
     { tool: "opencode", reason: "stores sessions in a SQLite DB (opencode.db) since v1.2.0 (per-record JSON before) — needs a SQLite reader, version-dependent" },
     { tool: "cursor", reason: "IDE-embedded; chat history lives in undocumented internal state that changes across Cursor versions — real ongoing maintenance, out of scope for this pass" },
-    { tool: "github-copilot", reason: "IDE-embedded; no accessible, stable local session log a third-party CLI can read" },
     { tool: "windsurf", reason: "IDE-embedded; history in undocumented internal state, same as Cursor" },
 ];
 /**
@@ -113,6 +126,13 @@ export function parseSessionFile(file) {
         if (obj && typeof obj === "object" && (obj.type === "session_meta" || obj.type === "response_item")) {
             return parseCodexTranscript(file);
         }
+        // Copilot CLI events.jsonl opens with a dotted event type (session.start,
+        // user.message, …). EXPERIMENTAL adapter; confirm it really is a Copilot log
+        // (a known event type somewhere) before using its reader, never on the
+        // dotted-type guess alone.
+        if (obj && typeof obj === "object" && typeof obj.type === "string" && obj.type.includes(".") && copilotFormatIsKnown(file)) {
+            return parseCopilotTranscript(file);
+        }
     }
     catch {
         /* first line is not JSON: treat as a Claude transcript below */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rulereceipt",
-  "version": "0.1.80",
+  "version": "0.1.81",
   "description": "Checks whether your AI coding agent followed your rules, with evidence. Works with Claude Code (Codex in testing); reads CLAUDE.md, AGENTS.md, Cursor, Copilot and Windsurf rules.",
   "repository": {
     "type": "git",