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 |
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: |
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 |
fetch_store_lines |
Mirror the store's row series into the checkout; the line to print. |
store_lines |
The line |
materialise_tools |
Supply every locked tool through the store and write the receipts; the lines. |
integrate |
Bring |
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)
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
¶
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. |
sync_workspace ¶
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
resolve_receipts ¶
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
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
continue_on_moved_code ¶
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
continue_on_moved_extensions ¶
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
require_mounted ¶
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
348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 | |
bring_current ¶
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
488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 | |
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
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
642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 | |
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
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
763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 | |
stale_locks ¶
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
sweep_residue ¶
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
fetch_store_lines ¶
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
store_lines ¶
The line fetch_store's answer prints: what the mirror holds and what moved.
Source code in packages/workshop/src/livery/workshop/_sync.py
materialise_tools ¶
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
integrate ¶
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
match_lock ¶
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.