1"""The ``env`` group: enter, show, set, and verify the environment.
3The cascade (``livery.workshop._envfile``) is the one config
4mechanism; this module is every way it reaches a consumer: applied
5to each ``fm`` run (a pre-tasks hook, environment always winning),
6emitted for a shell or an agent or GitHub Actions, shown masked, set
7scoped, and verified against the tool profile the present package
8types derive.
10Every task here repairs or diagnoses the environment, so none
11carries an availability gate: they must run on a cold checkout.
12"""
14from __future__ import annotations
16import os
17import shutil
18from dataclasses import dataclass, field
19from pathlib import Path
20from typing import TYPE_CHECKING, Annotated, Any, Literal
22import livery.footman as footman
23import livery.toolroom.tools as toolroom
24from livery.footman import Arg, Stdout, doc, fail, group, pre_task, pre_tasks
25from livery.forge import RepoConfig
26from livery.workshop._envfile import (
27 RUNG_PREFIX,
28 Source,
29 cascade_dirs,
30 is_secret_name,
31 load_cascade,
32 member_keys,
33 parse_env_file,
34 quote_value,
35 set_value,
36)
38if TYPE_CHECKING:
39 from collections.abc import Iterable, MutableMapping
41 from livery.workshop._declaration import DeclaredVariable
42 from livery.workshop._packages import Package
43 from livery.workshop._tools import ToolReceipt
45#: Names never emitted for an agent: the PATH family is composed per
46#: shell, not copied between sessions.
47NEVER_AGENT = ("PATH",)
49env = group("env", help="The environment: enter, show, set, verify")
51#: Keys the pre-tasks hook itself contributed this run. The hook's
52#: setdefault-ed values look pre-existing to a later cascade load, so
53#: the emitters merge this back before selecting on provenance.
54_APPLIED: dict[str, str] = {}
57def _workspace() -> tuple[Path, Path]:
58 from livery.workshop._extensions import workspace_root
60 root = workspace_root()
61 if root is None:61 ↛ 62line 61 didn't jump to line 62 because the condition on line 61 was never true
62 fail("no workspace: no workshop.toml above the working directory")
63 return root, footman.cwd()
66def _shared_dir() -> Path:
67 """Where ``.repo.shared.env`` lives: the runner's config directory."""
68 import livery.footman as footman
70 return footman.config_dir()
73@pre_tasks
74def apply_cascade(inv: footman.Invocation) -> None:
75 """Fold the cascade into this run's environment; environment wins.
77 Every ``fm`` command sees the repo's declared environment, so a
78 cold shell still runs with the tokens and settings the files
79 hold. Only absent keys are written, and what the hook itself
80 contributed is remembered: those values look pre-existing to a
81 later load, and the emitters must not misread them as the
82 shell's own. The variables the workspace's extensions declare
83 follow (`apply_declared`).
84 """
85 from livery.workshop._extensions import workspace_root
87 _ = inv
88 _APPLIED.clear()
89 root = workspace_root()
90 if root is None:
92 stack = load_cascade(root, Path.cwd())
93 for key, value in stack.managed().items():
94 # Truthiness, not presence, matches the cascade's own
95 # env-wins rule: a key exported empty reads as unset.
96 if not os.environ.get(key):96 ↛ 93line 96 didn't jump to line 93 because the condition on line 96 was always true
97 os.environ[key] = value
98 _APPLIED[key] = value
99 apply_declared(root, os.environ)
100 # The tools' half of the entry contract: whatever launched this
101 # process, it runs entered.
102 apply_entry(root, os.environ)
103 _warn_unmounted_extensions(root)
106def apply_declared(root: Path, environ: MutableMapping[str, str]) -> dict[str, str]:
107 """Set the variables the extensions of *root*'s set declare into *environ*.
109 On a CI job a value naming ``{place}`` takes the job's own
110 directory: ``RUNNER_TEMP`` on a GitHub or Gitea job, ``.workshop``
111 under ``CI_PROJECT_DIR`` on a GitLab one. Off a CI job it is not
112 set, and a desk keeps its own. A variable *environ* already
113 carries keeps its value, its declaration's ``always`` included: the
114 job's entry already placed it where the job's environment was
115 formed, and a nested run keeps the value its parent set. The
116 cascade's files count as the environment here, since they are folded
117 in first. What the hook contributes is remembered in `_APPLIED`. A
118 declaration that cannot be read costs these variables alone, said on
119 stderr, never the command: the mount and ``fm sync`` name it.
121 Returns:
122 The variables written, each to its value.
123 """
124 import sys
126 from livery.footman import Failed
127 from livery.workshop._declaration import DeclarationError
128 from livery.workshop._variables import job_place, placed, workspace_variables
130 try:
131 variables = workspace_variables(root)
132 except (DeclarationError, Failed) as error:
133 sys.stderr.write(f"declared variables skipped ({error})\n")
134 return {}
135 written: dict[str, str] = {}
136 for key, value in placed(variables, job_place(environ), environ).items():
137 if environ.get(key) != value:
138 environ[key] = value
139 _APPLIED[key] = value
140 written[key] = value
141 return written
144#: Whether this process's command had its checkout brought current:
145#: the per-task hook below does it once, before the first task.
146_SYNCED: list[bool] = []
149@pre_task
150def sync_first(inv: footman.Invocation, task: Any) -> None:
151 """Bring the checkout current before the command's first task runs.
153 Once per process, at the first task's per-task moment, which is
154 inside the run: discovery also runs in the child that rebuilds the
155 completion manifest, where a sync would run on a Tab press. The
156 sync runs on the workspace above the task's directory and decides
157 from the checkout's receipts ([livery.workshop._reconcile.apply][]);
158 the steps it runs are recorded as the task's own. A sync that wrote
159 receipts this process entered without enters again, into the
160 task's own environment, `task.env`: the task's body, the processes
161 it starts and the tasks it calls read it. Never `os.environ`: inside
162 a task footman notes that write as a misuse, and a workspace's notes
163 policy can fail the task for it.
164 """
165 from livery.workshop._extensions import workspace_root
167 _ = inv
168 if _SYNCED:
169 return
170 _SYNCED.append(True)
171 root = workspace_root()
172 if root is None:172 ↛ 173line 172 didn't jump to line 173 because the condition on line 172 was never true
173 return
174 # Belt and braces around the whole self-healing step: a raising
175 # pre-task hook fails the task, so nothing short of a deliberate
176 # SystemExit (the re-run handoff, which derives from
177 # BaseException) may escape it.
178 try:
179 from livery.workshop import _reconcile
181 if _reconcile.is_cli_process() and _reconcile.apply(
182 root, str(task.name), task.env
183 ):
184 apply_entry(root, task.env)
185 except Exception as error:
186 import sys
188 sys.stderr.write(f"environment sync skipped ({error})\n")
191def apply_entry(root: Path, environ: MutableMapping[str, str]) -> tuple[str, ...]:
192 """Enter the venv and the receipts' tools into *environ*.
194 The same PATH entries and variables `env.emit` hands an entered
195 shell, so every `fm` invocation resolves the locked tools whatever
196 launched it: an agent's shell, a CI step, a bare terminal. The
197 cascade hook enters the process environment before the run starts,
198 and every task starts from it; the per-task hook enters a task's
199 own environment ([livery.workshop._env_tasks.sync_first][]). The
200 emission leads PATH in its own order, the venv's bin first and the
201 tools after it, and the rest of PATH follows; an entry the emission
202 names moves to its place in front, since a tool directory ahead of
203 the venv would shadow the venv's pytest and mypy with the store's
204 plain ones. A variable *environ* already has wins, as the cascade's
205 do, and what the hook contributes is remembered in `_APPLIED`. A
206 receipts directory holding a file that is not a receipt costs the
207 tools' half alone, said on stderr, never the command. Idempotent: a
208 second application changes nothing.
210 Returns:
211 The PATH entries that were not on PATH before, in order.
212 """
213 import sys
215 try:
216 paths, env = _receipts_emission(root)
217 except ValueError as error:
218 sys.stderr.write(f"tool receipts skipped ({error})\n")
219 paths, env = (), {}
220 current = [e for e in environ.get("PATH", "").split(os.pathsep) if e]
221 leading: list[str] = []
222 seen: set[str] = set()
223 for entry in (str(venv_bin(root)), *paths):
224 if os.path.normcase(entry) not in seen:224 ↛ 223line 224 didn't jump to line 223 because the condition on line 224 was always true
225 leading.append(entry)
226 seen.add(os.path.normcase(entry))
227 added = tuple(
228 e
229 for e in leading
230 if os.path.normcase(e) not in {os.path.normcase(c) for c in current}
231 )
232 rest = [c for c in current if os.path.normcase(c) not in seen]
233 composed = os.pathsep.join([*leading, *rest])
234 if composed != environ.get("PATH", ""):
235 environ["PATH"] = composed
236 values = {"VIRTUAL_ENV": str(root / ".venv"), **env}
237 for key, value in values.items():
238 if not environ.get(key):
239 environ[key] = value
240 _APPLIED[key] = value
241 return added
244def _warn_unmounted_extensions(root: Path) -> None:
245 """Teach when the contract lists extensions this process never mounted.
247 The workshop mounts the extensions its contract lists when footman
248 loads it as a plugin of a project that depends on it. A process that
249 has the base's verbs without that load mounts none of them, and
250 every listed extension's tasks are missing. Loud, once per command,
251 with the repair named.
252 """
253 import sys
255 from livery.workshop import _extensions
257 if _extensions.MOUNTED or not (root / "workshop.toml").is_file():
258 return
259 declared = [
260 name for name in _extensions.extension_names(root) if name != _extensions.SELF
261 ]
262 if not declared:
263 return
264 import livery.footman as footman
266 prog = footman.prog()
267 sys.stderr.write(
268 f"{prog}: the contract lists extensions ({', '.join(declared)}) that"
269 " this run never mounted: the workshop mounts them when footman loads"
270 " it as a plugin of a project that depends on it. Run"
271 f" `{prog} sync` to compose tasks.py and install the environment again\n"
272 )
275@dataclass(frozen=True)
276class EnvDelta:
277 """What entering the environment adds: variables and PATH entries."""
279 values: dict[str, str] = field(default_factory=dict)
280 paths: tuple[str, ...] = ()
283#: The temporary directory of a Windows leg: ``runner`` puts it under
284#: the runner's own temp, ``system`` leaves it where Windows puts it.
285WINDOWS_TEMP_VALUES = ("runner", "system")
288def runner_placements(
289 environ: dict[str, str], variables: Iterable[DeclaredVariable] = ()
290) -> dict[str, str]:
291 """What a GitHub job places under the runner's temp: its caches and *variables*.
293 The runner's temp is the working drive, where the checkout and the
294 venv are; on a Windows runner the home directory is another drive,
295 and a tool store there cannot hardlink into the checkout, nor uv's
296 cache into the venv. The entry script exports the same paths
297 before its sync and materialise, since it runs before any verb
298 can; the workflow's cache step restores and saves the store under
299 the data directory. Empty off a runner that names no temp.
301 uv's cache and the data directory take many processes at once, so
302 a key the job's environment already sets keeps its value, and that
303 value is what gets persisted: a runner with a persistent cache sets
304 the key for every step and loses nothing, and the entry script,
305 which exports the same keys for its own sync before it asks for
306 the emission, hands them on to the steps after it, where an export
307 of a step's shell never reaches by itself.
309 *variables* are the ones the workspace's extensions declare, which
310 `apply_declared` sets for each run where the environment carries
311 none. A value naming ``{place}`` takes the runner's temp, which is
312 the job's own. The emission forms the environment of the job's later
313 steps, so an ``always`` one beats a value the runner sets for every
314 job.
316 Raises:
317 Failed: when one of *variables* names ``{place}`` on a job
318 (``GITHUB_ACTIONS`` set) whose runner names no
319 ``RUNNER_TEMP``, or when ``RUNNER_TEMP`` names no directory,
320 naming each such variable and the extension that declares
321 it: the job then has no directory of its own to keep it in.
322 """
323 from livery.footman import directory_variable
324 from livery.workshop._variables import declarers, placed
326 held = tuple(variables)
327 needing = declarers(variable for variable in held if variable.placed)
328 runner_temp = environ.get("RUNNER_TEMP", "")
329 if not runner_temp:
330 if environ.get("GITHUB_ACTIONS") and needing:
331 fail(
332 f"this job's runner sets no RUNNER_TEMP: {needing} in a directory"
333 " of the job's own, so run it on a runner that sets one"
334 )
335 return {}
336 if needing and not Path(runner_temp).is_dir():
337 fail(
338 f"RUNNER_TEMP names {runner_temp}, which is not a directory: {needing}"
339 " in it, so its runner must create it first"
340 )
341 shared = {
342 "UV_CACHE_DIR": f"{runner_temp}/uv-cache",
343 directory_variable("DATA_DIR"): f"{runner_temp}/footman",
344 }
345 found = {key: environ.get(key) or value for key, value in shared.items()}
346 found.update(placed(held, runner_temp, environ, forming=True))
347 return found
350def with_runner_placements(
351 delta: EnvDelta, environ: dict[str, str], variables: Iterable[DeclaredVariable] = ()
352) -> EnvDelta:
353 """*delta* with the runner's placements for a GitHub job, unchanged elsewhere."""
354 found = runner_placements(environ, variables)
355 if not found:
356 return delta
357 return EnvDelta(values={**delta.values, **found}, paths=delta.paths)
360def windows_temp_policy(root: Path) -> str:
361 """The contract's ``[ci] windows-temp``, or the forge kind's default.
363 ``runner`` for a GitHub-shaped workspace: GitHub's hosted Windows
364 runners keep the workspace, the uv cache, and the runner's temp on
365 the fast working drive and the system temp on the slow system
366 drive. ``system`` for every other forge, whose runners are the
367 workspace's own. A value that is neither refuses naming both.
368 """
369 from livery.workshop._contract import load_contract
371 contract = load_contract(root / "workshop.toml")
372 value = (contract.get("ci") or {}).get("windows-temp")
373 if value is None:
374 kind = str((contract.get("forge") or {}).get("kind", ""))
375 return "runner" if kind == "github" else "system"
376 if value not in WINDOWS_TEMP_VALUES:376 ↛ 377line 376 didn't jump to line 377 because the condition on line 376 was never true
377 fail(
378 f"[ci] windows-temp is {value!r}; it is one of"
379 f" {', '.join(WINDOWS_TEMP_VALUES)}"
380 )
381 return str(value)
384def with_runner_temp(
385 delta: EnvDelta,
386 root: Path,
387 environ: dict[str, str],
388 *,
389 platform: str = "",
390) -> tuple[EnvDelta, str]:
391 """*delta* with ``TEMP`` and ``TMP`` under the runner's temp on a Windows leg.
393 The tests' files and the environments they build with uv then
394 share the working drive with the uv cache, which the runner keeps
395 under its temp, so uv links instead of copying. Returns the delta
396 and one line saying what happened. Nothing changes off Windows,
397 under the ``system`` policy, or when the runner names no
398 ``RUNNER_TEMP``; the last two say so.
399 """
400 import sys
402 if (platform or sys.platform) != "win32":
403 return delta, ""
404 if windows_temp_policy(root) == "system":
405 return delta, "TEMP: the system temp stays ([ci] windows-temp = system)"
406 runner_temp = environ.get("RUNNER_TEMP", "")
407 if not runner_temp:
408 return delta, "TEMP: the runner names no RUNNER_TEMP; the system temp stays"
409 target = Path(runner_temp) / "tmp"
410 target.mkdir(parents=True, exist_ok=True)
411 values = {**delta.values, "TEMP": str(target), "TMP": str(target)}
412 return EnvDelta(values=values, paths=delta.paths), (
413 f"TEMP: {target} (the runner's working drive, beside the uv cache)"
414 )
417def venv_bin(root: Path) -> Path:
418 """The venv's executables directory: ``Scripts`` on Windows, ``bin`` elsewhere.
420 The emission runs on the machine it enters, so the running
421 platform is the right answer ([livery.workshop.scripts_dir][]).
422 """
423 from livery.workshop._pythons import scripts_dir
425 return scripts_dir(root / ".venv")
428def workspace_delta(
429 root: Path, cwd: Path, environ: dict[str, str] | None = None
430) -> EnvDelta:
431 """The delta an entered shell needs for this workspace.
433 The cascade's managed values, plus the venv: ``VIRTUAL_ENV`` and
434 the venv's bin on PATH, so ``fm`` and the venv tools resolve.
435 The seam a tool store would extend. *environ* is the process
436 environment the cascade reads; None means ``os.environ``.
437 """
438 seen = dict(os.environ) if environ is None else environ
439 stack = load_cascade(root, cwd, environ=seen)
440 values = dict(stack.managed())
441 for key, value in _APPLIED.items():
442 values.setdefault(key, seen.get(key, value))
443 values["VIRTUAL_ENV"] = str(root / ".venv")
444 paths, env = _receipts_emission(root)
445 values.update(env)
446 return EnvDelta(values=values, paths=(str(venv_bin(root)), *paths))
449def _receipts_emission(root: Path) -> tuple[tuple[str, ...], dict[str, str]]:
450 """What the checkout's receipts add: the tools materialised on this machine."""
451 from livery.workshop._tools import emission
453 return emission(root)
456def _posix_quote(value: str) -> str:
457 return "'" + value.replace("'", "'\\''") + "'"
460def _check_emittable(name: str, value: str) -> None:
461 import re
463 if not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", name):
464 fail(
465 f"{name!r} is not an exportable variable name: only the value"
466 " side is quoted, and a malformed name changes what the line"
467 " means."
468 )
469 if "\n" in value or "\r" in value:
470 fail(
471 f"{name} carries a line break, which cannot be quoted into a"
472 " single export line. Remove it from the env file."
473 )
476def emit_lines(delta: EnvDelta, dialect: str) -> list[str]:
477 """Serialise *delta* for *dialect* (``posix`` or ``pwsh``).
479 One export per variable, then exactly one PATH prepend. A value
480 or name that cannot be spelled safely is refused: only the value
481 side is quoted, and ``export A B=1`` exports ``A``.
482 """
483 lines: list[str] = []
484 for name in sorted(delta.values):
485 value = delta.values[name]
486 _check_emittable(name, value)
487 if dialect == "pwsh":
488 doubled = value.replace("'", "''")
489 lines.append(f"$env:{name} = '{doubled}'")
490 else:
491 lines.append(f"export {name}={_posix_quote(value)}")
492 if delta.paths:492 ↛ 501line 492 didn't jump to line 501 because the condition on line 492 was always true
493 for entry in delta.paths:
494 _check_emittable("PATH", entry)
495 if dialect == "pwsh":
496 joined = ";".join(entry.replace("'", "''") for entry in delta.paths)
497 lines.append(f"$env:PATH = '{joined};' + $env:PATH")
498 else:
499 joined = ":".join(_posix_quote(entry) for entry in delta.paths)
500 lines.append(f'export PATH={joined}:"$PATH"')
501 return lines
504_COMPLETION_HOOK = (
505 "# Interactive shells get completion; a pipe or script never does.\n"
506 'case $- in *i*) eval "$({prog} --setup-completion)";; esac'
507)
509#: The variable ``start`` reads for the file it writes the worktree's
510#: path to, when the shell function below runs the verb: the function
511#: then enters the worktree in the caller's own shell, since a child
512#: process cannot change its parent's directory.
513START_PATH_VARIABLE = "WORKSHOP_START_PATH_FILE"
515_START_HOOK = (
516 "# `{prog} start` enters the worktree in this shell: the verb writes the\n"
517 "# path to a file this function names, and the shell changes into it\n"
518 "# and evaluates its environment. A pipe or script never gets it.\n"
519 "case $- in *i*) {prog}() {{\n"
520 ' if [ "$1" = start ]; then\n'
521 " local _f _p _rc\n"
522 ' _f="$(mktemp)" || {{ command {prog} "$@"; return; }}\n'
523 ' {variable}="$_f" command {prog} "$@"\n'
524 " _rc=$?\n"
525 ' _p="$(cat "$_f" 2>/dev/null)"; rm -f "$_f"\n'
526 ' if [ "$_rc" -eq 0 ] && [ -n "$_p" ]; then\n'
527 ' cd "$_p" && eval "$(command {prog} --quiet env.emit posix)"\n'
528 " fi\n"
529 ' return "$_rc"\n'
530 " fi\n"
531 ' command {prog} "$@"\n'
532 "}};; esac"
533)
535_START_PWSH = (
536 "# `{prog} start` enters the worktree in this session: the verb writes the\n"
537 "# path to a file this function names, and the session changes into it\n"
538 "# and evaluates its environment.\n"
539 "function {prog} {{\n"
540 " $app = Get-Command {prog} -CommandType Application | Select-Object -First 1\n"
541 " if ($args.Count -gt 0 -and $args[0] -eq 'start') {{\n"
542 " $f = [System.IO.Path]::GetTempFileName()\n"
543 " $env:{variable} = $f\n"
544 " & $app @args\n"
545 " $rc = $LASTEXITCODE\n"
546 " Remove-Item Env:{variable} -ErrorAction SilentlyContinue\n"
547 " $p = Get-Content $f -ErrorAction SilentlyContinue\n"
548 " Remove-Item $f -ErrorAction SilentlyContinue\n"
549 " if ($rc -eq 0 -and $p) {{\n"
550 " Set-Location $p\n"
551 ' (& $app --quiet env.emit pwsh) -join "`n" | Invoke-Expression\n'
552 " }}\n"
553 " return\n"
554 " }}\n"
555 " & $app @args\n"
556 "}}"
557)
559# MenuComplete, because registering completions is only half the job:
560# PSReadLine's default Tab handler cycles candidates one keypress at a
561# time and shows neither the list nor the per-item help, so a shell
562# with completion fully working still feels like it has none. Guarded
563# twice over: PSReadLine is absent in constrained hosts, and a missing
564# module must not break entering the shell. No interactive guard:
565# pwsh has no reliable one-liner for it.
566_COMPLETION_PWSH = (
567 "if (Get-Command {prog} -ErrorAction SilentlyContinue) {{"
568 ' $fmHook = ({prog} --setup-completion=pwsh 2>$null) -join "`n";'
569 " if ($fmHook) {{ $fmHook | Invoke-Expression }} }}"
570 "; if (-not $env:WORKSHOP_NO_SHELL_CUSTOMISATION"
571 " -and (Get-Module -ListAvailable PSReadLine)) {{"
572 " Set-PSReadLineKeyHandler -Key Tab -Function MenuComplete }}"
573)
576def agent_delta(root: Path, cwd: Path, environ: dict[str, str]) -> EnvDelta:
577 """The variables an agent session needs, selected by membership.
579 Membership, not provenance: a session that already carries these
580 variables would reclassify them as pre-existing, and a
581 provenance filter would silently drop them. Secrets are included
582 on purpose, availability is the point; the PATH family is
583 excluded, it is composed per shell.
584 """
585 shared = _shared_dir()
586 keys = member_keys(root, cwd, shared)
587 values = {
588 key: environ.get(key, _APPLIED.get(key, ""))
589 for key in sorted(keys)
590 if key not in NEVER_AGENT and (environ.get(key) or _APPLIED.get(key))
591 }
592 values["VIRTUAL_ENV"] = str(root / ".venv")
593 paths, env = _receipts_emission(root)
594 values.update(env)
595 return EnvDelta(values=values, paths=(str(venv_bin(root)), *paths))
598def rung_file(environ: dict[str, str]) -> Path | None:
599 """Write the secrets the entry step carries into the shared slot's file.
601 The rendered entry step hands each declared key's CI secret to the
602 emission as ``RUNG_<KEY>``. The non-empty ones land in
603 ``repo-shared.env`` under the runner's temp, readable by its owner
604 alone, and the cascade reads that file as the shared slot
605 (``WORKSHOP_SHARED_ENV_FILE``): the precedence of a machine's
606 shared file, gone with the runner. An absent secret arrives empty
607 and writes nothing, so it cannot mask a committed value; a job
608 whose secrets all arrive empty still points the slot at the empty
609 file, so a self-hosted runner's own shared file is never read.
611 Returns:
612 The file's path, or None when the step carries no key at all.
614 Raises:
615 Failed: on a step carrying keys whose runner names no
616 ``RUNNER_TEMP`` directory, since the file is the job's own;
617 or on a secret with a line break, which one line of an env
618 file cannot hold.
619 """
620 carried = {
621 key[len(RUNG_PREFIX) :]: value
622 for key, value in environ.items()
623 if key.startswith(RUNG_PREFIX) and len(key) > len(RUNG_PREFIX)
624 }
625 if not carried:
626 return None
627 runner_temp = environ.get("RUNNER_TEMP", "")
628 if not runner_temp or not Path(runner_temp).is_dir():
629 fail(
630 "this job's runner names no RUNNER_TEMP directory: the entry keeps"
631 " the secrets' file in the job's own temporary directory, so run"
632 " it on a runner that sets one"
633 )
634 lines: list[str] = []
635 for key, value in sorted(carried.items()):
636 if not value:
637 continue
638 try:
639 lines.append(f"{key}={quote_value(value)}\n")
640 except ValueError:
641 fail(
642 f"the secret {key} carries a line break, which one line of"
643 " the shared slot's file cannot hold; store it without one"
644 )
645 path = Path(runner_temp) / "repo-shared.env"
646 path.write_text("".join(lines), encoding="utf-8")
647 path.chmod(0o600)
648 return path
651def github_persist(delta: EnvDelta, environ: dict[str, str]) -> list[str]:
652 """Append *delta* to GITHUB_ENV and GITHUB_PATH; what was written.
654 Only under GitHub Actions, and never a secret name: the runner's
655 env file is not a secret store, and the workflow's own secrets
656 mechanism carries those.
657 """
658 if not environ.get("GITHUB_ACTIONS"):
659 fail("--github persists into GITHUB_ENV, which only Actions sets")
660 written: list[str] = []
661 env_file = environ.get("GITHUB_ENV", "")
662 if env_file:662 ↛ 670line 662 didn't jump to line 670 because the condition on line 662 was always true
663 with Path(env_file).open("a", encoding="utf-8") as handle:
664 for name in sorted(delta.values):
665 if is_secret_name(name):
666 continue
667 _check_emittable(name, delta.values[name])
668 handle.write(f"{name}={delta.values[name]}\n")
669 written.append(name)
670 path_file = environ.get("GITHUB_PATH", "")
671 if path_file:
672 with Path(path_file).open("a", encoding="utf-8") as handle:
673 # The runner prepends each line in turn, so the last line
674 # written ends up first on PATH. Written last to first, the
675 # emission's order holds: the venv's bin ahead of the
676 # receipts' directories, as `eval "$(fm env.emit posix)"`
677 # puts them, so the venv's pytest and mypy keep winning over
678 # the store's copies of the same names.
679 for entry in reversed(delta.paths):
680 handle.write(f"{entry}\n")
681 written.append(f"PATH+{entry}")
682 return written
685@env.task(name="emit")
686def env_emit(
687 target: Arg[Literal["posix", "pwsh", ""]] = "",
688 agent: Annotated[
689 bool, doc("the agent selection: membership, secrets included")
690 ] = False,
691 github: Annotated[
692 bool, doc("persist into GITHUB_ENV/GITHUB_PATH (Actions only)")
693 ] = False,
694) -> Stdout[str]:
695 """Emit the environment for evaluation by a shell.
697 Bare: the entered-shell emission plus the interactive completion
698 hook. ``--agent``: the membership selection for an agent session
699 (evaluated by its env file, so no completion hook). ``--github``
700 writes the runner's env files, and on a Windows leg points
701 ``TEMP`` and ``TMP`` under the runner's temp when the contract's
702 ``[ci] windows-temp`` says ``runner``, the default of a
703 GitHub-shaped workspace; alone it prints what it wrote, and with a
704 target it prints that same emission for the shell to evaluate, so
705 the entry step enters and persists in one call.
706 """
707 import sys
709 root, cwd = _workspace()
710 dialect = target or ("pwsh" if sys.platform == "win32" else "posix")
711 if github:
712 from livery.workshop._variables import workspace_variables
714 environ = dict(os.environ)
715 rung = rung_file(environ)
716 if rung is not None:
717 # The cascade reads the slot from the environment it is
718 # handed, and the steps after read it persisted.
719 environ["WORKSHOP_SHARED_ENV_FILE"] = str(rung)
720 delta, note = with_runner_temp(
721 with_runner_placements(
722 workspace_delta(root, cwd, environ), environ, workspace_variables(root)
723 ),
724 root,
725 environ,
726 )
727 if rung is not None:
728 delta = EnvDelta(
729 values={**delta.values, "WORKSHOP_SHARED_ENV_FILE": str(rung)},
730 paths=delta.paths,
731 )
732 written = github_persist(delta, environ)
733 if target:
734 return "\n".join(emit_lines(delta, dialect))
735 return "\n".join([*written, note] if note else written)
736 if agent:
737 delta = agent_delta(root, cwd, dict(os.environ))
738 return "\n".join(emit_lines(delta, dialect))
739 delta = workspace_delta(root, cwd)
740 lines = emit_lines(delta, dialect)
741 hook = _COMPLETION_PWSH if dialect == "pwsh" else _COMPLETION_HOOK
742 lines.append(hook.format(prog=footman.prog()))
743 enter = _START_PWSH if dialect == "pwsh" else _START_HOOK
744 lines.append(enter.format(prog=footman.prog(), variable=START_PATH_VARIABLE))
745 return "\n".join(lines)
748def _mask(key: str, value: str) -> str:
749 if not is_secret_name(key) or not value:
750 return value
751 return f"({len(value)} chars, masked)"
754@env.task(name="show")
755def env_show(
756 full: Annotated[bool, doc("show secret values unmasked")] = False,
757) -> None:
758 """Show the cascade: sources, values, and the PATH breakdown.
760 Secrets are masked by the suffix convention unless ``--full``.
761 The PATH breakdown numbers every entry and marks the missing
762 directories; duplicates are shown as they are.
763 """
764 root, cwd = _workspace()
765 environ = dict(os.environ)
766 shared = _shared_dir()
767 print(" Sources:")
768 for directory in cascade_dirs(root, cwd):
769 for name in (".repo.env", ".repo.env.local"):
770 candidate = directory / name
771 if candidate.is_file():
772 print(f" {candidate}")
773 if (shared / ".repo.shared.env").is_file():773 ↛ 774line 773 didn't jump to line 774 because the condition on line 773 was never true
774 print(f" {shared / '.repo.shared.env'}")
775 # The pre-tasks hook already exported every managed key into this
776 # process, so a live-environ load would classify everything as
777 # the shell's own. Subtracting the hook's contributions restores
778 # the files' provenance; a key the shell genuinely exported still
779 # reads as environment.
780 seen = {k: v for k, v in environ.items() if k not in _APPLIED}
781 stack = load_cascade(root, cwd, environ=seen)
782 files_only = load_cascade(root, cwd, environ={})
783 if stack.values:783 ↛ 802line 783 didn't jump to line 802 because the condition on line 783 was always true
784 print(" Variables:")
785 width = max(len(key) for key in stack.values)
786 for key in sorted(stack.values):
787 value = stack.values[key] if full else _mask(key, stack.values[key])
788 source = stack.sources[key].name
789 if source == "shared" and environ.get("WORKSHOP_SHARED_ENV_FILE"):789 ↛ 790line 789 didn't jump to line 790 because the condition on line 789 was never true
790 source = "ci rung"
791 marker = ""
792 declared = files_only.values.get(key)
793 if (
794 stack.sources[key] is Source.environment
795 and declared is not None
796 and declared != stack.values[key]
797 ):
798 # An older export than the file declares: stale until
799 # the person re-enters.
800 marker = " [stale - the files say otherwise; re-enter]"
801 print(f" {key:<{width}} {value} ({source}){marker}")
802 print(" PATH:")
803 for index, entry in enumerate(environ.get("PATH", "").split(os.pathsep), 1):
804 marker = "" if Path(entry).is_dir() else " (missing)"
805 print(f" {index:>2} {entry}{marker}")
808@env.task(name="set", interactive=True)
809def env_set(
810 key: Annotated[str, doc("the variable name")],
811 value: Annotated[str, doc("the value; empty deletes the key")] = "",
812 scope: Annotated[
813 str,
814 doc(
815 "local (this machine), shared (this person), repo"
816 " (committed), ci (the forge's secret store)"
817 ),
818 ] = "local",
819) -> None:
820 """Set or delete one variable in the chosen scope's file.
822 ``local`` writes ``.repo.env.local`` at the workspace root,
823 ``shared`` the person-wide ``.repo.shared.env`` in the runner's
824 config directory,
825 ``repo`` the committed ``.repo.env``. ``ci`` writes a CI secret
826 through the forge protocol: under CI the entry step hands the
827 declared keys' secrets to the emission, which materialises them
828 into the shared slot, so a secret overrides the committed value
829 the way the shared file does on a machine. After a write the
830 higher-precedence sources are checked: a shadowed value is named
831 rather than discovered later.
832 """
833 root, _cwd = _workspace()
834 if scope == "ci":
835 _set_ci_secret(root, key, value)
836 return
837 environ = dict(os.environ)
838 shared = _shared_dir()
839 files = {
840 "local": root / ".repo.env.local",
841 "shared": shared / ".repo.shared.env",
842 "repo": root / ".repo.env",
843 }
844 if scope not in files:844 ↛ 845line 844 didn't jump to line 845 because the condition on line 844 was never true
845 fail(f"unknown scope {scope!r}: local, shared, repo, or ci")
846 path = files[scope]
847 if not value:
848 existing = parse_env_file(path)
849 if key not in existing:849 ↛ 850line 849 didn't jump to line 850 because the condition on line 849 was never true
850 print(f" {key} is not set in {path}")
851 return
852 if not footman.confirm(f"Delete {key} from {path}?"):
853 print(" Left alone")
854 return
855 lines = [
856 line
857 for line in path.read_text(encoding="utf-8").splitlines()
858 if not line.strip().startswith(f"{key}=")
859 ]
860 path.write_text("\n".join(lines) + "\n", encoding="utf-8")
861 print(f" Deleted {key} from {path}")
862 return
863 try:
864 set_value(path, key, value)
865 except ValueError as error:
866 fail(str(error))
867 print(f" Set {key} in {path}")
868 order: dict[str, Source] = {
869 "repo": Source.repo,
870 "shared": Source.shared,
871 "local": Source.local,
872 }
873 written = order[scope]
874 # The pre-tasks hook exported the cascade into this process, so a
875 # bare environ check would call every file-defined key the
876 # shell's own and warn falsely; only a key the hook did not
877 # contribute is genuinely the shell's.
878 if environ.get(key) and key not in _APPLIED:
879 print(
880 f" Note: {key} is set in your shell's own environment, which"
881 " overrides every env file, so this value will not take effect"
882 " until that export is gone."
883 )
884 else:
885 for other_scope, source in order.items():
886 if source < written and key in parse_env_file(files[other_scope]):
887 print(
888 f" Note: {key} is also defined in {files[other_scope]}"
889 f" ({source.name}), which overrides {written.name}: this"
890 " value will not take effect."
891 )
892 print(" Restart your terminal (or the editor) for this to take effect.")
895def _uv_drift(root: Path) -> str:
896 """A DRIFT line when the running uv is not the lock's pin; else "".
898 uv rides the dev group, so the lock pins it exactly; the venv
899 tools follow the lock by construction, but uv itself is resolved
900 from the machine and can drift. A workspace without a lock has
901 no pin to judge against and answers "".
902 """
903 from livery.workshop._entry import locked_uv_version
905 pinned = locked_uv_version(root)
906 if not pinned:
907 return ""
908 probe = toolroom.uv.opts(nofail=True, recorded=False)("--version")
909 running = probe.stdout.split()[1] if probe.stdout.split()[1:] else ""
910 if probe.code != 0 or not running:910 ↛ 911line 910 didn't jump to line 911 because the condition on line 910 was never true
911 return "uv: ? (could not read the running version)"
912 if running != pinned:
913 return f"uv: DRIFT (running {running}, the lock pins {pinned})"
914 return ""
917def tool_profile(root: Path) -> tuple[str, ...]:
918 """The tools the declaration sites require on this host, each once.
920 The base's, the steps', the extensions', the plugins', the
921 packages' own contracts' and the project's, as
922 `livery.workshop._tools` reads them; a workspace with no package
923 requires the base's uv, since its `tasks.py` runs in the venv uv
924 makes. A requirement scoped to other hosts alone is none here.
925 """
926 from livery.workshop._tools import this_host, tool_names
928 return tool_names(root, this_host())
931def served_by(receipt: ToolReceipt) -> str:
932 """Who serves *receipt*'s tool: the host at the version it printed, or the store."""
933 if receipt.source == "host":
934 return f"host {receipt.answered}".rstrip()
935 return f"store {receipt.version}"
938def missing_host_tools(root: Path) -> tuple[str, ...]:
939 """The tools the workspace's packages need from the host that do not resolve.
941 A host tool, such as a C compiler, is one the store never installs:
942 the machine provides it or the build cannot run, so ``fm doctor``
943 and ``fm env.check`` name an absence before a build fails midway.
944 Each package's set answers the ``host-tools`` query, and the answers
945 join, sorted, each tool once.
946 """
947 from livery.workshop._packages import discover_packages
949 packages = discover_packages(root) if (root / "packages").is_dir() else ()
950 needed = {tool for package in packages for tool in _host_tools(package)}
951 return tuple(sorted(tool for tool in needed if shutil.which(tool) is None))
954def _host_tools(package: Package) -> tuple[str, ...]:
955 """What *package* needs the host to provide: its set's ``host-tools`` answer."""
956 from livery.workshop._queries import HOST_TOOLS, answer
958 return tuple(answer(package, HOST_TOOLS))
961def _set_ci_secret(root: Path, key: str, value: str) -> None:
962 """Store one CI secret through the forge protocol.
964 A settings write, so it rides the admin ladder like configure.
965 The protocol's secret store is write-only and carries no delete,
966 so an empty value is a refusal naming the forge's own controls.
967 """
968 from livery.forge import Unsupported
969 from livery.workshop._forge_lane import admin_repository
971 if not value:
972 fail(
973 f"the forge protocol stores secrets write-only and cannot"
974 f" delete one: remove {key} in the forge's own settings"
975 )
976 repo, _var = admin_repository(root)
977 try:
978 repo.configure(RepoConfig(secrets={key: value}))
979 except Unsupported as error:
980 fail(
981 f"this forge cannot store CI secrets: {error}\n"
982 " On GitHub the secret API needs the github-secrets extra:"
983 " install livery-forge[github-secrets]."
984 )
985 print(f" {key}: stored as a CI secret (write-only; the value never reads back)")
986 committed = parse_env_file(root / ".repo.env")
987 if key not in committed:987 ↛ exitline 987 didn't return from function '_set_ci_secret' because the condition on line 987 was always true
988 print(
989 f" note: {key} is not declared in the committed .repo.env, so"
990 " the emitted entry step will not carry it into CI jobs;"
991 f" declare it with `{footman.prog()} env.set {key}"
992 " --scope=repo` (any value) to give the secret its slot"
993 )
996@env.task(name="check")
997def env_check() -> int:
998 """Verify this shell against the tools the sites require.
1000 Run it bare from the session being checked: a freshly entered
1001 shell would report itself, not yours.
1003 Every required tool must have a receipt, and every claim that
1004 receipt makes must hold here: the store wrote it to say what it
1005 installed, so it is what gets checked rather than a guess about
1006 where a tool of that name might live. A required tool with no
1007 receipt is a miss even when something of its name is on PATH,
1008 because what would run then is whatever the host happens to carry
1009 rather than the version this checkout pins. A receipt the lock has
1010 moved under is drift, and a miss prints the PATH breakdown and the
1011 remedy. With a lock, the stubs under `typings/` are counted, and
1012 their absence is a problem too.
1013 """
1014 from livery.workshop._tools import (
1015 TYPINGS,
1016 current_lock,
1017 has_index,
1018 receipt_gap,
1019 store_cannot_supply,
1020 stubs_present,
1021 tool_receipts,
1022 )
1023 from livery.workshop._tools import drift as receipt_drift
1025 root, _cwd = _workspace()
1026 problems: list[str] = []
1027 bin_dir = venv_bin(root)
1028 said = receipt_drift(root)
1029 written = tool_receipts(root)
1030 for tool in tool_profile(root):
1031 verdict = said.get(tool, "")
1032 receipt = written.get(tool)
1033 if receipt is None:
1034 problems.append(
1035 f"{tool}: MISSING (no receipt; `{footman.prog()} sync` writes one)"
1036 + (f" ({verdict})" if verdict else "")
1037 )
1038 continue
1039 if gap := receipt_gap(tool, receipt, bin_dir):1039 ↛ 1040line 1039 didn't jump to line 1040 because the condition on line 1039 was never true
1040 problems.append(f"{tool}: {gap}" + (f" ({verdict})" if verdict else ""))
1041 continue
1042 if verdict.startswith("DRIFT"):
1043 problems.append(f"{tool}: {verdict}")
1044 continue
1045 if verdict:
1046 print(f" {tool}: on PATH; {verdict}")
1047 else:
1048 print(f" {tool}: receipt ok; {served_by(receipt)}")
1049 if tool == "uv":
1050 drift = _uv_drift(root)
1051 if drift:1051 ↛ 1052line 1051 didn't jump to line 1052 because the condition on line 1051 was never true
1052 problems.append(drift)
1053 for tool in missing_host_tools(root):
1054 problems.append(
1055 f"{tool}: MISSING (a host compiler; install the platform"
1056 " toolchain: xcode-select --install on macOS,"
1057 " build-essential on Debian)"
1058 )
1059 if has_index(root) and current_lock(root) is not None:
1060 held = stubs_present(root)
1061 if held:
1062 print(f" stubs: {held} in {TYPINGS}/")
1063 else:
1064 problems.append(
1065 f"stubs: MISSING; run `{footman.prog()} toolroom.restub` to write"
1066 f" them into {TYPINGS}/"
1067 )
1068 if not problems:
1069 print(" environment ok: every required tool resolves")
1070 return 0
1071 for problem in problems:
1072 print(f" {problem}")
1073 print(" PATH:")
1074 for index, entry in enumerate(os.environ.get("PATH", "").split(os.pathsep), 1):
1075 marker = "" if Path(entry).is_dir() else " (missing)"
1076 print(f" {index:>2} {entry}{marker}")
1077 unsupplied = store_cannot_supply(root)
1078 if unsupplied:
1079 # Nothing is locked, so `sync` would supply nothing: the remedy
1080 # is the declaration and the lock, in that order.
1081 print(
1082 " The tools are what the base, the extensions, the plugins, the"
1083 " packages and the project require."
1084 )
1085 for line in unsupplied.splitlines():
1086 print(f" {line}" if line else "")
1087 else:
1088 print(
1089 " The tools are what the base, the extensions, the plugins, the"
1090 " packages and the project require."
1091 f" Run `{footman.prog()} sync` to materialise them, or enter the"
1092 f" environment with `{footman.prog()} shell`."
1093 )
1094 return 1