@stacksjs/github 0.70.55 → 0.70.57

package/package.json

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

package/src/bots.ts

@@ -1,34 +0,0 @@
-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

@@ -1,64 +0,0 @@
-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

@@ -1,180 +0,0 @@
-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

@@ -1,194 +0,0 @@
-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

@@ -1,36 +0,0 @@
-/**
- * @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

@@ -1,47 +0,0 @@
-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

@@ -1,194 +0,0 @@
-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

@@ -1,174 +0,0 @@
-/**
- * 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

@@ -1,43 +0,0 @@
-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

@@ -1,124 +0,0 @@
-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

@@ -1,71 +0,0 @@
-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
-}