alissa-tools-github-devloop 0.8.7__tar.gz → 0.8.9__tar.gz

{alissa_tools_github_devloop-0.8.7/src/main/alissa_tools_github_devloop.egg-info → alissa_tools_github_devloop-0.8.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-devloop
-Version: 0.8.7
+Version: 0.8.9
 Summary: ALISSA-TOOLS-GITHUB-DEVLOOP
 Home-page: https://alissa.app
 Author: Fahera

{alissa_tools_github_devloop-0.8.7 → alissa_tools_github_devloop-0.8.9}/src/main/alissa/tools/github/devloop/__main__.py

@@ -8,12 +8,15 @@ import logging
 import sys
 from pathlib import Path
 
+from .alissa_client import AlissaClient, AlissaError
 from .config import (
     HUB_ADD,
     HUB_SKIP,
     ON_MISSING_SKIP,
     ON_MISSING_SPAWN,
     ON_MISSING_WARN,
+    REPOS_BOWS,
+    REPOS_STATIC,
     Config,
     load_config_file,
     resolve_config_path,
@@ -34,7 +37,8 @@ def build_parser() -> argparse.ArgumentParser:
         "fresh developer sessions — the developer-side counterpart of "
         "alissa-reviewloop.",
         epilog="Every setting below can also live in the config file; CLI "
-        "arguments win, and ALISSA_DEV_REVIEWERS wins over --reviewer. "
+        "arguments win, and ALISSA_DEV_REVIEWERS wins over --reviewer "
+        "(ALISSA_DEV_REPOS_SOURCE likewise over --repos-source). "
         "workspace_root is CLI-only, so one config can drive several daemons "
         "over different workspaces.",
     )
@@ -76,6 +80,41 @@ def build_parser() -> argparse.ArgumentParser:
         "applies. Emptying the allowlist (which turns the daemon off — an "
         "empty allowlist watches NOTHING) is done in the config file.",
     )
+    over.add_argument(
+        "--repos-source",
+        choices=[REPOS_STATIC, REPOS_BOWS],
+        help="where the watch allowlist comes from: 'static' (the default) is "
+        "the `repos` list alone; 'bows' UNIONS it with the repos named by the "
+        "operator's active `autodev: <owner>/<repo>` bodies of work, so "
+        "enrolling a repo needs no redeploy. ALISSA_DEV_REPOS_SOURCE wins "
+        "over even this flag",
+    )
+    over.add_argument(
+        "--bows-refresh-polls",
+        type=int,
+        metavar="N",
+        help="bows mode: re-derive the allowlist every N poll passes "
+        "(default 5; 1 = every pass)",
+    )
+    over.add_argument(
+        "--bow-owner",
+        dest="bow_owners",
+        action="append",
+        metavar="ACTOR_ID",
+        help="bows mode: trust bodies of work OWNED by this Alissa actor as "
+        "repo feeds; repeatable, and one flag may carry several ids separated "
+        "by `|` or `,`. When given, REPLACES the config `bow_owners` list. "
+        "OPTIONAL — left unset, the daemon resolves its own token's actor at "
+        "boot and trusts only its own containers. Must be an actor ID (the "
+        "`ownerActorId` on the container's row); a username or display name "
+        "is refused",
+    )
+    over.add_argument(
+        "--alissa-endpoint",
+        metavar="URL",
+        help="bows mode: the Alissa REST API the feed listing is read from "
+        "(default https://api.alissa.app)",
+    )
     over.add_argument("--poll-interval", type=int, metavar="SECONDS")
     over.add_argument("--label", metavar="LABEL", help="issue label that marks dev-ready work")
     over.add_argument("--hub-template", metavar="TEMPLATE")
@@ -321,6 +360,10 @@ def overrides_from(args: argparse.Namespace) -> dict:
     through. `repos`/`reviewers` become tuples so they match the file form."""
     return {
         "repos": tuple(args.repos) if args.repos else None,
+        "repos_source": args.repos_source,
+        "bows_refresh_polls": args.bows_refresh_polls,
+        "bow_owners": tuple(args.bow_owners) if args.bow_owners else None,
+        "alissa_endpoint": args.alissa_endpoint,
         "poll_interval": args.poll_interval,
         "label": args.label,
         "hub_template": args.hub_template,
@@ -367,16 +410,70 @@ def resolve_config(args: argparse.Namespace) -> Config:
     )
 
 
+def resolve_feed_authority(
+    config: Config, client: "AlissaClient | None" = None
+) -> Config:
+    """Decide WHOSE bodies of work may enroll a repo, and say so out loud.
+
+    Two answers, one of them free:
+
+    * `bow_owners` **set** — the operator named the authority explicitly. That
+      is the multi-operator case: the feed containers belong to an actor this
+      token is not. Nothing is resolved, nothing is called.
+    * `bow_owners` **unset** — the authority is **self**. The token already
+      carries an identity, so `GET /v1/ping` answers the question the operator
+      would otherwise have hand-copied out of the API.
+
+    The whoami call is **fatal on failure**, deliberately, and that is the
+    whole fail-closed argument in one place. Carrying on with an empty
+    authority is technically safe (nothing would be trusted, so nothing would
+    enroll) but it is safe *silently*: the operator would see a daemon that
+    runs and watches only the static list, which is exactly what a correctly
+    configured daemon with no feeds yet looks like. Dying names the reason
+    while someone is watching. The property being protected is not "self is
+    trusted" but "only a KNOWN actor is trusted" — an unanswered whoami leaves
+    that unknown, and no default can fill it in.
+
+    Under `static` this is a no-op: that mode never reads a Body of Work, so
+    it never needs an identity, and a daemon that only watches its static list
+    must not fail to boot because an endpoint it does not use was unreachable.
+    """
+    if config.repos_source != REPOS_BOWS:
+        return config
+
+    if config.bow_owners:
+        log.info("bow feed authority: explicit (%s)", ", ".join(config.bow_owners))
+        return config
+
+    identity = (client or AlissaClient(base=config.alissa_endpoint)).whoami()
+    log.info("bow feed authority: self (%s)", identity.actor_id)
+    if identity.display_name:
+        # Logged as context, never compared: a display name is renameable,
+        # which is why `bow_owners` refuses to hold one.
+        log.debug("resolved from this token's identity: %r", identity.display_name)
+    # The id came from the API, so it is the authority on its own shape and is
+    # NOT put back through the config's actor-id check -- that check exists to
+    # catch an operator typing a username, not to second-guess the server.
+    return dataclasses.replace(config, bow_owners=(identity.actor_id,))
+
+
 def log_effective_config(config: Config, login: str) -> None:
     """The resolved settings, defaults and all. INFO carries the decisions an
     operator needs; -v (DEBUG) shows the full surface."""
     log.info("developing as GitHub user %s (from the gh token)", login)
+    bows = config.repos_source == REPOS_BOWS
     log.info(
-        "watching %s for label %r",
+        "watching %s for label %r (repos_source=%s%s)",
         ", ".join(config.repos) if config.repos
         else "NO repos (empty allowlist — set `repos` or pass --repo)",
         config.label,
+        config.repos_source,
+        f", refreshed every {config.bows_refresh_polls} poll(s) from "
+        f"`autodev: ` bodies of work" if bows else "",
     )
+    if bows:
+        log.debug("bow_owners: %s", ", ".join(config.bow_owners) or "none (INERT)")
+        log.debug("alissa_endpoint: %s", config.alissa_endpoint)
     log.info("reviewers: %s", ", ".join(config.reviewers) or "none")
     log.info(
         "poll every %ss; dry_run=%s; attempt_cap=%s; stale after %s min; "
@@ -427,11 +524,15 @@ def main(argv: "list[str] | None" = None) -> int:
     try:
         config = resolve_config(args)
         log.info("workspace: %s", config.workspace_root)
+        # Startup's one piece of Alissa I/O, and only under `bows`.
+        config = resolve_feed_authority(config)
 
         watcher = DevWatcher(config)
         for warning in watcher.preflight():
             log.warning(warning)
-        log_effective_config(config, watcher.github.login)
+        # `watcher.config`, not `config`: preflight ran the first feed refresh,
+        # so the allowlist the operator reads here is the DERIVED one.
+        log_effective_config(watcher.config, watcher.github.login)
 
         if args.once:
             watcher.poll_once()
@@ -443,6 +544,17 @@ def main(argv: "list[str] | None" = None) -> int:
     except (FileNotFoundError, ValueError) as exc:
         print(f"config error: {exc}", file=sys.stderr)
         return 2
+    except AlissaError as exc:
+        # Only reachable from resolve_feed_authority: an unanswered whoami
+        # leaves the feed authority unknown, and starting with it unknown is
+        # the one failure this mode must not have.
+        print(
+            f"alissa error: {exc} — repos_source='bows' could not resolve the "
+            f"feed authority (GET /v1/ping). Check ALISSA_API_TOKEN and "
+            f"alissa_endpoint, or set bow_owners explicitly",
+            file=sys.stderr,
+        )
+        return 2
     except RateLimited as exc:
         # Only --once can get here: run_forever absorbs rate limits by
         # backing off, but a single pass has no next pass to wait for.

alissa_tools_github_devloop-0.8.9/src/main/alissa/tools/github/devloop/alissa_client.py

@@ -0,0 +1,270 @@
+"""Alissa REST access — the two reads the BOW-derived allowlist needs.
+
+This is the SECOND Alissa adapter in the package, and the split is deliberate.
+`alissa.py` shells out to the `alissa` CLI, which is the daemon's established
+Alissa idiom for everything it does today (the tmux queue, the worker probe,
+`alissa code workspace add`). `repos_source: "bows"` needs two things that
+idiom cannot supply:
+
+* the **owner** of each Body of Work. `alissa bow list --json` does carry
+  `ownerActorId`, so this half is reachable from the CLI.
+* the **token's own actor id**, which the feed-authority gate defaults to.
+  The CLI has no whoami that prints an id: `alissa auth status` prints a
+  DISPLAY NAME, and a display name is exactly what an ownership check must
+  never compare against (names are renameable, so an allowlist written in
+  them grants authority to whoever holds the name when the check runs).
+
+So the authority gate is unimplementable over the CLI, and a mode that reads
+BOW ownership over one transport and identity over another would be two idioms
+anyway. Both reads therefore go over the REST API this daemon's Alissa token
+already authenticates — the same transport, endpoints and taxonomy orcloop's
+`alissa_client.py` uses, so the two daemons read one contract. Stdlib
+`urllib` only: the distribution ships no third-party runtime dependency, and
+this must not be the change that adds one.
+
+Endpoints, both verified against the live API:
+
+``GET /v1/ping``
+    ``{"pong", "timestamp", "userId", "actorId", "displayName"}`` — the
+    token's identity endpoint, and the only one (orcloop's spike found
+    ``/v1/me``, ``/v1/whoami``, ``/v1/actors/me`` and six others all 404).
+    `actorId` is the same opaque id that appears as `ownerActorId` on a Body
+    of Work, which is what lets the authority default to "self".
+
+``GET /v1/bodies-of-work?includeShared=true``
+    ``{"bodiesOfWork": [{"_id", "title", "status", "ownerActorId", ...}]}``.
+    `includeShared=true` is load-bearing: the endpoint defaults to OWNED-only,
+    and a feed container is created by the operator (there is no create
+    endpoint) with the daemon added as a COLLABORATOR — without the flag the
+    feed's only discovery path returns nothing and `bows` mode is silently
+    inert. The flag is also what makes the authority gate necessary: it widens
+    the listing to every container ANY actor shared with this one, unilaterally
+    and with no acceptance step on this side. Membership of this list means
+    "visible", never "authoritative" (see `config.Config.trusts_feed_owner`).
+
+Errors arrive as three narrow buckets so the caller can react without
+string-matching a stderr. The caller here is a REFRESH, and its answer to all
+three is the same — keep the last good set and warn — so the taxonomy exists
+for the log line and for the boot path, which distinguishes "your token is
+wrong" (permanent, operator-fixable) from "the API blinked".
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+
+log = logging.getLogger(__name__)
+
+DEFAULT_ENDPOINT = "https://api.alissa.app"
+
+# The env var the CLI itself reads, so a daemon whose `alissa` CLI is already
+# authenticated needs no second secret.
+ENV_TOKEN = "ALISSA_API_TOKEN"
+
+
+class AlissaError(Exception):
+    """Base of the taxonomy. `status` is 0 for a transport failure (there was
+    no HTTP response to carry one)."""
+
+    def __init__(self, status: int, detail: object, code: "str | None" = None):
+        super().__init__(f"HTTP {status}: {detail}" if status else str(detail))
+        self.status = status
+        self.detail = detail
+        self.code = code
+
+
+class AlissaAuthError(AlissaError):
+    """401/403, or no token at all. Permanent and operator-fixable — retrying
+    it every refresh only writes the same warning again."""
+
+
+class AlissaNotFound(AlissaError):
+    """404: the endpoint or resource is absent for this actor."""
+
+
+class AlissaTransient(AlissaError):
+    """408/429/5xx and every transport failure (DNS, refused, timeout). The
+    'the API blinked' bucket the never-shrink cache exists for."""
+
+
+@dataclass(frozen=True)
+class Identity:
+    """Who this token acts as (`GET /v1/ping`).
+
+    `actor_id` is the load-bearing field: it is the same opaque id a Body of
+    Work reports as `ownerActorId`, so it can be compared directly. The other
+    two are carried for LOGGING only — a display name must never reach an
+    authority check."""
+
+    actor_id: str
+    user_id: str = ""
+    display_name: str = ""
+
+
+@dataclass(frozen=True)
+class BodyOfWork:
+    """A Body of Work as the LIST endpoint reports it — only the four fields
+    the feed reads.
+
+    `owner_id` is the container's provenance and the only field here that is
+    not operator-authored text: the listing includes containers merely SHARED
+    with this actor, so the title alone cannot say whether a feed is one the
+    operator set up. Empty when the payload omits it, which the authority gate
+    treats as untrusted rather than unknown."""
+
+    id: str
+    title: str
+    status: str = ""
+    owner_id: str = ""
+
+
+class AlissaClient:
+    """The two reads, with the transport hidden behind the taxonomy.
+
+    Reads `ALISSA_API_TOKEN` from the environment; `base` defaults to the
+    public API. Both are constructor arguments so a test never needs the
+    network and an operator can point a daemon at another deployment."""
+
+    def __init__(
+        self,
+        token: "str | None" = None,
+        base: "str | None" = None,
+        *,
+        timeout: int = 30,
+    ):
+        self.base = (base or DEFAULT_ENDPOINT).rstrip("/")
+        self._token = token if token is not None else os.environ.get(ENV_TOKEN)
+        self._timeout = timeout
+
+    def _request(self, path: str) -> object:
+        """One GET. Every failure leaves as a taxonomy exception — the caller
+        never sees a raw urllib error or an HTTP status."""
+        if not self._token:
+            # No token at all is an auth condition, not a transport one: the
+            # operator must set the env var. Fail the way a 401 would, so the
+            # boot path treats it as permanent rather than retrying forever.
+            raise AlissaAuthError(0, f"{ENV_TOKEN} is not set")
+
+        req = urllib.request.Request(
+            f"{self.base}{path}",
+            method="GET",
+            headers={
+                "Accept": "application/json",
+                "Authorization": f"Bearer {self._token}",
+            },
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+                raw = resp.read().decode("utf-8")
+        except urllib.error.HTTPError as exc:
+            raise self._classify(exc) from None
+        except urllib.error.URLError as exc:
+            raise AlissaTransient(0, str(exc.reason)) from None
+        except (TimeoutError, OSError) as exc:  # pragma: no cover - defence
+            # A socket timeout on the READ does not arrive as URLError.
+            raise AlissaTransient(0, str(exc)) from None
+        try:
+            return json.loads(raw) if raw.strip() else {}
+        except json.JSONDecodeError as exc:
+            # A 2xx that is not JSON is a contract violation, not a retry
+            # signal -- but it must not escape as a bare ValueError either,
+            # because the refresh catches AlissaError and nothing else.
+            raise AlissaError(200, f"response was not JSON ({exc})") from None
+
+    @staticmethod
+    def _classify(exc: "urllib.error.HTTPError") -> AlissaError:
+        """Map an HTTP error onto the taxonomy. The API sends JSON error
+        bodies (`{"error": CODE, "message": ...}`); the code rides along when
+        present, but classification keys on the STATUS — codes are advisory,
+        statuses are the contract."""
+        detail: object = exc.read().decode("utf-8", "replace")
+        code: "str | None" = None
+        try:
+            parsed = json.loads(detail)  # type: ignore[arg-type]
+        except (json.JSONDecodeError, TypeError):
+            parsed = None
+        if isinstance(parsed, dict):
+            detail = parsed
+            raw_code = parsed.get("error")
+            code = raw_code if isinstance(raw_code, str) else None
+
+        status = exc.code
+        if status in (401, 403):
+            return AlissaAuthError(status, detail, code)
+        if status == 404:
+            return AlissaNotFound(status, detail, code)
+        if status in (408, 429) or 500 <= status <= 599:
+            return AlissaTransient(status, detail, code)
+        return AlissaError(status, detail, code)
+
+    def whoami(self) -> Identity:
+        """The identity this token acts as.
+
+        On the BOOT path, and fatal there — see
+        `__main__.resolve_feed_authority` for why an unanswered whoami must
+        stop the daemon rather than soften into an empty authority."""
+        payload = self._request("/v1/ping")
+        row = payload if isinstance(payload, dict) else {}
+        actor_id = row.get("actorId")
+        if not isinstance(actor_id, str) or not actor_id.strip():
+            # A 2xx with no actorId is a contract violation, not a missing
+            # resource: name it as such rather than letting an empty authority
+            # travel onwards looking like a configuration choice.
+            raise AlissaError(
+                200,
+                f"GET /v1/ping returned no actorId (got {payload!r}) — the "
+                f"token's acting identity could not be determined",
+            )
+        return Identity(
+            actor_id=actor_id.strip(),
+            user_id=str(row.get("userId") or ""),
+            display_name=str(row.get("displayName") or ""),
+        )
+
+    def list_bodies_of_work(self) -> "list[BodyOfWork]":
+        """Every Body of Work this actor owns OR collaborates on — ONE call.
+
+        There is no server-side title or status filter, so the caller narrows.
+        Rows without an `_id` are dropped: a container that cannot be
+        addressed cannot be reported on either.
+
+        A payload with no `bodiesOfWork` LIST is a contract violation, not an
+        empty listing, and is raised as such -- `whoami`'s missing-`actorId`
+        reasoning applied to the other read. Degrading it to `[]` would report
+        SUCCESS to the refresh, which would then derive nothing and drop every
+        feed-enrolled repo on a routine INFO line: a response-shape change or
+        an `alissa_endpoint` answering 200 with something else would silently
+        un-enroll everything, which is precisely what the never-shrink rule
+        promises cannot happen. Raising routes it to `_log_listing_failure`
+        instead, which keeps the last good set. `{"bodiesOfWork": []}` is
+        untouched -- present-and-empty is a legitimate empty listing, and the
+        documented way an operator un-enrolls the last repo."""
+        payload = self._request("/v1/bodies-of-work?includeShared=true")
+        rows = payload.get("bodiesOfWork") if isinstance(payload, dict) else None
+        if not isinstance(rows, list):
+            raise AlissaError(
+                200,
+                f"GET /v1/bodies-of-work returned no bodiesOfWork list "
+                f"(got {payload!r})",
+            )
+        out: "list[BodyOfWork]" = []
+        for row in rows:
+            if not isinstance(row, dict):
+                continue
+            bow_id = row.get("_id")
+            if not isinstance(bow_id, str) or not bow_id:
+                continue
+            out.append(
+                BodyOfWork(
+                    id=bow_id,
+                    title=str(row.get("title") or ""),
+                    status=str(row.get("status") or ""),
+                    owner_id=str(row.get("ownerActorId") or ""),
+                )
+            )
+        return out