agent-trace-cli 0.1.0__py3-none-any.whl

agent_trace/rewrite.py

@@ -0,0 +1,176 @@
+"""
+Post-rewrite ledger remapping — updates ledger commit SHAs after rebase/amend.
+
+Git's ``post-rewrite`` hook provides ``old_sha new_sha`` lines on stdin.
+For each pair we:
+
+  1. Remap the ledger row's ``commit_sha`` (and ``parent_sha`` if it was
+     itself rewritten).
+  2. Compare ``diff_signature(old)`` against ``diff_signature(new)``. If
+     they differ — i.e., the rewrite changed the tree (amend with edits,
+     rebase with conflict resolution, ``rebase --exec`` that mutates
+     content) — drop the remapped row and rebuild the ledger from the new
+     commit. The line numbers and hashes in the old ledger are stale; the
+     deterministic answer for the new commit comes from re-running the
+     builder against its actual diff.
+  3. Move the corresponding ``refs/notes/agent-trace`` note onto the new
+     SHA (removing the orphaned old one). Without this step notes silently
+     orphan on unreachable commits after rebase / amend.
+
+No external dependencies — stdlib only.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+
+def _git_silent(*args: str, cwd: str | None = None) -> int:
+    """Run a git command, return its exit code; suppress output."""
+    try:
+        r = subprocess.run(
+            ["git", *args],
+            capture_output=True, text=True, cwd=cwd, timeout=30,
+        )
+        return r.returncode
+    except Exception:
+        return 1
+
+
+def _remove_note(commit_sha: str, repo_dir: str) -> None:
+    """Best-effort removal of an agent-trace note on ``commit_sha``.
+    Silent if the note doesn't exist."""
+    if not commit_sha:
+        return
+    _git_silent(
+        "notes", "--ref", "agent-trace", "remove", "--ignore-missing", commit_sha,
+        cwd=repo_dir,
+    )
+
+
+def rewrite_ledgers(project_dir: str | None = None) -> int:
+    """After rebase/amend, remap (or rebuild) ledgers and move notes.
+
+    Reads old→new SHA mapping from stdin (git provides this in post-rewrite).
+    Returns count of ledger rows touched (remapped + rebuilt + dropped).
+    """
+    if project_dir is None:
+        import os
+        project_dir = os.getcwd()
+
+    sha_map: dict[str, str] = {}
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        parts = line.split()
+        if len(parts) >= 2:
+            sha_map[parts[0]] = parts[1]
+
+    if not sha_map:
+        return 0
+
+    from .ledger import build_attribution_ledger, diff_signature
+    from .storage import get_ledgers_path, resolve_project_id
+
+    pid = resolve_project_id(project_dir, create=False)
+    if not pid:
+        return 0
+    ledgers_path = get_ledgers_path(pid)
+    if not ledgers_path.exists():
+        return 0
+
+    ledgers: list[dict] = []
+    try:
+        for line in ledgers_path.read_text().splitlines():
+            line = line.strip()
+            if line:
+                try:
+                    ledgers.append(json.loads(line))
+                except json.JSONDecodeError:
+                    continue
+    except OSError:
+        return 0
+
+    # First pass: SHA remap (commit_sha + parent_sha) and bookkeep which
+    # rows moved so we can later decide rebuild-vs-keep.
+    touched = 0
+    moved: list[tuple[str, str, dict]] = []  # (old_sha, new_sha, ledger)
+    for ledger in ledgers:
+        old_sha = ledger.get("commit_sha", "")
+        if old_sha in sha_map:
+            new_sha = sha_map[old_sha]
+            ledger["commit_sha"] = new_sha
+            touched += 1
+            moved.append((old_sha, new_sha, ledger))
+        old_parent = ledger.get("parent_sha", "")
+        if old_parent and old_parent in sha_map:
+            ledger["parent_sha"] = sha_map[old_parent]
+
+    if touched == 0:
+        return 0
+
+    # Second pass: rebuild rows whose tree-diff changed.
+    # `ledgers` may be mutated in-place (rebuild) or have entries removed
+    # (rebuild returned None — the rewrite removed all AI lines).
+    rebuilt_old_shas: set[str] = set()
+    rebuild_failures: set[str] = set()
+    rebuilt_replacements: dict[str, dict | None] = {}  # new_sha -> rebuilt ledger or None
+    for old_sha, new_sha, _ in moved:
+        old_sig = diff_signature(old_sha, project_dir)
+        new_sig = diff_signature(new_sha, project_dir)
+        if old_sig is None or new_sig is None or old_sig == new_sig:
+            continue
+        # Tree changed — rebuild deterministically against the new commit.
+        try:
+            new_ledger = build_attribution_ledger(project_dir, commit_ref=new_sha)
+        except Exception:
+            rebuild_failures.add(old_sha)
+            continue
+        rebuilt_old_shas.add(old_sha)
+        rebuilt_replacements[new_sha] = new_ledger
+
+    # Rewrite the in-memory list with rebuilt entries swapped in (or dropped
+    # when the rebuild produced None).
+    if rebuilt_replacements:
+        new_list: list[dict] = []
+        for ledger in ledgers:
+            sha = ledger.get("commit_sha", "")
+            if sha in rebuilt_replacements:
+                rep = rebuilt_replacements.pop(sha)
+                if rep is not None:
+                    new_list.append(rep)
+                # If rep is None, the rewrite removed all AI lines; drop the row.
+            else:
+                new_list.append(ledger)
+        ledgers = new_list
+
+    try:
+        with open(ledgers_path, "w") as f:
+            for ledger in ledgers:
+                f.write(json.dumps(ledger) + "\n")
+    except OSError:
+        return 0
+
+    # Third pass: notes. Always drop the old note. Attach a fresh note for
+    # rebuilt ledgers; for purely-remapped ones, attach using the (already
+    # remapped) ledger. If the rebuild dropped the row, no note is attached.
+    try:
+        from .git_notes import attach_note_after_ledger
+
+        # Build a quick lookup of current rows by commit_sha (post-rebuild).
+        by_sha = {l.get("commit_sha", ""): l for l in ledgers}
+
+        for old_sha, new_sha, _ in moved:
+            _remove_note(old_sha, project_dir)
+            ledger = by_sha.get(new_sha)
+            if ledger is not None:
+                attach_note_after_ledger(project_dir, ledger)
+    except Exception:
+        # Don't let note bookkeeping fail the post-rewrite hook.
+        pass
+
+    return touched

agent_trace/rules.py

@@ -0,0 +1,209 @@
+"""
+Rule management for coding agents.
+
+Prebuilt rules teach coding agents (Cursor, Claude Code, Codex, ...)
+how to use agent-trace features. Each rule is identified by a short
+name and can be added/removed independently per tool.
+
+The list of supported tools is the adapter registry (``hooks``). To
+support a rule for a new agent, add the rule body under the agent's
+``name`` key in ``AVAILABLE_RULES`` — the adapter itself decides where
+the file lives (``rules_dir`` + ``rule_extension``).
+
+No external dependencies — stdlib only.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any
+
+from .hooks import get_adapter, iter_adapters
+
+
+def _supported_tools() -> tuple[str, ...]:
+    """Tools that declare a ``rules_dir`` are eligible for rules."""
+    return tuple(a.name for a in iter_adapters() if a.supports_rules())
+
+
+# Exported for argparse ``choices=`` and other callers. Computed lazily
+# so registering a new adapter is reflected without restarting Python.
+class _ToolChoices:
+    def __iter__(self):
+        return iter(_supported_tools())
+
+    def __contains__(self, item):
+        return item in _supported_tools()
+
+    def __getitem__(self, idx):
+        return _supported_tools()[idx]
+
+    def __len__(self):
+        return len(_supported_tools())
+
+    def __repr__(self):
+        return f"TOOL_CHOICES({_supported_tools()!r})"
+
+
+TOOL_CHOICES = _ToolChoices()
+
+
+# ===================================================================
+# Rule paths (delegated to the adapter)
+# ===================================================================
+
+def _rule_path(rule_name: str, tool: str, project_dir: str | None = None) -> Path:
+    adapter = get_adapter(tool)
+    if adapter is None or not adapter.supports_rules():
+        raise ValueError(f"Unknown tool or tool does not support rules: {tool}")
+    return adapter.rule_path(rule_name, project_dir)
+
+
+# ===================================================================
+# Rule content: context-for-agents
+# ===================================================================
+
+_CONTEXT_FOR_AGENTS_DESCRIPTION = (
+    "Teaches the agent to retrieve conversation context behind "
+    "AI-attributed code using `agent-trace context`"
+)
+
+_CONTEXT_FOR_AGENTS_BODY = """\
+# agent-trace: AI conversation context for code
+
+This project uses agent-trace to embed conversation context into code. When you read a file that contains AI-generated code, you can retrieve the conversation that produced it.
+
+## Step 1: Get attribution metadata (always do this first)
+
+```
+agent-trace context <file> --lines START-END --json
+```
+
+This returns attribution segments with metadata for each line range: whether it was AI or human authored, which model/tool wrote it, and crucially the `conversation_size` (character count, line count, turn count) and a short `preview` of the conversation.
+
+If there are no AI-attributed segments, or the preview gives you enough context, stop here.
+
+## Step 2: Decide how to load the full conversation
+
+Look at `conversation_size` for each AI-attributed segment:
+
+- **Small transcript (< 3000 characters):** Load it directly in your context. Run:
+  ```
+  agent-trace context <file> --lines START-END --full --json
+  ```
+  Read the `conversation_content` field directly.
+
+- **Large transcript (>= 3000 characters):** Do NOT load it into your main context window — it will pollute your working context. Instead, delegate to a subagent:
+  - Spawn a subagent (e.g. using the Task tool, a background agent, or whatever mechanism your host provides).
+  - The subagent should run:
+    ```
+    agent-trace context <file> --lines START-END --full --json
+    ```
+  - Instruct the subagent to read the full `conversation_content` and return a focused summary. Tell the subagent what you need to know — e.g. "summarize the rationale for this implementation", "what constraints were discussed", "why was this approach chosen over alternatives".
+  - Use the subagent's returned summary in your reasoning.
+
+## When to use this
+
+- When you're about to modify AI-generated code and want to understand the original intent
+- When you encounter code whose purpose or design isn't clear from the code itself
+- When the user asks about why code was written a certain way
+- You do NOT need to fetch context for every file you read — use judgment
+"""
+
+_CONTEXT_FOR_AGENTS_CURSOR = """\
+---
+description: agent-trace context retrieval for AI-attributed code
+alwaysApply: true
+---
+
+""" + _CONTEXT_FOR_AGENTS_BODY
+
+_CONTEXT_FOR_AGENTS_CLAUDE = _CONTEXT_FOR_AGENTS_BODY
+_CONTEXT_FOR_AGENTS_CODEX = _CONTEXT_FOR_AGENTS_BODY
+
+
+# ===================================================================
+# Rule registry
+# ===================================================================
+#
+# Each rule maps a tool ``name`` (matching an adapter) to the rule body
+# for that tool. Tools that aren't keyed simply skip the rule.
+
+AVAILABLE_RULES: dict[str, dict[str, Any]] = {
+    "context-for-agents": {
+        "description": _CONTEXT_FOR_AGENTS_DESCRIPTION,
+        "cursor": _CONTEXT_FOR_AGENTS_CURSOR,
+        "claude": _CONTEXT_FOR_AGENTS_CLAUDE,
+        "codex": _CONTEXT_FOR_AGENTS_CODEX,
+    },
+}
+
+
+# ===================================================================
+# Rule operations
+# ===================================================================
+
+def add_rule(rule_name: str, tool: str, project_dir: str | None = None) -> str:
+    """Write a rule file for the given tool. Returns the path written."""
+    if rule_name not in AVAILABLE_RULES:
+        print(f"Unknown rule: {rule_name}", file=sys.stderr)
+        print(f"Available rules: {', '.join(AVAILABLE_RULES.keys())}", file=sys.stderr)
+        sys.exit(1)
+
+    if tool not in _supported_tools():
+        print(f"Unknown tool: {tool}", file=sys.stderr)
+        print(f"Available tools: {', '.join(_supported_tools())}", file=sys.stderr)
+        sys.exit(1)
+
+    rule_def = AVAILABLE_RULES[rule_name]
+    if tool not in rule_def:
+        print(f"Rule '{rule_name}' is not defined for tool '{tool}'.", file=sys.stderr)
+        sys.exit(1)
+    content = rule_def[tool]
+    path = _rule_path(rule_name, tool, project_dir)
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content)
+    return str(path)
+
+
+def remove_rule(rule_name: str, tool: str, project_dir: str | None = None) -> str | None:
+    """Remove a rule file. Returns the path removed, or None if not found."""
+    if tool not in _supported_tools():
+        print(f"Unknown tool: {tool}", file=sys.stderr)
+        print(f"Available tools: {', '.join(_supported_tools())}", file=sys.stderr)
+        sys.exit(1)
+
+    path = _rule_path(rule_name, tool, project_dir)
+    if path.exists():
+        path.unlink()
+        return str(path)
+    return None
+
+
+def show_rules(project_dir: str | None = None) -> list[dict[str, str]]:
+    """Scan for active agent-trace rules. Returns list of {name, tool, path}."""
+    active: list[dict[str, str]] = []
+
+    for rule_name, rule_def in AVAILABLE_RULES.items():
+        for tool in _supported_tools():
+            if tool not in rule_def:
+                continue
+            path = _rule_path(rule_name, tool, project_dir)
+            if path.exists():
+                active.append({
+                    "name": rule_name,
+                    "tool": tool,
+                    "path": str(path),
+                })
+
+    return active
+
+
+def list_available_rules() -> list[dict[str, str]]:
+    """List all available prebuilt rules with descriptions."""
+    return [
+        {"name": name, "description": rule_def["description"]}
+        for name, rule_def in AVAILABLE_RULES.items()
+    ]

agent_trace/schemas/commit-link.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/ujjalsharma100/agent-trace-cli/main/schemas/commit-link.schema.json",
+  "title": "CommitLink",
+  "description": "One line in commit-links.jsonl. Optional ledger duplicates the ledger record when stored via remote POST.",
+  "type": "object",
+  "required": [
+    "commit_sha",
+    "parent_sha",
+    "trace_ids",
+    "files_changed",
+    "committed_at",
+    "created_at"
+  ],
+  "additionalProperties": true,
+  "properties": {
+    "commit_sha": { "type": "string", "minLength": 1 },
+    "parent_sha": { "type": ["string", "null"] },
+    "trace_ids": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "files_changed": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "committed_at": { "type": ["string", "null"] },
+    "created_at": { "type": "string" },
+    "ledger": {
+      "description": "Full ledger object when included (e.g. remote sync)",
+      "type": "object"
+    }
+  }
+}

agent_trace/schemas/git-note.schema.json

@@ -0,0 +1,88 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/ujjalsharma100/agent-trace-cli/main/schemas/git-note.schema.json",
+  "title": "GitNotePayload",
+  "description": "JSON blob under refs/notes/agent-trace. Schema 2.0: stats only count AI lines (anything else is implicitly NO_ATTRIBUTION).",
+  "type": "object",
+  "required": ["version", "trace_ids", "ledger_hash", "stats"],
+  "additionalProperties": false,
+  "properties": {
+    "version": {
+      "type": "string",
+      "const": "2.0"
+    },
+    "trace_ids": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "ledger_hash": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]+$"
+    },
+    "stats": {
+      "type": "object",
+      "required": ["ai_lines"],
+      "additionalProperties": false,
+      "properties": {
+        "ai_lines": { "type": "integer", "minimum": 0 },
+        "total_changed_lines": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "ledger": {
+      "type": "object",
+      "description": "Inline per-line attribution (optional, AI segments only)",
+      "required": ["files"],
+      "additionalProperties": false,
+      "properties": {
+        "files": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "required": ["line_attributions"],
+            "additionalProperties": false,
+            "properties": {
+              "line_attributions": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "required": ["start_line", "end_line", "type", "trace_id"],
+                  "additionalProperties": true,
+                  "properties": {
+                    "start_line": { "type": "integer", "minimum": 1 },
+                    "end_line": { "type": "integer", "minimum": 1 },
+                    "type": { "type": "string", "const": "ai" },
+                    "trace_id": { "type": "string" },
+                    "model_id": { "type": "string" },
+                    "conversation_id": { "type": "string" }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "description": "Map of conversation_id (sha256 over the original local transcript URL) to summary prose (optional)",
+      "additionalProperties": { "type": "string" }
+    },
+    "prompts": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "all_session_conversations": {
+      "type": "array",
+      "description": "Every conversation_id from traces in the commit staging window (not only those attributed in the commit), with optional stored summary per id",
+      "items": {
+        "type": "object",
+        "required": ["conversation_id", "summary"],
+        "additionalProperties": false,
+        "properties": {
+          "conversation_id": { "type": "string" },
+          "summary": { "type": ["string", "null"] }
+        }
+      }
+    }
+  }
+}

agent_trace/schemas/ledger.schema.json

@@ -0,0 +1,97 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/ujjalsharma100/agent-trace-cli/main/schemas/ledger.schema.json",
+  "title": "AttributionLedger",
+  "description": "One line in ledgers.jsonl. Schema 2.0: only AI segments are recorded. Anything not recorded is implicitly NO_ATTRIBUTION. Each AI segment carries per-line evidence (hash + content) for audit.",
+  "type": "object",
+  "required": [
+    "version",
+    "commit_sha",
+    "parent_sha",
+    "committed_at",
+    "created_at",
+    "trace_ids",
+    "files"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "version": {
+      "type": "string",
+      "enum": ["2.0"]
+    },
+    "commit_sha": { "type": "string", "minLength": 1 },
+    "parent_sha": { "type": ["string", "null"] },
+    "parent_committed_at": { "type": ["string", "null"] },
+    "committed_at": { "type": ["string", "null"] },
+    "created_at": { "type": "string" },
+    "trace_ids": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "files": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/fileAttribution" }
+    },
+    "derived_from": {
+      "description": "Set when the commit was produced by cherry-pick / revert / merge — used to explain why fallback attribution kicked in.",
+      "type": "object",
+      "required": ["kind"],
+      "additionalProperties": false,
+      "properties": {
+        "kind": { "type": "string", "enum": ["cherry-pick", "revert", "merge"] },
+        "source_sha": { "type": "string" },
+        "parents": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "used_fallback": {
+      "description": "True when one or more lines were attributed via the global hash-index fallback rather than the staging-window pool.",
+      "type": "boolean"
+    }
+  },
+  "$defs": {
+    "lineEvidence": {
+      "type": "object",
+      "required": ["line", "hash", "content"],
+      "additionalProperties": false,
+      "properties": {
+        "line": { "type": "integer", "minimum": 1 },
+        "hash": { "type": "string" },
+        "content": { "type": "string" }
+      }
+    },
+    "lineSegment": {
+      "type": "object",
+      "required": ["start_line", "end_line", "type", "trace_id"],
+      "additionalProperties": false,
+      "properties": {
+        "start_line": { "type": "integer", "minimum": 1 },
+        "end_line": { "type": "integer", "minimum": 1 },
+        "type": {
+          "type": "string",
+          "const": "ai"
+        },
+        "trace_id": { "type": "string", "minLength": 1 },
+        "model_id": { "type": ["string", "null"] },
+        "conversation_id": {
+          "type": ["string", "null"],
+          "description": "Opaque conversation identifier (sha256 over the original local transcript URL); same id used in trace records."
+        },
+        "evidence": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/lineEvidence" }
+        }
+      }
+    },
+    "fileAttribution": {
+      "type": "object",
+      "required": ["line_attributions"],
+      "additionalProperties": false,
+      "properties": {
+        "line_attributions": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/lineSegment" }
+        }
+      }
+    }
+  }
+}

agent_trace/schemas/remotes.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/ujjalsharma100/agent-trace-cli/main/schemas/remotes.schema.json",
+  "title": "RemotesConfig",
+  "description": "Named remotes for ~/.agent-trace/projects/<project_id>/remotes.json — git-remote-like URLs and auth references.",
+  "type": "object",
+  "additionalProperties": { "$ref": "#/$defs/remote" },
+  "$defs": {
+    "remote": {
+      "type": "object",
+      "required": ["url"],
+      "additionalProperties": false,
+      "properties": {
+        "url": {
+          "type": "string",
+          "minLength": 1
+        },
+        "auth": {
+          "type": "object",
+          "required": ["type", "token_ref"],
+          "additionalProperties": false,
+          "properties": {
+            "type": { "type": "string" },
+            "token_ref": { "type": "string" }
+          }
+        }
+      }
+    }
+  }
+}

agent_trace/schemas/sync-state.schema.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/ujjalsharma100/agent-trace-cli/main/schemas/sync-state.schema.json",
+  "title": "SyncState",
+  "description": "Per-remote manifest of synced item IDs (~/.agent-trace/projects/<id>/sync-state.json). The manifest is the source of truth for what's on the server; cursors are paging hints only.",
+  "type": "object",
+  "required": ["remotes"],
+  "additionalProperties": false,
+  "properties": {
+    "version": { "type": "integer" },
+    "remotes": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/remoteSync" }
+    }
+  },
+  "$defs": {
+    "syncedManifest": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "trace_ids":         { "type": "array", "items": { "type": "string" } },
+        "ledger_shas":       { "type": "array", "items": { "type": "string" } },
+        "commit_link_shas":  { "type": "array", "items": { "type": "string" } },
+        "blob_shas":         { "type": "array", "items": { "type": "string" } },
+        "conversation_ids":  { "type": "array", "items": { "type": "string" } },
+        "summary_keys":      { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "pullCursors": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "traces":        { "type": ["string", "null"] },
+        "ledgers":       { "type": ["string", "null"] },
+        "commit_links":  { "type": ["string", "null"] },
+        "conversations": { "type": ["string", "null"] },
+        "summaries":     { "type": ["string", "null"] }
+      }
+    },
+    "remoteSync": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "synced": { "$ref": "#/$defs/syncedManifest" },
+        "cursor": { "$ref": "#/$defs/pullCursors" }
+      }
+    }
+  }
+}