@goodandready/dsh-github-ops 0.1.2 → 0.2.0

package/lib/routes.js

@@ -0,0 +1,222 @@
+// HTTP routes the plugin's own user surfaces read.
+//
+// Three read-only endpoints, each behind the same rules: GET only, a local or same-origin
+// caller only, and no access value anywhere in the payload. They live here so the host half
+// stays a composition: the card, the Source Control tab and the sidebar panel each need one
+// endpoint, and none of them needs a tool.
+
+import { existsSync } from 'node:fs'
+import { join as joinPath } from 'node:path'
+
+import { statusPayload, isTrustedRequest, sendJson } from './status.js'
+import { parseStatus, parseBranches, parseStashes, parseCount, scmPayload, mergeStateFrom } from './scm.js'
+import { listIssues } from './tools/issues.js'
+import { listRuns } from './tools/actions.js'
+import { listNotifications, repoTreeView } from './tools/panel-data.js'
+
+/** Where the settings card reads the access status from. */
+export const STATUS_PATH = '/dsh-github-ops/status'
+
+/** Where the Source Control tab reads the working copy from. */
+export const SCM_PATH = '/dsh-github-ops/scm'
+
+/** Where the sidebar panel reads its data from (read-only). */
+export const PANEL_PATH = '/dsh-github-ops/panel'
+
+/**
+ * Register the three routes.
+ *
+ * @param ctx - the cordis context
+ * @param deps - resolveToken, client, liveConfig, describeError, makeGitRunner and cacheStats,
+ *               injected so this module stays free of the host's own composition.
+ */
+export function registerRoutes(ctx, deps) {
+  // The card reads the access status from here instead of from a tool result: the model has
+  // no business holding the access value, and the payload describes this machine's account,
+  // so only a local or same-origin caller is answered.
+  ctx.inject(['webServer'], (wctx) => {
+    try {
+      const register = () => wctx.webServer.register({
+        kind: 'exact',
+        path: STATUS_PATH,
+        handler: async (req, res) => {
+          if (req.method !== 'GET') return sendJson(res, 405, { error: 'method not allowed' })
+          if (!isTrustedRequest(req)) return sendJson(res, 403, { error: 'forbidden' })
+          const access = await resolveToken()
+          let identity = null
+          let rateLimit = null
+          let scopes = ''
+          let error = ''
+          if (access.value) {
+            try {
+              const github = await client()
+              const answer = await github.get('/user')
+              identity = answer.data
+              rateLimit = answer.rateLimit
+              scopes = typeof github.lastScopes === 'function' ? github.lastScopes() : ''
+            } catch (err) {
+              error = describeError(err)
+            }
+          }
+          sendJson(res, 200, statusPayload({
+            access,
+            identity,
+            rateLimit,
+            scopes,
+            cache: deps.cacheStats ? deps.cacheStats() : null,
+            interceptLinks: liveConfig().interceptLinks === true,
+            error,
+          }))
+        },
+      })
+      if (typeof wctx.effect === 'function') wctx.effect(register, 'dsh-github-ops: status route')
+      else register()
+    } catch (err) {
+      ctx.logger?.warn?.('[dsh-github-ops] status route not registered:', err && err.message)
+    }
+  })
+
+  // The Source Control tab reads the working copy through here: git is called on the session
+  // workspace, and only a local caller is answered. Nothing in this route writes.
+  ctx.inject(['webServer'], (wctx) => {
+    try {
+      const register = () => wctx.webServer.register({
+        kind: 'exact',
+        path: SCM_PATH,
+        handler: async (req, res) => {
+          if (req.method !== 'GET') return sendJson(res, 405, { error: 'method not allowed' })
+          if (!isTrustedRequest(req)) return sendJson(res, 403, { error: 'forbidden' })
+          const git = makeGitRunner()
+          const cwd = (typeof ctx.cwd === 'string' && ctx.cwd) || process.cwd()
+          const url = new URL(req.url || '/', 'http://localhost')
+          const file = url.searchParams.get('file') || ''
+          const staged = url.searchParams.get('staged') === '1'
+
+          if (file) {
+            // a single diff, capped: the tab shows a file at a time
+            const args = staged ? ['diff', '--cached', '--', file] : ['diff', '--', file]
+            const diff = await git(args, { cwd })
+            const text = diff.code === 0 ? diff.stdout : diff.stderr
+            return sendJson(res, 200, { file, staged, diff: String(text || '').slice(0, 200000) })
+          }
+
+          const branchAnswer = await git(['rev-parse', '--abbrev-ref', 'HEAD'], { cwd })
+          if (branchAnswer.code !== 0) {
+            return sendJson(res, 200, scmPayload({ cwd, error: 'not a git repository (or no commits yet)' }))
+          }
+          const branch = branchAnswer.stdout.trim()
+          const upstreamAnswer = await git(['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}'], { cwd })
+          const upstream = upstreamAnswer.code === 0 ? upstreamAnswer.stdout.trim() : ''
+          let ahead = null
+          let behind = null
+          if (upstream) {
+            const aheadAnswer = await git(['rev-list', '--count', `${upstream}..HEAD`], { cwd })
+            const behindAnswer = await git(['rev-list', '--count', `HEAD..${upstream}`], { cwd })
+            ahead = aheadAnswer.code === 0 ? parseCount(aheadAnswer.stdout) : null
+            behind = behindAnswer.code === 0 ? parseCount(behindAnswer.stdout) : null
+          }
+          const [statusAnswer, branchesAnswer, tagsAnswer, stashesAnswer] = await Promise.all([
+            git(['status', '--porcelain=v1'], { cwd }),
+            git(['branch', '--format=%(refname:short)\t%(HEAD)'], { cwd }),
+            git(['tag', '--list'], { cwd }),
+            git(['stash', 'list', '--format=%gd\t%gs'], { cwd }),
+          ])
+          const gitDirAnswer = await git(['rev-parse', '--absolute-git-dir'], { cwd })
+          const gitDir = gitDirAnswer.code === 0 ? gitDirAnswer.stdout.trim() : joinPath(cwd, '.git')
+          const merge = mergeStateFrom({
+            mergeHead: existsSync(joinPath(gitDir, 'MERGE_HEAD')),
+            rebaseDir: existsSync(joinPath(gitDir, 'rebase-merge')) || existsSync(joinPath(gitDir, 'rebase-apply')),
+            cherryPickHead: existsSync(joinPath(gitDir, 'CHERRY_PICK_HEAD')),
+            revertHead: existsSync(joinPath(gitDir, 'REVERT_HEAD')),
+          })
+          sendJson(res, 200, scmPayload({
+            cwd,
+            branch,
+            upstream,
+            ahead,
+            behind,
+            status: parseStatus(statusAnswer.code === 0 ? statusAnswer.stdout : ''),
+            branches: parseBranches(branchesAnswer.code === 0 ? branchesAnswer.stdout : ''),
+            tags: tagsAnswer.code === 0 ? tagsAnswer.stdout.split('\n').map((t) => t.trim()).filter(Boolean).slice(0, 50) : [],
+            stashes: parseStashes(stashesAnswer.code === 0 ? stashesAnswer.stdout : ''),
+            merge,
+          }))
+        },
+      })
+      if (typeof wctx.effect === 'function') wctx.effect(register, 'dsh-github-ops: scm route')
+      else register()
+    } catch (err) {
+      ctx.logger?.warn?.('[dsh-github-ops] scm route not registered:', err && err.message)
+    }
+  })
+
+  // The sidebar panel reads through here: one read-only endpoint with a `what` switch, so the
+  // panel needs a single contract instead of one route per screen. Only a local caller is
+  // answered, and nothing here writes.
+  ctx.inject(['webServer'], (wctx) => {
+    try {
+      const register = () => wctx.webServer.register({
+        kind: 'exact',
+        path: PANEL_PATH,
+        handler: async (req, res) => {
+          if (req.method !== 'GET') return sendJson(res, 405, { error: 'method not allowed' })
+          if (!isTrustedRequest(req)) return sendJson(res, 403, { error: 'forbidden' })
+          const access = await resolveToken()
+          if (!access.value) return sendJson(res, 200, { configured: false, guidance: access.guidance })
+          const url = new URL(req.url || '/', 'http://localhost')
+          const what = url.searchParams.get('what') || 'repos'
+          const repoSpec = url.searchParams.get('repo') || ''
+          const [repoOwner, repoName] = repoSpec.split('/')
+          const ref = url.searchParams.get('ref') || ''
+          const path = url.searchParams.get('path') || ''
+          const state = url.searchParams.get('state') || 'open'
+          const query = url.searchParams.get('q') || ''
+          try {
+            const github = await client()
+            if (what === 'repos') {
+              if (query) {
+                const { data } = await github.get('/search/repositories', { query: { q: query, per_page: 20, sort: 'stars' } })
+                return sendJson(res, 200, { configured: true, repos: (data.items || []).map((r) => ({ fullName: r.full_name, private: r.private, pushedAt: r.pushed_at, description: r.description || '', stars: r.stargazers_count })) })
+              }
+              const { data } = await github.get('/user/repos', { query: { per_page: 50, sort: 'pushed', affiliation: 'owner,collaborator,organization_member' } })
+              return sendJson(res, 200, { configured: true, repos: (data || []).filter((r) => !r.archived).map((r) => ({ fullName: r.full_name, private: r.private, pushedAt: r.pushed_at, description: r.description || '', stars: r.stargazers_count })) })
+            }
+            if (!repoOwner || !repoName) return sendJson(res, 200, { configured: true, error: 'a repository is required for this view' })
+            const repo = { owner: repoOwner, repo: repoName }
+            if (what === 'tree') {
+              const view = await repoTreeView(github, { ...repo, ref, path })
+              return sendJson(res, 200, { configured: true, ...view })
+            }
+            if (what === 'blob') {
+              const { data } = await github.get(`/repos/${repoOwner}/${repoName}/contents/${path}`, { query: ref ? { ref } : undefined })
+              if (Array.isArray(data)) return sendJson(res, 200, { configured: true, entries: data.map((e) => ({ name: e.name, type: e.type, size: e.size, path: e.path })) })
+              const encoded = String((data && data.content) || '').replace(/\n/g, '')
+              const text = encoded ? Buffer.from(encoded, 'base64').toString('utf8') : ''
+              return sendJson(res, 200, { configured: true, path: data.path, size: data.size, text: text.slice(0, 200000), truncated: text.length > 200000 })
+            }
+            if (what === 'issues' || what === 'pulls') {
+              const result = await listIssues(github, { ...repo, state, limit: 30, kind: what === 'pulls' ? 'pr' : 'issue' })
+              return sendJson(res, 200, { configured: true, items: result.issues })
+            }
+            if (what === 'runs') {
+              const result = await listRuns(github, { ...repo, limit: 20 })
+              return sendJson(res, 200, { configured: true, items: result.runs })
+            }
+            if (what === 'inbox') {
+              const result = await listNotifications(github, { limit: 30 })
+              return sendJson(res, 200, { configured: true, ...result })
+            }
+            return sendJson(res, 200, { configured: true, error: `unknown view "${what}"` })
+          } catch (err) {
+            return sendJson(res, 200, { configured: true, error: describeError(err) })
+          }
+        },
+      })
+      if (typeof wctx.effect === 'function') wctx.effect(register, 'dsh-github-ops: panel route')
+      else register()
+    } catch (err) {
+      ctx.logger?.warn?.('[dsh-github-ops] panel route not registered:', err && err.message)
+    }
+  })
+
+}

package/lib/scm.js

@@ -0,0 +1,115 @@
+// Reading a working copy, for the Source Control tab.
+//
+// The parsers are pure: they take the text git prints and return a structure. That keeps the
+// interesting part — porcelain status, ahead/behind, groups — testable without a repository,
+// and the host route stays a thin wrapper around `git` calls.
+//
+// Nothing here writes: the tab reads, and a write only happens when the human clicks.
+
+/** One entry of `git status --porcelain=v1` (XY PATH, with renames as "R  old -> new"). */
+export function parseStatusLine(line) {
+  if (!line || line.length < 4) return null
+  const index = line[0]
+  const worktree = line[1]
+  let path = line.slice(3)
+  let renamedFrom = ''
+  const arrow = path.indexOf(' -> ')
+  if (arrow !== -1) {
+    renamedFrom = path.slice(0, arrow)
+    path = path.slice(arrow + 4)
+  }
+  if (path.startsWith('"') && path.endsWith('"')) path = path.slice(1, -1)
+  return { index, worktree, path, renamedFrom }
+}
+
+/** Group a porcelain listing the way the panel shows it. */
+export function parseStatus(text) {
+  const lines = String(text || '').split('\n').filter((line) => line.trim().length > 0)
+  const staged = []
+  const changes = []
+  const untracked = []
+  const unmerged = []
+  for (const line of lines) {
+    const entry = parseStatusLine(line)
+    if (!entry) continue
+    const { index, worktree, path, renamedFrom } = entry
+    if (index === '?' && worktree === '?') {
+      untracked.push({ path, status: '?', staged: false })
+      continue
+    }
+    // a conflicted file is reported once, as a conflict, not as staged and modified
+    const conflict = 'UDUAAD'.includes(index) && 'UDUAAD'.includes(worktree)
+    if (conflict) {
+      unmerged.push({ path, status: 'U', staged: false })
+      continue
+    }
+    if (index !== ' ' && index !== '?') {
+      staged.push({ path, status: index, staged: true, renamedFrom: renamedFrom || undefined })
+    }
+    if (worktree !== ' ' && worktree !== '?') {
+      changes.push({ path, status: worktree, staged: false })
+    }
+  }
+  return { staged, changes, untracked, unmerged, total: staged.length + changes.length + untracked.length + unmerged.length }
+}
+
+/** `git branch --format='%(refname:short)\t%(HEAD)'` (or `git branch` output as a fallback). */
+export function parseBranches(text) {
+  const lines = String(text || '').split('\n').filter((line) => line.trim().length > 0)
+  return lines.map((line) => {
+    const [name, head] = line.split('\t')
+    const current = head ? head.trim() === '*' : line.trim().startsWith('*')
+    return { name: (name || line).replace(/^\*/, '').trim(), current }
+  }).filter((branch) => branch.name.length > 0)
+}
+
+/** `git stash list --format='%gd\t%gs'` or the default `stash@{0}: WIP on main: …`. */
+export function parseStashes(text) {
+  const lines = String(text || '').split('\n').filter((line) => line.trim().length > 0)
+  return lines.map((line) => {
+    const [ref, ...rest] = line.split('\t')
+    if (rest.length) return { ref: ref.trim(), message: rest.join(' ').trim() }
+    const colon = line.indexOf(':')
+    return colon === -1
+      ? { ref: line.trim(), message: '' }
+      : { ref: line.slice(0, colon).trim(), message: line.slice(colon + 1).trim() }
+  })
+}
+
+/** Counts from `git rev-list --count <range>`. */
+export function parseCount(text) {
+  const value = Number.parseInt(String(text || '').trim(), 10)
+  return Number.isFinite(value) && value >= 0 ? value : 0
+}
+
+/**
+ * The payload the tab renders. Everything is optional: a repository without an upstream has no
+ * ahead/behind, and that is reported as such rather than as an error.
+ */
+export function scmPayload({
+  cwd, branch, upstream, ahead, behind, status, branches, tags, stashes, merge, error,
+} = {}) {
+  return {
+    cwd: cwd || '',
+    isRepository: !error && Boolean(branch),
+    branch: branch || '',
+    upstream: upstream || '',
+    ahead: Number.isFinite(ahead) ? ahead : null,
+    behind: Number.isFinite(behind) ? behind : null,
+    files: status || { staged: [], changes: [], untracked: [], unmerged: [], total: 0 },
+    branches: Array.isArray(branches) ? branches : [],
+    tags: Array.isArray(tags) ? tags : [],
+    stashes: Array.isArray(stashes) ? stashes : [],
+    mergeState: merge || { inProgress: false, kind: '' },
+    error: error ? String(error).slice(0, 300) : '',
+  }
+}
+
+/** Detect a merge or rebase in progress from the presence of the marker files. */
+export function mergeStateFrom({ mergeHead = false, rebaseDir = false, cherryPickHead = false, revertHead = false } = {}) {
+  if (mergeHead) return { inProgress: true, kind: 'merge' }
+  if (rebaseDir) return { inProgress: true, kind: 'rebase' }
+  if (cherryPickHead) return { inProgress: true, kind: 'cherry-pick' }
+  if (revertHead) return { inProgress: true, kind: 'revert' }
+  return { inProgress: false, kind: '' }
+}

package/lib/status.js

@@ -0,0 +1,66 @@
+// What the settings card is allowed to know.
+//
+// The status of the access — where it comes from, which account, what the rate limit looks
+// like — belongs in the card, not in a tool result: the model has no business holding a token,
+// and a status block explains "not configured" far better than an error at the first call.
+//
+// The payload never contains the access value. The route answers only a local or same-origin
+// caller, because the payload describes the machine's account.
+
+/** Whether a request may read the status payload. Fail-closed. */
+export function isTrustedRequest(req) {
+  if (!req) return false
+  const address = (req.socket && (req.socket.remoteAddress || req.socket.address?.().address)) || ''
+  const loopback = address === '127.0.0.1' || address === '::1' || address === '::ffff:127.0.0.1'
+  if (loopback) return true
+  const host = header(req, 'host')
+  const origin = header(req, 'origin')
+  if (!host || !origin) return false
+  try {
+    return new URL(origin).host === host
+  } catch {
+    return false
+  }
+}
+
+function header(req, name) {
+  if (!req || !req.headers) return ''
+  const value = req.headers[name] || req.headers[name.toLowerCase()]
+  return typeof value === 'string' ? value.trim() : ''
+}
+
+/**
+ * The payload for the card.
+ *
+ * @param access - result of the access resolution: { value, source, guidance }
+ * @param identity - { login, name } or null when the call failed
+ * @param rateLimit - { limit, remaining, resetAt } or null
+ * @param cache - { size, ttlMs }
+ * @param error - a string when the identity call failed
+ */
+export function statusPayload({ access, identity, rateLimit, scopes, cache, error } = {}) {
+  const configured = Boolean(access && access.value)
+  return {
+    configured,
+    source: configured ? access.source || '' : '',
+    login: (identity && identity.login) || '',
+    name: (identity && identity.name) || '',
+    scopes: scopes || '',
+    rateLimit: rateLimit
+      ? { limit: rateLimit.limit, remaining: rateLimit.remaining, resetAt: rateLimit.resetAt }
+      : null,
+    cache: cache ? { size: cache.size, ttlMs: cache.ttlMs } : null,
+    guidance: configured ? '' : ((access && access.guidance) || ''),
+    error: error ? String(error).slice(0, 200) : '',
+  }
+}
+
+/** Answers one HTTP request with JSON. Shared by the route so the handler stays thin. */
+export function sendJson(res, statusCode, payload) {
+  try {
+    res.writeHead(statusCode, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' })
+    res.end(JSON.stringify(payload))
+  } catch {
+    // a client that went away must not break the route
+  }
+}

package/lib/tools/actions.js

@@ -38,7 +38,7 @@ export async function listRuns(client, { owner, repo, branch, workflow, status,
   if (branch) query.branch = branch
   if (status) query.status = status
   const { data } = await client.get(route, { query })
-  const runs = ((data && data.workflow_runs) || []).map(normalizeRun)
+  const runs = ((data && data.workflow_runs) || []).map(normalizeRun).slice(0, capped)
   return { runs, count: runs.length, total: (data && data.total_count) || runs.length }
 }
 

package/lib/tools/insights.js

@@ -0,0 +1,246 @@
+// Composed reports: the answers a person actually asks for.
+//
+// Each function is a small composition over the plain reads, so the cache in the client
+// makes a report cheap and the pieces stay testable. Nothing here is a verdict on quality:
+// a health score is a transparent heuristic with its evidence attached, and the digest only
+// reports what happened in a window.
+
+import { getRepo, normalizeRepo } from './repos.js'
+import { listReleases } from './releases.js'
+import { listIssues } from './issues.js'
+import { listRuns } from './actions.js'
+
+function ensureRepo({ owner, repo }) {
+  if (!owner || !repo) throw new Error('owner and repo are required')
+}
+
+function normalizeCommit(data) {
+  return {
+    sha: data && data.sha,
+    shortSha: data && data.sha ? String(data.sha).slice(0, 7) : '',
+    message: data && data.commit && data.commit.message ? String(data.commit.message).split('\n')[0] : '',
+    author: (data && data.commit && data.commit.author && data.commit.author.name) || (data && data.author && data.author.login) || '',
+    date: (data && data.commit && data.commit.author && data.commit.author.date) || '',
+  }
+}
+
+/** Recent commits of a branch. */
+export async function listCommits(client, { owner, repo, branch, limit = 10, since } = {}) {
+  ensureRepo({ owner, repo })
+  const capped = Math.max(1, Math.min(Number(limit) || 10, 100))
+  const query = { per_page: capped }
+  if (since) query.since = since
+  const { data } = await client.get(`/repos/${owner}/${repo}/commits`, {
+    query: branch ? { ...query, sha: branch } : query,
+  })
+  const commits = (Array.isArray(data) ? data : []).map(normalizeCommit).slice(0, capped)
+  return { commits, count: commits.length }
+}
+
+/** Top contributors by commit count. */
+export async function listContributors(client, { owner, repo, limit = 10 } = {}) {
+  ensureRepo({ owner, repo })
+  const capped = Math.max(1, Math.min(Number(limit) || 10, 100))
+  const { data } = await client.get(`/repos/${owner}/${repo}/contributors`, { query: { per_page: capped } })
+  const contributors = (Array.isArray(data) ? data : []).slice(0, capped).map((c) => ({
+    login: c.login,
+    contributions: c.contributions,
+    url: c.html_url,
+  }))
+  return { contributors, count: contributors.length }
+}
+
+/**
+ * One call that answers "what is this repository": overview, latest release, open issues,
+ * recent commits and top contributors. Composed calls share the client cache, so the whole
+ * report costs a handful of requests.
+ */
+export async function repoReport(client, { owner, repo, commits: commitLimit = 5, issues: issueLimit = 5, contributors: contributorLimit = 5 } = {}) {
+  ensureRepo({ owner, repo })
+  const overview = await getRepo(client, { owner, repo })
+  const [releases, openIssues, commitList, contributorList] = await Promise.all([
+    listReleases(client, { owner, repo, limit: 1 }).catch(() => ({ releases: [] })),
+    listIssues(client, { owner, repo, state: 'open', limit: issueLimit }).catch(() => ({ issues: [] })),
+    listCommits(client, { owner, repo, branch: overview.defaultBranch, limit: commitLimit }).catch(() => ({ commits: [] })),
+    listContributors(client, { owner, repo, limit: contributorLimit }).catch(() => ({ contributors: [] })),
+  ])
+  return {
+    repo: overview.fullName,
+    description: overview.description,
+    stars: overview.stars,
+    forks: overview.forks,
+    openIssues: overview.openIssues,
+    language: overview.language,
+    license: overview.license,
+    defaultBranch: overview.defaultBranch,
+    pushedAt: overview.pushedAt,
+    url: overview.url,
+    latestRelease: releases.releases[0] || null,
+    issues: openIssues.issues,
+    commits: commitList.commits,
+    contributors: contributorList.contributors,
+  }
+}
+
+/** What happened in a repository inside a look-back window. */
+export async function weeklyDigest(client, { owner, repo, days = 7, limit = 10 } = {}) {
+  ensureRepo({ owner, repo })
+  const window = Math.max(1, Math.min(Number(days) || 7, 90))
+  const capped = Math.max(1, Math.min(Number(limit) || 10, 50))
+  const since = new Date(Date.now() - window * 24 * 60 * 60 * 1000).toISOString()
+
+  const [releases, issues, pulls, commits] = await Promise.all([
+    listReleases(client, { owner, repo, limit: capped }).catch(() => ({ releases: [] })),
+    // pull requests are excluded from "new issues": they are reported separately below
+    listIssues(client, { owner, repo, state: 'all', kind: 'issue', limit: capped }).catch(() => ({ issues: [] })),
+    listIssues(client, { owner, repo, state: 'all', kind: 'pr', limit: capped }).catch(() => ({ issues: [] })),
+    listCommits(client, { owner, repo, limit: capped, since }).catch(() => ({ commits: [] })),
+  ])
+  const after = (value) => Boolean(value) && value >= since
+  return {
+    windowDays: window,
+    since,
+    releases: releases.releases.filter((r) => after(r.publishedAt || r.createdAt)),
+    newIssues: issues.issues.filter((i) => after(i.createdAt)),
+    mergedPulls: pulls.issues.filter((i) => after(i.closedAt || i.updatedAt)),
+    commits: commits.commits,
+  }
+}
+
+/**
+ * The attention queue: mentions, review requests, assignments and threads the token watches.
+ * Needs access with notification read permission; a missing scope surfaces as an actionable
+ * failure rather than an empty list.
+ */
+export async function listNotifications(client, { all = false, participating = false, limit = 20 } = {}) {
+  const capped = Math.max(1, Math.min(Number(limit) || 20, 100))
+  const query = { per_page: capped }
+  if (all) query.all = 'true'
+  if (participating) query.participating = 'true'
+  const { data } = await client.get('/notifications', { query })
+  const items = (Array.isArray(data) ? data : []).slice(0, capped).map((n) => ({
+    id: n.id,
+    reason: n.reason,
+    unread: Boolean(n.unread),
+    updatedAt: n.updated_at,
+    title: n.subject && n.subject.title,
+    type: n.subject && n.subject.type,
+    number: n.subject && n.subject.url ? Number(String(n.subject.url).split('/').pop()) : null,
+    repository: n.repository ? n.repository.full_name : '',
+  }))
+  const byReason = {}
+  for (const item of items) byReason[item.reason] = (byReason[item.reason] || 0) + 1
+  return { count: items.length, byReason, notifications: items }
+}
+
+/**
+ * A transparent maintenance heuristic. Every point of the score carries its evidence, and the
+ * result states plainly that it is not a security audit.
+ */
+export function healthOf({ repo, releases = [], issues = [], pulls = [], commits = [] } = {}) {
+  const dimensions = []
+  const daysSince = (value) => (value ? Math.floor((Date.now() - Date.parse(value)) / (24 * 60 * 60 * 1000)) : null)
+
+  const pushed = daysSince(repo && repo.pushedAt)
+  const activity = pushed === null ? 0 : pushed <= 7 ? 25 : pushed <= 30 ? 18 : pushed <= 90 ? 10 : 3
+  dimensions.push({ name: 'activity', score: activity, max: 25, evidence: pushed === null ? 'no push date' : `last push ${pushed} day(s) ago` })
+
+  const releaseScore = releases.length ? 20 : 8
+  dimensions.push({ name: 'releases', score: releaseScore, max: 20, evidence: releases.length ? `latest ${releases[0].tag} (${releases[0].publishedAt || 'unpublished'})` : 'no releases published' })
+
+  const openCount = Array.isArray(issues) ? issues.length : 0
+  const issueScore = openCount === 0 ? 20 : openCount <= 3 ? 15 : openCount <= 10 ? 9 : 4
+  dimensions.push({ name: 'issue-load', score: issueScore, max: 20, evidence: `${openCount} open issue(s) in the last page` })
+
+  const prScore = Array.isArray(pulls) && pulls.length ? 15 : 8
+  dimensions.push({ name: 'review-load', score: prScore, max: 15, evidence: Array.isArray(pulls) && pulls.length ? `${pulls.length} recent pull request(s)` : 'no recent pull requests' })
+
+  const commitCount = Array.isArray(commits) ? commits.length : 0
+  const commitScore = commitCount >= 5 ? 20 : commitCount > 0 ? 12 : 4
+  dimensions.push({ name: 'commits', score: commitScore, max: 20, evidence: `${commitCount} commit(s) in the last page` })
+
+  const score = dimensions.reduce((sum, d) => sum + d.score, 0)
+  const risks = []
+  if (pushed !== null && pushed > 90) risks.push(`no push for ${pushed} days`)
+  if (!releases.length) risks.push('no published release')
+  if (!(repo && repo.license)) risks.push('no license declared')
+  if (!(repo && repo.description)) risks.push('no description')
+  if (openCount > 10) risks.push('large open issue backlog')
+
+  const nextActions = []
+  if (!releases.length) nextActions.push('publish the first release')
+  if (!(repo && repo.license)) nextActions.push('add a LICENSE')
+  if (!(repo && repo.description)) nextActions.push('write a repository description')
+  if (pushed !== null && pushed > 90) nextActions.push('push a change or archive the repository')
+
+  return {
+    repo: repo && repo.fullName,
+    score,
+    max: 100,
+    dimensions,
+    risks,
+    nextActions,
+    disclaimer: 'A maintenance heuristic over public signals, not a security audit.',
+  }
+}
+
+/** Repository health for one repository, gathering its own evidence. */
+export async function repoHealth(client, { owner, repo } = {}) {
+  ensureRepo({ owner, repo })
+  const [repository, releases, issues, pulls, commits] = await Promise.all([
+    getRepo(client, { owner, repo }),
+    listReleases(client, { owner, repo, limit: 3 }).catch(() => ({ releases: [] })),
+    listIssues(client, { owner, repo, state: 'open', limit: 30 }).catch(() => ({ issues: [] })),
+    listIssues(client, { owner, repo, state: 'open', kind: 'pr', limit: 30 }).catch(() => ({ issues: [] })),
+    listCommits(client, { owner, repo, limit: 10 }).catch(() => ({ commits: [] })),
+  ])
+  return healthOf({ repo: repository, releases: releases.releases, issues: issues.issues, pulls: pulls.issues, commits: commits.commits })
+}
+
+/** Two repositories side by side, with numeric deltas. */
+export async function compareRepos(client, { first, second } = {}) {
+  const a = typeof first === 'string' ? first : ''
+  const b = typeof second === 'string' ? second : ''
+  if (!a.includes('/') || !b.includes('/')) throw new Error('pass two repositories as "owner/repo"')
+  const [left, right] = await Promise.all([a, b].map(async (spec) => {
+    const [owner, repo] = spec.split('/')
+    return getRepo(client, { owner, repo })
+  }))
+  const delta = (x, y) => (typeof x === 'number' && typeof y === 'number' ? x - y : null)
+  return {
+    first: left,
+    second: right,
+    deltas: {
+      stars: delta(left.stars, right.stars),
+      forks: delta(left.forks, right.forks),
+      openIssues: delta(left.openIssues, right.openIssues),
+    },
+  }
+}
+
+/** Recently created repositories, by stars. Uses the search quota. */
+export async function trendingRepos(client, { language, since, limit = 10 } = {}) {
+  const capped = Math.max(1, Math.min(Number(limit) || 10, 50))
+  const created = since || new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString().slice(0, 10)
+  const parts = [`created:>${created}`, 'stars:>50']
+  if (language) parts.push(`language:${language}`)
+  const { data } = await client.get('/search/repositories', {
+    query: { q: parts.join(' '), sort: 'stars', order: 'desc', per_page: capped },
+  })
+  const repos = ((data && data.items) || []).slice(0, capped).map(normalizeRepo)
+  return { since: created, count: repos.length, repos }
+}
+
+/** A user's repositories by stars. */
+export async function userRepos(client, { login, limit = 10 } = {}) {
+  if (!login) throw new Error('login is required')
+  const capped = Math.max(1, Math.min(Number(limit) || 10, 100))
+  const { data } = await client.get(`/users/${encodeURIComponent(login)}/repos`, {
+    query: { sort: 'stars', direction: 'desc', per_page: capped },
+  })
+  const repos = (Array.isArray(data) ? data : []).slice(0, capped).map(normalizeRepo)
+  return { login, count: repos.length, repos }
+}
+
+// Re-exported so a caller composing its own report needs one import.
+export { listRuns }