@goodandready/dsh-github-ops 0.1.2 → 0.2.0

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 }
+}

package/lib/tools/releases.js

@@ -36,7 +36,9 @@ export async function listReleases(client, { owner, repo, limit = RELEASE_LIST_L
   const { data, rateLimit } = await client.get(`/repos/${owner}/${repo}/releases`, {
     query: { per_page: capped },
   })
-  const releases = Array.isArray(data) ? data.map(normalizeRelease) : []
+  // GitHub honours per_page for this endpoint, but a proxy or a cached page may not:
+  // the caller asked for `capped` items, so the list is cut here as well.
+  const releases = (Array.isArray(data) ? data.map(normalizeRelease) : []).slice(0, capped)
   return { releases, count: releases.length, rateLimit }
 }
 

package/lib/tools/repos.js

@@ -67,7 +67,7 @@ export async function searchRepos(client, { query, limit = 20 }) {
   const { data } = await client.get('/search/repositories', {
     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,
     repos: items.map(normalizeRepo),

package/lib/tools/write-files.js

@@ -0,0 +1,207 @@
+// Writing files without a local checkout.
+//
+// A commit is built the way git builds it: blobs, a tree on top of the branch's tree, a
+// commit, then the ref moves. Nothing here needs a working copy, so the agent can create a
+// repository, publish files and open a pull request from a conversation alone.
+//
+// `force` is never implied: moving a ref backwards is an explicit request, and the tool layer
+// asks for `confirm: true` on top of it.
+
+function ensureRepo({ owner, repo }) {
+  if (!owner || !repo) throw new Error('owner and repo are required (pass "owner/repo")')
+}
+
+/** Files of a tree, one level or recursive, with the truncation flag GitHub returns. */
+export async function repoTree(client, { owner, repo, ref, path, recursive = true, limit = 500 } = {}) {
+  ensureRepo({ owner, repo })
+  const capped = Math.max(1, Math.min(Number(limit) || 500, 2000))
+  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: recursive ? { recursive: '1' } : undefined,
+  })
+  const entries = (data && Array.isArray(data.tree) ? data.tree : []).slice(0, capped).map((entry) => ({
+    path: entry.path,
+    type: entry.type,
+    size: entry.size,
+    sha: entry.sha,
+  }))
+  return {
+    ref: target,
+    path: path || '',
+    truncated: Boolean(data && data.truncated),
+    count: entries.length,
+    entries,
+  }
+}
+
+async function refSha(client, owner, repo, branch) {
+  try {
+    const { data } = await client.get(`/repos/${owner}/${repo}/git/ref/heads/${encodeURIComponent(branch)}`)
+    return data && data.object && data.object.sha ? data.object.sha : ''
+  } catch (err) {
+    if (err && err.status === 404) return ''
+    throw err
+  }
+}
+
+/** Encode one file the way the API wants it. */
+function fileBlob(file) {
+  const path = String(file.path || '').replace(/^\/+/, '')
+  if (!path) throw new Error('every file needs a path')
+  const base64 = file.base64 === true || file.encoding === 'base64'
+  return { path, content: String(file.content ?? ''), encoding: base64 ? 'base64' : 'utf-8' }
+}
+
+/**
+ * Commit one or more files to a branch, creating the branch when it does not exist.
+ *
+ * @returns {{commit: string, branch: string, files: number, created: boolean}}
+ */
+export async function pushFiles(client, { owner, repo, branch, message, files = [], base, force = false } = {}) {
+  ensureRepo({ owner, repo })
+  if (!branch) throw new Error('branch is required')
+  if (!message) throw new Error('message is required')
+  if (!Array.isArray(files) || files.length === 0) throw new Error('files must be a non-empty array')
+
+  const head = await refSha(client, owner, repo, branch)
+  let parent = head
+  let parentTree = ''
+  const created = !head
+  if (!head) {
+    const from = base || (await repoDefaultBranch(client, { owner, repo }))
+    parent = await refSha(client, owner, repo, from)
+    if (!parent) throw new Error(`cannot start branch "${branch}": "${from}" has no commit yet`)
+  }
+  const { data: commitData } = await client.get(`/repos/${owner}/${repo}/git/commits/${parent}`)
+  parentTree = commitData && commitData.tree ? commitData.tree.sha : ''
+
+  const tree = []
+  for (const file of files) {
+    const { path, content, encoding } = fileBlob(file)
+    const { data: blob } = await client.post(`/repos/${owner}/${repo}/git/blobs`, { content, encoding })
+    if (!blob || !blob.sha) throw new Error(`cannot create a blob for ${path}`)
+    tree.push({ path, mode: '100644', type: 'blob', sha: blob.sha })
+  }
+
+  const treePayload = { tree }
+  if (parentTree) treePayload.base_tree = parentTree
+  const { data: newTree } = await client.post(`/repos/${owner}/${repo}/git/trees`, treePayload)
+  if (!newTree || !newTree.sha) throw new Error('cannot create the tree')
+
+  const { data: newCommit } = await client.post(`/repos/${owner}/${repo}/git/commits`, {
+    message,
+    tree: newTree.sha,
+    parents: [parent],
+  })
+  if (!newCommit || !newCommit.sha) throw new Error('cannot create the commit')
+
+  if (head) {
+    await client.patch(`/repos/${owner}/${repo}/git/refs/heads/${encodeURIComponent(branch)}`, {
+      sha: newCommit.sha,
+      force: Boolean(force),
+    })
+  } else {
+    await client.post(`/repos/${owner}/${repo}/git/refs`, {
+      ref: `refs/heads/${branch}`,
+      sha: newCommit.sha,
+    })
+  }
+  return { commit: newCommit.sha, branch, files: tree.length, created }
+}
+
+/** Default branch of a repository (a fresh repository may not answer immediately). */
+export async function repoDefaultBranch(client, { owner, repo, attempts = 5, sleep = defaultSleep } = {}) {
+  ensureRepo({ owner, repo })
+  let lastError = null
+  for (let attempt = 1; attempt <= Math.max(1, attempts); attempt += 1) {
+    try {
+      const { data } = await client.get(`/repos/${owner}/${repo}`)
+      if (data && data.default_branch) return data.default_branch
+    } catch (err) {
+      lastError = err
+    }
+    if (attempt < attempts) await sleep(1000)
+  }
+  if (lastError) throw lastError
+  throw new Error(`cannot read the default branch of ${owner}/${repo} yet`)
+}
+
+function defaultSleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+/**
+ * Create a repository, publish files into it and optionally open a pull request — the
+ * "upload this project" flow in one call.
+ */
+export async function uploadProject(client, {
+  owner, repo, description, private: isPrivate = true, files = [], branch, base, title, body,
+  createPullRequest = false, org, attempts = 5, sleep = defaultSleep,
+} = {}) {
+  if (!repo) throw new Error('repository name is required')
+  if (!Array.isArray(files) || files.length === 0) throw new Error('files must be a non-empty array')
+
+  let repository = null
+  try {
+    repository = await client.post(org ? `/orgs/${org}/repos` : '/user/repos', {
+      name: repo,
+      description: description || '',
+      private: Boolean(isPrivate),
+      auto_init: true,
+    })
+  } catch (err) {
+    if (!err || err.status !== 422) throw err
+    // already exists: continue with it, the caller asked to publish into it
+    const full = org ? `${org}/${repo}` : `${owner}/${repo}`
+    const [foundOwner, foundRepo] = full.split('/')
+    const { data } = await client.get(`/repos/${foundOwner}/${foundRepo}`)
+    repository = data
+  }
+  const fullName = (repository && repository.full_name) || `${org || owner}/${repo}`
+  const [repoOwner, repoName] = fullName.split('/')
+  const target = branch || (await repoDefaultBranch(client, { owner: repoOwner, repo: repoName, attempts, sleep }))
+
+  const pushed = await pushFiles(client, {
+    owner: repoOwner, repo: repoName, branch: target, message: title || 'Initial commit', files, base,
+  })
+
+  let pullRequest = null
+  if (createPullRequest) {
+    const baseBranch = base || (await repoDefaultBranch(client, { owner: repoOwner, repo: repoName, attempts, sleep }))
+    if (baseBranch !== target) {
+      const { data } = await client.post(`/repos/${repoOwner}/${repoName}/pulls`, {
+        title: title || 'Initial commit',
+        head: target,
+        base: baseBranch,
+        body: body || '',
+      })
+      pullRequest = data ? { number: data.number, url: data.html_url } : null
+    }
+  }
+  return { repository: fullName, branch: target, commit: pushed.commit, files: pushed.files, pullRequest }
+}
+
+/** Delete one file, resolving its blob sha first (the contents API requires it). */
+export async function deleteFile(client, { owner, repo, path, message, branch } = {}) {
+  ensureRepo({ owner, repo })
+  if (!path) throw new Error('path is required')
+  if (!message) throw new Error('message is required')
+  const { data: current } = await client.get(`/repos/${owner}/${repo}/contents/${String(path).replace(/^\/+/, '')}`, {
+    query: branch ? { ref: branch } : undefined,
+  })
+  const sha = current && current.sha
+  if (!sha) throw new Error(`cannot resolve ${path}`)
+  const { data } = await client.del(`/repos/${owner}/${repo}/contents/${String(path).replace(/^\/+/, '')}`, {
+    body: { message, sha, ...(branch ? { branch } : {}) },
+  })
+  return { deleted: true, path, commit: data && data.commit ? data.commit.sha : null }
+}
+
+/** Delete a branch. */
+export async function deleteBranch(client, { owner, repo, branch } = {}) {
+  ensureRepo({ owner, repo })
+  if (!branch) throw new Error('branch is required')
+  await client.del(`/repos/${owner}/${repo}/git/refs/heads/${encodeURIComponent(branch)}`)
+  return { deleted: true, branch }
+}