@stacksjs/github 0.70.53

package/README.md

@@ -0,0 +1,26 @@
+# @stacksjs/github
+
+GitHub API client used by Stacks framework features. Currently powers the
+dashboard CI surface ([#1844](https://github.com/stacksjs/stacks/issues/1844));
+designed to be reused by future surfaces (failing-CI notifications, runner
+alerts, kanban→PR links, etc.).
+
+## What's in here
+
+- `getDashboardData()` — aggregated CI/runner snapshot across a configured
+
+  list of orgs, with on-disk caching and stale-while-revalidate semantics.
+
+- Lower-level helpers (`fetchAllRepos`, `fetchRepoStatus`, `fetchBotPRCounts`,
+
+  `fetchRepoActiveRuns`) for callers that need a single dimension.
+
+- A retrying `ghFetch` that respects GitHub's `Retry-After` /
+
+  `x-ratelimit-reset` headers so callers don't have to.
+
+## Auth
+
+A `GITHUB_TOKEN` environment variable is required. The token only needs
+`public_repo` scope for the default reads — bump permissions only if you
+add endpoints that need them.

package/dist/index.js

@@ -0,0 +1,18 @@
+// @bun
+export {
+  mapWithConcurrency,
+  ghHeaders,
+  ghFetch,
+  getDashboardData,
+  fetchWorkflowRuns,
+  fetchRunJobs,
+  fetchRepoStatus,
+  fetchRepoActiveRuns,
+  fetchFailedJobs,
+  fetchBotPRCounts,
+  fetchAllRepos,
+  detectRunnerPressure,
+  detectNewlyFailedRuns,
+  clearDashboardCache,
+  GITHUB_API
+};

package/dist/src/bots.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 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/src/client.d.ts

@@ -0,0 +1,15 @@
+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/src/dashboard.d.ts

@@ -0,0 +1,17 @@
+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/src/failure-detector.d.ts

@@ -0,0 +1,59 @@
+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/src/index.d.ts

@@ -0,0 +1,35 @@
+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/src/repos.d.ts

@@ -0,0 +1,7 @@
+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/src/run-history.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 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/src/runner-pressure-detector.d.ts

@@ -0,0 +1,74 @@
+/**
+ * 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/src/runners.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 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/src/runs.d.ts

@@ -0,0 +1,3 @@
+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/src/types.d.ts

@@ -0,0 +1,59 @@
+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';

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@stacksjs/github",
+  "type": "module",
+  "version": "0.70.53",
+  "description": "GitHub API client used by Stacks framework features (dashboard CI surface, notifications, runner alerts).",
+  "author": "Chris Breuer",
+  "contributors": [
+    "Chris Breuer <chris@stacksjs.com>"
+  ],
+  "license": "MIT",
+  "funding": "https://github.com/sponsors/chrisbbreuer",
+  "homepage": "https://github.com/stacksjs/stacks/tree/main/storage/framework/core/github#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stacksjs/stacks.git",
+    "directory": "./storage/framework/core/github"
+  },
+  "bugs": {
+    "url": "https://github.com/stacksjs/stacks/issues"
+  },
+  "keywords": [
+    "github",
+    "ci",
+    "actions",
+    "workflows",
+    "dashboard",
+    "stacks"
+  ],
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "README.md",
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun build.ts",
+    "typecheck": "bun tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "devDependencies": {
+    "better-dx": "^0.2.12"
+  },
+  "sideEffects": false
+}