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

hidden_moves_github_projects/__init__.py

@@ -0,0 +1,38 @@
+"""Read typed GitHub Projects records without a registry or protocol dependency."""
+
+from .client import ProjectsClient
+from .errors import (
+	CredentialError,
+	GraphQLError,
+	HTTPStatusError,
+	NotFoundError,
+	PaginationLimitError,
+	ProjectsError,
+	ProtocolError,
+	TransportError,
+)
+from .models import (
+	Content,
+	Diagnostic,
+	FieldPage,
+	FieldValue,
+	FieldValuePage,
+	ItemPage,
+	Iteration,
+	OwnerKind,
+	PageInfo,
+	Project,
+	ProjectField,
+	ProjectItem,
+	ProjectPage,
+	SelectOption,
+)
+from .transport import HTTPResponse, Transport
+
+__all__ = [
+	"Content", "CredentialError", "Diagnostic", "FieldPage", "FieldValue", "FieldValuePage",
+	"GraphQLError", "HTTPResponse", "HTTPStatusError", "ItemPage", "Iteration", "NotFoundError",
+	"OwnerKind", "PageInfo", "PaginationLimitError", "Project", "ProjectField", "ProjectItem",
+	"ProjectPage", "ProjectsClient", "ProjectsError", "ProtocolError", "SelectOption", "Transport",
+	"TransportError",
+]

hidden_moves_github_projects/__main__.py

@@ -0,0 +1,6 @@
+"""Run the optional configured local host only when explicitly executed."""
+
+from .host import main
+
+if __name__ == "__main__":
+	main()

hidden_moves_github_projects/_normalize.py

@@ -0,0 +1,204 @@
+"""Normalize only queried fields and retain diagnostics for unavailable data."""
+
+import math
+from typing import Any
+
+from .errors import NotFoundError, ProtocolError
+from .models import (
+	Content,
+	Diagnostic,
+	FieldValue,
+	FieldValuePage,
+	Iteration,
+	PageInfo,
+	Project,
+	ProjectField,
+	ProjectItem,
+	SelectOption,
+)
+
+
+def obj(value: Any) -> dict:
+	if not isinstance(value, dict):
+		raise ProtocolError("GitHub returned an invalid object.")
+	return value
+
+
+def text(value: Any, *, nullable: bool = False) -> str | None:
+	if nullable and value is None:
+		return None
+	if not isinstance(value, str):
+		raise ProtocolError("GitHub returned an invalid text field.")
+	return value
+
+
+def integer(value: Any) -> int:
+	if type(value) is not int:
+		raise ProtocolError("GitHub returned an invalid integer field.")
+	return value
+
+
+def boolean(value: Any) -> bool:
+	if type(value) is not bool:
+		raise ProtocolError("GitHub returned an invalid boolean field.")
+	return value
+
+
+def identity(value: Any) -> str:
+	value = text(value)
+	if not value:
+		raise ProtocolError("GitHub returned an invalid node identity.")
+	return value
+
+
+def sequence(value: Any) -> list:
+	if not isinstance(value, list):
+		raise ProtocolError("GitHub returned an invalid list.")
+	return value
+
+
+def connection(value: Any) -> tuple[list, PageInfo]:
+	value = obj(value)
+	page = obj(value.get("pageInfo"))
+	info = PageInfo(boolean(page.get("hasNextPage")), text(page.get("endCursor"), nullable=True))
+	if info.has_next_page and not info.end_cursor:
+		raise ProtocolError("GitHub omitted the next-page cursor.")
+	return sequence(value.get("nodes")), info
+
+
+def node(data: dict, expected: str) -> dict:
+	value = data.get("node")
+	if value is None:
+		raise NotFoundError("The requested node is absent or inaccessible.")
+	value = obj(value)
+	if value.get("__typename") != expected:
+		raise NotFoundError("The requested node has a different resource type.")
+	return value
+
+
+def project(value: dict) -> Project:
+	value = obj(value)
+	owner = obj(value.get("owner"))
+	kinds = {"User": "user", "Organization": "organization"}
+	kind = kinds.get(owner.get("__typename"))
+	if kind is None:
+		raise ProtocolError("GitHub returned an unsupported project owner.")
+	return Project(
+		identity(value.get("id")), integer(value.get("number")), text(value.get("title")),
+		text(value.get("url")), identity(owner.get("login")), kind,
+		text(value.get("shortDescription"), nullable=True), boolean(value.get("public")),
+		boolean(value.get("closed")),
+	)
+
+
+def iteration(value: dict, *, completed: bool = False) -> Iteration:
+	value = obj(value)
+	return Iteration(
+		identity(value.get("id")), text(value.get("title")), text(value.get("startDate")),
+		integer(value.get("duration")), completed,
+	)
+
+
+def project_field(value: dict | None) -> tuple[ProjectField, list[Diagnostic]]:
+	if value is None:
+		return ProjectField(None, None, None, "Unavailable"), [Diagnostic("unavailable_field")]
+	value = obj(value)
+	typename = text(value.get("__typename"))
+	field = ProjectField(
+		text(value.get("id"), nullable=True), text(value.get("name"), nullable=True),
+		text(value.get("dataType"), nullable=True), typename,
+	)
+	if typename not in {"ProjectV2Field", "ProjectV2SingleSelectField", "ProjectV2IterationField"}:
+		return field, [Diagnostic("unsupported_field_type", field.id, typename)]
+	identity(field.id)
+	text(field.name)
+	text(field.data_type)
+	if typename == "ProjectV2SingleSelectField":
+		field.options.extend(SelectOption(identity(obj(option).get("id")), text(option.get("name"))) for option in sequence(value.get("options")))
+	if typename == "ProjectV2IterationField":
+		config = obj(value.get("configuration"))
+		field.iterations.extend(iteration(item) for item in sequence(config.get("iterations")))
+		field.iterations.extend(iteration(item, completed=True) for item in sequence(config.get("completedIterations")))
+	return field, []
+
+
+def field_values(item_id: str, value: dict) -> FieldValuePage:
+	nodes, page = connection(value)
+	values, diagnostics = [], []
+	supported = {
+		"ProjectV2ItemFieldTextValue", "ProjectV2ItemFieldNumberValue", "ProjectV2ItemFieldDateValue",
+		"ProjectV2ItemFieldSingleSelectValue", "ProjectV2ItemFieldIterationValue",
+	}
+	for entry in nodes:
+		if entry is None:
+			values.append(FieldValue("Unavailable"))
+			diagnostics.append(Diagnostic("unavailable_field_value", item_id))
+			continue
+		entry = obj(entry)
+		typename = text(entry.get("__typename"))
+		field = obj(entry.get("field", {}))
+		kwargs = {
+			"graphql_type": typename,
+			"id": text(entry.get("id"), nullable=True),
+			"field_id": text(field.get("id"), nullable=True),
+			"field_name": text(field.get("name"), nullable=True),
+		}
+		if typename not in supported:
+			diagnostics.append(Diagnostic("unsupported_field_value", item_id, typename))
+		else:
+			identity(kwargs["id"])
+			identity(kwargs["field_id"])
+			text(kwargs["field_name"])
+			if typename.endswith("TextValue"):
+				kwargs["text"] = text(entry.get("text"), nullable=True)
+			elif typename.endswith("NumberValue"):
+				number = entry.get("number")
+				if number is not None:
+					if type(number) not in (float, int) or not math.isfinite(number):
+						raise ProtocolError("GitHub returned an invalid numeric field value.")
+					kwargs["number"] = float(number)
+			elif typename.endswith("DateValue"):
+				kwargs["date"] = text(entry.get("date"), nullable=True)
+			elif typename.endswith("SingleSelectValue"):
+				kwargs["option_id"] = text(entry.get("optionId"), nullable=True)
+				kwargs["option_name"] = text(entry.get("name"), nullable=True)
+			else:
+				kwargs["iteration"] = iteration({**entry, "id": entry.get("iterationId")})
+		values.append(FieldValue(**kwargs))
+	if page.has_next_page:
+		diagnostics.append(Diagnostic("field_values_incomplete", item_id))
+	return FieldValuePage(item_id, values, page, diagnostics)
+
+
+def content(value: dict | None, item_type: str, item_id: str) -> tuple[Content, list[Diagnostic]]:
+	if value is None:
+		kind = "redacted" if item_type == "REDACTED" else "unavailable"
+		return Content(kind), [Diagnostic(kind + "_content", item_id)]
+	value = obj(value)
+	typename = text(value.get("__typename"))
+	kinds = {"Issue": "issue", "PullRequest": "pull_request", "DraftIssue": "draft"}
+	if typename not in kinds:
+		return Content("unknown", graphql_type=typename), [Diagnostic("unsupported_content_type", item_id, typename)]
+	result = Content(
+		kind=kinds[typename], id=identity(value.get("id")), title=text(value.get("title")),
+		url=text(value.get("url"), nullable=True),
+		number=None if typename == "DraftIssue" else integer(value.get("number")),
+		repository=None if typename == "DraftIssue" else text(obj(value.get("repository")).get("nameWithOwner")),
+		state=text(value.get("state"), nullable=True), body=text(value.get("body"), nullable=True),
+		graphql_type=typename,
+	)
+	return result, []
+
+
+def item(value: dict, project_id: str) -> ProjectItem:
+	value = obj(value)
+	item_id = identity(value.get("id"))
+	item_type = text(value.get("type"))
+	linked, diagnostics = content(value.get("content"), item_type, item_id)
+	fields = field_values(item_id, value.get("fieldValues"))
+	diagnostics.extend(fields.diagnostics)
+	return ProjectItem(
+		item_id, project_id, item_type, boolean(value.get("isArchived")),
+		text(value.get("createdAt")), text(value.get("updatedAt")), linked,
+		fields.values, fields.page_info, not fields.diagnostics, diagnostics,
+	)

hidden_moves_github_projects/_queries.py

@@ -0,0 +1,69 @@
+"""Fixed read-only queries; account identities and cursors are variables."""
+
+PROJECT = """
+id number title url shortDescription public closed
+owner { __typename ... on User { login } ... on Organization { login } }
+"""
+PAGE = "pageInfo { hasNextPage endCursor }"
+FIELDS = """
+__typename
+... on ProjectV2FieldCommon { id name dataType }
+... on ProjectV2SingleSelectField { options { id name } }
+... on ProjectV2IterationField {
+  configuration {
+    iterations { id title startDate duration }
+    completedIterations { id title startDate duration }
+  }
+}
+"""
+VALUES = """
+__typename
+... on ProjectV2ItemFieldValueCommon {
+  id field { ... on ProjectV2FieldCommon { id name } }
+}
+... on ProjectV2ItemFieldTextValue { text }
+... on ProjectV2ItemFieldNumberValue { number }
+... on ProjectV2ItemFieldDateValue { date }
+... on ProjectV2ItemFieldSingleSelectValue { optionId name }
+... on ProjectV2ItemFieldIterationValue { iterationId title startDate duration }
+"""
+CONTENT = """
+__typename
+... on Issue { id number title url state repository { nameWithOwner } }
+... on PullRequest { id number title url state repository { nameWithOwner } }
+... on DraftIssue { id title body }
+"""
+
+
+def owner_query(kind: str, *, listing: bool) -> str:
+	if listing:
+		return f"""query ListProjects($owner: String!, $first: Int!, $cursor: String) {{
+  owner: {kind}(login: $owner) {{ projectsV2(first: $first, after: $cursor) {{
+    nodes {{ {PROJECT} }} {PAGE}
+  }} }}
+}}"""
+	return f"""query GetProject($owner: String!, $number: Int!) {{
+  owner: {kind}(login: $owner) {{ projectV2(number: $number) {{ {PROJECT} }} }}
+}}"""
+
+
+FIELD_QUERY = f"""query ProjectFields($id: ID!, $first: Int!, $cursor: String) {{
+  node(id: $id) {{ __typename ... on ProjectV2 {{
+    fields(first: $first, after: $cursor) {{ nodes {{ {FIELDS} }} {PAGE} }}
+  }} }}
+}}"""
+ITEM_QUERY = f"""query ProjectItems($id: ID!, $first: Int!, $cursor: String, $fieldFirst: Int!) {{
+  node(id: $id) {{ __typename ... on ProjectV2 {{
+    items(first: $first, after: $cursor) {{
+      nodes {{ id type isArchived createdAt updatedAt
+        content {{ {CONTENT} }}
+        fieldValues(first: $fieldFirst) {{ nodes {{ {VALUES} }} {PAGE} }}
+      }} {PAGE}
+    }}
+  }} }}
+}}"""
+VALUE_QUERY = f"""query ItemFieldValues($id: ID!, $first: Int!, $cursor: String) {{
+  node(id: $id) {{ __typename ... on ProjectV2Item {{
+    fieldValues(first: $first, after: $cursor) {{ nodes {{ {VALUES} }} {PAGE} }}
+  }} }}
+}}"""

hidden_moves_github_projects/client.py

@@ -0,0 +1,187 @@
+"""An ordinary read-only Projects client, independent of capability adapters."""
+
+import json
+import math
+from collections.abc import Callable, Iterator
+from urllib.parse import urlsplit
+from urllib.request import Request
+
+from . import _normalize as normalize
+from . import _queries
+from .errors import (
+	CredentialError,
+	GraphQLError,
+	HTTPStatusError,
+	NotFoundError,
+	PaginationLimitError,
+	ProtocolError,
+	TransportError,
+)
+from .models import (
+	Diagnostic,
+	FieldPage,
+	FieldValuePage,
+	ItemPage,
+	OwnerKind,
+	Project,
+	ProjectPage,
+)
+from .transport import HTTPResponse, Transport, http_transport
+
+_ERROR_CODES = {
+	"FORBIDDEN", "NOT_FOUND", "RATE_LIMITED", "UNAUTHORIZED", "UNPROCESSABLE",
+	"MAX_NODE_LIMIT_EXCEEDED", "GRAPHQL_VALIDATION_FAILED", "INSUFFICIENT_SCOPES",
+}
+
+
+def _text(value: str, label: str) -> str:
+	if not isinstance(value, str) or not value.strip():
+		raise ValueError(f"{label} must be a nonempty string.")
+	return value
+
+
+def _count(value: int, label: str, maximum: int = 100) -> int:
+	if type(value) is not int or not 1 <= value <= maximum:
+		raise ValueError(f"{label} must be an integer between 1 and {maximum}.")
+	return value
+
+
+def _cursor(value: str | None) -> str | None:
+	return None if value is None else _text(value, "cursor")
+
+
+class ProjectsClient:
+	"""Resolve explicit credentials and perform one bounded GraphQL read per call."""
+
+	def __init__(
+		self, token: str | Callable[[], str], *, transport: Transport = http_transport,
+		timeout: float = 10.0, max_response_bytes: int = 4_000_000,
+		endpoint: str = "https://api.github.com/graphql",
+	) -> None:
+		if type(timeout) not in (float, int) or not math.isfinite(timeout) or timeout <= 0:
+			raise ValueError("timeout must be a finite positive number.")
+		_count(max_response_bytes, "max_response_bytes", 16_000_000)
+		parsed = urlsplit(endpoint)
+		if parsed.scheme != "https" or not parsed.hostname or parsed.username or parsed.password or parsed.query or parsed.fragment:
+			raise ValueError("endpoint must be an HTTPS URL without credentials, query, or fragment.")
+		if not callable(token) and not isinstance(token, str):
+			raise TypeError("token must be a string or an explicit resolver.")
+		if not callable(transport):
+			raise TypeError("transport must be callable.")
+		self._token = token
+		self._transport = transport
+		self._timeout = float(timeout)
+		self._max_response_bytes = max_response_bytes
+		self._endpoint = endpoint
+
+	def __repr__(self) -> str:
+		return "ProjectsClient()"
+
+	def _execute(self, query: str, variables: dict) -> dict:
+		try:
+			token = self._token() if callable(self._token) else self._token
+		except Exception:  # noqa: BLE001 - Resolver failures may contain credentials.
+			raise CredentialError("The configured credential resolver failed.") from None
+		if not isinstance(token, str) or not token.strip() or any(char.isspace() for char in token):
+			raise CredentialError("The configured credential is empty or invalid.")
+		request = Request(
+			self._endpoint, data=json.dumps({"query": query, "variables": variables}, allow_nan=False).encode(),
+			headers={"Authorization": "Bearer " + token, "Accept": "application/json", "Content-Type": "application/json", "User-Agent": "hidden-moves-github-projects/0.1.0"},
+			method="POST",
+		)
+		try:
+			response = self._transport(request, timeout=self._timeout, max_bytes=self._max_response_bytes)
+		except Exception:  # noqa: BLE001 - Transport failures may echo request credentials.
+			raise TransportError("The configured GitHub transport failed.") from None
+		if not isinstance(response, HTTPResponse) or type(response.status) is not int or not 100 <= response.status <= 599 or not isinstance(response.body, bytes):
+			raise ProtocolError("The transport returned an invalid response.")
+		if response.status != 200:
+			raise HTTPStatusError(response.status)
+		if len(response.body) > self._max_response_bytes:
+			raise ProtocolError("The GitHub response exceeded the configured byte budget.")
+		try:
+			def reject_constant(value):
+				raise ValueError("non-finite JSON")
+			result = json.loads(response.body, parse_constant=reject_constant)
+		except (ValueError, UnicodeError, RecursionError):
+			raise ProtocolError("GitHub returned invalid JSON.") from None
+		result = normalize.obj(result)
+		errors = result.get("errors")
+		if errors is not None and not isinstance(errors, list):
+			raise ProtocolError("GitHub returned an invalid GraphQL error response.")
+		if errors:
+			codes = []
+			for error in errors:
+				code = error.get("type") if isinstance(error, dict) else None
+				codes.append(code if isinstance(code, str) and code in _ERROR_CODES else "GRAPHQL_ERROR")
+			raise GraphQLError(tuple(codes), partial_data=result.get("data") is not None)
+		return normalize.obj(result.get("data"))
+
+	def list(self, owner: str, owner_kind: OwnerKind, *, cursor: str | None = None, page_size: int = 50) -> ProjectPage:
+		"""Read one page of a user's or organization's Projects, retaining its cursor."""
+		if owner_kind not in ("user", "organization"):
+			raise ValueError("owner_kind must be user or organization.")
+		data = self._execute(_queries.owner_query(owner_kind, listing=True), {
+			"owner": _text(owner, "owner"), "first": _count(page_size, "page_size"), "cursor": _cursor(cursor),
+		})
+		if data.get("owner") is None:
+			raise NotFoundError("The requested owner is absent or inaccessible.")
+		nodes, page = normalize.connection(normalize.obj(data["owner"]).get("projectsV2"))
+		diagnostics = [Diagnostic("unavailable_project") for entry in nodes if entry is None]
+		return ProjectPage([normalize.project(entry) for entry in nodes if entry is not None], page, diagnostics)
+
+	def get(self, owner: str, owner_kind: OwnerKind, number: int) -> Project:
+		"""Read a Project by its owner kind, login, and Project number."""
+		if owner_kind not in ("user", "organization"):
+			raise ValueError("owner_kind must be user or organization.")
+		data = self._execute(_queries.owner_query(owner_kind, listing=False), {
+			"owner": _text(owner, "owner"), "number": _count(number, "number", 2_147_483_647),
+		})
+		owner_data = data.get("owner")
+		if owner_data is None or normalize.obj(owner_data).get("projectV2") is None:
+			raise NotFoundError("The requested Project is absent or inaccessible.")
+		return normalize.project(owner_data["projectV2"])
+
+	def fields(self, project_id: str, *, cursor: str | None = None, page_size: int = 50) -> FieldPage:
+		"""Read one field-definition page, including select options and iteration metadata."""
+		data = self._execute(_queries.FIELD_QUERY, {"id": _text(project_id, "project_id"), "first": _count(page_size, "page_size"), "cursor": _cursor(cursor)})
+		nodes, page = normalize.connection(normalize.node(data, "ProjectV2").get("fields"))
+		fields, diagnostics = [], []
+		for value in nodes:
+			field, hints = normalize.project_field(value)
+			fields.append(field)
+			diagnostics.extend(hints)
+		return FieldPage(project_id, fields, page, diagnostics)
+
+	def items(self, project_id: str, *, cursor: str | None = None, page_size: int = 50, field_page_size: int = 50) -> ItemPage:
+		"""Read a bounded item page; incomplete nested values retain their own cursors."""
+		data = self._execute(_queries.ITEM_QUERY, {
+			"id": _text(project_id, "project_id"), "first": _count(page_size, "page_size"),
+			"cursor": _cursor(cursor), "fieldFirst": _count(field_page_size, "field_page_size"),
+		})
+		nodes, page = normalize.connection(normalize.node(data, "ProjectV2").get("items"))
+		items = [normalize.item(value, project_id) for value in nodes if value is not None]
+		diagnostics = [Diagnostic("unavailable_item", project_id) for value in nodes if value is None]
+		diagnostics.extend(hint for value in items for hint in value.diagnostics)
+		return ItemPage(project_id, items, page, diagnostics)
+
+	def item_field_values(self, item_id: str, *, cursor: str | None = None, page_size: int = 50) -> FieldValuePage:
+		"""Continue a nested field-values connection using the item's distinct node ID."""
+		data = self._execute(_queries.VALUE_QUERY, {"id": _text(item_id, "item_id"), "first": _count(page_size, "page_size"), "cursor": _cursor(cursor)})
+		return normalize.field_values(item_id, normalize.node(data, "ProjectV2Item").get("fieldValues"))
+
+	def iter_item_pages(self, project_id: str, *, page_size: int = 50, field_page_size: int = 50, max_pages: int = 10) -> Iterator[ItemPage]:
+		"""Yield pages with diagnostics; exceeding the explicit budget reports truncation."""
+		_count(max_pages, "max_pages", 1000)
+		cursor = None
+		seen = set()
+		for _ in range(max_pages):
+			page = self.items(project_id, cursor=cursor, page_size=page_size, field_page_size=field_page_size)
+			yield page
+			if not page.page_info.has_next_page:
+				return
+			cursor = page.page_info.end_cursor
+			if cursor in seen:
+				raise ProtocolError("GitHub repeated an item-page cursor.")
+			seen.add(cursor)
+		raise PaginationLimitError("The item-page budget ended before the connection did.")

hidden_moves_github_projects/errors.py

@@ -0,0 +1,38 @@
+"""Public error categories; upstream messages and credentials are never copied."""
+
+
+class ProjectsError(Exception):
+	"""A sanitized failure reading GitHub Projects."""
+
+
+class CredentialError(ProjectsError):
+	"""Explicit credentials could not be resolved."""
+
+
+class TransportError(ProjectsError):
+	"""The configured HTTP transport failed."""
+
+
+class HTTPStatusError(ProjectsError):
+	def __init__(self, status: int) -> None:
+		self.status = status
+		super().__init__(f"GitHub returned HTTP status {status}.")
+
+
+class GraphQLError(ProjectsError):
+	def __init__(self, codes: tuple[str, ...], *, partial_data: bool) -> None:
+		self.codes = codes
+		self.partial_data = partial_data
+		super().__init__("GitHub rejected the GraphQL read (" + ", ".join(codes) + ").")
+
+
+class ProtocolError(ProjectsError):
+	"""An invalid or oversized response cannot be normalized."""
+
+
+class NotFoundError(ProjectsError):
+	"""The requested resource is absent or not visible to this credential."""
+
+
+class PaginationLimitError(ProjectsError):
+	"""An explicit iterator budget ended before the connection did."""

hidden_moves_github_projects/host.py

@@ -0,0 +1,70 @@
+"""Explicit client configuration and selection for a local stdio application."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import subprocess
+from collections.abc import Iterable
+from typing import TYPE_CHECKING
+
+from .client import ProjectsClient
+from .errors import CredentialError
+
+if TYPE_CHECKING:
+	from hidden_moves.adapters import CapabilityCatalog
+
+
+def resolve_gh_token() -> str:
+	"""Explicitly read the existing GitHub CLI login; never print its captured token."""
+	try:
+		process = subprocess.run(
+			["gh", "auth", "token", "--hostname", "github.com"],
+			capture_output=True, text=True, check=False, timeout=10,
+		)
+	except (OSError, subprocess.SubprocessError):
+		raise CredentialError("The existing GitHub CLI credential could not be read.") from None
+	if process.returncode or not process.stdout.strip():
+		raise CredentialError("The existing GitHub CLI credential is unavailable.")
+	return process.stdout.strip()
+
+
+def build_catalog(client: ProjectsClient, names: Iterable[str]) -> CapabilityCatalog:
+	"""Bind the configured client before explicitly selecting installed capabilities."""
+	from hidden_moves import Moves, discover_providers, load_provider
+	from hidden_moves.adapters import CapabilityCatalog
+
+	entries = [entry for entry in discover_providers() if entry.name == "github-projects"]
+	if len(entries) != 1:
+		raise ValueError("Install exactly one github-projects provider.")
+	moves = Moves(target=client)
+	load_provider(entries[0], moves.registry)
+	return CapabilityCatalog(moves, names)
+
+
+async def serve_client(client: ProjectsClient, names: Iterable[str]) -> None:
+	"""Serve the configured, selected catalog through the existing MCP SDK adapter."""
+	from hidden_moves_mcp import MCPAdapter, serve_stdio
+
+	catalog = build_catalog(client, names)
+	await serve_stdio(MCPAdapter(catalog).server("github-projects"))
+
+
+def main() -> None:
+	parser = argparse.ArgumentParser(description="Serve explicitly selected read-only GitHub Projects operations over local MCP stdio.")
+	parser.add_argument("--move", action="append", required=True, help="Qualified read capability; repeat to select multiple operations.")
+	parser.add_argument("--timeout", type=float, default=10.0, help="Finite GitHub socket timeout in seconds.")
+	args = parser.parse_args()
+	try:
+		from hidden_moves_mcp import MCPAdapter, serve_stdio
+
+		from hidden_moves import MoveError
+
+		client = ProjectsClient(resolve_gh_token, timeout=args.timeout)
+		catalog = build_catalog(client, args.move)
+		server = MCPAdapter(catalog).server("github-projects")
+	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/integration.py

@@ -0,0 +1,43 @@
+"""Optional target-bound definitions; the factory never resolves an account."""
+
+from hidden_moves import MoveAnnotations, MoveSpec
+
+from .client import ProjectsClient
+from .models import FieldPage, ItemPage, OwnerKind, Project, ProjectPage
+
+READ_CAPABILITIES = (
+	"github.projects.list", "github.projects.get", "github.projects.fields", "github.projects.items",
+)
+
+
+def list_projects(client: ProjectsClient, owner: str, owner_kind: OwnerKind, cursor: str | None = None, page_size: int = 50) -> ProjectPage:
+	"""Read one bounded Project page for an explicit user or organization owner."""
+	return client.list(owner, owner_kind, cursor=cursor, page_size=page_size)
+
+
+def get_project(client: ProjectsClient, owner: str, owner_kind: OwnerKind, number: int) -> Project:
+	"""Read one Project by owner identity and Project number."""
+	return client.get(owner, owner_kind, number)
+
+
+def project_fields(client: ProjectsClient, project_id: str, cursor: str | None = None, page_size: int = 50) -> FieldPage:
+	"""Read one field-definition page with select options and iteration metadata."""
+	return client.fields(project_id, cursor=cursor, page_size=page_size)
+
+
+def project_items(client: ProjectsClient, project_id: str, cursor: str | None = None, page_size: int = 50, field_page_size: int = 50) -> ItemPage:
+	"""Read one item page with nested completeness diagnostics and cursor state."""
+	return client.items(project_id, cursor=cursor, page_size=page_size, field_page_size=field_page_size)
+
+
+def provide_moves() -> tuple[MoveSpec, ...]:
+	"""Advertise read operations around an application-configured ProjectsClient."""
+	annotations = MoveAnnotations(read_only=True, destructive=False, idempotent=True, external=True)
+	return tuple(
+		MoveSpec(name=name, namespace="github.projects", func=operation,
+			bind_target=True, target_types=(ProjectsClient,), annotations=annotations)
+		for name, operation in (
+			("list", list_projects), ("get", get_project),
+			("fields", project_fields), ("items", project_items),
+		)
+	)