@modesto_ma/dsh-guanxiang 0.2.0-beta.2 → 0.2.0-beta.4

package/src/skill-update/tool.ts

@@ -4,11 +4,13 @@
  * - 只接受本进程中由同一会话派发过的任务运行目录；应用、仓库和分析时的提交
  *   取自派发记录，不取自运行目录里可被 Agent 改写的内容。
  * - 只改应用 SKILL 目录 `.dsh/skills/<skill>/` 下的文件，提交以分析时的提交为
- *   父提交，推送到新分支 `guanxiang/skill-<应用 id>-<树对象前缀>`，从不推送已有
- *   分支或默认分支。
- * - 推送前经 DSH 审批服务（`ctx.approval`）请求一次性授权；dsh_channels 把它
- *   显示为飞书决策卡片，DSH Web 显示为审批提示。只有 `allowed-once` 才推送；
- *   没有审批服务时工具报错，不推送。
+ *   父提交，提交到新分支 `guanxiang/skill-<应用 id>-<改动摘要前缀>`，从不提交到
+ *   已有分支或默认分支。
+ * - 提交和创建合并请求经 dsh-repo 的 `dshRepos` 服务完成，支持 GitLab 与
+ *   GitHub；令牌由 dsh-repo 按主机配置。没有该服务或版本不符时工具报错。
+ * - 提交前经 DSH 审批服务（`ctx.approval`）请求一次性授权；dsh_channels 把它
+ *   显示为飞书决策卡片，DSH Web 显示为审批提示。只有 `allowed-once` 才提交；
+ *   没有审批服务时工具报错，不提交。
  * - 子会话中不提供本工具。
  *
  * @module dsh-guanxiang/skill-update/tool
@@ -17,16 +19,18 @@
 import { randomBytes } from 'node:crypto'
 import { rename, rm, writeFile } from 'node:fs/promises'
 import { join, resolve } from 'node:path'
+import type { CommitAuthor } from 'dsh-repo/contract'
 import { z } from 'zod'
 import { describeIssue } from '../config.ts'
 import { isDelegatedAgent } from '../dispatch/tool.ts'
 import type { ContentBlock, HostApproval, ToolDefinition, ToolRunContext } from '../host.ts'
-import type { GitRunner } from '../repos/git.ts'
+import { messageOf, repoErrorCode, requireRepos } from '../repos/lookup.ts'
 import type { RepoRegistry } from '../repos/registry.ts'
 import type { AppManifest, EditableSettings } from '../settings/contract.ts'
-import { commitChange, prepareChange, pushForMergeRequest, remoteBranchExists } from './git.ts'
-import type { CommitAuthor, FileStat, PreparedChange } from './git.ts'
+import { prepareChange } from './change.ts'
+import type { FileStat, PreparedChange } from './change.ts'
 import { DIFF_FILE, FILES_DIR, PROPOSAL_DIR, ProposalError, readProposal, REASON_FILE } from './proposal.ts'
+import type { ProposedFile } from './proposal.ts'
 
 /** Model-facing tool name. */
 export const PROPOSE_TOOL_NAME = 'guanxiang_propose_skill'
@@ -69,7 +73,7 @@ export interface ProposeValue {
   status: ProposeStatus
   app: string
   repo: string
-  /** New branch the change was or would be pushed to. */
+  /** New branch the change was or would be committed to. */
   branch: string
   /** Branch the merge request targets. */
   target: string
@@ -77,6 +81,8 @@ export interface ProposeValue {
   /** Diff file in the task's run directory. */
   diffPath: string
   mergeRequestUrl?: string
+  /** Why the merge request was not created; only with `pushed`. */
+  mergeRequestError?: string
 }
 
 const argsSchema = z.object({
@@ -98,7 +104,7 @@ const PARAMETERS: Record<string, unknown> = {
 const FILE_STAT_SCHEMA = {
   type: 'object',
   additionalProperties: false,
-  required: ['path'],
+  required: ['path', 'added', 'removed'],
   properties: { path: { type: 'string' }, added: { type: 'number' }, removed: { type: 'number' } },
 } as const
 
@@ -115,6 +121,7 @@ const OUTPUT_SCHEMA = {
     files: { type: 'array', items: FILE_STAT_SCHEMA },
     diffPath: { type: 'string' },
     mergeRequestUrl: { type: 'string' },
+    mergeRequestError: { type: 'string' },
   },
 } as const
 
@@ -124,7 +131,7 @@ const OUTPUT_SCHEMA = {
  * @returns one line.
  */
 export function describeFiles(files: readonly FileStat[]): string {
-  return files.map(file => file.added === undefined ? `${file.path}（二进制）` : `${file.path}（+${file.added} −${file.removed ?? 0}）`).join('、')
+  return files.map(file => `${file.path}（+${file.added} −${file.removed}）`).join('、')
 }
 
 /**
@@ -135,12 +142,12 @@ export function describeFiles(files: readonly FileStat[]): string {
 export function renderProposeValue(value: ProposeValue): ContentBlock[] {
   const where = `${value.repo} 的分支 ${value.branch}（目标 ${value.target}）`
   const text = {
-    opened: `已推送到 ${where} 并创建合并请求：${value.mergeRequestUrl ?? ''}`,
-    pushed: `已推送到 ${where}，但服务器没有返回合并请求链接；请在 GitLab 上确认合并请求是否已创建。`,
-    exists: `${where} 已存在，同一改动可能已经提交过，本次没有推送。`,
-    rejected: '授权被拒绝，没有推送：用户拒绝了这次修改，或会话的审批策略为 never（例如「完全访问」权限模式）。',
-    cancelled: '授权请求被撤回，没有推送。',
-    unavailable: '当前没有可以回答授权请求的界面，没有推送。',
+    opened: `已提交到 ${where} 并创建合并请求：${value.mergeRequestUrl ?? ''}`,
+    pushed: `已提交到 ${where}，但创建合并请求失败（${value.mergeRequestError ?? '未知原因'}）；请在代码托管平台上从该分支手动创建。`,
+    exists: `${where} 已存在，同一改动可能已经提交过，本次没有提交。`,
+    rejected: '授权被拒绝，没有提交：用户拒绝了这次修改，或会话的审批策略为 never（例如「完全访问」权限模式）。',
+    cancelled: '授权请求被撤回，没有提交。',
+    unavailable: '当前没有可以回答授权请求的界面，没有提交。',
   }[value.status]
   return [{ type: 'text', text: `${text}\n改动：${describeFiles(value.files)}\ndiff：${value.diffPath}` }]
 }
@@ -149,15 +156,11 @@ export function renderProposeValue(value: ProposeValue): ContentBlock[] {
 export interface SkillUpdaterDeps {
   readonly registry: RepoRegistry
   settings(): EditableSettings
-  readonly git: GitRunner
-  readonly gitTimeoutMs: number
   readonly author?: CommitAuthor
   /** DSH's approval service, when the composition has one. */
   approval(): HostApproval | undefined
-}
-
-function messageOf(error: unknown): string {
-  return error instanceof Error ? error.message : String(error)
+  /** What `ctx.get('dshRepos')` returns now. */
+  repos(): unknown
 }
 
 /**
@@ -184,7 +187,7 @@ function skillDirOf(app: AppManifest): string {
 export class SkillUpdater {
   private readonly tasks = new Map<string, DispatchedTask>()
 
-  /** @param deps - registry, settings, git, and approval access. */
+  /** @param deps - registry, settings, approval, and `dshRepos` access. */
   constructor(private readonly deps: SkillUpdaterDeps) {}
 
   /** @returns whether proposals are enabled in the current settings. */
@@ -221,20 +224,17 @@ export class SkillUpdater {
   /**
    * Read the proposal, build its tree, and write the diff file.
    * @returns undefined when the task wrote no proposal.
-   * @throws ProposalError or a git failure.
+   * @throws ProposalError, or an error when dsh-repo is unavailable or the mirror cannot be read.
    */
-  private async prepare(task: DispatchedTask): Promise<{ reason: string; change: PreparedChange; target: string; diffPath: string } | undefined> {
+  private async prepare(task: DispatchedTask, signal?: AbortSignal): Promise<{ reason: string; files: readonly ProposedFile[]; change: PreparedChange; target: string; diffPath: string } | undefined> {
     const proposal = await readProposal(task.workDir, this.deps.settings().skillUpdates)
     if (proposal === undefined) return undefined
-    const commands = { git: this.deps.git, timeoutMs: this.deps.gitTimeoutMs }
-    const { change, target } = await this.deps.registry.withClone(task.url, async clone => ({
-      change: await prepareChange(commands, clone.dir, task.commit, skillDirOf(task.app), proposal.files),
-      target: clone.branch,
-    }))
+    const target = this.deps.registry.branchOf(task.url)
+    const change = await prepareChange(requireRepos(this.deps.repos()), { url: task.url, base: task.commit, skillDir: skillDirOf(task.app) }, proposal.files, signal)
     if (change.files.length === 0) throw new ProposalError(`提议的文件与提交 ${task.commit.slice(0, 12)} 中的 SKILL 相同，没有改动`)
     const diffPath = join(task.workDir, DIFF_FILE)
     await replaceFile(diffPath, change.diff)
-    return { reason: proposal.reason, change, target, diffPath }
+    return { reason: proposal.reason, files: proposal.files, change, target, diffPath }
   }
 
   /**
@@ -244,7 +244,7 @@ export class SkillUpdater {
   definition(): ToolDefinition<ProposeValue> {
     return {
       name: PROPOSE_TOOL_NAME,
-      description: '观象：把派发结果中某个应用的 SKILL 修改提议提交为合并请求。工具先请求用户授权，批准后推送新分支并创建合并请求，不会直接改动默认分支。'
+      description: '观象：把派发结果中某个应用的 SKILL 修改提议提交为合并请求。工具先请求用户授权，批准后提交到新分支并创建合并请求，不会直接改动默认分支。'
         + '仅在派发结果标出了 SKILL 修改提议时使用；不要自己用 git 推送。',
       parameters: PARAMETERS,
       output: {
@@ -261,7 +261,7 @@ export class SkillUpdater {
    * @param rawArgs - model arguments.
    * @param exec - execution context of the calling agent.
    * @returns how the submission ended.
-   * @throws when the arguments, task, proposal, or approval service are unusable, or git fails; nothing is pushed then.
+   * @throws when the arguments, task, proposal, approval service, or `dshRepos` service are unusable, or the commit fails; nothing is committed then.
    */
   async execute(rawArgs: unknown, exec: ToolRunContext): Promise<ProposeValue> {
     const parsed = argsSchema.safeParse(rawArgs)
@@ -275,22 +275,26 @@ export class SkillUpdater {
     if (task === undefined) throw new Error(`${parsed.data.workDir} 不是本次 DSH 运行中观象派发任务的运行目录；DSH 重启后需要重新分析`)
     if (task.sessionId !== agent.session.header.id) throw new Error(`${parsed.data.workDir} 不是当前会话派发的任务`)
     const approval = this.deps.approval()
-    if (approval === undefined) throw new Error('当前 DSH 组合没有审批服务（@deepseek-ai/dsh-user-approval），观象不会在未经授权时推送')
+    if (approval === undefined) throw new Error('当前 DSH 组合没有审批服务（@deepseek-ai/dsh-user-approval），观象不会在未经授权时提交')
+    const repos = requireRepos(this.deps.repos())
 
-    const prepared = await this.prepare(task)
+    let prepared: Awaited<ReturnType<SkillUpdater['prepare']>>
+    try {
+      prepared = await this.prepare(task, exec.signal)
+    } catch (error) {
+      exec.signal.throwIfAborted()
+      throw error
+    }
     if (prepared === undefined) throw new Error(`${task.workDir} 中没有 SKILL 修改提议（${PROPOSAL_DIR}/${REASON_FILE} 与 ${PROPOSAL_DIR}/${FILES_DIR}/）`)
     const { change, target, diffPath, reason } = prepared
-    const branch = `guanxiang/skill-${task.app.id}-${change.tree.slice(0, 10)}`
+    const branch = `guanxiang/skill-${task.app.id}-${change.digest.slice(0, 10)}`
     const base = { app: task.app.id, repo: task.url, branch, target, files: [...change.files], diffPath }
-    const commands = { git: this.deps.git, timeoutMs: this.deps.gitTimeoutMs }
 
-    if (await this.deps.registry.withClone(task.url, clone => remoteBranchExists(commands, clone.dir, branch, clone.env))) {
-      return { ...base, status: 'exists' }
-    }
+    if (await repos.getBranch(task.url, branch, { signal: exec.signal }) !== undefined) return { ...base, status: 'exists' }
 
     const preview = reason.replace(/\s+/g, ' ').slice(0, REASON_PREVIEW_CHARS)
-    const zh = `观象将向 ${task.url} 推送新分支 ${branch}，并创建合并请求合入 ${target}。改动：${describeFiles(change.files)}。摘要：${summary}。理由：${preview}`
-    const en = `GuanXiang will push branch ${branch} to ${task.url} and open a merge request into ${target}. Files: ${change.files.map(file => file.path).join(', ')}. Summary: ${summary}`
+    const zh = `观象将在 ${task.url} 提交新分支 ${branch}，并创建合并请求合入 ${target}。改动：${describeFiles(change.files)}。摘要：${summary}。理由：${preview}`
+    const en = `GuanXiang will commit branch ${branch} to ${task.url} and open a merge request into ${target}. Files: ${change.files.map(file => file.path).join(', ')}. Summary: ${summary}`
     const outcome = await approval.request({
       agent,
       toolName: PROPOSE_TOOL_NAME,
@@ -304,11 +308,32 @@ export class SkillUpdater {
 
     const message = `${summary}\n\n${reason}\n\nProposed-by: 观象 GuanXiang\nAnalyzed-commit: ${task.commit}\nSession: ${task.sessionId}\n`
     const description = `由观象在日志分析中提出（应用 ${task.app.id}，分析提交 ${task.commit.slice(0, 12)}，会话 ${task.sessionId}）。理由：${reason.slice(0, REASON_DESCRIPTION_CHARS)}`
-    const url = await this.deps.registry.withClone(task.url, async (clone) => {
-      exec.signal.throwIfAborted()
-      const commit = await commitChange(commands, clone.dir, change, message, this.deps.author)
-      return await pushForMergeRequest(commands, clone.dir, commit, branch, { target, title: summary, description }, clone.env)
-    })
-    return url === undefined ? { ...base, status: 'pushed' } : { ...base, status: 'opened', mergeRequestUrl: url }
+    // Only files that differ from the analyzed commit; an unchanged one would be an empty update.
+    const changed = new Set(change.files.map(file => file.path))
+    const files = prepared.files
+      .map(file => ({ action: 'write' as const, path: `${skillDirOf(task.app)}/${file.path}`, content: file.content }))
+      .filter(file => changed.has(file.path))
+    exec.signal.throwIfAborted()
+    try {
+      await repos.commitFiles(task.url, {
+        branch,
+        baseSha: task.commit,
+        newBranch: true,
+        message,
+        files,
+        ...this.deps.author === undefined ? {} : { author: this.deps.author },
+        signal: exec.signal,
+      })
+    } catch (error) {
+      if (repoErrorCode(error) === 'conflict') return { ...base, status: 'exists' }
+      throw error
+    }
+    try {
+      const opened = await repos.createChange(task.url, { title: summary, body: description, sourceBranch: branch, targetBranch: target, signal: exec.signal })
+      return { ...base, status: 'opened', mergeRequestUrl: opened.webUrl }
+    } catch (error) {
+      // The branch exists now; report it so the user can open the request by hand.
+      return { ...base, status: 'pushed', mergeRequestError: messageOf(error) }
+    }
   }
 }

package/src/repos/credentials.ts

@@ -1,104 +0,0 @@
-/**
- * HTTPS 访问令牌：按地址前缀为仓库挑选令牌配置，并生成只对一次 git 进程生效的
- * 凭据助手配置。令牌经子进程环境变量交给 git，不出现在命令行参数、仓库的
- * `.git/config` 或 git 输出里；只有服务器要求认证时 git 才向助手取令牌，
- * 本机为同一主机配置的其他凭据助手在这次调用中不参与。
- *
- * @module dsh-guanxiang/repos/credentials
- */
-
-import type { GitCredentialSpec } from '../settings/contract.ts'
-
-export { TOKEN_ENV_PATTERN } from '../settings/contract.ts'
-
-/** Environment variables the helper reads; set only on git child processes. */
-const USERNAME_VARIABLE = 'GUANXIANG_GIT_USERNAME'
-const TOKEN_VARIABLE = 'GUANXIANG_GIT_TOKEN'
-
-/** Answers git's `get` request from the two variables and ignores `store` and `erase`. */
-const HELPER = `!f() { test "$1" = get || exit 0; printf 'username=%s\\npassword=%s\\n' "$${USERNAME_VARIABLE}" "$${TOKEN_VARIABLE}"; }; f`
-
-/** Longest accepted token; personal access tokens are far shorter. */
-export const MAX_TOKEN_LENGTH = 4096
-
-/**
- * Normalize an access-token address prefix to `scheme://host[:port][/path]`
- * with a lowercase host and no trailing slash.
- * @param value - candidate prefix.
- * @returns the normalized prefix, or undefined when it is not an `https`/`http` URL without credentials, query, or fragment.
- */
-export function normalizeCredentialUrl(value: string): string | undefined {
-  let url: URL
-  try {
-    url = new URL(value)
-  } catch {
-    // Not a URL: refused.
-    return undefined
-  }
-  if (url.protocol !== 'https:' && url.protocol !== 'http:') return undefined
-  if (url.host === '' || url.username !== '' || url.password !== '' || url.search !== '' || url.hash !== '') return undefined
-  return `${url.protocol}//${url.host}${url.pathname.replace(/\/+$/, '')}`
-}
-
-/**
- * Whether a token value can be handed to git: non-empty, bounded, and free of
- * control characters, which would break the credential helper protocol.
- * @param value - candidate token.
- * @returns whether it is accepted.
- */
-export function isAcceptedToken(value: string): boolean {
-  return value.length > 0 && value.length <= MAX_TOKEN_LENGTH && !/[\u0000-\u001f\u007f]/.test(value)
-}
-
-/**
- * The access-token configuration for a repository address: the entry whose
- * prefix has the same scheme and host and the longest path that contains the
- * repository path. scp-like addresses, SSH URLs, and local paths never match.
- * @param url - repository address.
- * @param specs - configured access tokens with normalized prefixes.
- * @returns the matching entry, if any.
- */
-export function credentialFor(url: string, specs: readonly GitCredentialSpec[]): GitCredentialSpec | undefined {
-  let repo: URL
-  try {
-    repo = new URL(url)
-  } catch {
-    // scp-like addresses and local paths use other credentials.
-    return undefined
-  }
-  let best: { spec: GitCredentialSpec; length: number } | undefined
-  for (const spec of specs) {
-    const prefix = new URL(spec.url)
-    if (prefix.protocol !== repo.protocol || prefix.host !== repo.host) continue
-    const path = prefix.pathname.replace(/\/+$/, '')
-    if (path !== '' && repo.pathname !== path && !repo.pathname.startsWith(`${path}/`)) continue
-    if (best === undefined || path.length > best.length) best = { spec, length: path.length }
-  }
-  return best?.spec
-}
-
-/**
- * Environment that makes one git process answer the credential request for
- * the token's host with the given token. Existing `GIT_CONFIG_COUNT` entries
- * are kept; the helper list for that host is reset first so a stale password
- * from another helper cannot shadow the token.
- * @param spec - matching access-token configuration.
- * @param token - token value.
- * @param env - environment of the git process before this call.
- * @returns variables to add to the git process environment.
- */
-export function credentialEnvironment(spec: GitCredentialSpec, token: string, env: NodeJS.ProcessEnv = process.env): Record<string, string> {
-  const prefix = new URL(spec.url)
-  const key = `credential.${prefix.protocol}//${prefix.host}.helper`
-  const parsed = Number(env.GIT_CONFIG_COUNT ?? '0')
-  const base = Number.isInteger(parsed) && parsed > 0 ? parsed : 0
-  return {
-    GIT_CONFIG_COUNT: String(base + 2),
-    [`GIT_CONFIG_KEY_${base}`]: key,
-    [`GIT_CONFIG_VALUE_${base}`]: '',
-    [`GIT_CONFIG_KEY_${base + 1}`]: key,
-    [`GIT_CONFIG_VALUE_${base + 1}`]: HELPER,
-    [USERNAME_VARIABLE]: spec.username,
-    [TOKEN_VARIABLE]: token,
-  }
-}

package/src/repos/git.ts

@@ -1,74 +0,0 @@
-/**
- * 本机 git 命令的调用封装：沿用本机已有凭据（SSH key 或 credential helper），
- * 或由调用方经环境变量提供的访问令牌；禁止交互式提示，避免后台拉取卡在
- * 密码输入上。
- *
- * @module dsh-guanxiang/repos/git
- */
-
-import { execFile } from 'node:child_process'
-
-/** A failed git command with its combined output. */
-export class GitError extends Error {
-  /**
-   * @param args - git arguments that failed.
-   * @param output - trimmed stderr (or stdout when stderr is empty).
-   */
-  constructor(readonly args: readonly string[], readonly output: string) {
-    super(`git ${args.join(' ')} 失败：${output === '' ? '无输出' : output}`)
-  }
-}
-
-/** Options of one git command. */
-export interface GitRunOptions {
-  cwd?: string
-  timeoutMs: number
-  /** Variables added to the environment of this command only (credentials for network commands). */
-  env?: Readonly<Record<string, string>>
-  /** Text written to the command's standard input. */
-  input?: string
-  /** `all` resolves, or reports on failure, stdout followed by stderr, for commands such as `push --porcelain` that split their report. */
-  output?: 'stdout' | 'all'
-}
-
-/** Runs one git command and resolves its stdout (or all output, per {@link GitRunOptions.output}). */
-export type GitRunner = (args: readonly string[], options: GitRunOptions) => Promise<string>
-
-/**
- * Environment for non-interactive git: no terminal prompts, and SSH in batch
- * mode unless the user configured their own SSH command.
- * @param env - base environment.
- * @returns environment for git child processes.
- */
-export function gitEnvironment(env: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
-  const next: NodeJS.ProcessEnv = { ...env, GIT_TERMINAL_PROMPT: '0' }
-  if (env.GIT_SSH_COMMAND === undefined && env.GIT_SSH === undefined) next.GIT_SSH_COMMAND = 'ssh -o BatchMode=yes'
-  return next
-}
-
-/**
- * Default runner backed by the `git` executable on PATH.
- * @param args - git arguments.
- * @param options - working directory, timeout, extra environment, input, and output selection.
- * @returns stdout, or stdout followed by stderr.
- */
-export const runGit: GitRunner = (args, options) => new Promise((resolve, reject) => {
-  const child = execFile('git', [...args], {
-    cwd: options.cwd,
-    env: { ...gitEnvironment(), ...options.env },
-    timeout: options.timeoutMs,
-    maxBuffer: 16 * 1024 * 1024,
-    windowsHide: true,
-  }, (error, stdout, stderr) => {
-    if (error === null) {
-      resolve(options.output === 'all' ? `${stdout}${stderr}` : stdout)
-      return
-    }
-    const output = (options.output === 'all' || stderr.trim() === '' ? `${stdout}${stderr}` : stderr).trim()
-    const killed = (error as { killed?: boolean }).killed === true
-    reject(new GitError(args, killed ? `超时（${options.timeoutMs} ms）后被终止${output === '' ? '' : `：${output}`}` : output || error.message))
-  })
-  // A command that exits without reading its input fails through its exit status, not EPIPE.
-  child.stdin?.on('error', () => {})
-  child.stdin?.end(options.input)
-})

package/src/skill-update/git.ts

@@ -1,157 +0,0 @@
-/**
- * 在拉取仓库中用 git 底层命令生成 SKILL 修改的提交并推送：用临时索引文件
- * 在分析时的提交上替换文件、写出树对象，不改动任何检出、快照或本地分支；
- * 推送时用 GitLab push options 顺带创建合并请求。
- *
- * @module dsh-guanxiang/skill-update/git
- */
-
-import { mkdtemp, rm } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import type { GitRunner } from '../repos/git.ts'
-import type { ProposedFile } from './proposal.ts'
-
-/** Line counts of one changed file. */
-export interface FileStat {
-  /** Path relative to the repository root. */
-  readonly path: string
-  /** Added lines; undefined for a binary change. */
-  readonly added?: number
-  /** Removed lines; undefined for a binary change. */
-  readonly removed?: number
-}
-
-/** A proposal turned into a tree object on top of its base commit. */
-export interface PreparedChange {
-  readonly base: string
-  readonly tree: string
-  readonly files: readonly FileStat[]
-  /** Unified diff from the base commit to {@link tree}, limited to the skill directory. */
-  readonly diff: string
-}
-
-/** git runner and the timeout of one command. */
-export interface GitCommands {
-  readonly git: GitRunner
-  readonly timeoutMs: number
-}
-
-/** Author and committer of a commit. */
-export interface CommitAuthor {
-  readonly name: string
-  readonly email: string
-}
-
-/** Merge request fields sent as GitLab push options. */
-export interface MergeRequestOptions {
-  readonly target: string
-  readonly title: string
-  readonly description: string
-}
-
-const DIFF_FLAGS = ['--no-color', '--no-ext-diff', '--no-renames']
-
-/**
- * Write the proposed files over the skill directory of `base` into a new tree.
- * @param commands - git runner and timeout.
- * @param dir - repository directory whose object database receives the objects.
- * @param base - commit the analysis ran on.
- * @param skillDir - skill directory relative to the repository root, `/`-separated.
- * @param files - proposed files relative to `skillDir`.
- * @returns the tree, per-file line counts, and the diff; `files` is empty when nothing changes.
- * @throws when a proposed path replaces a symbolic link or a directory, or a git command fails.
- */
-export async function prepareChange(commands: GitCommands, dir: string, base: string, skillDir: string, files: readonly ProposedFile[]): Promise<PreparedChange> {
-  const { git, timeoutMs } = commands
-  const scratch = await mkdtemp(join(tmpdir(), 'guanxiang-index-'))
-  try {
-    const env = { GIT_INDEX_FILE: join(scratch, 'index') }
-    await git(['read-tree', base], { cwd: dir, timeoutMs, env })
-    const listing = await git(['ls-tree', '-r', '-t', '-z', base, '--', `${skillDir}/`], { cwd: dir, timeoutMs })
-    const modes = new Map<string, string>()
-    for (const record of listing.split('\0')) {
-      const tab = record.indexOf('\t')
-      if (tab < 0) continue
-      modes.set(record.slice(tab + 1), record.slice(0, record.indexOf(' ')))
-    }
-    for (const file of files) {
-      const path = `${skillDir}/${file.path}`
-      const existing = modes.get(path)
-      if (existing === '120000') throw new Error(`${path} 在仓库中是符号链接，不能用提议覆盖`)
-      if (existing === '040000') throw new Error(`${path} 在仓库中是目录，不能用文件覆盖`)
-      const blob = (await git(['hash-object', '-w', '--stdin'], { cwd: dir, timeoutMs, input: file.content })).trim()
-      await git(['update-index', '--add', '--cacheinfo', `${existing === '100755' ? '100755' : '100644'},${blob},${path}`], { cwd: dir, timeoutMs, env })
-    }
-    const tree = (await git(['write-tree'], { cwd: dir, timeoutMs, env })).trim()
-    const numstat = await git(['diff', ...DIFF_FLAGS, '--numstat', base, tree, '--', `${skillDir}/`], { cwd: dir, timeoutMs })
-    const stats = numstat.split('\n').filter(line => line !== '').map((line): FileStat => {
-      const [added = '-', removed = '-', ...path] = line.split('\t')
-      return { path: path.join('\t'), ...added === '-' ? {} : { added: Number(added) }, ...removed === '-' ? {} : { removed: Number(removed) } }
-    })
-    const diff = stats.length === 0 ? '' : await git(['diff', ...DIFF_FLAGS, base, tree, '--', `${skillDir}/`], { cwd: dir, timeoutMs })
-    return { base, tree, files: stats, diff }
-  } finally {
-    await rm(scratch, { recursive: true, force: true })
-  }
-}
-
-/**
- * Whether the remote already has a branch.
- * @param commands - git runner and timeout.
- * @param dir - clone directory.
- * @param branch - branch name.
- * @param env - network environment of the clone's address.
- * @returns whether `refs/heads/<branch>` exists on `origin`.
- */
-export async function remoteBranchExists(commands: GitCommands, dir: string, branch: string, env: Readonly<Record<string, string>>): Promise<boolean> {
-  const output = await commands.git(['ls-remote', '--heads', 'origin', `refs/heads/${branch}`], { cwd: dir, timeoutMs: commands.timeoutMs, env })
-  return output.trim() !== ''
-}
-
-/**
- * Commit a prepared tree on its base commit without touching any ref.
- * @param commands - git runner and timeout.
- * @param dir - clone directory.
- * @param change - prepared tree and its base.
- * @param message - full commit message.
- * @param author - explicit identity; omitted uses the host's git configuration.
- * @returns the new commit id.
- */
-export async function commitChange(commands: GitCommands, dir: string, change: PreparedChange, message: string, author: CommitAuthor | undefined): Promise<string> {
-  const env = author === undefined
-    ? undefined
-    : { GIT_AUTHOR_NAME: author.name, GIT_AUTHOR_EMAIL: author.email, GIT_COMMITTER_NAME: author.name, GIT_COMMITTER_EMAIL: author.email }
-  const output = await commands.git(['commit-tree', change.tree, '-p', change.base, '-F', '-'], { cwd: dir, timeoutMs: commands.timeoutMs, input: message, ...env === undefined ? {} : { env } })
-  return output.trim()
-}
-
-/** Push options cannot carry line breaks; collapse every whitespace run. */
-function oneLine(text: string): string {
-  return text.replace(/\s+/g, ' ').trim()
-}
-
-/**
- * Push a commit to a new remote branch and ask GitLab to open a merge request
- * for it (`merge_request.*` push options). The push carries an empty lease on
- * the branch, so it fails instead of updating a branch that appeared after
- * {@link remoteBranchExists} was checked. A server that does not support push
- * options rejects the push.
- * @param commands - git runner and timeout.
- * @param dir - clone directory.
- * @param commit - commit to push.
- * @param branch - new branch name.
- * @param request - merge request target and text.
- * @param env - network environment of the clone's address.
- * @returns the merge request URL the server printed, if any.
- */
-export async function pushForMergeRequest(commands: GitCommands, dir: string, commit: string, branch: string, request: MergeRequestOptions, env: Readonly<Record<string, string>>): Promise<string | undefined> {
-  const options = [
-    'merge_request.create',
-    `merge_request.target=${request.target}`,
-    `merge_request.title=${oneLine(request.title)}`,
-    `merge_request.description=${oneLine(request.description)}`,
-  ].flatMap(option => ['-o', option])
-  const output = await commands.git(['push', '--porcelain', `--force-with-lease=refs/heads/${branch}:`, ...options, 'origin', `${commit}:refs/heads/${branch}`], { cwd: dir, timeoutMs: commands.timeoutMs, env, output: 'all' })
-  return /https?:\/\/\S+\/-\/merge_requests\/\d+/.exec(output)?.[0]
-}