contexthub-cli 0.1.0

package/contexthub/cli.py

@@ -0,0 +1,1331 @@
+"""ContextHub CLI — ch init, ch commit, ch spawn, ch resolve, ch review-resolution, ch accept-resolution, ch search."""
+
+from __future__ import annotations
+
+import json
+import sys
+import time
+import urllib.request
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+
+import click
+
+from contexthub.core import git as gitops
+from contexthub.core.context import ContextError, capture_context, find_latest_session, parse_session_jsonl, truncate_context
+from contexthub.core.git import GitError
+from contexthub.core.github import parse_github_remote
+from contexthub.core.models import ContextRecord, RepoConfig, ResolutionRecord
+from contexthub.core.r2 import R2Error, get_resolution, upload_context, upload_resolution, update_resolution
+
+
+@click.group()
+def cli():
+    """ContextHub — intent-first version control on top of git."""
+    pass
+
+
+# ---------- ch init ----------
+
+
+@cli.command()
+@click.argument("url", required=False, default=None)
+def init(url: str | None):
+    """Initialize ContextHub in the current directory.
+
+    Accepts a GitHub URL, owner/repo shorthand, or auto-detects from git remote.
+
+    \b
+    Examples:
+      ch init https://github.com/org/repo.git
+      ch init git@github.com:org/repo.git
+      ch init org/repo
+      ch init          (auto-detect from existing remote)
+    """
+    # 1. Init git repo if needed
+    if not gitops.is_inside_work_tree():
+        click.echo("[1/6] Initializing git repository...")
+        try:
+            gitops.init_repo(cwd=Path.cwd())
+            click.echo("       Done.")
+        except GitError as e:
+            click.echo(f"       Error: {e}", err=True)
+            sys.exit(1)
+    else:
+        click.echo("[1/6] Git repository found.")
+
+    # 2. Find git root
+    git_root = gitops.get_toplevel()
+
+    # 3. Already initialized?
+    ch_dir = git_root / ".ch"
+    if ch_dir.is_dir():
+        click.echo("Already initialized.")
+        return
+
+    # 4. Determine owner/repo
+    click.echo("[2/6] Configuring repository...")
+    if url:
+        # Try parsing as a GitHub URL first
+        parsed = parse_github_remote(url)
+        if parsed:
+            owner, repo_name = parsed
+            remote_url = url
+        else:
+            # Try as owner/repo shorthand
+            parts = url.split("/")
+            if len(parts) == 2 and parts[0] and parts[1]:
+                owner, repo_name = parts
+                remote_url = f"https://github.com/{owner}/{repo_name}.git"
+            else:
+                click.echo(
+                    "       Error: Provide a GitHub URL or owner/repo format.",
+                    err=True,
+                )
+                sys.exit(1)
+
+        remote_name = "origin"
+        click.echo(f"       Repo: {owner}/{repo_name}")
+
+        # Add git remote if it doesn't exist
+        try:
+            existing = gitops.get_remote_url("origin", cwd=git_root)
+            click.echo(f"       Remote origin already set: {existing}")
+        except GitError:
+            try:
+                gitops.add_remote("origin", remote_url, cwd=git_root)
+                click.echo(f"       Added remote origin -> {remote_url}")
+            except GitError:
+                pass
+    else:
+        # Auto-detect from existing remote
+        try:
+            remote_url = gitops.get_remote_url("origin", cwd=git_root)
+        except GitError:
+            click.echo(
+                "       Error: No remote found. Pass a GitHub URL:",
+                err=True,
+            )
+            click.echo(
+                "       ch init https://github.com/owner/repo.git",
+                err=True,
+            )
+            sys.exit(1)
+
+        parsed = parse_github_remote(remote_url)
+        if parsed is None:
+            click.echo(
+                "       Error: Could not parse remote URL. Pass a GitHub URL.",
+                err=True,
+            )
+            sys.exit(1)
+        owner, repo_name = parsed
+        remote_name = "origin"
+        click.echo(f"       Detected: {owner}/{repo_name} from remote")
+
+    # 5. Create .ch/ directory and config
+    click.echo("[3/6] Creating .ch/config.json...")
+    ch_dir.mkdir(parents=True, exist_ok=True)
+    config = RepoConfig(
+        owner=owner,
+        repo=repo_name,
+        remote_url=remote_url,
+        remote_name=remote_name,
+    )
+    config_path = ch_dir / "config.json"
+    config_path.write_text(config.to_json() + "\n", encoding="utf-8")
+    click.echo("       Done.")
+
+    # 6. Add .ch/ to .gitignore
+    click.echo("[4/6] Updating .gitignore...")
+    gitignore_path = git_root / ".gitignore"
+    if gitignore_path.exists():
+        content = gitignore_path.read_text(encoding="utf-8")
+        if ".ch/" not in content and ".ch\n" not in content:
+            with open(gitignore_path, "a", encoding="utf-8") as f:
+                if not content.endswith("\n"):
+                    f.write("\n")
+                f.write(".ch/\n")
+            click.echo("       Added .ch/ to .gitignore")
+        else:
+            click.echo("       .ch/ already in .gitignore")
+    else:
+        gitignore_path.write_text(".ch/\n", encoding="utf-8")
+        click.echo("       Created .gitignore with .ch/")
+
+    # 7. Install Claude Code hooks in .claude/settings.json
+    click.echo("[5/6] Installing Claude Code hooks...")
+    _install_hooks(git_root)
+
+    # 8. Add agent instructions to CLAUDE.md
+    click.echo("[6/7] Adding agent instructions to CLAUDE.md...")
+    _install_claude_md(git_root)
+
+    # 9. Success
+    click.echo(f"[7/7] ContextHub initialized — connected to {owner}/{repo_name}")
+
+
+# ---------- ch watch ----------
+
+
+@cli.command()
+def watch():
+    """Live-tail the current Claude Code session transcript."""
+    git_root = _find_ch_root()
+    if git_root is None:
+        # Fall back to git root even without .ch/
+        try:
+            git_root = gitops.get_toplevel()
+        except GitError:
+            click.echo("Error: Not in a git repository.", err=True)
+            sys.exit(1)
+
+    result = find_latest_session(git_root)
+    if result is None:
+        click.echo("No active Claude Code session found for this project.", err=True)
+        sys.exit(1)
+
+    session_path, session_id = result
+    click.echo(f"Watching session: {session_id}")
+    click.echo(f"File: {session_path}")
+    click.echo("─" * 60)
+
+    last_size = 0
+    last_line_count = 0
+
+    try:
+        while True:
+            try:
+                current_size = session_path.stat().st_size
+            except FileNotFoundError:
+                click.echo("\nSession file removed.")
+                break
+
+            if current_size != last_size:
+                last_size = current_size
+                transcript = parse_session_jsonl(session_path)
+                lines = transcript.split("\n")
+                if len(lines) > last_line_count:
+                    # Print only new lines
+                    new_text = "\n".join(lines[last_line_count:])
+                    click.echo(new_text)
+                    last_line_count = len(lines)
+
+            time.sleep(1)
+    except KeyboardInterrupt:
+        click.echo("\nStopped watching.")
+
+
+# ---------- ch spawn ----------
+
+
+@cli.command()
+@click.argument("commit_sha")
+def spawn(commit_sha: str):
+    """Spawn a new Claude Code agent with context from a previous commit."""
+    import os
+    import tempfile
+
+    from contexthub.core.r2 import get_commit_context
+
+    # 1. Find config
+    git_root = _find_ch_root()
+    if git_root is None:
+        click.echo("Error: Not a ContextHub repo. Run 'ch init' first.", err=True)
+        sys.exit(1)
+
+    config_path = git_root / ".ch" / "config.json"
+    try:
+        config_data = json.loads(config_path.read_text(encoding="utf-8"))
+        config = RepoConfig.from_dict(config_data)
+    except (FileNotFoundError, json.JSONDecodeError, KeyError) as e:
+        click.echo(f"Error: Invalid .ch/config.json: {e}", err=True)
+        sys.exit(1)
+
+    # 2. Fetch commit context from R2
+    click.echo(f"Fetching context for {commit_sha}...")
+    try:
+        record = get_commit_context(config.owner, config.repo, commit_sha)
+    except Exception as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)
+
+    full_sha = record.get("git_commit_hash", commit_sha)
+    message = record.get("commit_message", "")
+    files = record.get("files_changed", [])
+    transcript = record.get("raw_context", "")
+
+    if not transcript:
+        click.echo("Error: No transcript found in this commit record.", err=True)
+        sys.exit(1)
+
+    # 3. Write context to temp file for the agent to read
+    context_file = Path(tempfile.mktemp(prefix=f"ch-context-{full_sha[:8]}-", suffix=".md"))
+    context_file.write_text(
+        f"# Context from commit {full_sha[:8]}\n\n"
+        f"**Commit message:** {message}\n"
+        f"**Files changed:** {', '.join(files)}\n"
+        f"**Branch:** {record.get('branch', 'unknown')}\n\n"
+        f"## Session Transcript\n\n{transcript}\n",
+        encoding="utf-8",
+    )
+
+    click.echo(f"Commit:  {full_sha[:8]}")
+    click.echo(f"Message: {message}")
+    click.echo(f"Files:   {len(files)} changed")
+    size_kb = len(transcript.encode("utf-8")) / 1024
+    click.echo(f"Context: {size_kb:.1f}KB")
+    click.echo(f"Written: {context_file}")
+    click.echo("Launching Claude Code agent...\n")
+
+    # 4. Launch claude with the context
+    initial_prompt = (
+        f"Read the file {context_file} — it contains the full session context "
+        f"from commit {full_sha[:8]} ({message}). "
+        f"Use this to understand what was done and continue working."
+    )
+    os.execlp("claude", "claude", initial_prompt)
+
+
+# ---------- ch resolve ----------
+
+
+@cli.command()
+@click.argument("local_sha")
+@click.argument("remote_sha", required=False, default=None)
+@click.option("--resolution-id", default=None, help="Reuse an existing resolution record instead of creating a new one.")
+def resolve(local_sha: str, remote_sha: str | None, resolution_id: str | None):
+    """Spawn a resolver agent with context from both sides of a merge conflict."""
+    import os
+    import tempfile
+
+    from contexthub.core.r2 import get_commit_context
+
+    # 1. Find config
+    git_root = _find_ch_root()
+    if git_root is None:
+        click.echo("Error: Not a ContextHub repo. Run 'ch init' first.", err=True)
+        sys.exit(1)
+
+    config_path = git_root / ".ch" / "config.json"
+    try:
+        config_data = json.loads(config_path.read_text(encoding="utf-8"))
+        config = RepoConfig.from_dict(config_data)
+    except (FileNotFoundError, json.JSONDecodeError, KeyError) as e:
+        click.echo(f"Error: Invalid .ch/config.json: {e}", err=True)
+        sys.exit(1)
+
+    # 2. Fetch context for local commit and write to separate temp file
+    click.echo(f"Fetching context for local commit {local_sha}...")
+    try:
+        local_record = get_commit_context(config.owner, config.repo, local_sha)
+    except Exception as e:
+        click.echo(f"Error fetching local context: {e}", err=True)
+        sys.exit(1)
+
+    local_message = local_record.get("commit_message", "")
+    local_files = local_record.get("files_changed", [])
+    local_full_sha = local_record.get("git_commit_hash", local_sha)
+
+    # Write local context to separate temp file
+    local_context_file = Path(tempfile.mktemp(prefix=f"ch-context-local-{local_full_sha[:8]}-", suffix=".md"))
+    local_context_file.write_text(_format_commit_context(local_record, "local"), encoding="utf-8")
+    click.echo(f"Local context: {local_context_file}")
+
+    # 3. Fetch context for remote commit and write to separate temp file
+    remote_context_file = None
+    remote_full_sha = ""
+    if remote_sha:
+        click.echo(f"Fetching context for remote commit {remote_sha}...")
+        try:
+            remote_record = get_commit_context(config.owner, config.repo, remote_sha)
+            remote_full_sha = remote_record.get("git_commit_hash", remote_sha)
+            remote_context_file = Path(tempfile.mktemp(prefix=f"ch-context-remote-{remote_full_sha[:8]}-", suffix=".md"))
+            remote_context_file.write_text(_format_commit_context(remote_record, "remote"), encoding="utf-8")
+            click.echo(f"Remote context: {remote_context_file}")
+        except Exception as e:
+            click.echo(f"Warning: Could not fetch remote context: {e}", err=True)
+
+    # 4. Start the rebase so the conflict markers are in the working tree
+    click.echo("Starting rebase to surface conflicts...")
+    try:
+        gitops.fetch(cwd=git_root)
+        gitops.pull_rebase(cwd=git_root)
+        # No conflict — rebase was clean
+        click.echo("No conflicts found — rebase succeeded cleanly.")
+        try:
+            gitops.push(cwd=git_root)
+            click.echo("Pushed to remote.")
+        except GitError as e:
+            click.echo(f"Warning: Push failed: {e}", err=True)
+        return
+    except GitError as e:
+        if "rebase_conflict" not in str(e):
+            click.echo(f"Error during rebase: {e}", err=True)
+            sys.exit(1)
+
+    # 5. Get conflicted files
+    conflicted = gitops.get_conflicted_files(cwd=git_root)
+    click.echo(f"Conflicts in {len(conflicted)} file(s):")
+    for f in conflicted:
+        click.echo(f"  {f}")
+
+    # 6. Create or reuse resolution record
+    if resolution_id:
+        click.echo(f"Reusing resolution record: {resolution_id}")
+        try:
+            update_resolution(config.owner, config.repo, resolution_id, {"status": "in_progress"})
+        except R2Error as e:
+            click.echo(f"Warning: Could not update resolution record: {e}", err=True)
+    else:
+        resolution_id = uuid.uuid4().hex[:12]
+        resolution = ResolutionRecord(
+            id=resolution_id,
+            owner=config.owner,
+            repo=config.repo,
+            local_sha=local_full_sha,
+            remote_sha=remote_full_sha or "",
+            session_id=None,
+            status="in_progress",
+            started_at=datetime.now(timezone.utc).isoformat(),
+            conflicted_files=conflicted,
+            repo_path=str(git_root),
+        )
+        try:
+            upload_resolution(config.owner, config.repo, resolution_id, resolution.to_dict())
+            click.echo(f"Resolution: {resolution_id}")
+        except R2Error as e:
+            click.echo(f"Warning: Could not upload resolution record: {e}", err=True)
+
+    # Write active resolution marker so hooks can link the session_id
+    active_res_file = git_root / ".ch" / "active_resolution"
+    active_res_file.write_text(resolution_id, encoding="utf-8")
+
+    # 7. Write instruction file with paths to context files and process steps
+    instruction_file = Path(tempfile.mktemp(prefix="ch-resolve-instructions-", suffix=".md"))
+    instructions = _build_resolver_instructions(
+        resolution_id=resolution_id,
+        local_sha=local_full_sha,
+        remote_sha=remote_full_sha,
+        local_context_file=str(local_context_file),
+        remote_context_file=str(remote_context_file) if remote_context_file else None,
+        conflicted_files=conflicted,
+        owner=config.owner,
+        repo=config.repo,
+    )
+    instruction_file.write_text(instructions, encoding="utf-8")
+
+    click.echo(f"Instructions: {instruction_file}")
+    click.echo("Launching resolver agent...\n")
+
+    # 8. Launch claude with instruction file (non-interactive, streaming JSON)
+    initial_prompt = (
+        f"Read the file {instruction_file} — it contains instructions for resolving a merge conflict "
+        f"between local commit {local_full_sha[:8]} and remote commit {remote_full_sha[:8] if remote_full_sha else 'unknown'}. "
+        f"Follow the steps in order. The rebase is in progress and conflict markers are in the working tree."
+    )
+    os.execlp("claude", "claude", "-p", initial_prompt, "--output-format", "stream-json", "--dangerously-skip-permissions")
+
+
+def _format_commit_context(record: dict, side: str) -> str:
+    """Format a commit context record as markdown for the agent to read."""
+    sha = record.get("git_commit_hash", "unknown")[:8]
+    message = record.get("commit_message", "")
+    files = record.get("files_changed", [])
+    goal = record.get("goal", "")
+    subgoal = record.get("subgoal", "")
+    transcript = record.get("raw_context", "")
+
+    parts = [
+        f"# {side.title()} Commit Context ({sha})\n",
+        f"\n**Commit:** {sha}\n",
+        f"**Message:** {message}\n",
+        f"**Files changed:** {', '.join(files)}\n",
+    ]
+
+    if goal:
+        parts.append(f"\n## Goal\n\n{goal}\n")
+
+    if subgoal:
+        parts.append(f"\n## Subgoal\n\n{subgoal}\n")
+
+    if transcript:
+        parts.append(f"\n## Session Transcript\n\n{transcript}\n")
+
+    return "".join(parts)
+
+
+def _build_resolver_instructions(
+    resolution_id: str,
+    local_sha: str,
+    remote_sha: str,
+    local_context_file: str,
+    remote_context_file: str | None,
+    conflicted_files: list[str],
+    owner: str,
+    repo: str,
+) -> str:
+    """Build the instruction file that guides the resolver agent through the process."""
+    parts = [
+        "# Merge Conflict Resolution Instructions\n",
+        "\n**You are an autonomous resolver agent.** Follow the steps below IN ORDER.\n",
+        "As you complete each step, the UI will update to show your progress.\n",
+        f"\n## Resolution Info\n",
+        f"- **Resolution ID:** {resolution_id}\n",
+        f"- **Local commit:** {local_sha[:8]}\n",
+        f"- **Remote commit:** {remote_sha[:8] if remote_sha else 'unknown'}\n",
+        f"- **Repository:** {owner}/{repo}\n",
+        f"\n## Conflicted Files\n",
+    ]
+
+    for f in conflicted_files:
+        parts.append(f"- `{f}`\n")
+
+    parts.append("\n## Process\n\n")
+    parts.append("Follow these steps **in order**:\n\n")
+
+    step = 1
+
+    # Step 1: Read local context
+    parts.append(f"### Step {step}: Read Local Commit Context\n\n")
+    parts.append(f"Read the local commit context to understand what changes were made and why:\n")
+    parts.append(f"```\n{local_context_file}\n```\n\n")
+    step += 1
+
+    # Step 2: Read remote context (if available)
+    if remote_context_file:
+        parts.append(f"### Step {step}: Read Remote Commit Context\n\n")
+        parts.append(f"Read the remote commit context to understand the incoming changes:\n")
+        parts.append(f"```\n{remote_context_file}\n```\n\n")
+        step += 1
+
+    # Step 3: Search for related commits
+    parts.append(f"### Step {step}: Search for Related Commits\n\n")
+    parts.append("Search for semantically related commits that might provide additional context.\n")
+    parts.append("Based on what you learned from the local and remote contexts, construct a search query:\n\n")
+    parts.append("```bash\n")
+    parts.append(f'ch search "<your search query based on the conflict>"\n')
+    parts.append("```\n\n")
+    parts.append("If the search returns relevant results, you can fetch their full context using:\n")
+    parts.append("```bash\n")
+    parts.append('ch get-context <commit-sha>\n')
+    parts.append("```\n\n")
+    step += 1
+
+    # Step 4: Read conflicted files
+    parts.append(f"### Step {step}: Read Conflicted Files\n\n")
+    parts.append("Read each conflicted file to see the conflict markers:\n\n")
+    for f in conflicted_files:
+        parts.append(f"- `{f}`\n")
+    parts.append("\n")
+    step += 1
+
+    # Step 5: Analyze and propose plan
+    parts.append(f"### Step {step}: Analyze and Propose Resolution Plan\n\n")
+    parts.append("Based on your understanding of both sides, propose a resolution plan.\n\n")
+    parts.append("For each conflicted file, describe:\n")
+    parts.append("1. What the **local side** changed and why (based on its goal/subgoal)\n")
+    parts.append("2. What the **remote side** changed and why (based on its goal/subgoal)\n")
+    parts.append("3. Your **proposed resolution**: which parts to keep from each side, and why\n")
+    parts.append("4. Any **trade-offs or risks** in your proposed resolution\n\n")
+    parts.append("**Do NOT edit any files yet.** Present your plan for user review.\n\n")
+    parts.append(f"When ready for review, run:\n")
+    parts.append(f"```bash\nch review-resolution {resolution_id}\n```\n")
+
+    return "".join(parts)
+
+
+# ---------- ch mark-resolved ----------
+
+
+@cli.command("mark-resolved")
+@click.argument("resolution_id")
+def mark_resolved(resolution_id: str):
+    """Mark a resolution as completed after the rebase succeeds."""
+    git_root = _find_ch_root()
+    if git_root is None:
+        click.echo("Error: Not a ContextHub repo. Run 'ch init' first.", err=True)
+        sys.exit(1)
+
+    config_path = git_root / ".ch" / "config.json"
+    try:
+        config_data = json.loads(config_path.read_text(encoding="utf-8"))
+        config = RepoConfig.from_dict(config_data)
+    except (FileNotFoundError, json.JSONDecodeError, KeyError) as e:
+        click.echo(f"Error: Invalid .ch/config.json: {e}", err=True)
+        sys.exit(1)
+
+    commit_hash = gitops.get_head_hash(cwd=git_root)
+
+    # Read session_id from marker file (written by stream hook)
+    active_res_file = git_root / ".ch" / "active_resolution"
+    session_id = None
+    if active_res_file.is_file():
+        lines = active_res_file.read_text(encoding="utf-8").strip().split("\n")
+        if len(lines) >= 2:
+            session_id = lines[1]
+
+    updates = {
+        "status": "completed",
+        "resolved_commit_hash": commit_hash,
+        "completed_at": datetime.now(timezone.utc).isoformat(),
+    }
+    if session_id:
+        updates["session_id"] = session_id
+
+    try:
+        update_resolution(config.owner, config.repo, resolution_id, updates)
+        click.echo(f"Resolution {resolution_id} marked completed (commit {commit_hash[:8]}).")
+        if session_id:
+            click.echo(f"Linked session: {session_id}")
+    except R2Error as e:
+        click.echo(f"Error: Could not update resolution record: {e}", err=True)
+        sys.exit(1)
+
+    # Don't delete active_resolution — handle_finalize needs it to link session_id
+
+
+# ---------- ch review-resolution ----------
+
+
+@cli.command("review-resolution")
+@click.argument("resolution_id")
+def review_resolution(resolution_id: str):
+    """Mark a resolution as pending review (called by resolver agent before asking user)."""
+    git_root = _find_ch_root()
+    if git_root is None:
+        click.echo("Error: Not a ContextHub repo. Run 'ch init' first.", err=True)
+        sys.exit(1)
+
+    config_path = git_root / ".ch" / "config.json"
+    try:
+        config_data = json.loads(config_path.read_text(encoding="utf-8"))
+        config = RepoConfig.from_dict(config_data)
+    except (FileNotFoundError, json.JSONDecodeError, KeyError) as e:
+        click.echo(f"Error: Invalid .ch/config.json: {e}", err=True)
+        sys.exit(1)
+
+    # Fetch current record to increment review_count
+    try:
+        record = get_resolution(config.owner, config.repo, resolution_id)
+    except R2Error as e:
+        click.echo(f"Error: Could not fetch resolution record: {e}", err=True)
+        sys.exit(1)
+
+    review_count = record.get("review_count", 0) + 1
+
+    updates = {
+        "status": "pending_review",
+        "review_requested_at": datetime.now(timezone.utc).isoformat(),
+        "review_count": review_count,
+    }
+
+    try:
+        update_resolution(config.owner, config.repo, resolution_id, updates)
+        click.echo(f"Resolution {resolution_id} marked pending_review (review #{review_count}).")
+    except R2Error as e:
+        click.echo(f"Error: Could not update resolution record: {e}", err=True)
+        sys.exit(1)
+
+
+# ---------- ch accept-resolution ----------
+
+
+@cli.command("accept-resolution")
+@click.argument("resolution_id")
+def accept_resolution(resolution_id: str):
+    """Mark a resolution as accepted by the user."""
+    git_root = _find_ch_root()
+    if git_root is None:
+        click.echo("Error: Not a ContextHub repo. Run 'ch init' first.", err=True)
+        sys.exit(1)
+
+    config_path = git_root / ".ch" / "config.json"
+    try:
+        config_data = json.loads(config_path.read_text(encoding="utf-8"))
+        config = RepoConfig.from_dict(config_data)
+    except (FileNotFoundError, json.JSONDecodeError, KeyError) as e:
+        click.echo(f"Error: Invalid .ch/config.json: {e}", err=True)
+        sys.exit(1)
+
+    updates = {
+        "status": "accepted",
+        "accepted_at": datetime.now(timezone.utc).isoformat(),
+    }
+
+    try:
+        update_resolution(config.owner, config.repo, resolution_id, updates)
+        click.echo(f"Resolution {resolution_id} accepted.")
+    except R2Error as e:
+        click.echo(f"Error: Could not update resolution record: {e}", err=True)
+        sys.exit(1)
+
+
+# ---------- ch get-context ----------
+
+
+@cli.command("get-context")
+@click.argument("sha")
+def get_context_cmd(sha: str):
+    """Fetch commit context from R2 and write to a temp file.
+
+    This command fetches the full context for a commit (goal, subgoal, transcript)
+    from R2 and writes it to a temp file that can be read by the agent.
+
+    \b
+    Examples:
+      ch get-context abc1234
+      ch get-context def5678
+    """
+    import tempfile
+
+    from contexthub.core.r2 import get_commit_context
+
+    # Find config
+    git_root = _find_ch_root()
+    if git_root is None:
+        click.echo("Error: Not a ContextHub repo. Run 'ch init' first.", err=True)
+        sys.exit(1)
+
+    config_path = git_root / ".ch" / "config.json"
+    try:
+        config_data = json.loads(config_path.read_text(encoding="utf-8"))
+        config = RepoConfig.from_dict(config_data)
+    except (FileNotFoundError, json.JSONDecodeError, KeyError) as e:
+        click.echo(f"Error: Invalid .ch/config.json: {e}", err=True)
+        sys.exit(1)
+
+    # Fetch context from R2
+    click.echo(f"Fetching context for commit {sha}...")
+    try:
+        record = get_commit_context(config.owner, config.repo, sha)
+    except Exception as e:
+        click.echo(f"Error: Could not fetch context: {e}", err=True)
+        sys.exit(1)
+
+    full_sha = record.get("git_commit_hash", sha)
+
+    # Write to temp file
+    context_file = Path(tempfile.mktemp(prefix=f"ch-context-{full_sha[:8]}-", suffix=".md"))
+    context_file.write_text(_format_commit_context(record, "related"), encoding="utf-8")
+
+    click.echo(f"Context written to: {context_file}")
+
+
+# ---------- ch search ----------
+
+
+@cli.command()
+@click.argument("query")
+@click.option("--limit", default=10, type=int, help="Max results to return (default 10)")
+@click.option("--owner", default=None, help="Repository owner (auto-detected from .ch/config.json)")
+@click.option("--repo", default=None, help="Repository name (auto-detected from .ch/config.json)")
+def search(query: str, limit: int, owner: str | None, repo: str | None):
+    """Semantic search over commit history.
+
+    \b
+    Examples:
+      ch search "authentication flow"
+      ch search "fix database connection" --limit 5
+      ch search "refactor" --owner myorg --repo myapp
+    """
+    # Auto-detect owner/repo from config if not provided
+    if not owner or not repo:
+        git_root = _find_ch_root()
+        if git_root is None:
+            click.echo(
+                "Error: Not a ContextHub repo and --owner/--repo not provided. "
+                "Run 'ch init' first or pass --owner and --repo.",
+                err=True,
+            )
+            sys.exit(1)
+        config_path = git_root / ".ch" / "config.json"
+        try:
+            config_data = json.loads(config_path.read_text(encoding="utf-8"))
+            config = RepoConfig.from_dict(config_data)
+            owner = owner or config.owner
+            repo = repo or config.repo
+        except (FileNotFoundError, json.JSONDecodeError, KeyError) as e:
+            click.echo(f"Error: Invalid .ch/config.json: {e}", err=True)
+            sys.exit(1)
+
+    # Call the search API
+    results = _call_search_api(query, owner, repo, limit)
+    if results is None:
+        click.echo("Error: Could not reach search API.", err=True)
+        sys.exit(1)
+
+    if not results:
+        click.echo("No results found.")
+        return
+
+    click.echo(f'\nFound {len(results)} result{"s" if len(results) != 1 else ""} for "{query}"\n')
+    for r in results:
+        score = r.get("score", 0)
+        sha = r.get("sha", r.get("commit_hash", "???????"))[:7]
+        message = r.get("message", r.get("commit_message", ""))
+        summary = r.get("summary", r.get("semantic_summary", ""))
+
+        pct = f"{score * 100:.0f}%"
+        click.echo(f"  {pct:>4} \u2502 {sha} \u2502 {message}")
+        if summary:
+            truncated = (summary[:72] + "...") if len(summary) > 75 else summary
+            click.echo(f"       \u2502         \u2502 {truncated}")
+
+
+# ---------- ch commit ----------
+
+
+@cli.command()
+@click.option("-m", "--message", required=True, help="Commit message")
+@click.option("--context", "context_file", default=None, help="File containing context")
+@click.option("--session", is_flag=True, help="Capture context from latest Claude Code session")
+@click.option("--stdin", "use_stdin", is_flag=True, help="Read context from stdin")
+@click.option("--no-push", is_flag=True, help="Skip pushing to remote")
+@click.option("--goal", default=None, help="High-level objective this commit works towards")
+@click.option("--subgoal", default=None, help="Specific task: problem, requirements, implementation")
+@click.option("--resolves", "resolution_id", default=None, help="Resolution ID to mark as completed")
+def commit(message: str, context_file: str | None, session: bool, use_stdin: bool, no_push: bool, goal: str | None, subgoal: str | None, resolution_id: str | None):
+    """Commit changes with agent context."""
+    # 1. Find .ch/ root
+    git_root = _find_ch_root()
+    if git_root is None:
+        click.echo("Error: Not a ContextHub repo. Run 'ch init' first.", err=True)
+        sys.exit(1)
+
+    # 2. Read config
+    config_path = git_root / ".ch" / "config.json"
+    try:
+        config_data = json.loads(config_path.read_text(encoding="utf-8"))
+        config = RepoConfig.from_dict(config_data)
+    except (FileNotFoundError, json.JSONDecodeError, KeyError) as e:
+        click.echo(f"Error: Invalid .ch/config.json: {e}", err=True)
+        sys.exit(1)
+
+    # 3. Capture context
+    explicit_context = session or context_file is not None or use_stdin
+    session_path = None
+    try:
+        if explicit_context:
+            raw_context, context_source, session_id = capture_context(
+                session=session,
+                context_file=context_file,
+                stdin=use_stdin,
+                git_root=git_root,
+            )
+        else:
+            # Auto-detect: if streaming hooks are active, reference the session
+            # without embedding the transcript (it's already in R2 via hooks)
+            result = find_latest_session(git_root)
+            if result is not None:
+                session_path, session_id = result
+                raw_context = None
+                context_source = "streamed_session"
+            else:
+                session_path = None
+                raw_context, context_source, session_id = None, None, None
+    except ContextError as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)
+
+    if raw_context is None and context_source is None:
+        click.echo("Warning: No context provided. Committing without context.", err=True)
+
+    # 4. Stage all changes
+    gitops.add_all(cwd=git_root)
+
+    # 5. Check there's something to commit
+    if not gitops.has_staged_changes(cwd=git_root):
+        click.echo("Error: Nothing to commit.", err=True)
+        sys.exit(1)
+
+    # 6. Create git commit
+    try:
+        gitops.commit(message, cwd=git_root)
+    except GitError as e:
+        click.echo(f"Error: Git commit failed: {e}", err=True)
+        sys.exit(1)
+
+    # 7. Get commit info
+    commit_hash = gitops.get_head_hash(cwd=git_root)
+    branch = gitops.get_current_branch(cwd=git_root)
+    files_changed = gitops.get_changed_files(commit_hash, cwd=git_root)
+
+    # 8. Build context record — embed transcript if available
+    transcript = None
+    if context_source == "streamed_session" and session_path and session_path.is_file():
+        try:
+            transcript = parse_session_jsonl(session_path)
+        except Exception:
+            pass
+
+    record = ContextRecord(
+        id=uuid.uuid4().hex[:12],
+        git_commit_hash=commit_hash,
+        commit_message=message,
+        files_changed=files_changed,
+        timestamp=datetime.now(timezone.utc).isoformat(),
+        raw_context=raw_context or transcript,
+        context_source=context_source,
+        session_id=session_id,
+        branch=branch,
+        goal=goal,
+        subgoal=subgoal,
+    )
+
+    try:
+        upload_context(config.owner, config.repo, commit_hash, record.to_dict())
+    except R2Error as e:
+        click.echo(
+            f"Error: {e}. Git commit succeeded ({commit_hash[:8]}).",
+            err=True,
+        )
+        # Don't exit — git commit is preserved
+        if not no_push:
+            _do_push(git_root, config, commit_hash)
+        _print_summary(commit_hash, branch, files_changed, raw_context or transcript, context_source, context_uploaded=False)
+        sys.exit(1)
+
+    # 10. If this commit resolves a merge conflict, update the resolution record
+    if resolution_id:
+        try:
+            update_resolution(config.owner, config.repo, resolution_id, {
+                "status": "completed",
+                "resolved_commit_hash": commit_hash,
+                "completed_at": datetime.now(timezone.utc).isoformat(),
+            })
+            click.echo(f"Resolution {resolution_id} marked completed.")
+        except R2Error as e:
+            click.echo(f"Warning: Could not update resolution record: {e}", err=True)
+
+    # 11. Push to remote (always, unless --no-push)
+    if not no_push:
+        _do_push(git_root, config, commit_hash)
+
+    # 12. Print summary
+    _print_summary(commit_hash, branch, files_changed, raw_context or transcript, context_source, context_uploaded=True)
+
+
+def _install_hooks(git_root: Path) -> None:
+    """Install Claude Code hooks into .claude/settings.json."""
+    claude_dir = git_root / ".claude"
+    claude_dir.mkdir(parents=True, exist_ok=True)
+    settings_path = claude_dir / "settings.json"
+
+    if settings_path.is_file():
+        try:
+            settings = json.loads(settings_path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, ValueError):
+            settings = {}
+    else:
+        settings = {}
+
+    hooks = settings.setdefault("hooks", {})
+
+    ch_stream_cmd = "ch _hook stream"
+    ch_finalize_cmd = "ch _hook finalize"
+
+    ch_stop_entry = {
+        "hooks": [{"type": "command", "command": ch_stream_cmd, "async": True}],
+    }
+    ch_end_entry = {
+        "hooks": [{"type": "command", "command": ch_finalize_cmd, "async": True}],
+    }
+
+    # Merge into existing hooks without duplicating
+    def _has_command(entries: list, cmd: str) -> bool:
+        for entry in entries:
+            for h in entry.get("hooks", []):
+                if h.get("command") == cmd:
+                    return True
+        return False
+
+    stop_hooks = hooks.get("Stop", [])
+    if not _has_command(stop_hooks, ch_stream_cmd):
+        stop_hooks.append(ch_stop_entry)
+    hooks["Stop"] = stop_hooks
+
+    end_hooks = hooks.get("SessionEnd", [])
+    if not _has_command(end_hooks, ch_finalize_cmd):
+        end_hooks.append(ch_end_entry)
+    hooks["SessionEnd"] = end_hooks
+
+    settings["hooks"] = hooks
+    settings_path.write_text(json.dumps(settings, indent=2) + "\n", encoding="utf-8")
+    click.echo("       Hooks: Stop -> ch _hook stream")
+    click.echo("       Hooks: SessionEnd -> ch _hook finalize")
+
+
+_CLAUDE_MD_SECTION = """\
+
+## ContextHub
+
+**Never use `git commit` or `git push` directly. Always use `ch commit`.**
+
+When you are done with your changes and ready to commit, ask the user:
+> "Ready to commit these changes? I'll use `ch commit` to save the context."
+
+Then run:
+```bash
+ch commit -m "concise description" --goal "<goal>" --subgoal "<subgoal>"
+```
+
+**Always include both `--goal` and `--subgoal`.** Write them as a software engineer scoping work — be detailed and specific, not terse. **Format both as markdown** so they render well when displayed later.
+
+#### `--goal` (the high-level objective)
+
+Describe the broader objective this commit contributes to as a short markdown paragraph. Include enough context that someone unfamiliar with the project can understand the purpose. Cover: what feature or system is being built, why it matters, what the end state looks like, and how this commit fits into the bigger picture.
+
+Example:
+```
+--goal "Building a complete **user authentication system** with OAuth2, session management, and role-based access control. The system needs to support enterprise SSO providers, handle token refresh flows, and integrate with the existing user database. This is the foundational auth layer that all API endpoints will depend on for access control."
+```
+
+#### `--subgoal` (the specific task in this commit)
+
+Describe exactly what this commit accomplishes. **Use markdown headers and bullet points** to structure the subgoal into sections: `## Problem`, `## Requirements`, `## Implementation`, `## Trade-offs`, and `## TODO`.
+
+Example:
+```
+--subgoal "## Problem
+The OAuth2 implementation was using the implicit grant flow which is deprecated and insecure for server-side apps — tokens were exposed in URL fragments.
+
+## Requirements
+- Must use Authorization Code flow with PKCE
+- Must handle token refresh without user interaction
+- Must store refresh tokens encrypted at rest
+
+## Implementation
+- Replaced the implicit flow in `auth_middleware.py` with Authorization Code + PKCE using a new `PKCEChallenge` class
+- Added `token_store.py` with AES-256 encrypted storage for refresh tokens
+- Updated the `/callback` endpoint to exchange codes for tokens server-side
+
+## Trade-offs
+Chose to store refresh tokens in the database rather than Redis for durability over speed — auth token refresh is infrequent enough that the latency is acceptable.
+
+## TODO
+- Token revocation endpoint
+- Refresh token rotation"
+```
+
+This stages, commits, uploads context to R2, and pushes — all in one step.
+
+### Merge Conflicts
+
+If `ch commit` detects a merge conflict during push, it will:
+1. Abort the rebase to keep the working tree clean
+2. Print a `ch resolve <local-sha> <remote-sha>` command
+
+**When you see this, run the printed `ch resolve` command.** It will spawn a resolver agent with full context from both sides of the conflict.
+
+### Spawning Agents with Context
+
+To continue work from a previous commit or understand its reasoning:
+```bash
+ch spawn <commit-sha>
+```
+"""
+
+
+def _install_claude_md(git_root: Path) -> None:
+    """Add ContextHub instructions to CLAUDE.md in the repo root."""
+    claude_md = git_root / "CLAUDE.md"
+    marker = "## ContextHub"
+
+    if claude_md.is_file():
+        content = claude_md.read_text(encoding="utf-8")
+        if marker in content:
+            click.echo("       CLAUDE.md already has ContextHub section.")
+            return
+        # Append to existing file
+        with open(claude_md, "a", encoding="utf-8") as f:
+            if not content.endswith("\n"):
+                f.write("\n")
+            f.write(_CLAUDE_MD_SECTION)
+        click.echo("       Appended ContextHub section to CLAUDE.md")
+    else:
+        claude_md.write_text(f"# Project Instructions\n{_CLAUDE_MD_SECTION}", encoding="utf-8")
+        click.echo("       Created CLAUDE.md with ContextHub instructions.")
+
+
+def _find_ch_root() -> Path | None:
+    """Walk up from cwd to find a directory containing .ch/."""
+    current = Path.cwd().resolve()
+    while True:
+        if (current / ".ch").is_dir():
+            return current
+        parent = current.parent
+        if parent == current:
+            return None
+        current = parent
+
+
+def _do_push(git_root: Path, config: RepoConfig | None = None, local_sha: str | None = None):
+    """Push to remote. On conflict, attempt rebase and offer to spawn resolver."""
+    try:
+        gitops.push(cwd=git_root)
+        click.echo("Pushed to remote.")
+        return
+    except GitError:
+        pass  # push failed, try to reconcile
+
+    # Push failed — fetch and try rebase
+    click.echo("Push failed — fetching remote changes...")
+    try:
+        gitops.fetch(cwd=git_root)
+    except GitError as e:
+        click.echo(f"Warning: Fetch failed: {e}", err=True)
+        return
+
+    # Get the incoming remote commits before rebase (for context lookup)
+    remote_shas = gitops.get_upstream_commits(cwd=git_root)
+
+    click.echo("Attempting rebase...")
+    try:
+        gitops.pull_rebase(cwd=git_root)
+        # Clean rebase — push again
+        click.echo("Rebase succeeded. Pushing...")
+        try:
+            gitops.push(cwd=git_root)
+            click.echo("Pushed to remote.")
+        except GitError as e:
+            click.echo(f"Warning: Push after rebase failed: {e}", err=True)
+        return
+    except GitError as e:
+        if "rebase_conflict" not in str(e):
+            click.echo(f"Warning: Rebase failed: {e}", err=True)
+            return
+
+    # Conflict detected
+    conflicted = gitops.get_conflicted_files(cwd=git_root)
+    click.echo(f"\nMerge conflict detected in {len(conflicted)} file(s):")
+    for f in conflicted:
+        click.echo(f"  {f}")
+
+    # Abort the rebase so the working tree is clean for the resolver
+    click.echo("Aborting rebase (resolver agent will handle it)...")
+    try:
+        gitops.abort_rebase(cwd=git_root)
+    except GitError:
+        pass
+
+    # Create resolution record in R2
+    if not config or not local_sha:
+        click.echo("Run 'ch resolve <local-sha> <remote-sha>' to resolve with context.", err=True)
+        return
+
+    # Snapshot conflicted files at the local SHA (before it's pushed to GitHub)
+    file_snapshots: dict[str, str] = {}
+    for f in conflicted:
+        try:
+            file_snapshots[f] = gitops.show_file(local_sha, f, cwd=git_root)
+        except GitError:
+            pass
+
+    remote_sha = remote_shas[0] if remote_shas else gitops.get_remote_head(cwd=git_root)
+    resolution_id = uuid.uuid4().hex[:12]
+    resolution = ResolutionRecord(
+        id=resolution_id,
+        owner=config.owner,
+        repo=config.repo,
+        local_sha=local_sha,
+        remote_sha=remote_sha or "",
+        session_id=None,
+        status="pending",
+        started_at=datetime.now(timezone.utc).isoformat(),
+        conflicted_files=conflicted,
+        repo_path=str(git_root),
+        file_snapshots=file_snapshots,
+    )
+    try:
+        upload_resolution(config.owner, config.repo, resolution_id, resolution.to_dict())
+        click.echo(f"\nResolution record created: {resolution_id}")
+    except R2Error as e:
+        click.echo(f"Warning: Could not upload resolution record: {e}", err=True)
+
+    click.echo(f"\nLocal commit:  {local_sha[:8]}")
+    if remote_sha:
+        click.echo(f"Remote commit: {remote_sha[:8]}")
+    click.echo(f"\nOpen the UI to resolve:")
+    click.echo(f"  http://localhost:3000/merge/{resolution_id}?owner={config.owner}&repo={config.repo}")
+
+
+def _print_summary(
+    commit_hash: str,
+    branch: str | None,
+    files_changed: list[str],
+    raw_context: str | None,
+    context_source: str | None,
+    context_uploaded: bool,
+):
+    """Print commit summary."""
+    click.echo(f"\nCommit: {commit_hash[:8]}")
+    if branch:
+        click.echo(f"Branch: {branch}")
+    click.echo(f"Files:  {len(files_changed)} changed")
+    for f in files_changed:
+        click.echo(f"  {f}")
+    if raw_context:
+        size_kb = len(raw_context.encode("utf-8")) / 1024
+        click.echo(f"Context: {size_kb:.1f}KB {'uploaded' if context_uploaded else 'NOT uploaded'}")
+    elif context_source == "streamed_session":
+        click.echo(f"Context: streamed session {'(commit record uploaded)' if context_uploaded else '(commit record NOT uploaded)'}")
+    else:
+        click.echo("Context: none")
+
+
+# ---------- search helpers ----------
+
+
+def _call_search_api(query: str, owner: str, repo: str, limit: int = 10, timeout: int = 30) -> list[dict] | None:
+    """Call the semantic search API. Returns list of results, or None on failure."""
+    payload = json.dumps({"query": query, "owner": owner, "repo": repo, "limit": limit}).encode("utf-8")
+    req = urllib.request.Request(
+        "http://localhost:3000/api/vectorize/search",
+        data=payload,
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
+        return data.get("results", [])
+    except Exception:
+        return None
+
+
+# ---------- resolve helpers ----------
+
+
+def _build_resolve_search_query(local_record: dict, remote_record: dict | None) -> str:
+    """Build a search query from both commits' messages, goals, and subgoals."""
+    parts: list[str] = []
+
+    # Commit messages first (most concise signal)
+    local_msg = local_record.get("commit_message", "")
+    if local_msg:
+        parts.append(local_msg)
+    if remote_record:
+        remote_msg = remote_record.get("commit_message", "")
+        if remote_msg:
+            parts.append(remote_msg)
+
+    # Goals next (broader context)
+    local_goal = local_record.get("goal", "")
+    if local_goal:
+        parts.append(local_goal)
+    if remote_record:
+        remote_goal = remote_record.get("goal", "")
+        if remote_goal:
+            parts.append(remote_goal)
+
+    # Subgoals last (truncated — they're long markdown)
+    local_subgoal = local_record.get("subgoal", "")
+    if local_subgoal:
+        parts.append(local_subgoal[:200])
+    if remote_record:
+        remote_subgoal = remote_record.get("subgoal", "")
+        if remote_subgoal:
+            parts.append(remote_subgoal[:200])
+
+    query = " ".join(parts)
+    # Truncate to ~500 chars total
+    return query[:500]
+
+
+def _search_related_commits(
+    query: str,
+    owner: str,
+    repo: str,
+    exclude_shas: list[str],
+) -> list[dict]:
+    """Search for semantically related commits and fetch their full R2 records.
+
+    Returns list of dicts with keys: record, score, sha.
+    Returns [] on any failure — fully graceful.
+    """
+    from contexthub.core.r2 import get_commit_context
+
+    if not query.strip():
+        return []
+
+    results = _call_search_api(query, owner, repo, limit=10)
+    if not results:
+        click.echo("No related commits found (or search unavailable).")
+        return []
+
+    # Filter: score >= 0.65, exclude local/remote SHAs, cap at 5
+    exclude_set = {s for s in exclude_shas if s}
+    filtered = []
+    for r in results:
+        score = r.get("score", 0)
+        sha = r.get("sha", r.get("commit_hash", ""))
+        if score < 0.65:
+            continue
+        if sha in exclude_set or sha[:7] in {s[:7] for s in exclude_set}:
+            continue
+        filtered.append((sha, score))
+        if len(filtered) >= 5:
+            break
+
+    if not filtered:
+        click.echo("No related commits found (or search unavailable).")
+        return []
+
+    # Fetch full records from R2
+    related: list[dict] = []
+    for sha, score in filtered:
+        try:
+            record = get_commit_context(owner, repo, sha)
+            related.append({"record": record, "score": score, "sha": sha})
+        except Exception:
+            continue  # skip this commit, others still included
+
+    if related:
+        click.echo(f"Found {len(related)} related commit(s) for additional context.")
+    else:
+        click.echo("No related commits found (or search unavailable).")
+
+    return related
+
+
+# ---------- ch _hook (hidden) ----------
+
+
+@cli.group("_hook", hidden=True)
+def hook_group():
+    """Internal hook handlers (called by Claude Code hooks)."""
+    pass
+
+
+@hook_group.command("stream")
+def hook_stream():
+    """Handle a Stop event — upload transcript snapshot to R2."""
+    try:
+        raw = sys.stdin.read()
+        hook_input = json.loads(raw)
+    except (json.JSONDecodeError, ValueError):
+        return
+
+    try:
+        from contexthub.hooks import handle_stream
+        handle_stream(hook_input)
+    except Exception:
+        pass  # hooks must never produce output or crash
+
+
+@hook_group.command("finalize")
+def hook_finalize():
+    """Handle a SessionEnd event — upload final transcript + meta to R2."""
+    try:
+        raw = sys.stdin.read()
+        hook_input = json.loads(raw)
+    except (json.JSONDecodeError, ValueError):
+        return
+
+    try:
+        from contexthub.hooks import handle_finalize
+        handle_finalize(hook_input)
+    except Exception:
+        pass  # hooks must never produce output or crash