@stacksjs/github 0.70.53 → 0.70.55

package/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2023 Open Web Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/github",
   "type": "module",
-  "version": "0.70.53",
+  "version": "0.70.55",
   "description": "GitHub API client used by Stacks framework features (dashboard CI surface, notifications, runner alerts).",
   "author": "Chris Breuer",
   "contributors": [
@@ -36,7 +36,8 @@
   "types": "dist/index.d.ts",
   "files": [
     "README.md",
-    "dist"
+    "dist",
+    "src"
   ],
   "scripts": {
     "build": "bun build.ts",

package/src/bots.ts

@@ -0,0 +1,34 @@
+import { ghFetch, GITHUB_API } from './client'
+
+/**
+ * Count open PRs authored by a GitHub App across every repo in an org.
+ * Returns a map keyed by `owner/repo` so callers can attribute counts back
+ * to the right repo card. Used to surface Renovate / GitHub Actions bot
+ * traffic in the dashboard.
+ */
+export async function fetchBotPRCounts(org: string, authorSlug: string): Promise<Map<string, number>> {
+  const counts = new Map<string, number>()
+  let page = 1
+
+  while (true) {
+    const q = `is:pr is:open org:${org} author:app/${authorSlug}`
+    const res = await ghFetch(`${GITHUB_API}/search/issues?q=${encodeURIComponent(q)}&per_page=100&page=${page}`)
+    if (!res.ok)
+      break
+
+    const data = await res.json() as { items: Array<{ repository_url: string }>, total_count: number }
+    if (!data.items || data.items.length === 0)
+      break
+
+    for (const item of data.items) {
+      const fullName = item.repository_url.replace(`${GITHUB_API}/repos/`, '')
+      counts.set(fullName, (counts.get(fullName) ?? 0) + 1)
+    }
+
+    if (data.items.length < 100)
+      break
+    page++
+  }
+
+  return counts
+}

package/src/client.ts

@@ -0,0 +1,64 @@
+export const GITHUB_API = 'https://api.github.com'
+
+function getToken(): string {
+  const token = process.env.GITHUB_TOKEN
+  if (!token)
+    throw new Error('GITHUB_TOKEN environment variable is required')
+  return token
+}
+
+export function ghHeaders(): Record<string, string> {
+  return {
+    'Authorization': `Bearer ${getToken()}`,
+    'Accept': 'application/vnd.github+json',
+    'X-GitHub-Api-Version': '2022-11-28',
+  }
+}
+
+/**
+ * `fetch` against the GitHub API that retries on secondary rate limits.
+ *
+ * GitHub signals back-off via either a `Retry-After` header (preferred) or
+ * an `x-ratelimit-reset` epoch second. The retry budget is bounded so a
+ * permanently rate-limited token doesn't hang callers indefinitely.
+ */
+export async function ghFetch(url: string, attempt = 0): Promise<Response> {
+  const res = await fetch(url, { headers: ghHeaders() })
+  if (res.ok || attempt >= 3)
+    return res
+
+  const isRateLimit
+    = res.status === 429
+      || (res.status === 403 && (res.headers.get('x-ratelimit-remaining') === '0' || res.headers.get('retry-after')))
+  if (!isRateLimit)
+    return res
+
+  const retryAfterHeader = res.headers.get('retry-after')
+  const resetHeader = res.headers.get('x-ratelimit-reset')
+  let waitMs = 1000 * 2 ** attempt
+  if (retryAfterHeader)
+    waitMs = Number(retryAfterHeader) * 1000
+  else if (resetHeader)
+    waitMs = Math.max(0, Number(resetHeader) * 1000 - Date.now()) + 500
+  await new Promise(r => setTimeout(r, Math.min(waitMs, 30_000)))
+  return ghFetch(url, attempt + 1)
+}
+
+/**
+ * Run `fn` over `items` with at most `limit` concurrent invocations.
+ * Result indices match input indices.
+ */
+export async function mapWithConcurrency<T, R>(items: T[], limit: number, fn: (item: T) => Promise<R>): Promise<R[]> {
+  const results: R[] = Array.from({ length: items.length })
+  let next = 0
+  async function worker(): Promise<void> {
+    while (true) {
+      const i = next++
+      if (i >= items.length)
+        return
+      results[i] = await fn(items[i])
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, () => worker()))
+  return results
+}

package/src/dashboard.ts

@@ -0,0 +1,180 @@
+import type { DashboardData, DashboardOptions, RepoStatus } from './types'
+import { fetchBotPRCounts } from './bots'
+import { mapWithConcurrency } from './client'
+import { fetchAllRepos } from './repos'
+import { fetchRepoActiveRuns } from './runners'
+import { fetchRepoStatus } from './runs'
+
+const DEFAULT_TTL_MS = 30 * 1000
+const DEFAULT_CACHE_PATH = '.cache/dashboard.json'
+const DEFAULT_RUNNER_CAP = 20
+
+/**
+ * In-memory cache scoped per cache-path. Multiple callers hitting the same
+ * disk-backed cache file share state; callers using distinct paths (e.g.
+ * test isolation) stay independent.
+ */
+interface CacheEntry {
+  data: DashboardData | null
+  savedAt: number
+  inflight: Promise<DashboardData> | null
+  diskLoaded: boolean
+}
+const caches = new Map<string, CacheEntry>()
+
+function entryFor(path: string): CacheEntry {
+  let e = caches.get(path)
+  if (!e) {
+    e = { data: null, savedAt: 0, inflight: null, diskLoaded: false }
+    caches.set(path, e)
+  }
+  return e
+}
+
+async function loadCacheFromDisk(entry: CacheEntry, path: string): Promise<void> {
+  if (entry.diskLoaded)
+    return
+  entry.diskLoaded = true
+  try {
+    const file = Bun.file(path)
+    if (!(await file.exists()))
+      return
+    const stored = await file.json() as { data: DashboardData, savedAt: number }
+    entry.data = stored.data
+    entry.savedAt = stored.savedAt
+  }
+  catch {
+    // corrupt or missing cache file is harmless — we just rebuild
+  }
+}
+
+async function saveCacheToDisk(path: string, data: DashboardData, savedAt: number): Promise<void> {
+  try {
+    await Bun.write(path, JSON.stringify({ data, savedAt }))
+  }
+  catch (err) {
+    console.warn('[github/dashboard] cache write failed:', err)
+  }
+}
+
+/**
+ * Build a fresh snapshot — fans out across orgs / repos / bot authors with
+ * bounded concurrency, then collates into the `DashboardData` shape the
+ * dashboard UI consumes.
+ */
+async function buildDashboardData(opts: DashboardOptions): Promise<DashboardData> {
+  const orgs = opts.orgs
+  const runnerCaps = opts.runnerCaps ?? {}
+  const defaultRunnerCap = opts.defaultRunnerCap ?? DEFAULT_RUNNER_CAP
+
+  const repos = await fetchAllRepos(orgs, opts.ignoreRepos)
+  const statuses = await mapWithConcurrency(repos, 8, r => fetchRepoStatus(r.owner, r.name, r.default_branch))
+
+  const prCountMaps = await Promise.all(
+    orgs.flatMap(org => [
+      fetchBotPRCounts(org, 'renovate').then(m => ({ type: 'renovate' as const, map: m })),
+      fetchBotPRCounts(org, 'github-actions').then(m => ({ type: 'actions' as const, map: m })),
+    ]),
+  )
+  const renovateCounts = new Map<string, number>()
+  const actionsCounts = new Map<string, number>()
+  for (const { type, map } of prCountMaps) {
+    const target = type === 'renovate' ? renovateCounts : actionsCounts
+    for (const [k, v] of map) target.set(k, (target.get(k) ?? 0) + v)
+  }
+
+  for (const s of statuses) {
+    const rCount = renovateCounts.get(s.fullName) ?? 0
+    const aCount = actionsCounts.get(s.fullName) ?? 0
+    s.renovatePRs = rCount
+    s.actionsPRs = aCount
+    if (rCount > 0)
+      s.renovatePRsUrl = `https://github.com/${s.fullName}/pulls?q=${encodeURIComponent('is:pr is:open author:app/renovate')}`
+    if (aCount > 0)
+      s.actionsPRsUrl = `https://github.com/${s.fullName}/pulls?q=${encodeURIComponent('is:pr is:open author:app/github-actions')}`
+  }
+
+  const runnerCounts = await mapWithConcurrency(repos, 8, async r => ({
+    owner: r.owner,
+    ...(await fetchRepoActiveRuns(r.owner, r.name)),
+  }))
+  const runners: Record<string, { running: number, queued: number, cap: number }> = {}
+  for (const org of orgs)
+    runners[org] = { running: 0, queued: 0, cap: runnerCaps[org] ?? defaultRunnerCap }
+  for (const c of runnerCounts) {
+    if (!runners[c.owner])
+      runners[c.owner] = { running: 0, queued: 0, cap: runnerCaps[c.owner] ?? defaultRunnerCap }
+    runners[c.owner].running += c.running
+    runners[c.owner].queued += c.queued
+  }
+
+  // failures float to the top of the feed so the dashboard's eye-line lands
+  // on what's broken, not on the long tail of green.
+  const order: Record<string, number> = { failure: 0, error: 1, pending: 2, success: 3, no_runs: 4 }
+  statuses.sort((a: RepoStatus, b: RepoStatus) => (order[a.status] ?? 5) - (order[b.status] ?? 5))
+
+  return {
+    repos: statuses,
+    fetchedAt: new Date().toISOString(),
+    total: statuses.length,
+    passing: statuses.filter(r => r.status === 'success').length,
+    failing: statuses.filter(r => r.status === 'failure' || r.status === 'error').length,
+    pending: statuses.filter(r => r.status === 'pending').length,
+    noRuns: statuses.filter(r => r.status === 'no_runs').length,
+    runners,
+  }
+}
+
+/**
+ * Aggregated CI/runner snapshot across the configured orgs.
+ *
+ * Stale-while-revalidate: if a cached snapshot exists, it is returned
+ * immediately and a background refresh kicks off once the TTL has elapsed.
+ * First-ever call (no in-memory and no on-disk cache) waits for the build
+ * so the dashboard renders against real data instead of `null`.
+ */
+export async function getDashboardData(opts: DashboardOptions): Promise<DashboardData> {
+  const ttl = opts.cacheTtlMs ?? DEFAULT_TTL_MS
+  const path = opts.cachePath ?? DEFAULT_CACHE_PATH
+  const entry = entryFor(path)
+
+  await loadCacheFromDisk(entry, path)
+  const now = Date.now()
+
+  if (entry.data) {
+    if (now - entry.savedAt >= ttl && !entry.inflight) {
+      entry.inflight = buildDashboardData(opts)
+        .then(async (data) => {
+          entry.data = data
+          entry.savedAt = Date.now()
+          await saveCacheToDisk(path, data, entry.savedAt)
+          return data
+        })
+        .finally(() => { entry.inflight = null })
+      entry.inflight.catch(err => console.warn('[github/dashboard] refresh failed:', err))
+    }
+    return entry.data
+  }
+
+  if (!entry.inflight) {
+    entry.inflight = buildDashboardData(opts)
+      .then(async (data) => {
+        entry.data = data
+        entry.savedAt = Date.now()
+        await saveCacheToDisk(path, data, entry.savedAt)
+        return data
+      })
+      .finally(() => { entry.inflight = null })
+  }
+  return entry.inflight
+}
+
+/**
+ * Drop the in-memory cache for a given cache path. Disk cache is left
+ * alone — callers that want a true reset should `Bun.write` an empty file
+ * or delete it before re-fetching. Used by tests and by an eventual
+ * "Refresh now" UI action.
+ */
+export function clearDashboardCache(cachePath = DEFAULT_CACHE_PATH): void {
+  caches.delete(cachePath)
+}

package/src/failure-detector.ts

@@ -0,0 +1,194 @@
+import type { RepoStatus } from './types'
+
+/**
+ * Pure failure-transition detector (stacksjs/stacks#1849).
+ *
+ * Given a fresh CI snapshot and the previous per-repo states the
+ * dashboard knows about, return the list of repos that *just*
+ * transitioned to a failed conclusion — the moment worth firing a
+ * notification on. Anything still failing, or newly passing, or
+ * still in flight, is silenced.
+ *
+ * Pure for a reason: easy to unit-test the transition matrix without
+ * a DB, a notify implementation, or the network. The persistence
+ * layer + notification fan-out live in defaults so framework
+ * packages stay infrastructure-free.
+ *
+ * @see PreviousRunState  what the persistence layer hands in
+ * @see FailedTransition  what we return — caller decides how to notify
+ */
+
+/** What a caller stored about a repo on its last snapshot pass. */
+export interface PreviousRunState {
+  /** GH "fullName" — `owner/repo`. The composite key used in storage. */
+  repoFullName: string
+  /** Last conclusion the dashboard saw. `null` when the repo was in
+   *  flight (status pending) or had no runs yet. */
+  lastConclusion: string | null
+  /** GH workflow run id of the last seen run. Used to silence noise
+   *  when the same failed run shows up across multiple polls — we
+   *  only want to fire on a NEW run that transitioned. */
+  lastRunId: number | null
+  /** Last notification dispatch timestamp (ISO). Drives the cooldown
+   *  window for flap-storms. `null` means "never fired". */
+  lastNotifiedAt: string | null
+}
+
+/** Per-transition payload the detector hands back to the caller. */
+export interface FailedTransition {
+  repoFullName: string
+  /** `failure`, `error`, `timed_out` — kept verbatim from snapshot. */
+  conclusion: string
+  /** Run id that introduced the failure. Stored back as `lastRunId`. */
+  runId: number | null
+  /** Pass-through metadata the notification template usually wants. */
+  workflowName: string | null
+  commitSha: string | null
+  commitMessage: string | null
+  commitAuthor: string | null
+  runUrl: string | null
+  /** For comparison + de-duping: the previous conclusion the detector
+   *  saw before deciding this counts as a transition. */
+  previousConclusion: string | null
+}
+
+export interface DetectOptions {
+  /**
+   * Minimum delay between consecutive notifications for the same
+   * repo. Defaults to 5 minutes. A red → green → red flap inside this
+   * window only fires the first transition; the second is silenced.
+   *
+   * Set to 0 to disable cooldown entirely.
+   */
+  cooldownMs?: number
+  /**
+   * Reference timestamp. Defaults to `Date.now()`. Injectable so the
+   * test suite can drive the clock and assert cooldown semantics
+   * deterministically.
+   */
+  now?: number
+}
+
+const DEFAULT_COOLDOWN_MS = 5 * 60 * 1000
+
+const FAILED_CONCLUSIONS = new Set<string>([
+  'failure',
+  'error',
+  'timed_out',
+  'startup_failure',
+])
+
+function isFailed(repo: { status: string, conclusion: string | null }): boolean {
+  // `RepoStatus.status` covers our internal bucket (success / failure /
+  // pending / error / no_runs). `failure` and `error` both count;
+  // `conclusion` adds GH's finer-grained terminology (timed_out,
+  // startup_failure) for the cases that surfaced as `error` upstream.
+  if (repo.status === 'failure' || repo.status === 'error')
+    return true
+  if (repo.conclusion && FAILED_CONCLUSIONS.has(repo.conclusion))
+    return true
+  return false
+}
+
+function isInFlight(repo: { status: string }): boolean {
+  return repo.status === 'pending'
+}
+
+/**
+ * Compute the failed-transition list.
+ *
+ * The "transition" is gated on:
+ *
+ *   1. The repo is currently in a failed state.
+ *   2. The repo is NOT in flight (pending). Pending → failure happens
+ *      mid-run; firing on it would just produce noise once the run
+ *      finishes and the same failure resurfaces with a final
+ *      conclusion.
+ *   3. The previous state was *not* failed. (Sticky-red repos don't
+ *      keep firing.)
+ *   4. The run id changed — if the same failed run id is still
+ *      surfacing, this is a duplicate poll, not a new failure.
+ *   5. Cooldown: `lastNotifiedAt` is either null or older than
+ *      `cooldownMs` ago.
+ */
+export function detectNewlyFailedRuns(
+  snapshot: { repos: RepoStatus[] },
+  previousStates: Map<string, PreviousRunState>,
+  options: DetectOptions = {},
+): FailedTransition[] {
+  const cooldownMs = options.cooldownMs ?? DEFAULT_COOLDOWN_MS
+  const now = options.now ?? Date.now()
+  const transitions: FailedTransition[] = []
+
+  for (const repo of snapshot.repos) {
+    if (!isFailed(repo) || isInFlight(repo))
+      continue
+
+    const prev = previousStates.get(repo.fullName)
+    const prevWasFailed = prev?.lastConclusion
+      ? FAILED_CONCLUSIONS.has(prev.lastConclusion) || prev.lastConclusion === 'failure' || prev.lastConclusion === 'error'
+      : false
+    if (prevWasFailed) {
+      // The repo is still red. Only count this as a transition if
+      // the run id has changed — i.e. a new failed run, not the same
+      // one surfacing again.
+      const currentRunId = parseRunIdFromUrl(repo.runUrl)
+      if (currentRunId !== null && prev?.lastRunId !== null && currentRunId === prev?.lastRunId)
+        continue
+      // Different run id while still failing — counts as a new
+      // transition (a fresh failed build after the previous one).
+      // BUT silence it if we already notified within the cooldown.
+      if (prev?.lastNotifiedAt && isWithinCooldown(prev.lastNotifiedAt, cooldownMs, now))
+        continue
+      transitions.push(toTransition(repo, prev?.lastConclusion ?? null))
+      continue
+    }
+
+    // Previously green / pending / no_runs / never-seen → now failed.
+    // The transition we care about. Still honour the cooldown — covers
+    // the "green → red → green → red" flap-storm case where the
+    // intermediate green resets `prevWasFailed` but the user still
+    // doesn't want to be paged twice in 30s.
+    if (prev?.lastNotifiedAt && isWithinCooldown(prev.lastNotifiedAt, cooldownMs, now))
+      continue
+
+    transitions.push(toTransition(repo, prev?.lastConclusion ?? null))
+  }
+
+  return transitions
+}
+
+function isWithinCooldown(lastNotifiedAt: string, cooldownMs: number, now: number): boolean {
+  if (cooldownMs === 0) return false
+  const ts = Date.parse(lastNotifiedAt)
+  if (Number.isNaN(ts)) return false
+  return (now - ts) < cooldownMs
+}
+
+/**
+ * Extract the run id from a GH run URL like
+ * `https://github.com/owner/repo/actions/runs/12345678`. Returns null
+ * if the URL doesn't match — we don't blow up the detector on
+ * unfamiliar URL shapes; we just fall through to "treat as a new run".
+ */
+function parseRunIdFromUrl(runUrl: string | null): number | null {
+  if (!runUrl) return null
+  const match = runUrl.match(/\/actions\/runs\/(\d+)/)
+  if (!match) return null
+  const id = Number(match[1])
+  return Number.isFinite(id) ? id : null
+}
+
+function toTransition(repo: RepoStatus, previousConclusion: string | null): FailedTransition {
+  return {
+    repoFullName: repo.fullName,
+    conclusion: repo.conclusion ?? repo.status,
+    runId: parseRunIdFromUrl(repo.runUrl),
+    workflowName: repo.workflowName,
+    commitSha: repo.commitSha,
+    commitMessage: repo.commitMessage,
+    commitAuthor: repo.commitAuthor,
+    runUrl: repo.runUrl,
+    previousConclusion,
+  }
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+/**
+ * @stacksjs/github — thin GitHub API client used by Stacks framework
+ * features (dashboard CI surface, future runner alerts, kanban→PR links).
+ *
+ * Top-level entry: {@link getDashboardData} returns the aggregated snapshot
+ * the dashboard renders. Lower-level helpers (`fetchAllRepos`,
+ * `fetchRepoStatus`, …) are also exported so other surfaces can pull a
+ * single dimension without pulling the whole snapshot through.
+ */
+
+export { fetchBotPRCounts } from './bots'
+export { ghFetch, ghHeaders, GITHUB_API, mapWithConcurrency } from './client'
+export { clearDashboardCache, getDashboardData } from './dashboard'
+export { detectNewlyFailedRuns } from './failure-detector'
+export type { DetectOptions, FailedTransition, PreviousRunState } from './failure-detector'
+export { fetchAllRepos } from './repos'
+export { fetchRepoActiveRuns } from './runners'
+export { fetchRunJobs, fetchWorkflowRuns } from './run-history'
+export type { WorkflowJob, WorkflowRun } from './run-history'
+export { detectRunnerPressure } from './runner-pressure-detector'
+export type {
+  DetectOptions as PressureDetectOptions,
+  PressureAction,
+  RunnerAlertState,
+  RunnerSample,
+} from './runner-pressure-detector'
+export { fetchFailedJobs, fetchRepoStatus } from './runs'
+export type {
+  DashboardData,
+  DashboardOptions,
+  FailedJob,
+  OrgRunnerUsage,
+  Repo,
+  RepoStatus,
+  RepoStatusKind,
+} from './types'

package/src/repos.ts

@@ -0,0 +1,47 @@
+import type { Repo } from './types'
+import { ghFetch, GITHUB_API } from './client'
+
+/**
+ * Fetch all non-archived public repos across `orgs`, filtering out any names
+ * in `ignore` (defaults to `.github` which exists in every org and never has
+ * project CI on it).
+ */
+export async function fetchAllRepos(orgs: string[], ignore: string[] = ['.github']): Promise<Repo[]> {
+  const ignored = new Set(ignore)
+  const all: Repo[] = []
+
+  for (const org of orgs) {
+    let page = 1
+    while (true) {
+      const res = await ghFetch(`${GITHUB_API}/orgs/${org}/repos?per_page=100&page=${page}&type=public`)
+      if (!res.ok)
+        break
+
+      const repos = await res.json() as Array<{
+        name: string
+        owner: { login: string }
+        full_name: string
+        html_url: string
+        default_branch: string
+        archived: boolean
+      }>
+      if (repos.length === 0)
+        break
+
+      for (const repo of repos) {
+        all.push({
+          name: repo.name,
+          owner: repo.owner.login,
+          full_name: repo.full_name,
+          html_url: repo.html_url,
+          default_branch: repo.default_branch,
+          archived: repo.archived,
+        })
+      }
+
+      page++
+    }
+  }
+
+  return all.filter(r => !r.archived && !ignored.has(r.name))
+}

package/src/run-history.ts

@@ -0,0 +1,194 @@
+import { ghFetch, GITHUB_API } from './client'
+
+/**
+ * Recent-workflow-runs + per-run job detail for the dashboard CI
+ * drilldown (stacksjs/stacks#1848).
+ *
+ * Distinct from `runs.ts` which is the *aggregator* — it folds the
+ * latest run per repo into a `RepoStatus` for the at-a-glance card.
+ * Here we want history: the last N runs for a single repo, plus the
+ * per-job detail for a single run. Different shapes, different
+ * callers, easier to keep them in separate files than to overload
+ * one module.
+ */
+
+export interface WorkflowRun {
+  id: number
+  /** GH's `status` field: queued / in_progress / completed. */
+  status: 'queued' | 'in_progress' | 'completed' | string
+  /** GH's `conclusion` field: success / failure / cancelled / null
+   *  (null while in flight). */
+  conclusion: 'success' | 'failure' | 'cancelled' | 'skipped' | 'timed_out' | 'action_required' | 'neutral' | 'startup_failure' | null
+  /** Workflow display name. */
+  name: string
+  /** Branch / ref the run was triggered on. */
+  headBranch: string | null
+  headSha: string
+  headShaShort: string
+  commitMessage: string | null
+  commitAuthor: string | null
+  /** `push`, `pull_request`, `schedule`, …  */
+  event: string
+  url: string
+  startedAt: string | null
+  updatedAt: string
+  /** Compute on the way out so the page can show "12m" without
+   *  rolling its own diff. */
+  durationMs: number | null
+}
+
+export interface WorkflowJob {
+  id: number
+  name: string
+  status: 'queued' | 'in_progress' | 'completed' | string
+  conclusion: WorkflowRun['conclusion']
+  startedAt: string | null
+  completedAt: string | null
+  durationMs: number | null
+  /** Direct link to GH's log viewer for this job. */
+  url: string
+  /** Step-level breakdown. UI usually only renders failed/cancelled
+   *  steps but the full list is here for completeness. */
+  steps: Array<{
+    name: string
+    status: WorkflowJob['status']
+    conclusion: WorkflowRun['conclusion']
+    number: number
+  }>
+}
+
+interface FetchRunsOptions {
+  /** Max runs to return. Defaults to 20. Hard-capped at 100 — anything
+   *  larger should paginate (separate workstream). */
+  limit?: number
+  /** Filter to a specific branch. Defaults to no filter (every run on
+   *  the default branch shows). */
+  branch?: string
+  /** Filter to a specific event type (`push`, `pull_request`, …). */
+  event?: string
+}
+
+function shortSha(sha: string): string {
+  return sha.length > 7 ? sha.slice(0, 7) : sha
+}
+
+function diffMs(start: string | null | undefined, end: string | null | undefined): number | null {
+  if (!start || !end) return null
+  const s = Date.parse(start)
+  const e = Date.parse(end)
+  if (Number.isNaN(s) || Number.isNaN(e)) return null
+  if (e < s) return null
+  return e - s
+}
+
+/**
+ * The N most recent workflow runs for a repo. Each entry is a
+ * lightweight summary — failed-job detail is fetched on-demand via
+ * {@link fetchRunJobs} so the drawer only pays the round-trip cost
+ * when the user actually expands a row.
+ */
+export async function fetchWorkflowRuns(
+  owner: string,
+  name: string,
+  options: FetchRunsOptions = {},
+): Promise<WorkflowRun[]> {
+  const limit = Math.max(1, Math.min(options.limit ?? 20, 100))
+  const params = new URLSearchParams()
+  params.set('per_page', String(limit))
+  if (options.branch) params.set('branch', options.branch)
+  if (options.event) params.set('event', options.event)
+
+  const res = await ghFetch(`${GITHUB_API}/repos/${owner}/${name}/actions/runs?${params.toString()}`)
+  if (!res.ok) return []
+
+  const data = await res.json() as {
+    workflow_runs?: Array<{
+      id: number
+      status: string
+      conclusion: string | null
+      name: string
+      head_branch: string | null
+      head_sha: string
+      head_commit: { message: string, author: { name: string } | null } | null
+      event: string
+      html_url: string
+      actor: { login: string } | null
+      run_started_at: string | null
+      created_at: string
+      updated_at: string
+    }>
+  }
+  const runs = data.workflow_runs ?? []
+
+  return runs.map((r): WorkflowRun => ({
+    id: r.id,
+    status: r.status,
+    conclusion: r.conclusion as WorkflowRun['conclusion'],
+    name: r.name,
+    headBranch: r.head_branch,
+    headSha: r.head_sha,
+    headShaShort: shortSha(r.head_sha),
+    commitMessage: r.head_commit?.message?.split('\n')[0] ?? null,
+    commitAuthor: r.head_commit?.author?.name ?? r.actor?.login ?? null,
+    event: r.event,
+    url: r.html_url,
+    startedAt: r.run_started_at ?? r.created_at ?? null,
+    updatedAt: r.updated_at,
+    durationMs: diffMs(r.run_started_at ?? r.created_at, r.updated_at),
+  }))
+}
+
+/**
+ * Per-job detail for a single run. Used by the drilldown drawer when
+ * the user expands a failing run to see *which* step broke. Different
+ * shape from `fetchFailedJobs` in `runs.ts` (which is at-a-glance
+ * "failed job names" for the card) — here we want everything,
+ * including step-level breakdown + timing.
+ *
+ * Returns an empty array on error so the drawer can render an empty
+ * state rather than a 500.
+ */
+export async function fetchRunJobs(
+  owner: string,
+  name: string,
+  runId: number,
+): Promise<WorkflowJob[]> {
+  const res = await ghFetch(`${GITHUB_API}/repos/${owner}/${name}/actions/runs/${runId}/jobs?per_page=100`)
+  if (!res.ok) return []
+
+  const data = await res.json() as {
+    jobs?: Array<{
+      id: number
+      name: string
+      status: string
+      conclusion: string | null
+      started_at: string | null
+      completed_at: string | null
+      html_url: string
+      steps?: Array<{
+        name: string
+        status: string
+        conclusion: string | null
+        number: number
+      }>
+    }>
+  }
+  const jobs = data.jobs ?? []
+
+  return jobs.map((j): WorkflowJob => ({
+    id: j.id,
+    name: j.name,
+    status: j.status,
+    conclusion: j.conclusion as WorkflowJob['conclusion'],
+    startedAt: j.started_at,
+    completedAt: j.completed_at,
+    durationMs: diffMs(j.started_at, j.completed_at),
+    url: j.html_url,
+    steps: (j.steps ?? []).map(s => ({
+      name: s.name,
+      status: s.status,
+      conclusion: s.conclusion as WorkflowJob['conclusion'],
+      number: s.number,
+    })),
+  }))
+}

package/src/runner-pressure-detector.ts

@@ -0,0 +1,174 @@
+/**
+ * Pure runner-pressure detector (stacksjs/stacks#1850).
+ *
+ * Given a time-series of per-org runner samples + the dashboard's
+ * memory of which orgs are currently "alerting", return the
+ * actions to take: fire a fresh alert, clear an existing one, or do
+ * nothing.
+ *
+ * **Hysteresis** matters here. Once an org has been alerted on
+ * (queue > threshold sustained for one window), we DON'T re-fire
+ * just because the queue spikes a second time within the same hour.
+ * The org has to first *clear* — drop below threshold for a full
+ * window — before another fire becomes possible. This is the
+ * difference between "useful CI pressure paging" and "every dashboard
+ * load spams Slack".
+ *
+ * Pure for the same reason as `failure-detector.ts`: easy to unit-
+ * test the hysteresis transitions, the persistence + fan-out live
+ * in defaults.
+ */
+
+/** One time-series row per org per snapshot refresh. */
+export interface RunnerSample {
+  org: string
+  running: number
+  queued: number
+  cap: number
+  /** ISO timestamp the sample was taken. Driven by the caller — we
+   *  don't `Date.now()` in this module so tests can drive the clock. */
+  sampledAt: string
+}
+
+/** Dashboard's last-known per-org alert state. */
+export interface RunnerAlertState {
+  org: string
+  alerting: boolean
+  /** ISO timestamp when this org most recently transitioned to
+   *  alerting. Null if it has never alerted. */
+  lastAlertedAt: string | null
+  /** ISO timestamp when this org most recently transitioned from
+   *  alerting → cleared. Null if it has never cleared (e.g. has
+   *  never been in an alerting state to begin with). */
+  lastClearedAt: string | null
+}
+
+/** Action the caller should take for one org. */
+export interface PressureAction {
+  org: string
+  /**
+   * - `fire`: org just crossed sustained-pressure threshold for one
+   *   full window AND wasn't already alerting. Caller should
+   *   notify + set `alerting = true`.
+   * - `clear`: org has been below threshold for one full window AND
+   *   was previously alerting. Caller should set `alerting = false`
+   *   (no notification — clearing alone is silent; users only want
+   *   the inbound page, not the "everything is fine again" email).
+   * - `none` is not returned; the detector simply omits orgs in
+   *   no-change states.
+   */
+  action: 'fire' | 'clear'
+  /** Latest sample (so the fan-out template can show "12 queued of
+   *  20 cap"). */
+  current: RunnerSample
+  /**
+   * How long the threshold has been sustained, in milliseconds.
+   * Computed from the oldest sample in the window. Reported in the
+   * notification body ("queued > 8 for 12m").
+   */
+  sustainedMs: number
+}
+
+export interface DetectOptions {
+  /** Queue depth at or above this counts as pressure. */
+  queuedThreshold: number
+  /** Duration the threshold must hold (in either direction) before
+   *  the detector transitions. */
+  windowMinutes: number
+  /** Reference clock — defaults to `Date.now()`. Tests pass it in. */
+  now?: number
+}
+
+/**
+ * Compute the per-org actions.
+ *
+ * Algorithm:
+ *
+ *   1. Bucket samples by org.
+ *   2. For each org, slice the samples within the last
+ *      `windowMinutes` of `now` (called `window`).
+ *   3. Skip orgs with `window.length === 0` (no samples ever) or
+ *      where the window is shorter than `windowMinutes`
+ *      (insufficient data — sustained-pressure can't be proven yet).
+ *   4. If the org is currently `alerting`:
+ *      - If every sample in the window is < threshold → emit
+ *        `clear` action.
+ *   5. If the org is NOT alerting:
+ *      - If every sample in the window is >= threshold → emit
+ *        `fire` action.
+ *
+ * Conditions that DON'T trigger anything:
+ *
+ *   - Mixed window (some above, some below threshold) → still
+ *     converging; wait for the next refresh.
+ *   - Sticky alerting with sustained pressure → already alerting,
+ *     no new action needed.
+ *   - Sticky clear with sustained calm → no action needed.
+ */
+export function detectRunnerPressure(
+  samples: RunnerSample[],
+  alertStates: Map<string, RunnerAlertState>,
+  options: DetectOptions,
+): PressureAction[] {
+  const now = options.now ?? Date.now()
+  const windowMs = options.windowMinutes * 60_000
+  const cutoffMs = now - windowMs
+
+  // Bucket samples by org.
+  const byOrg = new Map<string, RunnerSample[]>()
+  for (const s of samples) {
+    const t = Date.parse(s.sampledAt)
+    if (Number.isNaN(t) || t < cutoffMs)
+      continue
+    const list = byOrg.get(s.org) ?? []
+    list.push(s)
+    byOrg.set(s.org, list)
+  }
+
+  const actions: PressureAction[] = []
+
+  for (const [org, orgSamples] of byOrg.entries()) {
+    if (orgSamples.length === 0)
+      continue
+
+    // Sort by sampledAt ascending so [0] is oldest, [last] is newest.
+    orgSamples.sort((a, b) => Date.parse(a.sampledAt) - Date.parse(b.sampledAt))
+
+    // "Sustained for a full window" means the oldest in-window
+    // sample is at least `windowMinutes` old. If the org just
+    // started reporting, the window is shorter than required and
+    // we can't prove sustained pressure yet.
+    const oldestMs = Date.parse(orgSamples[0].sampledAt)
+    const newestMs = Date.parse(orgSamples[orgSamples.length - 1].sampledAt)
+    const sustainedMs = newestMs - oldestMs
+    if (sustainedMs < windowMs - 1000) {
+      // -1000ms tolerance — the very first sample of a fresh window
+      // can be slightly less than windowMs old due to integer math
+      // around the moment the boundary tips. Tests use exactly
+      // `windowMinutes` spacing; tolerance keeps them deterministic
+      // without making the prod boundary fuzzy.
+      continue
+    }
+
+    const allAboveOrEqual = orgSamples.every(s => s.queued >= options.queuedThreshold)
+    const allBelow = orgSamples.every(s => s.queued < options.queuedThreshold)
+    const state = alertStates.get(org)
+    const isAlerting = state?.alerting ?? false
+    const current = orgSamples[orgSamples.length - 1]
+
+    if (isAlerting) {
+      if (allBelow) {
+        actions.push({ org, action: 'clear', current, sustainedMs })
+      }
+      // Otherwise (still elevated, or mixed) stay alerting; no action.
+    }
+    else {
+      if (allAboveOrEqual) {
+        actions.push({ org, action: 'fire', current, sustainedMs })
+      }
+      // Otherwise (still calm, or mixed) stay cleared; no action.
+    }
+  }
+
+  return actions
+}

package/src/runners.ts

@@ -0,0 +1,43 @@
+import { ghFetch, GITHUB_API } from './client'
+
+/**
+ * Count jobs (not runs) currently using runners. A workflow run can be
+ * "in_progress" while some of its matrix jobs are still queued — only the
+ * actually-running jobs occupy runners, so we sum at the job level.
+ */
+export async function fetchRepoActiveRuns(owner: string, name: string): Promise<{ running: number, queued: number }> {
+  try {
+    const runRes = await ghFetch(`${GITHUB_API}/repos/${owner}/${name}/actions/runs?status=in_progress&per_page=100`)
+    if (!runRes.ok)
+      return { running: 0, queued: 0 }
+
+    const runData = await runRes.json() as { workflow_runs: Array<{ id: number }> }
+    const runs = runData.workflow_runs ?? []
+    if (runs.length === 0)
+      return { running: 0, queued: 0 }
+
+    const counts = await Promise.all(runs.map(async (r) => {
+      const jobsRes = await ghFetch(`${GITHUB_API}/repos/${owner}/${name}/actions/runs/${r.id}/jobs`)
+      if (!jobsRes.ok)
+        return { running: 0, queued: 0 }
+      const jobsData = await jobsRes.json() as { jobs: Array<{ status: string }> }
+      let running = 0
+      let queued = 0
+      for (const j of jobsData.jobs ?? []) {
+        if (j.status === 'in_progress')
+          running++
+        else if (j.status === 'queued')
+          queued++
+      }
+      return { running, queued }
+    }))
+
+    return counts.reduce(
+      (a, b) => ({ running: a.running + b.running, queued: a.queued + b.queued }),
+      { running: 0, queued: 0 },
+    )
+  }
+  catch {
+    return { running: 0, queued: 0 }
+  }
+}

package/src/runs.ts

@@ -0,0 +1,124 @@
+import type { FailedJob, RepoStatus } from './types'
+import { ghFetch, GITHUB_API } from './client'
+
+async function fillLatestCommit(base: RepoStatus, owner: string, name: string, branch: string): Promise<void> {
+  try {
+    const res = await ghFetch(`${GITHUB_API}/repos/${owner}/${name}/commits?sha=${branch}&per_page=1`)
+    if (!res.ok)
+      return
+
+    const commits = await res.json() as Array<{
+      sha: string
+      commit: { message: string, author: { name: string, date: string } | null }
+      author: { login: string } | null
+    }>
+    if (commits.length === 0)
+      return
+
+    const c = commits[0]
+    base.commitSha = c.sha.slice(0, 7)
+    base.commitMessage = c.commit.message.split('\n')[0]
+    base.commitUrl = `https://github.com/${owner}/${name}/commit/${c.sha}`
+    base.commitAuthor = c.commit.author?.name ?? c.author?.login ?? null
+    base.updatedAt = c.commit.author?.date ?? null
+  }
+  catch {
+    // commit info is best-effort
+  }
+}
+
+export async function fetchFailedJobs(owner: string, name: string, runId: number): Promise<FailedJob[]> {
+  try {
+    const res = await ghFetch(`${GITHUB_API}/repos/${owner}/${name}/actions/runs/${runId}/jobs?filter=latest`)
+    if (!res.ok)
+      return []
+
+    const data = await res.json() as { jobs: Array<{ name: string, conclusion: string | null, html_url: string }> }
+    return data.jobs
+      .filter(j => j.conclusion && j.conclusion !== 'success' && j.conclusion !== 'skipped')
+      .map(j => ({ name: j.name, conclusion: j.conclusion!, url: j.html_url }))
+  }
+  catch {
+    return []
+  }
+}
+
+export async function fetchRepoStatus(owner: string, name: string, defaultBranch: string): Promise<RepoStatus> {
+  const base: RepoStatus = {
+    name,
+    owner,
+    fullName: `${owner}/${name}`,
+    url: `https://github.com/${owner}/${name}`,
+    defaultBranch,
+    status: 'no_runs',
+    conclusion: null,
+    workflowName: null,
+    commitSha: null,
+    commitMessage: null,
+    commitUrl: null,
+    commitAuthor: null,
+    commitCount: null,
+    updatedAt: null,
+    runUrl: null,
+    failedJobs: [],
+    renovatePRs: 0,
+    renovatePRsUrl: null,
+    actionsPRs: 0,
+    actionsPRsUrl: null,
+  }
+
+  try {
+    const res = await ghFetch(`${GITHUB_API}/repos/${owner}/${name}/actions/runs?branch=${defaultBranch}&event=push&per_page=1`)
+
+    if (!res.ok) {
+      base.status = 'error'
+      await fillLatestCommit(base, owner, name, defaultBranch)
+      return base
+    }
+
+    const data = await res.json() as {
+      workflow_runs: Array<{
+        id: number
+        status: string
+        conclusion: string | null
+        name: string
+        head_sha: string
+        head_commit: { message: string, author: { name: string } | null } | null
+        updated_at: string
+        html_url: string
+        actor: { login: string } | null
+      }>
+    }
+
+    if (!data.workflow_runs || data.workflow_runs.length === 0) {
+      await fillLatestCommit(base, owner, name, defaultBranch)
+      return base
+    }
+
+    const run = data.workflow_runs[0]
+    base.workflowName = run.name
+    base.commitSha = run.head_sha.slice(0, 7)
+    base.commitMessage = run.head_commit?.message.split('\n')[0] ?? null
+    base.commitUrl = `https://github.com/${owner}/${name}/commit/${run.head_sha}`
+    base.commitAuthor = run.head_commit?.author?.name ?? run.actor?.login ?? null
+    base.updatedAt = run.updated_at
+    base.runUrl = run.html_url
+
+    if (run.status === 'completed') {
+      base.status = run.conclusion === 'success' ? 'success' : 'failure'
+      base.conclusion = run.conclusion
+
+      if (base.status === 'failure')
+        base.failedJobs = await fetchFailedJobs(owner, name, run.id)
+    }
+    else {
+      base.status = 'pending'
+      base.conclusion = run.status
+    }
+  }
+  catch {
+    base.status = 'error'
+  }
+
+  return base
+}

package/src/types.ts

@@ -0,0 +1,71 @@
+export interface FailedJob {
+  name: string
+  conclusion: string
+  url: string
+}
+
+export type RepoStatusKind = 'success' | 'failure' | 'pending' | 'no_runs' | 'error'
+
+export interface RepoStatus {
+  name: string
+  owner: string
+  fullName: string
+  url: string
+  defaultBranch: string
+  status: RepoStatusKind
+  conclusion: string | null
+  workflowName: string | null
+  commitSha: string | null
+  commitMessage: string | null
+  commitUrl: string | null
+  commitAuthor: string | null
+  commitCount: number | null
+  updatedAt: string | null
+  runUrl: string | null
+  failedJobs: FailedJob[]
+  renovatePRs: number
+  renovatePRsUrl: string | null
+  actionsPRs: number
+  actionsPRsUrl: string | null
+}
+
+export interface OrgRunnerUsage {
+  running: number
+  queued: number
+  cap: number
+}
+
+export interface DashboardData {
+  repos: RepoStatus[]
+  fetchedAt: string
+  total: number
+  passing: number
+  failing: number
+  pending: number
+  noRuns: number
+  runners: Record<string, OrgRunnerUsage>
+}
+
+export interface DashboardOptions {
+  /** Orgs to include in the snapshot. */
+  orgs: string[]
+  /** Self-hosted runner caps per org. Missing entries fall back to {@link defaultRunnerCap}. */
+  runnerCaps?: Record<string, number>
+  /** Fallback runner cap when {@link runnerCaps} omits an org. */
+  defaultRunnerCap?: number
+  /** Repo names to exclude (matches against the bare repo name). */
+  ignoreRepos?: string[]
+  /** Cache TTL in ms. Defaults to 30s. */
+  cacheTtlMs?: number
+  /** On-disk cache path. Defaults to `.cache/dashboard.json`. */
+  cachePath?: string
+}
+
+export interface Repo {
+  name: string
+  owner: string
+  full_name: string
+  html_url: string
+  default_branch: string
+  archived: boolean
+}