Coverage for packages/workshop/src/livery/workshop/_entry.py: 100%

Measured by coverage.py 7.16.2 on CPython 3.14 while the suites of tests, packages/workshop, packages/extensions/nanobind, packages/extensions/lfs, packages/extensions/docs ran.

1"""The workspace entry contract: the emitted ``setup.sh`` at the root.
2
3One choke point owns machine readiness. The script ensures uv at the
4lock's pinned version, syncs the venv against the lock, records the
5sync receipt, and emits the environment: sourced by a shell it enters
6that shell, and ``setup.sh github`` persists the emission into
7``GITHUB_ENV``/``GITHUB_PATH`` so every later CI step calls the
8runner bare. A GitLab job sources ``setup.sh gitlab``, and its shell
9keeps the emission for the job's later lines. The script sets the
10variables the workspace's extensions declare before its sync, and on a
11CI job of either kind places each one that names ``{place}`` in the
12job's own directory. Between entries the per-command reconcile
13(``livery.workshop._reconcile``) keeps the venv following the lock.
14
15The script is a generated artifact like the CI workflows: emitted by
16``livery.workshop._ci_generate.generate``, written by
17``fm sync``, judged by the drift check. POSIX only; a
18Windows CI leg runs it under the runner's bash, and a pwsh spelling
19is deferred to the tool-store port.
20"""
21
22from __future__ import annotations
23
24import shlex
25import tomllib
26from pathlib import Path
27from typing import TYPE_CHECKING
28
29import livery.footman as footman
30
31if TYPE_CHECKING:
32 from livery.workshop._declaration import DeclaredVariable
33
34
35def locked_uv_version(root: Path) -> str:
36 """The uv version the workspace lock pins, or "".
37
38 uv rides the dev group, so ``uv.lock`` pins it exactly. A
39 workspace without a lock, or whose lock does not carry uv, has no
40 pin to derive and answers "": the emitters then leave the
41 bootstrap unpinned rather than inventing a version.
42 """
43 lock = root / "uv.lock"
44 if not lock.is_file():
45 return ""
46 try:
47 parsed = tomllib.loads(lock.read_text("utf-8"))
48 except (tomllib.TOMLDecodeError, UnicodeDecodeError):
49 return ""
50 for package in parsed.get("package", []):
51 if isinstance(package, dict) and package.get("name") == "uv":
52 return str(package.get("version", ""))
53 return ""
54
55
56def installer_url(pin: str) -> str:
57 """The uv installer URL, versioned when a *pin* exists."""
58 if pin:
59 return f"https://astral.sh/uv/{pin}/install.sh"
60 return "https://astral.sh/uv/install.sh"
61
62
63# __PROG__ and __INSTALLER__ are substituted at emission; a template
64# with markers instead of an f-string, because the script itself is
65# full of shell braces.
66_SCRIPT = """\
67# The entry contract: uv at the lock's pin -> the venv synced against
68# the lock, its native members left for later -> `__PROG__ sync --locked`,
69# the one a person runs, changing nothing a commit holds: the tools
70# installed, the stubs and the checkout's own files written -> the
71# environment entered here -> the native members built against it.
72# Source it to enter this shell; `setup.sh github` persists the
73# emission (GITHUB_ENV/GITHUB_PATH) for the CI steps after it, which
74# then call __PROG__ bare, and a GitLab job sources `setup.sh gitlab`,
75# whose shell runs the job's later lines.
76_root="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
77# The variables the workspace's extensions declare, set before the sync
78# below, whose builds may read them. A value naming a directory of its
79# own is placed in a CI job's own directory and is not set off a CI job:
80# a GitHub job's is its temp, RUNNER_TEMP, and a GitLab job's is
81# .workshop under its checkout, CI_PROJECT_DIR, a path no two jobs
82# running at once share, which git ignores. A job whose runner names no
83# such directory stops here. A value the environment already carries
84# wins, unless the declaration says always: here the job's environment
85# is formed, so such a value beats one the runner sets for every job.
86_place=""
87# Called with the variable naming the job's directory, its value, the
88# declared variable, and the extension that declares it.
89_job_place() {
90 if [ -z "$2" ]; then
91 echo "setup: this job's runner sets no $1; $4 declares $3 in a" \\
92 "directory of the job's own, so run it on a runner that sets one" >&2
93 return 1
94 fi
95 if [ ! -d "$2" ]; then
96 echo "setup: $1 names $2, which is not a directory; $4 declares $3" \\
97 "in it, so its runner must create it first" >&2
98 return 1
99 fi
100}
101# Called with the variable's name, its value, always or nothing, the
102# extension that declares it, and what the variable is for.
103_declared() {
104 eval "_held=\\"\\${$1:-}\\""
105 if [ -n "$_held" ] && [ "$_held" != "$2" ]; then
106 [ "$3" = always ] || return 0
107 echo "setup: $1 is $2, as $4 declares it; the environment's $1," \\
108 "$_held, is not used: $5" >&2
109 fi
110 eval "$1=\\"\\$2\\""
111 export "$1"
112}
113# On a GitHub job uv's cache and the runner's data directory, the tool
114# store under it, live under the runner's temp, the working drive. On
115# a Windows runner the working drive is not the home directory's: a
116# store on the home drive cannot hardlink its entry points into the
117# checkout and copies instead, and so would uv's cache into the venv.
118# The workflow restores the store before this script runs and saves
119# it after the job; uv's cache is placed for the drive alone. Exported
120# before the sync and the materialise, and persisted by the emission
121# below for every later step. A placement the job already carries
122# stands: a runner that keeps its caches across jobs sets them in its
123# own environment, and the temp is only where nothing is set.
124if [ "${1:-}" = github ]; then
125__GITHUB_PLACE__ UV_CACHE_DIR="${UV_CACHE_DIR:-$RUNNER_TEMP/uv-cache}"
126 __DATA_DIR_VAR__="${__DATA_DIR_VAR__:-$RUNNER_TEMP/footman}"
127 export UV_CACHE_DIR __DATA_DIR_VAR__
128elif [ "${1:-}" = gitlab ]; then
129__GITLAB_PLACE__fi
130__DECLARED__# uv at the lock's pin, the version the venv carries: every sync in
131# this job, this script's and __PROG__'s own, runs the same uv and
132# fills one cache. A uv on PATH at the pin serves; any other version
133# is left where it is, and the pinned one is installed once, under
134# the runner's data directory, and put ahead of it. Without a lock
135# there is no pin, and any uv serves.
136_pin="__UV_PIN__"
137_uv_at_pin() {
138 command -v uv >/dev/null 2>&1 || return 1
139 [ -z "$_pin" ] || [ "$(uv --version 2>/dev/null | cut -d' ' -f2)" = "$_pin" ]
140}
141if ! _uv_at_pin; then
142 _uv_dir="${__DATA_DIR_VAR__:-$HOME/.local/share/footman}/uv/${_pin:-any}"
143 if [ ! -x "$_uv_dir/uv" ]; then
144 curl -LsSf __INSTALLER__ | env UV_UNMANAGED_INSTALL="$_uv_dir" sh >&2
145 fi
146 PATH="$_uv_dir:$PATH"
147 export PATH
148 # Name the install that failed here. Left to fall through, uv's
149 # absence surfaces below as "uv sync failed", which sends the
150 # reader after the venv instead of after the network.
151 if ! _uv_at_pin; then
152 echo "setup: could not install uv $_pin: check network access to astral.sh" >&2
153 return 1 2>/dev/null || exit 1
154 fi
155fi
156# An ARRAY, not a string: CI may invoke this with zsh, which does not
157# word-split unquoted expansions, so a two-word string would arrive
158# as one argument. Arrays expand the same under bash and zsh.
159_sync_args=()
160[ -f "$_root/uv.lock" ] && _sync_args+=(--locked)
161# A native member builds its extension at install against the tools
162# the store supplies below (the compiler's helpers, the provider that
163# resolves its native dependencies), so this sync leaves it out; the
164# workshop's sync below enters the environment itself and its own uv
165# sync builds it.
166_native=(__NATIVE_SKIP__)
167_sync() { uv sync --project "$_root" "${_sync_args[@]}" "$@" >&2; }
168_sync "${_native[@]}" \\
169 || { sleep 10; _sync "${_native[@]}"; } \\
170 || { echo "setup: uv sync failed" >&2; return 1 2>/dev/null || exit 1; }
171# The sync receipt: the lock as this venv last saw it. The runner's
172# per-command reconcile compares the two and re-syncs on drift.
173[ -f "$_root/uv.lock" ] && cp "$_root/uv.lock" "$_root/.venv/.workshop-sync-receipt"
174_run() { uv run --project "$_root" --no-sync __PROG__ "$@"; }
175# The sync a person runs, in the mode that changes nothing a commit
176# holds: the branch stays, no tracked file is written. It installs
177# the tools the lock holds, with a receipt each, and the stubs the type
178# checkers read into typings/, and writes the checkout's own untracked
179# files (the agent's fragments, skills and settings), so a job holds
180# what a person's checkout holds. A lock that is not current refuses
181# here, naming the lock. A tool the store could not supply is named and
182# not fatal: the gate says which step that cost. The emission below
183# puts the receipts' paths on PATH, so a tool the venv does not carry
184# (an archive from its own release) resolves for the gate.
185_run sync --locked >&2 \\
186 || { echo "setup: __PROG__ sync --locked refused; its message names why" >&2; \\
187 return 1 2>/dev/null || exit 1; }
188# Entered here, whether sourced or run, in one call: a sourcing shell
189# keeps it, and under `github` the same call persists the emission
190# for the steps after. Nothing installs after this line: the sync
191# above left the venv complete.
192if [ "${1:-}" = github ]; then
193 eval "$(_run env.emit posix --github)"
194else
195 eval "$(_run env.emit posix)"
196fi
197"""
198
199
200def entry_script(root: Path) -> str:
201 """The emitted ``setup.sh`` body for *root*, header not included.
202
203 The variables the extensions of *root*'s set declare are rendered
204 from their declarations: each one's line, and in each CI branch the
205 check that the job names a directory of its own, once for each
206 variable that names ``{place}``.
207
208 Raises:
209 Failed: when two of the extensions declare one variable, naming
210 both.
211 """
212 from livery.footman import directory_variable
213 from livery.workshop._variables import workspace_variables
214
215 pin = locked_uv_version(root)
216 skipped = " ".join(f"--no-install-package {name}" for name in native_members(root))
217 variables = workspace_variables(root)
218 return (
219 _SCRIPT.replace("__PROG__", footman.prog())
220 .replace("__INSTALLER__", installer_url(pin))
221 .replace("__DATA_DIR_VAR__", directory_variable("DATA_DIR"))
222 .replace("__UV_PIN__", pin)
223 .replace("__NATIVE_SKIP__", skipped)
224 .replace("__GITHUB_PLACE__", _job_place("github", variables))
225 # A shell branch takes no empty body: one that places nothing
226 # does nothing.
227 .replace("__GITLAB_PLACE__", _job_place("gitlab", variables) or " :\n")
228 .replace("__DECLARED__", _declared_lines(variables))
229 )
230
231
232def _job_place(mode: str, variables: tuple[DeclaredVariable, ...]) -> str:
233 """The lines of the script's *mode* branch that name the job's own directory.
234
235 One check for each of *variables* that names ``{place}``, so a job
236 whose runner names no directory stops naming the variable and the
237 extension that declares it, then the directory itself. Empty when
238 none names ``{place}``.
239 """
240 from livery.workshop._variables import JOB_DIRECTORIES
241
242 placed = [variable for variable in variables if variable.placed]
243 if not placed:
244 return ""
245 named, under = JOB_DIRECTORIES[mode]
246 lines = [
247 f' _job_place {named} "${{{named}:-}}" {variable.name}'
248 f" {shlex.quote(variable.extension)} \\\n"
249 " || { return 1 2>/dev/null || exit 1; }\n"
250 for variable in placed
251 ]
252 lines.append(f' _place="${named}{"/" + under if under else ""}"\n')
253 return "".join(lines)
254
255
256def _declared_lines(variables: tuple[DeclaredVariable, ...]) -> str:
257 """One ``_declared`` line for each of *variables*, as the script calls it.
258
259 A value naming ``{place}`` is set only where the script found one.
260 """
261 from livery.workshop._variables import PLACE_WORD
262
263 lines: list[str] = []
264 for variable in variables:
265 value = '"$_place"'.join(
266 shlex.quote(part) if part else ""
267 for part in variable.value.split(PLACE_WORD)
268 )
269 line = " ".join(
270 (
271 "_declared",
272 variable.name,
273 value or "''",
274 "always" if variable.always else "''",
275 shlex.quote(variable.extension),
276 shlex.quote(variable.doc),
277 )
278 )
279 lines.append(
280 f'[ -z "$_place" ] || {line}\n' if variable.placed else f"{line}\n"
281 )
282 return "".join(lines)
283
284
285def native_members(root: Path) -> tuple[str, ...]:
286 """The distribution names of the job-built members uv installs, in path order.
287
288 A member a job of the release point builds before the wave, the
289 workspace's ``job-built-members`` answer, carries native code its
290 install builds against the store's tools, so the entry installs it
291 after the tools are in the environment; every other member installs
292 in the first sync. A job-built member the uv workspace does not hold
293 is no uv install and is left out.
294 """
295 from livery.workshop._identity import roster
296 from livery.workshop._queries import JOB_BUILT_MEMBERS, answer
297
298 if not (root / "packages").is_dir():
299 return ()
300 built = answer(root, JOB_BUILT_MEMBERS)
301 # The roster's dev entry marks a member of the uv workspace.
302 return tuple(
303 entry["name"]
304 for entry in roster(root)
305 if "dev" in entry and f"packages/{entry['dir']}" in built
306 )