boxdown 1.0.0 → 1.2.0

package/src/doctor.ts

@@ -1,4 +1,5 @@
-import { existsSync } from 'node:fs'
+import { existsSync, mkdirSync, mkdtempSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
 
 import { resolveDevcontainerCli } from './devcontainer-cli.ts'
 import type { WorkspaceContext } from './paths.ts'
@@ -12,6 +13,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 +40,26 @@ 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, {
+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 (command: string, args: string[]): Promise<boolean> {
-  const result = await runBuffered(command, args, {
-    mirrorStdout: false,
-    mirrorStderr: false
-  })
-
+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 +69,59 @@ export async function runDoctorChecks (context: WorkspaceContext): Promise<Docto
     `Node ${nodeVersion}; expected >=24.0.0`
   ))
 
+  const sshAgent = await runCommand('ssh-add', ['-L'])
+  const identities = sshAgent.code === 0
+    ? sshAgent.stdout.split(/\r?\n/).filter((line) => line.trim().startsWith('ssh-')).length
+    : 0
+  checks.push({
+    name: 'git-signing-agent',
+    level: sshAgent.code === 0 && identities === 1 ? 'ok' : 'warn',
+    message: sshAgent.code !== 0
+      ? 'SSH agent is unavailable; Boxdown commits will remain unsigned'
+      : identities === 0
+        ? 'SSH agent has no identities; Boxdown commits will remain unsigned'
+        : identities > 1
+          ? 'SSH agent has multiple identities; Boxdown will not guess a signing key and commits will remain unsigned'
+          : '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 +133,156 @@ 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'
-    })
+  if (options.includeOptional ?? true) {
+    if (await commandWorks(runCommand, 'gh', ['--version'])) {
+      const ghAuth = await commandWorks(runCommand, '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'
+      })
+      if (ghAuth && identities === 1) {
+        const user = await runCommand('gh', ['api', 'user', '--jq', '.login'])
+        const signing = user.code === 0 && user.stdout.trim().length > 0
+          ? await runCommand('gh', ['api', `users/${user.stdout.trim()}/ssh_signing_keys`, '--paginate', '--jq', '.[].key'])
+          : { code: 1, stdout: '', stderr: '' }
+        const identity = sshAgent.stdout.split(/\r?\n/).find((line) => line.trim().startsWith('ssh-'))?.trim()
+        checks.push({
+          name: 'git-signing-github',
+          level: signing.code === 0 && identity !== undefined && signing.stdout.includes(identity.split(/\s+/, 3).slice(0, 2).join(' ')) ? 'ok' : 'warn',
+          message: signing.code !== 0
+            ? 'GitHub SSH signing-key registration could not be checked'
+            : signing.stdout.includes(identity?.split(/\s+/, 3).slice(0, 2).join(' ') ?? '')
+              ? '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-'))
+  const sources: DockerMountSource[] = [
+    { label: 'workspace', path: context.workspaceFolder },
+    { label: 'Boxdown devcontainer assets', path: context.assetsDevcontainerDir },
+    { label: 'Boxdown runtime state', path: runtimeProbeDir }
+  ]
+
+  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,87 @@
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import type { WorkspaceContext } from './paths.ts'
+import { runBuffered } from './process.ts'
+
+export type GitSigningReason = 'agent-unavailable' | 'no-identities' | 'ambiguous-identities' | 'configured-key-not-loaded' | 'agent-mount-unavailable'
+
+export interface GitSigningPlan {
+  enabled: boolean
+  reason?: GitSigningReason
+  publicKey?: string
+  agentSocketSource?: string
+}
+
+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 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 (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 })
+}
+
+async function dockerCanMountAgent (source: string): Promise<boolean> {
+  const images = await runBuffered('docker', ['image', 'ls', '--format', '{{.Repository}}:{{.Tag}}'], { mirrorStdout: false, mirrorStderr: false })
+  const image = images.stdout.split(/\r?\n/).map((value) => value.trim()).find((value) => value.length > 0 && value !== '<none>:<none>')
+  if (images.code !== 0 || image === undefined) return false
+
+  const created = await runBuffered('docker', ['create', '--pull=never', '--entrypoint', '/bin/true', '--mount', `type=bind,source=${source},target=/run/boxdown/ssh-agent.sock`, image], { mirrorStdout: false, mirrorStderr: false })
+  const containerId = created.stdout.trim().split(/\r?\n/)[0]
+  if (created.code !== 0 || containerId === undefined || containerId.length === 0) return false
+  await runBuffered('docker', ['rm', '-f', containerId], { mirrorStdout: false, mirrorStderr: false })
+  return true
+}
+
+export async function resolveGitSigningPlan (context: WorkspaceContext): Promise<GitSigningPlan> {
+  const result = await runBuffered('ssh-add', ['-L'], { mirrorStdout: false, mirrorStderr: false })
+  if (result.code !== 0) return { enabled: false, reason: 'agent-unavailable' }
+
+  const identities = result.stdout.split(/\r?\n/)
+  const format = await runBuffered('git', ['config', '--global', '--get', 'gpg.format'], { mirrorStdout: false, mirrorStderr: false })
+  const configuredKey = format.code === 0 && format.stdout.trim() === 'ssh'
+    ? (await runBuffered('git', ['config', '--global', '--get', 'user.signingkey'], { mirrorStdout: false, mirrorStderr: false })).stdout.trim()
+    : undefined
+  let githubKeys: string[] | undefined
+  if (identities.filter((key) => parseSshPublicKey(key) !== undefined).length > 1) {
+    const user = await runBuffered('gh', ['api', 'user', '--jq', '.login'], { mirrorStdout: false, mirrorStderr: false })
+    const login = user.stdout.trim()
+    if (user.code === 0 && login.length > 0) {
+      const github = await runBuffered('gh', ['api', `users/${login}/keys`, '--paginate', '--jq', '.[].key'], { mirrorStdout: false, mirrorStderr: false })
+      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 = process.platform === 'darwin'
+    ? '/run/host-services/ssh-auth.sock'
+    : process.env.SSH_AUTH_SOCK
+  if (agentSocketSource === undefined || agentSocketSource.length === 0) return { enabled: false, reason: 'agent-mount-unavailable' }
+  if (!await dockerCanMountAgent(agentSocketSource)) return { enabled: false, reason: 'agent-mount-unavailable' }
+
+  writeGitSigningPublicKey(context, selected.key)
+  return { enabled: true, publicKey: selected.key, agentSocketSource }
+}