dsh-github-router 0.1.0

package/lib/index.js

@@ -0,0 +1,52 @@
+/**
+ * dsh-github-router — DeepSeek Harness plugin for READ-ONLY GitHub access.
+ *
+ * Plugin code runs in the host process, so it is free of the sandbox's
+ * shell-side TLS/proxy failures — which is exactly why the routing lives
+ * inside the tools. The unrestricted token is compensated with a strict
+ * security posture:
+ *
+ * 1. Five read-only tools (github_probe / github_pr / github_issue /
+ *    github_file / github_api). There is no write, push, comment, or
+ *    mutation verb anywhere in this package.
+ * 2. Every network call is a GET with an explicit direct/proxy decision per
+ *    attempt (ambient proxy env is not blindly inherited); subprocess calls
+ *    are argv arrays — no shell interpolation.
+ * 3. api.github.com paths, repo file paths, refs, owners, and query values
+ *    are validated before use; tokens are attached only to api.github.com
+ *    and redacted from every output; page HTML is parsed by strict JSON
+ *    island extraction (JSON.parse only, never evaluated).
+ * 4. Plugin-owned state (fetch cache, response cache) lives under
+ *    <DSH_HOME>/storages/dsh-github-router; user repositories are only ever
+ *    read (log/diff/show) and only when explicitly granted.
+ * 5. Configuration rides the official settings seam (`dsh-github-router`
+ *    namespace: durable document, schema validation, revision fencing) and
+ *    is exposed to the browser through a plugin-owned remote API
+ *    (`githubRouterSettings/{describe,mutate}`), because the framework's
+ *    api-proxy only serves settings namespaces on its hardcoded allowlist.
+ * @module dsh-github-router
+ */
+import { installRemote } from './remote.js'
+import { registerGuidance } from './guidance.js'
+import { registerSkill } from './skill.js'
+import { registerApiTool } from './tools/api.js'
+import { registerFileTool } from './tools/file.js'
+import { registerIssueTool } from './tools/issue.js'
+import { registerPrTool } from './tools/pr.js'
+import { registerProbeTool } from './tools/probe.js'
+
+export const name = 'dsh-github-router'
+export const inject = ['tools', 'subprocess', 'skills', 'systemPrompt']
+
+export function apply(ctx, config = {}) {
+  const remote = installRemote(ctx, config)
+  const options = remote.options
+
+  registerSkill(ctx)
+  registerGuidance(ctx)
+  registerProbeTool(ctx, options)
+  registerPrTool(ctx, options)
+  registerIssueTool(ctx, options)
+  registerFileTool(ctx, options)
+  registerApiTool(ctx, options)
+}

package/lib/net.js

@@ -0,0 +1,213 @@
+/**
+ * Route-aware HTTP layer.
+ *
+ * Every request is a plain GET with an explicit proxy decision: direct
+ * requests use the global fetch, proxied requests go through the
+ * zero-dependency CONNECT tunnel client (see tunnel.js). The ambient
+ * HTTP(S)_PROXY environment variables are deliberately NOT inherited by
+ * global fetch, so routing stays under this plugin's control.
+ * @module dsh-github-router/net
+ */
+import { tunnelRequest } from './tunnel.js'
+
+/** Structured route failure with a stable machine code. */
+export class RouteError extends Error {
+  constructor(code, message, options = {}) {
+    super(message)
+    this.name = 'RouteError'
+    this.code = code // TRANSPORT | TIMEOUT | HTTP | PROXY_UNAVAILABLE | ABORTED
+    if (options.status !== undefined) this.status = options.status
+    if (options.cause !== undefined) this.cause = options.cause
+  }
+}
+
+/** One combined signal: caller cancellation plus a cooperative deadline. */
+export function makeAbort(signal, timeoutMs) {
+  const controller = new AbortController()
+  if (signal !== undefined && signal !== null) {
+    if (signal.aborted) controller.abort(signal.reason)
+    else signal.addEventListener('abort', () => controller.abort(signal.reason), { once: true })
+  }
+  const timer = setTimeout(
+    () => controller.abort(new DOMException(`request timed out after ${timeoutMs}ms`, 'TimeoutError')),
+    timeoutMs,
+  )
+  if (typeof timer.unref === 'function') timer.unref()
+  return { signal: controller.signal, cleanup: () => clearTimeout(timer) }
+}
+
+function classifyTransportError(error, signal) {
+  if (signal !== undefined && signal !== null && signal.aborted) return new RouteError('ABORTED', 'aborted by caller', { cause: error })
+  if (error && error.name === 'TimeoutError') return new RouteError('TIMEOUT', String(error.message || 'request timed out'), { cause: error })
+  if (error && error.name === 'AbortError') return new RouteError('ABORTED', 'aborted by caller', { cause: error })
+  return new RouteError('TRANSPORT', `request failed: ${String(error && error.message ? error.message : error)}`, { cause: error })
+}
+async function readBody(response, maxBytes) {
+  const declared = Number(response.headers.get('content-length') || '0')
+  if (declared > 0 && declared <= maxBytes) {
+    const buf = Buffer.from(await response.arrayBuffer())
+    return { data: buf, truncated: false }
+  }
+  const reader = response.body ? response.body.getReader() : null
+  if (reader === null) return { data: Buffer.alloc(0), truncated: false }
+  const chunks = []
+  let total = 0
+  try {
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) break
+      total += value.byteLength
+      if (total > maxBytes) {
+        chunks.push(Buffer.from(value).subarray(0, maxBytes - (total - value.byteLength)))
+        await reader.cancel().catch(() => {})
+        return { data: Buffer.concat(chunks), truncated: true }
+      }
+      chunks.push(Buffer.from(value))
+    }
+  } catch (error) {
+    await reader.cancel().catch(() => {})
+    throw error
+  }
+  return { data: Buffer.concat(chunks), truncated: false }
+}
+
+const KEPT_HEADERS = ['etag', 'last-modified', 'x-ratelimit-remaining', 'x-ratelimit-limit', 'x-ratelimit-reset']
+
+/** Headers projection compatible with both fetch (Headers) and the tunnel (plain object). */
+function pickHeaders(response) {
+  const get = (name) => {
+    if (response.headers === null || response.headers === undefined) return null
+    if (typeof response.headers.get === 'function') return response.headers.get(name)
+    return response.headers[name] ?? null
+  }
+  const out = {}
+  for (const name of KEPT_HEADERS) {
+    const value = get(name)
+    if (value !== null && value !== undefined && value.length > 0) out[name] = value
+  }
+  const retryAfter = get('retry-after')
+  if (typeof retryAfter === 'string' && retryAfter.length > 0) out['retry-after'] = retryAfter
+  return out
+}
+
+/**
+ * One GET attempt with an explicit proxy decision: direct requests go
+ * through global fetch, proxied requests through the zero-dependency
+ * CONNECT tunnel.
+ * @returns { status, ok, body: Buffer, truncated, headers, url }
+ * @throws {RouteError}
+ */
+export async function fetchOnce(url, options) {
+  const {
+    method = 'GET',
+    headers = {},
+    timeoutMs = 8000,
+    proxy,
+    signal,
+    maxBytes = 1048576,
+  } = options
+  if (proxy !== undefined && proxy !== null && proxy !== '') {
+    try {
+      const result = await tunnelRequest(url, { method, headers, timeoutMs, proxy, signal, maxBytes })
+      return {
+        status: result.status,
+        ok: result.ok,
+        body: result.body,
+        truncated: result.truncated,
+        headers: pickHeaders(result),
+        url: result.url,
+      }
+    } catch (error) {
+      throw classifyTransportError(error, signal)
+    }
+  }
+
+  const { signal: combined, cleanup } = makeAbort(signal, timeoutMs)
+  let response
+  try {
+    response = await fetch(url, {
+      method,
+      headers,
+      redirect: 'follow',
+      signal: combined,
+    })
+  } catch (error) {
+    cleanup()
+    throw classifyTransportError(error, signal)
+  }
+  try {
+    const body = await readBody(response, maxBytes)
+    cleanup()
+    return {
+      status: response.status,
+      ok: response.ok,
+      body: body.data,
+      truncated: body.truncated,
+      headers: pickHeaders(response),
+      url: response.url,
+    }
+  } catch (error) {
+    cleanup()
+    throw classifyTransportError(error, signal)
+  }
+}
+
+/** Retryable HTTP statuses for idempotent GETs. */
+export function isRetryableStatus(status) {
+  return status === 429 || (status >= 500 && status <= 599)
+}
+
+/**
+ * GET with bounded retries on 429/5xx (honoring Retry-After). Non-retryable
+ * failures surface immediately so the router can fall through to the next
+ * route instead of burning time.
+ */
+export async function fetchWithRetry(url, options) {
+  const { retries = 0, onAttempt } = options
+  let attempt = 0
+  for (;;) {
+    try {
+      const result = await fetchOnce(url, options)
+      if (onAttempt !== undefined) onAttempt('ok', result.status, attempt)
+      if (result.ok || !isRetryableStatus(result.status) || attempt >= retries) return result
+      const waitMs = retryDelayMs(result.headers['retry-after'], attempt)
+      if (onAttempt !== undefined) onAttempt('retry', result.status, attempt)
+      await new Promise((resolve) => setTimeout(resolve, waitMs))
+      attempt += 1
+    } catch (error) {
+      if (error instanceof RouteError && (error.code === 'TIMEOUT' || error.code === 'TRANSPORT') && attempt < retries) {
+        if (onAttempt !== undefined) onAttempt('retry', error.code, attempt)
+        await new Promise((resolve) => setTimeout(resolve, 500 * 2 ** attempt))
+        attempt += 1
+      } else {
+        throw error
+      }
+    }
+  }
+}
+
+function retryDelayMs(retryAfter, attempt) {
+  if (typeof retryAfter === 'string' && /^\d+$/.test(retryAfter)) {
+    const seconds = Number(retryAfter)
+    if (Number.isFinite(seconds) && seconds >= 0 && seconds <= 120) return seconds * 1000
+  }
+  return Math.min(5000, 500 * 2 ** attempt)
+}
+
+/** Fetch and decode text; invalid UTF-8 is replaced, never throws. */
+export async function fetchText(url, options) {
+  const result = await fetchWithRetry(url, options)
+  return { ...result, text: result.body.toString('utf8') }
+}
+
+/** Fetch and parse JSON; parse failures surface as a structured error. */
+export async function fetchJson(url, options) {
+  const result = await fetchWithRetry(url, options)
+  let json
+  try {
+    json = JSON.parse(result.body.toString('utf8'))
+  } catch (error) {
+    throw new RouteError('TRANSPORT', `unprocessable JSON response from ${url}: ${String(error && error.message ? error.message : error)}`, { cause: error })
+  }
+  return { ...result, json }
+}

package/lib/remote.js

@@ -0,0 +1,169 @@
+/**
+ * Host-side configuration routes for the browser settings page.
+ *
+ * The channel is the dshmarket pattern: the plugin mounts its own HTTP
+ * routes on the shared web server (`ctx.webServer.register`, prefix
+ * `/dsh-github-router`) and the browser page talks to them with plain
+ * same-origin fetch — no typert, no gateway, no framework allowlist. The
+ * routes are backed by the SAME official settings seam: the namespace
+ * stays durable in the settings document, with schema validation,
+ * revision fencing, and secret redaction.
+ *
+ * Mutating requests are POST-only, same-origin-checked (Origin === Host)
+ * and body-capped, mirroring dsh-market's route security posture.
+ * @module dsh-github-router/remote
+ */
+import { Config, NAMESPACE, resolveOptions } from './config.js'
+
+const ROUTE_PREFIX = '/dsh-github-router'
+const MAX_BODY_BYTES = 16384
+
+function sendJson(response, status, payload) {
+  response.writeHead(status, {
+    'cache-control': 'no-store',
+    'content-type': 'application/json; charset=utf-8',
+  })
+  response.end(JSON.stringify(payload))
+}
+
+/** Same-origin enforcement for mutating routes (dsh-market posture). */
+function sameOrigin(request) {
+  const origin = request.headers.origin
+  const host = request.headers.host
+  if (origin === undefined || host === undefined) return false
+  try {
+    return new URL(origin).host === host
+  } catch {
+    return false
+  }
+}
+
+/** Read and parse a JSON request body with a hard byte cap. */
+async function readJsonBody(request, maxBytes = MAX_BODY_BYTES) {
+  const chunks = []
+  let size = 0
+  for await (const chunk of request) {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
+    size += buffer.length
+    if (size > maxBytes) throw new Error('request body too large')
+    chunks.push(buffer)
+  }
+  return JSON.parse(Buffer.concat(chunks).toString('utf8'))
+}
+
+/**
+ * Install the settings-namespace registration, the options thunk, and the
+ * `/dsh-github-router/config` routes in one wiring. Returns the
+ * runtime-options thunk the tools consume.
+ */
+export function installRemote(ctx, config) {
+  const holder = { scope: null, settings: null }
+
+  ctx.inject(['settings'], (sctx) => {
+    holder.settings = sctx.settings
+    holder.scope = sctx.settings.register(NAMESPACE, Config, { base: config })
+    sctx.effect(() => () => {
+      holder.scope = null
+      holder.settings = null
+    }, 'dsh-github-router: settings scope teardown')
+  })
+
+  /** Redacted wire view of this namespace (value/base/user/revision/writable). */
+  function viewOf() {
+    if (holder.scope === null || holder.settings === null) return null
+    const descriptors = holder.settings.describe({ redactSecrets: true })
+    const descriptor = descriptors.find((d) => String(d.ns) === NAMESPACE)
+    if (descriptor === undefined) return null
+    return {
+      value: descriptor.value ?? {},
+      base: descriptor.base ?? {},
+      user: descriptor.user ?? {},
+      revision: descriptor.revision,
+      writable: holder.settings.writable === true,
+    }
+  }
+
+  function validateOps(payload) {
+    if (payload === null || typeof payload !== 'object' || !Array.isArray(payload.ops) || payload.ops.length === 0) {
+      return 'payload.ops must be a non-empty array'
+    }
+    if (payload.ops.length > 40) return 'too many ops in one write'
+    for (const op of payload.ops) {
+      if (op === null || typeof op !== 'object' || (op.op !== 'set' && op.op !== 'unset')) {
+        return 'each op must be { op: "set" | "unset", path: [field] }'
+      }
+      if (!Array.isArray(op.path) || op.path.length !== 1 || typeof op.path[0] !== 'string' || op.path[0].length === 0 || op.path[0].length > 64) {
+        return 'op.path must be a single field name'
+      }
+      if (op.op === 'set' && op.value === undefined) return 'set ops require a value'
+    }
+    return null
+  }
+
+  const routeHandler = async (request, response) => {
+    const pathname = new URL(request.url ?? '/', 'http://x').pathname
+    if (pathname !== ROUTE_PREFIX + '/config') {
+      sendJson(response, 404, { ok: false, error: 'unknown dsh-github-router route' })
+      return
+    }
+    if (request.method === 'GET') {
+      if (holder.scope === null || holder.settings === null) {
+        sendJson(response, 503, { ok: false, error: 'the settings service is not mounted in this deployment' })
+        return
+      }
+      const view = viewOf()
+      if (view === null) {
+        sendJson(response, 503, { ok: false, error: 'settings namespace is not registered' })
+        return
+      }
+      sendJson(response, 200, { ok: true, value: view })
+      return
+    }
+    if (request.method === 'POST') {
+      if (!sameOrigin(request)) {
+        sendJson(response, 403, { ok: false, error: 'configuration writes are limited to same-origin requests' })
+        return
+      }
+      if (holder.scope === null || holder.settings === null) {
+        sendJson(response, 503, { ok: false, error: 'the settings service is not mounted in this deployment' })
+        return
+      }
+      let payload
+      try {
+        payload = await readJsonBody(request)
+      } catch (error) {
+        sendJson(response, 400, { ok: false, error: `unreadable request body: ${String(error && error.message ? error.message : error)}` })
+        return
+      }
+      const invalid = validateOps(payload)
+      if (invalid !== null) {
+        sendJson(response, 400, { ok: false, error: invalid })
+        return
+      }
+      const expectedRevision = Number.isInteger(payload.expectedRevision) ? payload.expectedRevision : undefined
+      try {
+        await holder.scope.mutate(payload.ops, expectedRevision)
+      } catch (error) {
+        sendJson(response, 409, { ok: false, error: error instanceof Error ? error.message : String(error) })
+        return
+      }
+      const view = viewOf()
+      if (view === null) {
+        sendJson(response, 503, { ok: false, error: 'settings namespace disappeared after the write' })
+        return
+      }
+      sendJson(response, 200, { ok: true, value: view })
+      return
+    }
+    response.writeHead(405, { allow: 'GET, POST' })
+    response.end()
+  }
+
+  ctx.inject(['webServer'], (hctx) => {
+    hctx.effect(() => hctx.webServer.register({ kind: 'prefix', path: ROUTE_PREFIX, handler: routeHandler }), 'dsh-github-router: settings routes')
+  })
+
+  return {
+    options: () => (holder.scope !== null ? resolveOptions(holder.scope.get()) : resolveOptions(config)),
+  }
+}

package/lib/render.js

@@ -0,0 +1,154 @@
+/**
+ * Model-facing text renderers for the canonical tool values.
+ * @module dsh-github-router/render
+ */
+
+function routeLine(routes) {
+  const parts = Object.entries(routes ?? {})
+    .filter(([, v]) => v !== null && v !== undefined && v !== '')
+    .map(([k, v]) => `${k}=${v}`)
+  return parts.length > 0 ? `routes: ${parts.join(', ')}` : 'routes: none'
+}
+
+function notesLine(notes) {
+  return Array.isArray(notes) && notes.length > 0 ? `notes:\n${notes.map((n) => '  - ' + n).join('\n')}` : ''
+}
+
+export function renderPr(value) {
+  if (value && typeof value.error === 'string') {
+    const routes = value.routes ? `\n${routeLine(value.routes)}` : ''
+    const notes = notesLine(value.notes)
+    return [{ type: 'text', text: `github_pr failed: ${value.error}${routes}${notes ? '\n' + notes : ''}` }]
+  }
+  const p = value.pr ?? {}
+  const lines = []
+  lines.push(`# PR ${p.owner}/${p.repo}#${p.number}: ${p.title ?? '(no title)'}`)
+  const flags = []
+  if (p.state) flags.push(p.state.toLowerCase())
+  if (p.draft) flags.push('draft')
+  if (p.merged) flags.push('merged')
+  lines.push(
+    `state: ${flags.length > 0 ? flags.join(', ') : 'unknown'} | author: ${p.author ?? 'unknown'} | +${p.additions ?? '?'}/-${p.deletions ?? '?'} across ${p.changedFiles ?? '?'} files`,
+  )
+  if (p.baseRef && p.headRef) lines.push(`base: ${p.baseRef} (${(p.baseSha ?? '').slice(0, 8)}) -> head: ${p.headRef} (${(p.headSha ?? '').slice(0, 8)})`)
+  const dates = [p.createdAt ? `created ${p.createdAt}` : null, p.updatedAt ? `updated ${p.updatedAt}` : null, p.mergedAt ? `merged ${p.mergedAt}` : null].filter(Boolean)
+  if (dates.length > 0) lines.push(dates.join(' | '))
+  if (p.url) lines.push(`url: ${p.url}`)
+  if (p.body && p.body.length > 0) {
+    lines.push('')
+    lines.push('## Description')
+    lines.push(p.body)
+  }
+  if (value.discussion && value.discussion.length > 0) {
+    lines.push('', `## Discussion (${value.discussion.length}${value.routes.discussion ? ', via ' + value.routes.discussion : ''})`)
+    for (const item of value.discussion) {
+      lines.push(`- [${item.kind}] ${item.author ?? 'unknown'}${item.createdAt ? ' @ ' + item.createdAt : ''}${item.path ? ' (' + item.path + ')' : ''}`)
+      lines.push('  ' + String(item.body ?? '').split('\n').join('\n  '))
+    }
+  }
+  if (value.reviews && value.reviews.length > 0) {
+    lines.push('', `## Reviews (${value.reviews.length})`)
+    for (const r of value.reviews) {
+      lines.push(`- [${r.state ?? 'review'}] ${r.author ?? 'unknown'}${r.submittedAt ? ' @ ' + r.submittedAt : ''}`)
+      if (r.body) lines.push('  ' + String(r.body).split('\n').join('\n  '))
+    }
+  }
+  if (value.files && value.files.length > 0) {
+    lines.push('', `## Files (${value.files.length})`)
+    for (const f of value.files) {
+      const parts = [`${f.path}`, f.status ? ` [${f.status}]` : '', `+${f.additions ?? 0}/-${f.deletions ?? 0}`]
+      lines.push(`- ${parts.join(' ')}`)
+    }
+  }
+  if (value.commits && value.commits.length > 0) {
+    lines.push('', `## Commits (${value.commits.length})`)
+    for (const c of value.commits) {
+      lines.push(`- ${(c.sha ?? '').slice(0, 8)} ${c.author ?? ''}${c.date ? ' ' + c.date : ''}: ${String(c.message ?? '').split('\n')[0].slice(0, 140)}`)
+    }
+  }
+  if (value.diff !== null && value.diff !== undefined) {
+    lines.push('', `## Diff (via ${value.routes.diff ?? '?'}${value.diffTruncated ? ', truncated' : ''})`)
+    lines.push(value.diff)
+  }
+  lines.push('', routeLine(value.routes))
+  const notes = notesLine(value.notes)
+  if (notes.length > 0) lines.push(notes)
+  return [{ type: 'text', text: lines.join('\n') }]
+}
+
+export function renderIssue(value) {
+  if (value && typeof value.error === 'string') {
+    const routes = value.routes ? `\n${routeLine(value.routes)}` : ''
+    const notes = notesLine(value.notes)
+    return [{ type: 'text', text: `github_issue failed: ${value.error}${routes}${notes ? '\n' + notes : ''}` }]
+  }
+  const i = value.issue ?? {}
+  const lines = []
+  lines.push(`# Issue ${i.owner}/${i.repo}#${i.number}: ${i.title ?? '(no title)'}`)
+  lines.push(`state: ${i.state ?? 'unknown'}${i.stateReason ? ' (' + i.stateReason + ')' : ''} | author: ${i.author ?? 'unknown'} | comments: ${i.commentsCount ?? '?'}`)
+  const dates = [i.createdAt ? `created ${i.createdAt}` : null, i.updatedAt ? `updated ${i.updatedAt}` : null, i.closedAt ? `closed ${i.closedAt}` : null].filter(Boolean)
+  if (dates.length > 0) lines.push(dates.join(' | '))
+  if (i.labels && i.labels.length > 0) lines.push(`labels: ${i.labels.join(', ')}`)
+  if (i.url) lines.push(`url: ${i.url}`)
+  if (i.body && i.body.length > 0) {
+    lines.push('', '## Body')
+    lines.push(i.body)
+  }
+  if (value.comments && value.comments.length > 0) {
+    lines.push('', `## Comments (${value.comments.length}${value.routes.comments ? ', via ' + value.routes.comments : ''})`)
+    for (const c of value.comments) {
+      lines.push(`- [${c.kind}] ${c.author ?? 'unknown'}${c.createdAt ? ' @ ' + c.createdAt : ''}`)
+      lines.push('  ' + String(c.body ?? '').split('\n').join('\n  '))
+    }
+  }
+  lines.push('', routeLine(value.routes))
+  const notes = notesLine(value.notes)
+  if (notes.length > 0) lines.push(notes)
+  return [{ type: 'text', text: lines.join('\n') }]
+}
+
+export function renderFile(value) {
+  if (value && typeof value.error === 'string') {
+    const failures = Array.isArray(value.failures) && value.failures.length > 0 ? `\nfailures:\n${value.failures.map((f) => '  - ' + f).join('\n')}` : ''
+    return [{ type: 'text', text: `github_file failed: ${value.error}${failures}` }]
+  }
+  if (value.kind === 'directory') {
+    const lines = [`directory ${value.path} @ ${value.ref} (${value.entries.length} entries, via ${value.route})`]
+    for (const e of value.entries) lines.push(`- ${e.name} (${e.type}${e.size !== null && e.size !== undefined ? ', ' + e.size + ' bytes' : ''})`)
+    return [{ type: 'text', text: lines.join('\n') }]
+  }
+  const head = `file ${value.path} @ ${value.ref} (${value.size} bytes, via ${value.route}${value.truncated ? ', truncated at cap' : ''})`
+  return [{ type: 'text', text: head + '\n\n' + value.content }]
+}
+
+export function renderProbe(value) {
+  if (value && typeof value.error === 'string') return [{ type: 'text', text: `github_probe failed: ${value.error}` }]
+  const lines = ['# GitHub route probe (host-side connectivity)']
+  lines.push(`proxy in use: ${value.proxy ?? 'none'}`)
+  lines.push(`token configured: ${value.tokenConfigured ? 'yes' : 'no (anonymous limits)'}`)
+  lines.push('')
+  for (const c of value.checks) {
+    lines.push(`[${c.ok ? 'OK ' : 'FAIL'}] ${c.route.padEnd(16)} ${c.ms}ms  ${c.detail}`)
+  }
+  lines.push('')
+  lines.push('Live routes: ' + (value.live.length > 0 ? value.live.join(', ') : '(none)'))
+  lines.push('Recommendation:')
+  for (const r of value.recommendation) lines.push(`  - ${r}`)
+  return [{ type: 'text', text: lines.join('\n') }]
+}
+
+export function renderApi(value) {
+  if (value && typeof value.error === 'string') {
+    return [{ type: 'text', text: `github_api failed: ${value.error}${value.path ? ` (${value.path})` : ''}` }]
+  }
+  const rateClause = value.rateLimit !== null && value.rateLimit !== undefined ? ` (rate limit remaining: ${value.rateLimit})` : ''
+  const head = `GET ${value.path} -> HTTP ${value.status}${rateClause}${value.truncated ? ' [truncated]' : ''}`
+  let body
+  if (value.json !== undefined && value.json !== null) {
+    body = JSON.stringify(value.json, null, 2)
+  } else {
+    body = value.text ?? ''
+  }
+  if (body.length > 0) return [{ type: 'text', text: head + '\n\n' + body }]
+  return [{ type: 'text', text: head }]
+}