# Context Bridge

Context Bridge is a local-first pipeline between a repository and external LLMs or MCP clients.
It is intentionally narrow: it packs bounded repository context, ranks files and symbols with a
tree-sitter/PageRank graph, applies structured SemPatch YAML through AST matching, and writes
changes through a transaction layer with verification hooks.

It is not a full coding agent. It does not plan large refactors end to end. It focuses on the
I/O boundary: what leaves the repo, and what comes back in.

## What It Does

- pack repository context with manifests, byte limits, secret scanning, and optional visual snapshots,
- build repository maps from tree-sitter tags and reference scores,
- select task-relevant files within a token budget,
- apply SemPatch YAML with transactional prepare/commit semantics,
- expose the same primitives through CLI, MCP, and an agent skill,
- pair with a browser companion so web LLMs can operate on local code without copy/paste loops.

## Install

```bash
python -m pip install -e .
python -m pip install -e ".[mcp,visual]"
```

## Quick Start

Generate a repository map:

```bash
context-bridge map . --query "fix login token refresh" -o repo-map.md
```

Select a bounded bundle:

```bash
context-bridge select . --task "fix login token refresh" -o selected-context.md
```

Create a staged plan:

```bash
context-bridge playbook . --task "fix login token refresh" -o playbook.md
```

Apply a SemPatch response:

```bash
context-bridge apply answer.md --root .
context-bridge apply answer.md --root . --write
```

Migrate a legacy patch file once:

```bash
context-bridge migrate-old-patches legacy-answer.md -o answer.sempatch.md
```

## SemPatch

SemPatch is the required patch format. Each block is explicit YAML:

```yaml
--- sempatch ---
file: src/example.py
language: python
op: replace
selector:
  rule:
    pattern: |
      def hello():
        $$$BODY
replacement: |
  def hello():
      return "updated"
--- end sempatch ---
```

Use `op: create_file` with `content:` for new files. The tool validates the structure, matches
exactly one AST node, and runs inside a transaction when writing.

## MCP

```bash
context-bridge mcp
```

The MCP server exposes `pack_context`, `repo_map`, `context_playbook`, `select_context_for_task`,
`scan_text_for_secrets`, `inspect_sempatches`, `apply_patches`, and `sempatch_schema`.

## Browser Companion

The browser companion follows the same shape as existing Chrome/MCP bridge projects:
prefer Chrome Native Messaging for the local host boundary, then fall back to the
loopback HTTP bridge when native host registration is not available.

```bash
context-bridge ext native-manifest --extension-id <installed-extension-id> --output native-host.json
context-bridge ext serve
```

The `extension/` directory is a Chrome MV3 companion. It calls the native host
`com.context_bridge.native_host` first and uses `context-bridge ext serve` only as a fallback.

## Verification

Configure verify hooks in `.context-bridge.toml`:

```toml
[verify]
typescript = ["pnpm", "exec", "tsc", "--noEmit"]
python = ["python", "-m", "ruff", "check", "--quiet"]
rust = ["cargo", "check", "--quiet"]
```

`apply --write` runs verification by default. Use `--no-verify` only when you knowingly want
to skip the hooks.

## Visual Snapshots

`bundle --visual` does not ship a custom component renderer. It reuses an existing
Storybook, Ladle, or Histoire setup in the target project and captures it with Playwright:

```toml
[visual]
explorer = "storybook"
command = ["npm", "run", "storybook", "--", "--ci", "--port", "6006"]
url = "http://127.0.0.1:6006"
timeout_seconds = 45
```

If no story exists for a component, Context Bridge reports that clearly instead of emitting a fake
snapshot.

## Development

```bash
python -m unittest discover -s tests -v
python -m compileall -q src tests
```