Module github_read 

Structured, cached issue:// and pr:// read engine.

The read-command integration owns transport routing and protocol response adaptation. This module owns everything specific to GitHub resources: strict URL parsing, structured gh fetches, normalization, canonical rendering, durable-cache coordination, deferred network work, and vision-gated images.

Structs

DownloadedGithubImage

A downloader result whose final URL is retained for redirect validation.

GhCliFetcher

Structured gh issue view / gh pr view fetcher.

GhCommandOutput

A subprocess result for the gh command seam.

GithubComment

GithubCommentSelector

Ordinals selected by a /comments/<sel> discussion drill-down.

GithubDocument

Structured GitHub data consumed by the canonical Rust renderer.

GithubFetchRequest

Request context passed to a structured GitHub fetcher.

GithubImageAttachment

One complete, validated image attachment. Text rendering retains the source URL; this is out-of-band data for a caller that explicitly supports vision.

GithubPullRequestFile

GithubReaction

GithubReadCompletion

A completed GitHub read ready for the transport-specific response adapter.

GithubReadDeferred

Handle for a fetch or attachment task that is running away from the request loop. Poll it from PendingResponse; never wait on it in standalone input handling.

GithubReadEngine

Coordinates live GitHub fetches, durable fallback copies, single-flight work, rendering, and deferred attachments for both issue and PR reads.

GithubReadRequest

Request context that the read integration supplies before entering a deferred fetch. An absent capability is intentionally different from an inferred one: only Some(true) permits image downloads.

GithubResource

A validated issue:// or pr:// resource.

GithubReview

GithubReviewCommentSection

One review’s inline-comment section. Each section is capped independently, so an active review cannot crowd comments out of a different review.

InvalidGithubResource

A typed error produced before a GitHub resource can enter the fetch path.

NormalizeError

A structured-response error. The fetch layer maps this into a typed, redacted user-facing fetch failure.

ReqwestGithubImageDownloader

Production GitHub-image downloader. Redirect following is manual so every target receives the same allowlist check as the original URL.

SqliteGithubReadCacheStore

aft.db implementation of the GitHub read cache seam.

SystemGhCommandRunner

Production runner that executes the bare gh command in the caller’s working directory so the CLI owns short-form repository resolution.

SystemGithubReadClock

Production wall clock for cache timestamps.

Enums

GhCommandError

Error running gh before it produced a process result.

GithubDocumentKind

Resource-kind mirror included in structured fixtures and normalized data.

GithubReadError

The typed failures returned by the GitHub read engine.

GithubReadFreshness

Origin of the text that satisfied a request.

GithubReadSelector

Selector applied only after the complete canonical document is rendered.

GithubReadStart

The initial outcome for a GitHub read. Every read is deferred because it performs a live GitHub fetch before considering any cached fallback.

GithubResourceKind

One of the two GitHub resource kinds supported by the read scheme.

Constants

MAX_GITHUB_IMAGE_ATTACHMENTS

At most this many GitHub-hosted images become attachments for one read. Keeping the count fixed prevents a long issue thread from creating an unbounded transport payload.

MAX_GITHUB_IMAGE_ATTACHMENT_BYTES

Attachments for one read may contain at most this many downloaded bytes in total. A candidate that exceeds the remaining budget is dropped whole, so callers never receive a partial image.

MAX_RENDERED_COMMENTS_PER_SECTION

The maximum number of newest comments rendered for an issue or one pull request review-comment section. Older comments remain available on GitHub and are disclosed in the canonical document instead of silently dropped.

Traits

GhCommandRunner

Injectable gh runner. Fixture runners can assert the exact command and request working directory without requiring a real GitHub installation.

GithubFetcher

Fetches structured GitHub data. Implementations never return CLI display text; the engine only accepts a normalized document from this interface.

GithubImageDownloader

Synchronous downloader used inside a deferred worker. Tests can replace it with a deterministic fixture downloader that records URLs and byte budgets.

GithubReadCacheStore

A cache persistence seam. The production implementation stores canonical text in AFT’s existing aft.db; tests can use an in-memory fixture store.

GithubReadClock

Clock seam used to make freshness boundaries deterministic in tests.

Functions

apply_selector

Apply selection to the completed canonical render, never to raw GitHub data.

discover_github_image_urls

Discover eligible HTTPS GitHub image candidates in textual document order. Repeated URLs remain repeated candidates: their positions in the canonical document determine which attachment claims a count slot first.

download_github_image_attachments

Download complete attachment candidates without changing canonical text. This function is capability-agnostic so tests can call it directly; callers with a missing or false vision capability must not invoke it.

gh_pr_review_comments_args

Build the structured GraphQL fetch for inline PR review comments. The first pr view --json call resolves the repository; this second JSON call fills comment sections that gh pr view does not expose as a display field.

gh_view_args

Build the exact structured-view invocation. Short forms intentionally omit -R; explicit forms include it and are otherwise identical.

is_allowed_github_image_url

The only hosts allowed to become vision attachments. github.com is limited to /user-attachments/; an arbitrary GitHub page is not an image source and must not turn this feature into a generic web fetcher.

normalize_structured_document

Normalize gh --json or GraphQL JSON into the renderer’s stable model.

parse_resource

Parse only the GitHub resource forms that the read command exposes.

redact_gh_error

Redact ambient credentials while keeping GitHub’s actionable authorization, private-resource, and not-found diagnostics visible to the caller.

render_document

Render the complete, transport-independent GitHub document once in Rust.

sqlite_cache_store

Convenience constructor for the real cache location. The read integration supplies its existing aft.db path; this module never creates a second DB.