@goodandready/dsh-github-ops 0.1.0

package/lib/commands.js

@@ -0,0 +1,151 @@
+// Human slash commands: /pr, /review, /issue, /gh.
+//
+// A command never writes to GitHub itself. It gathers the read-only context it can see (the
+// checkout, the current branch, the remote) and hands the model an instruction to call the
+// right tool — so the write still passes through the approval gate, exactly as if the tool
+// had been called directly. Commands are the fast path for a human, not a second API.
+
+export const USAGE = {
+  pr: 'Usage: /pr create [title] — opens a pull request from the current branch',
+  review: 'Usage: /review [number] — reviews a pull request; without a number, the one for the current branch',
+  issue: 'Usage: /issue new <title> | /issue list | /issue show <number>',
+  gh: 'Usage: /gh <tool> [args] — describes how to call one of the plugin tools',
+}
+
+const TOOL_HINTS = {
+  releases: 'gh_release_list, gh_release_view, gh_release_create, gh_release_edit, gh_release_delete',
+  tags: 'gh_tag_list, gh_tag_create, gh_tag_delete',
+  mirror: 'gh_mirror_check, gh_mirror_publish',
+  runs: 'gh_run_list, gh_run_view, gh_run_jobs, gh_run_rerun, gh_run_cancel, gh_run_logs',
+  secrets: 'gh_secret_list, gh_secret_set, gh_secret_delete',
+  variables: 'gh_variable_list, gh_variable_set, gh_variable_delete',
+  rulesets: 'gh_ruleset_list, gh_ruleset_view, gh_ruleset_apply, gh_ruleset_delete',
+  protection: 'gh_branch_protection_get, gh_branch_protection_set, gh_branch_protection_delete',
+}
+
+/** The instruction a /pr create leaves for the model. Pure, so it is testable. */
+export function buildPrInstruction({ title, branch, base = 'main', repo, remoteUrl } = {}) {
+  const where = repo ? ` in ${repo}` : remoteUrl ? ` in the repository of ${remoteUrl}` : ''
+  return [
+    `The user ran /pr create${title ? ` "${title}"` : ''}.`,
+    `Current branch: ${branch || 'unknown'}.`,
+    `Call pr_create with head=${branch || '<current branch>'}, base=${base}${where}${title ? `, title="${title}"` : ''}, and a body that summarises the commits on the branch (git log ${base}..${branch}).`,
+    'If the branch is not pushed yet, say so instead of opening the pull request.',
+  ].join(' ')
+}
+
+/** The instruction a /review leaves for the model. */
+export function buildReviewInstruction({ number, branch, repo } = {}) {
+  const target = number ? `pull request #${number}` : `the pull request for ${branch || 'the current branch'}`
+  return [
+    `The user ran /review. Review ${target}${repo ? ` in ${repo}` : ''}.`,
+    `Call gh_review, then summarise the findings in your own words — critical items first.`,
+    number ? 'If the verdict matters, also call ci_run for the same number.' : 'Find the number with gh_search first if it is unknown.',
+  ].join(' ')
+}
+
+/** The instruction /issue leaves for the model. */
+export function buildIssueInstruction({ sub, title, number, repo } = {}) {
+  if (sub === 'new') {
+    return [
+      `The user ran /issue new${title ? ` "${title}"` : ''}.`,
+      `Call issue_open${repo ? ` in ${repo}` : ''} with that title and a body that spells out the problem, the impact and what done looks like.`,
+      'Ask for anything essential that is missing before opening it.',
+    ].join(' ')
+  }
+  if (sub === 'show') {
+    return `The user ran /issue show ${number}. Call gh_issue with action "get" and number ${number}${repo ? ` in ${repo}` : ''}, then summarise it.`
+  }
+  return `The user ran /issue list. Call gh_issue with action "list"${repo ? ` in ${repo}` : ''} and summarise the open items.`
+}
+
+/** The instruction /gh leaves for the model. */
+export function buildGhInstruction({ topic, tool, args } = {}) {
+  if (!topic && !tool) {
+    return `The user ran /gh. Available groups: ${Object.keys(TOOL_HINTS).join(', ')}. Ask which one, or name a tool directly (for example /gh gh_release_list).`
+  }
+  if (tool) return `The user ran /gh ${tool}${args ? ` ${args}` : ''}. Call the ${tool} tool with the arguments they meant.`
+  return `The user asked about ${topic}. Relevant tools: ${TOOL_HINTS[topic] || 'none'}.`
+}
+
+/**
+ * Register the commands. Every handler returns an instruction for the model; none of them
+ * touches GitHub.
+ */
+export function registerCommands(commands, { readGitState, repoHint } = {}) {
+  const disposers = []
+  const context = async () => {
+    try {
+      return (typeof readGitState === 'function' ? await readGitState() : {}) || {}
+    } catch {
+      return {}
+    }
+  }
+
+  disposers.push(commands.register({
+    name: 'pr',
+    description: 'Create a GitHub pull request from the current branch',
+    input: { hint: 'create [title]' },
+    handler: async (invocation) => {
+      const [sub, ...rest] = String(invocation.rawInput || '').trim().split(/\s+/)
+      if (sub !== 'create') return { kind: 'error', text: USAGE.pr }
+      const git = await context()
+      return {
+        kind: 'success',
+        text: buildPrInstruction({ title: rest.join(' '), branch: git.branch, base: git.base || 'main', repo: git.repo || (typeof repoHint === 'function' ? repoHint() : undefined), remoteUrl: git.remoteUrl }),
+      }
+    },
+  }))
+
+  disposers.push(commands.register({
+    name: 'review',
+    description: 'Review a GitHub pull request',
+    input: { hint: '[number]' },
+    handler: async (invocation) => {
+      const raw = String(invocation.rawInput || '').trim()
+      const number = /^\d+$/.test(raw) ? Number(raw) : undefined
+      const git = await context()
+      return {
+        kind: 'success',
+        text: buildReviewInstruction({ number, branch: git.branch, repo: git.repo || (typeof repoHint === 'function' ? repoHint() : undefined) }),
+      }
+    },
+  }))
+
+  disposers.push(commands.register({
+    name: 'issue',
+    description: 'Open, list or read GitHub issues',
+    input: { hint: 'new <title> | list | show <number>' },
+    handler: async (invocation) => {
+      const [sub, ...rest] = String(invocation.rawInput || '').trim().split(/\s+/)
+      const git = await context()
+      const repo = git.repo || (typeof repoHint === 'function' ? repoHint() : undefined)
+      if (sub === 'new') return { kind: 'success', text: buildIssueInstruction({ sub, title: rest.join(' '), repo }) }
+      if (sub === 'show' && /^\d+$/.test(rest[0] || '')) return { kind: 'success', text: buildIssueInstruction({ sub, number: Number(rest[0]), repo }) }
+      if (!sub || sub === 'list') return { kind: 'success', text: buildIssueInstruction({ sub: 'list', repo }) }
+      return { kind: 'error', text: USAGE.issue }
+    },
+  }))
+
+  disposers.push(commands.register({
+    name: 'gh',
+    description: 'Ask about the GitHub tools of this plugin',
+    input: { hint: '[group|tool] [args]' },
+    handler: async (invocation) => {
+      const [first, ...rest] = String(invocation.rawInput || '').trim().split(/\s+/)
+      const topic = first && TOOL_HINTS[first] ? first : undefined
+      const tool = first && /^[a-z]+_/.test(first) ? first : (topic ? undefined : first)
+      return { kind: 'success', text: buildGhInstruction({ topic, tool, args: rest.join(' ') }) }
+    },
+  }))
+
+  return () => {
+    for (const dispose of disposers) {
+      try {
+        if (typeof dispose === 'function') dispose()
+      } catch {
+        // a failing disposer must not stop the others
+      }
+    }
+  }
+}

package/lib/github.js

@@ -0,0 +1,315 @@
+// GitHub API client: REST v3 and GraphQL v4 in one place.
+//
+// The transport is injected (`fetchImpl`) and so is the sleep (`sleepImpl`), so every
+// caller and every test runs without a real network or real timers. Errors are normalized
+// into a single shape — `{ ok: false, status, code, message, rateLimit }` at the tool
+// layer — so a tool never throws the whole turn away because GitHub answered 404 or 403.
+//
+// Resilience: a read (GET/HEAD) is retried on a network failure, a timeout, or a 5xx, and
+// a 429 is honoured through `Retry-After` (seconds or a date) or the rate-limit reset. A
+// write is never retried automatically: a failed write has an unknown outcome, and
+// repeating it silently is worse than reporting it.
+
+export const DEFAULT_BASE_URL = 'https://api.github.com'
+export const DEFAULT_GRAPHQL_URL = 'https://api.github.com/graphql'
+export const DEFAULT_API_VERSION = '2022-11-28'
+export const DEFAULT_USER_AGENT = 'dsh-github-ops'
+
+/** Methods whose retry cannot duplicate a state change. */
+export const SAFE_RETRY_METHODS = new Set(['GET', 'HEAD'])
+
+/** Statuses worth another attempt for a read. */
+export const RETRYABLE_STATUS = new Set([429, 502, 503, 504])
+
+/** Normalized failure. */
+export class GitHubError extends Error {
+  constructor(message, { status = 0, code = '', rateLimit = null, details = null, attempts = 1 } = {}) {
+    super(message)
+    this.name = 'GitHubError'
+    this.status = status
+    this.code = code
+    this.rateLimit = rateLimit
+    this.details = details
+    this.attempts = attempts
+  }
+}
+
+function rateLimitFrom(headers) {
+  if (!headers || typeof headers.get !== 'function') return null
+  const remaining = headers.get('x-ratelimit-remaining')
+  const reset = headers.get('x-ratelimit-reset')
+  const limit = headers.get('x-ratelimit-limit')
+  if (remaining === null && reset === null && limit === null) return null
+  const out = {}
+  if (remaining !== null) out.remaining = Number(remaining)
+  if (limit !== null) out.limit = Number(limit)
+  if (reset !== null) {
+    out.resetAt = new Date(Number(reset) * 1000).toISOString()
+  }
+  return out
+}
+
+/**
+ * How long to wait before the next attempt.
+ *
+ * `Retry-After` wins (it is what the server asks for), then the rate-limit reset when the
+ * limit is spent, then exponential backoff. The result is capped so a hostile header
+ * cannot stall a turn.
+ */
+export function retryDelayMs({ headers, attempt, baseMs = 500, maxDelayMs = 10000 } = {}) {
+  const header = headers && typeof headers.get === 'function' ? headers.get('retry-after') : null
+  if (header) {
+    const seconds = Number(header)
+    if (Number.isFinite(seconds) && seconds >= 0) return Math.min(seconds * 1000, maxDelayMs)
+    const at = Date.parse(header)
+    if (Number.isFinite(at)) return Math.min(Math.max(at - Date.now(), 0), maxDelayMs)
+  }
+  const limit = rateLimitFrom(headers)
+  if (limit && limit.remaining === 0 && limit.resetAt) {
+    const wait = Date.parse(limit.resetAt) - Date.now()
+    if (Number.isFinite(wait) && wait > 0) return Math.min(wait, maxDelayMs)
+  }
+  const backoff = baseMs * (2 ** Math.max(0, attempt - 1))
+  return Math.min(backoff, maxDelayMs)
+}
+
+function buildUrl(baseUrl, path, query) {
+  const url = new URL(baseUrl.replace(/\/+$/, '') + (path.startsWith('/') ? path : `/${path}`))
+  if (query && typeof query === 'object') {
+    for (const [key, value] of Object.entries(query)) {
+      if (value === undefined || value === null || value === '') continue
+      url.searchParams.set(key, String(value))
+    }
+  }
+  return url.toString()
+}
+
+/**
+ * Create a client bound to one access value. Nothing here reads globals: the caller
+ * decides the access, the base URL, the transport and the clock.
+ */
+export function createGitHubClient({
+  token = '',
+  baseUrl = DEFAULT_BASE_URL,
+  graphqlUrl = DEFAULT_GRAPHQL_URL,
+  apiVersion = DEFAULT_API_VERSION,
+  userAgent = DEFAULT_USER_AGENT,
+  fetchImpl = globalThis.fetch,
+  sleepImpl,
+  timeoutMs = 30000,
+  maxRetries = 2,
+  retryBaseMs = 500,
+  maxRetryDelayMs = 10000,
+} = {}) {
+  if (typeof fetchImpl !== 'function') {
+    throw new GitHubError('no fetch implementation available', { code: 'no_fetch' })
+  }
+  const sleep = typeof sleepImpl === 'function'
+    ? sleepImpl
+    : (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+
+  async function attemptOnce({ method, path, query, body, url, accept, redirect }) {
+    const target = url || buildUrl(baseUrl, path, query)
+    const headers = {
+      accept,
+      'x-github-api-version': apiVersion,
+      'user-agent': userAgent,
+    }
+    if (token) headers.authorization = `Bearer ${token}`
+    if (body !== undefined) headers['content-type'] = 'application/json'
+
+    const controller = typeof AbortController === 'function' ? new AbortController() : null
+    const timer = controller && timeoutMs > 0
+      ? setTimeout(() => controller.abort(), timeoutMs)
+      : null
+
+    let response
+    try {
+      response = await fetchImpl(target, {
+        method,
+        headers,
+        body: body === undefined ? undefined : JSON.stringify(body),
+        signal: controller ? controller.signal : undefined,
+        ...(redirect ? { redirect } : {}),
+      })
+    } catch (err) {
+      if (timer) clearTimeout(timer)
+      const aborted = err && (err.name === 'AbortError' || err.code === 'ABORT_ERR')
+      throw new GitHubError(aborted ? `request timed out after ${timeoutMs}ms` : String((err && err.message) || err), {
+        code: aborted ? 'timeout' : 'network',
+      })
+    }
+    if (timer) clearTimeout(timer)
+
+    const rateLimit = rateLimitFrom(response.headers)
+    const text = typeof response.text === 'function' ? await response.text() : ''
+    let payload = null
+    if (text) {
+      try {
+        payload = JSON.parse(text)
+      } catch {
+        payload = { raw: text.slice(0, 2000) }
+      }
+    }
+    return { response, payload, rateLimit }
+  }
+
+  async function call({ method = 'GET', path, query, body, url, accept = 'application/vnd.github+json', redirect }) {
+    const upper = method.toUpperCase()
+    const retryable = SAFE_RETRY_METHODS.has(upper)
+    const attemptsAllowed = Math.max(1, Number(maxRetries) + 1)
+    let lastError = null
+
+    for (let attempt = 1; attempt <= attemptsAllowed; attempt += 1) {
+      let result
+      try {
+        result = await attemptOnce({ method: upper, path, query, body, url, accept, redirect })
+      } catch (err) {
+        lastError = err
+        if (!retryable || attempt >= attemptsAllowed) {
+          err.attempts = attempt
+          throw err
+        }
+        await sleep(retryDelayMs({ attempt, baseMs: retryBaseMs, maxDelayMs: maxRetryDelayMs }))
+        continue
+      }
+
+      const { response, payload, rateLimit } = result
+      if (response.ok) {
+        return { data: payload, status: response.status, rateLimit, attempts: attempt }
+      }
+
+      const message = (payload && (payload.message || payload.error)) || `HTTP ${response.status}`
+      const exhausted = rateLimit && rateLimit.remaining === 0
+      const error = new GitHubError(String(message), {
+        status: response.status,
+        code: exhausted ? 'rate_limited' : 'http_error',
+        rateLimit,
+        details: payload,
+        attempts: attempt,
+      })
+      lastError = error
+
+      const worthRetrying = retryable && RETRYABLE_STATUS.has(response.status)
+      if (!worthRetrying || attempt >= attemptsAllowed) throw error
+      await sleep(retryDelayMs({ headers: response.headers, attempt, baseMs: retryBaseMs, maxDelayMs: maxRetryDelayMs }))
+    }
+    throw lastError || new GitHubError('request failed', { code: 'http_error' })
+  }
+
+  return {
+    token,
+    baseUrl,
+
+    /** One REST call. `path` is relative to the API base, e.g. `/repos/o/r`. */
+    request(method, path, { query, body, accept } = {}) {
+      return call({ method: method.toUpperCase(), path, query, body, accept })
+    },
+
+    get(path, opts) {
+      return call({ method: 'GET', path, ...(opts || {}) })
+    },
+
+    post(path, body, opts) {
+      return call({ method: 'POST', path, body, ...(opts || {}) })
+    },
+
+    patch(path, body, opts) {
+      return call({ method: 'PATCH', path, body, ...(opts || {}) })
+    },
+
+    put(path, body, opts) {
+      return call({ method: 'PUT', path, body, ...(opts || {}) })
+    },
+
+    del(path, opts) {
+      return call({ method: 'DELETE', path, ...(opts || {}) })
+    },
+
+    /**
+     * Resolve an endpoint that answers with a redirect instead of JSON (the workflow
+     * logs archive is a 302 to a zip). Nothing is downloaded: the caller gets the URL.
+     */
+    async getRedirect(path, { query } = {}) {
+      const target = buildUrl(baseUrl, path, query)
+      const headers = {
+        accept: 'application/vnd.github+json',
+        'x-github-api-version': apiVersion,
+        'user-agent': userAgent,
+      }
+      if (token) headers.authorization = `Bearer ${token}`
+      let response
+      try {
+        response = await fetchImpl(target, { method: 'GET', headers, redirect: 'manual' })
+      } catch (err) {
+        throw new GitHubError(String((err && err.message) || err), { code: 'network' })
+      }
+      const location = typeof response.headers?.get === 'function' ? response.headers.get('location') : null
+      const rateLimit = rateLimitFrom(response.headers)
+      if (!response.ok && !location) {
+        throw new GitHubError(`HTTP ${response.status}`, { status: response.status, code: 'http_error', rateLimit })
+      }
+      return { status: response.status, location, rateLimit }
+    },
+
+    /** GraphQL v4. Returns `data` only; `errors` become a GitHubError. */
+    async graphql(query, variables) {
+      const { data } = await call({
+        method: 'POST',
+        url: graphqlUrl,
+        body: { query, variables: variables || {} },
+        accept: 'application/json',
+      })
+      if (data && Array.isArray(data.errors) && data.errors.length) {
+        throw new GitHubError(data.errors.map((e) => e.message).join('; '), {
+          code: 'graphql_error',
+          details: data.errors,
+        })
+      }
+      return data && data.data ? data.data : data
+    },
+
+    /**
+     * Walk a paginated REST list. `pageSize` maps to `per_page`; stops when a page
+     * is shorter than the page size or when `maxItems` is reached.
+     */
+    async paginate(path, { query = {}, pageSize = 100, maxItems = 1000 } = {}) {
+      const items = []
+      for (let page = 1; items.length < maxItems; page += 1) {
+        const { data } = await call({
+          method: 'GET',
+          path,
+          query: { ...query, per_page: pageSize, page },
+        })
+        if (!Array.isArray(data) || data.length === 0) break
+        items.push(...data)
+        if (data.length < pageSize) break
+      }
+      return items.slice(0, maxItems)
+    },
+  }
+}
+
+/** Split `owner/repo` (or `owner/repo#123`) into its parts. Returns null when malformed. */
+export function parseRepoSpec(spec) {
+  if (typeof spec !== 'string') return null
+  const match = spec.trim().match(/^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+?)(?:#(\d+))?$/)
+  if (!match) return null
+  return { owner: match[1], repo: match[2], number: match[3] ? Number(match[3]) : null }
+}
+
+/** Human-readable one-liner for a failure, used by every tool renderer. */
+export function describeError(err) {
+  if (!err) return 'unknown error'
+  if (err instanceof GitHubError) {
+    const parts = []
+    if (err.status) parts.push(`HTTP ${err.status}`)
+    if (err.code) parts.push(err.code)
+    if (err.attempts > 1) parts.push(`${err.attempts} attempts`)
+    if (err.rateLimit && err.rateLimit.remaining === 0) {
+      parts.push(`rate limit exhausted, resets at ${err.rateLimit.resetAt || 'unknown'}`)
+    }
+    return parts.length ? `${err.message} (${parts.join(', ')})` : err.message
+  }
+  return String(err.message || err)
+}