From 872b5cb25872a86af8f55547e339fe330413cc65 Mon Sep 17 00:00:00 2001 From: danny Date: Fri, 6 Nov 2026 18:46:11 +0100 Subject: [PATCH] D1: deployment UI, docs and G17 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- Cargo.lock | 1 + crates/engine/src/cmd/deploy.rs | 6 +- docs/architecture.md | 11 + docs/deployment.md | 54 ++ docs/gaps.md | 3 +- ui/src/commands/modals.ts | 4 +- ui/src/commands/uiCommands.ts | 6 + ui/src/components/StatusBar.vue | 5 +- ui/src/components/deploy/DeployStatusItem.vue | 233 +++++ ui/src/components/deploy/DeploymentDialog.vue | 867 ++++++++++++++++++ .../deploy/DeploymentLogToolWindow.vue | 217 +++++ ui/src/components/deploy/deploy.ts | 694 ++++++++++++++ ui/src/components/layout/MainLayout.vue | 33 +- ui/src/components/project/ProjectTree.vue | 15 +- ui/src/components/project/TreeContextMenu.vue | 32 +- ui/src/i18n/en.json | 86 ++ ui/src/ipc.ts | 23 + ui/tests/deploy/Deploy.test.ts | 356 +++++++ ui/tests/i18n/catalog.test.ts | 2 +- ui/tests/menu/AppMenu.test.ts | 2 +- ui/tests/palette/CommandPalette.test.ts | 2 +- ui/tests/vcs/DiffView.test.ts | 2 +- 22 files changed, 2628 insertions(+), 26 deletions(-) create mode 100644 docs/deployment.md create mode 100644 ui/src/components/deploy/DeployStatusItem.vue create mode 100644 ui/src/components/deploy/DeploymentDialog.vue create mode 100644 ui/src/components/deploy/DeploymentLogToolWindow.vue create mode 100644 ui/src/components/deploy/deploy.ts create mode 100644 ui/tests/deploy/Deploy.test.ts diff --git a/Cargo.lock b/Cargo.lock index 28aebf2..b322e1e 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -3236,6 +3236,7 @@ dependencies = [ name = "lutra-engine" version = "0.1.0-alpha" dependencies = [ + "lutra-deploy", "lutra-index", "lutra-lsp", "lutra-proc", diff --git a/crates/engine/src/cmd/deploy.rs b/crates/engine/src/cmd/deploy.rs index 0058ff2..17dade1 100644 --- a/crates/engine/src/cmd/deploy.rs +++ b/crates/engine/src/cmd/deploy.rs @@ -972,7 +972,7 @@ impl Command for TestConnection { &CommandSpec { id: "deploy.testConnection", label: "Deployment: Test Connection", - menu_path: Some("Tools/Deployment/Test Connection"), + menu_path: None, default_shortcut: None, params: "{ id?: server id (default server when absent) }; returns { ok: true, message } or { ok: false, message, hostKey?: { status: unknown|changed, host, algorithm, fingerprint, known? }, needsSecret?: password|passphrase, authFailed?: true }; other failures are errors", } @@ -1095,7 +1095,7 @@ impl Command for Upload { &CommandSpec { id: "deploy.upload", label: "Deployment: Upload to Server", - menu_path: Some("Tools/Deployment/Upload to Default Server"), + menu_path: None, default_shortcut: None, params: "{ paths: [project-relative file or folder, \"\" for the whole project], id?: server id (default server when absent) }; returns { files, bytes, skipped, failed }; progress as deployProgress, lines as deployLog; deploy.cancel stops it", } @@ -1121,7 +1121,7 @@ impl Command for Download { &CommandSpec { id: "deploy.download", label: "Deployment: Download from Server", - menu_path: Some("Tools/Deployment/Download from Default Server"), + menu_path: None, default_shortcut: None, params: "{ paths: [project-relative file or folder], id?: server id (default server when absent) }; replaces the local files; returns { files, bytes, skipped, failed }; progress as deployProgress; deploy.cancel stops it", } diff --git a/docs/architecture.md b/docs/architecture.md index 9c64c7a..4f57188 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -14,6 +14,7 @@ crates/engine (L4) command registry, workspace state, guard, recovery jou crates/lsp (L3) LSP client (Phpactor first), later DAP client crates/terminal (L3) pseudo-terminal sessions (portable-pty) crates/vcs (L3) Git through the installed git command +crates/deploy (L3) deployment: SFTP, FTP/FTPS, folder; keychain secrets, known hosts crates/index (L2) symbol index, usages, later type inference crates/vfs (L2) project model, file watching, ignore rules, encodings crates/search (L2) find in files (ignore + grep-searcher crates) @@ -752,6 +753,15 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat - **Checked in the app** (debug build with the bundled UI, Windows 11, git 2.47.1, control port 7949, a demo repository with two stashes on two branches and a modified file; commands and screenshots only, no input): `git.stashList` 143–157 ms, `git.stash` 640 ms, a pop 366 ms, each including the control round trip. The refusals came back as written above: applying onto a modified file ("would be overwritten" with git's text), nothing to stash (with the untracked hint), a missing entry. Screenshots of the list (`stash@{n}`, WIP text, branch, date; Drop, Pop, Apply) and of the form, plus the two new buttons in the Changes bar, read in the dark theme. - **Tests:** `crates/vcs/tests/stash.rs` (6 tests against real temp repositories: stash with and without a message, list order and hashes, apply, pop by an abbreviated hash, drop; untracked files only with the flag, including a nested folder and a name starting with `-`; no commit and nothing to stash; a missing and a changed entry, a bad hash; overwritten local changes and untracked files in the way, both leaving the work tree and the entry alone; a conflicted pop keeping the entry and blocking the next stash and apply); unit and property tests in `stash.rs` (list and subject parsing, message cleaning, unmerged counting, hints, chunking); `crates/engine/tests/git_stash.rs` (the command shapes, `gitChanged` only after changes, a changed hash, an empty stash, bad params); Vitest `ui/tests/vcs/Stash.test.ts` (13 tests: parsing, the form with `flushDirty` first, a blank message, a refusal, a failed save, Escape and focus, the list with keyboard and apply, a conflicted pop, the drop question, an empty stash, a failed read, the commands' registration, the Changes window's buttons). +### Deployment (C9 D1) + +- **Owner decision D27 (2026-11-02):** pure-Rust libraries (`russh` + `russh-sftp` with `ring`, `suppaftp` with `rustls`/`ring`, `keyring`); secrets only in the OS keychain. User guide: [`deployment.md`](deployment.md). +- **Crate (`crates/deploy`, L3):** `config` (servers per project, `deny_unknown_fields` so a hand-written `password` field is refused), `mapping` (longest local prefix wins, no `..`, excluded paths and `*`/`?` name patterns; unit and property tests), `secrets` (`SecretStore` trait, `Keychain`, `MemoryStore`; `Secret` debug-prints as `***`), `known_hosts` (Lutra's own file; unknown → `HostKeyUnknown`, different → `HostKeyMismatch`, checked before any credential is sent), `remote` (the `Remote` trait: `mkdir_all`, `put`, `get`, `kind`, `list`, `close`; the extension point for D2), `sftp`, `ftp`, `job` (plan, connect once, transfer file by file; a `Monitor` holds progress and log lines; a `Cancel` flag is checked between 32 KiB chunks and races every SFTP wait). Every library error passes `DeployError::redacted` with the secret in use. Names from remote listings are checked before they become local paths. +- **Test servers** (feature `testserver`, 127.0.0.1 only): a russh SFTP server over a folder with a fixed Ed25519 host key, and a small FTP server. Example `testserver` runs both for live checks. +- **Engine (`cmd/deploy.rs`):** configuration at `/deployment/.json`, known hosts at `/deployment/known_hosts`, keychain account `//`. Commands: `deploy.servers`, `deploy.saveServer {server, secret?}`, `deploy.removeServer`, `deploy.setDefault`, `deploy.setSecret`, `deploy.clearSecret`, `deploy.testConnection {id?}` (an unknown or changed host key, a missing secret or a refused sign-in is a value with `ok: false`), `deploy.trustHostKey {id, algorithm, fingerprint, replace?}`, `deploy.upload {paths, id?}`, `deploy.download {paths, id?}`, `deploy.cancel`, `deploy.log`, `deploy.clearLog`. Jobs are pending outcomes on a `lutra-deploy` thread; one at a time. `file.save` and `file.saveAll` queue uploads on save, which the pump starts and finishes. Events: `deployProgress`, `deployLog {entry}`. `Engine::set_secret_store` swaps the keychain (tests). +- **UI (`ui/src/components/deploy/`):** `deploy.ts` store, `DeployStatusItem.vue` (progress, Cancel, the `deployment.*` UI commands), `DeploymentDialog.vue` (exclusive modal `deployment`; write-only secret field; host-key question), `DeploymentLogToolWindow.vue` (bottom panel). The project tree's context menu gains Upload/Download for files and folders. +- **Tests:** `crates/deploy/tests/transfer.rs` (7: host key first use and mismatch, password and key sign-in, upload, download, cancel, FTP, unreachable), `crates/engine/tests/deploy.rs` (4, including a grep of every event, value, error and the config and data directories for the test password), `ui/tests/deploy/Deploy.test.ts` (12). + ## Decisions (M0) | Question | Decision | Why | @@ -772,6 +782,7 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat | Date | Change | Summary | |---|---|---| +| 2026-11-06 | minor | C9 D1: `crates/deploy` (L3), `deploy.*` commands, deployment events and UI | | 2026-11-02 | minor | C9 F1: `Kind::Path` and `check_path` (one validator for `settings.set` and the dialog, `path` in `settings.list`), `lutra_proc::spawn_detached` for the CLI's desktop start | | 2026-10-31 | minor | C7 B1: app identifier `com.tyrveil.lutra` with the one-time copy from `dev.lutra.desktop`, NSIS and DMG installers, `cargo xtask bundle` | | 2026-10-31 | minor | C7 A3: `git.mergeMessage` and the merge message prefill, `git.ignore` and the Changes context menu, gutter markers kept on their line, per-module `COMMAND_IDS` for the command listing test | diff --git a/docs/deployment.md b/docs/deployment.md new file mode 100644 index 0000000..d67b93b --- /dev/null +++ b/docs/deployment.md @@ -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/.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. diff --git a/docs/gaps.md b/docs/gaps.md index 7bb7305..3f0db9c 100644 --- a/docs/gaps.md +++ b/docs/gaps.md @@ -22,7 +22,7 @@ Every known shortfall, ranked. This is the work list: unless the owner gives a t | G14 | Localization: English and German interface: ~~English message catalog for UI strings~~ (M1.11), engine messages (`EngineError.message`) as message keys, language switch, plurals, German catalog | later | ~38 h | | G15 | Database tools, HTTP client, Docker and remote | later | ~430 h | | G16 | Plug-ins and ecosystem | later | ~120 h | -| G17 | Deployment: servers (FTP, SFTP, local/mounted), path mappings, upload/download, compare with server, edit remote files, save before deploy, optional upload on save per server (owner wish 2026-10-18; needs credential storage and network access, §4) | M7 | ~120 h | +| G17 | Deployment: **v1 done (C9 D1)**: SFTP, FTP, FTPS and folder servers per project, path mappings, excluded paths, upload/download of files and folders, upload on save (off by default), test connection, host-key check, keychain secrets, Deployment log. Open (D2): remote browser, edit remote files, compare with server, sync with preview | M7 | ~40 h | | G18 | Editor productivity: Local History, live and file templates, postfix completion, code generation, intention actions, auto import, scratch files, macros, compare files/folders, TODO view, language injections, code style/formatter | M6–M7 | ~400 h | | G19 | Remote development and Dev Containers | M9 | ~200 h | | G20 | AI features (chat, inline prompts, commit messages); MCP server is G7/M3 | M9 | ~60 h | @@ -55,6 +55,7 @@ G6 progress: M3.2 landed the LSP client library in `crates/lsp`: JSON-RPC framin | Date | Change | Summary | |---|---|---| +| 2026-11-06 | patch | G17: deployment v1 (C9 D1); remote browser, compare and sync left for D2 | | 2026-11-01 | patch | G8: chunk staging, unstaging and revert from the gutter and the diff viewer (C8 C3) | | 2026-10-31 | patch | C7 review: stray revision rows moved here; installers (B1, B2) and the alpha checklist (A2) change no gap | | 2026-10-31 | patch | A1: macOS system menus (G3), Retina region for the macOS screenshot fallback | diff --git a/ui/src/commands/modals.ts b/ui/src/commands/modals.ts index 15e0031..9fd5dd5 100644 --- a/ui/src/commands/modals.ts +++ b/ui/src/commands/modals.ts @@ -20,7 +20,8 @@ * - **Navigation (M3.5):** the definition picker and the inline rename field * are exclusive modals too. So is the branches popup (M4.5), and so are * "Clone Repository…" and "Manage Remotes…" (M4.10), the merge - * dialog (M4.8) and the stash dialog (M4.9). + * dialog (M4.8) and the stash dialog (M4.9), and the deployment servers + * dialog (G17). */ import { defineStore } from "pinia"; import { ref, watch } from "vue"; @@ -38,6 +39,7 @@ export type ModalId = | "branches" | "clone" | "remotes" + | "deployment" | "merge" | "stash"; diff --git a/ui/src/commands/uiCommands.ts b/ui/src/commands/uiCommands.ts index f987715..3f44186 100644 --- a/ui/src/commands/uiCommands.ts +++ b/ui/src/commands/uiCommands.ts @@ -21,6 +21,12 @@ export interface UiCommandSpec { /** The frontend's UI commands. */ export const UI_COMMANDS: readonly UiCommandSpec[] = [ + { id: "deployment.download", labelKey: "command.deployment.download", menuPath: "Tools/Deployment/Download Current File" }, + { id: "deployment.servers", labelKey: "command.deployment.servers", menuPath: "Tools/Deployment/Servers…" }, + { id: "deployment.showLog", labelKey: "command.deployment.showLog", menuPath: "Tools/Deployment/Deployment Log" }, + { id: "deployment.testConnection", labelKey: "command.deployment.testConnection", menuPath: "Tools/Deployment/Test Connection" }, + { id: "deployment.upload", labelKey: "command.deployment.upload", menuPath: "Tools/Deployment/Upload Current File" }, + { id: "deployment.uploadProject", labelKey: "command.deployment.uploadProject", menuPath: "Tools/Deployment/Upload Project" }, { id: "editor.reveal", labelKey: "command.editor.reveal" }, { id: "editor.complete", labelKey: "command.editor.complete", menuPath: "Edit/Complete Code" }, { id: "editor.quickDocumentation", labelKey: "command.editor.quickDocumentation", menuPath: "Edit/Quick Documentation", defaultShortcut: "Mod+I" }, diff --git a/ui/src/components/StatusBar.vue b/ui/src/components/StatusBar.vue index 6e9471f..ceff280 100644 --- a/ui/src/components/StatusBar.vue +++ b/ui/src/components/StatusBar.vue @@ -3,12 +3,14 @@ * Status bar along the bottom of the main window. Shows the product name and * version, or the last engine error, and on the right the language server's * progress (H3), a running fetch, pull, push or clone or the commits - * ahead and behind (M4.10), and the Git branch (M4.5). + * ahead and behind (M4.10), a running deployment job (G17), and the Git + * branch (M4.5). */ import { computed } from "vue"; import { t } from "../i18n"; import { useAppStore } from "../stores/app"; import LspProgressItem from "./problems/LspProgressItem.vue"; +import DeployStatusItem from "./deploy/DeployStatusItem.vue"; import BranchStatusItem from "./vcs/branches/BranchStatusItem.vue"; import RemoteStatusItem from "./vcs/remote/RemoteStatusItem.vue"; @@ -31,6 +33,7 @@ const label = computed(() => { > {{ label }} + diff --git a/ui/src/components/deploy/DeployStatusItem.vue b/ui/src/components/deploy/DeployStatusItem.vue new file mode 100644 index 0000000..d672b92 --- /dev/null +++ b/ui/src/components/deploy/DeployStatusItem.vue @@ -0,0 +1,233 @@ + + + + + diff --git a/ui/src/components/deploy/DeploymentDialog.vue b/ui/src/components/deploy/DeploymentDialog.vue new file mode 100644 index 0000000..50871bc --- /dev/null +++ b/ui/src/components/deploy/DeploymentDialog.vue @@ -0,0 +1,867 @@ + + +