@goodandready/dsh-github-ops 0.1.0

package/lib/index.js

@@ -0,0 +1,332 @@
+// dsh-github-ops — host half.
+//
+// Gives the agent the GitHub operations the release pipeline needs and the plugin
+// ecosystem lacks: releases, tags, a guarded generic API pass-through, repository and
+// file reads, issues, pull requests with a review pack, CI checks, workflow runs,
+// secrets/variables, rulesets and sanitized mirror publication.
+//
+// Security model: the token lives in the DSH credential service (settings hold only
+// the credential NAME), reads are free, and every state-changing call must carry
+// `confirm: true`. A small deny list refuses the calls a single confirmation cannot
+// undo (deleting a repository, transferring ownership, deleting an organization).
+
+import Schema from '@deepseek-ai/schemastery'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { credentialRef } from '@deepseek-ai/dsh-credentials'
+
+import { createGitHubClient, parseRepoSpec, describeError, GitHubError } from './github.js'
+import { resolveAccess, NO_ACCESS_GUIDANCE } from './auth.js'
+import { resolveRepoContext } from './repo-context.js'
+import { presentationFor } from './present.js'
+import { createRecords, startReviewJob } from './jobs.js'
+import { registerCommands } from './commands.js'
+import { registerJobTools } from './tools/register-jobs.js'
+import { registerApprovalGate, ALL_ACTIONS } from './approval.js'
+import { registerCoreTools } from './tools/register-core.js'
+import { registerCollabTools } from './tools/register-collab.js'
+import { registerMirrorTools } from './tools/register-mirror.js'
+import { registerOpsTools } from './tools/register-ops.js'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+
+const execFileAsync = promisify(execFile)
+
+/** git runner: never throws, always answers with a code and both streams. */
+function makeGitRunner() {
+  return async (args, { cwd, env } = {}) => {
+    try {
+      const { stdout, stderr } = await execFileAsync('git', args, {
+        cwd: cwd || process.cwd(),
+        env: { ...process.env, ...(env || {}) },
+        maxBuffer: 8 * 1024 * 1024,
+      })
+      return { code: 0, stdout, stderr }
+    } catch (err) {
+      return {
+        code: typeof err.code === 'number' ? err.code : 1,
+        stdout: err.stdout || '',
+        stderr: err.stderr || String((err && err.message) || err),
+      }
+    }
+  }
+}
+
+export const name = 'dsh-github-ops'
+export const inject = ['tools', 'credentials', 'settings']
+
+/** Output contract shared by every tool: a value or a described failure. */
+export const OUTPUT_SCHEMA = {
+  type: 'object',
+  additionalProperties: true,
+  properties: {
+    ok: { type: 'boolean' },
+    error: { type: 'string' },
+    data: { type: 'json' },
+  },
+}
+
+const MAX_RENDER_CHARS = 20000
+
+/** Actions this plugin can be asked to perform; exposed for settings validation. */
+export const KNOWN_ACTIONS = ALL_ACTIONS
+
+/** Render a tool result for the model: readable text, bounded so one call cannot flood the turn. */
+export function renderToolResult(toolName, value) {
+  if (!value || value.ok !== true) {
+    const error = (value && value.error) || 'unknown error'
+    return [{ type: 'text', text: `${toolName} failed: ${error}` }]
+  }
+  const data = value.data
+  let text
+  if (typeof data === 'string') text = data
+  else if (data === undefined || data === null) text = `${toolName}: done`
+  else {
+    try {
+      text = JSON.stringify(data, null, 2)
+    } catch {
+      text = String(data)
+    }
+  }
+  if (text.length > MAX_RENDER_CHARS) {
+    text = `${text.slice(0, MAX_RENDER_CHARS)}\n… output truncated (${text.length} characters total)`
+  }
+  return [{ type: 'text', text }]
+}
+
+export const Config = Schema.object({
+  tokenEnv: Schema.string().role('credential-ref').default('GITHUB_TOKEN')
+    .description('Name used to look up access: the DSH credential, then the environment variable, then the gh CLI. The value itself is never stored in settings.'),
+  tokenSource: Schema.string().default('auto')
+    .description('Where access comes from: "auto" tries the DSH credential, then the environment variable, then the gh CLI; pin it to "credentials", "env" or "gh" to use one source only.'),
+  defaultRepository: Schema.string().default('')
+    .description('Default repository as "owner/repo"; used when a tool call omits the repository.'),
+  baseUrl: Schema.string().default('https://api.github.com')
+    .description('GitHub API base URL; change it for GitHub Enterprise.'),
+  timeoutMs: Schema.number().default(30000)
+    .description('Per-request timeout in milliseconds.'),
+  maxRetries: Schema.number().default(2)
+    .description('Retries for a read (GET/HEAD) on a network failure, a timeout or a 5xx. Writes are never retried automatically.'),
+  reviewRulesJson: Schema.string().default('')
+    .description('Optional review-rule overrides as JSON: sensitivePaths, sensitiveSeverity, attentionPaths, migrationPaths, testsRequired, sourcePatterns, testPatterns, largeDiffLines.'),
+  allowedActions: Schema.array(Schema.string()).default([])
+    .description('Write actions this plugin may perform; anything else is denied. Empty means every known action is allowed, and each one still asks for confirmation.'),
+  autoApprove: Schema.array(Schema.string()).default([])
+    .description('Actions an unattended run (DSH_GITHUB_OPS_UNATTENDED=1) may perform without asking. Destructive actions are never auto-approved.'),
+  reviewJobTimeoutMs: Schema.number().default(120000)
+    .description('How long a background review job may run before it is cancelled.'),
+})
+
+export function apply(ctx, rawConfig) {
+  const config = { ...Config(), ...(rawConfig || {}) }
+  let settingsScope = null
+
+  ctx.inject(['settings'], (sctx) => {
+    try {
+      settingsScope = sctx.settings.register(name, Config, { base: config })
+    } catch (err) {
+      ctx.logger?.warn?.('[dsh-github-ops] settings namespace unavailable:', err && err.message)
+    }
+  })
+
+  /** Review-rule overrides from settings; a broken value is reported, never silently ignored. */
+  function reviewRules() {
+    const raw = liveConfig().reviewRulesJson
+    if (!raw || typeof raw !== 'string' || !raw.trim()) return undefined
+    try {
+      const parsed = JSON.parse(raw)
+      return parsed && typeof parsed === 'object' ? parsed : undefined
+    } catch (err) {
+      ctx.logger?.warn?.('[dsh-github-ops] reviewRulesJson is not valid JSON and was ignored:', err && err.message)
+      return undefined
+    }
+  }
+
+  function liveConfig() {
+    try {
+      const fromScope = settingsScope && settingsScope.get && settingsScope.get()
+      return { ...config, ...(fromScope || {}) }
+    } catch {
+      return config
+    }
+  }
+
+  /** The gh CLI session, when the machine already has `gh auth login` done. */
+  async function ghCliAccess() {
+    const { stdout } = await execFileAsync('gh', ['auth', 'token'], { timeout: 10000, maxBuffer: 1024 * 1024 })
+    return stdout
+  }
+
+  /** Resolve access for one operation; nothing is cached, so a rotation lands immediately. */
+  async function resolveToken() {
+    const cfg = liveConfig()
+    return resolveAccess({
+      // the credentials service takes a branded reference, not a bare name
+      credentials: {
+        resolve: async (name) => {
+          try {
+            return await ctx.credentials.resolve(credentialRef(name))
+          } catch {
+            return null
+          }
+        },
+      },
+      tokenEnv: cfg.tokenEnv,
+      tokenSource: cfg.tokenSource || 'auto',
+      env: process.env,
+      runGh: ghCliAccess,
+    })
+  }
+
+  async function client() {
+    const cfg = liveConfig()
+    const access = await resolveToken()
+    if (!access.value) {
+      throw new Error(`GitHub access is not configured: ${access.guidance || NO_ACCESS_GUIDANCE}`)
+    }
+    return createGitHubClient({
+      token: access.value,
+      baseUrl: cfg.baseUrl || 'https://api.github.com',
+      timeoutMs: Number(cfg.timeoutMs) || 30000,
+      maxRetries: Number.isFinite(Number(cfg.maxRetries)) ? Number(cfg.maxRetries) : 2,
+    })
+  }
+
+  /**
+   * Which repository a call is about: the one it names, the configured default, or — inside
+   * a checkout — the one the origin remote already identifies. A bare "#12" keeps talking to
+   * the repository the previous call used.
+   */
+  async function asRepo(args, cfg) {
+    const explicit = args && args.repository ? String(args.repository) : ''
+    const fallback = cfg.defaultRepository || ''
+    let remoteUrl = ''
+    if (!(explicit && explicit.includes('/')) && !fallback) {
+      const cwd = (typeof ctx.cwd === 'string' && ctx.cwd) || process.cwd()
+      const git = makeGitRunner()
+      const origin = await git(['remote', 'get-url', 'origin'], { cwd })
+      if (origin.code === 0) remoteUrl = origin.stdout.trim()
+    }
+    const resolved = resolveRepoContext({ explicit, fallback, remoteUrl })
+    if (!resolved) {
+      throw new Error('repository is required: pass "owner/repo", set a default repository in the plugin settings, or run inside a checkout with an origin remote')
+    }
+    return resolved
+  }
+
+  /**
+   * Register one tool whose failures become values: a GitHub error never breaks a turn.
+   * The tool contract requires an output schema plus a renderer, so both are supplied
+   * here once instead of in every definition.
+   *
+   * A tool name already claimed in this scope is a hard error in the core, and an error
+   * thrown from apply() takes the whole plugin tree — and therefore the harness — down.
+   * Another GitHub plugin may legitimately own the same name (the reference plugin
+   * exposes several of them), so a taken name is skipped and reported instead: this
+   * plugin must never be the reason a deployment cannot start.
+   */
+  const skippedTools = []
+  function tool(toolName, description, parameters, run) {
+    const definition = defineTool({
+      name: toolName,
+      description,
+      parameters,
+      output: {
+        schema: OUTPUT_SCHEMA,
+        render: (_args, value) => renderToolResult(toolName, value),
+      },
+      ...presentationFor(toolName),
+      execute: async (args) => {
+        try {
+          const value = await run(args || {})
+          return { ok: true, data: value }
+        } catch (err) {
+          const out = { ok: false, error: describeError(err) }
+          if (err instanceof GitHubError) {
+            if (err.status) out.status = err.status
+            if (err.code) out.code = err.code
+            if (err.rateLimit) out.rateLimit = err.rateLimit
+          }
+          return out
+        }
+      },
+    })
+    try {
+      ctx.tools.register(definition)
+    } catch (err) {
+      if (!/is already registered/.test(String((err && err.message) || err))) throw err
+      skippedTools.push(toolName)
+      ctx.logger?.warn?.(`[dsh-github-ops] tool "${toolName}" is already provided by another plugin; skipping it`)
+    }
+  }
+
+  const deps = { tool, asRepo, client, liveConfig, reviewRules }
+  registerCoreTools(deps)
+  registerCollabTools(deps)
+  registerOpsTools(deps)
+  registerMirrorTools({
+    tool,
+    git: makeGitRunner(),
+    defaultCwd: () => (typeof ctx.cwd === 'string' && ctx.cwd) || process.cwd(),
+  })
+
+  // Background reviews: the host registry when the composition has one, our own records
+  // otherwise, so the tool works in both worlds.
+  const records = createRecords()
+  let hostJobs = null
+  try {
+    hostJobs = ctx.get ? ctx.get('jobs') : undefined
+  } catch {
+    hostJobs = null
+  }
+  registerJobTools({
+    tool,
+    asRepo,
+    client,
+    liveConfig,
+    reviewRules,
+    jobs: {
+      start: (spec) => startReviewJob({ registry: hostJobs, records, ...spec }),
+      get: (id) => records.get(id),
+      list: () => records.list(),
+    },
+  })
+
+  // Slash commands are a fast path for a human: they only hand the model an instruction, so
+  // the write still goes through the approval gate.
+  ctx.inject(['commands'], (cctx) => {
+    try {
+      const git = makeGitRunner()
+      const readGitState = async () => {
+        const cwd = (typeof ctx.cwd === 'string' && ctx.cwd) || process.cwd()
+        const branch = await git(['rev-parse', '--abbrev-ref', 'HEAD'], { cwd })
+        const remote = await git(['remote', 'get-url', 'origin'], { cwd })
+        const resolved = remote.code === 0
+          ? resolveRepoContext({ remoteUrl: remote.stdout.trim() })
+          : null
+        return {
+          branch: branch.code === 0 ? branch.stdout.trim() : undefined,
+          repo: resolved ? `${resolved.owner}/${resolved.repo}` : undefined,
+          remoteUrl: remote.code === 0 ? remote.stdout.trim() : undefined,
+        }
+      }
+      registerCommands(cctx.commands, { readGitState })
+    } catch (err) {
+      ctx.logger?.warn?.('[dsh-github-ops] slash commands not registered:', err && err.message)
+    }
+  })
+
+  // Writes go through the approval contour: a named action, a reason a human can decide
+  // on, and no auto-approval for anything destructive.
+  try {
+    registerApprovalGate(ctx, () => liveConfig())
+  } catch (err) {
+    ctx.logger?.warn?.('[dsh-github-ops] approval gate not registered:', err && err.message)
+  }
+
+  if (skippedTools.length) {
+    ctx.logger?.warn?.(
+      `[dsh-github-ops] ${skippedTools.length} tool(s) left to the plugin that already provides them: `
+      + skippedTools.join(', '),
+    )
+  }
+}

package/lib/jobs.js

@@ -0,0 +1,107 @@
+// Long reviews as background jobs.
+//
+// A review of a big pull request can take a while, and a turn should not sit and wait for
+// it. When the host exposes a job registry (`ctx.jobs`) the work runs there, where the UI
+// can show it and cancel it; otherwise it runs in this plugin's own registry, so the feature
+// degrades to "works, just without the host UI" instead of "missing".
+//
+// Records are kept in memory, bounded, and never contain the access value.
+
+export const REVIEW_JOB_KIND = 'github-review'
+const DEFAULT_RECORD_LIMIT = 20
+
+/** Bounded record store for started jobs. */
+export function createRecords({ limit = DEFAULT_RECORD_LIMIT } = {}) {
+  const records = new Map()
+  return {
+    remember(id, record) {
+      records.set(id, record)
+      while (records.size > limit) {
+        const oldest = records.keys().next().value
+        records.delete(oldest)
+      }
+      return id
+    },
+    get(id) {
+      return records.get(id) || null
+    },
+    list() {
+      return [...records.entries()].map(([id, record]) => ({ id, ...record }))
+    },
+    get size() {
+      return records.size
+    },
+  }
+}
+
+function splitRepo(repo) {
+  const [owner, name] = String(repo || '').split('/')
+  if (!owner || !name) throw new Error(`"${repo}" is not an owner/repo pair`)
+  return { owner, repo: name }
+}
+
+/**
+ * Start one review job.
+ *
+ * @param registry - host job registry (ctx.jobs) when available
+ * @param records - record store from createRecords()
+ * @param spec - { repo, pr, label, owner, timeoutMs, maxDiffChars, rules, client, ciRun }
+ * @returns the job id
+ */
+export function startReviewJob({ registry, records, repo, pr, label, owner, timeoutMs = 120000, maxDiffChars, rules, client, ciRun }) {
+  const target = splitRepo(repo)
+  const record = {
+    kind: REVIEW_JOB_KIND,
+    status: 'running',
+    repo,
+    pr,
+    startedAt: new Date().toISOString(),
+    finishedAt: null,
+    report: null,
+    error: null,
+  }
+
+  const run = async () => {
+    try {
+      const clientInstance = typeof client === 'function' ? await client() : client
+      const report = await ciRun(clientInstance, { ...target, number: pr, maxDiffChars, rules })
+      record.status = 'done'
+      record.report = report
+      record.finishedAt = new Date().toISOString()
+      return report
+    } catch (err) {
+      record.status = 'failed'
+      record.error = String((err && err.message) || err)
+      record.finishedAt = new Date().toISOString()
+      throw err
+    }
+  }
+
+  const useHost = registry && typeof registry.start === 'function'
+  const id = useHost
+    ? registry.start({
+      kind: REVIEW_JOB_KIND,
+      label: label || `${REVIEW_JOB_KIND} ${repo}#${pr}`,
+      owner,
+      timeoutMs,
+      outputLimitBytes: 64 * 1024,
+      run,
+    })
+    : `local-${Date.now().toString(36)}-${records.size + 1}`
+
+  records.remember(id, record)
+  if (!useHost) {
+    // no host registry: run it in the background, but never let a rejection escape
+    Promise.resolve().then(run).catch(() => {})
+  }
+  return id
+}
+
+/** One-line status for the model, derived from a record. */
+export function describeRecord(record) {
+  if (!record) return 'unknown job'
+  if (record.status === 'running') return `running: review of ${record.repo}#${record.pr}`
+  if (record.status === 'failed') return `failed: review of ${record.repo}#${record.pr} — ${record.error}`
+  const verdict = record.report && record.report.verdict ? record.report.verdict : 'done'
+  return `${verdict}: review of ${record.repo}#${record.pr}`
+}

package/lib/present.js

@@ -0,0 +1,214 @@
+// Tool presentation: what the human sees instead of a JSON blob.
+//
+// `presentCall` renders the pending card before a tool runs, `presentResult` the completed
+// one. Both are pure: they take the arguments and the tool result and return a card, which
+// keeps them testable and cheap. A missing presentation simply falls back to the default
+// renderer, so an unlisted tool is never broken.
+
+const text = (title, body) => ({
+  card: 'generic',
+  title,
+  content: [{ type: 'text', text: body }],
+})
+
+const pending = (title, rawInput) => ({ card: 'generic', title, rawInput })
+
+/** Reduce an arbitrary argument set to the fields a pending card should show. */
+function pick(args, keys) {
+  const out = {}
+  for (const key of keys) if (args && args[key] !== undefined) out[key] = args[key]
+  return out
+}
+
+function failure(title, result) {
+  if (!result || result.ok !== false) return null
+  return text(title, String(result.error || 'unknown error'))
+}
+
+function repoOf(args) {
+  return args && args.repository ? String(args.repository) : 'the default repository'
+}
+
+export const identityMeta = (args) => ({ title: String((args && args.repository) || '') })
+
+const PRESENTATIONS = {
+  gh_repo: {
+    call: (args) => pending(`Read repository ${repoOf(args)}`, pick(args, ['repository'])),
+    result: (_args, r) => failure('Repository not read', r)
+      || text(r.data.fullName, `${r.data.description || '(no description)'}\n${r.data.private ? 'private' : 'public'} · ${r.data.defaultBranch} · ★${r.data.stars} · topics: ${r.data.topics.join(', ') || 'none'}`),
+  },
+  gh_file: {
+    call: (args) => pending(`Read ${args.path || 'a file'}`, pick(args, ['repository', 'path', 'ref'])),
+    result: (_args, r) => failure('File not read', r)
+      || text(r.data.path, r.data.kind === 'directory'
+        ? `${r.data.entries.length} entries: ${r.data.entries.slice(0, 12).map((e) => e.name).join(', ')}`
+        : `${r.data.size} bytes · sha ${String(r.data.sha || '').slice(0, 7)}${r.data.truncated ? ' · truncated' : ''}`),
+  },
+  gh_repo_search: {
+    call: (args) => pending(`Search repositories: ${args.query}`, pick(args, ['query'])),
+    result: (_args, r) => failure('Search failed', r)
+      || text(`${r.data.total} repositories`, r.data.repos.slice(0, 10).map((x) => `${x.fullName} ★${x.stars} — ${x.description || ''}`).join('\n')),
+  },
+  gh_release_list: {
+    call: (args) => pending(`List releases of ${repoOf(args)}`, pick(args, ['repository'])),
+    result: (_args, r) => failure('Releases not listed', r)
+      || text(`${r.data.count} releases`, r.data.releases.map((x) => `${x.tag}${x.draft ? ' (draft)' : ''}${x.prerelease ? ' (pre)' : ''} — ${x.name}`).join('\n')),
+  },
+  gh_release_view: {
+    call: (args) => pending(`Read release ${args.tag}`, pick(args, ['repository', 'tag'])),
+    result: (_args, r) => failure('Release not read', r)
+      || text(`Release ${r.data.tag}`, `${r.data.name}\n${r.data.draft ? 'draft · ' : ''}${r.data.assets.length} assets\n${r.data.url}`),
+  },
+  gh_release_create: {
+    call: (args) => pending(`Create release ${args.tag}`, pick(args, ['repository', 'tag', 'name', 'draft', 'prerelease', 'target'])),
+    result: (_args, r) => failure('Release not created', r)
+      || text(`Created release ${r.data.tag}`, `${r.data.url}${r.data.draft ? '\n(draft)' : ''}`),
+  },
+  gh_release_edit: {
+    call: (args) => pending(`Edit release ${args.tag || args.releaseId}`, pick(args, ['repository', 'tag', 'releaseId', 'name', 'makeLatest'])),
+    result: (_args, r) => failure('Release not edited', r)
+      || text(`Updated release ${r.data.tag}`, `name: ${r.data.name}\nlatest: ${r.data.draft ? 'no (draft)' : 'see the repository page'}\n${r.data.url}`),
+  },
+  gh_release_delete: {
+    call: (args) => pending(`Delete release ${args.tag || args.releaseId}`, pick(args, ['repository', 'tag', 'releaseId'])),
+    result: (_args, r) => failure('Release not deleted', r) || text(`Deleted release ${r.data.id}`, `tag ${r.data.tag || '(by id)'} — the git tag itself was not touched`),
+  },
+  gh_tag_list: {
+    call: (args) => pending(`List tags of ${repoOf(args)}`, pick(args, ['repository'])),
+    result: (_args, r) => failure('Tags not listed', r)
+      || text(`${r.data.count} tags`, r.data.tags.map((t) => `${t.name} ${String(t.sha).slice(0, 7)}`).join('\n')),
+  },
+  gh_tag_create: {
+    call: (args) => pending(`Create tag ${args.tag}`, pick(args, ['repository', 'tag', 'sha', 'message'])),
+    result: (_args, r) => failure('Tag not created', r)
+      || text(`Created tag ${r.data.name}`, `${r.data.annotated ? 'annotated' : 'lightweight'} → ${String(r.data.target).slice(0, 7)}`),
+  },
+  gh_tag_delete: {
+    call: (args) => pending(`Delete tag ${args.tag}`, pick(args, ['repository', 'tag'])),
+    result: (_args, r) => failure('Tag not deleted', r) || text(`Deleted tag ${r.data.tag}`, 'the tag is gone from the remote'),
+  },
+  gh_issue: {
+    call: (args) => pending(`${args.action === 'get' || args.action === 'comments' ? 'Read' : 'List'} issues of ${repoOf(args)}`, pick(args, ['repository', 'action', 'number', 'state', 'kind'])),
+    result: (_args, r) => {
+      const bad = failure('Issues not read', r)
+      if (bad) return bad
+      const data = r.data
+      if (data.comments) return text(`Issue #${data.number}: ${data.comments.length} comments`, data.comments.map((c) => `${c.author}: ${String(c.body).slice(0, 120)}`).join('\n'))
+      if (data.number) return text(`Issue #${data.number} (${data.state})`, `${data.title}\n${data.url}`)
+      return text(`${data.count} items`, (data.issues || []).map((i) => `#${i.number} [${i.kind}] ${i.title}`).join('\n'))
+    },
+  },
+  issue_open: {
+    call: (args) => pending(`Open issue: ${args.title}`, pick(args, ['repository', 'title', 'labels'])),
+    result: (_args, r) => failure('Issue not opened', r) || text(`Opened issue #${r.data.number}`, `${r.data.title}\n${r.data.url}`),
+  },
+  issue_comment: {
+    call: (args) => pending(`Comment on #${args.number}`, pick(args, ['repository', 'number'])),
+    result: (_args, r) => failure('Comment not posted', r) || text(`Commented on #${r.data.id ? '' : ''}`, `comment id ${r.data.id}`),
+  },
+  issue_close: {
+    call: (args) => pending(`Close #${args.number}`, pick(args, ['repository', 'number', 'stateReason'])),
+    result: (_args, r) => failure('Issue not closed', r) || text(`Closed #${r.data.number}`, `state ${r.data.state}${r.data.stateReason ? ` (${r.data.stateReason})` : ''}`),
+  },
+  gh_search: {
+    call: (args) => pending(`Search issues: ${args.query}`, pick(args, ['query'])),
+    result: (_args, r) => failure('Search failed', r)
+      || text(`${r.data.total} results`, r.data.issues.slice(0, 10).map((i) => `${i.repository ? i.repository + ' ' : ''}#${i.number} ${i.title}`).join('\n')),
+  },
+  pr_create: {
+    call: (args) => pending(`Create pull request: ${args.title}`, pick(args, ['repository', 'title', 'head', 'base', 'draft'])),
+    result: (_args, r) => failure('Pull request not created', r)
+      || text(`Created pull request #${r.data.number}`, `${r.data.url}\n${r.data.base} ← ${r.data.head}${r.data.draft ? ' (draft)' : ''}`),
+  },
+  pr_update: {
+    call: (args) => pending(`Update pull request #${args.number}`, pick(args, ['repository', 'number', 'title', 'state', 'base'])),
+    result: (_args, r) => failure('Pull request not updated', r)
+      || text(`Updated pull request #${r.data.number}`, `${r.data.title}\nstate ${r.data.state}\n${r.data.url}`),
+  },
+  pr_merge: {
+    call: (args) => pending(`Merge pull request #${args.number}`, pick(args, ['repository', 'number', 'method', 'deleteBranch'])),
+    result: (_args, r) => failure('Pull request not merged', r)
+      || text(r.data.merged ? `Merged #${'pull request'}` : 'Merge not performed', `${r.data.message || ''}${r.data.sha ? `\n${String(r.data.sha).slice(0, 7)}` : ''}${r.data.branchDeleted ? `\nhead branch ${r.data.branchDeleted} deleted` : ''}`),
+  },
+  gh_review: {
+    call: (args) => pending(`Review pull request #${args.number}`, pick(args, ['repository', 'number', 'maxDiffChars'])),
+    result: (_args, r) => failure('Review failed', r)
+      || text(`Pull request #${r.data.pull.number}: ${r.data.pull.title}`, [
+        `areas: ${r.data.areas.join(', ') || 'none'}`,
+        `files: ${r.data.files.length} · checks: ${r.data.checks ? r.data.checks.rollup : 'unknown'}`,
+        r.data.findings.length ? r.data.findings.map((f) => `[${f.level}] ${f.detail}`).join('\n') : 'no findings',
+      ].join('\n')),
+  },
+  review_post: {
+    call: (args) => pending(`Post review on #${args.number} (${args.mode || 'summary'})`, pick(args, ['repository', 'number', 'mode'])),
+    result: (_args, r) => failure('Review not posted', r) || text(`Review posted (${r.data.mode})`, String(r.data.url || `id ${r.data.id}`)),
+  },
+  gh_checks: {
+    call: (args) => pending(`Read checks of ${args.ref}`, pick(args, ['repository', 'ref'])),
+    result: (_args, r) => failure('Checks not read', r)
+      || text(`Checks: ${r.data.rollup}`, r.data.checkRuns.map((c) => `${c.name}: ${c.conclusion || c.status}`).join('\n') || 'no check runs'),
+  },
+  ci_run: {
+    call: (args) => pending(`CI review of pull request #${args.number}`, pick(args, ['repository', 'number'])),
+    result: (_args, r) => failure('CI review failed', r)
+      || text(`CI verdict for #${r.data.number}: ${r.data.verdict}`, r.data.summary),
+  },
+  gh_mirror_check: {
+    call: (args) => pending(`Mirror plan for ${args.ref || 'origin/main'}`, pick(args, ['cwd', 'ref', 'mirror', 'branch'])),
+    result: (_args, r) => failure('Mirror plan failed', r)
+      || text(`Mirror: ${r.data.willPublishCount} files would be published`, `${r.data.willDropCount} stay behind${r.data.refused ? `\nREFUSED: ${r.data.refused}` : ''}`),
+  },
+  gh_mirror_publish: {
+    call: (args) => pending(`Publish mirror ${args.ref || 'origin/main'}${args.dryRun ? ' (dry run)' : ''}`, pick(args, ['cwd', 'ref', 'mirror', 'branch', 'dryRun'])),
+    result: (_args, r) => failure('Mirror not published', r)
+      || text(r.data.pushed ? `Mirror published: ${String(r.data.commit).slice(0, 8)}` : 'Mirror dry run', `${r.data.willPublishCount} files, ${r.data.willDropCount} left behind\n${r.data.mirror}`),
+  },
+  gh_run_list: {
+    call: (args) => pending(`List workflow runs of ${repoOf(args)}`, pick(args, ['repository', 'branch', 'workflow', 'status'])),
+    result: (_args, r) => failure('Runs not listed', r)
+      || text(`${r.data.count} runs`, r.data.runs.map((x) => `#${x.id} ${x.name} ${x.conclusion || x.status} ${x.branch}`).join('\n')),
+  },
+  gh_run_jobs: {
+    call: (args) => pending(`Jobs of run ${args.runId}`, pick(args, ['repository', 'runId'])),
+    result: (_args, r) => failure('Jobs not read', r)
+      || text(`${r.data.count} jobs`, r.data.jobs.map((j) => `${j.name}: ${j.conclusion || j.status}${j.failedSteps.length ? ` — failed: ${j.failedSteps.map((s) => s.name).join(', ')}` : ''}`).join('\n')),
+  },
+  gh_variable_list: {
+    call: (args) => pending(`List variables of ${repoOf(args)}`, pick(args, ['repository', 'environment'])),
+    result: (_args, r) => failure('Variables not listed', r) || text(`${r.data.variables.length} variables`, r.data.variables.map((v) => `${v.name}=${v.value}`).join('\n')),
+  },
+  gh_secret_list: {
+    call: (args) => pending(`List secrets of ${repoOf(args)}`, pick(args, ['repository', 'environment'])),
+    result: (_args, r) => failure('Secrets not listed', r) || text(`${r.data.secrets.length} secrets`, r.data.secrets.map((s) => s.name).join('\n')),
+  },
+  gh_ruleset_list: {
+    call: (args) => pending(`List rulesets of ${repoOf(args)}`, pick(args, ['repository'])),
+    result: (_args, r) => failure('Rulesets not listed', r) || text(`${r.data.rulesets.length} rulesets`, r.data.rulesets.map((x) => `${x.name} (${x.target}, ${x.enforcement})`).join('\n')),
+  },
+  gh_branch_protection_get: {
+    call: (args) => pending(`Read branch protection of ${args.branch}`, pick(args, ['repository', 'branch'])),
+    result: (_args, r) => {
+      const bad = failure('Branch protection not read', r)
+      if (bad) return bad
+      const p = r.data
+      return text(`Branch protection: ${p.branch}`, `reviews: ${p.requiredReviews ? p.requiredReviews.approvals : 0}\nchecks: ${p.requiredStatusChecks ? p.requiredStatusChecks.contexts.join(', ') || 'none' : 'none'}\nforce pushes: ${p.allowForcePushes} · deletions: ${p.allowDeletions} · admins: ${p.enforceAdmins}`)
+    },
+  },
+  gh_api: {
+    call: (args) => pending(`GitHub API: ${args.method || 'GET'} ${args.path || 'graphql'}`, pick(args, ['method', 'path', 'query'])),
+    result: (_args, r) => failure('API call failed', r)
+      || text(`${r.data.method} ${r.data.status || ''}`.trim(), r.data.mutating ? 'state-changing call' : 'read-only call'),
+  },
+}
+
+/** Presentation hooks for one tool, or an empty object when it has none. */
+export function presentationFor(toolName) {
+  const entry = PRESENTATIONS[toolName]
+  if (!entry) return {}
+  return {
+    presentCall: entry.call,
+    presentResult: entry.result,
+  }
+}
+
+export const PRESENTED_TOOLS = Object.keys(PRESENTATIONS)