@foundation0/git 1.2.5 → 1.3.1

package/src/issue-dependencies.ts

@@ -1,469 +1,533 @@
-import type { GitServiceApiExecutionResult } from './git-service-api'
-import { spawn } from 'node:child_process'
-import crypto from 'node:crypto'
-
-const DEFAULT_REQUEST_TIMEOUT_MS = 60_000
-
-const parseRequestTimeoutMs = (value: unknown): number | null => {
-  if (typeof value === 'number' && Number.isFinite(value) && value > 0) {
-    return Math.floor(value)
-  }
-  if (typeof value !== 'string') {
-    return null
-  }
-  const trimmed = value.trim()
-  if (!trimmed) return null
-  const parsed = Number(trimmed)
-  if (!Number.isFinite(parsed) || parsed <= 0) return null
-  return Math.floor(parsed)
-}
-
-const resolveRequestTimeoutMs = (): number => {
-  const fromEnv =
-    parseRequestTimeoutMs(process.env.EXAMPLE_GIT_REQUEST_TIMEOUT_MS) ??
-    parseRequestTimeoutMs(process.env.EXAMPLE_HTTP_REQUEST_TIMEOUT_MS) ??
-    parseRequestTimeoutMs(process.env.EXAMPLE_HTTP_TIMEOUT_MS)
-  return fromEnv ?? DEFAULT_REQUEST_TIMEOUT_MS
-}
-
-const canUseAbortSignalTimeout = (): boolean =>
-  typeof AbortSignal !== 'undefined' && typeof (AbortSignal as unknown as { timeout?: unknown }).timeout === 'function'
-
-const isTestRuntime = (): boolean =>
-  Boolean(process.env.VITEST) || process.env.NODE_ENV === 'test'
-
-const resolveHttpTransport = (requested?: string): 'fetch' | 'curl' => {
-  const normalized = (requested ?? '').trim().toLowerCase()
-  if (normalized === 'fetch' || normalized === 'curl') {
-    return normalized
-  }
-
-  const isBun = Boolean(process.versions?.bun)
-  if (!isTestRuntime() && isBun && process.platform === 'win32') {
-    return 'curl'
-  }
-
-  return 'fetch'
-}
-
-const fetchWithTimeout = async (url: string, init: RequestInit): Promise<Response> => {
-  const requestTimeoutMs = resolveRequestTimeoutMs()
-  if (!Number.isFinite(requestTimeoutMs) || requestTimeoutMs <= 0) {
-    return fetch(url, init)
-  }
-
-  const timeoutSignal =
-    requestTimeoutMs > 0 && canUseAbortSignalTimeout()
-      ? (AbortSignal as unknown as { timeout: (ms: number) => AbortSignal }).timeout(requestTimeoutMs)
-      : null
-  const controller = !timeoutSignal ? new AbortController() : null
-  const timeoutId = controller ? setTimeout(() => controller.abort(), requestTimeoutMs) : null
-  try {
-    return await fetch(url, {
-      ...init,
-      ...(timeoutSignal ? { signal: timeoutSignal } : {}),
-      ...(controller ? { signal: controller.signal } : {}),
-    })
-  } catch (error) {
-    if ((timeoutSignal && timeoutSignal.aborted) || controller?.signal.aborted) {
-      throw new Error(`Request timed out after ${requestTimeoutMs}ms: ${init.method ?? 'GET'} ${url}`)
-    }
-    throw error
-  } finally {
-    if (timeoutId) {
-      clearTimeout(timeoutId)
-    }
-  }
-}
-
-const readStream = async (stream: NodeJS.ReadableStream | null): Promise<Buffer> => {
-  if (!stream) return Buffer.from([])
-
-  const chunks: Buffer[] = []
-  for await (const chunk of stream) {
-    if (typeof chunk === 'string') {
-      chunks.push(Buffer.from(chunk))
-    } else {
-      chunks.push(Buffer.from(chunk as ArrayBufferView))
-    }
-  }
-  return Buffer.concat(chunks)
-}
-
-const callCurl = async (
-  requestUrl: string,
-  init: { method: string; headers: Record<string, string>; body?: string },
-  requestTimeoutMs: number,
-): Promise<{ status: number; ok: boolean; bodyText: string }> => {
-  const curlExe = process.platform === 'win32' ? 'curl.exe' : 'curl'
-  const statusToken = crypto.randomBytes(8).toString('hex')
-  const marker = `\n__EXAMPLE_CURL_STATUS_${statusToken}__`
-  const writeOut = `${marker}%{http_code}${marker}`
-
-  const args: string[] = [
-    '--silent',
-    '--show-error',
-    '--location',
-    '--request', init.method,
-    '--write-out', writeOut,
-  ]
-
-  const timeoutSeconds = requestTimeoutMs > 0 ? Math.max(1, Math.ceil(requestTimeoutMs / 1000)) : null
-  if (timeoutSeconds !== null) {
-    args.push('--max-time', String(timeoutSeconds))
-  }
-
-  for (const [name, value] of Object.entries(init.headers)) {
-    args.push('--header', `${name}: ${value}`)
-  }
-
-  if (init.body !== undefined) {
-    args.push('--data-binary', '@-')
-  }
-
-  args.push(requestUrl)
-
-  const child = spawn(curlExe, args, {
-    stdio: ['pipe', 'pipe', 'pipe'],
-    windowsHide: true,
-  })
-
-  if (init.body !== undefined) {
-    child.stdin.write(init.body)
-  }
-  child.stdin.end()
-
-  const [stdoutBytes, stderrBytes] = await Promise.all([
-    readStream(child.stdout),
-    readStream(child.stderr),
-  ])
-
-  const exitCode: number = await new Promise((resolve) => {
-    child.on('close', (code) => resolve(code ?? 0))
-    child.on('error', () => resolve(1))
-  })
-
-  const stdout = stdoutBytes.toString('utf8')
-  const stderr = stderrBytes.toString('utf8').trim()
-
-  if (exitCode !== 0) {
-    const message = stderr || `curl failed with exit code ${exitCode}`
-    if (exitCode === 28 && requestTimeoutMs > 0) {
-      throw new Error(`Request timed out after ${requestTimeoutMs}ms: ${init.method} ${requestUrl}`)
-    }
-    throw new Error(message)
-  }
-
-  const endMarkerIndex = stdout.lastIndexOf(marker)
-  const startMarkerIndex = endMarkerIndex > -1 ? stdout.lastIndexOf(marker, endMarkerIndex - 1) : -1
-  if (startMarkerIndex < 0 || endMarkerIndex < 0) {
-    throw new Error('Failed to parse curl response status code.')
-  }
-
-  const statusText = stdout.slice(startMarkerIndex + marker.length, endMarkerIndex).trim()
-  const status = Number(statusText)
-  const bodyText = stdout.slice(0, startMarkerIndex)
-
-  if (!Number.isFinite(status) || status <= 0) {
-    throw new Error(`Invalid curl status code: ${statusText}`)
-  }
-
-  return {
-    status,
-    ok: status >= 200 && status < 300,
-    bodyText,
-  }
-}
-
-export interface GitIssueDependencyPayload {
-  index: number
-  owner: string
-  repo: string
-}
-
-export interface GitIssueDependencySyncResult {
-  added: number
-  removed: number
-  unchanged: number
-}
-
-type DependencyIssueRecord = {
-  number?: unknown
-  index?: unknown
-  issue?: unknown
-}
-
-const toIssueNumber = (value: unknown): number | null => {
-  const candidate = Number(value)
-  if (!Number.isFinite(candidate) || candidate <= 0 || Math.floor(candidate) !== candidate) {
-    return null
-  }
-  return candidate
-}
-
-const collectFromIssueRecord = (record: Record<string, unknown> | null | undefined): number[] => {
-  const values: number[] = []
-  if (!record) return values
-
-  const direct = toIssueNumber(record.number)
-  if (direct !== null) values.push(direct)
-
-  const fallback = toIssueNumber(record.index)
-  if (fallback !== null) values.push(fallback)
-
-  const issue = record.issue
-  if (issue && typeof issue === 'object' && !Array.isArray(issue)) {
-    const nested = issue as Record<string, unknown>
-    const nestedNumber = toIssueNumber(nested.number)
-    if (nestedNumber !== null) values.push(nestedNumber)
-
-    const nestedIndex = toIssueNumber(nested.index)
-    if (nestedIndex !== null) values.push(nestedIndex)
-  }
-
-  return values
-}
-
-export function extractDependencyIssueNumbers(raw: unknown): number[] {
-  const values: number[] = []
-
-  if (Array.isArray(raw)) {
-    for (const item of raw) {
-      if (!item || typeof item !== 'object' || Array.isArray(item)) {
-        continue
-      }
-
-      const candidate = item as DependencyIssueRecord
-      const direct = toIssueNumber(candidate.number)
-      if (direct !== null) values.push(direct)
-
-      const fallback = toIssueNumber(candidate.index)
-      if (fallback !== null) {
-        values.push(fallback)
-      }
-
-      values.push(...collectFromIssueRecord(candidate))
-    }
-
-    return [...new Set(values)]
-  }
-
-  if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
-    const container = raw as { dependencies?: unknown }
-    if (Array.isArray(container.dependencies)) {
-      return extractDependencyIssueNumbers(container.dependencies)
-    }
-
-    if (Array.isArray((container as { blocks?: unknown }).blocks)) {
-      return extractDependencyIssueNumbers((container as { blocks?: unknown }).blocks)
-    }
-
-    if (Array.isArray((container as { issues?: unknown }).issues)) {
-      return extractDependencyIssueNumbers((container as { issues?: unknown }).issues)
-    }
-
-    return collectFromIssueRecord(container as Record<string, unknown>)
-  }
-
-  return []
-}
-
-const resolveGiteaApiBase = (host: string): string => {
-  const trimmed = host.trim().replace(/\/$/, '')
-  return trimmed.endsWith('/api/v1') ? trimmed : `${trimmed}/api/v1`
-}
-
-const resolveRequiredGiteaHost = (host: string | undefined): string => {
-  const resolved = host?.trim() ?? process.env.GITEA_HOST?.trim()
-  if (!resolved) {
-    throw new Error('GITEA_HOST is required. Pass host explicitly or set process.env.GITEA_HOST.')
-  }
-  return resolved
-}
-
-const buildIssueDependenciesUrl = (host: string, owner: string, repo: string, issueNumber: number): string => {
-  return `${resolveGiteaApiBase(host)}/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/issues/${issueNumber}/dependencies`
-}
-
-export async function callIssueDependenciesApi(
-  method: 'GET' | 'POST' | 'DELETE',
-  owner: string,
-  repo: string,
-  issueNumber: number,
-  host: string | undefined,
-  token: string | undefined,
-  payload?: GitIssueDependencyPayload
-): Promise<GitServiceApiExecutionResult<unknown>> {
-  const resolvedHost = resolveRequiredGiteaHost(host)
-  const requestUrl = buildIssueDependenciesUrl(resolvedHost, owner, repo, issueNumber)
-  const headers = {
-    Accept: 'application/json',
-    ...(token ? { Authorization: `token ${token}` } : {}),
-    ...(payload ? { 'Content-Type': 'application/json' } : {}),
-  }
-
-  const requestTimeoutMs = resolveRequestTimeoutMs()
-  const transport = resolveHttpTransport(process.env.EXAMPLE_GIT_HTTP_TRANSPORT)
-
-  let ok = false
-  let status = 0
-  let parsedBody: unknown = ''
-  let responseText = ''
-
-  if (transport === 'curl') {
-    const result = await callCurl(
-      requestUrl,
-      {
-        method,
-        headers,
-        ...(payload ? { body: JSON.stringify(payload) } : {}),
-      },
-      requestTimeoutMs,
-    )
-    ok = result.ok
-    status = result.status
-    responseText = result.bodyText
-  } else {
-    const response = await fetchWithTimeout(requestUrl, {
-      method,
-      headers,
-      body: payload ? JSON.stringify(payload) : undefined,
-    })
-    ok = response.ok
-    status = response.status
-    responseText = await response.text()
-  }
-
-  parsedBody = responseText
-  try {
-    parsedBody = JSON.parse(responseText)
-  } catch {
-    // keep raw text
-  }
-
-  return {
-    ok,
-    status,
-    body: parsedBody,
-    mapping: {
-      featurePath: ['issue', 'dependencies'],
-      mappedPath: ['issue', 'dependencies'],
-      method,
-      query: [],
-      headers: [],
-      apiBase: resolveGiteaApiBase(resolvedHost),
-      swaggerPath: '/repos/{owner}/{repo}/issues/{index}/dependencies',
-      mapped: true,
-    },
-    request: {
-      url: requestUrl,
-      method,
-      headers: {
-        Accept: 'application/json',
-        ...(payload ? { 'Content-Type': 'application/json' } : {}),
-      },
-      query: [],
-      body: payload,
-    },
-    response: {
-      headers: {},
-    },
-  }
-}
-
-export async function syncIssueDependencies(
-  owner: string,
-  repo: string,
-  issueNumber: number,
-  desiredDependencyIssueNumbers: number[],
-  host: string | undefined,
-  token: string | undefined,
-  dryRun: boolean,
-  log?: ((message: string) => void) | null
-): Promise<GitIssueDependencySyncResult> {
-  const existingResult = await callIssueDependenciesApi('GET', owner, repo, issueNumber, host, token)
-  if (!existingResult.ok) {
-    throw new Error(
-      `Failed to load issue dependencies for #${issueNumber}: status=${existingResult.status} url=${existingResult.request.url}`
-    )
-  }
-
-  const existing = extractDependencyIssueNumbers(existingResult.body)
-  const desired = [...new Set(desiredDependencyIssueNumbers.filter((value): value is number => value > 0))]
-  const existingSet = new Set(existing)
-  const desiredSet = new Set(desired)
-  const toAdd = desired.filter((value) => !existingSet.has(value))
-  const toRemove = existing.filter((value) => !desiredSet.has(value))
-  const unchanged = desired.filter((value) => existingSet.has(value)).length
-
-  if (log) {
-    if (toAdd.length > 0 || toRemove.length > 0) {
-      log(`Issue #${issueNumber}: dependency sync [add=${toAdd.join(',') || 'none'}, remove=${toRemove.join(',') || 'none'}]`)
-    } else {
-      log(`Issue #${issueNumber}: dependency sync already correct`)
-    }
-  }
-
-  let added = 0
-  let removed = 0
-
-  if (!dryRun) {
-    for (const dep of toRemove) {
-      const removedResult = await callIssueDependenciesApi(
-        'DELETE',
-        owner,
-        repo,
-        issueNumber,
-        host,
-        token,
-        { index: dep, owner, repo },
-      )
-      if (!removedResult.ok) {
-        throw new Error(
-          `Failed to remove dependency ${dep} from issue #${issueNumber}: status=${removedResult.status} url=${removedResult.request.url}`
-        )
-      }
-      removed += 1
-    }
-
-    for (const dep of toAdd) {
-      const addedResult = await callIssueDependenciesApi(
-        'POST',
-        owner,
-        repo,
-        issueNumber,
-        host,
-        token,
-        { index: dep, owner, repo },
-      )
-      if (!addedResult.ok) {
-        throw new Error(
-          `Failed to add dependency ${dep} to issue #${issueNumber}: status=${addedResult.status} url=${addedResult.request.url}`
-        )
-      }
-      added += 1
-    }
-
-    const verifyResult = await callIssueDependenciesApi('GET', owner, repo, issueNumber, host, token)
-    if (!verifyResult.ok) {
-      throw new Error(
-        `Failed to verify dependencies for issue #${issueNumber}: status=${verifyResult.status} url=${verifyResult.request.url}`
-      )
-    }
-
-    const verified = extractDependencyIssueNumbers(verifyResult.body)
-    const verifiedSet = new Set(verified)
-    const missing = desired.filter((value) => !verifiedSet.has(value))
-    if (missing.length > 0) {
-      throw new Error(
-        `Dependency sync mismatch for issue #${issueNumber}. Missing dependencies: ${missing.join(', ')}`
-      )
-    }
-  }
-
-  return {
-    added,
-    removed,
-    unchanged,
-  }
-}
+import type { GitServiceApiExecutionResult } from './git-service-api'
+import { spawn } from 'node:child_process'
+import crypto from 'node:crypto'
+
+const DEFAULT_REQUEST_TIMEOUT_MS = 60_000
+
+const parseRequestTimeoutMs = (value: unknown): number | null => {
+  if (typeof value === 'number' && Number.isFinite(value) && value > 0) {
+    return Math.floor(value)
+  }
+  if (typeof value !== 'string') {
+    return null
+  }
+  const trimmed = value.trim()
+  if (!trimmed) return null
+  const parsed = Number(trimmed)
+  if (!Number.isFinite(parsed) || parsed <= 0) return null
+  return Math.floor(parsed)
+}
+
+const resolveRequestTimeoutMs = (): number => {
+  const fromEnv =
+    parseRequestTimeoutMs(process.env.EXAMPLE_GIT_REQUEST_TIMEOUT_MS) ??
+    parseRequestTimeoutMs(process.env.EXAMPLE_HTTP_REQUEST_TIMEOUT_MS) ??
+    parseRequestTimeoutMs(process.env.EXAMPLE_HTTP_TIMEOUT_MS)
+  return fromEnv ?? DEFAULT_REQUEST_TIMEOUT_MS
+}
+
+const canUseAbortSignalTimeout = (): boolean =>
+  typeof AbortSignal !== 'undefined' && typeof (AbortSignal as unknown as { timeout?: unknown }).timeout === 'function'
+
+const isTestRuntime = (): boolean =>
+  Boolean(process.env.VITEST) || process.env.NODE_ENV === 'test'
+
+const resolveHttpTransport = (requested?: string): 'fetch' | 'curl' => {
+  const normalized = (requested ?? '').trim().toLowerCase()
+  if (normalized === 'fetch' || normalized === 'curl') {
+    return normalized
+  }
+
+  const isBun = Boolean(process.versions?.bun)
+  if (!isTestRuntime() && isBun && process.platform === 'win32') {
+    return 'curl'
+  }
+
+  return 'fetch'
+}
+
+const fetchWithTimeout = async (url: string, init: RequestInit): Promise<Response> => {
+  const requestTimeoutMs = resolveRequestTimeoutMs()
+  if (!Number.isFinite(requestTimeoutMs) || requestTimeoutMs <= 0) {
+    return fetch(url, init)
+  }
+
+  const timeoutSignal =
+    requestTimeoutMs > 0 && canUseAbortSignalTimeout()
+      ? (AbortSignal as unknown as { timeout: (ms: number) => AbortSignal }).timeout(requestTimeoutMs)
+      : null
+  const controller = !timeoutSignal ? new AbortController() : null
+  const timeoutId = controller ? setTimeout(() => controller.abort(), requestTimeoutMs) : null
+  try {
+    return await fetch(url, {
+      ...init,
+      ...(timeoutSignal ? { signal: timeoutSignal } : {}),
+      ...(controller ? { signal: controller.signal } : {}),
+    })
+  } catch (error) {
+    if ((timeoutSignal && timeoutSignal.aborted) || controller?.signal.aborted) {
+      throw new Error(`Request timed out after ${requestTimeoutMs}ms: ${init.method ?? 'GET'} ${url}`)
+    }
+    throw error
+  } finally {
+    if (timeoutId) {
+      clearTimeout(timeoutId)
+    }
+  }
+}
+
+const readStream = async (stream: NodeJS.ReadableStream | null): Promise<Buffer> => {
+  if (!stream) return Buffer.from([])
+
+  return await new Promise<Buffer>((resolve) => {
+    const chunks: Buffer[] = []
+    let settled = false
+
+    const cleanup = () => {
+      stream.removeListener('data', onData)
+      stream.removeListener('end', onDone)
+      stream.removeListener('close', onDone)
+      stream.removeListener('error', onDone)
+    }
+
+    const settle = () => {
+      if (settled) return
+      settled = true
+      cleanup()
+      resolve(Buffer.concat(chunks))
+    }
+
+    const onDone = () => settle()
+
+    const onData = (chunk: unknown) => {
+      try {
+        if (typeof chunk === 'string') {
+          chunks.push(Buffer.from(chunk))
+          return
+        }
+
+        chunks.push(Buffer.from(chunk as ArrayBufferView))
+      } catch {
+        // best effort
+      }
+    }
+
+    stream.on('data', onData)
+    stream.on('end', onDone)
+    stream.on('close', onDone)
+    stream.on('error', onDone)
+  })
+}
+
+const callCurl = async (
+  requestUrl: string,
+  init: { method: string; headers: Record<string, string>; body?: string },
+  requestTimeoutMs: number,
+): Promise<{ status: number; ok: boolean; bodyText: string }> => {
+  const curlExe = process.platform === 'win32' ? 'curl.exe' : 'curl'
+  const statusToken = crypto.randomBytes(8).toString('hex')
+  const marker = `\n__EXAMPLE_CURL_STATUS_${statusToken}__`
+  const writeOut = `${marker}%{http_code}${marker}`
+
+  const args: string[] = [
+    '--silent',
+    '--show-error',
+    '--location',
+    '--request', init.method,
+    '--write-out', writeOut,
+  ]
+
+  const timeoutSeconds = requestTimeoutMs > 0 ? Math.max(1, Math.ceil(requestTimeoutMs / 1000)) : null
+  if (timeoutSeconds !== null) {
+    args.push('--max-time', String(timeoutSeconds))
+    args.push('--connect-timeout', String(Math.max(1, Math.min(30, timeoutSeconds))))
+  }
+
+  for (const [name, value] of Object.entries(init.headers)) {
+    args.push('--header', `${name}: ${value}`)
+  }
+
+  if (init.body !== undefined) {
+    args.push('--data-binary', '@-')
+  }
+
+  args.push(requestUrl)
+
+  const child = spawn(curlExe, args, {
+    stdio: ['pipe', 'pipe', 'pipe'],
+    windowsHide: true,
+  })
+
+  const hardTimeoutMs = requestTimeoutMs > 0 ? requestTimeoutMs + 2_000 : null
+  let hardTimedOut = false
+  const hardTimeoutId = hardTimeoutMs
+    ? setTimeout(() => {
+        hardTimedOut = true
+        try {
+          child.kill()
+        } catch {
+          // best effort
+        }
+        try {
+          child.stdout?.destroy()
+        } catch {
+          // best effort
+        }
+        try {
+          child.stderr?.destroy()
+        } catch {
+          // best effort
+        }
+      }, hardTimeoutMs)
+    : null
+
+  if (init.body !== undefined) {
+    child.stdin.write(init.body)
+  }
+  child.stdin.end()
+
+  const stdoutPromise = readStream(child.stdout)
+  const stderrPromise = readStream(child.stderr)
+
+  let exitCode: number
+  try {
+    exitCode = await new Promise((resolve) => {
+      child.on('close', (code) => resolve(code ?? 0))
+      child.on('error', () => resolve(1))
+    })
+  } finally {
+    if (hardTimeoutId) {
+      clearTimeout(hardTimeoutId)
+    }
+  }
+
+  const [stdoutBytes, stderrBytes] = await Promise.all([stdoutPromise, stderrPromise])
+
+  if (hardTimedOut && requestTimeoutMs > 0) {
+    throw new Error(`Request timed out after ${requestTimeoutMs}ms: ${init.method} ${requestUrl}`)
+  }
+
+  const stdout = stdoutBytes.toString('utf8')
+  const stderr = stderrBytes.toString('utf8').trim()
+
+  if (exitCode !== 0) {
+    const message = stderr || `curl failed with exit code ${exitCode}`
+    if (exitCode === 28 && requestTimeoutMs > 0) {
+      throw new Error(`Request timed out after ${requestTimeoutMs}ms: ${init.method} ${requestUrl}`)
+    }
+    throw new Error(message)
+  }
+
+  const endMarkerIndex = stdout.lastIndexOf(marker)
+  const startMarkerIndex = endMarkerIndex > -1 ? stdout.lastIndexOf(marker, endMarkerIndex - 1) : -1
+  if (startMarkerIndex < 0 || endMarkerIndex < 0) {
+    throw new Error('Failed to parse curl response status code.')
+  }
+
+  const statusText = stdout.slice(startMarkerIndex + marker.length, endMarkerIndex).trim()
+  const status = Number(statusText)
+  const bodyText = stdout.slice(0, startMarkerIndex)
+
+  if (!Number.isFinite(status) || status <= 0) {
+    throw new Error(`Invalid curl status code: ${statusText}`)
+  }
+
+  return {
+    status,
+    ok: status >= 200 && status < 300,
+    bodyText,
+  }
+}
+
+export interface GitIssueDependencyPayload {
+  index: number
+  owner: string
+  repo: string
+}
+
+export interface GitIssueDependencySyncResult {
+  added: number
+  removed: number
+  unchanged: number
+}
+
+type DependencyIssueRecord = {
+  number?: unknown
+  index?: unknown
+  issue?: unknown
+}
+
+const toIssueNumber = (value: unknown): number | null => {
+  const candidate = Number(value)
+  if (!Number.isFinite(candidate) || candidate <= 0 || Math.floor(candidate) !== candidate) {
+    return null
+  }
+  return candidate
+}
+
+const collectFromIssueRecord = (record: Record<string, unknown> | null | undefined): number[] => {
+  const values: number[] = []
+  if (!record) return values
+
+  const direct = toIssueNumber(record.number)
+  if (direct !== null) values.push(direct)
+
+  const fallback = toIssueNumber(record.index)
+  if (fallback !== null) values.push(fallback)
+
+  const issue = record.issue
+  if (issue && typeof issue === 'object' && !Array.isArray(issue)) {
+    const nested = issue as Record<string, unknown>
+    const nestedNumber = toIssueNumber(nested.number)
+    if (nestedNumber !== null) values.push(nestedNumber)
+
+    const nestedIndex = toIssueNumber(nested.index)
+    if (nestedIndex !== null) values.push(nestedIndex)
+  }
+
+  return values
+}
+
+export function extractDependencyIssueNumbers(raw: unknown): number[] {
+  const values: number[] = []
+
+  if (Array.isArray(raw)) {
+    for (const item of raw) {
+      if (!item || typeof item !== 'object' || Array.isArray(item)) {
+        continue
+      }
+
+      const candidate = item as DependencyIssueRecord
+      const direct = toIssueNumber(candidate.number)
+      if (direct !== null) values.push(direct)
+
+      const fallback = toIssueNumber(candidate.index)
+      if (fallback !== null) {
+        values.push(fallback)
+      }
+
+      values.push(...collectFromIssueRecord(candidate))
+    }
+
+    return [...new Set(values)]
+  }
+
+  if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+    const container = raw as { dependencies?: unknown }
+    if (Array.isArray(container.dependencies)) {
+      return extractDependencyIssueNumbers(container.dependencies)
+    }
+
+    if (Array.isArray((container as { blocks?: unknown }).blocks)) {
+      return extractDependencyIssueNumbers((container as { blocks?: unknown }).blocks)
+    }
+
+    if (Array.isArray((container as { issues?: unknown }).issues)) {
+      return extractDependencyIssueNumbers((container as { issues?: unknown }).issues)
+    }
+
+    return collectFromIssueRecord(container as Record<string, unknown>)
+  }
+
+  return []
+}
+
+const resolveGiteaApiBase = (host: string): string => {
+  const trimmed = host.trim().replace(/\/$/, '')
+  return trimmed.endsWith('/api/v1') ? trimmed : `${trimmed}/api/v1`
+}
+
+const resolveRequiredGiteaHost = (host: string | undefined): string => {
+  const resolved = host?.trim() ?? process.env.GITEA_HOST?.trim()
+  if (!resolved) {
+    throw new Error('GITEA_HOST is required. Pass host explicitly or set process.env.GITEA_HOST.')
+  }
+  return resolved
+}
+
+const buildIssueDependenciesUrl = (host: string, owner: string, repo: string, issueNumber: number): string => {
+  return `${resolveGiteaApiBase(host)}/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/issues/${issueNumber}/dependencies`
+}
+
+export async function callIssueDependenciesApi(
+  method: 'GET' | 'POST' | 'DELETE',
+  owner: string,
+  repo: string,
+  issueNumber: number,
+  host: string | undefined,
+  token: string | undefined,
+  payload?: GitIssueDependencyPayload
+): Promise<GitServiceApiExecutionResult<unknown>> {
+  const resolvedHost = resolveRequiredGiteaHost(host)
+  const requestUrl = buildIssueDependenciesUrl(resolvedHost, owner, repo, issueNumber)
+  const headers = {
+    Accept: 'application/json',
+    ...(token ? { Authorization: `token ${token}` } : {}),
+    ...(payload ? { 'Content-Type': 'application/json' } : {}),
+  }
+
+  const requestTimeoutMs = resolveRequestTimeoutMs()
+  const transport = resolveHttpTransport(process.env.EXAMPLE_GIT_HTTP_TRANSPORT)
+
+  let ok = false
+  let status = 0
+  let parsedBody: unknown = ''
+  let responseText = ''
+
+  if (transport === 'curl') {
+    const result = await callCurl(
+      requestUrl,
+      {
+        method,
+        headers,
+        ...(payload ? { body: JSON.stringify(payload) } : {}),
+      },
+      requestTimeoutMs,
+    )
+    ok = result.ok
+    status = result.status
+    responseText = result.bodyText
+  } else {
+    const response = await fetchWithTimeout(requestUrl, {
+      method,
+      headers,
+      body: payload ? JSON.stringify(payload) : undefined,
+    })
+    ok = response.ok
+    status = response.status
+    responseText = await response.text()
+  }
+
+  parsedBody = responseText
+  try {
+    parsedBody = JSON.parse(responseText)
+  } catch {
+    // keep raw text
+  }
+
+  return {
+    ok,
+    status,
+    body: parsedBody,
+    mapping: {
+      featurePath: ['issue', 'dependencies'],
+      mappedPath: ['issue', 'dependencies'],
+      method,
+      query: [],
+      headers: [],
+      apiBase: resolveGiteaApiBase(resolvedHost),
+      swaggerPath: '/repos/{owner}/{repo}/issues/{index}/dependencies',
+      mapped: true,
+    },
+    request: {
+      url: requestUrl,
+      method,
+      headers: {
+        Accept: 'application/json',
+        ...(payload ? { 'Content-Type': 'application/json' } : {}),
+      },
+      query: [],
+      body: payload,
+    },
+    response: {
+      headers: {},
+    },
+  }
+}
+
+export async function syncIssueDependencies(
+  owner: string,
+  repo: string,
+  issueNumber: number,
+  desiredDependencyIssueNumbers: number[],
+  host: string | undefined,
+  token: string | undefined,
+  dryRun: boolean,
+  log?: ((message: string) => void) | null
+): Promise<GitIssueDependencySyncResult> {
+  const existingResult = await callIssueDependenciesApi('GET', owner, repo, issueNumber, host, token)
+  if (!existingResult.ok) {
+    throw new Error(
+      `Failed to load issue dependencies for #${issueNumber}: status=${existingResult.status} url=${existingResult.request.url}`
+    )
+  }
+
+  const existing = extractDependencyIssueNumbers(existingResult.body)
+  const desired = [...new Set(desiredDependencyIssueNumbers.filter((value): value is number => value > 0))]
+  const existingSet = new Set(existing)
+  const desiredSet = new Set(desired)
+  const toAdd = desired.filter((value) => !existingSet.has(value))
+  const toRemove = existing.filter((value) => !desiredSet.has(value))
+  const unchanged = desired.filter((value) => existingSet.has(value)).length
+
+  if (log) {
+    if (toAdd.length > 0 || toRemove.length > 0) {
+      log(`Issue #${issueNumber}: dependency sync [add=${toAdd.join(',') || 'none'}, remove=${toRemove.join(',') || 'none'}]`)
+    } else {
+      log(`Issue #${issueNumber}: dependency sync already correct`)
+    }
+  }
+
+  let added = 0
+  let removed = 0
+
+  if (!dryRun) {
+    for (const dep of toRemove) {
+      const removedResult = await callIssueDependenciesApi(
+        'DELETE',
+        owner,
+        repo,
+        issueNumber,
+        host,
+        token,
+        { index: dep, owner, repo },
+      )
+      if (!removedResult.ok) {
+        throw new Error(
+          `Failed to remove dependency ${dep} from issue #${issueNumber}: status=${removedResult.status} url=${removedResult.request.url}`
+        )
+      }
+      removed += 1
+    }
+
+    for (const dep of toAdd) {
+      const addedResult = await callIssueDependenciesApi(
+        'POST',
+        owner,
+        repo,
+        issueNumber,
+        host,
+        token,
+        { index: dep, owner, repo },
+      )
+      if (!addedResult.ok) {
+        throw new Error(
+          `Failed to add dependency ${dep} to issue #${issueNumber}: status=${addedResult.status} url=${addedResult.request.url}`
+        )
+      }
+      added += 1
+    }
+
+    const verifyResult = await callIssueDependenciesApi('GET', owner, repo, issueNumber, host, token)
+    if (!verifyResult.ok) {
+      throw new Error(
+        `Failed to verify dependencies for issue #${issueNumber}: status=${verifyResult.status} url=${verifyResult.request.url}`
+      )
+    }
+
+    const verified = extractDependencyIssueNumbers(verifyResult.body)
+    const verifiedSet = new Set(verified)
+    const missing = desired.filter((value) => !verifiedSet.has(value))
+    if (missing.length > 0) {
+      throw new Error(
+        `Dependency sync mismatch for issue #${issueNumber}. Missing dependencies: ${missing.join(', ')}`
+      )
+    }
+  }
+
+  return {
+    added,
+    removed,
+    unchanged,
+  }
+}