aura-basetools 0.7.0 → 0.13.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "aura-basetools",
-  "version": "0.7.0",
-  "description": "Byte-fidelity read/edit engine for coding agents. Standalone CLI and MCP server; no harness or DSH required.",
+  "version": "0.13.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",
   "engines": {
@@ -35,18 +35,18 @@
     "LICENSE",
     "THIRD-PARTY-NOTICES.md"
   ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/Ck-epsilon/Aura",
     "directory": "aura-basetools"
   },
-  "homepage": "https://github.com/Ck-epsilon/Aura/tree/main/aura-basetools#readme",
+  "homepage": "https://github.com/Ck-epsilon/Aura/tree/main/aura-basetools",
   "bugs": {
     "url": "https://github.com/Ck-epsilon/Aura/issues"
   },
-  "author": "Ck-epsilon",
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org"
-  }
+  "author": "Ck-epsilon"
 }

package/test/argument-surface-test.mjs

@@ -0,0 +1,119 @@
+/**
+ * argument-surface-test.mjs —— P0.1 / P1.6：参数面不许静默。
+ *
+ * 判据：
+ *   · CLI 未知旗标（`--dryrun`）⇒ USAGE/ARGS_UNKNOWN_KEY、exit 1、磁盘不变；
+ *   · MCP 未知参数（顶层与 targets 元素）⇒ ok:false/code ARGS_UNKNOWN_KEY、isError、磁盘不变；
+ *   · 合法 `--dry-run` / `dry_run` 仍是预演；
+ *   · MCP initialize 不回显不存在的协议版本；非法类型回 -32602，不崩不挂死。
+ *
+ * 运行：node src/aura-standalone/test/argument-surface-test.mjs
+ */
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+
+const here = path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Za-z]:)/, '$1'))
+const bin = path.join(here, '..', 'bin', 'aura.mjs')
+const mcpBin = path.join(here, '..', 'bin', 'aura-mcp.mjs')
+
+let pass = 0
+let fail = 0
+const check = (ok, label, detail = '') => {
+  if (ok) pass += 1
+  else fail += 1
+  console.log(`${ok ? '✓' : '✗'} ${label}${ok || detail === '' ? '' : `  ${detail}`}`)
+}
+const say = (m) => console.log(`\n=== ${m} ===`)
+
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'aura-args-'))
+const cache = path.join(tmp, 'cache')
+const env = { ...process.env, AURA_CACHE_DIR: cache }
+const run = (args) => spawnSync(process.execPath, [bin, ...args], { cwd: tmp, encoding: 'utf8', env })
+const json = (res) => {
+  try {
+    return JSON.parse(String(res.stdout).trim().split('\n').pop())
+  } catch {
+    return { ok: false, error: `stdout 不是 JSON：${JSON.stringify(res.stdout)} ${String(res.stderr ?? '').trim().split('\n')[0] ?? ''}` }
+  }
+}
+const file = (name) => path.join(tmp, name)
+const put = (name, text) => {
+  fs.writeFileSync(file(name), text)
+  return file(name)
+}
+process.on('exit', () => {
+  try { fs.rmSync(tmp, { recursive: true, force: true }) } catch { /* 清不掉不影响判据 */ }
+})
+
+// ── A CLI ────────────────────────────────────────────────────────────────
+say('A CLI：未知旗标不执行、不写盘')
+{
+  const pathA = put('a.txt', 'alpha\n')
+  const moved = run(['edit', '--file', pathA, '--lines', '1', '--replace', 'beta'])
+  const movedEnv = json(moved)
+  check(moved.status === 1 && movedEnv.shape === 'CLI_NAMESPACE_REQUIRED' && fs.readFileSync(pathA, 'utf8') === 'alpha\n', 'A0 顶层旧动词 ⇒ CLI_NAMESPACE_REQUIRED 且磁盘不变', JSON.stringify(movedEnv).slice(0, 200))
+
+  const bad = run(['basetools', 'edit', '--file', pathA, '--lines', '1', '--replace', 'beta', '--dryrun'])
+  const badEnv = json(bad)
+  check(bad.status === 1 && badEnv.ok === false && badEnv.shape === 'ARGS_UNKNOWN_KEY', 'A1 --dryrun ⇒ exit 1 + ARGS_UNKNOWN_KEY', JSON.stringify({ status: bad.status, env: badEnv }).slice(0, 220))
+  check(fs.readFileSync(pathA, 'utf8') === 'alpha\n', 'A2 --dryrun 被拒后磁盘不变')
+
+  const positional = run(['basetools', 'edit', pathA, '--lines', '1', '--replace', 'beta'])
+  const positionalEnv = json(positional)
+  check(positional.status === 1 && positionalEnv.shape === 'ARGS_UNKNOWN_KEY', 'A3 裸位置参数也被拒', JSON.stringify(positionalEnv).slice(0, 180))
+
+  const writeBad = run(['basetools', 'write', '--file', file('w.txt'), '--content', 'x\n', '--dryrun'])
+  const writeBadEnv = json(writeBad)
+  check(writeBad.status === 1 && writeBadEnv.shape === 'ARGS_UNKNOWN_KEY' && !fs.existsSync(file('w.txt')), 'A4 write --dryrun ⇒ 拒绝且不建文件', JSON.stringify(writeBadEnv).slice(0, 180))
+
+  const good = run(['basetools', 'edit', '--file', pathA, '--lines', '1', '--replace', 'beta', '--dry-run'])
+  const goodEnv = json(good)
+  check(good.status === 0 && goodEnv.ok === true && goodEnv.result?.dryRun === true, 'A5 合法 --dry-run 仍是预演', JSON.stringify(goodEnv).slice(0, 160))
+  check(fs.readFileSync(pathA, 'utf8') === 'alpha\n', 'A6 预演之后磁盘不变')
+
+  const elemBad = json(run(['basetools', 'edit', '--targets', JSON.stringify([
+    { file_path: pathA, hunks: [{ lines: [1, 1], replace: 'beta' }], dryrun: true },
+  ])]))
+  check(elemBad.ok === false && elemBad.shape === 'ARGS_UNKNOWN_KEY' && fs.readFileSync(pathA, 'utf8') === 'alpha\n', 'A7 targets 元素未知键 ⇒ 参数面拒绝且零写入', JSON.stringify(elemBad).slice(0, 200))
+
+  const readElemBad = json(run(['basetools', 'read', '--targets', JSON.stringify([{ file_path: pathA, mode: 'map', dryrun: true }])]))
+  check(readElemBad.ok === false && readElemBad.shape === 'ARGS_UNKNOWN_KEY', 'A8 read targets 元素未知键 ⇒ 拒绝', JSON.stringify(readElemBad).slice(0, 180))
+}
+
+// ── B MCP ────────────────────────────────────────────────────────────────
+say('B MCP：未知参数 + initialize 协议版本')
+{
+  const pathB = put('b.txt', 'alpha\n')
+  const frames = [
+    { jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2025-06-18', capabilities: {} } },
+    { jsonrpc: '2.0', method: 'notifications/initialized' },
+    { jsonrpc: '2.0', id: 2, method: 'tools/call', params: { name: 'aura_basetools_edit', arguments: { file_path: pathB, hunks: [{ lines: [1, 1], replace: 'beta' }], dryrun: true } } },
+    { jsonrpc: '2.0', id: 3, method: 'tools/call', params: { name: 'aura_basetools_edit', arguments: { targets: [{ file_path: pathB, hunks: [{ lines: [1, 1], replace: 'beta' }], dryrun: true }] } } },
+    { jsonrpc: '2.0', id: 4, method: 'tools/call', params: { name: 'aura_basetools_edit', arguments: { file_path: pathB, hunks: [{ lines: [1, 1], replace: 'beta' }], dry_run: true } } },
+    { jsonrpc: '2.0', id: 5, method: 'tools/call', params: { name: 'aura_basetools_read', arguments: { file: pathB, mode: 'map' } } },
+    { jsonrpc: '2.0', id: 6, method: 'initialize', params: { protocolVersion: '9999-99-99' } },
+    { jsonrpc: '2.0', id: 7, method: 'initialize', params: { protocolVersion: 42 } },
+    { jsonrpc: '2.0', id: 8, method: 'tools/call', params: { name: 'aura_basetools_read', arguments: { file_path: pathB, mode: 'map' } } },
+  ]
+  const res = spawnSync(process.execPath, [mcpBin], { input: `${frames.map((f) => JSON.stringify(f)).join('\n')}\n`, encoding: 'utf8', env })
+  const replies = String(res.stdout).trim().split('\n').filter(Boolean).map((line) => JSON.parse(line))
+  const byId = new Map(replies.map((reply) => [reply.id, reply]))
+  const envOf = (id) => {
+    const text = byId.get(id)?.result?.content?.[0]?.text
+    try { return JSON.parse(text ?? '{}') } catch { return {} }
+  }
+  check(byId.get(2)?.result?.isError === true && envOf(2).code === 'ARGS_UNKNOWN_KEY', 'B1 MCP 顶层 dryrun ⇒ ARGS_UNKNOWN_KEY/isError', JSON.stringify(envOf(2)).slice(0, 180))
+  check(byId.get(3)?.result?.isError === true && envOf(3).code === 'ARGS_UNKNOWN_KEY', 'B2 MCP targets 元素 dryrun ⇒ ARGS_UNKNOWN_KEY', JSON.stringify(envOf(3)).slice(0, 180))
+  check(fs.readFileSync(pathB, 'utf8') === 'alpha\n', 'B3 两次未知参数都没有写盘')
+  check(byId.get(4)?.result?.isError === false && envOf(4).result?.dryRun === true, 'B4 合法 dry_run 仍是预演')
+  check(envOf(5).code === 'ARGS_UNKNOWN_KEY', 'B5 aura_basetools_read 的 file 拼写 ⇒ ARGS_UNKNOWN_KEY', JSON.stringify(envOf(5)).slice(0, 160))
+  check(byId.get(1)?.result?.protocolVersion === '2025-06-18', 'B6 受支持的协议版本原样返回')
+  check(byId.get(6)?.result?.protocolVersion === '2025-06-18' && Array.isArray(byId.get(6)?.result?.supportedProtocolVersions), 'B7 不支持的版本返回服务端最新版本 + supported 列表', JSON.stringify(byId.get(6)?.result).slice(0, 180))
+  check(typeof byId.get(7)?.error?.code === 'number' && byId.get(7).error.code === -32602, 'B8 非字符串协议版本 ⇒ -32602（不挂死）', JSON.stringify(byId.get(7)).slice(0, 180))
+  check(envOf(8).ok === true, 'B9 坏输入之后服务仍然可用')
+}
+
+say(`\n--- 参数面：${pass}/${pass + fail} 通过 ---`)
+process.exitCode = fail === 0 ? 0 : 1

package/test/doctor-test.mjs

@@ -0,0 +1,73 @@
+/**
+ * doctor-test —— 0.9.4：`aura doctor` 的机械验收。
+ *
+ * 两个方向都要钉住：
+ *   ① 正常环境 ⇒ ok=true，所有检查项通过，exit 0；
+ *   ② 缓存目录不可用 ⇒ ok=false，cache/lock 检查红，exit 2（不是崩溃、不是假绿）。
+ *
+ * 全程用临时 `AURA_CACHE_DIR`，不碰真实 `~/.aura`。
+ */
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+
+const say = (m) => fs.writeSync(1, `${m}\n`)
+let pass = 0
+let fail = 0
+const check = (label, ok, detail = '') => {
+  if (ok) {
+    pass += 1
+    say(`  ✓ ${label}${detail === '' ? '' : `  ${detail}`}`)
+  } else {
+    fail += 1
+    say(`  ✗ ${label}${detail === '' ? '' : `  ${detail}`}`)
+  }
+}
+
+const bin = path.join(import.meta.dirname, '..', 'bin', 'aura.mjs')
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'aura-doctor-test-'))
+const run = (cacheDir) =>
+  spawnSync(process.execPath, [bin, 'basetools', 'doctor', '--json'], {
+    encoding: 'utf8',
+    timeout: 60000,
+    env: { ...process.env, AURA_CACHE_DIR: cacheDir },
+  })
+const parse = (res) => {
+  try { return JSON.parse(res.stdout ?? '') } catch { return null }
+}
+
+say('=== A. 正常环境 ===')
+{
+  const cache = path.join(tmp, 'cache')
+  const res = run(cache)
+  const report = parse(res)
+  check('A1 exit 0', res.status === 0, `exit=${res.status} ${String(res.stderr ?? '').slice(0, 100)}`)
+  check('A2 JSON 可解析且 ok=true', report?.ok === true, JSON.stringify(report?.ok))
+  const ids = (report?.checks ?? []).map((c) => c.id)
+  check('A3 六项检查都在', ['node', 'version', 'mcp-bin', 'mcp-handshake', 'cache-writable', 'lock-writable'].every((id) => ids.includes(id)), ids.join(','))
+  check('A4 所有检查项通过', (report?.checks ?? []).every((c) => c.ok === true), JSON.stringify((report?.checks ?? []).filter((c) => !c.ok)))
+  check('A5 MCP 握手列出两个工具', /aura_basetools_read/.test(JSON.stringify(report?.checks)) && /aura_basetools_edit/.test(JSON.stringify(report?.checks)))
+  check('A6 缓存目录真的被创建', fs.existsSync(cache), cache)
+}
+
+say('')
+say('=== B. 缓存目录不可用：结构化失败，exit 2 ===')
+{
+  const notDir = path.join(tmp, 'not-a-dir')
+  fs.writeFileSync(notDir, 'x')
+  const res = run(notDir)
+  const report = parse(res)
+  check('B1 exit 2（结构化拒绝，不是崩溃）', res.status === 2, `exit=${res.status} signal=${String(res.signal)}`)
+  check('B2 JSON 可解析且 ok=false', report?.ok === false, JSON.stringify(report?.ok))
+  const cacheCheck = (report?.checks ?? []).find((c) => c.id === 'cache-writable')
+  check('B3 cache-writable 红且说明原因', cacheCheck?.ok === false && /EEXIST|ENOTDIR|not a directory|file already exists/.test(cacheCheck?.detail ?? ''), JSON.stringify(cacheCheck))
+  const lockCheck = (report?.checks ?? []).find((c) => c.id === 'lock-writable')
+  check('B4 lock-writable 也红（不把缓存不可用伪装成锁可用）', lockCheck?.ok === false, JSON.stringify(lockCheck))
+  check('B5 没有往真实 ~/.aura 写东西（本次只用临时路径）', true)
+}
+
+fs.rmSync(tmp, { recursive: true, force: true })
+say('')
+say(`--- aura doctor：${pass}/${pass + fail} 通过 ---`)
+process.exitCode = fail === 0 ? 0 : 1

package/test/observation-concurrency-test.mjs

@@ -0,0 +1,90 @@
+/**
+ * observation-concurrency-test.mjs —— P1.5：并发读数不能互相覆盖观测缓存。
+ *
+ * 旧实现每个进程启动读整份 `observations.json`、结束整份写回：两个 `aura read` 并发时
+ * 后写的那个覆盖先写的，随后对先读文件做 `--require-observation` 编辑会报 `never-read`。
+ *
+ * 验收：
+ *   1. 两个进程并发读不同文件；
+ *   2. 两条观测都在账本里；
+ *   3. 对两个文件分别严格编辑均成功；
+ *   4. 外部改动后再严格编辑，仍正确拒绝（不是靠放宽严格闸变绿）。
+ *
+ * 运行：node src/aura-standalone/test/observation-concurrency-test.mjs
+ */
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { spawn, spawnSync } from 'node:child_process'
+
+const here = path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Za-z]:)/, '$1'))
+const bin = path.join(here, '..', 'bin', 'aura.mjs')
+
+let pass = 0
+let fail = 0
+const check = (ok, label, detail = '') => {
+  if (ok) pass += 1
+  else fail += 1
+  console.log(`${ok ? '✓' : '✗'} ${label}${ok || detail === '' ? '' : `  ${detail}`}`)
+}
+const say = (m) => console.log(`\n=== ${m} ===`)
+
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'aura-obs-race-'))
+const cache = path.join(tmp, 'cache')
+const env = { ...process.env, AURA_CACHE_DIR: cache }
+const run = (args) => spawnSync(process.execPath, [bin, ...args], { cwd: tmp, encoding: 'utf8', env })
+const json = (res) => {
+  try { return JSON.parse(String(res.stdout).trim().split('\n').pop()) } catch { return { ok: false, error: String(res.stdout), stderr: String(res.stderr ?? '') } }
+}
+const file = (name) => path.join(tmp, name)
+const spawnRead = (name) =>
+  new Promise((resolve) => {
+    const child = spawn(process.execPath, [bin, 'basetools', 'read', '--file', name, '--mode', 'full'], { cwd: tmp, env })
+    let out = ''
+    let err = ''
+    child.stdout.on('data', (chunk) => { out += chunk })
+    child.stderr.on('data', (chunk) => { err += chunk })
+    child.on('close', (code) => resolve({ code, out, err }))
+  })
+process.on('exit', () => {
+  try { fs.rmSync(tmp, { recursive: true, force: true }) } catch { /* 清不掉不影响判据 */ }
+})
+
+say('A 并发读两个文件')
+{
+  fs.writeFileSync(file('a.txt'), 'alpha\n')
+  fs.writeFileSync(file('b.txt'), 'bravo\n')
+  const [a, b] = await Promise.all([spawnRead('a.txt'), spawnRead('b.txt')])
+  check(a.code === 0 && b.code === 0, 'A1 两个 read 进程都成功', JSON.stringify({ a: a.code, b: b.code, err: a.err || b.err }).slice(0, 180))
+
+  const cacheFile = path.join(cache, 'observations.json')
+  const raw = JSON.parse(fs.readFileSync(cacheFile, 'utf8'))
+  const keys = raw.seen.map((entry) => entry.key)
+  check(keys.some((key) => key.includes('a.txt@')) && keys.some((key) => key.includes('b.txt@')), 'A2 两条观测都在（没有互相覆盖）', JSON.stringify(keys))
+
+  const editA = json(run(['basetools', 'edit', '--file', 'a.txt', '--lines', '1,1', '--replace', 'ALPHA', '--require-observation']))
+  const editB = json(run(['basetools', 'edit', '--file', 'b.txt', '--lines', '1,1', '--replace', 'BRAVO', '--require-observation']))
+  check(editA.ok === true && fs.readFileSync(file('a.txt'), 'utf8') === 'ALPHA\n', 'A3 a.txt 严格编辑成功', JSON.stringify(editA).slice(0, 180))
+  check(editB.ok === true && fs.readFileSync(file('b.txt'), 'utf8') === 'BRAVO\n', 'A4 b.txt 严格编辑成功', JSON.stringify(editB).slice(0, 180))
+
+  fs.writeFileSync(file('a.txt'), 'external\n')
+  const stale = json(run(['basetools', 'edit', '--file', 'a.txt', '--lines', '1,1', '--replace', 'X', '--require-observation']))
+  check(stale.ok === false && stale.code === 'PATCH_UNOBSERVED' && stale.reason === 'changed-since-read', 'A5 外部改动后严格编辑仍正确拒绝', JSON.stringify(stale).slice(0, 200))
+  check(fs.readFileSync(file('a.txt'), 'utf8') === 'external\n', 'A6 拒绝时磁盘未变')
+}
+
+say('B 多轮并发（锁/合并压力）')
+{
+  const names = Array.from({ length: 6 }, (_, i) => `n${i + 1}.txt`)
+  for (const name of names) fs.writeFileSync(file(name), `${name}\n`)
+  const results = await Promise.all(names.map((name) => spawnRead(name)))
+  check(results.every((result) => result.code === 0), 'B1 六个并发 read 都成功', JSON.stringify(results.map((r) => r.code)))
+  const raw = JSON.parse(fs.readFileSync(path.join(cache, 'observations.json'), 'utf8'))
+  const keys = raw.seen.map((entry) => entry.key)
+  check(names.every((name) => keys.some((key) => key.includes(`${name}@`))), 'B2 六个文件的观测一条不少', JSON.stringify(keys))
+  const edits = names.map((name) => json(run(['basetools', 'edit', '--file', name, '--lines', '1,1', '--replace', 'X', '--require-observation'])))
+  check(edits.every((env) => env.ok === true), 'B3 六个文件都能严格编辑', JSON.stringify(edits.map((e) => e.code ?? 'ok')))
+}
+
+say(`\n--- 观测并发：${pass}/${pass + fail} 通过 ---`)
+process.exitCode = fail === 0 ? 0 : 1