shipback-sftp 0.0.0-stage → 0.2.0

package/src/mcp.js

@@ -0,0 +1,240 @@
+'use strict';
+// MCP server (stdio, JSON-RPC 2.0, one message per line) so an AI agent can deploy, check and undo.
+//
+// Safety is in what is NOT here: no mirror (deleting server files), no backup switch, no pruning of
+// backups. Every deploy is backed up, every deploy can be restored. On top of that:
+//   · deploy and restore need the planId from preview_deploy / preview_restore. If anything changed
+//     in between (a local edit, someone editing the live site), the ids differ and nothing runs.
+//   · restore refuses when a live file was edited after the run being undone, unless force is passed.
+//   · passwords never pass through the model: they come from the OS keychain (stored by the CLI or
+//     the app the first time) or SFTP_PASSWORD in the server's environment.
+const crypto = require('node:crypto');
+const path = require('node:path');
+const fs = require('node:fs/promises');
+const { loadSites } = require('./config');
+const { createCredentialStore } = require('./credentials');
+const { SftpRemoteFs } = require('./remote-fs');
+const { previewDeploy, runDeploy } = require('./deploy');
+const { runPull } = require('./pull');
+const { runRestore, describeBackups } = require('./restore');
+const { appendHistory, readHistory, recordFromSummary } = require('./history');
+
+const VERSION = require('../package.json').version;
+const PROTOCOLS = ['2025-06-18', '2025-03-26', '2024-11-05'];
+const LIST_MAX = 200;
+
+const hash = v => crypto.createHash('sha256').update(JSON.stringify(v)).digest('hex').slice(0, 16);
+const cap = list => list.length > LIST_MAX ? [...list.slice(0, LIST_MAX), `… and ${list.length - LIST_MAX} more`] : list;
+
+const SITE = { site: { type: 'string', description: 'Site name from sites.json (see list_sites)' } };
+const LOCAL = { localDir: { type: 'string', description: "Local folder to deploy from / compare with. Defaults to the site's localDir." } };
+const TOOLS = [
+  { name: 'list_sites', description: 'List the configured sites: name, host, remote root and default local folder. No passwords.',
+    inputSchema: { type: 'object', properties: {} } },
+  { name: 'preview_deploy', description: 'Show what a deploy would upload (new and changed files). Changes nothing. Returns a planId that deploy needs.',
+    inputSchema: { type: 'object', properties: { ...SITE, ...LOCAL }, required: ['site'] } },
+  { name: 'deploy', description: 'Upload the previewed plan. Every file it overwrites is backed up on the server first, and the whole deploy can be undone with restore. Never deletes server files. Refuses if the plan changed since preview_deploy.',
+    inputSchema: { type: 'object', properties: { ...SITE, ...LOCAL, planId: { type: 'string', description: 'planId from preview_deploy' } }, required: ['site', 'planId'] } },
+  { name: 'check_server_changes', description: "Before editing a site's local files: list files that are different or only on the server (someone edited the live site). Changes nothing.",
+    inputSchema: { type: 'object', properties: { ...SITE, ...LOCAL }, required: ['site'] } },
+  { name: 'pull', description: 'Download the server-side changes into the local folder, so local is the truth before editing. Local files it overwrites are backed up in <localDir>/_backup-<stamp>/. Never deletes local files.',
+    inputSchema: { type: 'object', properties: { ...SITE, ...LOCAL }, required: ['site'] } },
+  { name: 'list_backups', description: 'List the backups on the server, newest first, with what each run overwrote, added and deleted.',
+    inputSchema: { type: 'object', properties: { ...SITE }, required: ['site'] } },
+  { name: 'preview_restore', description: 'Show what restoring a backup would put back and remove, and any conflicts (live files edited after that run). Changes nothing. Returns a planId that restore needs.',
+    inputSchema: { type: 'object', properties: { ...SITE, backup: { type: 'string', description: 'Backup folder name, e.g. _backup-2026-10-18-1400. Default: the newest.' } }, required: ['site'] } },
+  { name: 'restore', description: 'Undo a deploy: put the backed-up files back and remove the files that run added. Backs up the current live files first, so the restore can itself be restored. Refuses on conflicts unless force is true; only pass force when the user has seen the conflicts and said to go ahead.',
+    inputSchema: { type: 'object', properties: { ...SITE, backup: { type: 'string', description: 'Backup folder name from preview_restore' }, planId: { type: 'string', description: 'planId from preview_restore' }, force: { type: 'boolean', description: 'Restore over files edited on the server since that run (they are backed up first)' } }, required: ['site', 'backup', 'planId'] } },
+  { name: 'history', description: 'Recent deploys, pulls and restores from this machine.',
+    inputSchema: { type: 'object', properties: { site: { type: 'string' }, limit: { type: 'number' } } } },
+];
+
+class ToolError extends Error {}
+
+/** createMcp({ sitesFile, historyFile, credentials, connect, env, now }) → { handle(message) → response | null } */
+function createMcp(opts = {}) {
+  const sitesFile = opts.sitesFile || process.env.SHIPBACK_SITES || path.join(process.cwd(), 'sites.json');
+  const historyFile = opts.historyFile || path.join(path.dirname(sitesFile), 'deploys.jsonl');
+  const env = opts.env || process.env;
+  const now = opts.now || (() => new Date());
+  let credentials = opts.credentials;
+  const store = () => credentials || (credentials = createCredentialStore().store);
+
+  async function getSite(name) {
+    if (typeof name !== 'string' || !name) throw new ToolError('Say which site: "site" is required (see list_sites)');
+    const { sites } = await loadSites(sitesFile);
+    const s = sites.find(x => x.name === name);
+    if (!s) throw new ToolError(`Unknown site "${name}". Known: ${sites.map(x => x.name).join(', ') || '(none — add one to ' + sitesFile + ')'}`);
+    return s;
+  }
+  async function connect(site) {
+    if (opts.connect) return opts.connect(site);
+    const o = { host: site.host, port: site.port, username: site.username };
+    if (site.privateKeyPath) o.privateKey = await fs.readFile(site.privateKeyPath);
+    else {
+      o.password = env.SFTP_PASSWORD ?? await store().get(site.name);
+      if (o.password == null) throw new ToolError(`No stored password for "${site.name}". Ask the user to run this once in a terminal, which stores it in the OS keychain: shipback ${site.name} --backups (or node bin/cli.js ${site.name} --backups from a clone)`);
+    }
+    return SftpRemoteFs.connect(o);
+  }
+  async function withSite(args, fn) {
+    const site = await getSite(args.site);
+    const rfs = await connect(site);
+    try { return await fn(site, rfs); } finally { await rfs.close(); }
+  }
+  const record = rec => appendHistory(historyFile, recordFromSummary({ trigger: 'mcp', ...rec })).catch(() => {});
+  const localOf = (site, args) => {
+    const d = args.localDir || site.localDir;
+    if (!d) throw new ToolError(`No local folder: pass "localDir" or set localDir for "${site.name}" in sites.json`);
+    return d;
+  };
+  const deployPlanId = (site, localDir, local, plan) => {
+    const sha = new Map(local.map(f => [f.path, f.sha256]));
+    return hash({ site: site.name, localDir, root: site.remoteRoot, upload: plan.upload.map(u => [u.path, u.reason, sha.get(u.path)]) });
+  };
+  const restorePlanId = (site, s) => hash({ site: site.name, root: site.remoteRoot, backup: s.backup, put: s.put, remove: s.remove, conflicts: s.conflicts });
+
+  const tools = {
+    async list_sites() {
+      const { sites } = await loadSites(sitesFile);
+      return { sitesFile, sites: sites.map(s => ({ name: s.name, host: s.host, port: s.port, remoteRoot: s.remoteRoot, localDir: s.localDir })) };
+    },
+
+    preview_deploy: args => withSite(args, async (site, rfs) => {
+      const localDir = localOf(site, args);
+      const { local, plan } = await previewDeploy({ localDir, remoteRoot: site.remoteRoot, remoteFs: rfs, ignore: site.ignore });
+      return {
+        planId: deployPlanId(site, localDir, local, plan), site: site.name, from: localDir, to: `${site.host}:${site.remoteRoot}`,
+        upload: cap(plan.upload.map(u => `${u.reason === 'new' ? '+' : '~'} ${u.path}`)), uploadBytes: plan.uploadBytes,
+        unchanged: plan.skip.length, onlyOnServer: plan.extra.length,
+        note: plan.upload.length ? `Files marked ~ will be backed up on the server before they are replaced. Nothing is deleted. Call deploy with this planId to go ahead.` : 'Nothing to upload.',
+      };
+    }),
+
+    deploy: args => withSite(args, async (site, rfs) => {
+      const localDir = localOf(site, args);
+      const { local, plan } = await previewDeploy({ localDir, remoteRoot: site.remoteRoot, remoteFs: rfs, ignore: site.ignore });
+      if (deployPlanId(site, localDir, local, plan) !== args.planId) throw new ToolError('The plan changed since preview_deploy (a local file or the server changed). Nothing was uploaded. Call preview_deploy again and check the new plan.');
+      if (!plan.upload.length) return { uploaded: [], note: 'Nothing to upload.' };
+      const startedAt = new Date().toISOString();
+      try {
+        const s = await runDeploy({ localDir, remoteRoot: site.remoteRoot, remoteFs: rfs, backup: true, mirror: false, ignore: site.ignore, now: now() });
+        await record({ action: 'deploy', site: site.name, localDir, remoteDir: site.remoteRoot, startedAt, summary: s });
+        const backup = s.backupDir && s.backupDir.split('/').pop();
+        return { uploaded: cap(s.uploaded), bytes: s.bytes, backedUp: cap(s.backedUp), backup, undo: backup ? `To undo this deploy: preview_restore with backup "${backup}", then restore.` : undefined };
+      } catch (e) { await record({ action: 'deploy', site: site.name, localDir, remoteDir: site.remoteRoot, startedAt, error: e.message }); throw e; }
+    }),
+
+    check_server_changes: args => withSite(args, async (site, rfs) => {
+      const localDir = localOf(site, args);
+      const s = await runPull({ localDir, remoteRoot: site.remoteRoot, remoteFs: rfs, dryRun: true, ignore: site.ignore });
+      const changed = s.plan.download;
+      return {
+        site: site.name, serverAhead: changed.length > 0,
+        differentOnServer: cap(changed.filter(d => d.reason === 'changed').map(d => d.path)),
+        onlyOnServer: cap(changed.filter(d => d.reason === 'new').map(d => d.path)),
+        onlyLocal: s.plan.extra.length, same: s.plan.skip.length,
+        note: changed.length ? 'The server has files the local folder does not match. If those are live edits to keep, call pull before editing.' : 'Local folder matches the server.',
+      };
+    }),
+
+    pull: args => withSite(args, async (site, rfs) => {
+      const localDir = localOf(site, args);
+      const startedAt = new Date().toISOString();
+      const s = await runPull({ localDir, remoteRoot: site.remoteRoot, remoteFs: rfs, backup: true, mirror: false, ignore: site.ignore, now: now() });
+      await record({ action: 'pull', site: site.name, localDir, remoteDir: site.remoteRoot, startedAt, summary: s });
+      return { downloaded: cap(s.downloaded), bytes: s.bytes, localBackup: s.backupDir || undefined };
+    }),
+
+    list_backups: args => withSite(args, async (site, rfs) => ({ site: site.name, backups: await describeBackups({ remoteRoot: site.remoteRoot, remoteFs: rfs }) })),
+
+    preview_restore: args => withSite(args, async (site, rfs) => {
+      const s = await runRestore({ remoteRoot: site.remoteRoot, remoteFs: rfs, name: args.backup, dryRun: true });
+      return {
+        planId: restorePlanId(site, s), site: site.name, backup: s.backup, undoes: s.action, legacy: s.legacy || undefined,
+        putBack: cap(s.put), remove: cap(s.remove), alreadyRight: s.same.length, conflicts: s.conflicts,
+        resumes: s.resumed || undefined,
+        note: s.stoppedEarly ? 'That run was cut off while saving its backups, before it changed any live file. There is nothing to undo.'
+          : s.conflicts.length ? 'Some live files were changed after that run. Show the user the conflicts; restore refuses them unless force is true.'
+          : s.put.length || s.remove.length ? 'Call restore with this backup and planId to go ahead. The current live files are backed up first.' : 'The site already matches this backup.',
+      };
+    }),
+
+    restore: args => withSite(args, async (site, rfs) => {
+      if (typeof args.backup !== 'string' || !args.backup) throw new ToolError('Say which backup: "backup" from preview_restore');
+      const dry = await runRestore({ remoteRoot: site.remoteRoot, remoteFs: rfs, name: args.backup, dryRun: true });
+      if (restorePlanId(site, dry) !== args.planId) throw new ToolError('The restore plan changed since preview_restore (the live site changed). Nothing was restored. Call preview_restore again.');
+      const startedAt = new Date().toISOString();
+      const s = await runRestore({ remoteRoot: site.remoteRoot, remoteFs: rfs, name: args.backup, force: args.force === true, now: now() });
+      await record({ action: 'restore', site: site.name, remoteDir: site.remoteRoot, startedAt, summary: s });
+      if (s.refused) throw new ToolError(`Refused: ${s.conflicts.length} live file(s) changed after that run, so nothing was restored: ${s.conflicts.map(c => `${c.path} (${c.why})`).join('; ')}. Only pass force: true if the user says so.`);
+      const undo = s.undoBackupDir && s.undoBackupDir.split('/').pop();
+      return { putBack: cap(s.put), removed: cap(s.remove), undo: undo ? `To undo this restore: preview_restore with backup "${undo}", then restore.` : undefined };
+    }),
+
+    async history(args) {
+      return { history: await readHistory(historyFile, { site: args.site || undefined, limit: Math.min(Number(args.limit) || 20, 100) }) };
+    },
+  };
+
+  async function callTool(name, args) {
+    if (!Object.hasOwn(tools, name)) return { content: [{ type: 'text', text: `Unknown tool "${name}"` }], isError: true };
+    try {
+      const out = await tools[name](args || {});
+      return { content: [{ type: 'text', text: JSON.stringify(out, null, 2) }] };
+    } catch (e) {
+      return { content: [{ type: 'text', text: e.undo ? `${e.message}
+${e.undo} Call preview_restore to see it.` : e.message }], isError: true };
+    }
+  }
+
+  async function handle(msg) {
+    const reply = result => ({ jsonrpc: '2.0', id: msg.id, result });
+    const fail = (code, message) => ({ jsonrpc: '2.0', id: msg.id ?? null, error: { code, message } });
+    if (!msg || msg.jsonrpc !== '2.0' || typeof msg.method !== 'string') return fail(-32600, 'Invalid request');
+    const isNotification = msg.id === undefined;
+    switch (msg.method) {
+      case 'initialize': {
+        const asked = msg.params && msg.params.protocolVersion;
+        return reply({
+          protocolVersion: PROTOCOLS.includes(asked) ? asked : PROTOCOLS[0],
+          capabilities: { tools: {} },
+          serverInfo: { name: 'shipback-sftp', version: VERSION },
+          instructions: 'Deploy to shared hosting over SFTP. preview_deploy then deploy; every deploy is backed up and can be undone with preview_restore then restore. Before editing a site, check_server_changes (and pull if the server is ahead).',
+        });
+      }
+      case 'ping': return reply({});
+      case 'tools/list': return reply({ tools: TOOLS });
+      case 'tools/call': return reply(await callTool(msg.params && msg.params.name, msg.params && msg.params.arguments));
+      default:
+        if (isNotification) return null; // notifications/initialized and friends need no answer
+        return fail(-32601, `Method not found: ${msg.method}`);
+    }
+  }
+
+  return { handle, TOOLS };
+}
+
+/** Wire createMcp to stdin/stdout, newline-delimited JSON. Logs go to stderr only. */
+function serveStdio(mcp, { input = process.stdin, output = process.stdout } = {}) {
+  let buf = '';
+  let chain = Promise.resolve();
+  input.setEncoding('utf8');
+  input.on('data', chunk => {
+    buf += chunk;
+    let i;
+    while ((i = buf.indexOf('\n')) >= 0) {
+      const line = buf.slice(0, i).trim(); buf = buf.slice(i + 1);
+      if (!line) continue;
+      chain = chain.then(async () => {
+        let msg;
+        try { msg = JSON.parse(line); } catch { output.write(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } }) + '\n'); return; }
+        const res = await mcp.handle(msg).catch(e => ({ jsonrpc: '2.0', id: msg.id ?? null, error: { code: -32603, message: e.message } }));
+        if (res) output.write(JSON.stringify(res) + '\n');
+      });
+    }
+  });
+  return new Promise(resolve => input.on('end', () => chain.then(resolve)));
+}
+
+module.exports = { createMcp, serveStdio, TOOLS };

package/src/prune.js

@@ -0,0 +1,105 @@
+'use strict';
+// Prune: remove _backup-<stamp>/ folders the deploys left on the server.
+//
+// Safety rule — a backup folder is only removed when every file in it still exists
+// byte-for-byte somewhere else on the server: live at the same path under the root, or
+// at the same path inside one of the backups being kept. A folder holding the only copy
+// of anything is refused (listed in summary.refused with the unique paths) unless
+// { force: true } is passed. Nothing is ever removed outside a _backup-* folder.
+//
+// runPrune({ remoteRoot, remoteFs, names?, keep?, dryRun, force, onEvent })
+//   names: exact folder names to remove ('_backup-2026-09-24-2352', …)
+//   keep:  or, keep the newest N backups and remove the rest (stamps sort by name)
+// → { dryRun, backups, targets, pruned: [{ name, files, bytes }], refused: [{ name, unique }], deleted, bytes }
+const crypto = require('node:crypto');
+const { BACKUP_PREFIX } = require('./diff');
+const { withLock } = require('./lock');
+const { BACKUP_INFO } = require('./backup');
+
+const sha256 = buf => crypto.createHash('sha256').update(buf).digest('hex');
+
+async function listBackups(remoteFs, root) {
+  const st = await remoteFs.stat(root);
+  if (!st || !st.isDir) throw new Error(`Remote folder not found: ${root}`);
+  return (await remoteFs.listDir(root)).filter(e => e.type === 'dir' && e.name.startsWith(BACKUP_PREFIX)).map(e => e.name).sort();
+}
+
+/** All directories under dir (absolute paths), deepest last. */
+async function walkDirs(remoteFs, dir) {
+  const out = [];
+  const walk = async abs => {
+    for (const e of await remoteFs.listDir(abs)) if (e.type === 'dir') { const p = abs + '/' + e.name; out.push(p); await walk(p); }
+  };
+  await walk(dir);
+  return out;
+}
+
+function chooseTargets(backups, { names, keep }) {
+  if (Array.isArray(names) && names.length) {
+    const targets = [];
+    for (const n of names) {
+      if (typeof n !== 'string' || !n.startsWith(BACKUP_PREFIX) || n.includes('/') || n.includes('..')) throw new Error(`Not a backup folder name: "${n}" (must be ${BACKUP_PREFIX}<stamp>)`);
+      if (!backups.includes(n)) throw new Error(`No such backup on the server: ${n}`);
+      if (!targets.includes(n)) targets.push(n);
+    }
+    return targets;
+  }
+  if (Number.isInteger(keep) && keep >= 0) return backups.slice(0, Math.max(0, backups.length - keep)); // sorted ascending ⇒ oldest first
+  throw new Error('Say which backups to prune: "names": ["_backup-…"] or "keep": N (newest N stay)');
+}
+
+function runPrune(opts) {
+  if (opts.dryRun) return pruneNow(opts);
+  return withLock({ remoteFs: opts.remoteFs, root: opts.remoteRoot, action: 'prune', onEvent: opts.onEvent }, () => pruneNow(opts));
+}
+
+async function pruneNow({ remoteRoot, remoteFs, names, keep, dryRun = false, force = false, onEvent = () => {} }) {
+  const root = remoteRoot.replace(/\/$/, '');
+  onEvent({ type: 'scan', side: 'remote', dir: root });
+  const backups = await listBackups(remoteFs, root);
+  const targets = chooseTargets(backups, { names, keep });
+  const kept = backups.filter(b => !targets.includes(b));
+  const summary = { dryRun, backups, targets, kept, pruned: [], refused: [], deleted: 0, bytes: 0 };
+  onEvent({ type: 'prune-plan', backups, targets, kept });
+
+  const hashCache = new Map();
+  const hashOf = async abs => {
+    if (hashCache.has(abs)) return hashCache.get(abs);
+    let h = null;
+    try { h = sha256(await remoteFs.readFile(abs)); } catch (e) { if (e.code !== 'ENOENT' && !/No such file/i.test(e.message)) throw e; }
+    hashCache.set(abs, h);
+    return h;
+  };
+
+  for (const name of targets) {
+    const dir = `${root}/${name}`;
+    const files = await remoteFs.listRecursive(dir);
+    const unique = [];
+    for (const f of files) {
+      if (f.path === BACKUP_INFO) continue; // the folder's own record, not a copy of a site file
+      const h = await hashOf(`${dir}/${f.path}`);
+      let twin = (await hashOf(`${root}/${f.path}`)) === h;
+      for (const k of kept) { if (twin) break; twin = (await hashOf(`${root}/${k}/${f.path}`)) === h; }
+      if (!twin) unique.push(f.path);
+    }
+    const bytes = files.reduce((s, f) => s + f.size, 0);
+    onEvent({ type: 'prune-check', name, files: files.length, bytes, unique: unique.length });
+    if (unique.length && !force) {
+      summary.refused.push({ name, unique });
+      onEvent({ type: 'refuse', name, unique });
+      continue;
+    }
+    if (!dryRun) {
+      for (const f of files) { await remoteFs.remove(`${dir}/${f.path}`); onEvent({ type: 'delete', path: `${name}/${f.path}` }); }
+      const dirs = await walkDirs(remoteFs, dir);
+      for (const d of dirs.reverse()) { await remoteFs.rmdir(d); onEvent({ type: 'rmdir', path: d.slice(root.length + 1) }); }
+      await remoteFs.rmdir(dir); onEvent({ type: 'rmdir', path: name });
+    }
+    summary.pruned.push({ name, files: files.length, bytes, forced: unique.length > 0 });
+    summary.deleted += files.length; summary.bytes += bytes;
+  }
+  onEvent({ type: 'done', summary });
+  return summary;
+}
+
+module.exports = { runPrune, listBackups, chooseTargets };

package/src/pull.js

@@ -0,0 +1,131 @@
+'use strict';
+// Pull: server → local. Downloads new/changed files into the local folder, backing up anything it
+// overwrites into <localDir>/_backup-<stamp>/. Never writes to the server.
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { scanLocal, loadIgnore, dropIgnored } = require('./manifest');
+const { MANIFEST_NAME, BACKUP_PREFIX } = require('./diff');
+const { makeStamp } = require('./backup');
+
+const isBackupDir = name => name.startsWith(BACKUP_PREFIX);
+const VERIFY_MAX = 8 * 1024 * 1024;
+
+async function readRemoteManifest(remoteFs, root) {
+  try { return JSON.parse((await remoteFs.readFile(`${root}/${MANIFEST_NAME}`)).toString('utf8')); } catch { return null; }
+}
+
+/**
+ * planPull({ localFiles, remoteListing, remoteManifest, mirror })
+ * → { download: [{ path, size, reason }], verify: [{ path, size, localSha }], skip: [path], extra: [path], delete: [path] }
+ */
+function planPull({ localFiles, remoteListing, remoteManifest, mirror = false }) {
+  const local = new Map(localFiles.map(f => [f.path, f]));
+  const manifest = (remoteManifest && remoteManifest.files) || {};
+  const deployedAt = remoteManifest && remoteManifest.deployedAt ? Date.parse(remoteManifest.deployedAt) : NaN;
+  const download = [], verify = [], skip = [];
+  const remoteSet = new Set();
+  for (const r of [...remoteListing].sort((a, b) => a.path.localeCompare(b.path))) {
+    if (r.path === MANIFEST_NAME) continue;
+    remoteSet.add(r.path);
+    const l = local.get(r.path);
+    if (!l) { download.push({ path: r.path, size: r.size, reason: 'new' }); continue; }
+    if (l.size !== r.size) { download.push({ path: r.path, size: r.size, reason: 'changed' }); continue; }
+    const m = manifest[r.path];
+    // We deployed this exact content and the server copy hasn't been touched since → unchanged without reading it.
+    const trusted = m && m.sha256 === l.sha256 && Number.isFinite(deployedAt) && r.mtime <= deployedAt + 60_000;
+    if (trusted) skip.push(r.path); else verify.push({ path: r.path, size: r.size, localSha: l.sha256 });
+  }
+  const extra = [...local.keys()].filter(p => !remoteSet.has(p)).sort();
+  return { download, verify, skip, extra, delete: mirror ? [...extra] : [] };
+}
+
+async function removeEmptyDirs(dir, stopAt) {
+  // walk up from dir removing empty folders until stopAt
+  let cur = dir;
+  while (cur.startsWith(stopAt) && cur !== stopAt) {
+    try { const ents = await fs.readdir(cur); if (ents.length) break; await fs.rmdir(cur); } catch { break; }
+    cur = path.dirname(cur);
+  }
+}
+
+/**
+ * runPull({ localDir, remoteRoot, remoteFs, dryRun, backup, mirror, ignore, now, onEvent })
+ * → { dryRun, plan, downloaded, backedUp, backupDir, deleted, bytes }
+ */
+async function runPull({ localDir, remoteRoot, remoteFs, dryRun = false, backup = true, mirror = false, ignore, now = new Date(), onEvent = () => {} }) {
+  const root = remoteRoot.replace(/\/$/, '');
+  const summary = { dryRun, plan: null, downloaded: [], backedUp: [], backupDir: null, deleted: [], bytes: 0 };
+  try {
+    onEvent({ type: 'scan', side: 'remote', dir: root });
+    const rootStat = await remoteFs.stat(root);
+    if (!rootStat) throw new Error(`Remote folder not found on server: ${root}`);
+    if (!rootStat.isDir) throw new Error(`Remote path is a file, not a folder: ${root}`);
+    const fullListing = await remoteFs.listRecursive(root, { skipDir: isBackupDir });
+    const remoteManifest = await readRemoteManifest(remoteFs, root);
+    onEvent({ type: 'scan', side: 'local', dir: localDir });
+    await fs.mkdir(localDir, { recursive: true });
+    const localFiles = await scanLocal(localDir, { ignore });
+    // ignored paths are hands-off on the server too: never offered as "new", never pulled over local copies
+    const remoteListing = dropIgnored(fullListing, await loadIgnore(localDir, ignore));
+    const plan = planPull({ localFiles, remoteListing, remoteManifest, mirror });
+
+    // settle same-size files by reading the server copy (once; content is kept so it isn't fetched twice)
+    const fetched = new Map();
+    for (const v of plan.verify) {
+      if (v.size > VERIFY_MAX) { plan.skip.push(v.path); continue; }
+      onEvent({ type: 'verify', path: v.path });
+      const data = await remoteFs.readFile(`${root}/${v.path}`);
+      if (crypto.createHash('sha256').update(data).digest('hex') === v.localSha) plan.skip.push(v.path);
+      else { plan.download.push({ path: v.path, size: v.size, reason: 'changed' }); fetched.set(v.path, data); }
+    }
+    plan.verify = []; plan.download.sort((a, b) => a.path.localeCompare(b.path)); plan.skip.sort();
+    plan.downloadBytes = plan.download.reduce((n, d) => n + d.size, 0);
+    summary.plan = plan;
+    onEvent({ type: 'plan', plan, localCount: localFiles.length, remoteCount: remoteListing.length, direction: 'pull' });
+    if (dryRun) { onEvent({ type: 'done', summary }); return summary; }
+
+    // 1. local backup of files about to be overwritten or deleted
+    const stamp = makeStamp(now);
+    const backupDir = path.join(localDir, `${BACKUP_PREFIX}${stamp}`);
+    if (backup) {
+      const targets = [...plan.download.filter(d => d.reason === 'changed').map(d => d.path), ...plan.delete];
+      for (const rel of targets) {
+        const src = path.join(localDir, ...rel.split('/'));
+        const dest = path.join(backupDir, ...rel.split('/'));
+        await fs.mkdir(path.dirname(dest), { recursive: true });
+        await fs.copyFile(src, dest);
+        summary.backedUp.push(rel);
+        onEvent({ type: 'backup', path: rel, to: dest });
+      }
+      if (summary.backedUp.length) summary.backupDir = backupDir;
+    }
+
+    // 2. download
+    let i = 0;
+    for (const d of plan.download) {
+      const data = fetched.get(d.path) || await remoteFs.readFile(`${root}/${d.path}`);
+      const dest = path.join(localDir, ...d.path.split('/'));
+      await fs.mkdir(path.dirname(dest), { recursive: true });
+      await fs.writeFile(dest, data);
+      summary.downloaded.push(d.path); summary.bytes += data.length;
+      onEvent({ type: 'download', path: d.path, bytes: data.length, reason: d.reason, done: ++i, total: plan.download.length });
+    }
+
+    // 3. mirror deletes (local)
+    for (const rel of plan.delete) {
+      const p = path.join(localDir, ...rel.split('/'));
+      await fs.rm(p, { force: true });
+      await removeEmptyDirs(path.dirname(p), localDir);
+      summary.deleted.push(rel);
+      onEvent({ type: 'delete', path: rel, side: 'local' });
+    }
+    onEvent({ type: 'done', summary });
+    return summary;
+  } catch (err) {
+    onEvent({ type: 'error', message: err.message, summary });
+    throw err;
+  }
+}
+
+module.exports = { runPull, planPull };

package/src/queue.js

@@ -0,0 +1,107 @@
+'use strict';
+// Drop-box queue: another process (an AI agent with no shell, a script, you) writes
+//   queue/<name>.request.json   { action: "deploy"|"pull"|"preview", site, localDir?, remoteDir?, dryRun?, mirror?, backup?, note? }
+//                               { action: "prune", site, remoteDir?, names?: ["_backup-…"], keep?: N, dryRun?, force?, note? }
+//                               { action: "restore", site, remoteDir?, name?: "_backup-…" | "latest", dryRun?, force?, note? }
+//                               { action: "backups", site, remoteDir? }   (list the backups and what each holds)
+// while the app is running. The watcher runs it and writes
+//   queue/<name>.result.json    { ok, action, site, startedAt, finishedAt, summary | error }
+//   queue/<name>.log.txt        the same lines the app's log panel shows
+// and renames the request to <name>.request.done.json so it is never run twice.
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+const QUEUE_SUFFIX = '.request.json';
+const ACTIONS = new Set(['deploy', 'pull', 'preview', 'prune', 'restore', 'backups']);
+const SITE_ACTIONS = ACTIONS;
+
+
+function fmtEvent(ev) {
+  const t = new Date().toLocaleTimeString();
+  switch (ev.type) {
+    case 'scan': return `${t}  scanning ${ev.side}: ${ev.dir}`;
+    case 'verify': return `${t}  checking ${ev.path}`;
+    case 'plan': { const p = ev.plan; const n = (p.upload || p.download || []).length; return `${t}  plan: ${n} to ${p.upload ? 'upload' : 'download'}, ${p.skip.length} unchanged, ${p.extra.length} extra, ${p.delete.length} to delete`; }
+    case 'mkdir': return `${t}  created ${ev.path}`;
+    case 'backup': return `${t}  backup ${ev.path} -> ${ev.to}`;
+    case 'upload': return `${t}  upload ${ev.path} ${ev.done}/${ev.total}`;
+    case 'download': return `${t}  download ${ev.path} ${ev.done}/${ev.total}`;
+    case 'delete': return `${t}  delete ${ev.path}`;
+    case 'rmdir': return `${t}  rmdir ${ev.path}`;
+    case 'prune-plan': return `${t}  backups on server: ${ev.backups.length} — prune ${ev.targets.length} (${ev.targets.join(', ') || 'none'}), keep ${ev.kept.length}`;
+    case 'prune-check': return `${t}  ${ev.name}: ${ev.files} files, ${ev.bytes} bytes, ${ev.unique} without a copy elsewhere`;
+    case 'refuse': return `${t}  REFUSED ${ev.name}: only copy of ${ev.unique.slice(0, 5).join(', ')}${ev.unique.length > 5 ? ` and ${ev.unique.length - 5} more` : ''} — pass "force": true to remove anyway`;
+    case 'restore-plan': return `${t}  restore ${ev.backup}${ev.legacy ? ' (no .backup.json: files only)' : ''}: ${ev.put.length} to put back, ${ev.remove.length} to remove, ${ev.same} already right, ${ev.conflicts} conflicts`;
+    case 'restore': return `${t}  put back ${ev.path}`;
+    case 'conflict': return `${t}  CONFLICT ${ev.path}: ${ev.why}`;
+    case 'manifest': return `${t}  wrote ${ev.path}`;
+    case 'done': return `${t}  done`;
+    case 'error': return `${t}  ERROR ${ev.message}${ev.undo ? ` ${ev.undo}` : ''}`;
+    default: return `${t}  ${ev.type}`;
+  }
+}
+
+/**
+ * createQueueWatcher({ queueDir, runJob, pollMs, log })
+ *   runJob({ request, name, onEvent }) → summary (throws on failure)
+ * → { start(), stop(), queueDir }
+ */
+function createQueueWatcher({ queueDir, runJob, pollMs = 1500, log = console.log }) {
+  let timer = null, busy = false, stopped = false;
+  const retries = new Map(); // name → consecutive parse failures
+
+  async function scan() {
+    if (busy || stopped) return;
+    busy = true;
+    try {
+      let names;
+      try { names = (await fs.readdir(queueDir)).filter(n => n.endsWith(QUEUE_SUFFIX)).sort(); } catch { names = []; }
+      for (const file of names) {
+        if (stopped) break;
+        const name = file.slice(0, -QUEUE_SUFFIX.length);
+        const reqPath = path.join(queueDir, file);
+        let request;
+        try { request = JSON.parse(await fs.readFile(reqPath, 'utf8')); }
+        catch (e) {
+          const n = (retries.get(name) || 0) + 1; retries.set(name, n);
+          if (n < 8) continue; // probably still being written — try again next round
+          await finish(name, reqPath, { ok: false, error: `request.json is not valid JSON: ${e.message}`, startedAt: new Date().toISOString() }, []);
+          retries.delete(name); continue;
+        }
+        retries.delete(name);
+        await runOne(name, reqPath, request);
+      }
+    } finally { busy = false; }
+  }
+
+  async function runOne(name, reqPath, request) {
+    const startedAt = new Date().toISOString();
+    const lines = [];
+    const onEvent = ev => lines.push(fmtEvent(ev));
+    log(`[queue] ${name}: ${request.action} ${request.site || ''}`);
+    let result;
+    if (!ACTIONS.has(request.action)) result = { ok: false, error: `Unknown action "${request.action}" — use deploy, pull, preview, prune, restore or backups` };
+    else if (SITE_ACTIONS.has(request.action) && (!request.site || typeof request.site !== 'string')) result = { ok: false, error: 'Request is missing "site"' };
+    else {
+      try { const summary = await runJob({ request, name, onEvent }); result = { ok: true, summary }; }
+      catch (e) { result = { ok: false, error: e.message }; lines.push(`ERROR ${e.message}`); }
+    }
+    await finish(name, reqPath, { ...result, action: request.action, site: request.site, note: request.note, startedAt }, lines);
+    log(`[queue] ${name}: ${result.ok ? 'ok' : 'FAILED — ' + result.error}`);
+  }
+
+  async function finish(name, reqPath, result, lines) {
+    result.finishedAt = new Date().toISOString();
+    await fs.writeFile(path.join(queueDir, name + '.log.txt'), lines.join('\n') + '\n');
+    await fs.writeFile(path.join(queueDir, name + '.result.json'), JSON.stringify(result, null, 2) + '\n');
+    await fs.rename(reqPath, path.join(queueDir, name + '.request.done.json')).catch(() => {});
+  }
+
+  return {
+    queueDir,
+    async start() { await fs.mkdir(queueDir, { recursive: true }); stopped = false; timer = setInterval(scan, pollMs); scan(); },
+    async stop() { stopped = true; if (timer) clearInterval(timer); timer = null; while (busy) await new Promise(r => setTimeout(r, 20)); },
+  };
+}
+
+module.exports = { createQueueWatcher, QUEUE_SUFFIX, ACTIONS, SITE_ACTIONS };