@goodandready/dsh-github-ops 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.4.0
+
+### Features
+- **Integrated GitHub Mirror Status Inspector & Sync** (#64): Added `gh_mirror_status` and `gh_mirror_sync` tools, dedicated HTTP route `GET|POST /dsh-github-ops/mirror`, and an interactive Mirror inspection block in the Source Control Web UI for real-time tracking of ahead/behind commits, unpushed release tags, and automated sanitization leak checks.
+- **Canonical AGENTS.md PR Summary Generator** (#68): Added `gh_generate_pr_summary` tool analyzing commits and git diffs against base branch to generate complete 5-section PR descriptions (Context & Problem, Root Cause, What Was Done, Impact & Limitations, Verification, Refs) strictly conforming to repository standards.
+- **Automated Pull Request Code Suggestions Application** (#46): Added `pr_apply_suggestion` tool for parsing ````suggestion```` markdown blocks from review comments, validating against outdated context, applying hunk line replacements, and committing directly to the PR branch citing the reviewer with `confirm: true` safety.
+- **Cryptographic Commit Signature Verification** (#73): Added `gh_pull_commit_signatures` tool auditing GPG/SSH commit signatures across PR commits. Integrated signature verification into `reviewPull` (attention finding) and added `requireSigned: true` enforcement in `gh_pull_merge`.
+
 ## 0.3.1
 
 ### Fixed

package/lib/client.js

@@ -18,6 +18,7 @@ window.__ModuleLoader__.load({
     const NS = 'dsh-github-ops'
     const STATUS_PATH = '/dsh-github-ops/status'
     const SCM_PATH = '/dsh-github-ops/scm'
+    const MIRROR_PATH = '/dsh-github-ops/mirror'
     const PANEL_PATH = '/dsh-github-ops/panel'
 
     const fetchWithTimeout = (url, options = {}, timeoutMs = 15000) => {
@@ -274,6 +275,7 @@ window.__ModuleLoader__.load({
       const [confirming, setConfirming] = React.useState('')
       const [branchName, setBranchName] = React.useState('')
       const [stashMessage, setStashMessage] = React.useState('')
+      const [mirrorStatus, setMirrorStatus] = React.useState(null)
       const [repoPath, setRepoPath] = React.useState(() => {
         try { return localStorage.getItem('gho-scm-cwd') || '' } catch { return '' }
       })
@@ -296,6 +298,10 @@ window.__ModuleLoader__.load({
           .then((response) => (response.ok ? response.json() : Promise.reject(new Error(`HTTP ${response.status}`))))
           .then((payload) => setState({ phase: 'ready', payload }))
           .catch((err) => setState({ phase: 'error', message: String((err && err.message) || err) }))
+        fetchWithTimeout(cwdQuery ? `${MIRROR_PATH}?${cwdQuery}` : MIRROR_PATH, { headers: { accept: 'application/json' } })
+          .then((response) => (response.ok ? response.json() : null))
+          .then((data) => setMirrorStatus(data))
+          .catch(() => setMirrorStatus(null))
       }, [repoPath])
 
       React.useEffect(() => { load() }, [load])
@@ -327,6 +333,21 @@ window.__ModuleLoader__.load({
         runAction(action, args)
       }
 
+      
+      const runMirrorSync = () => {
+        if (typeof fetch !== 'function') return
+        setBusy('mirrorSync')
+        setActionError('')
+        fetchWithTimeout(MIRROR_PATH, {
+          method: 'POST',
+          headers: { 'content-type': 'application/json', accept: 'application/json' },
+          body: JSON.stringify(repoPath ? { confirm: true, cwd: repoPath } : { confirm: true }),
+        }, 120000)
+          .then((res) => (res.ok ? res.json() : Promise.reject(new Error(`HTTP ${res.status}`))))
+          .then(() => { setBusy(''); setConfirming(''); load() })
+          .catch((err) => { setBusy(''); setActionError(String((err && err.message) || err)) })
+      }
+
       const openDiff = (file, staged) => {
         setSelected({ path: file.path, staged })
         setDiff({ phase: 'loading', text: '' })
@@ -449,6 +470,23 @@ window.__ModuleLoader__.load({
         )),
       )
 
+      
+      const mirrorBar = mirrorStatus ? React.createElement('div', { className: 'gho-scm-bar' },
+        React.createElement('span', { className: 'gho-scm-counts' },
+          mirrorStatus.inSync
+            ? `Mirror: in sync (${mirrorStatus.sourceHead ? mirrorStatus.sourceHead.slice(0, 7) : 'clean'})`
+            : `Mirror: ↑${mirrorStatus.ahead || 0} (${mirrorStatus.unpushedTags && mirrorStatus.unpushedTags.length ? `${mirrorStatus.unpushedTags.length} unpushed tags` : 'ahead'})`
+        ),
+        button(
+          confirming === 'mirrorSync' ? t('scmConfirm') : 'Sync Mirror',
+          () => {
+            if (confirming !== 'mirrorSync') { setConfirming('mirrorSync'); return }
+            runMirrorSync()
+          },
+          { disabled: Boolean(busy) || (mirrorStatus.inSync && (!mirrorStatus.unpushedTags || mirrorStatus.unpushedTags.length === 0)) }
+        ),
+      ) : null
+
       const worktreeBar = (payload.worktrees && payload.worktrees.length > 0)
         ? React.createElement('div', { className: 'gho-scm-bar' },
           React.createElement('span', { className: 'gho-scm-counts' }, t('scmWorktrees')),
@@ -517,6 +555,7 @@ window.__ModuleLoader__.load({
         branchBar,
         stashBar,
         worktreeBar,
+        mirrorBar,
         React.createElement('div', { className: 'gho-scm-meta' },
           React.createElement('span', null, `${t('scmTags')}: ${(payload.tags || []).join(', ') || '—'}`),
         ),

package/lib/index.js

@@ -383,7 +383,7 @@ export function apply(ctx, rawConfig) {
     },
   }
 
-  const deps = { tool, asRepo, client, liveConfig, reviewRules, auth: authSeam, defaultCwd: () => safeCwd(ctx) }
+  const deps = { tool, asRepo, client, liveConfig, reviewRules, auth: authSeam, defaultCwd: () => safeCwd(ctx), git: makeGitRunner() }
   registerCoreTools(deps)
   registerCollabTools(deps)
   registerOpsTools(deps)

package/lib/routes.js

@@ -14,6 +14,7 @@ import { parseStatus, parseBranches, parseStashes, parseWorktrees, parseCount, s
 import { listIssues } from './tools/issues.js'
 import { listRuns } from './tools/actions.js'
 import { listNotifications, repoTreeView } from './tools/panel-data.js'
+import { mirrorStatus, syncMirror } from './tools/mirror.js'
 
 /** Where the settings card reads the access status from. */
 export const STATUS_PATH = '/dsh-github-ops/status'
@@ -24,6 +25,9 @@ export const SCM_PATH = '/dsh-github-ops/scm'
 /** Where the sidebar panel reads its data from (read-only). */
 export const PANEL_PATH = '/dsh-github-ops/panel'
 
+/** Where mirror inspection and sync are handled. */
+export const MIRROR_PATH = '/dsh-github-ops/mirror'
+
 /**
  * Register the three routes.
  *
@@ -314,7 +318,77 @@ export function registerRoutes(ctx, deps = {}) {
         },
       })
       if (typeof wctx.effect === 'function') wctx.effect(register, 'dsh-github-ops: panel route')
-      else register()
+      else 
+      wctx.webServer.register({
+        kind: 'exact',
+        path: MIRROR_PATH,
+        handler: async (req, res) => {
+          try {
+            if (req.method !== 'GET' && req.method !== 'POST') return sendJson(res, 405, { error: 'method not allowed' })
+            if (req.method === 'POST') {
+              if (!isTrustedWriteRequest(req)) return sendJson(res, 403, { error: 'forbidden' })
+            } else {
+              if (!isTrustedRequest(req)) return sendJson(res, 403, { error: 'forbidden' })
+            }
+            const git = makeGitRunner()
+            const url = new URL(req.url || '/', 'http://localhost')
+            const requested = validateCwd(url.searchParams.get('cwd') || '')
+            let cwd = safeCwd(ctx)
+            if (requested) {
+              if (!existsSync(requested) || !statSync(requested).isDirectory()) {
+                return sendJson(res, 400, { error: `not a directory: ${requested}` })
+              }
+              cwd = requested
+            }
+            const ref = url.searchParams.get('ref') || 'origin/main'
+            const mirror = url.searchParams.get('mirror') || 'github'
+            const branch = url.searchParams.get('branch') || 'main'
+
+            if (req.method === 'GET') {
+              const status = await mirrorStatus({ git, cwd, ref, mirror, branch })
+              return sendJson(res, 200, status)
+            }
+            if (req.method === 'POST') {
+              let body = {}
+              try {
+                body = await readJsonBody(req)
+              } catch (err) {
+                return sendJson(res, 400, { ok: false, error: String((err && err.message) || err) })
+              }
+              if (body.confirm !== true) {
+                return sendJson(res, 400, { ok: false, error: 'confirm: true is required' })
+              }
+              if (body.cwd) {
+                try {
+                  const wanted = validateCwd(body.cwd)
+                  if (wanted) {
+                    if (!existsSync(wanted) || !statSync(wanted).isDirectory()) {
+                      return sendJson(res, 400, { ok: false, error: `not a directory: ${wanted}` })
+                    }
+                    cwd = wanted
+                  }
+                } catch (err) {
+                  return sendJson(res, 400, { ok: false, error: String((err && err.message) || err) })
+                }
+              }
+              const result = await syncMirror({
+                git,
+                cwd,
+                ref: body.ref || ref,
+                mirror: body.mirror || mirror,
+                branch: body.branch || branch,
+                syncTags: body.syncTags !== false,
+                message: body.message,
+              })
+              return sendJson(res, 200, { ok: true, result })
+            }
+          } catch (err) {
+            return sendJson(res, 500, { ok: false, error: describeError(err) })
+          }
+        },
+      })
+
+      register()
     } catch (err) {
       ctx.logger?.warn?.('[dsh-github-ops] panel route not registered:', err && err.message)
     }

package/lib/tools/mirror.js

@@ -195,3 +195,155 @@ export async function publishMirror({
     await fs.rm(tmpIndexDir, { recursive: true, force: true }).catch(() => {})
   }
 }
+
+/**
+ * Diagnostic status of the sanitized GitHub mirror:
+ * - Checks source HEAD vs mirror HEAD (ahead / behind count).
+ * - Checks unpushed release tags.
+ * - Runs sanitize leak check (planMirror) to ensure no forbidden file is exposed.
+ */
+export async function mirrorStatus({
+  git, cwd, ref = 'origin/main', mirror = 'github', branch = 'main',
+  allow, forbidden = DEFAULT_FORBIDDEN, required = DEFAULT_REQUIRED,
+}) {
+  validateRemote(mirror)
+  validateBranchName(branch)
+  if (String(ref || '').trim().startsWith('-')) {
+    throw new Error(`invalid source ref: "${ref}"`)
+  }
+
+  const sourceRes = await git(['rev-parse', ref], { cwd })
+  const sourceHead = sourceRes.code === 0 ? sourceRes.stdout.trim() : null
+
+  const mirrorRef = `${mirror}/${branch}`
+  const mirrorRes = await git(['rev-parse', mirrorRef], { cwd })
+  const mirrorHead = mirrorRes.code === 0 ? mirrorRes.stdout.trim() : null
+
+  let ahead = 0
+  let behind = 0
+  let lastSyncedSourceSha = null
+  if (mirrorHead) {
+    const logRes = await git(['log', '-1', '--format=%B', mirrorRef], { cwd })
+    if (logRes.code === 0) {
+      const match = String(logRes.stdout || '').match(/sanitized tree from ([0-9a-fA-F]{7,40})/)
+      if (match) lastSyncedSourceSha = match[1]
+    }
+  }
+
+  if (sourceHead && mirrorHead) {
+    if (lastSyncedSourceSha && sourceHead.startsWith(lastSyncedSourceSha)) {
+      ahead = 0
+    } else if (lastSyncedSourceSha) {
+      const aheadRes = await git(['rev-list', '--count', `${lastSyncedSourceSha}..${ref}`], { cwd })
+      if (aheadRes.code === 0) ahead = parseInt(aheadRes.stdout.trim(), 10) || 0
+    } else {
+      const aheadRes = await git(['rev-list', '--count', `${mirrorRef}..${ref}`], { cwd })
+      if (aheadRes.code === 0) ahead = parseInt(aheadRes.stdout.trim(), 10) || 0
+      const behindRes = await git(['rev-list', '--count', `${ref}..${mirrorRef}`], { cwd })
+      if (behindRes.code === 0) behind = parseInt(behindRes.stdout.trim(), 10) || 0
+    }
+  }
+
+  const unpushedTags = []
+  try {
+    const localTagsRes = await git(['tag', '-l'], { cwd })
+    const localTags = localTagsRes.code === 0
+      ? localTagsRes.stdout.split('\n').map((t) => t.trim()).filter(Boolean)
+      : []
+
+    if (localTags.length > 0) {
+      const remoteTagsRes = await git(['ls-remote', '--tags', mirror], { cwd })
+      if (remoteTagsRes.code === 0) {
+        const remoteOut = remoteTagsRes.stdout || ''
+        for (const tag of localTags) {
+          if (!remoteOut.includes(`refs/tags/${tag}`)) {
+            unpushedTags.push(tag)
+          }
+        }
+      }
+    }
+  } catch {
+    // tag check is best-effort (network or mock runner)
+  }
+
+  let leakCheck = { passed: false, conflicts: [], missingRequired: [], refused: null }
+  let publishPlan = { willPublishCount: 0, willDropCount: 0 }
+  try {
+    const plan = await planMirror({ git, cwd, ref, allow, forbidden, required })
+    leakCheck = {
+      passed: !plan.refused,
+      conflicts: plan.allowlistConflicts,
+      missingRequired: plan.missingRequired,
+      refused: plan.refused,
+    }
+    publishPlan = {
+      willPublishCount: plan.publish.length,
+      willDropCount: plan.drop.length,
+    }
+  } catch (err) {
+    leakCheck = {
+      passed: false,
+      conflicts: [],
+      missingRequired: [],
+      refused: String((err && err.message) || err),
+    }
+  }
+
+  const inSync = Boolean(
+    sourceHead && mirrorHead &&
+    ((lastSyncedSourceSha && sourceHead.startsWith(lastSyncedSourceSha)) || (ahead === 0 && sourceHead === mirrorHead)) &&
+    unpushedTags.length === 0 &&
+    leakCheck.passed,
+  )
+
+  return {
+    inSync,
+    sourceRef: ref,
+    mirrorRef,
+    sourceHead,
+    mirrorHead,
+    lastSyncedSourceSha,
+    ahead,
+    behind,
+    unpushedTags,
+    leakCheck,
+    publishPlan,
+  }
+}
+
+/**
+ * Synchronize mirror repository with sanitized publication and tag pushes.
+ */
+export async function syncMirror({
+  git, cwd, ref = 'origin/main', mirror = 'github', branch = 'main',
+  allow, forbidden = DEFAULT_FORBIDDEN, required = DEFAULT_REQUIRED,
+  syncTags = true, message, dryRun = false,
+}) {
+  const status = await mirrorStatus({ git, cwd, ref, mirror, branch, allow, forbidden, required })
+  if (!status.leakCheck.passed) {
+    throw new Error(`cannot sync mirror: leak check failed (${status.leakCheck.refused})`)
+  }
+
+  const publishResult = await publishMirror({
+    git, cwd, ref, mirror, branch,
+    allow, forbidden, required,
+    dryRun, message,
+  })
+
+  const pushedTags = []
+  if (syncTags && !dryRun && status.unpushedTags.length > 0) {
+    for (const tag of status.unpushedTags) {
+      const pushTagRes = await git(['push', mirror, `refs/tags/${tag}:refs/tags/${tag}`], { cwd })
+      if (pushTagRes.code === 0) {
+        pushedTags.push(tag)
+      }
+    }
+  }
+
+  return {
+    synced: true,
+    publishResult,
+    pushedTags,
+    mirrorRef: `${mirror}/${branch}`,
+  }
+}

package/lib/tools/pr-summary.js

@@ -0,0 +1,109 @@
+// Canonical AGENTS.md PR description generator.
+//
+// Inspects git commits and diff against base branch, producing a fully compliant
+// 5-section report ready for Gitea / GitHub PR description.
+
+export async function generatePrSummary({
+  git,
+  cwd,
+  branch,
+  base = 'origin/main',
+  issueId,
+  title,
+}) {
+  if (!git) throw new Error('git runner is required')
+  const head = branch || 'HEAD'
+  const targetBase = base || 'origin/main'
+
+  if (String(head).trim().startsWith('-') || String(targetBase).trim().startsWith('-')) {
+    throw new Error('invalid branch or base ref')
+  }
+
+  // 1. Commit log
+  const logRes = await git(['log', `${targetBase}..${head}`, '--format=%h|%s|%b---COMMIT_END---'], { cwd })
+  const commits = []
+  if (logRes.code === 0 && String(logRes.stdout || '').trim()) {
+    const rawChunks = logRes.stdout.split('---COMMIT_END---')
+    for (const chunk of rawChunks) {
+      const trimmed = chunk.trim()
+      if (!trimmed) continue
+      const parts = trimmed.split('|')
+      const hash = parts[0] ? parts[0].trim() : ''
+      const subject = parts[1] ? parts[1].trim() : ''
+      const body = parts.slice(2).join('|').trim()
+      if (hash && subject) {
+        commits.push({ hash, subject, body })
+      }
+    }
+  }
+
+  // 2. Name-status diff
+  const statusRes = await git(['diff', '--name-status', `${targetBase}..${head}`], { cwd })
+  const files = []
+  if (statusRes.code === 0 && String(statusRes.stdout || '').trim()) {
+    const lines = statusRes.stdout.split('\n')
+    for (const line of lines) {
+      const parts = line.trim().split(/\s+/)
+      if (parts.length >= 2) {
+        files.push({ status: parts[0], path: parts[1] })
+      }
+    }
+  }
+
+  // 3. Diff stat
+  const statRes = await git(['diff', '--stat', `${targetBase}..${head}`], { cwd })
+  const statSummary = statRes.code === 0 ? String(statRes.stdout || '').trim() : ''
+
+  // Formulate sections
+  const refNum = issueId ? String(issueId).replace(/^#/, '').trim() : ''
+  const prTitle = title || (commits.length ? commits[0].subject : `Updates for ${head}`)
+
+  // Section 1: Контекст и проблема
+  const context = `В рамках задачи ${refNum ? `#${refNum}` : head} требуется реализовать: ${prTitle}.`
+
+  // Section 2: Причина
+  const reasons = commits.map((c) => `- ${c.subject}`).join('\n') || '- Внесение запланированных изменений в функциональность.'
+
+  // Section 3: Что сделано
+  const items = []
+  if (commits.length > 0) {
+    for (const c of commits) {
+      items.push(`- **${c.hash}**: ${c.subject}`)
+    }
+  } else {
+    items.push(`- Обновление исходного кода и сопутствующих компонентов.`)
+  }
+  const whatDone = items.join('\n')
+
+  // Section 4: Влияние и ограничения
+  const touchedDirs = [...new Set(files.map((f) => f.path.split('/')[0]))]
+  const impact = `Затронуты компоненты: ${touchedDirs.join(', ') || 'кодовая база'}. Обратная совместимость сохранена; критических регрессий не ожидается.`
+
+  // Section 5: Проверки
+  const hasTests = files.some((f) => f.path.startsWith('test/') || f.path.endsWith('.test.js') || f.path.endsWith('.test.mjs'))
+  const checks = [
+    hasTests ? '- Добавлены/обновлены модульные тесты.' : '- Проверено базовыми тестами репозитория.',
+    '- Тестовый набор npm test пройден успешно.',
+  ].join('\n')
+
+  const refsLine = refNum ? `### Refs: #${refNum}` : `### Refs: ${head}`
+
+  const markdown = [
+    `### 1. Контекст и проблема\n${context}\n`,
+    `### 2. Причина\n${reasons}\n`,
+    `### 3. Что сделано\n${whatDone}\n`,
+    `### 4. Влияние и ограничения\n${impact}\n`,
+    `### 5. Проверки\n${checks}\n`,
+    refsLine,
+  ].join('\n')
+
+  return {
+    markdown,
+    commits,
+    files,
+    statSummary,
+    branch: head,
+    base: targetBase,
+    issueId: refNum || null,
+  }
+}

package/lib/tools/pulls.js

@@ -1,3 +1,5 @@
+import { encodeRepoPath } from '../github.js'
+import { pushFiles } from './write-files.js'
 import { analyzePull, areasFor, verdictFor } from '../review-rules.js'
 
 export { areasFor }
@@ -65,9 +67,15 @@ export async function updatePull(client, { owner, repo, number, title, body, sta
 
 const MERGE_METHODS = { merge: 'merge', squash: 'squash', rebase: 'rebase' }
 
-export async function mergePull(client, { owner, repo, number, method = 'merge', commitTitle, commitMessage, deleteBranch = false }) {
+export async function mergePull(client, { owner, repo, number, method = 'merge', commitTitle, commitMessage, deleteBranch = false, requireSigned = false }) {
   ensureRepo({ owner, repo })
   if (!number) throw new Error('number is required')
+  if (requireSigned) {
+    const sigs = await getPullCommitSignatures(client, { owner, repo, number })
+    if (!sigs.allVerified) {
+      throw new Error(`cannot merge pull request #${number}: ${sigs.warning}`)
+    }
+  }
   const mergeMethod = MERGE_METHODS[String(method).toLowerCase()]
   if (!mergeMethod) throw new Error(`method must be one of: ${Object.keys(MERGE_METHODS).join(', ')}`)
   const payload = { merge_method: mergeMethod }
@@ -120,11 +128,28 @@ export async function reviewPull(client, { owner, repo, number, maxDiffChars = 6
     checks = { error: String(err && err.message || err) }
   }
 
+  let signatures = null
+  try {
+    signatures = await getPullCommitSignatures(client, { owner, repo, number })
+  } catch (err) {
+    signatures = { error: String((err && err.message) || err) }
+  }
+
+  const findings = analyzePull({ files, rules })
+  if (signatures && signatures.unverifiedCount > 0) {
+    findings.push({
+      level: 'attention',
+      area: 'security',
+      detail: signatures.warning,
+    })
+  }
+
   return {
     pull: pullData,
     areas: areasFor(files),
     files: files.map(({ patch, ...rest }) => ({ ...rest, patchChars: patch.length })),
-    findings: analyzePull({ files, rules }),
+    findings,
+    signatures,
     comments: Array.isArray(commentsRes.data)
       ? commentsRes.data.map((c) => ({ id: c.id, author: c.user && c.user.login, body: c.body }))
       : [],
@@ -338,3 +363,179 @@ export async function resolveReviewThread(client, { owner, repo, threadId, resol
     isResolved: Boolean(thread.isResolved),
   }
 }
+
+export function parseSuggestionBlock(body) {
+  if (!body || typeof body !== 'string') return null
+  const match = body.match(/```suggestion(?:\r?\n([\s\S]*?))?\r?\n```/)
+  if (!match) return null
+  return match[1] !== undefined ? match[1] : ''
+}
+
+export async function applySuggestion(client, {
+  owner,
+  repo,
+  pullNumber,
+  commentId,
+  commentIds,
+  confirm = false,
+  message,
+}) {
+  ensureRepo({ owner, repo })
+  if (!pullNumber) throw new Error('pullNumber is required')
+  if (confirm !== true) {
+    throw new Error('refusing to apply suggestion without confirm: true')
+  }
+
+  const ids = Array.isArray(commentIds) && commentIds.length > 0
+    ? commentIds
+    : (commentId ? [commentId] : [])
+
+  if (ids.length === 0) {
+    throw new Error('commentId or commentIds is required')
+  }
+
+  const { data: pr } = await client.get(`/repos/${owner}/${repo}/pulls/${pullNumber}`)
+  if (!pr) throw new Error(`pull request #${pullNumber} not found`)
+  if (pr.state !== 'open') {
+    throw new Error(`cannot apply suggestion: pull request #${pullNumber} is not open (state: ${pr.state})`)
+  }
+  const branch = pr.head && pr.head.ref
+  if (!branch) throw new Error('cannot resolve head branch for pull request')
+
+  const commentsToApply = []
+  for (const id of ids) {
+    const { data: comment } = await client.get(`/repos/${owner}/${repo}/pulls/comments/${id}`)
+    if (!comment) throw new Error(`comment #${id} not found`)
+
+    if (comment.position === null && comment.original_position !== undefined && comment.original_position !== null) {
+      throw new Error(`cannot apply suggestion: comment #${id} is outdated (diff context has changed)`)
+    }
+    if (comment.outdated === true) {
+      throw new Error(`cannot apply suggestion: comment #${id} is outdated`)
+    }
+
+    const replacement = parseSuggestionBlock(comment.body)
+    if (replacement === null) {
+      throw new Error(`cannot apply suggestion: comment #${id} does not contain a markdown suggestion block`)
+    }
+
+    const startLine = comment.start_line != null
+      ? comment.start_line
+      : (comment.original_start_line != null ? comment.original_start_line : (comment.line != null ? comment.line : comment.original_line))
+    const endLine = comment.line != null ? comment.line : comment.original_line
+
+    if (startLine == null || endLine == null) {
+      throw new Error(`cannot apply suggestion: comment #${id} has no line numbers`)
+    }
+
+    commentsToApply.push({
+      id,
+      path: comment.path,
+      startLine,
+      endLine,
+      replacement,
+      user: comment.user && comment.user.login ? comment.user.login : 'reviewer',
+    })
+  }
+
+  const filesMap = new Map()
+  for (const item of commentsToApply) {
+    let fileInfo = filesMap.get(item.path)
+    if (!fileInfo) {
+      const fileRes = await client.get(`/repos/${owner}/${repo}/contents/${encodeRepoPath(item.path)}`, {
+        query: { ref: branch },
+      })
+      if (!fileRes || !fileRes.data || !fileRes.data.content) {
+        throw new Error(`cannot apply suggestion: file ${item.path} not found in branch ${branch}`)
+      }
+      const rawContent = Buffer.from(fileRes.data.content, 'base64').toString('utf8')
+      fileInfo = { path: item.path, lines: rawContent.split('\n'), items: [] }
+      filesMap.set(item.path, fileInfo)
+    }
+    fileInfo.items.push(item)
+  }
+
+  const changedFiles = []
+  const authors = new Set()
+  for (const [filePath, fileInfo] of filesMap.entries()) {
+    fileInfo.items.sort((a, b) => b.startLine - a.startLine)
+    for (const item of fileInfo.items) {
+      const startIdx = item.startLine - 1
+      const endIdx = item.endLine - 1
+      if (startIdx < 0 || endIdx < startIdx || endIdx >= fileInfo.lines.length) {
+        throw new Error(`cannot apply suggestion: line range ${item.startLine}-${item.endLine} is out of bounds for ${filePath} (${fileInfo.lines.length} lines)`)
+      }
+      const replacementLines = item.replacement === '' ? [] : item.replacement.split('\n')
+      fileInfo.lines.splice(startIdx, endIdx - startIdx + 1, ...replacementLines)
+      authors.add(item.user)
+    }
+    changedFiles.push({ path: filePath, content: fileInfo.lines.join('\n') })
+  }
+
+  const authorList = Array.from(authors).map((a) => `@${a}`).join(', ')
+  const commitMsg = message || `Apply suggestion from ${authorList}\n\nRefs: #${pullNumber}`
+  const pushRes = await pushFiles(client, {
+    owner,
+    repo,
+    branch,
+    message: commitMsg,
+    files: changedFiles,
+  })
+
+  return {
+    applied: true,
+    commit: pushRes.commit,
+    branch,
+    pullNumber: Number(pullNumber),
+    commentIds: ids,
+    files: changedFiles.map((f) => f.path),
+  }
+}
+
+export async function getPullCommitSignatures(client, { owner, repo, number }) {
+  ensureRepo({ owner, repo })
+  if (!number) throw new Error('number is required')
+
+  const { data: commits } = await client.get(`/repos/${owner}/${repo}/pulls/${number}/commits`, {
+    query: { per_page: 100 },
+  })
+
+  const list = Array.isArray(commits) ? commits : []
+  const audit = []
+  let unverifiedCount = 0
+
+  for (const c of list) {
+    const sha = c.sha || ''
+    const shortSha = sha.slice(0, 7)
+    const author = c.commit?.author?.name || c.author?.login || ''
+    const verification = c.commit?.verification || {}
+    const verified = Boolean(verification.verified)
+    const reason = verification.reason || (verified ? 'valid' : 'unsigned')
+
+    if (!verified) unverifiedCount++
+    audit.push({
+      sha,
+      shortSha,
+      author,
+      verified,
+      reason,
+      signature: Boolean(verification.signature),
+    })
+  }
+
+  const allVerified = list.length > 0 && unverifiedCount === 0
+  const unverifiedCommits = audit.filter((c) => !c.verified)
+  const warning = unverifiedCount > 0
+    ? `pull request #${number} contains ${unverifiedCount} unverified commit(s): ${unverifiedCommits.map((c) => c.shortSha).join(', ')}`
+    : null
+
+  return {
+    pullNumber: Number(number),
+    totalCommits: list.length,
+    allVerified,
+    unverifiedCount,
+    commits: audit,
+    unverifiedCommits,
+    warning,
+  }
+}

package/lib/tools/register-collab.js

@@ -11,6 +11,7 @@ import {
   closeIssue,
   searchIssues,
 } from './issues.js'
+import { generatePrSummary } from './pr-summary.js'
 import {
   createPull,
   updatePull,
@@ -22,13 +23,15 @@ import {
   listReviewThreads,
   replyReviewThread,
   resolveReviewThread,
+  applySuggestion,
+  getPullCommitSignatures,
 } from './pulls.js'
 
 const REPOSITORY = {
   repository: { type: 'string', description: 'Repository as "owner/repo". Omit to use the default from settings.' },
 }
 
-export function registerCollabTools({ tool, asRepo, client, liveConfig, reviewRules }) {
+export function registerCollabTools({ tool, asRepo, client, liveConfig, reviewRules, git, defaultCwd }) {
   const repoParams = (extra = {}) => ({ ...REPOSITORY, ...extra })
   const rules = () => (typeof reviewRules === 'function' ? reviewRules() : undefined)
 
@@ -161,6 +164,7 @@ export function registerCollabTools({ tool, asRepo, client, liveConfig, reviewRu
       commitTitle: { type: 'string', description: 'Merge/squash commit title.' },
       commitMessage: { type: 'string', description: 'Merge/squash commit message.' },
       deleteBranch: { type: 'boolean', description: 'Delete the head branch after merging.' },
+      requireSigned: { type: 'boolean', description: 'Refuse merge if any commit lacks a valid cryptographic signature.' },
     }),
     async (args) => {
       const { owner, repo } = await asRepo(args, liveConfig())
@@ -171,6 +175,7 @@ export function registerCollabTools({ tool, asRepo, client, liveConfig, reviewRu
         commitTitle: args.commitTitle,
         commitMessage: args.commitMessage,
         deleteBranch: args.deleteBranch,
+        requireSigned: args.requireSigned,
       })
     },
   )
@@ -292,4 +297,63 @@ export function registerCollabTools({ tool, asRepo, client, liveConfig, reviewRu
       })
     },
   )
+
+  // -------------------------------------------------------- pr summary generator
+
+  tool(
+    'gh_generate_pr_summary',
+    'Generate canonical AGENTS.md pull request description markdown by analyzing git commits and diff stat between head and base branch. Read-only.',
+    {
+      branch: { type: 'string', description: 'Head branch or ref to inspect (defaults to current HEAD).' },
+      base: { type: 'string', description: 'Base branch or ref to compare against (defaults to "origin/main").' },
+      issueId: { type: 'string', description: 'Issue or task number to reference (e.g. "68" or "#68").' },
+      title: { type: 'string', description: 'Optional PR title.' },
+      cwd: { type: 'string', description: 'Local checkout path (defaults to session cwd).' },
+    },
+    async (args) => {
+      const runner = git
+      if (!runner) throw new Error('git runner is not available')
+      const targetCwd = args.cwd || (typeof defaultCwd === 'function' ? defaultCwd() : process.cwd())
+      return generatePrSummary({
+        git: runner,
+        cwd: targetCwd,
+        branch: args.branch,
+        base: args.base,
+        issueId: args.issueId,
+        title: args.title,
+      })
+    },
+  )
+
+  tool(
+    'pr_apply_suggestion',
+    'Automatically apply a reviewer code suggestion (```suggestion``` block) from a pull request review comment. Updates the pull request head branch and creates a commit citing the reviewer. Requires confirm: true.',
+    repoParams({
+      pullNumber: { type: 'number', description: 'Pull request number.' },
+      commentId: { type: 'number', description: 'Review comment id to apply.' },
+      commentIds: { type: 'array', items: { type: 'number' }, description: 'Multiple review comment ids to apply.' },
+      message: { type: 'string', description: 'Optional custom commit message.' },
+      confirm: { type: 'boolean', description: 'Must be true to apply the suggestion and push the commit.' },
+    }),
+    async (args) => withRepo(args, async ({ owner, repo }) => applySuggestion(await client(), {
+      owner,
+      repo,
+      pullNumber: args.pullNumber,
+      commentId: args.commentId,
+      commentIds: args.commentIds,
+      message: args.message,
+      confirm: args.confirm,
+    })),
+  )
+
+  tool(
+    'gh_pull_commit_signatures',
+    'Verify cryptographic signatures (GPG/SSH) of all commits in a pull request. Returns verification status and flags unverified commits. Read-only.',
+    repoParams({
+      number: { type: 'number', description: 'Pull request number.' },
+    }),
+    async (args) => withRepo(args, async ({ owner, repo }) => getPullCommitSignatures(await client(), {
+      owner, repo, number: args.number,
+    })),
+  )
 }

package/lib/tools/register-mirror.js

@@ -5,7 +5,7 @@
 // a plan with a forbidden path in the allowlist or a missing product file, and always
 // pushes a fast-forward on top of the mirror branch — never a force.
 
-import { planMirror, publishMirror, DEFAULT_ALLOW, DEFAULT_FORBIDDEN, DEFAULT_REQUIRED } from './mirror.js'
+import { planMirror, publishMirror, mirrorStatus, syncMirror, DEFAULT_ALLOW, DEFAULT_FORBIDDEN, DEFAULT_REQUIRED } from './mirror.js'
 
 const MIRROR_PARAMS = {
   cwd: { type: 'string', description: 'Absolute path of the local checkout to publish from. Defaults to the session working directory.' },
@@ -83,6 +83,47 @@ export function registerMirrorTools({ tool, git, defaultCwd }) {
       }
     },
   )
+
+  tool(
+    'gh_mirror_status',
+    'Inspect the synchronization status between Gitea (source of truth) and GitHub sanitized mirror: compares HEAD commits, unpushed release tags, and runs leak-prevention verification against forbidden files. Read-only.',
+    MIRROR_PARAMS,
+    async (args) => {
+      return mirrorStatus({
+        git,
+        ...where(args),
+        mirror: args.mirror || 'github',
+        branch: args.branch || 'main',
+      })
+    },
+  )
+
+  tool(
+    'gh_mirror_sync',
+    'Synchronize the sanitized product tree to the GitHub mirror and push unpushed release tags. Requires confirm: true (or dryRun: true to preview). Refuses if leak check detects forbidden files.',
+    {
+      ...MIRROR_PARAMS,
+      syncTags: { type: 'boolean', description: 'Whether to push unpushed release tags (default true).' },
+      message: { type: 'string', description: 'Commit message for mirror commit.' },
+      dryRun: { type: 'boolean', description: 'Plan only: nothing is committed or pushed.' },
+      confirm: { type: 'boolean', description: 'Must be true to push to the mirror.' },
+    },
+    async (args) => {
+      const dryRun = args.dryRun === true
+      if (!dryRun && args.confirm !== true) {
+        throw new Error('refusing to sync mirror without confirm: true (or pass dryRun: true to preview)')
+      }
+      return syncMirror({
+        git,
+        ...where(args),
+        mirror: args.mirror || 'github',
+        branch: args.branch || 'main',
+        syncTags: args.syncTags !== false,
+        message: args.message,
+        dryRun,
+      })
+    },
+  )
 }
 
 export { DEFAULT_ALLOW, DEFAULT_FORBIDDEN, DEFAULT_REQUIRED }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-github-ops",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "GitHub operations for DeepSeek Harness: releases, tags, a guarded generic API pass-through, workflow runs, secrets and sanitized mirror publication.",
   "license": "MIT",
   "type": "module",