aura-basetools 0.17.0 → 0.18.0

package/README.md

@@ -1,4 +1,4 @@
-# aura-basetools 0.17.0
+# aura-basetools 0.18.0
 
 Byte-exact file tools for coding agents: read by intent, edit by address, and write whole files without corrupting bytes. One engine shared by a standalone CLI and an MCP server.
 
@@ -21,7 +21,7 @@ The engine is intentionally not a general file manager: it reads and edits UTF-8
 ### Install
 
 ```bash
-npm i -g aura-basetools@0.17.0
+npm i -g aura-basetools@0.18.0
 aura --version
 ```
 
@@ -91,7 +91,7 @@ Compared with the DSH built-in `dsh-tool-fs` tools, the differences are delibera
 - **Edits refuse stale bases.** A region-level gate rejects an edit when the addressed region changed after the read that authorized it, and points at the lines to re-read; `expect` makes the intended text explicit.
 - **Writes are verified, not assumed.** Every write goes through a temp file, flush, rename, and a byte-for-byte read-back; multi-target edits plan first and write nothing if any target fails.
 - **Changes can prove themselves.** `edit` / `write` accept an explicit `verify` command; a non-zero exit or timeout rolls the transaction back and returns the command output plus the rollback state. No auto-discovery of repo scripts.
-- **Changes can span calls.** `tx begin` opens a transaction; `edit` / `write` with `--tx <id>` append to it; `tx commit` checks files were not changed externally (`TX_STALE`) and can run `verify`; `tx rollback` restores all of them. MCP exposes the same lifecycle as `aura_basetools_tx` plus the `transaction` field on edit/write.
+- **Changes can span calls, and concurrent changes merge.** `tx begin` opens a transaction; `edit` / `write` with `--tx <id>` append to it; `tx commit` three-way-merges non-overlapping external edits, refuses overlapping ones (`TX_CONFLICT`) without writing, and can run `verify`; `tx rollback` restores all of them. MCP exposes the same lifecycle as `aura_basetools_tx` plus the `transaction` field on edit/write.
 - **Addressing is structural.** `target` / `lines` / `old` / `expect` / handles replace "copy the literal text exactly"; failure receipts include ready-to-use retry addresses.
 - **The core is DSH-free.** `aura-basetools` has no runtime dependencies and no DSH imports; the DSH adapter is a separate optional package.
 
@@ -136,7 +136,7 @@ MIT.
 ### 安装
 
 ```bash
-npm i -g aura-basetools@0.17.0
+npm i -g aura-basetools@0.18.0
 aura --version
 ```
 
@@ -206,7 +206,7 @@ npx -y --package aura-basetools aura basetools mcp
 - **依据过期就拒绝。** 区域级陈旧闸门在“授权读取之后该区域被改过”时拒绝，并指出重读哪几行；`expect` 让目标原文显式化。
 - **写完要验，不靠相信。** 每次写盘走临时文件、flush、rename，再做逐字节回读；多目标先全量规划，任一失败则一个字节都不写。
 - **变更可以自证。** `edit` / `write` 接受显式 `verify` 命令；非零退出或超时会把整个事务回滚，回执带命令输出与回滚状态。不自动发现仓库脚本。
-- **变更可以跨调用。** `tx begin` 开事务；`edit` / `write --tx <id>` 追加；`tx commit` 先检查文件没被外部改过（`TX_STALE`），可带 `verify`；`tx rollback` 恢复全部。MCP 用同一个生命周期：`aura_basetools_tx` + edit/write 的 `transaction` 字段。
+- **变更可以跨调用，也可以并发合并。** `tx begin` 开事务；`edit` / `write --tx <id>` 追加；`tx commit` 对外部非重叠改动做三方合并，重叠则 `TX_CONFLICT` 且零写入，可带 `verify`；`tx rollback` 恢复全部。MCP 用同一个生命周期：`aura_basetools_tx` + edit/write 的 `transaction` 字段。
 - **寻址是结构化的。** `target` / `lines` / `old` / `expect` / 句柄替代“把原文一字不差抄对”；失败回执带可直接用的重试地址。
 - **核心不依赖 DSH。** `aura-basetools` 零运行时依赖、无 DSH import；DSH 适配器是独立可选包。
 

package/lib/ops.mjs

@@ -728,13 +728,13 @@ export async function commitTransactionEnvelope(provider, { id, verify } = {}) {
   try {
     return await withWorkspaceLock(provider.root, async () => {
       const tx = openTransaction(provider.root, id)
-      const conflicts = tx.assertFresh(provider)
-      if (conflicts.length > 0) {
+      const merge = tx.mergeOnCommit(provider)
+      if (merge.conflicts.length > 0) {
         return {
           ok: false,
-          code: 'TX_STALE',
-          error: `transaction ${id} has ${conflicts.length} file(s) changed since the transaction wrote them`,
-          conflicts,
+          code: 'TX_CONFLICT',
+          error: `transaction ${id} has ${merge.conflicts.length} file(s) that cannot be merged; nothing was written`,
+          conflicts: merge.conflicts,
           transaction: tx.summary(),
         }
       }
@@ -754,7 +754,7 @@ export async function commitTransactionEnvelope(provider, { id, verify } = {}) {
         }
       }
       tx.commit()
-      return { ok: true, transaction: tx.summary(), ...(verification === undefined ? {} : { verification }) }
+      return { ok: true, transaction: tx.summary(), merges: merge.merged, ...(verification === undefined ? {} : { verification }) }
     })
   } catch (error) {
     return transactionError(error)

package/lib/transaction-store.mjs

@@ -14,6 +14,7 @@
  * 这不是安全边界；它只保证遵守本协议的进程不会静默覆盖并发写。
  */
 import fs from 'node:fs'
+import { spawnSync } from 'node:child_process'
 import os from 'node:os'
 import path from 'node:path'
 import crypto from 'node:crypto'
@@ -108,6 +109,8 @@ function fileSummary(entry) {
     written: entry.written,
     afterVersion: entry.afterVersion ?? null,
     backup: entry.backup ?? null,
+    writtenBackup: entry.writtenBackup ?? null,
+    rollbackBackup: entry.rollbackBackup ?? null,
   }
 }
 
@@ -117,6 +120,53 @@ function fileSummary(entry) {
  * @param root - 工作区根
  * @param tool - 产生它的工具名（仅记录）
  */
+function utf8Text(buf) {
+  const text = buf.toString('utf8')
+  if (!Buffer.from(text, 'utf8').equals(buf)) return null
+  if (text.includes('\u0000')) return null
+  return text
+}
+
+/**
+ * 2-way fast path + `git merge-file` 的三方合并。
+ *
+ * 文字层合并，不碰二进制；一方没变时直接取另一方，避免为无关文件启动 git。
+ * Git 不可用或冲突时返回 conflict，调用方拒绝提交，不写任何文件。
+ */
+function mergeText(baseBuf, oursBuf, theirsBuf, tmpDir) {
+  const base = utf8Text(baseBuf)
+  const ours = utf8Text(oursBuf)
+  const theirs = utf8Text(theirsBuf)
+  if (base === null || ours === null || theirs === null) return { ok: false, reason: 'not-utf8' }
+  if (ours === base) return { ok: true, bytes: theirsBuf }
+  if (theirs === base) return { ok: true, bytes: oursBuf }
+  ensureDir(tmpDir)
+  const stem = `${process.pid}-${crypto.randomBytes(4).toString('hex')}`
+  const baseFile = path.join(tmpDir, `${stem}.base`)
+  const oursFile = path.join(tmpDir, `${stem}.ours`)
+  const theirsFile = path.join(tmpDir, `${stem}.theirs`)
+  try {
+    fs.writeFileSync(baseFile, baseBuf)
+    fs.writeFileSync(oursFile, oursBuf)
+    fs.writeFileSync(theirsFile, theirsBuf)
+    const res = spawnSync('git', ['merge-file', '-p', '--diff3', oursFile, baseFile, theirsFile], {
+      encoding: null,
+      maxBuffer: 16 * 1024 * 1024,
+      windowsHide: true,
+    })
+    if (res.error?.code === 'ENOENT') return { ok: false, reason: 'git-unavailable' }
+    if (res.status === 0) return { ok: true, bytes: Buffer.from(res.stdout) }
+    if (res.status === 1) {
+      return { ok: false, reason: 'overlap', conflictText: Buffer.from(res.stdout).toString('utf8').slice(0, 4000) }
+    }
+    return { ok: false, reason: 'git-error', exitCode: res.status, stderr: String(res.stderr ?? '').slice(0, 500) }
+  } finally {
+    for (const file of [baseFile, oursFile, theirsFile]) {
+      try { fs.rmSync(file, { force: true }) } catch { /* 临时文件清不掉不影响判定 */ }
+    }
+  }
+}
+
 function makeTransaction(root, meta, dir) {
   const entries = new Map()
   for (let i = 0; i < meta.files.length; i += 1) {
@@ -177,16 +227,77 @@ function makeTransaction(root, meta, dir) {
         const result = await provider.writeText(target, content, expected)
         entry.written = true
         entry.afterVersion = result?.version ?? null
+        const writtenPath = path.join('written', `${entry.metaIndex}.bin`)
+        writeBytesAtomic(path.join(dir, writtenPath), fs.readFileSync(entry.realPath), 0o600)
+        entry.writtenBackup = writtenPath
         const summary = meta.files[entry.metaIndex]
         if (summary !== undefined) {
           summary.written = true
           summary.afterVersion = entry.afterVersion
+          summary.writtenBackup = entry.writtenBackup
         }
         saveMeta(meta)
         return result
       }
       return proxy
     },
+    /**
+     * 提交前的并发合并：事务写过的文件若被外部改过，尝试把我们的 diff 三方合并到当前内容。
+     * **先规划所有文件，全部可合并才写；任一冲突 ⇒ 零写入**，返回 conflicts 供调用方拒绝。
+     */
+    mergeOnCommit(provider) {
+      const plans = []
+      const conflicts = []
+      for (const entry of entries.values()) {
+        if (!entry.written) continue
+        let current
+        try { current = provider.stat(entry.path) } catch { current = undefined }
+        if (entry.afterVersion !== null && current?.version === entry.afterVersion) continue
+        if (!entry.writtenBackup || !entry.backup) {
+          conflicts.push({ path: entry.path, reason: 'no-merge-base' })
+          continue
+        }
+        let baseBytes
+        let oursBytes
+        let theirsBytes
+        try {
+          baseBytes = fs.readFileSync(path.join(dir, entry.backup))
+          oursBytes = fs.readFileSync(path.join(dir, entry.writtenBackup))
+          theirsBytes = fs.readFileSync(entry.realPath)
+        } catch (error) {
+          conflicts.push({ path: entry.path, reason: String(error?.message ?? error) })
+          continue
+        }
+        const merged = mergeText(baseBytes, oursBytes, theirsBytes, path.join(dir, 'merge-tmp'))
+        if (!merged.ok) {
+          conflicts.push({ path: entry.path, reason: merged.reason, ...(merged.conflictText === undefined ? {} : { conflictText: merged.conflictText }), ...(merged.exitCode === undefined ? {} : { exitCode: merged.exitCode }) })
+          continue
+        }
+        plans.push({ entry, theirsBytes, bytes: merged.bytes })
+      }
+      if (conflicts.length > 0) return { merged: [], conflicts }
+      const merged = []
+      for (const plan of plans) {
+        const { entry } = plan
+        const rollbackBackup = path.join('rollback', `${entry.metaIndex}.bin`)
+        writeBytesAtomic(path.join(dir, rollbackBackup), plan.theirsBytes, 0o600)
+        entry.rollbackBackup = rollbackBackup
+        writeBytesAtomic(entry.realPath, plan.bytes, entry.mode ?? 0o600)
+        const writtenBackup = path.join('written', `${entry.metaIndex}.bin`)
+        writeBytesAtomic(path.join(dir, writtenBackup), plan.bytes, 0o600)
+        entry.writtenBackup = writtenBackup
+        entry.afterVersion = provider.stat(entry.path)?.version ?? null
+        const summary = meta.files[entry.metaIndex]
+        if (summary !== undefined) {
+          summary.afterVersion = entry.afterVersion
+          summary.writtenBackup = entry.writtenBackup
+          summary.rollbackBackup = entry.rollbackBackup
+        }
+        merged.push({ path: entry.path, merged: true })
+      }
+      if (merged.length > 0) saveMeta(meta)
+      return { merged, conflicts: [] }
+    },
     /** 交叉调用提交前的乐观校验：事务写过的文件必须仍停在 afterVersion。 */
     assertFresh(provider) {
       const conflicts = []
@@ -227,7 +338,8 @@ function makeTransaction(root, meta, dir) {
         }
         try {
           if (entry.existed) {
-            writeBytesAtomic(entry.realPath, fs.readFileSync(path.join(dir, entry.backup)), entry.mode ?? 0o600)
+            const backup = entry.rollbackBackup ?? entry.backup
+            writeBytesAtomic(entry.realPath, fs.readFileSync(path.join(dir, backup)), entry.mode ?? 0o600)
           } else {
             fs.rmSync(entry.realPath, { force: true })
           }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aura-basetools",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Byte-exact read, edit and write tools for coding agents. Standalone CLI and MCP server; no DSH required. 面向 coding agent 的逐字节读写工具；独立 CLI / MCP，可选 DSH 适配器。",
   "license": "MIT",
   "type": "module",