shipback-sftp 0.0.0-stage → 0.2.0

package/src/remote-fs.js

@@ -0,0 +1,226 @@
+'use strict';
+// RemoteFs: the small set of server operations the deploy needs.
+//   stat(p) → { size, mtime(ms), isDir } | null
+//   listRecursive(dir, { skipDir }) → [{ path (posix, relative to dir), size, mtime(ms) }]  (files only)
+//   mkdirp(p) · readFile(p) → Buffer · writeFile(p, Buffer) · uploadFile(localPath, p)
+//   rename(a, b) · replace(tmp, dest) · remove(p) · rmdir(p) · close()
+//
+// Live files are never written in place: the new copy goes to partPath(dest) and replace() swaps it in, so a
+// dropped connection leaves the old file whole, never half a file. The part name keeps the extension (a stray
+// part of config.php is still run as PHP, not served as source) and listRecursive hides part files.
+const posix = require('node:path').posix;
+const fs = require('node:fs');
+const { Client } = require('ssh2');
+
+const PART_PREFIX = '.shipback-part-';
+const LOCK_NAME = '.shipback-lock';
+const partPath = p => posix.join(posix.dirname(p), PART_PREFIX + posix.basename(p));
+const isPart = rel => posix.basename(rel).startsWith(PART_PREFIX);
+const isHidden = rel => isPart(rel) || rel === LOCK_NAME; // Shipback's own working files: never deployed, pulled or listed
+
+// ---------------------------------------------------------------- MemoryRemoteFs (tests)
+class MemoryRemoteFs {
+  // failOn(p): throw before touching p · tornOn(p): write half of p, then throw (a dropped connection)
+  constructor() { this.files = new Map(); this.dirs = new Set(['/']); this.failOn = null; this.tornOn = null; }
+  _check(p) { if (this.failOn && this.failOn(p)) throw new Error(`Simulated failure on ${p}`); }
+  async stat(p) {
+    p = posix.normalize(p);
+    if (this.files.has(p)) { const f = this.files.get(p); return { size: f.data.length, mtime: f.mtime, isDir: false }; }
+    if (this.dirs.has(p)) return { size: 0, mtime: 0, isDir: true };
+    return null;
+  }
+  async listRecursive(dir, { skipDir } = {}) {
+    dir = posix.normalize(dir).replace(/\/$/, '');
+    const out = [];
+    for (const [p, f] of this.files) {
+      if (!p.startsWith(dir + '/')) continue;
+      const rel = p.slice(dir.length + 1);
+      if (skipDir && rel.split('/').slice(0, -1).some(seg => skipDir(seg))) continue;
+      if (isHidden(rel)) continue;
+      out.push({ path: rel, size: f.data.length, mtime: f.mtime });
+    }
+    return out.sort((a, b) => a.path.localeCompare(b.path));
+  }
+  async listDir(dir) {
+    dir = posix.normalize(dir).replace(/\/$/, '') || '/';
+    const prefix = dir === '/' ? '/' : dir + '/';
+    const out = new Map();
+    for (const d of this.dirs) if (d.startsWith(prefix) && d !== dir && !d.slice(prefix.length).includes('/')) out.set(d.slice(prefix.length), { name: d.slice(prefix.length), type: 'dir', size: 0, mtime: 0 });
+    for (const [p, f] of this.files) if (p.startsWith(prefix) && !p.slice(prefix.length).includes('/')) out.set(p.slice(prefix.length), { name: p.slice(prefix.length), type: 'file', size: f.data.length, mtime: f.mtime });
+    return [...out.values()].sort((a, b) => a.type === b.type ? a.name.localeCompare(b.name) : a.type === 'dir' ? -1 : 1);
+  }
+  async mkdirp(p) {
+    p = posix.normalize(p);
+    const parts = p.split('/').filter(Boolean);
+    let cur = '';
+    for (const part of parts) { cur += '/' + part; if (this.files.has(cur)) throw new Error(`Not a directory: ${cur}`); this.dirs.add(cur); }
+  }
+  async readFile(p) {
+    p = posix.normalize(p); this._check(p);
+    const f = this.files.get(p); if (!f) { const e = new Error(`No such file: ${p}`); e.code = 'ENOENT'; throw e; }
+    return Buffer.from(f.data);
+  }
+  async writeFile(p, data) {
+    p = posix.normalize(p); this._check(p);
+    if (!this.dirs.has(posix.dirname(p))) { const e = new Error(`No such directory: ${posix.dirname(p)}`); e.code = 'ENOENT'; throw e; }
+    if (this.tornOn && this.tornOn(p)) {
+      this.files.set(p, { data: Buffer.from(data).subarray(0, Math.floor(data.length / 2)), mtime: Date.now() });
+      throw new Error(`Simulated connection drop while writing ${p}`);
+    }
+    this.files.set(p, { data: Buffer.from(data), mtime: Date.now() });
+  }
+  async uploadFile(localPath, p) { await this.writeFile(p, await fs.promises.readFile(localPath)); }
+  async rename(a, b) { a = posix.normalize(a); b = posix.normalize(b); const f = this.files.get(a); if (!f) throw new Error(`No such file: ${a}`); this.files.delete(a); this.files.set(b, f); }
+  async replace(tmp, dest) { this._check(posix.normalize(dest)); await this.rename(tmp, dest); }
+  async createExclusive(p, data) { p = posix.normalize(p); if (this.files.has(p) || this.dirs.has(p)) return false; await this.writeFile(p, data); return true; }
+  async remove(p) { p = posix.normalize(p); this._check(p); if (!this.files.delete(p)) throw new Error(`No such file: ${p}`); }
+  async rmdir(p) { this.dirs.delete(posix.normalize(p)); }
+  async close() {}
+  dump() { return { dirs: [...this.dirs].sort(), files: [...this.files].map(([p, f]) => [p, f.data.toString('base64')]).sort() }; }
+}
+
+// ---------------------------------------------------------------- SftpRemoteFs (ssh2)
+// Many shared hosts firewall SSH: a wrong port or an unlisted IP is dropped silently, so ssh2 only says "timed out".
+const UNREACHABLE_HINT = 'Check the port (many shared hosts run SFTP on their own port, not 22) and that your host lets your '
+  + 'current IP in (some make you allow-list it under SSH Access, and home IPs change).';
+
+class SftpRemoteFs {
+  constructor(client, sftp) {
+    this.client = client; this.sftp = sftp;
+    // ssh2 drops pending SFTP callbacks when the line goes: without this a cut-off upload never settles and the
+    // CLI exits 0 with nothing said. Every operation fails with this error instead.
+    this.lost = null; this.pending = new Set();
+    const fail = why => {
+      if (this.lost) return;
+      this.lost = new Error(`Lost the connection to the server${why ? ` (${why})` : ''}`);
+      for (const reject of this.pending) reject(this.lost);
+      this.pending.clear();
+    };
+    client.on('close', () => fail()); client.on('error', e => fail(e.message));
+    if (sftp && sftp.on) sftp.on('close', () => fail());
+  }
+  _guard(op) {
+    if (this.lost) return Promise.reject(this.lost);
+    let reject;
+    const cut = new Promise((_, r) => { reject = r; this.pending.add(r); });
+    return Promise.race([op, cut]).finally(() => this.pending.delete(reject));
+  }
+
+  /** connect({ host, port, username, password | privateKey, readyTimeout }) */
+  static connect(opts) {
+    return new Promise((resolve, reject) => {
+      const client = new Client();
+      const cfg = {
+        host: opts.host, port: opts.port || 22, username: opts.username,
+        readyTimeout: opts.readyTimeout || 20000, keepaliveInterval: 15000,
+      };
+      if (opts.privateKey) { cfg.privateKey = opts.privateKey; if (opts.passphrase) cfg.passphrase = opts.passphrase; }
+      else cfg.password = opts.password;
+      let settled = false;
+      client.on('ready', () => {
+        client.sftp((err, sftp) => {
+          if (settled) return; settled = true;
+          if (err) { client.end(); return reject(err); }
+          resolve(new SftpRemoteFs(client, sftp));
+        });
+      });
+      client.on('error', err => {
+        if (settled) return; settled = true;
+        const msg = /authentication/i.test(err.message) ? (opts.privateKey
+            ? `Authentication failed for ${opts.username}@${opts.host} — the server rejected the key file. Authorize its public key in cPanel → Security → SSH Access → Manage SSH Keys, or clear "Private key file" in Edit site to log in with the password`
+            : `Authentication failed for ${opts.username}@${opts.host} (check username/password)`)
+          : /ECONNREFUSED|ENOTFOUND|EAI_AGAIN|Timed out/i.test(err.message) ? `Cannot reach ${opts.host}:${cfg.port} — ${err.message}. ${UNREACHABLE_HINT}`
+          : err.message;
+        reject(new Error(msg));
+      });
+      client.connect(cfg);
+    });
+  }
+
+  _p(fn) { return this._guard(new Promise((res, rej) => fn((err, val) => err ? rej(err) : res(val)))); }
+
+  async stat(p) {
+    try { const a = await this._p(cb => this.sftp.stat(p, cb)); return { size: a.size, mtime: a.mtime * 1000, isDir: a.isDirectory(), mode: a.mode }; }
+    catch (e) { if (e.code === 2 || /No such file/i.test(e.message)) return null; throw e; }
+  }
+  async listRecursive(dir, { skipDir } = {}) {
+    const out = [];
+    const walk = async (abs, rel) => {
+      const entries = await this._p(cb => this.sftp.readdir(abs, cb));
+      for (const e of entries) {
+        if (e.filename === '.' || e.filename === '..') continue;
+        const r = rel ? rel + '/' + e.filename : e.filename;
+        if (e.attrs.isDirectory()) { if (!(skipDir && skipDir(e.filename))) await walk(abs + '/' + e.filename, r); }
+        else if (e.attrs.isFile() && !isHidden(r)) out.push({ path: r, size: e.attrs.size, mtime: e.attrs.mtime * 1000 });
+      }
+    };
+    await walk(dir.replace(/\/$/, ''), '');
+    return out.sort((a, b) => a.path.localeCompare(b.path));
+  }
+  async listDir(dir) {
+    const entries = await this._p(cb => this.sftp.readdir(dir.replace(/\/$/, '') || '/', cb));
+    return entries.filter(e => e.filename !== '.' && e.filename !== '..')
+      .map(e => ({ name: e.filename, type: e.attrs.isDirectory() ? 'dir' : e.attrs.isFile() ? 'file' : 'other', size: e.attrs.size, mtime: e.attrs.mtime * 1000 }))
+      .sort((a, b) => a.type === b.type ? a.name.localeCompare(b.name) : a.type === 'dir' ? -1 : 1);
+  }
+  async mkdirp(p) {
+    const parts = posix.normalize(p).split('/').filter(Boolean);
+    let cur = '';
+    for (const part of parts) {
+      cur += '/' + part;
+      const st = await this.stat(cur);
+      if (st) { if (!st.isDir) throw new Error(`Not a directory on server: ${cur}`); continue; }
+      await this._p(cb => this.sftp.mkdir(cur, cb));
+    }
+  }
+  readFile(p) {
+    return this._guard(new Promise((resolve, reject) => {
+      const chunks = [];
+      this.sftp.createReadStream(p).on('data', c => chunks.push(c)).on('end', () => resolve(Buffer.concat(chunks))).on('error', reject);
+    }));
+  }
+  writeFile(p, data) {
+    return this._guard(new Promise((resolve, reject) => {
+      const ws = this.sftp.createWriteStream(p);
+      ws.on('error', reject).on('close', resolve);
+      ws.end(Buffer.from(data));
+    }));
+  }
+  uploadFile(localPath, p) {
+    return this._p(cb => this.sftp.fastPut(localPath, p, { concurrency: 4, chunkSize: 32768 }, cb));
+  }
+  rename(a, b) { return this._p(cb => this.sftp.rename(a, b, cb)); }
+  /** Create p only if nothing is there yet (O_EXCL): true if created, false if it already exists. */
+  async createExclusive(p, data) {
+    let handle;
+    try { handle = await this._p(cb => this.sftp.open(p, 'wx', cb)); }
+    catch (e) { if (await this.stat(p)) return false; throw e; }
+    try { const buf = Buffer.from(data); await this._p(cb => this.sftp.write(handle, buf, 0, buf.length, 0, cb)); }
+    finally { await this._p(cb => this.sftp.close(handle, cb)).catch(() => {}); }
+    return true;
+  }
+  /** Swap a fully written part file in over dest, keeping dest's permissions (suEXEC hosts 500 on 0666 PHP). */
+  async replace(tmp, dest) {
+    const st = await this.stat(dest);
+    if (st && st.mode !== undefined) await this._p(cb => this.sftp.chmod(tmp, st.mode & 0o7777, cb));
+    // OpenSSH (cPanel, Plesk, DirectAdmin, any VPS) has had posix-rename since 2008: one atomic step
+    try { return await this._p(cb => this.sftp.ext_openssh_rename(tmp, dest, cb)); }
+    catch (e) { if (!/does not support/i.test(e.message)) throw e; }
+    if (!st) return this.rename(tmp, dest);
+    try { return await this.rename(tmp, dest); } // some servers replace on a plain rename
+    catch { await this.remove(dest); return this.rename(tmp, dest); } // restore.js copes if the line drops between these two
+  }
+  remove(p) { return this._p(cb => this.sftp.unlink(p, cb)); }
+  rmdir(p) { return this._p(cb => this.sftp.rmdir(p, cb)); }
+  async close() { try { this.client.end(); } catch { /* ignore */ } }
+}
+
+/** Write a live file the safe way: to its part file first, then swapped in whole. Give { data } or { localPath }. */
+async function writeLive(remoteFs, dest, { data, localPath }) {
+  const part = partPath(dest);
+  if (localPath !== undefined) await remoteFs.uploadFile(localPath, part);
+  else await remoteFs.writeFile(part, data);
+  await remoteFs.replace(part, dest);
+}
+
+module.exports = { PART_PREFIX, LOCK_NAME, partPath, isPart, isHidden, writeLive, MemoryRemoteFs, SftpRemoteFs };

package/src/restore.js

@@ -0,0 +1,196 @@
+'use strict';
+// Restore: put a _backup-<stamp>/ folder back — the undo for a deploy.
+//
+// A deploy's backup folder holds the server copies of every file it overwrote or deleted, and
+// .backup.json saying which files it added and what it uploaded (sha256). Restore:
+//   · checks first that each live file is still what that run left there (or is already the old copy).
+//     A file edited on the server since is a conflict, and then nothing is changed unless { force: true }
+//   · checks each saved copy against the sha256 recorded when it was saved: a damaged copy is never put back
+//   · copes with a run that stopped part way: files it never reached are already right, and a file caught
+//     between "old removed" and "new swapped in" (servers without posix-rename) is found in its part file
+//   · backs up everything it is about to change into a new _backup-<stamp>/ with its own .backup.json,
+//     so a restore can itself be restored
+//   · writes each backed-up file back to its live path and removes the files that run added
+//   · drops the touched paths from .deploy-manifest.json, so the next deploy compares them by content
+// A backup with no .backup.json (made by an older version) restores its files only: summary.legacy = true,
+// added files stay, and there is nothing to check edits against.
+//
+// runRestore({ remoteRoot, remoteFs, name, dryRun, force, now, onEvent })
+//   name: the backup folder ('_backup-2026-10-18-1400') or 'latest' / omitted for the newest
+// → { dryRun, backup, action, legacy, put, remove, same, conflicts: [{ path, why }], refused, undoBackupDir }
+const crypto = require('node:crypto');
+const posix = require('node:path').posix;
+const { BACKUP_PREFIX, MANIFEST_NAME } = require('./diff');
+const { backupFiles, makeStamp, freeBackupDir, writeBackupInfo, readBackupInfo, BACKUP_INFO } = require('./backup');
+const { listBackups } = require('./prune');
+const { partPath, writeLive } = require('./remote-fs');
+const { withLock } = require('./lock');
+
+const sha256 = buf => crypto.createHash('sha256').update(buf).digest('hex');
+
+function chooseBackup(backups, name) {
+  if (!backups.length) throw new Error('There are no _backup-* folders on the server to restore from');
+  if (name === undefined || name === null || name === '' || name === 'latest') return backups[backups.length - 1];
+  if (typeof name !== 'string' || !name.startsWith(BACKUP_PREFIX) || name.includes('/') || name.includes('\\') || name.includes('..')) throw new Error(`Not a backup folder name: "${name}" (must be ${BACKUP_PREFIX}<stamp>, or "latest")`);
+  if (!backups.includes(name)) throw new Error(`No such backup on the server: ${name}`);
+  return name;
+}
+
+/** Backups newest first, each with what it holds: [{ name, action, at, overwritten, added, deleted, files, legacy }] */
+async function describeBackups({ remoteRoot, remoteFs }) {
+  const root = remoteRoot.replace(/\/$/, '');
+  const out = [];
+  for (const name of (await listBackups(remoteFs, root)).reverse()) {
+    const info = await readBackupInfo(remoteFs, `${root}/${name}`);
+    const files = (await remoteFs.listRecursive(`${root}/${name}`)).filter(f => f.path !== BACKUP_INFO).length;
+    out.push(info
+      ? { name, action: info.action, at: info.at, from: info.from, overwritten: info.overwritten.length, added: info.added.length, deleted: info.deleted.length, files, legacy: false, status: info.status }
+      : { name, files, legacy: true });
+  }
+  return out;
+}
+
+function runRestore(opts) {
+  if (opts.dryRun) return restoreNow(opts);
+  return withLock({ remoteFs: opts.remoteFs, root: opts.remoteRoot, action: 'restore', onEvent: opts.onEvent }, () => restoreNow(opts));
+}
+
+async function restoreNow({ remoteRoot, remoteFs, name, dryRun = false, force = false, now = new Date(), onEvent = () => {} }) {
+  const root = remoteRoot.replace(/\/$/, '');
+  onEvent({ type: 'scan', side: 'remote', dir: root });
+  let target = chooseBackup(await listBackups(remoteFs, root), name);
+  let info = await readBackupInfo(remoteFs, `${root}/${target}`);
+  let resumed = null;
+  // the latest run is a restore that was cut off: running it again finishes that restore
+  const latest = name === undefined || name === null || name === '' || name === 'latest';
+  if (latest && info && info.action === 'restore' && info.status && info.from) {
+    resumed = target; target = chooseBackup(await listBackups(remoteFs, root), info.from);
+    info = await readBackupInfo(remoteFs, `${root}/${target}`);
+  }
+  const dir = `${root}/${target}`;
+  const summary = { dryRun, backup: target, action: info ? info.action : undefined, legacy: !info, resumed, stoppedEarly: false, put: [], remove: [], same: [], conflicts: [], refused: false, undoBackupDir: null };
+  if (info && info.status === 'saving') {
+    // that run was cut off while it was still making its backup copies, before it changed a single live file
+    summary.stoppedEarly = true;
+    onEvent({ type: 'restore-plan', backup: target, put: [], remove: [], same: 0, conflicts: 0, legacy: false, stoppedEarly: true });
+    onEvent({ type: 'done', summary });
+    return summary;
+  }
+
+  const left = new Map();      // path → sha256 the run left there (overwritten + added)
+  const deleted = new Set();   // paths the run deleted
+  const was = new Map();       // path → sha256 of the copy saved in the backup folder (records from 0.2 on)
+  if (info) {
+    for (const e of [...info.overwritten, ...info.added]) left.set(e.path, e.sha256);
+    for (const e of info.deleted) deleted.add(e.path);
+    for (const e of [...info.overwritten, ...info.deleted]) if (e.was) was.set(e.path, e.was);
+  }
+  const live = async p => {
+    const st = await remoteFs.stat(`${root}/${p}`);
+    if (!st) {
+      // the line dropped mid-swap: the run's whole copy is still in the part file
+      const part = partPath(`${root}/${p}`);
+      if (left.has(p) && await remoteFs.stat(part) && sha256(await remoteFs.readFile(part)) === left.get(p)) return left.get(p);
+      return null;
+    }
+    return st.isDir ? 'dir' : sha256(await remoteFs.readFile(`${root}/${p}`));
+  };
+  const conflict = (p, why) => summary.conflicts.push({ path: p, why });
+
+  // 1. what goes back: every file in the backup folder
+  const puts = [];
+  for (const f of (await remoteFs.listRecursive(dir)).filter(f => f.path !== BACKUP_INFO)) {
+    const data = await remoteFs.readFile(`${dir}/${f.path}`);
+    if (was.has(f.path) && sha256(data) !== was.get(f.path)) { conflict(f.path, 'its copy in the backup folder is damaged (it no longer matches what was saved)'); continue; } // never put back, even forced
+    const now_ = await live(f.path);
+    if (now_ === sha256(data)) { summary.same.push(f.path); continue; }
+    if (now_ === 'dir') { conflict(f.path, 'is a folder on the server now'); continue; } // can't write a file over it, even forced
+    puts.push({ path: f.path, data });
+    if (left.has(f.path) && now_ !== left.get(f.path)) conflict(f.path, now_ === null ? 'deleted on the server after that run' : 'edited on the server after that run');
+    else if (deleted.has(f.path) && now_ !== null) conflict(f.path, 'put back on the server after that run deleted it');
+  }
+  // 2. what comes off: the files that run added
+  const removes = [];
+  if (info) for (const e of info.added) {
+    const now_ = await live(e.path);
+    if (now_ === null) { summary.same.push(e.path); continue; }
+    if (now_ === 'dir') { conflict(e.path, 'is a folder on the server now'); continue; }
+    removes.push(e.path);
+    if (now_ !== e.sha256) conflict(e.path, 'edited on the server after that run added it');
+  }
+  summary.put = puts.map(p => p.path).sort();
+  summary.remove = removes.sort();
+  summary.same.sort();
+  onEvent({ type: 'restore-plan', backup: target, put: summary.put, remove: summary.remove, same: summary.same.length, conflicts: summary.conflicts.length, legacy: summary.legacy });
+  for (const c of summary.conflicts) onEvent({ type: 'conflict', ...c });
+
+  if (summary.conflicts.length && !force) {
+    summary.refused = true;
+    onEvent({ type: 'done', summary });
+    return summary;
+  }
+  // part files a stopped run left behind (hidden from listings, but they hold the run's bytes)
+  const sweepParts = async () => {
+    for (const p of new Set([...left.keys(), ...deleted])) {
+      const part = partPath(`${root}/${p}`);
+      if (await remoteFs.stat(part)) await remoteFs.remove(part).catch(() => {});
+    }
+  };
+  if (dryRun) { onEvent({ type: 'done', summary }); return summary; }
+  if (!puts.length && !removes.length) { await sweepParts(); onEvent({ type: 'done', summary }); return summary; }
+  try {
+    // 3. back up what is live now, so this restore can be undone too. Its record says 'saving', then 'running'
+    //    while files are written, then nothing: cut off part way, running restore again finishes the job.
+    const undoDir = await freeBackupDir(remoteFs, root, makeStamp(now));
+    summary.undoBackupDir = undoDir;
+    const head = { action: 'restore', from: target, at: now.toISOString() };
+    await writeBackupInfo({ remoteFs, backupDir: undoDir, info: { ...head, status: 'saving', overwritten: [], added: [], deleted: [] } });
+    const res = await backupFiles({ remoteFs, root, paths: [...summary.put, ...summary.remove], backupDir: undoDir, onEvent });
+    const copied = new Set(res.copied);
+    const record = {
+      ...head,
+      overwritten: puts.filter(p => copied.has(p.path)).map(p => ({ path: p.path, sha256: sha256(p.data), was: res.was.get(p.path) })),
+      added: puts.filter(p => !copied.has(p.path)).map(p => ({ path: p.path, sha256: sha256(p.data) })),
+      deleted: removes.filter(p => copied.has(p)).map(p => ({ path: p, was: res.was.get(p) })),
+    };
+    await writeBackupInfo({ remoteFs, backupDir: undoDir, info: { ...record, status: 'running' } });
+
+    // 4. put the old copies back, take the added files off
+    const madeDirs = new Set();
+    for (const p of puts) {
+      const dest = `${root}/${p.path}`;
+      const d = posix.dirname(dest);
+      if (!madeDirs.has(d)) { await remoteFs.mkdirp(d); madeDirs.add(d); }
+      await writeLive(remoteFs, dest, { data: p.data });
+      onEvent({ type: 'restore', path: p.path, bytes: p.data.length });
+    }
+    for (const p of removes) { await remoteFs.remove(`${root}/${p}`); onEvent({ type: 'delete', path: p }); }
+    // folders the deploy made just for added files go too, once empty
+    for (const d of [...new Set(removes.map(p => posix.dirname(p)).filter(d => d !== '.'))].sort((a, b) => b.length - a.length)) {
+      for (let cur = d; cur !== '.'; cur = posix.dirname(cur)) {
+        const abs = `${root}/${cur}`;
+        if (!(await remoteFs.stat(abs)) || (await remoteFs.listDir(abs)).length) break;
+        await remoteFs.rmdir(abs);
+      }
+    }
+
+    await sweepParts();
+
+    // 5. the manifest no longer describes these paths
+    try {
+      const m = JSON.parse((await remoteFs.readFile(`${root}/${MANIFEST_NAME}`)).toString('utf8'));
+      for (const p of [...summary.put, ...summary.remove]) delete m.files[p];
+      await remoteFs.writeFile(`${root}/${MANIFEST_NAME}`, JSON.stringify(m, null, 1));
+    } catch { /* no manifest: nothing to correct */ }
+    await writeBackupInfo({ remoteFs, backupDir: undoDir, info: record });
+  } catch (err) {
+    err.undo = 'The restore stopped part way. Run the same restore again: it finishes the job.';
+    onEvent({ type: 'error', message: err.message, undo: err.undo, summary });
+    throw err;
+  }
+
+  onEvent({ type: 'done', summary });
+  return summary;
+}
+
+module.exports = { runRestore, describeBackups, chooseBackup };