Skip to content

Voice-to-text dictation app with local (Nvidia Parakeet/Whisper) and cloud models (BYOK). Privacy-first and available cross-platform.

43.7 KB
Raw Blame
// GitHub connector (spec §5): search issues and pull requests (a query),
// create an issue and comment (approval cards), only in the repositories the
// OpenWhispr GitHub App is installed on. The model only prepares; the card's
// Send commits exactly what the card shows, re-checked here first.
const { createGithubApi } = require("./githubApi");
const { createGithubAuth } = require("./githubAuth");
const { createGithubInstallations, REFETCH_AFTER_MS } = require("./githubInstallations");
const { isTransportErrorCode } = require("./deliveryClassifier");
const { formBody } = require("./providerHttp");
const {
  MAX_TITLE_LENGTH,
  MAX_BODY_LENGTH,
  MAX_QUERY_LENGTH,
  MAX_RESULTS,
  SNIPPET_LENGTH,
  LINE_BREAK,
  nonEmptyString,
  characterCount,
  clarify,
} = require("./connectorText");

const MAX_LABELS = 10;
// GitHub's 256-character search limit counts only the words, never the
// qualifiers, and MAX_QUERY_LENGTH already keeps the words under it. What
// bounds the `repo:` list is the request URL: GitHub answered 250 qualifiers
// (a 5 KB URL) and failed with a 5xx near 8 KB. The budget is `q` as the
// request's query string encodes it (formBody, as githubApi's rest builds
// it), so with the rest of the URL it stays under the 5 KB that worked.
const MAX_SEARCH_QUERY_LENGTH = 4900;
// A read of the installed repository count for the status gives up after
// this long, so a hung read never blocks the next one.
const STATUS_REPOSITORIES_TIMEOUT_MS = 5000;

const STATES = new Set(["open", "all"]);
const TYPES = new Set(["issue", "pr", "any"]);
// A GitHub App user token can't search issues and pull requests together:
// GitHub refuses a `q` without one of these with a 422, so `any` is two
// searches.
const TYPE_QUALIFIERS = { issue: "is:issue", pr: "is:pull-request" };
// The scope is always the installed repos and the type is always the tool's
// own (the user's is:pr beside an added is:issue would match nothing), so
// the user's own scope and type qualifiers (negated, quoted, after NOT or
// opening a group too) are removed; every other qualifier (label:, author:,
// is:closed, …) passes through. A quoted phrase is words to GitHub, so
// nothing in one is removed.
const OWN_QUALIFIER =
  /(^|[\s(])(?:NOT\s+)*-?(?:(?:repo|org|user):(?:"[^"]*"?|[^\s)]*)|(?:is|type):(?:issue|pr|pull-request)(?=$|[\s)]))|"[^"]*"/gi;
// What a removed qualifier can leave behind, each removed until none is
// left: an empty group (with a NOT or - in front of it), AND or OR opening
// the query or a group, an operator closing one, and an operator before AND
// or OR. GitHub would refuse the query, and a NOT would negate whatever came
// next. GitHub's operators are upper case; "or" is a word.
const LEFTOVERS = [
  /(\s?)(?:\bNOT\s*|-)?\(\s*\)/g,
  /(^|\()\s*(?:AND|OR)(?=\s|\)|$)/g,
  /(^|[\s(])(?:AND|OR|NOT)(?=\s*(?:\)|$))/g,
  /(^|[\s(])(?:AND|OR|NOT)\s+(?=(?:AND|OR)(?:\s|\)|$))/g,
];
// A state the query names itself: state:open beside is:closed would match
// nothing.
const STATE_QUALIFIER =
  /(^|[\s(])-?(?:is:(?:open|closed|merged|unmerged)|state:(?:open|closed))(?=$|[\s)])/i;
const OWNER_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/;
const REPO_PATTERN = /^[A-Za-z0-9._-]{1,100}$/;
const NUMBER_PATTERN = /^[1-9]\d{0,9}$/;
const SHORT_REFERENCE = /^([^/\s#]+)\/([^/\s#]+)#(\d+)$/;
// `repo#12` or `#12`: a comment target whose repo is found among the
// installed ones.
const INSTALLED_REFERENCE = /^([^/\s#]*)#(\d+)$/;
const SEARCH_REPO_URL = /^https:\/\/api\.github\.com\/repos\/([^/]+)\/([^/]+)$/;
const SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,99}$/i;
// spec §6.1: no email address reaches the model, internationalized ones
// (josé@example.com, bob@exämple.com, a full-width @) included. A GitHub
// mention ("@alice", no local part before the @) is left alone.
const EMAIL_PATTERN = /[\p{L}\p{N}._%+-]+[@@][\p{L}\p{N}.-]+\.\p{L}{2,}/gu;

const INVALID_REFERENCE = { ok: false, errorCode: "invalid_reference" };

function collapseWhitespace(text) {
  return String(text ?? "")
    .replace(/\s+/g, " ")
    .trim();
}

function redactEmails(text) {
  return String(text ?? "").replace(EMAIL_PATTERN, "[email]");
}

// A search result's title or body as at most `max` characters, emails
// redacted. EMAIL_PATTERN takes quadratic time on a long run of word
// characters, and anyone can open an issue with a 65,536-character body, so
// only a window a few times `max` is redacted. The window ends at a space
// when it can, so no address is cut in two where the excerpt might show it.
function excerpt(text, max) {
  const collapsed = collapseWhitespace(text);
  // UTF-16 units: at least twice `max` characters, however many are emoji.
  const windowLength = max * 4;
  if (collapsed.length <= windowLength) return clip(redactEmails(collapsed), max);
  const space = collapsed.lastIndexOf(" ", windowLength);
  let end = space > max ? space : windowLength;
  // Never keep half a surrogate pair.
  if (/[\uD800-\uDBFF]/.test(collapsed[end - 1])) end -= 1;
  return clip(`${redactEmails(collapsed.slice(0, end))}…`, max);
}

// At most `max` characters (code points, so never half a surrogate pair),
// ending in "…" when anything was cut.
function clip(text, max) {
  if (text.length <= max) return text;
  const characters = [...text];
  return characters.length <= max ? text : `${characters.slice(0, max - 1).join("")}…`;
}

function validRepoName(name) {
  return REPO_PATTERN.test(name) && name !== "." && name !== "..";
}

function reference(owner, repo, number) {
  if (!OWNER_PATTERN.test(owner) || !validRepoName(repo)) return INVALID_REFERENCE;
  if (!NUMBER_PATTERN.test(number)) return INVALID_REFERENCE;
  return { ok: true, owner, repo, number: Number(number) };
}

// `repo#12` (`name` is "repo") or `#12` (`name` is "").
function parseInstalledReference(input) {
  const match = INSTALLED_REFERENCE.exec(typeof input === "string" ? input.trim() : "");
  if (!match || (match[1] && !validRepoName(match[1])) || !NUMBER_PATTERN.test(match[2])) {
    return INVALID_REFERENCE;
  }
  return { ok: true, name: match[1], number: Number(match[2]) };
}

/**
 * An issue or pull request the user named: `owner/repo#12`, or its
 * github.com link (`/issues/12` or `/pull/12`, with anything after it).
 */
function parseGithubTarget(input) {
  const raw = typeof input === "string" ? input.trim() : "";
  const short = SHORT_REFERENCE.exec(raw);
  if (short) return reference(short[1], short[2], short[3]);
  let url;
  try {
    url = new URL(raw);
  } catch {
    return INVALID_REFERENCE;
  }
  if (
    url.protocol !== "https:" ||
    url.hostname.toLowerCase() !== "github.com" ||
    url.port ||
    url.username ||
    url.password
  ) {
    return INVALID_REFERENCE;
  }
  const [, owner, repo, kind, number] = url.pathname.split("/");
  if (kind !== "issues" && kind !== "pull") return INVALID_REFERENCE;
  return reference(owner ?? "", repo ?? "", number ?? "");
}

// A quote left open would make the rest of the query, the qualifiers added
// after the words included, one phrase; the last quote is dropped.
function withoutOpenQuote(text) {
  if ((text.match(/"/g) ?? []).length % 2 === 0) return text;
  const last = text.lastIndexOf('"');
  return text.slice(0, last) + text.slice(last + 1);
}

// A parenthesis without its pair (the user's own, or the ")" a removed
// qualifier's value stopped at) is dropped: an open group would take in the
// qualifiers added after the words. Parentheses in a quoted phrase are words.
function balancedParentheses(text) {
  const characters = [...text];
  const unpaired = [];
  const open = [];
  let quoted = false;
  characters.forEach((character, index) => {
    if (character === '"') quoted = !quoted;
    else if (quoted) return;
    else if (character === "(") open.push(index);
    else if (character === ")") {
      if (open.length > 0) open.pop();
      else unpaired.push(index);
    }
  });
  const dropped = new Set([...unpaired, ...open]);
  return characters.filter((_, index) => !dropped.has(index)).join("");
}

function withoutLeftovers(text) {
  let previous;
  let current = text;
  do {
    previous = current;
    for (const pattern of LEFTOVERS) current = current.replace(pattern, "$1 ");
  } while (current !== previous);
  return collapseWhitespace(current);
}

/**
 * The `q` for GET /search/issues: the user's words without their own scope
 * qualifiers, the type (`issue` or `pr`) and state (unless the words name
 * one), then one `repo:` per installed repo in the order given (most
 * recently updated first) while `q`, encoded as the request sends it, stays
 * within MAX_SEARCH_QUERY_LENGTH. `truncated` says some repos were left out.
 */
function buildSearchQuery({ query, type, state = "open", repos = [] }) {
  const unscoped = withoutOpenQuote(String(query ?? "")).replace(OWN_QUALIFIER, (match, lead) =>
    // A quoted phrase stays as it is.
    lead === undefined ? match : `${lead} `
  );
  const words = withoutLeftovers(balancedParentheses(unscoped));
  const stateQualifier = state === "all" || STATE_QUALIFIER.test(words) ? "" : "state:open";
  let q = [words, TYPE_QUALIFIERS[type], stateQualifier].filter(Boolean).join(" ");
  const searched = [];
  for (const fullName of repos) {
    const next = `${q}${q ? " " : ""}repo:${fullName}`;
    if (formBody({ q: next }).length > MAX_SEARCH_QUERY_LENGTH) break;
    q = next;
    searched.push(fullName);
  }
  // Without a single repo: qualifier the search would cover every repo the
  // user can see, not only the installed ones.
  if (searched.length === 0) return { ok: false, errorCode: "too_long" };
  return { ok: true, q, repos: searched, truncated: searched.length < repos.length };
}

// English for the model; the card and the tool step show translated copy by
// errorCode.
function failureMessage(errorCode) {
  switch (errorCode) {
    case "reconnect_needed":
      return "GitHub needs to be reconnected under Settings → Integrations → Connectors.";
    case "connection_changed":
      return "The GitHub connection changed, so nothing was done.";
    case "rate_limited":
      return "GitHub is limiting requests right now. Try again later.";
    case "no_repositories":
      return "The OpenWhispr GitHub App isn't installed on any repository yet. Tell the user to choose repositories for it in Settings → Integrations → Connectors.";
    case "forbidden":
      return "GitHub refused: the user may not have permission for that in this repository.";
    case "not_found":
      return "GitHub couldn't find that issue or pull request.";
    case "issues_disabled":
      return "Issues are turned off in that repository.";
    case "archived":
      return "That repository is archived, so it can't take new issues or comments.";
    case "invalid":
      return "GitHub couldn't accept this as written.";
    case "too_long":
      return `Keep the title to ${MAX_TITLE_LENGTH} characters and the text to ${MAX_BODY_LENGTH} characters or fewer.`;
    case "invalid_reference":
      return "Give the issue or pull request as owner/repo#123, repo#123, #123 or its github.com link.";
    case "credential_save_failed":
      return "Couldn't save the refreshed GitHub login.";
    case "not_configured":
      return "GitHub isn't available in this build of OpenWhispr.";
    case "network":
      return "Couldn't reach GitHub.";
    default:
      if (isTransportErrorCode(errorCode)) return "Couldn't reach GitHub.";
      return /^http_5\d\d$/.test(errorCode)
        ? "GitHub had a problem answering. Try again later."
        : "GitHub refused the request.";
  }
}

function failed(errorCode, message = failureMessage(errorCode)) {
  return { status: "failed", errorCode, message };
}

function commitFailed(errorCode, message = failureMessage(errorCode)) {
  return { state: "failed", errorCode, message };
}

// A lookup's failure, with its own message when it has one.
function failedWith(failure) {
  return failed(failure.errorCode, failure.message);
}

function commitFailedWith(failure) {
  return commitFailed(failure.errorCode, failure.message);
}

// The distinct names, in the order given.
function labelList(value) {
  const seen = new Set();
  const labels = [];
  for (const raw of Array.isArray(value) ? value : []) {
    if (typeof raw !== "string") continue;
    const label = raw.trim();
    const key = label.toLowerCase();
    if (!label || seen.has(key)) continue;
    seen.add(key);
    labels.push(label);
  }
  return labels;
}

function repoPath(repo) {
  return `/repos/${encodeURIComponent(repo.owner)}/${encodeURIComponent(repo.name)}`;
}

function findInstalled(repos, owner, name) {
  const wanted = `${owner}/${name}`.toLowerCase();
  return repos.find((repo) => repo.fullName.toLowerCase() === wanted) ?? null;
}

function searchItem(raw, fullName) {
  if (!Number.isInteger(raw?.number) || !nonEmptyString(raw?.html_url)) return null;
  const pullRequest = raw.pull_request && typeof raw.pull_request === "object";
  const state = pullRequest && raw.pull_request.merged_at ? "merged" : raw.state;
  return {
    reference: `${fullName}#${raw.number}`,
    isPullRequest: Boolean(pullRequest),
    title: excerpt(raw.title, MAX_TITLE_LENGTH),
    state: state === "closed" || state === "merged" ? state : "open",
    url: raw.html_url,
    updatedAt: nonEmptyString(raw.updated_at) ? raw.updated_at : null,
    assignee: nonEmptyString(raw.assignee?.login) ? raw.assignee.login : null,
    author: nonEmptyString(raw.user?.login) ? raw.user.login : null,
    labels: (Array.isArray(raw.labels) ? raw.labels : [])
      .map((label) => (typeof label === "string" ? label : label?.name))
      .filter(nonEmptyString)
      // GitHub caps a label name at 50 characters, so the quadratic pattern
      // has nothing long to run on.
      .map(redactEmails),
    snippet: excerpt(raw.body, SNIPPET_LENGTH),
  };
}

function createGithubConnector({
  api,
  auth,
  installations,
  credentials,
  getSlug = () => null,
  notifyStatusChanged = () => {},
  statusTimeoutMs = STATUS_REPOSITORIES_TIMEOUT_MS,
}) {
  // The installed repository count per OpenWhispr account, for its current
  // login ({ generation, count }), and the reads in flight. The manager asks
  // every connector for its status together, so the status answers with the
  // last count read and never waits on GitHub: Slack's Connect or the first
  // chat turn would wait with it.
  const repoCounts = new Map();
  const countReads = new Set();
  const countKey = (binding) => `${binding.ownerAccountId}:${binding.generation}`;

  function manageUrl() {
    const slug = getSlug();
    return typeof slug === "string" && SLUG_PATTERN.test(slug)
      ? `https://github.com/apps/${slug}/installations/new`
      : null;
  }

  // `truncated`: the installations listed more repositories than OpenWhispr
  // reads, so the repo may be installed after all.
  function notInstalled(fullName, truncated = false) {
    if (truncated) {
      return {
        errorCode: "repo_unlisted",
        message: `The OpenWhispr GitHub App isn't installed on ${fullName}, as far as OpenWhispr can tell: it reads the first 1,000 repositories of each installation. Ask the user to check the name.`,
      };
    }
    const installUrl = manageUrl();
    const message = `The OpenWhispr GitHub App isn't installed on ${fullName}.`;
    return {
      errorCode: "not_installed",
      message: installUrl
        ? `${message} Tell the user to install it on that repository: ${installUrl}`
        : `${message} Tell the user to install it on that repository from Settings → Integrations → Connectors.`,
    };
  }

  // One action's requests share this: the bound login and its current token.
  // A 401 means GitHub refused and did nothing, so it is refreshed once under
  // the same login and asked again; a second 401 means the login is gone.
  async function call(session, send) {
    const first = await send(session.token);
    if (first.ok || first.errorCode !== "unauthorized") return first;
    const refreshed = await auth.refreshRejected(session.binding, session.token);
    if (!refreshed.ok) return { ok: false, outcome: "failed", errorCode: refreshed.errorCode };
    session.token = refreshed.token;
    const second = await send(session.token);
    if (!second.ok && second.errorCode === "unauthorized") {
      return {
        ok: false,
        outcome: "failed",
        errorCode: auth.markReconnect(session.binding).errorCode,
      };
    }
    return second;
  }

  async function openSession(binding) {
    const access = await auth.getAccessToken(binding);
    if (!access.ok) return { failure: { errorCode: access.errorCode } };
    return { session: { binding, token: access.token, login: access.credential.login } };
  }

  // With `wanted` ({ owner, repo }), a list without that repo is read once
  // more, like one with no repo at all: the App may have just been installed.
  async function installedRepos(session, wanted) {
    const found = wanted
      ? (repos) => findInstalled(repos, wanted.owner, wanted.repo) !== null
      : (repos) => repos.length > 0;
    const listed = await call(session, (token) =>
      installations.listFinding(session.binding, token, found)
    );
    if (!listed.ok) return { failure: { errorCode: listed.errorCode } };
    if (listed.repos.length === 0) return { failure: { errorCode: "no_repositories" } };
    return { repos: listed.repos, truncated: listed.truncated === true };
  }

  // An installed repo that can take new issues and comments, or why not.
  function writableRepo(repo, fullName, truncated) {
    if (!repo) return { failure: notInstalled(fullName, truncated) };
    if (repo.archived) {
      return {
        failure: {
          errorCode: "archived",
          message: `${repo.fullName} is archived, so it can't take new issues or comments.`,
        },
      };
    }
    return { repo };
  }

  // writableRepo, with issues turned on. A repo with issues off still takes
  // comments on its pull requests, so only a new issue checks it.
  function issueRepo(repo, fullName, truncated) {
    const writable = writableRepo(repo, fullName, truncated);
    if (writable.failure || repo.hasIssues) return writable;
    return {
      failure: {
        errorCode: "issues_disabled",
        message: `Issues are turned off in ${repo.fullName}, so it can't take a new issue.`,
      },
    };
  }

  async function resolveRepo(session, input, options) {
    const resolved = await call(session, (token) =>
      installations.resolveRepo(session.binding, token, input, options)
    );
    if (resolved.ok) return { repo: resolved.repo };
    if (resolved.clarification) return { clarification: resolved.clarification };
    if (resolved.errorCode === "not_installed" || resolved.errorCode === "repo_unlisted") {
      return { failure: notInstalled(input.trim(), resolved.errorCode === "repo_unlisted") };
    }
    return { failure: { errorCode: resolved.errorCode, message: resolved.message } };
  }

  // GitHub answers 410 both when a repo's issues are off and when the issue
  // was deleted; the installed repo says which. Null for any other answer.
  function deletedIssue(result, repo, number) {
    if (result.errorCode !== "issues_disabled" || !repo.hasIssues) return null;
    return { errorCode: "not_found", message: `${repo.fullName}#${number} was deleted.` };
  }

  // GitHub answers 403 or 404 for a repo the App isn't installed on (any
  // more), and 403 for one archived since the list was read: the
  // installations are read again to tell those apart.
  async function refusal(session, result, repo) {
    if (result.errorCode === "forbidden" || result.errorCode === "not_found") {
      installations.clear(session.binding);
      const listed = await call(session, (token) => installations.list(session.binding, token));
      if (listed.ok) {
        const fresh = findInstalled(listed.repos, repo.owner, repo.name);
        const writable = writableRepo(fresh, repo.fullName, listed.truncated === true);
        if (writable.failure) return writable.failure;
      }
    }
    return { errorCode: result.errorCode };
  }

  // The issue or PR a comment goes on, in an installed repo, still open to
  // comments. Read at prepare and again at Send.
  async function readTarget(session, target) {
    const installed = await installedRepos(session, target);
    if (installed.failure) return installed;
    const writable = writableRepo(
      findInstalled(installed.repos, target.owner, target.repo),
      `${target.owner}/${target.repo}`,
      installed.truncated
    );
    if (writable.failure) return writable;
    const { repo } = writable;
    const read = await call(session, (token) =>
      api.rest("GET", `${repoPath(repo)}/issues/${target.number}`, { token })
    );
    if (!read.ok) {
      return {
        failure: deletedIssue(read, repo, target.number) ?? (await refusal(session, read, repo)),
      };
    }
    const issue = read.data;
    if (!Number.isInteger(issue?.number) || !nonEmptyString(issue?.html_url)) {
      return {
        failure: { errorCode: "bad_response", message: "GitHub's answer couldn't be read." },
      };
    }
    // fetch follows redirects, and GitHub 301s a transferred issue: the
    // reply can be a different issue than the one asked for (another
    // number, another repo, another title). Never trust it for the
    // destination or the payload without checking it answered the number
    // asked for, in this repo.
    const expectedIssueUrl =
      `https://github.com/${repo.fullName}/issues/${target.number}`.toLowerCase();
    const expectedPullUrl =
      `https://github.com/${repo.fullName}/pull/${target.number}`.toLowerCase();
    const actualUrl = issue.html_url.toLowerCase();
    if (
      issue.number !== target.number ||
      (actualUrl !== expectedIssueUrl && actualUrl !== expectedPullUrl)
    ) {
      return {
        failure: {
          errorCode: "not_found",
          message: `GitHub couldn't find that issue or pull request in ${repo.fullName}; it may have moved.`,
        },
      };
    }
    const destination = `${repo.fullName}#${target.number}`;
    // GitHub still takes comments on a locked conversation from people who
    // can push to the repo.
    if (issue.locked === true && !repo.canPush) {
      return {
        failure: {
          errorCode: "locked",
          message: `The conversation on ${destination} is locked, so it can't take new comments.`,
        },
      };
    }
    return {
      repo,
      destination,
      issue: {
        number: target.number,
        title: typeof issue.title === "string" ? issue.title : "",
        isPullRequest: Boolean(issue.pull_request),
        url: issue.html_url,
      },
    };
  }

  // One search per type (`any` is both), each limited to `repos`.
  async function runSearches(session, { query, type, state }, repos) {
    const searches = (type === "any" ? ["issue", "pr"] : [type]).map((kind) =>
      buildSearchQuery({ query, type: kind, state, repos: repos.map((repo) => repo.fullName) })
    );
    if (searches.some((built) => !built.ok)) {
      return {
        failure: {
          errorCode: "too_long",
          message:
            "The search is too long to limit to the user's repositories. Ask for a shorter search.",
        },
      };
    }
    const pages = await Promise.all(
      searches.map((built) =>
        call(session, (token) =>
          api.rest("GET", "/search/issues", {
            token,
            query: { q: built.q, sort: "updated", order: "desc", per_page: MAX_RESULTS },
          })
        )
      )
    );
    const failure = pages.find((found) => !found.ok);
    // A transport failure (offline, DNS, reset, timeout) would otherwise
    // reach normalizeQueryResult as an unrecognized code and get rewritten to
    // generic "query_failed" copy; "network" is a code it accepts as is.
    if (failure) {
      return {
        failure: {
          errorCode: isTransportErrorCode(failure.errorCode) ? "network" : failure.errorCode,
        },
      };
    }
    return { searches, pages };
  }

  // The search over the repo named, or every installed one. `truncated`:
  // the installations listed more repos than OpenWhispr reads, so some went
  // unsearched.
  async function scopedSearch(session, repo, params) {
    let scope;
    if (repo) {
      const resolved = await resolveRepo(session, repo);
      if (!resolved.repo) return resolved;
      scope = { repos: [resolved.repo], truncated: false };
    } else {
      scope = await installedRepos(session);
      if (scope.failure) return scope;
    }
    const run = await runSearches(session, params, scope.repos);
    return run.failure ? run : { ...run, truncated: scope.truncated };
  }

  async function searchIssues(args, binding) {
    const query = typeof args?.query === "string" ? args.query.trim() : "";
    if (!query) return clarify("Ask the user what to search GitHub for.");
    if (characterCount(query) > MAX_QUERY_LENGTH) {
      return failed("too_long", `Keep the search to ${MAX_QUERY_LENGTH} characters or fewer.`);
    }
    const state = args?.state ?? "open";
    const type = args?.type ?? "any";
    // Refused before GitHub is asked: the model's own input, not GitHub's
    // verdict.
    if (!STATES.has(state) || !TYPES.has(type)) {
      return failed("invalid_input", "state is open or all, and type is issue, pr or any.");
    }
    const opened = await openSession(binding);
    if (opened.failure) return failedWith(opened.failure);
    const { session } = opened;
    const repo = typeof args?.repo === "string" ? args.repo.trim() : "";
    const params = { query, type, state };

    let run = await scopedSearch(session, repo, params);
    // GitHub answers 422 when q names a repo the user can no longer search
    // (unticked on the install page, deleted, access lost), which the 60 s
    // cache can still list: the repos are read fresh and searched once more.
    if (run.failure?.errorCode === "invalid") {
      installations.clear(session.binding);
      run = await scopedSearch(session, repo, params);
    }
    if (run.clarification) return clarify(run.clarification.message, run.clarification.candidates);
    if (run.failure) return failedWith(run.failure);
    const { searches, pages } = run;
    const items = [];
    let truncated = run.truncated;
    searches.forEach((built, index) => {
      const found = pages[index];
      const searched = new Map(built.repos.map((fullName) => [fullName.toLowerCase(), fullName]));
      const raws = Array.isArray(found.data?.items) ? found.data.items : [];
      for (const raw of raws) {
        const match = SEARCH_REPO_URL.exec(raw?.repository_url ?? "");
        // GitHub may answer with repos the user can see but didn't install
        // the App on; those never reach the model.
        const fullName = match ? searched.get(`${match[1]}/${match[2]}`.toLowerCase()) : null;
        const item = fullName ? searchItem(raw, fullName) : null;
        if (item) items.push(item);
      }
      const total = found.data?.total_count;
      truncated ||=
        built.truncated ||
        found.data?.incomplete_results === true ||
        (Number.isInteger(total) && total > raws.length);
    });
    // Most recently updated first across both searches, as each one is.
    items.sort((a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? ""));
    return {
      status: "ok",
      items: items.slice(0, MAX_RESULTS),
      truncated: truncated || items.length > MAX_RESULTS,
    };
  }

  async function prepareIssue(args, binding) {
    // A title is one line: line breaks become spaces.
    const title = typeof args?.title === "string" ? args.title.replace(/[\r\n]+/g, " ").trim() : "";
    if (!title) return clarify("Ask the user what the issue's title should be.");
    if (characterCount(title) > MAX_TITLE_LENGTH) {
      return failed("too_long", `Keep the title to ${MAX_TITLE_LENGTH} characters or fewer.`);
    }
    const body = typeof args?.body === "string" ? args.body : "";
    if (characterCount(body) > MAX_BODY_LENGTH) {
      return failed("too_long", `Keep the description to ${MAX_BODY_LENGTH} characters or fewer.`);
    }
    const requested = labelList(args?.labels);
    // Never trimmed to fit: the card would show fewer labels than asked for
    // without saying so.
    if (requested.length > MAX_LABELS) {
      return failed("too_many_labels", `Pick at most ${MAX_LABELS} labels for one issue.`);
    }

    const opened = await openSession(binding);
    if (opened.failure) return failedWith(opened.failure);
    const { session } = opened;
    const resolved = await resolveRepo(session, typeof args?.repo === "string" ? args.repo : "", {
      forNewIssue: true,
    });
    if (resolved.clarification) {
      return clarify(
        `${resolved.clarification.message} The issue can go in any of these.`,
        resolved.clarification.candidates
      );
    }
    if (resolved.failure) return failedWith(resolved.failure);
    const writable = issueRepo(resolved.repo);
    if (writable.failure) return failedWith(writable.failure);
    const { repo } = writable;

    const labels = [];
    const dropped = [];
    if (requested.length > 0) {
      const listed = await call(session, (token) =>
        api.restAll(`${repoPath(repo)}/labels`, { token, query: { per_page: 100 } })
      );
      if (!listed.ok) {
        const refused = await refusal(session, listed, repo);
        // A 404 here is about the repo, never an issue or pull request.
        return failedWith(
          refused.errorCode === "not_found"
            ? {
                errorCode: "labels_unavailable",
                message: `Couldn't read the labels in ${repo.fullName}. Try again, or create the issue without labels.`,
              }
            : refused
        );
      }
      const existing = new Map(
        listed.items
          .filter((label) => nonEmptyString(label?.name))
          .map((label) => [label.name.toLowerCase(), label.name])
      );
      for (const label of requested) {
        const match = existing.get(label.toLowerCase());
        if (match) labels.push(match);
        // Only the first 1,000 labels were read, so this one may exist all
        // the same: it goes as asked, and the card lists it with the others
        // rather than saying the repo doesn't have it.
        else if (listed.truncated) labels.push(label);
        else dropped.push(label);
      }
    }

    const notes = [];
    if (labels.length > 0) {
      notes.push({
        key: "connectors.approval.issue.notes.labels",
        values: { labels: labels.join(", ") },
      });
    }
    if (dropped.length > 0) {
      notes.push({
        key: "connectors.approval.issue.notes.droppedLabels",
        values: { destination: repo.fullName, labels: dropped.join(", ") },
      });
    }
    // GitHub silently drops labels when the user can't push to the repo.
    if (labels.length > 0 && !repo.canPush) {
      notes.push({ key: "connectors.approval.github.notes.labelsMayNotApply" });
    }

    return {
      status: "ready",
      payload: { owner: repo.owner, repo: repo.name, title, body, labels },
      preview: {
        verbKey: "issue",
        destinationLabel: repo.fullName,
        accountLabel: `@${session.login}`,
        body,
        fields: { title, body },
        notes,
      },
    };
  }

  // The { owner, repo, number } a parsed target names, finding the repo of
  // `repo#12` or `#12` among the installed ones.
  async function commentTarget(session, parsed) {
    if (parsed.owner) return { target: parsed };
    const resolved = await resolveRepo(session, parsed.name);
    if (resolved.clarification) {
      return {
        clarification: clarify(
          `${resolved.clarification.message} The comment goes on #${parsed.number} there.`,
          resolved.clarification.candidates
        ),
      };
    }
    if (resolved.failure) return resolved;
    const { repo } = resolved;
    return { target: { owner: repo.owner, repo: repo.name, number: parsed.number } };
  }

  async function prepareComment(args, binding) {
    const full = parseGithubTarget(args?.target);
    const parsed = full.ok ? full : parseInstalledReference(args?.target);
    if (!parsed.ok) return failed("invalid_reference");
    const body = typeof args?.body === "string" ? args.body : "";
    if (!body.trim()) return clarify("Ask the user what the comment should say.");
    if (characterCount(body) > MAX_BODY_LENGTH) {
      return failed("too_long", `Keep the comment to ${MAX_BODY_LENGTH} characters or fewer.`);
    }
    const opened = await openSession(binding);
    if (opened.failure) return failedWith(opened.failure);
    const { session } = opened;
    const found = await commentTarget(session, parsed);
    if (found.clarification) return found.clarification;
    if (found.failure) return failedWith(found.failure);
    const read = await readTarget(session, found.target);
    if (read.failure) return failedWith(read.failure);

    const notes = [
      {
        key: "connectors.approval.comment.notes.targetTitle",
        values: { title: clip(collapseWhitespace(read.issue.title), MAX_TITLE_LENGTH) },
      },
    ];
    if (read.issue.isPullRequest)
      notes.push({ key: "connectors.approval.github.notes.pullRequest" });
    return {
      status: "ready",
      payload: { owner: read.repo.owner, repo: read.repo.name, number: read.issue.number, body },
      preview: {
        verbKey: "comment",
        destinationLabel: read.destination,
        accountLabel: `@${session.login}`,
        body,
        fields: { body },
        notes,
      },
    };
  }

  // The card's title and description, over what prepare stored.
  function issueEdits(payload, edits) {
    const changes = edits ?? {};
    const rawTitle = typeof changes.title === "string" ? changes.title : payload.title;
    const body = typeof changes.body === "string" ? changes.body : payload.body;
    // Every check from prepare again, before anything reaches GitHub.
    if (LINE_BREAK.test(rawTitle)) {
      return commitFailed("invalid", "The title must be a single line, so nothing was created.");
    }
    const title = rawTitle.trim();
    if (!title) return commitFailed("invalid", "The issue has no title, so nothing was created.");
    if (characterCount(title) > MAX_TITLE_LENGTH || characterCount(body) > MAX_BODY_LENGTH) {
      return commitFailed("too_long");
    }
    return { title, body };
  }

  async function createIssue(payload, edits, binding) {
    const checked = issueEdits(payload, edits);
    if (checked.state === "failed") return checked;
    const opened = await openSession(binding);
    if (opened.failure) return commitFailedWith(opened.failure);
    const { session } = opened;
    const installed = await installedRepos(session, payload);
    if (installed.failure) return commitFailedWith(installed.failure);
    const writable = issueRepo(
      findInstalled(installed.repos, payload.owner, payload.repo),
      `${payload.owner}/${payload.repo}`,
      installed.truncated
    );
    if (writable.failure) return commitFailedWith(writable.failure);
    const { repo } = writable;
    const created = await call(session, (token) =>
      api.rest("POST", `${repoPath(repo)}/issues`, {
        token,
        body: {
          title: checked.title,
          body: checked.body,
          ...(payload.labels.length > 0 ? { labels: payload.labels } : {}),
        },
      })
    );
    const checkUrl = `https://github.com/${repo.fullName}/issues`;
    if (created.ok) {
      const { number, html_url: url } = created.data ?? {};
      if (Number.isInteger(number) && nonEmptyString(url)) {
        return { state: "sent", url, resultLabel: `${repo.fullName}#${number}` };
      }
      return { state: "unknown", errorCode: "bad_response", checkUrl };
    }
    if (created.outcome === "failed") {
      const refused = await refusal(session, created, repo);
      // GitHub answers 404 to a write the user may not make there, and the
      // repo is still installed: no issue is missing.
      if (refused.errorCode === "not_found") {
        return commitFailed(
          "forbidden",
          `GitHub refused: the user may not be able to create issues in ${repo.fullName}.`
        );
      }
      return commitFailedWith(refused);
    }
    // GitHub has no idempotency key, so an uncertain create is never repeated.
    return { state: "unknown", errorCode: created.errorCode, checkUrl };
  }

  async function postComment(payload, edits, binding) {
    const body = typeof edits?.body === "string" ? edits.body : payload.body;
    if (!body.trim())
      return commitFailed("invalid", "The comment is empty, so nothing was posted.");
    if (characterCount(body) > MAX_BODY_LENGTH) return commitFailed("too_long");
    const opened = await openSession(binding);
    if (opened.failure) return commitFailedWith(opened.failure);
    const { session } = opened;
    const read = await readTarget(session, {
      owner: payload.owner,
      repo: payload.repo,
      number: payload.number,
    });
    if (read.failure) return commitFailedWith(read.failure);
    const posted = await call(session, (token) =>
      api.rest("POST", `${repoPath(read.repo)}/issues/${read.issue.number}/comments`, {
        token,
        body: { body },
      })
    );
    if (posted.ok) {
      return nonEmptyString(posted.data?.html_url)
        ? { state: "sent", url: posted.data.html_url }
        : { state: "unknown", errorCode: "bad_response", checkUrl: read.issue.url };
    }
    if (posted.outcome === "failed") {
      return commitFailedWith(
        deletedIssue(posted, read.repo, read.issue.number) ??
          (await refusal(session, posted, read.repo))
      );
    }
    return { state: "unknown", errorCode: posted.errorCode, checkUrl: read.issue.url };
  }

  function bindingFor(ownerAccountId, entry) {
    return {
      ownerAccountId,
      accountId: String(entry.credential.userId),
      generation: entry.generation,
    };
  }

  // A list younger than REFETCH_AFTER_MS is reused, so the status
  // broadcasts that follow each other don't each read every repository, and
  // an install picked on GitHub's own page moments ago still shows.
  async function countRepos(binding, signal) {
    const opened = await openSession(binding);
    let failure = opened.failure;
    if (!failure) {
      if (signal.aborted) return null;
      const listed = await call(opened.session, (token) =>
        installations.list(binding, token, { signal, maxAgeMs: REFETCH_AFTER_MS })
      );
      // More repositories are installed than OpenWhispr reads (1,000 each).
      if (listed.ok) return `${listed.repos.length}${listed.truncated ? "+" : ""}`;
      failure = listed;
    }
    // The refresh this read needed was refused and the login is saved as
    // needing a reconnect, but Settings and the offered tools only see that
    // in a status read. Announced even after the read was given up on.
    if (failure.errorCode === "reconnect_needed") notifyStatusChanged();
    return null;
  }

  // The installed repo count, within statusTimeoutMs. Best effort: a
  // failure or a timeout is null, never "0".
  async function repoCount(binding) {
    const signal = AbortSignal.timeout(statusTimeoutMs);
    const gaveUp = new Promise((resolve) => {
      signal.addEventListener("abort", () => resolve(null), { once: true });
    });
    return Promise.race([countRepos(binding, signal).catch(() => null), gaveUp]);
  }

  // The last read for this login ({ count }, a null count when it failed),
  // or null before one has finished.
  function lastRead(binding) {
    const last = repoCounts.get(binding.ownerAccountId);
    return last?.generation === binding.generation ? last : null;
  }

  // Reads the count again in the background and announces a changed one,
  // and the first read for a login even when it failed, so the row stops
  // waiting on it. A later count that couldn't be read keeps the last one.
  function refreshRepoCount(binding) {
    const key = countKey(binding);
    if (countReads.has(key)) return;
    countReads.add(key);
    void repoCount(binding).then((count) => {
      countReads.delete(key);
      const last = lastRead(binding);
      if (last && (count === null || count === last.count)) return;
      repoCounts.set(binding.ownerAccountId, { generation: binding.generation, count });
      notifyStatusChanged();
    });
  }

  return {
    id: "github",
    actions: {
      search_issues: { kind: "query" },
      create_issue: { kind: "approval", editable: { title: "line", body: "text" } },
      comment: { kind: "approval", editable: { body: "text" } },
    },

    async getStatus() {
      const url = manageUrl();
      const withManage = (status) => (url ? { ...status, manageUrl: url } : status);
      const ownerAccountId = credentials.activeAccountId();
      const entry = credentials.read(ownerAccountId, "github");
      if (!entry) {
        return withManage({
          connected: false,
          // Without the App's slug there's no way to choose repositories, and
          // every action would end in no_repositories.
          configured: auth.isConfigured() && url !== null,
          accountLabel: null,
          workspaceLabel: null,
          needsReconnect: false,
        });
      }
      // A login always reports configured, so Disconnect stays reachable.
      const status = { ...auth.statusOf(entry.credential), configured: true };
      if (status.needsReconnect) return withManage(status);
      const binding = bindingFor(ownerAccountId, entry);
      refreshRepoCount(binding);
      const last = lastRead(binding);
      // Pending until the first read for this login (after a connect, or
      // at launch) finishes, so the row doesn't offer to choose repositories
      // that may be installed already.
      return withManage({
        ...status,
        workspaceLabel: last?.count ?? null,
        ...(last ? {} : { workspaceLabelPending: true }),
      });
    },

    async getBinding() {
      const ownerAccountId = credentials.activeAccountId();
      const entry = credentials.read(ownerAccountId, "github");
      return entry ? bindingFor(ownerAccountId, entry) : null;
    },

    async query(action, args, { binding } = {}) {
      if (action !== "search_issues") return failed("unknown_action", "Unknown GitHub action.");
      return searchIssues(args, binding);
    },

    async prepare(action, args, { binding } = {}) {
      if (action === "create_issue") return prepareIssue(args, binding);
      if (action === "comment") return prepareComment(args, binding);
      return failed("unknown_action", "Unknown GitHub action.");
    },

    async commit(action, payload, edits, { binding } = {}) {
      if (action === "create_issue") return createIssue(payload, edits, binding);
      if (action === "comment") return postComment(payload, edits, binding);
      return commitFailed("unknown_action", "Unknown GitHub action.");
    },

    authorize: (options) => auth.authorize(options),
    // Only when every login is going (account deletion, Reset app data).
    // GitHub's secret-free revoke is its endpoint for exposed credentials and
    // emails the user, which reads as a leak after an ordinary Disconnect or
    // reconnect; those only delete the login here, and the App's
    // authorization stays on github.com either way.
    revoke: async (credential, { removingAll = false } = {}) => {
      if (removingAll) await auth.revoke(credential);
    },
  };
}

// Foundation §9.3: one api, auth and installations instance for every
// consumer, so concurrent actions share one single-flight refresh (GitHub's
// refresh tokens are single-use).
function buildGithubConnector(deps) {
  const api = createGithubApi({ fetchImpl: deps.fetch });
  const auth = createGithubAuth({
    api,
    credentials: deps.credentials,
    getClientId: () => deps.env?.GITHUB_APP_CLIENT_ID,
    broadcast: deps.broadcast,
    logger: deps.logger,
  });
  return createGithubConnector({
    api,
    auth,
    installations: createGithubInstallations({ api }),
    credentials: deps.credentials,
    getSlug: () => deps.env?.GITHUB_APP_SLUG,
    notifyStatusChanged: deps.notifyStatusChanged,
  });
}

module.exports = {
  createGithubConnector,
  buildGithubConnector,
  parseGithubTarget,
  buildSearchQuery,
  STATUS_REPOSITORIES_TIMEOUT_MS,
  MAX_TITLE_LENGTH,
  MAX_BODY_LENGTH,
  MAX_LABELS,
  MAX_RESULTS,
  SNIPPET_LENGTH,
};