hidden-moves-github-projects 0.1.0__py3-none-any.whl

hidden_moves_github_projects/models.py

@@ -0,0 +1,130 @@
+"""Concrete, transport-neutral records for bounded Projects reads."""
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+OwnerKind = Literal["user", "organization"]
+
+
+@dataclass(frozen=True)
+class PageInfo:
+	has_next_page: bool
+	end_cursor: str | None
+
+
+@dataclass(frozen=True)
+class Diagnostic:
+	code: str
+	node_id: str | None = None
+	graphql_type: str | None = None
+
+
+@dataclass(frozen=True)
+class Project:
+	id: str
+	number: int
+	title: str
+	url: str
+	owner_login: str
+	owner_kind: OwnerKind
+	description: str | None
+	public: bool
+	closed: bool
+
+
+@dataclass(frozen=True)
+class ProjectPage:
+	projects: list[Project]
+	page_info: PageInfo
+	diagnostics: list[Diagnostic] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class SelectOption:
+	id: str
+	name: str
+
+
+@dataclass(frozen=True)
+class Iteration:
+	id: str
+	title: str
+	start_date: str
+	duration: int
+	completed: bool = False
+
+
+@dataclass(frozen=True)
+class ProjectField:
+	id: str | None
+	name: str | None
+	data_type: str | None
+	graphql_type: str
+	options: list[SelectOption] = field(default_factory=list)
+	iterations: list[Iteration] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class FieldPage:
+	project_id: str
+	fields: list[ProjectField]
+	page_info: PageInfo
+	diagnostics: list[Diagnostic] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class Content:
+	kind: str
+	id: str | None = None
+	title: str | None = None
+	url: str | None = None
+	number: int | None = None
+	repository: str | None = None
+	state: str | None = None
+	body: str | None = None
+	graphql_type: str | None = None
+
+
+@dataclass(frozen=True)
+class FieldValue:
+	graphql_type: str
+	id: str | None = None
+	field_id: str | None = None
+	field_name: str | None = None
+	text: str | None = None
+	number: float | None = None
+	date: str | None = None
+	option_id: str | None = None
+	option_name: str | None = None
+	iteration: Iteration | None = None
+
+
+@dataclass(frozen=True)
+class FieldValuePage:
+	item_id: str
+	values: list[FieldValue]
+	page_info: PageInfo
+	diagnostics: list[Diagnostic] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class ProjectItem:
+	id: str
+	project_id: str
+	item_type: str
+	archived: bool
+	created_at: str
+	updated_at: str
+	content: Content
+	field_values: list[FieldValue]
+	field_values_page: PageInfo
+	field_values_complete: bool
+	diagnostics: list[Diagnostic] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class ItemPage:
+	project_id: str
+	items: list[ProjectItem]
+	page_info: PageInfo
+	diagnostics: list[Diagnostic] = field(default_factory=list)

hidden_moves_github_projects/snapshots.py

@@ -0,0 +1,122 @@
+"""Optional explicit Projects-to-Backpack snapshots; no synchronization or writes."""
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+from backpack_store import Backpack, DataclassCodec, Provenance, WriteResult
+from backpack_store.records import utc_now, validate_timestamp
+
+from .client import ProjectsClient
+from .errors import NotFoundError, ProjectsError
+from .models import OwnerKind, Project, ProjectItem
+
+SNAPSHOT_TYPE_KEY = "github.project_item_snapshot"
+SNAPSHOT_SCHEMA_VERSION = 1
+
+
+class SnapshotError(ProjectsError):
+    """A supplied snapshot does not match its source Project identity."""
+
+
+@dataclass(frozen=True)
+class ProjectItemSnapshot:
+    project: Project
+    item: ProjectItem
+    captured_at: str
+
+    def __post_init__(self) -> None:
+        if type(self.project) is not Project or type(self.item) is not ProjectItem:
+            raise SnapshotError(
+                "snapshots require normalized Project and ProjectItem DTOs"
+            )
+        if self.item.project_id != self.project.id:
+            raise SnapshotError("the item must belong to the supplied Project")
+        validate_timestamp(self.captured_at)
+
+
+def register_snapshot_codec(store: Backpack) -> None:
+    """Register the trusted current DTO codec; choose the database separately."""
+    store.register(
+        DataclassCodec(
+            ProjectItemSnapshot,
+            type_key=SNAPSHOT_TYPE_KEY,
+            schema_version=SNAPSHOT_SCHEMA_VERSION,
+        )
+    )
+
+
+def fetch_project_item(
+    client: ProjectsClient,
+    owner: str,
+    owner_kind: OwnerKind,
+    number: int,
+    item_id: str,
+    *,
+    page_size: int = 50,
+    field_page_size: int = 50,
+    max_pages: int = 10,
+) -> tuple[Project, ProjectItem]:
+    """Find one explicit item through bounded read pages, preserving diagnostics."""
+    if not isinstance(item_id, str) or not item_id or len(item_id) > 256:
+        raise ValueError("item_id must be an explicit opaque Project item ID")
+    project = client.get(owner, owner_kind, number)
+    for page in client.iter_item_pages(
+        project.id,
+        page_size=page_size,
+        field_page_size=field_page_size,
+        max_pages=max_pages,
+    ):
+        for item in page.items:
+            if item.id == item_id:
+                return project, item
+    raise NotFoundError(
+        "the requested item is not available in the bounded Project connection"
+    )
+
+
+def store_snapshot(
+    store: Backpack,
+    project: Project,
+    item: ProjectItem,
+    *,
+    captured_at: str | None = None,
+    tags: Iterable[str] = (),
+) -> WriteResult:
+    """Persist one dated DTO after the application registers its snapshot codec."""
+    snapshot = ProjectItemSnapshot(
+        project, item, utc_now() if captured_at is None else captured_at
+    )
+    provenance = Provenance(
+        source_url=project.url,
+        source_system="github-projects",
+        source_id=item.id,
+        captured_at=snapshot.captured_at,
+    )
+    return store.put(snapshot, tags=tags, provenance=provenance)
+
+
+def capture_project_item(
+    client: ProjectsClient,
+    store: Backpack,
+    owner: str,
+    owner_kind: OwnerKind,
+    number: int,
+    item_id: str,
+    *,
+    page_size: int = 50,
+    field_page_size: int = 50,
+    max_pages: int = 10,
+    tags: Iterable[str] = (),
+) -> WriteResult:
+    """Fetch first, then atomically persist; a fetch failure creates no record."""
+    project, item = fetch_project_item(
+        client,
+        owner,
+        owner_kind,
+        number,
+        item_id,
+        page_size=page_size,
+        field_page_size=field_page_size,
+        max_pages=max_pages,
+    )
+    return store_snapshot(store, project, item, tags=tags)

hidden_moves_github_projects/transport.py

@@ -0,0 +1,32 @@
+"""Bounded HTTP POST transport with credential-bearing redirects disabled."""
+
+from dataclasses import dataclass, field
+from typing import Protocol
+from urllib.error import HTTPError
+from urllib.request import HTTPRedirectHandler, Request, build_opener
+
+
+@dataclass(frozen=True)
+class HTTPResponse:
+	status: int
+	body: bytes = field(repr=False)
+
+
+class Transport(Protocol):
+	def __call__(self, request: Request, *, timeout: float, max_bytes: int) -> HTTPResponse: ...
+
+
+class _NoRedirect(HTTPRedirectHandler):
+	def redirect_request(self, req, fp, code, msg, headers, newurl):
+		return None
+
+
+def http_transport(request: Request, *, timeout: float, max_bytes: int) -> HTTPResponse:
+	"""Make one explicit request, reading at most the budget plus one sentinel byte."""
+	try:
+		with build_opener(_NoRedirect()).open(request, timeout=timeout) as response:
+			return HTTPResponse(response.status, response.read(max_bytes + 1))
+	except HTTPError as error:
+		status = error.code
+		error.close()
+		return HTTPResponse(status, b"")

hidden_moves_github_projects/write_host.py

@@ -0,0 +1,69 @@
+"""Explicit local write host, separate from the default read-only host."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+from collections.abc import Iterable
+from typing import TYPE_CHECKING
+
+from .client import ProjectsClient
+from .host import resolve_gh_token
+from .writes import ProjectsWriter
+
+if TYPE_CHECKING:
+    from hidden_moves.adapters import CapabilityCatalog
+
+
+def build_write_catalog(
+    writer: ProjectsWriter, names: Iterable[str]
+) -> CapabilityCatalog:
+    from hidden_moves import Moves, discover_providers, load_provider
+    from hidden_moves.adapters import CapabilityCatalog
+
+    names = tuple(names)
+    if not names:
+        raise ValueError("Select at least one explicit Project write capability.")
+    entries = [
+        entry for entry in discover_providers() if entry.name == "github-projects-write"
+    ]
+    if len(entries) != 1:
+        raise ValueError("Install exactly one github-projects-write provider.")
+    moves = Moves(target=writer)
+    load_provider(entries[0], moves.registry)
+    return CapabilityCatalog(moves, names)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Serve explicitly authorized bounded Project writes over local MCP stdio."
+    )
+    parser.add_argument(
+        "--allow-project",
+        action="append",
+        required=True,
+        help="Authorized Project node ID; repeat for each allowed Project.",
+    )
+    parser.add_argument(
+        "--move",
+        action="append",
+        required=True,
+        help="Qualified write capability; repeat to select operations.",
+    )
+    args = parser.parse_args()
+    try:
+        from hidden_moves_mcp import MCPAdapter, serve_stdio
+
+        from hidden_moves import MoveError
+
+        writer = ProjectsWriter(
+            ProjectsClient(resolve_gh_token), allowed_projects=args.allow_project
+        )
+        server = MCPAdapter(build_write_catalog(writer, args.move)).server(
+            "github-projects-write"
+        )
+    except ImportError:
+        parser.error("Install the Projects package with its [host] extra.")
+    except (MoveError, ValueError) as error:
+        parser.error(str(error))
+    asyncio.run(serve_stdio(server))

hidden_moves_github_projects/write_integration.py

@@ -0,0 +1,53 @@
+"""A separate explicitly bound write provider; no model-supplied approval flag."""
+
+from hidden_moves import MoveAnnotations, MoveSpec
+
+from .writes import ProjectsWriter, WriteOutcomeUnknownError, WriteReceipt
+
+WRITE_CAPABILITIES = ("github.projects.add_item", "github.projects.set_single_select")
+
+
+def add_item(writer: ProjectsWriter, project_id: str, content_id: str) -> WriteReceipt:
+    """Add an existing Issue/PR to an authorized Project and verify its identity."""
+    try:
+        return writer.add_item(project_id, content_id)
+    except WriteOutcomeUnknownError as error:
+        return error.receipt
+
+
+def set_single_select(
+    writer: ProjectsWriter,
+    project_id: str,
+    item_id: str,
+    field_name: str,
+    option_name: str,
+    expected_option_id: str | None,
+) -> WriteReceipt:
+    """Set a resolved choice after an expected-value check and verify the write."""
+    try:
+        return writer.set_single_select(
+            project_id, item_id, field_name, option_name, expected_option_id
+        )
+    except WriteOutcomeUnknownError as error:
+        return error.receipt
+
+
+def provide_write_moves() -> tuple[MoveSpec, ...]:
+    """Advertise only two writes; the application must configure the bound writer."""
+    annotations = MoveAnnotations(
+        read_only=False, destructive=True, idempotent=False, external=True
+    )
+    return tuple(
+        MoveSpec(
+            name=name,
+            namespace="github.projects",
+            func=operation,
+            bind_target=True,
+            target_types=(ProjectsWriter,),
+            annotations=annotations,
+        )
+        for name, operation in (
+            ("add_item", add_item),
+            ("set_single_select", set_single_select),
+        )
+    )