Skip to content

livery.workshop._workflow_engine

livery.workshop._workflow_engine

The shared reserved-branch engine and its one kind-specific seam.

Releasing and updating are the same shape underneath: cut a workflow/<name> branch, do some work, submit through livery.workshop._submit.submit_flow, and either publish or just merge. This module runs that shared lifecycle; a WorkflowDriver plugs in only prepare (do the work) and on_merged (a release publishes and tags; an update does nothing). Re-running the engine at any point is the recovery: the decision extension reads the state and does the right thing.

Classes:

Name Description
Submission

What a driver's prepare hands back for the shared submit.

WorkflowDriver

The only kind-specific seam; everything else is shared.

Functions:

Name Description
run_workflow

Drive driver one step: gather, decide, act.

tidy_leftover

Tear down a finished workflow's branches; safe, it is merged.

Attributes:

Name Type Description
PARKS_UPDATES

PARKS_UPDATES module-attribute

Submission dataclass

Submission(title: str, body: str)

What a driver's prepare hands back for the shared submit.

None from prepare means nothing to submit (already up to date, or the work completed on its own).

Attributes:

Name Type Description
title str
body str

title instance-attribute

title: str

body instance-attribute

body: str

WorkflowDriver

Bases: Protocol

The only kind-specific seam; everything else is shared.

Structural, so a driver provides these members and inherits nothing. branch is always workflow/<name>: one active workflow per name, the branch name is the identity, different names coexist.

Methods:

Name Description
prepare

Do the work; idempotent, called fresh and for recovery.

discard

Give the prepared branch up, so the next prepare starts from the base.

on_merged

After the merge: a release publishes and tags; else nothing.

Attributes:

Name Type Description
name str
kind WorkflowKind
armed bool
members tuple[str, ...]
watch float
branch str

The reserved branch, workflow/<name>.

base str

The branch the PR merges into.

name instance-attribute

name: str

kind instance-attribute

armed instance-attribute

armed: bool

members instance-attribute

members: tuple[str, ...]

watch instance-attribute

watch: float

branch property

branch: str

The reserved branch, workflow/<name>.

base property

base: str

The branch the PR merges into.

prepare

prepare() -> Submission | None

Do the work; idempotent, called fresh and for recovery.

Source code in packages/workshop/src/livery/workshop/_workflow_engine.py
def prepare(self) -> Submission | None:
    """Do the work; idempotent, called fresh and for recovery."""
    ...

discard

discard() -> None

Give the prepared branch up, so the next prepare starts from the base.

Source code in packages/workshop/src/livery/workshop/_workflow_engine.py
def discard(self) -> None:
    """Give the prepared branch up, so the next prepare starts from the base."""
    ...

on_merged

on_merged() -> None

After the merge: a release publishes and tags; else nothing.

Source code in packages/workshop/src/livery/workshop/_workflow_engine.py
def on_merged(self) -> None:
    """After the merge: a release publishes and tags; else nothing."""
    ...

run_workflow

run_workflow(driver: WorkflowDriver, repo: Repository, root: Path, *, current_user: str | None = None) -> None

Drive driver one step: gather, decide, act.

Loops for MERGE_DEFAULT (re-decide on the fresh state) and for a TIDY_THEN_START that removed another workflow's leftover, each other name tidied at most once so the loop cannot spin. STOP raises with its teaching. Everything else terminates.

Source code in packages/workshop/src/livery/workshop/_workflow_engine.py
def run_workflow(
    driver: WorkflowDriver,
    repo: Repository,
    root: Path,
    *,
    current_user: str | None = None,
) -> None:
    """Drive *driver* one step: gather, decide, act.

    Loops for MERGE_DEFAULT (re-decide on the fresh state) and for a
    TIDY_THEN_START that removed another workflow's leftover, each
    other name tidied at most once so the loop cannot spin. STOP
    raises with its teaching. Everything else terminates.
    """
    tidied: set[str] = set()
    while True:
        states = workflow_states(repo, root, base=driver.base)
        wf = next(
            (s for s in states if s.name == driver.name),
            WorkflowStatus(kind=None, state=WorkflowState.NONE),
        )
        others = tuple(s for s in states if s.name != driver.name)
        decision = workflow_decision(
            kind=driver.kind,
            name=driver.name,
            wf=wf,
            members=driver.members,
            branch=git.current_branch(root),
            dirty=not git.is_clean(root),
            behind_default=_behind_default(root, driver.base),
            default_branch=driver.base,
            current_user=(_forge_user(repo) if current_user is None else current_user),
            others=others,
        )
        action = decision.action

        # A bare repeat call into your own armed in-flight workflow:
        # the idempotent submit disarms whenever the arm choice is
        # off, so a status-check re-run would take the live schedule
        # away while announcing a retry. Say what is true and stop.
        if (
            action is WorkflowAction.RETRY
            and wf.state is WorkflowState.IN_PROGRESS
            and wf.armed is not False
            and not driver.armed
        ):
            fail(
                f"{driver.name} is already in flight and armed. Follow it"
                f" with `{footman.prog()} status --watch --workflow`, or re-run with"
                " --armed to re-assert the schedule deliberately."
            )

        message = decision.message
        if action is WorkflowAction.ARM and not driver.armed:
            message = (
                f"The ready {driver.name} PR stays unarmed; pass --armed to"
                " arm auto-merge."
            )
        if message:
            print(f"  {message}")

        if action is WorkflowAction.STOP:
            raise SystemExit(f"  {decision.message}")

        if action is WorkflowAction.MERGE_DEFAULT:
            _merge_default(root, driver.base)
            continue

        # A stale set re-derives in place: the prepare starts from the
        # base again and the push replaces the branch under the same
        # pull request.
        force = False
        if action is WorkflowAction.REPREPARE:
            driver.discard()
            force = True

        if action is WorkflowAction.TIDY_THEN_START:
            target = decision.tidy_target
            tidy_leftover(repo, root, target or wf, base=driver.base)
            if target is not None and target.name not in tidied:
                tidied.add(target.name)
                continue
        elif action is WorkflowAction.REOPEN:
            _reopen(repo, driver.branch)

        # The parking rule: while any release is live, a coexisting
        # update submits UNARMED, and the note teaches the re-run
        # (which also raises floors) before arming. The verify
        # backstop holds even when someone arms anyway.
        arm = driver.armed
        if arm and driver.kind is not WorkflowKind.RELEASE:
            parked_by = [
                other.name
                for other in others
                if other.kind is WorkflowKind.RELEASE and other.state in PARKS_UPDATES
            ]
            if parked_by:
                arm = False
                print(
                    f"  Release {parked_by[0]} is in flight: submitting"
                    " unarmed. After it lands, re-run"
                    f" `{footman.prog()} workflow.update`"
                    " (the re-run also raises floors to the fresh release),"
                    " then arm."
                )

        started = git.current_branch(root)
        submission = driver.prepare()
        if submission is None:
            print("  nothing to submit: everything is already current")
            return
        from livery.workshop._submit import submit_flow

        # The engine submits and reads the immediate outcome; the
        # long watch belongs to the drivers' own surfaces, which
        # know their done oracle (a release watches its receipts).
        submit_flow(
            repo,
            root,
            title=submission.title,
            body=submission.body,
            base=driver.base,
            armed=arm,
            armed_reason="the workflow engine",
            gate=False,
            follow_to_verdict=False,
            force=force,
        )
        _leave_reserved(root, driver, started)
        if arm and driver.watch > 0 and not _merged(repo, root, driver.branch):
            # An armed act waits the way `submit --armed` waits: from
            # the branch it returned to, since the pull request holds
            # the reserved branch on the remote. A blocker exits with
            # its code, the way the submit does.
            from livery.workshop._verdict import follow_pull_request

            print(f"  following PR of {driver.branch} to its merge")
            follow_pull_request(repo, driver.branch, root, timeout=driver.watch)
        if _merged(repo, root, driver.branch):
            driver.on_merged()
        return

tidy_leftover

tidy_leftover(repo: Repository, root: Path, wf: WorkflowStatus, *, base: str) -> None

Tear down a finished workflow's branches; safe, it is merged.

wf is the decision's tidy target, never assumed to be the driver's own branch: passing a live branch here would close its live PR, the exact mistake the target field prevents.

Source code in packages/workshop/src/livery/workshop/_workflow_engine.py
def tidy_leftover(
    repo: Repository, root: Path, wf: WorkflowStatus, *, base: str
) -> None:
    """Tear down a finished workflow's branches; safe, it is merged.

    *wf* is the decision's tidy target, never assumed to be the
    driver's own branch: passing a live branch here would close its
    live PR, the exact mistake the target field prevents.
    """
    if wf.branch:
        from livery.workshop._submit import teardown_branch

        teardown_branch(repo, root, wf.branch, base)