SXXXXXXX_CodeBridge/.github/copilot-instructions.md

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:

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):

{
  "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.