M4.10: remotes: fetch, pull, push, clone and manage remotes
Owner decision D23: Lutra runs fetch, pull (merge or rebase per the new git.pull.mode setting), push (upstream set on the first push) and clone through the user's git. Any HTTPS or SSH server works; sign-in stays with git's credential helper (its own window is allowed for network calls only) and the ssh agent. Terminal prompts stay off, ext:: is refused, and URL userinfo is redacted in every message, progress line and remote listing. - vcs: Call::network with a 30 min timeout, a stderr progress sink and a Cancel flag that kills git's process group; remote.rs with clone_repo, fetch, pull, push (--porcelain rejections), remotes and add/set-url/ remove; explained refusals (rejected push, sign-in, host key, not found, unreachable, no upstream, local changes, conflicts). - engine: git.fetch/pull/push/clone/cancel/remotes/remoteAdd/remoteSetUrl/ remoteRemove, one network call at a time, gitProgress events, gitChanged after changes. - ui: status-bar progress with Cancel and ahead/behind, vcs.fetch/pull/ push/clone/manageRemotes (Git menu, no default shortcuts), Clone Repository and Manage Remotes dialogs; desktop pick_dir IPC. - Tests against local bare repositories only (vcs 8, engine 3, Vitest 11) plus unit and property tests; docs updated. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
parent
48b892a6d5
commit
d097558ba5
36 changed files with 4426 additions and 45 deletions
|
|
@ -1,6 +1,6 @@
|
|||
# Architecture
|
||||
|
||||
> **Status:** M0 decisions recorded, M1 workspace, desktop bridge, tabs and editor, message catalog, engine construction, settings, themes, the recovery journal, notifications, UI commands, the palette, the settings dialog, the app icon and the syntax layer documented; M2 highlighting and `editor.reveal`, plus the search backend, the Find tool window, the symbol index, the Structure tool window and the go-to popup; M3 CLI and single instance, LSP client library, toolchain (PHP detection, Phpactor download), the app menu, MCP server, autosave and `flushDirty`, integrated terminal; engine ↔ Phpactor wiring and diagnostics (M3.3), pending outcomes (M3.5), completion, hover and signature help (M3.4); C5 child process groups (H1), settings dialog string and path controls and assist settings (H4), the banner-aligned themes and diagnostic/VCS tokens (H5), Phpactor UX: fast tick, messages, progress, `php -l` (H3); Git backend (M4.1), Changes tool window (M4.2); line changes, gutter markers and status colours (M4.4), diff viewer (M4.3), branches (M4.5) · **Last updated:** 2026-10-26
|
||||
> **Status:** M0 decisions recorded, M1 workspace, desktop bridge, tabs and editor, message catalog, engine construction, settings, themes, the recovery journal, notifications, UI commands, the palette, the settings dialog, the app icon and the syntax layer documented; M2 highlighting and `editor.reveal`, plus the search backend, the Find tool window, the symbol index, the Structure tool window and the go-to popup; M3 CLI and single instance, LSP client library, toolchain (PHP detection, Phpactor download), the app menu, MCP server, autosave and `flushDirty`, integrated terminal; engine ↔ Phpactor wiring and diagnostics (M3.3), pending outcomes (M3.5), completion, hover and signature help (M3.4); C5 child process groups (H1), settings dialog string and path controls and assist settings (H4), the banner-aligned themes and diagnostic/VCS tokens (H5), Phpactor UX: fast tick, messages, progress, `php -l` (H3); Git backend (M4.1), Changes tool window (M4.2); line changes, gutter markers and status colours (M4.4), diff viewer (M4.3), branches (M4.5); remotes: fetch, pull, push, clone and remote management (M4.10) · **Last updated:** 2026-10-28
|
||||
|
||||
## Overview
|
||||
|
||||
|
|
@ -561,7 +561,7 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
|
|||
|
||||
### Git backend (M4.1)
|
||||
|
||||
- **Owner decision D20:** Git runs through the user's installed `git` (minimum 2.30), found through the setting `git.executable` (string, section `git`; `""` means `git` from `PATH`). No network operation exists (no fetch, pull, push), and no call can open a credential or terminal prompt.
|
||||
- **Owner decision D20:** Git runs through the user's installed `git` (minimum 2.30), found through the setting `git.executable` (string, section `git`; `""` means `git` from `PATH`). No call can open a terminal prompt. Network calls (fetch, pull, push, clone) came with M4.10 under D23; see Remotes (M4.10).
|
||||
- **Crate `lutra-vcs` (L3, `crates/vcs`):**
|
||||
- `runner::run` is the only way git starts, and `runner::spawn` the only place a process starts, through H1's `lutra_proc::spawn`, so git and its hooks die with Lutra. Arguments are an array, never a shell. Every call gets `--no-pager --literal-pathspecs -c core.quotepath=false -c color.ui=false`, `GIT_TERMINAL_PROMPT=0`, `GCM_INTERACTIVE=never`, `GIT_OPTIONAL_LOCKS=0` for reads, no console window on Windows, and the variables that redirect git (`GIT_DIR`, `GIT_WORK_TREE`, `GIT_INDEX_FILE`, …) removed.
|
||||
- Timeouts: 30 s; commit, checkout and branch creation 120 s (hooks). A call past its timeout, or whose stdout passes its cap, is killed (a guard kills and reaps the child on every early return).
|
||||
|
|
@ -660,6 +660,43 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
|
|||
- **Commands** (UI commands, menu group Git, no default shortcuts): `vcs.branches` (Git › Branches…), `vcs.newBranch {name?, checkout?}` (Git › New Branch…; with a `name` it creates the branch without the popup, checked out unless `checkout: false`, and toasts a refusal), `vcs.checkout {branch}` (without `branch`, as from the palette, it opens the popup; a `branch` that is no non-blank string toasts an error). All are enabled while `git.branches` is (an open project).
|
||||
- **Tests:** `ui/tests/vcs/Branches.test.ts` (16 Vitest tests against a fake engine: parsing, filter, head label, the item's states, popup order and marking, filtering, keyboard, checkout after `flushDirty` through `runWaiting`, a refusal toast, a cancelled checkout, creating with a blank name, a refusal and success, Escape back to the list, the commands' registration, params and enabled state).
|
||||
|
||||
### Remotes (M4.10)
|
||||
|
||||
- **Owner decision D23 (2026-10-26):** Lutra may fetch, pull, push and clone through the user's git. Any HTTPS or SSH remote works (GitHub, GitLab, Forgejo, Bitbucket, a self-hosted server), and so does a local path, because git does the transport.
|
||||
- **Credentials stay with git.** HTTPS sign-in goes through git's credential helper. It may show its own window, such as Git Credential Manager's: network calls do not set `GCM_INTERACTIVE=never`, every other call still does. SSH remotes use the user's `ssh` with its agent and keys, `~/.ssh/config` and `known_hosts`; Lutra sets no `GIT_SSH_COMMAND` and touches no key. Terminal prompts stay off (`GIT_TERMINAL_PROMPT=0`, stdin closed, no console). A remote that needs a password nobody supplies, a passphrase key without an agent, or an unknown host key therefore fails with a message instead of hanging. Lutra never reads, stores or logs a credential.
|
||||
- **Redaction:** `runner::redact_urls` replaces the userinfo of every `scheme://user:secret@host` URL with `***` (`https://***@host/…`). It applies to every runner error message (`Output::message`), every progress line, and the URLs `git.remotes` returns. scp-like addresses (`git@host:path`) carry only a user name and stay as they are. Unit and property tests cover it.
|
||||
- **Crate (`crates/vcs/src/remote.rs`, plus the runner):**
|
||||
- `Call::network(cwd, args)`: a 30-minute timeout (`NETWORK_TIMEOUT`), a progress sink (stderr split at `\r`/`\n`, 1 KiB per line) and a `Cancel` flag. The runner polls the flag every 50 ms. When it is set, git and every process it started (`git-remote-https`, `ssh`, hooks) are killed through the `lutra_proc` group, and the call ends with `VcsError::Cancelled`.
|
||||
- Every network call runs with `-c protocol.ext.allow=never`, and `check_url` refuses `ext::` URLs, blank URLs, URLs starting with `-`, control characters and anything over 4,096 bytes. Remote names are checked for `-`, whitespace and control characters; git checks the rest. Arguments follow `--end-of-options`.
|
||||
- `Git::clone_repo(url, dir, net)` needs no repository. It runs `git clone --progress` in the parent folder, which must exist; `dir` must be absolute and missing or empty. A failed or cancelled clone removes what it left: the folder if the clone created it, else only its contents.
|
||||
- `Repo::fetch(remote?)`: `fetch --progress <remote>`, or `--all`. `Repo::pull(mode)`: `pull --progress --no-rebase --no-edit` or `--rebase`. `Repo::push(remote?)`: the current branch with `--porcelain`. With an upstream (`branch.<b>.remote` and `.merge`) it goes there as `refs/heads/<b>:<merge>`. Without one it goes to `<remote>` (the given one, else the only remote, else `origin`) as `refs/heads/<b>:refs/heads/<b>` with `--set-upstream`. Rejected refs (`!` lines) fail the push even if the exit status says otherwise.
|
||||
- `Repo::remotes()` reads `config -z --get-regexp ^remote\..*\.(url|pushurl)$` in config order. `remote_add`, `remote_set_url` and `remote_remove` run `git remote …`. Changes hold the repository's mutation lock.
|
||||
- **Clear messages:** `explain` puts one sentence before git's own text when the cause is known: a rejected push (pull first), a push the server refused (protected branch, hook), an unknown SSH host key, a failed sign-in (pointing at the credential helper and the ssh agent), a repository not found, a remote that cannot be reached, no upstream, local changes in the way, conflicts after a pull, diverged branches, a full clone target.
|
||||
- **Engine (`crates/engine/src/cmd/git_remote.rs`):** pending outcomes on `lutra-git-remote` threads, which detect git and open the repository for each call. `git.clone` needs no project.
|
||||
- `git.fetch {remote?}` → `{}`.
|
||||
- `git.pull {mode?: merge|rebase}` → `{}`; the default comes from the setting `git.pull.mode` (enum `merge`|`rebase`, default `merge`, section Git).
|
||||
- `git.push {remote?}` → `{remote, branch, upstreamSet}`.
|
||||
- `git.clone {url, dir}` → `{root}`.
|
||||
- `git.remotes` → `{remotes: [{name, fetchUrl?, pushUrl?}]}`.
|
||||
- `git.remoteAdd {name, url}`, `git.remoteSetUrl {name, url}`, `git.remoteRemove {name}` → `{}`.
|
||||
- `git.cancel` (immediate) → `{cancelled: true}`; disabled while nothing runs.
|
||||
- Bad URLs, names, modes and relative clone folders are `invalid_params`; git's refusals are `failed` with the explained text.
|
||||
- One network call runs at a time; a second is refused while one runs.
|
||||
- **Event `gitProgress {active, operation?, phase?, percent?}`:** sent from the pump when the running call's latest line changed (at most once per pump). `active: false` follows when the call ends; when the call failed, it arrives with the next pump. `gitChanged` follows every successful change in the open project.
|
||||
- **UI (`ui/src/components/vcs/remote/`):**
|
||||
- `remote.ts` is the Pinia store.
|
||||
- `RemoteStatusItem.vue` goes in the status bar, before the branch item. While a call runs it shows "Fetching: Receiving objects 45%" with a Cancel button (`git.cancel`). Otherwise it shows `↑ahead ↓behind` against the upstream from the shared status store, hidden when in step. The item supplies the UI commands and mounts the dialogs.
|
||||
- `vcs.fetch`, `vcs.pull` and `vcs.push` (Git › Fetch / Pull / Push) end in a toast: done, cancelled, or git's explained refusal. Pull runs `flushDirty()` first and cancels when a save fails. Push says when it set the upstream.
|
||||
- `vcs.clone` (Git › Clone Repository…, also without a project) opens a dialog with a URL field and a folder field. "Browse…" uses the new `pick_dir` IPC, the shell's native folder picker. The folder is the chosen parent plus the repository's name and follows URL edits until it is typed by hand. Clone runs `git.clone`, then `project.open`. git's refusal stays in the dialog. Cancel stops a running clone.
|
||||
- `vcs.manageRemotes` (Git › Manage Remotes…) lists the remotes with redacted URLs and a separate push URL. Each row offers "Edit URL" (the field starts empty when the URL is redacted, so `***` is never saved) and "Remove" (asked in the row). A form adds a remote. Refusals show in the dialog.
|
||||
- Both dialogs are exclusive modals (`clone`, `remotes`).
|
||||
- No default shortcuts. Commands are enabled with a project (clone always) and while no network call runs.
|
||||
- **Tests:**
|
||||
- `crates/vcs/tests/remote.rs`: 8 tests against local bare repositories, never the network. Clone with progress; a full or missing target and clean-up; a cancelled clone; push with and without upstream; a rejected push; fetch and pull by merge and rebase; pull without upstream; remote management with redacted URLs; cancel of a running push held by a sleeping `pre-receive` hook, which stops in well under 10 s.
|
||||
- Unit and property tests of the redaction, the progress lines, `explain`, the URL and name checks, and the parsers.
|
||||
- `crates/engine/tests/git_remote.rs`: 3 tests. Clone without a project, remotes, push with upstream and `gitChanged`, fetch and pull; cancel and the one-call rule; bad params.
|
||||
- `ui/tests/vcs/Remote.test.ts`: 11 Vitest tests.
|
||||
|
||||
## Decisions (M0)
|
||||
|
||||
| Question | Decision | Why |
|
||||
|
|
@ -678,6 +715,7 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
|
|||
| Date | Change | Summary |
|
||||
|---|---|---|
|
||||
| 2026-10-28 | minor | M4.6: history backend (`git.log`, `git.showCommit`, `git.showAt`), the shared hook for new git commands, the Log tab, diffs at a commit |
|
||||
| 2026-10-28 | minor | M4.10: remotes (`Call::network` with progress and cancel, URL redaction, `git.fetch/pull/push/clone/cancel/remotes/remoteAdd/remoteSetUrl/remoteRemove`, `gitProgress`, `git.pull.mode`, the clone and remotes dialogs) |
|
||||
| 2026-10-27 | minor | F3: `lutra_proc::spawn_suspended` (Phpactor) and `adopt` (ConPTY shell in a job), cancel superseded completions, syntax proptests compare leaf kinds |
|
||||
| 2026-10-27 | minor | C6 F1: remote branch checkout without a configured remote (`--no-track`), `git.lastMessage` and the Amend prefill, one shared git status store |
|
||||
| 2026-10-27 | minor | F2: `ui.screenshot` through WebView2 `CapturePreview` without focus; region fallback elsewhere; `--control` windows open unfocused |
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue