Recently Written · git

skills/deploy-handoff/handoff.py (30194 bytes)

 """Open a web page and wait while the user does a step that only a human may do.
 
 A tool calls this script when it reaches a step that an AI agent must not do:
 the final deploy, publish, or billing click, a sign-in, an OAuth consent, or
 the creation of a GitHub pull request. The script opens the page in the Brave
 profile that brave_profile names in the user config file, or else in the default
 browser. It shows a small dialog with the steps. It never clicks for the user.
 It prints the answer of the user as one JSON object on stdout.
 
 The command "terminal" shows the same dialog for a step at a prompt in a terminal,
 for example the install question of a tool or a sign-in of a command line program.
 It opens no page. The caller starts the program in a terminal that the user sees,
 and stops at the prompt. The script never types the answer for the user.
 
 The command "browser --fresh" starts a separate browser with a fresh profile for
 the browser-driver agent of this plugin. Use it only if the user asks for it.
 Playwright MCP controls that browser through a local port.
 
 Exit codes: 0 done, started, or running, 1 error, 2 bad arguments, 3 not done,
 4 timeout.
 """
 
 import argparse
 import contextlib
 import ctypes
 import http.client
 import json
 import os
 import re
 import shutil
 import subprocess
 import sys
 import time
 import tomllib
 import urllib.request
 import webbrowser
 from collections.abc import Callable, Iterable
 from dataclasses import dataclass
 from pathlib import Path
 from urllib.parse import quote, urlencode, urlsplit
 
 # A Wayland desktop without X11 has no Tk. Then MenuDialog shows the steps in bemenu.
 try:
     import tkinter as tk
     from tkinter import font as tkfont
     from tkinter import ttk
 
     HAVE_TK = True
 except ImportError:
     HAVE_TK = False
 
 USER_CONFIG = (
     Path(os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config")
     / "deploy-handoff"
     / "config.toml"
 )
 # The browser-driver agent uses a browser with a fresh profile of its own. Playwright MCP
 # controls it through this remote debugging port. .mcp.json at the root of the plugin uses the
 # same port.
 DEBUG_PORT = 9333
 BROWSER_PROFILE = USER_CONFIG.with_name("browser")
 # The time in seconds that a new browser gets to open DEBUG_PORT.
 BROWSER_START_SECONDS = 30
 # The browser listens on 127.0.0.1. A proxy must not get these requests.
 LOCAL_OPENER = urllib.request.build_opener(urllib.request.ProxyHandler({}))
 # GitHub refuses very long request lines. This limit keeps a margin.
 MAX_PR_URL_LENGTH = 8000
 EXIT_CODES = {"done": 0, "started": 0, "running": 0, "error": 1, "not_done": 3, "timeout": 4}
 # ASD-STE100 Simplified Technical English allows 20 words in one instruction.
 MAX_STEP_WORDS = 20
 PR_STEPS = (
     "Make sure that the branches, the title, and the description are correct.",
     'Click "Create pull request".',
 )
 HEADING = "Do these steps in your browser:"
 TERMINAL_HEADING = "Do these steps in the terminal:"
 FINISH = (
     'When you finish, click "Done".\n'
     'If you cannot finish, write the reason in the note. Then click "Not done".'
 )
 WARNING = (
     "Claude does not click for you. Before you sign in, make sure that the address bar "
     "shows the site above. Do not type a password, key, or card number in this window."
 )
 TERMINAL_WARNING = (
     "Claude does not type the answer for you. Do not type a password, key, or card number "
     "in this window."
 )
 
 # A plain DNS name in lowercase ASCII. The script refuses all other host forms,
 # so the browser and this script always read the same host from a URL.
 HOST_RE = re.compile(r"[a-z0-9-]+(?:\.[a-z0-9-]+)+")
 # Printable ASCII without a space. Callers percent-encode all other characters.
 URL_CHARS_RE = re.compile(r"[!-~]+")
 REPO_RE = re.compile(r"[A-Za-z0-9-]+/[A-Za-z0-9._-]+")
 GITHUB_REMOTE_RE = re.compile(
     r"(?:https://(?:[^@/]+@)?github\.com/|git@github\.com:|ssh://git@github\.com/)"
     r"(?P<repo>[A-Za-z0-9-]+/[A-Za-z0-9._-]+?)(?:\.git)?/?"
 )
 
 
 class HandoffError(Exception):
     """The script cannot start the handoff. The message tells the caller why."""
 
 
 @dataclass(frozen=True)
 class Request:
     """A page to open, or a terminal, and the steps that the user must do there."""
 
     title: str
     # None for a step in a terminal. Then place names the terminal.
     url: str | None
     steps: tuple[str, ...]
     # For a pull request: the repository as "owner/name", and the head branch.
     pr: tuple[str, str] | None = None
     # For a step in a terminal: where the prompt is, for example the name of a terminal tab.
     place: str | None = None
 
     def where(self) -> str:
         """Return the line that tells the user where to do the steps."""
         if self.url is None:
             return f"Where: {self.place}"
         return f"Site: {urlsplit(self.url).hostname}"
 
 
 def check_url(url: str) -> None:
     """Raise HandoffError if url is not an https URL with a plain host name.
 
     There is no list of allowed hosts: the user asks Claude to use only sites he trusts.
     The dialog shows the host, so the user can compare it with the address bar.
     """
     if "\\" in url or not URL_CHARS_RE.fullmatch(url):
         raise HandoffError(
             f"The URL must be printable ASCII with no spaces or backslashes: {url!r}"
         )
     try:
         parts = urlsplit(url)
     except ValueError as exc:
         raise HandoffError(f"The URL is not valid: {url}") from exc
     host = parts.hostname or ""
     # The netloc must be the host only: no user name, no password, and no port.
     if parts.scheme != "https" or parts.netloc.lower() != host or not HOST_RE.fullmatch(host):
         raise HandoffError(f"The URL must use https and a plain host name: {url}")
 
 
 def check_text(title: str, steps: Iterable[str]) -> None:
     """Raise HandoffError if the title or a step is not short Simplified Technical English."""
     named = [("The title", title), *((f"Step {n}", step) for n, step in enumerate(steps, 1))]
     for name, text in named:
         words = len(text.split())
         if not 0 < words <= MAX_STEP_WORDS or ";" in text:
             raise HandoffError(
                 f"{name} is not short Simplified Technical English ({words} words). "
                 f"Give one action in 1 to {MAX_STEP_WORDS} words, with no semicolons."
             )
 
 
 def check_place(place: str) -> None:
     """Raise HandoffError if place does not name a terminal in a few printable words."""
     words = len(place.split())
     if not 0 < words <= MAX_STEP_WORDS or not place.isprintable():
         raise HandoffError(
             f"The place is not a short name of a terminal ({words} words). "
             f"Give 1 to {MAX_STEP_WORDS} printable words, for example the name of the tab."
         )
 
 
 def read_config(path: Path) -> dict[str, object]:
     """Return the data of the TOML file at path."""
     try:
         return tomllib.loads(path.read_text(encoding="utf-8"))
     except (OSError, tomllib.TOMLDecodeError) as exc:
         raise HandoffError(f"Cannot read {path}: {exc}") from exc
 
 
 def brave_profile() -> str | None:
     """Return the name of the Brave profile in the user file, or None if the file names none."""
     if not USER_CONFIG.is_file():
         return None
     name = read_config(USER_CONFIG).get("brave_profile")
     if name is None:
         return None
     if not isinstance(name, str) or not name.strip():
         raise HandoffError(f"{USER_CONFIG}: brave_profile must be the name of a Brave profile.")
     return name.strip()
 
 
 def brave_data_dir() -> Path:
     """Return the folder in which Brave keeps its profiles."""
     if sys.platform == "win32":
         local = Path(os.environ.get("LOCALAPPDATA") or Path.home() / "AppData" / "Local")
         return local / "BraveSoftware" / "Brave-Browser" / "User Data"
     if sys.platform == "darwin":
         return Path.home() / "Library" / "Application Support" / "BraveSoftware" / "Brave-Browser"
     config = Path(os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config")
     return config / "BraveSoftware" / "Brave-Browser"
 
 
 def find_profile(local_state: Path, name: str) -> str:
     """Return the folder of the Brave profile with the display name name. Ignore the case."""
     try:
         cache = json.loads(local_state.read_text(encoding="utf-8"))["profile"]["info_cache"]
         folders = [
             str(folder)
             for folder, info in cache.items()
             if str(info.get("name", "")).casefold() == name.casefold()
         ]
     except (OSError, ValueError, KeyError, TypeError, AttributeError) as exc:
         raise HandoffError(f"Cannot read the Brave profiles in {local_state}: {exc!r}") from exc
     if len(folders) != 1:
         raise HandoffError(
             f"Found {len(folders)} Brave profiles with the name {name!r} in {local_state}. "
             f"Set brave_profile in {USER_CONFIG} to the name of one profile."
         )
     return folders[0]
 
 
 def open_in_profile(url: str, profile: str) -> None:
     """Open url in a new tab of the Brave profile with the display name profile."""
     exe = next((path for path in brave_candidates() if path.is_file()), None)
     if exe is None:
         raise HandoffError(f"Found no Brave. {USER_CONFIG} sets brave_profile to {profile!r}.")
     folder = find_profile(brave_data_dir() / "Local State", profile)
     # If Brave runs already, this command gives the URL to that Brave and ends.
     start_browser([str(exe), f"--profile-directory={folder}", url])
 
 
 def open_page(url: str) -> None:
     """Open url in a new tab. BROWSER can name a different default browser.
 
     Use the Brave profile of the user file if it names one. Then BROWSER has no effect.
     """
     profile = brave_profile()
     if profile is not None:
         open_in_profile(url, profile)
     elif not webbrowser.open(url, new=2):
         raise HandoffError("No browser opened the page. Set the BROWSER environment variable.")
 
 
 def browser_candidates() -> list[Path]:
     """Return the usual paths of Brave and Chrome on this system. Brave comes first."""
     if sys.platform == "win32":
         roots = [
             os.environ.get(name) for name in ("PROGRAMFILES", "PROGRAMFILES(X86)", "LOCALAPPDATA")
         ]
         programs = (
             r"BraveSoftware\Brave-Browser\Application\brave.exe",
             r"Google\Chrome\Application\chrome.exe",
         )
         return [Path(root, program) for program in programs for root in roots if root]
     if sys.platform == "darwin":
         return [
             Path("/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"),
             Path("/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"),
         ]
     names = ("brave-browser", "brave", "google-chrome", "chromium", "chromium-browser")
     return [Path(path) for name in names if (path := shutil.which(name))]
 
 
 def brave_candidates() -> list[Path]:
     """Return the usual paths of Brave on this system."""
     return [path for path in browser_candidates() if "brave" in path.name.lower()]
 
 
 def find_browser(candidates: Iterable[Path]) -> Path:
     """Return the first candidate that is a file."""
     for path in candidates:
         if path.is_file():
             return path
     raise HandoffError("Found no Brave or Chrome. Give --exe PATH.")
 
 
 def browser_command(exe: Path, profile: Path, port: int) -> list[str]:
     """Return the command that starts the browser of the browser-driver agent."""
     return [
         str(exe),
         f"--user-data-dir={profile}",
         f"--remote-debugging-port={port}",
         # Start with no window. With this flag and a remote debugging port, Chromium keeps
         # running after its last window closes. Without it, the browser stops when a person or
         # a program closes its window, and the agent cannot connect to the port.
         "--no-startup-window",
         "--no-first-run",
         "--no-default-browser-check",
         # Keep the pages active when other windows cover the window of this browser.
         "--disable-backgrounding-occluded-windows",
         "--disable-renderer-backgrounding",
         "--disable-background-timer-throttling",
     ]
 
 
 def debug_version(port: int) -> dict[str, object] | None:
     """Return the version data of the browser that listens on port, or None if none answers."""
     try:
         with LOCAL_OPENER.open(f"http://127.0.0.1:{port}/json/version", timeout=2) as response:
             data = json.load(response)
     except (OSError, ValueError, http.client.HTTPException):
         return None
     return data if isinstance(data, dict) else None
 
 
 def start_browser(command: list[str]) -> None:
     """Start the browser in a new process group, so that it runs after this script ends."""
     devnull = subprocess.DEVNULL
     try:
         if sys.platform == "win32":
             flags = subprocess.DETACHED_PROCESS | subprocess.CREATE_NEW_PROCESS_GROUP
             subprocess.Popen(
                 command, stdin=devnull, stdout=devnull, stderr=devnull, creationflags=flags
             )
         else:
             subprocess.Popen(
                 command, stdin=devnull, stdout=devnull, stderr=devnull, start_new_session=True
             )
     except OSError as exc:
         raise HandoffError(f"Cannot start {command[0]}: {exc}") from exc
 
 
 def wait_for_browser(port: int, seconds: float) -> dict[str, object]:
     """Wait until a browser answers on port. Return its version data."""
     deadline = time.monotonic() + seconds
     while (version := debug_version(port)) is None:
         if time.monotonic() > deadline:
             raise HandoffError(
                 f"The browser did not open port {port} in {seconds:g} seconds. If the browser "
                 "of the agent runs without this port, close it. Then run this command again."
             )
         time.sleep(0.5)
     return version
 
 
 def run_browser(exe: Path | None) -> dict[str, str | None]:
     """Start the browser of the browser-driver agent, or find it running."""
     status = "running"
     version = debug_version(DEBUG_PORT)
     if version is None:
         status = "started"
         BROWSER_PROFILE.mkdir(parents=True, exist_ok=True)
         exe = exe or find_browser(browser_candidates())
         start_browser(browser_command(exe, BROWSER_PROFILE, DEBUG_PORT))
         version = wait_for_browser(DEBUG_PORT, BROWSER_START_SECONDS)
     endpoint = f"http://127.0.0.1:{DEBUG_PORT}"
     return {"status": status, "browser": str(version.get("Browser")), "endpoint": endpoint}
 
 
 def github_repo(remote_url: str) -> str:
     """Return "owner/name" for the URL of a github.com remote."""
     match = GITHUB_REMOTE_RE.fullmatch(remote_url.strip())
     if match is None:
         raise HandoffError(f"{remote_url} is not a github.com remote. Give --repo OWNER/NAME.")
     return match["repo"]
 
 
 def fork_owner(remote_url: str, repo: str) -> str | None:
     """Return the owner of a GitHub remote that is not repo, for example a fork of repo, or None."""
     match = GITHUB_REMOTE_RE.fullmatch(remote_url.strip())
     if match is None or match["repo"].lower() == repo.lower():
         return None
     return match["repo"].split("/")[0]
 
 
 def compare_url(repo: str, base: str | None, head: str, title: str, body: str) -> str:
     """Return the GitHub page that shows a new pull request form with title and body filled in.
 
     head is BRANCH, or OWNER:BRANCH for a branch in a fork of repo.
     """
     # Without a base, GitHub compares head with the default branch. A branch name has no ":".
     head_ref = quote(head, safe="/:")
     refs = head_ref if base is None else f"{quote(base)}...{head_ref}"
     query = urlencode({"expand": "1", "title": title, "body": body}, quote_via=quote)
     url = f"https://github.com/{repo}/compare/{refs}?{query}"
     if len(url) > MAX_PR_URL_LENGTH:
         raise HandoffError(
             f"The pull request URL has {len(url)} characters. The limit is {MAX_PR_URL_LENGTH}. "
             "Make the body shorter."
         )
     return url
 
 
 def git(repo_dir: Path, *args: str) -> str:
     """Run git in repo_dir and return its output. Raise HandoffError if git fails."""
     command = ["git", "-C", str(repo_dir), *args]
     try:
         result = subprocess.run(
             command, capture_output=True, encoding="utf-8", errors="replace", timeout=60
         )
     except (OSError, subprocess.TimeoutExpired) as exc:
         raise HandoffError(f"{' '.join(command)} failed: {exc}") from exc
     if result.returncode != 0:
         raise HandoffError(f"{' '.join(command)} failed: {result.stderr.strip()}")
     return result.stdout.strip()
 
 
 def current_branch(repo_dir: Path) -> str:
     """Return the branch that HEAD is on."""
     branch = git(repo_dir, "branch", "--show-current")
     if not branch:
         raise HandoffError("HEAD is not on a branch. Give --head BRANCH.")
     return branch
 
 
 def check_pushed(repo_dir: Path, remote: str, branch: str) -> None:
     """Raise HandoffError if remote does not have the commit of the local branch."""
     ref = f"refs/heads/{branch}"
     local = git(repo_dir, "rev-parse", "--verify", ref)
     lines = git(repo_dir, "ls-remote", remote, ref).splitlines()
     remote_commits = [line.split()[0] for line in lines if line.split()[1:] == [ref]]
     if remote_commits != [local]:
         raise HandoffError(
             f"{remote} does not have the local commit of {branch}. Push {branch} first."
         )
 
 
 def find_open_pr(repo: str, head: str) -> str | None:
     """Return the URL of the open pull request from head, or None if gh cannot find one.
 
     head is BRANCH, or OWNER:BRANCH for a branch in a fork of repo.
     """
     owner, _, branch = head.rpartition(":")
     command = ["gh", "pr", "list", "--repo", repo, "--head", branch, "--state", "open"]
     if owner:
         # gh filters by the branch name only. The jq filter also checks the owner of the branch.
         login = f'select(.headRepositoryOwner.login | ascii_downcase == "{owner.lower()}")'
         command += ["--json", "url,headRepositoryOwner", "--jq", f"[.[] | {login}][0].url // empty"]
     else:
         command += ["--json", "url", "--jq", ".[0].url // empty"]
     try:
         result = subprocess.run(command, capture_output=True, encoding="utf-8", timeout=60)
     except (OSError, subprocess.TimeoutExpired):
         return None
     url = result.stdout.strip()
     return url if result.returncode == 0 and url else None
 
 
 def pr_request(args: argparse.Namespace) -> Request:
     """Make the request that opens the GitHub form for a new pull request."""
     repo_dir: Path = args.repo_dir
     remote_url = git(repo_dir, "remote", "get-url", args.remote)
     repo: str = args.repo or github_repo(remote_url)
     if not REPO_RE.fullmatch(repo):
         raise HandoffError(f"{repo!r} is not a repository name of the form OWNER/NAME.")
     head: str = args.head or current_branch(repo_dir)
     check_pushed(repo_dir, args.remote, head)
     # A pull request to another repository, for example from a fork to its upstream
     # repository, names the branch as OWNER:BRANCH.
     owner = fork_owner(remote_url, repo)
     head_ref = head if owner is None else f"{owner}:{head}"
     try:
         body: str = args.body_file.read_text(encoding="utf-8") if args.body_file else args.body
     except OSError as exc:
         raise HandoffError(f"Cannot read {args.body_file}: {exc}") from exc
     url = compare_url(repo, args.base, head_ref, args.title, body)
     return Request(f"Create pull request: {args.title}", url, PR_STEPS, pr=(repo, head_ref))
 
 
 class Dialog:
     """A small window on top of the browser. It shows the steps and records the answer."""
 
     def __init__(self, request: Request, timeout_minutes: float, reopen: Callable[[], None]):
         self.status = "not_done"
         self.note_text = ""
         if sys.platform == "win32":
             # Draw sharp text on high-DPI screens, as IDLE does. The call fails if the
             # process has already set the DPI awareness. That is not a problem.
             with contextlib.suppress(OSError):
                 ctypes.OleDLL("shcore").SetProcessDpiAwareness(1)
         self.root = tk.Tk()
         scale = self.root.winfo_fpixels("1i") / 96
         wrap = round(420 * scale)
         self.root.title(f"Claude handoff: {request.title}")
         self.root.attributes("-topmost", True)
         self.root.resizable(False, False)
         # Put the window in the bottom-left corner, above the taskbar. Deploy pages
         # usually put the final button on the right side.
         self.root.geometry(f"+{round(24 * scale)}-{round(80 * scale)}")
         self.root.protocol("WM_DELETE_WINDOW", lambda: self.finish("not_done"))
 
         steps = "\n".join(f"{number}. {step}" for number, step in enumerate(request.steps, 1))
         # Tk deletes a font when its Python object goes away, so the dialog keeps it.
         self.bold = tkfont.nametofont("TkDefaultFont").copy()
         self.bold.configure(weight="bold")
         frame = ttk.Frame(self.root, padding=round(12 * scale))
         frame.grid()
         # The user must see first what to do, and then where to do it.
         ttk.Label(frame, text=request.title, font=self.bold, wraplength=wrap).grid(sticky="w")
         heading = HEADING if request.url is not None else TERMINAL_HEADING
         ttk.Label(frame, text=heading, font=self.bold).grid(sticky="w", pady=(8, 0))
         ttk.Label(frame, text=steps, wraplength=wrap, justify="left").grid(sticky="w")
         where = ttk.Label(frame, text=request.where(), font=self.bold, wraplength=wrap)
         where.grid(sticky="w", pady=(8, 0))
         warning = TERMINAL_WARNING
         if request.url is not None:
             # A step on a page: show the address, and open the page again on a click.
             parts = urlsplit(request.url)
             shown = f"https://{parts.netloc}{parts.path}"
             if len(shown) > 80:
                 shown = shown[:77] + "..."
             link = ttk.Label(frame, text=shown, foreground="blue", cursor="hand2", wraplength=wrap)
             link.grid(sticky="w")
             link.bind("<Button-1>", lambda _event: reopen())
             warning = WARNING
         for text, color in ((FINISH, ""), (warning, "#b00020")):
             label = ttk.Label(frame, text=text, foreground=color, wraplength=wrap, justify="left")
             label.grid(sticky="w", pady=(8, 0))
         ttk.Label(frame, text="Note for Claude (optional):").grid(sticky="w", pady=(8, 0))
         self.note = ttk.Entry(frame)
         self.note.grid(sticky="ew")
         buttons = ttk.Frame(frame)
         buttons.grid(sticky="e", pady=(12, 0))
         self.done_button = ttk.Button(buttons, text="Done", command=lambda: self.finish("done"))
         self.done_button.grid(row=0, column=0, padx=(0, 8))
         self.not_done_button = ttk.Button(
             buttons, text="Not done", command=lambda: self.finish("not_done")
         )
         self.not_done_button.grid(row=0, column=1)
         self.timer = self.root.after(round(timeout_minutes * 60_000), self.finish, "timeout")
 
     def finish(self, status: str) -> None:
         """Record the answer and close the window."""
         self.root.after_cancel(self.timer)
         self.status = status
         self.note_text = self.note.get().strip()
         self.root.destroy()
 
     def run(self) -> tuple[str, str]:
         """Show the window until the user answers or the time ends."""
         self.root.mainloop()
         return self.status, self.note_text
 
 
 class MenuDialog:
     """The steps in a bemenu list, for a Wayland desktop that has no Tk."""
 
     DONE = "Done"
     NOT_DONE = "Not done"
 
     def __init__(self, request: Request, timeout_minutes: float, reopen: Callable[[], None]):
         if shutil.which("bemenu") is None:
             raise HandoffError("Cannot show the steps: install Python Tk or bemenu.")
         # Without a session, bemenu exits as if the user pressed Escape.
         if not os.environ.get("WAYLAND_DISPLAY"):
             raise HandoffError("Cannot show the steps: WAYLAND_DISPLAY is not set.")
         self.title = request.title
         self.deadline = time.monotonic() + timeout_minutes * 60
         steps = [f"{number}. {step}" for number, step in enumerate(request.steps, 1)]
         self.items = [
             *steps,
             request.where(),
             "If you cannot finish, type the reason and press Enter.",
             self.DONE,
             self.NOT_DONE,
         ]
 
     def run(self) -> tuple[str, str]:
         """Show the list until the user selects an answer or the time ends."""
         while (remaining := self.deadline - time.monotonic()) > 0:
             command = ["bemenu", "--list", str(len(self.items)), "--prompt", self.title]
             try:
                 answer = subprocess.run(
                     command,
                     input="\n".join(self.items),
                     capture_output=True,
                     text=True,
                     timeout=remaining,
                 )
             except subprocess.TimeoutExpired:
                 break
             choice = answer.stdout.strip()
             # Escape makes bemenu exit with code 1.
             if answer.returncode != 0 or choice == self.NOT_DONE:
                 return "not_done", ""
             if choice == self.DONE:
                 return "done", ""
             if choice not in self.items:
                 return "not_done", choice
             # The user selected a step or the site. Show the list again.
         return "timeout", ""
 
 
 def parse_args(argv: list[str] | None) -> argparse.Namespace:
     """Read the command line."""
     common = argparse.ArgumentParser(add_help=False)
     common.add_argument(
         "--timeout",
         type=float,
         default=30,
         metavar="MINUTES",
         help="the time to wait for the user (default: 30)",
     )
     parser = argparse.ArgumentParser(
         description="Open a web page and wait while the user does the final step."
     )
     commands = parser.add_subparsers(dest="command", required=True)
     page = commands.add_parser("open", parents=[common], help="open a page and show the steps")
     page.add_argument("--url", required=True, help="the https URL of the page")
     page.add_argument("--title", required=True, help="the action, for example: Publish 1.2")
     page.add_argument(
         "--step", action="append", required=True, help="one step for the user (give it again)"
     )
     page.add_argument(
         "--no-open", action="store_true", help="show only the dialog: the page is already open"
     )
     terminal = commands.add_parser(
         "terminal", parents=[common], help="show the steps for a prompt in a terminal"
     )
     terminal.add_argument("--title", required=True, help="the action, for example: Install 1.2")
     terminal.add_argument(
         "--where", required=True, help="where the prompt is, for example the name of the tab"
     )
     terminal.add_argument(
         "--step", action="append", required=True, help="one step for the user (give it again)"
     )
     pr = commands.add_parser("pr", parents=[common], help="open the GitHub pull request form")
     pr.add_argument("--title", required=True, help="the title of the pull request")
     body = pr.add_mutually_exclusive_group()
     body.add_argument("--body", default="", help="the description of the pull request")
     body.add_argument("--body-file", type=Path, help="a file with the description")
     pr.add_argument("--base", help="the branch to merge into (default: the default branch)")
     pr.add_argument("--head", help="the branch to merge (default: the current branch)")
     pr.add_argument("--repo", help="OWNER/NAME on GitHub (default: from the remote URL)")
     pr.add_argument("--remote", default="origin", help="the remote with the branch")
     pr.add_argument("--repo-dir", type=Path, default=Path(), help="the local repository")
     browser = commands.add_parser(
         "browser", help="start a browser with a fresh profile for the browser-driver agent"
     )
     browser.add_argument(
         "--fresh", action="store_true", help="confirm that the user asked for a fresh profile"
     )
     browser.add_argument("--exe", type=Path, help="the browser program (default: Brave or Chrome)")
     return parser.parse_args(argv)
 
 
 def report(result: dict[str, str | None]) -> int:
     """Print result as JSON. Return the exit code for its status."""
     print(json.dumps(result))
     return EXIT_CODES[str(result["status"])]
 
 
 def main(argv: list[str] | None = None) -> int:
     """Do the handoff. Return the exit code."""
     args = parse_args(argv)
     try:
         if args.command == "browser":
             if not args.fresh:
                 raise HandoffError(
                     "This command starts a browser with a fresh profile and no sign-in. Start it "
                     "only if the user asked for a fresh browser. Then give --fresh. Otherwise "
                     "use the Brave profile of the user."
                 )
             return report(run_browser(args.exe))
         if args.command == "terminal":
             # A step at a prompt in a terminal has no page: no host to check, nothing to open.
             check_text(args.title, args.step)
             check_place(args.where)
             request = Request(args.title, None, tuple(args.step), place=args.where)
         else:
             if args.command == "pr":
                 request = pr_request(args)
             else:
                 check_text(args.title, args.step)
                 request = Request(args.title, args.url, tuple(args.step))
             check_url(str(request.url))
             # With --no-open, the caller drove a browser to the page already.
             if args.command == "pr" or not args.no_open:
                 open_page(str(request.url))
         url = request.url
         show = Dialog if HAVE_TK else MenuDialog
         dialog = show(request, args.timeout, lambda: open_page(url) if url else None)
     except HandoffError as exc:
         return report({"status": "error", "error": str(exc)})
     status, note = dialog.run()
     result: dict[str, str | None] = {"status": status, "note": note}
     if request.pr is not None and status == "done":
         result["pr_url"] = find_open_pr(*request.pr)
     return report(result)
 
 
 if __name__ == "__main__":
     sys.exit(main())