taskops-cli 0.4.0__py3-none-any.whl → 0.4.2__py3-none-any.whl

taskops/_version.py

@@ -1,4 +1,4 @@
 from __future__ import annotations
 
 __title__ = "taskops"
-__version__ = "0.4.0"  # single source of truth; pyproject reads it dynamically
+__version__ = "0.4.2"  # single source of truth; pyproject reads it dynamically

taskops/_wire.py

@@ -1,4 +1,6 @@
 """One POST, one envelope, one place that turns an HTTP failure into OUR error.
+And, since the OWNER's `board forge` learned to ask GitHub, one GET that
+deliberately does NOT wear that envelope — `text()` at the bottom says why.
 
     {"ok": true,  "seq": 41, "data": {...}}     ->  the data, with `seq` in it
     {"ok": false, "error": {"code", "message"}} ->  raised, in the SERVER's words
@@ -53,6 +55,52 @@ def post(
     return _unwrap(envelope, url)
 
 
+def text(url: str, headers: dict[str, str], timeout: float) -> tuple[int, str]:
+    """GET a foreign body UNDECODED — the status, and whatever bytes came back.
+
+    `post` unwraps `{"ok", "data"}` because both of its callers speak to a
+    taskops door. GitHub does not: it answers its own shape and says what it
+    MEANS in the status — 401 is a bad token, 404 is "no repo you can see" — so
+    flattening those into one error would throw away the only thing the caller
+    can turn into a sentence somebody can act on.
+
+    Nor is the body decoded here. It briefly was, into an OBJECT, and its two
+    callers cannot use that: `https://github.com/<login>.keys` answers
+    `text/plain`, one ssh key line each, and `/repos/…/collaborators` answers a
+    JSON ARRAY, which `as_object` flattens to `{}` — a page of people read as
+    nobody, silently. So the decoding belongs to whoever knows what it asked
+    for, and what is shared here is the part that must never differ: the status
+    is preserved, and a failure with NO status at all — refused connection, DNS
+    miss, timeout — is `Unreachable` rather than an empty answer somebody could
+    read as "this person has no keys" and then quietly leave them out of a
+    team.
+    """
+    request = Request(url, headers=headers, method="GET")  # noqa: S310 — https, from our config
+    try:
+        with urlopen(request, timeout=timeout) as answer:  # noqa: S310
+            return int(answer.status), _read(answer.read())
+    except HTTPError as err:
+        return int(err.code), _read(_body_of(err))
+    except (URLError, TimeoutError, ValueError) as err:
+        raise Unreachable(
+            f"{url} did not answer ({err}). Nothing was granted and nothing was written — "
+            "a host that cannot ask does not guess."
+        ) from err
+
+
+def _body_of(err: HTTPError) -> bytes:
+    try:
+        return err.read()
+    except OSError:  # pragma: no cover — a body that dies mid-read
+        return b""
+
+
+def _read(raw: bytes) -> str:
+    """Undecodable bytes are not an exception here: the STATUS already carried
+    the meaning, and a mangled character must not become `Unreachable`."""
+    return raw.decode("utf-8", "replace")
+
+
 def _unwrap(body: dict[str, Any], url: str) -> dict[str, Any]:
     """v1 let three verbs answer with a bare array, which the client decoder turned
     into `{}` with no error anywhere. Here a missing envelope is loud."""

taskops/cli/commands.py

@@ -1,7 +1,9 @@
-"""The two commands that CONNECT a repo to a board, and the git hooks.
+"""The two commands that CONNECT a repo to a board: `init` and `join`.
 
-`serve`, `invite` and `ui` — the ones that run a server — live in `serving.py`.
-`main.py` only parses and dispatches.
+`serve`, `invite` and `ui` — the ones that run a server — live in `serving.py`,
+and what the git hooks call is `hooks.py`. Both were split off this file rather
+than growing it: these two WRITE a checkout's configuration once, and neither
+runs a server nor fires on every commit. `main.py` only parses and dispatches.
 """
 
 from __future__ import annotations
@@ -13,10 +15,10 @@ from pathlib import Path
 from . import enrol, watch
 from .. import session, identity
 from .._json import query
-from ..board import DIR, find_root, open_board
+from ..board import DIR, find_root, open_board, read_config
 from ..store import log
 from .._errors import TaskopsError
-from ..gitwork import run, bind, remote, install, trailer, claudefiles
+from ..gitwork import remote, install, claudefiles
 
 # ── the commands ────────────────────────────────────────────────────────────
 
@@ -24,7 +26,7 @@ from ..gitwork import run, bind, remote, install, trailer, claudefiles
 def init(here: Path) -> int:
     root = find_root(here)
     (root / DIR / "board").mkdir(parents=True, exist_ok=True)
-    (root / DIR / "board.json").write_text("{}\n", encoding="utf-8")
+    install.write_local(root)
     _wire(root, actor())
     print(f"local board in {root / DIR / 'board'} — the MCP tools are the way in")
     return 0
@@ -41,14 +43,21 @@ ORPHAN = (
 
 
 def join(
-    here: Path, target: str, given: str, key: str = "", discard: bool = False, invite: str = ""
+    here: Path,
+    target: str,
+    given: str,
+    key: str = "",
+    discard: bool = False,
+    invite: str = "",
 ) -> int:
-    """Connect this repo to a board. Bare like every other verb since the host is
-    recorded and the key is discovered:
-
-        taskops remote add https://host:8787        once per checkout
-        taskops join my-project                     registered key: signs in, done
-        taskops join my-project --invite <id>       first time: enrols the key too
+    """Connect this repo to a board. Bare like every other verb: the address is
+    CARRIED by the clone, the key is discovered, and the recorded remote is the
+    fallback for a checkout that carries nothing:
+
+        taskops join                                a clone: board.json travels, done
+        taskops join my-project --invite <id>       first time by invite: enrols the key
+        taskops remote add https://host:8787        no carried address? record the host…
+        taskops join my-project                     …and name the board
         taskops join my-project                     no key anywhere + public board: read-only
 
     The name defaults exactly as `board create`'s does (recorded name, else the
@@ -64,21 +73,38 @@ def join(
     archives (never deletes) before proceeding.
 
     With an invite, the invite and the PUBKEY travel in the same call: the server
-    burns the invite and enrols the key in one act. Either way the key then signs
-    in ON THE SPOT and what lands in remote.json is a SESSION with an expiry —
-    never a standing token to copy around. Keys exist so tokens do not travel.
+    burns the invite and enrols the key in one act. The key then signs in ON THE
+    SPOT and what lands in remote.json is a SESSION with an expiry — never a
+    standing token to copy around. Keys exist so tokens do not travel.
+
+    **There is no GitHub branch here any more, and there must not be one again.**
+    The flag that was here posted the joiner's own GitHub token to the host to be
+    verified, which made every dev's credential travel for a fact the OWNER
+    already holds. `taskops board forge` enrols the team from the owner's laptop
+    instead, so a dev whose key that sync published arrives at the `bare and
+    found` branch below: the plain `taskops join`, nothing to prove, nothing to
+    type, and no token of theirs anywhere.
     """
     from . import remote as remote_cli
 
     root = find_root(here)
     bare = "://" not in target
     if bare:
-        host, name = remote_cli.named(target)
-        target = f"{host}/{name}"
+        # v1's whole ambition, restored (its join.py said it in one line: "a
+        # clone carries `.taskops/board.json`, so the second developer types
+        # two words"). The committed address is read FIRST, so a fresh clone
+        # joins with no URL and no `remote add` — the recorded remote is for
+        # the checkout that has no carried address, or a DIFFERENT board.
+        carried = str(read_config(root).get("url", ""))
+        if carried and target in ("", carried.rsplit("/", 1)[-1]):
+            target = carried
+        else:
+            host, name = remote_cli.named(target)
+            target = f"{host}/{name}"
     base = target.partition("?")[0]
-    _keep_or_archive(root, base, discard)
     params = query(target)
     invite = invite or params.get("invite", "")
+    _keep_or_archive(root, base, discard)
     who = given or actor()
     name = who.partition(":")[2] or "me"
     found = Path(key).expanduser() if key else identity.discover_key()
@@ -123,29 +149,6 @@ def _keep_or_archive(root: Path, url: str, discard: bool) -> None:
     print(f"  the local board ({len(events)} events) is archived at {archive(local)}")
 
 
-def hook(here: Path, which: str, rest: list[str]) -> int:
-    """The two GIT hooks; `hook claude` is routed in `main` and never prints.
-
-    Neither of these may block a commit. Failures print and return 0.
-    """
-    root = find_root(here)
-    if which == "trailer":
-        if rest:
-            trailer.stamp_file(Path(rest[0]), run.branch_at(here))
-        return 0
-    facts = bind.commit_facts(here)
-    if facts is None:
-        return 0
-    try:
-        board = open_board(root, actor())
-        bind.record(board, root, facts)
-        bind.drain(board, root)
-    except TaskopsError as err:
-        print(f"taskops: {err}", file=sys.stderr)  # visible, never swallowed
-    bind.push_card(here, str(facts["branch"]))
-    return 0
-
-
 # ── plumbing ────────────────────────────────────────────────────────────────
 
 

taskops/cli/enrol.py

@@ -4,6 +4,18 @@ Split out of `commands.py` at its own seam — `join` and `board push` both need
 exactly this and only this: a repo with a local board has never joined
 anything, so its first push may also be its first introduction to the host,
 and there must not be two redemptions to keep in step.
+
+**One introduction lives on this side, and it is the invite.** There was a
+second for a day — it put the joiner's own GitHub token in a request body for
+the host to verify — and it is deleted, not disabled: the owner's `taskops board
+forge` now enrols the whole team from their own laptop (`cli/team.py`), so by the
+time a dev types `taskops join` their key is already in `allowed_signers` and
+there is nothing left to prove at the door. A dev's GitHub token never travels
+anywhere now, which is a stronger rule than never storing one.
+
+So this module knows GitHub not at all: `redeem` burns an invite somebody
+minted, `pubkey` reads the public half of a key, and neither leaves a standing
+credential behind.
 """
 
 from __future__ import annotations

taskops/cli/github.py

@@ -0,0 +1,196 @@
+"""The questions the OWNER asks GitHub, from their own laptop, with their own token.
+
+    collaborators("bernatch22/taskops", "push", token)  ->  ["ana", "leo", …]
+    keys_of("ana")                                      ->  ["ssh-ed25519 AAAA…", …]
+
+Two calls, and only the FIRST one is authenticated — `<login>.keys` is a public
+endpoint, which is the whole reason this chapter exists: somebody with push on a
+repo has already published the key they push with, so asking them for a second
+one was always redundant.
+
+**The token's whole life is inside `collaborators`.** Read by `token()`, put in
+one `Authorization` header per page, dropped with the frame: not returned, not
+printed, not written, and never sent to the taskops host — `http/members.py`
+takes principals and ssh key lines and does not know what GitHub is. That is how
+`taskops board forge` syncs a team without the host ever holding somebody's
+credential.
+
+**This is the ONLY place in taskops that talks to GitHub.** A board door used to
+ask the neighbouring question — does the token this stranger just POSTed have
+`need` on the repo — and it is deleted: it made every dev's own credential travel
+to the host for a fact the owner already holds. Here the token never leaves the
+machine that owns it, and the host is told nothing but principals and ssh key
+lines. A second door asking GitHub anything is the thing not to re-introduce.
+"""
+
+from __future__ import annotations
+
+import os
+import json
+import getpass
+from typing import Any
+
+from .. import _wire
+from .._json import as_rows, as_object
+from .._errors import TaskopsError
+
+API = "https://api.github.com"
+KEYS = "https://github.com"
+"""The two roots, as module constants so a test can point them at a stub over a
+real socket — mocking `_wire` instead would test neither urllib, nor the header
+the token travels in, nor the pagination, which is where a team of 31 silently
+became a team of 30."""
+
+TIMEOUT = 20.0
+PAGE = 100
+"""GitHub's own maximum. Asking for fewer would only make the loop below run
+more times against the same rate budget."""
+
+NO_TOKEN = (
+    "no GitHub token, and nothing was asked. Any ONE of these gives me one:\n"
+    "  gh auth login              the CLI's token is read automatically\n"
+    "  export GITHUB_TOKEN=…      an environment variable\n"
+    "  (or paste it at the hidden prompt)\n"
+    "No flag takes a token, deliberately: a token in a flag value lands in your shell "
+    "history forever, and this one is only ever used for a single command."
+)
+
+
+def token() -> str:
+    """WHERE the token comes from, in order — and never from a flag value.
+
+    `gh auth token` first, because the CLI is already installed and already
+    authenticated on the machine of anybody who ADMINS a repo, so the common
+    case asks the human nothing. Then `$GITHUB_TOKEN`, which is how CI and a
+    shell that never installed `gh` say it. Then a HIDDEN prompt.
+
+    **A flag is not one of the sources and must never become one.** A secret
+    passed as an argument is written to `~/.zsh_history` by the shell before the
+    process starts, survives every rotation of the token, and is visible in `ps`
+    to every user on the box while the command runs. The prompt is the fallback
+    precisely because it is the one input that leaves no trace.
+    """
+    from ..gitwork import run
+
+    try:
+        asked = run.tool("gh", "auth", "token", timeout=20.0)
+    except TaskopsError:
+        asked = None  # no `gh` on PATH, or it hung — the next source answers
+    if asked is not None and asked.ok and asked.out.strip():
+        return asked.out.strip()
+    if os.environ.get("GITHUB_TOKEN", "").strip():
+        return os.environ["GITHUB_TOKEN"].strip()
+    typed = getpass.getpass("GitHub token (input hidden, used once, stored nowhere): ").strip()
+    if not typed:
+        raise TaskopsError(NO_TOKEN)
+    return typed
+
+
+def collaborators(repo: str, need: str, secret: str) -> list[str]:
+    """Every human with `need` on `repo`, ALL of them — pagination is not optional.
+
+    A first page is 30 by default and 100 at most, and a team that outgrows one
+    page is exactly the team this command exists for: stopping at page one would
+    enrol some of them and report the rest as DRIFT, which reads as a revocation
+    list. The loop ends on a short page rather than on `Link: rel="next"`, which
+    would be a second condition saying the same thing.
+
+    The `permission=` filter is GitHub's own, and each row's `permissions` object
+    is checked against it because `http/github.py`'s door grants on exactly that
+    field — a filter and a door that disagree let somebody in through one and
+    never enrol them through the other. `type` drops bots: `github-actions[bot]`
+    is not a principal name and has no key to publish.
+    """
+    found: list[str] = []
+    page = 1
+    while True:
+        rows = _page(f"{API}/repos/{repo}/collaborators", repo, need, secret, page)
+        found.extend(
+            str(row.get("login", "")).strip()
+            for row in rows
+            if str(row.get("login", "")).strip() and _allowed(row, need)
+        )
+        if len(rows) < PAGE:
+            return found
+        page += 1
+
+
+def _page(url: str, repo: str, need: str, secret: str, page: int) -> list[dict[str, Any]]:
+    where = f"{url}?permission={need}&per_page={PAGE}&page={page}"
+    status, raw = _wire.text(where, headers(secret), TIMEOUT)
+    if status != 200:
+        raise TaskopsError(_why(status, repo, need, raw))
+    try:
+        return as_rows(json.loads(raw or "[]"))
+    except ValueError as err:  # pragma: no cover — a 200 that is not JSON
+        raise TaskopsError(f"GitHub answered {where} with something that is not JSON: {err}") from err
+
+
+def _allowed(row: dict[str, Any], need: str) -> bool:
+    """A row GitHub filtered in, confirmed against the field the door reads. An
+    entry with no `permissions` object at all is trusted to the filter — the
+    alternative is dropping a whole team the day that field is renamed."""
+    if str(row.get("type", "User")) != "User":
+        return False
+    seen = as_object(row.get("permissions"))
+    return not seen or seen.get(need) is True
+
+
+def keys_of(login: str) -> list[str]:
+    """`https://github.com/<login>.keys` — PUBLIC, no token, no rate budget spent.
+
+    An empty list is a real answer, not a failure: an account that pushes over
+    HTTPS has published no ssh key, and the caller NAMES those people with an
+    invite rather than leaving them out. A 404 — renamed or deleted between the
+    two calls — collapses to the same empty list for the same reason.
+    """
+    status, raw = _wire.text(f"{KEYS}/{login}.keys", {"User-Agent": "taskops"}, TIMEOUT)
+    if status != 200:
+        return []
+    seen: list[str] = []
+    for line in raw.splitlines():
+        one = line.strip()
+        if one and one not in seen:
+            seen.append(one)
+    return seen
+
+
+def headers(secret: str) -> dict[str, str]:
+    """The token's whole life. `X-GitHub-Api-Version` is pinned because the
+    shape of `permissions` is what this module reads, and an unpinned API is
+    free to reshape it — a silently missing key would read as "no access"."""
+    return {
+        "Authorization": f"Bearer {secret}",
+        "Accept": "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+        "User-Agent": "taskops",
+    }
+
+
+def _why(status: int, repo: str, need: str, raw: str) -> str:
+    """The refusal, and never the token in it — `raw` is GitHub's own body, which
+    holds its message and cannot hold the header it was refused for."""
+    try:
+        said = str(as_object(json.loads(raw or "{}")).get("message", ""))
+    except ValueError:
+        said = ""
+    tail = f" GitHub said: {said}" if said else ""
+    if status == 401:
+        return (
+            f"GitHub rejected that token (401) — expired, revoked or mistyped. Listing the "
+            f"collaborators of {repo} needs a token of somebody who can read them.{tail}"
+        )
+    if status == 403:
+        return (
+            f"GitHub refused that token (403) listing the collaborators of {repo} — an "
+            f"organisation that enforces SSO has to authorise it, and a rate limit answers "
+            f"the same way. Nobody was enrolled; the board's declaration stands, so the fix "
+            f"is to run the same command again.{tail}"
+        )
+    if status == 404:
+        return (
+            f"GitHub has no repository {repo!r} that this token can see — which is also what "
+            f"a private repo answers a token without access. Only somebody who can read its "
+            f"collaborators can sync them.{tail}"
+        )
+    return f"GitHub answered HTTP {status} listing the {need} collaborators of {repo} — nothing was enrolled.{tail}"

taskops/cli/grants.py

@@ -0,0 +1,59 @@
+"""`taskops invite` · `taskops revoke` — handing a credential out, and taking it back.
+
+    taskops invite <who> --board <name>    owner only — prints the join line
+    taskops revoke --key <SHA256:…> | --invite <id>
+
+The laptop half of `http/grants.py`, and the split is that seam and not a line
+count: `operate.py` is about a BOARD (create it, list them, say who may read it,
+name the forge that opens it) and this is about a CREDENTIAL — the two never
+share an argument. They do share the transport, which stays in `operate.py`
+where `push.py` already reaches for it; a third module holding three lines of
+`_wire.post` would be one more file to find and nothing to decide in it.
+
+**THE BREAK-GLASS PATH SURVIVES** on both verbs: `--root <dir>` runs the same
+act against the files directly, on the machine that holds them, and it is what
+you use when the server is down or the owner's key is lost. Not deprecated,
+never to be removed — a system whose only door is its own API cannot be
+repaired when that API is what broke. Those two acts live in `cli/admin.py`,
+beside `server init`: that module runs ON the box, this one is the laptop.
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from . import admin
+from .remote import address
+from .operate import call, signed_in
+from .._errors import TaskopsError
+
+
+def invite(args: argparse.Namespace) -> int:
+    """A one-time join line, minted by the server that will honour it."""
+    who, name = str(args.who), str(args.board)
+    if not who:
+        raise TaskopsError("taskops invite <who> --board <name>")
+    if args.root:  # break-glass: the files, on the box
+        return admin.on_box_invite(Path(str(args.root)).expanduser(), who, name)
+    if not name:
+        raise TaskopsError("which board? taskops invite <who> --board <name>")
+    host, _ = address(str(args.host))
+    made = call(host, "invite.mint", {"who": who, "board": name}, signed_in(host, args))
+    print(f"one-time invite for {who} (id {made['id']}, 7 days):")
+    print(f"  taskops join \"{host}/{made['board']}?invite={made['token']}\" --key ~/.ssh/id_ed25519")
+    return 0
+
+
+def revoke(args: argparse.Namespace) -> int:
+    """A key stops signing anybody in; an invite stops being redeemable."""
+    key, ident = str(args.key), str(args.invite)
+    if bool(key) == bool(ident):
+        raise TaskopsError("taskops revoke --key <SHA256:…> | --invite <id> — exactly one")
+    if args.root:  # break-glass: the files, on the box
+        return admin.on_box_revoke(Path(str(args.root)).expanduser(), key, ident)
+    host, _ = address(str(args.host))
+    verb = "key.revoke" if key else "invite.revoke"
+    gone = call(host, verb, {"key": key} if key else {"invite": ident}, signed_in(host, args, "sign_key"))
+    print(f"revoked {key or ident} ({gone.get('principal') or gone.get('subject')}) on {host}")
+    return 0

taskops/cli/hooks.py

@@ -0,0 +1,50 @@
+"""What the two GIT hooks call — the other half of what `join` installed.
+
+Split off `commands.py` at the seam that file's own docstring named ("the two
+commands that CONNECT a repo to a board, **and the git hooks**), the same way
+`serving.py` and `watch.py` were: `init` and `join` WRITE a checkout's
+configuration once, and these two run on every single commit somebody makes in
+it. Nothing here is reachable from a human's fingers — `gitwork/install.py`
+writes the shell scripts that call it, and `main.py` routes them.
+
+**Neither of these may ever block a commit.** A failure prints and returns 0.
+The hook is a courtesy that binds a commit to its card; a board that is down,
+a network that is out or a card that was closed a minute ago must cost somebody
+their commit exactly never. That is why the `TaskopsError` below is caught and
+written to stderr instead of raised — visible, and never in the way.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from ..board import find_root, open_board
+from .._errors import TaskopsError
+from ..gitwork import run, bind, trailer
+from .commands import actor
+
+
+def hook(here: Path, which: str, rest: list[str]) -> int:
+    """`hook trailer` stamps the message, `hook commit` binds the commit.
+
+    `hook claude` is a third one and it is routed in `main` instead, because it
+    prints NOTHING ever — including the `taskops: …` line every other failure
+    here is allowed to write.
+    """
+    root = find_root(here)
+    if which == "trailer":
+        if rest:
+            trailer.stamp_file(Path(rest[0]), run.branch_at(here))
+        return 0
+    facts = bind.commit_facts(here)
+    if facts is None:
+        return 0
+    try:
+        board = open_board(root, actor())
+        bind.record(board, root, facts)
+        bind.drain(board, root)
+    except TaskopsError as err:
+        print(f"taskops: {err}", file=sys.stderr)  # visible, never swallowed
+    bind.push_card(here, str(facts["branch"]))
+    return 0