`magpie-vcs`

Capability: contract:source-control

Kind: implementation

Vendor: Git

Runnable implementation of the source-control (VCS) capability documented in tools/github/source-control.md. It extracts the abstraction the dev-loop skills assume — branch, stage, commit, diff, log, fetch, push, working-tree reset — out of inline git calls into one backend-dispatching CLI.

A skill (or a person) runs the abstract operation:

uv run --project tools/vcs magpie-vcs -C <upstream> diff --base main
uv run --project tools/vcs magpie-vcs -C <upstream> log --grep ISSUE-123

The active backend is detected from the working copy (or forced with --backend / $MAGPIE_VCS), so the same command works whatever VCS the project enables under Tools enabled → Source control.

Prerequisites

Runtime: Python 3.11+ run via uv; stdlib-only (no runtime dependencies). The dev group pulls pytest, ruff, mypy.
CLIs: Depends on the active backend — the tool shells out to the underlying VCS binary. git for the complete backend; hg / svn are detected but their bindings are not yet implemented.
Credentials / auth: None of its own; write operations (fetch, push) inherit whatever auth the underlying VCS/remote needs.
Network: Local for read and local-write operations; fetch / push reach the project's remote (e.g. GitHub) over the network.

Configuration

The active backend is detected from the working copy or forced with --backend / $MAGPIE_VCS. Skills get the checkout path from <project-config>/user.md (or the resolved user config) and the expected source-control backend from <project-config>/project.md Tools enabled entries. Backend-specific adopter knobs belong in the relevant *-config.md file rather than in this tool.

Why

Before this tool the skills hard-coded git … inline. PR #609 added the capability contract (source-control.md) and pointed each git-using skill at it; this tool is the implementation of that contract — the single place a non-Git VCS bridge plugs in, instead of editing every skill.

The abstraction

VCSBackend is the abstract interface; each operation maps to the What the skills require table in source-control.md:

Operation	CLI	Read/Write
Detect backend	`detect`, `backends`, `root`	read
Working-tree status	`status`, `clean`	read
Current branch	`branch`	read
Show changes	`diff [--base REF] [--cached] [paths…]`	read
History read	`log [-n N] [--grep P] [--author A] [--since S] [paths…]`	read
Create line of work	`new-branch <name>`	write
Switch ref	`switch <ref>`	write
Stage	`stage <paths…>`	write
Commit	`commit -m <msg>`	write
Sync from forge	`fetch [remote] [ref]`	write
Publish	`push [-u] <remote> <ref>`	write
Reset working copy	`reset-worktree`	write

Write operations stay gated on explicit user confirmation in the calling skill, exactly as the tracker write paths are — the tool does not add its own prompt.

Backends

Backend	Status	Notes
`git`	complete	GitHub's native VCS; the default binding
`hg` (Mercurial)	complete	Mercurial VCS support
`svn` (Subversion)	extension point	detected; centralized model (`distributed = False`) → #602

Detection is real for every backend (so magpie-vcs detect reports the working copy's VCS correctly); the non-Git/non-Hg backends raise an actionable VCSError naming their tracking issue until the full binding lands.

Adding a backend

A VCS bridge (e.g. #602 Subversion) implements the full binding by replacing that backend's _UnimplementedBackend base with a concrete VCSBackend subclass — detect(), the read operations, the write

operations — and nothing else changes: detection, dispatch, the CLI, and every skill that calls magpie-vcs pick it up automatically.

How to use

# run the tests
uv run --project tools/vcs --group dev pytest

# in a skill / shell, against an upstream checkout
uv run --project tools/vcs magpie-vcs -C ~/code/foo detect
uv run --project tools/vcs magpie-vcs -C ~/code/foo status

Exit codes: 0 success, 1 for clean when the tree is dirty, 2 for any VCSError (unknown/unsupported backend, failed command).