alissa-tools-github-orcloop 0.2.0__tar.gz → 0.3.1__tar.gz

{alissa_tools_github_orcloop-0.2.0/src/main/alissa_tools_github_orcloop.egg-info → alissa_tools_github_orcloop-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-orcloop
-Version: 0.2.0
+Version: 0.3.1
 Summary: ALISSA-TOOLS-GITHUB-ORCLOOP
 Home-page: https://alissa.app
 Author: Fahera

{alissa_tools_github_orcloop-0.2.0 → alissa_tools_github_orcloop-0.3.1}/src/main/alissa/tools/github/orcloop/__main__.py

@@ -1,7 +1,10 @@
 """CLI entry point: alissa-orcloop (or python -m alissa.tools.github.orcloop).
 
 O1 wired the config surface and the argument parser; O3 wires the decision
-loop behind it. The CLI resolves and validates the full configuration
+loop behind it; O6 adds the release-feed selector (`--release-feed bow` and its
+`--bow-prefix` / `--bow-owner` / `--scan-fallback-interval` knobs).
+
+The CLI resolves and validates the full configuration
 (four-layer precedence, fail-closed `repos` guard), reports the effective
 settings, then runs the orchestrator: `--once` for a single sweep (pair it
 with `--dry-run -v` to print every decision and its reasons without touching
@@ -18,6 +21,8 @@ from pathlib import Path
 
 from .alissa_client import AlissaError
 from .config import (
+    FEED_BOW,
+    RELEASE_FEEDS,
     Config,
     load_config_file,
     resolve_config_path,
@@ -79,9 +84,10 @@ def build_parser() -> argparse.ArgumentParser:
         dest="repos",
         action="append",
         metavar="OWNER/REPO",
-        help="watch this repo; repeatable. When given, REPLACES the config "
-        "`repos` list. The allowlist is fail-closed: an empty allowlist is a "
-        "fatal startup error, not a no-op.",
+        help="watch this repo; repeatable, and one flag may carry several "
+        "entries separated by `|` (the daemon-family convention) or `,`. When "
+        "given, REPLACES the config `repos` list. The allowlist is fail-closed: "
+        "an empty allowlist is a fatal startup error, not a no-op.",
     )
     over.add_argument("--label", metavar="LABEL", help="issue label released work carries")
     over.add_argument("--poll-interval", type=int, metavar="SECONDS")
@@ -91,6 +97,41 @@ def build_parser() -> argparse.ArgumentParser:
     over.add_argument("--scope-key", metavar="KEY", help="Autonomous-Scope trailer key")
     over.add_argument("--alissa-endpoint", metavar="URL")
     over.add_argument("--ledger-path", type=Path, metavar="PATH")
+    over.add_argument(
+        "--release-feed",
+        choices=RELEASE_FEEDS,
+        metavar="{" + ",".join(RELEASE_FEEDS) + "}",
+        help="where release candidates come from: 'scan' (the default) lists "
+        "every committed task and filters it on the release marker; 'bow' "
+        "reads the per-repo Bodies of Work named <bow-prefix><owner>/<repo>, "
+        "where attaching a task is the release trigger AND the repo declaration",
+    )
+    over.add_argument(
+        "--bow-prefix",
+        metavar="PREFIX",
+        help="title prefix that marks a Body of Work as a release feed "
+        "(default 'autodev: '); the rest of the title is the target owner/repo",
+    )
+    over.add_argument(
+        "--bow-owner",
+        dest="bow_owners",
+        action="append",
+        metavar="ACTOR_ID",
+        help="bow feed only: trust bodies of work OWNED by this Alissa actor "
+        "as release feeds; repeatable. When given, REPLACES the config "
+        "`bow_owners` list. Fail-closed like --repo: `--release-feed bow` with "
+        "an empty owner list is a fatal startup error, because being SHARED a "
+        "body of work is not a claim to drive this daemon. An actor id is the "
+        "`ownerActorId` on the container's row in GET /v1/bodies-of-work.",
+    )
+    over.add_argument(
+        "--scan-fallback-interval",
+        type=int,
+        metavar="SECONDS",
+        help="bow feed only: how often to ALSO run the full marker scan and "
+        "log every marked task the feed did not surface (default 3600; 0 "
+        "disables it). The sweep reports, it never releases.",
+    )
 
     close = over.add_mutually_exclusive_group()
     close.add_argument(
@@ -139,6 +180,10 @@ def overrides_from(args: argparse.Namespace) -> dict:
         "ledger_path": args.ledger_path,
         "close_loop_enabled": args.close_loop_enabled,
         "dry_run": args.dry_run,
+        "release_feed": args.release_feed,
+        "bow_prefix": args.bow_prefix,
+        "bow_owners": tuple(args.bow_owners) if args.bow_owners else None,
+        "scan_fallback_interval": args.scan_fallback_interval,
     }
 
 
@@ -161,6 +206,22 @@ def log_effective_config(config: Config) -> None:
         config.poll_interval, config.repo_parallelism, config.dry_run,
         config.close_loop_enabled,
     )
+    if config.release_feed == FEED_BOW:
+        log.info(
+            "release feed: bow — candidates are the tasks attached to the "
+            "%r bodies of work OWNED by %s; scan fallback sweep %s",
+            config.bow_prefix,
+            ", ".join(config.bow_owners),
+            f"every {config.scan_fallback_interval}s"
+            if config.scan_fallback_interval
+            else "DISABLED",
+        )
+    else:
+        log.info(
+            "release feed: scan — candidates are committed tasks carrying %r, "
+            "targeted by their %s trailer",
+            config.label, config.marker_key,
+        )
     log.debug("marker_key: %s", config.marker_key)
     log.debug("scope_key: %s", config.scope_key)
     log.debug("release_blocked_floor_days: %s", config.release_blocked_floor_days)

{alissa_tools_github_orcloop-0.2.0 → alissa_tools_github_orcloop-0.3.1}/src/main/alissa/tools/github/orcloop/alissa_client.py

@@ -53,6 +53,47 @@ Three narrow, actionable buckets so the loop can react without string-matching:
 
 Anything else (a 400 validation error, say) surfaces as the base
 ``AlissaError`` -- a bug to fix, not a condition to retry blindly.
+
+THE BODY-OF-WORK SURFACE (O6)
+=============================
+The `bow` release feed reads candidates out of per-repo Bodies of Work instead
+of scanning every committed task. Three endpoints, all verified live against
+``api.alissa.app`` while implementing O6:
+
+* ``GET /v1/bodies-of-work?includeShared=true`` -> ``{"bodiesOfWork": [...]}``.
+  **One call, no server-side title/status filter** (``?status=``/``?q=`` are
+  silently ignored), so the ``bow_prefix`` match runs here. The endpoint does,
+  however, have a SCOPE parameter, and it is not optional for a daemon: the
+  default list is what the actor **owns**, and ``includeShared=true`` adds the
+  ones it merely collaborates on. Measured live: 14 owned, 19 with the flag.
+  Feed containers are operator-created (there is no create endpoint) and the
+  daemon is a collaborator, so every one of them lives in that difference --
+  omitting the flag makes the ``bow`` feed discover nothing, silently. A
+  collaborator BOW is otherwise perfectly visible: ``GET
+  /v1/bodies-of-work/<id>`` returns it and membership reads work; it is only
+  absent from the DEFAULT listing. This is the whole discovery cost: the number
+  of Bodies of Work an org has is a small constant, not a function of task
+  count. The flag also widens the listing to containers ANY actor shared with
+  the daemon, so each row carries its ``ownerActorId`` and the loop admits only
+  the owners the operator allowlisted (``bow_owners``) -- see
+  ``list_bodies_of_work``.
+* ``GET /v1/bodies-of-work/<id>`` -> ``{"bodyOfWork": {..., "tasks": [{"_id",
+  "status", "title"}]}}``. The membership list is EMBEDDED in the BOW detail;
+  there is no ``/bodies-of-work/<id>/tasks`` route, and ``GET /v1/tasks`` has no
+  ``bodyOfWorkId`` filter (an unknown query param is silently ignored, which
+  would have read as "every task is a member"). Member rows carry no
+  ``taskNumber``, so the loop resolves each committed member through
+  ``get_task`` -- which accepts the opaque ``_id`` as a ref.
+* ``DELETE /v1/bodies-of-work/<id>/tasks/<ref>`` -> ``{"removed": bool}``. The
+  detach that terminates a successful release. **Idempotent**: detaching a task
+  that is not attached returns ``removed: false`` rather than an error, so a
+  crash-resumed detach is safe. The ``<ref>`` accepts both ``TASK-<n>`` and the
+  opaque id. A task id that does not exist at all is a 404 (``TASK_NOT_FOUND``).
+
+Both BOW endpoints require the daemon actor to be a **collaborator** on the
+Body of Work (otherwise 403 ``FORBIDDEN`` on attach/detach) -- an operator setup
+step, documented in the README. orcloop never attaches: attaching is the
+operator's trigger, detaching is orcloop's terminal release act.
 """
 
 from __future__ import annotations
@@ -116,6 +157,38 @@ class MarkedTask:
     description: str
 
 
+@dataclass(frozen=True)
+class BodyOfWork:
+    """A Body of Work as the LIST endpoint reports it. Only the fields the feed
+    needs: the id to read membership with, the title carrying the
+    `<prefix><owner>/<repo>` naming convention, the BOW's own status, and
+    `owner_id` -- the actor that OWNS the container (`ownerActorId`).
+
+    `owner_id` is the container's provenance and the only thing here that is
+    not operator-authored text: the listing includes containers this actor was
+    merely SHARED, so the title alone cannot say whether a feed is one the
+    operator set up (see `Config.bow_owners`). Empty when the payload omits it,
+    which the caller treats as untrusted rather than unknown."""
+
+    id: str
+    title: str
+    status: str = ""
+    owner_id: str = ""
+
+
+@dataclass(frozen=True)
+class BowMember:
+    """One task attached to a Body of Work, as the BOW DETAIL endpoint reports
+    it. Deliberately thin: the membership rows carry `_id`, `status` and
+    `title` and NOTHING else -- no taskNumber, no description. `status` is
+    enough to hold an uncommitted member without a detail round-trip; a
+    committed member is resolved through `get_task(id)`."""
+
+    id: str
+    title: str
+    status: str
+
+
 @dataclass(frozen=True)
 class Criterion:
     id: str
@@ -296,6 +369,98 @@ class AlissaClient:
             )
         return out
 
+    # --- the Body-of-Work feed (O6) ----------------------------------------
+
+    def list_bodies_of_work(self) -> list[BodyOfWork]:
+        """Every Body of Work this actor owns OR collaborates on -- ONE call.
+
+        `includeShared=true` is load-bearing, not decoration: the endpoint
+        defaults to OWNED-only, and a feed container is created by the operator
+        in Studio (there is no create endpoint) with the daemon added as a
+        COLLABORATOR. Without the flag the feed's only discovery path returns
+        nothing and `release_feed: bow` is silently inert. There is still no
+        server-side title/status filter (see the module docstring), so the
+        caller narrows by prefix. Rows without an `_id` are dropped: a BOW that
+        cannot be addressed cannot be read for membership.
+
+        THE TRUST BOUNDARY THE FLAG MOVES. `includeShared=true` is necessary
+        (above) but it widens this listing to every container ANY actor in the
+        tenant has shared with the daemon -- unilaterally, with no acceptance
+        step on this side. So membership of this list is NOT a claim to be a
+        release feed: it means "visible", not "authoritative". The title-derived
+        gates downstream (`parse_bow_repo`, `Config.watches`) bound which repo a
+        release lands in, not whose task reaches it, and an allowlisted repo is
+        precisely where the daemon's writes are most trusted. Provenance is
+        therefore carried out of here as `BodyOfWork.owner_id` and checked
+        against the operator's `bow_owners` allowlist before a container is
+        treated as a feed. Collaboration makes a container READABLE (and is
+        still required, for detach); `bow_owners` makes it AUTHORITATIVE.
+        """
+        payload = self._request("GET", "/v1/bodies-of-work?includeShared=true")
+        rows = payload.get("bodiesOfWork") if isinstance(payload, dict) else None
+        if not isinstance(rows, list):
+            return []
+        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=row.get("title") or "",
+                    status=row.get("status") or "",
+                    owner_id=row.get("ownerActorId") or "",
+                )
+            )
+        return out
+
+    def body_of_work_tasks(self, bow_id: str) -> list[BowMember]:
+        """The tasks attached to one Body of Work, in the BOW's own order.
+
+        Membership is embedded in the BOW detail payload; there is no separate
+        listing route. Rows without an `_id` are dropped for the same reason as
+        above -- an unaddressable member cannot be resolved or detached.
+        """
+        payload = self._request(
+            "GET", f"/v1/bodies-of-work/{urllib.parse.quote(str(bow_id), safe='')}"
+        )
+        bow = payload.get("bodyOfWork") if isinstance(payload, dict) else None
+        if not isinstance(bow, dict):
+            raise AlissaError(200, f"no bodyOfWork object in response for {bow_id!r}")
+        out: list[BowMember] = []
+        for row in bow.get("tasks") or []:
+            if not isinstance(row, dict):
+                continue
+            task_id = row.get("_id")
+            if not isinstance(task_id, str) or not task_id:
+                continue
+            out.append(
+                BowMember(
+                    id=task_id,
+                    title=row.get("title") or "",
+                    status=row.get("status") or "",
+                )
+            )
+        return out
+
+    def detach_task(self, bow_id: str, ref: str) -> bool:
+        """Detach a task from a Body of Work; True when this call removed it.
+
+        Idempotent by contract: detaching an already-detached task answers
+        `removed: false` with a 2xx, so the terminal step of a release can be
+        retried after a crash without a "was it already done?" probe. `ref`
+        accepts `TASK-<n>` or the opaque task id.
+        """
+        payload = self._request(
+            "DELETE",
+            f"/v1/bodies-of-work/{urllib.parse.quote(str(bow_id), safe='')}"
+            f"/tasks/{urllib.parse.quote(str(ref), safe='')}",
+        )
+        return bool(payload.get("removed")) if isinstance(payload, dict) else False
+
     def get_task(self, ref: str) -> Task:
         """Full detail for one task. `ref` is any reference form the API accepts
         (`TASK-<n>`, public id, url). Raises `AlissaNotFound` when the bound