shipback-sftp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aldo Hushi
+
+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.

package/README.md

@@ -1,3 +1,212 @@
-# Temporary Holding Version
+# Shipback SFTP
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![test](https://github.com/aldohushi1-stack/shipback-sftp/actions/workflows/test.yml/badge.svg)](https://github.com/aldohushi1-stack/shipback-sftp/actions/workflows/test.yml)
+
+**Let the agent deploy. Keep the undo.**
+
+It's late, and the agent says "Deployed ✓". Then the client's contact form is gone. The agent overwrote a
+file someone had fixed by hand in cPanel last week, and shared hosting has no `git revert`.
+
+Shipback deploys a folder to any SFTP host: cPanel, Plesk, DirectAdmin, a plain VPS. Every deploy
+can be undone with one command. You can run it yourself, script it, or hand it to Claude Code, Cursor or
+any MCP client.
+
+- **Backup before every overwrite.** The server's copy of each file a deploy replaces is saved into
+  `_backup-<time>/` on the server, before the upload starts.
+- **One-command undo.** `--restore` puts those files back and removes the files that deploy added.
+- **It won't undo over a live edit.** If someone changed a file on the server after the deploy, restore
+  stops and names the file. Nothing is touched unless you pass `--force`, and even then the edited copy is
+  backed up first.
+- **Restores can be undone too.** A restore backs up what it replaces, the same way a deploy does.
+- **Safe for agents.** The MCP server has no switch to delete server files or skip the backup. A deploy
+  only runs the exact plan the agent previewed: if a file changed in between, it refuses.
+- **Spots the drift.** `--pull --dry-run` shows what changed on the server since your last deploy, so
+  edits made live in cPanel don't get overwritten by accident.
+
+No git or SSH shell is needed on the server, just SFTP. It needs Node 18+. The tests run on Windows, macOS
+and Linux with Node 18, 20 and 22 on every push. Passwords are kept in the OS keychain and never
+pass through the model.
+
+**It has run in production.** The deploy engine underneath has shipped [aldo.today](https://aldo.today) 235 times
+since September 2026 (2,907 files to a cPanel host). Restore and the MCP server are new in 0.1.
+
+## Quick start
+
+```bash
+git clone https://github.com/aldohushi1-stack/shipback-sftp.git
+cd shipback-sftp
+npm install
+cp sites.example.json sites.json      # then edit it
+node bin/cli.js mysite --dry-run      # see the plan; asks for the password once and stores it
+node bin/cli.js mysite                # deploy
+node bin/cli.js mysite --restore      # changed your mind? undo it
+```
+
+`npm link` in the folder installs it as the `shipback` and `shipback-mcp` commands, so `node bin/cli.js mysite`
+becomes `shipback mysite`.
+
+`sites.json`, one entry per site:
+
+```json
+{
+  "sites": [
+    {
+      "name": "mysite",
+      "host": "server123.example-host.com",
+      "port": 22,
+      "username": "cpaneluser",
+      "remoteRoot": "/home/cpaneluser/public_html",
+      "localDir": "/Users/you/sites/mysite",
+      "ignore": ["drafts/", "*.psd"]
+    }
+  ]
+}
+```
+
+Many shared hosts run SFTP on their own port rather than 22 (check *SSH Access* in your control panel),
+and some only accept connections from allow-listed IPs. If a connection times out, check those two
+first. Use `"privateKeyPath"` instead of a password if your host has your key.
+
+## Commands
+
+```bash
+node bin/cli.js <site> --dry-run                 # what a deploy would upload
+node bin/cli.js <site>                           # deploy: backup, upload, record
+node bin/cli.js <site> --local <folder>          # deploy a different folder than localDir
+node bin/cli.js <site> --pull --dry-run          # what changed on the server since the last deploy?
+node bin/cli.js <site> --pull                    # bring those changes down (local copies backed up first)
+node bin/cli.js <site> --backups                 # list backups: what each run overwrote, added, deleted
+node bin/cli.js <site> --restore --dry-run       # what an undo of the latest deploy would do
+node bin/cli.js <site> --restore [<backup>]      # undo it (or name an older _backup-… folder)
+node bin/cli.js <site> --prune --keep 10         # tidy old backups; refuses any holding the only copy of a file
+node bin/cli.js --history [site]                 # what went up, when, from where
+```
+
+Add `--json` to any command for machine-readable output. A refused restore exits with code 4.
+
+`--mirror` (delete server files that aren't in the local folder) and `--no-backup` exist for humans who
+know they want them. The agent tools don't offer them, and the [guard hook](#claude-code-guard-hook)
+blocks Claude from typing them.
+
+## How the undo works
+
+Each deploy writes `_backup-YYYY-MM-DD-HHMM/` in the remote root. It holds:
+
+- the server's copy of every file the deploy **overwrote** or **deleted**
+- `.backup.json`, a record of what the deploy **added**, and a SHA-256 of every file it left on the server
+
+`--restore` reads that record and checks each live file first:
+
+| Live file now | Restore does |
+| --- | --- |
+| exactly what the deploy uploaded | puts the old copy back (or removes it, if the deploy added it) |
+| already the old copy | nothing; it counts as already right |
+| different from both | **conflict**: stops, names the file, changes nothing (`--force` overrides) |
+
+Before writing anything, restore saves the current live files into a new `_backup-…` folder with its own
+record, so `--restore` on that folder takes you forward again. It also clears the restored paths from
+`.deploy-manifest.json`, so the next deploy compares them by content instead of trusting stale hashes.
+
+Backup folders are skipped by deploys and pulls, and are never deleted except by `--prune`.
+
+## Use it from an AI agent (MCP)
+
+`bin/mcp.js` is an MCP server over stdio.
+
+**Claude Code**
+
+```bash
+claude mcp add shipback-sftp -- node /path/to/shipback-sftp/bin/mcp.js --sites /path/to/sites.json
+```
+
+**Cursor, Claude Desktop, and others** (`mcp.json` / `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "shipback-sftp": {
+      "command": "node",
+      "args": ["/path/to/shipback-sftp/bin/mcp.js", "--sites", "/path/to/sites.json"]
+    }
+  }
+}
+```
+
+Run any CLI command for a site once first (for example `node bin/cli.js mysite --backups`). That stores
+the password in the OS keychain, where the MCP server reads it. The model never sees it. For CI you can set
+`SFTP_PASSWORD` in the server's environment instead.
+
+| Tool | Does |
+| --- | --- |
+| `list_sites` | the configured sites (no passwords) |
+| `preview_deploy` | what would upload; returns a `planId` |
+| `deploy` | uploads that plan; refuses if anything changed since the preview |
+| `check_server_changes` | files edited or added on the live server since the last deploy |
+| `pull` | brings those down into the local folder (local copies backed up) |
+| `list_backups` | backups, newest first, with what each run changed |
+| `preview_restore` | what an undo would put back and remove, plus any conflicts; returns a `planId` |
+| `restore` | runs that undo; refuses on conflicts unless `force` |
+| `history` | recent deploys, pulls and restores |
+
+What the tools leave out is deliberate: there is no mirror/delete, no way to skip the backup, and no
+pruning of backups.
+
+## Agents without a shell: the drop-box queue
+
+Some agent setups can write files but can't run commands. While the local app is running
+(`npm start`, or `start.bat` on Windows), anything that can write a file can queue a job:
+
+```
+queue/<name>.request.json   { "action": "deploy", "site": "mysite", "dryRun": true, "note": "new homepage" }
+queue/<name>.result.json    ← written when it finishes, with a .log.txt beside it
+```
+
+Actions: `deploy`, `preview`, `pull`, `restore`, `backups`, `prune`.
+
+## The local app
+
+`npm start` opens a small UI on `http://127.0.0.1:4646`: add sites, preview, deploy, pull, drag in
+one-off uploads, browse the server, and see history. It only answers requests from your own machine.
+
+## Claude Code guard hook
+
+If Claude also runs the CLI directly, add `bin/claude-guard.js` as a PreToolUse hook. It blocks
+`--mirror` and `--no-backup` in shell commands, queue files and API calls, and tells Claude why. You can
+still run them yourself in a terminal.
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash|PowerShell|Write|Edit|MultiEdit",
+        "hooks": [{ "type": "command", "command": "node /path/to/shipback-sftp/bin/claude-guard.js" }]
+      }
+    ]
+  }
+}
+```
+
+## Tests
+
+```bash
+npm test
+```
+
+The suite uses `node:test` and needs no network. Deploy, restore, the CLI and the MCP server are each
+also exercised end to end against a real SFTP server started inside the test run.
+
+## Limits
+
+- It compares by size and SHA-256. The first deploy to a site that already has files reads the server
+  copies of any same-size files to compare them.
+- Backups live on the same server as the site. They protect against bad deploys, not against losing the
+  hosting account. Keep your host's own backups too.
+- Files over 8 MB with the same size on both sides are assumed unchanged when there is no manifest hash
+  to compare.
+
+## License
+
+MIT © 2026 Aldo Hushi
+
+Runs aldo.today. Made at [BlueprintAU](https://blueprintau.com).

package/bin/claude-guard.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+'use strict';
+// Claude Code PreToolUse hook: stops Claude deploying with --mirror (deletes server files that
+// only live there: uploads, form data, .well-known) or --no-backup (overwrites with no copy),
+// whether by CLI flag, queue request file, or the local server's API.
+// Register it in ~/.claude/settings.json (see README). Exit 2 = blocked; stderr goes back to Claude.
+// Hooks only gate Claude's tool calls: you can still run either flag yourself in a terminal.
+
+// The flag inside the same simple command as the CLI (so `grep -- --mirror bin/cli.js` passes).
+const CLI_FLAG = /(?:cli\.js|npm\s+(?:run\s+)?deploy|\b(?:sftp-deploy|shipback)(?:\.cmd)?\s)[^\n;&|]*?\s--(mirror|no-backup)(?=$|[\s'";&|)])/i;
+const MIRROR_ON = /\bmirror["'\\]*\s*:\s*true\b/i;
+const BACKUP_OFF = /\bbackup["'\\]*\s*:\s*false\b/i;
+const QUEUE_OR_API = /\.request\.json|localhost|127\.0\.0\.1/i;
+const REQUEST_FILE = /\.request\.json$/i;
+
+function reason(what) {
+  return `shipback guard: ${what} is blocked for Claude. --mirror / "mirror": true deletes server files ` +
+    `that aren't in the local folder; --no-backup / "backup": false overwrites with no copy. Deploy without it. ` +
+    `If the user explicitly wants this, they run the command themselves in a terminal.`;
+}
+
+function jsonOption(text) {
+  if (MIRROR_ON.test(text)) return '"mirror": true';
+  if (BACKUP_OFF.test(text)) return '"backup": false';
+  return null;
+}
+
+// Returns the block reason, or null to let the call through.
+function check(input) {
+  const tool = input && input.tool_name;
+  const ti = (input && input.tool_input) || {};
+  if (tool === 'Bash' || tool === 'PowerShell') {
+    const cmd = String(ti.command || '');
+    const flag = cmd.match(CLI_FLAG);
+    if (flag) return reason(`--${flag[1]}`);
+    const opt = QUEUE_OR_API.test(cmd) && jsonOption(cmd);
+    return opt ? reason(opt) : null;
+  }
+  if (tool === 'Write' || tool === 'Edit' || tool === 'MultiEdit') {
+    if (!REQUEST_FILE.test(String(ti.file_path || ''))) return null;
+    const text = [ti.content, ti.new_string, ...(ti.edits || []).map(e => e && e.new_string)].filter(Boolean).join('\n');
+    const opt = jsonOption(text);
+    return opt ? reason(opt) : null;
+  }
+  return null;
+}
+
+if (require.main === module) {
+  let raw = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', d => { raw += d; });
+  process.stdin.on('end', () => {
+    let input;
+    try { input = JSON.parse(raw); } catch { process.exit(0); }
+    const why = check(input);
+    if (why) { process.stderr.write(why + '\n'); process.exit(2); }
+    process.exit(0);
+  });
+}
+
+module.exports = { check };

package/bin/cli.js

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+'use strict';
+// Command-line deploy / pull: node bin/cli.js <site> [--pull] [--local DIR] [--remote DIR] [--dry-run] [--no-backup] [--mirror] [--password PW]
+//                            node bin/cli.js <site> --prune NAME[,NAME…] | --keep N  [--force] [--dry-run]   (remove _backup-* folders on the server)
+//                            node bin/cli.js <site> --restore [NAME|latest] [--force] [--dry-run]   (undo a deploy from its _backup-* folder)
+//                            node bin/cli.js <site> --backups   (list the backups on the server)
+//                            node bin/cli.js --history [site]
+const path = require('node:path');
+const readline = require('node:readline');
+const { loadSites } = require('../src/config');
+const { createCredentialStore } = require('../src/credentials');
+const { SftpRemoteFs } = require('../src/remote-fs');
+const { runDeploy } = require('../src/deploy');
+const { runPull } = require('../src/pull');
+const { runPrune } = require('../src/prune');
+const { runRestore, describeBackups } = require('../src/restore');
+const { appendHistory, readHistory, recordFromSummary } = require('../src/history');
+
+function parseArgs(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--dry-run') out.dryRun = true;
+    else if (a === '--pull') out.pull = true;
+    else if (a === '--history') out.history = true;
+    else if (a === '--json') out.json = true;
+    else if (a === '--no-backup') out.backup = false;
+    else if (a === '--mirror') out.mirror = true;
+    else if (a === '--prune') { out.prune = true; const v = argv[i + 1]; if (v && !v.startsWith('--')) { out.names = v.split(',').map(x => x.trim()).filter(Boolean); i++; } }
+    else if (a === '--keep') { out.prune = true; out.keep = Number(argv[++i]); }
+    else if (a === '--force') out.force = true;
+    else if (a === '--restore') { out.restore = true; const v = argv[i + 1]; if (v && !v.startsWith('--')) { out.name = v; i++; } }
+    else if (a === '--backups') out.backups = true;
+    else if (a === '--local') out.local = argv[++i];
+    else if (a === '--remote') out.remote = argv[++i];
+    else if (a === '--password') out.password = argv[++i];
+    else if (a === '--sites') out.sites = argv[++i];
+    else if (a === '-h' || a === '--help') out.help = true;
+    else out._.push(a);
+  }
+  return out;
+}
+
+function ask(q, hidden) {
+  return new Promise(resolve => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+    if (hidden) { rl._writeToOutput = s => { if (/\n/.test(s)) rl.output.write('\n'); }; process.stdout.write(q); }
+    rl.question(hidden ? '' : q, ans => { rl.close(); resolve(ans); });
+  });
+}
+
+(async () => {
+  const args = parseArgs(process.argv.slice(2));
+  const sitesFile = args.sites || path.join(process.cwd(), 'sites.json');
+  const historyFile = path.join(path.dirname(sitesFile), 'deploys.jsonl');
+  if (args.history) {
+    const rows = await readHistory(historyFile, { site: args._[0], limit: 20 });
+    if (args.json) { console.log(JSON.stringify(rows, null, 2)); return; }
+    if (!rows.length) { console.log('No deploys recorded yet.'); return; }
+    for (const r of rows) {
+      const what = r.action === 'pull' ? `${(r.downloaded || []).length} downloaded` : `${(r.uploaded || []).length} uploaded`;
+      console.log(`${new Date(r.at).toLocaleString([], { year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit' })}  ${r.ok ? 'ok    ' : 'FAILED'}  ${r.action.padEnd(7)} ${r.site.padEnd(14)} ${what}${r.deleted && r.deleted.length ? `, ${r.deleted.length} deleted` : ''}${r.backupDir ? '  backup: ' + r.backupDir : ''}  [${r.trigger}]${r.error ? '  ' + r.error : ''}`);
+    }
+    return;
+  }
+  if (args.help || !args._[0]) {
+    console.log('Usage: node bin/cli.js <site> [--pull] [--local DIR] [--remote DIR] [--dry-run] [--no-backup] [--mirror] [--password PW] [--sites sites.json]');
+    console.log('       node bin/cli.js <site> --prune NAME[,NAME…] | --keep N [--force] [--dry-run]   remove _backup-* folders (only when every file has a copy elsewhere)');
+    console.log('       node bin/cli.js <site> --restore [NAME|latest] [--force] [--dry-run]   undo a deploy (refuses if a live file was edited since, unless --force)');
+    console.log('       node bin/cli.js <site> --backups [--json]   list the _backup-* folders and what each holds');
+    console.log('       node bin/cli.js --history [site] [--json]');
+    process.exit(args.help ? 0 : 1);
+  }
+  const { sites } = await loadSites(sitesFile);
+  const site = sites.find(s => s.name === args._[0]);
+  if (!site) { console.error(`Unknown site "${args._[0]}". Known: ${sites.map(s => s.name).join(', ') || '(none)'}`); process.exit(1); }
+  const localDir = args.local || site.localDir;
+  const remoteRoot = args.remote || site.remoteRoot;
+  if (!localDir && !args.prune && !args.restore && !args.backups) { console.error('No local folder: pass --local DIR or set localDir on the site'); process.exit(1); }
+
+  // Open the OS keychain only when a password has to come from it (or be saved to it): a --password or
+  // SFTP_PASSWORD run, like CI, never touches the vault.
+  const needsStore = !site.privateKeyPath && args.password == null && !process.env.SFTP_PASSWORD;
+  const { store, note } = needsStore ? createCredentialStore() : {};
+  let password = args.password ?? process.env.SFTP_PASSWORD ?? (site.privateKeyPath ? '' : await store.get(site.name));
+  if (password == null) { password = await ask(`Password for ${site.username}@${site.host}: `, true); }
+
+  const opts = { host: site.host, port: site.port, username: site.username };
+  if (site.privateKeyPath) opts.privateKey = require('node:fs').readFileSync(site.privateKeyPath); else opts.password = password;
+  process.stdout.write(`Connecting to ${site.host}… `);
+  let rfs;
+  try { rfs = await SftpRemoteFs.connect(opts); } catch (e) { console.error('\n' + e.message); process.exit(2); }
+  console.log('ok');
+  if (needsStore && (await store.get(site.name)) == null) { await store.set(site.name, password); console.log(note); }
+
+  const fmt = n => n < 1024 ? n + ' B' : n < 1048576 ? (n / 1024).toFixed(1) + ' KB' : (n / 1048576).toFixed(2) + ' MB';
+  const action = args.backups ? 'backups' : args.restore ? 'restore' : args.prune ? 'prune' : args.pull ? 'pull' : 'deploy';
+  const startedAt = new Date().toISOString();
+  const onEvent = ev => {
+    if (ev.type === 'plan') {
+      const list = ev.plan.upload || ev.plan.download, verb = ev.plan.upload ? 'upload' : 'download';
+      console.log(args.pull ? `\n${site.host}:${remoteRoot}  →  ${localDir}` : `\n${localDir}  →  ${site.host}:${remoteRoot}`);
+      for (const u of list) console.log(`  ${u.reason === 'new' ? '+' : '~'} ${u.path}  (${fmt(u.size)})`);
+      for (const d of ev.plan.delete) console.log(`  - ${d}`);
+      console.log(`  ${list.length} to ${verb} (${fmt(ev.plan.uploadBytes || ev.plan.downloadBytes || 0)}), ${ev.plan.skip.length} unchanged, ${ev.plan.extra.length} ${args.pull ? 'only local' : 'only on server'}${ev.plan.delete.length ? `, ${ev.plan.delete.length} to delete` : ''}\n`);
+    } else if (ev.type === 'backup') console.log(`  backup  ${ev.path}`);
+    else if (ev.type === 'upload' || ev.type === 'download') console.log(`  ${ev.type.padEnd(8)}${ev.path}  ${ev.done}/${ev.total}`);
+    else if (ev.type === 'delete') console.log(`  delete  ${ev.path}`);
+    else if (ev.type === 'rmdir') console.log(`  rmdir   ${ev.path}`);
+    else if (ev.type === 'prune-plan') console.log(`\n${site.host}:${remoteRoot}  backups: ${ev.backups.join(', ') || '(none)'}\n  prune: ${ev.targets.join(', ') || '(none)'}\n  keep:  ${ev.kept.join(', ') || '(none)'}\n`);
+    else if (ev.type === 'prune-check') console.log(`  ${ev.name}: ${ev.files} files (${fmt(ev.bytes)}), ${ev.unique} without a copy elsewhere`);
+    else if (ev.type === 'refuse') console.log(`  REFUSED ${ev.name}: only copy of ${ev.unique.join(', ')} — add --force to remove anyway`);
+    else if (ev.type === 'restore-plan') {
+      console.log(`
+${site.host}:${remoteRoot}  restore from ${ev.backup}${ev.legacy ? '  (older backup, no .backup.json: puts its files back, removes nothing, cannot check for edits)' : ''}`);
+      for (const p of ev.put) console.log(`  < ${p}`);
+      for (const p of ev.remove) console.log(`  - ${p}`);
+      console.log(`  ${ev.put.length} to put back, ${ev.remove.length} to remove, ${ev.same} already right${ev.conflicts ? `, ${ev.conflicts} CONFLICTS` : ''}
+`);
+    } else if (ev.type === 'conflict') console.log(`  CONFLICT ${ev.path}: ${ev.why}`);
+    else if (ev.type === 'restore') console.log(`  restore ${ev.path}`);
+    else if (ev.type === 'error') console.error(`  ERROR   ${ev.message}`);
+  };
+  const common = { localDir, remoteRoot, remoteFs: rfs, dryRun: !!args.dryRun, backup: args.backup !== false, mirror: !!args.mirror, ignore: site.ignore, onEvent };
+  try {
+    if (args.backups) {
+      const list = await describeBackups({ remoteRoot, remoteFs: rfs });
+      if (args.json) console.log(JSON.stringify(list, null, 2));
+      else if (!list.length) console.log('No backups on the server.');
+      else for (const b of list) console.log(`  ${b.name.padEnd(28)} ${b.legacy ? `${b.files} files (older backup, no record)` : `${b.action.padEnd(8)} ${b.overwritten} overwritten, ${b.added} added, ${b.deleted} deleted${b.from ? '  (undo of ' + b.from + ')' : ''}`}`);
+      return;
+    }
+    if (args.restore) {
+      const s = await runRestore({ remoteRoot, remoteFs: rfs, name: args.name, dryRun: !!args.dryRun, force: !!args.force, onEvent });
+      if (s.refused) { console.log(`Refused: ${s.conflicts.length} file(s) changed on the server after that run. Nothing was changed. Check them, then add --force to restore anyway (the live copies are backed up first).`); process.exitCode = 4; }
+      else if (s.dryRun) console.log('Dry run — nothing was changed.');
+      else console.log(`Done: ${s.put.length} put back, ${s.remove.length} removed${s.undoBackupDir ? `. Undo this with --restore ${s.undoBackupDir.split('/').pop()}` : ''}.`);
+      if (!s.dryRun) await appendHistory(historyFile, recordFromSummary({ action, site: site.name, trigger: 'cli', remoteDir: remoteRoot, startedAt, summary: s })).catch(() => {});
+      if (args.json) console.log(JSON.stringify(s));
+      return;
+    }
+    const s = args.prune ? await runPrune({ remoteRoot, remoteFs: rfs, names: args.names, keep: args.keep, dryRun: !!args.dryRun, force: !!args.force, onEvent })
+      : args.pull ? await runPull(common) : await runDeploy(common);
+    if (s.dryRun) console.log('Dry run — nothing was changed.');
+    else if (args.prune) {
+      console.log(`Done: ${s.pruned.length} backup folder(s) removed (${s.deleted} files, ${fmt(s.bytes)})${s.refused.length ? `, ${s.refused.length} refused` : ''}.`);
+      await appendHistory(historyFile, recordFromSummary({ action, site: site.name, trigger: 'cli', remoteDir: remoteRoot, startedAt, summary: s })).catch(() => {});
+    } else {
+      const moved = args.pull ? s.downloaded : s.uploaded;
+      console.log(`Done: ${moved.length} ${args.pull ? 'downloaded' : 'uploaded'} (${fmt(s.bytes)}), ${s.backedUp.length} backed up${s.backupDir ? ' to ' + s.backupDir : ''}, ${s.deleted.length} deleted.`);
+      await appendHistory(historyFile, recordFromSummary({ action, site: site.name, trigger: 'cli', localDir, remoteDir: remoteRoot, startedAt, summary: s })).catch(() => {});
+    }
+    if (args.json) console.log(JSON.stringify(s));
+  } catch (e) {
+    process.exitCode = 3;
+    await appendHistory(historyFile, recordFromSummary({ action, site: site.name, trigger: 'cli', localDir, remoteDir: remoteRoot, startedAt, error: e.message })).catch(() => {});
+  }
+  finally { await rfs.close(); }
+})();

package/bin/mcp.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+'use strict';
+// MCP server over stdio: shipback-mcp [--sites path/to/sites.json]
+// (or set SHIPBACK_SITES). See README → "Use it from an AI agent".
+const path = require('node:path');
+const { createMcp, serveStdio } = require('../src/mcp');
+
+const i = process.argv.indexOf('--sites');
+const sitesFile = i > 0 && process.argv[i + 1] ? path.resolve(process.argv[i + 1]) : undefined;
+serveStdio(createMcp({ sitesFile })).then(() => process.exit(0));

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "shipback-sftp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "SFTP deploys to shared hosting that you, a script or an AI agent can undo: backup before every overwrite, one-command restore that won't clobber live edits, and an MCP server.",
+  "keywords": [
+    "sftp",
+    "deploy",
+    "cpanel",
+    "shared-hosting",
+    "backup",
+    "rollback",
+    "mcp",
+    "mcp-server",
+    "claude-code",
+    "ai-agents"
+  ],
+  "author": "Aldo Hushi",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aldohushi1-stack/shipback-sftp.git"
+  },
+  "main": "src/deploy.js",
+  "bin": {
+    "shipback": "bin/cli.js",
+    "shipback-mcp": "bin/mcp.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "ui/",
+    "start.bat",
+    "sites.example.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node src/server.js",
+    "test": "node test/run.js",
+    "deploy": "node bin/cli.js",
+    "mcp": "node bin/mcp.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@napi-rs/keyring": "^2.1.0",
+    "ssh2": "^1.17.0"
+  }
+}

package/sites.example.json

@@ -0,0 +1,13 @@
+{
+  "sites": [
+    {
+      "name": "mysite",
+      "host": "server123.example-host.com",
+      "port": 22,
+      "username": "cpaneluser",
+      "remoteRoot": "/home/cpaneluser/public_html",
+      "localDir": "/Users/you/sites/mysite",
+      "ignore": ["drafts/", "*.psd"]
+    }
+  ]
+}

package/src/backup.js

@@ -0,0 +1,61 @@
+'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 posix = require('node:path').posix;
+const { BACKUP_PREFIX } = require('./diff');
+
+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;
+}
+
+/** backupFiles({ remoteFs, root, paths, stamp | backupDir, onEvent }) → { backupDir, copied } */
+async function backupFiles({ remoteFs, root, paths, stamp = makeStamp(), backupDir, onEvent = () => {} }) {
+  root = root.replace(/\/$/, '');
+  backupDir = backupDir || `${root}/${BACKUP_PREFIX}${stamp}`;
+  const copied = [];
+  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);
+    onEvent({ type: 'backup', path: rel, bytes: data.length, to: dest });
+  }
+  return { backupDir, copied };
+}
+
+/**
+ * writeBackupInfo({ remoteFs, backupDir, info })
+ *   info: { action, at, overwritten: [{ path, sha256 }], added: [{ path, sha256 }], deleted: [{ path }], from? }
+ *   sha256 = the content the run left at that path, so a later restore can tell if it was edited since.
+ */
+async function writeBackupInfo({ remoteFs, backupDir, info }) {
+  await remoteFs.mkdirp(backupDir);
+  await remoteFs.writeFile(`${backupDir}/${BACKUP_INFO}`, JSON.stringify({ version: 1, tool: 'shipback-sftp', ...info }, null, 1));
+}
+
+async function readBackupInfo(remoteFs, backupDir) {
+  try {
+    const info = JSON.parse((await remoteFs.readFile(`${backupDir}/${BACKUP_INFO}`)).toString('utf8'));
+    return info && info.version === 1 ? info : null;
+  } catch { return null; }
+}
+
+module.exports = { backupFiles, makeStamp, freeBackupDir, writeBackupInfo, readBackupInfo, 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 };