dsh-tower 1.3.0 → 2.0.1

package/lib/workspaceLock.js

@@ -0,0 +1,117 @@
+// Advisory repository workspace lock: one Tower session at a time when
+// `mode.workspaceLock` is enabled. Same-user trusted model, like the rest of
+// the Tower store: it prevents accidental double control, not a malicious
+// writer.
+import fsp from 'node:fs/promises'
+import path from 'node:path'
+import crypto from 'node:crypto'
+
+export function workspaceLockPath(commonDir) {
+  return path.join(commonDir, 'dsh-tower', 'tower.lock')
+}
+
+export function workspaceLockToken() {
+  return crypto.randomUUID()
+}
+
+async function readRecord(commonDir) {
+  const file = workspaceLockPath(commonDir)
+  try {
+    const text = await fsp.readFile(file, 'utf8')
+    const parsed = JSON.parse(text)
+    if (!parsed || typeof parsed !== 'object') return { file, record: null, corrupt: true }
+    return { file, record: parsed, corrupt: false }
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { file, record: null, corrupt: false }
+    return { file, record: null, corrupt: true }
+  }
+}
+
+async function removeLock(file) {
+  for (let attempt = 0; attempt < 5; attempt += 1) {
+    try {
+      await fsp.unlink(file)
+      return
+    } catch (error) {
+      if (error?.code === 'ENOENT') return
+      if (!['EPERM', 'EBUSY', 'EACCES'].includes(error?.code) || attempt === 4) throw error
+      await new Promise((resolve) => setTimeout(resolve, 10 * (attempt + 1)))
+    }
+  }
+}
+
+/**
+ * Try to become the repository's Tower session.
+ * @returns {{acquired:boolean, record?:object, holder?:object|null, tookOver?:boolean, corrupt?:boolean}}
+ */
+export async function acquireWorkspaceLock(commonDir, options) {
+  const { token, sessionId, agentId, staleMs = 300000, now = Date.now() } = options
+  await fsp.mkdir(path.dirname(workspaceLockPath(commonDir)), { recursive: true })
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    const record = { token, sessionId, agentId, pid: process.pid, at: now }
+    try {
+      await fsp.writeFile(workspaceLockPath(commonDir), JSON.stringify(record), { flag: 'wx' })
+      return { acquired: true, record, tookOver: attempt > 0 }
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error
+      const { record: current, corrupt, file } = await readRecord(commonDir)
+      if (corrupt || !current) {
+        // A corrupt lock is treated like an unknown holder; only a stale one
+        // is removed, so a concurrent writer is never silently overwritten.
+        let stale = false
+        try {
+          const stat = await fsp.stat(file)
+          stale = now - stat.mtimeMs > staleMs
+        } catch {
+          stale = true
+        }
+        if (stale) {
+          await removeLock(file)
+          continue
+        }
+        return { acquired: false, holder: null, corrupt: true }
+      }
+      if (current.sessionId === sessionId && current.agentId === agentId) {
+        await fsp.writeFile(workspaceLockPath(commonDir), JSON.stringify({ ...record, token: current.token }))
+        return { acquired: true, record: { ...record, token: current.token }, tookOver: false }
+      }
+      if (now - Number(current.at ?? 0) > staleMs) {
+        await removeLock(file)
+        continue
+      }
+      return { acquired: false, holder: current }
+    }
+  }
+  return { acquired: false, holder: null, corrupt: true }
+}
+
+/** Refresh the timestamp only when the lock still belongs to this session. */
+export async function touchWorkspaceLock(commonDir, options) {
+  const { token, now = Date.now() } = options
+  const { record, file } = await readRecord(commonDir)
+  if (!record || record.token !== token) return false
+  await fsp.writeFile(file, JSON.stringify({ ...record, at: now }))
+  return true
+}
+
+/** Release the lock only when this session owns it. */
+export async function releaseWorkspaceLock(commonDir, options) {
+  const { token } = options
+  const { record, file } = await readRecord(commonDir)
+  if (!record || (token && record.token !== token)) return false
+  await removeLock(file)
+  return true
+}
+
+export async function inspectWorkspaceLock(commonDir, options = {}) {
+  const { sessionId, staleMs = 300000, now = Date.now() } = options
+  const { record, corrupt } = await readRecord(commonDir)
+  if (!record) return { held: false, corrupt, self: false, holder: null, stale: false }
+  return {
+    held: true,
+    corrupt,
+    self: sessionId !== undefined && record.sessionId === sessionId,
+    holder: record,
+    stale: now - Number(record.at ?? 0) > staleMs,
+  }
+}

package/lib/worktreeOwnership.js

@@ -0,0 +1,166 @@
+// Worktree ownership verification.
+//
+// A stored worktree path is an identity claim, not a sandbox: before Tower
+// trusts it (preflight/merge/review/diff), the path must still resolve to the
+// same real directory, must not have been replaced by a symlink or junction,
+// and must still be the Git worktree of the recorded branch in the recorded
+// repository. Every mismatch is rejected with an actionable message; nothing
+// is repaired or recreated here.
+import fsp from 'node:fs/promises'
+import path from 'node:path'
+
+import { git } from './git.js'
+
+function fail(code, message) {
+  const error = new Error(message)
+  error.code = code
+  throw error
+}
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0
+}
+
+function compareKey(target) {
+  const resolved = path.resolve(target)
+  return process.platform === 'win32' ? resolved.toLowerCase() : resolved
+}
+
+function samePath(a, b) {
+  return compareKey(a) === compareKey(b)
+}
+
+async function realpathOrResolve(target) {
+  try {
+    return await fsp.realpath(target)
+  } catch (error) {
+    if (error?.code === 'ENOENT') return path.resolve(target)
+    throw error
+  }
+}
+
+/**
+ * Resolve a path to its canonical realpath. Requires an absolute path and an
+ * existing target; a dangling target is reported as a missing path.
+ */
+export async function canonicalPath(target) {
+  if (!isNonEmptyString(target)) fail('invalid-argument', 'path is required')
+  if (!path.isAbsolute(target)) fail('invalid-argument', `path must be an absolute path: ${target}`)
+  try {
+    return await fsp.realpath(target)
+  } catch (error) {
+    if (error?.code === 'ENOENT') fail('invalid-transition', `path does not exist: ${path.resolve(target)}`)
+    throw error
+  }
+}
+
+async function gitTop(resolved, label) {
+  try {
+    return await git(resolved, ['rev-parse', '--show-toplevel'])
+  } catch (error) {
+    fail('invalid-transition', `${label} ${resolved} is not a Git worktree: ${error.message}`)
+  }
+}
+
+/**
+ * Verify that a stored worktree still belongs to this repository, branch, and
+ * mission.
+ *
+ * @param {object} input
+ * @param {string} input.storedPath absolute worktree path recorded in state
+ * @param {string} [input.storedRealPath] realpath recorded when the worktree was created
+ * @param {string} input.branch expected branch
+ * @param {string} input.commonDir expected Git common dir (shared by worktrees)
+ * @param {string} [input.missionId] mission id, used in error messages
+ * @returns {Promise<{path:string, realPath:string}>}
+ */
+export async function assertOwnership(input = {}) {
+  const storedPath = input?.storedPath
+  const storedRealPath = input?.storedRealPath
+  const branch = input?.branch
+  const commonDir = input?.commonDir
+  const missionId = input?.missionId
+
+  if (!isNonEmptyString(storedPath)) fail('invalid-argument', 'storedPath is required')
+  if (!path.isAbsolute(storedPath)) fail('invalid-argument', `storedPath must be an absolute path: ${storedPath}`)
+  if (!isNonEmptyString(branch)) fail('invalid-argument', 'branch is required')
+  if (!isNonEmptyString(commonDir)) fail('invalid-argument', 'commonDir is required')
+  if (!path.isAbsolute(commonDir)) fail('invalid-argument', `commonDir must be an absolute path: ${commonDir}`)
+  if (missionId !== undefined && !isNonEmptyString(missionId)) {
+    fail('invalid-argument', `missionId must be a non-empty string: ${JSON.stringify(missionId)}`)
+  }
+  if (storedRealPath !== undefined && storedRealPath !== null && storedRealPath !== '') {
+    if (!isNonEmptyString(storedRealPath) || !path.isAbsolute(storedRealPath)) {
+      fail('invalid-argument', `storedRealPath must be an absolute path: ${storedRealPath}`)
+    }
+  }
+
+  const label = missionId ? `mission ${missionId} worktree` : 'worktree'
+  const resolved = path.resolve(storedPath)
+
+  let linkStat
+  try {
+    linkStat = await fsp.lstat(resolved)
+  } catch (error) {
+    if (error?.code === 'ENOENT') fail('invalid-transition', `${label} is missing: ${resolved}`)
+    throw error
+  }
+  if (linkStat.isSymbolicLink()) {
+    fail(
+      'invalid-transition',
+      `${label} ${resolved} is a symlink or junction; refusing to treat a redirected path as the owned worktree`,
+    )
+  }
+
+  const realPath = await canonicalPath(resolved)
+  const stat = await fsp.stat(realPath)
+  if (!stat.isDirectory()) fail('invalid-transition', `${label} is not a directory: ${resolved}`)
+
+  if (storedRealPath !== undefined && storedRealPath !== null && storedRealPath !== '' && !samePath(storedRealPath, realPath)) {
+    fail(
+      'invalid-transition',
+      `${label} real path changed: expected ${path.resolve(storedRealPath)}, found ${realPath}; refusing to use a replaced worktree`,
+    )
+  }
+
+  const topRaw = await gitTop(resolved, label)
+  const top = await canonicalPath(topRaw)
+  if (!samePath(top, realPath)) {
+    fail(
+      'invalid-transition',
+      `${label} path ${resolved} is not the Git worktree root (top-level is ${top}); refusing to trust a nested or redirected path`,
+    )
+  }
+
+  let head
+  try {
+    head = await git(resolved, ['rev-parse', '--abbrev-ref', 'HEAD'])
+  } catch (error) {
+    fail('invalid-transition', `${label} ${resolved} has no readable HEAD: ${error.message}`)
+  }
+  const actualBranch = head === 'HEAD' ? null : head.trim()
+  if (actualBranch !== branch) {
+    fail(
+      'invalid-transition',
+      `${label} ${resolved} is on ${actualBranch ?? 'detached HEAD'}, expected ${branch}`,
+    )
+  }
+
+  let commonRaw
+  try {
+    commonRaw = await git(resolved, ['rev-parse', '--git-common-dir'])
+  } catch (error) {
+    fail('invalid-transition', `${label} ${resolved} has no readable Git common dir: ${error.message}`)
+  }
+  const actualCommon = path.isAbsolute(commonRaw) ? path.resolve(commonRaw) : path.resolve(resolved, commonRaw)
+  const expectedCommon = await realpathOrResolve(path.resolve(commonDir))
+  const actualCommonReal = await realpathOrResolve(actualCommon)
+  if (!samePath(actualCommonReal, expectedCommon)) {
+    fail(
+      'invalid-transition',
+      `${label} ${resolved} belongs to a different repository (common dir ${actualCommonReal}, expected ${expectedCommon})`,
+    )
+  }
+
+  return { path: resolved, realPath }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-tower",
-  "version": "1.3.0",
+  "version": "2.0.1",
   "type": "module",
   "description": "DSH-native Tower: mission planning, worktree isolation, review-gated merges, and a human-owned Tower mode.",
   "license": "MIT",
@@ -42,6 +42,7 @@
     "skills/",
     "lib/*.js",
     "cordis.patch.yml",
+    "scripts/",
     "locale/*.json",
     "icon.svg",
     "README.md",
@@ -60,6 +61,8 @@
   "scripts": {
     "test": "node --test tests/*.test.mjs",
     "test:watch": "node --test --watch tests/*.test.mjs",
+    "test:coverage": "node --test --experimental-test-coverage tests/*.test.mjs",
+    "dev:hmr": "node scripts/enable-dev-hmr.mjs",
     "docs:check": "node scripts/check-docs.mjs",
     "check": "npm test && npm run docs:check"
   },

package/reviewer.js

@@ -13,6 +13,7 @@ const ALLOW = [
   'tower_send',
   'tower_inbox',
   'tower_finding',
+  'tower_findings',
   'tower_review',
   'skill',
 ]

package/scripts/check-docs.mjs

@@ -0,0 +1,135 @@
+// Documentation consistency check: tool names, blocker codes, error codes and
+// release numbers must not drift from the implementation. The Chinese
+// reference pages must cover the same names. Run: node scripts/check-docs.mjs
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const read = (file) => fs.readFileSync(path.join(root, file), 'utf8')
+const exists = (file) => fs.existsSync(path.join(root, file))
+
+const toolsSource = read('lib/tools.js') + read('index.js')
+const documentedTools = read('docs/reference/tools.md')
+const toolNames = [...new Set([...toolsSource.matchAll(/name: '(tower_[a-z_]+)'/g)].map((match) => match[1]))]
+  .filter((name) => name !== 'tower-control')
+  .sort()
+const missingTools = toolNames.filter((name) => !documentedTools.includes(`\`${name}\``))
+
+const towerSource = read('lib/tower.js')
+const blockersSource = read('docs/reference/blockers.md')
+const blockerCodes = new Set()
+for (const match of towerSource.matchAll(/push\(\s*'([a-z][a-z-]+)'/g)) blockerCodes.add(match[1])
+for (const code of [
+  'mission-missing',
+  'mission-not-completed',
+  'tasks-open',
+  'blockers-present',
+  'branch-missing',
+  'stale-base',
+  'read-only-survey',
+  'out-of-scope',
+  'base-dirty',
+  'deps-unmerged',
+  'no-review',
+  'review-mission-mismatch',
+  'not-clean',
+  'review-hold',
+  'review-not-approved',
+  'tip-moved',
+  'worker-busy',
+  'base-wrong-branch',
+  'branch-owned-by-closed-missions',
+  'merge-conflict',
+  'merge-hook-failed',
+  'merge-shape',
+  'rebase-conflict',
+  'worktree-dirty',
+  'no-check-evidence',
+  'worker-stale',
+  'worker-status-unknown',
+  'tests-missing',
+  'tests-failed',
+  'review-exemption-invalid',
+  'merge-intent-pending',
+  'batch-invalid',
+]) blockerCodes.add(code)
+const missingBlockers = [...blockerCodes].filter((code) => !blockersSource.includes(`\`${code}\``)).sort()
+
+const eventNames = [
+  'init',
+  'plan',
+  'mission',
+  'spawn',
+  'complete',
+  'review',
+  'merge',
+  'rebase',
+  'teardown',
+  'finding',
+  'findings',
+  'send',
+  'inbox',
+  'interrupt',
+  'diff',
+  'adopt',
+  'roster',
+  'status',
+  'preflight',
+  'doctor',
+  'test',
+  'batch',
+  'resource',
+  'import_legacy',
+  'legacy_map',
+]
+const documentedEvents = read('docs/reference/events.md')
+const missingEvents = eventNames.filter((name) => !documentedEvents.includes(`\`tower/${name}\``))
+
+const errorsSource = read('lib/errors.js')
+const documentedErrors = read('docs/reference/errors.md')
+const errorCodes = [...new Set([...errorsSource.matchAll(/^ {2}'([a-z][a-z-]+)':/gm)].map((match) => match[1]))].sort()
+const missingErrors = errorCodes.filter((code) => !documentedErrors.includes(`\`${code}\``))
+
+const packageJson = JSON.parse(read('package.json'))
+const changelog = read('CHANGELOG.md')
+const missingChangelog = !changelog.includes(`## ${packageJson.version}`)
+
+const problems = []
+if (missingTools.length > 0) problems.push(`docs/reference/tools.md misses tools: ${missingTools.join(', ')}`)
+if (missingBlockers.length > 0) problems.push(`docs/reference/blockers.md misses codes: ${missingBlockers.join(', ')}`)
+if (missingErrors.length > 0) problems.push(`docs/reference/errors.md misses codes: ${missingErrors.join(', ')}`)
+if (missingEvents.length > 0) problems.push(`docs/reference/events.md misses events: ${missingEvents.join(', ')}`)
+if (missingChangelog) problems.push(`CHANGELOG.md misses version ${packageJson.version}`)
+
+// Chinese parity: when the translation tree exists it must cover the same
+// reference names, so a tool or code cannot be added only in English.
+if (exists('docs/zh')) {
+  const zhPages = {
+    'docs/zh/README.md': null,
+    'docs/zh/reference/tools.md': (text) => toolNames.filter((name) => !text.includes(`\`${name}\``)),
+    'docs/zh/reference/blockers.md': (text) => [...blockerCodes].filter((code) => !text.includes(`\`${code}\``)),
+    'docs/zh/reference/errors.md': (text) => errorCodes.filter((code) => !text.includes(`\`${code}\``)),
+    'docs/zh/reference/events.md': (text) => eventNames.filter((name) => !text.includes(`\`tower/${name}\``)),
+    'docs/zh/reference/config.md': null,
+    'docs/zh/guide/hot-reload.md': null,
+  }
+  for (const [page, check] of Object.entries(zhPages)) {
+    if (!exists(page)) {
+      problems.push(`${page} is missing (Chinese docs parity)`)
+      continue
+    }
+    if (!check) continue
+    const missing = check(read(page))
+    if (missing.length > 0) problems.push(`${page} misses: ${missing.join(', ')}`)
+  }
+}
+
+if (problems.length > 0) {
+  console.error('documentation check failed:')
+  for (const problem of problems) console.error(`- ${problem}`)
+  process.exit(1)
+}
+console.log(
+  `docs ok: ${toolNames.length} tools, ${blockerCodes.size} blocker codes, ${errorCodes.length} error codes, ${eventNames.length} events, version ${packageJson.version}`,
+)