Coverage for packages/workshop/src/livery/workshop/_sync.py: 92%

Measured by coverage.py 7.16.2 on CPython 3.14 while the suites of tests, packages/workshop, packages/extensions/ty, packages/extensions/ruff, packages/extensions/python, packages/extensions/pytest, packages/extensions/pyrefly, packages/extensions/nanobind, packages/extensions/mypy, packages/extensions/mkdocstrings, packages/extensions/lfs, packages/extensions/docs, packages/extensions/cpp, packages/extensions/coverage, packages/extensions/conan, packages/extensions/cmake, packages/extensions/claude, packages/extensions/clang-tidy, packages/extensions/clang-format, packages/extensions/changelog, packages/extensions/basedpyright ran.

1"""``fm sync``: deliver every mounted extension's content to the repository.
2
3Walked in composition order, the base first, and the instance always
4wins last: the files each extension ships under ``content/``, composed
5by the fragment engine, where an extension takes another's file only
6by declaring it, and the files each extension's code writes from its
7``[fragments]`` renders ([livery.workshop._shipped_files][]). A file
8that belongs to this checkout alone goes through the materialiser: a
9link where it can, a copy where not, and an edited copy kept and named.
10
11Idempotent: a second run changes nothing and says nothing.
12"""
13
14from __future__ import annotations
15
16from pathlib import Path
17from typing import TYPE_CHECKING, Annotated, Any, NamedTuple
18
19import livery.footman as footman
20from livery import git
21from livery.footman import Forward, doc, fail, step, task
22from livery.workshop import _stack
23from livery.workshop._ci_context import state_store
24
25if TYPE_CHECKING:
26 from livery.git import Fetched
27
28from livery.workshop._extensions import (
29 workspace_root,
30)
31
32
33def sync_workspace(root: Path, *, local_only: bool = False) -> list[str]:
34 """Deliver every extension's content into *root*; the summary lines.
35
36 The engine behind ``fm sync``, separated so tests drive it against
37 temporary trees. *local_only* writes no file a commit holds: the
38 local outputs alone.
39 """
40 from livery.workshop._shipped_files import deliver
41
42 return deliver(root, local_only=local_only)
43
44
45def _foreign_authors(root: Path, since: str) -> set[str]:
46 """Author emails of the commits after *since* a rebase would rewrite; never mine."""
47 me = git.author_email(root)
48 authors = git.run(root, "log", "--format=%ae", f"{since}..HEAD").strip()
49 return {email for email in authors.splitlines() if email and email != me}
50
51
52def _rebase_args(onto: str, upstream: str) -> tuple[str, ...]:
53 """The rebase's arguments: onto *onto*, the commits after *upstream* when given."""
54 return ("--onto", onto, upstream) if upstream else (onto,)
55
56
57def resolve_receipts(root: Path) -> bool:
58 """Resolve a stopped merge or rebase whose every conflict is a render receipt.
59
60 Returns whether it did. Each conflicted receipt file is merged key
61 by key ([livery.workshop._fragment_engine.merge_receipts][]), with
62 the files beside it as the conflict left them, and staged. A
63 conflict in any other file leaves everything as it is, for the
64 caller's own path.
65 """
66 from pathlib import PurePosixPath
67
68 from livery.workshop._fragment_engine import (
69 RENDERED_MANIFEST,
70 merge_receipts,
71 receipts_from,
72 write_rendered,
73 )
74
75 unmerged = git.unmerged_paths(root)
76 if not unmerged or any(
77 PurePosixPath(path).name != RENDERED_MANIFEST for path in unmerged
78 ):
79 return False
80 for path in unmerged:
81 directory = (root / path).parent
82 merged = merge_receipts(
83 *(receipts_from(git.staged_text(root, path, stage)) for stage in (1, 2, 3)),
84 beside=directory,
85 )
86 write_rendered(directory, merged)
87 git.add(root, path)
88 print(f" {path}: the two sides' receipts merged, file by file")
89 return True
90
91
92def _try_rebase(root: Path, onto: str, upstream: str = "") -> tuple[str, str]:
93 """Attempt a rebase onto *onto*; how it ended and, when it failed, git's words.
94
95 The outcome is ``clean``, ``conflict`` or ``failed``.
96
97 With *upstream*, only the commits after it move. A stop whose
98 conflicts are all render receipts resolves them and goes on
99 ([livery.workshop._sync.resolve_receipts][]). Any other stop is
100 aborted, so the branch is exactly as it was: the caller decides
101 whether a person resolves it. It stopped on a conflict when paths
102 are left unmerged. Anything else that stops it, a commit the signer
103 refused or a hook, is ``failed`` with git's own words: each needs
104 another next act, and only git's words say which.
105 """
106 try:
107 git.run(root, "rebase", *_rebase_args(onto, upstream))
108 return "clean", ""
109 except git.GitError as error:
110 stopped = error
111 while resolve_receipts(root):
112 try:
113 git.run(root, "rebase", "--continue")
114 except git.GitError as error:
115 stopped = error
116 continue
117 return "clean", ""
118 unmerged = git.unmerged_paths(root)
119 git.run(root, "rebase", "--abort")
120 return ("conflict", "") if unmerged else ("failed", str(stopped))
121
122
123def _rebase_step(
124 root: Path, onto: str, *, interactive: bool, upstream: str = ""
125) -> bool:
126 """One rebase of the current branch onto *onto*; whether it landed.
127
128 With *upstream*, only the commits after it move: a stacked branch's
129 own. Foreign-authored commits gate the rebase: rewriting them
130 orphans every other copy of the branch, so the shared-branch case
131 goes through ``fm integrate`` (a merge) unless a person says
132 otherwise. A conflicted rebase is never entered silently: an
133 interactive run may choose to resolve it now, everything else
134 parks with the teaching. A rebase stopped by anything other than a
135 conflict leaves the branch as it was and prints git's words.
136 """
137 import livery.footman as footman
138
139 branch = git.current_branch(root)
140 foreign = _foreign_authors(root, upstream or onto)
141 if foreign:
142 listed = ", ".join(sorted(foreign))
143 if not (143 ↛ 156line 143 didn't jump to line 156 because the condition on line 143 was always true
144 interactive
145 and footman.confirm(
146 f"rebasing {branch} onto {onto} rewrites commits by"
147 f" {listed}; their copies would be orphaned. Rebase anyway?"
148 )
149 ):
150 print(
151 f" left {branch} behind {onto}: it carries commits by"
152 f" {listed}, and rewriting them orphans every other copy."
153 f" Bring the base in by merge instead: `{footman.prog()} integrate`."
154 )
155 return False
156 outcome, said = _try_rebase(root, onto, upstream)
157 if outcome == "clean":
158 print(f" rebased {branch} onto {onto}")
159 return True
160 if outcome == "failed":
161 print(
162 f" left {branch} behind {onto}: the rebase stopped, and not on a"
163 " conflict. git said:"
164 )
165 for line in said.splitlines():
166 print(f" {line}")
167 print(f" Fix what git names, then run `{footman.prog()} sync` again.")
168 return False
169 if interactive and footman.confirm(169 ↛ 173line 169 didn't jump to line 173 because the condition on line 169 was never true
170 f"rebasing {branch} onto {onto} hits conflicts. Start the rebase"
171 " and resolve them now?"
172 ):
173 import contextlib
174
175 with contextlib.suppress(git.GitError):
176 git.run(root, "rebase", *_rebase_args(onto, upstream))
177 raise SystemExit(
178 " the rebase is started and waiting on you: resolve the"
179 f" conflicts, `git rebase --continue`, then run `{footman.prog()} sync`"
180 " again."
181 )
182 print(
183 f" left {branch} behind {onto}: the rebase has conflicts. Run"
184 f" `{footman.prog()} sync` interactively to resolve them, or bring the base in"
185 f" by merge with `{footman.prog()} integrate`."
186 )
187 return False
188
189
190def restack(
191 root: Path,
192 branch: str,
193 *,
194 interactive: bool,
195 stack: tuple[str, str] | None = None,
196) -> bool | None:
197 """Move a stacked branch's own commits onto its parent, or onto main once it merged.
198
199 A branch ``fm start --from`` began carries its parent's commits
200 under its own. The ones after the recorded start commit are the
201 branch's own whatever the parent became since, so they move alone:
202 onto the parent's new tip when the parent moved, onto
203 ``origin/main`` once the parent merged and origin deleted it. A
204 parent squashed from several commits then moves nothing it
205 carried, where a plain rebase replays those commits against their
206 squash and conflicts. A branch started before the start commit was
207 recorded, or moved by hand off it since, falls back on git's own
208 matching, which drops a parent that landed as one commit. A branch
209 whose parent is still open and unchanged is left where it is: main
210 reaches it through the parent.
211
212 Returns whether the branch moved; None when it was left behind; a
213 branch that is not stacked returns False. *stack* is the branch's
214 stack when the caller read it already; read here otherwise.
215 """
216 parent, tip = stack if stack is not None else _stack.stack(root, branch)
217 if not parent:217 ↛ 218line 217 didn't jump to line 218 because the condition on line 217 was never true
218 return False
219 if tip and not git.is_ancestor(root, tip, "HEAD"):219 ↛ 220line 219 didn't jump to line 220 because the condition on line 219 was never true
220 tip = "" # moved by hand since: its history no longer holds the start
221 merged = parent not in git.remote_branches(root, parent)
222 onto = "origin/main" if merged else f"origin/{parent}"
223 if not merged:
224 target = git.sha_of(root, onto)
225 if tip == target or (not tip and git.is_ancestor(root, target, "HEAD")):
226 if not tip:226 ↛ 227line 226 didn't jump to line 227 because the condition on line 226 was never true
227 _stack.record_stack(root, branch, parent, target)
228 return False
229 if not _rebase_step(root, onto, interactive=interactive, upstream=tip):
230 return None
231 if merged:
232 _stack.forget_stack(root, branch)
233 print(f" {parent} has merged: {branch} stands on main now")
234 else:
235 _stack.record_stack(root, branch, parent, git.sha_of(root, onto))
236 return True
237
238
239def _repository(root: Path) -> Any:
240 from livery.workshop._forge_lane import this_repository
241
242 return this_repository(root)
243
244
245def _leave_merged_reserved(root: Path, branch: str) -> None:
246 """Step off a reserved branch whose pull request merged; else the engine owns it.
247
248 The release act returns to the branch it started from, so a
249 checkout standing on a merged reserved branch is one an older act
250 left there. The teardown every stop verb wears removes the branch
251 and steps back onto an up-to-date main; a branch holding something
252 the merge did not take is kept and named.
253 """
254 from livery.workshop._submit import (
255 merged_pull_request,
256 only_local_work,
257 teardown_branch,
258 )
259
260 try:
261 repo = _repository(root)
262 pull = merged_pull_request(repo, root, branch)
263 except Exception:
264 repo = None
265 pull = None
266 if repo is None or pull is None:
267 print(
268 f" {branch}: a reserved branch; the engine owns it until its pull"
269 " request merges"
270 )
271 return
272 why = only_local_work(root, branch, merged_head=pull.head_sha)
273 if why:
274 print(f" {branch}: PR #{pull.number} merged, but the branch holds {why}; kept")
275 return
276 print(f" {branch}: PR #{pull.number} merged; stepping off")
277 teardown_branch(repo, root, branch, "main")
278
279
280def continue_on_moved_code(
281 root: Path, before: str, after: str, *, verb: str = "sync"
282) -> bool:
283 """Hand the command to a fresh process when the checkout moved under it.
284
285 The modules this process imported are the checkout's old code;
286 what follows a move reads the new source, and a mixed process
287 fails on the first changed signature. The handoff re-runs the
288 same command through uv on the code now on disk; *verb* names it
289 in the line. Returns False when nothing moved; when the re-run
290 cannot start it is named and the command continues on the loaded
291 code, which returns True.
292 """
293 if after == before:
294 return False
295 from livery.workshop import _reconcile
296
297 print(
298 f" the checkout moved from {before[:12]} to {after[:12]}; the {verb}"
299 " continues on that code"
300 )
301 _reconcile._reexec(root, _reconcile.MOVED) # pyright: ignore[reportPrivateUsage]
302 return True
303
304
305def continue_on_moved_extensions(root: Path, moved: tuple[str, ...]) -> None:
306 """Hand the sync to a fresh process when its install moved a mounted extension.
307
308 *moved* names the base and the extensions whose distribution the
309 sync's ``uv sync`` moved or removed; when it names none, nothing
310 happens. This process found each extension's directory as it
311 mounted it, and reads its declaration, its shipped files and its
312 code from there; it reads the base's own files, its contract, its
313 seeds and its fragments, from the directory it imported the base
314 from.
315 An install that replaces an index's wheel with an editable member
316 at another path removes that directory, and the member's path joins
317 ``sys.path`` only when a process starts; an install from another
318 editable tree leaves the old one on disk, no longer installed. The
319 fresh process re-runs the command and mounts what the environment
320 installs now; an extension the install removed is then one the
321 mount finds missing, and the fresh process installs it or refuses,
322 naming it. This process does not read a moved extension again,
323 because it imported that extension's modules from the old place
324 already.
325
326 Raises:
327 Failed: when the fresh process cannot start, or the command
328 already re-ran once for a moved extension. Nothing was
329 delivered after the install then.
330 """
331 if not moved:
332 return
333 from livery.workshop import _reconcile
334
335 names = ", ".join(moved)
336 print(
337 f" the install moved or removed {names}; the sync continues in a fresh"
338 " process, which mounts what is installed now"
339 )
340 _reconcile._reexec(root, _reconcile.RELOCATED) # pyright: ignore[reportPrivateUsage]
341 fail(
342 f"the install moved or removed {names}, and this process cannot mount"
343 f" what is installed now: run `{footman.prog()} sync` again. Nothing was"
344 " delivered after the install"
345 )
346
347
348def require_mounted(
349 root: Path, flags: tuple[str, ...] = (), *, install: bool = True
350) -> None:
351 """Refuse to render or lock while an extension of the installed set is unmounted.
352
353 The extensions mount when the command starts. One the installed set
354 holds and no installed distribution declared then (a commit the sync
355 moved onto lists it, or a person just listed it, in the root's list
356 or a package's) registered nothing, and a render or a lock without
357 it would remove its files and its tools as withdrawn. When the
358 environment holds it now, or holds it once ``uv sync`` ran with
359 *flags*, the sync hands itself to a fresh process, which mounts it.
360
361 A newly listed extension is in no lock yet, so that ``uv sync``
362 cannot install it. With *install*, it is installed the way the
363 workspace resolves it: the project file alone is written again,
364 and its dev group names the extension's distribution, then ``uv
365 sync`` locks and installs through the file's ``[tool.uv.sources]``
366 and indexes. An extension the workspace sources from a path or
367 from git installs from there. That write reads the contracts
368 without judging their keys: a key of an extension no installed
369 distribution declares yet, such as the root's ``[python]`` table
370 before python is installed, has no declaration to be judged by
371 until the install. The fresh process then judges every contract
372 over the installed declarations and renders every file with the
373 extension mounted.
374
375 One no distribution declares even then refuses, naming it and the
376 list that brings it, and so does a handoff that cannot start. Each
377 refusal, and an install that fails, first puts back the project
378 file, its receipt and ``uv.lock`` as they were before the install,
379 so nothing is rendered or locked.
380
381 Raises:
382 Failed: when a listed extension cannot be mounted in this process,
383 or the install fails.
384 """
385 from livery.workshop import _reconcile
386 from livery.workshop._extensions import (
387 declared_now,
388 stale_declarations,
389 unmounted,
390 where_listed,
391 )
392 from livery.workshop._uv import run_uv
393
394 missing = unmounted(root)
395 if not missing:
396 return
397 installed = declared_now(missing)
398 # An environment from before the checkout's declares an extension
399 # by an entry point whose package ships no declaration file: its
400 # metadata is what `uv sync` brings current.
401 if installed != missing or stale_declarations(root):401 ↛ 404line 401 didn't jump to line 404 because the condition on line 401 was always true
402 run_uv("sync", *flags, root=root)
403 installed = declared_now(missing)
404 absent = [name for name in missing if name not in installed]
405 held: dict[str, bytes | None] = {}
406 if absent and install:
407 held = _install_listed(root, flags)
408 installed = declared_now(missing)
409 absent = [name for name in missing if name not in installed]
410 if absent:
411 _put_back(root, held)
412 why = (
413 "and installing it found no distribution declaring it"
414 if install
415 else f"and a sync with {' '.join(flags)} installs nothing outside the lock"
416 )
417 where = where_listed(root)
418 named = ", ".join(
419 f"{name} ({where[name]})" if name in where else name for name in absent
420 )
421 fail(
422 f"no installed distribution declares {named}, {why}: install the"
423 " distribution that ships each, or remove the entry. Nothing was"
424 " rendered or locked"
425 )
426 print(
427 f" extensions installed by this sync: {', '.join(installed)}; the sync"
428 " continues with them mounted"
429 )
430 _reconcile._reexec(root, _reconcile.INSTALLED) # pyright: ignore[reportPrivateUsage]
431 _put_back(root, held)
432 fail(
433 f"{', '.join(installed)} installed, and this process cannot mount"
434 f" them: run `{footman.prog()} sync` again. Nothing was rendered or locked"
435 )
436
437
438def _install_listed(root: Path, flags: tuple[str, ...]) -> dict[str, bytes | None]:
439 """Install the missing listed extensions the way the workspace resolves them.
440
441 Writes the project file alone, whose dev group names each listed
442 extension's distribution, then runs ``uv sync`` with *flags*, which
443 locks first. Besides the environment, the install writes three
444 files: the project file, its receipt and ``uv.lock``. An install
445 that fails puts them back before the failure goes on.
446
447 Returns:
448 What each of the three files held before, None for one that was
449 not there, for a refusal that puts them back.
450 """
451 from livery.workshop._contract import unjudged
452 from livery.workshop._fragment_engine import RENDERED_MANIFEST
453 from livery.workshop._shipped_files import PROJECT_FILE, deliver_project_file
454 from livery.workshop._uv import run_uv
455
456 held = {
457 name: (root / name).read_bytes() if (root / name).is_file() else None
458 for name in (PROJECT_FILE, RENDERED_MANIFEST, "uv.lock")
459 }
460 try:
461 with unjudged():
462 for line in deliver_project_file(root):
463 print(line)
464 run_uv("sync", *flags, root=root)
465 except BaseException:
466 _put_back(root, held)
467 raise
468 return held
469
470
471def _put_back(root: Path, held: dict[str, bytes | None]) -> None:
472 """Write back each file of *held* that moved, or remove one that was not there."""
473 moved: list[str] = []
474 for name, body in held.items():
475 path = root / name
476 now = path.read_bytes() if path.is_file() else None
477 if now == body:
478 continue
479 moved.append(name)
480 if body is None:480 ↛ 481line 480 didn't jump to line 481 because the condition on line 480 was never true
481 path.unlink()
482 else:
483 path.write_bytes(body)
484 if moved:
485 print(f" put back as they were before the install: {', '.join(moved)}")
486
487
488def bring_current(root: Path, *, interactive: bool, fetched: bool = False) -> None:
489 """Bring the current checkout up to date; the one-stop's first act.
490
491 ``main`` only ever fast-forwards. A reserved ``workflow/`` branch
492 belongs to the engine until its pull request merges, after which
493 the checkout steps off it; a detached HEAD names no branch, a
494 clone with no ``origin`` has nothing to follow, and a dirty tree
495 is never moved: each skips with its note. A feature
496 branch fast-forwards onto its moved remote, rebases onto it when
497 diverged, then rebases onto the base; a stacked branch follows its
498 parent instead ([livery.workshop._sync.restack][]). A rebase of a
499 pushed branch finishes the job with the leased force-push, because
500 rebased-locally with a stale remote is the worst state. *fetched*
501 says origin's heads are not to be fetched here: the one fetch that
502 also mirrors the state store brought them already, or the sync is
503 offline and the remote-tracking refs the last fetch left stand.
504 """
505 _ = root
506 branch = git.current_branch(root)
507 if not branch:
508 print(" detached HEAD: nothing to bring current")
509 return
510 if not git.has_remote(root, "origin"):
511 print(" no origin remote: nothing to bring current")
512 return
513 if not fetched:
514 git.fetch(root)
515 if branch == "main":
516 ahead = git.run(root, "rev-list", "--count", "origin/main..main").strip()
517 if ahead != "0":
518 print(
519 " main has local commits origin does not: never rebased,"
520 " never merged here. Move them to a branch."
521 )
522 return
523 behind = git.run(root, "rev-list", "--count", "main..origin/main").strip()
524 if behind == "0":524 ↛ 525line 524 didn't jump to line 525 because the condition on line 524 was never true
525 return
526 try:
527 git.run(root, "merge", "--ff-only", "origin/main")
528 except Exception as error:
529 # The two states need different acts, so the refusal is
530 # named with git's own reason, never read as "local
531 # commits" (usually it is uncommitted changes in the way).
532 print(f" main is {behind} behind and the fast-forward was refused:")
533 print(f" {error}")
534 return
535 if branch.startswith("workflow/"):
536 _leave_merged_reserved(root, branch)
537 return
538 if not git.is_clean(root):
539 print(" uncommitted changes: the branch stays where it is")
540 return
541 rebased = False
542 remote_exists = branch in git.remote_branches(root, "")
543 if remote_exists:
544 ahead_remote = git.run(
545 root, "rev-list", "--count", f"origin/{branch}..{branch}"
546 ).strip()
547 behind_remote = git.run(
548 root, "rev-list", "--count", f"{branch}..origin/{branch}"
549 ).strip()
550 if behind_remote != "0":
551 if ahead_remote == "0":551 ↛ 554line 551 didn't jump to line 554 because the condition on line 551 was always true
552 git.run(root, "merge", "--ff-only", f"origin/{branch}")
553 print(f" fast-forwarded {branch} to origin/{branch}")
554 elif not _rebase_step(root, f"origin/{branch}", interactive=interactive):
555 return
556 else:
557 rebased = True
558 behind_base = git.run(root, "rev-list", "--count", f"{branch}..origin/main").strip()
559 stack = _stack.stack(root, branch)
560 parent, _tip = stack
561 if parent:
562 moved = restack(root, branch, interactive=interactive, stack=stack)
563 if moved is None:
564 return
565 if moved:
566 rebased = True
567 elif behind_base != "0":567 ↛ 576line 567 didn't jump to line 576 because the condition on line 567 was always true
568 print(
569 f" {branch} is stacked on {parent}: main reaches it when"
570 f" {parent} merges"
571 )
572 elif behind_base != "0":
573 if not _rebase_step(root, "origin/main", interactive=interactive):
574 return
575 rebased = True
576 if rebased and remote_exists:
577 # The same commits, rewritten: the lease guards anything a
578 # colleague pushed since the fetch above.
579 git.push_force(root, branch)
580 print(f" origin/{branch} follows (leased force-push)")
581
582
583def _uv_flags(
584 *,
585 frozen: bool = False,
586 locked: bool = False,
587 offline: bool = False,
588 upgrade: bool = False,
589) -> tuple[str, ...]:
590 """The uv flags for the options this verb was given, in uv's spelling."""
591 flags: list[str] = []
592 if frozen:
593 flags.append("--frozen")
594 if locked:
595 flags.append("--locked")
596 if offline:
597 flags.append("--offline")
598 if upgrade:598 ↛ 599line 598 didn't jump to line 599 because the condition on line 598 was never true
599 flags.append("--upgrade")
600 return tuple(flags)
601
602
603@task
604def lock(
605 upgrade: Forward[bool] = False,
606 upgrade_tool: Annotated[
607 list[str] | None, doc("move just these tools to their newest")
608 ] = None,
609 check: Forward[bool] = False,
610) -> None:
611 """Write both locks: `toolroom.lock` for the tools, `uv.lock` for the venv.
612
613 The pair to `sync`, in uv's shape: this decides what a checkout
614 installs and nothing on the machine changes, and `sync` installs
615 what these say. An entry that still satisfies its declarations
616 stands, so a newer release moves nothing until an upgrade asks.
617
618 ``--upgrade`` moves every entry of both locks to its newest eligible
619 version, and ``--check`` reports whether both locks are current and
620 writes nothing, exiting non-zero when either would move. Both mean
621 the same thing to each half, so both reach both.
622
623 A name does not. ``--upgrade-tool`` names tools and reaches the
624 tools alone, because a tool is not a package in ``uv.lock``: for one
625 package there, ``uv lock --upgrade-package`` is the verb.
626 """
627 from livery.workshop._tool_tasks import tools_lock
628 from livery.workshop._uv import run_uv
629
630 root = workspace_root()
631 if root is None:
632 fail("no workspace: no workshop.toml above the working directory")
633 tools_lock(upgrade_tool=upgrade_tool)
634 run_uv(
635 "lock",
636 *_uv_flags(upgrade=upgrade),
637 *(("--check",) if check else ()),
638 root=root,
639 )
640
641
642@task(interactive=True)
643def sync(
644 frozen: Forward[bool] = False,
645 locked: Forward[bool] = False,
646 offline: Forward[bool] = False,
647) -> bool:
648 """Bring the checkout current, materialise content, match the lock.
649
650 The one-stop: fast-forward or rebase the current branch (asking
651 before anything conflicted or shared; a branch started on another
652 with ``fm start --from`` follows its parent; a directory with no git
653 history, no repository or no commit, has nothing to follow), remove
654 what a removed package left under ``packages/``, fetch origin's
655 state store into the checkout's mirror for the gate to read, then
656 every extension's fragments, skills, and hooks, then the two locks.
657 Both halves match their lock the way uv does: `toolroom.sync` for the
658 tools, ``uv sync`` for the environment, each writing its lock when
659 there is none or the declarations have moved past it. Last, the
660 composed and generated files are written again, since both read the
661 locks. Idempotent: re-running it is the recovery procedure.
662
663 The three options are uv's and reach both halves: ``--frozen``
664 installs each lock as it is and resolves nothing, ``--locked``
665 refuses when a lock is not current, and ``--offline`` uses what the
666 machine already holds. As uv's two leave its lock unchanged, ours
667 change nothing a commit holds: the branch is not moved and no
668 tracked file is written, while the checkout's own untracked files
669 are. They differ as uv's do, in whether the locks are judged:
670 ``--locked`` refuses a stale one, so CI's setup runs it and a job
671 holds what a person's checkout holds; ``--frozen`` takes them as
672 they are, which is how the per-command hook brings a checkout
673 current before every command, running this verb's work frozen and
674 offline ([livery.workshop._reconcile.apply][]). Judging the tracked
675 files stays the drift check's.
676
677 A frozen sync reads the receipts first
678 ([livery.workshop._reconcile.current][]). When the environment, the
679 tools and the delivered files all match them, its local steps have
680 nothing to do and are skipped, and nothing is printed, so the hook
681 costs a current checkout those reads and nothing else. A plain sync
682 renders and installs again regardless, since a fragment edit is in
683 no receipt; the tools' supply alone reads its receipts in every
684 mode ([livery.workshop._tool_tasks.sync_tools][]).
685
686 A checkout the first act moved holds code this process has not
687 loaded, so the rest of the sync is handed to a fresh process on
688 that code; the handoff is named, and a process that cannot be
689 started continues on the loaded code and says so. An extension the
690 workspace lists that the command started without is mounted the
691 same way before anything renders or locks: a sync never renders
692 without one. A newly listed extension is installed first, the way
693 the workspace resolves it: the sync writes the project file alone,
694 whose dev group then names the extension's distribution, and runs
695 ``uv sync``, which locks and installs through the file's
696 ``[tool.uv.sources]`` and indexes. So an extension the workspace
697 sources from a path or from git installs from there. When no
698 installed distribution declares the extension even then, the sync
699 refuses, naming the extension and the list that brings it. Before
700 that refusal, and when the install fails, it puts the project file,
701 its receipt and ``uv.lock`` back as they were. A ``uv sync`` that
702 moves or removes the distribution of the workshop, or of an
703 extension the command mounted, hands the rest of the sync over the
704 same way, before anything reads it again: this process found it
705 where the install no longer puts it. A handoff that cannot start
706 then refuses, and the next sync completes.
707
708 Shell completion answers from a manifest this command wrote as it
709 started, from what was installed then. A sync that changed the
710 distributions the environment installs, run by a person at a
711 terminal, starts the detached rebuild of that manifest for the
712 directory the command was typed in
713 ([livery.footman.refresh_completion][]), so the next Tab there
714 offers the tasks an installed extension brings. A sync that changed
715 nothing installed starts nothing, and so does one no person is
716 there for, in CI or under `--no-input`. A rebuild that cannot
717 start leaves the sync's outcome as it is.
718
719 Returns:
720 Whether the local steps ran. A frozen sync of a current
721 checkout returns False.
722 """
723 root = workspace_root()
724 if root is None:724 ↛ 725line 724 didn't jump to line 725 because the condition on line 724 was never true
725 fail("no workspace: no workshop.toml above the working directory")
726 synced = sync_and_compare(root, frozen=frozen, locked=locked, offline=offline)
727 if synced.installs_changed:
728 footman.refresh_completion(footman.current().invoked_dir or root)
729 return synced.ran
730
731
732class Synced(NamedTuple):
733 """What one sync did, as `sync_and_compare` reports it."""
734
735 ran: bool
736 """Whether the local steps ran. A frozen sync of a current checkout runs none."""
737 installs_changed: bool
738 """Whether the installed distributions differ after the sync from before it."""
739
740
741def sync_and_compare(
742 root: Path, *, frozen: bool = False, locked: bool = False, offline: bool = False
743) -> Synced:
744 """Do the sync verb's work on *root*, comparing what is installed before and after.
745
746 `sync_checkout` does the work, and the options mean what they mean
747 there. The comparison reads every distribution's name and entry
748 points in the environment, so an editable member installed again
749 with new entry points counts as a change. A sync whose local steps
750 did not run changed nothing, and the environment is not read again.
751
752 Returns:
753 Whether the local steps ran, and whether they changed what the
754 environment installs.
755 """
756 from livery.workshop._reconcile import installed_distributions
757
758 before = installed_distributions(root)
759 ran = sync_checkout(root, frozen=frozen, locked=locked, offline=offline)
760 return Synced(ran, ran and installed_distributions(root) != before)
761
762
763def sync_checkout(
764 root: Path, *, frozen: bool = False, locked: bool = False, offline: bool = False
765) -> bool:
766 """Do the sync verb's work on the workspace at *root*; whether the local steps ran.
767
768 [livery.workshop._sync.sync][] runs it on the workspace above its
769 task's directory; the options mean what they mean there. The
770 per-command hook ([livery.workshop._reconcile.apply][]) runs it
771 frozen and offline on the root it found, as a plain call and never
772 as a call of the verb: a task called from a hook resolves its own
773 directory, which can lie outside *root*, and its row joins the
774 run's report, where its failure would fail the command the hook
775 must never stop.
776
777 Returns:
778 Whether the local steps ran. A frozen sync of a current
779 checkout returns False.
780
781 Raises:
782 Failed: naming what stopped the sync, a stale lock under
783 *locked* or a listed extension this process cannot mount.
784 RunFailed: when a command one of the steps runs exits non-zero.
785 """
786 if locked:
787 # Refused before anything runs, naming the lock and the sync that
788 # writes it: uv's own refusal would name uv's command instead.
789 problems = stale_locks(root)
790 if problems:
791 fail(
792 "--locked: "
793 + "; ".join(problems)
794 + f". `{footman.prog()} sync` writes the locks; commit them"
795 )
796 # Neither mode changes what a commit holds.
797 local_only = locked or frozen
798 # Each phase is a step: a receipt line with its duration, a row in
799 # --json, a slice in a profile, and a unit parallel() could schedule
800 # where two were independent. They are not yet: the fetch moves the
801 # checkout before anything renders, the delivery writes the conan
802 # workspace file the tools' build reads, the tools come before uv's
803 # build, and the last delivery and the generated files read the locks
804 # both halves just wrote.
805 fetched = False
806 mirrored: tuple[str, ...] | None = None
807 if not local_only and not offline and git.has_commits(root):
808 mirrored = _mirrored(root)
809 fetched = fetch_origin(root, mirrored)()
810 if not local_only and not git.has_commits(root):
811 print(" no git history here: nothing to bring current")
812 elif not local_only:
813 # Offline, the remote-tracking refs the last fetch left are what
814 # the checkout holds: the bring-current reads them and fetches nothing.
815 moved = bring_checkout_current(root, fetched=fetched or offline)()
816 if moved is not None:
817 continue_on_moved_code(root, *moved)
818 # Before anything renders or locks: a listed extension the mount
819 # found missing would count as withdrawn, and its files and its
820 # tools would go.
821 require_mounted(
822 root,
823 _uv_flags(frozen=frozen, locked=locked, offline=offline),
824 install=not local_only,
825 )
826 # Before anything discovers packages: a removed package's leftover
827 # directory refuses discovery until it goes.
828 for line in sweep_residue(root):
829 print(line)
830 # The receipts say what the machine holds against the locks and the
831 # delivery. A frozen sync matches the machine to them and nothing
832 # else, so when every receipt matches its local steps have nothing
833 # to do and are skipped, silently: the per-command hook runs this
834 # form before every command. A plain sync renders again regardless,
835 # since a fragment edit is in no receipt. A receipt that cannot be
836 # read is off: the steps rewrite it.
837 from livery.workshop._reconcile import current, record_receipt
838
839 try:
840 why = current(root)
841 except Exception as error:
842 why = f"the receipts could not be read ({error})"
843 skipped = frozen and not why
844 # Offline touches no network: the mirror the last fetch took stands.
845 if offline:
846 if not skipped:
847 print(" store: not fetched (--offline); the last snapshot stands")
848 elif mirrored is None or _mirrored(root) != mirrored:
849 # The fetch above named the series declared before the mount. An
850 # extension the mount installed keeps series that fetch could
851 # not name, so the mirror is taken again, and only then.
852 fetch_store_mirror(root)()
853 if skipped:
854 return False
855 if frozen:
856 print(f" {why}; syncing from what the machine holds")
857 sync_workspace_files(root, local_only=local_only)()
858 sync_locked_tools(root, frozen=frozen or locked, offline=offline)()
859 prepare_installs(root)()
860 shifted = uv_sync(root, _uv_flags(frozen=frozen, locked=locked, offline=offline))()
861 # Before anything reads an extension again: one the install moved is
862 # no longer where this process found it.
863 continue_on_moved_extensions(root, shifted)
864 deliver_files(root, local_only=local_only)()
865 if not local_only:
866 write_generated(root)()
867 # The receipt records this sync, so the next command's sync
868 # compares instead of syncing again.
869 record_receipt(root)
870 return True
871
872
873def stale_locks(root: Path) -> list[str]:
874 """What is not current about *root*'s locks; empty when both are.
875
876 The two locks `sync --locked` refuses on: `uv.lock` against the
877 project's declarations (``uv lock --check``) and `toolroom.lock`
878 against its sites. A workspace without a lock has nothing here to
879 judge. The installed plugins are read again first, since a sync in
880 another process may have moved them under this one.
881 """
882 import livery.toolroom.tools as tools
883 from livery.footman import rescan_entry_points
884 from livery.toolroom.store import LOCK_FILE
885 from livery.workshop._tools import lock_is_current
886
887 problems: list[str] = []
888 if (root / "uv.lock").is_file():
889 result = tools.uv.opts(cwd=root, nofail=True, recorded=False)("lock", "--check")
890 if result.code != 0:890 ↛ 908line 890 didn't jump to line 908 because the condition on line 890 was always true
891 said = [
892 line.strip()
893 for line in (result.stderr or result.stdout).splitlines()
894 if line.strip()
895 ]
896 if any("needs to be updated" in line for line in said):
897 problems.append(
898 "uv.lock is not current: the declarations moved past it"
899 )
900 else:
901 # Not a verdict on the lock: uv could not resolve to
902 # compare (no network, an index refused), in its words.
903 error = next((line for line in said if line.startswith("error")), "")
904 problems.append(
905 "uv.lock could not be checked"
906 + (f" ({error or said[-1]})" if said else "")
907 )
908 if (root / LOCK_FILE).is_file():
909 # A plugin's tools are read through its installed metadata. A
910 # member stamped to a new version and synced by any command in
911 # this checkout moves to a new dist-info directory, and an entry
912 # point scanned before the move then names no distribution, which
913 # drops its plugin's tools. The release train makes this check
914 # half an hour after its scan.
915 rescan_entry_points()
916 current, why = lock_is_current(root)
917 if not current:
918 problems.append(f"{LOCK_FILE} is not current ({why})")
919 return problems
920
921
922def sweep_residue(root: Path) -> list[str]:
923 """Remove what removed packages left under ``packages/``; the lines.
924
925 A directory under ``packages/`` without a ``workshop.toml`` goes
926 when git tracks nothing under it and every file it holds is one git
927 ignores: the leftovers of a package the checkout moved past the
928 removal of ([livery.workshop._packages.Leftover][]). A directory
929 holding a file git neither tracks nor ignores, or a machine secret,
930 is named and kept; one where git tracks a file is a package missing
931 its contract, which discovery refuses by name. Says nothing when
932 there is nothing to sweep.
933 """
934 import shutil
935
936 from livery.workshop._packages import (
937 RESIDUE,
938 SECRET,
939 UNKNOWN,
940 UNTRACKED,
941 leftover,
942 package_directories,
943 )
944
945 lines: list[str] = []
946 for directory in package_directories(root):
947 if (directory / "workshop.toml").is_file():
948 continue
949 found = leftover(root, directory)
950 name = directory.relative_to(root).as_posix()
951 shown = ", ".join(found.paths[:3]) + (
952 f" and {len(found.paths) - 3} more" if len(found.paths) > 3 else ""
953 )
954 if found.state == RESIDUE:
955 try:
956 shutil.rmtree(directory)
957 except OSError as error:
958 lines.append(
959 f" {name}: what a removed package left behind could not be"
960 f" removed ({error}); delete the directory by hand"
961 )
962 continue
963 lines.append(
964 f" {name}: removed {len(found.paths)} ignored file(s) a removed"
965 " package left behind"
966 )
967 elif found.state == UNTRACKED:
968 lines.append(
969 f" {name}: no workshop.toml, and it holds files git neither tracks"
970 f" nor ignores ({shown}); kept"
971 )
972 elif found.state == SECRET:
973 lines.append(
974 f" {name}: no workshop.toml, and it holds a machine secret no"
975 f" checkout restores ({shown}); kept: move the secret out, then"
976 " delete the directory"
977 )
978 elif found.state == UNKNOWN:
979 lines.append(
980 f" {name}: no workshop.toml, and git could not say what it holds"
981 f" ({found.reason}); kept"
982 )
983 return lines
984
985
986def fetch_store_lines(root: Path) -> list[str]:
987 """Mirror the store's row series into the checkout; the line to print.
988
989 The mirror is what a machine's ``check`` reads
990 ([livery.git.fetched_snapshot][]): the remote row series the
991 workspace declares ([livery.workshop._series.mirrored_series][]),
992 never a keyed family, so a sync or a start refreshes it while it
993 has the network. A fetch that fails prints its reason and stops
994 nothing: the gate falls open on a store it cannot read, and the
995 last mirror stands.
996 """
997 from livery.git import fetch_store
998
999 return store_lines(fetch_store(state_store(root), series=_mirrored(root)))
1000
1001
1002def _mirrored(root: Path) -> tuple[str, ...]:
1003 """The series a sync mirrors: the remote row series *root* declares now."""
1004 from livery.workshop._series import mirrored_series
1005
1006 return mirrored_series(root)
1007
1008
1009def store_lines(fetched: Fetched) -> list[str]:
1010 """The line `fetch_store`'s answer prints: what the mirror holds and what moved."""
1011 if fetched.why:
1012 return [
1013 f" store: origin's state store not fetched ({fetched.why}); the last"
1014 " snapshot stands"
1015 ]
1016 if not fetched.changed:
1017 return [" store: up to date"]
1018 return [f" store: {fetched.changed} ref(s) changed, {fetched.held} mirrored"]
1019
1020
1021def _fetch_origin(root: Path, series: tuple[str, ...]) -> bool:
1022 """One round trip: origin's heads for the bring-current, the series for the gate.
1023
1024 Mirrors *series* and prints the store's line. Returns whether the
1025 fetch succeeded, so the bring-current knows origin's heads are
1026 fresh; after a failed fetch it fetches for itself and fails in its
1027 own words.
1028 """
1029 from livery.git import fetch_store
1030
1031 fetched = fetch_store(state_store(root), series=series, branches=True)
1032 for line in store_lines(fetched):
1033 print(line)
1034 return not fetched.why
1035
1036
1037def _bring_checkout_current(root: Path, *, fetched: bool) -> tuple[str, str]:
1038 """Bring the checkout current; HEAD before and after, for the handoff."""
1039 before = git.head_sha(root)
1040 bring_current(root, interactive=footman.attended(), fetched=fetched)
1041 return before, git.head_sha(root)
1042
1043
1044def _fetch_store_mirror(root: Path) -> None:
1045 for line in fetch_store_lines(root):1045 ↛ 1046line 1045 didn't jump to line 1046 because the loop on line 1045 never started
1046 print(line)
1047
1048
1049def _sync_workspace_files(root: Path, *, local_only: bool) -> None:
1050 for line in sync_workspace(root, local_only=local_only):1050 ↛ 1051line 1050 didn't jump to line 1051 because the loop on line 1050 never started
1051 print(line)
1052
1053
1054def _sync_locked_tools(root: Path, *, frozen: bool, offline: bool) -> None:
1055 from livery.workshop._tool_tasks import sync_tools
1056
1057 sync_tools(root, frozen=frozen, offline=offline)
1058
1059
1060def _prepare_installs(root: Path) -> None:
1061 # What a member's install needs in place first: the sync phase's
1062 # steps say what, conan's profile among them.
1063 from livery.workshop._lifecycle import sync as sync_phase
1064 from livery.workshop._packages import discover_packages
1065
1066 sync_phase(discover_packages(root), root)
1067
1068
1069def _uv_sync(root: Path, flags: tuple[str, ...]) -> tuple[str, ...]:
1070 """Run ``uv sync``; of the base and the installed set, those whose place it changed.
1071
1072 A place is where this process reads the base or an extension and
1073 where the environment installs it (`install_places` in the
1074 extensions module): one whose place differs after the install is
1075 one the install moved or removed.
1076 """
1077 from livery.footman import rescan_entry_points
1078 from livery.workshop._extensions import install_places, stack_names
1079 from livery.workshop._uv import run_uv
1080
1081 before = install_places(stack_names(root))
1082 run_uv("sync", *flags, root=root)
1083 # The install moves a member stamped to another version to a new
1084 # dist-info directory, and an entry point scanned before the move
1085 # names no distribution after it. Every reader that follows, the
1086 # deliver step first, reads the installed metadata as it now is.
1087 rescan_entry_points()
1088 after = install_places(before)
1089 return tuple(name for name, place in before.items() if after[name] != place)
1090
1091
1092def _deliver_files(root: Path, *, local_only: bool) -> None:
1093 from livery.workshop._shipped_files import deliver
1094
1095 for line in deliver(root, local_only=local_only):
1096 print(line)
1097
1098
1099def _write_generated(root: Path) -> None:
1100 from livery.workshop._templates import apply_generated
1101
1102 for path in apply_generated(root):
1103 print(f" generated: {path}")
1104
1105
1106# The sync's phases as steps, live: each prints its own lines as it goes
1107# and earns a receipt with its duration, a row in --json and a slice in a
1108# profile. A phase's title is what every one of those shows.
1109fetch_origin = step(_fetch_origin, title="fetch origin").opts(capture=False)
1110bring_checkout_current = step(_bring_checkout_current, title="bring current").opts(
1111 capture=False
1112)
1113fetch_store_mirror = step(_fetch_store_mirror, title="fetch store").opts(capture=False)
1114sync_workspace_files = step(_sync_workspace_files, title="sync workspace").opts(
1115 capture=False
1116)
1117sync_locked_tools = step(_sync_locked_tools, title="sync tools").opts(capture=False)
1118prepare_installs = step(_prepare_installs, title="prepare install").opts(capture=False)
1119uv_sync = step(_uv_sync, title="uv sync").opts(capture=False)
1120deliver_files = step(_deliver_files, title="deliver").opts(capture=False)
1121write_generated = step(_write_generated, title="generated").opts(capture=False)
1122
1123
1124def materialise_tools(root: Path, *, offline: bool = False) -> list[str]:
1125 """Supply every locked tool through the store and write the receipts; the lines.
1126
1127 The bundle the sites require, materialised as `fm sync` and
1128 `fm toolroom.sync` enter the environment, and the stubs the
1129 checkers read written after it: a checkout with no `toolroom.lock`
1130 yet has nothing to materialise and says so. *offline* supplies from
1131 the machine's store and its sources alone.
1132 """
1133 from livery.toolroom.store import LOCK_FILE
1134 from livery.workshop._tools import current_lock, materialise, stub_lines
1135
1136 if current_lock(root) is None:
1137 return [f" tools: no {LOCK_FILE}; `{footman.prog()} toolroom.lock` writes one"]
1138 done = materialise(root, strict=False, offline=offline)
1139 supplied = [m for m in done if m.receipt is not None]
1140 installed = [m.receipt.tool for m in supplied if m.installed and m.receipt]
1141 hosted = [
1142 f"{m.receipt.tool} {m.receipt.answered}".rstrip()
1143 for m in supplied
1144 if m.receipt is not None and m.receipt.source == "host"
1145 ]
1146 lines = [
1147 (
1148 f" tools: {len(supplied)} receipt(s), installed {', '.join(installed)}"
1149 if installed
1150 else " tools: up to date"
1151 )
1152 + (f", from the host: {', '.join(hosted)}" if hosted else ""),
1153 ]
1154 lines += [f" tools: {m.note}" for m in done if m.note]
1155 lines += [f" tools: could not materialise: {m.failure}" for m in done if m.failure]
1156 return lines + stub_lines(root, strict=False, offline=offline)
1157
1158
1159@task
1160def integrate() -> None:
1161 """Bring ``origin/main`` into the current branch by merge.
1162
1163 The shared-branch spelling: a merge never rewrites, so every
1164 other copy of the branch stays valid, and the squash erases the
1165 merge commit at landing. A conflict in the render's receipts alone
1166 is merged key by key and committed; any other conflict stops with
1167 git's own words: resolve, commit, and re-run.
1168 """
1169 root = workspace_root()
1170 if root is None:1170 ↛ 1171line 1170 didn't jump to line 1171 because the condition on line 1170 was never true
1171 fail("no workspace: no workshop.toml above the working directory")
1172 branch = git.current_branch(root)
1173 if not branch or branch == "main" or branch.startswith("workflow/"):1173 ↛ 1174line 1173 didn't jump to line 1174 because the condition on line 1173 was never true
1174 fail(
1175 "integrate brings origin/main into a feature branch, and"
1176 f" you are on {branch or '(detached)'!r}."
1177 )
1178 if not git.is_clean(root):1178 ↛ 1179line 1178 didn't jump to line 1179 because the condition on line 1178 was never true
1179 fail(
1180 "the working tree has uncommitted changes: commit them first,"
1181 " so the merge has one parent to speak for you."
1182 )
1183 before = git.head_sha(root)
1184 try:
1185 git.integrate(root, "main")
1186 except git.GitError as error:
1187 if not resolve_receipts(root):
1188 fail(
1189 f"the merge stopped on conflicts:\n{error}\n Resolve them,"
1190 " `git commit`, and the branch is current; re-running any verb"
1191 " is the recovery."
1192 )
1193 git.run(root, "commit", "--no-edit")
1194 if git.head_sha(root) == before:
1195 print(" already current with origin/main")
1196 return
1197 print(f" merged origin/main into {branch}")
1198 for line in sweep_residue(root):
1199 print(line)
1200 match_lock(root, since=before)
1201
1202
1203#: The files whose change across a HEAD move leaves the venv behind:
1204#: the lock, the root manifest, and every member's.
1205LOCK_FILES = ("uv.lock", "pyproject.toml", "packages/*/pyproject.toml")
1206
1207
1208def match_lock(root: Path, *, since: str) -> None:
1209 """Match the venv to the lock when HEAD moved across a change to it; say so.
1210
1211 *since* is the commit HEAD moved from. A merge that changed the
1212 lock, the root manifest, or a member's manifest leaves the venv
1213 installed from the old ones (a new entry point the venv never
1214 learned made the next gate red until a sync); the sync runs here,
1215 at the verb's end, and the receipts record it, so the next
1216 command's reconcile finds nothing to do.
1217 """
1218 from livery.workshop._reconcile import record_receipt
1219 from livery.workshop._uv import run_uv
1220
1221 changed = git.changed_between(root, since, "HEAD", LOCK_FILES)
1222 if not changed:
1223 return
1224 print(f" matching the lock: the merge changed {', '.join(changed)}")
1225 run_uv("sync", root=root)
1226 record_receipt(root)
1227 print(" matched the lock; the environment agrees with the merge")