livery.workshop._devenv¶
livery.workshop._devenv ¶
fm devenv: local development environments by name, in docker or on the host.
An environment is a forge with its runners and its seeded accounts,
brought up by name, kept until removed, and removed whole by one
verb. Its state is one directory under the runner's data directory,
forge-dev/envs/<name>/: the forge's data, the runners' registrations
and working directories, the seed's credentials, the port it took, the
pid files of its processes, and what a pass of the loop places there:
each variable an extension declares with a directory of its own
({place} in its [env] table). A tool's home placed there, say
one that keeps the remotes a release writes, names the environment's
forge and goes with the environment. A job's own placement is under
the runner's temporary directory for that job, which the runner
creates in its working directory and removes after the job. The caches
every environment shares, the tool store, uv's cache and footman's
data for the jobs, live beside them in forge-dev/cache/, and removing
an environment removes none of them. A new environment is warm from
its first job, except for what a job places in its own directory: every
job starts without it, and so does the first pass on a new
environment.
A removal takes the whole directory or refuses. A part this user may not remove, such as a file a build container left owned by root, is named with the command that makes it removable, and nothing is stopped or removed (livery.workshop._devenv.remove).
Host mode runs Gitea and its runners as processes of this machine,
from the gitea and gitea_runner records the store supplies; no
system service, no daemon registered with the operating system, so
fm devenv.rm leaves no trace. Docker mode is the compose rig
fm forge.dev.up runs, the one environment named dev, until the
rig takes a name of its own. A runner is labelled
<env>-<host>-<arch>-<nn>, the host and architecture its own.
Classes:
| Name | Description |
|---|---|
Environment |
One environment as its directory holds it. |
Functions:
| Name | Description |
|---|---|
rig_dir |
The rig's own directory under the runner's data directory. |
envs_dir |
Where the environments live, one directory each. |
cache_dir |
The caches every environment shares. |
this_host |
This machine's host key, |
runner_label |
The label a runner registers under: |
parse_runners |
The runner shapes spec names, one per runner, in order. |
environment |
The environment name as its directory records it; a refusal for a bad name. |
environments |
Every environment the rig holds, by name. |
daemon_environment |
The environment a daemon starts with: environ without the checkout's own. |
spawn_detached |
Start argv as a process of its own that outlives this one; its pid. |
stop |
Stop the process pid and wait for it to go; whether it went. |
free_port |
A TCP port nothing listens on right now. |
binary |
The executable of name at version from the store; supplied when absent. |
app_ini |
Gitea's configuration for env on port: sqlite, actions on, no ssh. |
runner_config |
The runner's configuration: the rig's shared caches, in every job's environment. |
up_host |
Bring env up in host mode: Gitea, the seed, then each runner. |
up_docker |
Bring the docker-mode environment up through the compose rig. |
down |
Stop env's processes and keep its directory; the lines to print. |
remove |
Stop env and remove its directory whole; the lines to print. |
removal_blocker |
Why this user cannot remove path whole; empty when every part of it can go. |
remove_tree |
Remove path whole, going on past each part that refuses; what stayed. |
purge_cache |
Remove the rig's shared caches, naming each; the lines to print. |
describe |
One line on env: its mode, its URL, and what runs. |
devenv_up |
Bring an environment up by name; idempotent, and the recovery procedure. |
devenv_ls |
List the environments: mode, URL, and what runs. |
devenv_down |
Stop an environment's processes and keep its state. |
devenv_rm |
Stop an environment and remove its directory; the caches stay unless asked. |
Attributes:
| Name | Type | Description |
|---|---|---|
devenv |
|
|
MODES |
Where an environment runs: as processes of this machine, or in the compose rig. |
|
DEFAULT_ENV |
The environment a verb addresses when none is named. |
|
GITEA_VERSION |
The Gitea release the |
|
RUNNER_VERSION |
The runner release the |
|
ADMIN |
The seeded administrator, the same on every environment. |
|
ORG |
The seeded organisation the loop's repositories live in. |
|
CACHES |
The rig's shared caches under |
|
HEALTH_TIMEOUT |
How long |
|
TASKKILL |
Windows' process killer, for |
|
SPAWN |
Callable[..., int]
|
|
ALIVE |
Callable[[int], bool]
|
|
STOP |
Callable[..., bool]
|
|
UNLINK |
Callable[[str], None]
|
|
BINARY |
Callable[..., Path]
|
|
HEALTHY |
Callable[[str], bool]
|
|
API |
Callable[..., int]
|
|
MODES
module-attribute
¶
Where an environment runs: as processes of this machine, or in the compose rig.
DEFAULT_ENV
module-attribute
¶
The environment a verb addresses when none is named.
GITEA_VERSION
module-attribute
¶
The Gitea release the gitea record supplies for host mode.
RUNNER_VERSION
module-attribute
¶
The runner release the gitea_runner record supplies for host mode.
ADMIN
module-attribute
¶
The seeded administrator, the same on every environment.
CACHES
module-attribute
¶
The rig's shared caches under forge-dev/cache/, one directory each.
HEALTH_TIMEOUT
module-attribute
¶
How long up waits for Gitea to answer its health endpoint.
Environment
dataclass
¶
One environment as its directory holds it.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
The environment's name, its directory's. |
mode |
str
|
|
directory |
Path
|
Where its state lives. |
Methods:
| Name | Description |
|---|---|
runner_dir |
Runner number's directory. |
variables |
The variables extensions declare, placed for a pass on this environment. |
values |
The env file's pairs; empty when there is none yet. |
update |
Set updates in the env file, key by key, keeping the rest. |
runner_dir ¶
variables ¶
The variables extensions declare, placed for a pass on this environment.
Each by name, to the value it takes against environ. The pass
forms the environment of the processes it starts, so one
environ carries wins unless the declaration says always,
and a value naming {place} takes this environment's
directory, so what the pass and the processes it starts keep
there goes with the environment. Each job a runner takes places
its own under the job's temporary directory, which
setup.sh github names, so no two of the pass and its jobs
share one.
Raises:
| Type | Description |
|---|---|
Failed
|
when two of extensions declare one variable. |
Source code in packages/workshop/src/livery/workshop/_devenv.py
values ¶
The env file's pairs; empty when there is none yet.
Source code in packages/workshop/src/livery/workshop/_devenv.py
update ¶
Set updates in the env file, key by key, keeping the rest.
Source code in packages/workshop/src/livery/workshop/_devenv.py
runner_label ¶
The label a runner registers under: <env>-<host>-<arch>-<nn>.
parse_runners ¶
The runner shapes spec names, one per runner, in order.
A comma-separated list of host, or host*<n> for that many.
Container shapes come with the container setups and refuse here
by name.
Source code in packages/workshop/src/livery/workshop/_devenv.py
environment ¶
environment(name: str) -> Environment
The environment name as its directory records it; a refusal for a bad name.
Source code in packages/workshop/src/livery/workshop/_devenv.py
environments ¶
environments() -> tuple[Environment, ...]
Every environment the rig holds, by name.
Source code in packages/workshop/src/livery/workshop/_devenv.py
daemon_environment ¶
The environment a daemon starts with: environ without the checkout's own.
A daemon inherits the entered environment on purpose: the store's
node on PATH is what the runner's JavaScript actions need. What it
must not inherit is the checkout the verb ran from: VIRTUAL_ENV
and UV_RUN_RECURSION_DEPTH, which uv sets for one command, and
that venv's bin directory leading PATH. A job's own setup enters
its own venv, and a runner whose PATH led with another checkout's
would resolve a tool there, at that checkout's version, ahead of
the job's lock, and print uv's warning on every sync.
Source code in packages/workshop/src/livery/workshop/_devenv.py
spawn_detached ¶
Start argv as a process of its own that outlives this one; its pid.
Stdout and stderr go to log, appended; stdin is closed. The
child leads its own session (its own process group on Windows), so
the shell that ran the verb never owns it and down can stop it
by its pid alone. The environment is this process's own less the
checkout's (livery.workshop._devenv.daemon_environment).
Source code in packages/workshop/src/livery/workshop/_devenv.py
stop ¶
Stop the process pid and wait for it to go; whether it went.
Source code in packages/workshop/src/livery/workshop/_devenv.py
binary ¶
The executable of name at version from the store; supplied when absent.
The record comes from the workspace's catalogue and the artifact through the store's sources and the origin, verified by the record's digest; a second call finds it present and downloads nothing.
Source code in packages/workshop/src/livery/workshop/_devenv.py
app_ini ¶
app_ini(env: Environment, port: int) -> str
Gitea's configuration for env on port: sqlite, actions on, no ssh.
Source code in packages/workshop/src/livery/workshop/_devenv.py
runner_config ¶
runner_config(env: Environment, number: int, *, capacity: int = 4) -> str
The runner's configuration: the rig's shared caches, in every job's environment.
A variable an extension declares with a directory of its own is not
among them: the runner takes capacity jobs at once, so each job
places it under the temporary directory the runner creates for it,
where setup.sh github places it, whatever value the job inherits.
It goes with the job.
Source code in packages/workshop/src/livery/workshop/_devenv.py
up_host ¶
up_host(env: Environment, runners: tuple[str, ...], *, offline: bool = False) -> None
Bring env up in host mode: Gitea, the seed, then each runner.
Raises:
| Type | Description |
|---|---|
Failed
|
when env's directory holds files and no env file, which is what a refused removal leaves; the message names the removal that finishes it. |
Source code in packages/workshop/src/livery/workshop/_devenv.py
up_docker ¶
up_docker(env: Environment) -> None
Bring the docker-mode environment up through the compose rig.
Source code in packages/workshop/src/livery/workshop/_devenv.py
down ¶
down(env: Environment) -> list[str]
Stop env's processes and keep its directory; the lines to print.
Source code in packages/workshop/src/livery/workshop/_devenv.py
remove ¶
remove(env: Environment) -> list[str]
Stop env and remove its directory whole; the lines to print.
The directory is checked first (livery.workshop._devenv.removal_blocker): a part this user may not remove refuses before anything is stopped or removed, so the environment stays as it was. A delete refused after the check, a file that changed hands or is held open, leaves the processes stopped and every other part removed, the env file with them; a bring-up under the name then refuses until the removal runs again.
Raises:
| Type | Description |
|---|---|
Failed
|
when a part of the directory cannot be removed, naming it, the reason, and the command that makes it removable. |
Source code in packages/workshop/src/livery/workshop/_devenv.py
removal_blocker ¶
Why this user cannot remove path whole; empty when every part of it can go.
A file goes when its directory may be changed by the user removing it, whoever owns the file, so the answer names the first directory under path, or path's own parent, that this user may not change, with its owner, or the first one it may not list. A build container that writes into a mounted directory as root leaves such a directory. Windows decides by other rules: there a removal finds out by trying (livery.workshop._devenv.remove_tree), and the answer is empty.
Source code in packages/workshop/src/livery/workshop/_devenv.py
remove_tree ¶
Remove path whole, going on past each part that refuses; what stayed.
Every part this user may remove goes, so what stays is what refused and the directories above it. Each entry is a path and the system's reason, the deepest first. A file marked read-only on Windows is made writable and removed, as git marks its pack files.
Source code in packages/workshop/src/livery/workshop/_devenv.py
purge_cache ¶
Remove the rig's shared caches, naming each; the lines to print.
Each cache is checked before it is removed, as an environment is (livery.workshop._devenv.remove).
Raises:
| Type | Description |
|---|---|
Failed
|
when a part of a cache cannot be removed, naming it, the reason, and the command that makes it removable; the caches before it are removed. |
Source code in packages/workshop/src/livery/workshop/_devenv.py
describe ¶
describe(env: Environment) -> str
One line on env: its mode, its URL, and what runs.
Source code in packages/workshop/src/livery/workshop/_devenv.py
devenv_up ¶
devenv_up(env: Annotated[str, doc("the environment's name")] = DEFAULT_ENV, mode: Annotated[str, doc('host or docker')] = 'host', runners: Annotated[str, doc('the runners: host, or host*<n>')] = 'host', offline: Annotated[bool, doc('supply the binaries from the store alone')] = False) -> None
Bring an environment up by name; idempotent, and the recovery procedure.
Host mode starts Gitea and each runner as processes of this
machine from the store's records, seeds the administrator, the
API token and the organisation, registers each runner once under
its label, and makes the environment the cascade's current forge.
Docker mode is the compose rig, the one environment named dev.
Source code in packages/workshop/src/livery/workshop/_devenv.py
devenv_ls ¶
List the environments: mode, URL, and what runs.
Source code in packages/workshop/src/livery/workshop/_devenv.py
devenv_down ¶
devenv_down(env: Annotated[str, doc("the environment's name")] = DEFAULT_ENV) -> None
Stop an environment's processes and keep its state.
Source code in packages/workshop/src/livery/workshop/_devenv.py
devenv_rm ¶
devenv_rm(env: Annotated[str, doc("the environment's name")] = DEFAULT_ENV, purge_caches: Annotated[bool, doc("remove the rig's shared caches too")] = False) -> None
Stop an environment and remove its directory; the caches stay unless asked.