wsb_github/

client.rs

//! The GitHub API: REST for repositories, issues, gists and the rest, and
//! GraphQL for Projects boards.

use std::collections::BTreeMap;

use anyhow::{Context, Result};
use serde::{Deserialize, Serialize};

fn github_status_error(action: &str, status: reqwest::StatusCode) -> anyhow::Error {
    anyhow::anyhow!(
        "{} failed with GitHub API status {}",
        action,
        status.as_u16()
    )
}

fn require_success(action: &str, response: reqwest::Response) -> Result<reqwest::Response> {
    let status = response.status();
    if status.is_success() {
        Ok(response)
    } else {
        Err(github_status_error(action, status))
    }
}

/// GitHub REST API client for issues management.
#[derive(Clone)]
pub struct GitHubClient {
    client: reqwest::Client,
    token: String,
    /// Where the API lives.
    ///
    /// `https://api.github.com` everywhere but in tests, which point it at a
    /// server they control. Conditional requests are the whole economics of
    /// mirroring — an unchanged repository must cost a 304 and nothing else —
    /// and a claim like that is worth proving against a server that can
    /// actually answer 304, rather than asserting the header is set and hoping.
    base: String,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct GitHubUser {
    pub login: String,
    pub avatar_url: Option<String>,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct GitHubLabel {
    pub name: String,
    pub color: String,
    pub description: Option<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GitHubIssue {
    pub number: i64,
    pub title: String,
    pub body: Option<String>,
    pub state: String,
    pub user: GitHubUser,
    pub labels: Vec<GitHubLabel>,
    pub comments: i64,
    pub created_at: String,
    pub updated_at: String,
    pub closed_at: Option<String>,
    pub html_url: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GitHubComment {
    pub id: i64,
    pub body: String,
    pub user: GitHubUser,
    pub created_at: String,
    pub updated_at: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GitHubGistFile {
    pub filename: Option<String>,
    #[serde(rename = "type")]
    pub mime_type: Option<String>,
    pub language: Option<String>,
    pub raw_url: Option<String>,
    pub size: Option<u64>,
    pub truncated: Option<bool>,
    pub content: Option<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GitHubGist {
    pub id: String,
    pub description: Option<String>,
    pub public: bool,
    pub html_url: String,
    pub created_at: String,
    pub updated_at: String,
    pub owner: Option<GitHubUser>,
    pub files: BTreeMap<String, GitHubGistFile>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GistFileInput {
    pub content: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CreateGistRequest {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,
    pub public: bool,
    pub files: BTreeMap<String, GistFileInput>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct UpdateGistRequest {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,
    pub files: BTreeMap<String, GistFileInput>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CreateIssueRequest {
    pub title: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub body: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub labels: Option<Vec<String>>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct UpdateIssueRequest {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub title: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub body: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub state: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub labels: Option<Vec<String>>,
}

// ---------------------------------------------------------------------------
// Everything else the workbench mirrors
// ---------------------------------------------------------------------------
//
// Each of these is stored whole, so the fields named here are only the ones
// something QUERIES on — a state to filter by, a time to order by, a name to
// show. Anything a page merely renders comes out of the payload, which is why
// adding a column to a card does not mean changing this file.

/// A pull request. GitHub's issues endpoint returns these too, which is why
/// they are filtered out of the issue list — a pull request is a different
/// thing to a person looking at either list.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GitHubPull {
    pub number: i64,
    pub title: String,
    pub body: Option<String>,
    /// `open` or `closed`. Merged is not a state GitHub reports here — a
    /// merged pull request is closed with `merged_at` set — so a page that
    /// wants to say "merged" reads that.
    pub state: String,
    #[serde(default)]
    pub draft: bool,
    pub user: GitHubUser,
    #[serde(default)]
    pub labels: Vec<GitHubLabel>,
    pub created_at: String,
    pub updated_at: String,
    pub closed_at: Option<String>,
    pub merged_at: Option<String>,
    pub html_url: String,
    pub head: GitHubPullRef,
    pub base: GitHubPullRef,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GitHubPullRef {
    /// The branch name.
    #[serde(rename = "ref")]
    pub branch: String,
    pub sha: String,
}

/// What CI says about one commit.
///
/// Two GitHub mechanisms in one shape: the older commit STATUSES (a context
/// and a state) and the newer CHECK RUNS (a name, a status and a conclusion).
/// A repository can use either or both, and a person wants one answer.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct GitHubChecks {
    /// The commit these are about.
    pub sha: String,
    /// `success` | `failure` | `pending` | `neutral` — the whole commit's
    /// verdict, decided by the rules in [`GitHubChecks::rollup`].
    pub state: String,
    pub runs: Vec<GitHubCheckRun>,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct GitHubCheckRun {
    pub name: String,
    /// `queued` | `in_progress` | `completed` for a check run; for a commit
    /// status, `completed` — it has no lifecycle to report.
    pub status: String,
    /// `success` | `failure` | `cancelled` | `skipped` | `neutral` | …, or
    /// absent while it is still running.
    pub conclusion: Option<String>,
    pub url: Option<String>,
}

impl GitHubChecks {
    /// One verdict for a commit, from every run reported about it.
    ///
    /// The order is what a person cares about, worst first: anything failing
    /// makes the commit failing, anything still running makes it pending, and
    /// only then is it a success. A rollup that let a green check hide a red
    /// one would be worse than showing nothing.
    pub fn rollup(runs: &[GitHubCheckRun]) -> String {
        if runs.is_empty() {
            return "neutral".to_string();
        }
        let failed = runs.iter().any(|run| {
            matches!(
                run.conclusion.as_deref(),
                Some("failure") | Some("timed_out") | Some("action_required") | Some("startup_failure")
            )
        });
        if failed {
            return "failure".to_string();
        }
        let running = runs
            .iter()
            .any(|run| run.status != "completed" || run.conclusion.is_none());
        if running {
            return "pending".to_string();
        }
        let succeeded = runs
            .iter()
            .any(|run| run.conclusion.as_deref() == Some("success"));
        if succeeded {
            "success".to_string()
        } else {
            // Everything skipped, cancelled or neutral: nothing failed and
            // nothing passed, and calling that a success would be a lie a
            // release gate could act on.
            "neutral".to_string()
        }
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GitHubRelease {
    pub id: i64,
    pub tag_name: String,
    pub name: Option<String>,
    pub body: Option<String>,
    pub draft: bool,
    pub prerelease: bool,
    pub created_at: String,
    pub published_at: Option<String>,
    pub html_url: String,
    #[serde(default)]
    pub assets: Vec<GitHubReleaseAsset>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GitHubReleaseAsset {
    pub name: String,
    pub size: i64,
    pub download_count: i64,
    pub browser_download_url: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GitHubTag {
    pub name: String,
    pub commit: GitHubTagCommit,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GitHubTagCommit {
    pub sha: String,
}

/// What GitHub says a repository IS.
///
/// `private` is the one the explorer draws: a lock on a row is the difference
/// between "this is ours" and "this is the world's", and it is the sort of
/// thing somebody should not have to open a browser to check before pasting.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GitHubRepository {
    pub full_name: String,
    pub private: bool,
    pub archived: bool,
    pub fork: bool,
    pub default_branch: String,
    pub description: Option<String>,
    pub html_url: String,
    #[serde(default)]
    pub topics: Vec<String>,
    pub stargazers_count: i64,
    pub watchers_count: i64,
    pub forks_count: i64,
    pub open_issues_count: i64,
    pub pushed_at: Option<String>,
    pub updated_at: Option<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GitHubMilestone {
    pub number: i64,
    pub title: String,
    pub description: Option<String>,
    pub state: String,
    pub open_issues: i64,
    pub closed_issues: i64,
    pub due_on: Option<String>,
    pub updated_at: String,
    pub html_url: String,
}

/// One thing GitHub thinks needs this person.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GitHubNotification {
    pub id: String,
    pub unread: bool,
    /// `mention` | `review_requested` | `assign` | `subscribed` | …
    pub reason: String,
    pub updated_at: String,
    pub subject: GitHubNotificationSubject,
    pub repository: GitHubNotificationRepo,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GitHubNotificationSubject {
    pub title: String,
    /// `Issue` | `PullRequest` | `Release` | `Discussion` | …
    #[serde(rename = "type")]
    pub kind: String,
    /// The API url of the thing. Absent for some subjects (a discussion, a
    /// security alert), which is why a page cannot assume it can link.
    pub url: Option<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GitHubNotificationRepo {
    pub full_name: String,
    pub private: bool,
}

/// How much of the API budget is left.
///
/// Mirrored like everything else, because "why is nothing refreshing" is a
/// question with an answer, and the answer is usually this.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct GitHubRateLimit {
    pub limit: i64,
    pub remaining: i64,
    /// Unix seconds. When the budget comes back.
    pub reset: i64,
    pub used: i64,
}

/// How much the world looked at a repository.
///
/// Needs push access, so a repository somebody merely reads answers 403. That
/// is recorded as this scope's error and nothing else — traffic is the one
/// thing here whose absence means nothing at all.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct GitHubTraffic {
    pub views: i64,
    pub unique_views: i64,
    pub clones: i64,
    pub unique_clones: i64,
    /// Per day, newest last, as GitHub reports it.
    #[serde(default)]
    pub view_days: Vec<GitHubTrafficDay>,
    #[serde(default)]
    pub clone_days: Vec<GitHubTrafficDay>,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct GitHubTrafficDay {
    pub timestamp: String,
    pub count: i64,
    pub uniques: i64,
}

/// GitHub's own shape for one traffic series, which this folds into
/// [`GitHubTraffic`].
#[derive(Debug, Clone, Deserialize)]
pub struct TrafficSeries {
    pub count: i64,
    pub uniques: i64,
    #[serde(default)]
    pub views: Vec<GitHubTrafficDay>,
    #[serde(default)]
    pub clones: Vec<GitHubTrafficDay>,
}

/// A repository ruleset, as much of it as anything here reads.
#[derive(Debug, Clone, Deserialize)]
pub struct RepositoryRuleset {
    pub id: i64,
    pub name: String,
    #[serde(default)]
    pub target: Option<String>,
    #[serde(default)]
    pub enforcement: Option<String>,
}

#[derive(Debug, Clone, Serialize)]
pub struct CreateCommentRequest {
    pub body: String,
}

impl GitHubClient {
    pub fn new(token: &str) -> Self {
        Self::against("https://api.github.com", token)
    }

    /// A client for an API at `base`. Tests use it; nothing else does.
    pub fn against(base: &str, token: &str) -> Self {
        let client = reqwest::Client::builder()
            .user_agent(concat!("wsb-github/", env!("CARGO_PKG_VERSION")))
            .no_proxy()
            .build()
            .expect("failed to build reqwest client");

        Self {
            client,
            token: token.to_string(),
            base: base.trim_end_matches('/').to_string(),
        }
    }

    /// One API URL.
    fn url(&self, path: &str) -> String {
        format!("{}{}", self.base, path)
    }

    /// Validate the token by fetching the authenticated user.
    pub async fn validate_token(&self) -> Result<String> {
        let response = require_success(
            "GitHub token validation",
            self.client
                .get(self.url("/user"))
                .bearer_auth(&self.token)
                .send()
                .await
                .context("GitHub API request failed")?,
        )?;
        let resp: GitHubUser = response
            .json()
            .await
            .context("failed to parse GitHub user response")?;
        Ok(resp.login)
    }

    /// Every repository ruleset, by name and id.
    ///
    /// Read before writing so applying protection twice is applying it once:
    /// GitHub's create endpoint does not upsert, and a second run would leave
    /// two rulesets with the same name saying the same thing.
    pub async fn list_rulesets(&self, owner: &str, repo: &str) -> Result<Vec<RepositoryRuleset>> {
        let response = require_success(
            "listing rulesets",
            self.client
                .get(self.url(&format!("/repos/{owner}/{repo}/rulesets")))
                .bearer_auth(&self.token)
                .send()
                .await
                .context("GitHub API request failed")?,
        )?;
        response
            .json()
            .await
            .context("failed to parse the ruleset list")
    }

    /// Create a ruleset, or replace the one that already has this name.
    ///
    /// The body is passed through rather than modelled: GitHub's rule shapes
    /// are a tagged union that grows, and a partial model here would silently
    /// drop the parts of a rule it did not know about.
    pub async fn put_ruleset(
        &self,
        owner: &str,
        repo: &str,
        name: &str,
        body: &serde_json::Value,
    ) -> Result<RepositoryRuleset> {
        let existing = self
            .list_rulesets(owner, repo)
            .await?
            .into_iter()
            .find(|ruleset| ruleset.name == name);

        let response = match &existing {
            Some(ruleset) => {
                self.client
                    .put(self.url(&format!(
                        "/repos/{owner}/{repo}/rulesets/{}",
                        ruleset.id
                    )))
                    .bearer_auth(&self.token)
                    .json(body)
                    .send()
                    .await
            }
            None => {
                self.client
                    .post(self.url(&format!("/repos/{owner}/{repo}/rulesets")))
                    .bearer_auth(&self.token)
                    .json(body)
                    .send()
                    .await
            }
        }
        .context("GitHub API request failed")?;

        let response = require_success(
            if existing.is_some() {
                "updating a ruleset"
            } else {
                "creating a ruleset"
            },
            response,
        )?;
        response
            .json()
            .await
            .context("failed to parse the ruleset GitHub wrote")
    }
}

/// What a conditional request answered.
///
/// `Unchanged` is not an empty answer and must never be stored as one: it says
/// the copy already held is still correct. Collapsing the two is how a mirror
/// empties itself every time nothing has happened — which, for a repository
/// nobody has touched today, is every single sync.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Fetched<T> {
    /// GitHub answered with data, and the ETag to send with the next request.
    Fresh { value: T, etag: Option<String> },
    /// GitHub answered 304: what is held is current. Costs no rate limit,
    /// which is what makes syncing forty repositories every few minutes
    /// affordable.
    Unchanged,
}

impl<T> Fetched<T> {
    pub fn value(self) -> Option<T> {
        match self {
            Self::Fresh { value, .. } => Some(value),
            Self::Unchanged => None,
        }
    }
}

/// How this side asks for "only what I do not already have".
#[derive(Debug, Clone, Default)]
pub struct Conditions {
    /// The ETag of the last answer, replayed as `If-None-Match`.
    pub etag: Option<String>,
    /// Only things updated at or after this time — GitHub's `since`.
    pub since: Option<String>,
}

impl GitHubClient {
    /// List issues, asking only for what changed.
    ///
    /// Two mechanisms, and both matter: `since` keeps the RESPONSE small on a
    /// repository with thousands of issues, and the ETag makes the whole
    /// request free when nothing moved at all. Neither is an optimisation for
    /// its own sake — a workbench that mirrors forty repositories continuously
    /// is rate-limited into uselessness without them.
    ///
    /// `since` is inclusive, so the issue that set the mark comes back once
    /// more and is written over itself. One row rewritten beats one update
    /// missed.
    pub async fn list_issues_changed(
        &self,
        owner: &str,
        repo: &str,
        conditions: &Conditions,
    ) -> Result<Fetched<Vec<GitHubIssue>>> {
        let mut url = self.url(&format!(
            "/repos/{owner}/{repo}/issues?state=all&per_page=100&sort=updated&direction=desc"
        ));
        if let Some(since) = &conditions.since {
            url.push_str(&format!("&since={since}"));
        }

        let mut request = self.client.get(&url).bearer_auth(&self.token);
        if let Some(etag) = &conditions.etag {
            request = request.header(reqwest::header::IF_NONE_MATCH, etag);
        }
        let response = request
            .send()
            .await
            .with_context(|| format!("failed to list issues for {owner}/{repo}"))?;

        if response.status() == reqwest::StatusCode::NOT_MODIFIED {
            return Ok(Fetched::Unchanged);
        }
        let etag = header_value(&response, reqwest::header::ETAG);
        let response = require_success(
            &format!("GitHub API error listing issues for {owner}/{repo}"),
            response,
        )?;
        let issues: Vec<GitHubIssue> = response
            .json()
            .await
            .context("failed to parse issues response")?;

        Ok(Fetched::Fresh {
            // Pull requests come back from the issues endpoint too, and a pull
            // request is not an issue to anybody reading this list.
            value: issues
                .into_iter()
                .filter(|issue| !issue.html_url.contains("/pull/"))
                .collect(),
            etag,
        })
    }

    /// List the authenticated user's gists, conditionally.
    ///
    /// No `since` here on purpose: the answer is authoritative about which
    /// gists EXIST, and a partial answer cannot be — a gist absent from an
    /// incremental page would read as deleted.
    pub async fn list_gists_changed(
        &self,
        conditions: &Conditions,
    ) -> Result<Fetched<Vec<GitHubGist>>> {
        let mut request = self
            .client
            .get(self.url("/gists?per_page=100"))
            .bearer_auth(&self.token);
        if let Some(etag) = &conditions.etag {
            request = request.header(reqwest::header::IF_NONE_MATCH, etag);
        }
        let response = request.send().await.context("failed to list gists")?;

        if response.status() == reqwest::StatusCode::NOT_MODIFIED {
            return Ok(Fetched::Unchanged);
        }
        let etag = header_value(&response, reqwest::header::ETAG);
        let response = require_success("failed to list gists", response)?;
        let gists: Vec<GitHubGist> = response
            .json()
            .await
            .context("failed to parse gists response")?;
        Ok(Fetched::Fresh { value: gists, etag })
    }
}

impl GitHubClient {
    /// A conditional GET that decodes into `T`.
    ///
    /// Every mirrored kind goes through this, so "ask only for what I do not
    /// already have" is written once. A 304 is an ANSWER — the copy held is
    /// current — and never an empty result, which is the distinction the whole
    /// mirror rests on.
    async fn conditional<T: serde::de::DeserializeOwned>(
        &self,
        what: &str,
        path: &str,
        conditions: &Conditions,
    ) -> Result<Fetched<T>> {
        let mut request = self.client.get(self.url(path)).bearer_auth(&self.token);
        if let Some(etag) = &conditions.etag {
            request = request.header(reqwest::header::IF_NONE_MATCH, etag);
        }
        let response = request
            .send()
            .await
            .with_context(|| format!("failed {what}"))?;

        if response.status() == reqwest::StatusCode::NOT_MODIFIED {
            return Ok(Fetched::Unchanged);
        }
        let etag = header_value(&response, reqwest::header::ETAG);
        let response = require_success(what, response)?;
        let value: T = response
            .json()
            .await
            .with_context(|| format!("failed to parse the answer to {what}"))?;
        Ok(Fetched::Fresh { value, etag })
    }

    /// Pull requests, newest movement first.
    ///
    /// A separate request from issues even though GitHub's issues endpoint
    /// returns both: that endpoint's pull requests are issue-shaped, missing
    /// the branch, the draft flag and the merge — everything that makes a pull
    /// request worth listing separately.
    pub async fn list_pulls_changed(
        &self,
        owner: &str,
        repo: &str,
        conditions: &Conditions,
    ) -> Result<Fetched<Vec<GitHubPull>>> {
        self.conditional(
            &format!("listing pull requests for {owner}/{repo}"),
            &format!("/repos/{owner}/{repo}/pulls?state=all&per_page=100&sort=updated&direction=desc"),
            conditions,
        )
        .await
    }

    /// What CI says about one commit: check runs AND commit statuses.
    ///
    /// Both, because a repository can use either — GitHub Actions writes check
    /// runs, most other systems write statuses — and a workbench that read one
    /// would report "no checks" for half the fleet.
    pub async fn checks_for(&self, owner: &str, repo: &str, commit: &str) -> Result<GitHubChecks> {
        #[derive(Deserialize)]
        struct CheckRuns {
            check_runs: Vec<RawCheckRun>,
        }
        #[derive(Deserialize)]
        struct RawCheckRun {
            name: String,
            status: String,
            conclusion: Option<String>,
            html_url: Option<String>,
        }
        #[derive(Deserialize)]
        struct CombinedStatus {
            statuses: Vec<RawStatus>,
        }
        #[derive(Deserialize)]
        struct RawStatus {
            context: String,
            state: String,
            target_url: Option<String>,
        }

        let runs: CheckRuns = require_success(
            &format!("listing check runs for {owner}/{repo}@{commit}"),
            self.client
                .get(self.url(&format!(
                    "/repos/{owner}/{repo}/commits/{commit}/check-runs?per_page=100"
                )))
                .bearer_auth(&self.token)
                .send()
                .await
                .context("GitHub API request failed")?,
        )?
        .json()
        .await
        .context("failed to parse the check runs")?;

        let combined: CombinedStatus = require_success(
            &format!("listing commit statuses for {owner}/{repo}@{commit}"),
            self.client
                .get(self.url(&format!(
                    "/repos/{owner}/{repo}/commits/{commit}/status"
                )))
                .bearer_auth(&self.token)
                .send()
                .await
                .context("GitHub API request failed")?,
        )?
        .json()
        .await
        .context("failed to parse the commit statuses")?;

        let mut all: Vec<GitHubCheckRun> = runs
            .check_runs
            .into_iter()
            .map(|run| GitHubCheckRun {
                name: run.name,
                status: run.status,
                conclusion: run.conclusion,
                url: run.html_url,
            })
            .collect();
        all.extend(combined.statuses.into_iter().map(|status| GitHubCheckRun {
            name: status.context,
            // A commit status has no lifecycle: it is written when it is
            // decided, so it is always complete.
            status: "completed".to_string(),
            conclusion: Some(match status.state.as_str() {
                "success" => "success".to_string(),
                "failure" | "error" => "failure".to_string(),
                other => other.to_string(),
            }),
            url: status.target_url,
        }));

        Ok(GitHubChecks {
            sha: commit.to_string(),
            state: GitHubChecks::rollup(&all),
            runs: all,
        })
    }

    pub async fn list_releases_changed(
        &self,
        owner: &str,
        repo: &str,
        conditions: &Conditions,
    ) -> Result<Fetched<Vec<GitHubRelease>>> {
        self.conditional(
            &format!("listing releases for {owner}/{repo}"),
            &format!("/repos/{owner}/{repo}/releases?per_page=100"),
            conditions,
        )
        .await
    }

    pub async fn list_tags_changed(
        &self,
        owner: &str,
        repo: &str,
        conditions: &Conditions,
    ) -> Result<Fetched<Vec<GitHubTag>>> {
        self.conditional(
            &format!("listing tags for {owner}/{repo}"),
            &format!("/repos/{owner}/{repo}/tags?per_page=100"),
            conditions,
        )
        .await
    }

    pub async fn repository_changed(
        &self,
        owner: &str,
        repo: &str,
        conditions: &Conditions,
    ) -> Result<Fetched<GitHubRepository>> {
        self.conditional(
            &format!("reading {owner}/{repo}"),
            &format!("/repos/{owner}/{repo}"),
            conditions,
        )
        .await
    }

    pub async fn list_milestones_changed(
        &self,
        owner: &str,
        repo: &str,
        conditions: &Conditions,
    ) -> Result<Fetched<Vec<GitHubMilestone>>> {
        self.conditional(
            &format!("listing milestones for {owner}/{repo}"),
            &format!("/repos/{owner}/{repo}/milestones?state=all&per_page=100"),
            conditions,
        )
        .await
    }

    pub async fn list_labels_changed(
        &self,
        owner: &str,
        repo: &str,
        conditions: &Conditions,
    ) -> Result<Fetched<Vec<GitHubLabel>>> {
        self.conditional(
            &format!("listing labels for {owner}/{repo}"),
            &format!("/repos/{owner}/{repo}/labels?per_page=100"),
            conditions,
        )
        .await
    }

    /// Comments on one issue or pull request.
    pub async fn list_comments_changed(
        &self,
        owner: &str,
        repo: &str,
        number: i64,
        conditions: &Conditions,
    ) -> Result<Fetched<Vec<GitHubComment>>> {
        self.conditional(
            &format!("listing comments on {owner}/{repo}#{number}"),
            &format!("/repos/{owner}/{repo}/issues/{number}/comments?per_page=100"),
            conditions,
        )
        .await
    }

    /// What GitHub thinks needs this person, across every repository.
    pub async fn list_notifications_changed(
        &self,
        conditions: &Conditions,
    ) -> Result<Fetched<Vec<GitHubNotification>>> {
        self.conditional(
            "listing notifications",
            "/notifications?all=false&per_page=50",
            conditions,
        )
        .await
    }

    /// How much API budget is left.
    ///
    /// Never conditional and never counted: GitHub exempts this endpoint from
    /// the limit it reports, which is the only reason it can be asked when the
    /// budget is gone — exactly when somebody needs to know.
    pub async fn rate_limit(&self) -> Result<GitHubRateLimit> {
        #[derive(Deserialize)]
        struct Envelope {
            resources: Resources,
        }
        #[derive(Deserialize)]
        struct Resources {
            core: GitHubRateLimit,
        }
        let envelope: Envelope = require_success(
            "reading the rate limit",
            self.client
                .get(self.url("/rate_limit"))
                .bearer_auth(&self.token)
                .send()
                .await
                .context("GitHub API request failed")?,
        )?
        .json()
        .await
        .context("failed to parse the rate limit")?;
        Ok(envelope.resources.core)
    }

    /// Views and clones over the last fortnight, which is all GitHub keeps.
    ///
    /// Needs push access. A repository somebody only reads answers 403, and
    /// that is recorded as this scope's error rather than as an empty series —
    /// zero views and "you may not ask" are different facts.
    pub async fn traffic(&self, owner: &str, repo: &str) -> Result<GitHubTraffic> {
        let views: TrafficSeries = require_success(
            &format!("reading traffic for {owner}/{repo}"),
            self.client
                .get(self.url(&format!("/repos/{owner}/{repo}/traffic/views")))
                .bearer_auth(&self.token)
                .send()
                .await
                .context("GitHub API request failed")?,
        )?
        .json()
        .await
        .context("failed to parse the view traffic")?;

        let clones: TrafficSeries = require_success(
            &format!("reading clone traffic for {owner}/{repo}"),
            self.client
                .get(self.url(&format!("/repos/{owner}/{repo}/traffic/clones")))
                .bearer_auth(&self.token)
                .send()
                .await
                .context("GitHub API request failed")?,
        )?
        .json()
        .await
        .context("failed to parse the clone traffic")?;

        Ok(GitHubTraffic {
            views: views.count,
            unique_views: views.uniques,
            clones: clones.count,
            unique_clones: clones.uniques,
            view_days: views.views,
            clone_days: clones.clones,
        })
    }
}

// ---------------------------------------------------------------------------
// Projects v2
// ---------------------------------------------------------------------------
//
// GraphQL, because GitHub retired the REST endpoints for it. That makes this
// the one part of the mirror that cannot be conditional: GraphQL answers 200
// to everything and carries no ETag, so a project is re-read whole each sweep.
// It is one request per project per sweep, which is affordable because a
// person has a handful of projects and forty repositories.
//
// A token needs the `project` scope to read any of this. Without it GitHub
// answers a permission error, which is recorded as this scope's error — the
// board keeps showing what it last held, and says why it is not refreshing.

/// A project board.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct GitHubProject {
    /// The GraphQL node id, which is what every mutation names.
    pub id: String,
    pub number: i64,
    pub title: String,
    pub url: String,
    pub short_description: Option<String>,
    pub closed: bool,
    pub updated_at: String,
    /// Who it belongs to, as a login. A project is an owner's, not a
    /// repository's — which is why the board is its own place in the workbench
    /// rather than a section of a repository's page.
    pub owner: String,
    /// Every field the board defines. The single-select ones are its columns.
    pub fields: Vec<GitHubProjectField>,
}

impl GitHubProject {
    /// The field a board is grouped by: its Status, or the first single-select
    /// it has.
    ///
    /// GitHub's own board groups by Status when it exists, and a project that
    /// renamed it is still a board with columns. Returning `None` is honest:
    /// a project with no single-select field has no columns, and inventing one
    /// would put every item in a made-up bucket.
    pub fn column_field(&self) -> Option<&GitHubProjectField> {
        self.fields
            .iter()
            .find(|field| field.kind == "single_select" && field.name == "Status")
            .or_else(|| {
                self.fields
                    .iter()
                    .find(|field| field.kind == "single_select")
            })
    }
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct GitHubProjectField {
    pub id: String,
    pub name: String,
    /// `single_select` | `text` | `number` | `date` | `iteration`.
    pub kind: String,
    /// The choices, for a single-select. Empty for every other kind.
    #[serde(default)]
    pub options: Vec<GitHubProjectFieldOption>,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct GitHubProjectFieldOption {
    pub id: String,
    pub name: String,
    /// GitHub's colour name for the option — what makes a board recognisable.
    pub color: String,
    /// Kept even when empty: updating the option list replaces the whole
    /// configuration, so omitting a description would erase one GitHub holds.
    ///
    /// A column with no description is the ordinary case, and GitHub says so
    /// with `null` — not with `""` and not by leaving the field out. As a bare
    /// `String` that failed to parse, so a board whose columns had no
    /// descriptions could not be read at all: "a project column has no
    /// description", about every board anybody makes without typing one.
    /// `null` is read as empty. ABSENT is not, and that difference is the
    /// whole of it: a key GitHub did not send means this build never asked for
    /// it, and reading that as `""` writes an empty description back over one
    /// that exists the next time the column list is updated. `default` used to
    /// erase exactly that distinction.
    #[serde(deserialize_with = "text_or_nothing")]
    pub description: String,
}

/// A string GitHub may answer with `null`, read as empty.
///
/// `null` is GitHub saying the column has no description, which is the
/// ordinary case and the truth. It is NOT the same as the key being absent:
/// that means nothing here knows what GitHub holds, and since a refresh writes
/// the whole column back, guessing empty erases a real description. Absence is
/// refused by there being no `default` on the field.
fn text_or_nothing<'de, D>(deserializer: D) -> Result<String, D::Error>
where
    D: serde::Deserializer<'de>,
{
    Ok(Option::<String>::deserialize(deserializer)?.unwrap_or_default())
}

#[derive(Debug, Clone, Serialize)]
struct ProjectColumnOptionInput {
    #[serde(skip_serializing_if = "Option::is_none")]
    id: Option<String>,
    name: String,
    color: String,
    description: String,
}

impl From<&GitHubProjectFieldOption> for ProjectColumnOptionInput {
    fn from(option: &GitHubProjectFieldOption) -> Self {
        Self {
            id: Some(option.id.clone()),
            name: option.name.clone(),
            color: option.color.clone(),
            description: option.description.clone(),
        }
    }
}

/// One card.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct GitHubProjectItem {
    pub id: String,
    /// `ISSUE` | `PULL_REQUEST` | `DRAFT_ISSUE` | `REDACTED`.
    pub kind: String,
    pub title: String,
    /// What the card POINTS AT — the issue, the pull request, or the draft
    /// itself. Distinct from the card's own id: a draft is edited by its
    /// content id and moved by its item id, and using one for the other is an
    /// error GitHub reports as "could not resolve to a node".
    pub content_id: Option<String>,
    /// The issue or pull request number, absent for a draft item — a draft
    /// lives only on the board and has nothing to open.
    pub number: Option<i64>,
    pub url: Option<String>,
    /// `owner/repo`, absent for a draft item.
    pub repository: Option<String>,
    /// `OPEN` | `CLOSED` | `MERGED`, absent for a draft.
    pub state: Option<String>,
    /// Why it is closed, when GitHub says: `COMPLETED` | `NOT_PLANNED`. The
    /// difference between finished and abandoned is not something a board
    /// should make a person open GitHub to learn.
    pub state_reason: Option<String>,
    /// The description, as markdown. A draft card's body is the whole of it —
    /// there is nowhere else to read it.
    pub body: Option<String>,
    pub author: Option<GitHubUser>,
    #[serde(default)]
    pub assignees: Vec<GitHubUser>,
    #[serde(default)]
    pub labels: Vec<GitHubLabel>,
    pub milestone: Option<String>,
    /// How many comments the conversation has. The comments themselves are
    /// read from the repository's own mirror when a card is opened — one
    /// mirror per conversation, not one per board.
    #[serde(default)]
    pub comment_count: i64,
    pub created_at: Option<String>,
    pub closed_at: Option<String>,
    /// Whether the pull request is a draft, and whether it was merged. Absent
    /// state on a merged PR reads as "closed", which loses the distinction
    /// that matters most about a pull request.
    #[serde(default)]
    pub is_draft: bool,
    #[serde(default)]
    pub merged: bool,
    /// `APPROVED` | `CHANGES_REQUESTED` | `REVIEW_REQUIRED`, for a pull
    /// request that has been looked at.
    pub review_decision: Option<String>,
    /// Archived on the board. An archived card is still an item and still has
    /// its field values; it is simply not shown unless it is asked for.
    #[serde(default)]
    pub archived: bool,
    /// Every field value this item carries, by FIELD id. Single-select values
    /// are the option id, so a column change is a value change and the page
    /// never has to match on names.
    #[serde(default)]
    pub field_values: BTreeMap<String, GitHubProjectValue>,
    pub updated_at: String,
}

impl GitHubProjectItem {
    /// Which column this item is in, for a given field.
    pub fn column(&self, field_id: &str) -> Option<&str> {
        match self.field_values.get(field_id)? {
            GitHubProjectValue::SingleSelect { option_id, .. } => Some(option_id),
            _ => None,
        }
    }
}

/// One field's value on one item.
/// `PartialEq` without `Eq`: a number field holds a float, and floats have no
/// total equality. Comparing two values for "did this change" is exactly what
/// `PartialEq` is for here.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum GitHubProjectValue {
    /// The option id AND its name: the id is what a mutation needs, the name
    /// is what a person reads, and looking one up from the other on every
    /// render is how a board gets slow.
    SingleSelect {
        option_id: String,
        name: String,
    },
    Text {
        text: String,
    },
    Number {
        number: f64,
    },
    Date {
        date: String,
    },
    Iteration {
        title: String,
        start_date: String,
    },
}

/// What a card carries, wherever it is read from.
///
/// One fragment rather than two queries that drift: the board reads a hundred
/// of these and a single card is re-read through the same shape after every
/// write, so a field added here appears in both without anybody remembering to
/// add it twice.
const ITEM_FRAGMENT: &str = r#"
fragment Card on ProjectV2Item {
  id type updatedAt isArchived
  fieldValues(first: 30) {
    nodes {
      ... on ProjectV2ItemFieldSingleSelectValue { name optionId field { ... on ProjectV2FieldCommon { id } } }
      ... on ProjectV2ItemFieldTextValue { text field { ... on ProjectV2FieldCommon { id } } }
      ... on ProjectV2ItemFieldNumberValue { number field { ... on ProjectV2FieldCommon { id } } }
      ... on ProjectV2ItemFieldDateValue { date field { ... on ProjectV2FieldCommon { id } } }
      ... on ProjectV2ItemFieldIterationValue { title startDate field { ... on ProjectV2FieldCommon { id } } }
    }
  }
  content {
    ... on DraftIssue {
      id title body createdAt updatedAt
      creator { login avatarUrl }
      assignees(first: 10) { nodes { login avatarUrl } }
    }
    ... on Issue {
      id title body number url state stateReason createdAt closedAt
      repository { nameWithOwner }
      author { login avatarUrl }
      assignees(first: 10) { nodes { login avatarUrl } }
      labels(first: 20) { nodes { name color description } }
      milestone { title }
      comments { totalCount }
    }
    ... on PullRequest {
      id title body number url state createdAt closedAt isDraft merged reviewDecision
      repository { nameWithOwner }
      author { login avatarUrl }
      assignees(first: 10) { nodes { login avatarUrl } }
      labels(first: 20) { nodes { name color description } }
      milestone { title }
      comments { totalCount }
    }
  }
}"#;

impl GitHubClient {
    /// One GraphQL request.
    ///
    /// GraphQL answers 200 with an `errors` array rather than a status, so a
    /// caller that only checked the status would treat "you may not read this
    /// project" as an empty project. That is the failure mode this whole
    /// mirror exists to prevent, so errors are raised here.
    async fn graphql(
        &self,
        what: &str,
        query: &str,
        variables: serde_json::Value,
    ) -> Result<serde_json::Value> {
        let response = require_success(
            what,
            self.client
                .post(self.url("/graphql"))
                .bearer_auth(&self.token)
                .json(&serde_json::json!({ "query": query, "variables": variables }))
                .send()
                .await
                .with_context(|| format!("GitHub API request failed while {what}"))?,
        )?;
        let body: serde_json::Value = response
            .json()
            .await
            .with_context(|| format!("failed to parse the answer to {what}"))?;

        if let Some(errors) = body.get("errors").and_then(|errors| errors.as_array()) {
            if !errors.is_empty() {
                let said = errors
                    .iter()
                    .filter_map(|error| error.get("message").and_then(|m| m.as_str()))
                    .collect::<Vec<_>>()
                    .join("; ");
                anyhow::bail!("{what}: {said}");
            }
        }
        body.get("data")
            .cloned()
            .ok_or_else(|| anyhow::anyhow!("{what}: the answer carried no data"))
    }

    /// Every project one owner has.
    ///
    /// `login` may be a user or an organisation, and `repositoryOwner` resolves
    /// either — which is the point. Asking `organization(login:)` and
    /// `user(login:)` in one query looks like it does the same thing and does
    /// not: GitHub answers the field that does not match with an error, and a
    /// GraphQL answer carrying errors AND data is a failed query as far as
    /// anything reading it is concerned. So every owner failed with "could not
    /// resolve to an Organization" (for a user) or "to a User" (for an
    /// organisation), and no board ever arrived.
    ///
    /// A login that is neither comes back as a null owner and no error, which
    /// is an owner with no boards rather than a failure — and a real failure,
    /// a token without `read:project`, still arrives as an error and is still
    /// raised.
    pub async fn list_projects(&self, login: &str) -> Result<Vec<GitHubProject>> {
        const QUERY: &str = r#"
query($login: String!) {
  repositoryOwner(login: $login) {
    __typename
    ... on Organization { projectsV2(first: 20, orderBy: {field: UPDATED_AT, direction: DESC}) { nodes { ...P } } }
    ... on User { projectsV2(first: 20, orderBy: {field: UPDATED_AT, direction: DESC}) { nodes { ...P } } }
  }
}
fragment P on ProjectV2 {
  id number title url shortDescription closed updatedAt
  fields(first: 50) {
    nodes {
      ... on ProjectV2FieldCommon { id name dataType }
      ... on ProjectV2SingleSelectField { id name dataType options { id name color description } }
    }
  }
}"#;
        let data = self
            .graphql(
                &format!("listing projects for {login}"),
                QUERY,
                serde_json::json!({ "login": login }),
            )
            .await?;

        projects_of_owner(&data, login)
    }

    /// One project in the complete shape a board write returns.
    async fn project(&self, project_id: &str) -> Result<GitHubProject> {
        const QUERY: &str = r#"
query($id: ID!) {
  node(id: $id) {
    ... on ProjectV2 {
      id number title url shortDescription closed updatedAt
      owner {
        ... on Organization { login }
        ... on User { login }
      }
      fields(first: 50) {
        nodes {
          ... on ProjectV2FieldCommon { id name dataType }
          ... on ProjectV2SingleSelectField {
            id name dataType options { id name color description }
          }
        }
      }
    }
  }
}"#;
        let data = self
            .graphql(
                &format!("reading project {project_id}"),
                QUERY,
                serde_json::json!({ "id": project_id }),
            )
            .await?;
        let node = data
            .get("node")
            .filter(|node| !node.is_null())
            .ok_or_else(|| anyhow::anyhow!("project {project_id} no longer exists"))?;
        let owner = node
            .get("owner")
            .and_then(|owner| owner.get("login"))
            .and_then(|login| login.as_str())
            .ok_or_else(|| anyhow::anyhow!("project {project_id} has no readable owner"))?;
        parse_project(node, owner)
    }

    /// Add one option to the board's column field.
    ///
    /// The project is read immediately before constructing the replacement
    /// list. Sending the browser's possibly stale list would let a second
    /// editor's new column disappear. Existing ids, colours and descriptions
    /// are carried exactly so GitHub preserves their identity and card values.
    pub async fn add_project_column(
        &self,
        project_id: &str,
        field_id: &str,
        name: &str,
        color: &str,
        description: &str,
    ) -> Result<GitHubProject> {
        validate_column_color(color)?;
        let name = name.trim();
        if name.is_empty() {
            anyhow::bail!("a project column needs a name");
        }
        let project = self.project(project_id).await?;
        let field = project
            .fields
            .iter()
            .find(|field| field.id == field_id)
            .ok_or_else(|| anyhow::anyhow!("project {project_id} has no field {field_id}"))?;
        if field.kind != "single_select" {
            anyhow::bail!(
                "field {field_id} is {}, not a single-select column field",
                field.kind
            );
        }
        if field
            .options
            .iter()
            .any(|option| option.name.eq_ignore_ascii_case(name))
        {
            anyhow::bail!("project {project_id} already has a column named '{name}'");
        }

        let mut options: Vec<ProjectColumnOptionInput> = field
            .options
            .iter()
            .map(ProjectColumnOptionInput::from)
            .collect();
        options.push(ProjectColumnOptionInput {
            id: None,
            name: name.to_string(),
            color: color.to_string(),
            description: description.trim().to_string(),
        });
        self.update_project_columns(field_id, &options).await?;
        self.project(project_id).await
    }

    /// Remove one option from the board's column field.
    ///
    /// GitHub clears the field value on cards that used the removed option.
    /// The handler consequently re-reads every item after this returns rather
    /// than patching those cards locally.
    pub async fn remove_project_column(
        &self,
        project_id: &str,
        field_id: &str,
        option_id: &str,
    ) -> Result<GitHubProject> {
        let project = self.project(project_id).await?;
        let field = project
            .fields
            .iter()
            .find(|field| field.id == field_id)
            .ok_or_else(|| anyhow::anyhow!("project {project_id} has no field {field_id}"))?;
        if field.kind != "single_select" {
            anyhow::bail!(
                "field {field_id} is {}, not a single-select column field",
                field.kind
            );
        }
        if !field.options.iter().any(|option| option.id == option_id) {
            anyhow::bail!("field {field_id} has no column {option_id}");
        }
        if field.options.len() == 1 {
            anyhow::bail!("the last project column cannot be removed; a single-select field requires an option");
        }
        let options: Vec<ProjectColumnOptionInput> = field
            .options
            .iter()
            .filter(|option| option.id != option_id)
            .map(ProjectColumnOptionInput::from)
            .collect();
        self.update_project_columns(field_id, &options).await?;
        self.project(project_id).await
    }

    async fn update_project_columns(
        &self,
        field_id: &str,
        options: &[ProjectColumnOptionInput],
    ) -> Result<()> {
        const MUTATION: &str = r#"
mutation($field: ID!, $options: [ProjectV2SingleSelectFieldOptionInput!]!) {
  updateProjectV2Field(input: { fieldId: $field, singleSelectOptions: $options }) {
    projectV2Field { ... on ProjectV2SingleSelectField { id } }
  }
}"#;
        self.graphql(
            &format!("updating the columns of field {field_id}"),
            MUTATION,
            serde_json::json!({ "field": field_id, "options": options }),
        )
        .await?;
        Ok(())
    }

    /// Every card on one board, following GitHub's pagination to the end.
    ///
    /// All of them rather than the first page: a board is read as columns, and
    /// a column missing its tail is a column with the wrong count in its
    /// header — which is worse than a slower sync.
    pub async fn project_items(&self, project_id: &str) -> Result<Vec<GitHubProjectItem>> {
        let query = format!(
            r#"
query($id: ID!, $after: String) {{
  node(id: $id) {{
    ... on ProjectV2 {{
      items(first: 50, after: $after) {{
        pageInfo {{ hasNextPage endCursor }}
        nodes {{ ...Card }}
      }}
    }}
  }}
}}
{ITEM_FRAGMENT}"#
        );
        let mut items = Vec::new();
        let mut after: Option<String> = None;
        loop {
            let data = self
                .graphql(
                    &format!("reading the items of project {project_id}"),
                    &query,
                    serde_json::json!({ "id": project_id, "after": after }),
                )
                .await?;
            let page = data
                .get("node")
                .and_then(|node| node.get("items"))
                .ok_or_else(|| anyhow::anyhow!("project {project_id} has no items to read"))?;

            for node in page
                .get("nodes")
                .and_then(|nodes| nodes.as_array())
                .unwrap_or(&Vec::new())
            {
                items.push(parse_project_item(node)?);
            }

            let more = page
                .get("pageInfo")
                .and_then(|info| info.get("hasNextPage"))
                .and_then(|more| more.as_bool())
                .unwrap_or(false);
            if !more {
                break;
            }
            after = page
                .get("pageInfo")
                .and_then(|info| info.get("endCursor"))
                .and_then(|cursor| cursor.as_str())
                .map(str::to_string);
            if after.is_none() {
                // More pages and no cursor to ask with: GitHub contradicting
                // itself. Stopping here would silently truncate the board.
                anyhow::bail!("project {project_id} says there is another page and gives no cursor");
            }
        }
        Ok(items)
    }

    /// One card, re-read.
    ///
    /// What every write here ends with. The alternative is patching the held
    /// payload by hand — which was how a move worked, and which quietly
    /// invents the parts of the answer it does not know: GitHub stamps
    /// `updatedAt`, may close an item, may have had another person change a
    /// field a second earlier. Asking costs one request and is never wrong.
    pub async fn project_item(&self, item_id: &str) -> Result<GitHubProjectItem> {
        let query = format!(
            r#"
query($id: ID!) {{ node(id: $id) {{ ...Card }} }}
{ITEM_FRAGMENT}"#
        );
        let data = self
            .graphql(
                &format!("re-reading item {item_id}"),
                &query,
                serde_json::json!({ "id": item_id }),
            )
            .await?;
        let node = data
            .get("node")
            .filter(|node| !node.is_null())
            .ok_or_else(|| anyhow::anyhow!("item {item_id} is not on this board any more"))?;
        parse_project_item(node)
    }

    /// Set one field on one card.
    ///
    /// Every field kind through one door, because they are one act: a person
    /// setting a due date and a person dragging a card between columns are
    /// both saying "this item's F is now V", and two code paths for that is
    /// how one of them ends up not refreshing what the other does.
    pub async fn set_project_field(
        &self,
        project_id: &str,
        item_id: &str,
        field_id: &str,
        value: &ProjectFieldWrite,
    ) -> Result<GitHubProjectItem> {
        const MUTATION: &str = r#"
mutation($project: ID!, $item: ID!, $field: ID!, $value: ProjectV2FieldValue!) {
  updateProjectV2ItemFieldValue(input: {
    projectId: $project, itemId: $item, fieldId: $field, value: $value
  }) { projectV2Item { id } }
}"#;
        self.graphql(
            &format!("setting a field on item {item_id}"),
            MUTATION,
            serde_json::json!({
                "project": project_id,
                "item": item_id,
                "field": field_id,
                "value": value.as_input(),
            }),
        )
        .await?;
        self.project_item(item_id).await
    }

    /// Take a field's value off a card.
    ///
    /// Distinct from setting it to empty: an empty text value is a value, and
    /// a board that could not tell "no due date" from "a due date of nothing"
    /// would show a column of blanks where it means to show none.
    pub async fn clear_project_field(
        &self,
        project_id: &str,
        item_id: &str,
        field_id: &str,
    ) -> Result<GitHubProjectItem> {
        const MUTATION: &str = r#"
mutation($project: ID!, $item: ID!, $field: ID!) {
  clearProjectV2ItemFieldValue(input: {
    projectId: $project, itemId: $item, fieldId: $field
  }) { projectV2Item { id } }
}"#;
        self.graphql(
            &format!("clearing a field on item {item_id}"),
            MUTATION,
            serde_json::json!({ "project": project_id, "item": item_id, "field": field_id }),
        )
        .await?;
        self.project_item(item_id).await
    }

    /// Put a card after another one, or first in the board's order.
    ///
    /// `after` is the card it lands behind; `None` puts it at the top. This is
    /// what a drag WITHIN a column means, and without it a board's order is
    /// whatever GitHub last decided.
    pub async fn move_project_item_after(
        &self,
        project_id: &str,
        item_id: &str,
        after: Option<&str>,
    ) -> Result<GitHubProjectItem> {
        const MUTATION: &str = r#"
mutation($project: ID!, $item: ID!, $after: ID) {
  updateProjectV2ItemPosition(input: {
    projectId: $project, itemId: $item, afterId: $after
  }) { items { totalCount } }
}"#;
        self.graphql(
            &format!("ordering item {item_id}"),
            MUTATION,
            serde_json::json!({ "project": project_id, "item": item_id, "after": after }),
        )
        .await?;
        self.project_item(item_id).await
    }

    /// Add a card that exists only on the board.
    ///
    /// A draft is a note with a place in the plan and no repository yet. It is
    /// the cheapest way to put something on a board, and refusing to create
    /// one is what sends a person to the website mid-thought.
    pub async fn add_project_draft(
        &self,
        project_id: &str,
        title: &str,
        body: &str,
    ) -> Result<GitHubProjectItem> {
        const MUTATION: &str = r#"
mutation($project: ID!, $title: String!, $body: String!) {
  addProjectV2DraftIssue(input: { projectId: $project, title: $title, body: $body }) {
    projectItem { id }
  }
}"#;
        let data = self
            .graphql(
                "adding a draft card",
                MUTATION,
                serde_json::json!({ "project": project_id, "title": title, "body": body }),
            )
            .await?;
        let id = data
            .get("addProjectV2DraftIssue")
            .and_then(|added| added.get("projectItem"))
            .and_then(|item| item.get("id"))
            .and_then(|id| id.as_str())
            .ok_or_else(|| {
                anyhow::anyhow!("the draft was created and GitHub did not say its id")
            })?;
        self.project_item(id).await
    }

    /// Rewrite a draft's title and body.
    ///
    /// Only a draft: an issue's title belongs to the issue and is edited where
    /// issues are, not on a board that happens to show it.
    pub async fn update_project_draft(
        &self,
        item_id: &str,
        draft_id: &str,
        title: &str,
        body: &str,
    ) -> Result<GitHubProjectItem> {
        const MUTATION: &str = r#"
mutation($draft: ID!, $title: String!, $body: String!) {
  updateProjectV2DraftIssue(input: { draftIssueId: $draft, title: $title, body: $body }) {
    draftIssue { id }
  }
}"#;
        self.graphql(
            &format!("editing draft {draft_id}"),
            MUTATION,
            serde_json::json!({ "draft": draft_id, "title": title, "body": body }),
        )
        .await?;
        self.project_item(item_id).await
    }

    /// Put an existing issue or pull request on the board, by its URL.
    ///
    /// The URL is what a person has in hand — it is what GitHub's own "add
    /// item" takes, and what is in the clipboard after reading an issue. It is
    /// resolved to a node id here rather than asking anybody to find one.
    pub async fn add_project_item_by_url(
        &self,
        project_id: &str,
        url: &str,
    ) -> Result<GitHubProjectItem> {
        const RESOLVE: &str = r#"
query($url: URI!) {
  resource(url: $url) {
    __typename
    ... on Issue { id }
    ... on PullRequest { id }
  }
}"#;
        let found = self
            .graphql(
                &format!("looking up {url}"),
                RESOLVE,
                serde_json::json!({ "url": url }),
            )
            .await?;
        let resource = found
            .get("resource")
            .filter(|resource| !resource.is_null())
            .ok_or_else(|| {
                anyhow::anyhow!("{url} is not something on GitHub this token can see")
            })?;
        let kind = resource
            .get("__typename")
            .and_then(|kind| kind.as_str())
            .unwrap_or("that");
        let content = resource.get("id").and_then(|id| id.as_str()).ok_or_else(|| {
            anyhow::anyhow!("{url} is a {kind}, and only an issue or a pull request can go on a board")
        })?;

        const MUTATION: &str = r#"
mutation($project: ID!, $content: ID!) {
  addProjectV2ItemById(input: { projectId: $project, contentId: $content }) {
    item { id }
  }
}"#;
        let data = self
            .graphql(
                &format!("adding {url} to the board"),
                MUTATION,
                serde_json::json!({ "project": project_id, "content": content }),
            )
            .await?;
        let id = data
            .get("addProjectV2ItemById")
            .and_then(|added| added.get("item"))
            .and_then(|item| item.get("id"))
            .and_then(|id| id.as_str())
            .ok_or_else(|| anyhow::anyhow!("the item was added and GitHub did not say its id"))?;
        self.project_item(id).await
    }

    /// Archive a card, or bring it back.
    ///
    /// Archiving is what a board does instead of deleting: the item keeps its
    /// field values and its history, and stops taking up a column. Deleting is
    /// separate, and is the one that cannot be undone.
    pub async fn archive_project_item(
        &self,
        project_id: &str,
        item_id: &str,
        archived: bool,
    ) -> Result<GitHubProjectItem> {
        const ARCHIVE: &str = r#"
mutation($project: ID!, $item: ID!) {
  archiveProjectV2Item(input: { projectId: $project, itemId: $item }) { item { id } }
}"#;
        const UNARCHIVE: &str = r#"
mutation($project: ID!, $item: ID!) {
  unarchiveProjectV2Item(input: { projectId: $project, itemId: $item }) { item { id } }
}"#;
        self.graphql(
            &format!("archiving item {item_id}"),
            if archived { ARCHIVE } else { UNARCHIVE },
            serde_json::json!({ "project": project_id, "item": item_id }),
        )
        .await?;
        self.project_item(item_id).await
    }

    /// Take a card off the board.
    ///
    /// The issue itself is untouched — this removes the card, which is the
    /// only thing a board owns. A draft has nowhere else to be, so deleting
    /// one deletes it.
    pub async fn delete_project_item(&self, project_id: &str, item_id: &str) -> Result<()> {
        const MUTATION: &str = r#"
mutation($project: ID!, $item: ID!) {
  deleteProjectV2Item(input: { projectId: $project, itemId: $item }) { deletedItemId }
}"#;
        self.graphql(
            &format!("removing item {item_id}"),
            MUTATION,
            serde_json::json!({ "project": project_id, "item": item_id }),
        )
        .await?;
        Ok(())
    }
}

/// A value being written to a field.
///
/// The kinds GitHub takes, named. A write that carried a bare string would
/// have to guess which kind the field is, and guessing wrong sets a date field
/// to the text "2026-08-19" — which GitHub accepts and nothing shows.
#[derive(Debug, Clone, PartialEq, serde::Deserialize)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum ProjectFieldWrite {
    SingleSelect {
        option_id: String,
    },
    Text {
        text: String,
    },
    Number {
        number: f64,
    },
    /// `YYYY-MM-DD`, which is what GitHub's `Date` scalar takes.
    Date {
        date: String,
    },
    Iteration {
        iteration_id: String,
    },
}

impl ProjectFieldWrite {
    /// The `ProjectV2FieldValue` input this is, as GitHub spells it.
    fn as_input(&self) -> serde_json::Value {
        match self {
            Self::SingleSelect { option_id } => {
                serde_json::json!({ "singleSelectOptionId": option_id })
            }
            Self::Text { text } => serde_json::json!({ "text": text }),
            Self::Number { number } => serde_json::json!({ "number": number }),
            Self::Date { date } => serde_json::json!({ "date": date }),
            Self::Iteration { iteration_id } => {
                serde_json::json!({ "iterationId": iteration_id })
            }
        }
    }
}

/// The boards in an answer to the owner query.
///
/// Split out from the request so the shape GitHub actually returns is
/// something a test can hold: an owner with boards, an owner with none, and a
/// login that is nobody all come back through here, and only the first is a
/// board.
fn projects_of_owner(data: &serde_json::Value, login: &str) -> Result<Vec<GitHubProject>> {
    // A login that resolves to nobody. Not an error: an owner this workspace
    // has repositories under may simply not exist as an account any more, and
    // a sweep that failed over it would stop mirroring the owners that do.
    let Some(owner) = data.get("repositoryOwner").filter(|owner| !owner.is_null()) else {
        return Ok(Vec::new());
    };
    // An owner kind with no boards at all — `projectsV2` is absent when the
    // owner is neither a User nor an Organization, which is a shape GitHub can
    // grow without this breaking.
    let Some(nodes) = owner
        .get("projectsV2")
        .and_then(|projects| projects.get("nodes"))
        .and_then(|nodes| nodes.as_array())
    else {
        return Ok(Vec::new());
    };
    nodes
        .iter()
        .map(|node| parse_project(node, login))
        .collect()
}

fn validate_column_color(color: &str) -> Result<()> {
    const COLORS: &[&str] = &[
        "GRAY", "BLUE", "GREEN", "YELLOW", "ORANGE", "RED", "PINK", "PURPLE",
    ];
    if COLORS.contains(&color) {
        return Ok(());
    }
    anyhow::bail!(
        "'{color}' is not a GitHub project column color; expected {}",
        COLORS.join(", ")
    )
}

fn parse_project(node: &serde_json::Value, login: &str) -> Result<GitHubProject> {
    let field_nodes = node
        .get("fields")
        .and_then(|fields| fields.get("nodes"))
        .and_then(|nodes| nodes.as_array())
        .ok_or_else(|| anyhow::anyhow!("a project has no field list"))?;
    let fields = field_nodes
        .iter()
        .map(|field| -> Result<GitHubProjectField> {
            let options = match field.get("options") {
                None => Vec::new(),
                Some(options) => options
                    .as_array()
                    .ok_or_else(|| anyhow::anyhow!("a project field's options are not a list"))?
                    .iter()
                    .map(|option| -> Result<GitHubProjectFieldOption> {
                        Ok(GitHubProjectFieldOption {
                            id: string_at(option, "id", "a project column")?,
                            name: string_at(option, "name", "a project column")?,
                            color: string_at(option, "color", "a project column")?,
                            description: optional_string_at(option, "description", "a project column")?,
                        })
                    })
                    .collect::<Result<Vec<_>>>()?,
            };
            Ok(GitHubProjectField {
                id: string_at(field, "id", "a project field")?,
                name: string_at(field, "name", "a project field")?,
                kind: string_at(field, "dataType", "a project field")?.to_ascii_lowercase(),
                options,
            })
        })
        .collect::<Result<Vec<_>>>()?;

    Ok(GitHubProject {
        id: string_at(node, "id", "a project")?,
        number: node
            .get("number")
            .and_then(|number| number.as_i64())
            .ok_or_else(|| anyhow::anyhow!("a project has no number"))?,
        title: string_at(node, "title", "a project")?,
        url: string_at(node, "url", "a project")?,
        short_description: node
            .get("shortDescription")
            .and_then(|text| text.as_str())
            .map(str::to_string),
        closed: node
            .get("closed")
            .and_then(|closed| closed.as_bool())
            .unwrap_or(false),
        updated_at: string_at(node, "updatedAt", "a project")?,
        owner: login.to_string(),
        fields,
    })
}

fn parse_project_item(node: &serde_json::Value) -> Result<GitHubProjectItem> {
    let content = node.get("content");
    let mut values = BTreeMap::new();
    if let Some(nodes) = node
        .get("fieldValues")
        .and_then(|values| values.get("nodes"))
        .and_then(|nodes| nodes.as_array())
    {
        for value in nodes {
            // A field value with no field is GitHub's answer for a value the
            // token may not read. Skipped rather than guessed at.
            let Some(field_id) = value
                .get("field")
                .and_then(|field| field.get("id"))
                .and_then(|id| id.as_str())
            else {
                continue;
            };
            let parsed = if let (Some(option), Some(name)) = (
                value.get("optionId").and_then(|id| id.as_str()),
                value.get("name").and_then(|name| name.as_str()),
            ) {
                GitHubProjectValue::SingleSelect {
                    option_id: option.to_string(),
                    name: name.to_string(),
                }
            } else if let Some(text) = value.get("text").and_then(|text| text.as_str()) {
                GitHubProjectValue::Text {
                    text: text.to_string(),
                }
            } else if let Some(number) = value.get("number").and_then(|number| number.as_f64()) {
                GitHubProjectValue::Number { number }
            } else if let Some(date) = value.get("date").and_then(|date| date.as_str()) {
                GitHubProjectValue::Date {
                    date: date.to_string(),
                }
            } else if let (Some(title), Some(start)) = (
                value.get("title").and_then(|title| title.as_str()),
                value.get("startDate").and_then(|date| date.as_str()),
            ) {
                GitHubProjectValue::Iteration {
                    title: title.to_string(),
                    start_date: start.to_string(),
                }
            } else {
                continue;
            };
            values.insert(field_id.to_string(), parsed);
        }
    }

    Ok(GitHubProjectItem {
        id: string_at(node, "id", "a project item")?,
        kind: string_at(node, "type", "a project item")?,
        title: content
            .and_then(|content| content.get("title"))
            .and_then(|title| title.as_str())
            .unwrap_or("(untitled)")
            .to_string(),
        content_id: text(content, "id"),
        number: content
            .and_then(|content| content.get("number"))
            .and_then(|number| number.as_i64()),
        url: content
            .and_then(|content| content.get("url"))
            .and_then(|url| url.as_str())
            .map(str::to_string),
        repository: content
            .and_then(|content| content.get("repository"))
            .and_then(|repo| repo.get("nameWithOwner"))
            .and_then(|name| name.as_str())
            .map(str::to_string),
        state: content
            .and_then(|content| content.get("state"))
            .and_then(|state| state.as_str())
            .map(str::to_string),
        state_reason: text(content, "stateReason"),
        body: text(content, "body"),
        // A draft card has a creator where an issue has an author. Both are
        // "who put this here", and a card that showed one and not the other
        // would look like nobody made it.
        author: content
            .and_then(|content| content.get("author").or_else(|| content.get("creator")))
            .and_then(parse_user),
        assignees: people(content, "assignees"),
        labels: content
            .and_then(|content| content.get("labels"))
            .and_then(|labels| labels.get("nodes"))
            .and_then(|nodes| nodes.as_array())
            .map(|nodes| {
                nodes
                    .iter()
                    .filter_map(|label| {
                        Some(GitHubLabel {
                            name: label.get("name")?.as_str()?.to_string(),
                            color: label
                                .get("color")
                                .and_then(|color| color.as_str())
                                .unwrap_or_default()
                                .to_string(),
                            description: label
                                .get("description")
                                .and_then(|text| text.as_str())
                                .map(str::to_string),
                        })
                    })
                    .collect()
            })
            .unwrap_or_default(),
        milestone: content
            .and_then(|content| content.get("milestone"))
            .and_then(|milestone| milestone.get("title"))
            .and_then(|title| title.as_str())
            .map(str::to_string),
        comment_count: content
            .and_then(|content| content.get("comments"))
            .and_then(|comments| comments.get("totalCount"))
            .and_then(|count| count.as_i64())
            .unwrap_or(0),
        created_at: text(content, "createdAt"),
        closed_at: text(content, "closedAt"),
        is_draft: flag(content, "isDraft"),
        merged: flag(content, "merged"),
        review_decision: text(content, "reviewDecision"),
        archived: node
            .get("isArchived")
            .and_then(|archived| archived.as_bool())
            .unwrap_or(false),
        field_values: values,
        updated_at: string_at(node, "updatedAt", "a project item")?,
    })
}

/// A string under the content, when the content is a kind that has one.
///
/// Every one of these is absent for some card kind — a draft has no state, an
/// issue has no review decision — so absence is the ordinary answer and never
/// a parse failure.
fn text(content: Option<&serde_json::Value>, key: &str) -> Option<String> {
    content
        .and_then(|content| content.get(key))
        .and_then(|value| value.as_str())
        .map(str::to_string)
}

fn flag(content: Option<&serde_json::Value>, key: &str) -> bool {
    content
        .and_then(|content| content.get(key))
        .and_then(|value| value.as_bool())
        .unwrap_or(false)
}

fn parse_user(node: &serde_json::Value) -> Option<GitHubUser> {
    Some(GitHubUser {
        login: node.get("login")?.as_str()?.to_string(),
        avatar_url: node
            .get("avatarUrl")
            .and_then(|url| url.as_str())
            .map(str::to_string),
    })
}

fn people(content: Option<&serde_json::Value>, key: &str) -> Vec<GitHubUser> {
    content
        .and_then(|content| content.get(key))
        .and_then(|people| people.get("nodes"))
        .and_then(|nodes| nodes.as_array())
        .map(|nodes| nodes.iter().filter_map(parse_user).collect())
        .unwrap_or_default()
}

fn string_at(node: &serde_json::Value, key: &str, what: &str) -> Result<String> {
    node.get(key)
        .and_then(|value| value.as_str())
        .map(str::to_string)
        .ok_or_else(|| anyhow::anyhow!("{what} has no {key}"))
}

/// A string a caller may legitimately have left unset, when the answer says so.
///
/// `null` and MISSING are not the same thing here, and treating them alike
/// broke this in both directions. A board column's description is the case:
/// nobody types one, GitHub answers `"description": null`, and reading that as
/// a missing field made every ordinary board unreadable — "a project column
/// has no description", about something the person never filled in.
///
/// The other direction costs more. A key that is not in the answer at all
/// means this query did not ask for it, so nothing here knows what GitHub
/// holds. A refresh writes the whole column back, so reading absence as `""`
/// erases a description that exists, on the next edit, without anybody
/// touching it. That is refused.
fn optional_string_at(node: &serde_json::Value, key: &str, what: &str) -> Result<String> {
    match node.get(key) {
        Some(serde_json::Value::Null) => Ok(String::new()),
        Some(serde_json::Value::String(text)) => Ok(text.clone()),
        Some(other) => Err(anyhow::anyhow!(
            "{what} has a {key} that is not text: {other}"
        )),
        None => Err(anyhow::anyhow!(
            "{what} came back without a {key}, so this cannot say what GitHub \
             holds for it — and a refresh writes the whole column back, which \
             would erase it. Refresh Projects to read them again."
        )),
    }
}

/// One header, as text, when it is there and readable.
fn header_value(response: &reqwest::Response, name: reqwest::header::HeaderName) -> Option<String> {
    response
        .headers()
        .get(name)
        .and_then(|value| value.to_str().ok())
        .map(str::to_string)
}

impl GitHubClient {
    /// List issues for a repository.
    pub async fn list_issues(
        &self,
        owner: &str,
        repo: &str,
        state: &str,
    ) -> Result<Vec<GitHubIssue>> {
        let url = self.url(&format!(
            "/repos/{}/{}/issues?state={}&per_page=100&sort=updated&direction=desc",
            owner, repo, state
        ));
        let response = require_success(
            &format!("GitHub API error listing issues for {}/{}", owner, repo),
            self.client
                .get(&url)
                .bearer_auth(&self.token)
                .send()
                .await
                .with_context(|| format!("failed to list issues for {}/{}", owner, repo))?,
        )?;
        let resp: Vec<GitHubIssue> = response
            .json()
            .await
            .context("failed to parse issues response")?;

        // Filter out pull requests (GitHub's issues API returns PRs too)
        Ok(resp
            .into_iter()
            .filter(|i| !i.html_url.contains("/pull/"))
            .collect())
    }

    /// Get a single issue.
    pub async fn get_issue(&self, owner: &str, repo: &str, number: i64) -> Result<GitHubIssue> {
        let url = self.url(&format!("/repos/{}/{}/issues/{}", owner, repo, number));
        let issue: GitHubIssue = require_success(
            &format!("failed to get issue {}/{}#{}", owner, repo, number),
            self.client
                .get(&url)
                .bearer_auth(&self.token)
                .send()
                .await?,
        )?
        .json()
        .await?;
        Ok(issue)
    }

    /// Create an issue.
    pub async fn create_issue(
        &self,
        owner: &str,
        repo: &str,
        req: &CreateIssueRequest,
    ) -> Result<GitHubIssue> {
        let url = self.url(&format!("/repos/{}/{}/issues", owner, repo));
        let issue: GitHubIssue = require_success(
            &format!("failed to create issue in {}/{}", owner, repo),
            self.client
                .post(&url)
                .bearer_auth(&self.token)
                .json(req)
                .send()
                .await?,
        )?
        .json()
        .await?;
        Ok(issue)
    }

    /// Update an issue (close, reopen, edit title/body/labels).
    pub async fn update_issue(
        &self,
        owner: &str,
        repo: &str,
        number: i64,
        req: &UpdateIssueRequest,
    ) -> Result<GitHubIssue> {
        let url = self.url(&format!("/repos/{}/{}/issues/{}", owner, repo, number));
        let issue: GitHubIssue = require_success(
            &format!("failed to update issue {}/{}#{}", owner, repo, number),
            self.client
                .patch(&url)
                .bearer_auth(&self.token)
                .json(req)
                .send()
                .await?,
        )?
        .json()
        .await?;
        Ok(issue)
    }

    /// List comments on an issue.
    pub async fn list_comments(
        &self,
        owner: &str,
        repo: &str,
        number: i64,
    ) -> Result<Vec<GitHubComment>> {
        let url = self.url(&format!(
            "/repos/{}/{}/issues/{}/comments?per_page=100",
            owner, repo, number
        ));
        let comments: Vec<GitHubComment> = require_success(
            &format!("failed to list comments for {}/{}#{}", owner, repo, number),
            self.client
                .get(&url)
                .bearer_auth(&self.token)
                .send()
                .await?,
        )?
        .json()
        .await?;
        Ok(comments)
    }

    /// Add a comment to an issue.
    pub async fn add_comment(
        &self,
        owner: &str,
        repo: &str,
        number: i64,
        body: &str,
    ) -> Result<GitHubComment> {
        let url = self.url(&format!("/repos/{}/{}/issues/{}/comments", owner, repo, number));
        let comment: GitHubComment = require_success(
            &format!("failed to add comment to {}/{}#{}", owner, repo, number),
            self.client
                .post(&url)
                .bearer_auth(&self.token)
                .json(&CreateCommentRequest {
                    body: body.to_string(),
                })
                .send()
                .await?,
        )?
        .json()
        .await?;
        Ok(comment)
    }

    /// List published gists for the authenticated user.
    pub async fn list_gists(&self) -> Result<Vec<GitHubGist>> {
        let response = require_success(
            "failed to list gists",
            self.client
                .get(self.url("/gists?per_page=100"))
                .bearer_auth(&self.token)
                .send()
                .await?,
        )?;
        let gists: Vec<GitHubGist> = response
            .json()
            .await
            .context("failed to parse gists response")?;
        Ok(gists)
    }

    /// Get a single gist including file contents.
    pub async fn get_gist(&self, gist_id: &str) -> Result<GitHubGist> {
        let url = self.url(&format!("/gists/{}", gist_id));
        let gist: GitHubGist = require_success(
            &format!("failed to get gist {}", gist_id),
            self.client
                .get(&url)
                .bearer_auth(&self.token)
                .send()
                .await?,
        )?
        .json()
        .await
        .context("failed to parse gist response")?;
        Ok(gist)
    }

    /// Create a gist.
    pub async fn create_gist(&self, req: &CreateGistRequest) -> Result<GitHubGist> {
        let gist: GitHubGist = require_success(
            "failed to create gist",
            self.client
                .post(&self.url("/gists"))
                .bearer_auth(&self.token)
                .json(req)
                .send()
                .await?,
        )?
        .json()
        .await
        .context("failed to parse create gist response")?;
        Ok(gist)
    }

    /// Update a gist.
    pub async fn update_gist(&self, gist_id: &str, req: &UpdateGistRequest) -> Result<GitHubGist> {
        let url = self.url(&format!("/gists/{}", gist_id));
        let gist: GitHubGist = require_success(
            &format!("failed to update gist {}", gist_id),
            self.client
                .patch(&url)
                .bearer_auth(&self.token)
                .json(req)
                .send()
                .await?,
        )?
        .json()
        .await
        .context("failed to parse update gist response")?;
        Ok(gist)
    }
}

/// Parse a GitHub URL into (owner, repo).
/// Handles: https://github.com/owner/repo[.git]
///          git@github.com:owner/repo[.git]
///          ssh://git@github.com/owner/repo[.git]
pub fn parse_github_url(url: &str) -> Option<(String, String)> {
    let url = url.trim();

    // HTTPS format
    if let Some(rest) = url
        .strip_prefix("https://github.com/")
        .or_else(|| url.strip_prefix("http://github.com/"))
    {
        return parse_owner_repo(rest);
    }

    // SSH formats: scp-like, and the URL form git writes for `ssh://`.
    if let Some(rest) = url
        .strip_prefix("git@github.com:")
        .or_else(|| url.strip_prefix("ssh://git@github.com/"))
    {
        return parse_owner_repo(rest);
    }

    None
}

fn parse_owner_repo(path: &str) -> Option<(String, String)> {
    let path = path.trim_end_matches(".git").trim_end_matches('/');
    let parts: Vec<&str> = path.splitn(3, '/').collect();
    if parts.len() >= 2 && !parts[0].is_empty() && !parts[1].is_empty() {
        Some((parts[0].to_string(), parts[1].to_string()))
    } else {
        None
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_parse_github_url_https() {
        assert_eq!(
            parse_github_url("https://github.com/wesm/agentsview"),
            Some(("wesm".to_string(), "agentsview".to_string()))
        );
    }

    #[test]
    fn test_parse_github_url_https_with_git_suffix() {
        assert_eq!(
            parse_github_url("https://github.com/wesm/agentsview.git"),
            Some(("wesm".to_string(), "agentsview".to_string()))
        );
    }

    #[test]
    fn test_parse_github_url_ssh() {
        assert_eq!(
            parse_github_url("git@github.com:wesm/agentsview.git"),
            Some(("wesm".to_string(), "agentsview".to_string()))
        );
    }

    /// The URL form of SSH is how `git clone ssh://…` records a remote, and a
    /// repository cloned that way is still on GitHub.
    #[test]
    fn test_parse_github_url_ssh_url_form() {
        assert_eq!(
            parse_github_url("ssh://git@github.com/wesm/agentsview.git"),
            Some(("wesm".to_string(), "agentsview".to_string()))
        );
    }

    #[test]
    fn test_parse_github_url_non_github() {
        assert_eq!(parse_github_url("https://gitlab.com/user/repo"), None);
    }

    #[test]
    fn test_parse_github_url_invalid() {
        assert_eq!(parse_github_url("not a url"), None);
    }

    /// One board, as GitHub returns it under `repositoryOwner`.
    fn owner_with_a_board(kind: &str) -> serde_json::Value {
        serde_json::json!({
            "repositoryOwner": {
                "__typename": kind,
                "projectsV2": { "nodes": [{
                    "id": "PVT_1",
                    "number": 7,
                    "title": "Roadmap",
                    "url": "https://github.com/orgs/machinefabric/projects/7",
                    "shortDescription": null,
                    "closed": false,
                    "updatedAt": "2026-08-19T09:00:00Z",
                    "fields": { "nodes": [] }
                }]}
            }
        })
    }

    /// TEST10074: a board is read whether its owner is a user or an
    /// organisation.
    ///
    /// The query asked `organization(login:)` and `user(login:)` in one go and
    /// took whichever came back. It looks equivalent to asking for the owner
    /// and is not: GitHub answers the field that does not match with an ERROR,
    /// and an answer carrying errors is a failed query — so every owner failed
    /// with "could not resolve to an Organization" or "to a User", and the
    /// Projects tab was empty on a workspace whose owners both had boards.
    #[test]
    fn test10074_a_board_is_read_for_either_kind_of_owner() {
        for kind in ["Organization", "User"] {
            let boards = projects_of_owner(&owner_with_a_board(kind), "machinefabric")
                .expect("the answer parses");
            assert_eq!(boards.len(), 1, "no board came back for a {kind} owner");
            assert_eq!(boards[0].number, 7);
            assert_eq!(boards[0].title, "Roadmap");
            assert_eq!(boards[0].owner, "machinefabric");
        }
    }

    /// TEST10075: an owner who is nobody has no boards, and is not a failure.
    ///
    /// `repositoryOwner` answers null rather than erroring for a login that
    /// does not resolve. That is an owner with nothing to mirror — an account
    /// that was renamed or closed — and treating it as a failure would stop
    /// the sweep over the owners that do exist. A REAL failure, a token
    /// without `read:project`, arrives as a GraphQL error instead and is
    /// raised before this is ever reached.
    #[test]
    fn test10075_an_owner_who_does_not_resolve_has_no_boards() {
        let nobody = serde_json::json!({ "repositoryOwner": serde_json::Value::Null });
        assert!(projects_of_owner(&nobody, "gone")
            .expect("a null owner is an answer")
            .is_empty());

        // An owner kind that carries no boards field at all — a shape GitHub
        // can grow — is the same thing and not a parse failure.
        let unknown = serde_json::json!({
            "repositoryOwner": { "__typename": "Mannequin" }
        });
        assert!(projects_of_owner(&unknown, "someone")
            .expect("an unknown owner kind is an answer")
            .is_empty());
    }

    /**
     * TEST10196: replacing a single-select option list must preserve every
     * existing option's identity, colour and description. GitHub clears card
     * values when an existing id is omitted, so a partial input is data loss,
     * not a cosmetic update.
     */
    #[test]
    fn test10196_a_column_update_preserves_the_complete_existing_options() {
        let option = GitHubProjectFieldOption {
            id: "OPT_TODO".to_string(),
            name: "Todo".to_string(),
            color: "GRAY".to_string(),
            description: "not started".to_string(),
        };
        let input = serde_json::to_value(ProjectColumnOptionInput::from(&option))
            .expect("the GraphQL input serializes");
        assert_eq!(input["id"], "OPT_TODO");
        assert_eq!(input["name"], "Todo");
        assert_eq!(input["color"], "GRAY");
        assert_eq!(input["description"], "not started");

        let new_option = ProjectColumnOptionInput {
            id: None,
            name: "Blocked".to_string(),
            color: "RED".to_string(),
            description: String::new(),
        };
        let new_input = serde_json::to_value(new_option).expect("new option serializes");
        assert!(
            new_input.get("id").is_none(),
            "GitHub assigns a new option id"
        );
        assert!(validate_column_color("RED").is_ok());
        assert!(validate_column_color("#ff0000").is_err());
    }
}

#[cfg(test)]
mod column_description_tests {
    use super::*;

    fn option(json: serde_json::Value) -> Result<GitHubProjectFieldOption, serde_json::Error> {
        serde_json::from_value(json)
    }

    /// TEST11607: a column GitHub says has no description reads as having none.
    ///
    /// `null` is the ordinary answer for a column nobody described, and it was
    /// once refused — so a board whose columns had no descriptions could not be
    /// read at all, which is most boards.
    #[test]
    fn test11607_a_null_description_is_no_description() {
        let read = option(serde_json::json!({
            "id": "OPT_1", "name": "Todo", "color": "GRAY", "description": null
        }))
        .expect("a column with no description is an ordinary column");
        assert_eq!(read.description, "");
    }

    /// TEST11608: a column whose description was never asked for is refused.
    ///
    /// The opposite direction, and the one that costs data. An absent key means
    /// this build did not ask GitHub for the field, so nothing here knows what
    /// it holds — and updating a column list writes the WHOLE configuration
    /// back, so reading absence as "" erases a description nobody touched.
    ///
    /// These two were the same case for a while, because the field carried a
    /// serde `default` as well as a null-reader. Fixing the first direction is
    /// what quietly enabled the second.
    #[test]
    fn test11608_an_absent_description_is_not_read_as_empty() {
        let refusal = option(serde_json::json!({
            "id": "OPT_1", "name": "Todo", "color": "GRAY"
        }))
        .expect_err("a column with no description FIELD was read as having none");
        assert!(
            refusal.to_string().contains("description"),
            "the refusal does not say which field: {refusal}"
        );
    }

    /// TEST11609: a description that is there is kept exactly.
    ///
    /// The control. A reader that refused everything, or emptied everything,
    /// would satisfy one of the two tests above and lose the actual text.
    #[test]
    fn test11609_a_real_description_survives() {
        let read = option(serde_json::json!({
            "id": "OPT_1", "name": "Todo", "color": "GRAY",
            "description": "not started yet"
        }))
        .expect("a described column reads");
        assert_eq!(read.description, "not started yet");
    }
}