@stacksjs/defaults 0.70.58 → 0.70.59

package/app/Actions/Dashboard/Auth/MeAction.ts

@@ -0,0 +1,84 @@
+import { Action } from '@stacksjs/actions'
+import { getUserRoles } from '@stacksjs/auth'
+
+interface MeResponse {
+  user: {
+    id: number
+    name: string | null
+    email: string | null
+  } | null
+  roles: string[]
+  /**
+   * Permissive defaults for the un-authenticated case (e.g. the dev dashboard
+   * on localhost where no bearer token is required). Surfaces are role-gated
+   * via `useRole()` which falls back to these when `user` is null, so the
+   * dashboard remains usable without auth.
+   */
+  unauthenticated?: true
+}
+
+/**
+ * `GET /api/dashboard/auth/me`
+ *
+ * Returns the currently-authenticated user plus the names of every role
+ * they hold. Powers the dashboard's `useRole()` composable
+ * ([stacksjs/stacks#1843](https://github.com/stacksjs/stacks/issues/1843))
+ * which gates dev-mode surfaces like CI tracking (#1844) and (eventually)
+ * client-mode hiding of infra surfaces.
+ *
+ * Auth model: this endpoint is intentionally **not** behind the `auth`
+ * middleware. The dashboard runs locally for `buddy dev --dashboard` with
+ * no bearer token at all, and we don't want every dashboard load to flash
+ * a 401 in the network tab. Instead:
+ *
+ *   - If the request carries a valid bearer token, the framework's auth
+ *     middleware already populated `request.user` — we return that user
+ *     plus their roles.
+ *   - If not, we return `{ user: null, roles: [], unauthenticated: true }`.
+ *     The composable's "no auth → assume dev" default kicks in client-side,
+ *     so the dashboard stays usable.
+ *
+ * In production where the dashboard sits behind auth, deploy with the
+ * `auth` middleware applied to the `/api/dashboard` group — the endpoint
+ * will then return real user/role data and `useRole()` will see the
+ * server-side identity.
+ */
+export default new Action({
+  name: 'Dashboard Auth Me',
+  description: 'Returns the authenticated user + their RBAC roles for dashboard role gating.',
+  method: 'GET',
+  apiResponse: true,
+  async handle(request) {
+    const user = (request as any)?.user ?? (request as any)?._authenticatedUser ?? null
+
+    if (!user || typeof user !== 'object' || typeof (user as { id?: unknown }).id !== 'number') {
+      const res: MeResponse = { user: null, roles: [], unauthenticated: true }
+      return res
+    }
+
+    const userId = (user as { id: number }).id
+
+    let roles: string[] = []
+    try {
+      const records = await getUserRoles(userId)
+      roles = records.map(r => r.name)
+    }
+    catch (err) {
+      // RBAC store not configured, migrations not run, or DB unreachable.
+      // Empty roles → useRole will fall back to its dev default. We don't
+      // want to 500 the dashboard just because the role tables haven't
+      // been migrated yet on a fresh project.
+      console.warn('[dashboard/auth/me] getUserRoles failed:', err instanceof Error ? err.message : err)
+    }
+
+    const res: MeResponse = {
+      user: {
+        id: userId,
+        name: (user as { name?: string | null }).name ?? null,
+        email: (user as { email?: string | null }).email ?? null,
+      },
+      roles,
+    }
+    return res
+  },
+})

package/app/Actions/Dashboard/BuddyDashboardAction.ts

@@ -0,0 +1,34 @@
+import { Action } from '@stacksjs/actions'
+
+export default new Action({
+  name: 'BuddyDashboardAction',
+  description: 'Returns Buddy CLI dashboard data including commands, output, and stats.',
+  method: 'GET',
+  async handle() {
+    const commands = [
+      { command: 'buddy build', description: 'Build the application', lastRun: '5m ago', status: 'success' },
+      { command: 'buddy dev', description: 'Start development server', lastRun: 'Running', status: 'running' },
+      { command: 'buddy test', description: 'Run test suite', lastRun: '1h ago', status: 'success' },
+      { command: 'buddy lint', description: 'Run linter', lastRun: '30m ago', status: 'success' },
+      { command: 'buddy deploy', description: 'Deploy to production', lastRun: '2d ago', status: 'success' },
+      { command: 'buddy migrate', description: 'Run database migrations', lastRun: '1d ago', status: 'success' },
+    ]
+
+    const recentOutput = `[14:32:45] Starting development server...
+[14:32:46] Compiling TypeScript...
+[14:32:48] Compiled successfully in 2.3s
+[14:32:48] Server running at http://localhost:3000
+[14:32:48] Hot reload enabled
+[14:32:50] Connected to database
+[14:32:50] Ready for requests`
+
+    const stats = [
+      { label: 'Commands Run', value: '1,234' },
+      { label: 'Avg Build Time', value: '2.3s' },
+      { label: 'Test Coverage', value: '89%' },
+      { label: 'Last Deploy', value: '2d ago' },
+    ]
+
+    return { commands, recentOutput, stats }
+  },
+})

package/app/Actions/Dashboard/Ci/RepoRunJobsAction.ts

@@ -0,0 +1,60 @@
+import { Action } from '@stacksjs/actions'
+import { dashboard as dashboardConfig } from '@stacksjs/config'
+import { fetchRunJobs } from '@stacksjs/github'
+
+/**
+ * `GET /api/dashboard/ci/repos/:owner/:name/runs/:runId/jobs`
+ * (stacksjs/stacks#1848).
+ *
+ * Returns the job-level breakdown for a single workflow run —
+ * surfaced when the user expands a failing row in the drilldown
+ * drawer. Pricier than the run list (one round-trip per request),
+ * so the page only fires this on demand.
+ *
+ * Same auth + scope model as `RepoRunsAction`: org must be in
+ * `config.dashboard.ci.orgs` for the endpoint to engage.
+ */
+export default new Action({
+  name: 'Dashboard CI Repo Run Jobs',
+  description: 'Job-level breakdown for a single workflow run (drilldown expand).',
+  method: 'GET',
+  apiResponse: true,
+  async handle(request) {
+    const ci = dashboardConfig?.ci
+
+    if (!ci?.enabled) {
+      return { jobs: [], disabled: true }
+    }
+
+    const owner = String((request as any)?.params?.owner ?? (request as any)?.param?.('owner') ?? '').trim()
+    const repo = String((request as any)?.params?.name ?? (request as any)?.param?.('name') ?? '').trim()
+    const runIdRaw = (request as any)?.params?.runId ?? (request as any)?.param?.('runId') ?? null
+    const runId = Number(runIdRaw)
+    if (!owner || !repo) {
+      return { error: 'Both `owner` and `name` route params are required.', status: 400 }
+    }
+    if (!Number.isFinite(runId) || runId <= 0) {
+      return { error: '`runId` must be a positive integer.', status: 400 }
+    }
+
+    const allowedOrgs = ci.orgs ?? []
+    if (allowedOrgs.length > 0 && !allowedOrgs.includes(owner)) {
+      return { error: 'Org not in `config.dashboard.ci.orgs`.', status: 403 }
+    }
+
+    try {
+      const jobs = await fetchRunJobs(owner, repo, runId)
+      return { owner, repo, runId, jobs }
+    }
+    catch (err) {
+      console.error('[dashboard/ci] RepoRunJobsAction failed:', err)
+      return {
+        owner,
+        repo,
+        runId,
+        jobs: [],
+        error: err instanceof Error ? err.message : 'unknown error',
+      }
+    }
+  },
+})

package/app/Actions/Dashboard/Ci/RepoRunsAction.ts

@@ -0,0 +1,67 @@
+import { Action } from '@stacksjs/actions'
+import { dashboard as dashboardConfig } from '@stacksjs/config'
+import { fetchWorkflowRuns } from '@stacksjs/github'
+
+/**
+ * `GET /api/dashboard/ci/repos/:owner/:name/runs?limit=N`
+ * (stacksjs/stacks#1848).
+ *
+ * Returns the N most recent workflow runs for a single repo. Used by
+ * the CI surface's drilldown drawer — clicking a repo card opens
+ * this and renders a timeline.
+ *
+ * Auth model mirrors the CI status endpoint:
+ *   - When the CI surface is disabled (`config.dashboard.ci.enabled
+ *     === false`), responds with an empty list rather than a 4xx so
+ *     the drawer renders an empty-state instead of an error.
+ *   - When `GITHUB_TOKEN` is missing, the helper bubbles an error
+ *     up through `fetchWorkflowRuns`; we catch it here and surface
+ *     it cleanly to the page.
+ */
+export default new Action({
+  name: 'Dashboard CI Repo Runs',
+  description: 'Latest N workflow runs for a single repo (drilldown).',
+  method: 'GET',
+  apiResponse: true,
+  async handle(request) {
+    const ci = dashboardConfig?.ci
+
+    if (!ci?.enabled) {
+      return { owner: null, repo: null, runs: [], disabled: true }
+    }
+
+    const owner = String((request as any)?.params?.owner ?? (request as any)?.param?.('owner') ?? '').trim()
+    const repo = String((request as any)?.params?.name ?? (request as any)?.param?.('name') ?? '').trim()
+    if (!owner || !repo) {
+      return { error: 'Both `owner` and `name` route params are required.', status: 400 }
+    }
+
+    // Scope check: only fetch runs for orgs the user explicitly
+    // configured. Stops the endpoint from being a generic GH proxy.
+    const allowedOrgs = ci.orgs ?? []
+    if (allowedOrgs.length > 0 && !allowedOrgs.includes(owner)) {
+      return { error: 'Org not in `config.dashboard.ci.orgs`.', status: 403 }
+    }
+
+    const url = new URL(request.url ?? `http://localhost/`)
+    const rawLimit = Number(url.searchParams.get('limit') ?? '20')
+    const limit = Number.isFinite(rawLimit) && rawLimit > 0
+      ? Math.min(Math.floor(rawLimit), 100)
+      : 20
+    const branch = url.searchParams.get('branch') || undefined
+
+    try {
+      const runs = await fetchWorkflowRuns(owner, repo, { limit, branch })
+      return { owner, repo, runs }
+    }
+    catch (err) {
+      console.error('[dashboard/ci] RepoRunsAction failed:', err)
+      return {
+        owner,
+        repo,
+        runs: [],
+        error: err instanceof Error ? err.message : 'unknown error',
+      }
+    }
+  },
+})

package/app/Actions/Dashboard/Ci/RunnerHistoryAction.ts

@@ -0,0 +1,58 @@
+import { Action } from '@stacksjs/actions'
+import { dashboard as dashboardConfig } from '@stacksjs/config'
+import { fetchRunnerHistory } from './runner-pressure-monitor'
+
+/**
+ * `GET /api/dashboard/ci/runner-history?org=stacksjs&limit=60`
+ * (stacksjs/stacks#1850).
+ *
+ * Returns the recent runner-sample history for one org so the CI
+ * page can render a small sparkline under each org's runner-pressure
+ * line. Bounded by `limit` (defaults to 60, hard cap 500) and the
+ * configured retention window — older samples aren't available
+ * because they've been pruned.
+ *
+ * Soft-errors to an empty samples array on any failure so the
+ * sparkline gracefully degrades to "no history yet" instead of
+ * yelling at the user.
+ */
+export default new Action({
+  name: 'Dashboard CI Runner History',
+  description: 'Recent runner-sample history for one org (sparkline data).',
+  method: 'GET',
+  apiResponse: true,
+  async handle(request) {
+    const ci = dashboardConfig?.ci
+    if (!ci?.enabled || !ci.alerts?.enabled) {
+      return { org: null, samples: [], disabled: true }
+    }
+
+    const url = new URL(request.url ?? 'http://localhost/')
+    const org = String(url.searchParams.get('org') ?? '').trim()
+    if (!org) {
+      return { error: '`org` query param is required.', status: 400 }
+    }
+
+    const allowedOrgs = ci.orgs ?? []
+    if (allowedOrgs.length > 0 && !allowedOrgs.includes(org)) {
+      return { error: 'Org not in `config.dashboard.ci.orgs`.', status: 403 }
+    }
+
+    const rawLimit = Number(url.searchParams.get('limit') ?? '60')
+    const limit = Number.isFinite(rawLimit) && rawLimit > 0
+      ? Math.min(Math.floor(rawLimit), 500)
+      : 60
+
+    try {
+      const samples = await fetchRunnerHistory(org, {
+        limit,
+        retentionHours: ci.alerts.retentionHours,
+      })
+      return { org, samples }
+    }
+    catch (err) {
+      console.error('[dashboard/ci] RunnerHistoryAction failed:', err)
+      return { org, samples: [], error: err instanceof Error ? err.message : 'unknown error' }
+    }
+  },
+})

package/app/Actions/Dashboard/Ci/StatusAction.ts

@@ -0,0 +1,73 @@
+import { Action } from '@stacksjs/actions'
+import { dashboard as dashboardConfig } from '@stacksjs/config'
+import { getDashboardData } from '@stacksjs/github'
+import { runCiFailureNotifier } from './failure-notifier'
+import { runRunnerPressureMonitor } from './runner-pressure-monitor'
+
+/**
+ * `GET /api/dashboard/ci/status`
+ *
+ * Aggregated CI / runner snapshot consumed by `dashboard/ci/index.stx`.
+ * Reads org list + runner caps from `config/dashboard.ts:ci.*` so installs
+ * pick their own surface (stacksjs/stacks#1844). When the surface is
+ * disabled or no orgs are configured, returns an empty snapshot rather
+ * than throwing — the page renders an empty-state in that case.
+ */
+export default new Action({
+  name: 'Dashboard CI Status',
+  description: 'Aggregated CI/runner snapshot across the configured GitHub orgs.',
+  method: 'GET',
+  apiResponse: true,
+  async handle() {
+    const ci = dashboardConfig?.ci
+
+    if (!ci?.enabled || !ci.orgs || ci.orgs.length === 0) {
+      return {
+        repos: [],
+        fetchedAt: new Date().toISOString(),
+        total: 0,
+        passing: 0,
+        failing: 0,
+        pending: 0,
+        noRuns: 0,
+        runners: {},
+        disabled: !ci?.enabled,
+      }
+    }
+
+    try {
+      const data = await getDashboardData({
+        orgs: ci.orgs,
+        runnerCaps: ci.runnerCaps,
+        defaultRunnerCap: ci.runnerCapDefault,
+        ignoreRepos: ci.ignoreRepos,
+      })
+      // Failing-CI notifications (stacksjs/stacks#1849) +
+      // runner-pressure alerts (stacksjs/stacks#1850). Both
+      // fire-and-forget so they don't block the response on the
+      // notification + time-series persistence round-trips. Each
+      // internally guards on its own enabled flag, so unrelated
+      // projects pay no cost.
+      void runCiFailureNotifier(data)
+      void runRunnerPressureMonitor(data)
+      return data
+    }
+    catch (err) {
+      // Most likely cause: GITHUB_TOKEN missing. Surface a clean error
+      // shape the page can render without leaking the env-var name to
+      // every browser viewing the dashboard.
+      console.error('[dashboard/ci] snapshot failed:', err)
+      return {
+        repos: [],
+        fetchedAt: new Date().toISOString(),
+        total: 0,
+        passing: 0,
+        failing: 0,
+        pending: 0,
+        noRuns: 0,
+        runners: {},
+        error: err instanceof Error ? err.message : 'unknown error',
+      }
+    }
+  },
+})

package/app/Actions/Dashboard/Ci/failure-notifier.ts

@@ -0,0 +1,214 @@
+/**
+ * CI failure notifier (stacksjs/stacks#1849).
+ *
+ * Bridges the pure `detectNewlyFailedRuns()` from @stacksjs/github
+ * with the persistence layer (the `ci_run_states` table) and the
+ * notification fan-out (`notify()` from @stacksjs/notifications).
+ *
+ * Lives in defaults — not in @stacksjs/github — because it pulls in
+ * the DB + notify infrastructure that the pure helper deliberately
+ * stays free of.
+ *
+ * Call from the CI StatusAction after a fresh snapshot resolves:
+ *
+ *   void runCiFailureNotifier(snapshot)
+ *
+ * `void` because we don't want to block the response on the
+ * notification round-trips. The fan-out happens behind the user's
+ * back; any failure is logged but doesn't bubble.
+ */
+
+import type { DashboardData, FailedTransition, PreviousRunState } from '@stacksjs/github'
+import { dashboard as dashboardConfig } from '@stacksjs/config'
+import { db } from '@stacksjs/database'
+import { detectNewlyFailedRuns } from '@stacksjs/github'
+import { notify } from '@stacksjs/notifications'
+
+interface CiRunStateRow {
+  repo_full_name: string
+  last_conclusion: string | null
+  last_run_id: number | null
+  last_seen_at: string | null
+  last_notified_at: string | null
+}
+
+/** Load the dashboard's last-seen state for every repo in one query. */
+async function loadPreviousStates(): Promise<Map<string, PreviousRunState>> {
+  const rows = await db.unsafe(
+    'SELECT repo_full_name, last_conclusion, last_run_id, last_notified_at FROM ci_run_states',
+  ).execute() as CiRunStateRow[]
+
+  const map = new Map<string, PreviousRunState>()
+  for (const r of rows ?? []) {
+    map.set(r.repo_full_name, {
+      repoFullName: r.repo_full_name,
+      lastConclusion: r.last_conclusion,
+      lastRunId: r.last_run_id == null ? null : Number(r.last_run_id),
+      lastNotifiedAt: r.last_notified_at,
+    })
+  }
+  return map
+}
+
+/**
+ * Upsert every repo in the snapshot's current state. Doesn't touch
+ * `last_notified_at` — that's owned by the notifier and only bumped
+ * when we actually fire.
+ */
+async function upsertSnapshotStates(snapshot: DashboardData): Promise<void> {
+  if (!snapshot.repos?.length) return
+  const nowIso = new Date().toISOString()
+  for (const r of snapshot.repos) {
+    const runId = parseRunIdFromUrl(r.runUrl)
+    // Two-step upsert — works across SQLite/MySQL/Postgres without
+    // dialect-specific ON CONFLICT shapes. Each repo is its own
+    // round-trip, but the table is small (one row per repo, so
+    // typically O(50) for a busy fleet) and this runs in the
+    // background after the response goes out.
+    const existing = await db.unsafe(
+      'SELECT repo_full_name FROM ci_run_states WHERE repo_full_name = ? LIMIT 1',
+      [r.fullName],
+    ).execute() as Array<{ repo_full_name: string }>
+    if (existing?.length) {
+      await db.updateTable('ci_run_states').set({
+        last_conclusion: r.conclusion ?? r.status,
+        last_run_id: runId,
+        last_seen_at: nowIso,
+        updated_at: nowIso,
+      } as any).where('repo_full_name', '=', r.fullName).execute()
+    }
+    else {
+      await db.insertInto('ci_run_states').values({
+        repo_full_name: r.fullName,
+        last_conclusion: r.conclusion ?? r.status,
+        last_run_id: runId,
+        last_seen_at: nowIso,
+        updated_at: nowIso,
+      } as any).execute()
+    }
+  }
+}
+
+/** Bump `last_notified_at` for the repos we just fired on. */
+async function markNotified(transitions: FailedTransition[]): Promise<void> {
+  if (!transitions.length) return
+  const nowIso = new Date().toISOString()
+  for (const t of transitions) {
+    await db.updateTable('ci_run_states')
+      .set({ last_notified_at: nowIso } as any)
+      .where('repo_full_name', '=', t.repoFullName)
+      .execute()
+  }
+}
+
+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
+}
+
+/** Build the human-readable payload for a single transition. */
+function buildPayload(t: FailedTransition): { subject: string, body: string, data: Record<string, unknown> } {
+  const shortSha = t.commitSha ? t.commitSha.slice(0, 7) : ''
+  const commit = t.commitMessage ? `${shortSha} ${t.commitMessage.split('\n')[0]}` : shortSha
+  const workflow = t.workflowName ? ` (${t.workflowName})` : ''
+  const author = t.commitAuthor ? ` — ${t.commitAuthor}` : ''
+  const subject = `CI failed: ${t.repoFullName}${workflow}`
+  const lines = [
+    `${t.repoFullName}${workflow}`,
+    `Conclusion: ${t.conclusion}`,
+  ]
+  if (commit) lines.push(`Commit: ${commit}${author}`)
+  if (t.runUrl) lines.push(`Run: ${t.runUrl}`)
+  return {
+    subject,
+    body: lines.join('\n'),
+    data: {
+      repoFullName: t.repoFullName,
+      runId: t.runId,
+      runUrl: t.runUrl,
+      conclusion: t.conclusion,
+      previousConclusion: t.previousConclusion,
+      commitSha: t.commitSha,
+    },
+  }
+}
+
+/**
+ * Run the full detect → notify → persist cycle for a fresh snapshot.
+ *
+ * Caller pattern: `void runCiFailureNotifier(snapshot)` from the
+ * StatusAction. The cycle:
+ *
+ *   1. Skip entirely if `ci.notifications.enabled` is false.
+ *   2. Load previous states from `ci_run_states`.
+ *   3. Run the pure detector with the configured cooldown.
+ *   4. For each transition, fan out via `notify()` to every
+ *      configured recipient × channel combination.
+ *      - `chat` channel doesn't need recipients (it broadcasts to
+ *        the configured Slack channel) — emit one notification with
+ *        no recipient details.
+ *      - Email / sms / database channels iterate the
+ *        `recipients` list.
+ *   5. Upsert the current state for every repo (so next call has a
+ *      diff baseline).
+ *   6. Bump `last_notified_at` for the repos we fired on.
+ *
+ * Errors at any step are logged and swallowed — a broken notifier
+ * must never take down the dashboard's read path.
+ */
+export async function runCiFailureNotifier(snapshot: DashboardData): Promise<void> {
+  const ci = dashboardConfig?.ci
+  const notifs = ci?.notifications
+  if (!notifs?.enabled || !snapshot.repos?.length)
+    return
+
+  const channels = (notifs.channels ?? ['chat']) as Array<'email' | 'sms' | 'chat' | 'database'>
+  const cooldownMs = (notifs.cooldownMinutes ?? 5) * 60_000
+  const recipients = notifs.recipients ?? []
+
+  try {
+    const previousStates = await loadPreviousStates()
+    const transitions = detectNewlyFailedRuns(snapshot, previousStates, { cooldownMs })
+
+    // Fan out. Each transition fires once per (recipient × channel)
+    // combination. For channels that don't need a recipient (chat),
+    // we still fire once per transition with an empty recipient
+    // record — the chat driver ignores recipient fields.
+    for (const t of transitions) {
+      const payload = buildPayload(t)
+      const broadcastChannels = channels.filter(c => c === 'chat')
+      const recipientChannels = channels.filter(c => c !== 'chat')
+
+      if (broadcastChannels.length > 0) {
+        try {
+          await notify({}, payload, broadcastChannels, { ignorePreferences: true })
+        }
+        catch (err) {
+          console.warn('[ci-failure-notifier] chat broadcast failed:', err)
+        }
+      }
+      if (recipientChannels.length > 0 && recipients.length > 0) {
+        for (const r of recipients) {
+          try {
+            await notify(r, payload, recipientChannels, { ignorePreferences: true })
+          }
+          catch (err) {
+            console.warn('[ci-failure-notifier] notify failed:', err)
+          }
+        }
+      }
+    }
+
+    // Order matters: upsert states FIRST so the next refresh sees
+    // the current conclusion + run id, then mark-notified to update
+    // `last_notified_at` on the rows we fired on.
+    await upsertSnapshotStates(snapshot)
+    await markNotified(transitions)
+  }
+  catch (err) {
+    console.warn('[ci-failure-notifier] cycle failed:', err)
+  }
+}