Usages:
  conventions: .goga/usages/conventions.md

Annotations: |
  The developer must apply the `conventions` practice during development and testing.
  Error output is routed through sys.stderr (click is not used).
  The module uses shutil, subprocess, tempfile, pathlib from the Python standard library only.

---

"sync(source: str, token: str | None = None, branch: str | None = None) -> exit_code:int":
  location: sync.py
  annotations: |
    Synchronization of .usages/ directories from a local path or git repository.

    `source`: path to the source directory or URL of a git repository
    `token`: authentication token for HTTPS git repositories
    `branch`: branch or tag to check out during cloning
    `exit_code`: 0 on success, 1 on failure

    Dispatch:
    - http://, https://, git@, ssh:// → git-mode
    - otherwise → local mode

    Algorithm (local mode):
    1. Resolve `source` to an absolute path via Path.resolve()
    2. Validate: path exists, is a directory, contains .usages/
    3. Derive dependency name from the path basename
    4. Execute synchronization

    Algorithm (git-mode):
    1. Extract dependency name from the URL (last segment without .git)
    2. Prepare the clone URL (inject `token` for HTTPS)
    3. Clone into a temporary directory via tempfile.mkdtemp()
    4. Validate: contains .usages/
    5. Run synchronization
    6. In the finally block — delete the temporary directory via shutil.rmtree()

    Synchronization (shared step):
    1. Target directory: .goga/usages/deps/<name>/
    2. Remove target directory if it exists (full re-sync)
    3. Recursively discover all .usages/ in the source tree
    4. For each discovered .usages/:
       - Compute relative path from source root to .usages/ parent
       - Create directory structure at .goga/usages/deps/<name>/<relative>/.usages/
       - Copy .usages/ contents (files and subdirectories)
    5. Report: dependency name, count of synchronized .usages/ directories

    Requirements:
    - Use shutil.copytree for directory copying
    - Use shutil.rmtree for directory removal
    - Invoke git clone via subprocess.run with capture_output=True, check=True
    - Allocate temporary directories via tempfile.mkdtemp()
    - Delete temporary directories in a finally block
    - Set GIT_TERMINAL_PROMPT=0 in env to suppress interactive prompts
    - Write I/O and git errors to stderr
    - Produce minimal output: dependency name, source, count of synchronized usages

---

Author: Mikhail Trifonov
CreatedAt: 15/05/26

Description: |
  Manifest describing synchronization of .usages/ from a local path or git repository
