@goodandready/dsh-github-ops 0.2.11 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.3.0
+
+### Features
+- **Token Capability Diagnostics & Scopes Audit** (#72): Introduced `gh_token_audit` tool (`auditTokenScopes`) providing automated token permission checks (classic vs fine-grained) and early capability warnings for missing repository, workflow, packages, or org administration scopes. Added `scopeWarnings` in `/status` payload.
+- **Selective CI Failure Log Inspector** (#67): Added `gh_run_failure_inspector` tool with regex-based failure step isolation, automatic ANSI sequence stripping, secret token masking, and highlighted failure summaries without needing to download full workflow artifact archives.
+- **Interactive Stash Management & Diff Preview** (#70): Added stash diff preview endpoint (`GET /scm?stash=stash@{N}`) and full lifecycle actions (`stashShow`, `stashApply`, `stashPop`, `stashDrop` with confirmation safety). Updated Source Control UI with quick diff viewer and stash operation buttons.
+
+## 0.2.12
+
+### Security
+- **Release Preflight Test Confirmation & CWD Containment** (#80): Required `confirm: true` to execute `npm test` during `gh_release_preflight` audit, and routed audit directory through `validateCwd` to prevent arbitrary directory test execution.
+- **SCM Symlink Traversal Protection** (#96): Enhanced `validateCwd` with `realpathSync` resolution to prevent directory traversal and symlink escape into protected system directories (`/etc`, `/proc`, `/sys`, etc.).
+- **Socket Remote Address Verification & IPv6 Support** (#97): Enforced socket `remoteAddress` validation in `isTrustedRequest` and `isTrustedWriteRequest` to block untrusted external clients from spoofing matching `Host` and `Origin` headers. Fixed unbracketed IPv6 address parsing in `isTrustedHost`.
+
+### Refactored
+- **Mirror Git Index Directory Isolation** (#91): Created mirror temporary git-index inside an isolated `fs.mkdtemp` (0700) directory with guaranteed cleanup in `finally`.
+- **Dead Parameter Aliases Removed** (#92): Removed undeclared schema fallback aliases (`tagName`, `targetCommitish`, `previousTagName`, `configurationFilePath`, `pullNumber`) from tool registrations.
+- **Unused Parameters & Re-exports Cleanup** (#95): Removed unused `repoHint` in slash commands, dead `liveConfig()` call in `gh_auth_status`, and unused re-export of `runReleasePreflight`.
+
 ## 0.2.11
 
 ### Security

package/lib/client.js

@@ -101,6 +101,7 @@ window.__ModuleLoader__.load({
       scmDelete: 'Delete',
       scmSwitch: 'Switch',
       scmStashSave: 'Save stash',
+      scmStashView: 'Diff',
       scmStashApply: 'Apply',
       scmStashPop: 'Pop',
       scmStashDrop: 'Drop',
@@ -203,6 +204,7 @@ window.__ModuleLoader__.load({
       scmDelete: '删除',
       scmSwitch: '切换',
       scmStashSave: '保存 stash',
+      scmStashView: '差异',
       scmStashApply: '应用',
       scmStashPop: '弹出',
       scmStashDrop: '删除',
@@ -328,7 +330,17 @@ window.__ModuleLoader__.load({
       const openDiff = (file, staged) => {
         setSelected({ path: file.path, staged })
         setDiff({ phase: 'loading', text: '' })
-        const query = `?file=${encodeURIComponent(file.path)}${staged ? '&staged=1' : ''}`
+        const query = `?file=${encodeURIComponent(file.path)}${staged ? '&staged=1' : ''}${cwdQuery ? `&${cwdQuery}` : ''}`
+        fetchWithTimeout(SCM_PATH + query, { headers: { accept: 'application/json' } })
+          .then((response) => (response.ok ? response.json() : Promise.reject(new Error(`HTTP ${response.status}`))))
+          .then((payload) => setDiff({ phase: 'ready', text: payload.diff || '' }))
+          .catch((err) => setDiff({ phase: 'error', text: String((err && err.message) || err) }))
+      }
+
+      const openStashDiff = (stashRef) => {
+        setSelected({ path: stashRef, isStash: true })
+        setDiff({ phase: 'loading', text: '' })
+        const query = `?stash=${encodeURIComponent(stashRef)}${cwdQuery ? `&${cwdQuery}` : ''}`
         fetchWithTimeout(SCM_PATH + query, { headers: { accept: 'application/json' } })
           .then((response) => (response.ok ? response.json() : Promise.reject(new Error(`HTTP ${response.status}`))))
           .then((payload) => setDiff({ phase: 'ready', text: payload.diff || '' }))
@@ -460,6 +472,7 @@ window.__ModuleLoader__.load({
           onChange: (event) => setStashMessage(event.target.value),
         }),
         button(t('scmStashSave'), () => runAction('stashPush', { message: stashMessage }), { disabled: Boolean(busy) }),
+        (payload.stashes || []).slice(0, 4).map((entry) => button(`${t('scmStashView')} ${entry.ref}`, () => openStashDiff(entry.ref))),
         (payload.stashes || []).slice(0, 4).map((entry) => button(`${t('scmStashApply')} ${entry.ref}`, () => runAction('stashApply', { ref: entry.ref }))),
         (payload.stashes || []).slice(0, 4).map((entry) => button(`${t('scmStashPop')} ${entry.ref}`, () => runAction('stashPop', { ref: entry.ref }))),
         (payload.stashes || []).slice(0, 4).map((entry) => button(
@@ -1128,7 +1141,7 @@ window.__ModuleLoader__.load({
     exports.SCM_ACTIONS = [
       'stage', 'unstage', 'discard', 'commit', 'push', 'sync',
       'branchCreate', 'branchCheckout', 'branchDelete',
-      'stashPush', 'stashApply', 'stashPop', 'stashDrop', 'continue', 'abort',
+      'stashPush', 'stashApply', 'stashPop', 'stashDrop', 'stashShow', 'continue', 'abort',
     ]
     exports.PullRequestBar = PullRequestBar
     exports.GitHubPanel = GitHubPanel

package/lib/commands.js

@@ -72,7 +72,7 @@ export function buildGhInstruction({ topic, tool, args } = {}) {
  * Register the commands. Every handler returns an instruction for the model; none of them
  * touches GitHub.
  */
-export function registerCommands(commands, { readGitState, repoHint } = {}) {
+export function registerCommands(commands, { readGitState } = {}) {
   const disposers = []
   const context = async () => {
     try {
@@ -92,7 +92,7 @@ export function registerCommands(commands, { readGitState, repoHint } = {}) {
       const git = await context()
       return {
         kind: 'success',
-        text: buildPrInstruction({ title: rest.join(' '), branch: git.branch, base: git.base || 'main', repo: git.repo || (typeof repoHint === 'function' ? repoHint() : undefined), remoteUrl: git.remoteUrl }),
+        text: buildPrInstruction({ title: rest.join(' '), branch: git.branch, base: git.base || 'main', repo: git.repo, remoteUrl: git.remoteUrl }),
       }
     },
   }))
@@ -107,7 +107,7 @@ export function registerCommands(commands, { readGitState, repoHint } = {}) {
       const git = await context()
       return {
         kind: 'success',
-        text: buildReviewInstruction({ number, branch: git.branch, repo: git.repo || (typeof repoHint === 'function' ? repoHint() : undefined) }),
+        text: buildReviewInstruction({ number, branch: git.branch, repo: git.repo }),
       }
     },
   }))
@@ -119,7 +119,7 @@ export function registerCommands(commands, { readGitState, repoHint } = {}) {
     handler: async (invocation) => {
       const [sub, ...rest] = String(invocation.rawInput || '').trim().split(/\s+/)
       const git = await context()
-      const repo = git.repo || (typeof repoHint === 'function' ? repoHint() : undefined)
+      const repo = git.repo
       if (sub === 'new') return { kind: 'success', text: buildIssueInstruction({ sub, title: rest.join(' '), repo }) }
       if (sub === 'show' && /^\d+$/.test(rest[0] || '')) return { kind: 'success', text: buildIssueInstruction({ sub, number: Number(rest[0]), repo }) }
       if (!sub || sub === 'list') return { kind: 'success', text: buildIssueInstruction({ sub: 'list', repo }) }

package/lib/routes.js

@@ -9,7 +9,7 @@ import { existsSync, statSync } from 'node:fs'
 import { join as joinPath } from 'node:path'
 
 import { statusPayload, isTrustedRequest, isTrustedWriteRequest, sendJson } from './status.js'
-import { buildAction, validateCwd } from './scm-write.js'
+import { buildAction, validateCwd, validateStashRef } from './scm-write.js'
 import { parseStatus, parseBranches, parseStashes, parseWorktrees, parseCount, scmPayload, mergeStateFrom } from './scm.js'
 import { listIssues } from './tools/issues.js'
 import { listRuns } from './tools/actions.js'
@@ -168,6 +168,19 @@ export function registerRoutes(ctx, deps = {}) {
             return sendJson(res, 200, { file, staged, diff: String(text || '').slice(0, 200000) })
           }
 
+          const stash = url.searchParams.get('stash') || ''
+          if (stash) {
+            let stashRef
+            try {
+              stashRef = validateStashRef(stash)
+            } catch (err) {
+              return sendJson(res, 400, { error: String((err && err.message) || err) })
+            }
+            const diff = await git(['stash', 'show', '-p', stashRef], { cwd })
+            const text = diff.code === 0 ? diff.stdout : diff.stderr
+            return sendJson(res, 200, { stash: stashRef, diff: String(text || '').slice(0, 200000) })
+          }
+
           const branchAnswer = await git(['rev-parse', '--abbrev-ref', 'HEAD'], { cwd })
           if (branchAnswer.code !== 0) {
             return sendJson(res, 200, scmPayload({ cwd, error: 'not a git repository (or no commits yet)' }))

package/lib/scm-write.js

@@ -1,3 +1,4 @@
+import { realpathSync } from 'node:fs'
 // Writing to a working copy, from the Source Control tab.
 //
 // Every action is a list of argv arrays — never a shell string. The route runs them one by one
@@ -35,9 +36,10 @@ export function validateMessage(message) {
   return trimmed
 }
 
-/** Stash references are `stash@{N}`; nothing else is accepted. */
+/** Stash references are `stash@{N}` or integer indices; nothing else is accepted. */
 export function validateStashRef(ref) {
-  const value = String(ref == null ? '' : ref).trim()
+  let value = String(ref == null ? '' : ref).trim()
+  if (/^\d{1,3}$/.test(value)) value = `stash@{${value}}`
   if (!/^stash@\{\d{1,3}\}$/.test(value)) throw new Error(`refusing an unsafe stash reference: "${value.slice(0, 40)}"`)
   return value
 }
@@ -91,11 +93,17 @@ export function buildAction(action, args = {}) {
       return result(name, steps, destructive, 'save the working copy to a stash')
     }
     case 'stashApply':
+    case 'stash_apply':
       return result(name, [['stash', 'apply', validateStashRef(args.ref)]], destructive, `apply ${args.ref}`)
     case 'stashPop':
+    case 'stash_pop':
       return result(name, [['stash', 'pop', validateStashRef(args.ref)]], destructive, `apply and drop ${args.ref}`)
     case 'stashDrop':
+    case 'stash_drop':
       return result(name, [['stash', 'drop', validateStashRef(args.ref)]], destructive, `drop ${args.ref}`)
+    case 'stashShow':
+    case 'stash_show':
+      return result(name, [['stash', 'show', '-p', validateStashRef(args.ref)]], destructive, `show diff of ${args.ref}`)
     case 'continue': {
       const verb = String(args.verb || '').trim()
       if (!CONTINUE_VERBS.includes(verb)) throw new Error(`refusing to continue an unknown operation: "${verb.slice(0, 20)}"`)
@@ -135,7 +143,7 @@ export function buildAction(action, args = {}) {
   }
 }
 
-const DESTRUCTIVE = new Set(['discard', 'branchDelete', 'stashDrop', 'abort', 'worktreeRemove'])
+const DESTRUCTIVE = new Set(['discard', 'branchDelete', 'stashDrop', 'stash_drop', 'abort', 'worktreeRemove'])
 
 function result(action, steps, destructive, summary) {
   return { action, steps, mutating: true, destructive, needsConfirm: destructive, summary }
@@ -145,7 +153,7 @@ function result(action, steps, destructive, summary) {
 export const ACTIONS = Object.freeze([
   'stage', 'unstage', 'discard', 'commit', 'push', 'sync',
   'branchCreate', 'branchCheckout', 'branchDelete',
-  'stashPush', 'stashApply', 'stashPop', 'stashDrop',
+  'stashPush', 'stashApply', 'stashPop', 'stashDrop', 'stashShow',
   'worktreeAdd', 'worktreeRemove',
   'continue', 'abort',
 ])
@@ -172,5 +180,16 @@ export function validateCwd(path) {
       throw new Error(`access to system directory "${root}" is not allowed`)
     }
   }
+  let realPath = value
+  try {
+    realPath = realpathSync(value)
+  } catch {
+    realPath = value
+  }
+  for (const root of DISALLOWED_ROOTS) {
+    if (realPath === root || realPath.startsWith(root + '/')) {
+      throw new Error(`access to system directory "${root}" is not allowed`)
+    }
+  }
   return value
 }

package/lib/status.js

@@ -1,3 +1,4 @@
+import { auditTokenScopes } from './token-audit.js'
 // What the settings card is allowed to know.
 //
 // The status of the access — where it comes from, which account, what the rate limit looks
@@ -14,8 +15,11 @@ function isTrustedHost(host) {
   if (hostname.startsWith('[')) {
     const end = hostname.indexOf(']')
     if (end > 0) hostname = hostname.slice(1, end)
-  } else {
-    hostname = hostname.split(':')[0]
+  } else if (hostname.includes(':')) {
+    const colons = hostname.split(':').length - 1
+    if (colons === 1) {
+      hostname = hostname.split(':')[0]
+    }
   }
   hostname = hostname.toLowerCase()
   if (!hostname) return false
@@ -43,6 +47,9 @@ export function isTrustedRequest(req) {
   const cleanIp = address.replace(/^::ffff:/, '')
   const loopback = cleanIp === '127.0.0.1' || cleanIp === '::1' || cleanIp.startsWith('127.')
 
+  // If socket remoteAddress is present, it MUST be a trusted local/private IP (never an untrusted remote IP)
+  if (cleanIp && !isTrustedHost(cleanIp)) return false
+
   const host = header(req, 'host')
   const origin = header(req, 'origin') || header(req, 'referer')
 
@@ -80,6 +87,12 @@ export function isTrustedWriteRequest(req) {
     return false
   }
 
+  const address = (req.socket && (req.socket.remoteAddress || req.socket.address?.().address)) || ''
+  const cleanIp = address.replace(/^::ffff:/, '')
+  const loopback = cleanIp === '127.0.0.1' || cleanIp === '::1' || cleanIp.startsWith('127.')
+
+  if (cleanIp && !isTrustedHost(cleanIp)) return false
+
   const host = header(req, 'host')
   const origin = header(req, 'origin') || header(req, 'referer')
   if (origin) {
@@ -91,9 +104,6 @@ export function isTrustedWriteRequest(req) {
     }
   } else {
     // Write request without origin: only permit local loopback
-    const address = (req.socket && (req.socket.remoteAddress || req.socket.address?.().address)) || ''
-    const cleanIp = address.replace(/^::ffff:/, '')
-    const loopback = cleanIp === '127.0.0.1' || cleanIp === '::1' || cleanIp.startsWith('127.')
     if (!loopback) return false
   }
 
@@ -117,12 +127,14 @@ function header(req, name) {
  */
 export function statusPayload({ access, identity, rateLimit, scopes, cache, error } = {}) {
   const configured = Boolean(access && access.value)
+  const audit = auditTokenScopes(scopes)
   return {
     configured,
     source: configured ? access.source || '' : '',
     login: (identity && identity.login) || '',
     name: (identity && identity.name) || '',
     scopes: scopes || '',
+    scopeWarnings: audit.warnings,
     rateLimit: rateLimit
       ? { limit: rateLimit.limit, remaining: rateLimit.remaining, resetAt: rateLimit.resetAt }
       : null,

package/lib/token-audit.js

@@ -0,0 +1,84 @@
+// Token scopes audit and capability diagnostics.
+// Compares GitHub x-oauth-scopes against features of dsh-github-ops.
+
+export const CAPABILITY_REQUIREMENTS = [
+  {
+    capability: 'Repositories & Code (Private)',
+    requiredAny: ['repo'],
+    impact: 'Access to private repositories, code pushes, branches, releases, issues and PRs',
+  },
+  {
+    capability: 'Repositories & Code (Public)',
+    requiredAny: ['repo', 'public_repo'],
+    impact: 'Access to public repository code, issues, releases and PRs',
+  },
+  {
+    capability: 'Workflows & CI Runs',
+    requiredAny: ['workflow'],
+    impact: 'Triggering workflow runs, cancelling runs and updating .github/workflows',
+  },
+  {
+    capability: 'GitHub Packages',
+    requiredAny: ['write:packages', 'read:packages'],
+    impact: 'Publishing and downloading package bundles from ghcr.io / npm.pkg.github.com',
+  },
+  {
+    capability: 'Organization & Teams',
+    requiredAny: ['read:org', 'admin:org'],
+    impact: 'Listing organization repositories, teams and membership',
+  },
+]
+
+export function auditTokenScopes(rawScopes) {
+  const scopesStr = typeof rawScopes === 'string' ? rawScopes.trim() : ''
+  if (!scopesStr) {
+    return {
+      scopes: [],
+      raw: '',
+      isFineGrained: true,
+      capabilities: [],
+      missing: [],
+      warnings: ['Token does not report OAuth scopes (typical for fine-grained Personal Access Tokens or GitHub Apps). Permissions are scoped per-repository.'],
+      hasFullRepoAccess: false,
+      hasWorkflowAccess: false,
+    }
+  }
+
+  const scopeList = scopesStr.split(',').map((s) => s.trim().toLowerCase()).filter(Boolean)
+  const scopeSet = new Set(scopeList)
+
+  const capabilities = []
+  const missing = []
+  const warnings = []
+
+  for (const item of CAPABILITY_REQUIREMENTS) {
+    const granted = item.requiredAny.some((s) => scopeSet.has(s))
+    capabilities.push({
+      capability: item.capability,
+      granted,
+      requiredAny: item.requiredAny,
+    })
+    if (!granted) {
+      missing.push({
+        capability: item.capability,
+        requiredAny: item.requiredAny,
+        impact: item.impact,
+      })
+      warnings.push(`Missing scope [${item.requiredAny.join(' or ')}] for ${item.capability}: ${item.impact}`)
+    }
+  }
+
+  const hasFullRepoAccess = scopeSet.has('repo')
+  const hasWorkflowAccess = scopeSet.has('workflow')
+
+  return {
+    scopes: scopeList,
+    raw: scopesStr,
+    isFineGrained: false,
+    capabilities,
+    missing,
+    warnings,
+    hasFullRepoAccess,
+    hasWorkflowAccess,
+  }
+}

package/lib/tools/actions.js

@@ -175,11 +175,13 @@ export async function getJobLogSummary(client, { owner, repo, runId, jobId, maxL
   }
 
   const lines = cleanLogContent(logText, maxLines)
+  const errorHighlights = lines.filter((l) => /\b(error|failed|failure|fatal)\b|##\[error\]|npm err!/i.test(l)).slice(-10)
   return {
     jobId: targetJobId,
     jobName: targetJobName,
     failedStep,
     lineCount: lines.length,
     lines,
+    errorHighlights,
   }
 }

package/lib/tools/mirror.js

@@ -162,7 +162,9 @@ export async function publishMirror({
 
   if (dryRun) return { ...plan, mirror: mirrorRef, parent, commit: null, pushed: false }
 
-  const indexFile = path.join(tmpdir(), `dsh-mirror-${process.pid}-${randomUUID()}.index`)
+  const fs = await import('node:fs/promises')
+  const tmpIndexDir = await fs.mkdtemp(path.join(tmpdir(), 'dsh-mirror-index-'))
+  const indexFile = path.join(tmpIndexDir, `mirror-${randomUUID()}.index`)
   const env = { GIT_INDEX_FILE: indexFile }
   try {
     await git(['read-tree', '--empty'], { cwd, env })
@@ -190,5 +192,6 @@ export async function publishMirror({
     }
   } finally {
     await git(['update-index', '--refresh'], { cwd, env }).catch(() => {})
+    await fs.rm(tmpIndexDir, { recursive: true, force: true }).catch(() => {})
   }
 }

package/lib/tools/register-collab.js

@@ -245,7 +245,7 @@ export function registerCollabTools({ tool, asRepo, client, liveConfig, reviewRu
       const { owner, repo } = await asRepo(args, liveConfig())
       return listReviewThreads(await client(), {
         owner, repo,
-        number: args.number || args.pullNumber,
+        number: args.number,
         unresolvedOnly: Boolean(args.unresolvedOnly),
       })
     },
@@ -266,7 +266,7 @@ export function registerCollabTools({ tool, asRepo, client, liveConfig, reviewRu
       const { owner, repo } = await asRepo(args, liveConfig())
       return replyReviewThread(await client(), {
         owner, repo,
-        number: args.number || args.pullNumber,
+        number: args.number,
         threadId: args.threadId,
         commentId: args.commentId,
         body: args.body,

package/lib/tools/register-core.js

@@ -1,3 +1,4 @@
+import { validateCwd } from '../scm-write.js'
 import { runReleasePreflight } from './release-preflight.js'
 // Core tool registrations: repository and file reads, releases, tags, the guarded
 // generic API pass-through, and repository creation/edits.
@@ -255,10 +256,10 @@ export function registerCoreTools({ tool, asRepo, client, liveConfig, defaultCwd
       const { owner, repo } = await asRepo(args, liveConfig())
       return generateReleaseNotes(await client(), {
         owner, repo,
-        tag: args.tag || args.tagName,
-        target: args.target || args.targetCommitish,
-        previousTag: args.previousTag || args.previousTagName,
-        configFile: args.configFile || args.configurationFilePath,
+        tag: args.tag,
+        target: args.target,
+        previousTag: args.previousTag,
+        configFile: args.configFile,
       })
     },
   )
@@ -337,16 +338,23 @@ export function registerCoreTools({ tool, asRepo, client, liveConfig, defaultCwd
 
   tool(
     'gh_release_preflight',
-    'Run automated pre-release audit on the plugin package: checks package.json version, cordis.patch.yml, CHANGELOG.md release notes, three READMEs (EN/RU/ZH), npm pack file sizes (<256 KiB), and git index hygiene.',
+    'Run automated pre-release audit on the plugin package: checks package.json version, cordis.patch.yml, CHANGELOG.md release notes, three READMEs (EN/RU/ZH), npm pack file sizes (<256 KiB), and git index hygiene. Running test suite requires confirm: true.',
     {
       cwd: { type: 'string', description: 'Directory to audit (defaults to workspace or process.cwd()).' },
-      runTests: { type: 'boolean', description: 'Whether to run npm test as part of the audit (default false).' },
+      runTests: { type: 'boolean', description: 'Whether to run npm test as part of the audit (requires confirm: true).' },
       maxFileSize: { type: 'number', description: 'Max allowed size in bytes per packaged file (default 262144).' },
+      confirm: { type: 'boolean', description: 'Must be true to execute npm test when runTests is true.' },
     },
     async (args) => {
+      if (args.runTests === true && args.confirm !== true) {
+        throw new Error('running test suite during preflight audit requires confirm: true')
+      }
+      const rawCwd = args.cwd || (typeof defaultCwd === 'function' ? defaultCwd() : process.cwd())
+      const validatedCwd = validateCwd(rawCwd)
       return runReleasePreflight({
-        cwd: args.cwd,
+        cwd: validatedCwd,
         runTests: args.runTests,
+        confirm: args.confirm,
         maxFileSize: args.maxFileSize,
       })
     },

package/lib/tools/register-ops.js

@@ -102,6 +102,19 @@ export function registerOpsTools({ tool, asRepo, client, liveConfig }) {
     async (args) => withRepo(args, async ({ owner, repo }) => getRunLogsUrl(await client(), { owner, repo, runId: args.runId })),
   )
 
+  tool(
+    'gh_run_failure_inspector',
+    'Inspect failed jobs and steps in a GitHub Actions workflow run, downloading only the relevant job log text, stripping ANSI escapes, redacting tokens, and returning the diagnostic error lines without downloading full zip archives. Read-only.',
+    repoParams({
+      runId: { type: 'number', description: 'Workflow run id (e.g. from gh_run_list).' },
+      jobId: { type: 'number', description: 'Specific job id to inspect (optional, defaults to first failed job).' },
+      maxLines: { type: 'number', description: 'Maximum log lines to return (default 100, max 250).' },
+    }),
+    async (args) => withRepo(args, async ({ owner, repo }) => getJobLogSummary(await client(), {
+      owner, repo, runId: args.runId, jobId: args.jobId, maxLines: args.maxLines,
+    })),
+  )
+
   tool(
     'gh_run_dispatch',
     'Trigger a workflow_dispatch event for a GitHub Actions workflow with inputs. Requires confirm: true.',

package/lib/tools/register-write.js

@@ -1,3 +1,4 @@
+import { auditTokenScopes } from '../token-audit.js'
 // Content and account tools: writing files without a checkout, and signing in without a
 // terminal.
 //
@@ -210,7 +211,6 @@ export function registerWriteTools({ tool, asRepo, client, liveConfig, auth }) {
     '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()
@@ -227,6 +227,28 @@ export function registerWriteTools({ tool, asRepo, client, liveConfig, auth }) {
     },
   )
 
+  tool(
+    'gh_token_audit',
+    'Audit OAuth token scopes and report granted vs missing capabilities (repo, workflow, packages, org) with diagnostic warnings. Read-only.',
+    {},
+    async () => {
+      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')
+      const rawScopes = github.lastScopes ? github.lastScopes() : ''
+      const audit = auditTokenScopes(rawScopes)
+      return {
+        configured: true,
+        source: access.source,
+        login: data && data.login,
+        name: data && data.name,
+        rateLimit: rateLimit || undefined,
+        ...audit,
+      }
+    },
+  )
+
   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.',
@@ -240,6 +262,4 @@ export function registerWriteTools({ tool, asRepo, client, liveConfig, auth }) {
     },
   )
 
-  // keep the imports honest for callers that compose their own flows
-  return { accessFilePath, readAccessFile }
 }

package/lib/tools/release-preflight.js

@@ -1,3 +1,4 @@
+import { validateCwd } from '../scm-write.js'
 // lib/tools/release-preflight.js
 // Automated release preflight audit for DSH plugins according to
 // dhs-plugin-release-workflow and dsh-documentation-standard.
@@ -23,8 +24,12 @@ const FORBIDDEN_PACK_EXACT = ['AGENTS.md', '.env', '.env.local', 'deploy.sh']
  * @param {object} [deps] Injectable dependencies for unit testing
  */
 export async function runReleasePreflight(options = {}, deps = {}) {
-  const cwd = options.cwd || process.cwd()
+  const rawCwd = options.cwd || process.cwd()
+  const cwd = validateCwd(rawCwd)
   const runTests = options.runTests === true
+  if (runTests && options.confirm !== true) {
+    throw new Error('running test suite during preflight audit requires confirm: true')
+  }
   const maxFileSize = typeof options.maxFileSize === 'number' ? options.maxFileSize : MAX_FILE_SIZE_DEFAULT
   const exec = deps.execFile || pExecFile
   const fsRead = deps.readFileSync || readFileSync

package/lib/tools/releases.js

@@ -236,4 +236,3 @@ export async function generateReleaseNotes(client, { owner, repo, tag, target, p
     previousTag: previousTag || '',
   }
 }
-export { runReleasePreflight } from './release-preflight.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-github-ops",
-  "version": "0.2.11",
+  "version": "0.3.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",