aura-basetools 0.16.0 → 0.18.0

package/README.md

@@ -1,4 +1,4 @@
-# aura-basetools 0.16.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.16.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.
+- **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.16.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` 恢复全部。
+- **变更可以跨调用，也可以并发合并。** `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/bin/aura-mcp.mjs

@@ -30,6 +30,10 @@ import {
   // 多目标（fs-contract-v2）的引擎绑定：与单目标同一处（`lib/ops.mjs`），bin 里不另找引擎。
   readManyWith,
   editManyEnvelope,
+  beginTransactionEnvelope,
+  commitTransactionEnvelope,
+  rollbackTransactionEnvelope,
+  statusTransactionEnvelope,
   assertReadTargets,
   assertEditTargets,
   assertTargetShape,
@@ -204,6 +208,7 @@ const TOOLS = [
           type: 'string',
           description: '写后验证命令（显式给出才执行；在 workspace 根下、受超时/输出上限约束）。非零退出 ⇒ 自动回滚并返回 PATCH_VERIFY_FAILED。不自动发现/执行仓库脚本。',
         },
+        transaction: { type: 'string', description: '跨调用事务 id（tx begin 返回）；本次修改追加到该事务，不立即 commit' },
         create: { type: 'string', description: '文件不存在时用它创建（整份内容）' },
         targets: TARGETS_SCHEMA,
       },
@@ -245,10 +250,25 @@ const TOOLS = [
           type: 'string',
           description: '写后验证命令（显式给出才执行；非零退出 ⇒ 自动回滚并返回 PATCH_VERIFY_FAILED）。',
         },
+        transaction: { type: 'string', description: '跨调用事务 id（tx begin 返回）；本次修改追加到该事务，不立即 commit' },
       },
       required: ['file_path', 'content'],
     },
   },
+  {
+    name: 'aura_basetools_tx',
+    description:
+      'Begin, commit, rollback, or inspect a cross-call transaction. Begin returns an id; pass it to edit/write `transaction` to append changes; commit checks each written file was not changed externally and can run `verify`; rollback restores all files.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: { type: 'string', enum: ['begin', 'commit', 'rollback', 'status'] },
+        transaction: { type: 'string', description: 'tx begin 返回的事务 id（begin 时不需要）' },
+        verify: { type: 'string', description: 'commit 时的写后验证命令；失败 ⇒ 整个事务回滚' },
+      },
+      required: ['action'],
+    },
+  },
 ]
 
 /**
@@ -333,6 +353,7 @@ async function editTargetsCall(provider, args) {
     dryRun: args.dry_run === true,
     ...(args.require_observation === true ? { requireObservation: true } : {}),
     ...(typeof args.verify === 'string' ? { verify: args.verify } : {}),
+    ...(typeof args.transaction === 'string' ? { transaction: args.transaction } : {}),
   })
 }
 
@@ -383,6 +404,14 @@ async function callTool(provider, name, args = {}) {
       }
     }
   }
+  if (name === 'aura_basetools_tx') {
+    const action = args.action
+    if (action === 'begin') return beginTransactionEnvelope(provider)
+    if (action === 'commit') return await commitTransactionEnvelope(provider, { id: args.transaction, verify: args.verify })
+    if (action === 'rollback') return await rollbackTransactionEnvelope(provider, { id: args.transaction })
+    if (action === 'status') return statusTransactionEnvelope(provider, { id: args.transaction })
+    return { ok: false, error: 'aura_basetools_tx needs action = begin | commit | rollback | status', code: 'BAD_ARGS' }
+  }
   if (name === 'aura_basetools_read') {
     if (multi) return await readTargetsCall(provider, args)
     const noShape = noShapeRefusal(args, 'aura_basetools_read')
@@ -418,6 +447,7 @@ async function callTool(provider, name, args = {}) {
       create: creating ? args.create : undefined,
       ...(args.require_observation === true ? { requireObservation: true } : {}),
       ...(typeof args.verify === 'string' ? { verify: args.verify } : {}),
+      ...(typeof args.transaction === 'string' ? { transaction: args.transaction } : {}),
     })
   }
   if (name === 'aura_basetools_write') {
@@ -429,6 +459,7 @@ async function callTool(provider, name, args = {}) {
       allowUnobserved: args.allow_unobserved === true,
       ...(typeof args.eol === 'string' ? { eol: args.eol } : {}),
       ...(typeof args.verify === 'string' ? { verify: args.verify } : {}),
+      ...(typeof args.transaction === 'string' ? { transaction: args.transaction } : {}),
     })
   }
   return { ok: false, error: `unknown tool ${JSON.stringify(name)}`, code: 'UNKNOWN_TOOL' }

package/lib/ops.mjs

@@ -99,6 +99,11 @@ export function capabilitiesEnvelope() {
           dsh: ['stale-region-gate', 'byte-verify'],
         },
       },
+      {
+        name: 'aura_basetools_tx',
+        actions: ['begin', 'commit', 'rollback', 'status'],
+        options: ['verify'],
+      },
       {
         name: 'aura_basetools_write',
         operations: ['create', 'overwrite'],
@@ -723,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(),
         }
       }
@@ -749,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.16.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",

package/test/standalone-test.mjs

@@ -385,7 +385,7 @@ say('F MCP：initialize / tools/list / tools/call')
   })()
   if (manifest !== null) check(byId.get(1)?.result?.serverInfo?.version === manifest.version, `serverInfo.version 跟包一致（${manifest.version}）`, String(byId.get(1)?.result?.serverInfo?.version))
   const tools = byId.get(2)?.result?.tools ?? []
-  check(tools.length === 3 && tools.some((t) => t.name === 'aura_basetools_read') && tools.some((t) => t.name === 'aura_basetools_edit') && tools.some((t) => t.name === 'aura_basetools_write'), `tools/list 三个工具（${tools.map((t) => t.name).join(',')}`)
+  check(tools.length === 4 && tools.some((t) => t.name === 'aura_basetools_read') && tools.some((t) => t.name === 'aura_basetools_edit') && tools.some((t) => t.name === 'aura_basetools_write') && tools.some((t) => t.name === 'aura_basetools_tx'), `tools/list 四个工具（${tools.map((t) => t.name).join(',')}`)
   const readEnv = JSON.parse(byId.get(3)?.result?.content?.[0]?.text ?? '{}')
   check(readEnv.ok === true && Array.isArray(readEnv.symbols ?? []), 'aura_basetools_read 经 MCP 可用', JSON.stringify(readEnv).slice(0, 120))
   const editEnv = JSON.parse(byId.get(4)?.result?.content?.[0]?.text ?? '{}')

package/test/write-test.mjs

@@ -210,7 +210,7 @@ say('C MCP：aura_basetools_write 声明面与调用面')
 
   const tools = byId.get(2)?.result?.tools ?? []
   const writeTool = tools.find((tool) => tool.name === 'aura_basetools_write')
-  check(tools.length === 3 && writeTool !== undefined, `C1 tools/list 三个工具且含 aura_basetools_write（${tools.map((tool) => tool.name).join(',')}）`)
+  check(tools.length === 4 && writeTool !== undefined, `C1 tools/list 四个工具且含 aura_basetools_write（${tools.map((tool) => tool.name).join(',')}）`)
   check(JSON.stringify(writeTool?.inputSchema?.required) === JSON.stringify(['file_path', 'content']), 'C2 aura_basetools_write schema 必填 file_path + content', JSON.stringify(writeTool?.inputSchema?.required))
   check(envOf(3).ok === true && envOf(3).result?.operation === 'create', 'C3 经 MCP 新建成功', JSON.stringify(envOf(3)).slice(0, 160))
   check(fs.readFileSync(file('mcp-created.txt'), 'utf8') === 'mcp\ncreate\n', 'C4 MCP 新建的内容真的落盘')