@0xbigboss/gh-pulse 1.0.0

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@0xbigboss/gh-pulse",
+  "version": "1.0.0",
+  "description": "GitHub analytics CLI for engineering visibility - PR metrics, contribution stats, team health",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/0xbigboss/gh-pulse"
+  },
+  "bin": {
+    "gh-pulse": "src/index.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "type": "module",
+  "scripts": {
+    "build": "echo 'no build step'",
+    "start": "bun src/index.ts"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "dependencies": {
+    "@0xbigboss/gh-pulse-core": "^1.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,947 @@
+#!/usr/bin/env bun
+import {
+  Cache,
+  GitHubClient,
+  loadConfig,
+  periodToRange,
+  resolveSince,
+  resolveUntil,
+  resolveRepos,
+  resolveTeamMembers,
+  syncRepos,
+  formatTimestamp,
+} from '@0xbigboss/gh-pulse-core'
+import type { ProgressEvent, Report, ReportInputs } from '@0xbigboss/gh-pulse-core'
+import {
+  buildPersonalReport,
+  buildTeamReport,
+  buildExecReport,
+  buildReportMeta,
+} from '@0xbigboss/gh-pulse-core'
+
+const USAGE = `gh-pulse [options]
+
+AUDIENCE
+  --for, -f <target>     me | team | exec | @<username>
+  --period, -p <period>  today | week | sprint | month | quarter
+  --since <date>         Start date (ISO 8601 or relative: 7d, 2w, 1m)
+  --until <date>         End date (ISO 8601 or relative)
+
+SCOPE
+  --repos, -r <pattern>  Repo filter (glob or comma-list)
+  --org, -o <org>        GitHub org to scan
+
+OUTPUT
+  --format <fmt>         table | json | markdown
+  --sort <field>         Sort by field
+  --quiet, -q            Suppress progress output
+  --verbose, -v          Show detailed progress
+
+CONFIG
+  --config, -c <path>    Config file path
+  --sync                 Force fresh sync (ignore cache TTL)
+
+FILTERS
+  --blockers             Focus on stale/stuck PRs only
+  --include-drafts       Include draft PRs in metrics
+`
+
+type OutputFormat = 'table' | 'json' | 'markdown'
+
+type ForTarget = 'me' | 'team' | 'exec' | string
+
+type Period = 'today' | 'week' | 'sprint' | 'month' | 'quarter'
+
+interface CliOptions {
+  forTarget: ForTarget
+  period: Period
+  format: OutputFormat
+  repos?: string
+  orgs?: string
+  since?: string
+  until?: string
+  configPath?: string
+  blockers: boolean
+  includeDrafts: boolean
+  sort?: string
+  quiet: boolean
+  verbose: boolean
+  sync: boolean
+  help: boolean
+}
+
+const DEFAULTS: CliOptions = {
+  forTarget: 'me',
+  period: 'week',
+  format: 'table',
+  blockers: false,
+  includeDrafts: false,
+  quiet: false,
+  verbose: false,
+  sync: false,
+  help: false,
+}
+
+async function main(): Promise<void> {
+  const args = parseArgs(process.argv.slice(2))
+  if (args.help) {
+    console.log(USAGE)
+    return
+  }
+  validateOptions(args)
+
+  const showProgress = !args.quiet && (args.verbose || Boolean(process.stderr.isTTY))
+  const onProgress = showProgress ? createProgressHandler({ verbose: args.verbose }) : undefined
+
+  const config = await loadConfig(args.configPath ? { path: args.configPath } : {})
+  const github = new GitHubClient({ token: config.github_token })
+
+  const target = await resolveTarget(args.forTarget, github)
+  const orgOverrides = args.orgs
+    ? args.orgs
+        .split(',')
+        .map((org) => org.trim())
+        .filter(Boolean)
+    : []
+  const repoPatterns = args.repos
+    ? args.repos
+        .split(',')
+        .map((repo) => repo.trim())
+        .filter(Boolean)
+    : []
+
+  const repos = await resolveRepos({
+    config,
+    github,
+    orgs: orgOverrides,
+    repoPatterns,
+    strict: true,
+    ...(onProgress ? { onProgress } : {}),
+  })
+
+  if (repos.length === 0) {
+    console.log('No repositories matched the current configuration.')
+    return
+  }
+
+  const now = new Date()
+  const timeRange = resolveTimeRange(args, config.timezone, now)
+
+  const cache = await Cache.open({ path: config.cache.path })
+  try {
+    await syncRepos({
+      repos,
+      cache,
+      github,
+      config,
+      timeRange,
+      forceSync: args.sync,
+      ...(onProgress ? { onProgress } : {}),
+    })
+
+    const teamMembers = await resolveTeamMembers({ config, github, repos, orgs: orgOverrides })
+    const excludeAuthors = new Set(config.exclude.authors)
+
+    const reportInputs: ReportInputs = {
+      repos,
+      timeRange,
+      includeDrafts: args.includeDrafts,
+      blockersOnly: args.blockers,
+      excludeAuthors,
+      excludeBots: config.exclude.bots,
+      teamMembers,
+      thresholds: {
+        stale_days: config.thresholds.stale_days,
+        stuck_days: config.thresholds.stuck_days,
+        large_pr_lines: config.thresholds.large_pr_lines ?? 500,
+      },
+      ...(target.user ? { subjectUser: target.user } : {}),
+    }
+
+    const report = buildReport(target, cache, reportInputs)
+    if (isEmptyPersonalReport(report)) {
+      console.log(`No activity found for @${report.user} in ${report.meta.period_label}`)
+      return
+    }
+
+    const sortedReport = applySort(report, args.sort)
+    const output = formatReport(
+      sortedReport,
+      args.format,
+      config.timezone,
+      args.blockers,
+      config.thresholds,
+    )
+    console.log(output)
+  } finally {
+    cache.close()
+  }
+}
+
+function parseArgs(argv: string[]): CliOptions {
+  const options: CliOptions = { ...DEFAULTS }
+
+  let index = 0
+  while (index < argv.length) {
+    const arg = argv[index]
+    if (!arg) {
+      break
+    }
+    if (arg === '--help' || arg === '-h') {
+      options.help = true
+      index += 1
+      continue
+    }
+
+    if (arg === '--blockers') {
+      options.blockers = true
+      index += 1
+      continue
+    }
+
+    if (arg === '--include-drafts') {
+      options.includeDrafts = true
+      index += 1
+      continue
+    }
+    if (arg === '--quiet' || arg === '-q') {
+      options.quiet = true
+      index += 1
+      continue
+    }
+    if (arg === '--verbose' || arg === '-v') {
+      options.verbose = true
+      index += 1
+      continue
+    }
+    if (arg === '--sync') {
+      options.sync = true
+      index += 1
+      continue
+    }
+
+    const [flag, inlineValue] =
+      arg.startsWith('--') && arg.includes('=') ? arg.split('=') : [arg, undefined]
+
+    if (inlineValue !== undefined) {
+      applyOption(options, flag, inlineValue)
+      index += 1
+      continue
+    }
+
+    const next = argv[index + 1]
+    if (!next || next.startsWith('-')) {
+      throw new Error(`Missing value for ${flag}`)
+    }
+
+    applyOption(options, flag, next)
+    index += 2
+  }
+
+  return options
+}
+
+function createProgressHandler(options: { verbose: boolean }): (event: ProgressEvent) => void {
+  return (event) => {
+    const progress =
+      typeof event.current === 'number' && typeof event.total === 'number'
+        ? ` (${event.current}/${event.total})`
+        : ''
+    const prefix = options.verbose ? `[${event.phase}] ` : ''
+    process.stderr.write(`${prefix}${event.message}${progress}\n`)
+  }
+}
+
+function applyOption(options: CliOptions, flag: string, value: string): void {
+  switch (flag) {
+    case '--for':
+    case '-f':
+      options.forTarget = value
+      return
+    case '--period':
+    case '-p':
+      options.period = value as Period
+      return
+    case '--format':
+      options.format = value as OutputFormat
+      return
+    case '--repos':
+    case '-r':
+      options.repos = value
+      return
+    case '--org':
+    case '-o':
+      options.orgs = value
+      return
+    case '--since':
+      options.since = value
+      return
+    case '--until':
+      options.until = value
+      return
+    case '--config':
+    case '-c':
+      options.configPath = value
+      return
+    case '--sort':
+      options.sort = value
+      return
+    default:
+      throw new Error(`Unknown argument: ${flag}`)
+  }
+}
+
+function validateOptions(options: CliOptions): void {
+  const validPeriods: Period[] = ['today', 'week', 'sprint', 'month', 'quarter']
+  if (!validPeriods.includes(options.period)) {
+    throw new Error(`Invalid period: ${options.period}`)
+  }
+
+  const validFormats: OutputFormat[] = ['table', 'json', 'markdown']
+  if (!validFormats.includes(options.format)) {
+    throw new Error(`Invalid format: ${options.format}`)
+  }
+}
+
+async function resolveTarget(
+  forTarget: ForTarget,
+  github: GitHubClient,
+): Promise<{
+  audience: 'personal' | 'individual' | 'team' | 'exec'
+  user?: string
+}> {
+  if (forTarget === 'team') {
+    return { audience: 'team' }
+  }
+  if (forTarget === 'exec') {
+    return { audience: 'exec' }
+  }
+  if (forTarget === 'me') {
+    const user = await github.getAuthenticatedUsername()
+    return { audience: 'personal', user }
+  }
+
+  const user = forTarget.startsWith('@') ? forTarget.slice(1) : forTarget
+  const exists = await github.userExists(user)
+  if (!exists) {
+    throw new Error(`User not found: ${user}`)
+  }
+  return { audience: 'individual', user }
+}
+
+function resolveTimeRange(
+  options: CliOptions,
+  timeZone: string,
+  now: Date,
+): {
+  start: number
+  end: number
+  label: string
+} {
+  const basePeriod = periodToRange(options.period, now, timeZone)
+
+  if (options.since || options.until) {
+    const start = options.since ? resolveSince(options.since, now) : basePeriod.start
+    const end = options.until ? resolveUntil(options.until, now) : now.getTime()
+    if (start > end) {
+      throw new Error('Invalid time range: start is after end')
+    }
+    const label = `custom ${options.since ?? 'start'} → ${options.until ?? 'now'}`
+    return { start, end, label }
+  }
+
+  return basePeriod
+}
+
+function buildReport(
+  target: { audience: 'personal' | 'individual' | 'team' | 'exec'; user?: string },
+  cache: Cache,
+  inputs: ReportInputs,
+): Report {
+  const meta = buildReportMeta({
+    audience: target.audience,
+    repos: inputs.repos,
+    periodLabel: inputs.timeRange.label,
+    start: inputs.timeRange.start,
+    end: inputs.timeRange.end,
+    cache,
+  })
+
+  switch (target.audience) {
+    case 'personal':
+    case 'individual':
+      if (!target.user) {
+        throw new Error('Missing user for personal report')
+      }
+      return buildPersonalReport(cache, {
+        ...inputs,
+        user: target.user,
+        meta,
+      })
+    case 'team':
+      return buildTeamReport(cache, { ...inputs, meta })
+    case 'exec':
+      return buildExecReport(cache, { ...inputs, meta })
+    default: {
+      const _exhaustive: never = target.audience
+      throw new Error(`Unhandled audience: ${_exhaustive}`)
+    }
+  }
+}
+
+function formatReport(
+  report: Report,
+  format: OutputFormat,
+  timeZone: string,
+  blockersOnly: boolean,
+  thresholds: { stale_days: number; stuck_days: number },
+): string {
+  if (format === 'json') {
+    return JSON.stringify(report, null, 2)
+  }
+
+  if (format === 'markdown') {
+    return formatMarkdown(report, timeZone, blockersOnly, thresholds)
+  }
+
+  return formatTable(report, timeZone, blockersOnly, thresholds)
+}
+
+function formatHeader(report: Report, timeZone: string): string[] {
+  const meta = report.meta
+  const lines: string[] = []
+  lines.push(`Audience: ${meta.audience}`)
+  lines.push(`Period: ${meta.period_label}`)
+  lines.push(
+    `Range: ${formatTimestamp(meta.start, timeZone)} → ${formatTimestamp(meta.end, timeZone)}`,
+  )
+  lines.push(`Repos: ${meta.repos.length}`)
+
+  const freshness = meta.data_freshness
+  if (freshness.dataAsOf) {
+    lines.push(`Data as of: ${formatTimestamp(freshness.dataAsOf, timeZone)}`)
+  }
+  if (freshness.cacheAgeMinutes !== null) {
+    lines.push(`Cache age: ${freshness.cacheAgeMinutes} minutes`)
+  }
+  lines.push(`Repos synced: ${freshness.reposSynced}/${freshness.totalRepos}`)
+  return lines
+}
+
+function formatTable(
+  report: Report,
+  timeZone: string,
+  blockersOnly: boolean,
+  thresholds: { stale_days: number; stuck_days: number },
+): string {
+  const sections: string[] = []
+  sections.push('gh-pulse report')
+  sections.push(...formatHeader(report, timeZone))
+  sections.push('')
+
+  switch (report.type) {
+    case 'personal':
+    case 'individual': {
+      if (blockersOnly) {
+        sections.push('Blockers')
+        const blockers = deriveBlockers(report, thresholds)
+        sections.push(
+          renderTable(
+            ['Repo', 'PR', 'Status', 'Days'],
+            blockers.map((b) => [b.repo, b.pr, b.status, `${b.days}`]),
+          ),
+        )
+        break
+      }
+
+      sections.push('Summary')
+      sections.push(
+        renderTable(
+          ['Metric', 'Value'],
+          [
+            ['PRs opened', `${report.summary.prs_opened}`],
+            ['PRs merged', `${report.summary.prs_merged}`],
+            ['PRs closed', `${report.summary.prs_closed}`],
+            ['Commits', `${report.summary.commits}`],
+            ['Repos touched', `${report.summary.repos_touched}`],
+            ['Lines changed', `${report.summary.lines_changed}`],
+          ],
+        ),
+      )
+
+      sections.push('Open Work')
+      sections.push(
+        renderTable(
+          ['Repo', 'PR', 'Age (days)', 'Title'],
+          report.open_work.open_prs.map((pr) => [
+            pr.repo,
+            `#${pr.number}`,
+            `${pr.age_days}`,
+            pr.title,
+          ]),
+        ),
+      )
+
+      sections.push('Review Debt - Requested')
+      sections.push(
+        renderTable(
+          ['Repo', 'PR', 'Author', 'Age (days)', 'Title'],
+          report.review_debt.requested.map((pr) => [
+            pr.repo,
+            `#${pr.number}`,
+            pr.author,
+            `${pr.age_days}`,
+            pr.title,
+          ]),
+        ),
+      )
+
+      sections.push('Review Debt - Team PRs')
+      sections.push(
+        renderTable(
+          ['Repo', 'PR', 'Author', 'Age (days)', 'Title'],
+          report.review_debt.team_prs.map((pr) => [
+            pr.repo,
+            `#${pr.number}`,
+            pr.author,
+            `${pr.age_days}`,
+            pr.title,
+          ]),
+        ),
+      )
+      break
+    }
+    case 'team': {
+      if (blockersOnly) {
+        sections.push('Blockers')
+        sections.push(
+          renderTable(
+            ['Repo', 'PR', 'Owner', 'Status', 'Days'],
+            report.blockers.map((blocker) => [
+              blocker.pr.repo,
+              `#${blocker.pr.number}`,
+              blocker.pr.author,
+              blocker.status,
+              `${blocker.days}`,
+            ]),
+          ),
+        )
+        break
+      }
+
+      sections.push('Velocity')
+      sections.push(
+        renderTable(
+          ['Metric', 'Value'],
+          [
+            ['PRs opened', `${report.velocity.prs_opened}`],
+            ['PRs merged', `${report.velocity.prs_merged}`],
+            ['PRs closed', `${report.velocity.prs_closed}`],
+            ['Cycle time p50 (ms)', `${report.velocity.cycle_time_p50 ?? 'n/a'}`],
+            ['Cycle time p90 (ms)', `${report.velocity.cycle_time_p90 ?? 'n/a'}`],
+            ['Review turnaround p50 (ms)', `${report.velocity.review_turnaround_p50 ?? 'n/a'}`],
+            ['Review turnaround p90 (ms)', `${report.velocity.review_turnaround_p90 ?? 'n/a'}`],
+          ],
+        ),
+      )
+
+      sections.push('Member Breakdown')
+      sections.push(
+        renderTable(
+          ['User', 'PRs authored', 'PRs reviewed', 'Commits', 'Lines changed'],
+          report.members.map((member) => [
+            member.user,
+            `${member.prs_authored}`,
+            `${member.prs_reviewed}`,
+            `${member.commits}`,
+            `${member.lines_changed}`,
+          ]),
+        ),
+      )
+
+      sections.push('Blockers')
+      sections.push(
+        renderTable(
+          ['Repo', 'PR', 'Owner', 'Status', 'Days'],
+          report.blockers.map((blocker) => [
+            blocker.pr.repo,
+            `#${blocker.pr.number}`,
+            blocker.pr.author,
+            blocker.status,
+            `${blocker.days}`,
+          ]),
+        ),
+      )
+      break
+    }
+    case 'exec': {
+      sections.push('Velocity Trends')
+      sections.push(
+        renderTable(
+          ['Week start', 'PRs merged', 'Cycle time p50 (ms)'],
+          report.velocity_trends.map((trend) => [
+            formatTimestamp(trend.bucket_start, timeZone),
+            `${trend.prs_merged}`,
+            `${trend.cycle_time_p50 ?? 'n/a'}`,
+          ]),
+        ),
+      )
+
+      sections.push('Repo Health')
+      sections.push(
+        renderTable(
+          ['Repo', 'Status', 'Last activity'],
+          report.repo_health.map((entry) => [
+            entry.repo,
+            entry.status,
+            entry.last_activity_at ? formatTimestamp(entry.last_activity_at, timeZone) : 'n/a',
+          ]),
+        ),
+      )
+
+      sections.push('Highlights')
+      sections.push(
+        renderTable(
+          ['Repo', 'PR', 'Reasons'],
+          report.highlights.map((entry) => [
+            entry.pr.repo,
+            `#${entry.pr.number}`,
+            entry.reasons.join('; '),
+          ]),
+        ),
+      )
+
+      sections.push('Team Breakdown')
+      sections.push(
+        renderTable(
+          ['User', 'PRs authored', 'PRs reviewed', 'Commits', 'Lines changed'],
+          report.team_breakdown.map((member) => [
+            member.user,
+            `${member.prs_authored}`,
+            `${member.prs_reviewed}`,
+            `${member.commits}`,
+            `${member.lines_changed}`,
+          ]),
+        ),
+      )
+      break
+    }
+    default: {
+      const _exhaustive: never = report
+      throw new Error(`Unhandled report type: ${_exhaustive}`)
+    }
+  }
+
+  return sections.join('\n')
+}
+
+function formatMarkdown(
+  report: Report,
+  timeZone: string,
+  blockersOnly: boolean,
+  thresholds: { stale_days: number; stuck_days: number },
+): string {
+  const lines: string[] = []
+  lines.push(`# gh-pulse ${report.type} report`)
+  lines.push('')
+  formatHeader(report, timeZone).forEach((line) => lines.push(`- ${line}`))
+  lines.push('')
+
+  const renderMarkdownTable = (headers: string[], rows: string[][]): void => {
+    lines.push(`| ${headers.join(' | ')} |`)
+    lines.push(`| ${headers.map(() => '---').join(' | ')} |`)
+    rows.forEach((row) => lines.push(`| ${row.join(' | ')} |`))
+    lines.push('')
+  }
+
+  switch (report.type) {
+    case 'personal':
+    case 'individual': {
+      if (blockersOnly) {
+        lines.push('## Blockers')
+        const blockers = deriveBlockers(report, thresholds)
+        renderMarkdownTable(
+          ['Repo', 'PR', 'Status', 'Days'],
+          blockers.map((b) => [b.repo, b.pr, b.status, `${b.days}`]),
+        )
+        break
+      }
+
+      lines.push('## Summary')
+      renderMarkdownTable(
+        ['Metric', 'Value'],
+        [
+          ['PRs opened', `${report.summary.prs_opened}`],
+          ['PRs merged', `${report.summary.prs_merged}`],
+          ['PRs closed', `${report.summary.prs_closed}`],
+          ['Commits', `${report.summary.commits}`],
+          ['Repos touched', `${report.summary.repos_touched}`],
+          ['Lines changed', `${report.summary.lines_changed}`],
+        ],
+      )
+
+      lines.push('## Open Work')
+      renderMarkdownTable(
+        ['Repo', 'PR', 'Age (days)', 'Title'],
+        report.open_work.open_prs.map((pr) => [
+          pr.repo,
+          `#${pr.number}`,
+          `${pr.age_days}`,
+          pr.title,
+        ]),
+      )
+
+      lines.push('## Review Debt - Requested')
+      renderMarkdownTable(
+        ['Repo', 'PR', 'Author', 'Age (days)', 'Title'],
+        report.review_debt.requested.map((pr) => [
+          pr.repo,
+          `#${pr.number}`,
+          pr.author,
+          `${pr.age_days}`,
+          pr.title,
+        ]),
+      )
+
+      lines.push('## Review Debt - Team PRs')
+      renderMarkdownTable(
+        ['Repo', 'PR', 'Author', 'Age (days)', 'Title'],
+        report.review_debt.team_prs.map((pr) => [
+          pr.repo,
+          `#${pr.number}`,
+          pr.author,
+          `${pr.age_days}`,
+          pr.title,
+        ]),
+      )
+      break
+    }
+    case 'team': {
+      if (blockersOnly) {
+        lines.push('## Blockers')
+        renderMarkdownTable(
+          ['Repo', 'PR', 'Owner', 'Status', 'Days'],
+          report.blockers.map((blocker) => [
+            blocker.pr.repo,
+            `#${blocker.pr.number}`,
+            blocker.pr.author,
+            blocker.status,
+            `${blocker.days}`,
+          ]),
+        )
+        break
+      }
+
+      lines.push('## Velocity')
+      renderMarkdownTable(
+        ['Metric', 'Value'],
+        [
+          ['PRs opened', `${report.velocity.prs_opened}`],
+          ['PRs merged', `${report.velocity.prs_merged}`],
+          ['PRs closed', `${report.velocity.prs_closed}`],
+          ['Cycle time p50 (ms)', `${report.velocity.cycle_time_p50 ?? 'n/a'}`],
+          ['Cycle time p90 (ms)', `${report.velocity.cycle_time_p90 ?? 'n/a'}`],
+          ['Review turnaround p50 (ms)', `${report.velocity.review_turnaround_p50 ?? 'n/a'}`],
+          ['Review turnaround p90 (ms)', `${report.velocity.review_turnaround_p90 ?? 'n/a'}`],
+        ],
+      )
+
+      lines.push('## Member Breakdown')
+      renderMarkdownTable(
+        ['User', 'PRs authored', 'PRs reviewed', 'Commits', 'Lines changed'],
+        report.members.map((member) => [
+          member.user,
+          `${member.prs_authored}`,
+          `${member.prs_reviewed}`,
+          `${member.commits}`,
+          `${member.lines_changed}`,
+        ]),
+      )
+
+      lines.push('## Blockers')
+      renderMarkdownTable(
+        ['Repo', 'PR', 'Owner', 'Status', 'Days'],
+        report.blockers.map((blocker) => [
+          blocker.pr.repo,
+          `#${blocker.pr.number}`,
+          blocker.pr.author,
+          blocker.status,
+          `${blocker.days}`,
+        ]),
+      )
+      break
+    }
+    case 'exec': {
+      lines.push('## Velocity Trends')
+      renderMarkdownTable(
+        ['Week start', 'PRs merged', 'Cycle time p50 (ms)'],
+        report.velocity_trends.map((trend) => [
+          formatTimestamp(trend.bucket_start, timeZone),
+          `${trend.prs_merged}`,
+          `${trend.cycle_time_p50 ?? 'n/a'}`,
+        ]),
+      )
+
+      lines.push('## Repo Health')
+      renderMarkdownTable(
+        ['Repo', 'Status', 'Last activity'],
+        report.repo_health.map((entry) => [
+          entry.repo,
+          entry.status,
+          entry.last_activity_at ? formatTimestamp(entry.last_activity_at, timeZone) : 'n/a',
+        ]),
+      )
+
+      lines.push('## Highlights')
+      renderMarkdownTable(
+        ['Repo', 'PR', 'Reasons'],
+        report.highlights.map((entry) => [
+          entry.pr.repo,
+          `#${entry.pr.number}`,
+          entry.reasons.join('; '),
+        ]),
+      )
+
+      lines.push('## Team Breakdown')
+      renderMarkdownTable(
+        ['User', 'PRs authored', 'PRs reviewed', 'Commits', 'Lines changed'],
+        report.team_breakdown.map((member) => [
+          member.user,
+          `${member.prs_authored}`,
+          `${member.prs_reviewed}`,
+          `${member.commits}`,
+          `${member.lines_changed}`,
+        ]),
+      )
+      break
+    }
+    default: {
+      const _exhaustive: never = report
+      throw new Error(`Unhandled report type: ${_exhaustive}`)
+    }
+  }
+
+  return lines.join('\n')
+}
+
+function renderTable(headers: string[], rows: string[][]): string {
+  if (rows.length === 0) {
+    return `${headers.join(' | ')}\n${headers.map(() => '---').join(' | ')}\n(no rows)`
+  }
+
+  const widths = headers.map((header, index) =>
+    Math.max(header.length, ...rows.map((row) => (row[index] ?? '').length)),
+  )
+  const formatRow = (row: string[]): string =>
+    row.map((cell, index) => cell.padEnd(widths[index] ?? 0, ' ')).join(' | ')
+
+  const headerRow = formatRow(headers)
+  const separator = widths.map((width) => '-'.repeat(width ?? 0)).join('-|-')
+  const body = rows.map(formatRow)
+  return [headerRow, separator, ...body].join('\n')
+}
+
+type BlockerRow = { repo: string; pr: string; status: string; days: number }
+
+function applySort(report: Report, sortField?: string): Report {
+  if (!sortField) {
+    return report
+  }
+
+  const sort = sortField.trim().toLowerCase()
+
+  if (report.type === 'team') {
+    return {
+      ...report,
+      members: sortMembers(report.members, sort),
+    }
+  }
+
+  if (report.type === 'exec') {
+    return {
+      ...report,
+      team_breakdown: sortMembers(report.team_breakdown, sort),
+    }
+  }
+
+  return report
+}
+
+function sortMembers(
+  members: Array<{
+    user: string
+    prs_authored: number
+    prs_reviewed: number
+    commits: number
+    lines_changed: number
+  }>,
+  sort: string,
+): Array<{
+  user: string
+  prs_authored: number
+  prs_reviewed: number
+  commits: number
+  lines_changed: number
+}> {
+  switch (sort) {
+    case 'user':
+    case 'author':
+      return [...members].toSorted((a, b) => a.user.localeCompare(b.user))
+    case 'prs_authored':
+      return [...members].toSorted((a, b) => b.prs_authored - a.prs_authored)
+    case 'prs_reviewed':
+      return [...members].toSorted((a, b) => b.prs_reviewed - a.prs_reviewed)
+    case 'commits':
+      return [...members].toSorted((a, b) => b.commits - a.commits)
+    case 'lines_changed':
+      return [...members].toSorted((a, b) => b.lines_changed - a.lines_changed)
+    default:
+      return members
+  }
+}
+
+function deriveBlockers(
+  report: Extract<Report, { type: 'personal' | 'individual' }>,
+  thresholds: { stale_days: number; stuck_days: number },
+): BlockerRow[] {
+  const staleDays = thresholds.stale_days
+  const stuckDays = thresholds.stuck_days
+  return report.open_work.open_prs.flatMap((pr) => {
+    const blockers: BlockerRow[] = []
+    const stale = Math.floor((Date.now() - pr.updated_at) / (24 * 60 * 60 * 1000))
+    const stuck = Math.floor((Date.now() - pr.created_at) / (24 * 60 * 60 * 1000))
+    if (stale >= staleDays) {
+      blockers.push({ repo: pr.repo, pr: `#${pr.number}`, status: 'stale', days: stale })
+    }
+    if (stuck >= stuckDays) {
+      blockers.push({ repo: pr.repo, pr: `#${pr.number}`, status: 'stuck', days: stuck })
+    }
+    return blockers
+  })
+}
+
+function isEmptyPersonalReport(
+  report: Report,
+): report is Extract<Report, { type: 'personal' | 'individual' }> {
+  if (report.type !== 'personal' && report.type !== 'individual') {
+    return false
+  }
+
+  const summary = report.summary
+  const hasSummary =
+    summary.prs_opened > 0 ||
+    summary.prs_merged > 0 ||
+    summary.prs_closed > 0 ||
+    summary.commits > 0
+
+  const hasOpenWork = report.open_work.open_prs.length > 0
+  const hasReviewDebt =
+    report.review_debt.requested.length > 0 || report.review_debt.team_prs.length > 0
+
+  return !(hasSummary || hasOpenWork || hasReviewDebt)
+}
+
+main().catch((error) => {
+  console.error(`gh-pulse error: ${error instanceof Error ? error.message : String(error)}`)
+  process.exit(1)
+})