@dsh-cove/dsh-web-all 0.0.0-stage → 0.4.3

package/src/host/services/web-search-anthropic/provider.ts

@@ -0,0 +1,325 @@
+/**
+ * Anthropic 兼容 Messages 搜索 provider（只补响应解析）。
+ *
+ * 一次搜索 = 一次 Messages 请求 + 原生 `web_search_20250305` 服务端工具：代价是
+ * 一个模型回合，回报是结构化结果。相对官方 provider 的唯一差别是**响应归一化**：
+ * 本 provider 同时接受标准 Anthropic 形状（`web_search_tool_result` 条目 + citation
+ * 摘录）与只有 citation 的形状（`server_tool_use` + `text.citations[]`，Bedrock 系
+ * 上游的表现），并在「模型只是申请调用客户端工具」时给出可操作的报错，而不是假装
+ * 搜到了东西。
+ *
+ * 配置不在本域：每次搜索都从官方设置条目现读（见 contracts 的
+ * `searchConfigFrom`），所以用户改的还是原来那个 Web search 配置面，
+ * 热更新立即生效，无需重挂插件。
+ *
+ * @module web-all/host/services/web-search-anthropic
+ */
+
+import {
+  WebSearchError,
+  WEB_SEARCH_ANTHROPIC_PROVIDER_ID,
+  type SearchConfig,
+  type WebSearchProvider,
+  type WebSearchRequest,
+  type WebSearchResult,
+  type WebSearchSource,
+} from './contracts.ts'
+
+/** 归因头；与 provider 行为一起演进。 */
+const USER_AGENT = 'dsh-web-all/web-search-anthropic'
+
+/** 一次引用位置；只有 citation 的形状把命中信息全放在这里。 */
+export interface CitationLocation {
+  type?: string
+  url?: string | null
+  title?: string | null
+  cited_text?: string | null
+}
+
+/** 一个内容块；只消费下方注释里列出的几种。 */
+export interface ContentBlock {
+  type?: string
+  text?: string | null
+  name?: string | null
+  citations?: readonly CitationLocation[] | null
+  /** `web_search_tool_result` 的载荷：条目数组，或一个错误对象。 */
+  content?: unknown
+}
+
+/** `web_search_tool_result` 里的一个可引用条目。 */
+export interface SearchResultItem {
+  type?: string
+  url?: string | null
+  title?: string | null
+  page_age?: string | null
+}
+
+/** Anthropic Messages 响应信封（best-effort；字段随上游而变）。 */
+export interface AnthropicResponse {
+  content?: readonly ContentBlock[] | null
+  stop_reason?: string | null
+  usage?: { server_tool_use?: { web_search_requests?: number | null } | null } | null
+}
+
+/** 归一化结果：来源 + 用于诊断的检索事实。 */
+export interface MappedSearchResponse {
+  sources: readonly WebSearchSource[]
+  /** 端点侧实际执行的服务端搜索次数（0 表示没搜）。 */
+  searches: number
+  /** 响应里有 `tool_use(web_search)`：模型申请调用客户端工具，端点没执行搜索。 */
+  clientToolUse: boolean
+  /** `web_search_tool_result` 自带的错误码（有则整体失败）。 */
+  resultError?: string
+}
+
+/** 一次搜索的运行期选项快照：配置 + 凭据解析面（测试可注入 fetch）。 */
+export interface AnthropicMessagesSearchProviderOptions extends SearchConfig {
+  /** 字面 key；存在时优先于 {@link resolveApiKey}。 */
+  apiKey?: string
+  /** 每次搜索解析一次当前 key（凭据服务 / 启动环境）。 */
+  resolveApiKey?: () => Promise<string | undefined>
+  /** 注入的 fetch，测试用。 */
+  fetchImpl?: typeof fetch
+}
+
+/** 收集每个 URL 的 citation 摘录（首次出现优先）；标准形状下它才是 snippet 来源。 */
+export function citationSnippets(blocks: readonly ContentBlock[]): Map<string, string> {
+  const map = new Map<string, string>()
+  for (const block of blocks) {
+    if (block.type !== 'text') continue
+    for (const cite of block.citations ?? []) {
+      const url = cite.url ?? ''
+      const text = cite.cited_text ?? ''
+      if (url !== '' && text !== '' && !map.has(url)) map.set(url, text)
+    }
+  }
+  return map
+}
+
+/** 读出 `web_search_tool_result` 自带的错误（载荷是对象而非数组时）。 */
+function resultErrorOf(block: ContentBlock): string | undefined {
+  const payload = block.content
+  if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) return undefined
+  const record = payload as { type?: unknown; error_code?: unknown }
+  if (record.error_code === undefined || record.error_code === null) return undefined
+  return `${String(record.type ?? 'web_search_tool_result_error')}: ${String(record.error_code)}`
+}
+
+/**
+ * 把两种 Anthropic 兼容响应形状统一成 seam 的 `sources[]`。
+ *
+ * 顺序：先走标准结果块（带 `page_age` 与条目级字段），拿不到任何条目时再回落到
+ * citation —— 只有 citation 的上游永远走第二条分支；两条分支都用同一张 citation
+ * 摘录表补 `snippet`，按 URL 去重（`max_uses > 1` 时同一 URL 可能多次出现）。
+ *
+ * @param response - 解析后的 Messages 响应体。
+ * @returns 归一化结果；`searches`/`clientToolUse`/`resultError` 供诊断使用。
+ */
+export function mapSearchResponse(response: AnthropicResponse): MappedSearchResponse {
+  const blocks = response.content ?? []
+  const searches = response.usage?.server_tool_use?.web_search_requests
+    ?? blocks.filter(block => block.type === 'server_tool_use' && block.name === 'web_search').length
+  const clientToolUse = blocks.some(block => block.type === 'tool_use' && block.name === 'web_search')
+  const resultError = blocks.filter(block => block.type === 'web_search_tool_result')
+    .map(resultErrorOf)
+    .find(error => error !== undefined)
+
+  const snippets = citationSnippets(blocks)
+  const sources: WebSearchSource[] = []
+  const seen = new Set<string>()
+  const add = (url: string | null | undefined, title: string | null | undefined, snippet: string | null | undefined, publishedAt?: string | null): void => {
+    const value = url ?? ''
+    if (value === '' || seen.has(value)) return
+    seen.add(value)
+    sources.push({
+      url: value,
+      ...title !== null && title !== undefined && title !== '' ? { title } : {},
+      ...snippet !== null && snippet !== undefined && snippet !== '' ? { snippet } : {},
+      ...publishedAt !== null && publishedAt !== undefined && publishedAt !== '' ? { publishedAt } : {},
+    })
+  }
+
+  for (const block of blocks) {
+    if (block.type !== 'web_search_tool_result' || !Array.isArray(block.content)) continue
+    for (const item of block.content as SearchResultItem[]) {
+      if (item?.type !== 'web_search_result') continue
+      const url = item.url ?? ''
+      add(url, item.title, snippets.get(url), item.page_age)
+    }
+  }
+
+  if (sources.length === 0) {
+    for (const block of blocks) {
+      if (block.type !== 'text') continue
+      for (const cite of block.citations ?? []) add(cite.url, cite.title, cite.cited_text)
+    }
+  }
+
+  return {
+    sources,
+    searches,
+    clientToolUse,
+    ...resultError !== undefined ? { resultError } : {},
+  }
+}
+
+/** 去掉尾斜杠，避免 `baseURL` 以 `/` 结尾时拼出 `//messages`。 */
+function trimTrailingSlash(value: string): string {
+  return value.endsWith('/') ? value.replace(/\/+$/u, '') : value
+}
+
+/** 端点与配置引导：把「这是配置问题、改哪里」写进错误里（指向官方那套配置面）。 */
+function endpointHint(endpoint: string): string {
+  return `\n\nThe web search request used endpoint ${JSON.stringify(endpoint)}. Search endpoint configuration is separate from chat: guide the user to Plugins > Built-in plugin settings > Web search, where they can change and save the Messages API base URL, the model, and the credential reference. Only the user should choose or change the endpoint.`
+}
+
+/** 端点没执行搜索时的可操作报错：区分「模型申请客户端工具」与「搜了但没结果」。 */
+function noResultError(mapped: MappedSearchResponse, config: SearchConfig): WebSearchError {
+  if (mapped.clientToolUse) {
+    return new WebSearchError(
+      `The endpoint returned a client-side tool_use(web_search) instead of executing the search itself, so model ${JSON.stringify(config.model)} has no web search results. `
+      + 'Native server-side web_search_20250305 is an Anthropic-model feature: on a multi-vendor gateway pick a Claude model, because DeepSeek/Gemini routes reply with a client tool call. '
+      + 'The model comes from the Web search settings, not from this plugin.',
+      'WEB_PROVIDER_ERROR',
+    )
+  }
+  if (mapped.searches === 0) {
+    return new WebSearchError(
+      `The endpoint executed no server-side web search for model ${JSON.stringify(config.model)} and returned no citeable sources; the request may not have triggered native web search.`,
+      'WEB_PROVIDER_ERROR',
+    )
+  }
+  return new WebSearchError(
+    `The endpoint executed ${mapped.searches} server-side web search(es) but returned no citeable sources.`,
+    'WEB_PROVIDER_ERROR',
+  )
+}
+
+/** 用 Anthropic 兼容 Messages 端点做检索的 provider。 */
+export class AnthropicMessagesSearchProvider implements WebSearchProvider {
+  readonly id = WEB_SEARCH_ANTHROPIC_PROVIDER_ID
+  private readonly resolveConfig: () => SearchConfig | undefined
+  private readonly resolveKey: () => Promise<string | undefined>
+  private readonly fetchImpl: typeof fetch | undefined
+
+  /**
+   * @param resolveConfig - 下一次操作的配置；thunk 而非快照，官方设置条目的热更新
+   * 因此每次搜索都生效，而不必重注册 provider（重注册会让 seam 的选择对用户可见地抖动）。
+   * @param resolveKey - 解析字面 key / 凭据服务 / 启动环境，每次搜索调用一次。
+   * @param fetchImpl - 注入的 fetch，测试用。
+   */
+  constructor(
+    resolveConfig: () => SearchConfig | undefined,
+    resolveKey: () => Promise<string | undefined>,
+    fetchImpl?: typeof fetch,
+  ) {
+    this.resolveConfig = resolveConfig
+    this.resolveKey = resolveKey
+    this.fetchImpl = fetchImpl
+  }
+
+  available(): boolean {
+    const config = this.resolveConfig()
+    return config !== undefined
+      && URL.canParse(config.baseURL)
+      && config.model !== ''
+      && Number.isInteger(config.maxTokens) && config.maxTokens > 0
+      && Number.isInteger(config.maxUses) && config.maxUses > 0
+  }
+
+  async search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult> {
+    const config = this.resolveConfig()
+    if (config === undefined) throw missingConfigError()
+    // 读经函数而非直接比属性：TS 会把 `signal?.aborted === true` 早退后的属性
+    // 窄化成 false，后续再判同一属性就成了「无重叠比较」。
+    const isAborted = (): boolean => signal?.aborted === true
+    const endpoint = `${trimTrailingSlash(config.baseURL)}/messages`
+    const apiKey = await this.apiKey(config, signal)
+    if (isAborted()) throw abortedError()
+
+    const body = {
+      model: config.model,
+      max_tokens: config.maxTokens,
+      messages: [{
+        role: 'user',
+        content: [{ type: 'text', text: `Perform a web search for the query: ${request.query}` }],
+      }],
+      tools: [{ type: 'web_search_20250305', name: 'web_search', max_uses: config.maxUses }],
+    }
+
+    const doFetch = this.fetchImpl ?? fetch
+    let response: Response
+    try {
+      response = await doFetch(endpoint, {
+        method: 'POST',
+        redirect: 'error',
+        headers: {
+          'x-api-key': apiKey,
+          'authorization': `Bearer ${apiKey}`,
+          'anthropic-version': config.apiVersion,
+          'content-type': 'application/json',
+          'accept': 'application/json',
+          'user-agent': USER_AGENT,
+        },
+        body: JSON.stringify(body),
+        ...signal === undefined ? {} : { signal },
+      })
+    } catch (error) {
+      if (isAborted()) throw abortedError()
+      throw new WebSearchError(`Web search request failed: ${String(error)}.${endpointHint(endpoint)}`, 'WEB_PROVIDER_ERROR')
+    }
+
+    if (!response.ok) {
+      let detail = ''
+      try {
+        const parsed = await response.json() as { error?: { message?: string } | string; message?: string }
+        detail = typeof parsed.error === 'string' ? parsed.error : parsed.error?.message ?? parsed.message ?? ''
+      } catch {
+        // 非 JSON 错误体：状态码已经足够定位。
+      }
+      const message = `Web search endpoint error (HTTP ${response.status})${detail === '' ? '' : `: ${detail}`}`
+      throw new WebSearchError(`${message}${endpointHint(endpoint)}`, 'WEB_PROVIDER_ERROR')
+    }
+
+    let mapped: MappedSearchResponse
+    try {
+      mapped = mapSearchResponse(await response.json() as AnthropicResponse)
+    } catch (error) {
+      throw new WebSearchError(`Web search returned an unprocessable response body: ${String(error)}`, 'WEB_PROVIDER_ERROR')
+    }
+
+    if (mapped.resultError !== undefined) {
+      throw new WebSearchError(`The endpoint's web search failed: ${mapped.resultError}.`, 'WEB_PROVIDER_ERROR')
+    }
+    if (mapped.sources.length === 0) throw noResultError(mapped, config)
+
+    return { sources: mapped.sources, truncated: false }
+  }
+
+  /** 解析一次操作的 key：调用方给的解析器（字面 key → 凭据服务 → 环境变量）。 */
+  private async apiKey(config: SearchConfig, signal?: AbortSignal): Promise<string> {
+    if (signal?.aborted === true) throw abortedError()
+    const resolved = await this.resolveKey()
+    if (resolved !== undefined && resolved.length > 0) return resolved
+    const ref = config.apiKeyEnv === '' ? 'the configured credential reference' : config.apiKeyEnv
+    throw new WebSearchError(
+      `Web search has no API key for "${ref}"; store it through the credentials service, export it in the launching environment, `
+      + 'or set the credential reference in the Web search settings.',
+      'WEB_PROVIDER_CREDENTIAL_MISSING',
+    )
+  }
+}
+
+/** 配置缺失：设置条目读不到、或基址/模型为空。 */
+function missingConfigError(): WebSearchError {
+  return new WebSearchError(
+    'Web search is pinned to the anthropic-messages provider, but no Messages API base URL and model are configured. '
+    + 'Guide the user to Plugins > Built-in plugin settings > Web search and set the Messages API base URL, the model, and the credential reference.',
+    'WEB_PROVIDER_CREDENTIAL_MISSING',
+  )
+}
+
+/** 调用方取消：与原生 provider 的 `WEB_ABORTED` 对齐。 */
+function abortedError(): WebSearchError {
+  return new WebSearchError('Web search aborted', 'WEB_ABORTED')
+}

package/src/host/services/worktree/git-runner.ts

@@ -0,0 +1,124 @@
+// Generated by scripts/sync-shared.mjs from shared/host/git-runner.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+/**
+ * Shared host git subprocess plumbing: the run result shape, the runner seam,
+ * the collected-output cap, and the production runner over the subprocess
+ * service. Packages receive this file as a generated copy via
+ * scripts/sync-shared.mjs; edit the shared source and re-run the sync instead
+ * of editing a copy.
+ *
+ * The context shape is declared structurally so this module stays
+ * self-contained (shared/ has no cordis dependency): any context whose
+ * `subprocess` satisfies SubprocessServiceLike works, which the plugin
+ * contexts do.
+ * @module dsh-web-shared/host/git-runner
+ */
+
+/** One finished git invocation. */
+export interface GitRunResult {
+  exitCode: number | null
+  stdout: string
+  stderr: string
+}
+
+/** The spawn seam the service runs git through (subprocess service in production). */
+export interface GitRunner {
+  run(argv: readonly string[], cwd: string, signal?: AbortSignal): Promise<GitRunResult>
+}
+
+/** Collected-output cap for one git command. */
+export const OUTPUT_CAP_BYTES = 1 << 20
+
+/** The subprocess service surface this runner consumes (structural). */
+export interface SubprocessServiceLike {
+  spawn(spec: {
+    argv: readonly string[]
+    cwd: string
+    stdio: {
+      stdin: 'ignore'
+      stdout: { maxBytes: number }
+      stderr: { maxBytes: number }
+    }
+    graceMs: number
+    signal?: AbortSignal
+  }): {
+    done: Promise<{ exitCode: number | null }>
+    collected: {
+      stdout?: { readFrom(offset: number): { text: string } }
+      stderr?: { readFrom(offset: number): { text: string } }
+    }
+  }
+}
+
+/** Per-package knobs for the shared production runner. */
+export interface GitRunnerOptions {
+  /** Build the full spawn argv from the git args (default ['git', ...argv]). */
+  spawnArgv?: (argv: readonly string[]) => readonly string[]
+  /** degrade turns spawn/run failures into exitCode 127 results instead of throwing. */
+  failureMode?: 'throw' | 'degrade'
+  /** console.error tag for degrade mode. */
+  errorTag?: string
+}
+
+/**
+ * Production runner over the subprocess service: one managed child per
+ * command, bounded collect on both streams. A caller-owned AbortSignal reaches
+ * the subprocess tree and remains authoritative even in degrade mode. Degrade
+ * mode keeps the SCM tab showing the friendly "not a git repository" state
+ * instead of a bare 400 when git is missing or the subprocess service fails.
+ * @param ctx - context carrying the subprocess service.
+ * @param options - per-package behavior knobs.
+ * @returns the runner.
+ */
+export function subprocessRunner(ctx: { subprocess: SubprocessServiceLike }, options: GitRunnerOptions = {}): GitRunner {
+  const spawnArgv = options.spawnArgv ?? ((argv) => ['git', ...argv])
+  const degrade = options.failureMode === 'degrade'
+  const errorTag = options.errorTag ?? 'git'
+  const failure = (prefix: string, error: unknown): GitRunResult => ({
+    exitCode: 127,
+    stdout: '',
+    stderr: prefix + (error instanceof Error ? error.message : String(error)),
+  })
+  return {
+    async run(argv, cwd, signal) {
+      signal?.throwIfAborted()
+      const spec = {
+        argv: spawnArgv(argv),
+        cwd,
+        stdio: {
+          stdin: 'ignore' as const,
+          stdout: { maxBytes: OUTPUT_CAP_BYTES },
+          stderr: { maxBytes: OUTPUT_CAP_BYTES },
+        },
+        graceMs: 10_000,
+        signal,
+      }
+      if (degrade) {
+        let handle
+        try {
+          handle = ctx.subprocess.spawn(spec)
+        } catch (error) {
+          signal?.throwIfAborted()
+          console.error('[' + errorTag + '] git spawn failed:', error)
+          return failure('git: spawn failed: ', error)
+        }
+        try {
+          const outcome = await handle.done
+          signal?.throwIfAborted()
+          const stdout = handle.collected.stdout?.readFrom(0).text ?? ''
+          const stderr = handle.collected.stderr?.readFrom(0).text ?? ''
+          return { exitCode: outcome.exitCode, stdout, stderr }
+        } catch (error) {
+          signal?.throwIfAborted()
+          console.error('[' + errorTag + '] git run failed:', error)
+          return failure('git: run failed: ', error)
+        }
+      }
+      const handle = ctx.subprocess.spawn(spec)
+      const outcome = await handle.done
+      signal?.throwIfAborted()
+      const stdout = handle.collected.stdout?.readFrom(0).text ?? ''
+      const stderr = handle.collected.stderr?.readFrom(0).text ?? ''
+      return { exitCode: outcome.exitCode, stdout, stderr }
+    },
+  }
+}

package/src/host/services/worktree/git.ts

@@ -0,0 +1,183 @@
+/**
+ * Host git subprocess plumbing for the worktree manager. We reuse the
+ * shared runner seam (`@deepseek-ai/dsh-subprocess`) the family already
+ * uses for git operations; this file only owns the worktree-specific git
+ * argv builders so the service layer stays declarative.
+ * @module dsh-client-ui-worktree/host/git
+ */
+
+import type { GitRunner } from './git-runner.ts'
+
+/** win32 ships git as git.exe (git for Windows); the .cmd/.bat shim in
+ *  PATH would otherwise be the resolution target and Node's spawn cannot
+ *  launch a .cmd file directly. Naming git.exe bypasses any shim and
+ *  always hits the native executable. cmd.exe routing is deliberately
+ *  NOT used: several git args carry %-format specs (--format on
+ *  for-each-ref / log) that cmd would expand and corrupt. */
+export function gitSpawnArgv(platform: NodeJS.Platform, argv: readonly string[]): readonly string[] {
+  return platform === 'win32' ? ['git.exe', ...argv] : ['git', ...argv]
+}
+
+/** `git rev-parse --path-format=absolute --git-common-dir` — used to map any
+ *  worktree back to its main repo. */
+export const GIT_COMMON_DIR_ARGV = ['rev-parse', '--path-format=absolute', '--git-common-dir'] as const
+
+/** `git worktree list --porcelain` — the canonical list of linked worktrees
+ *  with their branch, HEAD, and on-disk path. */
+export const WORKTREE_LIST_ARGV = ['worktree', 'list', '--porcelain'] as const
+
+/** `git symbolic-ref -q --short HEAD` — current branch, empty when detached. */
+export const HEAD_BRANCH_ARGV = ['symbolic-ref', '-q', '--short', 'HEAD'] as const
+
+/** `git rev-parse --short HEAD` — used when detached. */
+export const HEAD_SHORT_ARGV = ['rev-parse', '--short', 'HEAD'] as const
+
+/** `git status --porcelain` — used for the dirty count. */
+export const STATUS_PORCELAIN_ARGV = ['status', '--porcelain'] as const
+
+/**
+ * `git worktree add [-b <branch>] [--detach] <path> [<commit-ish>]` — the
+ * create argv. `branch` cuts a new branch at `commitIsh` and checks it out
+ * in the linked worktree; without it git checks out `commitIsh` itself, and
+ * a commit-ish that is not a branch name leaves a DETACHED HEAD. A detached
+ * worktree cannot be pushed (`git push -u origin <branch>` needs a local
+ * branch) or matched by `git worktree list --porcelain`, so every
+ * session-bound lane must pass `branch`.
+ *
+ * `-b` and `--detach` are mutually exclusive in git; passing both is a
+ * programmer error and throws rather than silently dropping one.
+ */
+export function worktreeAddArgv(
+  path: string,
+  commitIsh: string,
+  detach: boolean,
+  branch?: string,
+): readonly string[] {
+  if (detach && branch !== undefined) {
+    throw new Error('worktreeAddArgv: --detach and -b are mutually exclusive')
+  }
+  const argv = ['worktree', 'add']
+  if (detach) argv.push('--detach')
+  if (branch !== undefined) argv.push('-b', branch)
+  argv.push(path, commitIsh)
+  return argv
+}
+
+/**
+ * `git check-ignore -q <path>` — exit 0 when the path is ignored by the
+ * repository's ignore rules. Used to refuse creating a lane before the
+ * lane root is ignored, so an unignored `<repo>/.dsh/workspaces/` can never
+ * be swept into the main checkout by a `git add -A`.
+ */
+export function checkIgnoreArgv(path: string): readonly string[] {
+  return ['check-ignore', '-q', path]
+}
+
+/** `git worktree remove [--force] <path>` — the remove argv. */
+export function worktreeRemoveArgv(path: string, force: boolean): readonly string[] {
+  const argv = ['worktree', 'remove']
+  if (force) argv.push('--force')
+  argv.push(path)
+  return argv
+}
+
+/** `git worktree prune` — drop stale administrative records. */
+export const WORKTREE_PRUNE_ARGV = ['worktree', 'prune'] as const
+
+/** `git worktree list --porcelain` invocation helper. */
+export function worktreeListPorcelain(): readonly string[] {
+  return WORKTREE_LIST_ARGV
+}
+
+/** `git init -b <initialBranch>` — used for `POST /worktree/init`. */
+export function gitInitArgv(initialBranch: string): readonly string[] {
+  return ['init', '-b', initialBranch]
+}
+
+/** `git rev-parse --verify --quiet refs/heads/<branch>` — branch exists check. */
+export function verifyRefArgv(branch: string): readonly string[] {
+  return ['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`]
+}
+
+/** `git branch <name> [<start>]` — create branch from start point. */
+export function createBranchArgv(name: string, start?: string): readonly string[] {
+  const argv = ['branch', name]
+  if (start !== undefined) argv.push(start)
+  return argv
+}
+
+/** `git remote` — list configured remotes (we look for `origin`). */
+export const REMOTE_LIST_ARGV = ['remote'] as const
+
+/** `git remote get-url <name>` — the remote URL for compare-URL / API derivation. */
+export function remoteGetUrlArgv(name: string): readonly string[] {
+  return ['remote', 'get-url', name]
+}
+
+/** `git push -u origin <branch>` — push and set upstream. */
+export function pushUpstreamArgv(branch: string): readonly string[] {
+  return ['push', '-u', 'origin', branch]
+}
+
+/** `git ls-remote --exit-code origin refs/heads/<branch>` — remote branch existence probe. */
+export function lsRemoteBranchArgv(branch: string): readonly string[] {
+  return ['ls-remote', '--exit-code', 'origin', `refs/heads/${branch}`]
+}
+
+/** `git fetch origin --prune` — sync remote-tracking refs and drop deleted ones. */
+export const FETCH_PRUNE_ARGV = ['fetch', 'origin', '--prune'] as const
+
+/** `git merge-base --is-ancestor <candidate> <base>` — merge detection (exit 0 = ancestor). */
+export function mergeBaseIsAncestorArgv(candidate: string, base: string): readonly string[] {
+  return ['merge-base', '--is-ancestor', candidate, base]
+}
+
+/** `git rev-parse --verify --quiet refs/remotes/origin/<branch>` — pushed probe. */
+export function verifyRemoteRefArgv(branch: string): readonly string[] {
+  return ['rev-parse', '--verify', '--quiet', `refs/remotes/origin/${branch}`]
+}
+
+/** `git symbolic-ref refs/remotes/origin/HEAD` — remote default branch probe (fails when unset). */
+export const REMOTE_HEAD_REF = 'refs/remotes/origin/HEAD' as const
+export const REMOTE_HEAD_ARGV = ['symbolic-ref', REMOTE_HEAD_REF] as const
+
+/** `git branch -d|-D <branch>` — delete the local branch (refuses unmerged without -D). */
+export function branchDeleteArgv(branch: string, force: boolean): readonly string[] {
+  return ['branch', force ? '-D' : '-d', branch]
+}
+
+/** `git for-each-ref refs/heads refs/remotes/origin --format=%(refname:short)` —
+ *  candidate branches for the create/PR dialog dropdowns. Local branches
+ *  come first, then remote-tracking `origin/*` names (prefix stripped). */
+export const BRANCH_LIST_ARGV = [
+  'for-each-ref', 'refs/heads', 'refs/remotes/origin',
+  '--format=%(refname:short)',
+] as const
+
+/**
+ * Parse `git for-each-ref` output into a deduplicated short-name list:
+ * local branches in listing order first, then `origin/*` remote-tracking
+ * names with the `origin/` prefix stripped (skipping duplicates already
+ * seen locally, so `dev` + `origin/dev` collapse to one entry).
+ */
+export function parseBranchList(stdout: string): string[] {
+  const seen = new Set<string>()
+  const out: string[] = []
+  for (const raw of stdout.split('\n')) {
+    const line = raw.replace(/\r$/, '').trim()
+    if (line === '' || line === 'origin/HEAD') continue
+    const name = stripOriginPrefix(line)
+    if (name === '' || seen.has(name)) continue
+    seen.add(name)
+    out.push(name)
+  }
+  return out
+}
+
+/** Strip a leading `origin/` from a remote-tracking short ref. */
+export function stripOriginPrefix(ref: string): string {
+  return ref.startsWith('origin/') ? ref.slice('origin/'.length) : ref
+}
+
+/** Re-export the shared runner type for callers. */
+export type { GitRunner }

package/src/host/services/worktree/http.ts

@@ -0,0 +1,36 @@
+/**
+ * JSON request/response helpers. Kept tiny on purpose; the manager layer
+ * owns the response shape (`MutationResult` / `WorktreeErrorView`) and the
+ * route layer only does envelope + status code translation.
+ * @module dsh-client-ui-worktree/host/http
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http'
+
+/** Read a JSON object body. Returns `null` for empty bodies, throws otherwise. */
+export async function readJsonObject(req: IncomingMessage, limit = 1024 * 1024): Promise<Record<string, unknown> | null> {
+  const chunks: Buffer[] = []
+  let received = 0
+  for await (const chunk of req) {
+    received += chunk.length
+    if (received > limit) {
+      req.destroy()
+      throw new Error('request body too large')
+    }
+    chunks.push(chunk as Buffer)
+  }
+  if (received === 0) return null
+  const text = Buffer.concat(chunks).toString('utf8')
+  if (text.trim() === '') return null
+  const parsed = JSON.parse(text)
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('expected JSON object body')
+  }
+  return parsed as Record<string, unknown>
+}
+
+/** Write a JSON response with the given status. */
+export function writeJson(res: ServerResponse, status: number, payload: unknown): void {
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' })
+  res.end(JSON.stringify(payload))
+}