Shipback SFTP

Implementos SFTP a hosting compartido (cPanel, Plesk, cualquier host SFTP) que un agente de IA puede deshacer: cada implemento respalda los archivos que reemplaza en el servidor, y la restauración los devuelve, pero se niega si un archivo en vivo fue editado desde entonces.

GitHub

Documentación

Shipback SFTP

Deja que el agente despliegue. Conserva el deshacer.

Es tarde, y el agente dice "Desplegado ✓". Entonces el formulario de contacto del cliente desaparece. El agente sobrescribió un archivo que alguien había corregido a mano en cPanel la semana pasada, y el hosting compartido no tiene git revert.

Shipback despliega una carpeta en cualquier host SFTP: cPanel, Plesk, DirectAdmin, un VPS simple. Cada despliegue se puede deshacer con un solo comando. Puedes ejecutarlo tú mismo, scriptearlo, o entregárselo a Claude Code, Cursor o cualquier cliente MCP.

Respaldo antes de cada sobrescritura. La copia del servidor de cada archivo que un despliegue reemplaza se guarda en _backup-<time>/ en el servidor, antes de que comience la subida.
Deshacer con un comando. --restore restaura esos archivos y elimina los archivos que el despliegue agregó.
No deshace sobre una edición en vivo. Si alguien cambió un archivo en el servidor después del despliegue, la restauración se detiene y nombra el archivo. Nada se toca a menos que pases --force, e incluso entonces la copia editada se respalda primero.
Las restauraciones también se pueden deshacer. Una restauración respalda lo que reemplaza, de la misma manera que lo hace un despliegue.
Seguro para agentes. El servidor MCP no tiene un interruptor para eliminar archivos del servidor ni para omitir el respaldo. Un despliegue solo ejecuta el plan exacto que el agente previsualizó: si un archivo cambió en el medio, se niega.
Detecta la deriva. --pull --dry-run muestra qué cambió en el servidor desde tu último despliegue, para que las ediciones hechas en vivo en cPanel no se sobrescriban por accidente.

No se necesita git ni shell SSH en el servidor, solo SFTP. Requiere Node 18+. Las pruebas se ejecutan en Windows, macOS y Linux con Node 18, 20 y 22 en cada push. Las contraseñas se guardan en el llavero del sistema operativo y nunca pasan por el modelo.

Ha funcionado en producción. El motor de despliegue subyacente ha enviado aldo.today 235 veces desde septiembre de 2026 (2,907 archivos a un host cPanel). La restauración y el servidor MCP son nuevos en la versión 0.1.

Inicio rápido

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

¿Sin instalación global? npx -p shipback-sftp shipback mysite --dry-run funciona de la misma manera. --sites <file> apunta a un sites.json en otra carpeta.

Desde el código fuente: git clone https://github.com/aldohushi1-stack/shipback-sftp.git, npm install, y luego node bin/cli.js dondequiera que estos documentos digan shipback.

sites.json, una entrada por sitio:

{
  "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"]
    }
  ]
}

Muchos hosts compartidos ejecutan SFTP en su propio puerto en lugar del 22 (revisa Acceso SSH en tu panel de control), y algunos solo aceptan conexiones desde IPs en lista blanca. Si una conexión se agota, revisa esos dos primero. Usa "privateKeyPath" en lugar de una contraseña si tu host tiene tu clave.

Comandos

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

Agrega --json a cualquier comando para obtener salida legible por máquina. Una restauración rechazada sale con el código 4.

--mirror (eliminar archivos del servidor que no están en la carpeta local) y --no-backup existen para humanos que saben que los quieren. Las herramientas del agente no los ofrecen, y el gancho de protección bloquea a Claude de escribirlos.

Cómo funciona el deshacer

Cada despliegue escribe _backup-YYYY-MM-DD-HHMM/ en la raíz remota. Contiene:

la copia del servidor de cada archivo que el despliegue sobrescribió o eliminó
.backup.json, un registro de lo que el despliegue agregó, y un SHA-256 de cada archivo que dejó en el servidor

--restore lee ese registro y verifica cada archivo en vivo primero:

Archivo en vivo ahora	La restauración hace
exactamente lo que el despliegue subió	pone la copia anterior de vuelta (o la elimina, si el despliegue la agregó)
ya es la copia anterior	nada; cuenta como ya correcto
diferente de ambos	conflicto: se detiene, nombra el archivo, no cambia nada (`--force` anula)

Antes de escribir cualquier cosa, la restauración guarda los archivos en vivo actuales en una nueva carpeta _backup-… con su propio registro, para que --restore en esa carpeta te lleve hacia adelante de nuevo. También limpia las rutas restauradas de .deploy-manifest.json, para que el próximo despliegue las compare por contenido en lugar de confiar en hashes obsoletos.

Las carpetas de respaldo se omiten en despliegues y extracciones, y nunca se eliminan excepto por --prune.

Úsalo desde un agente de IA (MCP)

shipback-mcp (bin/mcp.js) es un servidor MCP sobre stdio.

Claude Code

claude mcp add shipback-sftp -- npx -y -p shipback-sftp shipback-mcp --sites /path/to/sites.json

Cursor, Claude Desktop y otros (mcp.json / claude_desktop_config.json):

{
  "mcpServers": {
    "shipback-sftp": {
      "command": "npx",
      "args": ["-y", "-p", "shipback-sftp", "shipback-mcp", "--sites", "/path/to/sites.json"]
    }
  }
}

En Windows, si el cliente no puede iniciar npx, usa "command": "cmd" con "/c", "npx" al frente de args. Después de una instalación global, "command": "shipback-mcp" también funciona, y desde un clon es node con bin/mcp.js como primer argumento.

Ejecuta cualquier comando CLI para un sitio una vez primero (por ejemplo shipback mysite --backups). Eso almacena la contraseña en el llavero del sistema operativo, donde el servidor MCP la lee. El modelo nunca la ve. Para CI puedes configurar SFTP_PASSWORD en el entorno del servidor en su lugar.

Herramienta	Hace
`list_sites`	los sitios configurados (sin contraseñas)
`preview_deploy`	qué se subiría; devuelve un `planId`
`deploy`	sube ese plan; se niega si algo cambió desde la vista previa
`check_server_changes`	archivos editados o agregados en el servidor en vivo desde el último despliegue
`pull`	trae esos archivos a la carpeta local (las copias locales se respaldan)
`list_backups`	respaldos, más recientes primero, con qué cambió cada ejecución
`preview_restore`	qué pondría de vuelta y eliminaría un deshacer, más cualquier conflicto; devuelve un `planId`
`restore`	ejecuta ese deshacer; se niega en conflictos a menos que `force`
`history`	despliegues, extracciones y restauraciones recientes

Lo que las herramientas omiten es deliberado: no hay espejo/eliminación, no hay forma de omitir el respaldo, y no hay poda de respaldos.

Agentes sin shell: la cola de buzón de entrada

Algunas configuraciones de agentes pueden escribir archivos pero no pueden ejecutar comandos. Mientras la aplicación local está en ejecución (npm start, o start.bat en Windows), cualquier cosa que pueda escribir un archivo puede poner en cola un trabajo:

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

Acciones: deploy, preview, pull, restore, backups, prune.

La aplicación local

npm start abre una pequeña interfaz en http://127.0.0.1:4646: agrega sitios, previsualiza, despliega, extrae, arrastra subidas únicas, navega por el servidor y ve el historial. Solo responde a solicitudes de tu propia máquina.

Gancho de protección de Claude Code

Si Claude también ejecuta el CLI directamente, agrega bin/claude-guard.js como un gancho PreToolUse. Bloquea --mirror y --no-backup en comandos de shell, archivos de cola y llamadas API, y le dice a Claude por qué. Aún puedes ejecutarlos tú mismo en una terminal. Después de npm install -g shipback-sftp, el archivo está en la carpeta que npm root -g imprime, bajo shipback-sftp/bin/.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|PowerShell|Write|Edit|MultiEdit",
        "hooks": [{ "type": "command", "command": "node /path/to/shipback-sftp/bin/claude-guard.js" }]
      }
    ]
  }
}

Pruebas

npm test

La suite usa node:test y no necesita red. El despliegue, la restauración, el CLI y el servidor MCP también se ejercitan de extremo a extremo contra un servidor SFTP real iniciado dentro de la ejecución de la prueba.

Límites

Compara por tamaño y SHA-256. El primer despliegue a un sitio que ya tiene archivos lee las copias del servidor de cualquier archivo del mismo tamaño para compararlas.
Los respaldos viven en el mismo servidor que el sitio. Protegen contra despliegues malos, no contra la pérdida de la cuenta de hosting. Mantén también los respaldos propios de tu host.
Los archivos de más de 8 MB con el mismo tamaño en ambos lados se asumen sin cambios cuando no hay un hash de manifiesto para comparar.

Licencia

Ejecuta aldo.today. Hecho en BlueprintAU.