Skip to content

livery.workshop._forge_lane

livery.workshop._forge_lane

Resolve this workspace's repository on its forge.

The workspace contract's [forge] table names the kind and owner; the repository name comes from the origin remote. Tokens resolve through livery.workshop._tokens: FORGE_TOKEN (host-qualified first), and each backend's own documented fallback when neither is set. Nothing here is inferred from ambient state beyond those documented lookups.

Functions:

Name Description
shown_url

url as a message may show it: any user and password replaced by ***.

forge_repository

This workspace's repository name on its forge: the name origin points at.

this_forge

The workspace's forge, per the contract's [forge] table.

admin_forge

The forge for an admin verb, and the variable that armed it.

admin_repository

The repository bound to the admin ladder's forge.

this_repository

The workspace's repository, per the contract and the remote.

forge_kind

The forge the workspace's contract names, github, gitea or gitlab.

pull_request_for

The pull request branch is or was the head of, or None.

shown_url

shown_url(url: str) -> str

url as a message may show it: any user and password replaced by ***.

A remote's URL can carry a token (http://oauth2:<token>@host/...), and a refusal that names the URL is printed, logged and recorded. An ssh spelling (git@host:owner/name) names a user and no secret, and is shown as it is.

Source code in packages/workshop/src/livery/workshop/_forge_lane.py
def shown_url(url: str) -> str:
    """*url* as a message may show it: any user and password replaced by ``***``.

    A remote's URL can carry a token (``http://oauth2:<token>@host/...``),
    and a refusal that names the URL is printed, logged and recorded. An
    ``ssh`` spelling (``git@host:owner/name``) names a user and no secret,
    and is shown as it is.
    """
    return _USERINFO_RE.sub(r"\g<scheme>***@", url)

forge_repository

forge_repository(root: Path) -> str

This workspace's repository name on its forge: the name origin points at.

The remote's URL in either spelling, https://host/owner/name or git@host:owner/name, with or without .git.

Raises:

Type Description
Failed

when root has no origin remote, or its URL names no owner and name.

Source code in packages/workshop/src/livery/workshop/_forge_lane.py
def forge_repository(root: Path) -> str:
    """This workspace's repository name on its forge: the name ``origin`` points at.

    The remote's URL in either spelling, ``https://host/owner/name`` or
    ``git@host:owner/name``, with or without ``.git``.

    Raises:
        Failed: when *root* has no ``origin`` remote, or its URL names
            no owner and name.
    """
    try:
        url = git.remote_url(root)
    except git.GitError as error:
        fail(f"no origin remote:\n{error}")
    match = _REMOTE_RE.search(url)
    if match is None:
        fail(f"cannot read owner/name from origin url {shown_url(url)!r}")
    return match.group("name")

this_forge

this_forge(root: Path) -> Forge

The workspace's forge, per the contract's [forge] table.

The token is FORGE_TOKEN (host-qualified first); with neither set, the backend's own documented fallback decides.

Returns:

Type Description
Forge

The connected livery.forge.Forge.

Source code in packages/workshop/src/livery/workshop/_forge_lane.py
def this_forge(root: Path) -> Forge:
    """The workspace's forge, per the contract's ``[forge]`` table.

    The token is ``FORGE_TOKEN`` (host-qualified first); with neither
    set, the backend's own documented fallback decides.

    Returns:
        The connected [livery.forge.Forge][].
    """
    contract = load_contract(root / "workshop.toml")
    forge_table = contract.get("forge") or {}
    kind = str(forge_table.get("kind", ""))
    url = str(forge_table.get("url", ""))
    if not kind:
        fail("workshop.toml [forge] must carry kind and owner")
    token, _ = forge_token(kind, url)
    return _connect(kind, url, token or None)

admin_forge

admin_forge(root: Path) -> tuple[Forge, str]

The forge for an admin verb, and the variable that armed it.

Least privilege by split tokens: the everyday verbs never read the admin name, and the admin verbs (configure, the post-abort reconcile) resolve FORGE_ADMIN_TOKEN (host-qualified first) with a fallback to the everyday token; the fallback keeps a solo developer whose one token already administers working with nothing extra. The second value names the admin variable used, "" for the fallback, so a refusal can teach the missing grant.

Source code in packages/workshop/src/livery/workshop/_forge_lane.py
def admin_forge(root: Path) -> tuple[Forge, str]:
    """The forge for an admin verb, and the variable that armed it.

    Least privilege by split tokens: the everyday verbs never read
    the admin name, and the admin verbs (configure, the post-abort
    reconcile) resolve ``FORGE_ADMIN_TOKEN`` (host-qualified first)
    with a fallback to the everyday token; the fallback keeps a solo
    developer whose one token already administers working with
    nothing extra. The second value names the admin variable used,
    "" for the fallback, so a refusal can teach the missing grant.
    """
    contract = load_contract(root / "workshop.toml")
    table = contract.get("forge") or {}
    kind = str(table.get("kind", ""))
    url = str(table.get("url", ""))
    token, var = admin_token(kind, url)
    if not var.startswith("FORGE_ADMIN_TOKEN"):
        return this_forge(root), ""
    return _connect(kind, url, token), var

admin_repository

admin_repository(root: Path) -> tuple[Repository, str]

The repository bound to the admin ladder's forge.

Source code in packages/workshop/src/livery/workshop/_forge_lane.py
def admin_repository(root: Path) -> tuple[Repository, str]:
    """The repository bound to the admin ladder's forge."""
    contract = load_contract(root / "workshop.toml")
    owner = str((contract.get("forge") or {}).get("owner", ""))
    if not owner:
        fail("workshop.toml [forge] must carry kind and owner")
    forge, var = admin_forge(root)
    return forge.repository(owner, forge_repository(root)), var

this_repository

this_repository(root: Path) -> Repository

The workspace's repository, per the contract and the remote.

Source code in packages/workshop/src/livery/workshop/_forge_lane.py
def this_repository(root: Path) -> Repository:
    """The workspace's repository, per the contract and the remote."""
    contract = load_contract(root / "workshop.toml")
    owner = str((contract.get("forge") or {}).get("owner", ""))
    if not owner:
        fail("workshop.toml [forge] must carry kind and owner")
    return this_forge(root).repository(owner, forge_repository(root))

forge_kind

forge_kind(root: Path) -> str

The forge the workspace's contract names, github, gitea or gitlab.

Empty when the contract names none, which the fake forge speaks for, and when there is no contract to read.

Source code in packages/workshop/src/livery/workshop/_forge_lane.py
def forge_kind(root: Path) -> str:
    """The forge the workspace's contract names, ``github``, ``gitea`` or ``gitlab``.

    Empty when the contract names none, which the fake forge speaks for,
    and when there is no contract to read.
    """
    path = root / "workshop.toml"
    if not path.is_file():
        return ""
    contract = load_contract(path)
    return str((contract.get("forge") or {}).get("kind", ""))

pull_request_for

pull_request_for(repo: Repository, root: Path, branch: str) -> PullRequest | None

The pull request branch is or was the head of, or None.

By head branch first, then by the branch's head commit: a forge that deletes the head branch on merge may clear the merged pull request's head ref, and the commit persists after the branch is gone. A pull request found by the commit is the branch's own only when its head branch is branch or empty, and never while branch is a stacked branch still at the commit it started from: that commit is the parent's head, so the pull request found is the parent's. A forge that cannot be asked raises; the caller decides what an unanswered question means, never this function.

Source code in packages/workshop/src/livery/workshop/_forge_lane.py
def pull_request_for(repo: Repository, root: Path, branch: str) -> PullRequest | None:
    """The pull request *branch* is or was the head of, or None.

    By head branch first, then by the branch's head commit: a forge
    that deletes the head branch on merge may clear the merged pull
    request's head ref, and the commit persists after the branch is
    gone. A pull request found by the commit is the branch's own only
    when its head branch is *branch* or empty, and never while
    *branch* is a stacked branch still at the commit it started from:
    that commit is the parent's head, so the pull request found is the
    parent's. A forge that cannot be asked raises; the caller decides
    what an unanswered question means, never this function.
    """
    pr = repo.pr.find_by_head(branch, state="all")
    if pr is not None:
        return pr
    sha = git.any_head(root, branch)
    if not sha:
        return None
    pr = repo.pr.find_by_head_sha(sha)
    if pr is None or (pr.head_branch and pr.head_branch != branch):
        return None
    _parent, start = _stack.stack(root, branch)
    return None if start == sha else pr