dsh-git-changes 0.0.0-stage → 0.1.1

package/lib/host/git-write.js

@@ -0,0 +1,194 @@
+/**
+ * git 写操作（暂存 / 取消暂存 / 提交 / 推送）。
+ *
+ * 只暴露固定语义的函数，不接受任意 git 参数透传。所有命令走 argv 数组，
+ * 路径由路由层完成 safeRelativePath + realpath + withinRoot 校验后传入。
+ *
+ * 与只读层的关键差异：写操作必须使用「完整进程环境」，否则子进程拿不到
+ * HOME / PATH，git 读不到 ~/.gitconfig 中的身份与 SSH/凭据配置。
+ */
+import { GitRunner } from './git.js'
+
+/** 暂存/取消暂存/提交的超时。 */
+const WRITE_TIMEOUT_MS = 15000
+/** 推送单独放宽（网络慢、大仓库）。 */
+const PUSH_TIMEOUT_MS = 120000
+/** 错误详情保留长度。 */
+const STDERR_LIMIT = 400
+/** 允许的最大提交信息长度。 */
+const COMMIT_MESSAGE_MAX = 5000
+
+/**
+ * 写操作子进程环境：完整进程环境 + 禁用交互式提示与可选锁。
+ * @returns {Record<string, string | undefined>}
+ */
+export function writeEnvironment() {
+  return {
+    ...process.env,
+    GIT_TERMINAL_PROMPT: '0',
+    GIT_OPTIONAL_LOCKS: '0',
+    LC_ALL: 'C',
+  }
+}
+
+/**
+ * 写操作环境：默认完整进程环境，测试可覆盖。
+ * @param {{env?: Record<string, string | undefined>}} request
+ */
+function environmentOf(request) {
+  return { ...writeEnvironment(), ...(request.env || {}) }
+}
+
+/**
+ * 创建懒加载的写操作 runner（超时按 push 上限设置）。
+ * @param {object} ctx Host context
+ * @param {string | null | Promise<string | null>} executable 已解析的 git 路径
+ * @returns {() => Promise<GitRunner | null>}
+ */
+export function createWriteGit(ctx, executable) {
+  let pending
+  return () => {
+    pending ??= Promise.resolve(executable).then((exe) => (exe
+      ? new GitRunner(ctx.subprocess, exe, { timeoutMs: PUSH_TIMEOUT_MS, outputMaxBytes: 8 * 1024 * 1024 })
+      : null))
+    return pending
+  }
+}
+
+/**
+ * 统一失败形状。
+ * @param {string} code 机器可读错误码
+ * @param {string} [detail] stderr 摘要
+ */
+function fail(code, detail) {
+  return { ok: false, code, detail: String(detail || '').slice(0, STDERR_LIMIT) }
+}
+
+/**
+ * 构造 literal pathspec，避免文件名中的 `*`、`?` 等被当成通配符。
+ * @param {string} path 仓库相对路径
+ */
+function pathspec(path) {
+  return ':(literal)' + path
+}
+
+/**
+ * 暂存一个或多个文件，或暂存全部（`all`）。
+ * @param {GitRunner} git 写 runner
+ * @param {{cwd:string, paths?:string[], all?:boolean, signal?:AbortSignal}} request
+ * @returns {Promise<{ok:true} | {ok:false, code:string, detail:string}>}
+ */
+export async function stagePaths(git, request) {
+  const args = ['add', '-A', '--']
+  if (request.all) args.push('.')
+  else args.push(...(request.paths || []).map(pathspec))
+  const result = await git.run(args, { cwd: request.cwd, signal: request.signal, env: environmentOf(request) })
+  if (result.exitCode !== 0) return fail('stage-failed', result.stderr)
+  return { ok: true }
+}
+
+/**
+ * 取消暂存一个或多个文件（恢复到工作区，不丢改动）。
+ * HEAD 不存在（unborn 分支）时 `git restore --staged` 不可用，退化为
+ * `git rm --cached -r`。
+ * @param {GitRunner} git 写 runner
+ * @param {{cwd:string, paths?:string[], all?:boolean, signal?:AbortSignal}} request
+ */
+export async function unstagePaths(git, request) {
+  const { cwd, signal } = request
+  const env = environmentOf(request)
+  const head = await git.run(['rev-parse', '--verify', '--quiet', 'HEAD'], { cwd, signal, env })
+  const unborn = head.exitCode !== 0
+  const target = request.all ? ['.'] : (request.paths || []).map(pathspec)
+  const args = unborn
+    ? ['rm', '--cached', '-r', '--', ...target]
+    : ['restore', '--staged', '--', ...target]
+  const result = await git.run(args, { cwd, signal, env })
+  if (result.exitCode !== 0) return fail('unstage-failed', result.stderr)
+  return { ok: true }
+}
+
+/**
+ * 放弃改动：已跟踪文件恢复到 index（未暂存）或 HEAD（已暂存），
+ * 未跟踪文件直接删除。不可撤销，由客户端二次确认。
+ * @param {GitRunner} git 写 runner
+ * @param {{cwd:string, paths?:string[], untrackedPaths?:string[], scope?:'staged'|'unstaged', signal?:AbortSignal}} request
+ * @returns {Promise<{ok:true} | {ok:false, code:string, detail:string}>}
+ */
+export async function discardPaths(git, request) {
+  const { cwd, signal } = request
+  const env = environmentOf(request)
+  const scope = request.scope === 'staged' ? 'staged' : 'unstaged'
+  const tracked = (request.paths || []).map(pathspec)
+  if (tracked.length > 0) {
+    const args = scope === 'staged'
+      ? ['restore', '--source=HEAD', '--staged', '--worktree', '--', ...tracked]
+      : ['restore', '--worktree', '--', ...tracked]
+    const result = await git.run(args, { cwd, signal, env })
+    if (result.exitCode !== 0) return fail('discard-failed', result.stderr)
+  }
+  const untracked = (request.untrackedPaths || []).map(pathspec)
+  if (untracked.length > 0) {
+    const result = await git.run(['clean', '-f', '-d', '--', ...untracked], { cwd, signal, env })
+    if (result.exitCode !== 0) return fail('discard-failed', result.stderr)
+  }
+  if (tracked.length === 0 && untracked.length === 0) return fail('empty-selection')
+  return { ok: true }
+}
+
+/**
+ * 提交暂存内容。
+ * @param {GitRunner} git 写 runner
+ * @param {{cwd:string, message:string, signal?:AbortSignal}} request
+ * @returns {Promise<{ok:true, sha:string|null} | {ok:false, code:string, detail:string}>}
+ */
+export async function commitChanges(git, request) {
+  const { cwd, signal } = request
+  const env = environmentOf(request)
+  const message = String(request.message || '').trim()
+  if (message.length === 0) return fail('empty-message', 'Commit message is required.')
+  if (message.length > COMMIT_MESSAGE_MAX) return fail('invalid-message', 'Commit message is too long.')
+  if (message.startsWith('-')) return fail('invalid-message', 'Commit message must not start with "-".')
+
+  const status = await git.run(['status', '--porcelain'], { cwd, signal, env })
+  if (status.exitCode !== 0) return fail('commit-failed', status.stderr)
+  const hasStaged = status.stdout
+    .split('\n')
+    .some((line) => line.length > 1 && line[0] !== ' ' && line[0] !== '?')
+  if (!hasStaged) return fail('nothing-staged', '没有暂存的改动可提交。')
+
+  const result = await git.run(['commit', '-m', message], { cwd, signal, env })
+  if (result.exitCode !== 0) {
+    if (/Author identity unknown|Please tell me who you are|unable to auto-detect email address/i.test(result.stderr)) {
+      return fail('identity-missing', 'git user.name / user.email 未配置。')
+    }
+    if (/nothing added to commit|no changes added to commit/i.test(result.stderr)) {
+      return fail('nothing-staged', '没有暂存的改动可提交。')
+    }
+    return fail('commit-failed', result.stderr)
+  }
+  const sha = await git.run(['rev-parse', 'HEAD'], { cwd, signal, env })
+  return { ok: true, sha: sha.exitCode === 0 ? sha.stdout.trim() : null }
+}
+
+/**
+ * 推送当前分支。永不 force，不自动创建上游。
+ * @param {GitRunner} git 写 runner
+ * @param {{cwd:string, signal?:AbortSignal}} request
+ * @returns {Promise<{ok:true, branch:string} | {ok:false, code:string, detail:string}>}
+ */
+export async function pushCurrentBranch(git, request) {
+  const { cwd, signal } = request
+  const env = environmentOf(request)
+  const head = await git.run(['rev-parse', '--abbrev-ref', 'HEAD'], { cwd, signal, env })
+  if (head.exitCode !== 0) return fail('push-failed', head.stderr)
+  const branch = head.stdout.trim()
+  if (!branch || branch === 'HEAD') return fail('detached-head', '当前处于 detached HEAD，无法推送。')
+  const upstream = await git.run(['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}'], { cwd, signal, env })
+  if (upstream.exitCode !== 0 || upstream.stdout.trim() === '') {
+    return fail('no-upstream', '当前分支没有上游，请先执行 git push -u origin ' + branch)
+  }
+  const result = await git.run(['push'], { cwd, signal, env })
+  if (result.exitCode !== 0) return fail('push-failed', result.stderr)
+  return { ok: true, branch }
+}