aura-basetools 0.16.0 → 0.17.0

package/README.md

@@ -1,4 +1,4 @@
-# aura-basetools 0.16.0
+# aura-basetools 0.17.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.17.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.** `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.
 - **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.17.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_STALE`），可带 `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'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aura-basetools",
-  "version": "0.16.0",
+  "version": "0.17.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 新建的内容真的落盘')