<!-- .github/copilot-instructions.md for CodeBridge -->
# Copilot / AI Agent Instructions — CodeBridge

Purpose: give AI coding agents the minimal, actionable knowledge to be productive here.

- **Big picture**: CodeBridge is a small Python/Tkinter desktop tool that computes differences between two directory trees, produces a ZIP "export package" with changed files plus a JSON manifest, and can apply such a package to a destination tree. UI (Tkinter) and core logic are separated under `codebridge/gui` and `codebridge/core`.

- **Entrypoint / Run**: run from repository root with:

```bash
python -m codebridge
```

- **Key modules & responsibilities**:
  - `codebridge/__main__.py`: app entry (creates `tk.Tk()` and `MainWindow`).
  - `codebridge/core/comparer.py`: `CodeComparer` — directory walking, ignore patterns, SHA-256 hashing, returns `(added, modified, deleted)` lists.
  - `codebridge/core/sync_manager.py`: `SyncManager` — creates ZIP export packages (writes `bridge_manifest.json`), and applies packages (handles deletions then extracts files).
  - `codebridge/gui/main_window.py`: `MainWindow` — path selection, drives comparisons using `CodeComparer`, and calls `SyncManager` for export/import. UI calls are synchronous (blocking).
  - `codebridge/gui/diff_viewer.py`: `DiffViewer` — side-by-side text diff and a "copy source to destination" action.
  - `codebridge/gui/commit_dialog.py`: `CommitDialog` — modal dialog that returns the commit message required for exports.

- **Data contract / manifest**: exported ZIP contains `bridge_manifest.json` with keys: `timestamp`, `commit_message`, and `changes` with `added`, `modified`, `deleted` lists. Example (used in code):

```json
{
  "timestamp": "2023-10-27T10:00:00",
  "commit_message": "...",
  "changes": {"added": [], "modified": [], "deleted": []}
}
```

- **Project-specific conventions** (agents should follow these precisely):
  - Code style: PEP8 is expected and naming should be English-only (variable/function/class names and comments).
  - GUI and core separation: changes that alter logic should go in `codebridge/core`; UI-only changes in `codebridge/gui`.
  - Long-running I/O: the UI currently performs I/O on the main thread. If you add heavy operations, prefer to wire them into a background thread and keep the modal/confirmation behavior intact.
  - Export flow: `MainWindow` requires a `CommitDialog` message for exports; do not remove the commit message requirement.
  - Import safety: imports prompt the user for confirmation in the UI. Preserve this confirmation when automating apply flows.

- **Patterns & pitfalls discovered in code**:
  - `CodeComparer.get_relative_files` returns a map of relative path -> full path; comparing uses `compute_hash` for both sides to detect modifications. Avoid changing relative-path semantics.
  - `SyncManager.create_export_package` writes only files listed in `added` and `modified` to the ZIP; deleted files are listed in the manifest but not packaged.
  - `SyncManager.apply_package` first removes `deleted` files from destination, then extracts packaged files. Do not change the ordering without tests.
  - GUI treeview tags: `added`, `modified`, `deleted` are used for coloring in `MainWindow._setup_treeview` — keep these exact tags when manipulating the tree.

- **How to make small changes safely (examples)**
  - Add a new ignore pattern: update `CodeComparer.IGNORE_PATTERNS` in `codebridge/core/comparer.py`.
  - Change manifest fields: update `SyncManager.create_export_package` and `apply_package` together and preserve backward compatibility (older manifests may be present).
  - Add non-blocking export: implement a background thread that calls `SyncManager.create_export_package` and update `MainWindow` to show progress (status bar TODO noted in design doc).

- **Testing & dev workflows (what exists / what's missing)**
  - There are no unit tests in the repository. Agents should add focused tests when changing core behaviors (compare/hash, manifest creation, apply ordering).
  - Use the interactive UI to validate flows quickly: run `python -m codebridge`, select source/destination folders, use Compare → Export → Import.

- **External dependencies & environment**
  - Uses Python standard library only (tkinter, zipfile, hashlib, json, shutil, difflib). Target Python 3.11+ (development was run with Python 3.13 in the project environment). Ensure `tkinter` is available on the host.

- **When editing code, prefer small, isolated PRs that**:
  - Modify `core/` with unit tests covering hashing and manifest details.
  - Preserve current UX: modal commit dialog and import confirmation.
  - Keep path semantics (relative paths in manifest) unchanged unless migrating with compatibility code.

---
If any of the above references are unclear or you want me to expand a section (examples, suggested tests, or an automatic background-export patch), tell me which part to expand and I'll update this file.