@goodandready/dsh-github-ops 0.1.0

package/lib/repo-context.js

@@ -0,0 +1,72 @@
+// Which repository a call is about.
+//
+// A tool call may name a repository, fall back to the configured default, or — inside a
+// checkout — simply mean "the repository I am in": the origin remote already says which
+// one it is, so demanding it again on every call is noise. Pure functions here; the caller
+// supplies the remote URL, which keeps this testable without a working copy.
+
+/** Parse `owner/repo`, `owner/repo#123`, `#123` or `123`. */
+export function parseRef(input) {
+  if (typeof input !== 'string') return null
+  const text = input.trim()
+  if (!text) return null
+
+  const bare = text.match(/^#?(\d+)$/)
+  if (bare) return { owner: '', repo: '', number: Number(bare[1]) }
+
+  const match = text.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 }
+}
+
+/**
+ * Extract `owner/repo` from any git remote URL a GitHub checkout uses:
+ * `git@github.com:owner/repo.git`, `ssh://git@github.com/owner/repo.git`,
+ * `https://github.com/owner/repo.git`, `https://user@host/owner/repo`.
+ * The host is not checked: a mirror remote pointing elsewhere still names a repository.
+ */
+export function parseRemoteUrl(url) {
+  if (typeof url !== 'string') return null
+  const text = url.trim()
+  if (!text) return null
+
+  const scp = text.match(/^[A-Za-z0-9_.-]+@[^:]+:([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+?)(?:\.git)?\/?$/)
+  if (scp) return { owner: scp[1], repo: scp[2], number: null, host: text.split(':')[0].split('@')[1] || '' }
+
+  try {
+    const parsed = new URL(text)
+    const parts = parsed.pathname.replace(/^\/+/, '').replace(/\.git$/, '').split('/')
+    if (parts.length >= 2 && parts[0] && parts[1]) {
+      return { owner: parts[0], repo: parts[1], number: null, host: parsed.hostname }
+    }
+  } catch {
+    // not a URL and not an scp-style remote
+  }
+  return null
+}
+
+/**
+ * Decide the repository for one call.
+ *
+ * Order: an explicit reference, then the configured default, then the origin remote of the
+ * working copy. `number` (a pull request or issue) is carried through so a caller can pass
+ * "123" and keep the repository it was already talking to.
+ */
+export function resolveRepoContext({ explicit, fallback, remoteUrl, remotes = {} } = {}) {
+  const fromExplicit = parseRef(explicit)
+  if (fromExplicit && fromExplicit.owner && fromExplicit.repo) return { ...fromExplicit, source: 'explicit' }
+
+  const fromFallback = parseRef(fallback)
+  if (fromFallback && fromFallback.owner && fromFallback.repo) {
+    return { ...fromFallback, number: fromExplicit && fromExplicit.number ? fromExplicit.number : null, source: 'settings' }
+  }
+
+  const fromRemote = parseRemoteUrl(remoteUrl) || parseRemoteUrl(remotes.origin) || parseRemoteUrl(remotes.github)
+  if (fromRemote) {
+    return { ...fromRemote, number: fromExplicit && fromExplicit.number ? fromExplicit.number : null, source: 'remote' }
+  }
+  if (fromExplicit && fromExplicit.number) {
+    throw new Error('a pull request or issue number needs a repository: pass "owner/repo#N", set a default repository in the plugin settings, or run inside a checkout with an origin remote')
+  }
+  return null
+}

package/lib/review-rules.js

@@ -0,0 +1,147 @@
+// Deterministic review rules.
+//
+// These are rules, not a model: they point a reader at what needs human attention and are
+// never presented as a verdict on correctness. Every threshold and path pattern is
+// configurable, because what deserves attention differs per repository — a `.gitea/**`
+// directory matters here and nowhere else.
+//
+// Patterns are globs: one without a `/` matches a basename at any depth (`.env` matches
+// `config/.env`), one with a `/` matches the whole repository path (`lib/**/*.js`).
+
+export const DEFAULT_RULES = {
+  /** Paths that must not change without a human reading the diff. */
+  sensitivePaths: [
+    '.env', '.env.*', '**/*.pem', '**/*.key', '**/*.p12', '**/*.pfx',
+    '.npmrc', '.credentials.yaml', '.credentials.yml',
+    'id_rsa', 'id_ed25519', 'id_ecdsa',
+    '**/secrets/**', 'AGENTS.md',
+  ],
+  sensitiveSeverity: 'critical',
+  /** Paths that need attention: infrastructure and internal documents. */
+  attentionPaths: [
+    '.github/workflows/*', '.gitea/workflows/*', 'docs/**', 'index.md', 'deploy.sh',
+  ],
+  /** Database migrations. */
+  migrationPaths: ['migrations/**', '**/migrations/**', '**/migration/**'],
+  /** A source change with no test change is worth a look. */
+  testsRequired: true,
+  sourcePatterns: ['**/*.js', '**/*.mjs', '**/*.cjs', '**/*.ts', '**/*.tsx', '**/*.py', '**/*.go', '**/*.rs', '**/*.java'],
+  testPatterns: ['test/**', 'tests/**', '**/*.test.*', '**/*_test.*', '**/test_*'],
+  /** A diff larger than this gets a note. */
+  largeDiffLines: 800,
+}
+
+function escapeLiteral(ch) {
+  return ch.replace(/[.+^${}()|[\]\\]/g, '\\$&')
+}
+
+/** Translate one glob into a regular expression. `**` crosses directories, `*` does not. */
+export function globToRegExp(pattern) {
+  const text = String(pattern || '').trim()
+  const anchored = text.includes('/')
+  const prefix = anchored ? '^' : '^(?:.*/)?'
+  let source = prefix
+  for (let index = 0; index < text.length; index += 1) {
+    const ch = text[index]
+    if (ch === '*') {
+      if (text[index + 1] === '*') {
+        // `**/` matches any depth including none
+        if (text[index + 2] === '/') {
+          source += '(?:.*/)?'
+          index += 2
+          continue
+        }
+        source += '.*'
+        index += 1
+        continue
+      }
+      source += '[^/]*'
+      continue
+    }
+    if (ch === '?') {
+      source += '[^/]'
+      continue
+    }
+    source += escapeLiteral(ch)
+  }
+  return new RegExp(`${source}$`)
+}
+
+/** Whether a repository path matches any of the globs. */
+export function matchesAnyGlob(path, patterns = []) {
+  const value = String(path || '')
+  return patterns.some((pattern) => globToRegExp(pattern).test(value))
+}
+
+/** Normalize a caller-supplied rule set over the defaults. */
+export function normalizeRules(rules) {
+  const merged = { ...DEFAULT_RULES, ...(rules && typeof rules === 'object' ? rules : {}) }
+  for (const key of ['sensitivePaths', 'attentionPaths', 'migrationPaths', 'sourcePatterns', 'testPatterns']) {
+    if (!Array.isArray(merged[key])) merged[key] = DEFAULT_RULES[key]
+  }
+  if (!['critical', 'attention', 'info'].includes(merged.sensitiveSeverity)) {
+    merged.sensitiveSeverity = DEFAULT_RULES.sensitiveSeverity
+  }
+  if (!Number.isFinite(merged.largeDiffLines) || merged.largeDiffLines <= 0) {
+    merged.largeDiffLines = DEFAULT_RULES.largeDiffLines
+  }
+  return merged
+}
+
+/** Top-level areas touched by a diff, used for a one-line summary. */
+export function areasFor(files = []) {
+  const areas = new Set()
+  for (const file of files) {
+    const parts = String(file.filename || file.path || '').split('/')
+    areas.add(parts.length > 1 ? parts[0] : (parts[0] || '').replace(/\.[^.]+$/, ''))
+  }
+  return [...areas].filter(Boolean).sort()
+}
+
+/**
+ * Findings for one pull request, deterministic and ordered: critical first, then
+ * attention, then info, and within a severity by area.
+ */
+export function analyzePull({ files = [], rules } = {}) {
+  const r = normalizeRules(rules)
+  const findings = []
+  const paths = files.map((f) => f.filename || f.path || '')
+
+  const sensitive = paths.filter((p) => matchesAnyGlob(p, r.sensitivePaths))
+  if (sensitive.length) {
+    findings.push({ level: r.sensitiveSeverity, area: 'sensitive-paths', detail: `paths that need a human eye: ${sensitive.join(', ')}` })
+  }
+
+  const attention = paths.filter((p) => matchesAnyGlob(p, r.attentionPaths))
+  if (attention.length) {
+    findings.push({ level: 'attention', area: 'attention-paths', detail: `infrastructure or internal documents changed: ${attention.join(', ')}` })
+  }
+
+  const migrations = paths.filter((p) => matchesAnyGlob(p, r.migrationPaths))
+  if (migrations.length) {
+    findings.push({ level: 'attention', area: 'migration', detail: `database migrations touched: ${migrations.join(', ')}` })
+  }
+
+  if (r.testsRequired) {
+    const sources = paths.filter((p) => matchesAnyGlob(p, r.sourcePatterns))
+    const tests = paths.filter((p) => matchesAnyGlob(p, r.testPatterns))
+    if (sources.length && !tests.length) {
+      findings.push({ level: 'attention', area: 'tests', detail: `${sources.length} source file(s) changed with no test change` })
+    }
+  }
+
+  const changed = files.reduce((sum, f) => sum + (Number(f.additions) || 0) + (Number(f.deletions) || 0), 0)
+  if (changed > r.largeDiffLines) {
+    findings.push({ level: 'attention', area: 'size', detail: `large diff: ${changed} changed lines` })
+  }
+  if (!files.length) findings.push({ level: 'info', area: 'empty', detail: 'no files in the diff' })
+
+  const rank = { critical: 0, attention: 1, info: 2 }
+  return findings.sort((a, b) => (rank[a.level] - rank[b.level]) || a.area.localeCompare(b.area))
+}
+
+/** Whether the findings and the CI rollup must block a merge. */
+export function verdictFor({ findings = [], checkRollup = 'unknown' } = {}) {
+  const blocking = findings.filter((f) => f.level === 'critical')
+  return blocking.length || checkRollup === 'failure' ? 'needs-changes' : 'success'
+}

package/lib/tools/actions.js

@@ -0,0 +1,107 @@
+// GitHub Actions: workflow runs, their jobs and steps, rerun/cancel, and the logs
+// archive URL (a redirect to a zip — the tool returns the URL instead of downloading
+// a binary into the conversation).
+
+function ensureRepo({ owner, repo }) {
+  if (!owner || !repo) {
+    throw new Error('owner and repo are required (pass "repository": "owner/repo" or set defaults in settings)')
+  }
+}
+
+export function normalizeRun(data) {
+  if (!data || typeof data !== 'object') return data
+  return {
+    id: data.id,
+    name: data.name,
+    displayTitle: data.display_title,
+    workflow: data.workflow_id,
+    event: data.event,
+    status: data.status,
+    conclusion: data.conclusion,
+    branch: data.head_branch,
+    sha: data.head_sha,
+    attempt: data.run_attempt,
+    createdAt: data.created_at,
+    updatedAt: data.updated_at,
+    url: data.html_url,
+    actor: data.actor && data.actor.login,
+  }
+}
+
+export async function listRuns(client, { owner, repo, branch, workflow, status, limit = 20 }) {
+  ensureRepo({ owner, repo })
+  const capped = Math.max(1, Math.min(Number(limit) || 20, 100))
+  const route = workflow
+    ? `/repos/${owner}/${repo}/actions/workflows/${encodeURIComponent(workflow)}/runs`
+    : `/repos/${owner}/${repo}/actions/runs`
+  const query = { per_page: capped }
+  if (branch) query.branch = branch
+  if (status) query.status = status
+  const { data } = await client.get(route, { query })
+  const runs = ((data && data.workflow_runs) || []).map(normalizeRun)
+  return { runs, count: runs.length, total: (data && data.total_count) || runs.length }
+}
+
+export async function getRun(client, { owner, repo, runId }) {
+  ensureRepo({ owner, repo })
+  if (!runId) throw new Error('runId is required')
+  const { data } = await client.get(`/repos/${owner}/${repo}/actions/runs/${runId}`)
+  return normalizeRun(data)
+}
+
+/** Jobs with their steps: what actually failed, without parsing a log archive. */
+export async function listRunJobs(client, { owner, repo, runId }) {
+  ensureRepo({ owner, repo })
+  if (!runId) throw new Error('runId is required')
+  const { data } = await client.get(`/repos/${owner}/${repo}/actions/runs/${runId}/jobs`, {
+    query: { per_page: 100 },
+  })
+  const jobs = ((data && data.jobs) || []).map((job) => ({
+    id: job.id,
+    name: job.name,
+    status: job.status,
+    conclusion: job.conclusion,
+    startedAt: job.started_at,
+    completedAt: job.completed_at,
+    url: job.html_url,
+    failedSteps: (job.steps || [])
+      .filter((s) => s.conclusion && !['success', 'skipped', 'neutral'].includes(s.conclusion))
+      .map((s) => ({ number: s.number, name: s.name, conclusion: s.conclusion })),
+  }))
+  return { jobs, count: jobs.length }
+}
+
+export async function rerunRun(client, { owner, repo, runId, failedOnly = false }) {
+  ensureRepo({ owner, repo })
+  if (!runId) throw new Error('runId is required')
+  const path = failedOnly
+    ? `/repos/${owner}/${repo}/actions/runs/${runId}/rerun-failed-jobs`
+    : `/repos/${owner}/${repo}/actions/runs/${runId}/rerun`
+  await client.post(path, {})
+  return { rerun: true, runId, failedOnly: Boolean(failedOnly) }
+}
+
+export async function cancelRun(client, { owner, repo, runId }) {
+  ensureRepo({ owner, repo })
+  if (!runId) throw new Error('runId is required')
+  await client.post(`/repos/${owner}/${repo}/actions/runs/${runId}/cancel`, {})
+  return { cancelled: true, runId }
+}
+
+/**
+ * Where the run logs live. GitHub answers the logs endpoint with a redirect to a zip,
+ * so the tool returns the URL (short-lived, needs the token to download) instead of
+ * pulling a binary into the conversation.
+ */
+export async function getRunLogsUrl(client, { owner, repo, runId }) {
+  ensureRepo({ owner, repo })
+  if (!runId) throw new Error('runId is required')
+  const { location, status } = await client.getRedirect(`/repos/${owner}/${repo}/actions/runs/${runId}/logs`)
+  return {
+    runId,
+    downloadUrl: location || '',
+    note: location
+      ? 'The archive is a zip and needs the same token to download; open it outside the conversation.'
+      : `GitHub answered HTTP ${status} without a download location — the logs may have expired.`,
+  }
+}

package/lib/tools/api.js

@@ -0,0 +1,44 @@
+// Generic `gh api` pass-through with an explicit safety boundary.
+//
+// Reads are free. Anything that changes state needs `confirm: true`, and a small
+// deny list refuses the calls that would be destructive in a way a single
+// confirmation cannot undo (deleting repositories, transferring ownership).
+
+const MUTATING = new Set(['POST', 'PATCH', 'PUT', 'DELETE'])
+
+const DENY = [
+  { method: 'DELETE', pattern: /^\/repos\/[^/]+\/[^/]+$/, reason: 'deleting a repository is refused' },
+  { method: 'POST', pattern: /^\/repos\/[^/]+\/[^/]+\/transfer$/, reason: 'transferring a repository is refused' },
+  { method: 'DELETE', pattern: /^\/orgs\/[^/]+$/, reason: 'deleting an organization is refused' },
+]
+
+export function validateApiCall({ method, path, confirm }) {
+  const m = String(method || 'GET').toUpperCase()
+  if (!path || !String(path).startsWith('/')) {
+    throw new Error('path must start with "/" and be relative to the API base, e.g. "/repos/owner/repo"')
+  }
+  for (const rule of DENY) {
+    if (rule.method === m && rule.pattern.test(path)) {
+      throw new Error(`${rule.reason} (${m} ${path})`)
+    }
+  }
+  const mutating = MUTATING.has(m)
+  if (mutating && confirm !== true) {
+    throw new Error(`refusing ${m} ${path}: pass confirm: true to run a state-changing call`)
+  }
+  return { method: m, mutating }
+}
+
+/** Run one generic API call. `body` may be an object (JSON) — it is passed as-is. */
+export async function callApi(client, { method = 'GET', path, query, body, confirm = false, graphql } = {}) {
+  if (graphql) {
+    const data = await client.graphql(graphql, body && typeof body === 'object' ? body : undefined)
+    return { graphql: true, data }
+  }
+  const { method: m, mutating } = validateApiCall({ method, path, confirm })
+  const opts = { query }
+  const { data, status, rateLimit } = m === 'GET' || m === 'DELETE'
+    ? await client.request(m, path, opts)
+    : await client.request(m, path, { ...opts, body })
+  return { method: m, mutating, status, rateLimit, data }
+}

package/lib/tools/issues.js

@@ -0,0 +1,101 @@
+// Issue operations: listing (pull requests come back marked `kind: "pr"`), reading
+// with comments, creating, commenting, closing, and the cross-repository search
+// endpoint (which has its own quota).
+
+function ensureRepo({ owner, repo }) {
+  if (!owner || !repo) {
+    throw new Error('owner and repo are required (pass "repository": "owner/repo" or set defaults in settings)')
+  }
+}
+
+export function normalizeIssue(data, { mine = '' } = {}) {
+  if (!data || typeof data !== 'object') return data
+  const isPull = Boolean(data.pull_request)
+  return {
+    number: data.number,
+    kind: isPull ? 'pr' : 'issue',
+    title: data.title,
+    state: data.state,
+    stateReason: data.state_reason || null,
+    author: data.user && data.user.login,
+    labels: Array.isArray(data.labels)
+      ? data.labels.map((l) => (typeof l === 'string' ? l : l.name))
+      : [],
+    assignees: Array.isArray(data.assignees) ? data.assignees.map((a) => a.login) : [],
+    comments: data.comments,
+    createdAt: data.created_at,
+    updatedAt: data.updated_at,
+    closedAt: data.closed_at,
+    url: data.html_url,
+    body: typeof data.body === 'string' ? data.body : '',
+    isMine: mine ? (data.user && data.user.login) === mine : undefined,
+  }
+}
+
+export async function listIssues(client, { owner, repo, state = 'open', labels, limit = 30, kind = 'all' }) {
+  ensureRepo({ owner, repo })
+  const capped = Math.max(1, Math.min(Number(limit) || 30, 100))
+  const query = { state, per_page: capped }
+  if (labels) query.labels = Array.isArray(labels) ? labels.join(',') : labels
+  const { data } = await client.get(`/repos/${owner}/${repo}/issues`, { query })
+  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')
+  return { issues, count: issues.length }
+}
+
+export async function getIssue(client, { owner, repo, number, includeComments = false }) {
+  ensureRepo({ owner, repo })
+  if (!number) throw new Error('number is required')
+  const { data } = await client.get(`/repos/${owner}/${repo}/issues/${number}`)
+  const issue = normalizeIssue(data)
+  if (!includeComments) return issue
+  const { data: comments } = await client.get(`/repos/${owner}/${repo}/issues/${number}/comments`, {
+    query: { per_page: 100 },
+  })
+  issue.commentList = Array.isArray(comments)
+    ? comments.map((c) => ({ id: c.id, author: c.user && c.user.login, createdAt: c.created_at, body: c.body }))
+    : []
+  return issue
+}
+
+export async function createIssue(client, { owner, repo, title, body, labels, assignees }) {
+  ensureRepo({ owner, repo })
+  if (!title) throw new Error('title is required')
+  const payload = { title, body: body || '' }
+  if (labels) payload.labels = Array.isArray(labels) ? labels : [labels]
+  if (assignees) payload.assignees = Array.isArray(assignees) ? assignees : [assignees]
+  const { data } = await client.post(`/repos/${owner}/${repo}/issues`, payload)
+  return normalizeIssue(data)
+}
+
+export async function commentIssue(client, { owner, repo, number, body }) {
+  ensureRepo({ owner, repo })
+  if (!number) throw new Error('number is required')
+  if (!body) throw new Error('body is required')
+  const { data } = await client.post(`/repos/${owner}/${repo}/issues/${number}/comments`, { body })
+  return { id: data && data.id, url: data && data.html_url, createdAt: data && data.created_at }
+}
+
+export async function closeIssue(client, { owner, repo, number, stateReason }) {
+  ensureRepo({ owner, repo })
+  if (!number) throw new Error('number is required')
+  const payload = { state: 'closed' }
+  if (stateReason) payload.state_reason = stateReason
+  const { data } = await client.patch(`/repos/${owner}/${repo}/issues/${number}`, payload)
+  return normalizeIssue(data)
+}
+
+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) || []
+  return {
+    total: (data && data.total_count) || items.length,
+    issues: items.map((i) => ({
+      ...normalizeIssue(i),
+      repository: i.repository_url ? String(i.repository_url).replace(/^.*\/repos\//, '') : undefined,
+    })),
+  }
+}

package/lib/tools/mirror.js

@@ -0,0 +1,163 @@
+// Sanitized mirror publication.
+//
+// A GitHub mirror is a product channel, not a copy of the history: only the npm
+// package contents plus the files a reader needs may reach it. Development sources,
+// build scripts, caches and agent instructions stay in the source forge.
+//
+// The git binary is injected as a runner (`git(args, { cwd, env })`), so the whole
+// flow is testable without a repository, and the caller decides which working copy
+// and which remote are used. Publication is always a fast-forward on top of the
+// mirror branch — rewriting mirror history is deliberately not implemented.
+
+export const DEFAULT_ALLOW = [
+  '.gitignore', 'LICENSE', 'README.md', 'README.ru.md', 'README.zh.md',
+  'CHANGELOG.md', 'package.json', 'cordis.patch.yml',
+]
+
+// `docs/**` is internal documentation and never belongs to a publication channel, so it
+// is forbidden even when a manifest happens to list it. `scripts/**` is NOT forbidden:
+// some packages legitimately ship build tooling, and the allowlist (the manifest's own
+// `files`) is what decides — the mirror publishes exactly the npm contents.
+export const DEFAULT_FORBIDDEN = [
+  'AGENTS.md', 'index.md', 'docs', 'deploy.sh', '.gitea', '.github', '.worktrees',
+  '.planning', '__pycache__', '.ruff_cache', '.venv', 'node_modules',
+]
+
+export const DEFAULT_REQUIRED = ['package.json', 'README.md']
+
+function matches(path, entries) {
+  return entries.some((entry) => {
+    const clean = String(entry).replace(/\/+$/, '')
+    if (!clean) return false
+    return path === clean || path.startsWith(`${clean}/`)
+  })
+}
+
+/** Split a tree into what may be published and what must stay behind. */
+export function sanitizePaths(paths, { allow = DEFAULT_ALLOW, forbidden = DEFAULT_FORBIDDEN } = {}) {
+  const publish = []
+  const drop = []
+  for (const path of paths) {
+    if (matches(path, forbidden) || !matches(path, allow)) drop.push(path)
+    else publish.push(path)
+  }
+  publish.sort()
+  drop.sort()
+  return { publish, drop }
+}
+
+/** Allowlist from a package manifest's `files` field, plus the reader-facing files. */
+export function allowlistFromManifest(manifest, extra = DEFAULT_ALLOW) {
+  const fromFiles = Array.isArray(manifest && manifest.files) ? manifest.files : []
+  const cleaned = fromFiles
+    .map((entry) => String(entry).replace(/\/\*\*$/, '').replace(/\/+$/, ''))
+    .filter(Boolean)
+  return [...new Set([...extra, ...cleaned])]
+}
+
+function parseLsTree(stdout) {
+  return String(stdout || '')
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean)
+}
+
+async function readManifest(git, { cwd, ref }) {
+  try {
+    const res = await git(['show', `${ref}:package.json`], { cwd })
+    if (res.code !== 0) return null
+    return JSON.parse(res.stdout)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Read-only plan: which files would be published, how many would be left behind, and
+ * whether the publication must be refused (forbidden path present, required file missing).
+ */
+export async function planMirror({ git, cwd, ref = 'origin/main', allow, forbidden, required = DEFAULT_REQUIRED }) {
+  const manifest = await readManifest(git, { cwd, ref })
+  const allowlist = allow || allowlistFromManifest(manifest)
+  const ls = await git(['ls-tree', '-r', '--name-only', ref], { cwd })
+  if (ls.code !== 0) {
+    throw new Error(`cannot read the tree of ${ref}: ${(ls.stderr || '').trim() || 'git ls-tree failed'}`)
+  }
+  const paths = parseLsTree(ls.stdout)
+  const { publish, drop } = sanitizePaths(paths, { allow: allowlist, forbidden })
+  const forbiddenEntries = forbidden || DEFAULT_FORBIDDEN
+  // A forbidden path inside the allowlist is a configuration mistake, not a file to
+  // publish: surface it instead of silently dropping it.
+  const allowlistConflicts = allowlist.filter((entry) => matches(entry, forbiddenEntries))
+  const missing = required.filter((r) => !publish.includes(r))
+  const sha = (await git(['rev-parse', ref], { cwd })).stdout.trim()
+  return {
+    ref,
+    sha,
+    publish,
+    drop,
+    total: paths.length,
+    allowlistConflicts,
+    missingRequired: missing,
+    refused: allowlistConflicts.length
+      ? `the allowlist contains forbidden paths: ${allowlistConflicts.join(', ')}`
+      : missing.length
+        ? `required product files are missing: ${missing.join(', ')}`
+        : null,
+  }
+}
+
+/**
+ * Publish the sanitized tree on top of the mirror branch (fast-forward, never a force).
+ * With dryRun the plan is returned and nothing is written or pushed.
+ */
+export async function publishMirror({
+  git, cwd, ref = 'origin/main', mirror = 'github', branch = 'main',
+  allow, forbidden, required = DEFAULT_REQUIRED, dryRun = false, message,
+}) {
+  const plan = await planMirror({ git, cwd, ref, allow, forbidden, required })
+  if (plan.refused) {
+    const err = new Error(plan.refused)
+    err.plan = plan
+    throw err
+  }
+  const source = plan.sha
+  const mirrorRef = `${mirror}/${branch}`
+  const head = await git(['rev-parse', mirrorRef], { cwd })
+  if (head.code !== 0) {
+    throw new Error(`mirror branch ${mirrorRef} is not available locally: run "git fetch ${mirror} ${branch}" first`)
+  }
+  const parent = head.stdout.trim()
+
+  if (dryRun) return { ...plan, mirror: mirrorRef, parent, commit: null, pushed: false }
+
+  const indexFile = `/tmp/dsh-github-ops-mirror-${process.pid}-${Date.now()}.index`
+  const env = { GIT_INDEX_FILE: indexFile }
+  try {
+    await git(['read-tree', '--empty'], { cwd, env })
+    for (const path of plan.publish) {
+      const blob = (await git(['rev-parse', `${ref}:${path}`], { cwd })).stdout.trim()
+      const updated = await git(['update-index', '--add', '--cacheinfo', `100644,${blob},${path}`], { cwd, env })
+      if (updated.code !== 0) throw new Error(`cannot stage ${path}: ${(updated.stderr || '').trim()}`)
+    }
+    const tree = (await git(['write-tree'], { cwd, env })).stdout.trim()
+    const commitMessage = message || `chore(publish): sanitized tree from ${source.slice(0, 8)}`
+    const commitRes = await git(['commit-tree', tree, '-p', parent, '-m', commitMessage], { cwd })
+    if (commitRes.code !== 0) throw new Error(`cannot create the mirror commit: ${(commitRes.stderr || '').trim()}`)
+    const commit = commitRes.stdout.trim()
+    const push = await git(['push', mirror, `${commit}:refs/heads/${branch}`], { cwd })
+    if (push.code !== 0) {
+      throw new Error(`push to ${mirrorRef} failed: ${(push.stderr || push.stdout || '').trim() || 'unknown error'}`)
+    }
+    return {
+      ...plan,
+      mirror: mirrorRef,
+      parent,
+      commit,
+      pushed: true,
+      correspondence: { source, mirror: commit },
+    }
+  } finally {
+    await git(['update-index', '--refresh'], { cwd, env }).catch(() => {})
+  }
+}