alissa-tools-github-revloop 0.13.0__tar.gz → 0.15.0__tar.gz

{alissa_tools_github_revloop-0.13.0/src/main/alissa_tools_github_revloop.egg-info → alissa_tools_github_revloop-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-revloop
-Version: 0.13.0
+Version: 0.15.0
 Summary: ALISSA-TOOLS-GITHUB-REVLOOP
 Home-page: https://alissa.app
 Author: Fahera

{alissa_tools_github_revloop-0.13.0 → alissa_tools_github_revloop-0.15.0}/setup.py

@@ -50,6 +50,7 @@ setup(
         "console_scripts": [
             "alissa-revloop=alissa.tools.github.revloop.__main__:main",
             "alissa-pr-review=alissa.tools.github.revloop.prreview:main",
+            "alissa-revloop-ui=alissa.tools.github.revloop.webui.__main__:main",
         ]
     },
     install_requires=requirements,

{alissa_tools_github_revloop-0.13.0 → alissa_tools_github_revloop-0.15.0}/src/main/alissa/tools/github/revloop/state.py

@@ -27,6 +27,7 @@ from __future__ import annotations
 import json
 import sqlite3
 import time
+from collections.abc import Iterable
 from pathlib import Path
 
 # Poll-snapshot retention: the newest N rows are kept, older ones pruned on
@@ -94,8 +95,35 @@ CREATE TABLE IF NOT EXISTS poll_snapshots (
 
 
 class State:
-    def __init__(self, path: Path):
+    def __init__(self, path: Path, *, read_only: bool = False):
+        """Open the ledger. The daemon opens it read-write (creating the file,
+        applying the schema, migrating an old `spawns` key); a read-only
+        CONSUMER -- the console sidecar -- must not do any of that.
+
+        `read_only` connects through the `mode=ro` URI, which cannot create the
+        database and raises `sqlite3.OperationalError` when it does not exist.
+        That is the point: a console pointed at a workspace with no daemon
+        state must report "no state here", not silently CREATE a state.db (and
+        thereby render an empty, healthy-looking dashboard the operator cannot
+        tell from an idle daemon), and must never run the migration on a
+        database the daemon owns.
+
+        The URI is built with `as_uri()`, never by interpolating the path into
+        an f-string: sqlite parses a `file:` URI, so an unescaped `#` truncates
+        the filename at a fragment, `?` at the query, and `%XX` is
+        percent-decoded. Any of the three in `--workspace-root` would yield a
+        DIFFERENT file and -- for `#` and `?` -- one with no `mode` parameter
+        left, silently falling back to `rwc`: read-only mode creating a
+        database, at a path that is not even the one asked for. `as_uri()`
+        percent-encodes everything but the separator, so the guarantee holds
+        for any path an operator can type.
+        """
         path = Path(path).expanduser()
+        if read_only:
+            uri = Path(path).absolute().as_uri() + "?mode=ro"
+            self._db = sqlite3.connect(uri, uri=True)
+            self._db.row_factory = sqlite3.Row
+            return
         path.parent.mkdir(parents=True, exist_ok=True)
         self._db = sqlite3.connect(str(path))
         self._db.row_factory = sqlite3.Row
@@ -332,3 +360,129 @@ class State:
             record["stages"] = json.loads(record.pop("stages_json"))
             out.append(record)
         return out
+
+    # -- console ledger bridge (read-only lists + the retry-now UPDATE) -----
+    #
+    # The console sidecar (webui) renders the spawn ledger, the escalation
+    # table and the ping ledger directly -- the operator inbox, the session ->
+    # PR mapping, and the retry-now action -- the way it reads poll_snapshots
+    # through read_snapshots: no GitHub call, just the local tables.
+    #
+    # Rows come back newest-first, and every reader takes the same optional
+    # `limit` read_snapshots does. Unlike poll_snapshots, `escalations` and
+    # `pings` are NEVER pruned (they are per-head / per-episode dedupe keys the
+    # daemon must keep), so a reader that returned all of them would grow an
+    # operator inbox that never clears. Bounding belongs here, in SQL, not in
+    # the caller's slice -- and, for `pings`, AFTER the kind filter rather than
+    # before it, or the noisier telemetry kind evicts the operator pages.
+    #
+    # `spawns` is bounded differently on purpose: it is a lookup table, not a
+    # display list, so it is selected by key rather than truncated by recency.
+
+    def read_spawns(
+        self,
+        limit: int | None = None,
+        *,
+        sessions: "Iterable[str] | None" = None,
+    ) -> list[dict]:
+        """Spawn rows (one per enqueued reviewer round), newest first.
+
+        `sessions` restricts the read to those session names. That is the
+        bound the console's session->round pairing wants, and a recency bound
+        (row count or time window) is NOT: a stale round whose session is
+        still alive is deferred indefinitely (see loop._defer_stale_round --
+        only an operator kill unblocks the respawn), so a live session's spawn
+        row can be arbitrarily old. Truncating by recency therefore drops the
+        pairing for exactly the wedged session an operator is looking for.
+        Selecting by name bounds the read by the live-session count instead,
+        at any row age. An empty collection reads nothing.
+        """
+        sql = (
+            "SELECT repo, number, round, head_sha, session, task_ref, spawned_at "
+            "FROM spawns"
+        )
+        params: tuple = ()
+        if sessions is not None:
+            names = tuple(sessions)
+            if not names:
+                return []
+            sql += " WHERE session IN (%s)" % ",".join("?" * len(names))
+            params = names
+        sql += " ORDER BY spawned_at DESC, number DESC, round DESC"
+        return self._read_rows(sql, limit, params)
+
+    def read_escalations(self, limit: int | None = None) -> list[dict]:
+        """Cap-out escalations (the terminal half of the operator inbox),
+        newest first. Keyed per head_sha: a fresh push after a cap-out is a new
+        row, so the console can show that the PR capped out again."""
+        return self._read_rows(
+            "SELECT repo, number, head_sha, escalated_at "
+            "FROM escalations ORDER BY escalated_at DESC, number DESC",
+            limit,
+        )
+
+    def read_pings(
+        self,
+        limit: int | None = None,
+        *,
+        kind_prefix: str | None = None,
+    ) -> list[dict]:
+        """Operator-ping rows, newest first. `kind` is free-form and carries
+        the episode identity (`stalled:<session>`,
+        `activity-deferred:<session>`).
+
+        `kind_prefix` selects one kind IN SQL, so `limit` bounds the rows the
+        caller actually wants. Filtering after the limit instead would let the
+        other kind evict them: only a deferral episode that outlasts
+        STALLED_DEFER_MULTIPLE stale windows writes a `stalled:` row, while
+        EVERY episode writes an `activity-deferred:` one, so the kind the
+        console does not page on is structurally the more numerous. Matched
+        with `substr`, not `LIKE`: the prefix is a literal, and `LIKE` would
+        need `%`/`_` escaped to keep it one.
+        """
+        sql = "SELECT repo, number, kind, pinged_at FROM pings"
+        params: tuple = ()
+        if kind_prefix is not None:
+            sql += " WHERE substr(kind, 1, ?) = ?"
+            params = (len(kind_prefix), kind_prefix)
+        sql += " ORDER BY pinged_at DESC, number DESC"
+        return self._read_rows(sql, limit, params)
+
+    def _read_rows(
+        self, sql: str, limit: int | None, params: tuple = ()
+    ) -> list[dict]:
+        if limit is not None:
+            sql += " LIMIT ?"
+            params = params + (limit,)
+        return [dict(row) for row in self._db.execute(sql, params).fetchall()]
+
+    def age_out_spawn(self, repo: str, number: int, round_: int, new_ts: int) -> bool:
+        """Retry-now: stamp the NEWEST spawn row of THIS round back to
+        `new_ts` (the console passes a time just past the stale window), so
+        `spawn_age` reads as stale and the daemon's own re-enqueue path can
+        respawn the round on its next pass. An UPDATE, never a DELETE: the
+        spawn history stays intact (the reap sweep still maps the old session
+        name back to its round), only the newest row's clock moves. Keyed per
+        round, like `get_spawn` -- a retry re-arms only the round the console
+        named. Returns False when there is no row to age (the console then
+        reports nothing to retry).
+
+        Aging is necessary but not sufficient for a respawn: the daemon defers
+        a stale round whose session still shows signs of life (loop's liveness
+        signal, which exists to stop double-spending a round). Kill the wedged
+        session first, then retry -- that is exactly the operator sequence the
+        stalled ping asks for.
+        """
+        row = self._db.execute(
+            "SELECT session FROM spawns WHERE repo=? AND number=? AND round=? "
+            "ORDER BY spawned_at DESC, rowid DESC LIMIT 1",
+            (repo, number, round_),
+        ).fetchone()
+        if row is None:
+            return False
+        self._db.execute(
+            "UPDATE spawns SET spawned_at=? WHERE session=?",
+            (int(new_ts), row["session"]),
+        )
+        self._db.commit()
+        return True

alissa_tools_github_revloop-0.15.0/src/main/alissa/tools/github/revloop/version

@@ -0,0 +1 @@
+0.15.0

alissa_tools_github_revloop-0.15.0/src/main/alissa/tools/github/revloop/webui/__init__.py

@@ -0,0 +1,36 @@
+"""The reviewer console: a stdlib-only sidecar (`alissa-revloop-ui`) that
+renders live review-daemon state for an operator, spending **zero** GitHub API
+budget of its own beyond two cached checks.
+
+Ported from the devloop's worker console (`alissa.tools.github.devloop.webui`,
+its PR #38) and adapted to reviewer semantics: the unit of work is a PR round,
+not an issue attempt, so the pipeline board is PR-centric (PR ref → round k of
+the cap → session → stage), the operator inbox pages cap-outs and stalled
+deferrals, and there is no worker-tasks panel (reviewers create no tasks) and
+no maintenance edge. Module shapes are copied deliberately -- family precedent
+is copy-adapt per repo; a shared-webui package is a separate, deferred lane.
+
+The daemon (loop.py) already persists everything the console needs: every poll
+pass writes one `poll_snapshots` row (UI-1, PR #35) carrying the pass timing,
+the candidate count, the decision-summary counts, and the compact per-item
+stage list. The sidecar reads that table through `State.read_snapshots`, plus
+the spawn ledger, the escalation table and the ping ledger (the operator
+inbox), all read-only. Its only live signals are local (`alissa tmux ls`, a
+`/proc` walk of each session's pane-PID tree) or cached (`gh api rate_limit`,
+60s; the PyPI version JSON, 10m) -- so a fleet of operators refreshing the
+dashboard never moves the daemon's rate budget.
+
+Layout:
+  auth.py     -- fail-closed passcode, HMAC-signed sessions, CSRF, login throttle
+  sysinfo.py  -- /proc process-tree CPU%/RSS (sample-free, vanished-PID tolerant)
+  sources.py  -- the read-only data layer + the retry-now UPDATE, cached checks
+  page.py     -- the single static HTML page (studio design system, both themes)
+  server.py   -- ThreadingHTTPServer wiring, routing, auth/CSRF gating, actions
+  __main__.py -- the `alissa-revloop-ui` console entry point
+"""
+
+from __future__ import annotations
+
+from .auth import Auth, LoginThrottle, PasscodeUnset, require_passcode
+
+__all__ = ["Auth", "LoginThrottle", "PasscodeUnset", "require_passcode"]

alissa_tools_github_revloop-0.15.0/src/main/alissa/tools/github/revloop/webui/__main__.py

@@ -0,0 +1,130 @@
+"""CLI entry point: `alissa-revloop-ui` (or `python -m ...revloop.webui`).
+
+The sidecar reads the SAME config the daemon resolved (so its echo panel is
+truthful) but never runs the daemon's preflight -- it makes no `gh api user`
+identity call, holds no GitHub token of its own, and spends GitHub budget only
+through the two cached checks in `sources`. It is fail-closed on the passcode:
+`ALISSA_UI_PASSCODE` unset -> exit before the socket ever binds.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from ..config import Config, load_config_file, resolve_config_path
+from ..version import version
+from .auth import Auth, PasscodeUnset, require_passcode
+from .server import App, make_server
+from .sources import Sources
+
+# The default bind port. Deliberately NOT the devloop console's 8787: the two
+# daemons routinely run on one machine (they are the two halves of the same
+# loop), and two sidecars fighting over one port is a boot failure an operator
+# would have to debug.
+DEFAULT_PORT = 8788
+
+# The log file to tail when `--log-file` is not given.
+ENV_LOG = "ALISSA_REVLOOP_LOG"
+
+
+def _env_flag(value: "str | None") -> bool:
+    """A truthy env flag: 1/true/yes/on (case-insensitive). Unset or anything
+    else is False -- fail-safe, so a stray value never silently flips a knob."""
+    return (value or "").strip().lower() in ("1", "true", "yes", "on")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="alissa-revloop-ui",
+        description="Reviewer console: a stdlib-only operator dashboard sidecar "
+        "for the alissa-revloop daemon. Reads the daemon's local state (poll "
+        "snapshots, spawn ledger, escalations, pings), tmux/proc, and two cached "
+        "checks; renders live state and offers kill/retry-now actions.",
+        epilog="Requires ALISSA_UI_PASSCODE (fail-closed). Reads the same "
+        "config file the daemon uses so its echo panel is truthful.",
+    )
+    p.add_argument("--version", action="version",
+                   version=f"%(prog)s {version.value}")
+    p.add_argument("--host", default="127.0.0.1", metavar="ADDR",
+                   help="bind address (default: 127.0.0.1 -- localhost only)")
+    p.add_argument("--port", type=int, default=DEFAULT_PORT, metavar="PORT",
+                   help=f"bind port (default: {DEFAULT_PORT})")
+    p.add_argument("--workspace-root", type=Path, default=None, metavar="PATH",
+                   help="the workspace whose daemon state to render "
+                   "(default: current directory)")
+    p.add_argument("-c", "--config-path", "--config", dest="config_path",
+                   type=Path, default=None, metavar="PATH",
+                   help="config file; without it, ./revloop.config.json then "
+                   "<workspace-root>/revloop.config.json, else defaults only")
+    p.add_argument("--state-path", type=Path, default=None, metavar="PATH",
+                   help="override the state.db location (default: from config)")
+    p.add_argument("--log-file", type=Path, default=None, metavar="PATH",
+                   help="daemon log file to tail in the console "
+                   f"(default: ${ENV_LOG}, else none)")
+    return p
+
+
+def resolve_config(args: argparse.Namespace) -> Config:
+    """Config exactly as the daemon resolves it (discovery + layers), minus the
+    preflight -- no network, no gh identity."""
+    workspace_root = args.workspace_root or Path.cwd()
+    path = resolve_config_path(args.config_path, workspace_root)
+    file_data = load_config_file(path) if path else {}
+    overrides = {"state_path": args.state_path}
+    return Config.build(workspace_root, file_data, overrides)
+
+
+def main(argv: "list[str] | None" = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    try:
+        passcode = require_passcode(os.environ)
+    except PasscodeUnset as exc:
+        print(f"refusing to start: {exc}", file=sys.stderr)
+        return 2
+
+    try:
+        config = resolve_config(args)
+    except (FileNotFoundError, ValueError) as exc:
+        print(f"config error: {exc}", file=sys.stderr)
+        return 2
+
+    log_file = args.log_file
+    if log_file is None:
+        env_log = os.environ.get(ENV_LOG)
+        log_file = Path(env_log) if env_log else None
+
+    auth = Auth(passcode)
+    sources = Sources(
+        config=config, running_version=version.value, log_path=log_file
+    )
+    # Add `Secure` to the session cookie when the console sits behind TLS
+    # termination (reverse proxy). Off by default for the localhost-HTTP posture.
+    secure_cookie = _env_flag(os.environ.get("ALISSA_UI_SECURE_COOKIE"))
+    app = App(
+        auth=auth, sources=sources, version=version.value,
+        secure_cookie=secure_cookie,
+    )
+    server = make_server(app, args.host, args.port)
+
+    print(
+        f"alissa-revloop-ui {version.value} -- serving on "
+        f"http://{args.host}:{args.port} (passcode required); "
+        f"watching {config.workspace_root}",
+        flush=True,
+    )
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.shutdown()
+        server.server_close()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

alissa_tools_github_revloop-0.15.0/src/main/alissa/tools/github/revloop/webui/auth.py

@@ -0,0 +1,200 @@
+"""Fail-closed authentication for the reviewer console.
+
+The whole surface is a single operator passcode (`ALISSA_UI_PASSCODE`). There
+is no user store: the sidecar is a personal operator tool, not a multi-tenant
+service. The security posture (identical to the devloop console's contract --
+one operator learns one console):
+
+* **Fail-closed.** No passcode in the environment -> the server refuses to
+  start (`require_passcode` raises). There is deliberately no "unauthenticated"
+  fallback -- an operator console with kill/retry actions must never boot open.
+* **Constant-time passcode compare.** `hmac.compare_digest`, so a wrong guess
+  leaks no timing signal about how many leading characters matched.
+* **HMAC-signed session cookie.** The signing key is derived from the passcode
+  AND a per-boot nonce, so (a) a stolen cookie cannot be forged without the
+  passcode, and (b) every restart invalidates all outstanding sessions (the
+  nonce changes) -- a cheap, deliberate "reboot logs everyone out".
+* **CSRF token bound to the session.** Every state-changing POST must present a
+  token that is itself an HMAC over the session cookie, so a cross-site form
+  post (which cannot read the cookie to derive the token) is rejected even
+  though the browser would attach the cookie.
+* **Login throttle.** A small sliding-window lockout blunts online guessing.
+
+Nothing here is a substitute for network isolation -- the sidecar is meant to
+sit behind localhost / a private network -- but it means an exposed port is not
+an instant takeover.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import secrets
+import time
+from typing import Callable, Mapping
+
+# The environment variable that carries the operator passcode. Unset or
+# whitespace-only means "no passcode" -> fail-closed (see require_passcode).
+# Deliberately the same name the devloop console uses: an operator running both
+# sidecars on one machine sets one secret, and the two are separate processes
+# with separate boot nonces regardless.
+ENV_PASSCODE = "ALISSA_UI_PASSCODE"
+
+# The session cookie name. Namespaced per console so a browser holding both
+# sidecars open (same host, different ports -- cookies are NOT port-scoped)
+# does not have one console's cookie overwrite the other's.
+SESSION_COOKIE = "alissa_revloop_ui"
+
+# Sessions live half a day by default; a signed cookie past its issue age is
+# rejected even though its signature still verifies.
+DEFAULT_SESSION_TTL = 12 * 60 * 60
+
+
+class PasscodeUnset(RuntimeError):
+    """Raised when ALISSA_UI_PASSCODE is missing or whitespace-only. The server
+    turns this into a refusal to start (fail-closed), never a warning."""
+
+
+def require_passcode(environ: Mapping[str, str]) -> str:
+    """The passcode, or raise PasscodeUnset. `environ` is passed in (not read
+    from os.environ here) so the boot check is a pure function the tests drive
+    directly. Whitespace-only counts as unset: a stray `ALISSA_UI_PASSCODE=` in
+    a compose file must fail closed, not boot with an empty secret."""
+    raw = environ.get(ENV_PASSCODE)
+    if raw is None or not raw.strip():
+        raise PasscodeUnset(
+            f"{ENV_PASSCODE} is unset -- the reviewer console refuses to start "
+            f"without a passcode (fail-closed). Set {ENV_PASSCODE} and retry."
+        )
+    return raw
+
+
+class LoginThrottle:
+    """A sliding-window login-attempt throttle. After `max_attempts` failures
+    inside `window_seconds`, logins are locked for `lockout_seconds`. A success
+    clears the record. Deliberately global (one operator, one console), so it
+    is a lockout, not a per-IP heuristic that a proxy could smear."""
+
+    def __init__(
+        self,
+        *,
+        max_attempts: int = 5,
+        window_seconds: float = 300.0,
+        lockout_seconds: float = 60.0,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self._max = max_attempts
+        self._window = window_seconds
+        self._lockout = lockout_seconds
+        self._clock = clock
+        self._failures: list[float] = []
+        self._locked_until = 0.0
+
+    def locked(self) -> bool:
+        return self._clock() < self._locked_until
+
+    def retry_after(self) -> float:
+        """Seconds until logins are accepted again (0.0 when not locked)."""
+        return max(0.0, self._locked_until - self._clock())
+
+    def record_failure(self) -> None:
+        now = self._clock()
+        self._failures = [t for t in self._failures if now - t < self._window]
+        self._failures.append(now)
+        if len(self._failures) >= self._max:
+            self._locked_until = now + self._lockout
+            self._failures = []
+
+    def record_success(self) -> None:
+        self._failures = []
+        self._locked_until = 0.0
+
+
+class Auth:
+    """Passcode verification, session issue/verify, and CSRF binding.
+
+    The signing key is `sha256(boot_nonce : passcode)`; changing either
+    invalidates every outstanding session, which is exactly the reboot/rotate
+    behaviour we want. All comparisons are constant-time.
+    """
+
+    def __init__(
+        self,
+        passcode: str,
+        *,
+        boot_nonce: str | None = None,
+        session_ttl: float = DEFAULT_SESSION_TTL,
+        clock: Callable[[], float] = time.time,
+        throttle: LoginThrottle | None = None,
+    ) -> None:
+        self._passcode = passcode
+        self.boot_nonce = boot_nonce or secrets.token_hex(16)
+        self._key = hashlib.sha256(
+            f"{self.boot_nonce}:{passcode}".encode()
+        ).digest()
+        self._ttl = session_ttl
+        self._clock = clock
+        self.throttle = throttle if throttle is not None else LoginThrottle()
+
+    # -- passcode / login --------------------------------------------------
+
+    def verify_passcode(self, submitted: str) -> bool:
+        return hmac.compare_digest(
+            (submitted or "").encode(), self._passcode.encode()
+        )
+
+    def attempt_login(self, submitted: str) -> tuple[bool, str]:
+        """Throttle-aware login. Returns (ok, reason) where reason is one of
+        "ok", "locked", "bad". A locked console never even compares the
+        passcode, so a lockout is not a timing oracle either."""
+        if self.throttle.locked():
+            return False, "locked"
+        if self.verify_passcode(submitted):
+            self.throttle.record_success()
+            return True, "ok"
+        self.throttle.record_failure()
+        return False, "bad"
+
+    # -- session cookie ----------------------------------------------------
+
+    def _mac(self, payload: str) -> str:
+        return hmac.new(self._key, payload.encode(), hashlib.sha256).hexdigest()
+
+    def issue_session(self) -> str:
+        """A fresh signed session token: `<sid>.<issued_at>.<mac>`."""
+        sid = secrets.token_hex(16)
+        issued = int(self._clock())
+        return self._sign(f"{sid}.{issued}")
+
+    def _sign(self, payload: str) -> str:
+        return f"{payload}.{self._mac(payload)}"
+
+    def verify_session(self, token: str | None) -> bool:
+        """True iff `token` is a well-formed, correctly-signed, unexpired
+        session cookie. Any malformed input returns False, never raises."""
+        if not token:
+            return False
+        payload, _, mac = token.rpartition(".")
+        if not payload or not mac:
+            return False
+        if not hmac.compare_digest(self._mac(payload), mac):
+            return False
+        _, _, issued_str = payload.rpartition(".")
+        try:
+            issued = int(issued_str)
+        except ValueError:
+            return False
+        return 0 <= (self._clock() - issued) <= self._ttl
+
+    # -- CSRF binding ------------------------------------------------------
+
+    def csrf_token(self, session_token: str) -> str:
+        """A CSRF token bound to a specific session cookie. A cross-site form
+        cannot read the cookie, so it cannot compute this -- the token is the
+        proof that the request originated from a page WE served."""
+        return self._mac(f"csrf:{session_token}")
+
+    def verify_csrf(self, session_token: str | None, csrf: str | None) -> bool:
+        if not session_token or not csrf:
+            return False
+        return hmac.compare_digest(self.csrf_token(session_token), csrf)