aura-basetools 0.15.0 → 0.16.0

package/README.md

@@ -1,4 +1,4 @@
-# aura-basetools 0.15.0
+# aura-basetools 0.16.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.15.0
+npm i -g aura-basetools@0.16.0
 aura --version
 ```
 
@@ -91,6 +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.
 - **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.
 
@@ -135,7 +136,7 @@ MIT.
 ### 安装
 
 ```bash
-npm i -g aura-basetools@0.15.0
+npm i -g aura-basetools@0.16.0
 aura --version
 ```
 
@@ -205,6 +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` 恢复全部。
 - **寻址是结构化的。** `target` / `lines` / `old` / `expect` / 句柄替代“把原文一字不差抄对”；失败回执带可直接用的重试地址。
 - **核心不依赖 DSH。** `aura-basetools` 零运行时依赖、无 DSH import；DSH 适配器是独立可选包。
 

package/bin/aura.mjs

@@ -6,6 +6,7 @@
  *   aura basetools edit  --file F (--hunks '<json>' | --hunks-file P) [--dry-run] [--verify "命令"] [--create <文本|@文件>]
  *   aura basetools read  --targets '[...]|@spec.json'                    一次读多个目标（与 --file 互斥）
  *   aura basetools edit  --targets '[...]|@spec.json'                    一次改多个文件（与 --file 互斥；任一规划失败 ⇒ 零写入）
+ *   aura basetools tx begin | commit --id <id> [--verify "命令"] | rollback --id <id> | status --id <id>
  *   aura basetools mcp
  *   aura --help | --version
  *
@@ -25,6 +26,10 @@ import {
   // 多目标（fs-contract-v2）的引擎绑定：与单目标同一处（`lib/ops.mjs`），bin 里不另找引擎。
   readManyWith,
   editManyEnvelope,
+  beginTransactionEnvelope,
+  commitTransactionEnvelope,
+  rollbackTransactionEnvelope,
+  statusTransactionEnvelope,
   capabilitiesEnvelope,
   writeEnvelope,
   assertReadTargets,
@@ -86,13 +91,14 @@ const COMMAND_FLAGS = {
     bool: ['pretty'],
   },
   edit: {
-    value: ['cwd', 'file', 'targets', 'hunks', 'hunks-file', 'create', 'target', 'lines', 'start-line', 'end-line', 'line-cue', 'anchor', 'old', 'context', 'handle', 'line', 'position', 'replace', 'expect', 'near', 'eol', 'verify'],
+    value: ['cwd', 'file', 'targets', 'hunks', 'hunks-file', 'create', 'target', 'lines', 'start-line', 'end-line', 'line-cue', 'anchor', 'old', 'context', 'handle', 'line', 'position', 'replace', 'expect', 'near', 'eol', 'verify', 'tx'],
     bool: ['pretty', 'dry-run', 'plan', 'replace-all', 'require-observation'],
   },
   write: {
-    value: ['cwd', 'file', 'content', 'eol', 'verify'],
+    value: ['cwd', 'file', 'content', 'eol', 'verify', 'tx'],
     bool: ['pretty', 'dry-run', 'plan', 'no-overwrite', 'allow-unobserved'],
   },
+  tx: { value: ['cwd', 'id', 'verify'], bool: ['pretty', 'json'] },
   doctor: { value: ['cwd'], bool: ['pretty', 'json'] },
   capabilities: { value: ['cwd'], bool: ['pretty'] },
   mcp: { value: ['cwd'], bool: ['pretty'] },
@@ -109,7 +115,9 @@ function validateCommandFlags(command, tokens) {
   if (spec === undefined) return undefined
   const valueFlags = new Set(spec.value)
   const boolFlags = new Set(spec.bool)
-  for (let i = 0; i < tokens.length; i += 1) {
+  // `tx` 的第一个裸位置参数是子命令（begin/commit/rollback/status）；其余命令不允许位置参数。
+  const start = command === 'tx' && tokens[0] !== undefined && !tokens[0].startsWith('--') ? 1 : 0
+  for (let i = start; i < tokens.length; i += 1) {
     const token = tokens[i]
     if (typeof token !== 'string' || !token.startsWith('--')) {
       return `unexpected argument ${JSON.stringify(token)} — this command takes flags only`
@@ -177,6 +185,10 @@ const USAGE = [
   '   aura basetools edit  --file <路径> --handle <h…> --line <段内行号> --replace <文本>            # 只换区间内第 k 行（1-based，从区间首行数起）',
   '   aura basetools edit  --file <路径> --handle <h…> --position before|after --replace <文本>  # 在区间边界插入，区间本身不动',
   "              （--line / --position 是从属键：只有与 --handle 同时给才成立，单独给不构成一次编辑）",
+  '  aura basetools tx begin               开一个跨调用事务（后续 edit/write 用 --tx <id> 加入）',
+  '  aura basetools tx commit --id <id> [--verify "命令"]  提交；verify 失败/文件被外部改过 ⇒ 拒绝并回滚',
+  '  aura basetools tx rollback --id <id>  回滚整个事务（按 afterVersion 校验）',
+  '  aura basetools tx status --id <id>    只读状态',
   '  aura basetools mcp                    启动 MCP stdio 服务',
   '  aura basetools write --file <路径> --content <文本|@文件> [--no-overwrite] [--dry-run|--plan] [--verify "命令"] [--allow-unobserved] [--eol auto|preserve|lf|crlf]',
   '             （覆写默认要求先读过这一版；--allow-unobserved 才允许盲写）',
@@ -305,7 +317,7 @@ if (command === '--version' || command === '-v') emit({ ok: true, version: VERSI
  * 旧顶层动词只给**迁移提示**，不再作为别名执行——保留别名等于保留未来的撞名。
  * 只提示、不执行：`aura basetools read` 不会偷偷改文件。
  */
-const MOVED_COMMANDS = new Set(['read', 'outline', 'edit', 'write', 'mcp', 'doctor', 'capabilities'])
+const MOVED_COMMANDS = new Set(['read', 'outline', 'edit', 'write', 'tx', 'mcp', 'doctor', 'capabilities'])
 if (!namespaced && MOVED_COMMANDS.has(command)) {
   emit(
     {
@@ -329,6 +341,29 @@ if (command === 'mcp') {
 
 const provider = openProvider(typeof flag('cwd') === 'string' ? flag('cwd') : process.cwd())
 
+if (command === 'tx') {
+  const action = argv[1]
+  const id = typeof flag('id') === 'string' ? flag('id') : undefined
+  if (action === 'begin') {
+    const env = beginTransactionEnvelope(provider)
+    emit(env, env.ok ? 0 : 2)
+  }
+  if (action === 'commit') {
+    const verify = typeof flag('verify') === 'string' ? flag('verify') : undefined
+    const env = await commitTransactionEnvelope(provider, { id, verify })
+    emit(env, env.ok ? 0 : 2)
+  }
+  if (action === 'rollback') {
+    const env = await rollbackTransactionEnvelope(provider, { id })
+    emit(env, env.ok ? 0 : 2)
+  }
+  if (action === 'status') {
+    const env = statusTransactionEnvelope(provider, { id })
+    emit(env, env.ok ? 0 : 2)
+  }
+  emit({ ok: false, error: 'tx 需要 begin | commit | rollback | status（commit/rollback/status 还要 --id）', code: 'USAGE' }, 1)
+}
+
 if (command === 'capabilities') {
   const env = { ok: true, version: VERSION, ...capabilitiesEnvelope() }
   process.stdout.write(`${JSON.stringify(env, null, has('pretty') ? 2 : 0)}\n`)
@@ -353,6 +388,7 @@ if (command === 'write') {
     allowUnobserved: has('allow-unobserved'),
     ...(typeof eol === 'string' ? { eol } : {}),
     ...(typeof flag('verify') === 'string' ? { verify: flag('verify') } : {}),
+    ...(typeof flag('tx') === 'string' ? { transaction: flag('tx') } : {}),
   })
   emit(env, env.ok ? 0 : 2)
 }
@@ -475,6 +511,7 @@ if (command === 'edit') {
       dryRun: has('dry-run') || has('plan') || spec.dryRun,
       ...(has('require-observation') ? { requireObservation: true } : {}),
       ...(typeof flag('verify') === 'string' ? { verify: flag('verify') } : {}),
+      ...(typeof flag('tx') === 'string' ? { transaction: flag('tx') } : {}),
     })
     emit(env, env.ok ? 0 : 2)
   }
@@ -588,6 +625,7 @@ if (command === 'edit') {
     create,
     ...(has('require-observation') ? { requireObservation: true } : {}),
     ...(typeof flag('verify') === 'string' ? { verify: flag('verify') } : {}),
+    ...(typeof flag('tx') === 'string' ? { transaction: flag('tx') } : {}),
   })
   emit(env, env.ok ? 0 : 2)
 }

package/lib/ops.mjs

@@ -14,7 +14,7 @@ import { spawnSync } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
 import { createNodeFsProvider, DEFAULT_MAX_TEXT_BYTES } from './fs-provider.mjs'
 import { withWorkspaceLock } from './workspace-lock.mjs'
-import { createTransaction } from './transaction-store.mjs'
+import { createTransaction, getTransactionMeta, openTransaction } from './transaction-store.mjs'
 import { createDiskStore } from './observation-store.mjs'
 
 /**
@@ -111,7 +111,7 @@ export function capabilitiesEnvelope() {
         },
       },
     ],
-    commands: ['basetools read', 'basetools edit', 'basetools write', 'basetools mcp', 'basetools doctor', 'basetools capabilities', '--version', '--help'],
+    commands: ['basetools read', 'basetools edit', 'basetools write', 'basetools tx', 'basetools mcp', 'basetools doctor', 'basetools capabilities', '--version', '--help'],
     langs,
     langsCount: langs.length,
     limits: {
@@ -519,6 +519,66 @@ function runVerification(command, cwd) {
   }
 }
 
+async function editInTransaction(provider, request) {
+  const verifyCommand = typeof request.verify === 'string' && request.verify.trim().length > 0 ? request.verify.trim() : null
+  try {
+    return await withWorkspaceLock(provider.root, async () => {
+      const tx = openTransaction(provider.root, request.transaction)
+      const env = await editEnvelopeInner(tx.proxy(provider), request)
+      if (!env.ok) return env
+      let verification
+      if (verifyCommand !== null) {
+        verification = runVerification(verifyCommand, provider.root)
+        if (!verification.ok) {
+          const rollback = await tx.rollback(provider)
+          return {
+            ok: false,
+            code: 'PATCH_VERIFY_FAILED',
+            error: `edit verification failed (exit ${verification.exitCode ?? 'no-status'}${verification.timedOut ? ', timed out' : ''}): ${verifyCommand}`,
+            verification,
+            rollback,
+            transaction: tx.summary(),
+          }
+        }
+      }
+      return { ...env, transaction: tx.summary(), ...(verification === undefined ? {} : { verification }) }
+    })
+  } catch (error) {
+    return transactionError(error)
+  }
+}
+
+async function editManyInTransaction(provider, request) {
+  const verifyCommand = typeof request.verify === 'string' && request.verify.trim().length > 0 ? request.verify.trim() : null
+  try {
+    return await withWorkspaceLock(provider.root, async () => {
+      const tx = openTransaction(provider.root, request.transaction)
+      const batch = await editManyEnvelopeInner(tx.proxy(provider), request)
+      if (!batch.ok) return batch
+      let verification
+      if (verifyCommand !== null) {
+        verification = runVerification(verifyCommand, provider.root)
+        if (!verification.ok) {
+          const rollback = await tx.rollback(provider)
+          const finalBatch = writePath.rebuildAfterRollback(batch, rollback)
+          return {
+            ...finalBatch,
+            ok: false,
+            code: 'PATCH_VERIFY_FAILED',
+            error: `edit verification failed (exit ${verification.exitCode ?? 'no-status'}${verification.timedOut ? ', timed out' : ''}): ${verifyCommand}`,
+            verification,
+            rollback,
+            transaction: tx.summary(),
+          }
+        }
+      }
+      return { ...batch, transaction: tx.summary(), ...(verification === undefined ? {} : { verification }) }
+    })
+  } catch (error) {
+    return transactionError(error)
+  }
+}
+
 /**
  * 写事务外壳：workspace 锁 + 事务日志 + 失败回滚。
  *
@@ -532,6 +592,7 @@ export async function editEnvelope(provider, request) {
    * 预演不建事务、不写盘，也不需要工作区锁；0.14.0 起事务日志只用于失败回滚。
    */
   if (request.dryRun === true) return editEnvelopeInner(provider, request)
+  if (typeof request.transaction === 'string' && request.transaction.length > 0) return editInTransaction(provider, request)
   const verifyCommand = typeof request.verify === 'string' && request.verify.trim().length > 0 ? request.verify.trim() : null
   try {
     return await withWorkspaceLock(provider.root, async () => {
@@ -583,6 +644,7 @@ export async function editManyEnvelope(provider, request) {
   if (provider.root === undefined) return editManyEnvelopeInner(provider, request)
   // 与单目标同一条：预演不建事务、不写盘，不能顶掉真正的最近 committed 事务。
   if (request.dryRun === true) return editManyEnvelopeInner(provider, request)
+  if (typeof request.transaction === 'string' && request.transaction.length > 0) return editManyInTransaction(provider, request)
   const verifyCommand = typeof request.verify === 'string' && request.verify.trim().length > 0 ? request.verify.trim() : null
   try {
     return await withWorkspaceLock(provider.root, async () => {
@@ -642,6 +704,85 @@ export async function editManyEnvelope(provider, request) {
   }
 }
 
+/** 开一个跨调用事务；后续 `edit --tx <id>` 写在同一份日志里。 */
+export function beginTransactionEnvelope(provider) {
+  if (provider.root === undefined) return { ok: false, error: 'transactions need a workspace root', code: 'TX_NO_ROOT' }
+  try {
+    const tx = createTransaction(provider.root, 'aura_basetools_tx')
+    return { ok: true, transaction: tx.summary() }
+  } catch (error) {
+    return transactionError(error)
+  }
+}
+
+/** 提交跨调用事务：先做 afterVersion 乐观校验，再跑可选 verify；失败自动 rollback。 */
+export async function commitTransactionEnvelope(provider, { id, verify } = {}) {
+  if (provider.root === undefined) return { ok: false, error: 'transactions need a workspace root', code: 'TX_NO_ROOT' }
+  if (typeof id !== 'string' || id.length === 0) return { ok: false, error: 'commit needs a transaction id', code: 'TX_BAD_ID' }
+  const verifyCommand = typeof verify === 'string' && verify.trim().length > 0 ? verify.trim() : null
+  try {
+    return await withWorkspaceLock(provider.root, async () => {
+      const tx = openTransaction(provider.root, id)
+      const conflicts = tx.assertFresh(provider)
+      if (conflicts.length > 0) {
+        return {
+          ok: false,
+          code: 'TX_STALE',
+          error: `transaction ${id} has ${conflicts.length} file(s) changed since the transaction wrote them`,
+          conflicts,
+          transaction: tx.summary(),
+        }
+      }
+      let verification
+      if (verifyCommand !== null) {
+        verification = runVerification(verifyCommand, provider.root)
+        if (!verification.ok) {
+          const rollback = await tx.rollback(provider)
+          return {
+            ok: false,
+            code: 'PATCH_VERIFY_FAILED',
+            error: `transaction verification failed (exit ${verification.exitCode ?? 'no-status'}${verification.timedOut ? ', timed out' : ''}): ${verifyCommand}`,
+            verification,
+            rollback,
+            transaction: tx.summary(),
+          }
+        }
+      }
+      tx.commit()
+      return { ok: true, transaction: tx.summary(), ...(verification === undefined ? {} : { verification }) }
+    })
+  } catch (error) {
+    return transactionError(error)
+  }
+}
+
+/** 回滚跨调用事务：与内部失败回滚同一套 afterVersion 校验。 */
+export async function rollbackTransactionEnvelope(provider, { id } = {}) {
+  if (provider.root === undefined) return { ok: false, error: 'transactions need a workspace root', code: 'TX_NO_ROOT' }
+  if (typeof id !== 'string' || id.length === 0) return { ok: false, error: 'rollback needs a transaction id', code: 'TX_BAD_ID' }
+  try {
+    return await withWorkspaceLock(provider.root, async () => {
+      const tx = openTransaction(provider.root, id)
+      const rollback = await tx.rollback(provider)
+      return { ok: rollback.status === 'rolled_back', rollback, transaction: tx.summary() }
+    })
+  } catch (error) {
+    return transactionError(error)
+  }
+}
+
+/** 只读事务状态。 */
+export function statusTransactionEnvelope(provider, { id } = {}) {
+  if (provider.root === undefined) return { ok: false, error: 'transactions need a workspace root', code: 'TX_NO_ROOT' }
+  if (typeof id !== 'string' || id.length === 0) return { ok: false, error: 'status needs a transaction id', code: 'TX_BAD_ID' }
+  try {
+    const meta = getTransactionMeta(provider.root, id)
+    return { ok: true, transaction: { id: meta.id, status: meta.status, files: meta.files.length, written: meta.files.filter((f) => f.written).length, dir: meta.dir } }
+  } catch (error) {
+    return transactionError(error)
+  }
+}
+
 /** 整文件写的紧凑回执：不把整份 old/new 文本塞进 applied（那是 edit 的形状，不是 write 的）。 */
 function compactWriteReceipt(env, content) {
   if (env === null || typeof env !== 'object' || env.ok !== true) return env
@@ -683,7 +824,7 @@ function compactWriteReceipt(env, content) {
  * `preserve` 按 content 原样写（与内置 Write 的“给什么写什么”对齐），`lf` / `crlf` 强制统一。
  * 新建文件永远按 content 原样写；显式传非 `auto` 的 eol 会被拒绝（不做静默忽略）。
  */
-export async function writeEnvelope(provider, { file, content, dryRun = false, noOverwrite = false, allowUnobserved = false, eol = 'auto', verify } = {}) {
+export async function writeEnvelope(provider, { file, content, dryRun = false, noOverwrite = false, allowUnobserved = false, eol = 'auto', verify, transaction } = {}) {
   if (typeof file !== 'string' || file.length === 0) {
     return { ok: false, error: 'write needs a file path', code: 'WRITE_BAD_ARGS' }
   }
@@ -710,7 +851,7 @@ export async function writeEnvelope(provider, { file, content, dryRun = false, n
       if (dryRun) {
         return { ok: true, result: { path: displayPath, operation: 'create', bytes: Buffer.byteLength(content, 'utf8'), dryRun: true } }
       }
-      return compactWriteReceipt(await editEnvelope(provider, { file, create: content, verify }), content)
+      return compactWriteReceipt(await editEnvelope(provider, { file, create: content, verify, transaction }), content)
     }
     return compactWriteReceipt(
       await editEnvelope(provider, {
@@ -722,6 +863,7 @@ export async function writeEnvelope(provider, { file, content, dryRun = false, n
         skipStaleGate: allowUnobserved === true,
         toolName: 'aura_basetools_write',
         verify,
+        transaction,
       }),
       content,
     )

package/lib/transaction-store.mjs

@@ -117,22 +117,13 @@ function fileSummary(entry) {
  * @param root - 工作区根
  * @param tool - 产生它的工具名（仅记录）
  */
-export function createTransaction(root, tool = 'aura_basetools_edit') {
-  const id = transactionId()
-  const dir = path.join(transactionsRoot(root), id)
-  ensureDir(dir)
-  const meta = {
-    id,
-    tool,
-    root: path.resolve(root),
-    createdAt: new Date().toISOString(),
-    status: 'pending',
-    files: [],
-    dir,
-  }
-  saveMeta(meta)
+function makeTransaction(root, meta, dir) {
   const entries = new Map()
-  let closed = false
+  for (let i = 0; i < meta.files.length; i += 1) {
+    const saved = meta.files[i]
+    entries.set(saved.path, { ...saved, metaIndex: i })
+  }
+  let closed = meta.status !== 'pending'
 
   const entryKey = (provider, target) => normalizeTarget(provider, target)
 
@@ -174,7 +165,7 @@ export function createTransaction(root, tool = 'aura_basetools_edit') {
   }
 
   const tx = {
-    id,
+    id: meta.id,
     dir,
     meta,
     entries,
@@ -196,17 +187,29 @@ export function createTransaction(root, tool = 'aura_basetools_edit') {
       }
       return proxy
     },
+    /** 交叉调用提交前的乐观校验：事务写过的文件必须仍停在 afterVersion。 */
+    assertFresh(provider) {
+      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) {
+          conflicts.push({ path: entry.path, expected: entry.afterVersion, actual: current?.version ?? null })
+        }
+      }
+      return conflicts
+    },
     commit() {
       if (closed) return
       meta.status = 'committed'
       meta.committedAt = new Date().toISOString()
-      // 只有 meta 真正落盘后才 closed；否则调用方还能 rollback 已经写出的文件。
       saveMeta(meta)
       closed = true
       prune(root)
     },
     summary() {
-      return { id, dir, status: meta.status, files: meta.files.length }
+      return { id: meta.id, dir, status: meta.status, files: meta.files.length, written: meta.files.filter((f) => f.written).length }
     },
     async rollback(provider, options = {}) {
       if (closed) return { status: meta.status, restored: 0, conflicts: [] }
@@ -243,6 +246,48 @@ export function createTransaction(root, tool = 'aura_basetools_edit') {
   return tx
 }
 
+/**
+ * 创建一个 pending 事务。此时还没有任何文件被记录；第一次 writeText 前才记原始字节。
+ *
+ * @param root - 工作区根
+ * @param tool - 产生它的工具名（仅记录）
+ */
+export function createTransaction(root, tool = 'aura_basetools_edit') {
+  const id = transactionId()
+  const dir = path.join(transactionsRoot(root), id)
+  ensureDir(dir)
+  const meta = {
+    id,
+    tool,
+    root: path.resolve(root),
+    createdAt: new Date().toISOString(),
+    status: 'pending',
+    files: [],
+    dir,
+  }
+  saveMeta(meta)
+  return makeTransaction(root, meta, dir)
+}
+
+/** 打开一个仍处于 pending 的跨调用事务。 */
+export function openTransaction(root, id) {
+  const dir = path.join(transactionsRoot(root), id)
+  const meta = loadMeta(dir)
+  if (meta.status !== 'pending') {
+    throw Object.assign(new Error(`transaction ${id} is ${meta.status}, not open`), { code: 'TX_NOT_OPEN' })
+  }
+  return makeTransaction(root, meta, dir)
+}
+
+/** 读一个事务的元数据（状态/文件数）；不存在时抛 TX_NOT_FOUND。 */
+export function getTransactionMeta(root, id) {
+  try {
+    return loadMeta(path.join(transactionsRoot(root), id))
+  } catch {
+    throw Object.assign(new Error(`transaction not found: ${id}`), { code: 'TX_NOT_FOUND' })
+  }
+}
+
 function readAllMeta(root) {
   const dir = transactionsRoot(root)
   let names

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aura-basetools",
-  "version": "0.15.0",
+  "version": "0.16.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",