D1: deployment UI, docs and G17
Some checks are pending
ci / ci (macos-15) (push) Waiting to run
ci / ci (ubuntu-24.04) (push) Waiting to run
ci / ci (windows-2025) (push) Waiting to run

Servers dialog (write-only keychain secret, test connection, unknown and
changed host key), status-bar progress with Cancel, Deployment log tool
window, Upload/Download in the project tree menu and Tools › Deployment.
docs/deployment.md, architecture section, G17 row.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
danny 2026-11-06 18:46:11 +01:00
parent f3c9ef9ce3
commit 872b5cb258
22 changed files with 2628 additions and 26 deletions

54
docs/deployment.md Normal file
View file

@ -0,0 +1,54 @@
# Deployment
> **Status:** Deployment v1 (C9 D1, owner decision D27): servers per project, upload, download, upload on save, test connection, host keys, Deployment log. Remote browser, compare and sync follow in D2 · **Last updated:** 2026-11-06
Lutra uploads a PHP project to a server and downloads files back, the way people deploy shared hosting and small servers every day.
## Servers
Open **Tools › Deployment › Servers…**. Each project has its own list; one is the default server (the only one is the default automatically).
| Field | Meaning |
|---|---|
| Name | Shown in the log, the status bar and toasts. |
| Type | **SFTP** (SSH), **FTPS** (FTP with explicit TLS, certificates checked against the system's trusted roots), **FTP** (unencrypted: everything, including the password, crosses the network in clear text; prefer SFTP or FTPS), or a **local or mounted folder**. |
| Host, Port, User | Port defaults to 22 (SFTP) or 21 (FTP, FTPS). |
| Sign in with | SFTP: password, private key file (with an optional passphrase), or the SSH agent (Pageant or the OpenSSH Authentication Agent on Windows, `SSH_AUTH_SOCK` on macOS). FTP and FTPS: password. |
| Root folder | The server folder everything is relative to; empty for the login folder. For a folder server: the absolute local folder. |
| Path mappings | Local folder (project-relative, empty for the root) → remote folder (relative to the root, or absolute with a leading `/`). The longest matching local folder wins. Without mappings the project root goes to the root. Files outside every mapping are skipped. |
| Excluded paths | One per line. A path excludes itself and everything below it (`var/cache`); a pattern with `*` or `?` matches file and folder names (`*.log`). `.git`, `.svn` and `.hg` are never deployed. |
| Upload on save | Off by default. When on, every saved file that maps to the server is uploaded in the background. |
The configuration lives in Lutra's config directory (`deployment/<project-id>.json`), not in the project, and never contains a password.
## Passwords and passphrases
- They are stored **only in the operating system's keychain**: the Windows Credential Manager or the macOS Keychain, under the service "Lutra Deployment".
- Lutra never writes them to a file, a log, the recovery journal, an event, MCP or control-channel output, or an error message. The password field in the dialog is write-only: after Save it empties again and says "Stored in the system keychain".
- Removing a server removes its keychain entries.
- Linux has no keychain store yet; there, use the SSH agent or a key without a passphrase.
## Host keys (SFTP)
On the first connection, **Test Connection** shows the server's key fingerprint (`ssh-ed25519 SHA256:…`). Compare it with the one from the server's administrator, then choose **Trust and Connect**. Trusted keys are kept in Lutra's own known-hosts file (`deployment/known_hosts` in the config directory); `~/.ssh/known_hosts` is neither read nor changed.
If the key later differs, Lutra **refuses to connect** and says so: someone may be intercepting the connection. Only if you know the server was reinstalled, test the connection and choose **Replace the Trusted Key**.
Uploads and downloads never ask about a key; they fail with a message pointing to Test Connection.
## Upload and download
- **Project tree:** right-click a file or folder › **Upload to Server** / **Download from Server** (default server).
- **Tools › Deployment:** Upload Current File, Download Current File, Upload Project, Test Connection, Deployment Log.
- The same actions are in the command palette. Lutra assigns no default shortcuts; bind them in the keymap.
- Uploads send what is on disk; save first. Downloads replace the local files.
- While a job runs, the status bar shows it with a Cancel button. One job runs at a time; uploads on save wait for the running one.
- Every file, skip and error goes to the **Deployment** log in the bottom panel (newest 1,000 lines). A failing file is logged and the job goes on; a lost connection or a refused sign-in stops it. Each error says what to do.
## For agents and scripts
The `deploy.*` engine commands (`deploy.servers`, `deploy.saveServer`, `deploy.setSecret`, `deploy.testConnection`, `deploy.trustHostKey`, `deploy.upload`, `deploy.download`, `deploy.cancel`, `deploy.log`, …) work over the control channel and MCP like every command; see `docs/architecture.md` › Deployment. Their results never contain a secret.
## Not yet (D2)
A remote file browser, opening and editing remote files, compare with the server, and sync with a preview.