1"""``fm new.project``: birth, end to end, one idempotent verb.
3Seed the contract, write the project's seeds, lock and sync, deliver
4the extension content, generate the CI files, initialise git, then the
5forge half: create the repository, assert its configuration, push,
6and open the unarmed setup pull request. Every step detects done
7and walks past it, so re-running is the recovery procedure and a
8kill between any two steps costs nothing. ``--local`` is everything
9that stays on the machine and nothing that leaves it.
11The task lives above any repository, so the workspace it makes never
12needed one. The workspace's extensions are the stock list
13(``birth_extensions``) unless ``--extensions`` names them, and the
14birth writes them as their canonical list.
15"""
17from __future__ import annotations
19import datetime
20import re
21import tempfile
22from pathlib import Path
23from typing import TYPE_CHECKING, Annotated
25import livery.footman as footman
26from livery import git
27from livery.footman import Arg, doc, fail, hidden
28from livery.forge import Forge, ForgeError, Repository
29from livery.workshop._contract import toml_string
30from livery.workshop._templates import new as new_group
32if TYPE_CHECKING:
33 from livery.toolroom.tools import Result
35#: The web host each kind means when the contract carries no URL.
36_PUBLIC_HOSTS = {"github": "https://github.com", "gitlab": "https://gitlab.com"}
39#: The catalogue a newborn resolves its tools against: this extension's own
40#: published index, a strongroom store served as static files under the
41#: site the extension publishes. Hardcoded, and it moves when the site does.
42PUBLISHED_INDEX = "https://docs.willem.net/livery/tools/"
45def _sync_tools(root: Path) -> None:
46 """Write the newborn's first `toolroom.lock` and install what it names.
48 Without this a newborn's own gate reaches for checkers the store
49 never installed: the lock says what to install and nothing writes
50 one for a project that has never had one. Idempotent, like every
51 other step of the birth. The engine takes the newborn's root as a
52 value: this runs inside the birth's own task, and a task may not
53 change the process directory.
54 """
55 from livery.workshop._tool_tasks import sync_tools
57 sync_tools(root)
60def _hand_off(
61 root: Path,
62 *,
63 forge: str = "",
64 owner: str = "",
65 url: str = "",
66 local: bool = False,
67 extension: str = "",
68) -> None:
69 """Finish the birth with the runner *root*'s environment holds, inside *root*.
71 Run as ``new.project --resume`` from the project's own directory,
72 where the project's extensions are mounted at the versions it
73 locked: its tools, its composed and generated files and its forge
74 half come from them, which a process started elsewhere cannot
75 promise. The answers ride in the contract; the flags pass what it
76 does not hold. The child shares the console and its failure is the
77 birth's.
79 Raises:
80 Failed: when the environment has no runner, naming it.
81 """
82 from livery.workshop._pythons import runner_script
84 prog = footman.prog()
85 runner = runner_script(root / ".venv")
86 if not runner.is_file():
87 fail(
88 f"{runner} is missing: {root}'s environment has no {prog} to finish"
89 f" the birth with. `uv sync` in {root} installs it; then run"
90 f" `{prog} new.project --resume` there"
91 )
92 argv = [str(runner), "new.project", "--resume"]
93 argv += [
94 f"--{key}={value}"
95 for key, value in (
96 ("forge", forge),
97 ("owner", owner),
98 ("url", url),
99 ("extension", extension),
100 )
101 if value
102 ]
103 if local:103 ↛ 105line 103 didn't jump to line 105 because the condition on line 103 was always true
104 argv.append("--local")
105 print(f" environment: the birth continues with {runner}")
106 footman.run(argv, cwd=root, capture=False)
109def _git(root: Path, *args: str) -> str:
110 """Run git under *root*; stdout, or fail with git's own words."""
111 try:
112 return git.run(root, *args)
113 except git.GitError as error:
114 fail(str(error))
117def _git_outside(*args: str) -> Result:
118 """Run git where no repository is implied; the result, never a refusal.
120 The birth verb runs above any repository, and several of its
121 questions must not be answered by whatever repository the
122 person happens to stand in. The temporary directory is that
123 nowhere. Every caller reads the exit code itself.
124 """
125 return git.call(Path(tempfile.gettempdir()), *args)
128def _git_config(name: str) -> str:
129 """A global git config value, empty when unset."""
130 result = _git_outside("config", "--global", "--get", name)
131 return result.stdout.strip() if result.code == 0 else ""
134def _clone_url(kind: str, url: str, owner: str, name: str) -> str:
135 """The remote the newborn pushes to, credential-free."""
136 web = (url or _PUBLIC_HOSTS.get(kind, "")).rstrip("/")
137 if not web:
138 fail("the forge needs a URL: pass --url (gitea has no public default)")
139 return f"{web}/{owner}/{name}.git"
142def _remote_is_foreign(clone_url: str) -> bool:
143 """Whether the remote already has commits (foreign, never adopted)."""
144 listing = _git_outside("ls-remote", clone_url)
145 return listing.code == 0 and bool(listing.stdout.strip())
148def _connect(kind: str, url: str) -> tuple[Forge, str]:
149 """The target forge on the everyday token ladder, and the token.
151 The token rides back so the pushes can authenticate with it: the
152 committed remote stays credential-free (a human's pushes ride
153 their credential helper), and automation pushes to a
154 token-carrying URL instead, the way the emitted GitLab lane and
155 the stamp transport already do.
156 """
157 from livery.workshop._forge_lane import _connect as connect
158 from livery.workshop._tokens import forge_token
160 token, _ = forge_token(kind, url)
161 forge = connect(kind, url, token or None)
162 if not token:
163 # The connection resolved its own dialect variable; the push
164 # credential mirrors that resolution or automation cannot
165 # push at all.
166 token = forge.token
167 return forge, token
170def _push_target(clone_url: str, token: str) -> str:
171 """Where pushes go: the token-embedded URL when one resolved.
173 Only http(s) URLs can carry the credential; anything else pushes
174 to the remote as-is. The token-embedded URL is a
175 [livery.footman.Secret][]: a profile trace and every other place
176 a command line is shown carry ``***`` in its place, and git alone
177 receives the value. The caller passes it to git unchanged, since
178 any string operation on it returns a plain `str`, which is shown
179 in the clear.
180 """
181 if token and clone_url.startswith(("http://", "https://")):
182 scheme, _, rest = clone_url.partition("://")
183 return footman.Secret(f"{scheme}://oauth2:{token}@{rest}")
184 return "origin"
187#: The extensions a stock App's birth lists, as their canonical list:
188#: the type checker's, the changelog's, coverage's, the site's API
189#: reference, which requires the site's, the test runner's, python and
190#: the python formatter's. python is the language of the workspace's own
191#: tests and ``tasks.py``: those tests hold the root's set, and run while
192#: it holds python. An agent's files are a choice the project makes, so
193#: no agent's extension is among them.
194STOCK = (
195 "basedpyright",
196 "changelog",
197 "coverage",
198 "mkdocstrings",
199 "pytest",
200 "python",
201 "ruff",
202)
205def birth_extensions(builtin: list[str] | tuple[str, ...]) -> list[str]:
206 """The extensions a birth lists, from the running App's builtin providers.
208 Footman's own providers and the base are never listed. A stock App
209 (the base among its builtins) lists the stock list (``STOCK``), and
210 a branded App its own extensions beside them, all as their
211 canonical list (``canonical_extensions``). A brand's extension
212 takes another's file or step by requiring it and declaring the
213 replacement, never by where it is listed.
214 """
215 kept = [entry for entry in builtin if not entry.startswith("footman.")]
216 kept = kept or ["livery.workshop"]
217 listed = [entry for entry in kept if entry != "livery.workshop"]
218 if "livery.workshop" in kept:
219 listed[:0] = STOCK
220 return canonical_extensions(listed)
223def canonical_extensions(names: list[str] | tuple[str, ...]) -> list[str]:
224 """*names* as the canonical list a birth writes.
226 The minimal list of their set in composition order, as the installed
227 declarations compose it: an extension another one requires is left
228 out, and a name no installed distribution declares requires
229 nothing.
231 Raises:
232 Failed: when the set's declared order has no start, naming the
233 cycle.
234 """
235 from livery.workshop._composition import OrderCycle, canonical
236 from livery.workshop._extensions import installed_declaration
238 try:
239 return list(canonical(names, installed_declaration))
240 except OrderCycle as error:
241 fail(f"the extensions cannot be listed: {error}")
244@new_group.task(name="project", expose="always", interactive=True, cwd="asinvoked")
245def new_project(
246 folder: Annotated[
247 Arg[str],
248 doc("where the project is born, an empty or new folder; this one by default"),
249 ] = "",
250 name: Annotated[
251 str, doc("the workspace's name, also the repository's; the folder's by default")
252 ] = "",
253 forge: Annotated[str, doc("github, gitea, or gitlab; github by default")] = "",
254 owner: Annotated[
255 str, doc("the owner or organisation the repository lives under")
256 ] = "",
257 url: Annotated[
258 str, doc("the forge server (empty for github.com and gitlab.com)")
259 ] = "",
260 description: Annotated[str, doc("one sentence for the virtual root")] = "",
261 author: Annotated[str, doc("the authors entry's name (default: git config)")] = "",
262 email: Annotated[str, doc("the authors entry's email (default: git config)")] = "",
263 namespace: Annotated[str, doc("dotted namespace packages live in")] = "",
264 extension: Annotated[
265 str,
266 doc(
267 "also scaffold this named extension package, with its branded App,"
268 " and self-host it: the workspace becomes the extension's home"
269 ),
270 ] = "",
271 local: Annotated[
272 bool, doc("everything that stays on the machine, nothing that leaves it")
273 ] = False,
274 extensions: Annotated[
275 str,
276 doc(
277 "the extensions the workspace lists, comma-separated, each by name,"
278 " written as their canonical list; the stock list by default, which"
279 " names python for the workspace's own tests"
280 ),
281 ] = "",
282 resume: Annotated[bool, hidden] = False,
283) -> None:
284 """Create a workspace in an empty or new folder, end to end, as one verb.
286 The birth seeds the contract, whose ``[workspace] extensions`` is
287 the stock list or the one ``--extensions`` names, written as its
288 canonical list: no extension another one requires, in composition
289 order. The stock list names python: the workspace's own tests hold
290 the root's set, and run while it holds python. It writes the
291 project's files, locks and syncs its environment, then hands the
292 rest to the runner that environment holds, run as
293 ``new.project --resume`` inside the project. There the project's
294 own extensions are mounted, so its
295 tools, its composed and generated files and its forge half come
296 from them at the versions it locked. A folder that holds a project
297 refuses, naming ``--resume``, which finishes that project's birth:
298 every step of it detects done and walks past it, so it is also
299 the recovery after a birth that stopped part way. Headless runs
300 never hang; a missing required answer is a refusal listing what to
301 pass.
302 """
303 # The task's directory is the launch directory (`asinvoked`), not
304 # the directory of whichever tasks file mounted the verb: the folder
305 # means where the caller stands.
306 here = footman.cwd()
307 root = (here / folder).resolve() if folder else here
308 prog = footman.prog()
309 held = (root / "workshop.toml").is_file()
310 if resume:
311 if not held:
312 fail(
313 f"{root} holds no project to resume: `{prog} new.project`"
314 " births one into an empty or new folder"
315 )
316 from livery.workshop._extensions import workspace_root
318 # Inside the project this process is its own runner; elsewhere
319 # the project's runner finishes it.
320 finish = _finish if workspace_root() == root else _hand_off
321 finish(
322 root, forge=forge, owner=owner, url=url, local=local, extension=extension
323 )
324 return
325 if held:
326 fail(
327 f"{root} holds a project already; `{prog} new.project --resume`"
328 " finishes its birth"
329 )
330 if root.exists() and any(root.iterdir()):
331 fail(f"{root} is not empty: a project is born into an empty or new folder")
332 name = name or root.name
333 forge = forge or "github"
334 _check_answers(name, forge=forge, owner=owner, url=url, local=local)
335 # The contract: a birth-time seed the render never touches. The
336 # list is the running App's own builtin providers, minus footman's
337 # and the base, which is never listed (contract 19): a branded App's
338 # children carry its extensions. Stock fm's carry the stock list,
339 # whose distributions the newborn's sync installs.
340 # footman.BUILTIN is an import-time snapshot of the stock brand;
341 # the running App's own list lives in _paths.builtin() (a public
342 # runtime accessor is footman#536's family). It is composed before
343 # the folder is made, so a list that cannot be written leaves none.
344 from livery.footman import builtins
346 named = [e.strip() for e in extensions.split(",") if e.strip()]
347 listed = canonical_extensions(named) if named else birth_extensions(builtins())
348 root.mkdir(parents=True, exist_ok=True)
349 contract = root / "workshop.toml"
350 spelled = ", ".join(f'"{entry}"' for entry in listed)
351 year = str(datetime.datetime.now(tz=datetime.UTC).year)
352 author_name = author or _git_config("user.name") or f"{name} authors"
353 author_email = email or _git_config("user.email")
354 person = f"{{ name = {toml_string(author_name)}"
355 if author_email:355 ↛ 357line 355 didn't jump to line 357 because the condition on line 355 was always true
356 person += f", email = {toml_string(author_email)}"
357 person += " }"
358 lines = [
359 "[workspace]",
360 f"name = {toml_string(name)}",
361 "description = "
362 + toml_string(description or f"The {name} monorepo (virtual root)."),
363 f"namespace = {toml_string(namespace or name.replace('-', '_'))}",
364 f"authors = [{person}]",
365 f'copyright-year = "{year}"',
366 f"extensions = [{spelled}]",
367 ]
368 lines += ["", "[forge]", f'kind = "{forge}"']
369 if owner:
370 lines.append(f'owner = "{owner}"')
371 if url:
372 lines.append(f'url = "{url}"')
373 lines += [
374 "",
375 "[toolroom]",
376 f'index = "{PUBLISHED_INDEX}"',
377 "",
378 "[ci]",
379 'runners = ["ubuntu-latest"]',
380 'required-context = "gate"',
381 ]
382 contract.write_text("\n".join(lines) + "\n", encoding="utf-8")
383 print(" workshop.toml: seeded")
385 _prepare(root)
386 _hand_off(root, local=local, extension=extension)
389def _check_answers(name: str, *, forge: str, owner: str, url: str, local: bool) -> None:
390 """Refuse answers no birth can use, listing what to pass."""
391 if not re.fullmatch(r"[a-z][a-z0-9-]*", name):
392 fail(
393 f"project name {name!r}: use lowercase letters, digits, hyphens"
394 " (the folder's name, unless --name gives one)"
395 )
396 if forge not in ("github", "gitea", "gitlab"):396 ↛ 397line 396 didn't jump to line 397 because the condition on line 396 was never true
397 fail(f"unknown forge kind {forge!r}: use github, gitea, or gitlab")
398 if not local and not owner:
399 fail(
400 "answers missing for the forge half: pass --owner (and --url"
401 " for a self-hosted server), or --local for everything that"
402 " stays on the machine"
403 )
404 if forge == "gitea" and not local and not url:
405 fail("gitea has no public default server: pass --url")
408def _prepare(root: Path) -> None:
409 """Write what a newborn starts with, then lock and sync its environment.
411 The seeds are the files a workspace starts with, its own from then
412 on: one that exists is never touched, so a resumed birth writes
413 only what a stopped one did not. The project file is composed from
414 the answers and the lock reads it, so the composed files are
415 written before the first lock.
416 """
417 from livery.workshop._identity import project_facts
418 from livery.workshop._seeds import PROJECT, create
419 from livery.workshop._shipped_files import deliver
420 from livery.workshop._templates import package_injections
421 from livery.workshop._uv import run_uv
423 seeded = create(
424 root, root, PROJECT, {**project_facts(root), **package_injections(root)}
425 )
426 print(f" seeds: {len(seeded)} written" if seeded else " seeds: already written")
427 for line in deliver(root):
428 print(line)
429 run_uv("lock", root=root)
430 run_uv("sync", root=root)
431 print(" environment: locked and synced")
434def _finish(
435 root: Path,
436 *,
437 forge: str = "",
438 owner: str = "",
439 url: str = "",
440 local: bool = False,
441 extension: str = "",
442) -> None:
443 """Finish *root*'s birth from inside it: everything after its environment.
445 The answers come from the contract the birth seeded; a flag passes
446 what it does not hold, the owner a local birth left out, say.
447 """
448 from livery.workshop._contract import load_contract
450 contract = load_contract(root / "workshop.toml")
451 workspace = contract.get("workspace") or {}
452 seeded = contract.get("forge") or {}
453 name = str(workspace.get("name", root.name))
454 description = str(workspace.get("description", ""))
455 forge = forge or str(seeded.get("kind", "github"))
456 owner = owner or str(seeded.get("owner", ""))
457 url = url or str(seeded.get("url", ""))
458 _check_answers(name, forge=forge, owner=owner, url=url, local=local)
459 _prepare(root)
461 _sync_tools(root)
463 from livery.workshop._sync import sync_workspace
465 for line in sync_workspace(root):465 ↛ 466line 465 didn't jump to line 466 because the loop on line 465 never started
466 print(line)
468 from livery.workshop._templates import apply_project
470 for changed in apply_project(root):
471 print(f" rendered: {changed}")
473 if extension:
474 _add_extension(root, extension)
476 if not (root / ".git").is_dir():
477 _git(root, "init", "-q", "--initial-branch=main")
478 print(" git: initialised")
479 else:
480 print(" git: already initialised")
481 if not git.has_commits(root):
482 _git(root, "add", "-A")
483 _git(root, "commit", "-q", "-m", "chore: birth")
484 print(" git: birth committed")
485 else:
486 _git(root, "add", "-A")
487 status = _git(root, "status", "--porcelain")
488 if status.strip():488 ↛ 489line 488 didn't jump to line 489 because the condition on line 488 was never true
489 _git(root, "commit", "-q", "-m", "chore: birth aftercare")
490 print(" git: aftercare committed")
492 if local:
493 print(
494 " --local: done. Skipped, because they leave the machine:"
495 " repo.create, the repository configuration, the push, and"
496 f" the setup PR. `{footman.prog()} new.project --resume"
497 " --owner=...` here finishes the forge half."
498 )
499 return
501 clone_url = _clone_url(forge, url, owner, name)
502 target, push_token = _connect(forge, url)
503 push_to = _push_target(clone_url, push_token)
504 existing = target.get_repo(owner, name)
505 created_now = False
506 if existing is None:
507 target.create_repo(
508 owner,
509 name,
510 private=True,
511 description=description or f"The {name} monorepo (virtual root).",
512 )
513 created_now = True
514 print(f" repository: created {owner}/{name}")
515 elif _remote_is_foreign(clone_url) and not _pushed_by_us(root, clone_url):
516 fail(
517 f"{owner}/{name} already exists on the forge with its own"
518 " history: pick another name, or delete the foreign"
519 " repository first. Nothing was pushed."
520 )
521 else:
522 print(f" repository: {owner}/{name} already exists; adopting")
524 remotes = _git(root, "remote")
525 if "origin" in remotes.split():
526 _git(root, "remote", "set-url", "origin", clone_url)
527 else:
528 _git(root, "remote", "add", "origin", clone_url)
529 if created_now:
530 # The protocol initialises a created repository with a default
531 # branch, so the birth history replaces that init commit; the
532 # repository is seconds old and this checkout is its author.
533 _git(root, "push", "-q", "--force", "-u", push_to, "main")
534 print(" pushed: main")
535 else:
536 pushed = git.call(root, "push", "-q", "-u", push_to, "main")
537 if pushed.code == 0:537 ↛ 539line 537 didn't jump to line 539 because the condition on line 537 was always true
538 print(" pushed: main")
539 elif "protected branch" in f"{pushed.stdout}{pushed.stderr}":
540 # The resumed repository already governs itself: main
541 # moves through pull requests now, so local aftercare
542 # stays here and rides the next submitted branch.
543 print(
544 " main is protected (the birth already configured it):"
545 " the local commits stay here; submit them as a pull"
546 f" request with `{footman.prog()} submit`"
547 )
548 else:
549 fail(f"git push exited {pushed.code}:\n{pushed.stdout}{pushed.stderr}")
551 from livery.workshop._workflow_tasks import assert_configuration
553 assert_configuration(root)
555 _open_setup_pr(root, target.repository(owner, name), push_to)
556 print(
557 " done: merge the setup PR to prove the gate; the repository"
558 " is protected and live"
559 )
562def _add_extension(root: Path, extension: str) -> None:
563 """Scaffold *extension* and self-host it: the workspace becomes its home.
565 The extension package is born from the ``workshop-extension``
566 template with its branded App, a script named after the extension's
567 directory, and the contract's list gains its import path, written
568 again as its canonical list, so the home composes with its own
569 extension at HEAD from the first commit. Idempotent: an
570 already-listed extension walks past.
571 """
572 from livery.workshop._sync import sync_workspace
573 from livery.workshop._templates import render_member, wire_member
575 if (root / "packages" / extension).exists():
576 print(f" extension: packages/{extension} already scaffolded")
577 return
578 app = extension.rsplit("/", 1)[-1]
579 import_path = render_member(root, extension, "workshop-extension", {"app": app})
580 # Wired in the birth's own process: the template needs python, which
581 # the root's list holds, so this process mounted it already, and a
582 # list without python refused the render above.
583 wire_member(root, extension)
584 contract = root / "workshop.toml"
585 text = contract.read_text("utf-8")
586 if f'"{import_path}"' not in text:586 ↛ 604line 586 didn't jump to line 604 because the condition on line 586 was always true
587 import tomllib
589 match = re.search(r"^extensions = \[(.*)\]$", text, flags=re.M)
590 if match is None:590 ↛ 591line 590 didn't jump to line 591 because the condition on line 590 was never true
591 fail(
592 f"cannot self-host {import_path}: the contract has no"
593 " extensions line; add it by hand"
594 )
595 workspace = tomllib.loads(text).get("workspace", {})
596 named = [str(entry) for entry in workspace.get("extensions", [])]
597 listed = canonical_extensions([*named, import_path])
598 written = ", ".join(f'"{entry}"' for entry in listed)
599 text = text[: match.start()] + f"extensions = [{written}]" + text[match.end() :]
600 contract.write_text(text, encoding="utf-8")
601 print(f" extensions: {import_path} self-hosted")
602 # The stack changed: re-deliver content and re-render through the
603 # composed source, so the home's files carry its own overlay.
604 from livery.workshop._templates import apply_project as reapply
606 for line in sync_workspace(root):606 ↛ 607line 606 didn't jump to line 607 because the loop on line 606 never started
607 print(line)
608 for changed in reapply(root):608 ↛ 609line 608 didn't jump to line 609 because the loop on line 608 never started
609 print(f" rendered: {changed}")
612def _pushed_by_us(root: Path, clone_url: str) -> bool:
613 """Whether the remote's main is this checkout's history (a resume)."""
614 try:
615 sha = git.ls_remote(root, "refs/heads/main", remote=clone_url).get(
616 "refs/heads/main", ""
617 )
618 except git.GitError:
619 sha = ""
620 if not sha:620 ↛ 621line 620 didn't jump to line 621 because the condition on line 620 was never true
621 return True # exists but empty: get-or-create proceeds
622 return git.tracks(root, sha)
625#: The setup branch: a trivial change whose PR proves the gate wires
626#: end to end before any real work rides it.
627_SETUP_BRANCH = "chore/setup-check"
630def _open_setup_pr(root: Path, repo: Repository, push_to: str) -> None:
631 """Open the unarmed setup PR; find it instead when it exists."""
632 found = repo.pr.find_by_head(_SETUP_BRANCH)
633 if found is not None:
634 print(f" setup PR: already open (#{found.number})")
635 return
636 branches = _git(root, "branch", "--list", _SETUP_BRANCH)
637 if not branches.strip():637 ↛ 639line 637 didn't jump to line 639 because the condition on line 637 was always true
638 _git(root, "branch", _SETUP_BRANCH, "main")
639 _git(root, "push", "-q", push_to, _SETUP_BRANCH)
640 # The branch needs a diff or some forges refuse the PR; an empty
641 # commit rides it, evaporating in the squash.
642 tip = _git(root, "rev-parse", _SETUP_BRANCH).strip()
643 main = _git(root, "rev-parse", "main").strip()
644 if tip == main:644 ↛ 649line 644 didn't jump to line 649 because the condition on line 644 was always true
645 _git(root, "switch", "-q", _SETUP_BRANCH)
646 _git(root, "commit", "-q", "--allow-empty", "-m", "chore: setup check")
647 _git(root, "push", "-q", push_to, _SETUP_BRANCH)
648 _git(root, "switch", "-q", "main")
649 try:
650 opened = repo.pr.open(
651 _SETUP_BRANCH,
652 "main",
653 "chore: setup check",
654 "The birth verb's proof: CI runs, the gate reports, branch"
655 " protection holds. Merge when green; the squash evaporates"
656 " the empty commit.",
657 )
658 except ForgeError as error:
659 fail(f"the setup PR did not open:\n{error}")
660 print(f" setup PR: opened #{opened.number}, unarmed")