boxdown 1.0.0 → 1.2.1

package/src/doctor.ts

@@ -1,6 +1,10 @@
-import { existsSync } from 'node:fs'
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { dirname, join } from 'node:path'
 
 import { resolveDevcontainerCli } from './devcontainer-cli.ts'
+import { buildGeneratedDevcontainerConfig, type DevcontainerConfig } from './config.ts'
+import { BOXDOWN_SECRET_ENV_NAMES } from './constants.ts'
+import { resolveConfiguredSshSigningKey, selectGitSigningKey, type GitSigningReason } from './git-signing.ts'
 import type { WorkspaceContext } from './paths.ts'
 import { runBuffered } from './process.ts'
 
@@ -12,6 +16,20 @@ export interface DoctorCheck {
   message: string
 }
 
+export interface DoctorCommandResult {
+  code: number
+  stdout: string
+  stderr: string
+}
+
+export type DoctorCommandRunner = (command: string, args: string[]) => Promise<DoctorCommandResult>
+
+export interface RunDoctorChecksOptions {
+  includeOptional?: boolean
+  includeDockerMountProbe?: boolean
+  runCommand?: DoctorCommandRunner
+}
+
 function nodeVersionPasses (version: string): boolean {
   const major = Number.parseInt(version.split('.')[0] ?? '', 10)
   return Number.isInteger(major) && major >= 24
@@ -25,26 +43,56 @@ function check (name: string, pass: boolean, okMessage: string, failMessage: str
   }
 }
 
-async function commandWorks (command: string, args: string[]): Promise<boolean> {
-  const result = await runBuffered(command, args, {
-    mirrorStdout: false,
-    mirrorStderr: false
-  })
+function secretEnvironmentConfigCheck (context: WorkspaceContext): DoctorCheck {
+  let config: DevcontainerConfig
 
-  return result.code === 0
+  try {
+    config = existsSync(context.generatedConfigPath)
+      ? JSON.parse(readFileSync(context.generatedConfigPath, 'utf8')) as DevcontainerConfig
+      : buildGeneratedDevcontainerConfig(context)
+  } catch {
+    return {
+      name: 'secret-environment-config',
+      level: 'warn',
+      message: 'Generated config could not be checked for secret-safe environment handling'
+    }
+  }
+
+  const runArgs = Array.isArray(config.runArgs) ? config.runArgs : []
+  const containerEnv = config.containerEnv ?? {}
+  const unsafe = runArgs.includes('--env-file') ||
+    runArgs.some((arg) => arg.includes('.env.development')) ||
+    BOXDOWN_SECRET_ENV_NAMES.some((name) => Object.hasOwn(containerEnv, name))
+
+  return {
+    name: 'secret-environment-config',
+    level: unsafe ? 'warn' : 'ok',
+    message: unsafe
+      ? 'Generated config still exposes Boxdown secrets through Docker environment settings; recreate after upgrading Boxdown'
+      : 'Generated config uses runtime-mounted secrets without Docker environment values'
+  }
 }
 
-async function commandExists (command: string, args: string[]): Promise<boolean> {
-  const result = await runBuffered(command, args, {
+async function runDoctorCommand (command: string, args: string[]): Promise<DoctorCommandResult> {
+  return runBuffered(command, args, {
     mirrorStdout: false,
     mirrorStderr: false
   })
+}
+
+async function commandWorks (runCommand: DoctorCommandRunner, command: string, args: string[]): Promise<boolean> {
+  const result = await runCommand(command, args)
+  return result.code === 0
+}
 
+async function commandExists (runCommand: DoctorCommandRunner, command: string, args: string[]): Promise<boolean> {
+  const result = await runCommand(command, args)
   return result.code !== 127
 }
 
-export async function runDoctorChecks (context: WorkspaceContext): Promise<DoctorCheck[]> {
+export async function runDoctorChecks (context: WorkspaceContext, options: RunDoctorChecksOptions = {}): Promise<DoctorCheck[]> {
   const checks: DoctorCheck[] = []
+  const runCommand = options.runCommand ?? runDoctorCommand
   const nodeVersion = process.versions.node
 
   checks.push(check(
@@ -54,37 +102,117 @@ export async function runDoctorChecks (context: WorkspaceContext): Promise<Docto
     `Node ${nodeVersion}; expected >=24.0.0`
   ))
 
+  const sshAgent = await runCommand('ssh-add', ['-L'])
+  const identityLines = sshAgent.code === 0
+    ? sshAgent.stdout.split(/\r?\n/).filter((line) => line.trim().startsWith('ssh-'))
+    : []
+  const identities = identityLines.length
+  let configuredKey: string | undefined
+  let configuredFailure: { reason: GitSigningReason, detail?: string } | undefined
+  const format = await runCommand('git', ['config', '--global', '--get', 'gpg.format'])
+  if (format.code === 0 && format.stdout.trim() === 'ssh') {
+    const signingKey = await runCommand('git', ['config', '--global', '--get', 'user.signingkey'])
+    if (signingKey.code === 0 && signingKey.stdout.trim().length > 0) {
+      const resolved = resolveConfiguredSshSigningKey(signingKey.stdout.trim(), {
+        homeDir: dirname(context.hostGitconfigPath),
+        workspaceFolder: context.workspaceFolder
+      })
+      if (resolved.key === undefined) {
+        configuredFailure = {
+          reason: resolved.reason ?? 'configured-key-invalid',
+          detail: resolved.detail
+        }
+      } else {
+        configuredKey = resolved.key
+      }
+    }
+  }
+
+  const includeOptional = options.includeOptional ?? true
+  let ghAvailable = false
+  let ghAuth = false
+  let githubLogin: string | undefined
+  let githubAuthKeys: string[] | undefined
+  if (includeOptional) {
+    ghAvailable = await commandWorks(runCommand, 'gh', ['--version'])
+    if (ghAvailable) {
+      ghAuth = await commandWorks(runCommand, 'gh', ['auth', 'status', '--hostname', 'github.com'])
+      if (ghAuth && configuredKey === undefined && configuredFailure === undefined && identities > 1) {
+        const user = await runCommand('gh', ['api', 'user', '--jq', '.login'])
+        githubLogin = user.code === 0 && user.stdout.trim().length > 0 ? user.stdout.trim() : undefined
+        if (githubLogin !== undefined) {
+          const authentication = await runCommand('gh', ['api', `users/${githubLogin}/keys`, '--paginate', '--jq', '.[].key'])
+          if (authentication.code === 0) githubAuthKeys = authentication.stdout.split(/\r?\n/)
+        }
+      }
+    }
+  }
+
+  const selected: { key?: string, reason?: GitSigningReason } = configuredFailure ?? selectGitSigningKey(identityLines, configuredKey, githubAuthKeys)
+  const selectedByConfiguration = selected.key !== undefined && configuredKey !== undefined
+  const selectedByGithub = selected.key !== undefined && configuredKey === undefined && identities > 1
+  const signingMessages: Record<GitSigningReason, string> = {
+    'agent-unavailable': 'SSH agent is unavailable; Boxdown commits will remain unsigned',
+    'no-identities': 'SSH agent has no identities; Boxdown commits will remain unsigned',
+    'ambiguous-identities': 'SSH agent has multiple identities; Boxdown will not guess a signing key and commits will remain unsigned',
+    'configured-key-unreadable': 'Configured SSH signing-key file could not be read; Boxdown commits will remain unsigned',
+    'configured-key-invalid': 'Configured SSH signing key is not a valid public key; Boxdown commits will remain unsigned',
+    'configured-key-not-loaded': 'Configured SSH signing key is not loaded in the agent; Boxdown commits will remain unsigned',
+    'agent-socket-unavailable': 'Host SSH-agent socket is unavailable; Boxdown commits will remain unsigned',
+    'docker-probe-image-unavailable': 'No local Docker image is available to probe commit-signing agent forwarding',
+    'agent-mount-unavailable': 'Docker could not mount the host SSH-agent socket; Boxdown commits will remain unsigned'
+  }
+  checks.push({
+    name: 'git-signing-agent',
+    level: sshAgent.code === 0 && selected.key !== undefined ? 'ok' : 'warn',
+    message: sshAgent.code !== 0
+      ? signingMessages['agent-unavailable']
+      : selected.key === undefined
+        ? signingMessages[selected.reason ?? 'ambiguous-identities']
+        : selectedByConfiguration
+          ? 'Configured SSH signing key is loaded in the agent'
+          : selectedByGithub
+            ? 'GitHub authentication keys identify one SSH agent identity for Boxdown commit signing'
+            : 'One SSH agent identity is available for Boxdown commit signing'
+  })
+
   checks.push(check(
     'devcontainers-cli',
-    await packagedDevcontainerCliWorks(context),
+    await packagedDevcontainerCliWorks(context, runCommand),
     'Packaged @devcontainers/cli is available',
     'Packaged @devcontainers/cli is required but was not available'
   ))
 
+  const dockerCliWorks = await commandWorks(runCommand, 'docker', ['--version'])
   checks.push(check(
     'docker-cli',
-    await commandWorks('docker', ['--version']),
+    dockerCliWorks,
     'Docker CLI is available',
     'Docker CLI is required but was not available'
   ))
 
+  const dockerDaemonWorks = await commandWorks(runCommand, 'docker', ['info'])
   checks.push(check(
     'docker-daemon',
-    await commandWorks('docker', ['info']),
+    dockerDaemonWorks,
     'Docker daemon is reachable',
     'Docker daemon is required but was not reachable'
   ))
 
   checks.push(check(
     'ssh',
-    await commandExists('ssh', ['-V']),
+    await commandExists(runCommand, 'ssh', ['-V']),
     'ssh is available',
     'ssh is required but was not available'
   ))
 
+  if (options.includeDockerMountProbe ?? true) {
+    checks.push(await checkDockerBindMounts(context, runCommand, dockerCliWorks && dockerDaemonWorks))
+  }
+
   checks.push(check(
     'ssh-keygen',
-    await commandExists('ssh-keygen', ['-?']),
+    await commandExists(runCommand, 'ssh-keygen', ['-?']),
     'ssh-keygen is available',
     'ssh-keygen is required but was not available'
   ))
@@ -96,28 +224,162 @@ export async function runDoctorChecks (context: WorkspaceContext): Promise<Docto
     `Missing Boxdown devcontainer assets: ${context.assetsDevcontainerDir}`
   ))
 
-  if (await commandWorks('gh', ['--version'])) {
-    const ghAuth = await commandWorks('gh', ['auth', 'status', '--hostname', 'github.com'])
-    checks.push({
-      name: 'gh-auth',
-      level: ghAuth ? 'ok' : 'warn',
-      message: ghAuth ? 'GitHub CLI auth is available' : 'GitHub CLI is available but not authenticated'
-    })
-  } else {
-    checks.push({
-      name: 'gh',
-      level: 'warn',
-      message: 'GitHub CLI is optional and was not available'
-    })
+  checks.push(secretEnvironmentConfigCheck(context))
+
+  if (includeOptional) {
+    if (ghAvailable) {
+      checks.push({
+        name: 'gh-auth',
+        level: ghAuth ? 'ok' : 'warn',
+        message: ghAuth ? 'GitHub CLI auth is available' : 'GitHub CLI is available but not authenticated'
+      })
+      if (ghAuth && selected.key !== undefined) {
+        if (githubLogin === undefined) {
+          const user = await runCommand('gh', ['api', 'user', '--jq', '.login'])
+          githubLogin = user.code === 0 && user.stdout.trim().length > 0 ? user.stdout.trim() : undefined
+        }
+        const signing = githubLogin !== undefined
+          ? await runCommand('gh', ['api', `users/${githubLogin}/ssh_signing_keys`, '--paginate', '--jq', '.[].key'])
+          : { code: 1, stdout: '', stderr: '' }
+        checks.push({
+          name: 'git-signing-github',
+          level: signing.code === 0 && signing.stdout.includes(selected.key) ? 'ok' : 'warn',
+          message: signing.code !== 0
+            ? 'GitHub SSH signing-key registration could not be checked'
+            : signing.stdout.includes(selected.key)
+              ? 'Selected SSH key is registered with GitHub for commit signing'
+              : 'Register the selected public key with GitHub as a signing key to receive Verified badges'
+        })
+      }
+    } else {
+      checks.push({
+        name: 'gh',
+        level: 'warn',
+        message: 'GitHub CLI is optional and was not available'
+      })
+    }
   }
 
   return checks
 }
 
-async function packagedDevcontainerCliWorks (context: WorkspaceContext): Promise<boolean> {
+function dockerProbeImage (output: string): string | undefined {
+  return output
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .find((image) => image.length > 0 && image !== '<none>:<none>')
+}
+
+function dockerMountError (output: string): boolean {
+  return /invalid mount config|bind source path does not exist|mount denied|file sharing|mounts denied|permission denied|operation not permitted/i.test(output)
+}
+
+function compactOutput (output: string): string {
+  return output.trim().replace(/\s+/g, ' ').slice(0, 300)
+}
+
+interface DockerMountSource {
+  label: string
+  path: string
+}
+
+async function checkDockerBindMounts (
+  context: WorkspaceContext,
+  runCommand: DoctorCommandRunner,
+  dockerReady: boolean
+): Promise<DoctorCheck> {
+  if (!dockerReady) {
+    return {
+      name: 'docker-bind-mounts',
+      level: 'warn',
+      message: 'Docker bind-mount readiness was not checked because Docker is unavailable'
+    }
+  }
+
+  const imageResult = await runCommand('docker', ['image', 'ls', '--format', '{{.Repository}}:{{.Tag}}'])
+  const image = imageResult.code === 0 ? dockerProbeImage(imageResult.stdout) : undefined
+
+  if (image === undefined) {
+    return {
+      name: 'docker-bind-mounts',
+      level: 'warn',
+      message: 'Docker bind-mount readiness was not checked because no local Docker image is available'
+    }
+  }
+
+  mkdirSync(context.workspaceDataDir, { recursive: true })
+  const runtimeProbeDir = mkdtempSync(join(context.workspaceDataDir, 'doctor-mount-probe-'))
+  mkdirSync(context.workspaceSecretEnvDir, { recursive: true, mode: 0o700 })
+  chmodSync(context.workspaceSecretEnvDir, 0o700)
+  const sources: DockerMountSource[] = [
+    { label: 'workspace', path: context.workspaceFolder },
+    { label: 'Boxdown devcontainer assets', path: context.assetsDevcontainerDir },
+    { label: 'Boxdown runtime state', path: runtimeProbeDir },
+    { label: 'Boxdown runtime secret state', path: context.workspaceSecretEnvDir }
+  ]
+
+  try {
+    for (const source of sources) {
+      const createResult = await runCommand('docker', [
+        'create',
+        '--pull=never',
+        '--entrypoint',
+        '/bin/true',
+        '--mount',
+        `type=bind,source=${source.path},target=/boxdown-preflight,readonly`,
+        image
+      ])
+      const output = `${createResult.stderr}\n${createResult.stdout}`
+
+      if (createResult.code !== 0) {
+        if (dockerMountError(output)) {
+          return {
+            name: 'docker-bind-mounts',
+            level: 'fail',
+            message: `Docker cannot bind-mount the ${source.label} path (${source.path}). Check Docker Desktop file sharing and host-folder permissions.`
+          }
+        }
+
+        return {
+          name: 'docker-bind-mounts',
+          level: 'warn',
+          message: `Docker bind-mount readiness could not be checked for ${source.label}: ${compactOutput(output) || 'Docker create failed'}`
+        }
+      }
+
+      const containerId = createResult.stdout.trim().split(/\r?\n/)[0]
+      if (containerId === undefined || containerId.length === 0) {
+        return {
+          name: 'docker-bind-mounts',
+          level: 'warn',
+          message: `Docker bind-mount readiness could not be checked for ${source.label}: Docker did not return a container ID`
+        }
+      }
+
+      const removeResult = await runCommand('docker', ['rm', '-f', containerId])
+      if (removeResult.code !== 0) {
+        return {
+          name: 'docker-bind-mounts',
+          level: 'warn',
+          message: `Docker bind-mount readiness was checked, but the disposable probe container could not be removed: ${compactOutput(removeResult.stderr) || 'docker rm failed'}`
+        }
+      }
+    }
+  } finally {
+    rmSync(runtimeProbeDir, { recursive: true, force: true })
+  }
+
+  return {
+    name: 'docker-bind-mounts',
+    level: 'ok',
+    message: 'Docker can bind-mount Boxdown workspace, assets, and runtime-state paths'
+  }
+}
+
+async function packagedDevcontainerCliWorks (context: WorkspaceContext, runCommand: DoctorCommandRunner): Promise<boolean> {
   try {
     const cli = resolveDevcontainerCli(context)
-    return await commandWorks(cli.command, [...cli.argsPrefix, '--version'])
+    return await commandWorks(runCommand, cli.command, [...cli.argsPrefix, '--version'])
   } catch {
     return false
   }

package/src/git-signing.ts

@@ -0,0 +1,267 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { isAbsolute, join, resolve } from 'node:path'
+
+import type { WorkspaceCommandLogger } from './logging.ts'
+import type { WorkspaceContext } from './paths.ts'
+import { runBuffered, type CommandResult } from './process.ts'
+
+export type GitSigningReason = 'agent-unavailable' | 'no-identities' | 'ambiguous-identities' | 'configured-key-unreadable' | 'configured-key-invalid' | 'configured-key-not-loaded' | 'agent-socket-unavailable' | 'docker-probe-image-unavailable' | 'agent-mount-unavailable'
+
+export interface GitSigningPlan {
+  enabled: boolean
+  reason?: GitSigningReason
+  detail?: string
+  publicKey?: string
+  agentSocketSource?: string
+}
+
+const GIT_SIGNING_REASON_MESSAGES: Record<GitSigningReason, string> = {
+  'agent-unavailable': 'the host SSH agent is unavailable',
+  'no-identities': 'the host SSH agent has no loaded identities',
+  'ambiguous-identities': 'multiple SSH identities are loaded and no signing key could be selected safely',
+  'configured-key-unreadable': 'the configured SSH signing-key file could not be read',
+  'configured-key-invalid': 'the configured SSH signing key is not a valid public key',
+  'configured-key-not-loaded': 'the configured SSH signing key is not loaded in the agent',
+  'agent-socket-unavailable': 'the host SSH-agent socket is unavailable',
+  'docker-probe-image-unavailable': 'no local Docker image is available to probe the SSH-agent mount',
+  'agent-mount-unavailable': 'Docker could not mount the host SSH-agent socket'
+}
+
+function compactDiagnosticDetail (detail: string): string {
+  return detail
+    .trim()
+    .replace(/\s+/gu, ' ')
+    .slice(0, 2000)
+    .replace(/-----BEGIN [^-]*PRIVATE KEY-----.*?(?:-----END [^-]*PRIVATE KEY-----|$)/giu, '[redacted-private-key]')
+    .replace(/\b(?:ssh-[A-Za-z0-9-]+|ecdsa-sha2-[A-Za-z0-9-]+|sk-(?:ssh-[A-Za-z0-9-]+|ecdsa-sha2-[A-Za-z0-9-]+))\s+[A-Za-z0-9+/=]{16,}/gu, '[redacted-ssh-key]')
+    .replace(/\b(?:github_pat_|gh[pousr]_|glpat-|xox[baprs]-)[A-Za-z0-9_-]{8,}/gu, '[redacted-token]')
+    .replace(/\b(?:Bearer\s+|token[=:]\s*)[A-Za-z0-9._~+/-]{8,}/giu, '[redacted-token]')
+    .slice(0, 300)
+}
+
+export function reportGitSigningPlan (
+  plan: GitSigningPlan,
+  options: {
+    logger?: Pick<WorkspaceCommandLogger, 'boxdown'>
+    quiet?: boolean
+    writeWarning?: (message: string) => void
+  } = {}
+): void {
+  if (plan.enabled) return
+
+  const reason = plan.reason ?? 'agent-unavailable'
+  const detail = plan.detail === undefined ? '' : ` detail=${compactDiagnosticDetail(plan.detail)}`
+  options.logger?.boxdown(`git-signing: enabled=false reason=${reason}${detail}\n`)
+
+  if (options.quiet !== true) {
+    const writeWarning = options.writeWarning ?? ((message: string) => process.stderr.write(message))
+    writeWarning(`boxdown: commit signing disabled: ${GIT_SIGNING_REASON_MESSAGES[reason]}; commits will remain unsigned.\n`)
+  }
+}
+
+export function parseSshPublicKey (value: string): string | undefined {
+  const [algorithm, key] = value.trim().split(/\s+/, 3)
+  if (algorithm === undefined || key === undefined || !/^ssh-[A-Za-z0-9-]+$/.test(algorithm) || key.length === 0) {
+    return undefined
+  }
+
+  return `${algorithm} ${key}`
+}
+
+export interface ConfiguredSshSigningKeyResult {
+  key?: string
+  reason?: Extract<GitSigningReason, 'configured-key-unreadable' | 'configured-key-invalid'>
+  detail?: string
+}
+
+export function resolveConfiguredSshSigningKey (
+  value: string,
+  options: { homeDir?: string, workspaceFolder: string }
+): ConfiguredSshSigningKeyResult {
+  const inlineValue = value.startsWith('key::') ? value.slice('key::'.length) : value
+  const inlineKey = parseSshPublicKey(inlineValue)
+  if (inlineKey !== undefined) {
+    return { key: inlineKey }
+  }
+  if (value.startsWith('key::')) {
+    return {
+      reason: 'configured-key-invalid',
+      detail: 'configured inline value is not a valid SSH public key'
+    }
+  }
+
+  let keyPath: string
+  if (value.startsWith('~/')) {
+    if (options.homeDir === undefined) {
+      return {
+        reason: 'configured-key-unreadable',
+        detail: 'configured public-key file could not be read'
+      }
+    }
+    keyPath = join(options.homeDir, value.slice(2))
+  } else {
+    keyPath = isAbsolute(value) ? value : resolve(options.workspaceFolder, value)
+  }
+
+  let publicKeyText: string
+  try {
+    publicKeyText = readFileSync(keyPath, 'utf8')
+  } catch {
+    return {
+      reason: 'configured-key-unreadable',
+      detail: 'configured public-key file could not be read'
+    }
+  }
+
+  const publicKey = parseSshPublicKey(publicKeyText.split(/\r?\n/u).find((line) => line.trim().length > 0) ?? '')
+  return publicKey === undefined
+    ? {
+        reason: 'configured-key-invalid',
+        detail: 'configured public-key file does not contain a valid SSH public key'
+      }
+    : { key: publicKey }
+}
+
+export function selectGitSigningKey (identities: string[], configuredKey?: string, githubKeys?: string[]): { key?: string, reason?: GitSigningReason } {
+  const keys = identities.map(parseSshPublicKey).filter((key): key is string => key !== undefined)
+  if (keys.length === 0) return { reason: 'no-identities' }
+
+  const configured = configuredKey === undefined ? undefined : parseSshPublicKey(configuredKey)
+  if (configuredKey !== undefined && configured === undefined) {
+    return { reason: 'configured-key-invalid' }
+  }
+  if (configured !== undefined) {
+    return keys.includes(configured) ? { key: configured } : { reason: 'configured-key-not-loaded' }
+  }
+
+  const github = new Set((githubKeys ?? []).map(parseSshPublicKey).filter((key): key is string => key !== undefined))
+  const matches = keys.filter((key) => github.has(key))
+  if (matches.length === 1) return { key: matches[0] }
+  if (keys.length === 1) return { key: keys[0] }
+  return { reason: 'ambiguous-identities' }
+}
+
+export function writeGitSigningPublicKey (context: WorkspaceContext, key: string): void {
+  mkdirSync(context.gitSigningStateDir, { recursive: true, mode: 0o700 })
+  writeFileSync(join(context.gitSigningStateDir, 'signing-key.pub'), `${parseSshPublicKey(key) ?? key}\n`, { mode: 0o644 })
+}
+
+type GitSigningCommandRunner = (command: string, args: string[]) => Promise<CommandResult>
+
+interface ResolveGitSigningPlanOptions {
+  env?: NodeJS.ProcessEnv
+  platform?: NodeJS.Platform
+  runCommand?: GitSigningCommandRunner
+}
+
+type AgentMountProbeResult =
+  | { ok: true }
+  | { ok: false, reason: Extract<GitSigningReason, 'docker-probe-image-unavailable' | 'agent-mount-unavailable'>, detail: string }
+
+async function runGitSigningCommand (command: string, args: string[]): Promise<CommandResult> {
+  return runBuffered(command, args, { mirrorStdout: false, mirrorStderr: false })
+}
+
+function failedCommandDetail (label: string, result: CommandResult): string {
+  const stderr = compactDiagnosticDetail(result.stderr)
+  return stderr.length === 0
+    ? `${label} failed with exit code ${result.code}`
+    : `${label} failed with exit code ${result.code}: ${stderr}`
+}
+
+async function probeDockerAgentMount (source: string, runCommand: GitSigningCommandRunner): Promise<AgentMountProbeResult> {
+  const images = await runCommand('docker', ['image', 'ls', '--format', '{{.Repository}}:{{.Tag}}'])
+  const image = images.stdout.split(/\r?\n/).map((value) => value.trim()).find((value) => value.length > 0 && value !== '<none>:<none>')
+  if (images.code !== 0) {
+    return {
+      ok: false,
+      reason: 'agent-mount-unavailable',
+      detail: failedCommandDetail('Docker image listing', images)
+    }
+  }
+  if (image === undefined) {
+    return {
+      ok: false,
+      reason: 'docker-probe-image-unavailable',
+      detail: 'no tagged local Docker image was found'
+    }
+  }
+
+  const created = await runCommand('docker', ['create', '--pull=never', '--entrypoint', '/bin/true', '--mount', `type=bind,source=${source},target=/run/boxdown/ssh-agent.sock`, image])
+  const containerId = created.stdout.trim().split(/\r?\n/)[0]
+  if (created.code !== 0 || containerId === undefined || containerId.length === 0) {
+    return {
+      ok: false,
+      reason: 'agent-mount-unavailable',
+      detail: failedCommandDetail('Docker SSH-agent mount probe', created)
+    }
+  }
+  await runCommand('docker', ['rm', '-f', containerId])
+  return { ok: true }
+}
+
+export async function resolveGitSigningPlan (context: WorkspaceContext, options: ResolveGitSigningPlanOptions = {}): Promise<GitSigningPlan> {
+  const runCommand = options.runCommand ?? runGitSigningCommand
+  const result = await runCommand('ssh-add', ['-L'])
+  if (result.code !== 0) {
+    return {
+      enabled: false,
+      reason: 'agent-unavailable',
+      detail: failedCommandDetail('ssh-add -L', result)
+    }
+  }
+
+  const identities = result.stdout.split(/\r?\n/)
+  const format = await runCommand('git', ['config', '--global', '--get', 'gpg.format'])
+  let configuredKey: string | undefined
+  if (format.code === 0 && format.stdout.trim() === 'ssh') {
+    const signingKey = await runCommand('git', ['config', '--global', '--get', 'user.signingkey'])
+    if (signingKey.code === 0 && signingKey.stdout.trim().length > 0) {
+      const resolvedKey = resolveConfiguredSshSigningKey(signingKey.stdout.trim(), {
+        homeDir: options.env?.HOME ?? process.env.HOME,
+        workspaceFolder: context.workspaceFolder
+      })
+      if (resolvedKey.key === undefined) {
+        return {
+          enabled: false,
+          reason: resolvedKey.reason ?? 'configured-key-invalid',
+          detail: resolvedKey.detail
+        }
+      }
+      configuredKey = resolvedKey.key
+    }
+  }
+  let githubKeys: string[] | undefined
+  if (configuredKey === undefined && identities.filter((key) => parseSshPublicKey(key) !== undefined).length > 1) {
+    const user = await runCommand('gh', ['api', 'user', '--jq', '.login'])
+    const login = user.stdout.trim()
+    if (user.code === 0 && login.length > 0) {
+      const github = await runCommand('gh', ['api', `users/${login}/keys`, '--paginate', '--jq', '.[].key'])
+      if (github.code === 0) githubKeys = github.stdout.split(/\r?\n/)
+    }
+  }
+  const selected = selectGitSigningKey(identities, configuredKey, githubKeys)
+  if (selected.key === undefined) return { enabled: false, reason: selected.reason }
+
+  const agentSocketSource = (options.platform ?? process.platform) === 'darwin'
+    ? '/run/host-services/ssh-auth.sock'
+    : options.env?.SSH_AUTH_SOCK ?? process.env.SSH_AUTH_SOCK
+  if (agentSocketSource === undefined || agentSocketSource.length === 0) {
+    return {
+      enabled: false,
+      reason: 'agent-socket-unavailable',
+      detail: 'SSH_AUTH_SOCK is not set'
+    }
+  }
+  const mountProbe = await probeDockerAgentMount(agentSocketSource, runCommand)
+  if (!mountProbe.ok) {
+    return {
+      enabled: false,
+      reason: mountProbe.reason,
+      detail: mountProbe.detail
+    }
+  }
+
+  writeGitSigningPublicKey(context, selected.key)
+  return { enabled: true, publicKey: selected.key, agentSocketSource }
+}