Skip to content

livery.workshop._e2e

livery.workshop._e2e

fm ci.e2e: the CI and release story against a local forge.

The workshop's own development substrate: provision a scratch repository on the seeded local forge, and drive the emitted workflows through a real runner against the forge's own package registry, so the whole second world runs consequence-free before anything reaches a public forge. The loop's workspace splits its one runner's check leg into two shards, so every pass proves the slice, the gate job's fold and the durations row beside the gate itself.

The verb registers only where the workshop develops itself, the way fm forge.fixtures.record does: a consumer checkout does not carry it at all.

Classes:

Name Description
RunCount

How many runner runs the pass has followed so far; the timing table reads it.

Current

The environment a pass runs on, as the loop reads its forge from it.

Lane

One local forge the loop runs against, as the host and the runner reach it.

LoopMember

One member of the loop: its directory and the template it is born from.

Pass

What one pass carries between its scenarios.

Timing

What one scenario cost.

Scenario

One thing the loop proves, by name, with what must have run before it.

Functions:

Name Description
scrub_ci_markers

Remove CI's markers from environ; the names removed, in declared order.

child_environment

The environment a child the pass starts by hand begins with, extra over it.

edit_environments

Write values and drop remove where this task and every child read them.

dev_members

The members whose dev wheels the loop eats: the workshop and what a birth lists.

enter_environment

Run the pass on environment name, brought up first; the environment.

provision

Ensure the loop's repository, idempotently, with its secrets.

write_dev_index

Lay wheels out at folder as a simple index uv reads; folder.

checkout_index

Build what a newborn installs from root as a local index at folder; its URL.

build_content_named

Build package's wheel into out, at a version naming its content; the wheel.

require_dev_branch

Refuse unless root stands on a branch whose release verb is the dev act.

scratch_branch

Run a pass from a scratch branch where a build would be the release train.

start_over

Delete the loop's repository, its registry releases, and root; the lines.

judge_runs

One line per run; red fails with every red run named.

members_for

The loop's members named names, in the loop's order; all when empty.

landed_members

The loop's members a pass lands for steps naming named, by name, in order.

steps_declared_off

The steps extension name declares enabled = false, by <phase>.<step>.

extension_under_test

The list a pass births to test extension name, and the members it lands.

red_jobs_text

The failed jobs of run with the last lines of each log, as text to print.

loop_stack

The extensions a plain pass's birth lists, as their canonical list.

scenarios_for

The scenarios spec names, their needs added, in the registry's order.

daemon_needed

Whether any of scenarios needs the runner's docker socket.

run_scenario

Run scenario for pass_, timed; a failure is timed and marked, then raised.

timing_table

The lines a pass ends with: each scenario's time and runs, then the total.

record_pass

Put the pass's timings on the local loop series; the line to print.

e2e

Exercise the CI and release story on a local environment, by scenario.

Attributes:

Name Type Description
E2E_OWNER
E2E_REPO
DEV_MEMBER
KEPT_BY_SYNC
SHARDS
RUNS
CURRENT
CI_MARKERS tuple[str, ...]
LANES dict[str, Lane]
GitlabCall
LOOP_MEMBERS tuple[LoopMember, ...]
CONTRIBUTING_MEMBER
CONTRIBUTED_POINT
VERIFY_TASK
RATCHET_MEMBER
SITE
SCENARIOS tuple[Scenario, ...]
SETS dict[str, tuple[str, ...]]
LOOP_SERIES

E2E_OWNER module-attribute

E2E_OWNER = 'livery'

E2E_REPO module-attribute

E2E_REPO = 'ci-e2e-loop'

DEV_MEMBER module-attribute

DEV_MEMBER = 'packages/workshop'

KEPT_BY_SYNC module-attribute

KEPT_BY_SYNC = ('.venv', 'typings', '.workshop')

SHARDS module-attribute

SHARDS = 2

RUNS module-attribute

RUNS = RunCount()

CURRENT module-attribute

CURRENT = Current()

CI_MARKERS module-attribute

CI_MARKERS: tuple[str, ...] = ('CI', 'GITHUB_ACTIONS', 'GITEA_ACTIONS', 'GITLAB_CI')

LANES module-attribute

LANES: dict[str, Lane] = {'gitea': Lane('gitea', 'http://gitea:3000', 'GITEA_URL', 'GITEA_TOKEN', '/api/v1/version', 'act_runner'), 'gitlab': Lane('gitlab', 'http://gitlab:8929', 'GITLAB_URL', 'GITLAB_TOKEN', '/api/v4/version', 'gitlab-runner')}

GitlabCall module-attribute

GitlabCall = Callable[[str, str, str, 'dict[str, object] | None'], 'tuple[int, object]']

LOOP_MEMBERS module-attribute

LOOP_MEMBERS: tuple[LoopMember, ...] = (LoopMember('loop-echo', 'python-library'), LoopMember('loop-native', 'nanobind-module'), LoopMember('loop-cpp', 'cpp-package'))

CONTRIBUTING_MEMBER module-attribute

CONTRIBUTING_MEMBER = 'loop-echo'

CONTRIBUTED_POINT module-attribute

CONTRIBUTED_POINT = 'echo-audit'

VERIFY_TASK module-attribute

VERIFY_TASK = 'release.verify'

RATCHET_MEMBER module-attribute

RATCHET_MEMBER = 'loop-native'

SITE module-attribute

SITE = 'docs'

SCENARIOS module-attribute

SCENARIOS: tuple[Scenario, ...] = (Scenario('birth', (), _born), Scenario('verified-skip', ('birth',), lambda p: _prove_verified_skip(_at(p), p.forge)), Scenario('members', ('birth',), lambda p: _ensure_members(_at(p), p.members)), Scenario('ratchet', ('members',), lambda p: _prepare_ratchet(_at(p), p.forge)), Scenario('scoped-leg', ('ratchet',), lambda p: _prove_scoped_leg(_at(p), p.forge)), Scenario('unproven-push', ('scoped-leg',), lambda p: _prove_unproven_push(_at(p), p.forge)), Scenario('prose-leg', ('members',), lambda p: _prove_prose_leg(_at(p), p.forge)), Scenario('tests-leg', ('members',), lambda p: _prove_tests_leg(_at(p), p.forge)), Scenario('release', ('members',), lambda p: _release_act(_at(p), p.forge), daemon=True), Scenario('nightly', ('release',), lambda p: _prove_nightly(_at(p), p.forge)), Scenario('dispatched-gate', ('members',), lambda p: _prove_dispatched_gate(_at(p), p.forge)), Scenario('contributed-point', ('members',), lambda p: _prove_contributed_point(_at(p), p.forge)))

SETS module-attribute

SETS: dict[str, tuple[str, ...]] = {'develop': ('birth', 'verified-skip', 'members', 'scoped-leg', 'unproven-push'), 'release': ('birth', 'verified-skip', 'members', 'scoped-leg', 'unproven-push', 'release'), 'points': ('nightly', 'dispatched-gate', 'contributed-point'), 'extension': ('birth', 'members'), 'all': tuple(scenario.name for scenario in SCENARIOS)}

LOOP_SERIES module-attribute

LOOP_SERIES = LOOP

RunCount dataclass

RunCount(count: int = 0)

How many runner runs the pass has followed so far; the timing table reads it.

Attributes:

Name Type Description
count int

count class-attribute instance-attribute

count: int = 0

Current dataclass

Current(name: str = '', mode: str = '', url: str = '', token: str = '', label: str = 'ubuntu-latest')

The environment a pass runs on, as the loop reads its forge from it.

Attributes:

Name Type Description
name str

The environment's name; empty outside a pass.

mode str

host or docker.

url str

The forge's URL in host mode; empty in docker mode, where the cascade's shared file names it.

token str

The seeded API token in host mode.

label str

The runner label the loop's workspace names as its runner and its wheel platform; the hosted name in docker mode, the environment's own label in host mode.

name class-attribute instance-attribute

name: str = ''

mode class-attribute instance-attribute

mode: str = ''

url class-attribute instance-attribute

url: str = ''

token class-attribute instance-attribute

token: str = ''

label class-attribute instance-attribute

label: str = 'ubuntu-latest'

Lane dataclass

Lane(kind: str, alias: str, url_var: str, token_var: str, version_path: str, runner: str)

One local forge the loop runs against, as the host and the runner reach it.

Attributes:

Name Type Description
kind str

The forge kind, gitea or gitlab.

alias str

The forge as CI sees it, the compose service name and port, true on the host too through its hosts entry.

url_var str

The shared env key the seed writes the host-side URL to.

token_var str

The shared env key the seed writes the lane token to.

version_path str

The API path the hosts-entry probe reads.

runner str

The compose service of the lane's runner.

Methods:

Name Description
publish

The PyPI upload base for the loop's packages at base, the alias by default.

index

The simple index the loop's packages are read from.

kind instance-attribute

kind: str

alias instance-attribute

alias: str

url_var instance-attribute

url_var: str

token_var instance-attribute

token_var: str

version_path instance-attribute

version_path: str

runner instance-attribute

runner: str

host property

host: str

The compose hostname alone, for the hosts entry.

publish

publish(base: str = '') -> str

The PyPI upload base for the loop's packages at base, the alias by default.

Gitea keeps an owner's registry; GitLab a project's, addressed by its URL-encoded path.

Source code in packages/workshop/src/livery/workshop/_e2e.py
def publish(self, base: str = "") -> str:
    """The PyPI upload base for the loop's packages at *base*, the alias by default.

    Gitea keeps an owner's registry; GitLab a project's, addressed
    by its URL-encoded path.
    """
    base = base or self.alias
    if self.kind == "gitlab":
        from urllib.parse import quote

        project = quote(f"{E2E_OWNER}/{E2E_REPO}", safe="")
        return f"{base}/api/v4/projects/{project}/packages/pypi"
    return f"{base}/api/packages/{E2E_OWNER}/pypi"

index

index(base: str = '') -> str

The simple index the loop's packages are read from.

Source code in packages/workshop/src/livery/workshop/_e2e.py
def index(self, base: str = "") -> str:
    """The simple index the loop's packages are read from."""
    return f"{self.publish(base)}/simple"

LoopMember dataclass

LoopMember(name: str, template: str)

One member of the loop: its directory and the template it is born from.

Attributes:

Name Type Description
name str

The member's directory under packages/.

template str

The template whose verb, fm new.package.<template>, births it, and whose extensions the member's contract lists.

Methods:

Name Description
listed

The extensions the member's contract lists, from its template.

needs

The extensions the loop's root lists before the member is created.

holds

The extensions the member's set holds: its list and what it requires.

name instance-attribute

name: str

template instance-attribute

template: str

listed

listed() -> tuple[str, ...]

The extensions the member's contract lists, from its template.

The template's extensions in their canonical form, which a birth writes into the contract, so the loop and the birth name one list. The template is read from every available one, whatever the driving checkout's lists hold: the loop's workspace, not the driver's, creates the member.

Source code in packages/workshop/src/livery/workshop/_e2e.py
def listed(self) -> tuple[str, ...]:
    """The extensions the member's contract lists, from its template.

    The template's ``extensions`` in their canonical form, which a
    birth writes into the contract, so the loop and the birth name
    one list. The template is read from every available one,
    whatever the driving checkout's lists hold: the loop's
    workspace, not the driver's, creates the member.
    """
    from livery.workshop._composition import canonical
    from livery.workshop._extensions import installed_declaration
    from livery.workshop._seeds import available_templates

    declared = available_templates()[self.template]
    return canonical(declared.extensions, installed_declaration)

needs

needs() -> tuple[str, ...]

The extensions the loop's root lists before the member is created.

Those its template's chain needs: each template's extensions and the extension declaring it, since a creation installs nothing.

Source code in packages/workshop/src/livery/workshop/_e2e.py
def needs(self) -> tuple[str, ...]:
    """The extensions the loop's root lists before the member is created.

    Those its template's chain needs: each template's
    ``extensions`` and the extension declaring it, since a creation
    installs nothing.
    """
    from livery.workshop._seeds import chain_needs, template_chain

    return chain_needs(template_chain(self.template))

holds

holds() -> tuple[str, ...]

The extensions the member's set holds: its list and what it requires.

Source code in packages/workshop/src/livery/workshop/_e2e.py
def holds(self) -> tuple[str, ...]:
    """The extensions the member's set holds: its list and what it requires."""
    from livery.workshop._composition import closure
    from livery.workshop._extensions import installed_declaration

    return closure(self.listed(), installed_declaration)

Pass dataclass

Pass(forge: str, url: str, fresh: bool = False, root: Path | None = None, timings: list[Timing] = list(), extension: str = '', stack: tuple[str, ...] = (), members: tuple[str, ...] = ())

What one pass carries between its scenarios.

Attributes:

Name Type Description
forge str

The lane's kind, gitea or gitlab.

url str

The forge's host-side URL from the shared environment.

fresh bool

Whether the pass starts over from nothing.

root Path | None

The loop's workspace once birth has run; None before.

timings list[Timing]

One entry per scenario run, in order.

extension str

The extension under test; empty for a plain pass.

stack tuple[str, ...]

The extensions the birth lists: the loop's own (livery.workshop._e2e.loop_stack) or the extension under test's; empty for the stock list.

members tuple[str, ...]

The members the members scenario lands, by name; empty for all.

forge instance-attribute

forge: str

url instance-attribute

url: str

fresh class-attribute instance-attribute

fresh: bool = False

root class-attribute instance-attribute

root: Path | None = None

timings class-attribute instance-attribute

timings: list[Timing] = field(default_factory=list)

extension class-attribute instance-attribute

extension: str = ''

stack class-attribute instance-attribute

stack: tuple[str, ...] = ()

members class-attribute instance-attribute

members: tuple[str, ...] = ()

Timing dataclass

Timing(name: str, seconds: float, runs: int, failed: bool = False)

What one scenario cost.

Attributes:

Name Type Description
name str

The scenario.

seconds float

Its wall time.

runs int

The runner runs it followed.

failed bool

Whether it ended in a refusal or an error.

name instance-attribute

name: str

seconds instance-attribute

seconds: float

runs instance-attribute

runs: int

failed class-attribute instance-attribute

failed: bool = False

Scenario dataclass

Scenario(name: str, needs: tuple[str, ...], run: Callable[[Pass], None], daemon: bool = False)

One thing the loop proves, by name, with what must have run before it.

Attributes:

Name Type Description
name str

The name --scenario takes.

needs tuple[str, ...]

The scenarios this one builds on; a pass runs them first, once, whether or not they were named.

run Callable[[Pass], None]

The proof, given the pass.

daemon bool

Whether it needs the runner's docker socket: the release builds the native member's wheel through cibuildwheel on the runner, and nothing else does.

name instance-attribute

name: str

needs instance-attribute

needs: tuple[str, ...]

run instance-attribute

run: Callable[[Pass], None]

daemon class-attribute instance-attribute

daemon: bool = False

scrub_ci_markers

scrub_ci_markers(environ: MutableMapping[str, str]) -> tuple[str, ...]

Remove CI's markers from environ; the names removed, in declared order.

Source code in packages/workshop/src/livery/workshop/_e2e.py
def scrub_ci_markers(environ: MutableMapping[str, str]) -> tuple[str, ...]:
    """Remove CI's markers from *environ*; the names removed, in declared order."""
    removed = tuple(name for name in CI_MARKERS if name in environ)
    for name in removed:
        del environ[name]
    return removed

child_environment

child_environment(**extra: str) -> dict[str, str]

The environment a child the pass starts by hand begins with, extra over it.

The process environment over the task's. The pass is a serial task, so the process environment is the real one, where the pass writes its forge's own token after the task started; the task's carries what the git plugin wrote at the task's start, the tools' identity and the unsigned setting, which the process environment lacks. A spawn given an explicit environment takes neither by itself.

Source code in packages/workshop/src/livery/workshop/_e2e.py
def child_environment(**extra: str) -> dict[str, str]:
    """The environment a child the pass starts by hand begins with, *extra* over it.

    The process environment over the task's. The pass is a serial task,
    so the process environment is the real one, where the pass writes
    its forge's own token after the task started; the task's carries
    what the git plugin wrote at the task's start, the tools' identity
    and the unsigned setting, which the process environment lacks. A
    spawn given an explicit environment takes neither by itself.
    """
    return {**footman.current().env, **os.environ, **extra}

edit_environments

edit_environments(values: Mapping[str, str], *, remove: Sequence[str] = ()) -> tuple[str, ...]

Write values and drop remove where this task and every child read them.

The pass is a serial task, so os.environ in it is the real environment, which a child given an explicit environment built from it inherits; footman's own run and the store's tool handles spawn from the task's ctx.env, the environment the task started with, so the same edit lands there too. Without the second write a git the pass runs through the store commits without the identity and the unsigned setting, which a hosted runner showed. Returns the names removed from the process environment, in remove's order.

Source code in packages/workshop/src/livery/workshop/_e2e.py
def edit_environments(
    values: Mapping[str, str], *, remove: Sequence[str] = ()
) -> tuple[str, ...]:
    """Write *values* and drop *remove* where this task and every child read them.

    The pass is a serial task, so ``os.environ`` in it is the real
    environment, which a child given an explicit environment built from
    it inherits; footman's own ``run`` and the store's tool handles
    spawn from the task's ``ctx.env``, the environment the task started
    with, so the same edit lands there too. Without the second write a
    git the pass runs through the store commits without the identity
    and the unsigned setting, which a hosted runner showed. Returns the
    names removed from the process environment, in *remove*'s order.
    """
    from livery.footman import current

    environments: list[MutableMapping[str, str]] = [os.environ, current().env]
    removed = tuple(name for name in remove if name in os.environ)
    for environ in environments:
        environ.update(values)
        for name in remove:
            environ.pop(name, None)
    return removed

dev_members

dev_members(root: Path, extensions: Sequence[str] | None = None) -> tuple[str, ...]

The members whose dev wheels the loop eats: the workshop and what a birth lists.

Directory names, the workshop first, then each member that ships an extension a birth lists, and each dependency after the first member that names it, once. An edge of every kind counts: the wheel the runner installs resolves all of them from the loop's registry, and a member the closure does not reach publishes nothing there. An extension depends on the workshop, never the other way round, so the workshop's closure alone leaves the newborn's listed extensions nothing to install. extensions is the stack a birth lists, the stock list when None.

Raises:

Type Description
Failed

when root has no workshop member to eat.

Source code in packages/workshop/src/livery/workshop/_e2e.py
def dev_members(root: Path, extensions: Sequence[str] | None = None) -> tuple[str, ...]:
    """The members whose dev wheels the loop eats: the workshop and what a birth lists.

    Directory names, the workshop first, then each member that ships
    an extension a birth lists, and each dependency after the first
    member that names it, once. An edge of every kind counts: the
    wheel the runner installs resolves all of them from the loop's
    registry, and a member the closure does not reach publishes
    nothing there. An extension depends on the workshop, never the
    other way round, so the workshop's closure alone leaves the
    newborn's listed extensions nothing to install. *extensions* is
    the stack a birth lists, the stock list when None.

    Raises:
        Failed: when *root* has no workshop member to eat.
    """
    from livery.workshop._extensions import SELF, distribution_of, listing
    from livery.workshop._new_project import birth_extensions
    from livery.workshop._packages import discover_packages

    by_path = {package.path: package for package in discover_packages(root)}
    workshop = by_path.get(DEV_MEMBER)
    if workshop is None:
        fail(f"{root}: no {DEV_MEMBER} member; the loop eats the workshop's dev wheels")
    listed = birth_extensions([SELF]) if extensions is None else extensions
    stock = {distribution_of(listing(entry).name) for entry in listed}
    shipping = sorted(
        (p for p in by_path.values() if p.name in stock and p is not workshop),
        key=lambda package: package.path,
    )
    ordered: list[str] = []
    pending = [workshop, *shipping]
    while pending:
        package = pending.pop(0)
        if package.member in ordered:
            continue
        ordered.append(package.member)
        pending.extend(
            by_path[edge.path] for edge in package.depends if edge.path in by_path
        )
    return tuple(ordered)

enter_environment

enter_environment(name: str, extensions: Sequence[str], *, fresh: bool = False) -> Environment

Run the pass on environment name, brought up first; the environment.

A host-mode environment is brought up; with fresh it is removed first, so the pass gets a new forge, and so is a directory that a refused removal left. A removal that cannot take the whole directory refuses, and the pass stops there (livery.workshop._devenv.remove). The forge's URL and token then go into the pass's environment (_enter_host). A docker-mode environment is the compose rig, used as it is, fresh or not.

In both modes the pass and every process it starts then run with the variables the set of extensions, the list the loop's workspace is born with, declares, each one naming {place} placed in the environment's directory. A tool's home placed there goes with the environment: a release writes a remote into it that names the environment's forge, and a home shared with an earlier pass would keep that remote after the forge is gone, so a later install that asks the remotes tries it and fails. A fresh pass starts with nothing an earlier one wrote there.

Source code in packages/workshop/src/livery/workshop/_e2e.py
def enter_environment(
    name: str, extensions: Sequence[str], *, fresh: bool = False
) -> Environment:
    """Run the pass on environment *name*, brought up first; the environment.

    A host-mode environment is brought up; with *fresh* it is removed
    first, so the pass gets a new forge, and so is a directory that a
    refused removal left. A removal that cannot take the whole
    directory refuses, and the pass stops there
    ([livery.workshop._devenv.remove][]). The forge's URL and token then
    go into the pass's environment (`_enter_host`). A docker-mode
    environment is the compose rig, used as it is, fresh or not.

    In both modes the pass and every process it starts then run with
    the variables the set of *extensions*, the list the loop's
    workspace is born with, declares, each one naming ``{place}``
    placed in the environment's directory. A tool's home placed there
    goes with the environment: a release writes a remote into it that
    names the environment's forge, and a home shared with an earlier
    pass would keep that remote after the forge is gone, so a later
    install that asks the remotes tries it and fails. A fresh pass
    starts with nothing an earlier one wrote there.
    """
    from livery.workshop import _devenv

    place = _devenv.environment(name)
    if fresh and place.mode != "docker" and place.directory.is_dir():
        for line in _devenv.remove(place):
            print(line)
        place = _devenv.environment(name)
    if place.mode == "docker":
        CURRENT.name, CURRENT.mode = name, "docker"
    else:
        _devenv.up_host(place, ("host",))
        place = _devenv.environment(name)
        _enter_host(place.values(), name)
    from livery.workshop._composition import closure
    from livery.workshop._extensions import installed_declaration

    held = closure(extensions, installed_declaration)
    variables = place.variables(held, os.environ)
    edit_environments(variables)
    for variable, value in variables.items():
        print(f"  {variable}: {value}")
    return place

provision

provision(kind: str = 'gitea') -> None

Ensure the loop's repository, idempotently, with its secrets.

The repository is created on the seeded organisation when absent and reused when present. UV_PUBLISH_TOKEN is written as an Actions secret with the forge token's value, because the forge's own package registry authenticates with the same credential as its API. Re-running is the recovery procedure.

Source code in packages/workshop/src/livery/workshop/_e2e.py
def provision(kind: str = "gitea") -> None:
    """Ensure the loop's repository, idempotently, with its secrets.

    The repository is created on the seeded organisation when absent
    and reused when present. ``UV_PUBLISH_TOKEN`` is written as an
    Actions secret with the forge token's value, because the forge's
    own package registry authenticates with the same credential as
    its API. Re-running is the recovery procedure.
    """
    from livery.forge import ForgeError, RepoConfig

    forge, token = _dev_forge(kind)
    try:
        existing = forge.get_repo(E2E_OWNER, E2E_REPO)
    except ForgeError as error:
        fail(
            f"the local forge did not answer: {error}. Is the container"
            f" up? `{footman.prog()} forge.dev.up --profile=gitea`"
        )
    if existing is None:
        forge.create_repo(
            E2E_OWNER,
            E2E_REPO,
            private=False,
            description="The workshop's local CI loop. Scratch; recreated freely.",
        )
        print(f"  created {E2E_OWNER}/{E2E_REPO}")
    else:
        print(f"  reusing {E2E_OWNER}/{E2E_REPO}")
    repo = forge.repository(E2E_OWNER, E2E_REPO)
    if kind == "gitlab":
        _make_project_public(os.environ.get(_lane(kind).url_var, ""), token)
        print("  project: public, so its registry reads without a credential")
    # Three secrets, all the lane token: the registry credential the
    # publish reads, the forge lane's everyday token, and the admin
    # ladder's, because the emitted governance job asks for it and
    # the seeded admin account holds every grant anyway. GitLab's jobs
    # push through a fourth, a project access token, since the job
    # token cannot push.
    secrets = {
        "UV_PUBLISH_TOKEN": token,
        "FORGE_TOKEN": token,
        "FORGE_ADMIN_TOKEN": token,
    }
    if kind == "gitlab":
        secrets["GITLAB_PUSH_TOKEN"] = _mint_push_token(
            os.environ.get(_lane(kind).url_var, ""), token
        )
    repo.configure(RepoConfig(secrets=secrets))
    print(f"  secrets set: {', '.join(secrets)}")

write_dev_index

write_dev_index(folder: Path, wheels: Collection[Path]) -> Path

Lay wheels out at folder as a simple index uv reads; folder.

One directory per project, named as PEP 503 normalises it, holding the project's wheels and a page that links them, and a root page that links the projects. Whatever folder held before goes, so a wheel an earlier pass built is never offered again.

Source code in packages/workshop/src/livery/workshop/_e2e.py
def write_dev_index(folder: Path, wheels: Collection[Path]) -> Path:
    """Lay *wheels* out at *folder* as a simple index uv reads; *folder*.

    One directory per project, named as PEP 503 normalises it, holding
    the project's wheels and a page that links them, and a root page
    that links the projects. Whatever *folder* held before goes, so a
    wheel an earlier pass built is never offered again.
    """
    if folder.exists():
        shutil.rmtree(folder)
    folder.mkdir(parents=True)
    projects: dict[str, list[Path]] = {}
    for wheel in wheels:
        name = re.sub(r"[-_.]+", "-", wheel.name.split("-", 1)[0]).lower()
        projects.setdefault(name, []).append(wheel)
    for name, files in sorted(projects.items()):
        (folder / name).mkdir()
        for wheel in files:
            shutil.copy2(wheel, folder / name / wheel.name)
        _index_page(folder / name, sorted(wheel.name for wheel in files))
    _index_page(folder, [f"{name}/" for name in sorted(projects)])
    return folder

checkout_index

checkout_index(root: Path, folder: Path, extensions: Sequence[str] | None = None) -> str

Build what a newborn installs from root as a local index at folder; its URL.

The members are livery.workshop._e2e.dev_members: the workshop, what it depends on, and the extensions a birth lists. Each is built by build_content_named, at the version its manifest declares with a local segment naming its content, and livery.workshop._e2e.write_dev_index lays the wheels out. Named first in UV_INDEX, the index serves every distribution it holds, whatever its version, because uv takes a package from the first index that has it; every other package comes from the next. UV_FIND_LINKS would not do: a folder named there only adds candidates, and a stable release on PyPI beats a dev wheel (measured). This is how a workspace installs this checkout's code before a release, never the dev act, which on a main-family branch is the release train. extensions is the stack the birth lists, the stock list when None.

Source code in packages/workshop/src/livery/workshop/_e2e.py
def checkout_index(
    root: Path, folder: Path, extensions: Sequence[str] | None = None
) -> str:
    """Build what a newborn installs from *root* as a local index at *folder*; its URL.

    The members are [livery.workshop._e2e.dev_members][]: the workshop,
    what it depends on, and the extensions a birth lists. Each is built
    by `build_content_named`, at the version its manifest declares with
    a local segment naming its content, and
    [livery.workshop._e2e.write_dev_index][] lays the wheels out. Named
    first in ``UV_INDEX``, the index serves every distribution it holds,
    whatever its version, because uv takes a package from the first
    index that has it; every other package comes from the next.
    ``UV_FIND_LINKS`` would not do: a folder named there only adds
    candidates, and a stable release on PyPI beats a dev wheel
    (measured). This is how a workspace installs this checkout's code
    before a release, never the dev act, which on a main-family branch
    is the release train. *extensions* is the stack the birth lists,
    the stock list when None.
    """
    import tempfile

    from livery.workshop._packages import discover_packages

    members = set(dev_members(root, extensions))
    with tempfile.TemporaryDirectory() as scratch:
        built = Path(scratch) / "wheels"
        for package in discover_packages(root):
            if package.member in members:
                build_content_named(package, root, built)
        write_dev_index(folder, sorted(built.glob("*.whl")))
    return folder.as_uri()

build_content_named

build_content_named(package: Package, root: Path, out: Path) -> Path

Build package's wheel into out, at a version naming its content; the wheel.

The build reads a copy of the package's directory, without its build outputs and environments. The copy's version gains a local segment, a digest of the copy's files, so the wheel's file name changes whenever its content does. uv caches an installed wheel by its file name and the place it came from, and installs the cached copy again without reading a newer file of that name (measured). The package's own files stay as they are. root is the workspace package belongs to, whose stamp phase writes the version.

Raises:

Type Description
Failed

when nothing in the package's set answers its version, or adds a step to the stamp phase.

Source code in packages/workshop/src/livery/workshop/_e2e.py
def build_content_named(package: Package, root: Path, out: Path) -> Path:
    """Build *package*'s wheel into *out*, at a version naming its content; the wheel.

    The build reads a copy of the package's directory, without its build
    outputs and environments. The copy's version gains a local segment,
    a digest of the copy's files, so the wheel's file name changes
    whenever its content does. uv caches an installed wheel by its file
    name and the place it came from, and installs the cached copy again
    without reading a newer file of that name (measured). The package's
    own files stay as they are. *root* is the workspace *package*
    belongs to, whose stamp phase writes the version.

    Raises:
        Failed: when nothing in the package's set answers its version,
            or adds a step to the stamp phase.
    """
    import tempfile

    import livery.toolroom.tools as toolroom

    skipped = shutil.ignore_patterns(
        ".venv", "dist", "build", "__pycache__", "_docs", "*.egg-info"
    )
    with tempfile.TemporaryDirectory() as scratch:
        copy = Path(scratch) / "copy" / package.member
        shutil.copytree(package.directory, copy, ignore=skipped)
        _stamp_content(replace(package, directory=copy), root)
        built = Path(scratch) / "built"
        toolroom.uv.opts(cwd=root, recorded=False)(
            "build", "--wheel", "--out-dir", str(built), str(copy)
        )
        (wheel,) = built.glob("*.whl")
        out.mkdir(parents=True, exist_ok=True)
        return Path(shutil.copy2(wheel, out / wheel.name))

require_dev_branch

require_dev_branch(root: Path) -> None

Refuse unless root stands on a branch whose release verb is the dev act.

The loop builds the dev wheels it installs with workflow.release in this checkout, and the branch decides that verb's act. On main or a reserved workflow/ branch it is the release train, which opens a real release on this repository's forge, and a merged one publishes to the real index; a detached HEAD names no act at all.

Source code in packages/workshop/src/livery/workshop/_e2e.py
def require_dev_branch(root: Path) -> None:
    """Refuse unless *root* stands on a branch whose release verb is the dev act.

    The loop builds the dev wheels it installs with `workflow.release`
    in this checkout, and the branch decides that verb's act. On
    ``main`` or a reserved ``workflow/`` branch it is the release train,
    which opens a real release on this repository's forge, and a merged
    one publishes to the real index; a detached HEAD names no act at all.
    """
    from livery.workshop._release_driver import runs_the_train

    branch = git.current_branch(root)
    if branch and not runs_the_train(branch):
        return
    where = f"'{branch}'" if branch else "a detached HEAD"
    prog = footman.prog()
    fail(
        f"the loop builds its dev wheels with `{prog} workflow.release`, and on"
        f" {where} that is the release train, which opens a real release: start a"
        f" branch at this commit (`{prog} start chore/<slug>`) and run the loop there"
    )

scratch_branch

scratch_branch(root: Path | None, *, enabled: bool) -> Generator[None, None, None]

Run a pass from a scratch branch where a build would be the release train.

--from-main: a nightly's checkout stands on main, where the loop's first build is the release train, so the pass moves to chore/loop-<stamp> at the same commit before anything builds and returns afterwards, deleting the branch when it gained no commit. A checkout already on a dev branch, or none, is left alone. A dirty tree refuses naming the paths, so the scratch branch holds exactly the commit it started from.

Parameters:

Name Type Description Default
root Path | None

The driver checkout, None when the pass runs outside one.

required
enabled bool

Whether --from-main was asked.

required

Yields:

Type Description
None

Nothing; the pass runs inside.

Source code in packages/workshop/src/livery/workshop/_e2e.py
@contextlib.contextmanager
def scratch_branch(root: Path | None, *, enabled: bool) -> Generator[None, None, None]:
    """Run a pass from a scratch branch where a build would be the release train.

    ``--from-main``: a nightly's checkout stands on ``main``, where the
    loop's first build is the release train, so the pass moves to
    ``chore/loop-<stamp>`` at the same commit before anything builds
    and returns afterwards, deleting the branch when it gained no
    commit. A checkout already on a dev branch, or none, is left
    alone. A dirty tree refuses naming the paths, so the scratch branch
    holds exactly the commit it started from.

    Args:
        root: The driver checkout, None when the pass runs outside one.
        enabled: Whether ``--from-main`` was asked.

    Yields:
        Nothing; the pass runs inside.
    """
    from livery.workshop._release_driver import runs_the_train

    if root is None or not enabled:
        yield
        return
    branch = git.current_branch(root)
    if branch and not runs_the_train(branch):
        yield
        return
    dirty = git.dirty_paths(root)
    if dirty:
        fail(
            "--from-main starts a scratch branch at this commit, and the working"
            f" tree has changes: {', '.join(dirty)}; commit or discard them first"
        )
    origin = branch or git.head_sha(root)
    scratch = f"chore/loop-{datetime.now(UTC):%Y%m%dT%H%M%SZ}"
    git.create_branch(root, scratch)
    where = f"'{branch}'" if branch else "a detached HEAD"
    print(f"  from main: left {where} for {scratch} at {git.head_sha(root)[:12]}")
    try:
        yield
    finally:
        _leave_scratch(root, origin, scratch, branch)

start_over

start_over(lane: Forge, token: str, root: Path, *, url: str, wait: float = 120.0, kind: str = 'gitea') -> list[str]

Delete the loop's repository, its registry releases, and root; the lines.

Refuses while root holds commits its origin has not seen, since the repository they would land in is about to go. A repository or a release already gone is not an error: the next birth wants them absent, and a re-run of the reset is the recovery procedure. A delete the forge answers too slowly for the client completes on the server anyway, so the reset waits up to wait seconds for the repository to be gone before it refuses.

Source code in packages/workshop/src/livery/workshop/_e2e.py
def start_over(
    lane: Forge,
    token: str,
    root: Path,
    *,
    url: str,
    wait: float = 120.0,
    kind: str = "gitea",
) -> list[str]:
    """Delete the loop's repository, its registry releases, and *root*; the lines.

    Refuses while *root* holds commits its origin has not seen, since
    the repository they would land in is about to go. A repository or
    a release already gone is not an error: the next birth wants them
    absent, and a re-run of the reset is the recovery procedure. A
    delete the forge answers too slowly for the client completes on
    the server anyway, so the reset waits up to *wait* seconds for
    the repository to be gone before it refuses.
    """
    if (root / ".git").is_dir():
        unpushed = _unpushed_commits(root)
        if unpushed:
            listed = "\n".join(f"    {line}" for line in unpushed)
            fail(
                f"{root} holds commits its origin has not seen:\n{listed}\n"
                "  push or discard them before starting over"
            )
    lines: list[str] = []
    try:
        lane.delete_repo(E2E_OWNER, E2E_REPO)
    except ForgeError as error:
        if not _gone_within(lane, wait):
            raise ForgeError(
                f"{E2E_OWNER}/{E2E_REPO} is still on the dev forge after the"
                f" delete's wait: {error}"
            ) from error
        lines.append(
            f"  deleted {E2E_OWNER}/{E2E_REPO} on the dev forge (the delete"
            " outran the client's wait and finished on the server)"
        )
    else:
        lines.append(f"  deleted {E2E_OWNER}/{E2E_REPO} on the dev forge")
    purged = _purge(kind, url, token)
    lines.append(
        f"  purged {len(purged)} release(s) from the registry"
        + (f": {', '.join(purged)}" if purged else "")
    )
    if root.exists():
        _rmtree(root)
        lines.append(f"  removed {root}")
    return lines

judge_runs

judge_runs(repo: Repository, runs: tuple[Run, ...], *, branch: str = '') -> list[str]

One line per run; red fails with every red run named.

A failed run is red. A cancelled run is red too, unless a twin for the same head took over and completed green, in which case the twin's verdict stands and the line says so; a successor for a moved head means the watched sha is no longer the branch's and is named as red, since the loop watches a sha of its own. A cancellation nobody took over stays red rather than quietly passing.

Source code in packages/workshop/src/livery/workshop/_e2e.py
def judge_runs(
    repo: Repository, runs: tuple[Run, ...], *, branch: str = ""
) -> list[str]:
    """One line per run; red fails with every red run named.

    A failed run is red. A cancelled run is red too, unless a twin
    for the same head took over and completed green, in which case
    the twin's verdict stands and the line says so; a successor for a
    moved head means the watched sha is no longer the branch's and is
    named as red, since the loop watches a sha of its own. A
    cancellation nobody took over stays red rather than quietly
    passing.
    """
    from livery.workshop._runs import successor

    lines: list[str] = []
    failed: list[str] = []
    for run in runs:
        verdict: str = run.conclusion or run.status
        if run.conclusion == "cancelled":
            found = successor(repo, run, branch=branch)
            if found is None:
                verdict = "cancelled; no newer run for its head is known"
                failed.append(run.workflow)
            elif found.same_head and found.run.conclusion == "success":
                verdict = (
                    f"cancelled, superseded by run {found.run.id} for the same"
                    " head (success)"
                )
            elif found.same_head:
                verdict = (
                    f"cancelled, superseded by run {found.run.id} for the same head"
                    f" ({found.run.conclusion or found.run.status})"
                )
                failed.append(run.workflow)
            else:
                verdict = (
                    f"cancelled, superseded by run {found.run.id} for the moved head"
                    f" {found.run.head_sha[:12]}; the watched sha is no longer"
                    " the branch's"
                )
                failed.append(run.workflow)
        elif run.conclusion == "failure":
            failed.append(run.workflow)
        lines.append(f"  {run.workflow:14} {verdict}")
    if failed:
        names = ", ".join(failed)
        fail(f"red runs on the loop: {names}; logs: {repo.web_url()}/actions")
    return lines

members_for

members_for(names: Sequence[str] = ()) -> tuple[LoopMember, ...]

The loop's members named names, in the loop's order; all when empty.

Source code in packages/workshop/src/livery/workshop/_e2e.py
def members_for(names: Sequence[str] = ()) -> tuple[LoopMember, ...]:
    """The loop's members named *names*, in the loop's order; all when empty."""
    return tuple(member for member in LOOP_MEMBERS if not names or member.name in names)

landed_members

landed_members(named: Iterable[str]) -> tuple[str, ...]

The loop's members a pass lands for steps naming named, by name, in order.

A member lands for an extension a step names that its set holds and that no member whose set lies within its own holds too: the smaller member stands for that extension. loop-native's set holds loop-echo's, so a step naming python lands loop-echo alone, and one naming conan lands loop-native and loop-cpp. A pass carries the members its steps were written for, and no slower one besides.

Source code in packages/workshop/src/livery/workshop/_e2e.py
def landed_members(named: Iterable[str]) -> tuple[str, ...]:
    """The loop's members a pass lands for steps naming *named*, by name, in order.

    A member lands for an extension a step names that its set holds and
    that no member whose set lies within its own holds too: the smaller
    member stands for that extension. loop-native's set holds
    loop-echo's, so a step naming python lands loop-echo alone, and one
    naming conan lands loop-native and loop-cpp. A pass carries the
    members its steps were written for, and no slower one besides.
    """
    wanted = set(named)
    sets = {member.name: frozenset(member.holds()) for member in LOOP_MEMBERS}
    landed: list[str] = []
    for member in LOOP_MEMBERS:
        held = sets[member.name]
        own = set(held)
        for other, smaller in sets.items():
            if other != member.name and smaller < held:
                own -= smaller
        if own & wanted:
            landed.append(member.name)
    return tuple(landed)

steps_declared_off

steps_declared_off(name: str) -> tuple[str, ...]

The steps extension name declares enabled = false, by <phase>.<step>.

An extension pass turns each on in the newborn's root contract, so every step of the extension under test registers and runs.

Source code in packages/workshop/src/livery/workshop/_e2e.py
def steps_declared_off(name: str) -> tuple[str, ...]:
    """The steps extension *name* declares ``enabled = false``, by ``<phase>.<step>``.

    An extension pass turns each on in the newborn's root contract, so
    every step of the extension under test registers and runs.
    """
    from livery.workshop._extensions import declaration

    found = declaration(name)
    if found is None:
        return ()
    return tuple(record.name for record in found.additions.steps if not record.enabled)

extension_under_test

extension_under_test(name: str) -> tuple[tuple[str, ...], tuple[str, ...]]

The list a pass births to test extension name, and the members it lands.

The members are the loop's whose sets hold an extension name's steps name, by name (landed_members), so each step has something of its own to judge. The list is name and what those members' templates need (LoopMember.needs), as their canonical list: a creation installs nothing, so the root lists them before the members are created, and the set takes in what each requires. The steps name declares off are turned on in the newborn's contract (steps_declared_off), so each of its steps registers.

Raises:

Type Description
Failed

when no installed distribution declares name, naming the installed ones; when name registers no step.

Source code in packages/workshop/src/livery/workshop/_e2e.py
def extension_under_test(name: str) -> tuple[tuple[str, ...], tuple[str, ...]]:
    """The list a pass births to test extension *name*, and the members it lands.

    The members are the loop's whose sets hold an extension *name*'s
    steps name, by name (`landed_members`), so each step has something
    of its own to judge. The list is *name* and what those members'
    templates need (`LoopMember.needs`), as their canonical list: a
    creation installs nothing, so the root lists them before the
    members are created, and the set takes in what each requires. The
    steps *name* declares off are turned on in the newborn's contract
    (`steps_declared_off`), so each of its steps registers.

    Raises:
        Failed: when no installed distribution declares *name*, naming
            the installed ones; when *name* registers no step.
    """
    from livery.workshop._extensions import declaration, installed_extensions
    from livery.workshop._new_project import canonical_extensions

    found = declaration(name)
    if found is None:
        installed = ", ".join(installed_extensions()) or "none"
        fail(
            f"extension {name!r}: no installed distribution declares it;"
            f" the installed ones are {installed}"
        )
    steps = found.additions.steps
    if not steps:
        fail(
            f"extension {name!r} registers no step: a pass would have"
            " nothing of its own to run"
        )
    named = {extension for record in steps for extension in record.extensions}
    members = landed_members(named)
    needs = [needed for member in members_for(members) for needed in member.needs()]
    return tuple(canonical_extensions([name, *needs])), members

red_jobs_text

red_jobs_text(repo: Repository, run: Run, *, lines: int = 60) -> str

The failed jobs of run with the last lines of each log, as text to print.

A run that went red on the loop's forge is readable at its page on a desk; inside a hosted job the forge vanishes with the job, so the pass prints what the page would show. Every job that ended in failure is named with its log's tail; a run whose jobs all passed or never ran gives the header line alone.

Source code in packages/workshop/src/livery/workshop/_e2e.py
def red_jobs_text(repo: Repository, run: Run, *, lines: int = 60) -> str:
    """The failed jobs of *run* with the last *lines* of each log, as text to print.

    A run that went red on the loop's forge is readable at its page on
    a desk; inside a hosted job the forge vanishes with the job, so the
    pass prints what the page would show. Every job that ended in
    failure is named with its log's tail; a run whose jobs all passed
    or never ran gives the header line alone.
    """
    out = [f"  run {run.id} ended {run.conclusion}: {run.url or repo.web_url()}"]
    for job in repo.checks.jobs(run.id):
        if job.conclusion != "failure":
            continue
        tail = repo.checks.job_log(job.id).rstrip("\n").splitlines()[-lines:]
        out.append(f"  {job.name}: failure; the last {len(tail)} line(s) of its log:")
        out.extend(f"    {line}" for line in tail)
    return "\n".join(out)

loop_stack

loop_stack() -> tuple[str, ...]

The extensions a plain pass's birth lists, as their canonical list.

The stock list without the site, and what the loop's members' templates need (LoopMember.needs): a creation installs nothing, so the root lists them before the members are created. The site is the docs extension and every stock entry whose declaration requires it, directly or through another: the docs extension puts a docs job on every run of the loop's project, for a site nothing in a pass reads, and an extension that requires it brings it into the root's set. The pass proves the gate, the release train and the points, and fm ci.e2e --extension=docs proves the docs extension on its own. A stock entry no installed distribution declares requires nothing and stays.

Source code in packages/workshop/src/livery/workshop/_e2e.py
def loop_stack() -> tuple[str, ...]:
    """The extensions a plain pass's birth lists, as their canonical list.

    The stock list without the site, and what the loop's members'
    templates need (`LoopMember.needs`): a creation installs nothing,
    so the root lists them before the members are created. The site is
    the docs extension and every stock entry whose declaration requires
    it, directly or through another: the docs extension puts a docs job
    on every run of the loop's project, for a site nothing in a pass
    reads, and an extension that requires it brings it into the root's
    set. The pass proves the gate, the release train and the points,
    and ``fm ci.e2e --extension=docs`` proves the docs extension on its
    own. A stock entry no installed distribution declares requires
    nothing and stays.
    """
    from livery.workshop._extensions import SELF, installed_declaration
    from livery.workshop._new_project import birth_extensions, canonical_extensions

    def builds_the_site(name: str, seen: frozenset[str]) -> bool:
        if name == SITE:
            return True
        found = installed_declaration(name)
        needed = found.requires if found is not None else ()
        return any(
            builds_the_site(other, seen | {name})
            for other in needed
            if other not in seen
        )

    stock = [
        entry
        for entry in birth_extensions([SELF])
        if not builds_the_site(entry, frozenset())
    ]
    needs = [needed for member in LOOP_MEMBERS for needed in member.needs()]
    return tuple(canonical_extensions([*stock, *needs]))

scenarios_for

scenarios_for(spec: str) -> tuple[Scenario, ...]

The scenarios spec names, their needs added, in the registry's order.

spec is comma-separated set names and scenario names. A name that is neither refuses naming both lists; an empty spec refuses too. A need is run once however many names reach it.

Source code in packages/workshop/src/livery/workshop/_e2e.py
def scenarios_for(spec: str) -> tuple[Scenario, ...]:
    """The scenarios *spec* names, their needs added, in the registry's order.

    *spec* is comma-separated set names and scenario names. A name
    that is neither refuses naming both lists; an empty *spec*
    refuses too. A need is run once however many names reach it.
    """
    by_name = {scenario.name: scenario for scenario in SCENARIOS}
    wanted: set[str] = set()
    for token in (part.strip() for part in spec.split(",")):
        if not token:
            continue
        if token in SETS:
            wanted.update(SETS[token])
        elif token in by_name:
            wanted.add(token)
        else:
            fail(
                f"{token!r} is not a scenario or a set; the sets are"
                f" {', '.join(SETS)} and the scenarios {', '.join(by_name)}"
            )
    if not wanted:
        fail(f"--scenario names nothing; the sets are {', '.join(SETS)}")
    pending = list(wanted)
    while pending:
        for need in by_name[pending.pop()].needs:
            if need not in wanted:
                wanted.add(need)
                pending.append(need)
    return tuple(scenario for scenario in SCENARIOS if scenario.name in wanted)

daemon_needed

daemon_needed(scenarios: Sequence[Scenario]) -> bool

Whether any of scenarios needs the runner's docker socket.

Source code in packages/workshop/src/livery/workshop/_e2e.py
def daemon_needed(scenarios: Sequence[Scenario]) -> bool:
    """Whether any of *scenarios* needs the runner's docker socket."""
    return any(scenario.daemon for scenario in scenarios)

run_scenario

run_scenario(pass_: Pass, scenario: Scenario) -> None

Run scenario for pass_, timed; a failure is timed and marked, then raised.

Source code in packages/workshop/src/livery/workshop/_e2e.py
def run_scenario(pass_: Pass, scenario: Scenario) -> None:
    """Run *scenario* for *pass_*, timed; a failure is timed and marked, then raised."""
    import time

    started = time.monotonic()
    runs_before = RUNS.count
    print(f"  scenario {scenario.name}")
    failed = True
    try:
        scenario.run(pass_)
        failed = False
    finally:
        pass_.timings.append(
            Timing(
                scenario.name,
                time.monotonic() - started,
                RUNS.count - runs_before,
                failed,
            )
        )

timing_table

timing_table(timings: Sequence[Timing]) -> list[str]

The lines a pass ends with: each scenario's time and runs, then the total.

Source code in packages/workshop/src/livery/workshop/_e2e.py
def timing_table(timings: Sequence[Timing]) -> list[str]:
    """The lines a pass ends with: each scenario's time and runs, then the total."""
    if not timings:
        return ["  timing: nothing ran"]
    width = max(len(timing.name) for timing in timings)
    lines = [
        f"  {timing.name:<{width}}  {timing.seconds:7.1f}s  {timing.runs} run(s)"
        + ("  failed" if timing.failed else "")
        for timing in timings
    ]
    total = sum(timing.seconds for timing in timings)
    runs = sum(timing.runs for timing in timings)
    lines.append(f"  {'total':<{width}}  {total:7.1f}s  {runs} run(s)")
    return lines

record_pass

record_pass(root: Path, pass_: Pass, asked: str) -> str

Put the pass's timings on the local loop series; the line to print.

Source code in packages/workshop/src/livery/workshop/_e2e.py
def record_pass(root: Path, pass_: Pass, asked: str) -> str:
    """Put the pass's timings on the local loop series; the line to print."""
    from datetime import UTC, datetime

    when = datetime.now(UTC).strftime("%Y%m%dT%H%M%SZ")
    row: dict[str, object] = {
        "forge": pass_.forge,
        "asked": asked,
        **({"extension": pass_.extension} if pass_.extension else {}),
        "scenarios": [
            {
                "name": timing.name,
                "seconds": round(timing.seconds, 1),
                "runs": timing.runs,
                "failed": timing.failed,
            }
            for timing in pass_.timings
        ],
    }
    why = LOOP_SERIES.put(
        state_store(root),
        {f"pass-{when}.json": row},
        message=f"loop: pass {when} ({asked})",
    )
    if why:
        return f"  loop series: {why}; the pass is not recorded"
    return f"  loop series: pass {when} recorded ({len(pass_.timings)} scenario(s))"

e2e

e2e(forge: str = 'gitea', fresh: bool = False, scenario: str = '', env: str = 'e2e', purge_cache: bool = False, extension: str = '', from_main: bool = False) -> None

Exercise the CI and release story on a local environment, by scenario.

--env names the environment the pass runs on, e2e by default: one that does not exist is brought up in host mode with one runner, --fresh removes it and brings it up again, so a fresh pass is a new forge, and --purge-cache removes the rig's shared caches first. The docker-mode environment dev is the compose rig, addressed as before. Each variable an extension of the loop's set declares with a directory of its own is placed inside the environment, so what a release writes there goes with the environment's forge. --scenario names what the pass proves: scenario names, set names, or both, comma-separated. The sets are develop (birth, the verified skip, the members, the scoped leg), the default, release (develop and the release act), points (the nightly, the dispatched gate, the contributed point), extension (birth and the members) and all; a scenario's needs run first, once. --extension tests one extension in isolation, extension the default set: the birth lists that extension and what it requires instead of the loop's stack, and the members are the loop's whose sets hold an extension its steps name. birth builds this checkout's workshop, its dependencies and the extensions a birth lists into a local index, births or resumes the loop's workspace through fm new.project from that index (so an extension the birth lists needs no release), with its repository, protection and setup pull request, provisions the secrets, wires the workspace to the dev wheels in the forge's registry, and follows the pushed head's runs to their verdicts on the real runner. Re-running is the recovery procedure at every step. The pass ends with a table, each scenario's time and runs, and records the same rows on the local loop series. --fresh starts over from nothing: the loop's repository on the dev forge, its releases in the forge's registry, and the local workspace go, then the pass births everything anew. It refuses while the workspace holds commits the forge has not seen. --from-main moves a checkout standing on main or a reserved workflow/ branch, where a build would be the release train, to a scratch branch at the same commit for the pass and back afterwards; the nightly's checkout is one.

Source code in packages/workshop/src/livery/workshop/_e2e.py
@ci.task(name="e2e", serial=True)
@git.unsigned
def e2e(
    forge: str = "gitea",
    fresh: bool = False,
    scenario: str = "",
    env: str = "e2e",
    purge_cache: bool = False,
    extension: str = "",
    from_main: bool = False,
) -> None:
    """Exercise the CI and release story on a local environment, by scenario.

    ``--env`` names the environment the pass runs on, `e2e` by
    default: one that does not exist is brought up in host mode
    with one runner, ``--fresh`` removes it and brings it up
    again, so a fresh pass is a new forge, and ``--purge-cache``
    removes the rig's shared caches first. The docker-mode
    environment ``dev`` is the compose rig, addressed as before.
    Each variable an extension of the loop's set declares with a
    directory of its own is placed inside the environment, so what a
    release writes there goes with the environment's forge.
    ``--scenario`` names what the pass proves: scenario names, set
    names, or both, comma-separated. The sets are ``develop``
    (birth, the verified skip, the members, the scoped leg), the
    default, ``release`` (develop and the release act), ``points``
    (the nightly, the dispatched gate, the contributed point),
    ``extension`` (birth and the members) and ``all``; a scenario's
    needs run first, once. ``--extension`` tests one extension in
    isolation, ``extension`` the default set: the birth lists that
    extension and what it requires instead of the loop's stack, and
    the members are the loop's whose sets hold an extension its steps
    name. ``birth`` builds
    this checkout's workshop, its dependencies and the extensions a
    birth lists into a local index, births or resumes the loop's
    workspace through ``fm new.project`` from that index (so an
    extension the birth lists needs no release), with its
    repository, protection and setup pull request, provisions the
    secrets, wires the workspace to the dev wheels in the forge's
    registry, and follows the pushed head's runs to their verdicts
    on the real runner. Re-running is the recovery procedure at every
    step. The pass ends with a table, each scenario's time and
    runs, and records the same rows on the local ``loop`` series.
    ``--fresh`` starts over from nothing: the loop's repository on
    the dev forge, its releases in the forge's registry, and the
    local workspace go, then the pass births everything anew. It
    refuses while the workspace holds commits the forge has not
    seen. ``--from-main`` moves a checkout standing on ``main`` or a
    reserved ``workflow/`` branch, where a build would be the release
    train, to a scratch branch at the same commit for the pass and
    back afterwards; the nightly's checkout is one.
    """
    import os

    from livery.workshop import _devenv
    from livery.workshop._extensions import workspace_root

    driver = workspace_root()
    with scratch_branch(driver, enabled=from_main):
        if driver is not None:
            # Before anything is brought up: on a branch whose release
            # verb is the train, the first build would open a release.
            require_dev_branch(driver)
        asked = scenario or ("extension" if extension else "develop")
        chosen = scenarios_for(asked)
        stack, members = (
            extension_under_test(extension) if extension else (loop_stack(), ())
        )
        if forge != "gitea":
            fail(
                f"--env addresses a Gitea environment; --forge={forge} has none yet"
            )
        if purge_cache:
            for line in _devenv.purge_cache():
                print(line)
        enter_environment(env, stack, fresh=fresh)
        # Every commit the pass makes, the driver's, the birth's and
        # the loop's own fm's, is unsigned and carries the tools'
        # identity: the task's marks and the git plugin put both in
        # the task's environment, which rides into each child. On a
        # hosted runner the job's CI markers would reach every child,
        # which would then refuse a fix and stamp its runs as the
        # runner's; the pass drives its project as a desk.
        scrubbed = edit_environments({}, remove=CI_MARKERS)
        if scrubbed:
            names = ", ".join(scrubbed)
            print(f"  ci markers removed for the pass's children: {names}")
        _require_host_alias(forge)
        if daemon_needed(chosen):
            _require_runner_docker(forge)
        pass_ = Pass(
            forge,
            CURRENT.url or os.environ.get(_lane(forge).url_var, ""),
            fresh,
            extension=extension,
            stack=stack,
            members=members,
        )
        RUNS.count = 0
        try:
            for item in chosen:
                run_scenario(pass_, item)
        finally:
            for line in timing_table(pass_.timings):
                print(line)
            driver = workspace_root()
            if driver is not None:
                print(record_pass(driver, pass_, asked))
        names = ", ".join(item.name for item in chosen)
        print(f"  the loop proved {names}")