dsh-remote 0.8.46 → 0.8.48

package/lib/search.js

@@ -1,230 +1,235 @@
-// dsh-remote — portable recursive search over SFTP.
-// Replaces `find … -exec grep` (which needs a POSIX shell and dies on
-// Windows remotes). Walks the remote tree over SFTP readdir/stat/readFile with
-// the same bounded-parallelism + ignore rules as the mirror sync.
-import { joinRemotePath, shq } from './paths.js'
-
-function mapLimit(items, limit, fn) {
-  const limitN = Math.max(1, Math.min(Math.floor(limit) || 1, items.length))
-  let next = 0
-  const worker = async () => {
-    while (next < items.length) {
-      const i = next++
-      try { await fn(items[i], i) } catch { /* per-item errors are the fn's concern */ }
-    }
-  }
-  const workers = []
-  for (let w = 0; w < limitN; w++) workers.push(worker())
-  return Promise.all(workers)
-}
-
-/** fnmatch-lite for the `glob` filter (matches the entry BASENAME). */
-export function matchGlob(name, glob) {
-  let re = ''
-  let i = 0
-  const g = String(glob || '')
-  while (i < g.length) {
-    const c = g[i]
-    if (c === '*') {
-      if (g[i + 1] === '*') { re += '.*'; i += 2; continue }
-      re += '[^/]*'; i++; continue
-    }
-    if (c === '?') { re += '[^/]'; i++; continue }
-    if ('\\^$+{}[]()|.'.includes(c)) re += '\\' + c
-    else re += c
-    i++
-  }
-  return new RegExp('^' + re + '$').test(String(name))
-}
-
-const BINARY_SNIFF = 8192
-function looksBinary(buf) {
-  const n = Math.min(buf.length, BINARY_SNIFF)
-  for (let i = 0; i < n; i++) if (buf[i] === 0) return true
-  return false
-}
-
-/**
- * Recursively search a remote directory.
- *
- * Cancellation (issue #44): the walk takes an AbortSignal and checks it at every
- * directory and every entry. Before this it was completely uninterruptible —
- * no signal was accepted and no flag was consulted — so a large-tree search
- * could never be stopped: DSH tool cancellation is *cooperative*
- * (@deepseek-ai/dsh-tool-call-timeout-policy can only ask a tool to stop), which
- * meant `session/cancel`, steering, and the tool timeout policy all had no
- * effect and the turn stayed `running` forever. On abort we return the partial
- * result instead of throwing, so the model still gets whatever was found.
- *
- * @param {object} sftp - pooled SFTP client
- * @param {string} rootDir
- * @param {object} opts - `signal` (AbortSignal), `maxDurationMs`, plus the caps below
- * @returns {Promise<{matches: Array<{path, line, text}>, scanned: number, truncated: boolean, cancelled?: boolean}>}
- */
-export async function searchTree(sftp, rootDir, opts = {}) {
-  const {
-    regex,             // RegExp (already compiled with ignoreCase where asked)
-    glob,              // optional basename glob filter
-    contextLines = 0,
-    maxMatches = 500,
-    maxDepth = 12,
-    maxFiles = 20000,
-    maxScanBytes = 1024 * 1024,
-    maxDurationMs = 0, // 0 = no wall-clock budget
-    isIgnored = () => false,
-    signal,
-  } = opts
-
-  const matches = []
-  let scanned = 0
-  let truncated = false
-  let cancelled = false
-  const startedAt = Date.now()
-
-  /** True when the caller asked us to stop (abort, or the time budget is spent). */
-  const shouldStop = () => {
-    if (cancelled || truncated) return true
-    if (signal && signal.aborted) { cancelled = true; return true }
-    if (maxDurationMs > 0 && Date.now() - startedAt >= maxDurationMs) { truncated = true; return true }
-    return false
-  }
-
-  const walk = async (dir, depth) => {
-    if (shouldStop() || scanned >= maxFiles) return
-    let entries = []
-    try { entries = (await sftp.readdir(dir)) || [] } catch { return }
-    const dirs = []
-    for (const e of entries) {
-      const name = String(e.filename)
-      if (name === '.' || name === '..') continue
-      const isDir = !!(e.attrs && e.attrs.isDirectory && e.attrs.isDirectory())
-      if (isDir) dirs.push(name)
-    }
-    // Depth-first, dirs first, but stop as soon as we hit caps.
-    for (const name of dirs) {
-      if (shouldStop() || scanned >= maxFiles) return
-      if (depth <= 0) continue
-      const sub = joinRemotePath(dir, name)
-      if (isIgnored(name, true)) continue
-      await walk(sub, depth - 1)
-    }
-    if (shouldStop() || scanned >= maxFiles) return
-
-    const fileNames = entries
-      .filter((e) => !(e.attrs && e.attrs.isDirectory && e.attrs.isDirectory()))
-      .map((e) => String(e.filename))
-      .filter((n) => n !== '.' && n !== '..')
-    await mapLimit(fileNames, 4, async (name) => {
-      // Checked per entry: this is the loop that used to run for hours.
-      if (shouldStop() || scanned >= maxFiles || matches.length >= maxMatches) return
-      if (glob && !matchGlob(name, glob)) return
-      if (isIgnored(name, false)) return
-      const fp = joinRemotePath(dir, name)
-      scanned++
-      let st
-      try { st = await sftp.stat(fp) } catch { return }
-      if (shouldStop()) return
-      if (st.size > maxScanBytes) return
-      let buf
-      try { buf = await sftp.readFile(fp) } catch { return }
-      if (shouldStop()) return
-      if (looksBinary(buf)) return
-      const content = buf.toString('utf8').replace(/\r\n/g, '\n')
-      const lines = content.split('\n')
-      const hitLines = new Set()
-      for (let i = 0; i < lines.length; i++) {
-        if (regex.test(lines[i])) {
-          regex.lastIndex = 0
-          for (let c = Math.max(0, i - contextLines); c <= Math.min(lines.length - 1, i + contextLines); c++) {
-            hitLines.add(c)
-          }
-          if (matches.length >= maxMatches) { truncated = true; return }
-        }
-      }
-      if (hitLines.size) {
-        for (const ln of [...hitLines].sort((a, b) => a - b)) {
-          if (matches.length >= maxMatches) { truncated = true; return }
-          matches.push({ path: fp, line: ln + 1, text: lines[ln] })
-        }
-      }
-    })
-  }
-
-  await walk(rootDir, maxDepth)
-  if (scanned >= maxFiles) truncated = true
-  return { matches, scanned, truncated, cancelled }
-}
-
-function parseGrepLines(stdout, maxMatches) {
-  const matches = []
-  let truncated = false
-  for (const line of String(stdout || '').split('\n')) {
-    if (!line) continue
-    const m = line.match(/^(.*?):(\d+):(.*)$/)
-    if (!m) continue
-    if (matches.length >= maxMatches) { truncated = true; break }
-    matches.push({ path: m[1], line: Number(m[2]), text: m[3] })
-  }
-  return { matches, truncated }
-}
-
-/**
- * POSIX fast path: `rg` then `grep -R`. Returns null when the remote has
- * neither, so the caller can fall back to an SFTP walk (Windows / no grep).
- */
-export async function searchViaShell(pool, rootDir, opts = {}) {
-  const {
-    pattern,
-    ignoreCase = true,
-    glob,
-    contextLines = 0,
-    maxMatches = 500,
-    signal,
-  } = opts
-  // Honour an already-aborted signal before spawning a remote grep on a huge tree.
-  if (signal && signal.aborted) {
-    return { matches: [], scanned: 0, truncated: false, cancelled: true, via: 'none' }
-  }
-  const ic = ignoreCase ? ' -i' : ''
-  const globFlag = glob ? ` --glob ${shq(glob)}` : ''
-  const ctx = contextLines > 0 ? ` -C ${Number(contextLines)}` : ''
-  const rg = `rg -n --no-heading -I${ic}${globFlag}${ctx} --max-count ${maxMatches} -- ${shq(pattern)} ${shq(rootDir)}`
-  const grepGlob = glob ? ` --include=${shq(glob)}` : ''
-  const grep = `grep -R -n -I -E${ic}${grepGlob}${ctx} -- ${shq(pattern)} ${shq(rootDir)}`
-  const script = `if command -v rg >/dev/null 2>&1; then ${rg}; elif command -v grep >/dev/null 2>&1; then ${grep}; else exit 127; fi`
-  const res = await pool.exec(script, { timeoutMs: opts.timeoutMs, signal })
-  // A cancelled call must return as cancelled (with whatever partial output the
-  // remote produced), NOT throw: throwing would make searchRemote fall through
-  // to the slower SFTP walk, i.e. keep running after the caller said stop.
-  if (res.signal === 'ABORTED') {
-    const partial = parseGrepLines(res.stdout, maxMatches)
-    return { matches: partial.matches, scanned: partial.matches.length, truncated: false, cancelled: true, via: 'none' }
-  }
-  // 0 = hits, 1 = no hits; other codes mean the tools are missing / failed.
-  if (res.signal === 'TIMEOUT') throw new Error('search timed out')
-  if (res.code !== 0 && res.code !== 1) throw new Error(res.stderr || `search exit ${res.code}`)
-  const parsed = parseGrepLines(res.stdout, maxMatches)
-  return {
-    matches: parsed.matches,
-    scanned: parsed.matches.length,
-    truncated: parsed.truncated || /truncated|max-count/i.test(String(res.stderr || '')),
-    via: /rg/.test(String(res.stderr || '')) ? 'rg' : 'grep',
-  }
-}
-
-/** Prefer a POSIX grep/rg, fall back to the portable SFTP walk. */
-export async function searchRemote(pool, rootDir, opts = {}) {
-  if (pool && pool.platform !== 'windows') {
-    try {
-      const fast = await searchViaShell(pool, rootDir, opts)
-      if (fast && Array.isArray(fast.matches)) return fast
-    } catch (e) {
-      // An abort is terminal, not a "try the slower fallback" signal.
-      if (opts.signal && opts.signal.aborted) {
-        return { matches: [], scanned: 0, truncated: false, cancelled: true, via: 'none' }
-      }
-    }
-  }
-  const sftp = await pool.sftp()
-  return searchTree(sftp, rootDir, opts)
-}
+// dsh-remote — portable recursive search over SFTP.
+// Replaces `find … -exec grep` (which needs a POSIX shell and dies on
+// Windows remotes). Walks the remote tree over SFTP readdir/stat/readFile with
+// the same bounded-parallelism + ignore rules as the mirror sync.
+import { joinRemotePath, relPathUnder, shq } from './paths.js'
+
+function mapLimit(items, limit, fn) {
+  const limitN = Math.max(1, Math.min(Math.floor(limit) || 1, items.length))
+  let next = 0
+  const worker = async () => {
+    while (next < items.length) {
+      const i = next++
+      try { await fn(items[i], i) } catch { /* per-item errors are the fn's concern */ }
+    }
+  }
+  const workers = []
+  for (let w = 0; w < limitN; w++) workers.push(worker())
+  return Promise.all(workers)
+}
+
+/** fnmatch-lite for the `glob` filter (matches the entry BASENAME). */
+export function matchGlob(name, glob) {
+  let re = ''
+  let i = 0
+  const g = String(glob || '')
+  while (i < g.length) {
+    const c = g[i]
+    if (c === '*') {
+      if (g[i + 1] === '*') { re += '.*'; i += 2; continue }
+      re += '[^/]*'; i++; continue
+    }
+    if (c === '?') { re += '[^/]'; i++; continue }
+    if ('\\^$+{}[]()|.'.includes(c)) re += '\\' + c
+    else re += c
+    i++
+  }
+  return new RegExp('^' + re + '$').test(String(name))
+}
+
+const BINARY_SNIFF = 8192
+function looksBinary(buf) {
+  const n = Math.min(buf.length, BINARY_SNIFF)
+  for (let i = 0; i < n; i++) if (buf[i] === 0) return true
+  return false
+}
+
+/**
+ * Recursively search a remote directory.
+ *
+ * Cancellation (issue #44): the walk takes an AbortSignal and checks it at every
+ * directory and every entry. Before this it was completely uninterruptible —
+ * no signal was accepted and no flag was consulted — so a large-tree search
+ * could never be stopped: DSH tool cancellation is *cooperative*
+ * (@deepseek-ai/dsh-tool-call-timeout-policy can only ask a tool to stop), which
+ * meant `session/cancel`, steering, and the tool timeout policy all had no
+ * effect and the turn stayed `running` forever. On abort we return the partial
+ * result instead of throwing, so the model still gets whatever was found.
+ *
+ * @param {object} sftp - pooled SFTP client
+ * @param {string} rootDir
+ * @param {object} opts - `signal` (AbortSignal), `maxDurationMs`, plus the caps below
+ * @returns {Promise<{matches: Array<{path, line, text}>, scanned: number, truncated: boolean, cancelled?: boolean}>}
+ */
+export async function searchTree(sftp, rootDir, opts = {}) {
+  const {
+    regex,             // RegExp (already compiled with ignoreCase where asked)
+    glob,              // optional basename glob filter
+    contextLines = 0,
+    maxMatches = 500,
+    maxDepth = 12,
+    maxFiles = 20000,
+    maxScanBytes = 1024 * 1024,
+    maxDurationMs = 0, // 0 = no wall-clock budget
+    isIgnored = () => false,
+    signal,
+  } = opts
+
+  const matches = []
+  let scanned = 0
+  let truncated = false
+  let cancelled = false
+  const startedAt = Date.now()
+
+  /** True when the caller asked us to stop (abort, or the time budget is spent). */
+  const shouldStop = () => {
+    if (cancelled || truncated) return true
+    if (signal && signal.aborted) { cancelled = true; return true }
+    if (maxDurationMs > 0 && Date.now() - startedAt >= maxDurationMs) { truncated = true; return true }
+    return false
+  }
+
+  const walk = async (dir, depth) => {
+    if (shouldStop() || scanned >= maxFiles) return
+    let entries = []
+    try { entries = (await sftp.readdir(dir)) || [] } catch { return }
+    const dirs = []
+    for (const e of entries) {
+      const name = String(e.filename)
+      if (name === '.' || name === '..') continue
+      const isDir = !!(e.attrs && e.attrs.isDirectory && e.attrs.isDirectory())
+      if (isDir) dirs.push(name)
+    }
+    // Depth-first, dirs first, but stop as soon as we hit caps.
+    for (const name of dirs) {
+      if (shouldStop() || scanned >= maxFiles) return
+      if (depth <= 0) continue
+      const sub = joinRemotePath(dir, name)
+      // isIgnored receives the path RELATIVE to the search root (the same
+      // contract sync has), so root-anchored ignore rules — `/proc/` when the
+      // workspace is the filesystem root (issue #60), `Library/Caches/` in the
+      // default search set — actually match here; a bare basename would never
+      // satisfy an anchored pattern and those rules were silently dead.
+      if (isIgnored(relPathUnder(rootDir, sub) || name, true)) continue
+      await walk(sub, depth - 1)
+    }
+    if (shouldStop() || scanned >= maxFiles) return
+
+    const fileNames = entries
+      .filter((e) => !(e.attrs && e.attrs.isDirectory && e.attrs.isDirectory()))
+      .map((e) => String(e.filename))
+      .filter((n) => n !== '.' && n !== '..')
+    await mapLimit(fileNames, 4, async (name) => {
+      // Checked per entry: this is the loop that used to run for hours.
+      if (shouldStop() || scanned >= maxFiles || matches.length >= maxMatches) return
+      if (glob && !matchGlob(name, glob)) return
+      const fp = joinRemotePath(dir, name)
+      if (isIgnored(relPathUnder(rootDir, fp) || name, false)) return
+      scanned++
+      let st
+      try { st = await sftp.stat(fp) } catch { return }
+      if (shouldStop()) return
+      if (st.size > maxScanBytes) return
+      let buf
+      try { buf = await sftp.readFile(fp) } catch { return }
+      if (shouldStop()) return
+      if (looksBinary(buf)) return
+      const content = buf.toString('utf8').replace(/\r\n/g, '\n')
+      const lines = content.split('\n')
+      const hitLines = new Set()
+      for (let i = 0; i < lines.length; i++) {
+        if (regex.test(lines[i])) {
+          regex.lastIndex = 0
+          for (let c = Math.max(0, i - contextLines); c <= Math.min(lines.length - 1, i + contextLines); c++) {
+            hitLines.add(c)
+          }
+          if (matches.length >= maxMatches) { truncated = true; return }
+        }
+      }
+      if (hitLines.size) {
+        for (const ln of [...hitLines].sort((a, b) => a - b)) {
+          if (matches.length >= maxMatches) { truncated = true; return }
+          matches.push({ path: fp, line: ln + 1, text: lines[ln] })
+        }
+      }
+    })
+  }
+
+  await walk(rootDir, maxDepth)
+  if (scanned >= maxFiles) truncated = true
+  return { matches, scanned, truncated, cancelled }
+}
+
+function parseGrepLines(stdout, maxMatches) {
+  const matches = []
+  let truncated = false
+  for (const line of String(stdout || '').split('\n')) {
+    if (!line) continue
+    const m = line.match(/^(.*?):(\d+):(.*)$/)
+    if (!m) continue
+    if (matches.length >= maxMatches) { truncated = true; break }
+    matches.push({ path: m[1], line: Number(m[2]), text: m[3] })
+  }
+  return { matches, truncated }
+}
+
+/**
+ * POSIX fast path: `rg` then `grep -R`. Returns null when the remote has
+ * neither, so the caller can fall back to an SFTP walk (Windows / no grep).
+ */
+export async function searchViaShell(pool, rootDir, opts = {}) {
+  const {
+    pattern,
+    ignoreCase = true,
+    glob,
+    contextLines = 0,
+    maxMatches = 500,
+    signal,
+  } = opts
+  // Honour an already-aborted signal before spawning a remote grep on a huge tree.
+  if (signal && signal.aborted) {
+    return { matches: [], scanned: 0, truncated: false, cancelled: true, via: 'none' }
+  }
+  const ic = ignoreCase ? ' -i' : ''
+  const globFlag = glob ? ` --glob ${shq(glob)}` : ''
+  const ctx = contextLines > 0 ? ` -C ${Number(contextLines)}` : ''
+  const rg = `rg -n --no-heading -I${ic}${globFlag}${ctx} --max-count ${maxMatches} -- ${shq(pattern)} ${shq(rootDir)}`
+  const grepGlob = glob ? ` --include=${shq(glob)}` : ''
+  const grep = `grep -R -n -I -E${ic}${grepGlob}${ctx} -- ${shq(pattern)} ${shq(rootDir)}`
+  const script = `if command -v rg >/dev/null 2>&1; then ${rg}; elif command -v grep >/dev/null 2>&1; then ${grep}; else exit 127; fi`
+  const res = await pool.exec(script, { timeoutMs: opts.timeoutMs, signal })
+  // A cancelled call must return as cancelled (with whatever partial output the
+  // remote produced), NOT throw: throwing would make searchRemote fall through
+  // to the slower SFTP walk, i.e. keep running after the caller said stop.
+  if (res.signal === 'ABORTED') {
+    const partial = parseGrepLines(res.stdout, maxMatches)
+    return { matches: partial.matches, scanned: partial.matches.length, truncated: false, cancelled: true, via: 'none' }
+  }
+  // 0 = hits, 1 = no hits; other codes mean the tools are missing / failed.
+  if (res.signal === 'TIMEOUT') throw new Error('search timed out')
+  if (res.code !== 0 && res.code !== 1) throw new Error(res.stderr || `search exit ${res.code}`)
+  const parsed = parseGrepLines(res.stdout, maxMatches)
+  return {
+    matches: parsed.matches,
+    scanned: parsed.matches.length,
+    truncated: parsed.truncated || /truncated|max-count/i.test(String(res.stderr || '')),
+    via: /rg/.test(String(res.stderr || '')) ? 'rg' : 'grep',
+  }
+}
+
+/** Prefer a POSIX grep/rg, fall back to the portable SFTP walk. */
+export async function searchRemote(pool, rootDir, opts = {}) {
+  if (pool && pool.platform !== 'windows') {
+    try {
+      const fast = await searchViaShell(pool, rootDir, opts)
+      if (fast && Array.isArray(fast.matches)) return fast
+    } catch (e) {
+      // An abort is terminal, not a "try the slower fallback" signal.
+      if (opts.signal && opts.signal.aborted) {
+        return { matches: [], scanned: 0, truncated: false, cancelled: true, via: 'none' }
+      }
+    }
+  }
+  const sftp = await pool.sftp()
+  return searchTree(sftp, rootDir, opts)
+}

package/lib/sftp-surface.js

@@ -1,76 +1,76 @@
-// dsh-remote — the promisified SFTP surface every backend presents.
-//
-// Both SSH transports (the native ssh2 pool in lib/pool.js and the
-// system-OpenSSH pool in lib/openssh.js) must expose the SAME object to
-// callers: lib/sync.js, lib/search.js, lib/routes-fs.js, lib/remote-fs.js and
-// the rw_* tools all consume this exact shape. Keeping one implementation
-// matters more than it looks: the timeout, dead-channel and range-read rules
-// below encode failures that were expensive to find (issue #44), and a second
-// hand-copied version would drift away from the fixed one.
-//
-// The two rules that are easy to get wrong:
-//   • A dead channel must fail FAST. ssh2's own EOF handling only rejects the
-//     requests pending at that moment; every later request is registered and
-//     never answered, so each waits out the full commandTimeoutMs. Over a tree
-//     walk that is N × 2 × timeout — days on a large directory.
-//   • `readPartial` exists so an oversized preview never downloads the whole
-//     file to show its head.
-import { toSftpPath } from './paths.js'
-
-/**
- * Wrap a live SFTP channel (ssh2's SFTP instance) in the promisified surface
- * the plugin's callers expect.
- *
- * @param {object} sftp - an ssh2 SFTP channel (already negotiated/ready).
- * @param {object} opts
- * @param {number} opts.commandTimeoutMs - per-operation timeout.
- * @returns {object} promisified sftp surface.
- */
-export function buildSftpSurface(sftp, { commandTimeoutMs }) {
-  // A dead channel must fail fast (see the header). ssh2's SFTP instance and the
-  // system-OpenSSH engine both emit these, so one hook covers both backends.
-  let dead = false
-  const markDead = () => { dead = true }
-  if (typeof sftp.on === 'function') {
-    sftp.on('end', markDead)
-    sftp.on('close', markDead)
-    sftp.on('error', markDead)
-  }
-  const withTimeout = (fn) => (...args) =>
-    new Promise((resolve, reject) => {
-      if (dead) return reject(new Error('sftp channel closed'))
-      const timer = setTimeout(() => reject(new Error('sftp operation timed out')), commandTimeoutMs)
-      const finish = (err, value) => {
-        clearTimeout(timer)
-        err ? reject(err) : resolve(value)
-      }
-      try { fn(...args, finish) } catch (err) { clearTimeout(timer); reject(err) }
-    })
-  const P = (p) => toSftpPath(p)
-  return {
-    readdir: (dir) => withTimeout((d, cb) => sftp.readdir(d, cb))(P(dir)),
-    stat: (p) => withTimeout((d, cb) => sftp.stat(d, cb))(P(p)),
-    lstat: (p) => withTimeout((d, cb) => sftp.lstat(d, cb))(P(p)),
-    mkdir: (dir) => withTimeout((d, cb) => sftp.mkdir(d, cb))(P(dir)),
-    rmdir: (dir) => withTimeout((d, cb) => sftp.rmdir(d, cb))(P(dir)),
-    unlink: (p) => withTimeout((d, cb) => sftp.unlink(d, cb))(P(p)),
-    rename: (p, d) => withTimeout((a, b, cb) => sftp.rename(a, b, cb))(P(p), P(d)),
-    realpath: (p) => withTimeout((d, cb) => sftp.realpath(d, cb))(P(p)),
-    readFile: (p) => withTimeout((d, cb) => sftp.readFile(d, cb))(P(p)),
-    writeFile: (p, data) => withTimeout((d, data2, cb) => sftp.writeFile(d, data2, cb))(P(p), data),
-    fastGet: (p, lp) => withTimeout((d, l, cb) => sftp.fastGet(d, l, cb))(P(p), lp),
-    fastPut: (lp, p) => withTimeout((l, d, cb) => sftp.fastPut(l, d, cb))(lp, P(p)),
-    // Range read for oversized previews: never downloads the whole file.
-    readPartial: (p, offset, length) => withTimeout((d, off, len, cb) => {
-      sftp.open(d, 'r', (e, handle) => {
-        if (e) return cb(e)
-        const buf = Buffer.alloc(len)
-        sftp.read(handle, buf, 0, len, off, (e2, bytesRead, data) => {
-          sftp.close(handle, () => {})
-          if (e2) return cb(e2)
-          cb(null, Buffer.isBuffer(data) ? data.subarray(0, bytesRead) : buf.subarray(0, bytesRead))
-        })
-      })
-    })(P(p), offset, length),
-  }
-}
+// dsh-remote — the promisified SFTP surface every backend presents.
+//
+// Both SSH transports (the native ssh2 pool in lib/pool.js and the
+// system-OpenSSH pool in lib/openssh.js) must expose the SAME object to
+// callers: lib/sync.js, lib/search.js, lib/routes-fs.js, lib/remote-fs.js and
+// the rw_* tools all consume this exact shape. Keeping one implementation
+// matters more than it looks: the timeout, dead-channel and range-read rules
+// below encode failures that were expensive to find (issue #44), and a second
+// hand-copied version would drift away from the fixed one.
+//
+// The two rules that are easy to get wrong:
+//   • A dead channel must fail FAST. ssh2's own EOF handling only rejects the
+//     requests pending at that moment; every later request is registered and
+//     never answered, so each waits out the full commandTimeoutMs. Over a tree
+//     walk that is N × 2 × timeout — days on a large directory.
+//   • `readPartial` exists so an oversized preview never downloads the whole
+//     file to show its head.
+import { toSftpPath } from './paths.js'
+
+/**
+ * Wrap a live SFTP channel (ssh2's SFTP instance) in the promisified surface
+ * the plugin's callers expect.
+ *
+ * @param {object} sftp - an ssh2 SFTP channel (already negotiated/ready).
+ * @param {object} opts
+ * @param {number} opts.commandTimeoutMs - per-operation timeout.
+ * @returns {object} promisified sftp surface.
+ */
+export function buildSftpSurface(sftp, { commandTimeoutMs }) {
+  // A dead channel must fail fast (see the header). ssh2's SFTP instance and the
+  // system-OpenSSH engine both emit these, so one hook covers both backends.
+  let dead = false
+  const markDead = () => { dead = true }
+  if (typeof sftp.on === 'function') {
+    sftp.on('end', markDead)
+    sftp.on('close', markDead)
+    sftp.on('error', markDead)
+  }
+  const withTimeout = (fn) => (...args) =>
+    new Promise((resolve, reject) => {
+      if (dead) return reject(new Error('sftp channel closed'))
+      const timer = setTimeout(() => reject(new Error('sftp operation timed out')), commandTimeoutMs)
+      const finish = (err, value) => {
+        clearTimeout(timer)
+        err ? reject(err) : resolve(value)
+      }
+      try { fn(...args, finish) } catch (err) { clearTimeout(timer); reject(err) }
+    })
+  const P = (p) => toSftpPath(p)
+  return {
+    readdir: (dir) => withTimeout((d, cb) => sftp.readdir(d, cb))(P(dir)),
+    stat: (p) => withTimeout((d, cb) => sftp.stat(d, cb))(P(p)),
+    lstat: (p) => withTimeout((d, cb) => sftp.lstat(d, cb))(P(p)),
+    mkdir: (dir) => withTimeout((d, cb) => sftp.mkdir(d, cb))(P(dir)),
+    rmdir: (dir) => withTimeout((d, cb) => sftp.rmdir(d, cb))(P(dir)),
+    unlink: (p) => withTimeout((d, cb) => sftp.unlink(d, cb))(P(p)),
+    rename: (p, d) => withTimeout((a, b, cb) => sftp.rename(a, b, cb))(P(p), P(d)),
+    realpath: (p) => withTimeout((d, cb) => sftp.realpath(d, cb))(P(p)),
+    readFile: (p) => withTimeout((d, cb) => sftp.readFile(d, cb))(P(p)),
+    writeFile: (p, data) => withTimeout((d, data2, cb) => sftp.writeFile(d, data2, cb))(P(p), data),
+    fastGet: (p, lp) => withTimeout((d, l, cb) => sftp.fastGet(d, l, cb))(P(p), lp),
+    fastPut: (lp, p) => withTimeout((l, d, cb) => sftp.fastPut(l, d, cb))(lp, P(p)),
+    // Range read for oversized previews: never downloads the whole file.
+    readPartial: (p, offset, length) => withTimeout((d, off, len, cb) => {
+      sftp.open(d, 'r', (e, handle) => {
+        if (e) return cb(e)
+        const buf = Buffer.alloc(len)
+        sftp.read(handle, buf, 0, len, off, (e2, bytesRead, data) => {
+          sftp.close(handle, () => {})
+          if (e2) return cb(e2)
+          cb(null, Buffer.isBuffer(data) ? data.subarray(0, bytesRead) : buf.subarray(0, bytesRead))
+        })
+      })
+    })(P(p), offset, length),
+  }
+}