@goodandready/dsh-github-ops 0.1.2 → 0.2.1

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 }

package/lib/tools/issues.js

@@ -41,6 +41,7 @@ export async function listIssues(client, { owner, repo, state = 'open', labels,
   let issues = Array.isArray(data) ? data.map((i) => normalizeIssue(i)) : []
   if (kind === 'pr') issues = issues.filter((i) => i.kind === 'pr')
   if (kind === 'issue') issues = issues.filter((i) => i.kind === 'issue')
+  issues = issues.slice(0, capped)
   return { issues, count: issues.length }
 }
 
@@ -90,7 +91,7 @@ export async function searchIssues(client, { query, limit = 20 }) {
   if (!query) throw new Error('query is required')
   const capped = Math.max(1, Math.min(Number(limit) || 20, 100))
   const { data } = await client.get('/search/issues', { query: { q: query, per_page: capped } })
-  const items = (data && data.items) || []
+  const items = ((data && data.items) || []).slice(0, capped)
   return {
     total: (data && data.total_count) || items.length,
     issues: items.map((i) => ({

package/lib/tools/panel-data.js

@@ -0,0 +1,45 @@
+// Data shapes the sidebar panel needs.
+//
+// The panel shows a repository the way a person browses it: a tree, a file, the issue and pull
+// request lists, the recent runs and the attention inbox. These are thin compositions over the
+// existing readers, kept here so the route stays a switch instead of a second implementation.
+
+export { listNotifications } from './insights.js'
+
+function ensureRepo({ owner, repo }) {
+  if (!owner || !repo) throw new Error('owner and repo are required')
+}
+
+/**
+ * One level of a repository tree, ready for a file browser: directories first, then files,
+ * each with the path the panel asks for next.
+ */
+export async function repoTreeView(client, { owner, repo, ref, path = '', limit = 200 } = {}) {
+  ensureRepo({ owner, repo })
+  const capped = Math.max(1, Math.min(Number(limit) || 200, 1000))
+  const target = ref || 'HEAD'
+  const suffix = path ? `/${String(path).replace(/^\/+|\/+$/g, '')}` : ''
+  const { data } = await client.get(`/repos/${owner}/${repo}/git/trees/${encodeURIComponent(target)}${suffix}`, {
+    query: { per_page: capped },
+  })
+  const entries = (data && Array.isArray(data.tree) ? data.tree : [])
+    .slice(0, capped)
+    .map((entry) => ({
+      name: String(entry.path || '').split('/').pop(),
+      path: entry.path,
+      type: entry.type,
+      size: entry.size,
+      sha: entry.sha,
+    }))
+    .sort((a, b) => {
+      if (a.type !== b.type) return a.type === 'tree' ? -1 : 1
+      return String(a.name).localeCompare(String(b.name))
+    })
+  return {
+    ref: target,
+    path: path || '',
+    truncated: Boolean(data && data.truncated),
+    count: entries.length,
+    entries,
+  }
+}

package/lib/tools/register-insights.js

@@ -0,0 +1,126 @@
+// Registrations for the composed reports: the answers a person asks for in one call.
+
+import {
+  repoReport,
+  weeklyDigest,
+  listNotifications,
+  repoHealth,
+  compareRepos,
+  trendingRepos,
+  userRepos,
+  listContributors,
+  listCommits,
+} from './insights.js'
+
+const REPOSITORY = {
+  repository: { type: 'string', description: 'Repository as "owner/repo". Omit to use the default from settings or the checkout.' },
+}
+
+export function registerInsightTools({ tool, asRepo, client, liveConfig }) {
+  const repoParams = (extra = {}) => ({ ...REPOSITORY, ...extra })
+
+  tool(
+    'gh_repo_report',
+    'One call that says what a repository is: overview, latest release, open issues, recent commits and top contributors. Read-only; the parts share the client cache, so it stays cheap.',
+    repoParams({
+      commits: { type: 'number', description: 'How many recent commits to include (default 5).' },
+      issues: { type: 'number', description: 'How many open issues to include (default 5).' },
+      contributors: { type: 'number', description: 'How many contributors to include (default 5).' },
+    }),
+    async (args) => {
+      const { owner, repo } = await asRepo(args, liveConfig())
+      return repoReport(await client(), {
+        owner, repo, commits: args.commits, issues: args.issues, contributors: args.contributors,
+      })
+    },
+  )
+
+  tool(
+    'gh_weekly_digest',
+    'What happened in a repository inside a look-back window: releases, new issues, merged or closed pull requests and commits. Read-only.',
+    repoParams({
+      days: { type: 'number', description: 'Look-back window in days (default 7).' },
+      limit: { type: 'number', description: 'How many items per list (default 10).' },
+    }),
+    async (args) => {
+      const { owner, repo } = await asRepo(args, liveConfig())
+      return weeklyDigest(await client(), { owner, repo, days: args.days, limit: args.limit })
+    },
+  )
+
+  tool(
+    'gh_notifications',
+    'The attention queue for the authenticated account: mentions, review requests, assignments and watched threads, grouped by reason. Needs access with notification read permission. Read-only.',
+    {
+      all: { type: 'boolean', description: 'Include already-read notifications.' },
+      participating: { type: 'boolean', description: 'Only threads the account participates in.' },
+      limit: { type: 'number', description: 'How many notifications to return (default 20).' },
+    },
+    async (args) => listNotifications(await client(), { all: args.all, participating: args.participating, limit: args.limit }),
+  )
+
+  tool(
+    'gh_repo_health',
+    'A transparent maintenance score for a repository: five weighted dimensions with the evidence for each, the risks found and concrete next actions. It is a heuristic over public signals, not a security audit. Read-only.',
+    repoParams(),
+    async (args) => {
+      const { owner, repo } = await asRepo(args, liveConfig())
+      return repoHealth(await client(), { owner, repo })
+    },
+  )
+
+  tool(
+    'gh_compare',
+    'Two repositories side by side with numeric deltas for stars, forks and open issues. Read-only.',
+    {
+      first: { type: 'string', description: 'First repository as "owner/repo".' },
+      second: { type: 'string', description: 'Second repository as "owner/repo".' },
+    },
+    async (args) => compareRepos(await client(), { first: args.first, second: args.second }),
+  )
+
+  tool(
+    'gh_trending',
+    'Recently created repositories sorted by stars, optionally filtered by language. Uses the search quota. Read-only.',
+    {
+      language: { type: 'string', description: 'Language filter, e.g. "TypeScript".' },
+      since: { type: 'string', description: 'Created after this date (YYYY-MM-DD); defaults to 30 days ago.' },
+      limit: { type: 'number', description: 'How many repositories (default 10).' },
+    },
+    async (args) => trendingRepos(await client(), { language: args.language, since: args.since, limit: args.limit }),
+  )
+
+  tool(
+    'gh_contributors',
+    'Top contributors of a repository by commit count. Read-only.',
+    repoParams({ limit: { type: 'number', description: 'How many contributors (default 10).' } }),
+    async (args) => {
+      const { owner, repo } = await asRepo(args, liveConfig())
+      return listContributors(await client(), { owner, repo, limit: args.limit })
+    },
+  )
+
+  tool(
+    'gh_user_repos',
+    "A user's or organization's repositories sorted by stars. Read-only.",
+    {
+      login: { type: 'string', description: 'GitHub login of the user or organization.' },
+      limit: { type: 'number', description: 'How many repositories (default 10).' },
+    },
+    async (args) => userRepos(await client(), { login: args.login, limit: args.limit }),
+  )
+
+  tool(
+    'gh_commits',
+    'Recent commits of a repository, optionally since a date and on a specific branch. Read-only.',
+    repoParams({
+      branch: { type: 'string', description: 'Branch or ref; defaults to the default branch.' },
+      since: { type: 'string', description: 'Only commits after this ISO timestamp.' },
+      limit: { type: 'number', description: 'How many commits (default 10).' },
+    }),
+    async (args) => {
+      const { owner, repo } = await asRepo(args, liveConfig())
+      return listCommits(await client(), { owner, repo, branch: args.branch, since: args.since, limit: args.limit })
+    },
+  )
+}

package/lib/tools/register-write.js

@@ -0,0 +1,245 @@
+// Content and account tools: writing files without a checkout, and signing in without a
+// terminal.
+//
+// Nothing here stores a value in a tool result: the sign-in writes its file and reports only
+// the account and the scope. Destructive calls (deleting a file or a branch, signing out,
+// forcing a ref) need `confirm: true`.
+
+import {
+  repoTree,
+  pushFiles,
+  uploadProject,
+  deleteFile,
+  deleteBranch,
+} from './write-files.js'
+import {
+  startDeviceFlow,
+  pollDeviceFlow,
+  writeAccessFile,
+  readAccessFile,
+  clearAccessFile,
+  accessFilePath,
+  DEFAULT_CLIENT_ID,
+  DEFAULT_SCOPE,
+} from '../auth-device.js'
+
+const REPOSITORY = {
+  repository: { type: 'string', description: 'Repository as "owner/repo". Omit to use the default from settings or the checkout.' },
+}
+
+const FILES_PARAM = {
+  type: 'array',
+  description: 'Files to publish: [{ path, content, base64? }]. `path` is relative to the repository root.',
+  items: { type: 'object', additionalProperties: true },
+}
+
+export function registerWriteTools({ tool, asRepo, client, liveConfig, auth }) {
+  const repoParams = (extra = {}) => ({ ...REPOSITORY, ...extra })
+  const authConfig = () => auth.config()
+
+  tool(
+    'gh_repo_tree',
+    'List the file tree of a repository at a ref, recursively by default. Read-only, and much cheaper than walking directories one by one.',
+    repoParams({
+      ref: { type: 'string', description: 'Branch, tag or commit; defaults to HEAD.' },
+      path: { type: 'string', description: 'Only the subtree under this path.' },
+      recursive: { type: 'boolean', description: 'Walk the whole tree (default true).' },
+      limit: { type: 'number', description: 'How many entries (default 500).' },
+    }),
+    async (args) => {
+      const { owner, repo } = await asRepo(args, liveConfig())
+      return repoTree(await client(), {
+        owner, repo, ref: args.ref, path: args.path, recursive: args.recursive !== false, limit: args.limit,
+      })
+    },
+  )
+
+  tool(
+    'gh_push_files',
+    'Commit one or more files to a branch without a local checkout: blobs, a tree on top of the branch tree, a commit, then the ref moves. Creates the branch when it does not exist. Read the branch first if you need to preserve its current content.',
+    repoParams({
+      branch: { type: 'string', description: 'Branch to write to.' },
+      message: { type: 'string', description: 'Commit message.' },
+      files: FILES_PARAM,
+      base: { type: 'string', description: 'Branch to start from when the target branch does not exist.' },
+      force: { type: 'boolean', description: 'Move the ref backwards. Requires confirm: true and is never implied.' },
+      confirm: { type: 'boolean', description: 'Required when force is true.' },
+    }),
+    async (args) => {
+      if (args.force === true && args.confirm !== true) {
+        throw new Error('refusing to force a ref without confirm: true')
+      }
+      const { owner, repo } = await asRepo(args, liveConfig())
+      return pushFiles(await client(), {
+        owner, repo, branch: args.branch, message: args.message, files: args.files, base: args.base, force: args.force === true,
+      })
+    },
+  )
+
+  tool(
+    'gh_upload_project',
+    'Create a repository, publish files into it and optionally open a pull request — the whole "upload this project" flow in one call. An existing repository is used as is instead of failing.',
+    {
+      repository: { type: 'string', description: 'Target repository as "owner/repo"; the owner is used for the default account.' },
+      org: { type: 'string', description: 'Organization to create the repository in.' },
+      description: { type: 'string', description: 'Repository description.' },
+      private: { type: 'boolean', description: 'Private repository (default true).' },
+      files: FILES_PARAM,
+      branch: { type: 'string', description: 'Branch to publish into; defaults to the default branch.' },
+      base: { type: 'string', description: 'Base branch for the pull request.' },
+      title: { type: 'string', description: 'Commit message and pull request title.' },
+      body: { type: 'string', description: 'Pull request body.' },
+      createPullRequest: { type: 'boolean', description: 'Open a pull request after publishing.' },
+    },
+    async (args) => {
+      const cfg = liveConfig()
+      let owner = args.org || ''
+      let repo = args.repository || ''
+      if (repo.includes('/')) {
+        const [ownerPart, repoPart] = repo.split('/')
+        owner = args.org || ownerPart
+        repo = repoPart
+      } else if (!owner) {
+        const resolved = await asRepo({ repository: cfg.defaultRepository }, cfg).catch(() => null)
+        owner = resolved ? resolved.owner : ''
+      }
+      return uploadProject(await client(), {
+        owner,
+        repo,
+        org: args.org,
+        description: args.description,
+        private: args.private !== false,
+        files: args.files,
+        branch: args.branch,
+        base: args.base,
+        title: args.title,
+        body: args.body,
+        createPullRequest: args.createPullRequest === true,
+      })
+    },
+  )
+
+  tool(
+    'gh_delete_file',
+    'Delete one file from a branch. Requires confirm: true.',
+    repoParams({
+      path: { type: 'string', description: 'File path inside the repository.' },
+      message: { type: 'string', description: 'Commit message.' },
+      branch: { type: 'string', description: 'Branch; defaults to the default branch.' },
+      confirm: { type: 'boolean', description: 'Must be true to delete.' },
+    }),
+    async (args) => {
+      if (args.confirm !== true) throw new Error('refusing to delete a file without confirm: true')
+      const { owner, repo } = await asRepo(args, liveConfig())
+      return deleteFile(await client(), { owner, repo, path: args.path, message: args.message, branch: args.branch })
+    },
+  )
+
+  tool(
+    'gh_delete_branch',
+    'Delete a branch. Requires confirm: true.',
+    repoParams({
+      branch: { type: 'string', description: 'Branch to delete.' },
+      confirm: { type: 'boolean', description: 'Must be true to delete.' },
+    }),
+    async (args) => {
+      if (args.confirm !== true) throw new Error('refusing to delete a branch without confirm: true')
+      const { owner, repo } = await asRepo(args, liveConfig())
+      return deleteBranch(await client(), { owner, repo, branch: args.branch })
+    },
+  )
+
+  // ------------------------------------------------------------------ account
+
+  tool(
+    'gh_auth_login',
+    'Start a GitHub sign-in without a terminal: returns a short code and a URL for the human. Approve it in the browser, then call gh_auth_finish to collect the access. Stored in this plugin\'s own file with mode 0600; the value is never returned.',
+    {
+      scope: { type: 'string', description: `OAuth scope to request (default "${DEFAULT_SCOPE}").` },
+      clientId: { type: 'string', description: `OAuth app id (default: the public gh CLI application ${DEFAULT_CLIENT_ID}).` },
+    },
+    async (args) => {
+      const cfg = authConfig()
+      const flow = await startDeviceFlow({
+        clientId: args.clientId || cfg.clientId || DEFAULT_CLIENT_ID,
+        scope: args.scope || cfg.scope || DEFAULT_SCOPE,
+        fetchImpl: globalThis.fetch,
+      })
+      auth.remember(flow)
+      return {
+        userCode: flow.userCode,
+        verificationUri: flow.verificationUri,
+        expiresInSeconds: flow.expiresInSeconds,
+        pollIntervalSeconds: flow.intervalSeconds,
+        next: 'ask the human to approve, then call gh_auth_finish',
+      }
+    },
+  )
+
+  tool(
+    'gh_auth_finish',
+    'Collect a started sign-in. Polls while the human is approving, then stores the access in this plugin\'s file and reports the sign-in name only.',
+    {
+      maxWaitMs: { type: 'number', description: 'How long to keep polling (default 120000).' },
+    },
+    async (args) => {
+      const pending = auth.pending()
+      if (!pending) throw new Error('no sign-in is in progress: call gh_auth_login first')
+      const cfg = authConfig()
+      const outcome = await pollDeviceFlow({
+        clientId: cfg.clientId || DEFAULT_CLIENT_ID,
+        clientSecret: auth.secret(),
+        deviceCode: pending.deviceCode,
+        intervalSeconds: pending.intervalSeconds,
+        maxWaitMs: args.maxWaitMs,
+        fetchImpl: globalThis.fetch,
+      })
+      if (outcome.status !== 'authorized') return { status: outcome.status, message: outcome.message }
+      const saved = await writeAccessFile(auth.path(), {
+        token: outcome.token,
+        scope: outcome.scope || pending.scope,
+        source: 'device-flow',
+      })
+      auth.forget()
+      return { status: 'authorized', stored: saved.path, login: saved.login || '', scope: saved.scope }
+    },
+  )
+
+  tool(
+    'gh_auth_status',
+    'Report where the current access comes from and whether it works: the source (credential, environment, this plugin\'s sign-in, gh CLI), the account, and the remaining API rate limit. The value itself is never shown. Read-only.',
+    {},
+    async () => {
+      const cfg = liveConfig()
+      const access = await auth.resolve()
+      if (!access.value) return { configured: false, guidance: access.guidance }
+      const github = await client()
+      const { data, rateLimit } = await github.get('/user')
+      return {
+        configured: true,
+        source: access.source,
+        login: data && data.login,
+        name: data && data.name,
+        scopes: github.lastScopes ? github.lastScopes() : undefined,
+        rateLimit: rateLimit || undefined,
+        accessFile: auth.path(),
+      }
+    },
+  )
+
+  tool(
+    'gh_auth_logout',
+    'Forget the sign-in stored by this plugin (gh_auth_login). Other sources (a DSH credential, the environment, the gh CLI) are untouched. Requires confirm: true.',
+    { confirm: { type: 'boolean', description: 'Must be true to sign out.' } },
+    async (args) => {
+      if (args.confirm !== true) throw new Error('refusing to sign out without confirm: true')
+      const file = auth.path()
+      const stored = await readAccessFile(file)
+      const result = await clearAccessFile(file)
+      return { ...result, had: Boolean(stored), note: result.removed ? 'the stored sign-in is gone' : 'nothing was stored' }
+    },
+  )
+
+  // keep the imports honest for callers that compose their own flows
+  return { accessFilePath, readAccessFile }
+}