Skip to content

livery.workshop._sync

livery.workshop._sync

fm sync: deliver every mounted extension's content to the repository.

Walked in composition order, the base first, and the instance always wins last: the files each extension ships under content/, composed by the fragment engine, where an extension takes another's file only by declaring it, and the files each extension's code writes from its [fragments] renders (livery.workshop._shipped_files). A file that belongs to this checkout alone goes through the materialiser: a link where it can, a copy where not, and an edited copy kept and named.

Idempotent: a second run changes nothing and says nothing.

Classes:

Name Description
Synced

What one sync did, as sync_and_compare reports it.

Functions:

Name Description
sync_workspace

Deliver every extension's content into root; the summary lines.

resolve_receipts

Resolve a stopped merge or rebase whose every conflict is a render receipt.

restack

Move a stacked branch's own commits onto its parent, or onto main once it merged.

continue_on_moved_code

Hand the command to a fresh process when the checkout moved under it.

continue_on_moved_extensions

Hand the sync to a fresh process when its install moved a mounted extension.

require_mounted

Refuse to render or lock while an extension of the installed set is unmounted.

bring_current

Bring the current checkout up to date; the one-stop's first act.

lock

Write both locks: toolroom.lock for the tools, uv.lock for the venv.

sync

Bring the checkout current, materialise content, match the lock.

sync_and_compare

Do the sync verb's work on root, comparing what is installed before and after.

sync_checkout

Do the sync verb's work on the workspace at root; whether the local steps ran.

stale_locks

What is not current about root's locks; empty when both are.

sweep_residue

Remove what removed packages left under packages/; the lines.

fetch_store_lines

Mirror the store's row series into the checkout; the line to print.

store_lines

The line fetch_store's answer prints: what the mirror holds and what moved.

materialise_tools

Supply every locked tool through the store and write the receipts; the lines.

integrate

Bring origin/main into the current branch by merge.

match_lock

Match the venv to the lock when HEAD moved across a change to it; say so.

Attributes:

Name Type Description
fetch_origin
bring_checkout_current
fetch_store_mirror
sync_workspace_files
sync_locked_tools
prepare_installs
uv_sync
deliver_files
write_generated
LOCK_FILES

fetch_origin module-attribute

fetch_origin = step(_fetch_origin, title='fetch origin').opts(capture=False)

bring_checkout_current module-attribute

bring_checkout_current = step(_bring_checkout_current, title='bring current').opts(capture=False)

fetch_store_mirror module-attribute

fetch_store_mirror = step(_fetch_store_mirror, title='fetch store').opts(capture=False)

sync_workspace_files module-attribute

sync_workspace_files = step(_sync_workspace_files, title='sync workspace').opts(capture=False)

sync_locked_tools module-attribute

sync_locked_tools = step(_sync_locked_tools, title='sync tools').opts(capture=False)

prepare_installs module-attribute

prepare_installs = step(_prepare_installs, title='prepare install').opts(capture=False)

uv_sync module-attribute

uv_sync = step(_uv_sync, title='uv sync').opts(capture=False)

deliver_files module-attribute

deliver_files = step(_deliver_files, title='deliver').opts(capture=False)

write_generated module-attribute

write_generated = step(_write_generated, title='generated').opts(capture=False)

LOCK_FILES module-attribute

LOCK_FILES = ('uv.lock', 'pyproject.toml', 'packages/*/pyproject.toml')

Synced

Bases: NamedTuple

What one sync did, as sync_and_compare reports it.

Attributes:

Name Type Description
ran bool

Whether the local steps ran. A frozen sync of a current checkout runs none.

installs_changed bool

Whether the installed distributions differ after the sync from before it.

ran instance-attribute

ran: bool

Whether the local steps ran. A frozen sync of a current checkout runs none.

installs_changed instance-attribute

installs_changed: bool

Whether the installed distributions differ after the sync from before it.

sync_workspace

sync_workspace(root: Path, *, local_only: bool = False) -> list[str]

Deliver every extension's content into root; the summary lines.

The engine behind fm sync, separated so tests drive it against temporary trees. local_only writes no file a commit holds: the local outputs alone.

Source code in packages/workshop/src/livery/workshop/_sync.py
def sync_workspace(root: Path, *, local_only: bool = False) -> list[str]:
    """Deliver every extension's content into *root*; the summary lines.

    The engine behind ``fm sync``, separated so tests drive it against
    temporary trees. *local_only* writes no file a commit holds: the
    local outputs alone.
    """
    from livery.workshop._shipped_files import deliver

    return deliver(root, local_only=local_only)

resolve_receipts

resolve_receipts(root: Path) -> bool

Resolve a stopped merge or rebase whose every conflict is a render receipt.

Returns whether it did. Each conflicted receipt file is merged key by key (livery.workshop._fragment_engine.merge_receipts), with the files beside it as the conflict left them, and staged. A conflict in any other file leaves everything as it is, for the caller's own path.

Source code in packages/workshop/src/livery/workshop/_sync.py
def resolve_receipts(root: Path) -> bool:
    """Resolve a stopped merge or rebase whose every conflict is a render receipt.

    Returns whether it did. Each conflicted receipt file is merged key
    by key ([livery.workshop._fragment_engine.merge_receipts][]), with
    the files beside it as the conflict left them, and staged. A
    conflict in any other file leaves everything as it is, for the
    caller's own path.
    """
    from pathlib import PurePosixPath

    from livery.workshop._fragment_engine import (
        RENDERED_MANIFEST,
        merge_receipts,
        receipts_from,
        write_rendered,
    )

    unmerged = git.unmerged_paths(root)
    if not unmerged or any(
        PurePosixPath(path).name != RENDERED_MANIFEST for path in unmerged
    ):
        return False
    for path in unmerged:
        directory = (root / path).parent
        merged = merge_receipts(
            *(receipts_from(git.staged_text(root, path, stage)) for stage in (1, 2, 3)),
            beside=directory,
        )
        write_rendered(directory, merged)
        git.add(root, path)
        print(f"  {path}: the two sides' receipts merged, file by file")
    return True

restack

restack(root: Path, branch: str, *, interactive: bool, stack: tuple[str, str] | None = None) -> bool | None

Move a stacked branch's own commits onto its parent, or onto main once it merged.

A branch fm start --from began carries its parent's commits under its own. The ones after the recorded start commit are the branch's own whatever the parent became since, so they move alone: onto the parent's new tip when the parent moved, onto origin/main once the parent merged and origin deleted it. A parent squashed from several commits then moves nothing it carried, where a plain rebase replays those commits against their squash and conflicts. A branch started before the start commit was recorded, or moved by hand off it since, falls back on git's own matching, which drops a parent that landed as one commit. A branch whose parent is still open and unchanged is left where it is: main reaches it through the parent.

Returns whether the branch moved; None when it was left behind; a branch that is not stacked returns False. stack is the branch's stack when the caller read it already; read here otherwise.

Source code in packages/workshop/src/livery/workshop/_sync.py
def restack(
    root: Path,
    branch: str,
    *,
    interactive: bool,
    stack: tuple[str, str] | None = None,
) -> bool | None:
    """Move a stacked branch's own commits onto its parent, or onto main once it merged.

    A branch ``fm start --from`` began carries its parent's commits
    under its own. The ones after the recorded start commit are the
    branch's own whatever the parent became since, so they move alone:
    onto the parent's new tip when the parent moved, onto
    ``origin/main`` once the parent merged and origin deleted it. A
    parent squashed from several commits then moves nothing it
    carried, where a plain rebase replays those commits against their
    squash and conflicts. A branch started before the start commit was
    recorded, or moved by hand off it since, falls back on git's own
    matching, which drops a parent that landed as one commit. A branch
    whose parent is still open and unchanged is left where it is: main
    reaches it through the parent.

    Returns whether the branch moved; None when it was left behind; a
    branch that is not stacked returns False. *stack* is the branch's
    stack when the caller read it already; read here otherwise.
    """
    parent, tip = stack if stack is not None else _stack.stack(root, branch)
    if not parent:
        return False
    if tip and not git.is_ancestor(root, tip, "HEAD"):
        tip = ""  # moved by hand since: its history no longer holds the start
    merged = parent not in git.remote_branches(root, parent)
    onto = "origin/main" if merged else f"origin/{parent}"
    if not merged:
        target = git.sha_of(root, onto)
        if tip == target or (not tip and git.is_ancestor(root, target, "HEAD")):
            if not tip:
                _stack.record_stack(root, branch, parent, target)
            return False
    if not _rebase_step(root, onto, interactive=interactive, upstream=tip):
        return None
    if merged:
        _stack.forget_stack(root, branch)
        print(f"  {parent} has merged: {branch} stands on main now")
    else:
        _stack.record_stack(root, branch, parent, git.sha_of(root, onto))
    return True

continue_on_moved_code

continue_on_moved_code(root: Path, before: str, after: str, *, verb: str = 'sync') -> bool

Hand the command to a fresh process when the checkout moved under it.

The modules this process imported are the checkout's old code; what follows a move reads the new source, and a mixed process fails on the first changed signature. The handoff re-runs the same command through uv on the code now on disk; verb names it in the line. Returns False when nothing moved; when the re-run cannot start it is named and the command continues on the loaded code, which returns True.

Source code in packages/workshop/src/livery/workshop/_sync.py
def continue_on_moved_code(
    root: Path, before: str, after: str, *, verb: str = "sync"
) -> bool:
    """Hand the command to a fresh process when the checkout moved under it.

    The modules this process imported are the checkout's old code;
    what follows a move reads the new source, and a mixed process
    fails on the first changed signature. The handoff re-runs the
    same command through uv on the code now on disk; *verb* names it
    in the line. Returns False when nothing moved; when the re-run
    cannot start it is named and the command continues on the loaded
    code, which returns True.
    """
    if after == before:
        return False
    from livery.workshop import _reconcile

    print(
        f"  the checkout moved from {before[:12]} to {after[:12]}; the {verb}"
        " continues on that code"
    )
    _reconcile._reexec(root, _reconcile.MOVED)  # pyright: ignore[reportPrivateUsage]
    return True

continue_on_moved_extensions

continue_on_moved_extensions(root: Path, moved: tuple[str, ...]) -> None

Hand the sync to a fresh process when its install moved a mounted extension.

moved names the base and the extensions whose distribution the sync's uv sync moved or removed; when it names none, nothing happens. This process found each extension's directory as it mounted it, and reads its declaration, its shipped files and its code from there; it reads the base's own files, its contract, its seeds and its fragments, from the directory it imported the base from. An install that replaces an index's wheel with an editable member at another path removes that directory, and the member's path joins sys.path only when a process starts; an install from another editable tree leaves the old one on disk, no longer installed. The fresh process re-runs the command and mounts what the environment installs now; an extension the install removed is then one the mount finds missing, and the fresh process installs it or refuses, naming it. This process does not read a moved extension again, because it imported that extension's modules from the old place already.

Raises:

Type Description
Failed

when the fresh process cannot start, or the command already re-ran once for a moved extension. Nothing was delivered after the install then.

Source code in packages/workshop/src/livery/workshop/_sync.py
def continue_on_moved_extensions(root: Path, moved: tuple[str, ...]) -> None:
    """Hand the sync to a fresh process when its install moved a mounted extension.

    *moved* names the base and the extensions whose distribution the
    sync's ``uv sync`` moved or removed; when it names none, nothing
    happens. This process found each extension's directory as it
    mounted it, and reads its declaration, its shipped files and its
    code from there; it reads the base's own files, its contract, its
    seeds and its fragments, from the directory it imported the base
    from.
    An install that replaces an index's wheel with an editable member
    at another path removes that directory, and the member's path joins
    ``sys.path`` only when a process starts; an install from another
    editable tree leaves the old one on disk, no longer installed. The
    fresh process re-runs the command and mounts what the environment
    installs now; an extension the install removed is then one the
    mount finds missing, and the fresh process installs it or refuses,
    naming it. This process does not read a moved extension again,
    because it imported that extension's modules from the old place
    already.

    Raises:
        Failed: when the fresh process cannot start, or the command
            already re-ran once for a moved extension. Nothing was
            delivered after the install then.
    """
    if not moved:
        return
    from livery.workshop import _reconcile

    names = ", ".join(moved)
    print(
        f"  the install moved or removed {names}; the sync continues in a fresh"
        " process, which mounts what is installed now"
    )
    _reconcile._reexec(root, _reconcile.RELOCATED)  # pyright: ignore[reportPrivateUsage]
    fail(
        f"the install moved or removed {names}, and this process cannot mount"
        f" what is installed now: run `{footman.prog()} sync` again. Nothing was"
        " delivered after the install"
    )

require_mounted

require_mounted(root: Path, flags: tuple[str, ...] = (), *, install: bool = True) -> None

Refuse to render or lock while an extension of the installed set is unmounted.

The extensions mount when the command starts. One the installed set holds and no installed distribution declared then (a commit the sync moved onto lists it, or a person just listed it, in the root's list or a package's) registered nothing, and a render or a lock without it would remove its files and its tools as withdrawn. When the environment holds it now, or holds it once uv sync ran with flags, the sync hands itself to a fresh process, which mounts it.

A newly listed extension is in no lock yet, so that uv sync cannot install it. With install, it is installed the way the workspace resolves it: the project file alone is written again, and its dev group names the extension's distribution, then uv sync locks and installs through the file's [tool.uv.sources] and indexes. An extension the workspace sources from a path or from git installs from there. That write reads the contracts without judging their keys: a key of an extension no installed distribution declares yet, such as the root's [python] table before python is installed, has no declaration to be judged by until the install. The fresh process then judges every contract over the installed declarations and renders every file with the extension mounted.

One no distribution declares even then refuses, naming it and the list that brings it, and so does a handoff that cannot start. Each refusal, and an install that fails, first puts back the project file, its receipt and uv.lock as they were before the install, so nothing is rendered or locked.

Raises:

Type Description
Failed

when a listed extension cannot be mounted in this process, or the install fails.

Source code in packages/workshop/src/livery/workshop/_sync.py
def require_mounted(
    root: Path, flags: tuple[str, ...] = (), *, install: bool = True
) -> None:
    """Refuse to render or lock while an extension of the installed set is unmounted.

    The extensions mount when the command starts. One the installed set
    holds and no installed distribution declared then (a commit the sync
    moved onto lists it, or a person just listed it, in the root's list
    or a package's) registered nothing, and a render or a lock without
    it would remove its files and its tools as withdrawn. When the
    environment holds it now, or holds it once ``uv sync`` ran with
    *flags*, the sync hands itself to a fresh process, which mounts it.

    A newly listed extension is in no lock yet, so that ``uv sync``
    cannot install it. With *install*, it is installed the way the
    workspace resolves it: the project file alone is written again,
    and its dev group names the extension's distribution, then ``uv
    sync`` locks and installs through the file's ``[tool.uv.sources]``
    and indexes. An extension the workspace sources from a path or
    from git installs from there. That write reads the contracts
    without judging their keys: a key of an extension no installed
    distribution declares yet, such as the root's ``[python]`` table
    before python is installed, has no declaration to be judged by
    until the install. The fresh process then judges every contract
    over the installed declarations and renders every file with the
    extension mounted.

    One no distribution declares even then refuses, naming it and the
    list that brings it, and so does a handoff that cannot start. Each
    refusal, and an install that fails, first puts back the project
    file, its receipt and ``uv.lock`` as they were before the install,
    so nothing is rendered or locked.

    Raises:
        Failed: when a listed extension cannot be mounted in this process,
            or the install fails.
    """
    from livery.workshop import _reconcile
    from livery.workshop._extensions import (
        declared_now,
        stale_declarations,
        unmounted,
        where_listed,
    )
    from livery.workshop._uv import run_uv

    missing = unmounted(root)
    if not missing:
        return
    installed = declared_now(missing)
    # An environment from before the checkout's declares an extension
    # by an entry point whose package ships no declaration file: its
    # metadata is what `uv sync` brings current.
    if installed != missing or stale_declarations(root):
        run_uv("sync", *flags, root=root)
        installed = declared_now(missing)
    absent = [name for name in missing if name not in installed]
    held: dict[str, bytes | None] = {}
    if absent and install:
        held = _install_listed(root, flags)
        installed = declared_now(missing)
        absent = [name for name in missing if name not in installed]
    if absent:
        _put_back(root, held)
        why = (
            "and installing it found no distribution declaring it"
            if install
            else f"and a sync with {' '.join(flags)} installs nothing outside the lock"
        )
        where = where_listed(root)
        named = ", ".join(
            f"{name} ({where[name]})" if name in where else name for name in absent
        )
        fail(
            f"no installed distribution declares {named}, {why}: install the"
            " distribution that ships each, or remove the entry. Nothing was"
            " rendered or locked"
        )
    print(
        f"  extensions installed by this sync: {', '.join(installed)}; the sync"
        " continues with them mounted"
    )
    _reconcile._reexec(root, _reconcile.INSTALLED)  # pyright: ignore[reportPrivateUsage]
    _put_back(root, held)
    fail(
        f"{', '.join(installed)} installed, and this process cannot mount"
        f" them: run `{footman.prog()} sync` again. Nothing was rendered or locked"
    )

bring_current

bring_current(root: Path, *, interactive: bool, fetched: bool = False) -> None

Bring the current checkout up to date; the one-stop's first act.

main only ever fast-forwards. A reserved workflow/ branch belongs to the engine until its pull request merges, after which the checkout steps off it; a detached HEAD names no branch, a clone with no origin has nothing to follow, and a dirty tree is never moved: each skips with its note. A feature branch fast-forwards onto its moved remote, rebases onto it when diverged, then rebases onto the base; a stacked branch follows its parent instead (livery.workshop._sync.restack). A rebase of a pushed branch finishes the job with the leased force-push, because rebased-locally with a stale remote is the worst state. fetched says origin's heads are not to be fetched here: the one fetch that also mirrors the state store brought them already, or the sync is offline and the remote-tracking refs the last fetch left stand.

Source code in packages/workshop/src/livery/workshop/_sync.py
def bring_current(root: Path, *, interactive: bool, fetched: bool = False) -> None:
    """Bring the current checkout up to date; the one-stop's first act.

    ``main`` only ever fast-forwards. A reserved ``workflow/`` branch
    belongs to the engine until its pull request merges, after which
    the checkout steps off it; a detached HEAD names no branch, a
    clone with no ``origin`` has nothing to follow, and a dirty tree
    is never moved: each skips with its note. A feature
    branch fast-forwards onto its moved remote, rebases onto it when
    diverged, then rebases onto the base; a stacked branch follows its
    parent instead ([livery.workshop._sync.restack][]). A rebase of a
    pushed branch finishes the job with the leased force-push, because
    rebased-locally with a stale remote is the worst state. *fetched*
    says origin's heads are not to be fetched here: the one fetch that
    also mirrors the state store brought them already, or the sync is
    offline and the remote-tracking refs the last fetch left stand.
    """
    _ = root
    branch = git.current_branch(root)
    if not branch:
        print("  detached HEAD: nothing to bring current")
        return
    if not git.has_remote(root, "origin"):
        print("  no origin remote: nothing to bring current")
        return
    if not fetched:
        git.fetch(root)
    if branch == "main":
        ahead = git.run(root, "rev-list", "--count", "origin/main..main").strip()
        if ahead != "0":
            print(
                "  main has local commits origin does not: never rebased,"
                " never merged here. Move them to a branch."
            )
            return
        behind = git.run(root, "rev-list", "--count", "main..origin/main").strip()
        if behind == "0":
            return
        try:
            git.run(root, "merge", "--ff-only", "origin/main")
        except Exception as error:
            # The two states need different acts, so the refusal is
            # named with git's own reason, never read as "local
            # commits" (usually it is uncommitted changes in the way).
            print(f"  main is {behind} behind and the fast-forward was refused:")
            print(f"  {error}")
        return
    if branch.startswith("workflow/"):
        _leave_merged_reserved(root, branch)
        return
    if not git.is_clean(root):
        print("  uncommitted changes: the branch stays where it is")
        return
    rebased = False
    remote_exists = branch in git.remote_branches(root, "")
    if remote_exists:
        ahead_remote = git.run(
            root, "rev-list", "--count", f"origin/{branch}..{branch}"
        ).strip()
        behind_remote = git.run(
            root, "rev-list", "--count", f"{branch}..origin/{branch}"
        ).strip()
        if behind_remote != "0":
            if ahead_remote == "0":
                git.run(root, "merge", "--ff-only", f"origin/{branch}")
                print(f"  fast-forwarded {branch} to origin/{branch}")
            elif not _rebase_step(root, f"origin/{branch}", interactive=interactive):
                return
            else:
                rebased = True
    behind_base = git.run(root, "rev-list", "--count", f"{branch}..origin/main").strip()
    stack = _stack.stack(root, branch)
    parent, _tip = stack
    if parent:
        moved = restack(root, branch, interactive=interactive, stack=stack)
        if moved is None:
            return
        if moved:
            rebased = True
        elif behind_base != "0":
            print(
                f"  {branch} is stacked on {parent}: main reaches it when"
                f" {parent} merges"
            )
    elif behind_base != "0":
        if not _rebase_step(root, "origin/main", interactive=interactive):
            return
        rebased = True
    if rebased and remote_exists:
        # The same commits, rewritten: the lease guards anything a
        # colleague pushed since the fetch above.
        git.push_force(root, branch)
        print(f"  origin/{branch} follows (leased force-push)")

lock

lock(upgrade: Forward[bool] = False, upgrade_tool: Annotated[list[str] | None, doc('move just these tools to their newest')] = None, check: Forward[bool] = False) -> None

Write both locks: toolroom.lock for the tools, uv.lock for the venv.

The pair to sync, in uv's shape: this decides what a checkout installs and nothing on the machine changes, and sync installs what these say. An entry that still satisfies its declarations stands, so a newer release moves nothing until an upgrade asks.

--upgrade moves every entry of both locks to its newest eligible version, and --check reports whether both locks are current and writes nothing, exiting non-zero when either would move. Both mean the same thing to each half, so both reach both.

A name does not. --upgrade-tool names tools and reaches the tools alone, because a tool is not a package in uv.lock: for one package there, uv lock --upgrade-package is the verb.

Source code in packages/workshop/src/livery/workshop/_sync.py
@task
def lock(
    upgrade: Forward[bool] = False,
    upgrade_tool: Annotated[
        list[str] | None, doc("move just these tools to their newest")
    ] = None,
    check: Forward[bool] = False,
) -> None:
    """Write both locks: `toolroom.lock` for the tools, `uv.lock` for the venv.

    The pair to `sync`, in uv's shape: this decides what a checkout
    installs and nothing on the machine changes, and `sync` installs
    what these say. An entry that still satisfies its declarations
    stands, so a newer release moves nothing until an upgrade asks.

    ``--upgrade`` moves every entry of both locks to its newest eligible
    version, and ``--check`` reports whether both locks are current and
    writes nothing, exiting non-zero when either would move. Both mean
    the same thing to each half, so both reach both.

    A name does not. ``--upgrade-tool`` names tools and reaches the
    tools alone, because a tool is not a package in ``uv.lock``: for one
    package there, ``uv lock --upgrade-package`` is the verb.
    """
    from livery.workshop._tool_tasks import tools_lock
    from livery.workshop._uv import run_uv

    root = workspace_root()
    if root is None:
        fail("no workspace: no workshop.toml above the working directory")
    tools_lock(upgrade_tool=upgrade_tool)
    run_uv(
        "lock",
        *_uv_flags(upgrade=upgrade),
        *(("--check",) if check else ()),
        root=root,
    )

sync

sync(frozen: Forward[bool] = False, locked: Forward[bool] = False, offline: Forward[bool] = False) -> bool

Bring the checkout current, materialise content, match the lock.

The one-stop: fast-forward or rebase the current branch (asking before anything conflicted or shared; a branch started on another with fm start --from follows its parent; a directory with no git history, no repository or no commit, has nothing to follow), remove what a removed package left under packages/, fetch origin's state store into the checkout's mirror for the gate to read, then every extension's fragments, skills, and hooks, then the two locks. Both halves match their lock the way uv does: toolroom.sync for the tools, uv sync for the environment, each writing its lock when there is none or the declarations have moved past it. Last, the composed and generated files are written again, since both read the locks. Idempotent: re-running it is the recovery procedure.

The three options are uv's and reach both halves: --frozen installs each lock as it is and resolves nothing, --locked refuses when a lock is not current, and --offline uses what the machine already holds. As uv's two leave its lock unchanged, ours change nothing a commit holds: the branch is not moved and no tracked file is written, while the checkout's own untracked files are. They differ as uv's do, in whether the locks are judged: --locked refuses a stale one, so CI's setup runs it and a job holds what a person's checkout holds; --frozen takes them as they are, which is how the per-command hook brings a checkout current before every command, running this verb's work frozen and offline (livery.workshop._reconcile.apply). Judging the tracked files stays the drift check's.

A frozen sync reads the receipts first (livery.workshop._reconcile.current). When the environment, the tools and the delivered files all match them, its local steps have nothing to do and are skipped, and nothing is printed, so the hook costs a current checkout those reads and nothing else. A plain sync renders and installs again regardless, since a fragment edit is in no receipt; the tools' supply alone reads its receipts in every mode (livery.workshop._tool_tasks.sync_tools).

A checkout the first act moved holds code this process has not loaded, so the rest of the sync is handed to a fresh process on that code; the handoff is named, and a process that cannot be started continues on the loaded code and says so. An extension the workspace lists that the command started without is mounted the same way before anything renders or locks: a sync never renders without one. A newly listed extension is installed first, the way the workspace resolves it: the sync writes the project file alone, whose dev group then names the extension's distribution, and runs uv sync, which locks and installs through the file's [tool.uv.sources] and indexes. So an extension the workspace sources from a path or from git installs from there. When no installed distribution declares the extension even then, the sync refuses, naming the extension and the list that brings it. Before that refusal, and when the install fails, it puts the project file, its receipt and uv.lock back as they were. A uv sync that moves or removes the distribution of the workshop, or of an extension the command mounted, hands the rest of the sync over the same way, before anything reads it again: this process found it where the install no longer puts it. A handoff that cannot start then refuses, and the next sync completes.

Shell completion answers from a manifest this command wrote as it started, from what was installed then. A sync that changed the distributions the environment installs, run by a person at a terminal, starts the detached rebuild of that manifest for the directory the command was typed in (livery.footman.refresh_completion), so the next Tab there offers the tasks an installed extension brings. A sync that changed nothing installed starts nothing, and so does one no person is there for, in CI or under --no-input. A rebuild that cannot start leaves the sync's outcome as it is.

Returns:

Type Description
bool

Whether the local steps ran. A frozen sync of a current

bool

checkout returns False.

Source code in packages/workshop/src/livery/workshop/_sync.py
@task(interactive=True)
def sync(
    frozen: Forward[bool] = False,
    locked: Forward[bool] = False,
    offline: Forward[bool] = False,
) -> bool:
    """Bring the checkout current, materialise content, match the lock.

    The one-stop: fast-forward or rebase the current branch (asking
    before anything conflicted or shared; a branch started on another
    with ``fm start --from`` follows its parent; a directory with no git
    history, no repository or no commit, has nothing to follow), remove
    what a removed package left under ``packages/``, fetch origin's
    state store into the checkout's mirror for the gate to read, then
    every extension's fragments, skills, and hooks, then the two locks.
    Both halves match their lock the way uv does: `toolroom.sync` for the
    tools, ``uv sync`` for the environment, each writing its lock when
    there is none or the declarations have moved past it. Last, the
    composed and generated files are written again, since both read the
    locks. Idempotent: re-running it is the recovery procedure.

    The three options are uv's and reach both halves: ``--frozen``
    installs each lock as it is and resolves nothing, ``--locked``
    refuses when a lock is not current, and ``--offline`` uses what the
    machine already holds. As uv's two leave its lock unchanged, ours
    change nothing a commit holds: the branch is not moved and no
    tracked file is written, while the checkout's own untracked files
    are. They differ as uv's do, in whether the locks are judged:
    ``--locked`` refuses a stale one, so CI's setup runs it and a job
    holds what a person's checkout holds; ``--frozen`` takes them as
    they are, which is how the per-command hook brings a checkout
    current before every command, running this verb's work frozen and
    offline ([livery.workshop._reconcile.apply][]). Judging the tracked
    files stays the drift check's.

    A frozen sync reads the receipts first
    ([livery.workshop._reconcile.current][]). When the environment, the
    tools and the delivered files all match them, its local steps have
    nothing to do and are skipped, and nothing is printed, so the hook
    costs a current checkout those reads and nothing else. A plain sync
    renders and installs again regardless, since a fragment edit is in
    no receipt; the tools' supply alone reads its receipts in every
    mode ([livery.workshop._tool_tasks.sync_tools][]).

    A checkout the first act moved holds code this process has not
    loaded, so the rest of the sync is handed to a fresh process on
    that code; the handoff is named, and a process that cannot be
    started continues on the loaded code and says so. An extension the
    workspace lists that the command started without is mounted the
    same way before anything renders or locks: a sync never renders
    without one. A newly listed extension is installed first, the way
    the workspace resolves it: the sync writes the project file alone,
    whose dev group then names the extension's distribution, and runs
    ``uv sync``, which locks and installs through the file's
    ``[tool.uv.sources]`` and indexes. So an extension the workspace
    sources from a path or from git installs from there. When no
    installed distribution declares the extension even then, the sync
    refuses, naming the extension and the list that brings it. Before
    that refusal, and when the install fails, it puts the project file,
    its receipt and ``uv.lock`` back as they were. A ``uv sync`` that
    moves or removes the distribution of the workshop, or of an
    extension the command mounted, hands the rest of the sync over the
    same way, before anything reads it again: this process found it
    where the install no longer puts it. A handoff that cannot start
    then refuses, and the next sync completes.

    Shell completion answers from a manifest this command wrote as it
    started, from what was installed then. A sync that changed the
    distributions the environment installs, run by a person at a
    terminal, starts the detached rebuild of that manifest for the
    directory the command was typed in
    ([livery.footman.refresh_completion][]), so the next Tab there
    offers the tasks an installed extension brings. A sync that changed
    nothing installed starts nothing, and so does one no person is
    there for, in CI or under `--no-input`. A rebuild that cannot
    start leaves the sync's outcome as it is.

    Returns:
        Whether the local steps ran. A frozen sync of a current
        checkout returns False.
    """
    root = workspace_root()
    if root is None:
        fail("no workspace: no workshop.toml above the working directory")
    synced = sync_and_compare(root, frozen=frozen, locked=locked, offline=offline)
    if synced.installs_changed:
        footman.refresh_completion(footman.current().invoked_dir or root)
    return synced.ran

sync_and_compare

sync_and_compare(root: Path, *, frozen: bool = False, locked: bool = False, offline: bool = False) -> Synced

Do the sync verb's work on root, comparing what is installed before and after.

sync_checkout does the work, and the options mean what they mean there. The comparison reads every distribution's name and entry points in the environment, so an editable member installed again with new entry points counts as a change. A sync whose local steps did not run changed nothing, and the environment is not read again.

Returns:

Type Description
Synced

Whether the local steps ran, and whether they changed what the

Synced

environment installs.

Source code in packages/workshop/src/livery/workshop/_sync.py
def sync_and_compare(
    root: Path, *, frozen: bool = False, locked: bool = False, offline: bool = False
) -> Synced:
    """Do the sync verb's work on *root*, comparing what is installed before and after.

    `sync_checkout` does the work, and the options mean what they mean
    there. The comparison reads every distribution's name and entry
    points in the environment, so an editable member installed again
    with new entry points counts as a change. A sync whose local steps
    did not run changed nothing, and the environment is not read again.

    Returns:
        Whether the local steps ran, and whether they changed what the
        environment installs.
    """
    from livery.workshop._reconcile import installed_distributions

    before = installed_distributions(root)
    ran = sync_checkout(root, frozen=frozen, locked=locked, offline=offline)
    return Synced(ran, ran and installed_distributions(root) != before)

sync_checkout

sync_checkout(root: Path, *, frozen: bool = False, locked: bool = False, offline: bool = False) -> bool

Do the sync verb's work on the workspace at root; whether the local steps ran.

livery.workshop._sync.sync runs it on the workspace above its task's directory; the options mean what they mean there. The per-command hook (livery.workshop._reconcile.apply) runs it frozen and offline on the root it found, as a plain call and never as a call of the verb: a task called from a hook resolves its own directory, which can lie outside root, and its row joins the run's report, where its failure would fail the command the hook must never stop.

Returns:

Type Description
bool

Whether the local steps ran. A frozen sync of a current

bool

checkout returns False.

Raises:

Type Description
Failed

naming what stopped the sync, a stale lock under locked or a listed extension this process cannot mount.

RunFailed

when a command one of the steps runs exits non-zero.

Source code in packages/workshop/src/livery/workshop/_sync.py
def sync_checkout(
    root: Path, *, frozen: bool = False, locked: bool = False, offline: bool = False
) -> bool:
    """Do the sync verb's work on the workspace at *root*; whether the local steps ran.

    [livery.workshop._sync.sync][] runs it on the workspace above its
    task's directory; the options mean what they mean there. The
    per-command hook ([livery.workshop._reconcile.apply][]) runs it
    frozen and offline on the root it found, as a plain call and never
    as a call of the verb: a task called from a hook resolves its own
    directory, which can lie outside *root*, and its row joins the
    run's report, where its failure would fail the command the hook
    must never stop.

    Returns:
        Whether the local steps ran. A frozen sync of a current
        checkout returns False.

    Raises:
        Failed: naming what stopped the sync, a stale lock under
            *locked* or a listed extension this process cannot mount.
        RunFailed: when a command one of the steps runs exits non-zero.
    """
    if locked:
        # Refused before anything runs, naming the lock and the sync that
        # writes it: uv's own refusal would name uv's command instead.
        problems = stale_locks(root)
        if problems:
            fail(
                "--locked: "
                + "; ".join(problems)
                + f". `{footman.prog()} sync` writes the locks; commit them"
            )
    # Neither mode changes what a commit holds.
    local_only = locked or frozen
    # Each phase is a step: a receipt line with its duration, a row in
    # --json, a slice in a profile, and a unit parallel() could schedule
    # where two were independent. They are not yet: the fetch moves the
    # checkout before anything renders, the delivery writes the conan
    # workspace file the tools' build reads, the tools come before uv's
    # build, and the last delivery and the generated files read the locks
    # both halves just wrote.
    fetched = False
    mirrored: tuple[str, ...] | None = None
    if not local_only and not offline and git.has_commits(root):
        mirrored = _mirrored(root)
        fetched = fetch_origin(root, mirrored)()
    if not local_only and not git.has_commits(root):
        print("  no git history here: nothing to bring current")
    elif not local_only:
        # Offline, the remote-tracking refs the last fetch left are what
        # the checkout holds: the bring-current reads them and fetches nothing.
        moved = bring_checkout_current(root, fetched=fetched or offline)()
        if moved is not None:
            continue_on_moved_code(root, *moved)
    # Before anything renders or locks: a listed extension the mount
    # found missing would count as withdrawn, and its files and its
    # tools would go.
    require_mounted(
        root,
        _uv_flags(frozen=frozen, locked=locked, offline=offline),
        install=not local_only,
    )
    # Before anything discovers packages: a removed package's leftover
    # directory refuses discovery until it goes.
    for line in sweep_residue(root):
        print(line)
    # The receipts say what the machine holds against the locks and the
    # delivery. A frozen sync matches the machine to them and nothing
    # else, so when every receipt matches its local steps have nothing
    # to do and are skipped, silently: the per-command hook runs this
    # form before every command. A plain sync renders again regardless,
    # since a fragment edit is in no receipt. A receipt that cannot be
    # read is off: the steps rewrite it.
    from livery.workshop._reconcile import current, record_receipt

    try:
        why = current(root)
    except Exception as error:
        why = f"the receipts could not be read ({error})"
    skipped = frozen and not why
    # Offline touches no network: the mirror the last fetch took stands.
    if offline:
        if not skipped:
            print("  store: not fetched (--offline); the last snapshot stands")
    elif mirrored is None or _mirrored(root) != mirrored:
        # The fetch above named the series declared before the mount. An
        # extension the mount installed keeps series that fetch could
        # not name, so the mirror is taken again, and only then.
        fetch_store_mirror(root)()
    if skipped:
        return False
    if frozen:
        print(f"  {why}; syncing from what the machine holds")
    sync_workspace_files(root, local_only=local_only)()
    sync_locked_tools(root, frozen=frozen or locked, offline=offline)()
    prepare_installs(root)()
    shifted = uv_sync(root, _uv_flags(frozen=frozen, locked=locked, offline=offline))()
    # Before anything reads an extension again: one the install moved is
    # no longer where this process found it.
    continue_on_moved_extensions(root, shifted)
    deliver_files(root, local_only=local_only)()
    if not local_only:
        write_generated(root)()
    # The receipt records this sync, so the next command's sync
    # compares instead of syncing again.
    record_receipt(root)
    return True

stale_locks

stale_locks(root: Path) -> list[str]

What is not current about root's locks; empty when both are.

The two locks sync --locked refuses on: uv.lock against the project's declarations (uv lock --check) and toolroom.lock against its sites. A workspace without a lock has nothing here to judge. The installed plugins are read again first, since a sync in another process may have moved them under this one.

Source code in packages/workshop/src/livery/workshop/_sync.py
def stale_locks(root: Path) -> list[str]:
    """What is not current about *root*'s locks; empty when both are.

    The two locks `sync --locked` refuses on: `uv.lock` against the
    project's declarations (``uv lock --check``) and `toolroom.lock`
    against its sites. A workspace without a lock has nothing here to
    judge. The installed plugins are read again first, since a sync in
    another process may have moved them under this one.
    """
    import livery.toolroom.tools as tools
    from livery.footman import rescan_entry_points
    from livery.toolroom.store import LOCK_FILE
    from livery.workshop._tools import lock_is_current

    problems: list[str] = []
    if (root / "uv.lock").is_file():
        result = tools.uv.opts(cwd=root, nofail=True, recorded=False)("lock", "--check")
        if result.code != 0:
            said = [
                line.strip()
                for line in (result.stderr or result.stdout).splitlines()
                if line.strip()
            ]
            if any("needs to be updated" in line for line in said):
                problems.append(
                    "uv.lock is not current: the declarations moved past it"
                )
            else:
                # Not a verdict on the lock: uv could not resolve to
                # compare (no network, an index refused), in its words.
                error = next((line for line in said if line.startswith("error")), "")
                problems.append(
                    "uv.lock could not be checked"
                    + (f" ({error or said[-1]})" if said else "")
                )
    if (root / LOCK_FILE).is_file():
        # A plugin's tools are read through its installed metadata. A
        # member stamped to a new version and synced by any command in
        # this checkout moves to a new dist-info directory, and an entry
        # point scanned before the move then names no distribution, which
        # drops its plugin's tools. The release train makes this check
        # half an hour after its scan.
        rescan_entry_points()
        current, why = lock_is_current(root)
        if not current:
            problems.append(f"{LOCK_FILE} is not current ({why})")
    return problems

sweep_residue

sweep_residue(root: Path) -> list[str]

Remove what removed packages left under packages/; the lines.

A directory under packages/ without a workshop.toml goes when git tracks nothing under it and every file it holds is one git ignores: the leftovers of a package the checkout moved past the removal of (livery.workshop._packages.Leftover). A directory holding a file git neither tracks nor ignores, or a machine secret, is named and kept; one where git tracks a file is a package missing its contract, which discovery refuses by name. Says nothing when there is nothing to sweep.

Source code in packages/workshop/src/livery/workshop/_sync.py
def sweep_residue(root: Path) -> list[str]:
    """Remove what removed packages left under ``packages/``; the lines.

    A directory under ``packages/`` without a ``workshop.toml`` goes
    when git tracks nothing under it and every file it holds is one git
    ignores: the leftovers of a package the checkout moved past the
    removal of ([livery.workshop._packages.Leftover][]). A directory
    holding a file git neither tracks nor ignores, or a machine secret,
    is named and kept; one where git tracks a file is a package missing
    its contract, which discovery refuses by name. Says nothing when
    there is nothing to sweep.
    """
    import shutil

    from livery.workshop._packages import (
        RESIDUE,
        SECRET,
        UNKNOWN,
        UNTRACKED,
        leftover,
        package_directories,
    )

    lines: list[str] = []
    for directory in package_directories(root):
        if (directory / "workshop.toml").is_file():
            continue
        found = leftover(root, directory)
        name = directory.relative_to(root).as_posix()
        shown = ", ".join(found.paths[:3]) + (
            f" and {len(found.paths) - 3} more" if len(found.paths) > 3 else ""
        )
        if found.state == RESIDUE:
            try:
                shutil.rmtree(directory)
            except OSError as error:
                lines.append(
                    f"  {name}: what a removed package left behind could not be"
                    f" removed ({error}); delete the directory by hand"
                )
                continue
            lines.append(
                f"  {name}: removed {len(found.paths)} ignored file(s) a removed"
                " package left behind"
            )
        elif found.state == UNTRACKED:
            lines.append(
                f"  {name}: no workshop.toml, and it holds files git neither tracks"
                f" nor ignores ({shown}); kept"
            )
        elif found.state == SECRET:
            lines.append(
                f"  {name}: no workshop.toml, and it holds a machine secret no"
                f" checkout restores ({shown}); kept: move the secret out, then"
                " delete the directory"
            )
        elif found.state == UNKNOWN:
            lines.append(
                f"  {name}: no workshop.toml, and git could not say what it holds"
                f" ({found.reason}); kept"
            )
    return lines

fetch_store_lines

fetch_store_lines(root: Path) -> list[str]

Mirror the store's row series into the checkout; the line to print.

The mirror is what a machine's check reads (livery.git.fetched_snapshot): the remote row series the workspace declares (livery.workshop._series.mirrored_series), never a keyed family, so a sync or a start refreshes it while it has the network. A fetch that fails prints its reason and stops nothing: the gate falls open on a store it cannot read, and the last mirror stands.

Source code in packages/workshop/src/livery/workshop/_sync.py
def fetch_store_lines(root: Path) -> list[str]:
    """Mirror the store's row series into the checkout; the line to print.

    The mirror is what a machine's ``check`` reads
    ([livery.git.fetched_snapshot][]): the remote row series the
    workspace declares ([livery.workshop._series.mirrored_series][]),
    never a keyed family, so a sync or a start refreshes it while it
    has the network. A fetch that fails prints its reason and stops
    nothing: the gate falls open on a store it cannot read, and the
    last mirror stands.
    """
    from livery.git import fetch_store

    return store_lines(fetch_store(state_store(root), series=_mirrored(root)))

store_lines

store_lines(fetched: Fetched) -> list[str]

The line fetch_store's answer prints: what the mirror holds and what moved.

Source code in packages/workshop/src/livery/workshop/_sync.py
def store_lines(fetched: Fetched) -> list[str]:
    """The line `fetch_store`'s answer prints: what the mirror holds and what moved."""
    if fetched.why:
        return [
            f"  store: origin's state store not fetched ({fetched.why}); the last"
            " snapshot stands"
        ]
    if not fetched.changed:
        return ["  store: up to date"]
    return [f"  store: {fetched.changed} ref(s) changed, {fetched.held} mirrored"]

materialise_tools

materialise_tools(root: Path, *, offline: bool = False) -> list[str]

Supply every locked tool through the store and write the receipts; the lines.

The bundle the sites require, materialised as fm sync and fm toolroom.sync enter the environment, and the stubs the checkers read written after it: a checkout with no toolroom.lock yet has nothing to materialise and says so. offline supplies from the machine's store and its sources alone.

Source code in packages/workshop/src/livery/workshop/_sync.py
def materialise_tools(root: Path, *, offline: bool = False) -> list[str]:
    """Supply every locked tool through the store and write the receipts; the lines.

    The bundle the sites require, materialised as `fm sync` and
    `fm toolroom.sync` enter the environment, and the stubs the
    checkers read written after it: a checkout with no `toolroom.lock`
    yet has nothing to materialise and says so. *offline* supplies from
    the machine's store and its sources alone.
    """
    from livery.toolroom.store import LOCK_FILE
    from livery.workshop._tools import current_lock, materialise, stub_lines

    if current_lock(root) is None:
        return [f"  tools: no {LOCK_FILE}; `{footman.prog()} toolroom.lock` writes one"]
    done = materialise(root, strict=False, offline=offline)
    supplied = [m for m in done if m.receipt is not None]
    installed = [m.receipt.tool for m in supplied if m.installed and m.receipt]
    hosted = [
        f"{m.receipt.tool} {m.receipt.answered}".rstrip()
        for m in supplied
        if m.receipt is not None and m.receipt.source == "host"
    ]
    lines = [
        (
            f"  tools: {len(supplied)} receipt(s), installed {', '.join(installed)}"
            if installed
            else "  tools: up to date"
        )
        + (f", from the host: {', '.join(hosted)}" if hosted else ""),
    ]
    lines += [f"  tools: {m.note}" for m in done if m.note]
    lines += [f"  tools: could not materialise: {m.failure}" for m in done if m.failure]
    return lines + stub_lines(root, strict=False, offline=offline)

integrate

integrate() -> None

Bring origin/main into the current branch by merge.

The shared-branch spelling: a merge never rewrites, so every other copy of the branch stays valid, and the squash erases the merge commit at landing. A conflict in the render's receipts alone is merged key by key and committed; any other conflict stops with git's own words: resolve, commit, and re-run.

Source code in packages/workshop/src/livery/workshop/_sync.py
@task
def integrate() -> None:
    """Bring ``origin/main`` into the current branch by merge.

    The shared-branch spelling: a merge never rewrites, so every
    other copy of the branch stays valid, and the squash erases the
    merge commit at landing. A conflict in the render's receipts alone
    is merged key by key and committed; any other conflict stops with
    git's own words: resolve, commit, and re-run.
    """
    root = workspace_root()
    if root is None:
        fail("no workspace: no workshop.toml above the working directory")
    branch = git.current_branch(root)
    if not branch or branch == "main" or branch.startswith("workflow/"):
        fail(
            "integrate brings origin/main into a feature branch, and"
            f" you are on {branch or '(detached)'!r}."
        )
    if not git.is_clean(root):
        fail(
            "the working tree has uncommitted changes: commit them first,"
            " so the merge has one parent to speak for you."
        )
    before = git.head_sha(root)
    try:
        git.integrate(root, "main")
    except git.GitError as error:
        if not resolve_receipts(root):
            fail(
                f"the merge stopped on conflicts:\n{error}\n  Resolve them,"
                " `git commit`, and the branch is current; re-running any verb"
                " is the recovery."
            )
        git.run(root, "commit", "--no-edit")
    if git.head_sha(root) == before:
        print("  already current with origin/main")
        return
    print(f"  merged origin/main into {branch}")
    for line in sweep_residue(root):
        print(line)
    match_lock(root, since=before)

match_lock

match_lock(root: Path, *, since: str) -> None

Match the venv to the lock when HEAD moved across a change to it; say so.

since is the commit HEAD moved from. A merge that changed the lock, the root manifest, or a member's manifest leaves the venv installed from the old ones (a new entry point the venv never learned made the next gate red until a sync); the sync runs here, at the verb's end, and the receipts record it, so the next command's reconcile finds nothing to do.

Source code in packages/workshop/src/livery/workshop/_sync.py
def match_lock(root: Path, *, since: str) -> None:
    """Match the venv to the lock when HEAD moved across a change to it; say so.

    *since* is the commit HEAD moved from. A merge that changed the
    lock, the root manifest, or a member's manifest leaves the venv
    installed from the old ones (a new entry point the venv never
    learned made the next gate red until a sync); the sync runs here,
    at the verb's end, and the receipts record it, so the next
    command's reconcile finds nothing to do.
    """
    from livery.workshop._reconcile import record_receipt
    from livery.workshop._uv import run_uv

    changed = git.changed_between(root, since, "HEAD", LOCK_FILES)
    if not changed:
        return
    print(f"  matching the lock: the merge changed {', '.join(changed)}")
    run_uv("sync", root=root)
    record_receipt(root)
    print("  matched the lock; the environment agrees with the merge")