@stacksjs/github 0.70.87 → 0.70.88

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/github",
   "type": "module",
-  "version": "0.70.87",
+  "version": "0.70.88",
   "description": "GitHub API client used by Stacks framework features (dashboard CI surface, notifications, runner alerts).",
   "author": "Chris Breuer",
   "contributors": [

package/dist/bots.d.ts

@@ -1,7 +0,0 @@
-/**
- * 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 declare function fetchBotPRCounts(org: string, authorSlug: string): Promise<Map<string, number>>;

package/dist/bots.js

@@ -1,21 +0,0 @@
-import { ghFetch, GITHUB_API } from "./client";
-export async function fetchBotPRCounts(org, authorSlug) {
-  const counts = new Map;
-  let page = 1;
-  while (!0) {
-    const q = `is:pr is:open org:${org} author:app/${authorSlug}`, res = await ghFetch(`${GITHUB_API}/search/issues?q=${encodeURIComponent(q)}&per_page=100&page=${page}`);
-    if (!res.ok)
-      break;
-    const data = await res.json();
-    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/dist/client.d.ts

@@ -1,15 +0,0 @@
-export declare function ghHeaders(): Record<string, string>;
-/**
- * `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 declare function ghFetch(url: string, attempt?: number): Promise<Response>;
-/**
- * Run `fn` over `items` with at most `limit` concurrent invocations.
- * Result indices match input indices.
- */
-export declare function mapWithConcurrency<T, R>(items: T[], limit: number, fn: (item: T) => Promise<R>): Promise<R[]>;
-export declare const GITHUB_API: 'https://api.github.com';

package/dist/client.js

@@ -1,43 +0,0 @@
-export const GITHUB_API = "https://api.github.com";
-function getToken() {
-  const token = process.env.GITHUB_TOKEN;
-  if (!token)
-    throw Error("GITHUB_TOKEN environment variable is required");
-  return token;
-}
-export function ghHeaders() {
-  return {
-    Authorization: `Bearer ${getToken()}`,
-    Accept: "application/vnd.github+json",
-    "X-GitHub-Api-Version": "2022-11-28"
-  };
-}
-export async function ghFetch(url, attempt = 0) {
-  const res = await fetch(url, { headers: ghHeaders() });
-  if (res.ok || attempt >= 3)
-    return res;
-  if (!(res.status === 429 || res.status === 403 && (res.headers.get("x-ratelimit-remaining") === "0" || res.headers.get("retry-after"))))
-    return res;
-  const retryAfterHeader = res.headers.get("retry-after"), 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, 30000)));
-  return ghFetch(url, attempt + 1);
-}
-export async function mapWithConcurrency(items, limit, fn) {
-  const results = Array.from({ length: items.length });
-  let next = 0;
-  async function worker() {
-    while (!0) {
-      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/dist/dashboard.d.ts

@@ -1,17 +0,0 @@
-import type { DashboardData, DashboardOptions } from './types';
-/**
- * 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 declare function getDashboardData(opts: DashboardOptions): Promise<DashboardData>;
-/**
- * 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 declare function clearDashboardCache(cachePath?: unknown): void;

package/dist/dashboard.js

@@ -1,110 +0,0 @@
-import { fetchBotPRCounts } from "./bots";
-import { mapWithConcurrency } from "./client";
-import { fetchAllRepos } from "./repos";
-import { fetchRepoActiveRuns } from "./runners";
-import { fetchRepoStatus } from "./runs";
-const DEFAULT_TTL_MS = 30000, DEFAULT_CACHE_PATH = ".cache/dashboard.json", DEFAULT_RUNNER_CAP = 20, caches = new Map;
-function entryFor(path) {
-  let e = caches.get(path);
-  if (!e) {
-    e = { data: null, savedAt: 0, inflight: null, diskLoaded: !1 };
-    caches.set(path, e);
-  }
-  return e;
-}
-async function loadCacheFromDisk(entry, path) {
-  if (entry.diskLoaded)
-    return;
-  entry.diskLoaded = !0;
-  try {
-    const file = Bun.file(path);
-    if (!await file.exists())
-      return;
-    const stored = await file.json();
-    entry.data = stored.data;
-    entry.savedAt = stored.savedAt;
-  } catch {}
-}
-async function saveCacheToDisk(path, data, savedAt) {
-  try {
-    await Bun.write(path, JSON.stringify({ data, savedAt }));
-  } catch (err) {
-    console.warn("[github/dashboard] cache write failed:", err);
-  }
-}
-async function buildDashboardData(opts) {
-  const orgs = opts.orgs, runnerCaps = opts.runnerCaps ?? {}, defaultRunnerCap = opts.defaultRunnerCap ?? DEFAULT_RUNNER_CAP, repos = await fetchAllRepos(orgs, opts.ignoreRepos), statuses = await mapWithConcurrency(repos, 8, (r) => fetchRepoStatus(r.owner, r.name, r.default_branch)), prCountMaps = await Promise.all(orgs.flatMap((org) => [
-    fetchBotPRCounts(org, "renovate").then((m) => ({ type: "renovate", map: m })),
-    fetchBotPRCounts(org, "github-actions").then((m) => ({ type: "actions", map: m }))
-  ])), renovateCounts = new Map, actionsCounts = new Map;
-  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, 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)
-  })), runners = {};
-  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;
-  }
-  const order = { failure: 0, error: 1, pending: 2, success: 3, no_runs: 4 };
-  statuses.sort((a, b) => (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
-  };
-}
-export async function getDashboardData(opts) {
-  const ttl = opts.cacheTtlMs ?? DEFAULT_TTL_MS, path = opts.cachePath ?? DEFAULT_CACHE_PATH, 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;
-}
-export function clearDashboardCache(cachePath = DEFAULT_CACHE_PATH) {
-  caches.delete(cachePath);
-}

package/dist/failure-detector.d.ts

@@ -1,59 +0,0 @@
-import type { RepoStatus } from './types';
-/**
- * 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 declare function detectNewlyFailedRuns(snapshot: { repos: RepoStatus[] }, previousStates: Map<string, PreviousRunState>, options?: DetectOptions): FailedTransition[];
-/**
- * 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 declare interface PreviousRunState {
-  repoFullName: string
-  lastConclusion: string | null
-  lastRunId: number | null
-  lastNotifiedAt: string | null
-}
-/** Per-transition payload the detector hands back to the caller. */
-export declare interface FailedTransition {
-  repoFullName: string
-  conclusion: string
-  runId: number | null
-  workflowName: string | null
-  commitSha: string | null
-  commitMessage: string | null
-  commitAuthor: string | null
-  runUrl: string | null
-  previousConclusion: string | null
-}
-export declare interface DetectOptions {
-  cooldownMs?: number
-  now?: number
-}

package/dist/failure-detector.js

@@ -1,67 +0,0 @@
-const DEFAULT_COOLDOWN_MS = 300000, FAILED_CONCLUSIONS = new Set([
-  "failure",
-  "error",
-  "timed_out",
-  "startup_failure"
-]);
-function isFailed(repo) {
-  if (repo.status === "failure" || repo.status === "error")
-    return !0;
-  if (repo.conclusion && FAILED_CONCLUSIONS.has(repo.conclusion))
-    return !0;
-  return !1;
-}
-function isInFlight(repo) {
-  return repo.status === "pending";
-}
-export function detectNewlyFailedRuns(snapshot, previousStates, options = {}) {
-  const cooldownMs = options.cooldownMs ?? DEFAULT_COOLDOWN_MS, now = options.now ?? Date.now(), transitions = [];
-  for (const repo of snapshot.repos) {
-    if (!isFailed(repo) || isInFlight(repo))
-      continue;
-    const prev = previousStates.get(repo.fullName);
-    if (prev?.lastConclusion ? FAILED_CONCLUSIONS.has(prev.lastConclusion) || prev.lastConclusion === "failure" || prev.lastConclusion === "error" : !1) {
-      const currentRunId = parseRunIdFromUrl(repo.runUrl);
-      if (currentRunId !== null && prev?.lastRunId !== null && currentRunId === prev?.lastRunId)
-        continue;
-      if (prev?.lastNotifiedAt && isWithinCooldown(prev.lastNotifiedAt, cooldownMs, now))
-        continue;
-      transitions.push(toTransition(repo, prev?.lastConclusion ?? null));
-      continue;
-    }
-    if (prev?.lastNotifiedAt && isWithinCooldown(prev.lastNotifiedAt, cooldownMs, now))
-      continue;
-    transitions.push(toTransition(repo, prev?.lastConclusion ?? null));
-  }
-  return transitions;
-}
-function isWithinCooldown(lastNotifiedAt, cooldownMs, now) {
-  if (cooldownMs === 0)
-    return !1;
-  const ts = Date.parse(lastNotifiedAt);
-  if (Number.isNaN(ts))
-    return !1;
-  return now - ts < cooldownMs;
-}
-function parseRunIdFromUrl(runUrl) {
-  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, previousConclusion) {
-  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/dist/index.d.ts

@@ -1,35 +0,0 @@
-export type { DetectOptions, FailedTransition, PreviousRunState } from './failure-detector';
-export type { WorkflowJob, WorkflowRun } from './run-history';
-export type {
-  DetectOptions as PressureDetectOptions,
-  PressureAction,
-  RunnerAlertState,
-  RunnerSample,
-} from './runner-pressure-detector';
-export type {
-  DashboardData,
-  DashboardOptions,
-  FailedJob,
-  OrgRunnerUsage,
-  Repo,
-  RepoStatus,
-  RepoStatusKind,
-} from './types';
-/**
- * @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 { fetchAllRepos } from './repos';
-export { fetchRepoActiveRuns } from './runners';
-export { fetchRunJobs, fetchWorkflowRuns } from './run-history';
-export { detectRunnerPressure } from './runner-pressure-detector';
-export { fetchFailedJobs, fetchRepoStatus } from './runs';

package/dist/index.js

@@ -1,9 +0,0 @@
-export { fetchBotPRCounts } from "./bots";
-export { ghFetch, ghHeaders, GITHUB_API, mapWithConcurrency } from "./client";
-export { clearDashboardCache, getDashboardData } from "./dashboard";
-export { detectNewlyFailedRuns } from "./failure-detector";
-export { fetchAllRepos } from "./repos";
-export { fetchRepoActiveRuns } from "./runners";
-export { fetchRunJobs, fetchWorkflowRuns } from "./run-history";
-export { detectRunnerPressure } from "./runner-pressure-detector";
-export { fetchFailedJobs, fetchRepoStatus } from "./runs";

package/dist/repos.d.ts

@@ -1,7 +0,0 @@
-import type { Repo } from './types';
-/**
- * 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 declare function fetchAllRepos(orgs: string[], ignore?: string[]): Promise<Repo[]>;

package/dist/repos.js

@@ -1,26 +0,0 @@
-import { ghFetch, GITHUB_API } from "./client";
-export async function fetchAllRepos(orgs, ignore = [".github"]) {
-  const ignored = new Set(ignore), all = [];
-  for (const org of orgs) {
-    let page = 1;
-    while (!0) {
-      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();
-      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/dist/run-history.d.ts

@@ -1,66 +0,0 @@
-/**
- * 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 declare function fetchWorkflowRuns(owner: string, name: string, options?: FetchRunsOptions): Promise<WorkflowRun[]>;
-/**
- * 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 declare function fetchRunJobs(owner: string, name: string, runId: number): Promise<WorkflowJob[]>;
-/**
- * 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 declare interface WorkflowRun {
-  id: number
-  status: 'queued' | 'in_progress' | 'completed' | string
-  conclusion: 'success' | 'failure' | 'cancelled' | 'skipped' | 'timed_out' | 'action_required' | 'neutral' | 'startup_failure' | null
-  name: string
-  headBranch: string | null
-  headSha: string
-  headShaShort: string
-  commitMessage: string | null
-  commitAuthor: string | null
-  event: string
-  url: string
-  startedAt: string | null
-  updatedAt: string
-  durationMs: number | null
-}
-export declare interface WorkflowJob {
-  id: number
-  name: string
-  status: 'queued' | 'in_progress' | 'completed' | string
-  conclusion: WorkflowRun['conclusion']
-  startedAt: string | null
-  completedAt: string | null
-  durationMs: number | null
-  url: string
-  steps: Array<{
-    name: string
-    status: WorkflowJob['status']
-    conclusion: WorkflowRun['conclusion']
-    number: number
-  }>
-}
-declare interface FetchRunsOptions {
-  limit?: number
-  branch?: string
-  event?: string
-}

package/dist/run-history.js

@@ -1,63 +0,0 @@
-import { ghFetch, GITHUB_API } from "./client";
-function shortSha(sha) {
-  return sha.length > 7 ? sha.slice(0, 7) : sha;
-}
-function diffMs(start, end) {
-  if (!start || !end)
-    return null;
-  const s = Date.parse(start), e = Date.parse(end);
-  if (Number.isNaN(s) || Number.isNaN(e))
-    return null;
-  if (e < s)
-    return null;
-  return e - s;
-}
-export async function fetchWorkflowRuns(owner, name, options = {}) {
-  const limit = Math.max(1, Math.min(options.limit ?? 20, 100)), 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 [];
-  return ((await res.json()).workflow_runs ?? []).map((r) => ({
-    id: r.id,
-    status: r.status,
-    conclusion: r.conclusion,
-    name: r.name,
-    headBranch: r.head_branch,
-    headSha: r.head_sha,
-    headShaShort: shortSha(r.head_sha),
-    commitMessage: r.head_commit?.message?.split(`
-`)[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)
-  }));
-}
-export async function fetchRunJobs(owner, name, runId) {
-  const res = await ghFetch(`${GITHUB_API}/repos/${owner}/${name}/actions/runs/${runId}/jobs?per_page=100`);
-  if (!res.ok)
-    return [];
-  return ((await res.json()).jobs ?? []).map((j) => ({
-    id: j.id,
-    name: j.name,
-    status: j.status,
-    conclusion: j.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,
-      number: s.number
-    }))
-  }));
-}

package/dist/runner-pressure-detector.d.ts

@@ -1,74 +0,0 @@
-/**
- * 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 declare function detectRunnerPressure(samples: RunnerSample[], alertStates: Map<string, RunnerAlertState>, options: DetectOptions): PressureAction[];
-/**
- * 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 declare interface RunnerSample {
-  org: string
-  running: number
-  queued: number
-  cap: number
-  sampledAt: string
-}
-/** Dashboard's last-known per-org alert state. */
-export declare interface RunnerAlertState {
-  org: string
-  alerting: boolean
-  lastAlertedAt: string | null
-  lastClearedAt: string | null
-}
-/** Action the caller should take for one org. */
-export declare interface PressureAction {
-  org: string
-  action: 'fire' | 'clear'
-  current: RunnerSample
-  sustainedMs: number
-}
-export declare interface DetectOptions {
-  queuedThreshold: number
-  windowMinutes: number
-  now?: number
-}

package/dist/runner-pressure-detector.js

@@ -1,27 +0,0 @@
-export function detectRunnerPressure(samples, alertStates, options) {
-  const now = options.now ?? Date.now(), windowMs = options.windowMinutes * 60000, cutoffMs = now - windowMs, byOrg = new Map;
-  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 = [];
-  for (const [org, orgSamples] of byOrg.entries()) {
-    if (orgSamples.length === 0)
-      continue;
-    orgSamples.sort((a, b) => Date.parse(a.sampledAt) - Date.parse(b.sampledAt));
-    const oldestMs = Date.parse(orgSamples[0].sampledAt), sustainedMs = Date.parse(orgSamples[orgSamples.length - 1].sampledAt) - oldestMs;
-    if (sustainedMs < windowMs - 1000)
-      continue;
-    const allAboveOrEqual = orgSamples.every((s) => s.queued >= options.queuedThreshold), allBelow = orgSamples.every((s) => s.queued < options.queuedThreshold), isAlerting = alertStates.get(org)?.alerting ?? !1, current = orgSamples[orgSamples.length - 1];
-    if (isAlerting) {
-      if (allBelow)
-        actions.push({ org, action: "clear", current, sustainedMs });
-    } else if (allAboveOrEqual)
-      actions.push({ org, action: "fire", current, sustainedMs });
-  }
-  return actions;
-}

package/dist/runners.d.ts

@@ -1,6 +0,0 @@
-/**
- * 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 declare function fetchRepoActiveRuns(owner: string, name: string): Promise<{ running: number, queued: number }>;

package/dist/runners.js

@@ -1,26 +0,0 @@
-import { ghFetch, GITHUB_API } from "./client";
-export async function fetchRepoActiveRuns(owner, name) {
-  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 runs = (await runRes.json()).workflow_runs ?? [];
-    if (runs.length === 0)
-      return { running: 0, queued: 0 };
-    return (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();
-      let running = 0, queued = 0;
-      for (const j of jobsData.jobs ?? [])
-        if (j.status === "in_progress")
-          running++;
-        else if (j.status === "queued")
-          queued++;
-      return { running, queued };
-    }))).reduce((a, b) => ({ running: a.running + b.running, queued: a.queued + b.queued }), { running: 0, queued: 0 });
-  } catch {
-    return { running: 0, queued: 0 };
-  }
-}

package/dist/runs.d.ts

@@ -1,3 +0,0 @@
-import type { FailedJob, RepoStatus } from './types';
-export declare function fetchFailedJobs(owner: string, name: string, runId: number): Promise<FailedJob[]>;
-export declare function fetchRepoStatus(owner: string, name: string, defaultBranch: string): Promise<RepoStatus>;

package/dist/runs.js

@@ -1,84 +0,0 @@
-import { ghFetch, GITHUB_API } from "./client";
-async function fillLatestCommit(base, owner, name, branch) {
-  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(), [c] = commits;
-    if (!c)
-      return;
-    base.commitSha = c.sha.slice(0, 7);
-    base.commitMessage = c.commit.message.split(`
-`)[0] ?? null;
-    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 {}
-}
-export async function fetchFailedJobs(owner, name, runId) {
-  try {
-    const res = await ghFetch(`${GITHUB_API}/repos/${owner}/${name}/actions/runs/${runId}/jobs?filter=latest`);
-    if (!res.ok)
-      return [];
-    return (await res.json()).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, name, defaultBranch) {
-  const base = {
-    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(), [run] = data.workflow_runs ?? [];
-    if (!run) {
-      await fillLatestCommit(base, owner, name, defaultBranch);
-      return base;
-    }
-    base.workflowName = run.name;
-    base.commitSha = run.head_sha.slice(0, 7);
-    base.commitMessage = run.head_commit?.message.split(`
-`)[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/dist/types.d.ts

@@ -1,59 +0,0 @@
-export declare interface FailedJob {
-  name: string
-  conclusion: string
-  url: string
-}
-export declare 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 declare interface OrgRunnerUsage {
-  running: number
-  queued: number
-  cap: number
-}
-export declare interface DashboardData {
-  repos: RepoStatus[]
-  fetchedAt: string
-  total: number
-  passing: number
-  failing: number
-  pending: number
-  noRuns: number
-  runners: Record<string, OrgRunnerUsage>
-}
-export declare interface DashboardOptions {
-  orgs: string[]
-  runnerCaps?: Record<string, number>
-  defaultRunnerCap?: number
-  ignoreRepos?: string[]
-  cacheTtlMs?: number
-  cachePath?: string
-}
-export declare interface Repo {
-  name: string
-  owner: string
-  full_name: string
-  html_url: string
-  default_branch: string
-  archived: boolean
-}
-export type RepoStatusKind = 'success' | 'failure' | 'pending' | 'no_runs' | 'error';