contexthub-cli 0.1.0

package/contexthub/core/r2.py

@@ -0,0 +1,221 @@
+"""Cloudflare R2 upload client (S3-compatible via boto3)."""
+
+from __future__ import annotations
+
+import json
+import os
+
+import boto3
+from botocore.exceptions import ClientError
+
+BUCKET_NAME = "ch-context"
+
+REQUIRED_ENV_VARS = ("R2_ACCOUNT_ID", "R2_ACCESS_KEY_ID", "R2_SECRET_ACCESS_KEY")
+
+
+class R2Error(Exception):
+    pass
+
+
+def _get_client():
+    # Fall back to CLOUDFLARE_ACCOUNT_ID if R2_ACCOUNT_ID isn't set
+    account_id = os.environ.get("R2_ACCOUNT_ID") or os.environ.get("CLOUDFLARE_ACCOUNT_ID")
+    access_key = os.environ.get("R2_ACCESS_KEY_ID")
+    secret_key = os.environ.get("R2_SECRET_ACCESS_KEY")
+
+    if not account_id or not access_key or not secret_key:
+        raise R2Error(
+            "R2 credentials not configured. Set R2_ACCOUNT_ID (or CLOUDFLARE_ACCOUNT_ID), "
+            "R2_ACCESS_KEY_ID, and R2_SECRET_ACCESS_KEY."
+        )
+    endpoint_url = f"https://{account_id}.r2.cloudflarestorage.com"
+
+    return boto3.client(
+        "s3",
+        endpoint_url=endpoint_url,
+        aws_access_key_id=access_key,
+        aws_secret_access_key=secret_key,
+        region_name="auto",
+    )
+
+
+def upload_context(owner: str, repo: str, commit_hash: str, payload: dict) -> None:
+    """Upload a commit context JSON payload to R2.
+
+    Object key: {owner}/{repo}/commits/{commit_hash}.json
+    """
+    client = _get_client()
+    key = f"{owner}/{repo}/commits/{commit_hash}.json"
+    body = json.dumps(payload, indent=2)
+
+    try:
+        client.put_object(
+            Bucket=BUCKET_NAME,
+            Key=key,
+            Body=body.encode("utf-8"),
+            ContentType="application/json",
+        )
+    except ClientError as e:
+        raise R2Error(f"Failed to upload context: {e}")
+
+
+def upload_session_transcript(
+    owner: str, repo: str, session_id: str, payload: dict
+) -> None:
+    """Upload a session transcript snapshot to R2.
+
+    Object key: {owner}/{repo}/sessions/{session_id}/transcript.json
+    Overwrites on each call (latest state).
+    """
+    client = _get_client()
+    key = f"{owner}/{repo}/sessions/{session_id}/transcript.json"
+    body = json.dumps(payload, indent=2)
+
+    try:
+        client.put_object(
+            Bucket=BUCKET_NAME,
+            Key=key,
+            Body=body.encode("utf-8"),
+            ContentType="application/json",
+        )
+    except ClientError as e:
+        raise R2Error(f"Failed to upload session transcript: {e}")
+
+
+def upload_session_meta(
+    owner: str, repo: str, session_id: str, payload: dict
+) -> None:
+    """Upload session metadata to R2.
+
+    Object key: {owner}/{repo}/sessions/{session_id}/meta.json
+    Written once at session end.
+    """
+    client = _get_client()
+    key = f"{owner}/{repo}/sessions/{session_id}/meta.json"
+    body = json.dumps(payload, indent=2)
+
+    try:
+        client.put_object(
+            Bucket=BUCKET_NAME,
+            Key=key,
+            Body=body.encode("utf-8"),
+            ContentType="application/json",
+        )
+    except ClientError as e:
+        raise R2Error(f"Failed to upload session meta: {e}")
+
+
+def get_commit_context(owner: str, repo: str, commit_hash: str) -> dict:
+    """Read a commit context record from R2.
+
+    Tries full hash first, then prefix match.
+    Returns the parsed JSON dict (direct read, nothing written to disk).
+    """
+    client = _get_client()
+
+    # Try exact key first
+    key = f"{owner}/{repo}/commits/{commit_hash}.json"
+    try:
+        resp = client.get_object(Bucket=BUCKET_NAME, Key=key)
+        return json.loads(resp["Body"].read().decode("utf-8"))
+    except ClientError:
+        pass
+
+    # Try prefix match (short SHA)
+    prefix = f"{owner}/{repo}/commits/{commit_hash}"
+    try:
+        resp = client.list_objects_v2(Bucket=BUCKET_NAME, Prefix=prefix, MaxKeys=10)
+        contents = resp.get("Contents", [])
+        # Filter to .json files (not directories)
+        matches = [c for c in contents if c["Key"].endswith(".json")]
+        if len(matches) == 1:
+            resp = client.get_object(Bucket=BUCKET_NAME, Key=matches[0]["Key"])
+            return json.loads(resp["Body"].read().decode("utf-8"))
+        elif len(matches) > 1:
+            keys = [c["Key"].split("/")[-1].replace(".json", "") for c in matches]
+            raise R2Error(f"Ambiguous SHA prefix. Matches: {', '.join(keys)}")
+    except ClientError as e:
+        raise R2Error(f"Failed to download context: {e}")
+
+    raise R2Error(f"No commit context found for {commit_hash}")
+
+
+def upload_resolution(owner: str, repo: str, resolution_id: str, payload: dict) -> None:
+    """Upload a resolution record to R2.
+
+    Object key: {owner}/{repo}/resolutions/{resolution_id}.json
+    """
+    client = _get_client()
+    key = f"{owner}/{repo}/resolutions/{resolution_id}.json"
+    body = json.dumps(payload, indent=2)
+
+    try:
+        client.put_object(
+            Bucket=BUCKET_NAME,
+            Key=key,
+            Body=body.encode("utf-8"),
+            ContentType="application/json",
+        )
+    except ClientError as e:
+        raise R2Error(f"Failed to upload resolution: {e}")
+
+
+def update_resolution(owner: str, repo: str, resolution_id: str, updates: dict) -> dict:
+    """Read-modify-write a resolution record in R2. Returns the updated record."""
+    client = _get_client()
+    key = f"{owner}/{repo}/resolutions/{resolution_id}.json"
+
+    try:
+        resp = client.get_object(Bucket=BUCKET_NAME, Key=key)
+        record = json.loads(resp["Body"].read().decode("utf-8"))
+    except ClientError as e:
+        raise R2Error(f"Failed to read resolution for update: {e}")
+
+    record.update(updates)
+    body = json.dumps(record, indent=2)
+
+    try:
+        client.put_object(
+            Bucket=BUCKET_NAME,
+            Key=key,
+            Body=body.encode("utf-8"),
+            ContentType="application/json",
+        )
+    except ClientError as e:
+        raise R2Error(f"Failed to update resolution: {e}")
+
+    return record
+
+
+def get_resolution(owner: str, repo: str, resolution_id: str) -> dict:
+    """Read a resolution record from R2."""
+    client = _get_client()
+    key = f"{owner}/{repo}/resolutions/{resolution_id}.json"
+
+    try:
+        resp = client.get_object(Bucket=BUCKET_NAME, Key=key)
+        return json.loads(resp["Body"].read().decode("utf-8"))
+    except ClientError as e:
+        raise R2Error(f"Failed to read resolution: {e}")
+
+
+def list_resolutions(owner: str, repo: str) -> list[dict]:
+    """List all resolution records for a repo. Returns parsed JSON dicts."""
+    client = _get_client()
+    prefix = f"{owner}/{repo}/resolutions/"
+
+    try:
+        resp = client.list_objects_v2(Bucket=BUCKET_NAME, Prefix=prefix)
+        contents = resp.get("Contents", [])
+    except ClientError as e:
+        raise R2Error(f"Failed to list resolutions: {e}")
+
+    results = []
+    for obj in contents:
+        if obj["Key"].endswith(".json"):
+            try:
+                resp = client.get_object(Bucket=BUCKET_NAME, Key=obj["Key"])
+                results.append(json.loads(resp["Body"].read().decode("utf-8")))
+            except (ClientError, json.JSONDecodeError):
+                pass
+    return results

package/contexthub/hooks.py

@@ -0,0 +1,154 @@
+"""Hook handlers for Claude Code Stop/SessionEnd events.
+
+Called via `ch _hook stream` and `ch _hook finalize`.
+All exceptions are caught silently — hooks must never crash the agent.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+from contexthub.core.context import parse_session_jsonl
+from contexthub.core.models import RepoConfig
+from contexthub.core.r2 import upload_session_meta, upload_session_transcript, update_resolution
+
+
+def find_config_from_cwd(cwd: str) -> tuple[Path, RepoConfig] | None:
+    """Walk up from cwd to find .ch/config.json and return (git_root, config)."""
+    current = Path(cwd).resolve()
+    while True:
+        config_path = current / ".ch" / "config.json"
+        if config_path.is_file():
+            try:
+                data = json.loads(config_path.read_text(encoding="utf-8"))
+                config = RepoConfig.from_dict(data)
+                return current, config
+            except (json.JSONDecodeError, KeyError):
+                return None
+        parent = current.parent
+        if parent == current:
+            return None
+        current = parent
+
+
+def handle_stream(hook_input: dict) -> None:
+    """Handle a Stop event: parse the transcript and upload to R2.
+
+    hook_input keys: session_id, transcript_path, cwd
+    """
+    session_id = hook_input.get("session_id")
+    transcript_path = hook_input.get("transcript_path")
+    cwd = hook_input.get("cwd")
+
+    if not session_id or not transcript_path or not cwd:
+        return
+
+    result = find_config_from_cwd(cwd)
+    if result is None:
+        return
+    git_root, config = result
+
+    path = Path(transcript_path)
+    if not path.is_file():
+        return
+
+    transcript = parse_session_jsonl(path)
+
+    from contexthub.core import git as gitops
+
+    try:
+        branch = gitops.get_current_branch(cwd=git_root)
+    except Exception:
+        branch = None
+
+    payload = {
+        "session_id": session_id,
+        "owner": config.owner,
+        "repo": config.repo,
+        "branch": branch,
+        "updated_at": datetime.now(timezone.utc).isoformat(),
+        "status": "active",
+        "transcript": transcript,
+    }
+
+    upload_session_transcript(config.owner, config.repo, session_id, payload)
+
+    # Link session_id to active resolution (write locally for mark-resolved to pick up)
+    active_res_file = git_root / ".ch" / "active_resolution"
+    if active_res_file.is_file():
+        content = active_res_file.read_text(encoding="utf-8").strip()
+        # Only write session_id if not already linked (file has no newline yet)
+        if "\n" not in content:
+            active_res_file.write_text(f"{content}\n{session_id}", encoding="utf-8")
+
+
+def handle_finalize(hook_input: dict) -> None:
+    """Handle a SessionEnd event: final transcript upload + session metadata.
+
+    hook_input keys: session_id, transcript_path, cwd
+    """
+    session_id = hook_input.get("session_id")
+    transcript_path = hook_input.get("transcript_path")
+    cwd = hook_input.get("cwd")
+
+    if not session_id or not transcript_path or not cwd:
+        return
+
+    result = find_config_from_cwd(cwd)
+    if result is None:
+        return
+    git_root, config = result
+
+    path = Path(transcript_path)
+    if not path.is_file():
+        return
+
+    transcript = parse_session_jsonl(path)
+
+    from contexthub.core import git as gitops
+
+    try:
+        branch = gitops.get_current_branch(cwd=git_root)
+    except Exception:
+        branch = None
+
+    # Upload final transcript snapshot
+    transcript_payload = {
+        "session_id": session_id,
+        "owner": config.owner,
+        "repo": config.repo,
+        "branch": branch,
+        "updated_at": datetime.now(timezone.utc).isoformat(),
+        "status": "completed",
+        "transcript": transcript,
+    }
+    upload_session_transcript(
+        config.owner, config.repo, session_id, transcript_payload
+    )
+
+    # Upload session metadata
+    meta_payload = {
+        "session_id": session_id,
+        "owner": config.owner,
+        "repo": config.repo,
+        "branch": branch,
+        "ended_at": datetime.now(timezone.utc).isoformat(),
+        "transcript_size_bytes": len(transcript.encode("utf-8")),
+    }
+    upload_session_meta(config.owner, config.repo, session_id, meta_payload)
+
+    # If this was a resolver session, link the session_id to the resolution
+    active_res_file = git_root / ".ch" / "active_resolution"
+    if active_res_file.is_file():
+        content = active_res_file.read_text(encoding="utf-8").strip()
+        resolution_id = content.split("\n")[0]
+        if resolution_id:
+            try:
+                update_resolution(config.owner, config.repo, resolution_id, {
+                    "session_id": session_id,
+                })
+            except Exception:
+                pass
+            active_res_file.unlink(missing_ok=True)

package/install.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# postinstall script — creates a venv and installs Python dependencies
+set -euo pipefail
+
+PACKAGE_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# ── Find Python 3.10+ ───────────────────────────────────────────────
+PYTHON=""
+for candidate in python3.13 python3.12 python3.11 python3.10 python3; do
+  if command -v "$candidate" &>/dev/null; then
+    # Verify version >= 3.10
+    version=$("$candidate" -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')" 2>/dev/null || true)
+    major="${version%%.*}"
+    minor="${version#*.}"
+    if [ "$major" = "3" ] && [ "$minor" -ge 10 ] 2>/dev/null; then
+      PYTHON="$(command -v "$candidate")"
+      break
+    fi
+  fi
+done
+
+if [ -z "$PYTHON" ]; then
+  echo "error: Python 3.10+ is required but not found." >&2
+  echo "Install Python from https://python.org and try again." >&2
+  exit 1
+fi
+
+echo "contexthub: using $PYTHON ($("$PYTHON" --version 2>&1))"
+
+# ── Check that venv module is available ──────────────────────────────
+if ! "$PYTHON" -m venv --help &>/dev/null; then
+  echo "error: Python venv module not available." >&2
+  echo "On Debian/Ubuntu, install it with:  sudo apt install python3-venv" >&2
+  exit 1
+fi
+
+# ── Create venv and install deps ─────────────────────────────────────
+echo "contexthub: creating venv..."
+"$PYTHON" -m venv "$PACKAGE_DIR/.venv"
+
+echo "contexthub: installing dependencies..."
+"$PACKAGE_DIR/.venv/bin/pip" install --quiet --disable-pip-version-check -r "$PACKAGE_DIR/requirements.txt"
+
+echo "contexthub: installed successfully."

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "contexthub-cli",
+  "version": "0.1.0",
+  "description": "ContextHub — intent-first version control on top of git",
+  "bin": {
+    "ch": "./bin/ch"
+  },
+  "files": [
+    "bin/",
+    "contexthub/**/*.py",
+    "install.sh",
+    "requirements.txt"
+  ],
+  "scripts": {
+    "postinstall": "bash install.sh"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "license": "MIT"
+}

package/requirements.txt

@@ -0,0 +1,2 @@
+click>=8.0
+boto3>=1.28