livery.workshop._env_tasks¶
livery.workshop._env_tasks ¶
The env group: enter, show, set, and verify the environment.
The cascade (livery.workshop._envfile) is the one config
mechanism; this module is every way it reaches a consumer: applied
to each fm run (a pre-tasks hook, environment always winning),
emitted for a shell or an agent or GitHub Actions, shown masked, set
scoped, and verified against the tool profile the present package
types derive.
Every task here repairs or diagnoses the environment, so none carries an availability gate: they must run on a cold checkout.
Classes:
| Name | Description |
|---|---|
EnvDelta |
What entering the environment adds: variables and PATH entries. |
Functions:
| Name | Description |
|---|---|
apply_cascade |
Fold the cascade into this run's environment; environment wins. |
apply_declared |
Set the variables the extensions of root's set declare into environ. |
sync_first |
Bring the checkout current before the command's first task runs. |
apply_entry |
Enter the venv and the receipts' tools into environ. |
runner_placements |
What a GitHub job places under the runner's temp: its caches and variables. |
with_runner_placements |
delta with the runner's placements for a GitHub job, unchanged elsewhere. |
windows_temp_policy |
The contract's |
with_runner_temp |
delta with |
venv_bin |
The venv's executables directory: |
workspace_delta |
The delta an entered shell needs for this workspace. |
emit_lines |
Serialise delta for dialect ( |
agent_delta |
The variables an agent session needs, selected by membership. |
rung_file |
Write the secrets the entry step carries into the shared slot's file. |
github_persist |
Append delta to GITHUB_ENV and GITHUB_PATH; what was written. |
env_emit |
Emit the environment for evaluation by a shell. |
env_show |
Show the cascade: sources, values, and the PATH breakdown. |
env_set |
Set or delete one variable in the chosen scope's file. |
tool_profile |
The tools the declaration sites require on this host, each once. |
served_by |
Who serves receipt's tool: the host at the version it printed, or the store. |
missing_host_tools |
The tools the workspace's packages need from the host that do not resolve. |
env_check |
Verify this shell against the tools the sites require. |
Attributes:
| Name | Type | Description |
|---|---|---|
NEVER_AGENT |
|
|
env |
|
|
WINDOWS_TEMP_VALUES |
|
|
START_PATH_VARIABLE |
|
EnvDelta
dataclass
¶
apply_cascade ¶
apply_cascade(inv: Invocation) -> None
Fold the cascade into this run's environment; environment wins.
Every fm command sees the repo's declared environment, so a
cold shell still runs with the tokens and settings the files
hold. Only absent keys are written, and what the hook itself
contributed is remembered: those values look pre-existing to a
later load, and the emitters must not misread them as the
shell's own. The variables the workspace's extensions declare
follow (apply_declared).
Source code in packages/workshop/src/livery/workshop/_env_tasks.py
apply_declared ¶
Set the variables the extensions of root's set declare into environ.
On a CI job a value naming {place} takes the job's own
directory: RUNNER_TEMP on a GitHub or Gitea job, .workshop
under CI_PROJECT_DIR on a GitLab one. Off a CI job it is not
set, and a desk keeps its own. A variable environ already
carries keeps its value, its declaration's always included: the
job's entry already placed it where the job's environment was
formed, and a nested run keeps the value its parent set. The
cascade's files count as the environment here, since they are folded
in first. What the hook contributes is remembered in _APPLIED. A
declaration that cannot be read costs these variables alone, said on
stderr, never the command: the mount and fm sync name it.
Returns:
| Type | Description |
|---|---|
dict[str, str]
|
The variables written, each to its value. |
Source code in packages/workshop/src/livery/workshop/_env_tasks.py
sync_first ¶
sync_first(inv: Invocation, task: Any) -> None
Bring the checkout current before the command's first task runs.
Once per process, at the first task's per-task moment, which is
inside the run: discovery also runs in the child that rebuilds the
completion manifest, where a sync would run on a Tab press. The
sync runs on the workspace above the task's directory and decides
from the checkout's receipts (livery.workshop._reconcile.apply);
the steps it runs are recorded as the task's own. A sync that wrote
receipts this process entered without enters again, into the
task's own environment, task.env: the task's body, the processes
it starts and the tasks it calls read it. Never os.environ: inside
a task footman notes that write as a misuse, and a workspace's notes
policy can fail the task for it.
Source code in packages/workshop/src/livery/workshop/_env_tasks.py
apply_entry ¶
Enter the venv and the receipts' tools into environ.
The same PATH entries and variables env.emit hands an entered
shell, so every fm invocation resolves the locked tools whatever
launched it: an agent's shell, a CI step, a bare terminal. The
cascade hook enters the process environment before the run starts,
and every task starts from it; the per-task hook enters a task's
own environment (livery.workshop._env_tasks.sync_first). The
emission leads PATH in its own order, the venv's bin first and the
tools after it, and the rest of PATH follows; an entry the emission
names moves to its place in front, since a tool directory ahead of
the venv would shadow the venv's pytest and mypy with the store's
plain ones. A variable environ already has wins, as the cascade's
do, and what the hook contributes is remembered in _APPLIED. A
receipts directory holding a file that is not a receipt costs the
tools' half alone, said on stderr, never the command. Idempotent: a
second application changes nothing.
Returns:
| Type | Description |
|---|---|
tuple[str, ...]
|
The PATH entries that were not on PATH before, in order. |
Source code in packages/workshop/src/livery/workshop/_env_tasks.py
runner_placements ¶
runner_placements(environ: dict[str, str], variables: Iterable[DeclaredVariable] = ()) -> dict[str, str]
What a GitHub job places under the runner's temp: its caches and variables.
The runner's temp is the working drive, where the checkout and the venv are; on a Windows runner the home directory is another drive, and a tool store there cannot hardlink into the checkout, nor uv's cache into the venv. The entry script exports the same paths before its sync and materialise, since it runs before any verb can; the workflow's cache step restores and saves the store under the data directory. Empty off a runner that names no temp.
uv's cache and the data directory take many processes at once, so a key the job's environment already sets keeps its value, and that value is what gets persisted: a runner with a persistent cache sets the key for every step and loses nothing, and the entry script, which exports the same keys for its own sync before it asks for the emission, hands them on to the steps after it, where an export of a step's shell never reaches by itself.
variables are the ones the workspace's extensions declare, which
apply_declared sets for each run where the environment carries
none. A value naming {place} takes the runner's temp, which is
the job's own. The emission forms the environment of the job's later
steps, so an always one beats a value the runner sets for every
job.
Raises:
| Type | Description |
|---|---|
Failed
|
when one of variables names |
Source code in packages/workshop/src/livery/workshop/_env_tasks.py
with_runner_placements ¶
with_runner_placements(delta: EnvDelta, environ: dict[str, str], variables: Iterable[DeclaredVariable] = ()) -> EnvDelta
delta with the runner's placements for a GitHub job, unchanged elsewhere.
Source code in packages/workshop/src/livery/workshop/_env_tasks.py
windows_temp_policy ¶
The contract's [ci] windows-temp, or the forge kind's default.
runner for a GitHub-shaped workspace: GitHub's hosted Windows
runners keep the workspace, the uv cache, and the runner's temp on
the fast working drive and the system temp on the slow system
drive. system for every other forge, whose runners are the
workspace's own. A value that is neither refuses naming both.
Source code in packages/workshop/src/livery/workshop/_env_tasks.py
with_runner_temp ¶
with_runner_temp(delta: EnvDelta, root: Path, environ: dict[str, str], *, platform: str = '') -> tuple[EnvDelta, str]
delta with TEMP and TMP under the runner's temp on a Windows leg.
The tests' files and the environments they build with uv then
share the working drive with the uv cache, which the runner keeps
under its temp, so uv links instead of copying. Returns the delta
and one line saying what happened. Nothing changes off Windows,
under the system policy, or when the runner names no
RUNNER_TEMP; the last two say so.
Source code in packages/workshop/src/livery/workshop/_env_tasks.py
venv_bin ¶
The venv's executables directory: Scripts on Windows, bin elsewhere.
The emission runs on the machine it enters, so the running platform is the right answer (livery.workshop.scripts_dir).
Source code in packages/workshop/src/livery/workshop/_env_tasks.py
workspace_delta ¶
The delta an entered shell needs for this workspace.
The cascade's managed values, plus the venv: VIRTUAL_ENV and
the venv's bin on PATH, so fm and the venv tools resolve.
The seam a tool store would extend. environ is the process
environment the cascade reads; None means os.environ.
Source code in packages/workshop/src/livery/workshop/_env_tasks.py
emit_lines ¶
Serialise delta for dialect (posix or pwsh).
One export per variable, then exactly one PATH prepend. A value
or name that cannot be spelled safely is refused: only the value
side is quoted, and export A B=1 exports A.
Source code in packages/workshop/src/livery/workshop/_env_tasks.py
agent_delta ¶
The variables an agent session needs, selected by membership.
Membership, not provenance: a session that already carries these variables would reclassify them as pre-existing, and a provenance filter would silently drop them. Secrets are included on purpose, availability is the point; the PATH family is excluded, it is composed per shell.
Source code in packages/workshop/src/livery/workshop/_env_tasks.py
rung_file ¶
Write the secrets the entry step carries into the shared slot's file.
The rendered entry step hands each declared key's CI secret to the
emission as RUNG_<KEY>. The non-empty ones land in
repo-shared.env under the runner's temp, readable by its owner
alone, and the cascade reads that file as the shared slot
(WORKSHOP_SHARED_ENV_FILE): the precedence of a machine's
shared file, gone with the runner. An absent secret arrives empty
and writes nothing, so it cannot mask a committed value; a job
whose secrets all arrive empty still points the slot at the empty
file, so a self-hosted runner's own shared file is never read.
Returns:
| Type | Description |
|---|---|
Path | None
|
The file's path, or None when the step carries no key at all. |
Raises:
| Type | Description |
|---|---|
Failed
|
on a step carrying keys whose runner names no
|
Source code in packages/workshop/src/livery/workshop/_env_tasks.py
github_persist ¶
Append delta to GITHUB_ENV and GITHUB_PATH; what was written.
Only under GitHub Actions, and never a secret name: the runner's env file is not a secret store, and the workflow's own secrets mechanism carries those.
Source code in packages/workshop/src/livery/workshop/_env_tasks.py
env_emit ¶
env_emit(target: Arg[Literal['posix', 'pwsh', '']] = '', agent: Annotated[bool, doc('the agent selection: membership, secrets included')] = False, github: Annotated[bool, doc('persist into GITHUB_ENV/GITHUB_PATH (Actions only)')] = False) -> Stdout[str]
Emit the environment for evaluation by a shell.
Bare: the entered-shell emission plus the interactive completion
hook. --agent: the membership selection for an agent session
(evaluated by its env file, so no completion hook). --github
writes the runner's env files, and on a Windows leg points
TEMP and TMP under the runner's temp when the contract's
[ci] windows-temp says runner, the default of a
GitHub-shaped workspace; alone it prints what it wrote, and with a
target it prints that same emission for the shell to evaluate, so
the entry step enters and persists in one call.
Source code in packages/workshop/src/livery/workshop/_env_tasks.py
env_show ¶
Show the cascade: sources, values, and the PATH breakdown.
Secrets are masked by the suffix convention unless --full.
The PATH breakdown numbers every entry and marks the missing
directories; duplicates are shown as they are.
Source code in packages/workshop/src/livery/workshop/_env_tasks.py
env_set ¶
env_set(key: Annotated[str, doc('the variable name')], value: Annotated[str, doc('the value; empty deletes the key')] = '', scope: Annotated[str, doc("local (this machine), shared (this person), repo (committed), ci (the forge's secret store)")] = 'local') -> None
Set or delete one variable in the chosen scope's file.
local writes .repo.env.local at the workspace root,
shared the person-wide .repo.shared.env in the runner's
config directory,
repo the committed .repo.env. ci writes a CI secret
through the forge protocol: under CI the entry step hands the
declared keys' secrets to the emission, which materialises them
into the shared slot, so a secret overrides the committed value
the way the shared file does on a machine. After a write the
higher-precedence sources are checked: a shadowed value is named
rather than discovered later.
Source code in packages/workshop/src/livery/workshop/_env_tasks.py
808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 | |
tool_profile ¶
The tools the declaration sites require on this host, each once.
The base's, the steps', the extensions', the plugins', the
packages' own contracts' and the project's, as
livery.workshop._tools reads them; a workspace with no package
requires the base's uv, since its tasks.py runs in the venv uv
makes. A requirement scoped to other hosts alone is none here.
Source code in packages/workshop/src/livery/workshop/_env_tasks.py
served_by ¶
served_by(receipt: ToolReceipt) -> str
Who serves receipt's tool: the host at the version it printed, or the store.
Source code in packages/workshop/src/livery/workshop/_env_tasks.py
missing_host_tools ¶
The tools the workspace's packages need from the host that do not resolve.
A host tool, such as a C compiler, is one the store never installs:
the machine provides it or the build cannot run, so fm doctor
and fm env.check name an absence before a build fails midway.
Each package's set answers the host-tools query, and the answers
join, sorted, each tool once.
Source code in packages/workshop/src/livery/workshop/_env_tasks.py
env_check ¶
env_check() -> int
Verify this shell against the tools the sites require.
Run it bare from the session being checked: a freshly entered shell would report itself, not yours.
Every required tool must have a receipt, and every claim that
receipt makes must hold here: the store wrote it to say what it
installed, so it is what gets checked rather than a guess about
where a tool of that name might live. A required tool with no
receipt is a miss even when something of its name is on PATH,
because what would run then is whatever the host happens to carry
rather than the version this checkout pins. A receipt the lock has
moved under is drift, and a miss prints the PATH breakdown and the
remedy. With a lock, the stubs under typings/ are counted, and
their absence is a problem too.
Source code in packages/workshop/src/livery/workshop/_env_tasks.py
996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 | |