1"""The workspace entry contract: the emitted ``setup.sh`` at the root.
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.
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"""
22from __future__ import annotations
24import shlex
25import tomllib
26from pathlib import Path
27from typing import TYPE_CHECKING
29import livery.footman as footman
31if TYPE_CHECKING:
32 from livery.workshop._declaration import DeclaredVariable
35def locked_uv_version(root: Path) -> str:
36 """The uv version the workspace lock pins, or "".
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 ""
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"
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"""
200def entry_script(root: Path) -> str:
201 """The emitted ``setup.sh`` body for *root*, header not included.
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}``.
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
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 )
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.
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
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)
256def _declared_lines(variables: tuple[DeclaredVariable, ...]) -> str:
257 """One ``_declared`` line for each of *variables*, as the script calls it.
259 A value naming ``{place}`` is set only where the script found one.
260 """
261 from livery.workshop._variables import PLACE_WORD
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)
285def native_members(root: Path) -> tuple[str, ...]:
286 """The distribution names of the job-built members uv installs, in path order.
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
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 )