aura-basetools 0.14.0 → 0.15.0

package/README.md

@@ -1,4 +1,4 @@
-# aura-basetools 0.14.0
+# aura-basetools 0.15.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.14.0
+npm i -g aura-basetools@0.15.0
 aura --version
 ```
 
@@ -90,6 +90,7 @@ Compared with the DSH built-in `dsh-tool-fs` tools, the differences are delibera
 - **Read by intent, not whole file.** `map` / `digest` / `lines` / `search` return the structural slice you ask for; the customer comparison measured about 1/24 of the context for the same file.
 - **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.
 - **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.
 
@@ -134,7 +135,7 @@ MIT.
 ### 安装
 
 ```bash
-npm i -g aura-basetools@0.14.0
+npm i -g aura-basetools@0.15.0
 aura --version
 ```
 
@@ -203,6 +204,7 @@ npx -y --package aura-basetools aura basetools mcp
 - **按意图读，不读整份。** `map` / `digest` / `lines` / `search` 只返回你要的结构切片；客户版对照实测同一文件上下文约 1/24。
 - **依据过期就拒绝。** 区域级陈旧闸门在“授权读取之后该区域被改过”时拒绝，并指出重读哪几行；`expect` 让目标原文显式化。
 - **写完要验，不靠相信。** 每次写盘走临时文件、flush、rename，再做逐字节回读；多目标先全量规划，任一失败则一个字节都不写。
+- **变更可以自证。** `edit` / `write` 接受显式 `verify` 命令；非零退出或超时会把整个事务回滚，回执带命令输出与回滚状态。不自动发现仓库脚本。
 - **寻址是结构化的。** `target` / `lines` / `old` / `expect` / 句柄替代“把原文一字不差抄对”；失败回执带可直接用的重试地址。
 - **核心不依赖 DSH。** `aura-basetools` 零运行时依赖、无 DSH import；DSH 适配器是独立可选包。
 

package/bin/aura-mcp.mjs

@@ -200,6 +200,10 @@ const TOOLS = [
           type: 'boolean',
           description: '严格新鲜度：要求这一版文件在本会话里被读过（或由本工具写过）；否则 PATCH_UNOBSERVED。create 不受影响；dry_run 同样执行这条判决。',
         },
+        verify: {
+          type: 'string',
+          description: '写后验证命令（显式给出才执行；在 workspace 根下、受超时/输出上限约束）。非零退出 ⇒ 自动回滚并返回 PATCH_VERIFY_FAILED。不自动发现/执行仓库脚本。',
+        },
         create: { type: 'string', description: '文件不存在时用它创建（整份内容）' },
         targets: TARGETS_SCHEMA,
       },
@@ -237,6 +241,10 @@ const TOOLS = [
           enum: ['auto', 'preserve', 'lf', 'crlf'],
           description: '覆写时的换行风格：auto（默认）适配文件已有风格；preserve 按 content 原样写；lf/crlf 强制。新建文件始终按 content 原样写（非 auto 会被拒绝）。',
         },
+        verify: {
+          type: 'string',
+          description: '写后验证命令（显式给出才执行；非零退出 ⇒ 自动回滚并返回 PATCH_VERIFY_FAILED）。',
+        },
       },
       required: ['file_path', 'content'],
     },
@@ -324,6 +332,7 @@ async function editTargetsCall(provider, args) {
     targets,
     dryRun: args.dry_run === true,
     ...(args.require_observation === true ? { requireObservation: true } : {}),
+    ...(typeof args.verify === 'string' ? { verify: args.verify } : {}),
   })
 }
 
@@ -408,6 +417,7 @@ async function callTool(provider, name, args = {}) {
       dryRun: args.dry_run === true,
       create: creating ? args.create : undefined,
       ...(args.require_observation === true ? { requireObservation: true } : {}),
+      ...(typeof args.verify === 'string' ? { verify: args.verify } : {}),
     })
   }
   if (name === 'aura_basetools_write') {
@@ -418,6 +428,7 @@ async function callTool(provider, name, args = {}) {
       noOverwrite: args.no_overwrite === true,
       allowUnobserved: args.allow_unobserved === true,
       ...(typeof args.eol === 'string' ? { eol: args.eol } : {}),
+      ...(typeof args.verify === 'string' ? { verify: args.verify } : {}),
     })
   }
   return { ok: false, error: `unknown tool ${JSON.stringify(name)}`, code: 'UNKNOWN_TOOL' }

package/bin/aura.mjs

@@ -3,7 +3,7 @@
  * aura CLI（薄壳）：参数解析 → `lib/ops.mjs` → 一行 JSON。
  *
  *   aura basetools read  --file F [--mode …] [--around X] [--lines a,b] [--search S] [--since V] [--max-chars N]
- *   aura basetools edit  --file F (--hunks '<json>' | --hunks-file P) [--dry-run] [--create <文本|@文件>]
+ *   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 mcp
@@ -86,11 +86,11 @@ 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'],
+    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'],
     bool: ['pretty', 'dry-run', 'plan', 'replace-all', 'require-observation'],
   },
   write: {
-    value: ['cwd', 'file', 'content', 'eol'],
+    value: ['cwd', 'file', 'content', 'eol', 'verify'],
     bool: ['pretty', 'dry-run', 'plan', 'no-overwrite', 'allow-unobserved'],
   },
   doctor: { value: ['cwd'], bool: ['pretty', 'json'] },
@@ -166,9 +166,9 @@ const USAGE = [
   // `--file` 指向**目录**时直接给一张仓库地图（模块/目录/依赖方向），不需要额外旗标。
   '             （--file 传目录 ⇒ 仓库地图：模块清单 + 目录骨架 + 被依赖最多的模块 + 入口点）',
   '  aura basetools read  --targets <json|@文件>                               # 一次读多个目标（≤32 项；与 --file 互斥）',
-  '  aura basetools edit  --targets <json|@文件> [--dry-run|--plan]          # 一次改多个文件（先全量规划，任一失败则零写入）',
+  '  aura basetools edit  --targets <json|@文件> [--dry-run|--plan] [--verify "命令"]  # 一次改多个文件（先全量规划，任一失败则零写入）',
   "  aura basetools edit  --file <路径> --create <内容|@文件>                     # 建文件（不必再给 --hunks）",
-  "  aura basetools edit  --file <路径> (--hunks '<json>' | --hunks-file <路径>) [--dry-run|--plan] [--eol auto|preserve|lf|crlf] [--require-observation]",
+  "  aura basetools edit  --file <路径> (--hunks '<json>' | --hunks-file <路径>) [--dry-run|--plan] [--verify \"命令\"] [--eol auto|preserve|lf|crlf] [--require-observation]",
   '   aura basetools edit  --file <路径> --lines <a,b> --replace <文本> [--expect <文本>] [--near <n>]',
   '   aura basetools edit  --file <路径> --old <原文> --replace <文本> --replace-all        # 改全部非重叠出现',
           "              （只改一处时不必包成 JSON：--target / --lines / --start-line+--end-line / --line-cue / --anchor 任选其一）",
@@ -178,7 +178,7 @@ const USAGE = [
   '   aura basetools edit  --file <路径> --handle <h…> --position before|after --replace <文本>  # 在区间边界插入，区间本身不动',
   "              （--line / --position 是从属键：只有与 --handle 同时给才成立，单独给不构成一次编辑）",
   '  aura basetools mcp                    启动 MCP stdio 服务',
-  '  aura basetools write --file <路径> --content <文本|@文件> [--no-overwrite] [--dry-run|--plan] [--allow-unobserved] [--eol auto|preserve|lf|crlf]',
+  '  aura basetools write --file <路径> --content <文本|@文件> [--no-overwrite] [--dry-run|--plan] [--verify "命令"] [--allow-unobserved] [--eol auto|preserve|lf|crlf]',
   '             （覆写默认要求先读过这一版；--allow-unobserved 才允许盲写）',
   '  aura basetools doctor [--json]        自检：Node/版本/MCP 握手/缓存与锁目录可写',
   '  aura basetools capabilities [--pretty] 能力清单：读模式/地址档/语言/限制（JSON）',
@@ -352,6 +352,7 @@ if (command === 'write') {
     noOverwrite: has('no-overwrite'),
     allowUnobserved: has('allow-unobserved'),
     ...(typeof eol === 'string' ? { eol } : {}),
+    ...(typeof flag('verify') === 'string' ? { verify: flag('verify') } : {}),
   })
   emit(env, env.ok ? 0 : 2)
 }
@@ -473,6 +474,7 @@ if (command === 'edit') {
       targets: spec.targets,
       dryRun: has('dry-run') || has('plan') || spec.dryRun,
       ...(has('require-observation') ? { requireObservation: true } : {}),
+      ...(typeof flag('verify') === 'string' ? { verify: flag('verify') } : {}),
     })
     emit(env, env.ok ? 0 : 2)
   }
@@ -585,6 +587,7 @@ if (command === 'edit') {
     dryRun: has('dry-run') || has('plan'),
     create,
     ...(has('require-observation') ? { requireObservation: true } : {}),
+    ...(typeof flag('verify') === 'string' ? { verify: flag('verify') } : {}),
   })
   emit(env, env.ok ? 0 : 2)
 }

package/lib/ops.mjs

@@ -10,6 +10,7 @@
  * （`flatHunk` 也从这里出去），于是「引擎在哪」这个问题在整棵树里只有一个答案。
  */
 import fs from 'node:fs'
+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'
@@ -91,7 +92,7 @@ export function capabilitiesEnvelope() {
       {
         name: 'aura_basetools_edit',
         addressKinds: [...new Set([...engineArgs.FLAT_ADDRESS_KEYS, 'old', 'context', 'position'])],
-        options: ['replace_all', 'require_observation'],
+        options: ['replace_all', 'require_observation', 'verify'],
         writeSafety: {
           cli: ['workspace-lock', 'stale-region-gate', 'byte-verify'],
           mcp: ['workspace-lock', 'stale-region-gate', 'byte-verify'],
@@ -101,7 +102,7 @@ export function capabilitiesEnvelope() {
       {
         name: 'aura_basetools_write',
         operations: ['create', 'overwrite'],
-        options: ['eol'],
+        options: ['eol', 'verify'],
         writeSafety: {
           cli: ['workspace-lock', 'stale-region-gate', 'observation-gate', 'byte-verify'],
           mcp: ['workspace-lock', 'stale-region-gate', 'observation-gate', 'byte-verify'],
@@ -479,6 +480,45 @@ function transactionError(error) {
   }
 }
 
+const VERIFY_OUTPUT_LIMIT = 4000
+const tailText = (value) => {
+  const text = String(value ?? '')
+  return text.length <= VERIFY_OUTPUT_LIMIT ? text : `…${text.slice(-VERIFY_OUTPUT_LIMIT)}`
+}
+
+/**
+ * 写后验证：**只在调用方显式给出命令时**执行。
+ *
+ * 不是自动发现仓库脚本，也不绕过沙箱/权限；命令在 workspace 根下跑，有超时与输出上限。
+ * 失败由外层事务回滚，调用方拿到的是可判定的 `PATCH_VERIFY_FAILED`，不是“写完再说”。
+ */
+function runVerification(command, cwd) {
+  const timeout = Math.min(600000, Math.max(1000, Number(process.env.AURA_VERIFY_TIMEOUT_MS) || 120000))
+  const started = Date.now()
+  const res = spawnSync(command, {
+    cwd,
+    shell: true,
+    encoding: 'utf8',
+    timeout,
+    maxBuffer: 8 * 1024 * 1024,
+    env: process.env,
+    windowsHide: true,
+  })
+  const timedOut = res.error?.code === 'ETIMEDOUT'
+  return {
+    command,
+    cwd,
+    ok: res.status === 0 && res.error === undefined,
+    exitCode: res.status,
+    signal: res.signal ?? null,
+    timedOut,
+    durationMs: Date.now() - started,
+    stdout: tailText(res.stdout),
+    stderr: tailText(res.stderr),
+    ...(res.error === undefined ? {} : { error: String(res.error.message ?? res.error) }),
+  }
+}
+
 /**
  * 写事务外壳：workspace 锁 + 事务日志 + 失败回滚。
  *
@@ -492,11 +532,34 @@ export async function editEnvelope(provider, request) {
    * 预演不建事务、不写盘，也不需要工作区锁；0.14.0 起事务日志只用于失败回滚。
    */
   if (request.dryRun === true) return editEnvelopeInner(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 = createTransaction(provider.root, 'aura_basetools_edit')
       const env = await editEnvelopeInner(tx.proxy(provider), request)
       if (env.ok) {
+        if (verifyCommand !== null) {
+          const verification = runVerification(verifyCommand, provider.root)
+          if (!verification.ok) {
+            const rollback = await tx.rollback(provider)
+            return {
+              ok: false,
+              error: `edit verification failed (exit ${verification.exitCode ?? 'no-status'}${verification.timedOut ? ', timed out' : ''}): ${verifyCommand}`,
+              code: 'PATCH_VERIFY_FAILED',
+              verification,
+              rollback,
+            }
+          }
+          try {
+            tx.commit()
+          } catch (error) {
+            const rollback = await tx.rollback(provider)
+            error.transaction = tx.summary()
+            error.rollback = rollback
+            throw error
+          }
+          return { ...env, verification }
+        }
         try {
           tx.commit()
         } catch (error) {
@@ -520,12 +583,37 @@ export async function editManyEnvelope(provider, request) {
   if (provider.root === undefined) return editManyEnvelopeInner(provider, request)
   // 与单目标同一条：预演不建事务、不写盘，不能顶掉真正的最近 committed 事务。
   if (request.dryRun === true) return editManyEnvelopeInner(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 = createTransaction(provider.root, 'aura_basetools_edit')
       try {
         const batch = await editManyEnvelopeInner(tx.proxy(provider), request)
         if (batch.ok) {
+          if (verifyCommand !== null) {
+            const 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,
+              }
+            }
+            try {
+              tx.commit()
+            } catch (error) {
+              const rollback = await tx.rollback(provider)
+              error.transaction = tx.summary()
+              error.rollback = rollback
+              throw error
+            }
+            return { ...batch, verification }
+          }
           try {
             tx.commit()
           } catch (error) {
@@ -567,6 +655,7 @@ function compactWriteReceipt(env, content) {
   const bytes = result.write_verify?.bytes ?? (dryRun && result.operation === 'create' ? Buffer.byteLength(content, 'utf8') : undefined)
   return {
     ok: true,
+    ...(env.verification === undefined ? {} : { verification: env.verification }),
     result: {
       path: result.path,
       operation: result.operation ?? 'write',
@@ -594,7 +683,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' } = {}) {
+export async function writeEnvelope(provider, { file, content, dryRun = false, noOverwrite = false, allowUnobserved = false, eol = 'auto', verify } = {}) {
   if (typeof file !== 'string' || file.length === 0) {
     return { ok: false, error: 'write needs a file path', code: 'WRITE_BAD_ARGS' }
   }
@@ -621,7 +710,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 }), content)
+      return compactWriteReceipt(await editEnvelope(provider, { file, create: content, verify }), content)
     }
     return compactWriteReceipt(
       await editEnvelope(provider, {
@@ -632,6 +721,7 @@ export async function writeEnvelope(provider, { file, content, dryRun = false, n
         requireObservation: allowUnobserved !== true,
         skipStaleGate: allowUnobserved === true,
         toolName: 'aura_basetools_write',
+        verify,
       }),
       content,
     )

package/package.json

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