shipback-sftp 0.0.0-stage → 0.2.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,242 @@
-# 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.
+
+**[The undo promise](UNDO-PROMISE.md):** one command puts the site back byte for byte, even after a deploy that
+was cut off halfway. It never overwrites a live edit. Each of the thirteen lines in the promise has its own test, and
+if undo ever breaks one of them, that's the first bug I fix.
+
+- **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.
+- **Never half a file.** Each file goes up beside the live one and is swapped in whole, so a dropped connection
+  leaves the old file, not a broken one.
+- **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.
+- **One run at a time.** A deploy or restore holds a lock on the site while it writes. A second one is turned away
+  with nothing changed, so an agent and a person can't deploy over each other.
+- **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 since 0.1, and the
+cut-off handling behind the promise is new in 0.2.
+
+## Quick start
+
+```bash
+npm install -g shipback-sftp          # installs the shipback and shipback-mcp commands
+cd ~/sites                            # any folder with a sites.json in it (format below)
+shipback mysite --dry-run             # see the plan; asks for the password once and stores it
+shipback mysite                       # deploy
+shipback mysite --restore             # changed your mind? undo it
+```
+
+No global install? `npx -p shipback-sftp shipback mysite --dry-run` works the same way. `--sites <file>`
+points at a `sites.json` in another folder.
+
+From source: `git clone https://github.com/aldohushi1-stack/shipback-sftp.git`, `npm install`, then
+`node bin/cli.js` wherever these docs say `shipback`.
+
+`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
+shipback <site> --dry-run                 # what a deploy would upload
+shipback <site>                           # deploy: backup, upload, record
+shipback <site> --local <folder>          # deploy a different folder than localDir
+shipback <site> --pull --dry-run          # what changed on the server since the last deploy?
+shipback <site> --pull                    # bring those changes down (local copies backed up first)
+shipback <site> --backups                 # list backups: what each run overwrote, added, deleted
+shipback <site> --restore --dry-run       # what an undo of the latest deploy would do
+shipback <site> --restore [<backup>]      # undo it (or name an older _backup-… folder)
+shipback <site> --prune --keep 10         # tidy old backups; refuses any holding the only copy of a file
+shipback --history [site]                 # what went up, when, from where
+```
+
+Add `--json` to any command for machine-readable output. A refused restore exits with code 4, and a run turned away
+because another one is writing to the site exits with code 5.
+
+`--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**, a SHA-256 of every file it left on the server, and a
+  SHA-256 of every copy it saved, so a damaged copy is never put back
+
+The record says `saving` until every copy is made. A deploy cut off before then hasn't changed anything, and
+`--restore` says so. New files go up as `.shipback-part-<name>` beside the live file and are renamed over it in one
+step, keeping its permissions. Listings hide part files, and the next deploy or restore clears any that are left.
+
+While a deploy, upload, restore or prune writes, it holds `.shipback-lock` in the remote root and refreshes it every
+30 seconds. The lock is never deployed, pulled or listed. A lock goes stale, and the next run takes it over, when its
+process on this computer has ended or nothing has refreshed it for 2 minutes. So a run that was cut off never leaves
+a site locked for long.
+
+`--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. If a restore is cut off, plain `--restore` sees that
+the latest run is an unfinished restore and finishes it. 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)
+
+`shipback-mcp` (`bin/mcp.js`) is an MCP server over stdio.
+
+**Claude Code**
+
+```bash
+claude mcp add shipback-sftp -- npx -y -p shipback-sftp shipback-mcp --sites /path/to/sites.json
+```
+
+**Cursor, Claude Desktop, and others** (`mcp.json` / `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "shipback-sftp": {
+      "command": "npx",
+      "args": ["-y", "-p", "shipback-sftp", "shipback-mcp", "--sites", "/path/to/sites.json"]
+    }
+  }
+}
+```
+
+On Windows, if the client can't start `npx`, use `"command": "cmd"` with `"/c", "npx"` at the front of
+`args`. After a global install, `"command": "shipback-mcp"` works too, and from a clone it's `node` with
+`bin/mcp.js` as the first arg.
+
+Run any CLI command for a site once first (for example `shipback 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. After `npm install -g shipback-sftp`, the file is in the folder
+`npm root -g` prints, under `shipback-sftp/bin/`.
+
+```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. `test/promise.test.js` holds one test per line of the
+[undo promise](UNDO-PROMISE.md). 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.
+- What undo doesn't cover (databases, `--no-backup` deploys, pruned backups and so on) is listed in
+  [the undo promise](UNDO-PROMISE.md#what-it-doesnt-cover).
+
+## License
+
+MIT © 2026 Aldo Hushi
+
+Runs aldo.today. Made at [BlueprintAU](https://blueprintau.com).

package/UNDO-PROMISE.md

@@ -0,0 +1,52 @@
+# The undo promise
+
+Any deploy Shipback makes can be undone with one command:
+
+```bash
+shipback mysite --restore
+```
+
+Agents get the same thing as `preview_restore` then `restore`. Here is exactly what it does. Each line has a test with
+the same number in [`test/promise.test.js`](test/promise.test.js). Those tests run on every push, on Windows, macOS
+and Linux, and compare every byte on the server, not a sample.
+
+| | When you undo a deploy |
+| --- | --- |
+| **P1** | Every file it replaced or deleted comes back byte for byte. Every file it added is removed, along with any folder it created for them. Nothing else on the server is touched: uploads, form data and `.well-known` stay as they are. |
+| **P2** | If the deploy was cut off part way (Wi-Fi dropped, laptop lid shut), the live site never had half a file on it, and the same one command still undoes it. No `--force`. |
+| **P3** | That holds on servers that can't swap a file in one step too. |
+| **P4** | If it was cut off while it was still saving backups, it hadn't changed anything yet. Undo says so and doesn't guess. |
+| **P5** | If the backup can't be saved (a full disk, say), nothing goes up. |
+| **P6** | If the undo itself is cut off, run it again and it finishes. |
+| **P7** | If someone changed one of those files on the server after the deploy, undo stops, names the file and changes nothing at all. You decide what happens next. |
+| **P8** | A backup copy that's been damaged since is never written back, even with `--force`. |
+| **P9** | The undo can be undone. |
+| **P10** | All of this works through a real SFTP server, and replaced files keep their permissions. |
+| **P11** | A dropped connection fails the deploy out loud and tells you how to undo it. It never stops in silence. |
+| **P12** | Only one deploy or undo writes to a site at a time. A second one is turned away without changing anything, so two runs can never get mixed into one backup. A lock left behind by a run that was cut off clears itself. |
+| **P13** | Undo never touches anything outside the site folder, even if a backup record has been tampered with to say it should. A record that can't be read is refused, never guessed at. |
+
+These have also been run on a real cPanel host, including cutting the connection halfway through a deploy and running
+two deploys at once.
+
+## If it doesn't
+
+If undo ever fails to do one of those things, [open an "Undo didn't work" issue](https://github.com/aldohushi1-stack/shipback-sftp/issues/new?template=undo_failed.yml).
+
+- It's the first thing I fix, ahead of everything else.
+- I'll help you get your files back by hand. Everything the deploy replaced is still in its `_backup-…` folder on your server.
+- The fix ships with a test built from your case, so it can't happen again.
+
+## What it doesn't cover
+
+- **Deploys made with `--no-backup`.** They have nothing to undo from. The agent tools can't make them.
+- **Backups that are gone.** Undo needs that deploy's `_backup-…` folder. `--prune` will remove old ones if you ask, and so can you or your host.
+- **Anything outside the site folder:** databases, server settings, cron jobs, email.
+- **Backups made before 0.2.** Those still restore, but they don't carry the checksums behind P4 and P8.
+- **File dates and owners.** Restored files get the current time. A file brought back after a deploy deleted it gets the server's default permissions.
+- **Losing the hosting account.** Backups sit on the same server as the site. Keep your host's own backups too.
+
+This is a promise about what the software does and how I'll treat it when it doesn't. It isn't insurance, and the
+MIT licence's "no warranty" still stands.
+
+Aldo Hushi, 20 October 2026

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,162 @@
+#!/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}${ev.undo ? `
+          ${ev.undo}` : ''}`);
+  };
+  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 + ')' : ''}${b.status === 'saving' ? '  [cut off before changing anything]' : b.status ? '  [cut off part way]' : ''}`}`);
+      return;
+    }
+    if (args.restore) {
+      const s = await runRestore({ remoteRoot, remoteFs: rfs, name: args.name, dryRun: !!args.dryRun, force: !!args.force, onEvent });
+      if (s.resumed) console.log(`(${s.resumed} is a restore that was cut off, so this finishes it: restoring ${s.backup})`);
+      if (s.stoppedEarly) console.log(`${s.backup} was cut off while it was still saving backups, before it changed any live file. Nothing to undo.`);
+      else 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 = e.code === 'ELOCKED' ? 5 : 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,51 @@
 {
   "name": "shipback-sftp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.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",
+    "UNDO-PROMISE.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"]
+    }
+  ]
+}