64 lines
4.9 KiB
Markdown
64 lines
4.9 KiB
Markdown
<!-- .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.
|