dsh-remote 0.8.50 → 0.8.52

package/lib/instructions.js

@@ -0,0 +1,288 @@
+// dsh-remote — remote instruction-file index (issue #68).
+//
+// The core instruction loader (@deepseek-ai/dsh-agent-instructions) discovers
+// AGENTS.md through the LOCAL filesystem only: from two user-global roots plus
+// the projectRoot→cwd ancestor chain. A remote session's cwd is the local
+// MIRROR of the remote workspace, and that mirror stays empty until rw_sync —
+// so a 20 KB AGENTS.md that governs the remote repo never enters the model's
+// context, while the same file is auto-injected in a local session. File
+// ACCESS was never the problem (rw_read_file reads it fine); what is missing
+// is the model knowing it should.
+//
+// This module closes the gap on the plugin side, along the two cheapest axes
+// the issue lists (the third — a remote ctx.fs provider — belongs to core):
+//
+//   1. INDEX in the system prompt: a shallow scan of the remote workspace
+//      (root + at most two directory levels down, AGENTS.md / CLAUDE.md only)
+//      is rendered into the dsh-remote prompt section as a path list with
+//      headings, telling every new session the files exist and to read them
+//      with rw_read_file before editing that tree. This is an INDEX, not a
+//      second injection pipeline — the full text stays out of the prompt and
+//      out of any parallel baseline, exactly as the issue demands.
+//   2. MIRROR the found files into the local mirror at their relative paths
+//      (three-way safe — a local edit is never clobbered, see below). A
+//      root-level AGENTS.md then sits exactly where the CORE loader looks in
+//      a local session, so the normal baseline/incremental machinery picks it
+//      up unchanged; no plugin-side injection logic runs in parallel with it.
+//
+// Deliberate non-goals (the issue's "请不要做"):
+//   - NO unbounded recursion of the remote root (multi-project roots like
+//     /root would scan forever): the walk is depth- and count-capped.
+//   - NO full-text injection from the plugin.
+
+import { existsSync, mkdirSync, statSync, writeFileSync, utimesSync } from 'node:fs'
+import path from 'node:path'
+import { joinRemotePath, relPathUnder } from './paths.js'
+import { loadSyncState, saveSyncState } from './sync.js'
+
+/** File names treated as agent instruction files (compared case-insensitively;
+ *  the mirrored copy keeps the remote's exact casing). */
+export const INSTRUCTION_NAMES = ['agents.md', 'claude.md']
+
+/** An instruction file bigger than this is indexed (path + note) but not read. */
+export const INSTRUCTION_MAX_BYTES = 256 * 1024
+
+/** Caps that keep the shallow scan shallow. */
+export const INSTRUCTION_MAX_FILES = 20
+export const INSTRUCTION_MAX_DIRS = 60
+export const INSTRUCTION_MAX_DEPTH = 2 // 0 = workspace root, 1 = sub/, 2 = sub/sub/
+
+/** Directories that never contain a project's governing instructions. */
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', '.svn', '.hg', 'dist', 'build', 'out',
+  '.next', '.nuxt', '.cache', '.turbo', 'coverage', 'target', 'vendor',
+])
+
+export const isInstructionName = (name) => INSTRUCTION_NAMES.includes(String(name || '').toLowerCase())
+
+/** Pull the first Markdown headings out of an instruction file, for the index. */
+export function extractHeadings(text, max = 8) {
+  const out = []
+  for (const line of String(text || '').split('\n')) {
+    const m = /^#{1,3}\s+(.+?)\s*#*\s*$/.exec(line)
+    if (!m) continue
+    out.push(m[1].slice(0, 60))
+    if (out.length >= max) break
+  }
+  return out
+}
+
+/**
+ * Shallow-scan a remote workspace for instruction files: the root directory
+ * plus up to INSTRUCTION_MAX_DEPTH levels of subdirectories, matching
+ * AGENTS.md / CLAUDE.md basenames. Bounded by INSTRUCTION_MAX_DIRS readdirs
+ * and INSTRUCTION_MAX_FILES files; anything past the caps is silently
+ * skipped (the index is a hint, not an inventory).
+ *
+ * @param {object} sftp - the promisified sftp surface (readdir/stat/readFile).
+ * @param {string} remoteRoot - absolute remote workspace path (normalized).
+ * @returns {Promise<Array<{rel: string, remote: string, size: number, mtime: number, content: Buffer|null, headings: string[]}>>}
+ *   `content`/`headings` are null/empty for files over INSTRUCTION_MAX_BYTES.
+ */
+export async function scanInstructionFiles(sftp, remoteRoot, opts = {}) {
+  const maxDepth = Math.max(0, Math.min(Number(opts.maxDepth ?? INSTRUCTION_MAX_DEPTH) || 0, 4))
+  const maxDirs = Math.max(1, Number(opts.maxDirs ?? INSTRUCTION_MAX_DIRS) || INSTRUCTION_MAX_DIRS)
+  const maxFiles = Math.max(1, Number(opts.maxFiles ?? INSTRUCTION_MAX_FILES) || INSTRUCTION_MAX_FILES)
+  const files = []
+  // Breadth-first so a wide root cannot push the walk deep before the shallow
+  // (more commonly governing) files are seen.
+  const queue = [{ dir: remoteRoot, depth: 0 }]
+  let dirsScanned = 0
+  while (queue.length && files.length < maxFiles && dirsScanned < maxDirs) {
+    const { dir, depth } = queue.shift()
+    dirsScanned++
+    let entries = []
+    try { entries = (await sftp.readdir(dir)) || [] } catch { continue }
+    for (const e of entries) {
+      const name = String(e.filename || '')
+      if (!name || name === '.' || name === '..' || name.startsWith('.')) {
+        // Hidden entries are skipped wholesale EXCEPT the names themselves
+        // never start with a dot, so nothing is lost.
+        continue
+      }
+      const isDir = !!(e.attrs && typeof e.attrs.isDirectory === 'function' && e.attrs.isDirectory())
+      const isLink = !!(e.attrs && typeof e.attrs.isSymbolicLink === 'function' && e.attrs.isSymbolicLink())
+      if (isDir) {
+        // Symlinked dirs are not followed: the walk stays inside the workspace
+        // tree and cannot loop through a link back to an ancestor.
+        if (isLink) continue
+        if (depth < maxDepth && !SKIP_DIRS.has(name.toLowerCase()) && queue.length + dirsScanned < maxDirs) {
+          queue.push({ dir: joinRemotePath(dir, name), depth: depth + 1 })
+        }
+        continue
+      }
+      if (!isInstructionName(name)) continue
+      const remote = joinRemotePath(dir, name)
+      const rel = relPathUnder(remoteRoot, remote) || name
+      let st = null
+      try { st = await sftp.stat(remote) } catch { continue }
+      const size = st && typeof st.size === 'number' ? st.size : 0
+      const mtime = st && typeof st.mtime === 'number' ? st.mtime : 0
+      let content = null
+      let headings = []
+      if (size <= INSTRUCTION_MAX_BYTES) {
+        try {
+          content = await sftp.readFile(remote)
+          headings = extractHeadings(content.toString('utf8'))
+        } catch { content = null }
+      }
+      files.push({ rel, remote, size, mtime, content, headings })
+      if (files.length >= maxFiles) break
+    }
+  }
+  return files
+}
+
+// The three-way keys mirror lib/sync.js exactly (size + whole-second mtime):
+// a file this module places into the mirror must be indistinguishable from
+// one rw_sync pulled, or the next sync would report a phantom conflict.
+const keyOf = (size, mtime) => `${size}:${Math.floor(mtime || 0)}`
+const localKeyOf = (st) => (st ? keyOf(st.size, st.mtimeMs / 1000) : null)
+
+/**
+ * Write scanned instruction files into the local mirror at their workspace-
+ * relative paths, three-way safe against `.dsh-remote-sync-state.json`:
+ *
+ *   - local missing                        → write (+ align mtime, record state)
+ *   - local identical to remote            → keep (record state if absent)
+ *   - remote changed, local untouched (L==S) → write (a plain pull)
+ *   - local edited (L!=S), remote unchanged → SKIP — a local edit is never
+ *     clobbered; rw_sync surfaces it as a conflict like any other file
+ *   - both changed / unknown local content → SKIP (rw_sync arbitrates)
+ *
+ * @returns {{written: string[], present: Set<string>}} rel paths written now,
+ *   and every rel that exists locally afterwards (for the index's "mirrored"
+ *   badge).
+ */
+export function syncInstructionsToMirror(files, mirrorDir) {
+  const written = []
+  const present = new Set()
+  if (!mirrorDir || !Array.isArray(files) || !files.length) return { written, present }
+  const state = loadSyncState(mirrorDir)
+  let stateDirty = false
+  for (const f of files) {
+    if (!f || !f.rel || !f.content) continue
+    const lp = path.join(mirrorDir, ...String(f.rel).split('/'))
+    const rk = keyOf(f.size, f.mtime)
+    const sk = state[f.rel] ? keyOf(state[f.rel].size, state[f.rel].mtime) : null
+    let lk = null
+    try { lk = existsSync(lp) ? localKeyOf(statSync(lp)) : null } catch { lk = null }
+    if (lk === rk) {
+      // Identical bytes in place already (same size AND mtime second) — only
+      // make sure the snapshot knows about it.
+      present.add(f.rel)
+      if (!sk) { state[f.rel] = { size: f.size, mtime: f.mtime }; stateDirty = true }
+      continue
+    }
+    const canWrite = lk === null || (sk !== null && rk !== sk && lk === sk)
+    if (!canWrite) continue
+    try {
+      mkdirSync(path.dirname(lp), { recursive: true })
+      writeFileSync(lp, f.content)
+      // Align the local mtime to the remote's so the next rw_sync sees
+      // L==R==S and skips the file instead of flagging a local modification.
+      try { utimesSync(lp, new Date(f.mtime * 1000), new Date(f.mtime * 1000)) } catch { /* cosmetic */ }
+      state[f.rel] = { size: f.size, mtime: f.mtime }
+      stateDirty = true
+      written.push(f.rel)
+      present.add(f.rel)
+    } catch { /* a mirror write failure must not break the index */ }
+  }
+  if (stateDirty) {
+    try { saveSyncState(mirrorDir, state) } catch { /* best effort */ }
+  }
+  return { written, present }
+}
+
+/**
+ * Render the prompt-section index of remote instruction files. Paths are
+ * shown through `display` (the platform-aware display formatter), headings
+ * give the model a content hint without injecting the full text.
+ */
+export function formatInstructionIndex(files, display = (p) => p) {
+  const lines = files.slice(0, 10).map((f) => {
+    const h = f.headings && f.headings.length ? ` (headings: ${f.headings.slice(0, 6).join(' / ')})` : ''
+    const over = f.size > INSTRUCTION_MAX_BYTES ? ` (${Math.round(f.size / 1024)} KB)` : ''
+    const mirrored = f.mirrored ? '; synced into the local mirror' : ''
+    return `- ${display(f.remote)}${h}${over}${mirrored}`
+  })
+  return (
+    'Remote instruction files found in this workspace (they govern how to work in their directories; '
+    + 'root-level copies were synced into the local mirror, but nested ones are NOT auto-injected — '
+    + 'read them with rw_read_file before editing that tree):\n'
+    + lines.join('\n')
+  )
+}
+
+/**
+ * Per-process index of remote instruction scans, keyed by mirror directory.
+ * Deduplicates in-flight scans, negative-caches failures for a minute (an
+ * offline machine must not turn every prompt assembly into a connect
+ * attempt), and never throws — the index is strictly best-effort.
+ */
+export function createInstructionIndex() {
+  const cache = new Map() // resolvedMirrorDir → { scannedAt, files } | { failedAt }
+  const inflight = new Map() // resolvedMirrorDir → Promise
+  const RETRY_AFTER_MS = 60 * 1000
+
+  const keyOfDir = (mirrorDir) => {
+    try { return path.resolve(String(mirrorDir)) } catch { return String(mirrorDir || '') }
+  }
+
+  /**
+   * Scan (or return the cached scan of) one mirror's remote workspace.
+   * @param {{pool: {sftp: Function}, ws: string, mirrorDir: string, force?: boolean}} arg
+   * @returns {Promise<{scannedAt: number, files: Array}|null>}
+   */
+  const refresh = ({ pool, ws, mirrorDir, force = false }) => {
+    if (!pool || typeof pool.sftp !== 'function' || !ws || !mirrorDir) return Promise.resolve(null)
+    const key = keyOfDir(mirrorDir)
+    const cur = cache.get(key)
+    if (!force && cur && cur.files) return Promise.resolve(cur)
+    if (!force && cur && cur.failedAt && Date.now() - cur.failedAt < RETRY_AFTER_MS) return Promise.resolve(null)
+    if (inflight.has(key)) return inflight.get(key)
+    const job = (async () => {
+      try {
+        const sftp = await pool.sftp()
+        const files = await scanInstructionFiles(sftp, ws)
+        const synced = syncInstructionsToMirror(files, mirrorDir)
+        const entry = {
+          scannedAt: Date.now(),
+          files: files.map((f) => ({
+            rel: f.rel,
+            remote: f.remote,
+            size: f.size,
+            headings: f.headings,
+            mirrored: synced.present.has(f.rel),
+          })),
+        }
+        cache.set(key, entry)
+        return entry
+      } catch {
+        // Negative-cache: the machine may simply be offline; retry at most
+        // once a minute, not once per prompt assembly.
+        cache.set(key, { failedAt: Date.now() })
+        return null
+      } finally {
+        inflight.delete(key)
+      }
+    })()
+    inflight.set(key, job)
+    return job
+  }
+
+  /** The cached index for a mirror, or null when unknown/failed. */
+  const get = (mirrorDir) => {
+    const e = cache.get(keyOfDir(mirrorDir))
+    return e && e.files ? e : null
+  }
+
+  /** Fire-and-forget refresh for prompt-assembly time: starts a scan only
+   *  when nothing is known about the mirror yet (recent failures included). */
+  const note = ({ pool, ws, mirrorDir }) => {
+    if (cache.has(keyOfDir(mirrorDir))) return
+    refresh({ pool, ws, mirrorDir }).catch(() => { /* guarded inside */ })
+  }
+
+  return { refresh, get, note, _cache: cache }
+}

package/lib/openssh.js

@@ -785,7 +785,16 @@ export class SystemOpenSshPool {
         throw new Error('ssh target changed while opening sftp')
       }
       this._sftpChild = child
-      return buildSftpSurface(sftp, { commandTimeoutMs: this.config.commandTimeoutMs })
+      return buildSftpSurface(sftp, {
+        commandTimeoutMs: this.config.commandTimeoutMs,
+        onTimeout: () => {
+          // A timed-out SFTP session is dead: kill the child and drop the cached
+          // session so the next call re-handshakes instead of queueing behind the
+          // wedged one (issue #65).
+          try { child.kill() } catch { /* already gone */ }
+          drop()
+        },
+      })
     })
     // Never cache a rejected open: the next call must retry rather than get the
     // same error back forever (a failed handshake is usually transient).

package/lib/pool.js

@@ -197,6 +197,8 @@ export class SshPool {
     this.onReady = null
     /** Optional hook called when the pool closes. */
     this.onCloseHook = null
+    /** Consecutive SFTP subchannel-open timeouts (issue #65). */
+    this._sftpTimeouts = 0
   }
 
   resolveKeyPath() {
@@ -324,6 +326,7 @@ export class SshPool {
           return
         }
         this.client = client
+        this._sftpTimeouts = 0
         resolve(client)
         if (this.onReady) { try { this.onReady(client) } catch {} }
       })
@@ -684,10 +687,25 @@ export class SshPool {
                   }
                   return reject(new Error('ssh sftp failed: ' + ((err && err.message) || err)))
                 }
+                // A successful open proves the connection healthy: the strike
+                // counter counts CONSECUTIVE timeouts, so it resets here —
+                // two unrelated transient blips hours apart must not tear down
+                // a fine connection.
+                this._sftpTimeouts = 0
                 // The promisified surface (timeouts, dead-channel fail-fast,
                 // range reads) is shared verbatim with the system-OpenSSH
                 // backend — see lib/sftp-surface.js for the rules it encodes.
-                resolve(buildSftpSurface(sftp, { commandTimeoutMs: this.config.commandTimeoutMs }))
+                resolve(buildSftpSurface(sftp, {
+                  commandTimeoutMs: this.config.commandTimeoutMs,
+                  onTimeout: () => {
+                    // A timed-out SFTP subchannel is dead: close it so the next
+                    // operation does not queue behind the wedged one, and count
+                    // the strike so a second consecutive timeout tears down the
+                    // whole pooled connection (issue #65).
+                    try { sftp.end() } catch { /* already gone */ }
+                    this._noteSftpTimeout()
+                  },
+                }))
               })
             } catch (e) {
               clearAttempt()
@@ -699,6 +717,16 @@ export class SshPool {
     )
   }
 
+  /**
+   * Count a timed-out SFTP subchannel open. A second consecutive timeout means
+   * the pooled connection itself is wedged (issue #65): tear it down so the
+   * next sftp() call re-handshakes instead of queueing behind the dead one.
+   */
+  _noteSftpTimeout() {
+    this._sftpTimeouts = (this._sftpTimeouts || 0) + 1
+    if (this._sftpTimeouts >= 2) this.invalidate()
+  }
+
   /**
    * Drop the cached client and force a fresh connection on the next call.
    * Called when a channel open fails (e.g. "Channel open failure: open

package/lib/remote-fs.js

@@ -98,6 +98,17 @@ export async function removeRemoteTree(sftp, p, maxFiles = 2000) {
   return removed
 }
 
+/** MIME types for image formats the preview panel can render inline. */
+const IMAGE_MIME_TYPES = {
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  webp: 'image/webp',
+  svg: 'image/svg+xml',
+  bmp: 'image/bmp',
+}
+
 function looksBinary(buf) {
   const n = Math.min(buf.length, 8192)
   for (let i = 0; i < n; i++) if (buf[i] === 0) return true
@@ -107,6 +118,14 @@ function looksBinary(buf) {
 /**
  * Read a remote file for the sidebar/editor. Oversized files use a range read
  * (`readPartial`) so we never `fastGet` the whole blob onto disk.
+ *
+ * Images are the exception (issue #66): a PREFIX of an image is a broken
+ * picture, not a preview, so for a recognised image extension the caller's
+ * text-oriented cap is skipped and the file is read whole up to the hard 2MB
+ * ceiling; the panel renders it inline as `<img src="data:…">`. An image past
+ * the ceiling degrades to the plain binary stub + download button rather than
+ * shipping a guaranteed-broken half render. (`<img>` is also the safe sink
+ * for SVG: unlike inline markup it cannot run the file's scripts.)
  */
 export async function previewRemoteFile(sftp, target, opts = {}) {
   const {
@@ -114,7 +133,10 @@ export async function previewRemoteFile(sftp, target, opts = {}) {
     encoding = 'utf-8',
     decodeBuf = (buf) => buf.toString('utf8'),
   } = opts
-  const cap = Math.min(Math.max(Number(maxBytes) || 256 * 1024, 1024), 2 * 1024 * 1024)
+  const hardCap = 2 * 1024 * 1024
+  const name = String(target).split(/[\\/]/).pop() || ''
+  const imageMime = IMAGE_MIME_TYPES[(name.split('.').pop() || '').toLowerCase()]
+  const cap = imageMime ? hardCap : Math.min(Math.max(Number(maxBytes) || 256 * 1024, 1024), hardCap)
   const st = await sftp.stat(target)
   const mtime = st && typeof st.mtime === 'number' ? st.mtime : 0
   const size = st && typeof st.size === 'number' ? st.size : 0
@@ -131,6 +153,9 @@ export async function previewRemoteFile(sftp, target, opts = {}) {
   } else {
     buf = await sftp.readFile(target)
   }
+  if (imageMime && !truncated) {
+    return { ok: true, binary: false, image: true, mime: imageMime, content: buf.toString('base64'), truncated, size, mtime }
+  }
   if (looksBinary(buf)) {
     return {
       ok: true, binary: true, size, mtime,

package/lib/sftp-surface.js

@@ -26,7 +26,7 @@ import { toSftpPath } from './paths.js'
  * @param {number} opts.commandTimeoutMs - per-operation timeout.
  * @returns {object} promisified sftp surface.
  */
-export function buildSftpSurface(sftp, { commandTimeoutMs }) {
+export function buildSftpSurface(sftp, { commandTimeoutMs, onTimeout }) {
   // 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
@@ -39,12 +39,19 @@ export function buildSftpSurface(sftp, { commandTimeoutMs }) {
   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)
+      let timedOut = false
+      const timer = setTimeout(() => {
+        timedOut = true
+        markDead()
+        if (typeof onTimeout === 'function') { try { onTimeout() } catch { /* best effort */ } }
+        reject(new Error('sftp operation timed out'))
+      }, commandTimeoutMs)
       const finish = (err, value) => {
         clearTimeout(timer)
+        if (timedOut) return
         err ? reject(err) : resolve(value)
       }
-      try { fn(...args, finish) } catch (err) { clearTimeout(timer); reject(err) }
+      try { fn(...args, finish) } catch (err) { clearTimeout(timer); if (!timedOut) reject(err) }
     })
   const P = (p) => toSftpPath(p)
   return {
@@ -55,7 +62,43 @@ export function buildSftpSurface(sftp, { commandTimeoutMs }) {
     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)),
+    // POSIX rename(2) semantics: atomically REPLACE an existing destination.
+    // Plain SSH_FXP_RENAME fails when the target exists (OpenSSH's sftp-server
+    // enforces that even though it advertises posix-rename@openssh.com — ssh2
+    // only sends the extension when asked explicitly, verified against
+    // OpenSSH_9.6 in issue #65). Servers with the extension get one atomic
+    // request; servers without it get the move-aside dance, whose every hop
+    // targets a path that does not exist, which plain RENAME always permits.
+    // rw_edit's atomic write depends on this — without it every edit of an
+    // existing file fails with a bare "Failure".
+    renameOverwrite: (p, d) => withTimeout((a, b, cb) => {
+      const ext = sftp._extensions && sftp._extensions['posix-rename@openssh.com']
+      if (ext === '1' && typeof sftp.ext_openssh_rename === 'function') {
+        return sftp.ext_openssh_rename(a, b, cb)
+      }
+      const bak = `${b}.dsh-remote-bak-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.tmp`
+      sftp.rename(b, bak, (e1) => {
+        if (e1) {
+          // Destination absent → a plain rename is already overwrite-safe.
+          if (/no such/i.test(String((e1 && e1.message) || e1))) return sftp.rename(a, b, cb)
+          return cb(e1)
+        }
+        sftp.rename(a, b, (e2) => {
+          if (e2) {
+            // Roll the original back into place before reporting the failure.
+            return sftp.rename(bak, b, () => cb(e2))
+          }
+          // Best effort: a leftover backup must not fail the operation.
+          sftp.unlink(bak, () => cb(null))
+        })
+      })
+    })(P(p), P(d)),
     realpath: (p) => withTimeout((d, cb) => sftp.realpath(d, cb))(P(p)),
+    // Attribute write (chmod semantics live in setstat at the protocol level,
+    // so BOTH backends — ssh2's SFTPWrapper and its raw protocol SFTP — answer
+    // this one shape). Used by rw_edit to restore the original mode after an
+    // atomic rename replace (issue #65).
+    setstat: (p, attrs) => withTimeout((d, a, cb) => sftp.setstat(d, a, cb))(P(p), attrs),
     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),

package/lib/sshconfig.js

@@ -32,11 +32,21 @@ import { existsSync, readFileSync, readdirSync, statSync, mkdirSync, writeFileSy
 import { homedir } from 'node:os'
 import path from 'node:path'
 
-/** Default location of the user's ssh config. */
-export const sshConfigPath = () => path.join(homedir(), '.ssh', 'config')
+/** Default location of the user's ssh config. An env override exists so tests
+ *  (and any deployment that isolates its home directory) can point the plugin
+ *  at a substitute file instead of the real ~/.ssh/config. */
+export const sshConfigPath = () => {
+  const env = process.env.DSH_REMOTE_SSH_CONFIG
+  if (env && String(env).trim()) return path.resolve(String(env).trim())
+  return path.join(homedir(), '.ssh', 'config')
+}
 
 /** Directory `Include` paths are resolved against (ssh_config(5)). */
-export const sshConfigDir = () => path.join(homedir(), '.ssh')
+export const sshConfigDir = () => {
+  const env = process.env.DSH_REMOTE_SSH_CONFIG
+  if (env && String(env).trim()) return path.dirname(path.resolve(String(env).trim()))
+  return path.join(homedir(), '.ssh')
+}
 
 /** Parameters the resolver cares about, lowercase (as parsed). */
 const KNOWN_PARAMS = new Set([

package/node_modules/buildcheck/.eslintrc.js

@@ -0,0 +1,5 @@
+'use strict';
+
+module.exports = {
+  extends: '@mscdex/eslint-config',
+};

package/node_modules/buildcheck/.github/workflows/ci.yml

@@ -0,0 +1,88 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [ master ]
+
+jobs:
+  tests-linux:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: [10.x, 12.x, 14.x, 16.x, 18.x, 20.x, 22.x, 24.x]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+      - name: Check Node.js version
+        run: node -pe process.versions
+      - name: Install module
+        run: npm install
+      - name: Run tests
+        run: npm test
+  tests-macos-intel:
+    runs-on: macos-15-intel
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: [10.x, 12.x, 14.x, 16.x, 18.x, 20.x, 22.x, 24.x]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+      - name: Check Node.js version
+        run: node -pe process.versions
+      - name: Install module
+        run: npm install
+      - name: Run tests
+        run: npm test
+  tests-macos-arm:
+    runs-on: macos-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: [16.x, 18.x, 20.x, 22.x, 24.x]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+      - name: Check Node.js version
+        run: node -pe process.versions
+      - name: Install module
+        run: npm install
+      - name: Run tests
+        run: npm test
+  tests-windows-2022:
+    runs-on: windows-2022
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: [24.x]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+      - name: Check Node.js version
+        run: node -pe process.versions
+      - name: Install module
+        run: npm install
+      - name: Run tests
+        run: npm test

package/node_modules/buildcheck/.github/workflows/lint.yml

@@ -0,0 +1,27 @@
+name: lint
+
+on:
+  pull_request:
+  push:
+    branches: [ master ]
+
+env:
+  NODE_VERSION: 22.x
+
+jobs:
+  lint-js:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - name: Use Node.js ${{ env.NODE_VERSION }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+      - name: Check Node.js version
+        run: node -pe process.versions
+      - name: Install ESLint + ESLint configs/plugins
+        run: npm install --only=dev
+      - name: Lint files
+        run: npm run lint

package/node_modules/buildcheck/.npmignore

@@ -0,0 +1,3 @@
+.eslintcache
+**/node_modules/**
+/package-lock.json

package/node_modules/buildcheck/LICENSE

@@ -0,0 +1,19 @@
+Copyright Brian White. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.