backstory-cli 0.1.0__py3-none-any.whl

backstory/__init__.py

@@ -0,0 +1,2 @@
+"""backstory - AI commit memory layer."""
+

backstory/__main__.py

@@ -0,0 +1,6 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+

backstory/attach.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from backstory.dump import clear_pending_session, load_pending_session
+from backstory.okf import parse_session_markdown, render_session_markdown, session_id_to_filename
+from backstory.storage import build_storage_paths, ensure_storage_layout
+
+
+def attach_pending_to_commit(repo_root: Path, commit_hash: str) -> dict[str, Any] | None:
+    """Attach the latest pending AI session to a Git commit.
+
+    Steps:
+        1. Load the pending session.
+        2. Update it with the commit hash.
+        3. Write a summary file.
+        4. Save commit-to-session mapping via Git notes.
+        5. Clear the pending session.
+
+    Returns the updated session dict, or ``None`` if no pending session exists.
+    """
+    session = load_pending_session(repo_root)
+    if session is None:
+        return None
+
+    # --- Link session to commit ---
+    commit_msg = _get_commit_message(repo_root, commit_hash)
+    session["commit"] = {
+        "hash": commit_hash,
+        "message": commit_msg or "",
+    }
+
+    paths = ensure_storage_layout(repo_root)
+    stable_path = paths.sessions / session_id_to_filename(session["session_id"])
+    stable_path.write_text(render_session_markdown(session), encoding="utf-8")
+
+    # --- Write a Git note ---
+    _write_git_note(repo_root, commit_hash, session)
+
+    # --- Clear pending ---
+    clear_pending_session(repo_root)
+
+    return session
+
+
+def _get_commit_message(repo_root: Path, commit_hash: str) -> str | None:
+    """Get the subject line of a commit."""
+    try:
+        result = subprocess.run(
+            ["git", "log", "-1", "--format=%s", commit_hash],
+            cwd=repo_root,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if result.returncode == 0:
+            return result.stdout.strip() or None
+        return None
+    except OSError:
+        return None
+
+
+def _write_git_note(repo_root: Path, commit_hash: str, session: dict) -> None:
+    """Attach a Git note with session metadata to the commit."""
+    import json
+
+    note = json.dumps(
+        {
+            "ai_session": session.get("session_id"),
+            "agent": session.get("agent", {}).get("name"),
+            "created_at": session.get("created_at"),
+        },
+        indent=2,
+    )
+    try:
+        subprocess.run(
+            ["git", "notes", "add", "-f", "-m", note, commit_hash],
+            cwd=repo_root,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except OSError:
+        pass  # Git notes are best-effort
+
+
+def _render_summary(session: dict, commit_hash: str, commit_msg: str | None) -> str:
+    """Render a human-readable summary markdown file."""
+    rendered = render_session_markdown(session)
+    parsed = parse_session_markdown(rendered)
+    lines: list[str] = []
+    lines.append(f"# backstory for Commit {commit_hash}")
+    lines.append("")
+    if commit_msg:
+        lines.append(f"**{commit_msg}**")
+        lines.append("")
+    lines.append("## Task")
+    lines.append("")
+    lines.append(parsed.task_title)
+    lines.append("")
+    if parsed.why:
+        lines.append("## Why")
+        lines.append("")
+        lines.append(parsed.why)
+        lines.append("")
+    if parsed.files_changed:
+        lines.append("## Files Changed")
+        lines.append("")
+        for f in parsed.files_changed:
+            lines.append(f"- `{f}`")
+        lines.append("")
+    if parsed.decisions:
+        lines.append("## Key Decisions")
+        lines.append("")
+        for d in parsed.decisions:
+            lines.append(f"- {d}")
+        lines.append("")
+    if parsed.risks:
+        lines.append("## Risks")
+        lines.append("")
+        for r in parsed.risks:
+            lines.append(f"- {r}")
+        lines.append("")
+    lines.append(f"Agent: {parsed.agent_name}")
+    if parsed.agent_model:
+        lines.append(f"Model: {parsed.agent_model}")
+    lines.append("")
+    lines.append(f"Session ID: {parsed.session_id or session.get('session_id', 'unknown')}")
+    return "\n".join(lines)

backstory/cli.py

@@ -0,0 +1,381 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from backstory.attach import attach_pending_to_commit
+from backstory.contradiction import detect_potential_contradictions
+from backstory.dump import capture_session, save_pending_session
+from backstory.dump import discover_transcript_path
+from backstory.init import initialize_repo, print_init_summary
+from backstory.retrieval import (
+    commit_for_line,
+    commits_for_file,
+    commits_for_range,
+    files_in_diff,
+    format_retrieval_result,
+    resolve_repo_root,
+)
+from backstory.summarize import summarize_transcript
+from backstory.transcript import (
+    ExtractedDecisions,
+    detect_agent_name,
+    detect_model,
+    format_decisions,
+    import_transcript,
+    normalize_messages,
+)
+
+COMMANDS = [
+    "init",
+    "dump",
+    "attach",
+    "why",
+    "show",
+    "search",
+    "context",
+    "status",
+    "redact",
+    "repair",
+]
+
+RETRIEVAL_COMMANDS = [
+    "file",
+    "line",
+    "range",
+    "diff",
+    "code",
+]
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="backstory")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # --- init ---
+    init_p = subparsers.add_parser("init", help="Initialize backstory in this repo")
+    init_p.add_argument("--no-hooks", action="store_true", help="Skip Git hook installation")
+    init_p.add_argument("--force", action="store_true", help="Overwrite existing config and hooks")
+
+    # --- dump ---
+    dump_p = subparsers.add_parser("dump", help="Capture an AI session")
+    dump_p.add_argument("--agent", default=None, help="Agent name (claude, codex)")
+    dump_p.add_argument("--transcript", type=Path, default=None, help="Path to transcript JSON file")
+    dump_p.add_argument("--task", default=None, help="Short task description")
+    dump_p.add_argument("--hook", default=None, help=argparse.SUPPRESS)  # internal: called from hook
+
+    # --- attach ---
+    attach_p = subparsers.add_parser("attach", help="Attach pending session to a commit")
+    attach_p.add_argument("commit_spec", nargs="?", default="HEAD", help="Commit hash or reference")
+    attach_p.add_argument("--hook", default=None, help=argparse.SUPPRESS)  # internal
+
+    # --- basic commands (no extra args yet) ---
+    for name in ("why", "show", "search", "context", "status", "redact", "repair"):
+        subparsers.add_parser(name)
+
+    # --- retrieval commands ---
+    file_p = subparsers.add_parser("file", help="Show commits affecting a file")
+    file_p.add_argument("path", help="File path to query")
+
+    line_p = subparsers.add_parser("line", help="Show what changed a specific line")
+    line_p.add_argument("spec", help="path/to/file.py:42")
+
+    range_p = subparsers.add_parser("range", help="Show commits affecting a line range")
+    range_p.add_argument("spec", help="path/to/file.py:10-20")
+
+    code_p = subparsers.add_parser("code", help="Alias for range")
+    code_p.add_argument("spec", help="path/to/file.py:10-20")
+
+    subparsers.add_parser("diff", help="Show prior context for uncommitted changes")
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    return _dispatch(args)
+
+
+def _dispatch(args: argparse.Namespace) -> int:
+    handler = _get_handler(args.command)
+    if handler is None:
+        print(f"Unknown command: {args.command}", file=sys.stderr)
+        return 1
+    return handler(args)
+
+
+def _get_handler(command: str):
+    return {
+        "init": _handle_init,
+        "dump": _handle_dump,
+        "attach": _handle_attach,
+        "file": _handle_file,
+        "line": _handle_line,
+        "range": _handle_range,
+        "code": _handle_range,
+        "diff": _handle_diff,
+    }.get(command)
+
+
+def _resolve_repo() -> Path | None:
+    return resolve_repo_root(Path.cwd())
+
+
+# ---------------------------------------------------------------------------
+# init handler
+# ---------------------------------------------------------------------------
+
+
+def _handle_init(args: argparse.Namespace) -> int:
+    repo = _resolve_repo()
+    if repo is None:
+        print("Not in a Git repository.", file=sys.stderr)
+        print("Run this command inside a Git repository.", file=sys.stderr)
+        return 1
+
+    result = initialize_repo(
+        repo_root=repo,
+        install_git_hooks=not args.no_hooks,
+        force=args.force,
+    )
+    print_init_summary(repo, result)
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# dump handler
+# ---------------------------------------------------------------------------
+
+
+def _handle_dump(args: argparse.Namespace) -> int:
+    repo = _resolve_repo()
+    if repo is None:
+        print("Not in a Git repository.", file=sys.stderr)
+        return 1
+
+    # Resolve agent name
+    agent_name = args.agent or "manual"
+    model: str | None = None
+    decisions = None
+
+    transcript_path = args.transcript
+    if transcript_path is None:
+        transcript_path = discover_transcript_path(repo)
+        if transcript_path is not None:
+            print(f"Auto-detected transcript: {transcript_path}", file=sys.stderr)
+
+    if transcript_path:
+        # Step 1: Read the raw transcript file
+        raw = import_transcript(transcript_path)
+        if raw is None:
+            print(f"Warning: could not read transcript from {transcript_path}", file=sys.stderr)
+        else:
+            # Step 2: Detect agent metadata from the transcript envelope
+            agent_name = detect_agent_name(raw) or agent_name
+            model = detect_model(raw)
+
+            # Step 3: Normalize to message list
+            messages = normalize_messages(raw)
+
+            if messages:
+                # Step 4: Ask the agent to summarize its own transcript
+                print(f"Asking {agent_name} to summarize transcript...", file=sys.stderr)
+                decisions = summarize_transcript(
+                    messages=messages,
+                    agent_name=agent_name,
+                    model=model,
+                )
+
+                if decisions:
+                    print(format_decisions(decisions))
+                    print()
+                else:
+                    print(
+                        "  (agent summarization unavailable — "
+                        "install claude CLI for automatic extraction)",
+                        file=sys.stderr,
+                    )
+                    # Still capture the session with basic info
+                    decisions = ExtractedDecisions(
+                        agent_name=agent_name,
+                        model=model,
+                        task=args.task or "",
+                        decisions=[],
+                    )
+            else:
+                print("Warning: no messages found in transcript", file=sys.stderr)
+
+    # Override agent name from --agent flag if explicitly provided
+    if args.agent:
+        agent_name = args.agent
+
+    # Capture session (NO raw conversation stored — only extracted decisions)
+    session = capture_session(
+        repo_root=repo,
+        task=args.task,
+        agent=agent_name,
+        decisions=decisions,
+    )
+
+    path = save_pending_session(repo, session)
+    print(f"Session saved: {session['session_id']}")
+    print(f"Pending:       {path}")
+
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# attach handler
+# ---------------------------------------------------------------------------
+
+
+def _handle_attach(args: argparse.Namespace) -> int:
+    repo = _resolve_repo()
+    if repo is None:
+        print("Not in a Git repository.", file=sys.stderr)
+        return 1
+
+    result = attach_pending_to_commit(repo, args.commit_spec)
+    if result is None:
+        if not args.hook:
+            print("No pending session to attach.")
+        return 0
+
+    print(f"Attached session {result['session_id']} to commit {args.commit_spec}")
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# file handler
+# ---------------------------------------------------------------------------
+
+
+def _handle_file(args: argparse.Namespace) -> int:
+    repo = _resolve_repo()
+    if repo is None:
+        print("Not in a Git repository.", file=sys.stderr)
+        return 1
+
+    commits = commits_for_file(repo, args.path)
+    output = format_retrieval_result(
+        file_path=args.path,
+        line_range=None,
+        commits=commits,
+    )
+    print(output)
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# Parse helpers for line/range specs
+# ---------------------------------------------------------------------------
+
+
+def _parse_line_spec(spec: str) -> tuple[str, int] | None:
+    """Parse 'path/to/file.py:42' into (path, 42)."""
+    if ":" not in spec:
+        return None
+    parts = spec.rsplit(":", 1)
+    try:
+        return parts[0], int(parts[1])
+    except (ValueError, IndexError):
+        return None
+
+
+def _parse_range_spec(spec: str) -> tuple[str, int, int] | None:
+    """Parse 'path/to/file.py:10-20' into (path, 10, 20)."""
+    if ":" not in spec or "-" not in spec:
+        return None
+    path_part, range_part = spec.rsplit(":", 1)
+    if "-" not in range_part:
+        return None
+    try:
+        start_str, end_str = range_part.split("-", 1)
+        return path_part, int(start_str), int(end_str)
+    except (ValueError, IndexError):
+        return None
+
+
+# ---------------------------------------------------------------------------
+# line / range / diff handlers
+# ---------------------------------------------------------------------------
+
+
+def _handle_line(args: argparse.Namespace) -> int:
+    repo = _resolve_repo()
+    if repo is None:
+        print("Not in a Git repository.", file=sys.stderr)
+        return 1
+
+    parsed = _parse_line_spec(args.spec)
+    if parsed is None:
+        print("Invalid format. Use: backstory line <file>:<line>", file=sys.stderr)
+        return 1
+
+    path, line = parsed
+    commit = commit_for_line(repo, path, line)
+    commits = [commit] if commit else []
+    output = format_retrieval_result(
+        file_path=path,
+        line_range=(line, line),
+        commits=commits,
+    )
+    print(output)
+    return 0
+
+
+def _handle_range(args: argparse.Namespace) -> int:
+    repo = _resolve_repo()
+    if repo is None:
+        print("Not in a Git repository.", file=sys.stderr)
+        return 1
+
+    parsed = _parse_range_spec(args.spec)
+    if parsed is None:
+        print("Invalid format. Use: backstory range <file>:<start>-<end>", file=sys.stderr)
+        return 1
+
+    path, start, end = parsed
+    commits = commits_for_range(repo, path, start, end)
+    output = format_retrieval_result(
+        file_path=path,
+        line_range=(start, end),
+        commits=commits,
+    )
+    print(output)
+    return 0
+
+
+def _handle_diff(args: argparse.Namespace) -> int:
+    repo = _resolve_repo()
+    if repo is None:
+        print("Not in a Git repository.", file=sys.stderr)
+        return 1
+
+    changed_files = files_in_diff(repo)
+    if not changed_files:
+        print("No uncommitted changes detected.")
+        return 0
+
+    print("Relevant prior context for current diff:")
+    print("")
+
+    for idx, file_path in enumerate(changed_files, 1):
+        commits = commits_for_file(repo, file_path)
+        print(f"{idx}. {file_path}")
+        if commits:
+            print(f"   Most recent commit: {commits[0].hash} - {commits[0].message}")
+            print(f"   Author: {commits[0].author}")
+        else:
+            print("   No previous commits found.")
+        print()
+
+    warnings = detect_potential_contradictions(repo, changed_files)
+    if warnings:
+        print("Potential contradictions:")
+        for warning in warnings:
+            print(f"  - {warning}")
+        print()
+
+    return 0

backstory/config.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from backstory.storage import (
+    INDEX_DB_NAME,
+    KNOWLEDGE_DIR_NAME,
+    PENDING_SESSION_NAME,
+    REDACTIONS_DIR_NAME,
+    SESSIONS_DIR_NAME,
+    STORAGE_DIR_NAME,
+    ensure_storage_layout,
+)
+
+
+DEFAULT_CONFIG = {
+    "version": 1,
+    "storage": {
+        "root": STORAGE_DIR_NAME,
+        "knowledge_dir": KNOWLEDGE_DIR_NAME,
+        "sessions_dir": SESSIONS_DIR_NAME,
+        "pending_file": PENDING_SESSION_NAME,
+        "redactions_dir": REDACTIONS_DIR_NAME,
+        "index_db": INDEX_DB_NAME,
+    },
+    "capture": {
+        "store_git_diff": True,
+        "store_transcripts": True,
+    },
+    "redaction": {
+        "enabled": True,
+    },
+}
+
+
+def config_path(repo_root: Path) -> Path:
+    return repo_root / ".backstory" / "config.json"
+
+
+def write_default_config(repo_root: Path) -> Path:
+    ensure_storage_layout(repo_root)
+    path = config_path(repo_root)
+    path.write_text(json.dumps(DEFAULT_CONFIG, indent=2) + "\n")
+    return path
+
+
+def load_config(repo_root: Path) -> dict:
+    return json.loads(config_path(repo_root).read_text())

backstory/contradiction.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+from backstory.okf import parse_session_markdown
+from backstory.storage import build_storage_paths
+
+NEGATION_PATTERNS = (
+    r"\bnot\b",
+    r"\bnever\b",
+    r"\binstead\b",
+    r"\bavoid\b",
+    r"\bprevent\b",
+    r"\bno longer\b",
+    r"\brather than\b",
+)
+
+
+def detect_potential_contradictions(repo_root: Path, changed_files: list[str]) -> list[str]:
+    """Return human-readable warnings for likely contradictions.
+
+    The first implementation is conservative: it only warns when a current
+    changed file overlaps with a previously attached session and that session
+    contains at least one negated or reversing decision.
+    """
+    changed = {path for path in changed_files if path}
+    if not changed:
+        return []
+
+    warnings: list[str] = []
+    for session in _load_attached_sessions(repo_root):
+        session_files = set(session.get("files", {}).get("changed", []))
+        overlap = sorted(changed.intersection(session_files))
+        if not overlap:
+            continue
+
+        reasoning = session.get("reasoning_summary", {})
+        decisions = reasoning.get("decisions", [])
+        for decision in decisions:
+            if _looks_like_reversal(decision):
+                commit_hash = session.get("commit", {}).get("hash") or session.get("session_id", "unknown")
+                warnings.append(
+                    f"Potential contradiction from {str(commit_hash)[:7]} on {', '.join(overlap)}: {decision}"
+                )
+                break
+
+    return warnings
+
+
+def _load_attached_sessions(repo_root: Path) -> list[dict[str, Any]]:
+    """Load attached session objects from local storage."""
+    paths = build_storage_paths(repo_root)
+    sessions: list[dict[str, Any]] = []
+
+    if not paths.sessions.exists():
+        return sessions
+
+    for path in sorted(paths.sessions.glob("*.md")):
+        if path.name == "latest.md":
+            continue
+        try:
+            knowledge = parse_session_markdown(path.read_text(encoding="utf-8"))
+        except OSError:
+            continue
+        sessions.append(knowledge.to_session_dict())
+
+    return sessions
+
+
+def _looks_like_reversal(text: str) -> bool:
+    """Detect the negated phrasing typically used in a contradictory decision."""
+    lowered = text.lower()
+    return any(re.search(pattern, lowered) for pattern in NEGATION_PATTERNS)