Metadata-Version: 2.5
Name: vibedata-motherduck-flight
Version: 0.1.0
Summary: VibeData run-time delivery for a MotherDuck Flight: check the Domain repository out at a given ref, authenticated by the Flight's own secret, and hand the project directory back. The Flight program names the load; this gets the code to it.
Author-email: Vibedata <eng@acceleratedata.ai>
License: MIT
Requires-Python: >=3.11
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# vibedata-motherduck-flight

Run-time delivery for a MotherDuck Flight: check the Domain repository out at a
given ref and hand back the project directory.

```python
from vibedata.flight import checkout

project_dir = checkout(GIT_REPO, PROJECT_SUBDIR, GIT_REF, GIT_SECRET_NAME, GIT_SECRET_PARAM)
```

Resolving the credential, fetching the tree and failing in a way that says what
to do live here, so the Flight program is left naming the load.

**The credential** reaches the container as a `flights` secret, injected under
`<secret_name>_<PARAM>` and as a bare `<PARAM>`. The Flight program declares
both halves — the secret's name and its parameter — because that pair is what
someone needs to create the secret, and the platform checks the name but never
the parameter keys. The declared name is tried first, so two attached secrets
carrying the same parameter cannot resolve to the wrong one; any other
namespaced injection is the fallback that keeps the Flight working under a
secret the Domain owner renamed. The bare alias comes last, because across
attached secrets it is last-attached-wins.

**The token never reaches the argv.** It goes to git through `GIT_ASKPASS`, as a
child-process environment variable; the remote URL carries only the
`x-access-token` username. A token in the URL would reach the argv, the git
config written to disk, and every log line that echoes the command.
`GIT_CONFIG_GLOBAL`, `GIT_CONFIG_NOSYSTEM` and a redirected `HOME` keep the
checkout from reading the runtime's own git configuration, including any
credential helper in it.

**Every failure raises** `GitCheckoutError` — a non-zero exit, a timeout, or an
absent `git`. A partial tree builds a subset of the project and reports success
over it, so a caller has one type to render and one thing to say.

`fetch` + `checkout FETCH_HEAD`, never `clone --branch`: a fetch refspec takes a
branch, a tag or a full commit SHA uniformly, and `clone --branch` rejects a SHA.

Requires `git` on PATH, a writable temp dir, and egress to the git host — all of
which the Flight runtime supplies.
