feat: add 'uvbox git' subcommand for git repository sources (#19)

[hasansezertasan]

Closes #19.

Summary

Adds a new uvbox git <git-spec> subcommand alongside the existing pypi and wheel source types. The git spec is passed through to uv tool install --from verbatim, so any form uv accepts works (@main, @v1.0.0, @<commit>, ssh://, etc.).

uvbox git git+https://github.com/org/repo
uvbox git git+https://github.com/org/repo@v1.0.0
uvbox git git+ssh://git@github.com/org/private-repo

Implements the approach @Coruscant11 chose in this comment: subcommand with the git spec as a positional CLI argument, no changes to the uvbox.toml schema.

When the outer version check decides to install/update, uvToolInstallGit runs uv tool install --from <spec> <name> --upgrade. auto-update = true with no [package.version] set re-enters that path on every run (the version compare treats the unset case as always-stale), delivering the pycrucible delete_after_run-equivalent behavior the issue requested. If a user sets [package.version].static on a git build, a user-visible warning is logged because the git ref is the source of truth.

Design notes

• Additive only. The pypi and wheel leaf install functions are untouched. A regression test in box/config_identifier_test.go locks in a byte-stable golden hash for ComputeIdentifier to guarantee existing binaries find the same XDG dir.
• Distinct identifier per git source. The git spec participates in ComputeIdentifier (only when set), so binaries built from git+url@main and git+url@v1.0.0 get separate isolated install dirs. No cross-contamination with pypi-built binaries of the same package.
• Source embedding via file, not ldflag. See "Pre-existing bug discovered" below.
• Validation: must start with git+, the URL after the prefix must parse, the scheme must be one of http/https/ssh/file, and non-file schemes must have a host. Semantic ref resolution (branch/tag/commit existence) is still delegated to uv on first run.
• Git and embedded wheels are mutually exclusive. Enforced both at build time (boxer preRun) and runtime (pure selectInstallMethod helper in box/box_package.go returns an error when both GIT_SOURCE and INSTALL_WHEELS are set).

Pre-existing bug discovered (and worked around)

The original spec proposed embedding the git source via -ldflags "-X main.GIT_SOURCE=...". The smoke test surfaced that this does not work because of a pre-existing bug introduced in #14 (commit f19680f, "fix: Use environment variables for ldflags"):

The Go toolchain splits GOFLAGS on whitespace. Any ldflag string containing -X main.foo=bar is split across flag boundaries, and the toolchain rejects -X as an unknown top-level flag with go: parsing $GOFLAGS: unknown flag -X.

This silently broke the uvbox wheel path in main since #14 was merged — it sets -X main.INSTALL_WHEELS=yes, which fails the same way. No test exercises wheel mode end-to-end so nobody noticed. Reproduction:

GOFLAGS='-ldflags=-s -w -X main.INSTALL_WHEELS=yes' go build -o hello .
# go: parsing $GOFLAGS: unknown flag -X

This PR does not fix the wheel bug — touching it requires re-validating the original Windows-via-uvx fix from #14 on Windows, which is out of scope here. The wheel path remains broken in main and should be addressed in a separate PR.

For git, this PR sidesteps GOFLAGS entirely by embedding the source in a small file (box/git_source.txt) read at compile time via //go:embed. boxer's writeGitSourceFile writes the spec into this file before go build. Empty file = pypi/wheel build, non-empty = git build. Same end result, different transport.

Files

Runtime (box/):

• box/box_package_git.go (new) — GIT_SOURCE (loaded from embedded git_source.txt), uvToolInstallGit (accepts packageVersion for signature parity, warns and drops it since the git ref is authoritative; captures uv stdout into the returned error on failure), buildUvToolInstallFromArgs pure helper
• box/box_package.go — pure selectInstallMethod(gitSource, installWheels) helper dispatches to pypi/wheels/git; rejects the git+wheels combination at runtime. InstallPackage now propagates downloadTemporaryFile errors instead of swallowing them at Debug level (pre-existing silent failure fixed while on the hot path)
• box/config.go — ComputeIdentifier conditionally appends GIT_SOURCE (no-op when empty)
• box/generate.go — adds empty git_source.txt placeholder generation, mirroring the existing wheels/placeholder pattern
• box/config_identifier_test.go (new) — golden-hash regression test (with regeneration recipe) + git distinction tests
• box/box_package_git_test.go (new) — pure-helper command-shape tests
• box/box_package_test.go (new) — TestSelectInstallMethod dispatch matrix (pypi/wheels/git × default/conflict)

Build-time (boxer/):

• boxer/git.go (new) — buildGoBuildLdflags pure helper (without git, since git uses file embed), validateGitSource (URL-parsing, scheme whitelist, host check), writeGitSourceFile
• boxer/main.go — new gitCmd cobra command, GitSource CLI var, validateGitSourceFlag in preRun (also enforces mutual exclusion with WheelsToEmbed and prints helpful hints on invalid input), writeGitSourceFile call in insertFilesIntoBoxRepository
• boxer/git_test.go (new) — ldflag regression tests for pypi/wheel, writeGitSourceFile tests, validateGitSource positive cases, TestValidateGitSource_RejectsMalformed (scheme typos, prefix-only, missing host), TestValidateGitSourceFlag_EmptyIsNoop (guards the "pypi/wheel builds unaffected" contract)

Docs:

• README.md — feature bullet updated, new "Build from a Git Repository" section, behavior of [package.version] for git builds, private repo auth note, runtime git requirement
• examples/git/simple-app.toml (new) — minimal runnable example using VaasuDevanS/cowsay-python
• .gitignore — adds box/git_source.txt

Test Plan

• Full box test suite passes (go test ./...) including the ComputeIdentifier golden-hash regression guard and the new selectInstallMethod dispatch matrix
• Full boxer test suite passes including ldflag regression guards for the existing pypi/wheel paths and the new validateGitSource URL-parsing cases
• go vet ./... clean in both modules
• Manual smoke test: uvbox git git+https://github.com/VaasuDevanS/cowsay-python --darwin --arm builds, the resulting binary runs end-to-end (./cowsay -t "hi" prints the cow), self update reports "Already up-to-date", self path shows a git-distinct identifier
• Regression: uvbox pypi still works, produces a different identifier hash (separate XDG dir from the git build of the same package)

Reviewers can reproduce the smoke test using the committed example config:

# Build boxer from source
cd boxer && go generate && go build -o /tmp/uvbox . && cd ..

# Build a cowsay binary straight from the git repo using the example config
/tmp/uvbox git git+https://github.com/VaasuDevanS/cowsay-python \
    --config examples/git/simple-app.toml \
    --darwin --arm   # adjust --darwin/--linux/--windows and --arm/--amd to your host

# Run the produced artifact
cd dist && tar xzf cowsay-*.tar.gz && ./cowsay -t "git works!"

See examples/git/simple-app.toml for the config, including the commented-out [package.version] auto-update = true block that flips the binary into "always re-resolve the git ref on every run" mode.

Update — review round 1 (commit a38fe58)

Addressed findings from a multi-agent PR review pass. All changes are additive to the original design:

• Propagate constraints-file download error (pre-existing silent failure in InstallPackage, now on the git hot path)
• Reject GIT_SOURCE + INSTALL_WHEELS conflict at build time (boxer preRun) and runtime (selectInstallMethod)
• Warn when [package.version] is set on a git build — uvToolInstallGit logs logger.Warn instead of silently ignoring
• Capture uv stdout into error messages on git install failure, so resolver/auth output isn't discarded
• Deepen validateGitSource with net/url parsing — reject scheme typos, unsupported schemes, and missing hosts at build time instead of on end-user machines
• New tests: box/box_package_test.go (dispatch matrix) and expanded boxer/git_test.go (malformed-spec cases + empty-flag no-op guard)
• Doc reconciliation: README [package.version] section, golden-hash regeneration recipe, trimmed duplicated inline comments

🤖 Generated with Claude Code

[Coruscant11]

Gonna have a look tomorrow!

[hasansezertasan]

Gonna have a look tomorrow!

Don't hurry, it's still in draft 🤓.

[hasansezertasan]

I pushed quickly today to get this PR ready. I'm not actively working with Go day-to-day — I put this together by reading through the surrounding code and iterating with an AI agent. There may be edge cases I missed, so I'd really appreciate a careful review. Thanks again!

@Coruscant11

[Coruscant11]

I am starting to review. First thank for this PR, looking at it, I am just currently working on improving CI and tests, and fix the wheels issue your PR mentionned (really appreciate the catch).

Goal is to fix the issues that are bothering your PR so that we can have a good base.

[hasansezertasan]

I am starting to review. First thank for this PR, looking at it, I am just currently working on improving CI and tests, and fix the wheels issue your PR mentionned (really appreciate the catch).

Goal is to fix the issues that are bothering your PR so that we can have a good base.

Thanks for the review. I addressed your comments. Can you take a look at it again 🤓?

[Coruscant11]

Remains only to fix the wheel issue you reported on my side!
Then I can come back to this PR. Expect to clear this tomorrow.
Thanks again for your patience!!