dsh-remote 0.7.4 → 0.8.1

package/lib/paths.js

@@ -0,0 +1,169 @@
+// dsh-remote — pure path / shell helpers (no fs, no ssh).
+// Split out of lib/index.js so they are unit-testable without loading the
+// plugin. Both POSIX (`/a/b`) and Windows (`D:\Code`, `\\server\share`) forms
+// are supported everywhere.
+
+/** Single-quote one shell argument verbatim. */
+export function shq(s) {
+  return "'" + String(s).replace(/'/g, "'\\''") + "'"
+}
+
+/**
+ * Normalize a remote path into a clean absolute path, supporting BOTH POSIX
+ * (`/home/user`) and Windows (`D:\Code`, `C:/Users/x`, `\\server\share`) forms.
+ *
+ * - POSIX paths keep `/` separators and a leading `/`.
+ * - Windows drive paths keep their `X:` prefix and are returned with `\`
+ *   separators (the native form on a Windows remote); a leading `/` is NOT
+ *   added, so `D:\Code` stays `D:\Code` instead of becoming `/D:\Code`.
+ * - UNC paths (`\\server\share\…`) keep the `\\server\share` prefix.
+ * - `.` / `..` segments are collapsed in both separator styles.
+ */
+export function normalizeRemotePath(p) {
+  const s = String(p)
+  // Windows UNC: \\server\share\…
+  const unc = s.match(/^(\\\\[^\\]+(?:\\[^\\]+)?)(?:\\|$)(.*)$/s)
+  if (unc) {
+    const [prefix, rest] = [unc[1], unc[2]]
+    const parts = []
+    for (const seg of rest.split(/[\\/]+/)) {
+      if (seg === '' || seg === '.') continue
+      if (seg === '..') { parts.pop(); continue }
+      parts.push(seg)
+    }
+    return parts.length ? prefix + '\\' + parts.join('\\') : prefix
+  }
+  // Windows drive: X:\… or X:/…
+  const drive = s.match(/^([a-zA-Z]:)(?:[\\/]|$)(.*)$/s)
+  if (drive) {
+    const [prefix, rest] = [drive[1], drive[2]]
+    const parts = []
+    for (const seg of rest.split(/[\\/]+/)) {
+      if (seg === '' || seg === '.') continue
+      if (seg === '..') { parts.pop(); continue }
+      parts.push(seg)
+    }
+    return prefix + '\\' + parts.join('\\')
+  }
+  // POSIX: /a/b/c
+  const parts = []
+  for (const seg of s.split('/')) {
+    if (seg === '' || seg === '.') continue
+    if (seg === '..') {
+      parts.pop()
+      continue
+    }
+    parts.push(seg)
+  }
+  return '/' + parts.join('/')
+}
+
+/** Join a remote dir + entry name, honoring the dir's own separator style. */
+export function joinRemotePath(dir, name) {
+  const d = String(dir)
+  if (!d) return String(name)
+  if (d.endsWith('/') || d.endsWith('\\')) return d + String(name)
+  return d + (d.includes('\\') ? '\\' : '/') + String(name)
+}
+
+/** Parent dir of a remote absolute path (string-level; POSIX or Windows). */
+export function remoteDirname(p) {
+  const norm = normalizeRemotePath(p)
+  // Windows drive/UNC root: D:\ or \\server\share
+  if (norm === '/' || /^[a-zA-Z]:\\?$/.test(norm) || /^\\\\[^\\]+\\[^\\]+$/.test(norm)) {
+    // Ensure a drive root ends with a backslash: D: → D:\
+    const m = norm.match(/^([a-zA-Z]:)$/)
+    return m ? m[1] + '\\' : norm
+  }
+  const sep = norm.includes('\\') ? '\\' : '/'
+  const idx = norm.lastIndexOf(sep)
+  if (idx <= 0) {
+    // Windows drive with a child (D:\Code) → D:\
+    const m = norm.match(/^([a-zA-Z]:)\\/)
+    return m ? m[1] + '\\' : sep === '/' && norm.startsWith('/') ? '/' : norm
+  }
+  // A parent that is a Windows drive root also needs the trailing backslash.
+  const parent = norm.slice(0, idx)
+  if (sep === '\\' && /^[a-zA-Z]:$/.test(parent)) return parent + '\\'
+  return parent
+}
+
+/** Create every level of a remote dir via SFTP (true mkdir -p: parents AND the
+ * target itself), working for both POSIX (`/a/b`) and Windows (`D:\a\b`)
+ * paths. Best effort: an existing or permission-denied level is skipped.
+ * FILE-oriented callers must pass the parent dir (remoteDirname(filePath)). */
+export async function mkdirRemoteDirs(sftp, dir) {
+  const target = normalizeRemotePath(dir)
+  const isWin = target.includes('\\')
+  // Split off a Windows drive prefix (D:) so it is not treated as a segment.
+  const drive = isWin ? (target.match(/^([a-zA-Z]:)[\\/]?(.*)$/s) || null) : null
+  const segs = drive ? drive[2].split(/[\\/]/).filter(Boolean) : target.split(/[\\/]/).filter(Boolean)
+  let cur = isWin ? (drive ? drive[1] + '\\' : '') : ''
+  // Drive root (D:\) itself, best effort (usually exists).
+  if (isWin && cur) { try { await sftp.mkdir(cur) } catch { /* exists */ } }
+  for (const s of segs) {
+    if (cur) {
+      if (!cur.endsWith('\\') && !cur.endsWith('/')) cur += isWin ? '\\' : '/'
+      cur += s
+    } else {
+      cur = (isWin ? s + ':' : '/' + s)
+    }
+    try { await sftp.mkdir(cur) } catch { /* exists or no perms */ }
+  }
+}
+
+/**
+ * Convert an internal remote path (POSIX `/a/b` or Windows `D:\Code`) into the
+ * path format the SFTP server understands.
+ *
+ * Windows OpenSSH's sftp-server accepts POSIX-style paths: a drive letter is
+ * written `/D:/…` (equivalent to `D:\…`). POSIX paths pass through unchanged.
+ * UNC paths are kept as-is (the server resolves `\\server\share` itself).
+ */
+export function toSftpPath(p) {
+  const norm = normalizeRemotePath(p)
+  const m = norm.match(/^([a-zA-Z]):\\(.*)$/s)
+  if (m) return '/' + m[1] + ':/' + m[2].replace(/\\/g, '/')
+  return norm
+}
+
+/** Basename of a remote absolute path (POSIX or Windows). */
+export function remotePathBase(p) {
+  const norm = normalizeRemotePath(p).replace(/[\\/]+$/, '')
+  const base = norm.split(/[\\/]/).pop()
+  // Windows drive root (D:\) has no meaningful basename
+  if (!base || /^[a-zA-Z]:$/.test(base)) return 'workspace'
+  return base
+}
+
+/** Relative path of `p` under `root` (POSIX form, no leading slash), or null
+ * when `p` is not inside `root`. Both POSIX and Windows drive paths work
+ * (Windows is compared in its `/D:/…` POSIX-equivalent form). */
+export function relPathUnder(root, p) {
+  const posix = (x) => {
+    let n = normalizeRemotePath(x).replace(/[\\/]+$/, '')
+    const m = n.match(/^([a-zA-Z]):(.*)$/s)
+    if (m) return '/' + m[1].toLowerCase() + ':/' + (m[2] ? m[2].replace(/\\/g, '/').replace(/^\/+/, '') : '')
+    return n.replace(/\\/g, '/')
+  }
+  const r = posix(root)
+  const n = posix(p)
+  if (n === r) return ''
+  const prefix = r === '/' ? '/' : r + '/'
+  if (n.startsWith(prefix)) return n.slice(prefix.length)
+  return null
+}
+
+export function truncate(s, max) {
+  if (s.length <= max) return s
+  return s.slice(0, max) + `\n…[truncated: ${s.length - max} more chars]`
+}
+
+/** 32-bit string hash rendered in base36 (short, collision-safe enough). */
+export function shortHash(s) {
+  let h = 0
+  for (let i = 0; i < s.length; i++) {
+    h = ((h << 5) - h + s.charCodeAt(i)) | 0
+  }
+  return (h >>> 0).toString(36)
+}

package/lib/search.js

@@ -0,0 +1,127 @@
+// 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 } 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.
+ * @returns {Promise<{matches: Array<{path, line, text}>, scanned: number, truncated: 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,
+    isIgnored = () => false,
+  } = opts
+
+  const matches = []
+  let scanned = 0
+  let truncated = false
+
+  const walk = async (dir, depth) => {
+    if (truncated || 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 (truncated || scanned >= maxFiles) return
+      if (depth <= 0) continue
+      const sub = joinRemotePath(dir, name)
+      if (isIgnored(name, true)) continue
+      await walk(sub, depth - 1)
+    }
+    if (truncated || 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) => {
+      if (truncated || 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 (st.size > maxScanBytes) return
+      let buf
+      try { buf = await sftp.readFile(fp) } catch { 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)
+  return { matches, scanned, truncated }
+}

package/lib/sshconfig.js

@@ -0,0 +1,57 @@
+// dsh-remote — ~/.ssh/config parser for the "import from ssh config" feature.
+// Pure parsing (no auth material is ever read: only Host/HostName/User/Port/
+// IdentityFile/ProxyJump). IdentityFile is imported as a PATH reference only —
+// the plugin never auto-reads keys (v0.5.5 policy).
+import { readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import path from 'node:path'
+
+export const sshConfigPath = () => path.join(homedir(), '.ssh', 'config')
+
+/** Read the user's ~/.ssh/config text ('' when absent/unreadable). */
+export function readSshConfigText(filePath = sshConfigPath()) {
+  try {
+    return readFileSync(filePath, 'utf8')
+  } catch {
+    return ''
+  }
+}
+
+/**
+ * Parse OpenSSH config text into host entries.
+ * @returns {Array<{host: string, hostName: string, user: string, port: number, identityFile: string, proxyJump: string}>}
+ *   host = alias pattern (may be '*' / '!foo' / comma list — caller filters).
+ */
+export function parseSshConfig(text) {
+  const entries = []
+  let cur = null
+  const lines = String(text || '').split('\n')
+  for (const raw of lines) {
+    const line = raw.trim()
+    if (!line || line.startsWith('#') || line.startsWith('Include ')) continue
+    const m = line.match(/^(\S+)\s+(.*)$/)
+    if (!m) continue
+    const key = m[1].toLowerCase()
+    const val = m[2].trim()
+    if (key === 'host') {
+      cur = { host: val, hostName: '', user: '', port: 22, identityFile: '', proxyJump: '' }
+      entries.push(cur)
+      continue
+    }
+    if (!cur) continue
+    if (key === 'hostname') cur.hostName = val
+    else if (key === 'user') cur.user = val
+    else if (key === 'port') cur.port = Number(val) || 22
+    else if (key === 'identityfile') cur.identityFile = val
+    else if (key === 'proxyjump') cur.proxyJump = val
+  }
+  return entries
+}
+
+/** Entries a user can actually import: concrete aliases (skip wildcards). */
+export function importableEntries(text) {
+  return parseSshConfig(text).filter((e) => {
+    if (!e.host || e.host.includes('*') || e.host.includes('!') || e.host.includes(',')) return false
+    return e.hostName || e.user || e.port !== 22 || e.identityFile || e.proxyJump
+  })
+}

package/lib/sync.js

@@ -0,0 +1,270 @@
+// dsh-remote — three-way conflict-aware mirror sync (remote ⇄ local mirror).
+//
+// Why three-way: plain rsync-style pull/push silently clobbers whichever side
+// changed while the other side was edited. We keep a per-mirror snapshot of the
+// last-synced remote state (`.dsh-remote-sync-state.json`: relPath →
+// {mtime,size}) and compare remote (R), local (L) and last-synced (S):
+//
+//   R==S && L==S          → unchanged, skip
+//   R!=S && L==S          → remote changed → pull it (or push when pushing)
+//   R==S && L!=S          → local changed, remote untouched
+//                            • pull (rw_sync): would clobber local edit → conflict
+//                            • push (rw_push): normal upload
+//   R!=S && L!=S && R==L  → both changed to the same bytes → skip
+//   R!=S && L!=S && R!=L  → BOTH changed differently → conflict (never clobber)
+//
+// `force: true` downgrades every conflict to a plain overwrite (rsync behavior).
+// `dryRun: true` computes the full plan without writing anything.
+// After a successful pull the local mtime is aligned to the remote mtime, and
+// after a successful push the local mtime is aligned to the remote mtime the
+// server assigned — so the invariant L==R==S holds and the next run is cheap.
+import { readdirSync, statSync, mkdirSync, existsSync, readFileSync, writeFileSync, utimesSync, renameSync } from 'node:fs'
+import path from 'node:path'
+import { joinRemotePath, relPathUnder } 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)
+}
+
+const keyOf = (size, mtime) => `${size}:${Math.floor(mtime || 0)}`
+const localKey = (st) => (st ? keyOf(st.size, st.mtimeMs / 1000) : null)
+const remoteKey = (st) => (st ? keyOf(st.size, st.mtime) : null)
+
+/** Recursively pull remote → local mirror (three-way, ignore-aware). */
+export async function syncTree(sftp, remoteDir, localDir, opts = {}) {
+  const {
+    maxDepth = 5,
+    maxFiles = 500,
+    maxFileBytes = 0,
+    isIgnored = () => false,
+    dryRun = false,
+    force = false,
+    state = {},
+  } = opts
+  const stats = { files: 0, dirs: 0, skippedUnchanged: 0, skippedLarge: 0, conflicts: [], staleRemote: 0, touched: [] }
+  const nextState = { ...state }
+
+  const walk = async (rDir, lDir, depth) => {
+    const entries = await sftp.readdir(rDir).then((l) => l || [], () => [])
+    // Directories first (sequential, depth-bounded) so every file has a home.
+    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) continue
+      if (depth <= 0 || stats.files >= maxFiles) continue
+      const rp = joinRemotePath(rDir, name)
+      const lp = path.join(lDir, name)
+      const rel = relPathUnder(remoteDir, rp) || name
+      if (isIgnored(rel, true)) continue
+      if (!existsSync(lp)) mkdirSync(lp, { recursive: true })
+      await walk(rp, lp, depth - 1)
+      stats.dirs++
+      if (stats.files >= maxFiles) break
+    }
+    if (stats.files >= maxFiles) return
+
+    const files = entries.filter(
+      (e) => !(e.attrs && e.attrs.isDirectory && e.attrs.isDirectory()) &&
+        String(e.filename) !== '.' && String(e.filename) !== '..',
+    )
+    await mapLimit(files, 4, async (e) => {
+      if (stats.files >= maxFiles) return
+      const name = String(e.filename)
+      const rp = joinRemotePath(rDir, name)
+      const lp = path.join(lDir, name)
+      const rel = relPathUnder(remoteDir, rp) || name
+      if (isIgnored(rel, false)) return
+      let r
+      try { r = await sftp.stat(rp) } catch { return }
+      if (maxFileBytes > 0 && r.size > maxFileBytes) { stats.skippedLarge++; return }
+      const rk = remoteKey(r)
+      const sk = state[rel] ? keyOf(state[rel].size, state[rel].mtime) : null
+      let lk = null
+      if (existsSync(lp)) {
+        try { lk = localKey(statSync(lp)) } catch { lk = null }
+      }
+      if (sk && rk === sk && lk && lk === sk) { stats.skippedUnchanged++; return }
+      if (!force && sk && rk !== sk && lk && lk !== sk && rk !== lk) {
+        stats.conflicts.push({ path: rp, reason: 'both-modified（远端与本地都改过，跳过不覆盖）' })
+        return
+      }
+      if (!force && sk && rk === sk && lk && lk !== sk) {
+        // Pull would clobber a local edit; the remote never changed.
+        stats.conflicts.push({ path: rp, reason: 'local-modified（本地改过而远端未变；如需覆盖请用 force / rw_push）' })
+        return
+      }
+      if (dryRun) {
+        stats.files++
+        stats.touched.push(rp)
+        nextState[rel] = { size: r.size, mtime: r.mtime }
+        return
+      }
+      try {
+        const buf = await sftp.readFile(rp)
+        writeFileSync(lp, buf)
+        try { utimesSync(lp, new Date(r.mtime * 1000), new Date(r.mtime * 1000)) } catch {}
+        stats.files++
+        stats.touched.push(rp)
+        nextState[rel] = { size: r.size, mtime: r.mtime }
+      } catch { /* skip unreadable */ }
+    })
+  }
+
+  await walk(remoteDir, localDir, maxDepth)
+  // Informational: remote entries in the snapshot that no longer exist remotely.
+  for (const rel of Object.keys(state)) {
+    if (state[rel] && !nextState[rel]) stats.staleRemote++
+  }
+  return { stats, nextState }
+}
+
+/** Recursively push local mirror → remote (three-way, ignore-aware). */
+export async function pushTree(sftp, localDir, remoteDir, opts = {}) {
+  const {
+    maxFiles = 500,
+    maxFileBytes = 0,
+    isIgnored = () => false,
+    dryRun = false,
+    force = false,
+    state = {},
+  } = opts
+  const stats = { files: 0, dirs: 0, skippedUnchanged: 0, skippedLarge: 0, conflicts: [], staleLocal: 0, pushed: [] }
+  const nextState = { ...state }
+
+  const walk = async (lDir, rDir) => {
+    const entries = readdirSync(lDir, { withFileTypes: true }).filter(
+      (e) => e.name !== '.dsh-remote-meta.json' && e.name !== '.dsh-remote-sync-state.json',
+    )
+    for (const e of entries) {
+      if (!e.isDirectory()) continue
+      if (stats.files >= maxFiles) break
+      const rp = joinRemotePath(rDir, e.name)
+      const rel = relPathUnder(remoteDir, rp) || e.name
+      if (isIgnored(rel, true)) continue
+      try { await sftp.mkdir(rp) } catch { /* already exists */ }
+      stats.dirs++
+      await walk(path.join(lDir, e.name), rp)
+      if (stats.files >= maxFiles) break
+    }
+    if (stats.files >= maxFiles) return
+
+    const files = entries.filter((e) => !e.isDirectory())
+    await mapLimit(files, 4, async (e) => {
+      if (stats.files >= maxFiles) return
+      const lp = path.join(lDir, e.name)
+      const rp = joinRemotePath(rDir, e.name)
+      const rel = relPathUnder(remoteDir, rp) || e.name
+      if (isIgnored(rel, false)) return
+      let l
+      try { l = statSync(lp) } catch { return }
+      if (maxFileBytes > 0 && l.size > maxFileBytes) { stats.skippedLarge++; return }
+      const lk = localKey(l)
+      let r = null
+      try { r = await sftp.stat(rp) } catch { /* absent → upload */ }
+      const rk = remoteKey(r)
+      const sk = state[rel] ? keyOf(state[rel].size, state[rel].mtime) : null
+      if (r && sk && lk === sk && rk === sk) { stats.skippedUnchanged++; return }
+      if (r && !force && sk && rk !== sk && lk !== sk && rk !== lk) {
+        stats.conflicts.push({ path: rp, reason: 'both-modified（远端与本地都改过，跳过不覆盖）' })
+        return
+      }
+      if (r && !force && sk && rk !== sk && lk === sk) {
+        stats.conflicts.push({ path: rp, reason: 'remote-modified（远端改过而本地未变；如需覆盖请用 force / 先 rw_sync）' })
+        return
+      }
+      if (r && !force && sk && rk === sk && lk && lk !== sk) {
+        // Normal case: local edited since sync, remote untouched → push.
+      }
+      if (dryRun) {
+        stats.files++
+        stats.pushed.push(rp)
+        return
+      }
+      try {
+        const buf = readFileSync(lp)
+        await sftp.writeFile(rp, buf)
+        // Align local mtime to whatever the remote server assigned, so the
+        // L==R==S invariant holds for the next run.
+        let r2 = null
+        try { r2 = await sftp.stat(rp) } catch {}
+        const rmt = r2 ? r2.mtime : Math.floor(Date.now() / 1000)
+        try { utimesSync(lp, new Date(rmt * 1000), new Date(rmt * 1000)) } catch {}
+        stats.files++
+        stats.pushed.push(rp)
+        nextState[rel] = { size: l.size, mtime: rmt }
+      } catch { /* skip unwritable */ }
+    })
+  }
+
+  await walk(localDir, remoteDir)
+  for (const rel of Object.keys(state)) {
+    if (state[rel] && !nextState[rel]) stats.staleLocal++
+  }
+  return { stats, nextState }
+}
+
+/** Load the sync-state snapshot from a mirror dir (or {}). */
+export function loadSyncState(localDir) {
+  try {
+    const j = JSON.parse(readFileSync(path.join(localDir, '.dsh-remote-sync-state.json'), 'utf8'))
+    if (j && typeof j === 'object' && !Array.isArray(j)) return j
+  } catch {}
+  return {}
+}
+
+/** Persist the snapshot (atomic-ish: tmp + rename). */
+export function saveSyncState(localDir, state) {
+  try {
+    mkdirSync(localDir, { recursive: true })
+    const tmp = path.join(localDir, '.dsh-remote-sync-state.json.tmp')
+    writeFileSync(tmp, JSON.stringify(state, null, 1))
+    renameSync(tmp, path.join(localDir, '.dsh-remote-sync-state.json'))
+  } catch { /* best effort */ }
+}
+
+/** Push ONE local mirror file back to the remote (used by auto-push).
+ * Same three-way guard as pushTree: never clobbers a remote change. Returns
+ * { status: 'pushed'|'unchanged'|'conflict'|'skipped'|'missing' } and the
+ * updated state delta ({rel: {size, mtime}} when pushed). */
+export async function pushOneFile(sftp, localDir, remoteDir, rel, opts = {}) {
+  const { maxFileBytes = 0, isIgnored = () => false, force = false, state = {} } = opts
+  if (isIgnored(rel, false)) return { status: 'skipped' }
+  const lp = path.join(localDir, rel.replace(/\//g, path.sep))
+  const rp = joinRemotePath(remoteDir, rel)
+  let l
+  try { l = statSync(lp) } catch { return { status: 'missing' } }
+  if (maxFileBytes > 0 && l.size > maxFileBytes) return { status: 'skipped' }
+  const lk = localKey(l)
+  let r = null
+  try { r = await sftp.stat(rp) } catch { /* absent → upload */ }
+  const rk = remoteKey(r)
+  const sk = state[rel] ? keyOf(state[rel].size, state[rel].mtime) : null
+  if (r && sk && lk === sk && rk === sk) return { status: 'unchanged' }
+  if (r && !force && sk && rk !== sk && lk !== sk && rk !== lk) {
+    return { status: 'conflict', reason: 'both-modified' }
+  }
+  if (r && !force && sk && rk !== sk && lk === sk) {
+    return { status: 'conflict', reason: 'remote-modified' }
+  }
+  try {
+    await sftp.writeFile(rp, readFileSync(lp))
+    let r2 = null
+    try { r2 = await sftp.stat(rp) } catch {}
+    const rmt = r2 ? r2.mtime : Math.floor(Date.now() / 1000)
+    try { utimesSync(lp, new Date(rmt * 1000), new Date(rmt * 1000)) } catch {}
+    return { status: 'pushed', state: { [rel]: { size: l.size, mtime: rmt } } }
+  } catch (e) {
+    return { status: 'skipped', error: String((e && e.message) || e) }
+  }
+}