github

type AddPRCommentRequest ¶

type AddPRCommentRequest struct {
	Owner string
	Repo  string
	Ref   string
	Body  string
}

AddPRCommentRequest is the typed payload for Interface.AddPRComment. Owner / Repo follow the same optional-inference semantics. Ref accepts a PR number or branch name, mirroring ReadPRRequest. Body is the Markdown source — required, non-empty.

type AddPRCommentResult ¶

type AddPRCommentResult struct {
	URL string
	ID  int64
}

AddPRCommentResult is the typed envelope AddPRComment returns on success. URL is the comment's permalink — callers surface it so the user can jump to the posted comment on GitHub. ID is the comment's numeric ID, useful for future edit/delete flows (out of scope for v0.5.0 but exposed now to avoid a breaking change later).

type CacheStats ¶

type CacheStats struct {
	PRs        int
	PRDiffs    int
	Checks     int
	Issues     int
	IssueLists int
}

Stats reports per-method cache occupancy. Useful for debugging and for the eventual doctor probe — we want to see whether the cache is actually hot during a session.

type CachingClient ¶

type CachingClient struct {
	Inner Interface
	// contains filtered or unexported fields
}

CachingClient is a memoizing wrapper around any Interface. Reads are cached for the lifetime of the wrapper (which the runtime holds for the session). Writes pass through and invalidate matching read entries so the next read sees fresh state.

Cache shape is deliberately simple: per-method maps keyed by request fingerprints. No TTL — the runtime tears the wrapper down at session end, which is the only invalidation event the roadmap commits to.

Thread-safe via a single mutex. Sessions can have parallel tool calls in flight (the agent runs read tools concurrently when they're parallel-safe), so locking matters. The mutex is held only across map mutation, not across the Inner call — a cache miss releases the lock, makes the call, then re-acquires to store. Two concurrent misses on the same key make two calls; that's the cost of not holding the lock across the network. The double-fetch is rare in practice (the agent dispatches reads once per turn) and avoiding it would require per-key singleflight, which is more machinery than the current signal warrants.

func NewCachingClient(inner Interface) *CachingClient

func (c *CachingClient) AddPRComment(ctx context.Context, req AddPRCommentRequest) (AddPRCommentResult, error)

func (c *CachingClient) CreateIssue(ctx context.Context, req CreateIssueRequest) (CreateIssueResult, error)

func (c *CachingClient) CreatePR(ctx context.Context, req CreatePRRequest) (CreatePRResult, error)

func (c *CachingClient) ListFailedWorkflowJobLogTails(ctx context.Context, req FailedWorkflowLogsRequest) (FailedWorkflowLogsResult, error)

func (c *CachingClient) ListOpenIssues(ctx context.Context, req ListIssuesRequest) ([]IssueSummary, error)

func (c *CachingClient) ListPRChecks(ctx context.Context, req ReadPRRequest) ([]CheckRun, error)

func (c *CachingClient) RateLimit() RateLimitSnapshot

func (c *CachingClient) ReadIssue(ctx context.Context, req ReadIssueRequest) (IssueDetails, error)

func (c *CachingClient) ReadPR(ctx context.Context, req ReadPRRequest) (PRDetails, error)

func (c *CachingClient) ReadPRDiff(ctx context.Context, req ReadPRRequest) (string, error)

func (c *CachingClient) RerunFailedPRChecks(ctx context.Context, req ReadPRRequest) (RerunFailedPRChecksResult, error)

func (c *CachingClient) Reset()

func (c *CachingClient) Stats() CacheStats

func (c *CachingClient) UpdatePR(ctx context.Context, req UpdatePRRequest) (UpdatePRResult, error)

type CheckRun ¶

type CheckRun struct {
	Name        string
	State       string
	Conclusion  string
	StartedAt   time.Time
	CompletedAt time.Time
}

CheckRun is one row from ListPRChecks. Name is the check's label (e.g. "build", "test", "lint"). State is the lifecycle state ("QUEUED" / "IN_PROGRESS" / "COMPLETED"). Conclusion is the outcome once State is COMPLETED ("SUCCESS" / "FAILURE" / "CANCELLED" / "NEUTRAL" / "SKIPPED" / "TIMED_OUT" / "ACTION_REQUIRED"); empty before completion.

Times are zero-valued when the check hasn't started or completed yet — callers must IsZero-check before formatting.

type CreateIssueRequest ¶

type CreateIssueRequest struct {
	Owner     string   // repo owner (optional; inferred from cwd when empty)
	Repo      string   // repo name  (optional; inferred from cwd when empty)
	Title     string   // issue title (required)
	Body      string   // issue body / description (optional)
	Labels    []string // labels to apply (optional)
	Assignees []string // assignees to assign (optional)
}

CreateIssueRequest is the typed payload for Interface.CreateIssue.

Owner and Repo are optional: when both are empty, the underlying implementation infers them from the working directory's git remote (the gh CLI's default behavior). Setting them explicitly is what the future cloud bot will need (it can't rely on cwd) and the local CLI can always use it for cross-repo cases.

type CreateIssueResult ¶

type CreateIssueResult struct {
	URL    string
	Number int
}

CreateIssueResult is the typed envelope CreateIssue returns on success. Number is the GitHub issue number. URL is the canonical https://github.com/... issue URL.

type CreatePRRequest ¶

type CreatePRRequest struct {
	Owner string // repo owner (optional; inferred from cwd when empty)
	Repo  string // repo name  (optional; inferred from cwd when empty)
	Base  string // base branch the PR merges into (required)
	Head  string // head branch / SHA the PR ships (optional; "" = current branch)
	Title string // PR title (required)
	Body  string // PR body / description (required)
	Draft bool   // open as draft (default: open as ready-for-review)
}

CreatePRRequest is the typed payload for Interface.CreatePR.

Owner and Repo are optional: when both are empty, the underlying implementation infers them from the working directory's git remote (the gh CLI's default behavior). Setting them explicitly is what the future cloud bot will need (it can't rely on cwd) and the local CLI can always use it for cross-repo cases.

type CreatePRResult ¶

type CreatePRResult struct {
	URL    string
	Number int
}

CreatePRResult is the typed envelope CreatePR returns on success. Number is the GitHub PR number (best-effort: shellout impl returns 0 when it can't parse one; typed v0.5.0 impl will always populate it). URL is the canonical https://github.com/... PR URL.

type FailedWorkflowJobLog ¶ added in v0.4.0

type FailedWorkflowJobLog struct {
	WorkflowRunID int64
	WorkflowName  string
	WorkflowURL   string
	JobID         int64
	JobName       string
	JobURL        string
	Conclusion    string
	LogTail       []string
	LogError      string
}

FailedWorkflowJobLog is one failed GitHub Actions job plus the capped tail of its log. WorkflowName and JobName are separate so a renderer can group or display either without parsing check labels.

type FailedWorkflowLogsRequest ¶ added in v0.4.0

type FailedWorkflowLogsRequest struct {
	Owner     string // repo owner (optional; inferred from cwd when empty)
	Repo      string // repo name  (optional; inferred from cwd when empty)
	HeadSHA   string // commit SHA whose workflow runs should be inspected (required)
	TailLines int    // max lines per failed job; <=0 uses implementation default
	MaxRuns   int    // max workflow runs to inspect; <=0 uses implementation default
}

FailedWorkflowLogsRequest selects the failed GitHub Actions logs to fetch for a single PR head SHA. Owner / Repo follow the same optional inference semantics as the other GitHub request types.

type FailedWorkflowLogsResult ¶ added in v0.4.0

type FailedWorkflowLogsResult struct {
	HeadSHA string
	Jobs    []FailedWorkflowJobLog
}

FailedWorkflowLogsResult is the typed envelope for failed job log tails. Missing logs are reported per job via LogError rather than as a hard failure so callers still see which checks failed.

type Interface ¶

type Interface interface {
	// CreatePR opens a pull request. Returns ErrGitHubUnavailable when
	// the local environment can't make the call (no gh, no auth)
	// so callers can fall back gracefully rather than reporting a
	// generic execution failure.
	CreatePR(ctx context.Context, req CreatePRRequest) (CreatePRResult, error)

	// ReadPR fetches typed metadata about a single pull request.
	// Ref accepts either a PR number ("17") or a branch name; gh
	// itself accepts both, and the v0.5.0 typed client will mirror
	// that ergonomics. Returns ErrPRNotFound when nothing matches.
	ReadPR(ctx context.Context, req ReadPRRequest) (PRDetails, error)

	// ReadPRDiff fetches the unified diff for a pull request as a
	// single string. Capped by the caller (tool wrapper trims for
	// model consumption); the Interface itself returns the full diff.
	ReadPRDiff(ctx context.Context, req ReadPRRequest) (string, error)

	// ListPRChecks returns the typed status of every check run on a
	// PR. Empty slice is a valid result (PR with no CI). The
	// `/git-review-pr` flow surfaces failing checks at the top of
	// the review, which is why typed access matters here.
	ListPRChecks(ctx context.Context, req ReadPRRequest) ([]CheckRun, error)

	// ListFailedWorkflowJobLogTails returns capped log tails for failed
	// GitHub Actions jobs on a specific head SHA. This is the typed
	// read-only counterpart to `gh run view --log-failed | tail`, used
	// only after checks report a failure.
	ListFailedWorkflowJobLogTails(ctx context.Context, req FailedWorkflowLogsRequest) (FailedWorkflowLogsResult, error)

	// RerunFailedPRChecks re-runs failed GitHub Actions jobs for every
	// failed workflow run attached to a PR's current head SHA. It uses
	// GitHub's failed-jobs endpoint rather than rerunning successful jobs.
	RerunFailedPRChecks(ctx context.Context, req ReadPRRequest) (RerunFailedPRChecksResult, error)

	// UpdatePR rewrites an existing PR's title and body. Used by
	// /git-update-pr after follow-up commits make the original
	// description stale. Other PR-level edits (labels, base,
	// reviewers, draft toggle) are intentionally out of scope —
	// the v0.5.0 spec defers them until a concrete workflow asks.
	// Returns ErrPRNotFound when nothing matches the ref;
	// ErrGitHubUnavailable when the local environment can't make the
	// call.
	UpdatePR(ctx context.Context, req UpdatePRRequest) (UpdatePRResult, error)

	// ReadIssue fetches typed metadata about a single issue —
	// title, body, state, labels, assignees, and the most-recent
	// comments. Powers /git-implement-issue's first step. Returns
	// ErrIssueNotFound when the issue doesn't exist.
	ReadIssue(ctx context.Context, req ReadIssueRequest) (IssueDetails, error)

	// ListOpenIssues returns lightweight summaries of open issues
	// matching the supplied filters. Empty filters return all open
	// issues (paginated by GitHub's defaults — we don't fetch all
	// pages here; callers that need pagination ask for it).
	// Surfaces issues for /git-implement-issue tab-completion and
	// for future planning surfaces.
	ListOpenIssues(ctx context.Context, req ListIssuesRequest) ([]IssueSummary, error)

	// AddPRComment posts a top-level conversation comment on a PR.
	// Approval-gated by the tool layer (see GHPRAddCommentTool).
	// Used to cross-link related issues, request reviewers via
	// @-mention, or post structured follow-ups after a /git-review-pr
	// run. Not for inline review comments (different endpoint;
	// different scope).
	AddPRComment(ctx context.Context, req AddPRCommentRequest) (AddPRCommentResult, error)

	// CreateIssue opens a new issue. Returns ErrGitHubUnavailable when
	// the local environment can't make the call (no gh, no auth)
	// so callers can fall back gracefully rather than reporting a
	// generic execution failure.
	CreateIssue(ctx context.Context, req CreateIssueRequest) (CreateIssueResult, error)

	// RateLimit returns the most recent rate-limit snapshot the
	// implementation has observed. Snapshot.IsSet() is false when
	// no API call has populated the tracker yet. Used by the doctor
	// probe and by mutation tools to surface low-budget warnings.
	// Implementations that don't track rate state (test doubles)
	// may return a zero-valued snapshot.
	RateLimit() RateLimitSnapshot
}

Interface is the typed surface yottacode uses to talk to GitHub. Kept minimal: only the methods at least one shipped caller needs. Growing it as new commands need new endpoints (rather than front-loading the entire `go-github` surface) keeps the test burden bounded — each method we add ships with at least one caller that exercises it.

type IssueComment ¶

type IssueComment struct {
	Author  string
	Body    string
	Created time.Time
}

IssueComment is one row from IssueDetails.Comments. Body is the raw Markdown source the commenter wrote. Author is the login. Created is the UTC creation timestamp.

type IssueDetails ¶

type IssueDetails struct {
	Number    int
	Title     string
	Body      string
	State     string // "OPEN" | "CLOSED"
	Author    string
	URL       string
	Labels    []string
	Assignees []string
	Comments  []IssueComment
}

IssueDetails is the typed envelope ReadIssue returns. Field shape mirrors PRDetails where it overlaps (Number, Title, Body, State, Author, URL, Labels) so the model brief and tool wrappers can render issues and PRs with shared template code.

Assignees is the login list (not display names) — matches the Author convention. Comments is most-recent-first, capped per MaxComments. Empty Comments doesn't mean "no comments existed" when MaxComments was negative; check the request to disambiguate.

type IssueSummary ¶

type IssueSummary struct {
	Number    int
	Title     string
	Author    string
	URL       string
	Labels    []string
	Assignees []string
}

IssueSummary is the lightweight envelope ListOpenIssues returns. Subset of IssueDetails — enough for a picker / completion list. Callers that need bodies + comments follow up with ReadIssue.

type ListIssuesRequest ¶

type ListIssuesRequest struct {
	Owner     string
	Repo      string
	Labels    []string
	Assignee  string
	Milestone string
}

ListIssuesRequest is the typed payload for Interface.ListOpenIssues. Owner / Repo follow the same optional-inference semantics as the other request types. Filters are AND-ed — e.g., Labels=["bug"] and Assignee="octocat" returns only issues with both.

Empty Labels means "no label filter" (any label OK, no label OK). Empty Assignee / Milestone means "no filter on that axis". State is fixed to "open" by the method semantics — callers that need closed issues use ReadIssue with a specific number.

type PRDetails ¶

type PRDetails struct {
	Number    int
	Title     string
	Body      string
	State     string // "OPEN" | "CLOSED" | "MERGED"
	Draft     bool
	BaseRef   string
	HeadRef   string
	HeadSHA   string
	Mergeable string // "MERGEABLE" | "CONFLICTING" | "UNKNOWN"
	Author    string // login, not display name
	URL       string
	Labels    []string
}

PRDetails is the typed envelope ReadPR returns. Fields mirror the `gh pr view --json` schema yottacode needs today; growing it as callers ask for more fields keeps the contract surface pinned to actual use rather than front-loading the entire API.

State and Mergeable are uppercase strings matching the GitHub API's enum literals (OPEN / CLOSED / MERGED, MERGEABLE / CONFLICTING / UNKNOWN) so downstream pattern-matching against the wire format stays unambiguous.

type RateLimitSnapshot ¶

type RateLimitSnapshot struct {
	Limit       int
	Remaining   int
	Reset       time.Time
	LastUpdated time.Time
}

RateLimitSnapshot is the typed envelope for GitHub's per-hour REST rate-limit budget. Returned by TypedClient.RateLimit after at least one API call has populated the tracker. Limit is the hourly cap (5000 for authenticated users); Remaining is what's left; Reset is when the budget refills.

Zero-value snapshot (LastUpdated.IsZero) means "no API call has populated this tracker yet" — callers should not infer anything from Remaining=0 unless LastUpdated is non-zero.

func (s RateLimitSnapshot) IsLow() bool

func (s RateLimitSnapshot) IsSet() bool

func (s RateLimitSnapshot) WarningText() string

type ReadIssueRequest ¶

type ReadIssueRequest struct {
	Owner       string
	Repo        string
	Number      int
	MaxComments int
}

ReadIssueRequest is the typed payload for Interface.ReadIssue. Owner / Repo follow the same optional-inference semantics as the PR request types. Number is required (issues don't have a branch fallback the way PRs do).

MaxComments caps the comment fetch — issues can be lengthy threads, and the model rarely needs every comment for context. Zero means "use the implementation's default" (currently 20 most-recent comments). Negative means "skip comments entirely".

type ReadPRRequest ¶

type ReadPRRequest struct {
	Owner string
	Repo  string
	Ref   string // PR number or branch name; "" = current branch
}

ReadPRRequest is the typed payload for the read trio (ReadPR, ReadPRDiff, ListPRChecks). Owner / Repo follow the same optional-inference semantics as CreatePRRequest.

Ref is the PR identifier — either a number ("17") or a branch name ("feature/x"). Empty Ref tells the implementation to use the cwd's current branch, mirroring `gh pr view` with no arg.

type RerunFailedPRChecksResult ¶ added in v0.4.0

type RerunFailedPRChecksResult struct {
	RunIDs []int64
	Count  int
}

RerunFailedPRChecksResult reports which workflow runs were asked to rerun failed jobs. The endpoint is asynchronous; success means GitHub accepted the rerun request, not that CI has passed.

type TokenFile ¶

type TokenFile struct {
	Token   string `json:"token"`
	User    string `json:"user,omitempty"`
	Created string `json:"created,omitempty"` // RFC3339
}

TokenFile is the on-disk shape WriteTokenFile produces and tokenFromFile reads. Token is the only field the resolver uses; User and Created are metadata for `yottacode doctor` and future audit/UX surfaces.

type TokenResolver ¶

type TokenResolver struct {
	// contains filtered or unexported fields
}

TokenResolver caches the resolved token for a process. Safe for concurrent use — the underlying sync.Once + struct fields are immutable after the first successful resolve.

func NewTokenResolver() *TokenResolver

func (r *TokenResolver) Resolve(ctx context.Context) (token, source string, err error)

type TypedClient ¶

type TypedClient struct {
	Cwd      string
	Resolver *TokenResolver

	// HTTPClient is an optional injection point for tests. When
	// nil, the typed client uses go-github's default
	// http.Client. Tests provide a transport that returns
	// canned responses.
	HTTPClient *http.Client
	// contains filtered or unexported fields
}

TypedClient is the Interface implementation backed by the go-github typed REST client. Replaces the gh-CLI ShellOut implementation we shipped first.

Three reliability wins over ShellOut:

1. **No gh CLI dependency.** The auth resolver still opportunistically piggybacks on `gh auth token` if it's available (one-shot at first use), but API calls go direct over HTTPS. Users can `apt remove gh` and yottacode still works if $GITHUB_TOKEN is set or the `~/.yottacode/github.json` file exists.
2. **No GraphQL field deprecation traps.** ShellOut hit `repository.pullRequest.projectCards` deprecation through gh's internal query. The REST endpoints we use here don't reference projectCards.
3. **Faster per call.** No subprocess spawn; in-process HTTP.

Cwd is used for inferring (owner, repo) when the caller's request doesn't supply them explicitly. Resolver and the underlying *gogithub.Client are lazy-initialized via sync.Once so the first call pays the auth cost and subsequent calls reuse the client.

func NewTypedClient(cwd string) *TypedClient

func (c *TypedClient) AddPRComment(ctx context.Context, req AddPRCommentRequest) (AddPRCommentResult, error)

func (c *TypedClient) AuthedUserLogin(ctx context.Context) (string, error)

func (c *TypedClient) CreateIssue(ctx context.Context, req CreateIssueRequest) (CreateIssueResult, error)

func (c *TypedClient) CreatePR(ctx context.Context, req CreatePRRequest) (CreatePRResult, error)

func (c *TypedClient) ListFailedWorkflowJobLogTails(ctx context.Context, req FailedWorkflowLogsRequest) (FailedWorkflowLogsResult, error)

func (c *TypedClient) ListOpenIssues(ctx context.Context, req ListIssuesRequest) ([]IssueSummary, error)

func (c *TypedClient) ListPRChecks(ctx context.Context, req ReadPRRequest) ([]CheckRun, error)

func (c *TypedClient) RateLimit() RateLimitSnapshot

func (c *TypedClient) ReadIssue(ctx context.Context, req ReadIssueRequest) (IssueDetails, error)

func (c *TypedClient) ReadPR(ctx context.Context, req ReadPRRequest) (PRDetails, error)

func (c *TypedClient) ReadPRDiff(ctx context.Context, req ReadPRRequest) (string, error)

func (c *TypedClient) RerunFailedPRChecks(ctx context.Context, req ReadPRRequest) (RerunFailedPRChecksResult, error)

func (c *TypedClient) UpdatePR(ctx context.Context, req UpdatePRRequest) (UpdatePRResult, error)

type UpdatePRRequest ¶

type UpdatePRRequest struct {
	Owner string
	Repo  string
	Ref   string
	Title string
	Body  string
}

UpdatePRRequest is the typed payload for Interface.UpdatePR. Owner / Repo follow the same optional-inference semantics as the other request types. Ref accepts a PR number or branch name. Both Title and Body must be non-empty — empty Body would clobber the existing description, which is almost never what the caller wants and is easy to do by accident.

type UpdatePRResult ¶

type UpdatePRResult struct {
	URL    string
	Number int
}

UpdatePRResult is the typed envelope UpdatePR returns on success. URL is the canonical PR URL (unchanged by an edit), surfaced so callers can re-link to the updated PR.

type VerifyResult ¶

type VerifyResult struct {
	Login string
}

VerifyResult is the typed outcome of a token check. Login is the authenticated user's GitHub handle (so the setup wizard can display "Authenticated as @octocat" for sanity check). Returned only on success — failure modes return an error.

func VerifyToken(ctx context.Context, token string) (VerifyResult, error)