shipback-sftp 0.0.0-stage → 0.2.0

package/src/backup.js

@@ -0,0 +1,94 @@
+'use strict';
+// Copy the server's current copy of each file into <root>/_backup-<stamp>/<path> before it is overwritten or deleted.
+// A deploy also writes <backup>/.backup.json — what it overwrote, added and deleted, and the sha256 of what it
+// uploaded — so restore.js can undo it and tell when a live file was edited after the deploy.
+const crypto = require('node:crypto');
+const posix = require('node:path').posix;
+const { BACKUP_PREFIX, MANIFEST_NAME } = require('./diff');
+const { writeLive, isHidden } = require('./remote-fs');
+
+const BACKUP_INFO = '.backup.json';
+
+const pad = n => String(n).padStart(2, '0');
+function makeStamp(d = new Date()) {
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}-${pad(d.getHours())}${pad(d.getMinutes())}`;
+}
+
+/** First _backup-<stamp> folder name not already on the server (two runs in one minute get -2, -3 …). */
+async function freeBackupDir(remoteFs, root, stamp) {
+  root = root.replace(/\/$/, '');
+  let dir = `${root}/${BACKUP_PREFIX}${stamp}`;
+  for (let n = 2; await remoteFs.stat(dir); n++) dir = `${root}/${BACKUP_PREFIX}${stamp}-${n}`;
+  return dir;
+}
+
+const sha256 = buf => crypto.createHash('sha256').update(buf).digest('hex');
+
+/**
+ * backupFiles({ remoteFs, root, paths, stamp | backupDir, onEvent }) → { backupDir, copied, was }
+ *   was: Map path → sha256 of the copy saved, so restore can check the copy is still intact before using it
+ */
+async function backupFiles({ remoteFs, root, paths, stamp = makeStamp(), backupDir, onEvent = () => {} }) {
+  root = root.replace(/\/$/, '');
+  backupDir = backupDir || `${root}/${BACKUP_PREFIX}${stamp}`;
+  const copied = [];
+  const was = new Map();
+  const madeDirs = new Set();
+  for (const rel of paths) {
+    const src = `${root}/${rel}`;
+    const st = await remoteFs.stat(src);
+    if (!st || st.isDir) continue;
+    const dest = `${backupDir}/${rel}`;
+    const dir = posix.dirname(dest);
+    if (!madeDirs.has(dir)) { await remoteFs.mkdirp(dir); madeDirs.add(dir); }
+    const data = await remoteFs.readFile(src);
+    await remoteFs.writeFile(dest, data);
+    copied.push(rel);
+    was.set(rel, sha256(data));
+    onEvent({ type: 'backup', path: rel, bytes: data.length, to: dest });
+  }
+  return { backupDir, copied, was };
+}
+
+/**
+ * writeBackupInfo({ remoteFs, backupDir, info })
+ *   info: { action, at, overwritten: [{ path, sha256, was }], added: [{ path, sha256 }], deleted: [{ path, was }], from? }
+ *   sha256 = the content the run left at that path, so a later restore can tell if it was edited since.
+ *   was = the sha256 of the copy saved in the backup folder (from 0.2; older records have none).
+ *   status (from 0.2): 'saving' while the copies are being made, so a run cut off then is known to have changed
+ *   nothing; a restore also says 'running' while it writes, so cutting it off can be finished by running it again.
+ *   No status = the record is whole. It is swapped in whole too, never left half written.
+ */
+async function writeBackupInfo({ remoteFs, backupDir, info }) {
+  await remoteFs.mkdirp(backupDir);
+  await writeLive(remoteFs, `${backupDir}/${BACKUP_INFO}`, { data: Buffer.from(JSON.stringify({ version: 1, tool: 'shipback-sftp', ...info }, null, 1)) });
+}
+
+/** A path a record may name: relative, inside the site, and not one of Shipback's own files. */
+function siteRelative(p) {
+  if (typeof p !== 'string' || !p || p.startsWith('/') || p.includes('\\') || p.includes('\0') || /^[A-Za-z]:/.test(p)) return false;
+  const segs = p.split('/');
+  return segs.every(s => s && s !== '.' && s !== '..' && !s.startsWith(BACKUP_PREFIX)) && p !== MANIFEST_NAME && !isHidden(p);
+}
+
+/**
+ * The run's record, or null if the folder has none (a backup made before .backup.json existed).
+ * A record that can't be read, or that names any path outside the site, throws: restore never guesses from it,
+ * and never falls back to putting files back unchecked.
+ */
+async function readBackupInfo(remoteFs, backupDir) {
+  if (!(await remoteFs.stat(`${backupDir}/${BACKUP_INFO}`))) return null;
+  let info;
+  try { info = JSON.parse((await remoteFs.readFile(`${backupDir}/${BACKUP_INFO}`)).toString('utf8')); }
+  catch (e) { throw new Error(`${posix.basename(backupDir)}/${BACKUP_INFO} is damaged (${e.message.split('\n')[0]}), so it can't be restored safely`); }
+  if (!info || info.version !== 1) throw new Error(`${posix.basename(backupDir)}/${BACKUP_INFO} is not a record this version understands`);
+  for (const key of ['overwritten', 'added', 'deleted']) {
+    if (!Array.isArray(info[key])) throw new Error(`${posix.basename(backupDir)}/${BACKUP_INFO} is damaged (no "${key}" list), so it can't be restored safely`);
+    for (const e of info[key]) {
+      if (!e || !siteRelative(e.path)) throw new Error(`${posix.basename(backupDir)}/${BACKUP_INFO} names a path outside the site (${JSON.stringify(e && e.path)}). Nothing was changed`);
+    }
+  }
+  return info;
+}
+
+module.exports = { backupFiles, makeStamp, freeBackupDir, writeBackupInfo, readBackupInfo, siteRelative, BACKUP_INFO };

package/src/config.js

@@ -0,0 +1,44 @@
+'use strict';
+// sites.json — { sites: [{ name, host, port, username, remoteRoot, localDir, ignore: [] }] }. Never holds passwords.
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+const SITE_FIELDS = ['name', 'host', 'port', 'username', 'remoteRoot', 'localDir', 'ignore', 'privateKeyPath'];
+
+function normaliseSite(s) {
+  const out = {};
+  for (const k of SITE_FIELDS) if (s[k] !== undefined && s[k] !== '') out[k] = s[k];
+  out.port = Number(out.port) || 22;
+  out.ignore = Array.isArray(out.ignore) ? out.ignore : [];
+  for (const k of ['name', 'host', 'username', 'remoteRoot']) if (!out[k] || typeof out[k] !== 'string') throw new Error(`Site is missing "${k}"`);
+  if (!/^[\w.-]+$/.test(out.name)) throw new Error('Site name may only use letters, numbers, dots, dashes and underscores');
+  out.remoteRoot = out.remoteRoot.replace(/\\/g, '/').replace(/\/$/, '') || '/';
+  return out;
+}
+
+async function loadSites(file) {
+  try {
+    const data = JSON.parse(await fs.readFile(file, 'utf8'));
+    return { sites: (data.sites || []).map(normaliseSite) };
+  } catch (e) {
+    if (e.code === 'ENOENT') return { sites: [] };
+    throw new Error(`Could not read ${path.basename(file)}: ${e.message}`);
+  }
+}
+
+async function saveSite(file, site) {
+  const clean = normaliseSite(site);
+  const cfg = await loadSites(file);
+  const i = cfg.sites.findIndex(s => s.name === clean.name);
+  if (i >= 0) cfg.sites[i] = clean; else cfg.sites.push(clean);
+  await fs.writeFile(file, JSON.stringify(cfg, null, 2) + '\n');
+  return clean;
+}
+
+async function deleteSite(file, name) {
+  const cfg = await loadSites(file);
+  cfg.sites = cfg.sites.filter(s => s.name !== name);
+  await fs.writeFile(file, JSON.stringify(cfg, null, 2) + '\n');
+}
+
+module.exports = { loadSites, saveSite, deleteSite, normaliseSite };

package/src/credentials.js

@@ -0,0 +1,32 @@
+'use strict';
+// Password storage. Windows → Credential Manager (Generic Credentials) via @napi-rs/keyring.
+// If the OS vault is unavailable, fall back to memory for this session only and say so.
+const SERVICE = 'shipback-sftp';
+
+class MemoryStore {
+  constructor() { this.map = new Map(); this.kind = 'memory'; }
+  async get(account) { return this.map.has(account) ? this.map.get(account) : null; }
+  async set(account, password) { this.map.set(account, password); }
+  async delete(account) { this.map.delete(account); }
+}
+
+class KeyringStore {
+  constructor(Entry) { this.Entry = Entry; this.kind = 'keyring'; }
+  async get(account) { try { return new this.Entry(SERVICE, account).getPassword() ?? null; } catch { return null; } }
+  async set(account, password) { new this.Entry(SERVICE, account).setPassword(password); }
+  async delete(account) { try { new this.Entry(SERVICE, account).deletePassword(); } catch { /* not there */ } }
+}
+
+/** Pick the best available store. Returns { store, note } */
+function createCredentialStore() {
+  try {
+    const { Entry } = require('@napi-rs/keyring');
+    // probe: the vault must be readable, otherwise fall back
+    new Entry(SERVICE, '__probe__').getPassword();
+    return { store: new KeyringStore(Entry), note: process.platform === 'win32' ? 'Passwords are kept in Windows Credential Manager.' : 'Passwords are kept in the OS keychain.' };
+  } catch (e) {
+    return { store: new MemoryStore(), note: `OS credential vault unavailable (${e.message.split('\n')[0]}). Passwords are kept in memory for this session only.` };
+  }
+}
+
+module.exports = { MemoryStore, KeyringStore, createCredentialStore, SERVICE };

package/src/deploy.js

@@ -0,0 +1,145 @@
+'use strict';
+// Deploy orchestrator: scan → plan → backup → upload → (delete) → manifest.
+const path = require('node:path');
+const posix = path.posix;
+const { scanLocal, loadIgnore, dropIgnored, sha256File } = require('./manifest');
+const { plan: makePlan, resolveVerify, MANIFEST_NAME, BACKUP_PREFIX } = require('./diff');
+const { backupFiles, makeStamp, freeBackupDir, writeBackupInfo } = require('./backup');
+const { writeLive } = require('./remote-fs');
+const { withLock } = require('./lock');
+
+const isBackupDir = name => name.startsWith(BACKUP_PREFIX);
+
+async function readRemoteManifest(remoteFs, root) {
+  try { return JSON.parse((await remoteFs.readFile(`${root}/${MANIFEST_NAME}`)).toString('utf8')); }
+  catch { return null; }
+}
+
+/** Preview only: scan both sides and return the plan. */
+async function previewDeploy({ localDir, remoteRoot, remoteFs, mirror = false, ignore, onEvent = () => {} }) {
+  const root = remoteRoot.replace(/\/$/, '');
+  onEvent({ type: 'scan', side: 'local', dir: localDir });
+  const local = await scanLocal(localDir, { ignore });
+  onEvent({ type: 'scan', side: 'remote', dir: root });
+  const rootStat = await remoteFs.stat(root);
+  if (rootStat && !rootStat.isDir) throw new Error(`Remote path is a file, not a folder: ${root}`);
+  // ignored paths are hands-off on the server too: never counted as extra, never mirror-deleted
+  const remoteListing = rootStat ? dropIgnored(await remoteFs.listRecursive(root, { skipDir: isBackupDir }), await loadIgnore(localDir, ignore)) : [];
+  const remoteManifest = rootStat ? await readRemoteManifest(remoteFs, root) : null;
+  const plan = makePlan({ local, remoteManifest, remoteListing, mirror });
+  if (plan.verify.length) await resolveVerify(plan, { readFile: p => remoteFs.readFile(`${root}/${p}`), onEvent });
+  onEvent({ type: 'plan', plan, localCount: local.length, remoteCount: remoteListing.length, remoteExists: !!rootStat });
+  return { local, plan, remoteExists: !!rootStat };
+}
+
+/**
+ * runDeploy({ localDir, remoteRoot, remoteFs, dryRun, backup, mirror, ignore, now, onEvent })
+ * → { dryRun, plan, uploaded, backedUp, backupDir, deleted, bytes }
+ */
+async function runDeploy(opts) {
+  if (opts.dryRun) return deployNow(opts);
+  return withLock({ remoteFs: opts.remoteFs, root: opts.remoteRoot, action: 'deploy', createRoot: true, onEvent: opts.onEvent }, () => deployNow(opts));
+}
+
+async function deployNow({ localDir, remoteRoot, remoteFs, dryRun = false, backup = true, mirror = false, ignore, now = new Date(), onEvent = () => {} }) {
+  const root = remoteRoot.replace(/\/$/, '');
+  const summary = { dryRun, plan: null, uploaded: [], backedUp: [], backupDir: null, deleted: [], bytes: 0 };
+  try {
+    const { local, plan, remoteExists } = await previewDeploy({ localDir, remoteRoot: root, remoteFs, mirror, ignore, onEvent });
+    summary.plan = plan;
+    if (dryRun) { onEvent({ type: 'done', summary }); return summary; }
+
+    if (!remoteExists) { await remoteFs.mkdirp(root); onEvent({ type: 'mkdir', path: root }); }
+
+    // 1. backup everything about to be overwritten or deleted, plus .backup.json so restore can undo this run.
+    //    The record says 'saving' until every copy is made: cut off before that, the run has changed nothing.
+    if (backup && (plan.upload.length || plan.delete.length)) {
+      const backupDir = await freeBackupDir(remoteFs, root, makeStamp(now));
+      await writeBackupInfo({ remoteFs, backupDir, info: { action: 'deploy', at: now.toISOString(), status: 'saving', overwritten: [], added: [], deleted: [] } });
+      const targets = [...plan.upload.filter(u => u.reason === 'changed').map(u => u.path), ...plan.delete];
+      const res = await backupFiles({ remoteFs, root, paths: targets, backupDir, onEvent });
+      const copied = new Set(res.copied);
+      const sha = new Map(local.map(f => [f.path, f.sha256]));
+      await writeBackupInfo({ remoteFs, backupDir, info: {
+        action: 'deploy', at: now.toISOString(),
+        overwritten: plan.upload.filter(u => copied.has(u.path)).map(u => ({ path: u.path, sha256: sha.get(u.path), was: res.was.get(u.path) })),
+        added: plan.upload.filter(u => !copied.has(u.path)).map(u => ({ path: u.path, sha256: sha.get(u.path) })),
+        deleted: plan.delete.filter(p => copied.has(p)).map(p => ({ path: p, was: res.was.get(p) })),
+      } });
+      summary.backedUp = res.copied;
+      summary.backupDir = backupDir;
+    }
+
+    // 2. upload new + changed, each swapped in whole (a dropped line leaves the old file, not half a new one)
+    const madeDirs = new Set([root]);
+    for (const u of plan.upload) {
+      const dest = `${root}/${u.path}`;
+      const dir = posix.dirname(dest);
+      if (!madeDirs.has(dir)) { await remoteFs.mkdirp(dir); madeDirs.add(dir); }
+      await writeLive(remoteFs, dest, { localPath: path.join(localDir, ...u.path.split('/')) });
+      summary.uploaded.push(u.path); summary.bytes += u.size;
+      onEvent({ type: 'upload', path: u.path, bytes: u.size, reason: u.reason, done: summary.uploaded.length, total: plan.upload.length });
+    }
+
+    // 3. mirror deletes
+    for (const p of plan.delete) {
+      await remoteFs.remove(`${root}/${p}`);
+      summary.deleted.push(p);
+      onEvent({ type: 'delete', path: p });
+    }
+
+    // 4. manifest for next time
+    const files = {};
+    for (const f of local) files[f.path] = { sha256: f.sha256, size: f.size, mtime: f.mtime };
+    await remoteFs.writeFile(`${root}/${MANIFEST_NAME}`, JSON.stringify({ version: 1, deployedAt: new Date().toISOString(), files }, null, 1));
+    onEvent({ type: 'manifest', path: MANIFEST_NAME, count: local.length });
+    onEvent({ type: 'done', summary });
+    return summary;
+  } catch (err) {
+    // a deploy that stopped part way is undone like any other: everything it touched is in its backup record
+    if (summary.backupDir && summary.uploaded.length) err.undo = `${summary.uploaded.length} of ${summary.plan.upload.length} files went up before it stopped. --restore undoes them (${posix.basename(summary.backupDir)}).`;
+    onEvent({ type: 'error', message: err.message, undo: err.undo, summary });
+    throw err;
+  }
+}
+
+/** Ad-hoc upload of named local files into a remote dir (with backup of anything overwritten). */
+function uploadFiles(opts) {
+  return withLock({ remoteFs: opts.remoteFs, root: opts.remoteDir, action: 'upload', createRoot: true, onEvent: opts.onEvent }, () => uploadNow(opts));
+}
+
+async function uploadNow({ files, remoteDir, remoteFs, backup = true, now = new Date(), onEvent = () => {} }) {
+  // files: [{ name, localPath, size }]
+  const root = remoteDir.replace(/\/$/, '');
+  const summary = { uploaded: [], backedUp: [], backupDir: null, bytes: 0 };
+  try {
+    await remoteFs.mkdirp(root);
+    if (backup && files.length) {
+      const backupDir = await freeBackupDir(remoteFs, root, makeStamp(now));
+      await writeBackupInfo({ remoteFs, backupDir, info: { action: 'upload', at: now.toISOString(), status: 'saving', overwritten: [], added: [], deleted: [] } });
+      const res = await backupFiles({ remoteFs, root, paths: files.map(f => f.name), backupDir, onEvent });
+      const copied = new Set(res.copied);
+      const shas = new Map();
+      for (const f of files) shas.set(f.name, await sha256File(f.localPath));
+      await writeBackupInfo({ remoteFs, backupDir, info: {
+        action: 'upload', at: now.toISOString(),
+        overwritten: files.filter(f => copied.has(f.name)).map(f => ({ path: f.name, sha256: shas.get(f.name), was: res.was.get(f.name) })),
+        added: files.filter(f => !copied.has(f.name)).map(f => ({ path: f.name, sha256: shas.get(f.name) })),
+        deleted: [],
+      } });
+      summary.backedUp = res.copied; summary.backupDir = backupDir;
+    }
+    for (const f of files) {
+      await writeLive(remoteFs, `${root}/${f.name}`, { localPath: f.localPath });
+      summary.uploaded.push(f.name); summary.bytes += f.size || 0;
+      onEvent({ type: 'upload', path: f.name, bytes: f.size || 0, reason: 'upload', done: summary.uploaded.length, total: files.length });
+    }
+    onEvent({ type: 'done', summary });
+    return summary;
+  } catch (err) {
+    onEvent({ type: 'error', message: err.message, summary });
+    throw err;
+  }
+}
+
+module.exports = { runDeploy, previewDeploy, uploadFiles, MANIFEST_NAME };

package/src/diff.js

@@ -0,0 +1,65 @@
+'use strict';
+// Compare a local manifest against the server and decide what to upload / skip / delete.
+const MANIFEST_NAME = '.deploy-manifest.json';
+const BACKUP_PREFIX = '_backup-';
+
+function isProtectedRemote(p) {
+  return p === MANIFEST_NAME || p.startsWith(BACKUP_PREFIX) || p.includes('/' + BACKUP_PREFIX);
+}
+
+/**
+ * plan({ local, remoteManifest, remoteListing, mirror })
+ *  local:          [{ path, size, mtime, sha256 }]
+ *  remoteManifest: { files: { path: { sha256 } } } | null   (written by the last deploy)
+ *  remoteListing:  [{ path, size, mtime }]                  (files actually on the server)
+ * → { upload: [{ path, size, reason }], skip: [path], verify: [{ path, size, sha256 }], extra: [path], delete: [path], uploadBytes }
+ * `verify` = same size on both sides but no manifest hash to compare; resolveVerify() settles those.
+ */
+function plan({ local, remoteManifest, remoteListing, mirror = false }) {
+  const remote = new Map(remoteListing.map(f => [f.path, f]));
+  const manifest = (remoteManifest && remoteManifest.files) || {};
+  const upload = [], skip = [], verify = [];
+  const localSet = new Set();
+  for (const f of [...local].sort((a, b) => a.path.localeCompare(b.path))) {
+    localSet.add(f.path);
+    const r = remote.get(f.path);
+    if (!r) { upload.push({ path: f.path, size: f.size, reason: 'new' }); continue; }
+    const m = manifest[f.path];
+    if (m && m.sha256 === f.sha256 && r.size === f.size) {
+      skip.push(f.path);                 // exactly what we deployed last time
+    } else if (r.size !== f.size) {
+      upload.push({ path: f.path, size: f.size, reason: 'changed' });
+    } else {
+      // same size but no manifest hash to trust (never deployed by us, or the folder was pulled since): read the server copy
+      verify.push({ path: f.path, size: f.size, sha256: f.sha256 });
+    }
+  }
+  const extra = [...remote.keys()].filter(p => !localSet.has(p) && !isProtectedRemote(p)).sort();
+  return finalise({ upload, skip, verify, extra, delete: mirror ? [...extra] : [] });
+}
+
+function finalise(p) {
+  p.upload.sort((a, b) => a.path.localeCompare(b.path));
+  p.skip.sort();
+  p.uploadBytes = p.upload.reduce((n, u) => n + u.size, 0);
+  return p;
+}
+
+/**
+ * Resolve the `verify` list by hashing the server copies. Files above `maxBytes` are assumed
+ * unchanged (same size, too big to be worth a download). Mutates and returns the plan.
+ */
+async function resolveVerify(plan, { readFile, maxBytes = 8 * 1024 * 1024, onEvent = () => {} }) {
+  const crypto = require('node:crypto');
+  for (const v of plan.verify) {
+    if (v.size > maxBytes) { plan.skip.push(v.path); continue; }
+    onEvent({ type: 'verify', path: v.path });
+    const remoteHash = crypto.createHash('sha256').update(await readFile(v.path)).digest('hex');
+    if (remoteHash === v.sha256) plan.skip.push(v.path);
+    else plan.upload.push({ path: v.path, size: v.size, reason: 'changed' });
+  }
+  plan.verify = [];
+  return finalise(plan);
+}
+
+module.exports = { plan, resolveVerify, MANIFEST_NAME, BACKUP_PREFIX, isProtectedRemote };

package/src/history.js

@@ -0,0 +1,37 @@
+'use strict';
+// deploys.jsonl — one line per deploy / upload / pull, so "what went up and when" is answerable later.
+const fs = require('node:fs/promises');
+
+async function appendHistory(file, record) {
+  await fs.appendFile(file, JSON.stringify(record) + '\n');
+}
+
+async function readHistory(file, { site, limit = 50 } = {}) {
+  let text;
+  try { text = await fs.readFile(file, 'utf8'); } catch (e) { if (e.code === 'ENOENT') return []; throw e; }
+  const out = [];
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    try { const r = JSON.parse(line); if (!site || r.site === site) out.push(r); } catch { /* skip corrupt line */ }
+  }
+  return out.reverse().slice(0, limit);
+}
+
+/** Build a compact history record from a run summary (deploy / upload / pull). */
+function recordFromSummary({ action, site, trigger = 'ui', localDir, remoteDir, startedAt, summary = {}, error }) {
+  const plan = summary.plan || {};
+  return {
+    at: new Date().toISOString(), startedAt, action, site, trigger, ok: !error, error: error || undefined,
+    localDir, remoteDir, dryRun: !!summary.dryRun,
+    uploaded: summary.uploaded || undefined, downloaded: summary.downloaded || undefined, deleted: summary.deleted || undefined,
+    pruned: summary.pruned ? summary.pruned.map(p => p.name) : undefined, refused: Array.isArray(summary.refused) ? summary.refused.map(r => r.name) : undefined,
+    restoredFrom: action === 'restore' ? summary.backup : undefined,
+    restored: action === 'restore' ? summary.put : undefined, removed: action === 'restore' ? summary.remove : undefined,
+    refusedConflicts: summary.conflicts && summary.refused ? summary.conflicts.length : undefined,
+    backedUp: summary.backedUp ? summary.backedUp.length : undefined, backupDir: summary.backupDir || summary.undoBackupDir || undefined,
+    bytes: summary.bytes || 0,
+    unchanged: plan.skip ? plan.skip.length : undefined, extra: plan.extra ? plan.extra.length : undefined,
+  };
+}
+
+module.exports = { appendHistory, readHistory, recordFromSummary };

package/src/lock.js

@@ -0,0 +1,92 @@
+'use strict';
+// One run at a time per site. Deploy, upload, restore and prune hold <root>/.shipback-lock while they write: two
+// at once would interleave their backups, and an undo could then pick up half of each. A second run is refused
+// and told who holds the lock.
+//
+// A run that is cut off can't take its lock away, so a lock counts as stale (and is taken over) when:
+//   · it was taken on this computer by a process that has ended, or by this process for a run that is over, or
+//   · nobody has refreshed it for STALE_MS (the holder rewrites it every HEARTBEAT_MS while it runs)
+//
+// withLock({ remoteFs, root, action, createRoot, onEvent }, fn) → fn's result, the lock held throughout.
+// Only a deploy or upload creates a missing root; a restore or prune there has nothing to protect and fails by itself.
+const crypto = require('node:crypto');
+const os = require('node:os');
+const { LOCK_NAME } = require('./remote-fs');
+
+const HEARTBEAT_MS = 30000;
+const STALE_MS = 120000;
+const held = new Set(); // tokens this process holds right now
+
+// the lock sits in the web root, so it carries a hash of the computer's name, not the name
+const machine = () => crypto.createHash('sha256').update(os.hostname()).digest('hex').slice(0, 12);
+
+function pidAlive(pid) {
+  try { process.kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; }
+}
+
+async function readLock(remoteFs, file) {
+  try { return JSON.parse((await remoteFs.readFile(file)).toString('utf8')); } catch { return null; }
+}
+
+/** Why a lock can be taken over, or null if its run may still be going. */
+function staleReason(lock, mtime, now) {
+  if (lock && lock.machine === machine() && Number.isInteger(lock.pid)) {
+    if (lock.pid === process.pid ? !held.has(lock.token) : !pidAlive(lock.pid)) return 'its run on this computer has ended';
+  }
+  if (now - mtime > STALE_MS) return `nothing has refreshed it for ${Math.round((now - mtime) / 60000)} min`;
+  return null;
+}
+
+class LockedError extends Error {
+  constructor(lock) {
+    const who = lock && lock.machine === machine() ? 'on this computer' : 'from another computer';
+    super(`Another ${lock && lock.action || 'run'} is writing to this site right now (started ${lock && lock.at || 'just now'}, ${who}). `
+      + 'Nothing was changed. Try again when it finishes. A lock left by a run that was cut off clears itself within 2 minutes.');
+    this.code = 'ELOCKED';
+  }
+}
+
+async function acquire({ remoteFs, root, action, now = Date.now, onEvent = () => {} }) {
+  const file = `${root}/${LOCK_NAME}`;
+  const token = crypto.randomBytes(8).toString('hex');
+  const body = () => Buffer.from(JSON.stringify({ tool: 'shipback-sftp', action, token, pid: process.pid, machine: machine(), at: new Date(now()).toISOString() }));
+  for (let attempt = 0; attempt < 3; attempt++) {
+    if (await remoteFs.createExclusive(file, body())) {
+      held.add(token);
+      let beat = Promise.resolve();
+      const timer = setInterval(() => { beat = beat.then(() => remoteFs.writeFile(file, body())).catch(() => {}); }, HEARTBEAT_MS);
+      if (timer.unref) timer.unref();
+      return async () => {
+        clearInterval(timer);
+        held.delete(token);
+        await beat;
+        const cur = await readLock(remoteFs, file);
+        if (cur && cur.token === token) await remoteFs.remove(file).catch(() => {});
+      };
+    }
+    const st = await remoteFs.stat(file);
+    if (!st) continue; // released between the two calls
+    const lock = await readLock(remoteFs, file);
+    const why = staleReason(lock, st.mtime, now());
+    if (!why) throw new LockedError(lock);
+    onEvent({ type: 'stale-lock', action: lock && lock.action, at: lock && lock.at, why });
+    await remoteFs.remove(file).catch(() => {});
+  }
+  throw new LockedError(await readLock(remoteFs, file));
+}
+
+async function withLock({ remoteFs, root, action, createRoot = false, now, onEvent = () => {} }, fn) {
+  root = root.replace(/\/$/, '');
+  let release = null;
+  try {
+    const exists = await remoteFs.stat(root);
+    if (exists || createRoot) {
+      if (!exists) await remoteFs.mkdirp(root);
+      release = await acquire({ remoteFs, root, action, now, onEvent });
+    }
+  } catch (err) { onEvent({ type: 'error', message: err.message, code: err.code }); throw err; }
+  try { return await fn(); }
+  finally { if (release) await release().catch(() => {}); } // a dropped connection can't release: the lock then goes stale
+}
+
+module.exports = { withLock, LockedError, STALE_MS, HEARTBEAT_MS };

package/src/manifest.js

@@ -0,0 +1,98 @@
+'use strict';
+// Local folder scan → manifest [{ path, size, mtime, sha256 }], with gitignore-style ignore rules.
+const fs = require('node:fs/promises');
+const { createReadStream } = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const DEFAULT_IGNORE = ['.git/', 'node_modules/', 'Thumbs.db', '.DS_Store', 'desktop.ini', '*.tmp', '.deployignore', '_backup-*/'];
+const IGNORE_FILE = '.deployignore';
+
+function parseIgnoreFile(text) {
+  return String(text || '').split(/\r?\n/).map(l => l.trim()).filter(l => l && !l.startsWith('#'));
+}
+
+function globToRegex(glob) {
+  let re = '';
+  for (const ch of glob) {
+    if (ch === '*') re += '[^/]*';
+    else if (ch === '?') re += '[^/]';
+    else re += ch.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  }
+  return re;
+}
+
+/** makeMatcher(globs) → (relPosixPath, isDir) => boolean */
+function makeMatcher(globs) {
+  const rules = globs.map(g => {
+    let dirOnly = false, pattern = g;
+    if (pattern.endsWith('/')) { dirOnly = true; pattern = pattern.slice(0, -1); }
+    const anchored = pattern.includes('/');
+    if (anchored && pattern.startsWith('/')) pattern = pattern.slice(1);
+    const body = globToRegex(pattern);
+    // anchored patterns match from the root; bare names match at any depth
+    const re = anchored ? new RegExp('^' + body + '(/|$)') : new RegExp('(^|/)' + body + '(/|$)');
+    return { re, dirOnly };
+  });
+  return (rel, isDir) => {
+    for (const r of rules) {
+      const m = r.re.exec(rel);
+      if (!m) continue;
+      if (!r.dirOnly) return true;
+      // dir-only rule: matches if the matched segment is a directory (i.e. something follows it, or the entry itself is a dir)
+      const matchedToEnd = m[0].length === rel.length - m.index && !m[0].endsWith('/');
+      if (!matchedToEnd || isDir) return true;
+    }
+    return false;
+  };
+}
+
+function sha256File(p) {
+  return new Promise((resolve, reject) => {
+    const h = crypto.createHash('sha256');
+    createReadStream(p).on('data', d => h.update(d)).on('end', () => resolve(h.digest('hex'))).on('error', reject);
+  });
+}
+
+/**
+ * loadIgnore(dir, ignore) → (relPosixPath, isDir) => boolean
+ * The one set of ignore rules for a site: built-in defaults + the site's "ignore" list + the local .deployignore.
+ * Used for the local scan AND to filter the server listing, so an ignored path is hands-off in both directions
+ * (never uploaded, never pulled, never mirror-deleted).
+ */
+async function loadIgnore(dir, ignore = []) {
+  let globs = [...DEFAULT_IGNORE, ...(ignore || [])];
+  try { globs = globs.concat(parseIgnoreFile(await fs.readFile(path.join(dir, IGNORE_FILE), 'utf8'))); } catch { /* none */ }
+  return makeMatcher(globs);
+}
+
+/** dropIgnored(remoteListing, ignored) → the listing without ignored files ([{ path, ... }], paths relative to the root) */
+function dropIgnored(listing, ignored) {
+  return listing.filter(f => !ignored(f.path, false));
+}
+
+/** scanLocal(dir, { ignore }) → sorted manifest */
+async function scanLocal(dir, opts = {}) {
+  let st;
+  try { st = await fs.stat(dir); } catch (e) { throw new Error(`Local folder not found: ${dir}`); }
+  if (!st.isDirectory()) throw new Error(`Not a folder: ${dir}`);
+  const ignored = await loadIgnore(dir, opts.ignore);
+  const out = [];
+  async function walk(abs, rel) {
+    const entries = await fs.readdir(abs, { withFileTypes: true });
+    for (const e of entries) {
+      const r = rel ? rel + '/' + e.name : e.name;
+      if (e.isDirectory()) { if (!ignored(r, true)) await walk(path.join(abs, e.name), r); continue; }
+      if (!e.isFile()) continue;
+      if (ignored(r, false)) continue;
+      const full = path.join(abs, e.name);
+      const s = await fs.stat(full);
+      out.push({ path: r, size: s.size, mtime: Math.floor(s.mtimeMs), sha256: await sha256File(full) });
+    }
+  }
+  await walk(dir, '');
+  out.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  return out;
+}
+
+module.exports = { scanLocal, loadIgnore, dropIgnored, makeMatcher, parseIgnoreFile, DEFAULT_IGNORE, IGNORE_FILE, sha256File };