ramets 0.3.0__py3-none-any.whl

ramets/__init__.py

@@ -0,0 +1,13 @@
+"""ramets — Per-branch AI coding context.
+
+Your codebase is one organism. Each branch is a ramet.
+
+Named after Pando (Populus tremuloides), the world's largest organism —
+a single aspen clone where individual trunks (ramets) share one root system (genet).
+
+- Genet: the shared base knowledge graph (common ancestor of all branches)
+- Ramets: per-branch delta-encoded graphs (individual trunks from the shared root)
+- Decisions: structured tracking of AI suggestions and user choices
+"""
+
+__version__ = "0.3.0"

ramets/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as `python -m ramets`."""
+
+from ramets.cli import main
+
+main()

ramets/cli.py

@@ -0,0 +1,501 @@
+"""CLI entry point — `ramets` command.
+
+Your codebase is one organism. Each branch is a ramet.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from ramets.core.branch import (
+    current_branch,
+    get_db_path,
+    get_main_repo_root,
+    get_ramets_dir,
+)
+from ramets.core.db import GenetDB
+
+
+def _get_db() -> GenetDB:
+    """Get a database connection, or exit with helpful message."""
+    db_path = get_db_path()
+    if not db_path.exists():
+        click.echo("No ramets database found. Run `ramets init` first.", err=True)
+        sys.exit(1)
+    return GenetDB(db_path)
+
+
+@click.group()
+@click.version_option()
+def main():
+    """ramets — Per-branch AI coding context.
+
+    Your codebase is one organism. Each branch is a ramet.
+
+    Named after Pando (Populus tremuloides), the world's largest organism —
+    individual trunks (ramets) sharing one root system (genet).
+    """
+    pass
+
+
+@main.command()
+@click.option("--no-hooks", is_flag=True, help="Skip git/Claude hook installation")
+@click.option("--no-claude-hooks", is_flag=True, help="Skip Claude Code hook installation")
+def init(no_hooks: bool, no_claude_hooks: bool):
+    """Initialize ramets in the current repository.
+
+    Creates .ramets/, builds the genet (base graph), and installs hooks.
+    """
+    try:
+        repo_root = get_main_repo_root()
+    except RuntimeError:
+        click.echo("Error: Not inside a git repository.", err=True)
+        sys.exit(1)
+
+    ramets_dir = get_ramets_dir()
+    ramets_dir.mkdir(parents=True, exist_ok=True)
+
+    # Initialize database
+    db_path = ramets_dir / "store.db"
+    db = GenetDB(db_path)
+    db.init_schema()
+
+    click.echo(f"Initialized .ramets/ at {ramets_dir}")
+
+    # Build genet
+    click.echo("Building genet (base graph)...")
+    from ramets.core.base import build_genet
+
+    graph_data = build_genet(db, repo_root)
+    node_count = len(graph_data.get("nodes", []))
+    edge_count = len(graph_data.get("links", []))
+    click.echo(f"Genet built: {node_count} nodes, {edge_count} edges")
+
+    # Register current branch
+    branch = current_branch(cwd=repo_root)
+    db.register_branch(branch)
+    click.echo(f"Registered branch: {branch}")
+
+    # Install git hooks
+    if not no_hooks:
+        from ramets.hooks.git import install_git_hooks
+
+        installed = install_git_hooks(repo_root)
+        click.echo(f"Installed git hooks: {', '.join(installed)}")
+
+    # Install Claude Code hooks
+    if not no_hooks and not no_claude_hooks:
+        from ramets.hooks.claude import install_claude_hooks
+
+        install_claude_hooks(repo_root)
+        click.echo("Installed Claude Code hooks in .claude/settings.json")
+
+    # Add .ramets/ to .gitignore
+    gitignore = repo_root / ".gitignore"
+    if gitignore.exists():
+        content = gitignore.read_text()
+        if ".ramets/" not in content:
+            with open(gitignore, "a") as f:
+                f.write("\n# ramets knowledge graph (local)\n.ramets/\n")
+            click.echo("Added .ramets/ to .gitignore")
+    else:
+        gitignore.write_text("# ramets knowledge graph (local)\n.ramets/\n")
+        click.echo("Created .gitignore with .ramets/")
+
+    db.close()
+
+    click.echo('\nReady! Try: ramets query "how does the main module work?"')
+    click.echo(f"Storage: {db_path.stat().st_size / 1024:.0f} KB")
+
+
+@main.command()
+def build():
+    """Full genet rebuild from current HEAD."""
+    db = _get_db()
+    repo_root = get_main_repo_root()
+
+    click.echo("Rebuilding genet...")
+    from ramets.core.base import build_genet
+
+    graph_data = build_genet(db, repo_root)
+    node_count = len(graph_data.get("nodes", []))
+    edge_count = len(graph_data.get("links", []))
+    click.echo(f"Genet rebuilt: {node_count} nodes, {edge_count} edges")
+
+    db.close()
+
+
+@main.command()
+def update():
+    """Incremental delta update for current branch.
+
+    Called by post-commit hook. Computes what changed vs genet.
+    """
+    db = _get_db()
+    repo_root = get_main_repo_root()
+    branch = current_branch(cwd=repo_root)
+
+    from ramets.core.base import load_genet_or_build
+    from ramets.core.delta import compute_deltas
+    from ramets.extract.ast_bridge import extract_graph
+
+    genet = load_genet_or_build(db, repo_root)
+    branch_graph = extract_graph(repo_root)
+    deltas = compute_deltas(genet, branch_graph)
+
+    from ramets.core.branch import current_commit
+
+    commit = current_commit(cwd=repo_root)
+
+    # Replace deltas (compute_deltas returns full diff vs genet, not incremental)
+    db.conn.execute("DELETE FROM ramet_deltas WHERE branch = ?", (branch,))
+    db.conn.execute("DELETE FROM ramets WHERE branch = ?", (branch,))
+    db.conn.commit()
+
+    if deltas:
+        db.append_deltas(branch, commit, deltas)
+        click.echo(f"{len(deltas)} deltas for {branch}")
+    else:
+        click.echo(f"No changes for {branch}")
+
+    db.close()
+
+
+@main.command()
+def status():
+    """Show genet freshness, ramet count, delta sizes, storage."""
+    db = _get_db()
+
+    genet_meta = db.genet_meta()
+    if genet_meta:
+        click.echo(
+            f"Genet: {genet_meta['node_count']} nodes, "
+            f"{genet_meta['edge_count']} edges "
+            f"(commit {genet_meta['commit_sha']}, built {genet_meta['built_at']})"
+        )
+    else:
+        click.echo("Genet: not built")
+
+    branches = db.list_branches()
+    click.echo(f"\nBranches: {len(branches)}")
+    for b in branches:
+        delta_count = db.delta_count(b["name"])
+        ramet = db.ramet_meta(b["name"])
+        cached = f" [cached: {ramet['node_count']}n/{ramet['edge_count']}e]" if ramet else ""
+        click.echo(f"  {b['name']}: {delta_count} deltas{cached}")
+
+    ramets_dir = get_ramets_dir()
+    db_size = (ramets_dir / "store.db").stat().st_size
+    click.echo(f"\nStorage: {db_size / 1024:.0f} KB ({ramets_dir})")
+
+    db.close()
+
+
+@main.command("query")
+@click.argument("question")
+@click.option("--branch", "-b", default=None, help="Branch to query (default: current)")
+@click.option("--depth", "-d", default=3, help="BFS traversal depth")
+@click.option("--budget", default=2000, help="Approximate token budget")
+def query_cmd(question: str, branch: str | None, depth: int, budget: int):
+    """Query the knowledge graph."""
+    db = _get_db()
+
+    from ramets.core.materialize import query_graph
+
+    result = query_graph(db, question, branch=branch, depth=depth, token_budget=budget)
+    click.echo(result)
+    db.close()
+
+
+@main.command("diff")
+@click.argument("branch_a")
+@click.argument("branch_b", default="main")
+def diff_cmd(branch_a: str, branch_b: str):
+    """Show graph differences between two branches."""
+    db = _get_db()
+
+    from ramets.core.materialize import diff_branches
+
+    result = diff_branches(db, branch_a, branch_b)
+    click.echo(result)
+    db.close()
+
+
+@main.command()
+def summary():
+    """Print the session summary (~400 tokens)."""
+    db = _get_db()
+
+    from ramets.core.materialize import summary as gen_summary
+
+    result = gen_summary(db)
+    click.echo(result)
+    db.close()
+
+
+@main.command()
+@click.option("--open", "open_obsidian", is_flag=True, help="Open vault in Obsidian")
+@click.option("--dir", "vault_dir", default=None, help="Custom output directory")
+@click.option("--all-branches", is_flag=True, help="Generate all branch layers")
+def obsidian(open_obsidian: bool, vault_dir: str | None, all_branches: bool):
+    """Generate Obsidian vault with branch layers."""
+    db = _get_db()
+
+    from ramets.obsidian.vault import generate_vault
+
+    output = Path(vault_dir) if vault_dir else get_ramets_dir() / "obsidian"
+
+    branches_to_render = None
+    if all_branches:
+        branches_to_render = [b["name"] for b in db.list_branches()]
+
+    generate_vault(db, output, branches=branches_to_render)
+    click.echo(f"Obsidian vault generated at {output}")
+
+    if open_obsidian:
+        import subprocess
+
+        subprocess.run(
+            ["open", f"obsidian://open?path={output}"],
+            check=False,
+        )
+        click.echo("Opening in Obsidian...")
+
+    db.close()
+
+
+@main.command()
+@click.option("--question", "-q", required=True, help="The decision question")
+@click.option(
+    "--options",
+    "-o",
+    multiple=True,
+    required=True,
+    help="Options (repeat for each). Format: 'label' or 'label:description'",
+)
+@click.option("--chosen", "-c", type=int, required=True, help="Index of chosen option (0-based)")
+@click.option(
+    "--category",
+    type=click.Choice(
+        [
+            "architecture",
+            "implementation",
+            "dependency",
+            "naming",
+            "algorithm",
+            "refactor",
+            "config",
+            "test_strategy",
+            "api_design",
+            "data_model",
+            "performance",
+            "security",
+        ]
+    ),
+    default="implementation",
+    help="Decision category",
+)
+@click.option("--rationale", "-r", default="", help="Why this option was chosen")
+@click.option("--confidence", type=float, default=0.8, help="Confidence level (0.0-1.0)")
+@click.option("--file", "context_files", multiple=True, help="Related files")
+def decide(
+    question: str,
+    options: tuple[str, ...],
+    chosen: int,
+    category: str,
+    rationale: str,
+    confidence: float,
+    context_files: tuple[str, ...],
+):
+    """Record a design/implementation decision.
+
+    Examples:
+        ramets decide -q "Auth strategy?" -o "JWT" -o "Session cookies" -c 0 -r "Stateless"
+        ramets decide -q "ORM choice?" -o "SQLAlchemy:Full ORM" -o "Raw SQL" -c 1 --category dependency
+    """
+    db = _get_db()
+
+    from ramets.core.branch import current_commit
+    from ramets.decision.schema import Decision, Option
+    from ramets.decision.tracker import DecisionTracker
+
+    if chosen < 0 or chosen >= len(options):
+        click.echo(f"Error: --chosen must be 0-{len(options) - 1}", err=True)
+        sys.exit(1)
+
+    parsed_options = []
+    for opt_str in options:
+        if ":" in opt_str:
+            label, desc = opt_str.split(":", 1)
+            parsed_options.append(Option(label=label.strip(), description=desc.strip()))
+        else:
+            parsed_options.append(Option(label=opt_str.strip()))
+
+    branch = current_branch()
+    commit = current_commit()
+
+    decision = Decision(
+        branch=branch,
+        category=category,
+        question=question,
+        options=parsed_options,
+        chosen=chosen,
+        rationale=rationale,
+        confidence=confidence,
+        context_files=list(context_files),
+        commit_sha=commit,
+    )
+
+    tracker = DecisionTracker(db)
+    did = tracker.record(decision)
+    chosen_label = parsed_options[chosen].label
+
+    click.echo(f"Decision recorded: {did}")
+    click.echo(f"  Q: {question}")
+    click.echo(f"  Chose: {chosen_label}")
+    if rationale:
+        click.echo(f"  Why: {rationale}")
+
+    db.close()
+
+
+@main.command()
+@click.option("--branch", "-b", default=None, help="Filter by branch")
+@click.option("--category", default=None, help="Filter by category")
+@click.option("--status", default="active", help="Filter by status")
+@click.option("--search", "-s", default=None, help="Full-text search")
+@click.option("--id", "decision_id", default=None, help="Show specific decision by ID")
+def decisions(
+    branch: str | None,
+    category: str | None,
+    status: str,
+    search: str | None,
+    decision_id: str | None,
+):
+    """List or search decisions for the current branch.
+
+    Examples:
+        ramets decisions                     # All active decisions
+        ramets decisions -s "auth"           # Search for auth-related
+        ramets decisions --id abc123         # Show specific decision
+        ramets decisions --category architecture
+    """
+    db = _get_db()
+
+    from ramets.decision.tracker import DecisionTracker
+
+    tracker = DecisionTracker(db)
+
+    if decision_id:
+        d = tracker.get(decision_id)
+        if d is None:
+            click.echo(f"Decision not found: {decision_id}", err=True)
+            sys.exit(1)
+        _print_decision_detail(d)
+        db.close()
+        return
+
+    if search:
+        results = tracker.search(search)
+    else:
+        if branch is None:
+            branch = current_branch()
+        results = tracker.query(branch=branch, category=category, status=status)
+
+    if not results:
+        click.echo("No decisions found.")
+    else:
+        click.echo(f"Decisions: {len(results)}")
+        for d in results:
+            chosen_label = d.options[d.chosen].label if d.options else "?"
+            status_icon = {"active": "●", "superseded": "○", "reversed": "✗", "deferred": "◌"}.get(
+                d.status.value, "?"
+            )
+            click.echo(f"  {status_icon} [{d.id}] {d.question}")
+            click.echo(f"    → {chosen_label} ({d.category.value}, {d.confidence or '?'})")
+
+    db.close()
+
+
+def _print_decision_detail(d) -> None:
+    """Print full decision details."""
+    click.echo(f"Decision: {d.id}")
+    click.echo(f"  Question: {d.question}")
+    click.echo(f"  Category: {d.category.value}")
+    click.echo(f"  Branch: {d.branch}")
+    click.echo(f"  Status: {d.status.value}")
+    click.echo(f"  Timestamp: {d.timestamp}")
+    click.echo(f"  Confidence: {d.confidence}")
+    if d.commit_sha:
+        click.echo(f"  Commit: {d.commit_sha}")
+    click.echo("  Options:")
+    for i, opt in enumerate(d.options):
+        marker = " ✓" if i == d.chosen else "  "
+        desc = f" — {opt.description}" if opt.description else ""
+        click.echo(f"   {marker} [{i}] {opt.label}{desc}")
+        if opt.pros:
+            for pro in opt.pros:
+                click.echo(f"         + {pro}")
+        if opt.cons:
+            for con in opt.cons:
+                click.echo(f"         - {con}")
+    if d.rationale:
+        click.echo(f"  Rationale: {d.rationale}")
+    if d.context_files:
+        click.echo(f"  Files: {', '.join(d.context_files)}")
+
+
+@main.command()
+def gc():
+    """Prune dead ramets, compact the genet database."""
+    db = _get_db()
+
+    from ramets.core.branch import list_worktrees
+
+    # Get active branches from worktrees + current
+    active = {current_branch()}
+    for wt in list_worktrees():
+        if "branch" in wt:
+            active.add(wt["branch"])
+
+    # Find stale branches
+    all_branches = db.list_branches()
+    stale = [b for b in all_branches if b["name"] not in active]
+
+    if stale:
+        for b in stale:
+            db.delete_ramet(b["name"])
+            db.conn.execute("DELETE FROM branches WHERE name = ?", (b["name"],))
+            click.echo(f"  Pruned: {b['name']}")
+        db.conn.commit()
+        click.echo(f"Pruned {len(stale)} stale ramets")
+    else:
+        click.echo("No stale ramets to prune")
+
+    # VACUUM to reclaim space
+    db.conn.execute("VACUUM")
+    click.echo("Database compacted")
+
+    db.close()
+
+
+@main.command()
+def serve():
+    """Start MCP server (stdio for Claude Code)."""
+    try:
+        from ramets.mcp.server import run_server
+
+        run_server()
+    except ImportError:
+        click.echo(
+            "MCP dependencies not installed. Run: pip install ramets[mcp]",
+            err=True,
+        )
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

ramets/core/__init__.py

@@ -0,0 +1 @@
+"""Core storage and graph operations."""

ramets/core/base.py

@@ -0,0 +1,45 @@
+"""Genet builder — constructs the base (shared root) graph.
+
+Wraps graphify's AST extraction to build the initial knowledge graph,
+then stores it as a compressed blob in the genet table.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ramets.core.branch import current_commit, get_repo_root
+from ramets.core.db import GenetDB
+from ramets.extract.ast_bridge import extract_graph
+
+
+def build_genet(db: GenetDB, repo_path: Path | None = None) -> dict:
+    """Build the base graph from the current HEAD and store it.
+
+    Args:
+        db: The genet database connection.
+        repo_path: Repository root path. Defaults to current repo root.
+
+    Returns:
+        The graph data dict {nodes: [...], links: [...]}.
+    """
+    if repo_path is None:
+        repo_path = get_repo_root()
+
+    commit_sha = current_commit(cwd=repo_path)
+
+    # Extract AST graph via graphify
+    graph_data = extract_graph(repo_path)
+
+    # Store as genet
+    db.store_genet(graph_data, commit_sha)
+
+    return graph_data
+
+
+def load_genet_or_build(db: GenetDB, repo_path: Path | None = None) -> dict:
+    """Load genet from DB, or build if it doesn't exist."""
+    genet = db.load_genet()
+    if genet is not None:
+        return genet
+    return build_genet(db, repo_path)

ramets/core/branch.py

@@ -0,0 +1,116 @@
+"""Branch and worktree detection.
+
+Resolves the current branch, the main repo root (even from worktrees),
+and the .ramets/ data directory.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+
+def git_run(*args: str, cwd: Path | None = None) -> str:
+    """Run a git command and return stdout, stripped."""
+    result = subprocess.run(
+        ["git", *args],
+        capture_output=True,
+        text=True,
+        cwd=str(cwd) if cwd else None,
+    )
+    return result.stdout.strip()
+
+
+def get_repo_root(cwd: Path | None = None) -> Path:
+    """Get the working tree root (could be a worktree)."""
+    root = git_run("rev-parse", "--show-toplevel", cwd=cwd)
+    if not root:
+        raise RuntimeError("Not inside a git repository")
+    return Path(root)
+
+
+def get_main_repo_root(cwd: Path | None = None) -> Path:
+    """Get the main repo root, resolving through worktrees.
+
+    In a worktree, .git is a file pointing to the main repo's .git/worktrees/<name>.
+    We resolve back to the main repo root.
+    """
+    root = get_repo_root(cwd)
+    git_common = git_run("rev-parse", "--git-common-dir", cwd=root)
+    if git_common and not git_common.startswith("--"):
+        common_path = Path(git_common)
+        if not common_path.is_absolute():
+            common_path = (root / common_path).resolve()
+        # .git/worktrees/xxx → .git → repo root
+        if common_path.name == ".git":
+            return common_path.parent
+        # Already at .git
+        return common_path.parent
+    return root
+
+
+def get_ramets_dir(cwd: Path | None = None) -> Path:
+    """Get the .ramets/ directory path (at main repo root)."""
+    return get_main_repo_root(cwd) / ".ramets"
+
+
+def get_db_path(cwd: Path | None = None) -> Path:
+    """Get the path to store.db."""
+    return get_ramets_dir(cwd) / "store.db"
+
+
+def current_branch(cwd: Path | None = None) -> str:
+    """Get the current branch name."""
+    branch = git_run("rev-parse", "--abbrev-ref", "HEAD", cwd=cwd)
+    return branch or "HEAD"
+
+
+def current_commit(cwd: Path | None = None) -> str:
+    """Get the current commit SHA (short)."""
+    return git_run("rev-parse", "--short", "HEAD", cwd=cwd)
+
+
+def merge_base(
+    branch_a: str = "HEAD", branch_b: str = "main", cwd: Path | None = None
+) -> str | None:
+    """Find the merge-base commit between two branches."""
+    result = git_run("merge-base", branch_a, branch_b, cwd=cwd)
+    return result or None
+
+
+def changed_files(since: str = "HEAD~1", until: str = "HEAD", cwd: Path | None = None) -> list[str]:
+    """Get files changed between two commits."""
+    output = git_run("diff", "--name-only", since, until, cwd=cwd)
+    if not output:
+        return []
+    return [f.strip() for f in output.splitlines() if f.strip()]
+
+
+def is_worktree(cwd: Path | None = None) -> bool:
+    """Check if the current directory is a git worktree (not the main repo)."""
+    root = get_repo_root(cwd)
+    main_root = get_main_repo_root(cwd)
+    return root != main_root
+
+
+def list_worktrees(cwd: Path | None = None) -> list[dict]:
+    """List all worktrees for this repo."""
+    output = git_run("worktree", "list", "--porcelain", cwd=cwd)
+    if not output:
+        return []
+    worktrees = []
+    current: dict = {}
+    for line in output.splitlines():
+        if line.startswith("worktree "):
+            if current:
+                worktrees.append(current)
+            current = {"path": line.split(" ", 1)[1]}
+        elif line.startswith("HEAD "):
+            current["head"] = line.split(" ", 1)[1]
+        elif line.startswith("branch "):
+            current["branch"] = line.split(" ", 1)[1].replace("refs/heads/", "")
+        elif line == "bare":
+            current["bare"] = True
+    if current:
+        worktrees.append(current)
+    return worktrees