aura-basetools 0.19.0 → 0.20.0

package/README.md

@@ -1,4 +1,4 @@
-# aura-basetools 0.19.0
+# aura-basetools 0.20.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.19.0
+npm i -g aura-basetools@0.20.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.
+- **MCP clients get a server-side nudge.** `initialize.instructions` asks the client to prefer `aura_basetools_*` and to use `aura_basetools_tx` for multi-call changes; whether it is honored is the client's choice.
 - **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 +137,7 @@ MIT.
 ### 安装
 
 ```bash
-npm i -g aura-basetools@0.19.0
+npm i -g aura-basetools@0.20.0
 aura --version
 ```
 

package/bin/aura-mcp.mjs

@@ -21,6 +21,18 @@
  */
 import { readFileSync, realpathSync } from 'node:fs'
 import process from 'node:process'
+
+/**
+ * MCP `initialize.instructions`: the only standard server-side nudge many MCP clients will
+ * prepend to their prompt. Keep it imperative and factual; it must not promise client behavior
+ * the client does not implement.
+ */
+const SERVER_INSTRUCTIONS = [
+  'Prefer the aura_basetools_* tools over built-in Read/Edit/Write for file work when they are available.',
+  'Read with aura_basetools_read; edit with aura_basetools_edit; create or overwrite with aura_basetools_write.',
+  'For changes spanning multiple calls use aura_basetools_tx begin -> edit/write with transaction -> commit; rollback on failure.',
+  'These tools preserve BOM and per-line endings, gate only the addressed region for staleness, verify writes, and keep multi-target edits atomic.',
+].join(' ')
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import {
   openProvider,
@@ -504,6 +516,7 @@ export async function serve() {
           supportedProtocolVersions: SUPPORTED_PROTOCOLS,
           capabilities: { tools: { listChanged: false } },
           serverInfo: { name: 'aura-basetools', version: VERSION },
+          instructions: SERVER_INSTRUCTIONS,
         })
       }
       if (method === 'ping') return reply(id, {})

package/lib/observation-store.mjs

@@ -204,8 +204,10 @@ export function createDiskStore(file = observationsPath()) {
    * 陈旧锁（进程崩溃留下）超过 `LOCK_STALE_MS` 后清掉。拿不到锁时仍做一次尽力而为的
    * 合并写入——缓存损坏/丢一条都不该让编辑失败，但正常情况下不会走到这条。
    */
-  const LOCK_STALE_MS = 5000
-  const LOCK_WAIT_MS = 2000
+  // Runner 上 6 个 Node 进程同时启动时，2s 不够；拿不到锁仍写入会互相覆盖（实测 CI 偶发）。
+  // 锁只覆盖一次极小的 read-merge-write，15s 是安全上限，不是常态等待。
+  const LOCK_STALE_MS = 30000
+  const LOCK_WAIT_MS = 15000
   const sleep = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms)
   const acquireLock = () => {
     const lock = `${file}.lock`
@@ -221,7 +223,9 @@ export function createDiskStore(file = observationsPath()) {
         try { fs.writeFileSync(fd, String(process.pid)) } finally { fs.closeSync(fd) }
         return lock
       } catch (error) {
-        if (error?.code !== 'EEXIST') return null
+        // Windows 上另一个进程正在 rename/unlink 时，`wx` 可能给 EPERM/EACCES 而不是 EEXIST；
+        // 这不是“没锁可用”，而是“锁正在换手”，继续等到 deadline。
+        if (error?.code !== 'EEXIST' && error?.code !== 'EPERM' && error?.code !== 'EACCES') return null
         try {
           const st = fs.statSync(lock)
           if (Date.now() - st.mtimeMs > LOCK_STALE_MS) {
@@ -254,7 +258,20 @@ export function createDiskStore(file = observationsPath()) {
       if (path.sep !== '\\') {
         try { fs.chmodSync(tmp, 0o600) } catch { /* 同上 */ }
       }
-      fs.renameSync(tmp, file)
+      // Windows：另一个进程正读 observations.json 时，rename 目标可能短暂 EPERM/EBUSY。
+      // 不重试就会静默丢掉这一条观测（CI 的 6 并发实测 1/5 概率）。
+      let renamed = false
+      for (let attempt = 0; attempt < 50; attempt += 1) {
+        try {
+          fs.renameSync(tmp, file)
+          renamed = true
+          break
+        } catch (error) {
+          if (!['EPERM', 'EBUSY', 'EACCES'].includes(error?.code) || attempt === 49) throw error
+          sleep(20)
+        }
+      }
+      if (!renamed) throw new Error('observation cache rename did not complete')
       lastStamp = fileStamp()
       if (path.sep !== '\\') {
         try { fs.chmodSync(file, 0o600) } catch { /* 同上 */ }

package/package.json

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

@@ -375,6 +375,12 @@ say('F MCP：initialize / tools/list / tools/call')
   const byId = new Map(replies.map((r) => [r.id, r]))
   check(byId.get(1)?.result?.protocolVersion === '2025-06-18', 'initialize 回显协议版本', JSON.stringify(byId.get(1)).slice(0, 120))
   check(byId.get(1)?.result?.serverInfo?.name === 'aura-basetools', 'serverInfo.name = aura-basetools')
+  const instructions = byId.get(1)?.result?.instructions
+  check(
+    typeof instructions === 'string' && instructions.includes('Prefer the aura_basetools_*') && instructions.includes('aura_basetools_tx'),
+    'initialize 带服务器 instructions（优先 aura + tx）',
+    String(instructions ?? '').slice(0, 120),
+  )
   // 版本号曾经写死在 bin 里（包到 0.4.0，服务对外还报 0.2.1）—— 这里钉住它跟包清单一致
   const manifest = (() => {
     try {