turbo-editors/turbo-core · 22712c7

added .memory/handoffs/2026-09-29-ssh-remote-editing.md +39 -0 Viewed

new file mode 100644
@@ -0,0 +1,39 @@
	1	+# Handoff — 2026-09-29 — remote editing over ssh (`-ssh`)
	2	+
	3	+## State
	4	+
	5	+turbo-core has `fsys` (the one door to project files), `remote` (ssh ControlMaster + SFTP + remote shell/tool argv) and `app.UseRemote`. All six editors wire `-ssh`/`--ssh` in `main.go`. `go test ./...` green here; everything verified against a real sshd (Docker demo in `../demo-remote-machine`) including a password login driven in a pty. Uncommitted, on `main`, unreleased.
	6	+
	7	+## In flight
	8	+
	9	+Nothing half-written. The feature is complete for the agreed scope; what remains is release work.
	10	+
	11	+## Next steps
	12	+
	13	+1. Run the quality gate (`python3 ../.claude/skills/quality/scripts/quality_report.py --workspace .` — note the path; `qlty` must be installed, it was not in this sandbox).
	14	+2. Commit, set `release.env` to `v1.0.5`, run `./01-release.tag.sh`.
	15	+3. In each editor, remove the workspace and `go get rickub.com/turbo-editors/turbo-core@v1.0.5 && go mod tidy && GOWORK=off make check` — their two `TestTheTagScript*` tests go green only then.
	16	+4. Try it from macOS against a real server (never done): the control socket path shortening (`/tmp` when `os.TempDir()` > 60 bytes) is the macOS-specific part.
	17	+
	18	+## Open questions / blockers
	19	+
	20	+- LSP over ssh was deliberately left out (user's scope choice). If wanted later: run the server via `session.RunCommand(dir, server, false)` stdio and translate `file://` URIs — the paths are already remote-absolute, so maybe only the root needs care.
	21	+- Agents over ssh likewise off; ACP agents would need to run remotely too.
	22	+- No reconnect if the master dies mid-session (laptop sleep): saves fail with the SFTP error. Worth a ticket.
	23	+
	24	+## Watch out for
	25	+
	26	+- `remote` does not import `fsys`; its `FS` satisfies the interface structurally. Keep it that way (no cycle risk, but the diagram and packages reference say so).
	27	+- `pkg/sftp` test server: close the server first then the client in cleanup, or `client.Close` hangs waiting for the reader goroutine.
	28	+- A test that swaps `fsys.Use` must restore it (`t.Cleanup(func(){ fsys.Use(previous) })`) and must not run in parallel.
	29	+- `app/remote_test.go`'s fake remote echoes the directory; a long temp path wraps in the 80-column simulation screen — assert on a prefix.
	30	+- `go install golang.org/x/tools/cmd/goimports@latest` was used for import fixing (in `~/go/bin`), not a project tool.
	31	+
	32	+## Follow-up discussion (same day) — why LSP and agents are off over ssh, and the way to turn them on
	33	+
	34	+The user asked why a local language server / agent cannot work on remote files. Answer given, and the recommended next feature:
	35	+
	36	+- Local LSP on remote files is wrong, not merely missing: servers read the project from disk by path (pylsp/jedi → the remote virtualenv's site-packages; gopls → go.mod, module graph, module cache; rust-analyzer → `cargo metadata`, crates). `file:///home/bob/…` does not exist on the Mac → at best single-buffer completion, at worst "module not found" diagnostics everywhere.
	37	+- Local agent on remote code is dangerous: agents act with their own tools (docker agent never uses ACP `fs/`), start in the local* cwd, run shell commands locally, and could write local files believing they edit the project.
	38	+- The right design for both is to run them on the remote machine over the shared connection — both protocols are stdio: `ssh -S <sock> -T dest "cd DIR && exec pylsp"` / `… exec docker agent serve acp …`. Paths are already remote-absolute (fsys), so URIs match. To do for LSP: stop resolving the server executable on the local disk (`lsp/server.go` `os.Stat` of `Server.Dirs`), make `lsp/uri.go` stop calling local `filepath.Abs`/`EvalSymlinks` on remote paths, start the process via `Remote.RunCommand`-style argv; server must be installed remotely (install hint as today). For agents: same launch; route `readForAgent`/`writeForAgent` (`os.ReadFile`/`os.WriteFile` in `app/agents.go`) and `projectRoot()` (`os.Getwd`) through fsys; the model endpoint may be on the Mac's localhost → needs `ssh -R` reverse forward.
	39	+- Recommended order: remote LSP first (most useful, least work). The user has not yet said yes — ask at the start of the next session.

++# Handoff — 2026-09-29 — remote editing over ssh (`-ssh`)
++
++## State
++
++turbo-core has `fsys` (the one door to project files), `remote` (ssh ControlMaster + SFTP + remote shell/tool argv) and `app.UseRemote`. All six editors wire `-ssh`/`--ssh` in `main.go`. `go test ./...` green here; everything verified against a real sshd (Docker demo in `../demo-remote-machine`) including a password login driven in a pty. Uncommitted, on `main`, unreleased.
++
++## In flight
++
++Nothing half-written. The feature is complete for the agreed scope; what remains is release work.
++
++## Next steps
++
++1. Run the quality gate (`python3 ../.claude/skills/quality/scripts/quality_report.py --workspace .` — note the path; `qlty` must be installed, it was not in this sandbox).
++2. Commit, set `release.env` to `v1.0.5`, run `./01-release.tag.sh`.
++3. In each editor, remove the workspace and `go get rickub.com/turbo-editors/turbo-core@v1.0.5 && go mod tidy && GOWORK=off make check` — their two `TestTheTagScript*` tests go green only then.
++4. Try it from macOS against a real server (never done): the control socket path shortening (`/tmp` when `os.TempDir()` > 60 bytes) is the macOS-specific part.
++
++## Open questions / blockers
++
++- **LSP over ssh** was deliberately left out (user's scope choice). If wanted later: run the server via `session.RunCommand(dir, server, false)` stdio and translate `file://` URIs — the paths are already remote-absolute, so maybe only the root needs care.
++- **Agents over ssh** likewise off; ACP agents would need to run remotely too.
++- **No reconnect** if the master dies mid-session (laptop sleep): saves fail with the SFTP error. Worth a ticket.
++
++## Watch out for
++
++- `remote` does **not** import `fsys`; its `FS` satisfies the interface structurally. Keep it that way (no cycle risk, but the diagram and packages reference say so).
++- `pkg/sftp` test server: close the **server first** then the client in cleanup, or `client.Close` hangs waiting for the reader goroutine.
++- A test that swaps `fsys.Use` must restore it (`t.Cleanup(func(){ fsys.Use(previous) })`) and must not run in parallel.
++- `app/remote_test.go`'s fake remote echoes the directory; a long temp path wraps in the 80-column simulation screen — assert on a prefix.
++- `go install golang.org/x/tools/cmd/goimports@latest` was used for import fixing (in `~/go/bin`), not a project tool.
++
++## Follow-up discussion (same day) — why LSP and agents are off over ssh, and the way to turn them on
++
++The user asked why a *local* language server / agent cannot work on remote files. Answer given, and the recommended next feature:
++
++- **Local LSP on remote files is wrong, not merely missing**: servers read the project from disk by path (pylsp/jedi → the remote virtualenv's site-packages; gopls → go.mod, module graph, module cache; rust-analyzer → `cargo metadata`, crates). `file:///home/bob/…` does not exist on the Mac → at best single-buffer completion, at worst "module not found" diagnostics everywhere.
++- **Local agent on remote code is dangerous**: agents act with their own tools (docker agent never uses ACP `fs/*`), start in the *local* cwd, run shell commands locally, and could write local files believing they edit the project.
++- **The right design for both is to run them on the remote machine over the shared connection** — both protocols are stdio: `ssh -S <sock> -T dest "cd DIR && exec pylsp"` / `… exec docker agent serve acp …`. Paths are already remote-absolute (fsys), so URIs match. To do for LSP: stop resolving the server executable on the local disk (`lsp/server.go` `os.Stat` of `Server.Dirs`), make `lsp/uri.go` stop calling local `filepath.Abs`/`EvalSymlinks` on remote paths, start the process via `Remote.RunCommand`-style argv; server must be installed remotely (install hint as today). For agents: same launch; route `readForAgent`/`writeForAgent` (`os.ReadFile`/`os.WriteFile` in `app/agents.go`) and `projectRoot()` (`os.Getwd`) through fsys; the model endpoint may be on the Mac's localhost → needs `ssh -R` reverse forward.
++- **Recommended order: remote LSP first** (most useful, least work). The user has not yet said yes — ask at the start of the next session.

modified .memory/history.md +12 -0 Viewed

@@ -335,3 +335,15 @@
335	335	- Tests: 20 new in `terminal`, 5 in `app` (both round trips, Edit ▸ Copy/Paste, bracketed paste from outside, highlight). `make check` green, `-race` green on `app`+`terminal`. Falsified: removing the terminal branch from `App.Copy` turned `TestEditCopyAndPasteReachTheTerminalInFront` red. Quality #39 PASS after the code, #40 PASS after the READMEs.
336	336	- Docs: `terminal/README.md`, `app/README.md`, `docs/{en,fr}/reference/app.md` here; in all six editors (EN+FR): `how-to/use-a-terminal.md` (new section), `reference/terminal.md` (finished-window paragraph, keys table, mouse table, new "Copying and pasting" table, mode 2004 row, "not implemented" list, colours table), `reference/keyboard.md` (terminal and mouse rows), `explanation/terminal-windows.md` (new section). Applied by one anchored script; every anchor matched once in every editor.
337	337	- Not done: not committed, not tagged (v1.0.4 still pending along with #30 and #31 from the previous session); not tried in a real terminal by hand; no ticket was opened for it. Noted for the user: the AsciiDoc work of the previous session was still uncommitted when this started, and this sits on top of it.
	338	+
	339	+## 2026-09-29 — Remote editing over ssh: `fsys`, `remote`, `app.UseRemote` (ticket #33)
	340	+
	341	+- Asked (umbrella session, `/methodical-dev`): `turbo-python -ssh user@machine` / `--ssh`, to edit files on a remote machine; then extended by the user to all six editors; plus a Docker Compose "remote machine" in `turbo-editors/demo-remote-machine` testable with a password. User chose: the system `ssh` with ControlMaster (after an explanation of it vs `x/crypto/ssh`), SFTP via `github.com/pkg/sftp` (vs a hand-written SFTP client or shell commands), scope files + tree + terminals + tools, agents disabled, LSP off, `user@machine[:path]`, stay on `main`, no stops between steps ("va au bout du bout").
	342	+- Changes: new `fsys/` (`FS`, `Local`, `Use`, `Current`, `IsLocal`, `Abs`, package funcs) and `fsys/fsystest/` (`Memory`); new `remote/` (`target.go`, `session.go`, `files.go`); `app/remote.go` (`Remote`, `UseRemote`, `Remote()`, `refuseAgentsOverSSH`, `connectionStatus`); `app/terminals.go` (`shellOptions`, `commandOptions`), `app/toolchain.go` (`startTool`), `app/agents.go` + `app/menus.go` (agents refused remotely), `app/app.go` (`remote` field, status); `tools/run.go` (`StartProgram`, shared `start`) + `programAttributes` per platform; `os.` → `fsys.` in buffer, projectfile, settings, snippets (project file only), tools, filetree and ten `app` files. `go.mod`: `github.com/pkg/sftp v1.13.11` (x/sys → v0.47.0, x/term, x/text bumped by MVS; `x/crypto`, `kr/fs` indirect).
	343	+- Bug found and fixed on the way: `Session.Close` would hang if the SFTP channel's process started but never spoke SFTP (no client to close its stdin) — now killed; test `TestAChannelThatNeverSpeaksSFTPIsReportedAndCloseDoesNotHang`.
	344	+- Tests: `fsys` (7 + example), `fsystest` (4), `remote` (21: target parsing incl. option-injection refusal, FS against pkg/sftp's real server over pipes, Connect/Close end to end with the test binary as a fake ssh, command lines, quoting, `Open`), `remote/integration_test.go` (real sshd, skipped without `TURBO_CORE_SSH_KEY` — passed against the demo container), routing tests `fsys_test.go` in buffer (4), projectfile, settings, tools, filetree, snippets, app (3), `app/remote_test.go` (7), `tools/program_test.go` (3). `go test ./...` green.
	345	+- Verified end to end: `turbo-python -ssh` in a pty with password auth against the demo container (see summary).
	346	+- Quality: gate not run — `qlty` absent from this sandbox; the skill forbids installing it by hand. `gofmt -l` and `go vet ./...` clean.
	347	+- Docs (EN+FR): new `reference/fsys.md`, `reference/remote.md`, `how-to/add-remote-editing.md`, `explanation/remote-editing.md`; updated `reference/packages.md`, `reference/app.md`, `explanation/architecture.md`, `how-to/run-the-tests.md`, both indexes, root `README.md`; package READMEs `fsys/`, `remote/` new, app/tools/buffer/projectfile/filetree/settings/snippets updated; `docs/diagrams/packages.drawio` regenerated from `go list` (it had drifted before this session).
	348	+- Not done: nothing committed or tagged; v1.0.5 not released.
	349	+- Later, same session: the user asked why LSP and agents are off over ssh; explained that a local server/agent on remote files is wrong (they read/act on their own disk by path), and that the fix is to run them remotely over the ControlMaster connection (both are stdio). Proposed remote LSP first; awaiting the user's go-ahead. Details and the files to change in the handoff `2026-09-29-ssh-remote-editing.md`. No code changed.

  - **Tests**: 20 new in `terminal`, 5 in `app` (both round trips, Edit ▸ Copy/Paste, bracketed paste from outside, highlight). `make check` green, `-race` green on `app`+`terminal`. Falsified: removing the terminal branch from `App.Copy` turned `TestEditCopyAndPasteReachTheTerminalInFront` red. Quality #39 PASS after the code, #40 PASS after the READMEs.
  - **Docs**: `terminal/README.md`, `app/README.md`, `docs/{en,fr}/reference/app.md` here; in **all six editors** (EN+FR): `how-to/use-a-terminal.md` (new section), `reference/terminal.md` (finished-window paragraph, keys table, mouse table, new "Copying and pasting" table, mode 2004 row, "not implemented" list, colours table), `reference/keyboard.md` (terminal and mouse rows), `explanation/terminal-windows.md` (new section). Applied by one anchored script; every anchor matched once in every editor.
  - **Not done**: not committed, not tagged (v1.0.4 still pending along with #30 and #31 from the previous session); not tried in a real terminal by hand; no ticket was opened for it. Noted for the user: the AsciiDoc work of the previous session was still uncommitted when this started, and this sits on top of it.
++
++## 2026-09-29 — Remote editing over ssh: `fsys`, `remote`, `app.UseRemote` (ticket #33)
++
++- **Asked** (umbrella session, `/methodical-dev`): `turbo-python -ssh user@machine` / `--ssh`, to edit files on a remote machine; then extended by the user to all six editors; plus a Docker Compose "remote machine" in `turbo-editors/demo-remote-machine` testable with a password. User chose: the system `ssh` with ControlMaster (after an explanation of it vs `x/crypto/ssh`), SFTP via `github.com/pkg/sftp` (vs a hand-written SFTP client or shell commands), scope files + tree + terminals + tools, agents disabled, LSP off, `user@machine[:path]`, stay on `main`, no stops between steps ("va au bout du bout").
++- **Changes**: new `fsys/` (`FS`, `Local`, `Use`, `Current`, `IsLocal`, `Abs`, package funcs) and `fsys/fsystest/` (`Memory`); new `remote/` (`target.go`, `session.go`, `files.go`); `app/remote.go` (`Remote`, `UseRemote`, `Remote()`, `refuseAgentsOverSSH`, `connectionStatus`); `app/terminals.go` (`shellOptions`, `commandOptions`), `app/toolchain.go` (`startTool`), `app/agents.go` + `app/menus.go` (agents refused remotely), `app/app.go` (`remote` field, status); `tools/run.go` (`StartProgram`, shared `start`) + `programAttributes` per platform; `os.*` → `fsys.*` in buffer, projectfile, settings, snippets (project file only), tools, filetree and ten `app` files. `go.mod`: `github.com/pkg/sftp v1.13.11` (x/sys → v0.47.0, x/term, x/text bumped by MVS; `x/crypto`, `kr/fs` indirect).
++- **Bug found and fixed on the way**: `Session.Close` would hang if the SFTP channel's process started but never spoke SFTP (no client to close its stdin) — now killed; test `TestAChannelThatNeverSpeaksSFTPIsReportedAndCloseDoesNotHang`.
++- **Tests**: `fsys` (7 + example), `fsystest` (4), `remote` (21: target parsing incl. option-injection refusal, FS against pkg/sftp's real server over pipes, Connect/Close end to end with the test binary as a fake ssh, command lines, quoting, `Open`), `remote/integration_test.go` (real sshd, skipped without `TURBO_CORE_SSH_KEY` — passed against the demo container), routing tests `fsys_test.go` in buffer (4), projectfile, settings, tools, filetree, snippets, app (3), `app/remote_test.go` (7), `tools/program_test.go` (3). `go test ./...` green.
++- **Verified end to end**: `turbo-python -ssh` in a pty with password auth against the demo container (see summary).
++- **Quality**: gate **not run** — `qlty` absent from this sandbox; the skill forbids installing it by hand. `gofmt -l` and `go vet ./...` clean.
++- **Docs** (EN+FR): new `reference/fsys.md`, `reference/remote.md`, `how-to/add-remote-editing.md`, `explanation/remote-editing.md`; updated `reference/packages.md`, `reference/app.md`, `explanation/architecture.md`, `how-to/run-the-tests.md`, both indexes, root `README.md`; package READMEs `fsys/`, `remote/` new, app/tools/buffer/projectfile/filetree/settings/snippets updated; `docs/diagrams/packages.drawio` regenerated from `go list` (it had drifted before this session).
++- **Not done**: nothing committed or tagged; v1.0.5 not released.
++- **Later, same session**: the user asked why LSP and agents are off over ssh; explained that a *local* server/agent on remote files is wrong (they read/act on their own disk by path), and that the fix is to run them *remotely* over the ControlMaster connection (both are stdio). Proposed remote LSP first; awaiting the user's go-ahead. Details and the files to change in the handoff `2026-09-29-ssh-remote-editing.md`. No code changed.

modified .memory/summary.md +22 -4 Viewed

@@ -14,10 +14,13 @@ Extracted from turbo-go on 2026-09-01, at the point a second editor was wanted.
14	14
15	15	## Architecture
16	16
17		-Nineteen packages. Dependencies run strictly downwards, no cycles, and no interface indirection introduced to prevent one.
	17	+Twenty-two packages (counting the root `main` that holds only `release_test.go`). Dependencies run strictly downwards, no cycles, and no interface indirection introduced to prevent one.
18	18
19	19	```
20		-app → {editor, ui, lsp, acp, buffer, terminal, filetree, settings, snippets, tools, syntax, theme, profile, version}
	20	+app → {editor, ui, lsp, acp, buffer, terminal, filetree, settings, snippets, tools, syntax, theme, profile, version, fsys}
	21	+ remote → github.com/pkg/sftp ← execs ssh; its FS satisfies fsys.FS without importing fsys
	22	+ buffer │ projectfile │ filetree │ settings │ snippets │ tools → fsys (+ what is listed)
	23	+ fsys → stdlib only
21	24	editor → {buffer, syntax, ui, theme}
22	25	terminal → {ui, theme, tcell, golang.org/x/sys}
23	26	filetree → {ui, theme, tcell}
@@ -34,8 +37,10 @@ app → {editor, ui, lsp, acp, buffer, terminal, filetree, settings, snippets, t
34	37	\| Package \| What it holds \| Depends on \|
35	38	\| --- \| --- \| --- \|
36	39	\| `profile` \| The editor's identity: name, slug, language, tools menu, root markers, server, templates — and every path derived from the slug \| stdlib only \|
37		-\| `buffer` \| Text of one file: lines of runes, cursor, selection, undo, search, load/save \| stdlib only \|
38		-\| `projectfile` \| Atomic writes of a project's own TOML files \| stdlib only \|
	40	+\| `buffer` \| Text of one file: lines of runes, cursor, selection, undo, search, load/save \| `fsys` \|
	41	+\| `projectfile` \| Atomic writes of a project's own TOML files \| `fsys` \|
	42	+\| `fsys` \| The one door to the project's files (package-level `Use`, default `Local{}`); `fsys/fsystest.Memory` for tests \| stdlib only \|
	43	+\| `remote` \| `-ssh`: ControlMaster login via the `ssh` command, files over SFTP, argv of remote shells/tools \| `github.com/pkg/sftp`, the `ssh` command \|
39	44	\| `configrepo` \| A shared `.turbo-<slug>` fetched from a forge URL by a shallow git clone (`-load-config`) \| `projectfile`, `profile`, the `git` command \|
40	45	\| `version` \| What build of itself the binary is: linker stamp, then Go build info \| stdlib only \|
41	46	\| `lsp` \| LSP framing, JSON-RPC 2.0, the child process \| `profile` \|
@@ -145,6 +150,8 @@ The decisions inherited from turbo-go about the editor's behaviour — the eve
145	150
146	151	- Text is copied out of a terminal window and pasted into it (2026-09-21, v1.0.4). `terminal/view_select.go`. The keys are the editor's other spelling of copy and paste — `Ctrl-Ins` / `Shift-Ins` — because `Ctrl-C` and `Ctrl-V` are the shell's; both are claimed even when they do nothing, since sent through either arrives as a plain `Insert`. The selection is two `Point`s of the whole text (history index + live rows), which is what keeps it on the same text while the shell writes below it — a line scrolling off the top keeps its index. Mouse selects by cell (drag clamped to the window's edge); `Shift-↑`/`Shift-↓` select whole lines from the shell's cursor row and turn a mouse selection into whole lines (one rule, not two). Trailing blanks are trimmed only from a line selected to its right edge. A click drops the selection; output, scrolling and typing keep it. Highlight is `editor.selection`, no new theme key (the acp view does the same). Copy goes through `App.copyToClipboards` (renamed from `copyFromAgent`): editor clipboard + OSC 52 + `Copied N lines`. `Paste` turns `\n` into `\r` and, when the screen says mode 2004 is on, wraps in `ESC[200~`…`ESC[201~` — the emulator now remembers 2004 (`Screen.BracketedPaste`), which is the one place its boundary moved; it still never pastes by itself. `App.Copy`/`App.Paste` route to a terminal in front; `handlePaste` hands a bracketed paste from the outer terminal to a terminal window whole, as it already did for an agent window. A finished terminal still selects and copies (the keys run before the `Exited` check) but `Paste` returns false. `OnCopy`/`OnPaste` are exported fields, unlike `OnChange`/`OnExit`: only the event loop calls them, so no goroutine reads them. Accepted edge: when the scrollback is full (2000 lines), each trimmed line shifts a held selection up by one — dropped on the next click anyway. Rejected: Escape to drop the selection (vim needs Escape); `Shift-Home`/`End` (not needed yet); a `terminal.selection` theme key (nine TOML files for no visible gain). Tests: 20 in `terminal/view_select_test.go`, 5 in `app/terminal_clipboard_test.go` (round trip both ways, menu actions, bracketed paste, highlight).
147	152
	153	+- Remote editing over ssh drives the `ssh` command, shares one ControlMaster connection, and moves files over SFTP (2026-09-29, unreleased, ticket #33). New `fsys` (package-level `Use(FS)`, same argument as `syntax.Register`) is now the only way `buffer`, `projectfile`, `settings`, `snippets` (project file only — the user's stays `os`), `tools`, `filetree` and `app` touch project files; themes, the user's snippets, `lsp`, `acp` and `configrepo` stay on `os` on purpose. New `remote`: `ParseTarget` (`[user@]host[:path]`, scp-style, no port — use `~/.ssh/config`; refuses a leading `-`), `Connect` runs `ssh -o ControlMaster=yes -o ControlPersist=60 -N -f` in the foreground before tcell takes the screen (password prompt there), then everything with `-S sock -o ControlMaster=no -o BatchMode=yes`: one `ssh -s … sftp` channel (`github.com/pkg/sftp` v1.13.11 — the only new dependency; it forced `golang.org/x/sys` v0.38→v0.47 by MVS), shells `ssh -t … "exec /bin/sh -c 'cd DIR && exec \"${SHELL:-/bin/sh}\" -l'"`, tools `-T`/`-t … "exec /bin/sh -c 'cd DIR && CMD'"`. Atomic save = temp + `posix-rename@openssh.com`. `app.UseRemote(app.Remote)` (3-method interface: `Name`, `ShellCommand`, `RunCommand`) routes F8 and tools through it (`tools.StartProgram` added for captured runs), shows `⇄ name` on the status bar, refuses agents (menu shows `(not available over ssh)`). No LSP over ssh: the command skips `StartLanguageServer`. Windows → `ErrUnsupported` (no ControlMaster). Rejected, with reasons in `docs/*/explanation/remote-editing.md`: `x/crypto/ssh` (ignores ~/.ssh/config, host-key prompt to reimplement), shell `cat`/`ls` (non-portable output, a process per stat), hand-written SFTP, sshfs, copying the binary over, threading an FS through every package. Chosen by the user: system ssh + ControlMaster, SFTP via pkg/sftp, scope = files+tree+terminals+tools, agents off, all six editors.
	154	+
148	155	## Build, test, run
149	156
150	157	```bash
@@ -188,8 +195,19 @@ python3 ~/.claude/skills/quality/scripts/quality_report.py --workspace .
188	195
189	196	- v1.0.4 is ready to tag (`release.env` says so): the shadow fix, AsciiDoc, and terminal copy/paste, above. `make check` green, `-race` green on `app` and `terminal`, quality gate #40 PASS, 0 smells. Not committed. Nothing in it changes an editor's code; re-pinning is cosmetic but every editor shows the defect until it does.
190	197
	198	+## State as of 2026-09-29
	199	+
	200	+- Remote editing (`-ssh`) is implemented but unreleased and uncommitted, on `main`: `fsys/`, `fsys/fsystest/`, `remote/`, `app/remote.go`, `tools.StartProgram`, and the routing through `fsys` above. `go test ./...` green (root `release_test` included, since it runs inside the module); `gofmt`/`go vet` clean. The editors need this released as v1.0.5 — until then they build only under a `go.work`, and their `release_test` fails (see their memories).
	201	+- Verified for real: `remote/integration_test.go` against the Docker sshd in `turbo-editors/demo-remote-machine` (`TURBO_CORE_SSH_KEY=… go test ./remote -run Real`), and `turbo-python -ssh` driven in a pty (pyte) with password login: prompt before the screen, remote file opened/edited/saved (checked on the machine), F9 tree, a popup tool printing `remote-machine`, F8 bash on the machine, status `⇄ … LSP: off`, clean exit, no master or socket left.
	202	+- Quality gate NOT run: `qlty` is not installed in this sandbox (and the skill's script is under `.claude/skills/quality/`, not `~/.claude/skills/`). Per the skill, not installed by hand. Run it before tagging v1.0.5.
	203	+- Docs: EN+FR `reference/fsys.md`, `reference/remote.md`, `how-to/add-remote-editing.md`, `explanation/remote-editing.md`; packages, app, architecture, index, run-the-tests updated; package READMEs for `fsys`, `remote` + updates to app, tools, buffer, projectfile, filetree, settings, snippets. `docs/diagrams/packages.drawio` regenerated from `go list` (22 packages, 4 external modules, 61 arrows) — the old one had drifted (no `configrepo`, no `fsys`).
	204	+
191	205	## Not yet established
192	206
	207	+- Remote editing has never run with a macOS client, a macOS server, or through a real `ProxyJump`. Verified Linux→Linux (Docker) only. The control socket path is shortened to `/tmp` when `os.TempDir()` is longer than 60 bytes, which is the macOS case, but untested there.
	208	+- LSP and agents over ssh: designed, not built. Run them on the remote machine via `ssh -S … -T dest "cd DIR && exec <server\|agent>"` (stdio); a local one on remote files is wrong. Files to change are listed in `handoffs/2026-09-29-ssh-remote-editing.md`. Awaiting the user's decision; remote LSP recommended first.
	209	+- A dropped connection mid-session is unhandled beyond errors: saves then fail with the SFTP error in a dialog; there is no reconnect.
	210	+
193	211	- Agent windows have been driven, but only from a script. The whole path was exercised against a real `docker agent` v1.139.0 and a real llama.cpp serving JetBrains Mellum2 — the menu, the window, a prompt, a streamed reply, a shell tool call, the permission dialog answered, and Go code in a fence read back off the wire with the right colours per span. It was done by driving the binary through a pty from a script; nobody has typed into one with their hands. Untried: the mouse, `Tab` between the panes on a real keyboard, resizing the window mid-turn, and two agents side by side.
194	212	- The `/` and `@` pickers have only been driven by tests. Commands, hints, embedded and linked mentions are all asserted on the wire against the fake agent, and the popup on a simulation screen, but no real agent has announced a command to this client yet — `docker agent` was not available in the sandbox on 2026-09-15 — and the user's own `mini-me` agent (`mm -acp`, which Zed discovers commands from) has never been pointed at an agent window. Whether its `available_commands_update` arrives before or after `session/new` returns, and whether it embeds context, are both unknown.
195	213	- `release_test.go` fails in this sandbox for a reason that is not the code. It copies the module with `cp -r`, and the sandbox's filesystem returns NUL bytes from `cp` for some recently written inodes (`acp/picker.go`, `app/agent_files.go` on 2026-09-15). Recreating the files at fresh inodes did not clear it this time. `cat`, `git`, `gofmt`, `go build` and `go test ./acp ./app` all read the right bytes.

  ## Architecture
--Nineteen packages. Dependencies run strictly downwards, no cycles, and no interface indirection introduced to prevent one.
++Twenty-two packages (counting the root `main` that holds only `release_test.go`). Dependencies run strictly downwards, no cycles, and no interface indirection introduced to prevent one.
  ```
--app → {editor, ui, lsp, acp, buffer, terminal, filetree, settings, snippets, tools, syntax, theme, profile, version}
++app → {editor, ui, lsp, acp, buffer, terminal, filetree, settings, snippets, tools, syntax, theme, profile, version, fsys}
++       remote   → github.com/pkg/sftp   ← execs ssh; its FS satisfies fsys.FS without importing fsys
++       buffer │ projectfile │ filetree │ settings │ snippets │ tools → fsys (+ what is listed)
++       fsys     → stdlib only
         editor   → {buffer, syntax, ui, theme}
         terminal → {ui, theme, tcell, golang.org/x/sys}
         filetree → {ui, theme, tcell}
  | Package | What it holds | Depends on |
  | --- | --- | --- |
  | `profile` | The editor's identity: name, slug, language, tools menu, root markers, server, templates — and every path derived from the slug | **stdlib only** |
--| `buffer` | Text of one file: lines of runes, cursor, selection, undo, search, load/save | **stdlib only** |
++| `buffer` | Text of one file: lines of runes, cursor, selection, undo, search, load/save | `fsys` |
--| `projectfile` | Atomic writes of a project's own TOML files | **stdlib only** |
++| `projectfile` | Atomic writes of a project's own TOML files | `fsys` |
++| `fsys` | The one door to the project's files (package-level `Use`, default `Local{}`); `fsys/fsystest.Memory` for tests | **stdlib only** |
++| `remote` | `-ssh`: ControlMaster login via the `ssh` command, files over SFTP, argv of remote shells/tools | `github.com/pkg/sftp`, the `ssh` command |
  | `configrepo` | A shared `.turbo-<slug>` fetched from a forge URL by a shallow git clone (`-load-config`) | `projectfile`, `profile`, the `git` command |
  | `version` | What build of itself the binary is: linker stamp, then Go build info | **stdlib only** |
  | `lsp` | LSP framing, JSON-RPC 2.0, the child process | `profile` |
  - **Text is copied out of a terminal window and pasted into it (2026-09-21, v1.0.4).** `terminal/view_select.go`. The keys are the editor's *other* spelling of copy and paste — `Ctrl-Ins` / `Shift-Ins` — because `Ctrl-C` and `Ctrl-V` are the shell's; both are claimed even when they do nothing, since sent through either arrives as a plain `Insert`. The selection is two `Point`s of the **whole text** (history index + live rows), which is what keeps it on the same text while the shell writes below it — a line scrolling off the top keeps its index. Mouse selects by cell (drag clamped to the window's edge); `Shift-↑`/`Shift-↓` select whole lines from the shell's cursor row and turn a mouse selection into whole lines (one rule, not two). Trailing blanks are trimmed only from a line selected to its right edge. A click drops the selection; output, scrolling and typing keep it. Highlight is `editor.selection`, no new theme key (the acp view does the same). Copy goes through `App.copyToClipboards` (renamed from `copyFromAgent`): editor clipboard + OSC 52 + `Copied N lines`. `Paste` turns `\n` into `\r` and, when the screen says **mode 2004** is on, wraps in `ESC[200~`…`ESC[201~` — the emulator now *remembers* 2004 (`Screen.BracketedPaste`), which is the one place its boundary moved; it still never pastes by itself. `App.Copy`/`App.Paste` route to a terminal in front; `handlePaste` hands a bracketed paste from the outer terminal to a terminal window whole, as it already did for an agent window. A finished terminal still selects and copies (the keys run before the `Exited` check) but `Paste` returns false. `OnCopy`/`OnPaste` are exported fields, unlike `OnChange`/`OnExit`: only the event loop calls them, so no goroutine reads them. Accepted edge: when the scrollback is full (2000 lines), each trimmed line shifts a held selection up by one — dropped on the next click anyway. Rejected: Escape to drop the selection (vim needs Escape); `Shift-Home`/`End` (not needed yet); a `terminal.selection` theme key (nine TOML files for no visible gain). Tests: 20 in `terminal/view_select_test.go`, 5 in `app/terminal_clipboard_test.go` (round trip both ways, menu actions, bracketed paste, highlight).
++- **Remote editing over ssh drives the `ssh` command, shares one ControlMaster connection, and moves files over SFTP (2026-09-29, unreleased, ticket #33).** New `fsys` (package-level `Use(FS)`, same argument as `syntax.Register`) is now the only way `buffer`, `projectfile`, `settings`, `snippets` (project file only — the user's stays `os`), `tools`, `filetree` and `app` touch project files; themes, the user's snippets, `lsp`, `acp` and `configrepo` stay on `os` on purpose. New `remote`: `ParseTarget` (`[user@]host[:path]`, scp-style, no port — use `~/.ssh/config`; refuses a leading `-`), `Connect` runs `ssh -o ControlMaster=yes -o ControlPersist=60 -N -f` in the foreground **before tcell takes the screen** (password prompt there), then everything with `-S sock -o ControlMaster=no -o BatchMode=yes`: one `ssh -s … sftp` channel (`github.com/pkg/sftp` v1.13.11 — the only new dependency; it forced `golang.org/x/sys` v0.38→v0.47 by MVS), shells `ssh -t … "exec /bin/sh -c 'cd DIR && exec \"${SHELL:-/bin/sh}\" -l'"`, tools `-T`/`-t … "exec /bin/sh -c 'cd DIR && CMD'"`. Atomic save = temp + `posix-rename@openssh.com`. `app.UseRemote(app.Remote)` (3-method interface: `Name`, `ShellCommand`, `RunCommand`) routes F8 and tools through it (`tools.StartProgram` added for captured runs), shows `⇄ name` on the status bar, refuses agents (menu shows `(not available over ssh)`). No LSP over ssh: the command skips `StartLanguageServer`. Windows → `ErrUnsupported` (no ControlMaster). Rejected, with reasons in `docs/*/explanation/remote-editing.md`: `x/crypto/ssh` (ignores ~/.ssh/config, host-key prompt to reimplement), shell `cat`/`ls` (non-portable output, a process per stat), hand-written SFTP, sshfs, copying the binary over, threading an FS through every package. Chosen by the user: system ssh + ControlMaster, SFTP via pkg/sftp, scope = files+tree+terminals+tools, agents off, all six editors.
++
  ## Build, test, run
  ```bash
  - **v1.0.4 is ready to tag** (`release.env` says so): the shadow fix, AsciiDoc, and terminal copy/paste, above. `make check` green, `-race` green on `app` and `terminal`, quality gate #40 PASS, 0 smells. Not committed. Nothing in it changes an editor's code; re-pinning is cosmetic but every editor shows the defect until it does.
++## State as of 2026-09-29
++
++- **Remote editing (`-ssh`) is implemented but unreleased and uncommitted**, on `main`: `fsys/`, `fsys/fsystest/`, `remote/`, `app/remote.go`, `tools.StartProgram`, and the routing through `fsys` above. `go test ./...` green (root `release_test` included, since it runs inside the module); `gofmt`/`go vet` clean. **The editors need this released as v1.0.5** — until then they build only under a `go.work`, and their `release_test` fails (see their memories).
++- **Verified for real**: `remote/integration_test.go` against the Docker sshd in `turbo-editors/demo-remote-machine` (`TURBO_CORE_SSH_KEY=… go test ./remote -run Real`), and `turbo-python -ssh` driven in a pty (pyte) with **password** login: prompt before the screen, remote file opened/edited/saved (checked on the machine), F9 tree, a popup tool printing `remote-machine`, F8 bash on the machine, status `⇄ … LSP: off`, clean exit, no master or socket left.
++- **Quality gate NOT run**: `qlty` is not installed in this sandbox (and the skill's script is under `.claude/skills/quality/`, not `~/.claude/skills/`). Per the skill, not installed by hand. Run it before tagging v1.0.5.
++- **Docs**: EN+FR `reference/fsys.md`, `reference/remote.md`, `how-to/add-remote-editing.md`, `explanation/remote-editing.md`; packages, app, architecture, index, run-the-tests updated; package READMEs for `fsys`, `remote` + updates to app, tools, buffer, projectfile, filetree, settings, snippets. `docs/diagrams/packages.drawio` **regenerated** from `go list` (22 packages, 4 external modules, 61 arrows) — the old one had drifted (no `configrepo`, no `fsys`).
++
  ## Not yet established
++- **Remote editing has never run with a macOS client, a macOS server, or through a real `ProxyJump`.** Verified Linux→Linux (Docker) only. The control socket path is shortened to `/tmp` when `os.TempDir()` is longer than 60 bytes, which is the macOS case, but untested there.
++- **LSP and agents over ssh: designed, not built.** Run them on the remote machine via `ssh -S … -T dest "cd DIR && exec <server|agent>"` (stdio); a local one on remote files is wrong. Files to change are listed in `handoffs/2026-09-29-ssh-remote-editing.md`. Awaiting the user's decision; remote LSP recommended first.
++- **A dropped connection mid-session is unhandled beyond errors**: saves then fail with the SFTP error in a dialog; there is no reconnect.
++
  - **Agent windows have been driven, but only from a script.** The whole path was exercised against a real `docker agent` v1.139.0 and a real llama.cpp serving JetBrains Mellum2 — the menu, the window, a prompt, a streamed reply, a shell tool call, the permission dialog answered, and Go code in a fence read back off the wire with the right colours per span. It was done by driving the binary through a pty from a script; **nobody has typed into one with their hands**. Untried: the mouse, `Tab` between the panes on a real keyboard, resizing the window mid-turn, and two agents side by side.
  - **The `/` and `@` pickers have only been driven by tests.** Commands, hints, embedded and linked mentions are all asserted on the wire against the fake agent, and the popup on a simulation screen, but no real agent has announced a command to this client yet — `docker agent` was not available in the sandbox on 2026-09-15 — and the user's own `mini-me` agent (`mm -acp`, which Zed discovers commands from) has never been pointed at an agent window. Whether its `available_commands_update` arrives before or after `session/new` returns, and whether it embeds context, are both unknown.
  - **`release_test.go` fails in this sandbox for a reason that is not the code.** It copies the module with `cp -r`, and the sandbox's filesystem returns NUL bytes from `cp` for some recently written inodes (`acp/picker.go`, `app/agent_files.go` on 2026-09-15). Recreating the files at fresh inodes did **not** clear it this time. `cat`, `git`, `gofmt`, `go build` and `go test ./acp ./app` all read the right bytes.

modified README.md +5 -3 Viewed

@@ -2,7 +2,7 @@
2	2
3	3	The library every Turbo editor is built on.
4	4
5		-turbo-core is a Turbo C-style terminal IDE with a hole where the language goes: a menu bar, movable overlapping windows, modal dialogs, mouse support, loadable TOML themes, completion over LSP, terminal windows running a real shell, per-project settings, a project tree, snippets, and a menu of the commands a project runs on itself. None of it knows what language is being edited.
	5	+turbo-core is a Turbo C-style terminal IDE with a hole where the language goes: a menu bar, movable overlapping windows, modal dialogs, mouse support, loadable TOML themes, completion over LSP, terminal windows running a real shell, per-project settings, a project tree, snippets, a menu of the commands a project runs on itself, and editing another machine's files over ssh. None of it knows what language is being edited.
6	6
7	7	An editor built on it is a command, a `profile.Profile`, and a scanner:
8	8
@@ -45,13 +45,15 @@ Go 1.26.5 or later.
45	45
46	46	## What is in it
47	47
48		-Sixteen packages. Dependencies run strictly downwards, with no cycles and no interface indirection introduced to prevent one.
	48	+Twenty-one packages. Dependencies run strictly downwards, with no cycles and no interface indirection introduced to prevent one.
49	49
50	50	\| Package \| What it holds \|
51	51	\| --- \| --- \|
52	52	\| `profile` \| The editor's identity: name, slug, language server, starter templates \|
53	53	\| `buffer` \| The text of one file: lines of runes, cursor, selection, undo, search \|
54	54	\| `projectfile` \| Atomic writes of a project's own TOML files \|
	55	+\| `fsys` \| The one door to the project's files — the local disk, or another machine's after `fsys.Use` \|
	56	+\| `remote` \| Another machine over the `ssh` command: one shared connection, files over SFTP, remote shells and tools — every editor's `-ssh user@machine[:dir]` \|
55	57	\| `configrepo` \| A shared `.turbo-<slug>` directory fetched from a repository URL — rickub, GitHub, GitLab, Codeberg — by a shallow git clone \|
56	58	\| `version` \| What build of itself a binary is \|
57	59	\| `lsp` \| LSP framing, JSON-RPC 2.0, the child process \|
@@ -88,7 +90,7 @@ python3 ~/.claude/skills/quality/scripts/quality_report.py --workspace .
88	90
89	91	Full documentation in English and French, following [Diátaxis](https://diataxis.fr):
90	92
91		-- [English](docs/en/README.md) — tutorial, five how-to guides, four reference pages, two explanations
	93	+- [English](docs/en/README.md) — a tutorial, seven how-to guides, six reference pages, three explanations
92	94	- [Français](docs/fr/README.md) — le même, en français
93	95
94	96	## Licence

  The library every Turbo editor is built on.
--turbo-core is a Turbo C-style terminal IDE with a hole where the language goes: a menu bar, movable overlapping windows, modal dialogs, mouse support, loadable TOML themes, completion over LSP, terminal windows running a real shell, per-project settings, a project tree, snippets, and a menu of the commands a project runs on itself. None of it knows what language is being edited.
++turbo-core is a Turbo C-style terminal IDE with a hole where the language goes: a menu bar, movable overlapping windows, modal dialogs, mouse support, loadable TOML themes, completion over LSP, terminal windows running a real shell, per-project settings, a project tree, snippets, a menu of the commands a project runs on itself, and editing another machine's files over ssh. None of it knows what language is being edited.
  An editor built on it is a command, a `profile.Profile`, and a scanner:
  ## What is in it
--Sixteen packages. Dependencies run strictly downwards, with no cycles and no interface indirection introduced to prevent one.
++Twenty-one packages. Dependencies run strictly downwards, with no cycles and no interface indirection introduced to prevent one.
  | Package | What it holds |
  | --- | --- |
  | `profile` | The editor's identity: name, slug, language server, starter templates |
  | `buffer` | The text of one file: lines of runes, cursor, selection, undo, search |
  | `projectfile` | Atomic writes of a project's own TOML files |
++| `fsys` | The one door to the project's files — the local disk, or another machine's after `fsys.Use` |
++| `remote` | Another machine over the `ssh` command: one shared connection, files over SFTP, remote shells and tools — every editor's `-ssh user@machine[:dir]` |
  | `configrepo` | A shared `.turbo-<slug>` directory fetched from a repository URL — rickub, GitHub, GitLab, Codeberg — by a shallow git clone |
  | `version` | What build of itself a binary is |
  | `lsp` | LSP framing, JSON-RPC 2.0, the child process |
  Full documentation in **English** and **French**, following [Diátaxis](https://diataxis.fr):
--- [English](docs/en/README.md) — tutorial, five how-to guides, four reference pages, two explanations
++- [English](docs/en/README.md) — a tutorial, seven how-to guides, six reference pages, three explanations
  - [Français](docs/fr/README.md) — le même, en français
  ## Licence

modified app/README.md +5 -1 Viewed

@@ -44,6 +44,10 @@ Two things are this package's rather than `acp`'s, and both are about the editor
44	44	- The permission dialog. `session/request_permission` arrives on the session's reading goroutine; `recordPermission` puts it in a queue and wakes the loop, and `askNextPermission` opens the box on the next turn. One at a time — `pendingPermissions.asking` holds the rest back — because two agents asking at once would stack two modals over each other. Escape means the agent's own reject option, not a cancellation: the turn is still running and the agent may carry on without what it asked for.
45	45	- The file methods. `readForAgent` answers from the buffer when the file is open and modified, so the agent sees the edit you just made rather than the version on disk. `writeForAgent` puts the agent's text into the buffer and leaves it unsaved, so the change is in front of you, undoable with `Ctrl-Z` and yours to keep with `F2`. Both take `agentFiles`, because they run on a session's goroutine while the event loop may be writing the same buffers.
46	46
	47	+## Another machine
	48	+
	49	+`UseRemote(r)` says the project is somewhere else; `fsys` has already been switched there by the command, so the files need nothing more. What changes here: `NewTerminal` starts `r.ShellCommand(dir)` instead of the local shell (`shellOptions`), a tool runs `r.RunCommand(dir, command, …)` — through `tools.StartProgram` when captured, in a terminal window otherwise (`commandOptions`, `startTool`) — and the status bar starts with `⇄ user@host`. Agent windows are refused with a message (`refuseAgentsOverSSH`), and the Agent menu holds one disabled line saying why: an agent would read and write this machine's files while the screen shows the other's. `app` knows the machine only as the three-method `Remote` interface, so `remote_test.go` drives it with a fake that runs `/bin/sh` locally.
	50	+
47	51	## Project settings and automatic saving
48	52
49	53	A project's settings file is read by `main` and handed here through `UseSettings`, which applies autosave and remembers the path. The theme is not applied here: `main` resolves it first, because a `-theme` flag outranks the project's choice and only `main` knows whether one was given.
@@ -66,7 +70,7 @@ Two consequences worth knowing: a failed save clears the deadline before wri
66	70
67	71	`a.treeWindow` and `a.treeView` are a pair of fields rather than a map, because there is at most one tree: the root is fixed at start-up, so a second view of it would have nothing to distinguish it. `ProjectTree` raises the existing window instead of opening another, the same way opening an already-open file raises its window.
68	72
69		-The tree is rooted at `os.Getwd()` — the same rule the settings file follows, so "the project" means one thing throughout the editor. `refreshTree` runs after every save, which is the one moment the editor knows the project changed; everything else is the user's `F5`.
	73	+The tree is rooted at `fsys.Getwd()` — the same rule the settings file follows, so "the project" means one thing throughout the editor. `refreshTree` runs after every save, which is the one moment the editor knows the project changed; everything else is the user's `F5`.
70	74
71	75	## The Go menu, and putting files back afterwards
72	76

  - **The permission dialog.** `session/request_permission` arrives on the session's reading goroutine; `recordPermission` puts it in a queue and wakes the loop, and `askNextPermission` opens the box on the next turn. One at a time — `pendingPermissions.asking` holds the rest back — because two agents asking at once would stack two modals over each other. Escape means the agent's *own* reject option, not a cancellation: the turn is still running and the agent may carry on without what it asked for.
  - **The file methods.** `readForAgent` answers from the **buffer** when the file is open and modified, so the agent sees the edit you just made rather than the version on disk. `writeForAgent` puts the agent's text into the buffer and leaves it unsaved, so the change is in front of you, undoable with `Ctrl-Z` and yours to keep with `F2`. Both take `agentFiles`, because they run on a session's goroutine while the event loop may be writing the same buffers.
++## Another machine
++
++`UseRemote(r)` says the project is somewhere else; `fsys` has already been switched there by the command, so the files need nothing more. What changes here: `NewTerminal` starts `r.ShellCommand(dir)` instead of the local shell (`shellOptions`), a tool runs `r.RunCommand(dir, command, …)` — through `tools.StartProgram` when captured, in a terminal window otherwise (`commandOptions`, `startTool`) — and the status bar starts with `⇄ user@host`. Agent windows are refused with a message (`refuseAgentsOverSSH`), and the Agent menu holds one disabled line saying why: an agent would read and write this machine's files while the screen shows the other's. `app` knows the machine only as the three-method `Remote` interface, so `remote_test.go` drives it with a fake that runs `/bin/sh` locally.
++
  ## Project settings and automatic saving
  A project's settings file is read by `main` and handed here through `UseSettings`, which applies autosave and remembers the path. The theme is **not** applied here: `main` resolves it first, because a `-theme` flag outranks the project's choice and only `main` knows whether one was given.
  `a.treeWindow` and `a.treeView` are a pair of fields rather than a map, because there is at most one tree: the root is fixed at start-up, so a second view of it would have nothing to distinguish it. `ProjectTree` raises the existing window instead of opening another, the same way opening an already-open file raises its window.
--The tree is rooted at `os.Getwd()` — the same rule the settings file follows, so "the project" means one thing throughout the editor. `refreshTree` runs after every save, which is the one moment the editor knows the project changed; everything else is the user's `F5`.
++The tree is rooted at `fsys.Getwd()` — the same rule the settings file follows, so "the project" means one thing throughout the editor. `refreshTree` runs after every save, which is the one moment the editor knows the project changed; everything else is the user's `F5`.
  ## The Go menu, and putting files back afterwards

modified app/actions_file.go +2 -2 Viewed

@@ -4,11 +4,11 @@ package app
4	4
5	5	import (
6	6	"fmt"
7		- "os"
8	7	"path/filepath"
9	8
10	9	"rickub.com/turbo-editors/turbo-core/buffer"
11	10	"rickub.com/turbo-editors/turbo-core/editor"
	11	+ "rickub.com/turbo-editors/turbo-core/fsys"
12	12	"rickub.com/turbo-editors/turbo-core/lsp"
13	13	"rickub.com/turbo-editors/turbo-core/ui"
14	14	)
@@ -185,7 +185,7 @@ func (a App) save(view editor.View, path string) {
185	185	// fileExists reports whether there is already a file at a path — asked before
186	186	// a write, so that afterwards the save knows whether it created the file.
187	187	func fileExists(path string) bool {
188		- _, err := os.Stat(path)
	188	+ _, err := fsys.Stat(path)
189	189	return err == nil
190	190	}
191	191

  import (
  	"fmt"
--	"os"
  	"path/filepath"
  	"rickub.com/turbo-editors/turbo-core/buffer"
  	"rickub.com/turbo-editors/turbo-core/editor"
++	"rickub.com/turbo-editors/turbo-core/fsys"
  	"rickub.com/turbo-editors/turbo-core/lsp"
  	"rickub.com/turbo-editors/turbo-core/ui"
  )
  // fileExists reports whether there is already a file at a path — asked before
  // a write, so that afterwards the save knows whether it created the file.
  func fileExists(path string) bool {
--	_, err := os.Stat(path)
++	_, err := fsys.Stat(path)
  	return err == nil
  }

modified app/agents.go +9 -0 Viewed

@@ -28,6 +28,9 @@ type agentWindow struct {
28	28	// that window. Opening the same agent twice gives two independent sessions,
29	29	// the way two terminals are two shells.
30	30	func (a *App) NewAgent(name string) {
	31	+ if a.refuseAgentsOverSSH() {
	32	+ return
	33	+ }
31	34	list, err := a.loadAgents()
32	35	if err != nil {
33	36	a.ShowMessage("Agents", err.Error())
@@ -268,6 +271,9 @@ type agentFileLock = sync.Mutex
268	271	// command line came out as, and whatever the agent itself said on its standard
269	272	// error, which is where a misconfigured model endpoint reports itself.
270	273	func (a *App) AgentStatus() {
	274	+ if a.refuseAgentsOverSSH() {
	275	+ return
	276	+ }
271	277	a.ShowMessage("Agent status", a.agentReport())
272	278	}
273	279
@@ -374,6 +380,9 @@ func lastLines(lines []string, n int) []string {
374	380	// format is learnt, and pointing it at your own agent is the first thing
375	381	// anybody does. A project that already has one is opened unchanged.
376	382	func (a *App) CreateAgentsFile() {
	383	+ if a.refuseAgentsOverSSH() {
	384	+ return
	385	+ }
377	386	create := func(project string) (string, error) { return acp.Create(a.profile, project) }
378	387	a.createProjectFile("Agents", create, acp.ErrExists)
379	388	}

  // that window. Opening the same agent twice gives two independent sessions,
  // the way two terminals are two shells.
  func (a *App) NewAgent(name string) {
++	if a.refuseAgentsOverSSH() {
++		return
++	}
  	list, err := a.loadAgents()
  	if err != nil {
  		a.ShowMessage("Agents", err.Error())
  // command line came out as, and whatever the agent itself said on its standard
  // error, which is where a misconfigured model endpoint reports itself.
  func (a *App) AgentStatus() {
++	if a.refuseAgentsOverSSH() {
++		return
++	}
  	a.ShowMessage("Agent status", a.agentReport())
  }
  // format is learnt, and pointing it at your own agent is the first thing
  // anybody does. A project that already has one is opened unchanged.
  func (a *App) CreateAgentsFile() {
++	if a.refuseAgentsOverSSH() {
++		return
++	}
  	create := func(project string) (string, error) { return acp.Create(a.profile, project) }
  	a.createProjectFile("Agents", create, acp.ErrExists)
  }

modified app/app.go +6 -2 Viewed

@@ -79,6 +79,10 @@ type App struct {
79	79	// running is the command whose output is showing in a dialog, when one is.
80	80	running *toolRun
81	81
	82	+ // remote is the machine the project is on, when it is not this one. Nil
	83	+ // means local, which is every editor that was not started with -ssh.
	84	+ remote Remote
	85	+
82	86	// toolValues is what was last typed into a tool's parameters box, by tool
83	87	// name and then by label. It lives for the session only: a value somebody
84	88	// typed this afternoon is not a decision the project made, so it does not
@@ -399,7 +403,7 @@ func (a *App) draw() {
399	403	func (a *App) updateStatus() {
400	404	view := a.activeView()
401	405	if view == nil {
402		- a.status.SetExtra(a.language.Status())
	406	+ a.status.SetExtra(a.connectionStatus())
403	407	return
404	408	}
405	409
@@ -407,7 +411,7 @@ func (a *App) updateStatus() {
407	411	if diagnostic, ok := a.language.FirstError(view.Buffer().Path()); ok {
408	412	extra = fmt.Sprintf("%s ⚠ %s", extra, diagnostic.Message)
409	413	} else {
410		- extra = fmt.Sprintf("%s %s", extra, a.language.Status())
	414	+ extra = fmt.Sprintf("%s %s", extra, a.connectionStatus())
411	415	}
412	416	a.status.SetExtra(extra)
413	417	}

  	// running is the command whose output is showing in a dialog, when one is.
  	running *toolRun
++	// remote is the machine the project is on, when it is not this one. Nil
++	// means local, which is every editor that was not started with -ssh.
++	remote Remote
++
  	// toolValues is what was last typed into a tool's parameters box, by tool
  	// name and then by label. It lives for the session only: a value somebody
  	// typed this afternoon is not a decision the project made, so it does not
  func (a *App) updateStatus() {
  	view := a.activeView()
  	if view == nil {
--		a.status.SetExtra(a.language.Status())
++		a.status.SetExtra(a.connectionStatus())
  		return
  	}
  	if diagnostic, ok := a.language.FirstError(view.Buffer().Path()); ok {
  		extra = fmt.Sprintf("%s  ⚠ %s", extra, diagnostic.Message)
  	} else {
--		extra = fmt.Sprintf("%s  %s", extra, a.language.Status())
++		extra = fmt.Sprintf("%s  %s", extra, a.connectionStatus())
  	}
  	a.status.SetExtra(extra)
  }

modified app/code.go +2 -2 Viewed

@@ -7,10 +7,10 @@ import (
7	7	"context"
8	8	"errors"
9	9	"fmt"
10		- "os"
11	10	"path/filepath"
12	11	"strings"
13	12
	13	+ "rickub.com/turbo-editors/turbo-core/fsys"
14	14	"rickub.com/turbo-editors/turbo-core/lsp"
15	15	"rickub.com/turbo-editors/turbo-core/ui"
16	16	)
@@ -134,7 +134,7 @@ func (a *App) linesOf(path string) []string {
134	134	return strings.Split(view.Buffer().Text(), "\n")
135	135	}
136	136	}
137		- data, err := os.ReadFile(path)
	137	+ data, err := fsys.ReadFile(path)
138	138	if err != nil {
139	139	return nil
140	140	}

  	"context"
  	"errors"
  	"fmt"
--	"os"
  	"path/filepath"
  	"strings"
++	"rickub.com/turbo-editors/turbo-core/fsys"
  	"rickub.com/turbo-editors/turbo-core/lsp"
  	"rickub.com/turbo-editors/turbo-core/ui"
  )
  			return strings.Split(view.Buffer().Text(), "\n")
  		}
  	}
--	data, err := os.ReadFile(path)
++	data, err := fsys.ReadFile(path)
  	if err != nil {
  		return nil
  	}

modified app/dialogs.go +8 -7 Viewed

@@ -1,11 +1,12 @@
1	1	package app
2	2
3	3	import (
4		- "os"
	4	+ "io/fs"
5	5	"path/filepath"
6	6	"sort"
7	7	"strings"
8	8
	9	+ "rickub.com/turbo-editors/turbo-core/fsys"
9	10	"rickub.com/turbo-editors/turbo-core/ui"
10	11	)
11	12
@@ -66,17 +67,17 @@ func NewFileDialog(title, startPath string, screen ui.Rect) *FileDialog {
66	67	// splitStartPath turns the path a dialog opens on into a directory and a name.
67	68	func splitStartPath(startPath string) (directory, name string) {
68	69	if startPath == "" {
69		- if working, err := os.Getwd(); err == nil {
	70	+ if working, err := fsys.Getwd(); err == nil {
70	71	return working, ""
71	72	}
72	73	return ".", ""
73	74	}
74	75
75		- absolute, err := filepath.Abs(startPath)
	76	+ absolute, err := fsys.Abs(startPath)
76	77	if err != nil {
77	78	absolute = startPath
78	79	}
79		- if info, err := os.Stat(absolute); err == nil && info.IsDir() {
	80	+ if info, err := fsys.Stat(absolute); err == nil && info.IsDir() {
80	81	return absolute, ""
81	82	}
82	83	return filepath.Dir(absolute), filepath.Base(absolute)
@@ -145,7 +146,7 @@ func (f *FileDialog) confirm() {
145	146	f.choose()
146	147	return
147	148	}
148		- if info, err := os.Stat(path); err == nil && info.IsDir() {
	149	+ if info, err := fsys.Stat(path); err == nil && info.IsDir() {
149	150	f.enter(path)
150	151	return
151	152	}
@@ -183,7 +184,7 @@ func (f *FileDialog) enter(directory string) {
183	184	func (f *FileDialog) readDirectory() {
184	185	f.dialog.SetTitle(f.title + " — " + shortenPath(f.directory, fileDialogWidth-len(f.title)-8))
185	186
186		- entries, err := os.ReadDir(f.directory)
	187	+ entries, err := fsys.ReadDir(f.directory)
187	188	if err != nil {
188	189	f.entries = []string{parentEntry}
189	190	f.list.SetItems(f.entries)
@@ -196,7 +197,7 @@ func (f *FileDialog) readDirectory() {
196	197
197	198	// directoryEntries returns the names to list: the parent, then the
198	199	// directories, then the files, each group sorted.
199		-func directoryEntries(entries []os.DirEntry) []string {
	200	+func directoryEntries(entries []fs.DirEntry) []string {
200	201	var directories, files []string
201	202	for _, entry := range entries {
202	203	if strings.HasPrefix(entry.Name(), ".") {

  package app
  import (
--	"os"
++	"io/fs"
  	"path/filepath"
  	"sort"
  	"strings"
++	"rickub.com/turbo-editors/turbo-core/fsys"
  	"rickub.com/turbo-editors/turbo-core/ui"
  )
  // splitStartPath turns the path a dialog opens on into a directory and a name.
  func splitStartPath(startPath string) (directory, name string) {
  	if startPath == "" {
--		if working, err := os.Getwd(); err == nil {
++		if working, err := fsys.Getwd(); err == nil {
  			return working, ""
  		}
  		return ".", ""
  	}
--	absolute, err := filepath.Abs(startPath)
++	absolute, err := fsys.Abs(startPath)
  	if err != nil {
  		absolute = startPath
  	}
--	if info, err := os.Stat(absolute); err == nil && info.IsDir() {
++	if info, err := fsys.Stat(absolute); err == nil && info.IsDir() {
  		return absolute, ""
  	}
  	return filepath.Dir(absolute), filepath.Base(absolute)
  		f.choose()
  		return
  	}
--	if info, err := os.Stat(path); err == nil && info.IsDir() {
++	if info, err := fsys.Stat(path); err == nil && info.IsDir() {
  		f.enter(path)
  		return
  	}
  func (f *FileDialog) readDirectory() {
  	f.dialog.SetTitle(f.title + " — " + shortenPath(f.directory, fileDialogWidth-len(f.title)-8))
--	entries, err := os.ReadDir(f.directory)
++	entries, err := fsys.ReadDir(f.directory)
  	if err != nil {
  		f.entries = []string{parentEntry}
  		f.list.SetItems(f.entries)
  // directoryEntries returns the names to list: the parent, then the
  // directories, then the files, each group sorted.
--func directoryEntries(entries []os.DirEntry) []string {
++func directoryEntries(entries []fs.DirEntry) []string {
  	var directories, files []string
  	for _, entry := range entries {
  		if strings.HasPrefix(entry.Name(), ".") {

added app/fsys_test.go +58 -0 Viewed

new file mode 100644
@@ -0,0 +1,58 @@
	1	+package app
	2	+
	3	+import (
	4	+ "testing"
	5	+
	6	+ "rickub.com/turbo-editors/turbo-core/fsys"
	7	+ "rickub.com/turbo-editors/turbo-core/fsys/fsystest"
	8	+)
	9	+
	10	+// newMemoryApp returns an editor whose files exist only in memory, as they
	11	+// would only exist on the far side of -ssh. Anything it finds or writes there
	12	+// proves the editor went through fsys rather than to the local disk.
	13	+func newMemoryApp(t testing.T) (App, *fsystest.Memory) {
	14	+ t.Helper()
	15	+ memory := fsystest.New("/remote/project")
	16	+ previous := fsys.Use(memory)
	17	+ t.Cleanup(func() { fsys.Use(previous) })
	18	+
	19	+ a, _ := newTestApp(t)
	20	+ return a, memory
	21	+}
	22	+
	23	+func TestTheProjectTreeIsRootedInTheCurrentFileSystem(t *testing.T) {
	24	+ a, memory := newMemoryApp(t)
	25	+ memory.AddFile("/remote/project/main.py", "")
	26	+
	27	+ a.ProjectTree()
	28	+
	29	+ if got := a.Desktop().Active().Title(); got != "project" {
	30	+ t.Errorf("the tree window is called %q, want project", got)
	31	+ }
	32	+}
	33	+
	34	+func TestAFileIsOpenedAndSavedThroughTheCurrentFileSystem(t *testing.T) {
	35	+ a, memory := newMemoryApp(t)
	36	+ memory.AddFile("/remote/project/main.py", "print(1)\n")
	37	+
	38	+ a.Open("main.py")
	39	+ if got := activeBuffer(t, a).Text(); got != "print(1)\n" {
	40	+ t.Fatalf("the buffer holds %q", got)
	41	+ }
	42	+ typeText(a, "# ")
	43	+ a.save(a.ActiveView(), activeBuffer(t, a).Path())
	44	+
	45	+ if got, _ := memory.File("/remote/project/main.py"); got != "# print(1)\n" {
	46	+ t.Errorf("the file now holds %q", got)
	47	+ }
	48	+}
	49	+
	50	+func TestTheToolsMenuReadsTheProjectsToolsFileThroughTheCurrentFileSystem(t *testing.T) {
	51	+ a, memory := newMemoryApp(t)
	52	+ memory.AddFile("/remote/project/"+testProfile().ProjectDir()+"/tools.toml", "[[tool]]\nname = \"Run\"\ncommand = \"python3 main.py\"\n")
	53	+
	54	+ list, err := a.loadTools()
	55	+ if err != nil \|\| list.Len() != 1 {
	56	+ t.Errorf("loadTools = %d tools, %v; want the one in the remote file", list.Len(), err)
	57	+ }
	58	+}

++package app
++
++import (
++	"testing"
++
++	"rickub.com/turbo-editors/turbo-core/fsys"
++	"rickub.com/turbo-editors/turbo-core/fsys/fsystest"
++)
++
++// newMemoryApp returns an editor whose files exist only in memory, as they
++// would only exist on the far side of -ssh. Anything it finds or writes there
++// proves the editor went through fsys rather than to the local disk.
++func newMemoryApp(t *testing.T) (*App, *fsystest.Memory) {
++	t.Helper()
++	memory := fsystest.New("/remote/project")
++	previous := fsys.Use(memory)
++	t.Cleanup(func() { fsys.Use(previous) })
++
++	a, _ := newTestApp(t)
++	return a, memory
++}
++
++func TestTheProjectTreeIsRootedInTheCurrentFileSystem(t *testing.T) {
++	a, memory := newMemoryApp(t)
++	memory.AddFile("/remote/project/main.py", "")
++
++	a.ProjectTree()
++
++	if got := a.Desktop().Active().Title(); got != "project" {
++		t.Errorf("the tree window is called %q, want project", got)
++	}
++}
++
++func TestAFileIsOpenedAndSavedThroughTheCurrentFileSystem(t *testing.T) {
++	a, memory := newMemoryApp(t)
++	memory.AddFile("/remote/project/main.py", "print(1)\n")
++
++	a.Open("main.py")
++	if got := activeBuffer(t, a).Text(); got != "print(1)\n" {
++		t.Fatalf("the buffer holds %q", got)
++	}
++	typeText(a, "# ")
++	a.save(a.ActiveView(), activeBuffer(t, a).Path())
++
++	if got, _ := memory.File("/remote/project/main.py"); got != "# print(1)\n" {
++		t.Errorf("the file now holds %q", got)
++	}
++}
++
++func TestTheToolsMenuReadsTheProjectsToolsFileThroughTheCurrentFileSystem(t *testing.T) {
++	a, memory := newMemoryApp(t)
++	memory.AddFile("/remote/project/"+testProfile().ProjectDir()+"/tools.toml", "[[tool]]\nname = \"Run\"\ncommand = \"python3 main.py\"\n")
++
++	list, err := a.loadTools()
++	if err != nil || list.Len() != 1 {
++		t.Errorf("loadTools = %d tools, %v; want the one in the remote file", list.Len(), err)
++	}
++}

modified app/menus.go +4 -0 Viewed

@@ -82,6 +82,10 @@ func (a App) agentMenu() ui.Menu {
82	82	// agentItems builds the menu's contents, which are read from the file every
83	83	// time it drops down so that editing acp.toml never needs a restart.
84	84	func (a App) agentItems() []ui.MenuItem {
	85	+ if a.remote != nil {
	86	+ return []*ui.MenuItem{{Label: "(not available over ssh)", Enabled: never}}
	87	+ }
	88	+
85	89	var items []*ui.MenuItem
86	90
87	91	list, err := a.loadAgents()

  // agentItems builds the menu's contents, which are read from the file every
  // time it drops down so that editing acp.toml never needs a restart.
  func (a *App) agentItems() []*ui.MenuItem {
++	if a.remote != nil {
++		return []*ui.MenuItem{{Label: "(not available over ssh)", Enabled: never}}
++	}
++
  	var items []*ui.MenuItem
  	list, err := a.loadAgents()

modified app/project.go +8 -8 Viewed

@@ -5,9 +5,9 @@ package app
5	5
6	6	import (
7	7	"errors"
8		- "os"
9	8	"path/filepath"
10	9
	10	+ "rickub.com/turbo-editors/turbo-core/fsys"
11	11	"rickub.com/turbo-editors/turbo-core/settings"
12	12	"rickub.com/turbo-editors/turbo-core/snippets"
13	13	"rickub.com/turbo-editors/turbo-core/tools"
@@ -42,7 +42,7 @@ func (a *App) CreateProjectSettings() {
42	42	// for one just created and for one that already existed: a caller wanting to
43	43	// remember the path wants it in both cases.
44	44	func (a *App) createProjectFile(title string, create func(string) (string, error), alreadyThere error) (string, bool) {
45		- project, err := os.Getwd()
	45	+ project, err := fsys.Getwd()
46	46	if err != nil {
47	47	a.ShowMessage(title, "Cannot tell which directory this is:\n"+err.Error())
48	48	return "", false
@@ -122,7 +122,7 @@ func (a *App) snippetsFile() projectFile {
122	122	// somebody's repository by itself. The item is greyed out in that case anyway —
123	123	// the dialog is for the caller that is not a menu.
124	124	func (a *App) openProjectFile(file projectFile) {
125		- project, err := os.Getwd()
	125	+ project, err := fsys.Getwd()
126	126	if err != nil \|\| !file.exists(project) {
127	127	a.ShowMessage(file.title, "This project has no "+file.relative+" yet.\n\n"+file.creator+" makes one.")
128	128	return
@@ -132,7 +132,7 @@ func (a *App) openProjectFile(file projectFile) {
132	132
133	133	// hasProjectFile reports whether the project has one of them.
134	134	func (a *App) hasProjectFile(file projectFile) bool {
135		- project, err := os.Getwd()
	135	+ project, err := fsys.Getwd()
136	136	return err == nil && file.exists(project)
137	137	}
138	138
@@ -188,7 +188,7 @@ func not(condition func() bool) func() bool {
188	188	// this file, and a -theme flag given on the command line is the more explicit
189	189	// statement of the two for the session it was given in.
190	190	func (a *App) reapplySettings(path string) {
191		- project, err := os.Getwd()
	191	+ project, err := fsys.Getwd()
192	192	if err != nil \|\| !samePath(path, settings.Path(a.profile, project)) {
193	193	return
194	194	}
@@ -223,11 +223,11 @@ func describeAutosave(s settings.Settings) string {
223	223	// absolute paths so that "./.turbo-go/settings.toml" and the absolute spelling
224	224	// of it are recognised as one file.
225	225	func samePath(one, other string) bool {
226		- oneAbs, err := filepath.Abs(one)
	226	+ oneAbs, err := fsys.Abs(one)
227	227	if err != nil {
228	228	return one == other
229	229	}
230		- otherAbs, err := filepath.Abs(other)
	230	+ otherAbs, err := fsys.Abs(other)
231	231	if err != nil {
232	232	return one == other
233	233	}
@@ -253,7 +253,7 @@ func (a *App) rememberTheme(name string) {
253	253	// it, because ".turbo-go/settings.toml" reads better in a status bar than the
254	254	// absolute path of the same file.
255	255	func (a *App) shortPath(path string) string {
256		- working, err := os.Getwd()
	256	+ working, err := fsys.Getwd()
257	257	if err != nil {
258	258	return path
259	259	}

  import (
  	"errors"
--	"os"
  	"path/filepath"
++	"rickub.com/turbo-editors/turbo-core/fsys"
  	"rickub.com/turbo-editors/turbo-core/settings"
  	"rickub.com/turbo-editors/turbo-core/snippets"
  	"rickub.com/turbo-editors/turbo-core/tools"
  // for one just created and for one that already existed: a caller wanting to
  // remember the path wants it in both cases.
  func (a *App) createProjectFile(title string, create func(string) (string, error), alreadyThere error) (string, bool) {
--	project, err := os.Getwd()
++	project, err := fsys.Getwd()
  	if err != nil {
  		a.ShowMessage(title, "Cannot tell which directory this is:\n"+err.Error())
  		return "", false
  // somebody's repository by itself. The item is greyed out in that case anyway —
  // the dialog is for the caller that is not a menu.
  func (a *App) openProjectFile(file projectFile) {
--	project, err := os.Getwd()
++	project, err := fsys.Getwd()
  	if err != nil || !file.exists(project) {
  		a.ShowMessage(file.title, "This project has no "+file.relative+" yet.\n\n"+file.creator+" makes one.")
  		return
  // hasProjectFile reports whether the project has one of them.
  func (a *App) hasProjectFile(file projectFile) bool {
--	project, err := os.Getwd()
++	project, err := fsys.Getwd()
  	return err == nil && file.exists(project)
  }
  // this file, and a -theme flag given on the command line is the more explicit
  // statement of the two for the session it was given in.
  func (a *App) reapplySettings(path string) {
--	project, err := os.Getwd()
++	project, err := fsys.Getwd()
  	if err != nil || !samePath(path, settings.Path(a.profile, project)) {
  		return
  	}
  // absolute paths so that "./.turbo-go/settings.toml" and the absolute spelling
  // of it are recognised as one file.
  func samePath(one, other string) bool {
--	oneAbs, err := filepath.Abs(one)
++	oneAbs, err := fsys.Abs(one)
  	if err != nil {
  		return one == other
  	}
--	otherAbs, err := filepath.Abs(other)
++	otherAbs, err := fsys.Abs(other)
  	if err != nil {
  		return one == other
  	}
  // it, because ".turbo-go/settings.toml" reads better in a status bar than the
  // absolute path of the same file.
  func (a *App) shortPath(path string) string {
--	working, err := os.Getwd()
++	working, err := fsys.Getwd()
  	if err != nil {
  		return path
  	}

added app/remote.go +66 -0 Viewed

new file mode 100644
@@ -0,0 +1,66 @@
	1	+// Working on another machine: what changes in the editor when its files are
	2	+// reached over ssh.
	3	+
	4	+package app
	5	+
	6	+// Remote is what the editor needs from a machine it is editing over ssh:
	7	+// a name to show, and the command lines that open a shell or run a tool
	8	+// there. *remote.Session is one.
	9	+//
	10	+// The files themselves are not here. They come through fsys, which the
	11	+// command switches to the remote machine before the editor is made; by the
	12	+// time UseRemote is called, every file the editor reads is already remote.
	13	+type Remote interface {
	14	+ // Name is how the machine is shown: user@host.
	15	+ Name() string
	16	+ // ShellCommand is the command line of an interactive shell in dir.
	17	+ ShellCommand(dir string) []string
	18	+ // RunCommand is the command line that runs one command line in dir, with
	19	+ // a terminal on the far side when withTerminal is true.
	20	+ RunCommand(dir, command string, withTerminal bool) []string
	21	+}
	22	+
	23	+// UseRemote tells the editor its project is on another machine.
	24	+//
	25	+// From then on a terminal window is a shell over there, a tool runs over
	26	+// there, and the status bar names the machine. Agent windows are refused: an
	27	+// agent is a program on this machine, and one reading and writing the local
	28	+// disk while the editor shows the remote one would be editing a different
	29	+// project from the one on screen.
	30	+//
	31	+// No language server is started here; the command leaves that out when it
	32	+// connects, because the servers this editor knows how to find are on this
	33	+// machine and the files they would be asked about are not.
	34	+//
	35	+// session, _ := remote.Connect(ctx, target, remote.Options{})
	36	+// fsys.Use(session.FS())
	37	+// editor := app.New(screen, themeName, profile)
	38	+// editor.UseRemote(session)
	39	+func (a *App) UseRemote(r Remote) {
	40	+ a.remote = r
	41	+}
	42	+
	43	+// Remote returns the machine being edited, or nil when the files are local.
	44	+func (a *App) Remote() Remote { return a.remote }
	45	+
	46	+// agentsUnavailableOverSSH is what the agent menu and its commands say when
	47	+// the project is on another machine.
	48	+const agentsUnavailableOverSSH = "Agent windows are not available while\nediting over ssh.\n\nAn agent runs on this machine and would read\nand write this machine's files, not the ones\nthe editor is showing."
	49	+
	50	+// refuseAgentsOverSSH reports that agents are off, and whether it did.
	51	+func (a *App) refuseAgentsOverSSH() bool {
	52	+ if a.remote == nil {
	53	+ return false
	54	+ }
	55	+ a.ShowMessage("Agents", agentsUnavailableOverSSH)
	56	+ return true
	57	+}
	58	+
	59	+// connectionStatus is what the right of the status bar says about where the
	60	+// files are and the language server, when no window is open.
	61	+func (a *App) connectionStatus() string {
	62	+ if a.remote == nil {
	63	+ return a.language.Status()
	64	+ }
	65	+ return "⇄ " + a.remote.Name() + " " + a.language.Status()
	66	+}

++// Working on another machine: what changes in the editor when its files are
++// reached over ssh.
++
++package app
++
++// Remote is what the editor needs from a machine it is editing over ssh:
++// a name to show, and the command lines that open a shell or run a tool
++// there. *remote.Session is one.
++//
++// The files themselves are not here. They come through fsys, which the
++// command switches to the remote machine before the editor is made; by the
++// time UseRemote is called, every file the editor reads is already remote.
++type Remote interface {
++	// Name is how the machine is shown: user@host.
++	Name() string
++	// ShellCommand is the command line of an interactive shell in dir.
++	ShellCommand(dir string) []string
++	// RunCommand is the command line that runs one command line in dir, with
++	// a terminal on the far side when withTerminal is true.
++	RunCommand(dir, command string, withTerminal bool) []string
++}
++
++// UseRemote tells the editor its project is on another machine.
++//
++// From then on a terminal window is a shell over there, a tool runs over
++// there, and the status bar names the machine. Agent windows are refused: an
++// agent is a program on this machine, and one reading and writing the local
++// disk while the editor shows the remote one would be editing a different
++// project from the one on screen.
++//
++// No language server is started here; the command leaves that out when it
++// connects, because the servers this editor knows how to find are on this
++// machine and the files they would be asked about are not.
++//
++//	session, _ := remote.Connect(ctx, target, remote.Options{})
++//	fsys.Use(session.FS())
++//	editor := app.New(screen, themeName, profile)
++//	editor.UseRemote(session)
++func (a *App) UseRemote(r Remote) {
++	a.remote = r
++}
++
++// Remote returns the machine being edited, or nil when the files are local.
++func (a *App) Remote() Remote { return a.remote }
++
++// agentsUnavailableOverSSH is what the agent menu and its commands say when
++// the project is on another machine.
++const agentsUnavailableOverSSH = "Agent windows are not available while\nediting over ssh.\n\nAn agent runs on this machine and would read\nand write this machine's files, not the ones\nthe editor is showing."
++
++// refuseAgentsOverSSH reports that agents are off, and whether it did.
++func (a *App) refuseAgentsOverSSH() bool {
++	if a.remote == nil {
++		return false
++	}
++	a.ShowMessage("Agents", agentsUnavailableOverSSH)
++	return true
++}
++
++// connectionStatus is what the right of the status bar says about where the
++// files are and the language server, when no window is open.
++func (a *App) connectionStatus() string {
++	if a.remote == nil {
++		return a.language.Status()
++	}
++	return "⇄ " + a.remote.Name() + "  " + a.language.Status()
++}

added app/remote_test.go +132 -0 Viewed

new file mode 100644
@@ -0,0 +1,132 @@
	1	+package app
	2	+
	3	+import (
	4	+ "os"
	5	+ "slices"
	6	+ "strings"
	7	+ "testing"
	8	+
	9	+ "github.com/gdamore/tcell/v2"
	10	+
	11	+ "rickub.com/turbo-editors/turbo-core/tools"
	12	+)
	13	+
	14	+// fakeRemote stands in for an ssh session. Its command lines run /bin/sh on
	15	+// this machine, and say which directory and command they were given, so a
	16	+// test can see that the editor asked the remote side — not a local shell — to
	17	+// run something, and where.
	18	+type fakeRemote struct{}
	19	+
	20	+func (fakeRemote) Name() string { return "bob@machine" }
	21	+
	22	+func (fakeRemote) ShellCommand(dir string) []string {
	23	+ return []string{"/bin/sh", "-c", `echo "remote shell in $0"; sleep 30`, dir}
	24	+}
	25	+
	26	+func (fakeRemote) RunCommand(dir, command string, withTerminal bool) []string {
	27	+ return []string{"/bin/sh", "-c", `echo "remote run [$1] in $0 terminal=$2"`, dir, command, map[bool]string{true: "yes", false: "no"}[withTerminal]}
	28	+}
	29	+
	30	+// newRemoteApp returns an editor told its project is on the fake machine.
	31	+func newRemoteApp(t testing.T) App {
	32	+ t.Helper()
	33	+ a, _ := newToolsApp(t, "")
	34	+ a.UseRemote(fakeRemote{})
	35	+ return a
	36	+}
	37	+
	38	+func TestRemoteReturnsNilForALocalEditorAndTheMachineForARemoteOne(t *testing.T) {
	39	+ local, _ := newTestApp(t)
	40	+ if local.Remote() != nil {
	41	+ t.Errorf("Remote() = %v for an editor never told of a machine", local.Remote())
	42	+ }
	43	+ if newRemoteApp(t).Remote() == nil {
	44	+ t.Error("Remote() = nil after UseRemote")
	45	+ }
	46	+}
	47	+
	48	+func TestAPopupToolRunsOnTheRemoteMachineInTheProjectDirectory(t *testing.T) {
	49	+ a := newRemoteApp(t)
	50	+ root, _ := os.Getwd()
	51	+
	52	+ runAndDrain(t, a, tools.Tool{Name: "Test", Command: "pytest -q"})
	53	+
	54	+ lines := outputLines(a)
	55	+ want := "remote run [pytest -q] in " + root + " terminal=no"
	56	+ if !slices.ContainsFunc(lines, func(line string) bool { return strings.HasSuffix(line, want) \|\| line == want }) {
	57	+ t.Errorf("output = %q, want a line %q", lines, want)
	58	+ }
	59	+ if got := a.running.dialog.Title(); !strings.Contains(got, "pytest -q") {
	60	+ t.Errorf("the dialog is called %q, want it named after the command, not after ssh", got)
	61	+ }
	62	+}
	63	+
	64	+func TestATerminalToolRunsOnTheRemoteMachineWithATerminal(t *testing.T) {
	65	+ skipWithoutPTY(t)
	66	+ a := newRemoteApp(t)
	67	+ t.Cleanup(a.closeTerminals)
	68	+
	69	+ options := a.commandOptions("python3", "/srv/app")
	70	+ if options.Shell != "/bin/sh" \|\| options.Dir != "" \|\| options.Args[len(options.Args)-1] != "yes" {
	71	+ t.Errorf("commandOptions = %+v, want the remote's command line with a terminal, started here", options)
	72	+ }
	73	+
	74	+ a.RunTool(tools.Tool{Name: "REPL", Command: "python3", Output: tools.OutputTerminal})
	75	+ if got := a.Desktop().Active().Title(); got != "python3" {
	76	+ t.Errorf("the window is called %q, want the command", got)
	77	+ }
	78	+}
	79	+
	80	+func TestATerminalWindowIsAShellOnTheRemoteMachine(t *testing.T) {
	81	+ skipWithoutPTY(t)
	82	+ a := newRemoteApp(t)
	83	+ t.Cleanup(a.closeTerminals)
	84	+ screen := a.screen.(tcell.SimulationScreen)
	85	+
	86	+ options, name := a.shellOptions("/home/bob/app")
	87	+ if name != "bob@machine" \|\| options.Dir != "" \|\| options.Args[len(options.Args)-1] != "/home/bob/app" {
	88	+ t.Errorf("shellOptions = %+v, %q", options, name)
	89	+ }
	90	+
	91	+ // The directory is the working directory, too long for one line of the
	92	+ // window; that it was passed at all is checked through shellOptions above.
	93	+ a.NewTerminal()
	94	+ waitOnScreen(t, a, screen, "NewTerminal", "remote shell in /")
	95	+ if got := a.Desktop().Active().Title(); got != "bob@machine" {
	96	+ t.Errorf("the window is called %q, want the machine", got)
	97	+ }
	98	+}
	99	+
	100	+func TestTheAgentMenuSaysAgentsAreNotAvailableOverSSH(t *testing.T) {
	101	+ a := newRemoteApp(t)
	102	+
	103	+ items := a.agentItems()
	104	+ if len(items) != 1 \|\| !strings.Contains(items[0].Label, "not available over ssh") \|\| items[0].Enabled() {
	105	+ t.Errorf("agent menu = %+v, want one disabled line saying why", items)
	106	+ }
	107	+}
	108	+
	109	+func TestOpeningAnAgentOverSSHExplainsWhyNot(t *testing.T) {
	110	+ for name, open := range map[string]func(a *App){
	111	+ "NewAgent": func(a *App) { a.NewAgent("anything") },
	112	+ "CreateAgentsFile": func(a *App) { a.CreateAgentsFile() },
	113	+ "AgentStatus": func(a *App) { a.AgentStatus() },
	114	+ } {
	115	+ a := newRemoteApp(t)
	116	+ open(a)
	117	+ if a.Modals() != 1 \|\| len(a.agents) != 0 {
	118	+ t.Errorf("%s: Modals() = %d, agents = %d; want one message and no agent", name, a.Modals(), len(a.agents))
	119	+ }
	120	+ }
	121	+}
	122	+
	123	+func TestTheStatusBarNamesTheRemoteMachine(t *testing.T) {
	124	+ a := newRemoteApp(t)
	125	+ if got := a.connectionStatus(); !strings.HasPrefix(got, "⇄ bob@machine") {
	126	+ t.Errorf("connectionStatus() = %q, want it to start with the machine", got)
	127	+ }
	128	+ local, _ := newTestApp(t)
	129	+ if got := local.connectionStatus(); strings.Contains(got, "⇄") {
	130	+ t.Errorf("a local editor's status names a machine: %q", got)
	131	+ }
	132	+}

++package app
++
++import (
++	"os"
++	"slices"
++	"strings"
++	"testing"
++
++	"github.com/gdamore/tcell/v2"
++
++	"rickub.com/turbo-editors/turbo-core/tools"
++)
++
++// fakeRemote stands in for an ssh session. Its command lines run /bin/sh on
++// this machine, and say which directory and command they were given, so a
++// test can see that the editor asked the remote side — not a local shell — to
++// run something, and where.
++type fakeRemote struct{}
++
++func (fakeRemote) Name() string { return "bob@machine" }
++
++func (fakeRemote) ShellCommand(dir string) []string {
++	return []string{"/bin/sh", "-c", `echo "remote shell in $0"; sleep 30`, dir}
++}
++
++func (fakeRemote) RunCommand(dir, command string, withTerminal bool) []string {
++	return []string{"/bin/sh", "-c", `echo "remote run [$1] in $0 terminal=$2"`, dir, command, map[bool]string{true: "yes", false: "no"}[withTerminal]}
++}
++
++// newRemoteApp returns an editor told its project is on the fake machine.
++func newRemoteApp(t *testing.T) *App {
++	t.Helper()
++	a, _ := newToolsApp(t, "")
++	a.UseRemote(fakeRemote{})
++	return a
++}
++
++func TestRemoteReturnsNilForALocalEditorAndTheMachineForARemoteOne(t *testing.T) {
++	local, _ := newTestApp(t)
++	if local.Remote() != nil {
++		t.Errorf("Remote() = %v for an editor never told of a machine", local.Remote())
++	}
++	if newRemoteApp(t).Remote() == nil {
++		t.Error("Remote() = nil after UseRemote")
++	}
++}
++
++func TestAPopupToolRunsOnTheRemoteMachineInTheProjectDirectory(t *testing.T) {
++	a := newRemoteApp(t)
++	root, _ := os.Getwd()
++
++	runAndDrain(t, a, tools.Tool{Name: "Test", Command: "pytest -q"})
++
++	lines := outputLines(a)
++	want := "remote run [pytest -q] in " + root + " terminal=no"
++	if !slices.ContainsFunc(lines, func(line string) bool { return strings.HasSuffix(line, want) || line == want }) {
++		t.Errorf("output = %q, want a line %q", lines, want)
++	}
++	if got := a.running.dialog.Title(); !strings.Contains(got, "pytest -q") {
++		t.Errorf("the dialog is called %q, want it named after the command, not after ssh", got)
++	}
++}
++
++func TestATerminalToolRunsOnTheRemoteMachineWithATerminal(t *testing.T) {
++	skipWithoutPTY(t)
++	a := newRemoteApp(t)
++	t.Cleanup(a.closeTerminals)
++
++	options := a.commandOptions("python3", "/srv/app")
++	if options.Shell != "/bin/sh" || options.Dir != "" || options.Args[len(options.Args)-1] != "yes" {
++		t.Errorf("commandOptions = %+v, want the remote's command line with a terminal, started here", options)
++	}
++
++	a.RunTool(tools.Tool{Name: "REPL", Command: "python3", Output: tools.OutputTerminal})
++	if got := a.Desktop().Active().Title(); got != "python3" {
++		t.Errorf("the window is called %q, want the command", got)
++	}
++}
++
++func TestATerminalWindowIsAShellOnTheRemoteMachine(t *testing.T) {
++	skipWithoutPTY(t)
++	a := newRemoteApp(t)
++	t.Cleanup(a.closeTerminals)
++	screen := a.screen.(tcell.SimulationScreen)
++
++	options, name := a.shellOptions("/home/bob/app")
++	if name != "bob@machine" || options.Dir != "" || options.Args[len(options.Args)-1] != "/home/bob/app" {
++		t.Errorf("shellOptions = %+v, %q", options, name)
++	}
++
++	// The directory is the working directory, too long for one line of the
++	// window; that it was passed at all is checked through shellOptions above.
++	a.NewTerminal()
++	waitOnScreen(t, a, screen, "NewTerminal", "remote shell in /")
++	if got := a.Desktop().Active().Title(); got != "bob@machine" {
++		t.Errorf("the window is called %q, want the machine", got)
++	}
++}
++
++func TestTheAgentMenuSaysAgentsAreNotAvailableOverSSH(t *testing.T) {
++	a := newRemoteApp(t)
++
++	items := a.agentItems()
++	if len(items) != 1 || !strings.Contains(items[0].Label, "not available over ssh") || items[0].Enabled() {
++		t.Errorf("agent menu = %+v, want one disabled line saying why", items)
++	}
++}
++
++func TestOpeningAnAgentOverSSHExplainsWhyNot(t *testing.T) {
++	for name, open := range map[string]func(a *App){
++		"NewAgent":         func(a *App) { a.NewAgent("anything") },
++		"CreateAgentsFile": func(a *App) { a.CreateAgentsFile() },
++		"AgentStatus":      func(a *App) { a.AgentStatus() },
++	} {
++		a := newRemoteApp(t)
++		open(a)
++		if a.Modals() != 1 || len(a.agents) != 0 {
++			t.Errorf("%s: Modals() = %d, agents = %d; want one message and no agent", name, a.Modals(), len(a.agents))
++		}
++	}
++}
++
++func TestTheStatusBarNamesTheRemoteMachine(t *testing.T) {
++	a := newRemoteApp(t)
++	if got := a.connectionStatus(); !strings.HasPrefix(got, "⇄ bob@machine") {
++		t.Errorf("connectionStatus() = %q, want it to start with the machine", got)
++	}
++	local, _ := newTestApp(t)
++	if got := local.connectionStatus(); strings.Contains(got, "⇄") {
++		t.Errorf("a local editor's status names a machine: %q", got)
++	}
++}

modified app/root.go +4 -4 Viewed

@@ -4,9 +4,9 @@
4	4	package app
5	5
6	6	import (
7		- "os"
8	7	"path/filepath"
9	8
	9	+ "rickub.com/turbo-editors/turbo-core/fsys"
10	10	"rickub.com/turbo-editors/turbo-core/profile"
11	11	)
12	12
@@ -29,12 +29,12 @@ import (
29	29	// root := app.ProjectRoot(golang.Profile(), []string{"internal/app/app.go"})
30	30	// editor.StartLanguageServer(ctx, root)
31	31	func ProjectRoot(p profile.Profile, files []string) string {
32		- start, err := os.Getwd()
	32	+ start, err := fsys.Getwd()
33	33	if err != nil {
34	34	start = "."
35	35	}
36	36	if len(files) > 0 {
37		- if absolute, err := filepath.Abs(files[0]); err == nil {
	37	+ if absolute, err := fsys.Abs(files[0]); err == nil {
38	38	start = filepath.Dir(absolute)
39	39	}
40	40	}
@@ -68,7 +68,7 @@ func markedRoot(start string, markers []string) string {
68	68	// holdsAny reports whether a directory holds one of the marker files.
69	69	func holdsAny(directory string, markers []string) bool {
70	70	for _, marker := range markers {
71		- if _, err := os.Stat(filepath.Join(directory, marker)); err == nil {
	71	+ if _, err := fsys.Stat(filepath.Join(directory, marker)); err == nil {
72	72	return true
73	73	}
74	74	}

  package app
  import (
--	"os"
  	"path/filepath"
++	"rickub.com/turbo-editors/turbo-core/fsys"
  	"rickub.com/turbo-editors/turbo-core/profile"
  )
  //	root := app.ProjectRoot(golang.Profile(), []string{"internal/app/app.go"})
  //	editor.StartLanguageServer(ctx, root)
  func ProjectRoot(p profile.Profile, files []string) string {
--	start, err := os.Getwd()
++	start, err := fsys.Getwd()
  	if err != nil {
  		start = "."
  	}
  	if len(files) > 0 {
--		if absolute, err := filepath.Abs(files[0]); err == nil {
++		if absolute, err := fsys.Abs(files[0]); err == nil {
  			start = filepath.Dir(absolute)
  		}
  	}
  // holdsAny reports whether a directory holds one of the marker files.
  func holdsAny(directory string, markers []string) bool {
  	for _, marker := range markers {
--		if _, err := os.Stat(filepath.Join(directory, marker)); err == nil {
++		if _, err := fsys.Stat(filepath.Join(directory, marker)); err == nil {
  			return true
  		}
  	}

modified app/snippets.go +2 -3 Viewed

@@ -4,8 +4,7 @@
4	4	package app
5	5
6	6	import (
7		- "os"
8		-
	7	+ "rickub.com/turbo-editors/turbo-core/fsys"
9	8	"rickub.com/turbo-editors/turbo-core/snippets"
10	9	"rickub.com/turbo-editors/turbo-core/syntax"
11	10	"rickub.com/turbo-editors/turbo-core/ui"
@@ -87,7 +86,7 @@ func snippetSubmenu(a App, list []snippets.Snippet) []ui.MenuItem {
87	86
88	87	// loadSnippets reads the project's snippets and the user's own.
89	88	func (a *App) loadSnippets() (snippets.List, error) {
90		- working, err := os.Getwd()
	89	+ working, err := fsys.Getwd()
91	90	if err != nil {
92	91	return snippets.List{}, err
93	92	}

  package app
  import (
--	"os"
++	"rickub.com/turbo-editors/turbo-core/fsys"
--
  	"rickub.com/turbo-editors/turbo-core/snippets"
  	"rickub.com/turbo-editors/turbo-core/syntax"
  	"rickub.com/turbo-editors/turbo-core/ui"
  // loadSnippets reads the project's snippets and the user's own.
  func (a *App) loadSnippets() (snippets.List, error) {
--	working, err := os.Getwd()
++	working, err := fsys.Getwd()
  	if err != nil {
  		return snippets.List{}, err
  	}

modified app/terminals.go +32 -4 Viewed

@@ -5,11 +5,12 @@ package app
5	5
6	6	import (
7	7	"errors"
8		- "os"
9	8	"path/filepath"
10	9
11	10	"rickub.com/turbo-editors/turbo-core/editor"
	11	+ "rickub.com/turbo-editors/turbo-core/fsys"
12	12	"rickub.com/turbo-editors/turbo-core/terminal"
	13	+ "rickub.com/turbo-editors/turbo-core/tools"
13	14	"rickub.com/turbo-editors/turbo-core/ui"
14	15	)
15	16
@@ -25,8 +26,10 @@ func (a *App) NewTerminal() {
25	26	// The shell writes from a goroutine of its own, so neither callback may
26	27	// touch the desktop: they only ask the event loop to come round again. They
27	28	// are options rather than fields because NewView starts that goroutine.
	29	+ options, name := a.shellOptions(a.terminalDirectory())
28	30	view, err := terminal.NewView(terminal.ViewOptions{
29		- Options: terminal.Options{Dir: a.terminalDirectory()},
	31	+ Options: options,
	32	+ Name: name,
30	33	OnChange: a.wake,
31	34	OnExit: a.wake,
32	35	})
@@ -60,16 +63,41 @@ func (a *App) reportTerminalFailure(err error) {
60	63	// being edited, or the editor's own working directory.
61	64	func (a *App) terminalDirectory() string {
62	65	if view := a.activeView(); view != nil && view.Buffer().Path() != "" {
63		- if absolute, err := filepath.Abs(view.Buffer().Path()); err == nil {
	66	+ if absolute, err := fsys.Abs(view.Buffer().Path()); err == nil {
64	67	return filepath.Dir(absolute)
65	68	}
66	69	}
67		- if working, err := os.Getwd(); err == nil {
	70	+ if working, err := fsys.Getwd(); err == nil {
68	71	return working
69	72	}
70	73	return ""
71	74	}
72	75
	76	+// shellOptions says how to start an interactive shell in dir, and what to
	77	+// call its window until the shell names itself.
	78	+//
	79	+// Locally that is the user's own shell, started in dir. Over ssh it is ssh,
	80	+// started wherever this process is — dir is a directory on the other machine,
	81	+// and it is the remote shell that changes into it.
	82	+func (a *App) shellOptions(dir string) (terminal.Options, string) {
	83	+ if a.remote == nil {
	84	+ return terminal.Options{Dir: dir}, ""
	85	+ }
	86	+ argv := a.remote.ShellCommand(dir)
	87	+ return terminal.Options{Shell: argv[0], Args: argv[1:]}, a.remote.Name()
	88	+}
	89	+
	90	+// commandOptions says how to run one command line in dir in a terminal
	91	+// window: the shell tools uses, locally; ssh with a terminal on the far side,
	92	+// remotely.
	93	+func (a *App) commandOptions(command, dir string) terminal.Options {
	94	+ if a.remote == nil {
	95	+ return terminal.Options{Shell: tools.Shell(), Args: tools.ShellArgs(command), Dir: dir}
	96	+ }
	97	+ argv := a.remote.RunCommand(dir, command, true)
	98	+ return terminal.Options{Shell: argv[0], Args: argv[1:]}
	99	+}
	100	+
73	101	// closeTerminal ends a shell and takes its window away.
74	102	//
75	103	// A terminal is not asked about unsaved work: there is none. What it holds is

  import (
  	"errors"
--	"os"
  	"path/filepath"
  	"rickub.com/turbo-editors/turbo-core/editor"
++	"rickub.com/turbo-editors/turbo-core/fsys"
  	"rickub.com/turbo-editors/turbo-core/terminal"
++	"rickub.com/turbo-editors/turbo-core/tools"
  	"rickub.com/turbo-editors/turbo-core/ui"
  )
  	// The shell writes from a goroutine of its own, so neither callback may
  	// touch the desktop: they only ask the event loop to come round again. They
  	// are options rather than fields because NewView starts that goroutine.
++	options, name := a.shellOptions(a.terminalDirectory())
  	view, err := terminal.NewView(terminal.ViewOptions{
--		Options:  terminal.Options{Dir: a.terminalDirectory()},
++		Options:  options,
++		Name:     name,
  		OnChange: a.wake,
  		OnExit:   a.wake,
  	})
  // being edited, or the editor's own working directory.
  func (a *App) terminalDirectory() string {
  	if view := a.activeView(); view != nil && view.Buffer().Path() != "" {
--		if absolute, err := filepath.Abs(view.Buffer().Path()); err == nil {
++		if absolute, err := fsys.Abs(view.Buffer().Path()); err == nil {
  			return filepath.Dir(absolute)
  		}
  	}
--	if working, err := os.Getwd(); err == nil {
++	if working, err := fsys.Getwd(); err == nil {
  		return working
  	}
  	return ""
  }
++// shellOptions says how to start an interactive shell in dir, and what to
++// call its window until the shell names itself.
++//
++// Locally that is the user's own shell, started in dir. Over ssh it is ssh,
++// started wherever this process is — dir is a directory on the other machine,
++// and it is the remote shell that changes into it.
++func (a *App) shellOptions(dir string) (terminal.Options, string) {
++	if a.remote == nil {
++		return terminal.Options{Dir: dir}, ""
++	}
++	argv := a.remote.ShellCommand(dir)
++	return terminal.Options{Shell: argv[0], Args: argv[1:]}, a.remote.Name()
++}
++
++// commandOptions says how to run one command line in dir in a terminal
++// window: the shell tools uses, locally; ssh with a terminal on the far side,
++// remotely.
++func (a *App) commandOptions(command, dir string) terminal.Options {
++	if a.remote == nil {
++		return terminal.Options{Shell: tools.Shell(), Args: tools.ShellArgs(command), Dir: dir}
++	}
++	argv := a.remote.RunCommand(dir, command, true)
++	return terminal.Options{Shell: argv[0], Args: argv[1:]}
++}
++
  // closeTerminal ends a shell and takes its window away.
  //
  // A terminal is not asked about unsaved work: there is none. What it holds is

modified app/toolchain.go +15 -10 Viewed

@@ -7,11 +7,11 @@ package app
7	7
8	8	import (
9	9	"fmt"
10		- "os"
11	10	"strconv"
12	11	"strings"
13	12
14	13	"rickub.com/turbo-editors/turbo-core/buffer"
	14	+ "rickub.com/turbo-editors/turbo-core/fsys"
15	15
16	16	"rickub.com/turbo-editors/turbo-core/terminal"
17	17	"rickub.com/turbo-editors/turbo-core/tools"
@@ -81,7 +81,7 @@ func (a App) commandItems(menu string) []ui.MenuItem {
81	81
82	82	// loadTools reads the project's tools file.
83	83	func (a *App) loadTools() (tools.List, error) {
84		- working, err := os.Getwd()
	84	+ working, err := fsys.Getwd()
85	85	if err != nil {
86	86	return tools.List{}, err
87	87	}
@@ -146,7 +146,7 @@ func (a *App) rememberToolValues(tool string, values map[string]string) {
146	146	// runFilledTool runs a command whose placeholders, if it had any, are already
147	147	// substituted, and shows its output where the tool asked for.
148	148	func (a *App) runFilledTool(tool tools.Tool, command string) {
149		- working, err := os.Getwd()
	149	+ working, err := fsys.Getwd()
150	150	if err != nil {
151	151	a.ShowMessage(a.toolsMenuName(), "Cannot tell which directory this is:\n"+err.Error())
152	152	return
@@ -168,12 +168,8 @@ func (a *App) runFilledTool(tool tools.Tool, command string) {
168	168	func (a *App) runInTerminal(command, dir string) {
169	169	view, err := terminal.NewView(terminal.ViewOptions{
170	170	// The same shell the popup uses, told to run one command line and
171		- // exit; tools knows which shell that is on this platform.
172		- Options: terminal.Options{
173		- Shell: tools.Shell(),
174		- Args: tools.ShellArgs(command),
175		- Dir: dir,
176		- },
	171	+ // exit — on this machine, or on the one being edited.
	172	+ Options: a.commandOptions(command, dir),
177	173	Name: command,
178	174	OnChange: a.wake,
179	175	// A command that has finished may have rewritten the files on disk,
@@ -204,7 +200,7 @@ func (a *App) runInTerminal(command, dir string) {
204	200	// typed at that moment, and watching a build's output arrive is most of what
205	201	// makes waiting for it bearable.
206	202	func (a *App) runCaptured(tool tools.Tool, command, dir string) {
207		- run, err := tools.Start(command, dir, a.wake)
	203	+ run, err := a.startTool(command, dir)
208	204	if err != nil {
209	205	a.ShowMessage(a.toolsMenuName(), err.Error())
210	206	return
@@ -219,6 +215,15 @@ func (a *App) runCaptured(tool tools.Tool, command, dir string) {
219	215	a.pushModal(dialog, func(ui.Result) { a.finishRun() })
220	216	}
221	217
	218	+// startTool starts a command line with its output collected: with /bin/sh
	219	+// (or cmd.exe) here, or with /bin/sh on the machine being edited.
	220	+func (a App) startTool(command, dir string) (tools.Run, error) {
	221	+ if a.remote == nil {
	222	+ return tools.Start(command, dir, a.wake)
	223	+ }
	224	+ return tools.StartProgram(command, a.remote.RunCommand(dir, command, false), a.wake)
	225	+}
	226	+
222	227	// toolRun is the command whose output is showing, and where it goes.
223	228	type toolRun struct {
224	229	run *tools.Run

  import (
  	"fmt"
--	"os"
  	"strconv"
  	"strings"
  	"rickub.com/turbo-editors/turbo-core/buffer"
++	"rickub.com/turbo-editors/turbo-core/fsys"
  	"rickub.com/turbo-editors/turbo-core/terminal"
  	"rickub.com/turbo-editors/turbo-core/tools"
  // loadTools reads the project's tools file.
  func (a *App) loadTools() (tools.List, error) {
--	working, err := os.Getwd()
++	working, err := fsys.Getwd()
  	if err != nil {
  		return tools.List{}, err
  	}
  // runFilledTool runs a command whose placeholders, if it had any, are already
  // substituted, and shows its output where the tool asked for.
  func (a *App) runFilledTool(tool tools.Tool, command string) {
--	working, err := os.Getwd()
++	working, err := fsys.Getwd()
  	if err != nil {
  		a.ShowMessage(a.toolsMenuName(), "Cannot tell which directory this is:\n"+err.Error())
  		return
  func (a *App) runInTerminal(command, dir string) {
  	view, err := terminal.NewView(terminal.ViewOptions{
  		// The same shell the popup uses, told to run one command line and
--		// exit; tools knows which shell that is on this platform.
++		// exit — on this machine, or on the one being edited.
--		Options: terminal.Options{
++		Options:  a.commandOptions(command, dir),
--			Shell: tools.Shell(),
--			Args:  tools.ShellArgs(command),
--			Dir:   dir,
--		},
  		Name:     command,
  		OnChange: a.wake,
  		// A command that has finished may have rewritten the files on disk,
  // typed at that moment, and watching a build's output arrive is most of what
  // makes waiting for it bearable.
  func (a *App) runCaptured(tool tools.Tool, command, dir string) {
--	run, err := tools.Start(command, dir, a.wake)
++	run, err := a.startTool(command, dir)
  	if err != nil {
  		a.ShowMessage(a.toolsMenuName(), err.Error())
  		return
  	a.pushModal(dialog, func(ui.Result) { a.finishRun() })
  }
++// startTool starts a command line with its output collected: with /bin/sh
++// (or cmd.exe) here, or with /bin/sh on the machine being edited.
++func (a *App) startTool(command, dir string) (*tools.Run, error) {
++	if a.remote == nil {
++		return tools.Start(command, dir, a.wake)
++	}
++	return tools.StartProgram(command, a.remote.RunCommand(dir, command, false), a.wake)
++}
++
  // toolRun is the command whose output is showing, and where it goes.
  type toolRun struct {
  	run    *tools.Run

modified app/toolmenus.go +3 -3 Viewed

@@ -4,10 +4,10 @@
4	4	package app
5	5
6	6	import (
7		- "os"
8	7	"time"
9	8	"unicode"
10	9
	10	+ "rickub.com/turbo-editors/turbo-core/fsys"
11	11	"rickub.com/turbo-editors/turbo-core/tools"
12	12	"rickub.com/turbo-editors/turbo-core/ui"
13	13	)
@@ -129,7 +129,7 @@ type fileStamp struct {
129	129	// stampOf describes a file. A file that is not there stamps as the zero value,
130	130	// so appearing and disappearing both register as changes.
131	131	func stampOf(path string) fileStamp {
132		- info, err := os.Stat(path)
	132	+ info, err := fsys.Stat(path)
133	133	if err != nil {
134	134	return fileStamp{}
135	135	}
@@ -138,7 +138,7 @@ func stampOf(path string) fileStamp {
138	138
139	139	// toolsFileStamp describes the project's tools file.
140	140	func (a *App) toolsFileStamp() fileStamp {
141		- working, err := os.Getwd()
	141	+ working, err := fsys.Getwd()
142	142	if err != nil {
143	143	return fileStamp{}
144	144	}

  package app
  import (
--	"os"
  	"time"
  	"unicode"
++	"rickub.com/turbo-editors/turbo-core/fsys"
  	"rickub.com/turbo-editors/turbo-core/tools"
  	"rickub.com/turbo-editors/turbo-core/ui"
  )
  // stampOf describes a file. A file that is not there stamps as the zero value,
  // so appearing and disappearing both register as changes.
  func stampOf(path string) fileStamp {
--	info, err := os.Stat(path)
++	info, err := fsys.Stat(path)
  	if err != nil {
  		return fileStamp{}
  	}
  // toolsFileStamp describes the project's tools file.
  func (a *App) toolsFileStamp() fileStamp {
--	working, err := os.Getwd()
++	working, err := fsys.Getwd()
  	if err != nil {
  		return fileStamp{}
  	}

modified app/tree.go +2 -3 Viewed

@@ -4,9 +4,8 @@
4	4	package app
5	5
6	6	import (
7		- "os"
8		-
9	7	"rickub.com/turbo-editors/turbo-core/filetree"
	8	+ "rickub.com/turbo-editors/turbo-core/fsys"
10	9	"rickub.com/turbo-editors/turbo-core/ui"
11	10	)
12	11
@@ -26,7 +25,7 @@ func (a *App) ProjectTree() {
26	25	return
27	26	}
28	27
29		- root, err := os.Getwd()
	28	+ root, err := fsys.Getwd()
30	29	if err != nil {
31	30	a.ShowMessage("Project tree", "Cannot tell which directory this is:\n"+err.Error())
32	31	return

  package app
  import (
--	"os"
--
  	"rickub.com/turbo-editors/turbo-core/filetree"
++	"rickub.com/turbo-editors/turbo-core/fsys"
  	"rickub.com/turbo-editors/turbo-core/ui"
  )
  		return
  	}
--	root, err := os.Getwd()
++	root, err := fsys.Getwd()
  	if err != nil {
  		a.ShowMessage("Project tree", "Cannot tell which directory this is:\n"+err.Error())
  		return

modified buffer/README.md +2 -0 Viewed

@@ -4,6 +4,8 @@ The text of one edited file: its lines, the cursor, the selection and the undo h
4	4
5	5	This package knows nothing about terminals, rendering or syntax colouring. Everything here is plain data manipulation, which is why it is fully testable on its own and why every other package can depend on it without dragging a terminal in.
6	6
	7	+Opening, reloading and saving go through `fsys`, so under `-ssh` the file is the remote machine's. A save still goes to a temporary file beside the target and is renamed over it, keeping the mode of the file it replaces.
	8	+
7	9	## Model
8	10
9	11	- Text is a slice of lines, each a slice of runes. A buffer always holds at least one line, so an empty buffer is one empty line rather than none.

  This package knows nothing about terminals, rendering or syntax colouring. Everything here is plain data manipulation, which is why it is fully testable on its own and why every other package can depend on it without dragging a terminal in.
++Opening, reloading and saving go through `fsys`, so under `-ssh` the file is the remote machine's. A save still goes to a temporary file beside the target and is renamed over it, keeping the mode of the file it replaces.
++
  ## Model
  - Text is a slice of lines, each a slice of runes. A buffer always holds **at least one line**, so an empty buffer is one empty line rather than none.

modified buffer/file.go +14 -44 Viewed

@@ -4,7 +4,8 @@ import (
4	4	"errors"
5	5	"fmt"
6	6	"os"
7		- "path/filepath"
	7	+
	8	+ "rickub.com/turbo-editors/turbo-core/fsys"
8	9	)
9	10
10	11	// ErrNoPath is returned by Save when the buffer has never been given a file
@@ -31,7 +32,7 @@ func Open(path string) (*Buffer, error) {
31	32	b := New()
32	33	b.path = path
33	34
34		- data, err := os.ReadFile(path)
	35	+ data, err := fsys.ReadFile(path)
35	36	if errors.Is(err, os.ErrNotExist) {
36	37	b.clearHistory()
37	38	return b, nil
@@ -73,7 +74,7 @@ func (b *Buffer) Reload() (bool, error) {
73	74	return false, ErrModified
74	75	}
75	76
76		- data, err := os.ReadFile(b.path)
	77	+ data, err := fsys.ReadFile(b.path)
77	78	if err != nil {
78	79	return false, fmt.Errorf("buffer: reload %s: %w", b.path, err)
79	80	}
@@ -103,7 +104,8 @@ func (b *Buffer) Save() error {
103	104	//
104	105	// The write goes to a temporary file in the same directory which is then
105	106	// renamed over the target, so an interrupted save cannot leave a half-written
106		-// source file behind.
	107	+// source file behind. Like every read and write here it goes through fsys, so
	108	+// under -ssh the file is the remote one.
107	109	func (b *Buffer) SaveAs(path string) error {
108	110	if err := writeFileAtomically(path, []byte(b.Text())); err != nil {
109	111	return err
@@ -113,56 +115,24 @@ func (b *Buffer) SaveAs(path string) error {
113	115	return nil
114	116	}
115	117
116		-// writeFileAtomically writes data to path via a temporary file and a rename,
117		-// so that readers of path only ever see the old content or the new one.
	118	+// writeFileAtomically writes data to path so that readers of path only ever
	119	+// see the old content or the new one, keeping the permissions of the file it
	120	+// replaces. It goes through fsys, so the file may be on another machine.
118	121	func writeFileAtomically(path string, data []byte) error {
119		- dir := filepath.Dir(path)
120		-
121		- tmp, err := os.CreateTemp(dir, "."+filepath.Base(path)+".*")
122		- if err != nil {
123		- return fmt.Errorf("buffer: save %s: %w", path, err)
124		- }
125		- tmpName := tmp.Name()
126		-
127		- // CreateTemp makes the file readable by its owner only; the rename would
128		- // otherwise silently tighten the permissions of an existing source file.
129		- if err := os.Chmod(tmpName, modeOf(path)); err != nil {
130		- tmp.Close()
131		- os.Remove(tmpName)
132		- return fmt.Errorf("buffer: save %s: %w", path, err)
133		- }
134		-
135		- // From here on every failure must remove the temporary file, or a failed
136		- // save would litter the user's source directory.
137		- if err := writeAndClose(tmp, data); err != nil {
138		- os.Remove(tmpName)
139		- return fmt.Errorf("buffer: save %s: %w", path, err)
140		- }
141		-
142		- if err := os.Rename(tmpName, path); err != nil {
143		- os.Remove(tmpName)
	122	+ if err := fsys.WriteFileAtomic(path, data, modeOf(path)); err != nil {
144	123	return fmt.Errorf("buffer: save %s: %w", path, err)
145	124	}
146	125	return nil
147	126	}
148	127
149		-// writeAndClose writes data to f and closes it, reporting the first failure.
150		-func writeAndClose(f *os.File, data []byte) error {
151		- if _, err := f.Write(data); err != nil {
152		- f.Close()
153		- return err
154		- }
155		- return f.Close()
156		-}
157		-
158		-// defaultFileMode is what a source file created by the editor gets, before the
159		-// process umask is applied.
	128	+// defaultFileMode is what a source file created by the editor gets.
160	129	const defaultFileMode = 0o644
161	130
162	131	// modeOf returns the permissions of an existing file, or defaultFileMode when
163		-// the file is new or cannot be inspected.
	132	+// the file is new or cannot be inspected. Without it the temporary file's
	133	+// permissions would silently replace those of the source file being saved.
164	134	func modeOf(path string) os.FileMode {
165		- info, err := os.Stat(path)
	135	+ info, err := fsys.Stat(path)
166	136	if err != nil {
167	137	return defaultFileMode
168	138	}

  	"errors"
  	"fmt"
  	"os"
--	"path/filepath"
++
++	"rickub.com/turbo-editors/turbo-core/fsys"
  )
  // ErrNoPath is returned by Save when the buffer has never been given a file
  	b := New()
  	b.path = path
--	data, err := os.ReadFile(path)
++	data, err := fsys.ReadFile(path)
  	if errors.Is(err, os.ErrNotExist) {
  		b.clearHistory()
  		return b, nil
  		return false, ErrModified
  	}
--	data, err := os.ReadFile(b.path)
++	data, err := fsys.ReadFile(b.path)
  	if err != nil {
  		return false, fmt.Errorf("buffer: reload %s: %w", b.path, err)
  	}
  //
  // The write goes to a temporary file in the same directory which is then
  // renamed over the target, so an interrupted save cannot leave a half-written
--// source file behind.
++// source file behind. Like every read and write here it goes through fsys, so
++// under -ssh the file is the remote one.
  func (b *Buffer) SaveAs(path string) error {
  	if err := writeFileAtomically(path, []byte(b.Text())); err != nil {
  		return err
  	return nil
  }
--// writeFileAtomically writes data to path via a temporary file and a rename,
++// writeFileAtomically writes data to path so that readers of path only ever
--// so that readers of path only ever see the old content or the new one.
++// see the old content or the new one, keeping the permissions of the file it
++// replaces. It goes through fsys, so the file may be on another machine.
  func writeFileAtomically(path string, data []byte) error {
--	dir := filepath.Dir(path)
++	if err := fsys.WriteFileAtomic(path, data, modeOf(path)); err != nil {
--
--	tmp, err := os.CreateTemp(dir, "."+filepath.Base(path)+".*")
--	if err != nil {
--		return fmt.Errorf("buffer: save %s: %w", path, err)
--	}
--	tmpName := tmp.Name()
--
--	// CreateTemp makes the file readable by its owner only; the rename would
--	// otherwise silently tighten the permissions of an existing source file.
--	if err := os.Chmod(tmpName, modeOf(path)); err != nil {
--		tmp.Close()
--		os.Remove(tmpName)
--		return fmt.Errorf("buffer: save %s: %w", path, err)
--	}
--
--	// From here on every failure must remove the temporary file, or a failed
--	// save would litter the user's source directory.
--	if err := writeAndClose(tmp, data); err != nil {
--		os.Remove(tmpName)
--		return fmt.Errorf("buffer: save %s: %w", path, err)
--	}
--
--	if err := os.Rename(tmpName, path); err != nil {
--		os.Remove(tmpName)
  		return fmt.Errorf("buffer: save %s: %w", path, err)
  	}
  	return nil
  }
--// writeAndClose writes data to f and closes it, reporting the first failure.
++// defaultFileMode is what a source file created by the editor gets.
--func writeAndClose(f *os.File, data []byte) error {
--	if _, err := f.Write(data); err != nil {
--		f.Close()
--		return err
--	}
--	return f.Close()
--}
--
--// defaultFileMode is what a source file created by the editor gets, before the
--// process umask is applied.
  const defaultFileMode = 0o644
  // modeOf returns the permissions of an existing file, or defaultFileMode when
--// the file is new or cannot be inspected.
++// the file is new or cannot be inspected. Without it the temporary file's
++// permissions would silently replace those of the source file being saved.
  func modeOf(path string) os.FileMode {
--	info, err := os.Stat(path)
++	info, err := fsys.Stat(path)
  	if err != nil {
  		return defaultFileMode
  	}

added buffer/fsys_test.go +81 -0 Viewed

new file mode 100644
@@ -0,0 +1,81 @@
	1	+package buffer
	2	+
	3	+import (
	4	+ "testing"
	5	+
	6	+ "rickub.com/turbo-editors/turbo-core/fsys"
	7	+ "rickub.com/turbo-editors/turbo-core/fsys/fsystest"
	8	+)
	9	+
	10	+// useMemory makes the buffer read and write a file system that exists only in
	11	+// memory, so a file found there proves the buffer went through fsys.
	12	+func useMemory(t testing.T) fsystest.Memory {
	13	+ t.Helper()
	14	+ memory := fsystest.New("/remote/project")
	15	+ previous := fsys.Use(memory)
	16	+ t.Cleanup(func() { fsys.Use(previous) })
	17	+ return memory
	18	+}
	19	+
	20	+func TestOpenAndSaveGoThroughTheCurrentFileSystem(t *testing.T) {
	21	+ memory := useMemory(t)
	22	+ memory.AddFile("/remote/project/app.py", "x = 1\n")
	23	+
	24	+ b, err := Open("/remote/project/app.py")
	25	+ if err != nil {
	26	+ t.Fatal(err)
	27	+ }
	28	+ if b.Text() != "x = 1\n" {
	29	+ t.Fatalf("Text() = %q", b.Text())
	30	+ }
	31	+ b.SetText("x = 2\n")
	32	+ if err := b.Save(); err != nil {
	33	+ t.Fatal(err)
	34	+ }
	35	+ if got, _ := memory.File("/remote/project/app.py"); got != "x = 2\n" {
	36	+ t.Errorf("saved file = %q", got)
	37	+ }
	38	+}
	39	+
	40	+func TestSavingKeepsTheModeOfTheFileItReplaces(t *testing.T) {
	41	+ memory := useMemory(t)
	42	+ if err := memory.WriteFileAtomic("/remote/project/run.sh", []byte("echo\n"), 0o755); err != nil {
	43	+ t.Fatal(err)
	44	+ }
	45	+
	46	+ b, _ := Open("/remote/project/run.sh")
	47	+ b.SetText("echo hi\n")
	48	+ if err := b.Save(); err != nil {
	49	+ t.Fatal(err)
	50	+ }
	51	+ if mode := memory.Mode("/remote/project/run.sh"); mode != 0o755 {
	52	+ t.Errorf("mode after save = %v, want 0755", mode)
	53	+ }
	54	+}
	55	+
	56	+func TestANewFileIsSavedWithTheDefaultMode(t *testing.T) {
	57	+ memory := useMemory(t)
	58	+ b, err := Open("/remote/project/new.py")
	59	+ if err != nil {
	60	+ t.Fatal(err)
	61	+ }
	62	+ b.SetText("pass\n")
	63	+ if err := b.Save(); err != nil {
	64	+ t.Fatal(err)
	65	+ }
	66	+ if mode := memory.Mode("/remote/project/new.py"); mode != defaultFileMode {
	67	+ t.Errorf("mode = %v, want %v", mode, defaultFileMode)
	68	+ }
	69	+}
	70	+
	71	+func TestReloadReadsTheCurrentFileSystem(t *testing.T) {
	72	+ memory := useMemory(t)
	73	+ memory.AddFile("/remote/project/a.py", "1\n")
	74	+ b, _ := Open("/remote/project/a.py")
	75	+
	76	+ memory.AddFile("/remote/project/a.py", "2\n")
	77	+ changed, err := b.Reload()
	78	+ if err != nil \|\| !changed \|\| b.Text() != "2\n" {
	79	+ t.Errorf("Reload = %v, %v; text %q", changed, err, b.Text())
	80	+ }
	81	+}

++package buffer
++
++import (
++	"testing"
++
++	"rickub.com/turbo-editors/turbo-core/fsys"
++	"rickub.com/turbo-editors/turbo-core/fsys/fsystest"
++)
++
++// useMemory makes the buffer read and write a file system that exists only in
++// memory, so a file found there proves the buffer went through fsys.
++func useMemory(t *testing.T) *fsystest.Memory {
++	t.Helper()
++	memory := fsystest.New("/remote/project")
++	previous := fsys.Use(memory)
++	t.Cleanup(func() { fsys.Use(previous) })
++	return memory
++}
++
++func TestOpenAndSaveGoThroughTheCurrentFileSystem(t *testing.T) {
++	memory := useMemory(t)
++	memory.AddFile("/remote/project/app.py", "x = 1\n")
++
++	b, err := Open("/remote/project/app.py")
++	if err != nil {
++		t.Fatal(err)
++	}
++	if b.Text() != "x = 1\n" {
++		t.Fatalf("Text() = %q", b.Text())
++	}
++	b.SetText("x = 2\n")
++	if err := b.Save(); err != nil {
++		t.Fatal(err)
++	}
++	if got, _ := memory.File("/remote/project/app.py"); got != "x = 2\n" {
++		t.Errorf("saved file = %q", got)
++	}
++}
++
++func TestSavingKeepsTheModeOfTheFileItReplaces(t *testing.T) {
++	memory := useMemory(t)
++	if err := memory.WriteFileAtomic("/remote/project/run.sh", []byte("echo\n"), 0o755); err != nil {
++		t.Fatal(err)
++	}
++
++	b, _ := Open("/remote/project/run.sh")
++	b.SetText("echo hi\n")
++	if err := b.Save(); err != nil {
++		t.Fatal(err)
++	}
++	if mode := memory.Mode("/remote/project/run.sh"); mode != 0o755 {
++		t.Errorf("mode after save = %v, want 0755", mode)
++	}
++}
++
++func TestANewFileIsSavedWithTheDefaultMode(t *testing.T) {
++	memory := useMemory(t)
++	b, err := Open("/remote/project/new.py")
++	if err != nil {
++		t.Fatal(err)
++	}
++	b.SetText("pass\n")
++	if err := b.Save(); err != nil {
++		t.Fatal(err)
++	}
++	if mode := memory.Mode("/remote/project/new.py"); mode != defaultFileMode {
++		t.Errorf("mode = %v, want %v", mode, defaultFileMode)
++	}
++}
++
++func TestReloadReadsTheCurrentFileSystem(t *testing.T) {
++	memory := useMemory(t)
++	memory.AddFile("/remote/project/a.py", "1\n")
++	b, _ := Open("/remote/project/a.py")
++
++	memory.AddFile("/remote/project/a.py", "2\n")
++	changed, err := b.Reload()
++	if err != nil || !changed || b.Text() != "2\n" {
++		t.Errorf("Reload = %v, %v; text %q", changed, err, b.Text())
++	}
++}

modified docs/diagrams/packages.drawio +87 -56 Viewed

@@ -4,62 +4,93 @@
4	4	<root>
5	5	<mxCell id="0"/>
6	6	<mxCell id="1" parent="0"/>
7		- <mxCell id="2" value="<b>app</b><br/><font style='font-size:10px'>assembly: menus, dialogs, routing</font>" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-105" y="0" width="210" height="56" as="geometry"/></mxCell>
8		- <mxCell id="3" value="<b>acp</b><br/><font style='font-size:10px'>a coding agent in a window</font>" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-459" y="134" width="210" height="56" as="geometry"/></mxCell>
9		- <mxCell id="4" value="<b>editor</b><br/><font style='font-size:10px'>the editing widget</font>" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-223" y="134" width="210" height="56" as="geometry"/></mxCell>
10		- <mxCell id="5" value="<b>filetree</b><br/><font style='font-size:10px'>the project as a tree</font>" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="13" y="134" width="210" height="56" as="geometry"/></mxCell>
11		- <mxCell id="6" value="<b>terminal</b><br/><font style='font-size:10px'>a shell in a window</font>" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="249" y="134" width="210" height="56" as="geometry"/></mxCell>
12		- <mxCell id="7" value="<b>lsp</b><br/><font style='font-size:10px'>LSP framing and the server process</font>" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-695" y="268" width="210" height="56" as="geometry"/></mxCell>
13		- <mxCell id="8" value="<b>settings</b><br/><font style='font-size:10px'>the project&#x27;s settings.toml</font>" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-459" y="268" width="210" height="56" as="geometry"/></mxCell>
14		- <mxCell id="9" value="<b>snippets</b><br/><font style='font-size:10px'>the project&#x27;s and user&#x27;s snippets</font>" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-223" y="268" width="210" height="56" as="geometry"/></mxCell>
15		- <mxCell id="10" value="<b>syntax</b><br/><font style='font-size:10px'>colouring, and the language registry</font>" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="13" y="268" width="210" height="56" as="geometry"/></mxCell>
16		- <mxCell id="11" value="<b>tools</b><br/><font style='font-size:10px'>the commands a project runs on itself</font>" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="249" y="268" width="210" height="56" as="geometry"/></mxCell>
17		- <mxCell id="12" value="<b>ui</b><br/><font style='font-size:10px'>Turbo Vision widgets</font>" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="485" y="268" width="210" height="56" as="geometry"/></mxCell>
18		- <mxCell id="13" value="<b>buffer</b><br/><font style='font-size:10px'>the text of one file</font>" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-813" y="402" width="210" height="56" as="geometry"/></mxCell>
19		- <mxCell id="14" value="<b>jsonrpc</b><br/><font style='font-size:10px'>JSON-RPC 2.0 over a framed stream</font>" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-577" y="402" width="210" height="56" as="geometry"/></mxCell>
20		- <mxCell id="15" value="<b>main</b><br/><font style='font-size:10px'></font>" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-341" y="402" width="210" height="56" as="geometry"/></mxCell>
21		- <mxCell id="16" value="<b>profile</b><br/><font style='font-size:10px'>what makes one editor differ from another</font>" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-105" y="402" width="210" height="56" as="geometry"/></mxCell>
22		- <mxCell id="17" value="<b>projectfile</b><br/><font style='font-size:10px'>atomic writes of a project&#x27;s files</font>" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="131" y="402" width="210" height="56" as="geometry"/></mxCell>
23		- <mxCell id="18" value="<b>theme</b><br/><font style='font-size:10px'>TOML into tcell styles</font>" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="367" y="402" width="210" height="56" as="geometry"/></mxCell>
24		- <mxCell id="19" value="<b>version</b><br/><font style='font-size:10px'>what build this binary is</font>" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="603" y="402" width="210" height="56" as="geometry"/></mxCell>
25		- <mxCell id="20" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="3" target="14"><mxGeometry relative="1" as="geometry"/></mxCell>
26		- <mxCell id="21" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="3" target="16"><mxGeometry relative="1" as="geometry"/></mxCell>
27		- <mxCell id="22" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="3" target="17"><mxGeometry relative="1" as="geometry"/></mxCell>
28		- <mxCell id="23" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="3" target="10"><mxGeometry relative="1" as="geometry"/></mxCell>
29		- <mxCell id="24" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="3" target="18"><mxGeometry relative="1" as="geometry"/></mxCell>
30		- <mxCell id="25" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="3" target="12"><mxGeometry relative="1" as="geometry"/></mxCell>
31		- <mxCell id="26" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="3"><mxGeometry relative="1" as="geometry"/></mxCell>
32		- <mxCell id="27" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="13"><mxGeometry relative="1" as="geometry"/></mxCell>
33		- <mxCell id="28" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="4"><mxGeometry relative="1" as="geometry"/></mxCell>
34		- <mxCell id="29" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="5"><mxGeometry relative="1" as="geometry"/></mxCell>
35		- <mxCell id="30" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="7"><mxGeometry relative="1" as="geometry"/></mxCell>
36		- <mxCell id="31" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="16"><mxGeometry relative="1" as="geometry"/></mxCell>
37		- <mxCell id="32" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="8"><mxGeometry relative="1" as="geometry"/></mxCell>
38		- <mxCell id="33" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="9"><mxGeometry relative="1" as="geometry"/></mxCell>
39		- <mxCell id="34" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="10"><mxGeometry relative="1" as="geometry"/></mxCell>
40		- <mxCell id="35" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="6"><mxGeometry relative="1" as="geometry"/></mxCell>
41		- <mxCell id="36" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="18"><mxGeometry relative="1" as="geometry"/></mxCell>
42		- <mxCell id="37" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="11"><mxGeometry relative="1" as="geometry"/></mxCell>
43		- <mxCell id="38" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="12"><mxGeometry relative="1" as="geometry"/></mxCell>
44		- <mxCell id="39" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="19"><mxGeometry relative="1" as="geometry"/></mxCell>
45		- <mxCell id="40" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="4" target="13"><mxGeometry relative="1" as="geometry"/></mxCell>
46		- <mxCell id="41" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="4" target="10"><mxGeometry relative="1" as="geometry"/></mxCell>
47		- <mxCell id="42" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="4" target="18"><mxGeometry relative="1" as="geometry"/></mxCell>
48		- <mxCell id="43" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="4" target="12"><mxGeometry relative="1" as="geometry"/></mxCell>
49		- <mxCell id="44" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="5" target="18"><mxGeometry relative="1" as="geometry"/></mxCell>
50		- <mxCell id="45" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="5" target="12"><mxGeometry relative="1" as="geometry"/></mxCell>
51		- <mxCell id="46" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="7" target="14"><mxGeometry relative="1" as="geometry"/></mxCell>
52		- <mxCell id="47" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="7" target="16"><mxGeometry relative="1" as="geometry"/></mxCell>
53		- <mxCell id="48" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="8" target="16"><mxGeometry relative="1" as="geometry"/></mxCell>
54		- <mxCell id="49" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="8" target="17"><mxGeometry relative="1" as="geometry"/></mxCell>
55		- <mxCell id="50" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="9" target="16"><mxGeometry relative="1" as="geometry"/></mxCell>
56		- <mxCell id="51" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="9" target="17"><mxGeometry relative="1" as="geometry"/></mxCell>
57		- <mxCell id="52" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="10" target="18"><mxGeometry relative="1" as="geometry"/></mxCell>
58		- <mxCell id="53" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="6" target="18"><mxGeometry relative="1" as="geometry"/></mxCell>
59		- <mxCell id="54" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="6" target="12"><mxGeometry relative="1" as="geometry"/></mxCell>
60		- <mxCell id="55" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="11" target="16"><mxGeometry relative="1" as="geometry"/></mxCell>
61		- <mxCell id="56" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="11" target="17"><mxGeometry relative="1" as="geometry"/></mxCell>
62		- <mxCell id="57" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="12" target="18"><mxGeometry relative="1" as="geometry"/></mxCell>
	7	+ <mxCell id="2" value="<b>app</b><br/><font style='font-size:10px'>assembly: menus, dialogs, routing</font>" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-577" y="0" width="210" height="56" as="geometry"/></mxCell>
	8	+ <mxCell id="3" value="<b>configrepo</b><br/><font style='font-size:10px'>a shared .turbo-&lt;slug&gt; by git clone</font>" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-341" y="0" width="210" height="56" as="geometry"/></mxCell>
	9	+ <mxCell id="4" value="<b>fsys/fsystest</b><br/><font style='font-size:10px'>an in-memory fsys.FS for tests</font>" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-105" y="0" width="210" height="56" as="geometry"/></mxCell>
	10	+ <mxCell id="5" value="<b>main</b><br/><font style='font-size:10px'>release scripts&#x27; tests</font>" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="131" y="0" width="210" height="56" as="geometry"/></mxCell>
	11	+ <mxCell id="6" value="<b>remote</b><br/><font style='font-size:10px'>another machine over the ssh command</font>" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="367" y="0" width="210" height="56" as="geometry"/></mxCell>
	12	+ <mxCell id="7" value="<b>acp</b><br/><font style='font-size:10px'>a coding agent in a window</font>" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-1049" y="134" width="210" height="56" as="geometry"/></mxCell>
	13	+ <mxCell id="8" value="<b>editor</b><br/><font style='font-size:10px'>the editing widget</font>" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-813" y="134" width="210" height="56" as="geometry"/></mxCell>
	14	+ <mxCell id="9" value="<b>filetree</b><br/><font style='font-size:10px'>the project as a tree</font>" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-577" y="134" width="210" height="56" as="geometry"/></mxCell>
	15	+ <mxCell id="10" value="<b>lsp</b><br/><font style='font-size:10px'>LSP framing and the server process</font>" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-341" y="134" width="210" height="56" as="geometry"/></mxCell>
	16	+ <mxCell id="11" value="<b>settings</b><br/><font style='font-size:10px'>the project&#x27;s settings.toml</font>" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-105" y="134" width="210" height="56" as="geometry"/></mxCell>
	17	+ <mxCell id="12" value="<b>snippets</b><br/><font style='font-size:10px'>the project&#x27;s and user&#x27;s snippets</font>" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="131" y="134" width="210" height="56" as="geometry"/></mxCell>
	18	+ <mxCell id="13" value="<b>terminal</b><br/><font style='font-size:10px'>a shell in a window</font>" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="367" y="134" width="210" height="56" as="geometry"/></mxCell>
	19	+ <mxCell id="14" value="<b>tools</b><br/><font style='font-size:10px'>the commands a project runs on itself</font>" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="603" y="134" width="210" height="56" as="geometry"/></mxCell>
	20	+ <mxCell id="15" value="<b>version</b><br/><font style='font-size:10px'>what build this binary is</font>" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="839" y="134" width="210" height="56" as="geometry"/></mxCell>
	21	+ <mxCell id="16" value="<b>buffer</b><br/><font style='font-size:10px'>the text of one file</font>" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-695" y="268" width="210" height="56" as="geometry"/></mxCell>
	22	+ <mxCell id="17" value="<b>jsonrpc</b><br/><font style='font-size:10px'>JSON-RPC 2.0 over a framed stream</font>" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-459" y="268" width="210" height="56" as="geometry"/></mxCell>
	23	+ <mxCell id="18" value="<b>profile</b><br/><font style='font-size:10px'>what makes one editor differ from another</font>" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-223" y="268" width="210" height="56" as="geometry"/></mxCell>
	24	+ <mxCell id="19" value="<b>projectfile</b><br/><font style='font-size:10px'>atomic writes of a project&#x27;s files</font>" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="13" y="268" width="210" height="56" as="geometry"/></mxCell>
	25	+ <mxCell id="20" value="<b>syntax</b><br/><font style='font-size:10px'>colouring, and the language registry</font>" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="249" y="268" width="210" height="56" as="geometry"/></mxCell>
	26	+ <mxCell id="21" value="<b>ui</b><br/><font style='font-size:10px'>Turbo Vision widgets</font>" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="485" y="268" width="210" height="56" as="geometry"/></mxCell>
	27	+ <mxCell id="22" value="<b>fsys</b><br/><font style='font-size:10px'>the one door to the project&#x27;s files</font>" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-223" y="402" width="210" height="56" as="geometry"/></mxCell>
	28	+ <mxCell id="23" value="<b>theme</b><br/><font style='font-size:10px'>TOML into tcell styles</font>" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="13" y="402" width="210" height="56" as="geometry"/></mxCell>
	29	+ <mxCell id="24" value="<b>golang.org/x/sys</b><br/><font style='font-size:10px'>pty, pseudo-console</font>" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#f5f5f5;strokeColor=#999999;dashed=1;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-459" y="536" width="210" height="56" as="geometry"/></mxCell>
	30	+ <mxCell id="25" value="<b>pkg/sftp</b><br/><font style='font-size:10px'>SFTP client over ssh&#x27;s channel</font>" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#f5f5f5;strokeColor=#999999;dashed=1;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-223" y="536" width="210" height="56" as="geometry"/></mxCell>
	31	+ <mxCell id="26" value="<b>tcell/v2</b><br/><font style='font-size:10px'>the terminal</font>" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#f5f5f5;strokeColor=#999999;dashed=1;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="13" y="536" width="210" height="56" as="geometry"/></mxCell>
	32	+ <mxCell id="27" value="<b>toml</b><br/><font style='font-size:10px'>configuration files</font>" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#f5f5f5;strokeColor=#999999;dashed=1;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="249" y="536" width="210" height="56" as="geometry"/></mxCell>
	33	+ <mxCell id="28" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="7" target="17"><mxGeometry relative="1" as="geometry"/></mxCell>
	34	+ <mxCell id="29" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="7" target="18"><mxGeometry relative="1" as="geometry"/></mxCell>
	35	+ <mxCell id="30" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="7" target="19"><mxGeometry relative="1" as="geometry"/></mxCell>
	36	+ <mxCell id="31" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="7" target="20"><mxGeometry relative="1" as="geometry"/></mxCell>
	37	+ <mxCell id="32" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="7" target="26"><mxGeometry relative="1" as="geometry"/></mxCell>
	38	+ <mxCell id="33" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="7" target="23"><mxGeometry relative="1" as="geometry"/></mxCell>
	39	+ <mxCell id="34" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="7" target="27"><mxGeometry relative="1" as="geometry"/></mxCell>
	40	+ <mxCell id="35" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="7" target="21"><mxGeometry relative="1" as="geometry"/></mxCell>
	41	+ <mxCell id="36" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="7"><mxGeometry relative="1" as="geometry"/></mxCell>
	42	+ <mxCell id="37" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="16"><mxGeometry relative="1" as="geometry"/></mxCell>
	43	+ <mxCell id="38" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="8"><mxGeometry relative="1" as="geometry"/></mxCell>
	44	+ <mxCell id="39" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="9"><mxGeometry relative="1" as="geometry"/></mxCell>
	45	+ <mxCell id="40" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="22"><mxGeometry relative="1" as="geometry"/></mxCell>
	46	+ <mxCell id="41" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="10"><mxGeometry relative="1" as="geometry"/></mxCell>
	47	+ <mxCell id="42" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="18"><mxGeometry relative="1" as="geometry"/></mxCell>
	48	+ <mxCell id="43" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="11"><mxGeometry relative="1" as="geometry"/></mxCell>
	49	+ <mxCell id="44" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="12"><mxGeometry relative="1" as="geometry"/></mxCell>
	50	+ <mxCell id="45" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="20"><mxGeometry relative="1" as="geometry"/></mxCell>
	51	+ <mxCell id="46" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="26"><mxGeometry relative="1" as="geometry"/></mxCell>
	52	+ <mxCell id="47" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="13"><mxGeometry relative="1" as="geometry"/></mxCell>
	53	+ <mxCell id="48" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="23"><mxGeometry relative="1" as="geometry"/></mxCell>
	54	+ <mxCell id="49" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="14"><mxGeometry relative="1" as="geometry"/></mxCell>
	55	+ <mxCell id="50" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="21"><mxGeometry relative="1" as="geometry"/></mxCell>
	56	+ <mxCell id="51" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="15"><mxGeometry relative="1" as="geometry"/></mxCell>
	57	+ <mxCell id="52" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="16" target="22"><mxGeometry relative="1" as="geometry"/></mxCell>
	58	+ <mxCell id="53" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="3" target="18"><mxGeometry relative="1" as="geometry"/></mxCell>
	59	+ <mxCell id="54" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="3" target="19"><mxGeometry relative="1" as="geometry"/></mxCell>
	60	+ <mxCell id="55" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="8" target="16"><mxGeometry relative="1" as="geometry"/></mxCell>
	61	+ <mxCell id="56" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="8" target="20"><mxGeometry relative="1" as="geometry"/></mxCell>
	62	+ <mxCell id="57" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="8" target="26"><mxGeometry relative="1" as="geometry"/></mxCell>
	63	+ <mxCell id="58" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="8" target="23"><mxGeometry relative="1" as="geometry"/></mxCell>
	64	+ <mxCell id="59" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="8" target="21"><mxGeometry relative="1" as="geometry"/></mxCell>
	65	+ <mxCell id="60" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="9" target="22"><mxGeometry relative="1" as="geometry"/></mxCell>
	66	+ <mxCell id="61" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="9" target="26"><mxGeometry relative="1" as="geometry"/></mxCell>
	67	+ <mxCell id="62" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="9" target="23"><mxGeometry relative="1" as="geometry"/></mxCell>
	68	+ <mxCell id="63" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="9" target="21"><mxGeometry relative="1" as="geometry"/></mxCell>
	69	+ <mxCell id="64" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="10" target="17"><mxGeometry relative="1" as="geometry"/></mxCell>
	70	+ <mxCell id="65" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="10" target="18"><mxGeometry relative="1" as="geometry"/></mxCell>
	71	+ <mxCell id="66" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="19" target="22"><mxGeometry relative="1" as="geometry"/></mxCell>
	72	+ <mxCell id="67" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="6" target="25"><mxGeometry relative="1" as="geometry"/></mxCell>
	73	+ <mxCell id="68" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="11" target="22"><mxGeometry relative="1" as="geometry"/></mxCell>
	74	+ <mxCell id="69" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="11" target="18"><mxGeometry relative="1" as="geometry"/></mxCell>
	75	+ <mxCell id="70" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="11" target="19"><mxGeometry relative="1" as="geometry"/></mxCell>
	76	+ <mxCell id="71" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="11" target="27"><mxGeometry relative="1" as="geometry"/></mxCell>
	77	+ <mxCell id="72" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="12" target="22"><mxGeometry relative="1" as="geometry"/></mxCell>
	78	+ <mxCell id="73" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="12" target="18"><mxGeometry relative="1" as="geometry"/></mxCell>
	79	+ <mxCell id="74" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="12" target="19"><mxGeometry relative="1" as="geometry"/></mxCell>
	80	+ <mxCell id="75" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="12" target="27"><mxGeometry relative="1" as="geometry"/></mxCell>
	81	+ <mxCell id="76" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="20" target="23"><mxGeometry relative="1" as="geometry"/></mxCell>
	82	+ <mxCell id="77" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="13" target="24"><mxGeometry relative="1" as="geometry"/></mxCell>
	83	+ <mxCell id="78" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="13" target="26"><mxGeometry relative="1" as="geometry"/></mxCell>
	84	+ <mxCell id="79" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="13" target="23"><mxGeometry relative="1" as="geometry"/></mxCell>
	85	+ <mxCell id="80" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="13" target="21"><mxGeometry relative="1" as="geometry"/></mxCell>
	86	+ <mxCell id="81" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="23" target="26"><mxGeometry relative="1" as="geometry"/></mxCell>
	87	+ <mxCell id="82" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="23" target="27"><mxGeometry relative="1" as="geometry"/></mxCell>
	88	+ <mxCell id="83" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="14" target="22"><mxGeometry relative="1" as="geometry"/></mxCell>
	89	+ <mxCell id="84" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="14" target="18"><mxGeometry relative="1" as="geometry"/></mxCell>
	90	+ <mxCell id="85" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="14" target="19"><mxGeometry relative="1" as="geometry"/></mxCell>
	91	+ <mxCell id="86" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="14" target="27"><mxGeometry relative="1" as="geometry"/></mxCell>
	92	+ <mxCell id="87" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="21" target="26"><mxGeometry relative="1" as="geometry"/></mxCell>
	93	+ <mxCell id="88" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="21" target="23"><mxGeometry relative="1" as="geometry"/></mxCell>
63	94	</root>
64	95	</mxGraphModel>
65	96	</diagram>

        <root>
          <mxCell id="0"/>
          <mxCell id="1" parent="0"/>
--        <mxCell id="2" value="&lt;b&gt;app&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;assembly: menus, dialogs, routing&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-105" y="0" width="210" height="56" as="geometry"/></mxCell>
++        <mxCell id="2" value="&lt;b&gt;app&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;assembly: menus, dialogs, routing&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-577" y="0" width="210" height="56" as="geometry"/></mxCell>
--        <mxCell id="3" value="&lt;b&gt;acp&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;a coding agent in a window&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-459" y="134" width="210" height="56" as="geometry"/></mxCell>
++        <mxCell id="3" value="&lt;b&gt;configrepo&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;a shared .turbo-&amp;lt;slug&amp;gt; by git clone&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-341" y="0" width="210" height="56" as="geometry"/></mxCell>
--        <mxCell id="4" value="&lt;b&gt;editor&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;the editing widget&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-223" y="134" width="210" height="56" as="geometry"/></mxCell>
++        <mxCell id="4" value="&lt;b&gt;fsys/fsystest&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;an in-memory fsys.FS for tests&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-105" y="0" width="210" height="56" as="geometry"/></mxCell>
--        <mxCell id="5" value="&lt;b&gt;filetree&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;the project as a tree&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="13" y="134" width="210" height="56" as="geometry"/></mxCell>
++        <mxCell id="5" value="&lt;b&gt;main&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;release scripts&amp;#x27; tests&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="131" y="0" width="210" height="56" as="geometry"/></mxCell>
--        <mxCell id="6" value="&lt;b&gt;terminal&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;a shell in a window&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="249" y="134" width="210" height="56" as="geometry"/></mxCell>
++        <mxCell id="6" value="&lt;b&gt;remote&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;another machine over the ssh command&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="367" y="0" width="210" height="56" as="geometry"/></mxCell>
--        <mxCell id="7" value="&lt;b&gt;lsp&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;LSP framing and the server process&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-695" y="268" width="210" height="56" as="geometry"/></mxCell>
++        <mxCell id="7" value="&lt;b&gt;acp&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;a coding agent in a window&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-1049" y="134" width="210" height="56" as="geometry"/></mxCell>
--        <mxCell id="8" value="&lt;b&gt;settings&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;the project&amp;#x27;s settings.toml&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-459" y="268" width="210" height="56" as="geometry"/></mxCell>
++        <mxCell id="8" value="&lt;b&gt;editor&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;the editing widget&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-813" y="134" width="210" height="56" as="geometry"/></mxCell>
--        <mxCell id="9" value="&lt;b&gt;snippets&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;the project&amp;#x27;s and user&amp;#x27;s snippets&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-223" y="268" width="210" height="56" as="geometry"/></mxCell>
++        <mxCell id="9" value="&lt;b&gt;filetree&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;the project as a tree&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-577" y="134" width="210" height="56" as="geometry"/></mxCell>
--        <mxCell id="10" value="&lt;b&gt;syntax&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;colouring, and the language registry&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="13" y="268" width="210" height="56" as="geometry"/></mxCell>
++        <mxCell id="10" value="&lt;b&gt;lsp&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;LSP framing and the server process&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-341" y="134" width="210" height="56" as="geometry"/></mxCell>
--        <mxCell id="11" value="&lt;b&gt;tools&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;the commands a project runs on itself&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="249" y="268" width="210" height="56" as="geometry"/></mxCell>
++        <mxCell id="11" value="&lt;b&gt;settings&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;the project&amp;#x27;s settings.toml&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-105" y="134" width="210" height="56" as="geometry"/></mxCell>
--        <mxCell id="12" value="&lt;b&gt;ui&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;Turbo Vision widgets&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="485" y="268" width="210" height="56" as="geometry"/></mxCell>
++        <mxCell id="12" value="&lt;b&gt;snippets&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;the project&amp;#x27;s and user&amp;#x27;s snippets&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="131" y="134" width="210" height="56" as="geometry"/></mxCell>
--        <mxCell id="13" value="&lt;b&gt;buffer&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;the text of one file&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-813" y="402" width="210" height="56" as="geometry"/></mxCell>
++        <mxCell id="13" value="&lt;b&gt;terminal&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;a shell in a window&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="367" y="134" width="210" height="56" as="geometry"/></mxCell>
--        <mxCell id="14" value="&lt;b&gt;jsonrpc&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;JSON-RPC 2.0 over a framed stream&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-577" y="402" width="210" height="56" as="geometry"/></mxCell>
++        <mxCell id="14" value="&lt;b&gt;tools&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;the commands a project runs on itself&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="603" y="134" width="210" height="56" as="geometry"/></mxCell>
--        <mxCell id="15" value="&lt;b&gt;main&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-341" y="402" width="210" height="56" as="geometry"/></mxCell>
++        <mxCell id="15" value="&lt;b&gt;version&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;what build this binary is&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="839" y="134" width="210" height="56" as="geometry"/></mxCell>
--        <mxCell id="16" value="&lt;b&gt;profile&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;what makes one editor differ from another&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-105" y="402" width="210" height="56" as="geometry"/></mxCell>
++        <mxCell id="16" value="&lt;b&gt;buffer&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;the text of one file&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-695" y="268" width="210" height="56" as="geometry"/></mxCell>
--        <mxCell id="17" value="&lt;b&gt;projectfile&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;atomic writes of a project&amp;#x27;s files&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="131" y="402" width="210" height="56" as="geometry"/></mxCell>
++        <mxCell id="17" value="&lt;b&gt;jsonrpc&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;JSON-RPC 2.0 over a framed stream&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-459" y="268" width="210" height="56" as="geometry"/></mxCell>
--        <mxCell id="18" value="&lt;b&gt;theme&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;TOML into tcell styles&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="367" y="402" width="210" height="56" as="geometry"/></mxCell>
++        <mxCell id="18" value="&lt;b&gt;profile&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;what makes one editor differ from another&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-223" y="268" width="210" height="56" as="geometry"/></mxCell>
--        <mxCell id="19" value="&lt;b&gt;version&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;what build this binary is&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="603" y="402" width="210" height="56" as="geometry"/></mxCell>
++        <mxCell id="19" value="&lt;b&gt;projectfile&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;atomic writes of a project&amp;#x27;s files&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="13" y="268" width="210" height="56" as="geometry"/></mxCell>
--        <mxCell id="20" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="3" target="14"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="20" value="&lt;b&gt;syntax&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;colouring, and the language registry&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="249" y="268" width="210" height="56" as="geometry"/></mxCell>
--        <mxCell id="21" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="3" target="16"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="21" value="&lt;b&gt;ui&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;Turbo Vision widgets&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="485" y="268" width="210" height="56" as="geometry"/></mxCell>
--        <mxCell id="22" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="3" target="17"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="22" value="&lt;b&gt;fsys&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;the one door to the project&amp;#x27;s files&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-223" y="402" width="210" height="56" as="geometry"/></mxCell>
--        <mxCell id="23" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="3" target="10"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="23" value="&lt;b&gt;theme&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;TOML into tcell styles&lt;/font&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="13" y="402" width="210" height="56" as="geometry"/></mxCell>
--        <mxCell id="24" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="3" target="18"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="24" value="&lt;b&gt;golang.org/x/sys&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;pty, pseudo-console&lt;/font&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#f5f5f5;strokeColor=#999999;dashed=1;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-459" y="536" width="210" height="56" as="geometry"/></mxCell>
--        <mxCell id="25" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="3" target="12"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="25" value="&lt;b&gt;pkg/sftp&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;SFTP client over ssh&amp;#x27;s channel&lt;/font&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#f5f5f5;strokeColor=#999999;dashed=1;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="-223" y="536" width="210" height="56" as="geometry"/></mxCell>
--        <mxCell id="26" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="3"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="26" value="&lt;b&gt;tcell/v2&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;the terminal&lt;/font&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#f5f5f5;strokeColor=#999999;dashed=1;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="13" y="536" width="210" height="56" as="geometry"/></mxCell>
--        <mxCell id="27" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="13"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="27" value="&lt;b&gt;toml&lt;/b&gt;&lt;br/&gt;&lt;font style=&#x27;font-size:10px&#x27;&gt;configuration files&lt;/font&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#f5f5f5;strokeColor=#999999;dashed=1;fontSize=12;verticalAlign=middle;" vertex="1" parent="1"><mxGeometry x="249" y="536" width="210" height="56" as="geometry"/></mxCell>
--        <mxCell id="28" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="4"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="28" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="7" target="17"><mxGeometry relative="1" as="geometry"/></mxCell>
--        <mxCell id="29" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="5"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="29" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="7" target="18"><mxGeometry relative="1" as="geometry"/></mxCell>
--        <mxCell id="30" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="7"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="30" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="7" target="19"><mxGeometry relative="1" as="geometry"/></mxCell>
--        <mxCell id="31" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="16"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="31" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="7" target="20"><mxGeometry relative="1" as="geometry"/></mxCell>
--        <mxCell id="32" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="8"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="32" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="7" target="26"><mxGeometry relative="1" as="geometry"/></mxCell>
--        <mxCell id="33" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="9"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="33" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="7" target="23"><mxGeometry relative="1" as="geometry"/></mxCell>
--        <mxCell id="34" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="10"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="34" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="7" target="27"><mxGeometry relative="1" as="geometry"/></mxCell>
--        <mxCell id="35" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="6"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="35" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="7" target="21"><mxGeometry relative="1" as="geometry"/></mxCell>
--        <mxCell id="36" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="18"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="36" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="7"><mxGeometry relative="1" as="geometry"/></mxCell>
--        <mxCell id="37" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="11"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="37" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="16"><mxGeometry relative="1" as="geometry"/></mxCell>
--        <mxCell id="38" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="12"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="38" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="8"><mxGeometry relative="1" as="geometry"/></mxCell>
--        <mxCell id="39" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="19"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="39" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="9"><mxGeometry relative="1" as="geometry"/></mxCell>
--        <mxCell id="40" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="4" target="13"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="40" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="22"><mxGeometry relative="1" as="geometry"/></mxCell>
--        <mxCell id="41" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="4" target="10"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="41" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="10"><mxGeometry relative="1" as="geometry"/></mxCell>
--        <mxCell id="42" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="4" target="18"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="42" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="18"><mxGeometry relative="1" as="geometry"/></mxCell>
--        <mxCell id="43" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="4" target="12"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="43" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="11"><mxGeometry relative="1" as="geometry"/></mxCell>
--        <mxCell id="44" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="5" target="18"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="44" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="12"><mxGeometry relative="1" as="geometry"/></mxCell>
--        <mxCell id="45" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="5" target="12"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="45" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="20"><mxGeometry relative="1" as="geometry"/></mxCell>
--        <mxCell id="46" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="7" target="14"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="46" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="26"><mxGeometry relative="1" as="geometry"/></mxCell>
--        <mxCell id="47" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="7" target="16"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="47" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="13"><mxGeometry relative="1" as="geometry"/></mxCell>
--        <mxCell id="48" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="8" target="16"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="48" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="23"><mxGeometry relative="1" as="geometry"/></mxCell>
--        <mxCell id="49" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="8" target="17"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="49" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="14"><mxGeometry relative="1" as="geometry"/></mxCell>
--        <mxCell id="50" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="9" target="16"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="50" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="21"><mxGeometry relative="1" as="geometry"/></mxCell>
--        <mxCell id="51" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="9" target="17"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="51" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="2" target="15"><mxGeometry relative="1" as="geometry"/></mxCell>
--        <mxCell id="52" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="10" target="18"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="52" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="16" target="22"><mxGeometry relative="1" as="geometry"/></mxCell>
--        <mxCell id="53" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="6" target="18"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="53" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="3" target="18"><mxGeometry relative="1" as="geometry"/></mxCell>
--        <mxCell id="54" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="6" target="12"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="54" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="3" target="19"><mxGeometry relative="1" as="geometry"/></mxCell>
--        <mxCell id="55" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="11" target="16"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="55" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="8" target="16"><mxGeometry relative="1" as="geometry"/></mxCell>
--        <mxCell id="56" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="11" target="17"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="56" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="8" target="20"><mxGeometry relative="1" as="geometry"/></mxCell>
--        <mxCell id="57" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="12" target="18"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="57" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="8" target="26"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="58" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="8" target="23"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="59" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="8" target="21"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="60" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="9" target="22"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="61" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="9" target="26"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="62" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="9" target="23"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="63" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="9" target="21"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="64" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="10" target="17"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="65" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="10" target="18"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="66" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="19" target="22"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="67" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="6" target="25"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="68" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="11" target="22"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="69" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="11" target="18"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="70" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="11" target="19"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="71" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="11" target="27"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="72" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="12" target="22"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="73" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="12" target="18"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="74" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="12" target="19"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="75" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="12" target="27"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="76" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="20" target="23"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="77" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="13" target="24"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="78" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="13" target="26"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="79" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="13" target="23"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="80" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="13" target="21"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="81" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="23" target="26"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="82" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="23" target="27"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="83" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="14" target="22"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="84" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="14" target="18"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="85" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="14" target="19"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="86" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="14" target="27"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="87" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="21" target="26"><mxGeometry relative="1" as="geometry"/></mxCell>
++        <mxCell id="88" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;endFill=1;strokeColor=#6c8ebf;" edge="1" parent="1" source="21" target="23"><mxGeometry relative="1" as="geometry"/></mxCell>
        </root>
      </mxGraphModel>
    </diagram>

modified docs/en/README.md +4 -0 Viewed

@@ -13,6 +13,7 @@ This documentation follows [Diátaxis](https://diataxis.fr): four kinds of page,
13	13	- [Add a language](how-to/add-a-language.md) — write a scanner and register it.
14	14	- [Talk to a language server](how-to/talk-to-a-language-server.md) — point the editor at gopls, rust-analyzer, or anything else that speaks LSP.
15	15	- [Write the starter files](how-to/write-the-starter-files.md) — the settings, snippets and tools templates your editor offers to create.
	16	+- [Add remote editing](how-to/add-remote-editing.md) — give an editor `-ssh user@machine[:dir]`, to edit another machine's files.
16	17	- [Run the tests](how-to/run-the-tests.md) — the one command, and what it covers.
17	18	- [Test without publishing](how-to/test-without-publishing.md) — run the editors against a turbo-core you have only changed locally.
18	19	- [Release the library](how-to/release-the-library.md) — tagging a version the editors can depend on.
@@ -23,11 +24,14 @@ This documentation follows [Diátaxis](https://diataxis.fr): four kinds of page,
23	24	- [Packages](reference/packages.md) — what each package holds, and what it may depend on.
24	25	- [The syntax extension point](reference/syntax.md) — `Definition`, `Register`, `LineScanner`, `LineIndex`.
25	26	- [The app API](reference/app.md) — what a command may call on a running editor.
	27	+- [fsys](reference/fsys.md) — the one door to the project's files.
	28	+- [remote](reference/remote.md) — another machine over the `ssh` command.
26	29
27	30	## [Explanation](explanation/) — why it is like this
28	31
29	32	- [Architecture](explanation/architecture.md) — the shape of the library and the rule that keeps it that shape.
30	33	- [What belongs here](explanation/what-belongs-here.md) — the line between the library and an editor built on it, and how it was drawn.
	34	+- [Remote editing](explanation/remote-editing.md) — why `-ssh` drives the ssh command, shares one connection, and moves files over SFTP.
31	35
32	36	## Where the editors are
33	37

  - [Add a language](how-to/add-a-language.md) — write a scanner and register it.
  - [Talk to a language server](how-to/talk-to-a-language-server.md) — point the editor at gopls, rust-analyzer, or anything else that speaks LSP.
  - [Write the starter files](how-to/write-the-starter-files.md) — the settings, snippets and tools templates your editor offers to create.
++- [Add remote editing](how-to/add-remote-editing.md) — give an editor `-ssh user@machine[:dir]`, to edit another machine's files.
  - [Run the tests](how-to/run-the-tests.md) — the one command, and what it covers.
  - [Test without publishing](how-to/test-without-publishing.md) — run the editors against a turbo-core you have only changed locally.
  - [Release the library](how-to/release-the-library.md) — tagging a version the editors can depend on.
  - [Packages](reference/packages.md) — what each package holds, and what it may depend on.
  - [The syntax extension point](reference/syntax.md) — `Definition`, `Register`, `LineScanner`, `LineIndex`.
  - [The app API](reference/app.md) — what a command may call on a running editor.
++- [fsys](reference/fsys.md) — the one door to the project's files.
++- [remote](reference/remote.md) — another machine over the `ssh` command.
  ## [Explanation](explanation/) — why it is like this
  - [Architecture](explanation/architecture.md) — the shape of the library and the rule that keeps it that shape.
  - [What belongs here](explanation/what-belongs-here.md) — the line between the library and an editor built on it, and how it was drawn.
++- [Remote editing](explanation/remote-editing.md) — why `-ssh` drives the ssh command, shares one connection, and moves files over SFTP.
  ## Where the editors are

modified docs/en/explanation/architecture.md +6 -1 Viewed

@@ -2,7 +2,7 @@
2	2
3	3	## What is this about?
4	4
5		-turbo-core is a terminal IDE with a hole where the language goes. Eighteen packages implement everything an editor does — text, undo, windows, menus, dialogs, themes, a VT emulator, a file tree, an LSP client, a coding agent — and none of them knows what language is being edited. An editor built on it is a command, a `profile.Profile`, and a scanner.
	5	+turbo-core is a terminal IDE with a hole where the language goes. Twenty-one packages implement everything an editor does — text, undo, windows, menus, dialogs, themes, a VT emulator, a file tree, an LSP client, a coding agent, editing over ssh — and none of them knows what language is being edited. An editor built on it is a command, a `profile.Profile`, and a scanner.
6	6
7	7	The library was not designed that way. It was extracted from Turbo Go, which had been a single 35,000-line program for a fortnight, at the moment a second editor was wanted. Nearly all of it moved unchanged; the seam is where it turned out to have to be, not where anybody predicted.
8	8
@@ -44,6 +44,10 @@ It is not safe from two goroutines at once, and there is no reason for it to be.
44	44
45	45	This looks inconsistent and is deliberate. A package that takes a profile it uses one field of would be a package that depends on the editor's whole identity to answer a question about a directory.
46	46
	47	+## Why the project's files have one door
	48	+
	49	+Every read and write of a project file — the source, the tree, the Open dialog, the project's own TOML files — goes through `fsys`, and nothing else in the library touches those files with package `os`. That is what lets an editor started with `-ssh` swap the local disk for another machine with one call, `fsys.Use`, before anything reads. It is package-level state for the reasons the syntax registry is; the whole argument, and what was deliberately left on the local disk, is in [remote editing](remote-editing.md).
	50	+
47	51	## How it relates to the rest
48	52
49	53	The editors built on it are the proof the seam is real. Turbo Go's own packages went from fourteen to one; Turbo Rust was built on the library without changing it, and the four defects that surfaced while building it were all in Turbo Rust's own scanner rather than in the library — which is the outcome the extraction was for. Turbo Python, the third, was built against a published tag with no change to the library at all.
@@ -52,6 +56,7 @@ The editors built on it are the proof the seam is real. Turbo Go's own packages
52	56
53	57	- What is in each package: [packages reference](../reference/packages.md)
54	58	- Where the line falls: [what belongs here](what-belongs-here.md)
	59	+- Editing another machine's files: [remote editing](remote-editing.md)
55	60
56	61	## Why jsonrpc was pulled out of lsp
57	62

  ## What is this about?
--turbo-core is a terminal IDE with a hole where the language goes. Eighteen packages implement everything an editor does — text, undo, windows, menus, dialogs, themes, a VT emulator, a file tree, an LSP client, a coding agent — and none of them knows what language is being edited. An editor built on it is a command, a `profile.Profile`, and a scanner.
++turbo-core is a terminal IDE with a hole where the language goes. Twenty-one packages implement everything an editor does — text, undo, windows, menus, dialogs, themes, a VT emulator, a file tree, an LSP client, a coding agent, editing over ssh — and none of them knows what language is being edited. An editor built on it is a command, a `profile.Profile`, and a scanner.
  The library was not designed that way. It was extracted from Turbo Go, which had been a single 35,000-line program for a fortnight, at the moment a second editor was wanted. Nearly all of it moved unchanged; the seam is where it turned out to have to be, not where anybody predicted.
  This looks inconsistent and is deliberate. A package that takes a profile it uses one field of would be a package that depends on the editor's whole identity to answer a question about a directory.
++## Why the project's files have one door
++
++Every read and write of a *project* file — the source, the tree, the Open dialog, the project's own TOML files — goes through `fsys`, and nothing else in the library touches those files with package `os`. That is what lets an editor started with `-ssh` swap the local disk for another machine with one call, `fsys.Use`, before anything reads. It is package-level state for the reasons the syntax registry is; the whole argument, and what was deliberately left on the local disk, is in [remote editing](remote-editing.md).
++
  ## How it relates to the rest
  The editors built on it are the proof the seam is real. Turbo Go's own packages went from fourteen to one; Turbo Rust was built on the library without changing it, and the four defects that surfaced while building it were all in Turbo Rust's own scanner rather than in the library — which is the outcome the extraction was for. Turbo Python, the third, was built against a published tag with no change to the library at all.
  - What is in each package: [packages reference](../reference/packages.md)
  - Where the line falls: [what belongs here](what-belongs-here.md)
++- Editing another machine's files: [remote editing](remote-editing.md)
  ## Why jsonrpc was pulled out of lsp

added docs/en/explanation/remote-editing.md +62 -0 Viewed

new file mode 100644
@@ -0,0 +1,62 @@
	1	+# Remote editing — explanation
	2	+
	3	+## What is this about?
	4	+
	5	+`turbo-python -ssh bob@machine:/srv/app` edits the files of another machine as if they were local: the windows, the project tree, the Open dialog and the project's settings, snippets and tools files are the remote ones; a terminal window is a shell over there; a tool runs over there. Every editor gets it from turbo-core the same way — two packages, `fsys` and `remote`, and one call, `app.UseRemote`.
	6	+
	7	+This page is about why it is built the way it is: why the editor drives the `ssh` command rather than speaking SSH itself, why files travel over SFTP, why the file system is package-level state, and what was deliberately left on the local machine.
	8	+
	9	+## One door for the files
	10	+
	11	+Before this feature, about fifty places in turbo-core called `os.ReadFile`, `os.Stat`, `os.Getwd` and their relatives directly. Remote editing needed all of those that concern the project to go somewhere else, and none of those that concern the person to move.
	12	+
	13	+So the project's files now have one door, `fsys`, and it is package-level state set once at start-up. That is the same shape — and the same argument — as `syntax.Register` (see [architecture](architecture.md)): the choice is made once per process, before anything reads; nothing changes it afterwards; and the alternative, threading a file-system value through `buffer`, `filetree`, `settings`, `snippets`, `tools`, `projectfile` and every call site in `app`, would have changed the signature of half the library for a decision nobody takes twice. The cost is the usual one for global state: a test that swaps it must put it back, and none of the packages that use it can run tests that swap it in parallel. None did.
	14	+
	15	+The line between "the project" and "the person" is drawn where it already was. The user's themes and own snippets are habits, and follow the person to whatever machine they edit. A language server's executable and a coding agent are programs on this machine. `-load-config` copies into the local working directory, which is where it is typed.
	16	+
	17	+## Why the ssh command, and not an SSH library
	18	+
	19	+Go has a good SSH client, `golang.org/x/crypto/ssh`. It was rejected, for the reason `configrepo` runs `git` instead of speaking smart HTTP: the installed command already knows everything the person has set up, and a library knows none of it.
	20	+
	21	+The ssh command reads `~/.ssh/config` — `Host` aliases, ports, `User`, `IdentityFile`, `ProxyJump` through a bastion — and uses the agent, `known_hosts`, a key's passphrase, a password, a hardware key. A library would have had to reimplement each of those, one at a time, and the dangerous one first: accepting a host key the person has never seen is a question with a security answer, and OpenSSH already asks it correctly.
	22	+
	23	+The cost is that the editor starts processes rather than calling functions, which is why `ControlMaster` matters.
	24	+
	25	+## Why ControlMaster
	26	+
	27	+Without it, every ssh command is a new connection: a TCP handshake, a key exchange, an authentication — and, with a password, a prompt, every time. The editor opens a shell here, runs a tool there, and stats every open file once a second.
	28	+
	29	+`ControlMaster` makes the first connection the master and leaves a Unix socket behind it; every later `ssh -S <socket>` travels through that one authenticated connection in milliseconds and asks nothing. So the editor logs in once, in the foreground, before it takes the screen — which is the only moment ssh can ask a question on the terminal — and passes `BatchMode=yes` to everything afterwards, so that a lost master fails loudly instead of drawing a password prompt over the editor.
	30	+
	31	+`ControlPersist=60` keeps the master alive for a minute after its last user. The editor holds the SFTP channel open until it closes, so the minute only matters after a crash: the connection then goes away on its own.
	32	+
	33	+The cost is Windows: its OpenSSH port has no ControlMaster, and `Connect` returns `ErrUnsupported` there.
	34	+
	35	+## Why SFTP for the files, and not shell commands
	36	+
	37	+Once a shared connection exists, the cheapest-looking way to read a file is `ssh … cat file`, and to list a directory `ssh … ls`. It was rejected for two reasons.
	38	+
	39	+The output of `ls` and `stat` is not portable — GNU and BSD disagree on flags and on formats — and a file watcher built on parsing it is a watcher that breaks on the first macOS server. And a process per operation means a process per open file per second for the watcher alone.
	40	+
	41	+SFTP is the protocol OpenSSH already ships for exactly this, over one channel of the same connection (`ssh -s … sftp`): binary, portable, and one request per operation. The client is `github.com/pkg/sftp`, the one real dependency the feature added. Writing the dozen SFTP messages the editor needs by hand was considered and rejected as protocol code to maintain for no gain.
	42	+
	43	+An atomic save survives the move: the new content is written to a temporary file beside the target and renamed over it with `posix-rename@openssh.com`, which replaces the target in one step, as `rename(2)` does locally.
	44	+
	45	+## Why every remote command is `/bin/sh -c '…'`
	46	+
	47	+ssh hands the command it is given to the user's login shell, which may be fish, or anything else that does not read `cd dir && exec …` the way sh does. So every command sent is `exec /bin/sh -c '<script>'`, quoted once for the login shell: a tool's command line means over there what it means locally — `/bin/sh -c`, pipes and `&&` included — and a terminal starts the user's own shell with `exec "${SHELL:-/bin/sh}" -l` from inside sh.
	48	+
	49	+## What is switched off, and why
	50	+
	51	+- The language server. The servers an editor knows how to find are on this machine; the files they would be asked about are not. Starting pylsp remotely over the same connection is possible, but the paths in its answers would then have to be translated, and the server would have to be installed there. It is left for later rather than half done.
	52	+- Agent windows. An agent is a program on this machine that reads and writes this machine's files. One running while the editor shows the remote project would be editing a different project from the one on screen. The Agent menu says so rather than offering it.
	53	+
	54	+## Rejected alternatives
	55	+
	56	+- Mounting with sshfs. Needs macFUSE on macOS, a kernel extension the person has to install and approve, and leaves the terminals and tools local.
	57	+- Copying the editor to the machine and running it there. The binary is built for the person's machine — `darwin/arm64` — and the server is usually `linux/amd64`; and the editor would lose the local clipboard and the person's themes.
	58	+- An interface threaded through every package instead of `fsys.Use`. See "One door for the files" above.
	59	+
	60	+## How it relates to the rest
	61	+
	62	+`fsys` sits below everything that touches a project file, with no dependencies of its own. `remote` does not even import it — its `FS` has the right methods, which is all a Go interface asks. It sits beside `configrepo`, since both drive an installed command, and `app` knows it only through the three-method `app.Remote` interface, so its tests use a fake that runs `/bin/sh` locally. Each editor adds the flag in its `main.go`; the reference is [remote](../reference/remote.md), and the recipe [add remote editing](../how-to/add-remote-editing.md).

++# Remote editing — explanation
++
++## What is this about?
++
++`turbo-python -ssh bob@machine:/srv/app` edits the files of another machine as if they were local: the windows, the project tree, the Open dialog and the project's settings, snippets and tools files are the remote ones; a terminal window is a shell over there; a tool runs over there. Every editor gets it from turbo-core the same way — two packages, `fsys` and `remote`, and one call, `app.UseRemote`.
++
++This page is about why it is built the way it is: why the editor drives the `ssh` command rather than speaking SSH itself, why files travel over SFTP, why the file system is package-level state, and what was deliberately left on the local machine.
++
++## One door for the files
++
++Before this feature, about fifty places in turbo-core called `os.ReadFile`, `os.Stat`, `os.Getwd` and their relatives directly. Remote editing needed all of those that concern *the project* to go somewhere else, and none of those that concern *the person* to move.
++
++So the project's files now have one door, `fsys`, and it is package-level state set once at start-up. That is the same shape — and the same argument — as `syntax.Register` (see [architecture](architecture.md)): the choice is made once per process, before anything reads; nothing changes it afterwards; and the alternative, threading a file-system value through `buffer`, `filetree`, `settings`, `snippets`, `tools`, `projectfile` and every call site in `app`, would have changed the signature of half the library for a decision nobody takes twice. The cost is the usual one for global state: a test that swaps it must put it back, and none of the packages that use it can run tests that swap it in parallel. None did.
++
++The line between "the project" and "the person" is drawn where it already was. The user's themes and own snippets are habits, and follow the person to whatever machine they edit. A language server's executable and a coding agent are programs on this machine. `-load-config` copies into the local working directory, which is where it is typed.
++
++## Why the ssh command, and not an SSH library
++
++Go has a good SSH client, `golang.org/x/crypto/ssh`. It was rejected, for the reason `configrepo` runs `git` instead of speaking smart HTTP: the installed command already knows everything the person has set up, and a library knows none of it.
++
++The ssh command reads `~/.ssh/config` — `Host` aliases, ports, `User`, `IdentityFile`, `ProxyJump` through a bastion — and uses the agent, `known_hosts`, a key's passphrase, a password, a hardware key. A library would have had to reimplement each of those, one at a time, and the dangerous one first: accepting a host key the person has never seen is a question with a security answer, and OpenSSH already asks it correctly.
++
++The cost is that the editor starts processes rather than calling functions, which is why `ControlMaster` matters.
++
++## Why ControlMaster
++
++Without it, every ssh command is a new connection: a TCP handshake, a key exchange, an authentication — and, with a password, a prompt, every time. The editor opens a shell here, runs a tool there, and stats every open file once a second.
++
++`ControlMaster` makes the first connection the master and leaves a Unix socket behind it; every later `ssh -S <socket>` travels through that one authenticated connection in milliseconds and asks nothing. So the editor logs in once, in the foreground, **before it takes the screen** — which is the only moment ssh can ask a question on the terminal — and passes `BatchMode=yes` to everything afterwards, so that a lost master fails loudly instead of drawing a password prompt over the editor.
++
++`ControlPersist=60` keeps the master alive for a minute after its last user. The editor holds the SFTP channel open until it closes, so the minute only matters after a crash: the connection then goes away on its own.
++
++The cost is Windows: its OpenSSH port has no ControlMaster, and `Connect` returns `ErrUnsupported` there.
++
++## Why SFTP for the files, and not shell commands
++
++Once a shared connection exists, the cheapest-looking way to read a file is `ssh … cat file`, and to list a directory `ssh … ls`. It was rejected for two reasons.
++
++The output of `ls` and `stat` is not portable — GNU and BSD disagree on flags and on formats — and a file watcher built on parsing it is a watcher that breaks on the first macOS server. And a process per operation means a process per open file per second for the watcher alone.
++
++SFTP is the protocol OpenSSH already ships for exactly this, over one channel of the same connection (`ssh -s … sftp`): binary, portable, and one request per operation. The client is `github.com/pkg/sftp`, the one real dependency the feature added. Writing the dozen SFTP messages the editor needs by hand was considered and rejected as protocol code to maintain for no gain.
++
++An atomic save survives the move: the new content is written to a temporary file beside the target and renamed over it with `posix-rename@openssh.com`, which replaces the target in one step, as `rename(2)` does locally.
++
++## Why every remote command is `/bin/sh -c '…'`
++
++ssh hands the command it is given to the user's *login* shell, which may be fish, or anything else that does not read `cd dir && exec …` the way sh does. So every command sent is `exec /bin/sh -c '<script>'`, quoted once for the login shell: a tool's command line means over there what it means locally — `/bin/sh -c`, pipes and `&&` included — and a terminal starts the user's own shell with `exec "${SHELL:-/bin/sh}" -l` from inside sh.
++
++## What is switched off, and why
++
++- **The language server.** The servers an editor knows how to find are on this machine; the files they would be asked about are not. Starting pylsp remotely over the same connection is possible, but the paths in its answers would then have to be translated, and the server would have to be installed there. It is left for later rather than half done.
++- **Agent windows.** An agent is a program on this machine that reads and writes this machine's files. One running while the editor shows the remote project would be editing a different project from the one on screen. The Agent menu says so rather than offering it.
++
++## Rejected alternatives
++
++- **Mounting with sshfs.** Needs macFUSE on macOS, a kernel extension the person has to install and approve, and leaves the terminals and tools local.
++- **Copying the editor to the machine and running it there.** The binary is built for the person's machine — `darwin/arm64` — and the server is usually `linux/amd64`; and the editor would lose the local clipboard and the person's themes.
++- **An interface threaded through every package** instead of `fsys.Use`. See "One door for the files" above.
++
++## How it relates to the rest
++
++`fsys` sits below everything that touches a project file, with no dependencies of its own. `remote` does not even import it — its `FS` has the right methods, which is all a Go interface asks. It sits beside `configrepo`, since both drive an installed command, and `app` knows it only through the three-method `app.Remote` interface, so its tests use a fake that runs `/bin/sh` locally. Each editor adds the flag in its `main.go`; the reference is [remote](../reference/remote.md), and the recipe [add remote editing](../how-to/add-remote-editing.md).

added docs/en/how-to/add-remote-editing.md +82 -0 Viewed

new file mode 100644
@@ -0,0 +1,82 @@
	1	+# How to add remote editing to an editor
	2	+
	3	+This guide gives an editor built on turbo-core a `-ssh user@machine[:directory]` flag, so it edits another machine's files, and runs its terminals and tools there. It assumes your `main.go` has the shape of the one in [build an editor](../tutorials/build-an-editor.md): flags, `loadProjectSettings`, `newScreen`, `app.New`, `StartLanguageServer`, `Run`.
	4	+
	5	+## Steps
	6	+
	7	+1. Import the two packages:
	8	+
	9	+ ```go
	10	+ "rickub.com/turbo-editors/turbo-core/fsys"
	11	+ "rickub.com/turbo-editors/turbo-core/remote"
	12	+ ```
	13	+
	14	+2. Add the flag. Go's `flag` package accepts `-ssh` and `--ssh` alike:
	15	+
	16	+ ```go
	17	+ flag.StringVar(&opts.ssh, "ssh", "", "edit the files of another machine over ssh: user@machine[:directory]")
	18	+ ```
	19	+
	20	+3. Add the function that connects and switches every file read to the machine:
	21	+
	22	+ ```go
	23	+ func connectRemote(target string) (*remote.Session, error) {
	24	+ if target == "" {
	25	+ return nil, nil
	26	+ }
	27	+ session, err := remote.Open(context.Background(), target)
	28	+ if err != nil {
	29	+ return nil, err
	30	+ }
	31	+ fsys.Use(session.FS())
	32	+ return session, nil
	33	+ }
	34	+ ```
	35	+
	36	+4. Call it first in `edit`, before `newScreen` — ssh may need the terminal to ask for a password — and close it on the way out:
	37	+
	38	+ ```go
	39	+ session, err := connectRemote(opts.ssh)
	40	+ if err != nil {
	41	+ return err
	42	+ }
	43	+ if session != nil {
	44	+ defer session.Close()
	45	+ }
	46	+ ```
	47	+
	48	+5. Read the project directory through `fsys`, so that it is the remote one:
	49	+
	50	+ ```go
	51	+ project, err := fsys.Getwd() // was os.Getwd()
	52	+ ```
	53	+
	54	+6. Tell the editor, and do not start a local language server for remote files:
	55	+
	56	+ ```go
	57	+ editor := app.New(screen, themeName, p)
	58	+ if session != nil {
	59	+ editor.UseRemote(session)
	60	+ }
	61	+ // …
	62	+ if !opts.noLSP && session == nil {
	63	+ editor.StartLanguageServer(ctx, app.ProjectRoot(p, opts.files))
	64	+ }
	65	+ ```
	66	+
	67	+7. Build, then try it against the demo machine in `turbo-editors/demo-remote-machine` (its README says how to start it):
	68	+
	69	+ ```bash
	70	+ go build -o bin/turbo-x . && ./bin/turbo-x -ssh turbo-demo:workspace/hello-python
	71	+ ```
	72	+
	73	+## Variants
	74	+
	75	+- Testing the flag without a machine. Split `parseFlags` into a function taking a `*flag.FlagSet` and the arguments, and give it `flag.NewFlagSet(name, flag.ContinueOnError)` in a test. A bad target such as `-oProxyCommand=x` is refused by `connectRemote` before anything runs, so it can be tested with no ssh at all.
	76	+- Testing file access without a machine. `fsys.Use(fsystest.New("/remote/project"))` in a test makes every read and write go to memory; see [fsys](../reference/fsys.md).
	77	+- Your editor is built against the published library. `fsys` and `remote` arrived after v1.0.4; require the version that has them, or use a workspace — [test without publishing](test-without-publishing.md).
	78	+
	79	+## See also
	80	+
	81	+- Every function used here: [remote](../reference/remote.md), [fsys](../reference/fsys.md), [the app API](../reference/app.md)
	82	+- What changes in the editor, and why: [remote editing](../explanation/remote-editing.md)

++# How to add remote editing to an editor
++
++This guide gives an editor built on turbo-core a `-ssh user@machine[:directory]` flag, so it edits another machine's files, and runs its terminals and tools there. It assumes your `main.go` has the shape of the one in [build an editor](../tutorials/build-an-editor.md): flags, `loadProjectSettings`, `newScreen`, `app.New`, `StartLanguageServer`, `Run`.
++
++## Steps
++
++1. Import the two packages:
++
++   ```go
++   "rickub.com/turbo-editors/turbo-core/fsys"
++   "rickub.com/turbo-editors/turbo-core/remote"
++   ```
++
++2. Add the flag. Go's `flag` package accepts `-ssh` and `--ssh` alike:
++
++   ```go
++   flag.StringVar(&opts.ssh, "ssh", "", "edit the files of another machine over ssh: user@machine[:directory]")
++   ```
++
++3. Add the function that connects and switches every file read to the machine:
++
++   ```go
++   func connectRemote(target string) (*remote.Session, error) {
++   	if target == "" {
++   		return nil, nil
++   	}
++   	session, err := remote.Open(context.Background(), target)
++   	if err != nil {
++   		return nil, err
++   	}
++   	fsys.Use(session.FS())
++   	return session, nil
++   }
++   ```
++
++4. Call it first in `edit`, **before** `newScreen` — ssh may need the terminal to ask for a password — and close it on the way out:
++
++   ```go
++   session, err := connectRemote(opts.ssh)
++   if err != nil {
++   	return err
++   }
++   if session != nil {
++   	defer session.Close()
++   }
++   ```
++
++5. Read the project directory through `fsys`, so that it is the remote one:
++
++   ```go
++   project, err := fsys.Getwd() // was os.Getwd()
++   ```
++
++6. Tell the editor, and do not start a local language server for remote files:
++
++   ```go
++   editor := app.New(screen, themeName, p)
++   if session != nil {
++   	editor.UseRemote(session)
++   }
++   // …
++   if !opts.noLSP && session == nil {
++   	editor.StartLanguageServer(ctx, app.ProjectRoot(p, opts.files))
++   }
++   ```
++
++7. Build, then try it against the demo machine in `turbo-editors/demo-remote-machine` (its README says how to start it):
++
++   ```bash
++   go build -o bin/turbo-x . && ./bin/turbo-x -ssh turbo-demo:workspace/hello-python
++   ```
++
++## Variants
++
++- **Testing the flag without a machine.** Split `parseFlags` into a function taking a `*flag.FlagSet` and the arguments, and give it `flag.NewFlagSet(name, flag.ContinueOnError)` in a test. A bad target such as `-oProxyCommand=x` is refused by `connectRemote` before anything runs, so it can be tested with no ssh at all.
++- **Testing file access without a machine.** `fsys.Use(fsystest.New("/remote/project"))` in a test makes every read and write go to memory; see [fsys](../reference/fsys.md).
++- **Your editor is built against the published library.** `fsys` and `remote` arrived after v1.0.4; require the version that has them, or use a workspace — [test without publishing](test-without-publishing.md).
++
++## See also
++
++- Every function used here: [remote](../reference/remote.md), [fsys](../reference/fsys.md), [the app API](../reference/app.md)
++- What changes in the editor, and why: [remote editing](../explanation/remote-editing.md)

modified docs/en/how-to/run-the-tests.md +11 -0 Viewed

@@ -57,6 +57,17 @@ make help
57	57
58	58	Use `make race`, not `make test`. A data race in a constructor that starts a goroutine hid here for a whole feature, because a shell takes longer to produce output than an assignment takes to run.
59	59
	60	+### You changed `remote`, and want a real sshd
	61	+
	62	+`go test ./remote/` needs no network: it runs a real SFTP server through pipes, and the test binary itself stands in for ssh. To run the one test that talks to a real sshd, start the demo machine in `turbo-editors/demo-remote-machine` and give the test its key:
	63	+
	64	+```bash
	65	+(cd ../demo-remote-machine && ./make-key.sh && docker compose up -d --build)
	66	+TURBO_CORE_SSH_KEY=$PWD/../demo-remote-machine/keys/id_demo go test ./remote/ -run Real -v
	67	+```
	68	+
	69	+`TURBO_CORE_SSH_PORT` (default `2222`) and `TURBO_CORE_SSH_TARGET` (default `bob@127.0.0.1:workspace/hello-python`) point it elsewhere. Without `TURBO_CORE_SSH_KEY` the test skips itself.
	70	+
60	71	### A test passed the moment you wrote it
61	72
62	73	Break the code it covers and watch it fail. This project has more than one recorded case of a test that passed because it tested nothing — a callback nobody wired, a step the test itself performed. A new test that has never failed has not been tested.

  Use `make race`, not `make test`. A data race in a constructor that starts a goroutine hid here for a whole feature, because a shell takes longer to produce output than an assignment takes to run.
++### You changed `remote`, and want a real sshd
++
++`go test ./remote/` needs no network: it runs a real SFTP server through pipes, and the test binary itself stands in for ssh. To run the one test that talks to a real sshd, start the demo machine in `turbo-editors/demo-remote-machine` and give the test its key:
++
++```bash
++(cd ../demo-remote-machine && ./make-key.sh && docker compose up -d --build)
++TURBO_CORE_SSH_KEY=$PWD/../demo-remote-machine/keys/id_demo go test ./remote/ -run Real -v
++```
++
++`TURBO_CORE_SSH_PORT` (default `2222`) and `TURBO_CORE_SSH_TARGET` (default `bob@127.0.0.1:workspace/hello-python`) point it elsewhere. Without `TURBO_CORE_SSH_KEY` the test skips itself.
++
  ### A test passed the moment you wrote it
  Break the code it covers and watch it fail. This project has more than one recorded case of a test that passed because it tested nothing — a callback nobody wired, a step the test itself performed. A new test that has never failed has not been tested.

modified docs/en/reference/app.md +18 -0 Viewed

@@ -99,6 +99,23 @@ Saving keeps the server's set of open documents true. Writing a file the server
99	99	\| `Message(text string)` \| A one-line note on the status bar. \|
100	100	\| `ShowMessage(title, message string)` \| A modal box. \|
101	101
	102	+## Another machine
	103	+
	104	+\| Method \| Description \|
	105	+\| --- \| --- \|
	106	+\| `UseRemote(r Remote)` \| Tells the editor its project is on another machine. Call it after `app.New`, having already switched `fsys` to that machine. From then on terminal windows and tools run through `r`, the status bar starts with `⇄ <r.Name()>`, and agent windows are refused with a message. \|
	107	+\| `Remote() Remote` \| The machine being edited, or nil when the files are local. \|
	108	+
	109	+`Remote` is an interface; `*remote.Session` implements it.
	110	+
	111	+\| `Remote` method \| Used for \|
	112	+\| --- \| --- \|
	113	+\| `Name() string` \| The status bar, and a terminal window's title until the shell names itself. \|
	114	+\| `ShellCommand(dir string) []string` \| The argv of `New terminal` (F8): a login shell in `dir`, the directory of the front file or the project. Started from the editor's own local working directory. \|
	115	+\| `RunCommand(dir, command string, withTerminal bool) []string` \| The argv of a tool: `withTerminal` true for `output = "terminal"`, false for `popup` and `editor`, which go through `tools.StartProgram`. `dir` is the project directory. \|
	116	+
	117	+What `UseRemote` does not do: start or stop a language server (the command decides; see [add remote editing](../how-to/add-remote-editing.md)), or change where themes and the user's snippets are read from.
	118	+
102	119	## Tool parameters
103	120
104	121	A command may ask for values before it runs, by writing `{{label}}` where the value goes. `app.RunTool` opens a box for them; nothing here draws anything.
@@ -131,3 +148,4 @@ A command may ask for values before it runs, by writing `{{label}}` where the va
131	148
132	149	- [Build an editor](../tutorials/build-an-editor.md)
133	150	- [Profile reference](profile.md)
	151	+- [remote](remote.md), [fsys](fsys.md)

  | `Message(text string)` | A one-line note on the status bar. |
  | `ShowMessage(title, message string)` | A modal box. |
++## Another machine
++
++| Method | Description |
++| --- | --- |
++| `UseRemote(r Remote)` | Tells the editor its project is on another machine. Call it after `app.New`, having already switched `fsys` to that machine. From then on terminal windows and tools run through `r`, the status bar starts with `⇄ <r.Name()>`, and agent windows are refused with a message. |
++| `Remote() Remote` | The machine being edited, or nil when the files are local. |
++
++`Remote` is an interface; `*remote.Session` implements it.
++
++| `Remote` method | Used for |
++| --- | --- |
++| `Name() string` | The status bar, and a terminal window's title until the shell names itself. |
++| `ShellCommand(dir string) []string` | The argv of `New terminal` (F8): a login shell in `dir`, the directory of the front file or the project. Started from the editor's own local working directory. |
++| `RunCommand(dir, command string, withTerminal bool) []string` | The argv of a tool: `withTerminal` true for `output = "terminal"`, false for `popup` and `editor`, which go through `tools.StartProgram`. `dir` is the project directory. |
++
++What `UseRemote` does not do: start or stop a language server (the command decides; see [add remote editing](../how-to/add-remote-editing.md)), or change where themes and the user's snippets are read from.
++
  ## Tool parameters
  A command may ask for values before it runs, by writing `{{label}}` where the value goes. `app.RunTool` opens a box for them; nothing here draws anything.
  - [Build an editor](../tutorials/build-an-editor.md)
  - [Profile reference](profile.md)
++- [remote](remote.md), [fsys](fsys.md)

added docs/en/reference/fsys.md +84 -0 Viewed

new file mode 100644
@@ -0,0 +1,84 @@
	1	+# Reference: fsys
	2	+
	3	+> Neutral description of package `fsys`, the one door through which the editor reaches the files of the project it edits, and of `fsys/fsystest`, its in-memory stand-in for tests.
	4	+
	5	+Import path: `rickub.com/turbo-editors/turbo-core/fsys`. Depends on the standard library only.
	6	+
	7	+## What goes through it
	8	+
	9	+\| Goes through `fsys` \| Stays on the local disk (package `os`) \|
	10	+\| --- \| --- \|
	11	+\| Source files opened, reloaded and saved (`buffer`) \| The user's themes (`theme`) \|
	12	+\| The project tree (`filetree`) \| The user's own snippets file (`snippets.UserPath`) \|
	13	+\| The Open and Save As dialogs (`app`) \| The language server's executable (`lsp`) \|
	14	+\| `.turbo-<slug>/settings.toml`, `snippets.toml`, `tools.toml` (`settings`, `snippets`, `tools`, `projectfile`) \| The agents file and the agents' own reads and writes (`acp`) \|
	15	+\| The working directory the editor treats as the project (`app`) \| `-load-config`'s clone and copy (`configrepo`) \|
	16	+\| The file watcher's once-a-second stat (`app`) \| \|
	17	+
	18	+## Interface `FS`
	19	+
	20	+```go
	21	+type FS interface {
	22	+ ReadFile(name string) ([]byte, error)
	23	+ WriteFileAtomic(name string, data []byte, perm fs.FileMode) error
	24	+ ReadDir(name string) ([]fs.DirEntry, error)
	25	+ Stat(name string) (fs.FileInfo, error)
	26	+ MkdirAll(name string, perm fs.FileMode) error
	27	+ Getwd() (string, error)
	28	+}
	29	+```
	30	+
	31	+\| Method \| Contract \|
	32	+\| --- \| --- \|
	33	+\| `ReadFile` \| The whole content of a file. \|
	34	+\| `WriteFileAtomic` \| Replaces a file with `data` and mode `perm` so that a reader sees the old content or the new one, never half. The directory must exist. \|
	35	+\| `ReadDir` \| A directory's entries, sorted by name. \|
	36	+\| `Stat` \| Describes a file, following symbolic links. \|
	37	+\| `MkdirAll` \| Makes a directory and every missing parent. \|
	38	+\| `Getwd` \| The absolute directory relative paths start from. \|
	39	+
	40	+Every error meaning "no such file" satisfies `errors.Is(err, fs.ErrNotExist)`. Relative paths are relative to `Getwd`.
	41	+
	42	+## Functions
	43	+
	44	+\| Function \| Description \|
	45	+\| --- \| --- \|
	46	+\| `Use(f FS) (previous FS)` \| Makes `f` the file system every package goes through; returns the one it replaces. Safe from any goroutine; meant to be called once, at start-up, before any file is opened. \|
	47	+\| `Current() FS` \| The file system in use. \|
	48	+\| `IsLocal() bool` \| Whether the file system in use is `Local`. \|
	49	+\| `ReadFile`, `WriteFileAtomic`, `ReadDir`, `Stat`, `MkdirAll`, `Getwd` \| The `FS` methods, on `Current()`. \|
	50	+\| `Abs(path string) (string, error)` \| `path` made absolute against `Getwd()` and cleaned. The remote-aware counterpart of `filepath.Abs`. \|
	51	+
	52	+## Type `Local`
	53	+
	54	+`Local{}` is the default: the disk of the machine the editor runs on, through package `os`. `WriteFileAtomic` writes `.<name>.<random>` beside the target, sets `perm`, and renames it over the target; the temporary file is removed on every failure.
	55	+
	56	+## Package `fsystest`
	57	+
	58	+Import path: `rickub.com/turbo-editors/turbo-core/fsys/fsystest`. For tests only.
	59	+
	60	+\| Function / method \| Description \|
	61	+\| --- \| --- \|
	62	+\| `New(working string) *Memory` \| An empty in-memory `FS` whose working directory, and every directory above it, exists. Safe for concurrent use. \|
	63	+\| `(*Memory) AddFile(name, content string)` \| Creates or replaces a file with mode `0644`, making its directories. \|
	64	+\| `(*Memory) File(name string) (string, bool)` \| A file's content, and whether it exists. \|
	65	+\| `(*Memory) Mode(name string) fs.FileMode` \| A file's permissions, `0` when absent. \|
	66	+
	67	+Each write moves the file's modification time on by one nanosecond, so a watcher comparing stamps sees every change.
	68	+
	69	+## Example
	70	+
	71	+```go
	72	+memory := fsystest.New("/remote/project")
	73	+memory.AddFile("/remote/project/hello.py", "print('hello')\n")
	74	+
	75	+previous := fsys.Use(memory)
	76	+defer fsys.Use(previous)
	77	+
	78	+data, _ := fsys.ReadFile("hello.py") // "print('hello')\n"
	79	+```
	80	+
	81	+## See also
	82	+
	83	+- The SFTP implementation of `FS`: [remote](remote.md)
	84	+- Why the files have one door: [remote editing](../explanation/remote-editing.md)

++# Reference: fsys
++
++> Neutral description of package `fsys`, the one door through which the editor reaches the files of the project it edits, and of `fsys/fsystest`, its in-memory stand-in for tests.
++
++Import path: `rickub.com/turbo-editors/turbo-core/fsys`. Depends on the standard library only.
++
++## What goes through it
++
++| Goes through `fsys` | Stays on the local disk (package `os`) |
++| --- | --- |
++| Source files opened, reloaded and saved (`buffer`) | The user's themes (`theme`) |
++| The project tree (`filetree`) | The user's own snippets file (`snippets.UserPath`) |
++| The Open and Save As dialogs (`app`) | The language server's executable (`lsp`) |
++| `.turbo-<slug>/settings.toml`, `snippets.toml`, `tools.toml` (`settings`, `snippets`, `tools`, `projectfile`) | The agents file and the agents' own reads and writes (`acp`) |
++| The working directory the editor treats as the project (`app`) | `-load-config`'s clone and copy (`configrepo`) |
++| The file watcher's once-a-second stat (`app`) | |
++
++## Interface `FS`
++
++```go
++type FS interface {
++	ReadFile(name string) ([]byte, error)
++	WriteFileAtomic(name string, data []byte, perm fs.FileMode) error
++	ReadDir(name string) ([]fs.DirEntry, error)
++	Stat(name string) (fs.FileInfo, error)
++	MkdirAll(name string, perm fs.FileMode) error
++	Getwd() (string, error)
++}
++```
++
++| Method | Contract |
++| --- | --- |
++| `ReadFile` | The whole content of a file. |
++| `WriteFileAtomic` | Replaces a file with `data` and mode `perm` so that a reader sees the old content or the new one, never half. The directory must exist. |
++| `ReadDir` | A directory's entries, sorted by name. |
++| `Stat` | Describes a file, following symbolic links. |
++| `MkdirAll` | Makes a directory and every missing parent. |
++| `Getwd` | The absolute directory relative paths start from. |
++
++Every error meaning "no such file" satisfies `errors.Is(err, fs.ErrNotExist)`. Relative paths are relative to `Getwd`.
++
++## Functions
++
++| Function | Description |
++| --- | --- |
++| `Use(f FS) (previous FS)` | Makes `f` the file system every package goes through; returns the one it replaces. Safe from any goroutine; meant to be called once, at start-up, before any file is opened. |
++| `Current() FS` | The file system in use. |
++| `IsLocal() bool` | Whether the file system in use is `Local`. |
++| `ReadFile`, `WriteFileAtomic`, `ReadDir`, `Stat`, `MkdirAll`, `Getwd` | The `FS` methods, on `Current()`. |
++| `Abs(path string) (string, error)` | `path` made absolute against `Getwd()` and cleaned. The remote-aware counterpart of `filepath.Abs`. |
++
++## Type `Local`
++
++`Local{}` is the default: the disk of the machine the editor runs on, through package `os`. `WriteFileAtomic` writes `.<name>.<random>` beside the target, sets `perm`, and renames it over the target; the temporary file is removed on every failure.
++
++## Package `fsystest`
++
++Import path: `rickub.com/turbo-editors/turbo-core/fsys/fsystest`. For tests only.
++
++| Function / method | Description |
++| --- | --- |
++| `New(working string) *Memory` | An empty in-memory `FS` whose working directory, and every directory above it, exists. Safe for concurrent use. |
++| `(*Memory) AddFile(name, content string)` | Creates or replaces a file with mode `0644`, making its directories. |
++| `(*Memory) File(name string) (string, bool)` | A file's content, and whether it exists. |
++| `(*Memory) Mode(name string) fs.FileMode` | A file's permissions, `0` when absent. |
++
++Each write moves the file's modification time on by one nanosecond, so a watcher comparing stamps sees every change.
++
++## Example
++
++```go
++memory := fsystest.New("/remote/project")
++memory.AddFile("/remote/project/hello.py", "print('hello')\n")
++
++previous := fsys.Use(memory)
++defer fsys.Use(previous)
++
++data, _ := fsys.ReadFile("hello.py") // "print('hello')\n"
++```
++
++## See also
++
++- The SFTP implementation of `FS`: [remote](remote.md)
++- Why the files have one door: [remote editing](../explanation/remote-editing.md)

modified docs/en/reference/packages.md +23 -15 Viewed

@@ -2,16 +2,19 @@
2	2
3	3	> Neutral, exhaustive description of what turbo-core holds.
4	4
5		-Nineteen packages. Dependencies run strictly downwards; there are no cycles and no interface indirection to prevent one.
	5	+Twenty-two packages. Dependencies run strictly downwards; there are no cycles and no interface indirection to prevent one.
6	6
7	7	```
8		-app → {editor, ui, lsp, buffer, terminal, filetree, settings, snippets, tools, syntax, theme, profile, version}
	8	+app → {editor, ui, lsp, buffer, terminal, filetree, settings, snippets, tools, syntax, theme, profile, version, fsys}
	9	+ remote → github.com/pkg/sftp ← runs the ssh command; implements fsys.FS without importing fsys
9	10	editor → {buffer, syntax, ui, theme}
10	11	terminal → {ui, theme, tcell, golang.org/x/sys}
11		- filetree → {ui, theme, tcell}
12		- snippets → {toml, projectfile, profile}
13		- settings → {toml, projectfile, profile}
14		- tools → {toml, projectfile, profile}
	12	+ filetree → {ui, theme, tcell, fsys}
	13	+ snippets → {toml, projectfile, profile, fsys}
	14	+ settings → {toml, projectfile, profile, fsys}
	15	+ tools → {toml, projectfile, profile, fsys}
	16	+ buffer, projectfile → fsys
	17	+ fsys → stdlib only
15	18	configrepo → {projectfile, profile} ← runs the git command
16	19	syntax → theme
17	20	ui → theme
@@ -22,35 +25,39 @@ app → {editor, ui, lsp, buffer, terminal, filetree, settings, snippets, tools,
22	25	\| Package \| What it holds \| Depends on \|
23	26	\| --- \| --- \| --- \|
24	27	\| `profile` \| The editor's identity: name, slug, language server, starter templates, and the paths derived from them \| stdlib only \|
25		-\| `buffer` \| The text of one file: lines of runes, cursor, selection, undo, search, load and save \| stdlib only \|
26		-\| `projectfile` \| Atomic writes of the TOML files a project keeps in the editor's own directory \| stdlib only \|
	28	+\| `fsys` \| The one door to the project's files: the `FS` interface, the local disk, and `Use` to switch every package to another machine \| stdlib only \|
	29	+\| `fsys/fsystest` \| An in-memory `fsys.FS`, for tests \| `fsys` \|
	30	+\| `remote` \| Another machine over the `ssh` command: a ControlMaster connection, the files over SFTP, the command lines of remote shells and tools (`-ssh`) \| `github.com/pkg/sftp`, the `ssh` command; its `FS` satisfies `fsys.FS` without importing `fsys` \|
	31	+\| `buffer` \| The text of one file: lines of runes, cursor, selection, undo, search, load and save \| `fsys` \|
	32	+\| `projectfile` \| Atomic writes of the TOML files a project keeps in the editor's own directory \| `fsys` \|
27	33	\| `configrepo` \| A shared configuration directory fetched from a forge URL (rickub, GitHub, GitLab, Codeberg) by a shallow git clone, for an editor's `-load-config` \| `projectfile`, `profile`, the `git` command \|
28	34	\| `version` \| What build of itself a binary is: linker stamp, then Go build info \| stdlib only \|
29	35	\| `jsonrpc` \| JSON-RPC 2.0 over a framed stream: calls, notifications, inbound requests answerable later \| stdlib only \|
30	36	\| `lsp` \| LSP framing, the methods, and the child process \| `jsonrpc`, `profile` \|
31	37	\| `theme` \| TOML into tcell styles; eleven embedded themes plus the user's own; two kinds of inheritance \| `tcell`, `toml` \|
32	38	\| `syntax` \| Colouring: nine built-in languages, the registry an editor adds its own to, and the scanner toolkit \| `theme` \|
33		-\| `settings` \| A project's `settings.toml`: load, create, rewrite one key in place \| `toml`, `projectfile`, `profile` \|
34		-\| `snippets` \| Reusable text from a project's and a user's `snippets.toml`, grouped for a menu \| `toml`, `projectfile`, `profile` \|
35		-\| `tools` \| The commands a project runs on itself, and which menu each is in \| `toml`, `projectfile`, `profile` \|
	39	+\| `settings` \| A project's `settings.toml`: load, create, rewrite one key in place \| `toml`, `projectfile`, `profile`, `fsys` \|
	40	+\| `snippets` \| Reusable text from a project's and a user's `snippets.toml`, grouped for a menu \| `toml`, `projectfile`, `profile`, `fsys` \|
	41	+\| `tools` \| The commands a project runs on itself, and which menu each is in; `Start` through the local shell, `StartProgram` for an argv such as a remote one \| `toml`, `projectfile`, `profile`, `fsys` \|
36	42	\| `ui` \| Turbo Vision widgets: painter, desktop, window, menu, dialog, controls, status bar \| `theme`, `tcell` \|
37	43	\| `editor` \| The editing widget: viewport, scrolling, keys, mouse, snippet insertion \| `buffer`, `syntax`, `theme`, `ui` \|
38	44	\| `terminal` \| A shell in a window: pseudo-terminal, VT/ANSI emulator, screen grid, the widget \| `theme`, `ui`, `tcell`, `golang.org/x/sys` \|
39		-\| `filetree` \| A project's files as an expandable tree, and the window showing it \| `theme`, `ui`, `tcell` \|
	45	+\| `filetree` \| A project's files as an expandable tree, and the window showing it \| `theme`, `ui`, `tcell`, `fsys` \|
40	46	\| `acp` \| A coding agent in a window: the Agent Client Protocol, the conversation, the widget \| `jsonrpc`, `profile`, `projectfile`, `syntax`, `theme`, `ui`, `tcell`, `toml` \|
41		-\| `app` \| Assembly: menus, dialogs, event routing, completion popup, language-server lifecycle \| all of the above \|
	47	+\| `app` \| Assembly: menus, dialogs, event routing, completion popup, language-server lifecycle, remote shells and tools (`UseRemote`) \| all of the above except `remote`, which it knows through the `app.Remote` interface \|
42	48
43	49	## Third-party dependencies
44	50
45		-Three, and only three:
	51	+Four direct ones:
46	52
47	53	\| Module \| Why \|
48	54	\| --- \| --- \|
49	55	\| `github.com/gdamore/tcell/v2` \| the terminal \|
50	56	\| `github.com/BurntSushi/toml` \| every configuration file the editor reads \|
51	57	\| `golang.org/x/sys` \| the pseudo-terminal ioctls on Linux and macOS; the pseudo-console, process and job-object calls on Windows \|
	58	+\| `github.com/pkg/sftp` \| the SFTP client `remote` reads and writes a machine's files with, over the channel ssh opens; it brings `github.com/kr/fs` and `golang.org/x/crypto` in as indirect requirements \|
52	59
53		-The tokeniser, the JSON-RPC client, the LSP framing and the VT/ANSI emulator are hand-written.
	60	+The tokeniser, the JSON-RPC client, the LSP framing and the VT/ANSI emulator are hand-written. SSH itself is not in the binary: `remote` runs the installed `ssh` command.
54	61
55	62	## The diagram
56	63
@@ -59,3 +66,4 @@ The tokeniser, the JSON-RPC client, the LSP framing and the VT/ANSI emulator are
59	66	## See also
60	67
61	68	- Why the graph is shaped this way: [architecture](../explanation/architecture.md)
	69	+- The two packages of remote editing: [fsys](fsys.md), [remote](remote.md)

  > Neutral, exhaustive description of what turbo-core holds.
--Nineteen packages. Dependencies run strictly downwards; there are no cycles and no interface indirection to prevent one.
++Twenty-two packages. Dependencies run strictly downwards; there are no cycles and no interface indirection to prevent one.
  ```
--app → {editor, ui, lsp, buffer, terminal, filetree, settings, snippets, tools, syntax, theme, profile, version}
++app → {editor, ui, lsp, buffer, terminal, filetree, settings, snippets, tools, syntax, theme, profile, version, fsys}
++       remote   → github.com/pkg/sftp   ← runs the ssh command; implements fsys.FS without importing fsys
         editor   → {buffer, syntax, ui, theme}
         terminal → {ui, theme, tcell, golang.org/x/sys}
--       filetree → {ui, theme, tcell}
++       filetree → {ui, theme, tcell, fsys}
--       snippets → {toml, projectfile, profile}
++       snippets → {toml, projectfile, profile, fsys}
--       settings → {toml, projectfile, profile}
++       settings → {toml, projectfile, profile, fsys}
--       tools    → {toml, projectfile, profile}
++       tools    → {toml, projectfile, profile, fsys}
++       buffer, projectfile → fsys
++       fsys     → stdlib only
         configrepo → {projectfile, profile}   ← runs the git command
         syntax   → theme
         ui       → theme
  | Package | What it holds | Depends on |
  | --- | --- | --- |
  | `profile` | The editor's identity: name, slug, language server, starter templates, and the paths derived from them | **stdlib only** |
--| `buffer` | The text of one file: lines of runes, cursor, selection, undo, search, load and save | **stdlib only** |
++| `fsys` | The one door to the project's files: the `FS` interface, the local disk, and `Use` to switch every package to another machine | **stdlib only** |
--| `projectfile` | Atomic writes of the TOML files a project keeps in the editor's own directory | **stdlib only** |
++| `fsys/fsystest` | An in-memory `fsys.FS`, for tests | `fsys` |
++| `remote` | Another machine over the `ssh` command: a ControlMaster connection, the files over SFTP, the command lines of remote shells and tools (`-ssh`) | `github.com/pkg/sftp`, the `ssh` command; its `FS` satisfies `fsys.FS` without importing `fsys` |
++| `buffer` | The text of one file: lines of runes, cursor, selection, undo, search, load and save | `fsys` |
++| `projectfile` | Atomic writes of the TOML files a project keeps in the editor's own directory | `fsys` |
  | `configrepo` | A shared configuration directory fetched from a forge URL (rickub, GitHub, GitLab, Codeberg) by a shallow git clone, for an editor's `-load-config` | `projectfile`, `profile`, the `git` command |
  | `version` | What build of itself a binary is: linker stamp, then Go build info | **stdlib only** |
  | `jsonrpc` | JSON-RPC 2.0 over a framed stream: calls, notifications, inbound requests answerable later | **stdlib only** |
  | `lsp` | LSP framing, the methods, and the child process | `jsonrpc`, `profile` |
  | `theme` | TOML into tcell styles; eleven embedded themes plus the user's own; two kinds of inheritance | `tcell`, `toml` |
  | `syntax` | Colouring: nine built-in languages, the registry an editor adds its own to, and the scanner toolkit | `theme` |
--| `settings` | A project's `settings.toml`: load, create, rewrite one key in place | `toml`, `projectfile`, `profile` |
++| `settings` | A project's `settings.toml`: load, create, rewrite one key in place | `toml`, `projectfile`, `profile`, `fsys` |
--| `snippets` | Reusable text from a project's and a user's `snippets.toml`, grouped for a menu | `toml`, `projectfile`, `profile` |
++| `snippets` | Reusable text from a project's and a user's `snippets.toml`, grouped for a menu | `toml`, `projectfile`, `profile`, `fsys` |
--| `tools` | The commands a project runs on itself, and which menu each is in | `toml`, `projectfile`, `profile` |
++| `tools` | The commands a project runs on itself, and which menu each is in; `Start` through the local shell, `StartProgram` for an argv such as a remote one | `toml`, `projectfile`, `profile`, `fsys` |
  | `ui` | Turbo Vision widgets: painter, desktop, window, menu, dialog, controls, status bar | `theme`, `tcell` |
  | `editor` | The editing widget: viewport, scrolling, keys, mouse, snippet insertion | `buffer`, `syntax`, `theme`, `ui` |
  | `terminal` | A shell in a window: pseudo-terminal, VT/ANSI emulator, screen grid, the widget | `theme`, `ui`, `tcell`, `golang.org/x/sys` |
--| `filetree` | A project's files as an expandable tree, and the window showing it | `theme`, `ui`, `tcell` |
++| `filetree` | A project's files as an expandable tree, and the window showing it | `theme`, `ui`, `tcell`, `fsys` |
  | `acp` | A coding agent in a window: the Agent Client Protocol, the conversation, the widget | `jsonrpc`, `profile`, `projectfile`, `syntax`, `theme`, `ui`, `tcell`, `toml` |
--| `app` | Assembly: menus, dialogs, event routing, completion popup, language-server lifecycle | all of the above |
++| `app` | Assembly: menus, dialogs, event routing, completion popup, language-server lifecycle, remote shells and tools (`UseRemote`) | all of the above except `remote`, which it knows through the `app.Remote` interface |
  ## Third-party dependencies
--Three, and only three:
++Four direct ones:
  | Module | Why |
  | --- | --- |
  | `github.com/gdamore/tcell/v2` | the terminal |
  | `github.com/BurntSushi/toml` | every configuration file the editor reads |
  | `golang.org/x/sys` | the pseudo-terminal ioctls on Linux and macOS; the pseudo-console, process and job-object calls on Windows |
++| `github.com/pkg/sftp` | the SFTP client `remote` reads and writes a machine's files with, over the channel ssh opens; it brings `github.com/kr/fs` and `golang.org/x/crypto` in as indirect requirements |
--The tokeniser, the JSON-RPC client, the LSP framing and the VT/ANSI emulator are hand-written.
++The tokeniser, the JSON-RPC client, the LSP framing and the VT/ANSI emulator are hand-written. SSH itself is not in the binary: `remote` runs the installed `ssh` command.
  ## The diagram
  ## See also
  - Why the graph is shaped this way: [architecture](../explanation/architecture.md)
++- The two packages of remote editing: [fsys](fsys.md), [remote](remote.md)

added docs/en/reference/remote.md +115 -0 Viewed

new file mode 100644
@@ -0,0 +1,115 @@
	1	+# Reference: remote
	2	+
	3	+> Neutral description of package `remote`, which reaches another machine through the installed `ssh` command: a shared connection, the files over SFTP, and the command lines of remote shells and tools.
	4	+
	5	+Import path: `rickub.com/turbo-editors/turbo-core/remote`. Depends on `github.com/pkg/sftp`, and on the `ssh` command at run time. Its `FS` satisfies `fsys.FS` without importing `fsys`.
	6	+
	7	+## Type `Target`
	8	+
	9	+What `-ssh` names: `[user@]host[:path]`, the way `scp` writes a remote location.
	10	+
	11	+\| Field \| Description \|
	12	+\| --- \| --- \|
	13	+\| `User` \| Who to log in as. Empty leaves it to ssh (`User` in `~/.ssh/config`, else the local user name). \|
	14	+\| `Host` \| A name, an address, or a `Host` alias from `~/.ssh/config`. An IPv6 address is written in brackets: `bob@[2001:db8::1]:/srv`. \|
	15	+\| `Path` \| The directory to open. Empty or `~` is the remote home; `~/x` and a relative path are relative to it. \|
	16	+
	17	+\| Function / method \| Description \|
	18	+\| --- \| --- \|
	19	+\| `ParseTarget(argument string) (Target, error)` \| Reads `[user@]host[:path]`. The user is everything before the last `@`. \|
	20	+\| `(Target) Destination() string` \| `user@host`, or `host` when no user was named: what ssh is given. \|
	21	+\| `(Target) String() string` \| The target written back as it is typed. \|
	22	+
	23	+`ParseTarget` returns an error wrapping `ErrBadTarget` for: an empty host or user, a host or user starting with `-` (ssh would read it as an option), a space, tab, newline or `/` in the host or user, and an unclosed or misplaced `[…]`.
	24	+
	25	+There is no port in the syntax; a port goes in `~/.ssh/config` under a `Host` alias.
	26	+
	27	+## Connecting
	28	+
	29	+\| Function \| Description \|
	30	+\| --- \| --- \|
	31	+\| `Open(ctx, argument string) (*Session, error)` \| `ParseTarget`, then prints `Connecting to <target>…` on standard error, then `Connect` with the default `Options`. What an editor's `-ssh` flag calls. \|
	32	+\| `Connect(ctx, target Target, options Options) (*Session, error)` \| Logs in, opens the file channel, resolves the directory. Must be called before the editor takes the terminal. \|
	33	+
	34	+`Options`:
	35	+
	36	+\| Field \| Default \| Description \|
	37	+\| --- \| --- \| --- \|
	38	+\| `Program` \| `"ssh"` on `PATH` \| The ssh command to run. \|
	39	+
	40	+What `Connect` runs, in order:
	41	+
	42	+\| Step \| Command \| Notes \|
	43	+\| --- \| --- \| --- \|
	44	+\| Log in \| `ssh -o ControlMaster=yes -o ControlPath=<socket> -o ControlPersist=60 -N -f -- <destination>` \| In the foreground, on the terminal: this is where ssh asks for a password, a passphrase, or whether to trust a new host key. Returns once logged in; the connection stays behind the socket. \|
	45	+\| Files \| `ssh -S <socket> -o ControlMaster=no -o BatchMode=yes -s -- <destination> sftp` \| One SFTP channel, open until `Close`. \|
	46	+\| Directory \| SFTP `realpath` then `stat` of `Path` \| Must be an existing directory. \|
	47	+
	48	+The socket is `<tmp>/turbo-ssh-XXXX/control`, where `<tmp>` is `os.TempDir()`, or `/tmp` when that is longer than 60 bytes (a Unix socket path is limited to about 100).
	49	+
	50	+## Type `Session`
	51	+
	52	+\| Method \| Description \|
	53	+\| --- \| --- \|
	54	+\| `FS() *FS` \| The remote files, rooted at the directory being edited. What the command passes to `fsys.Use`. \|
	55	+\| `Target() Target` \| What was connected to. \|
	56	+\| `Name() string` \| `Destination()`: how the machine is shown. \|
	57	+\| `ShellCommand(dir string) []string` \| The argv of an interactive login shell in `dir`: `ssh -S … -t -- <destination> "exec /bin/sh -c 'cd <dir> && exec \"${SHELL:-/bin/sh}\" -l'"`. \|
	58	+\| `RunCommand(dir, command string, withTerminal bool) []string` \| The argv running one command line with `/bin/sh` in `dir`: `ssh -S … -t\|-T -- <destination> "exec /bin/sh -c 'cd <dir> && <command>'"`. `-t` when `withTerminal`, else `-T`. \|
	59	+\| `Close() error` \| Closes the file channel, runs `ssh -S … -O exit -- <destination>`, removes the socket's directory. Terminals and tools running over the connection end with it. Safe to call twice. \|
	60	+
	61	+`Session` implements `app.Remote`.
	62	+
	63	+Every command after the login passes `ControlMaster=no` and `BatchMode=yes`: it never opens a connection of its own and never prompts, because the editor owns the terminal by then.
	64	+
	65	+## Type `FS`
	66	+
	67	+The remote files over SFTP; implements `fsys.FS`. Paths are slash-separated (`path`, not `path/filepath`), relative to the directory being edited.
	68	+
	69	+\| Method \| SFTP requests \|
	70	+\| --- \| --- \|
	71	+\| `ReadFile` \| `open`, `read`…, `close` \|
	72	+\| `WriteFileAtomic` \| `open` of `.<name>.<random>` with `O_EXCL`, `write`…, `close`, `setstat` (mode), `posix-rename@openssh.com` over the target; `remove` of the temporary on failure \|
	73	+\| `ReadDir` \| `opendir`, `readdir`…; sorted by name \|
	74	+\| `Stat` \| `stat` \|
	75	+\| `MkdirAll` \| `stat` / `mkdir` per level; the remote umask decides the mode \|
	76	+\| `Getwd` \| none: the directory resolved at `Connect` \|
	77	+
	78	+A server's "no such file" status is wrapped so that `errors.Is(err, fs.ErrNotExist)` holds.
	79	+
	80	+## Errors
	81	+
	82	+\| Error \| Cause \|
	83	+\| --- \| --- \|
	84	+\| `ErrBadTarget` \| The `-ssh` argument is not `[user@]host[:path]`, or would be read by ssh as an option. \|
	85	+\| `ErrNoSSH` \| No ssh command on `PATH`. \|
	86	+\| `ErrUnsupported` \| Windows: its OpenSSH port has no ControlMaster. \|
	87	+\| `ssh <destination>: exit status 255` \| The login failed; ssh has already said why on the terminal. \|
	88	+\| `opening the file channel to <destination>: … (<what ssh said>)` \| The server refused the `sftp` subsystem. \|
	89	+\| `finding <path> on the remote machine: …` / `opening … : …` \| The directory does not exist. \|
	90	+\| `<path> on the remote machine is not a directory: invalid argument` \| The path names a file. \|
	91	+
	92	+## Related: `tools.StartProgram`
	93	+
	94	+```go
	95	+func StartProgram(command string, argv []string, onLine func()) (*tools.Run, error)
	96	+```
	97	+
	98	+Runs `argv` with no local shell in between; `command` is what the run is called (`Run.Command()`, the dialog title). Output merged, stoppable with `Stop`, as `tools.Start`. An empty `argv` is an error. This is how a captured tool runs over ssh: `tools.StartProgram(command, session.RunCommand(dir, command, false), wake)`.
	99	+
	100	+## Example
	101	+
	102	+```go
	103	+session, err := remote.Open(ctx, "bob@build-box:/srv/app")
	104	+if err != nil {
	105	+ return err
	106	+}
	107	+defer session.Close()
	108	+fsys.Use(session.FS())
	109	+```
	110	+
	111	+## See also
	112	+
	113	+- The interface it implements: [fsys](fsys.md)
	114	+- Wiring it into an editor: [add remote editing](../how-to/add-remote-editing.md)
	115	+- Why it drives the ssh command: [remote editing](../explanation/remote-editing.md)

++# Reference: remote
++
++> Neutral description of package `remote`, which reaches another machine through the installed `ssh` command: a shared connection, the files over SFTP, and the command lines of remote shells and tools.
++
++Import path: `rickub.com/turbo-editors/turbo-core/remote`. Depends on `github.com/pkg/sftp`, and on the `ssh` command at run time. Its `FS` satisfies `fsys.FS` without importing `fsys`.
++
++## Type `Target`
++
++What `-ssh` names: `[user@]host[:path]`, the way `scp` writes a remote location.
++
++| Field | Description |
++| --- | --- |
++| `User` | Who to log in as. Empty leaves it to ssh (`User` in `~/.ssh/config`, else the local user name). |
++| `Host` | A name, an address, or a `Host` alias from `~/.ssh/config`. An IPv6 address is written in brackets: `bob@[2001:db8::1]:/srv`. |
++| `Path` | The directory to open. Empty or `~` is the remote home; `~/x` and a relative path are relative to it. |
++
++| Function / method | Description |
++| --- | --- |
++| `ParseTarget(argument string) (Target, error)` | Reads `[user@]host[:path]`. The user is everything before the **last** `@`. |
++| `(Target) Destination() string` | `user@host`, or `host` when no user was named: what ssh is given. |
++| `(Target) String() string` | The target written back as it is typed. |
++
++`ParseTarget` returns an error wrapping `ErrBadTarget` for: an empty host or user, a host or user starting with `-` (ssh would read it as an option), a space, tab, newline or `/` in the host or user, and an unclosed or misplaced `[…]`.
++
++There is no port in the syntax; a port goes in `~/.ssh/config` under a `Host` alias.
++
++## Connecting
++
++| Function | Description |
++| --- | --- |
++| `Open(ctx, argument string) (*Session, error)` | `ParseTarget`, then prints `Connecting to <target>…` on standard error, then `Connect` with the default `Options`. What an editor's `-ssh` flag calls. |
++| `Connect(ctx, target Target, options Options) (*Session, error)` | Logs in, opens the file channel, resolves the directory. Must be called before the editor takes the terminal. |
++
++`Options`:
++
++| Field | Default | Description |
++| --- | --- | --- |
++| `Program` | `"ssh"` on `PATH` | The ssh command to run. |
++
++What `Connect` runs, in order:
++
++| Step | Command | Notes |
++| --- | --- | --- |
++| Log in | `ssh -o ControlMaster=yes -o ControlPath=<socket> -o ControlPersist=60 -N -f -- <destination>` | In the foreground, on the terminal: this is where ssh asks for a password, a passphrase, or whether to trust a new host key. Returns once logged in; the connection stays behind the socket. |
++| Files | `ssh -S <socket> -o ControlMaster=no -o BatchMode=yes -s -- <destination> sftp` | One SFTP channel, open until `Close`. |
++| Directory | SFTP `realpath` then `stat` of `Path` | Must be an existing directory. |
++
++The socket is `<tmp>/turbo-ssh-XXXX/control`, where `<tmp>` is `os.TempDir()`, or `/tmp` when that is longer than 60 bytes (a Unix socket path is limited to about 100).
++
++## Type `Session`
++
++| Method | Description |
++| --- | --- |
++| `FS() *FS` | The remote files, rooted at the directory being edited. What the command passes to `fsys.Use`. |
++| `Target() Target` | What was connected to. |
++| `Name() string` | `Destination()`: how the machine is shown. |
++| `ShellCommand(dir string) []string` | The argv of an interactive login shell in `dir`: `ssh -S … -t -- <destination> "exec /bin/sh -c 'cd <dir> && exec \"${SHELL:-/bin/sh}\" -l'"`. |
++| `RunCommand(dir, command string, withTerminal bool) []string` | The argv running one command line with `/bin/sh` in `dir`: `ssh -S … -t|-T -- <destination> "exec /bin/sh -c 'cd <dir> && <command>'"`. `-t` when `withTerminal`, else `-T`. |
++| `Close() error` | Closes the file channel, runs `ssh -S … -O exit -- <destination>`, removes the socket's directory. Terminals and tools running over the connection end with it. Safe to call twice. |
++
++`Session` implements `app.Remote`.
++
++Every command after the login passes `ControlMaster=no` and `BatchMode=yes`: it never opens a connection of its own and never prompts, because the editor owns the terminal by then.
++
++## Type `FS`
++
++The remote files over SFTP; implements `fsys.FS`. Paths are slash-separated (`path`, not `path/filepath`), relative to the directory being edited.
++
++| Method | SFTP requests |
++| --- | --- |
++| `ReadFile` | `open`, `read`…, `close` |
++| `WriteFileAtomic` | `open` of `.<name>.<random>` with `O_EXCL`, `write`…, `close`, `setstat` (mode), `posix-rename@openssh.com` over the target; `remove` of the temporary on failure |
++| `ReadDir` | `opendir`, `readdir`…; sorted by name |
++| `Stat` | `stat` |
++| `MkdirAll` | `stat` / `mkdir` per level; the remote umask decides the mode |
++| `Getwd` | none: the directory resolved at `Connect` |
++
++A server's "no such file" status is wrapped so that `errors.Is(err, fs.ErrNotExist)` holds.
++
++## Errors
++
++| Error | Cause |
++| --- | --- |
++| `ErrBadTarget` | The `-ssh` argument is not `[user@]host[:path]`, or would be read by ssh as an option. |
++| `ErrNoSSH` | No ssh command on `PATH`. |
++| `ErrUnsupported` | Windows: its OpenSSH port has no ControlMaster. |
++| `ssh <destination>: exit status 255` | The login failed; ssh has already said why on the terminal. |
++| `opening the file channel to <destination>: … (<what ssh said>)` | The server refused the `sftp` subsystem. |
++| `finding <path> on the remote machine: …` / `opening … : …` | The directory does not exist. |
++| `<path> on the remote machine is not a directory: invalid argument` | The path names a file. |
++
++## Related: `tools.StartProgram`
++
++```go
++func StartProgram(command string, argv []string, onLine func()) (*tools.Run, error)
++```
++
++Runs `argv` with no local shell in between; `command` is what the run is called (`Run.Command()`, the dialog title). Output merged, stoppable with `Stop`, as `tools.Start`. An empty `argv` is an error. This is how a captured tool runs over ssh: `tools.StartProgram(command, session.RunCommand(dir, command, false), wake)`.
++
++## Example
++
++```go
++session, err := remote.Open(ctx, "bob@build-box:/srv/app")
++if err != nil {
++	return err
++}
++defer session.Close()
++fsys.Use(session.FS())
++```
++
++## See also
++
++- The interface it implements: [fsys](fsys.md)
++- Wiring it into an editor: [add remote editing](../how-to/add-remote-editing.md)
++- Why it drives the ssh command: [remote editing](../explanation/remote-editing.md)

modified docs/fr/README.md +4 -0 Viewed

@@ -13,6 +13,7 @@ Cette documentation suit [Diátaxis](https://diataxis.fr) : quatre sortes de pag
13	13	- [Ajouter un langage](how-to/add-a-language.md) — écrire un analyseur et l'enregistrer.
14	14	- [Dialoguer avec un serveur de langage](how-to/talk-to-a-language-server.md) — brancher l'éditeur sur gopls, rust-analyzer, ou tout autre serveur LSP.
15	15	- [Écrire les fichiers de départ](how-to/write-the-starter-files.md) — les modèles de réglages, d'extraits et d'outils que votre éditeur propose de créer.
	16	+- [Ajouter l'édition à distance](how-to/add-remote-editing.md) — donner à un éditeur `-ssh user@machine[:dir]`, pour éditer les fichiers d'une autre machine.
16	17	- [Lancer les tests](how-to/run-the-tests.md) — la commande unique, et ce qu'elle couvre.
17	18	- [Tester sans publier](how-to/test-without-publishing.md) — faire tourner les éditeurs sur un turbo-core modifié seulement en local.
18	19	- [Publier la bibliothèque](how-to/release-the-library.md) — poser une version dont les éditeurs peuvent dépendre.
@@ -23,11 +24,14 @@ Cette documentation suit [Diátaxis](https://diataxis.fr) : quatre sortes de pag
23	24	- [Paquets](reference/packages.md) — ce que contient chaque paquet, et ce dont il a le droit de dépendre.
24	25	- [Le point d'extension syntaxique](reference/syntax.md) — `Definition`, `Register`, `LineScanner`, `LineIndex`.
25	26	- [L'API app](reference/app.md) — ce qu'une commande peut appeler sur un éditeur en marche.
	27	+- [fsys](reference/fsys.md) — la porte unique vers les fichiers du projet.
	28	+- [remote](reference/remote.md) — une autre machine via la commande `ssh`.
26	29
27	30	## [Explications](explanation/) — pourquoi c'est ainsi
28	31
29	32	- [Architecture](explanation/architecture.md) — la forme de la bibliothèque, et la règle qui la maintient.
30	33	- [Ce qui appartient ici](explanation/what-belongs-here.md) — la frontière entre la bibliothèque et un éditeur bâti dessus, et comment elle a été tracée.
	34	+- [L'édition à distance](explanation/remote-editing.md) — pourquoi `-ssh` pilote la commande ssh, partage une seule connexion, et fait passer les fichiers en SFTP.
31	35
32	36	## Où sont les éditeurs
33	37

  - [Ajouter un langage](how-to/add-a-language.md) — écrire un analyseur et l'enregistrer.
  - [Dialoguer avec un serveur de langage](how-to/talk-to-a-language-server.md) — brancher l'éditeur sur gopls, rust-analyzer, ou tout autre serveur LSP.
  - [Écrire les fichiers de départ](how-to/write-the-starter-files.md) — les modèles de réglages, d'extraits et d'outils que votre éditeur propose de créer.
++- [Ajouter l'édition à distance](how-to/add-remote-editing.md) — donner à un éditeur `-ssh user@machine[:dir]`, pour éditer les fichiers d'une autre machine.
  - [Lancer les tests](how-to/run-the-tests.md) — la commande unique, et ce qu'elle couvre.
  - [Tester sans publier](how-to/test-without-publishing.md) — faire tourner les éditeurs sur un turbo-core modifié seulement en local.
  - [Publier la bibliothèque](how-to/release-the-library.md) — poser une version dont les éditeurs peuvent dépendre.
  - [Paquets](reference/packages.md) — ce que contient chaque paquet, et ce dont il a le droit de dépendre.
  - [Le point d'extension syntaxique](reference/syntax.md) — `Definition`, `Register`, `LineScanner`, `LineIndex`.
  - [L'API app](reference/app.md) — ce qu'une commande peut appeler sur un éditeur en marche.
++- [fsys](reference/fsys.md) — la porte unique vers les fichiers du projet.
++- [remote](reference/remote.md) — une autre machine via la commande `ssh`.
  ## [Explications](explanation/) — pourquoi c'est ainsi
  - [Architecture](explanation/architecture.md) — la forme de la bibliothèque, et la règle qui la maintient.
  - [Ce qui appartient ici](explanation/what-belongs-here.md) — la frontière entre la bibliothèque et un éditeur bâti dessus, et comment elle a été tracée.
++- [L'édition à distance](explanation/remote-editing.md) — pourquoi `-ssh` pilote la commande ssh, partage une seule connexion, et fait passer les fichiers en SFTP.
  ## Où sont les éditeurs

modified docs/fr/explanation/architecture.md +6 -1 Viewed

@@ -2,7 +2,7 @@
2	2
3	3	## De quoi s'agit-il ?
4	4
5		-turbo-core est un IDE de terminal avec un trou à l'endroit du langage. Dix-huit paquets mettent en œuvre tout ce que fait un éditeur — texte, annulation, fenêtres, menus, dialogues, thèmes, un émulateur VT, une arborescence de fichiers, un client LSP, un agent de code — et aucun d'eux ne sait quel langage est édité. Un éditeur bâti dessus, c'est une commande, un `profile.Profile`, et un analyseur.
	5	+turbo-core est un IDE de terminal avec un trou à l'endroit du langage. Vingt et un paquets mettent en œuvre tout ce que fait un éditeur — texte, annulation, fenêtres, menus, dialogues, thèmes, un émulateur VT, une arborescence de fichiers, un client LSP, un agent de code, l'édition via ssh — et aucun d'eux ne sait quel langage est édité. Un éditeur bâti dessus, c'est une commande, un `profile.Profile`, et un analyseur.
6	6
7	7	La bibliothèque n'a pas été conçue ainsi. Elle a été extraite de Turbo Go, qui avait été un unique programme de 35 000 lignes pendant quinze jours, au moment où l'on a voulu un second éditeur. La quasi-totalité a bougé sans changement ; la couture est là où il s'est avéré qu'elle devait être, pas là où quelqu'un l'avait prédit.
8	8
@@ -44,6 +44,10 @@ Ce n'est pas sûr depuis deux goroutines à la fois, et il n'y a aucune raison q
44	44
45	45	Cela a l'air incohérent et c'est délibéré. Un paquet qui recevrait un profil dont il n'utilise qu'un champ serait un paquet qui dépend de toute l'identité de l'éditeur pour répondre à une question sur un répertoire.
46	46
	47	+## Pourquoi les fichiers du projet ont une seule porte
	48	+
	49	+Toute lecture et écriture d'un fichier du projet — le source, l'arborescence, le dialogue Ouvrir, les fichiers TOML du projet — passe par `fsys`, et rien d'autre dans la bibliothèque ne touche ces fichiers avec le paquet `os`. C'est ce qui permet à un éditeur lancé avec `-ssh` de remplacer le disque local par une autre machine en un seul appel, `fsys.Use`, avant toute lecture. C'est un état de paquet pour les mêmes raisons que le registre syntaxique ; l'argument complet, et ce qui a été laissé exprès sur le disque local, sont dans [l'édition à distance](remote-editing.md).
	50	+
47	51	## Comment cela se relie au reste
48	52
49	53	Les éditeurs bâtis dessus sont la preuve que la couture est réelle. Les paquets propres à Turbo Go sont passés de quatorze à un ; Turbo Rust a été bâti sur la bibliothèque sans la modifier, et les quatre défauts apparus pendant sa construction étaient tous dans son propre analyseur plutôt que dans la bibliothèque — ce qui est le résultat pour lequel l'extraction a été faite. Turbo Python, le troisième, a été bâti sur un tag publié sans la moindre modification de la bibliothèque.
@@ -52,6 +56,7 @@ Les éditeurs bâtis dessus sont la preuve que la couture est réelle. Les paque
52	56
53	57	- Ce que contient chaque paquet : [référence des paquets](../reference/packages.md)
54	58	- Où tombe la frontière : [ce qui appartient ici](what-belongs-here.md)
	59	+- Éditer les fichiers d'une autre machine : [l'édition à distance](remote-editing.md)
55	60
56	61	## Pourquoi jsonrpc a été extrait de lsp
57	62

  ## De quoi s'agit-il ?
--turbo-core est un IDE de terminal avec un trou à l'endroit du langage. Dix-huit paquets mettent en œuvre tout ce que fait un éditeur — texte, annulation, fenêtres, menus, dialogues, thèmes, un émulateur VT, une arborescence de fichiers, un client LSP, un agent de code — et aucun d'eux ne sait quel langage est édité. Un éditeur bâti dessus, c'est une commande, un `profile.Profile`, et un analyseur.
++turbo-core est un IDE de terminal avec un trou à l'endroit du langage. Vingt et un paquets mettent en œuvre tout ce que fait un éditeur — texte, annulation, fenêtres, menus, dialogues, thèmes, un émulateur VT, une arborescence de fichiers, un client LSP, un agent de code, l'édition via ssh — et aucun d'eux ne sait quel langage est édité. Un éditeur bâti dessus, c'est une commande, un `profile.Profile`, et un analyseur.
  La bibliothèque n'a pas été conçue ainsi. Elle a été extraite de Turbo Go, qui avait été un unique programme de 35 000 lignes pendant quinze jours, au moment où l'on a voulu un second éditeur. La quasi-totalité a bougé sans changement ; la couture est là où il s'est avéré qu'elle devait être, pas là où quelqu'un l'avait prédit.
  Cela a l'air incohérent et c'est délibéré. Un paquet qui recevrait un profil dont il n'utilise qu'un champ serait un paquet qui dépend de toute l'identité de l'éditeur pour répondre à une question sur un répertoire.
++## Pourquoi les fichiers du projet ont une seule porte
++
++Toute lecture et écriture d'un fichier *du projet* — le source, l'arborescence, le dialogue Ouvrir, les fichiers TOML du projet — passe par `fsys`, et rien d'autre dans la bibliothèque ne touche ces fichiers avec le paquet `os`. C'est ce qui permet à un éditeur lancé avec `-ssh` de remplacer le disque local par une autre machine en un seul appel, `fsys.Use`, avant toute lecture. C'est un état de paquet pour les mêmes raisons que le registre syntaxique ; l'argument complet, et ce qui a été laissé exprès sur le disque local, sont dans [l'édition à distance](remote-editing.md).
++
  ## Comment cela se relie au reste
  Les éditeurs bâtis dessus sont la preuve que la couture est réelle. Les paquets propres à Turbo Go sont passés de quatorze à un ; Turbo Rust a été bâti sur la bibliothèque sans la modifier, et les quatre défauts apparus pendant sa construction étaient tous dans son propre analyseur plutôt que dans la bibliothèque — ce qui est le résultat pour lequel l'extraction a été faite. Turbo Python, le troisième, a été bâti sur un tag publié sans la moindre modification de la bibliothèque.
  - Ce que contient chaque paquet : [référence des paquets](../reference/packages.md)
  - Où tombe la frontière : [ce qui appartient ici](what-belongs-here.md)
++- Éditer les fichiers d'une autre machine : [l'édition à distance](remote-editing.md)
  ## Pourquoi jsonrpc a été extrait de lsp

added docs/fr/explanation/remote-editing.md +62 -0 Viewed

new file mode 100644
@@ -0,0 +1,62 @@
	1	+# L'édition à distance — explication
	2	+
	3	+## De quoi s'agit-il ?
	4	+
	5	+`turbo-python -ssh bob@machine:/srv/app` édite les fichiers d'une autre machine comme s'ils étaient locaux : les fenêtres, l'arborescence du projet, le dialogue Ouvrir et les fichiers de réglages, d'extraits et d'outils du projet sont ceux de la machine distante ; une fenêtre terminal est un shell là-bas ; un outil s'exécute là-bas. Chaque éditeur l'obtient de turbo-core de la même façon — deux paquets, `fsys` et `remote`, et un appel, `app.UseRemote`.
	6	+
	7	+Cette page explique pourquoi c'est construit ainsi : pourquoi l'éditeur pilote la commande `ssh` au lieu de parler SSH lui-même, pourquoi les fichiers voyagent en SFTP, pourquoi le système de fichiers est un état de paquet, et ce qui a été laissé exprès sur la machine locale.
	8	+
	9	+## Une seule porte pour les fichiers
	10	+
	11	+Avant cette fonctionnalité, une cinquantaine d'endroits de turbo-core appelaient directement `os.ReadFile`, `os.Stat`, `os.Getwd` et leurs cousins. L'édition à distance exigeait que tous ceux qui concernent le projet aillent ailleurs, et qu'aucun de ceux qui concernent la personne ne bouge.
	12	+
	13	+Les fichiers du projet ont donc désormais une seule porte, `fsys`, et c'est un état de paquet fixé une fois au démarrage. C'est la même forme — et le même argument — que `syntax.Register` (voir [l'architecture](architecture.md)) : le choix se fait une fois par processus, avant toute lecture ; rien ne le change ensuite ; et l'alternative, faire circuler une valeur « système de fichiers » à travers `buffer`, `filetree`, `settings`, `snippets`, `tools`, `projectfile` et chaque appel de `app`, aurait changé la signature de la moitié de la bibliothèque pour une décision que personne ne prend deux fois. Le coût est celui de tout état global : un test qui le change doit le remettre, et aucun des paquets qui l'utilisent ne peut lancer en parallèle des tests qui le changent. Aucun ne le faisait.
	14	+
	15	+La frontière entre « le projet » et « la personne » passe là où elle passait déjà. Les thèmes de l'utilisateur et ses extraits personnels sont des habitudes, qui suivent la personne sur la machine qu'elle édite. L'exécutable d'un serveur de langage et un agent de code sont des programmes de cette machine-ci. `-load-config` copie dans le répertoire de travail local, là où on le tape.
	16	+
	17	+## Pourquoi la commande ssh, et pas une bibliothèque SSH
	18	+
	19	+Go a un bon client SSH, `golang.org/x/crypto/ssh`. Il a été écarté, pour la même raison que `configrepo` lance `git` au lieu de parler le HTTP intelligent : la commande installée sait déjà tout ce que la personne a configuré, et une bibliothèque n'en sait rien.
	20	+
	21	+La commande ssh lit `~/.ssh/config` — alias `Host`, ports, `User`, `IdentityFile`, `ProxyJump` via un bastion — et utilise l'agent, `known_hosts`, la passphrase d'une clé, un mot de passe, une clé matérielle. Une bibliothèque aurait dû réimplémenter chacun de ces points, un par un, et le dangereux en premier : accepter une clé d'hôte que la personne n'a jamais vue est une question dont la réponse relève de la sécurité, et OpenSSH la pose déjà correctement.
	22	+
	23	+Le coût, c'est que l'éditeur lance des processus au lieu d'appeler des fonctions. C'est pour ça que `ControlMaster` compte.
	24	+
	25	+## Pourquoi ControlMaster
	26	+
	27	+Sans lui, chaque commande ssh est une nouvelle connexion : poignée de main TCP, échange de clés, authentification — et, avec un mot de passe, une question, à chaque fois. Or l'éditeur ouvre un shell ici, lance un outil là, et fait un `stat` de chaque fichier ouvert toutes les secondes.
	28	+
	29	+`ControlMaster` fait de la première connexion le maître et laisse une socket Unix derrière elle ; chaque `ssh -S <socket>` suivant passe par cette connexion déjà authentifiée en quelques millisecondes, sans rien demander. L'éditeur se connecte donc une fois, au premier plan, avant de prendre l'écran — le seul moment où ssh peut poser une question sur le terminal — puis passe `BatchMode=yes` à tout ce qui suit, pour qu'un maître perdu échoue bruyamment au lieu d'afficher une demande de mot de passe par-dessus l'éditeur.
	30	+
	31	+`ControlPersist=60` garde le maître en vie une minute après son dernier utilisateur. L'éditeur tient le canal SFTP ouvert jusqu'à sa fermeture, donc cette minute ne compte qu'après un plantage : la connexion s'en va alors d'elle-même.
	32	+
	33	+Le coût, c'est Windows : son portage d'OpenSSH n'a pas de ControlMaster, et `Connect` y renvoie `ErrUnsupported`.
	34	+
	35	+## Pourquoi SFTP pour les fichiers, et pas des commandes shell
	36	+
	37	+Une fois la connexion partagée établie, la façon la moins chère en apparence de lire un fichier est `ssh … cat fichier`, et de lister un répertoire `ssh … ls`. Elle a été écartée pour deux raisons.
	38	+
	39	+La sortie de `ls` et de `stat` n'est pas portable — GNU et BSD divergent sur les options et les formats — et un surveillant de fichiers qui l'analyse casse au premier serveur macOS. Et un processus par opération, c'est un processus par fichier ouvert et par seconde rien que pour le surveillant.
	40	+
	41	+SFTP est le protocole qu'OpenSSH fournit précisément pour cela, sur un canal de la même connexion (`ssh -s … sftp`) : binaire, portable, et une requête par opération. Le client est `github.com/pkg/sftp`, la seule vraie dépendance ajoutée par la fonctionnalité. Écrire à la main la douzaine de messages SFTP dont l'éditeur a besoin a été envisagé et écarté : du code de protocole à maintenir, sans rien gagner.
	42	+
	43	+L'enregistrement atomique survit au voyage : le nouveau contenu est écrit dans un fichier temporaire à côté de la cible, puis renommé par-dessus avec `posix-rename@openssh.com`, qui remplace la cible en une étape, comme `rename(2)` en local.
	44	+
	45	+## Pourquoi toute commande distante est `/bin/sh -c '…'`
	46	+
	47	+ssh confie la commande qu'on lui donne au shell de connexion de l'utilisateur, qui peut être fish, ou tout autre shell qui ne lit pas `cd dir && exec …` comme sh. Toute commande envoyée est donc `exec /bin/sh -c '<script>'`, citée une fois pour le shell de connexion : la ligne de commande d'un outil signifie là-bas ce qu'elle signifie ici — `/bin/sh -c`, tubes et `&&` compris — et un terminal lance le shell de l'utilisateur avec `exec "${SHELL:-/bin/sh}" -l` depuis sh.
	48	+
	49	+## Ce qui est désactivé, et pourquoi
	50	+
	51	+- Le serveur de langage. Les serveurs qu'un éditeur sait trouver sont sur cette machine ; les fichiers sur lesquels on les interrogerait n'y sont pas. Lancer pylsp à distance sur la même connexion est possible, mais il faudrait alors traduire les chemins de ses réponses, et que le serveur soit installé là-bas. C'est laissé pour plus tard plutôt que fait à moitié.
	52	+- Les fenêtres d'agent. Un agent est un programme de cette machine, qui lit et écrit les fichiers de cette machine. Un agent qui tournerait pendant que l'éditeur montre le projet distant éditerait un autre projet que celui à l'écran. Le menu Agent le dit au lieu de le proposer.
	53	+
	54	+## Alternatives écartées
	55	+
	56	+- Monter avec sshfs. Il faut macFUSE sous macOS, une extension du noyau que la personne doit installer et approuver, et les terminaux et outils restent locaux.
	57	+- Copier l'éditeur sur la machine et l'y lancer. Le binaire est construit pour la machine de la personne — `darwin/arm64` — et le serveur est le plus souvent en `linux/amd64` ; et l'éditeur perdrait le presse-papiers local et les thèmes de la personne.
	58	+- Une interface passée à travers chaque paquet au lieu de `fsys.Use`. Voir « Une seule porte pour les fichiers » ci-dessus.
	59	+
	60	+## Comment cela se relie au reste
	61	+
	62	+`fsys` se trouve sous tout ce qui touche un fichier du projet, sans dépendance à lui. `remote` ne l'importe même pas — son `FS` a les bonnes méthodes, c'est tout ce que demande une interface Go. Il se trouve à côté de `configrepo`, puisque tous deux pilotent une commande installée, et `app` ne le connaît qu'à travers l'interface `app.Remote` à trois méthodes, si bien que ses tests utilisent une doublure qui lance `/bin/sh` en local. Chaque éditeur ajoute le flag dans son `main.go` ; la référence est [remote](../reference/remote.md), et la recette [ajouter l'édition à distance](../how-to/add-remote-editing.md).

++# L'édition à distance — explication
++
++## De quoi s'agit-il ?
++
++`turbo-python -ssh bob@machine:/srv/app` édite les fichiers d'une autre machine comme s'ils étaient locaux : les fenêtres, l'arborescence du projet, le dialogue Ouvrir et les fichiers de réglages, d'extraits et d'outils du projet sont ceux de la machine distante ; une fenêtre terminal est un shell là-bas ; un outil s'exécute là-bas. Chaque éditeur l'obtient de turbo-core de la même façon — deux paquets, `fsys` et `remote`, et un appel, `app.UseRemote`.
++
++Cette page explique pourquoi c'est construit ainsi : pourquoi l'éditeur pilote la commande `ssh` au lieu de parler SSH lui-même, pourquoi les fichiers voyagent en SFTP, pourquoi le système de fichiers est un état de paquet, et ce qui a été laissé exprès sur la machine locale.
++
++## Une seule porte pour les fichiers
++
++Avant cette fonctionnalité, une cinquantaine d'endroits de turbo-core appelaient directement `os.ReadFile`, `os.Stat`, `os.Getwd` et leurs cousins. L'édition à distance exigeait que tous ceux qui concernent *le projet* aillent ailleurs, et qu'aucun de ceux qui concernent *la personne* ne bouge.
++
++Les fichiers du projet ont donc désormais une seule porte, `fsys`, et c'est un état de paquet fixé une fois au démarrage. C'est la même forme — et le même argument — que `syntax.Register` (voir [l'architecture](architecture.md)) : le choix se fait une fois par processus, avant toute lecture ; rien ne le change ensuite ; et l'alternative, faire circuler une valeur « système de fichiers » à travers `buffer`, `filetree`, `settings`, `snippets`, `tools`, `projectfile` et chaque appel de `app`, aurait changé la signature de la moitié de la bibliothèque pour une décision que personne ne prend deux fois. Le coût est celui de tout état global : un test qui le change doit le remettre, et aucun des paquets qui l'utilisent ne peut lancer en parallèle des tests qui le changent. Aucun ne le faisait.
++
++La frontière entre « le projet » et « la personne » passe là où elle passait déjà. Les thèmes de l'utilisateur et ses extraits personnels sont des habitudes, qui suivent la personne sur la machine qu'elle édite. L'exécutable d'un serveur de langage et un agent de code sont des programmes de cette machine-ci. `-load-config` copie dans le répertoire de travail local, là où on le tape.
++
++## Pourquoi la commande ssh, et pas une bibliothèque SSH
++
++Go a un bon client SSH, `golang.org/x/crypto/ssh`. Il a été écarté, pour la même raison que `configrepo` lance `git` au lieu de parler le HTTP intelligent : la commande installée sait déjà tout ce que la personne a configuré, et une bibliothèque n'en sait rien.
++
++La commande ssh lit `~/.ssh/config` — alias `Host`, ports, `User`, `IdentityFile`, `ProxyJump` via un bastion — et utilise l'agent, `known_hosts`, la passphrase d'une clé, un mot de passe, une clé matérielle. Une bibliothèque aurait dû réimplémenter chacun de ces points, un par un, et le dangereux en premier : accepter une clé d'hôte que la personne n'a jamais vue est une question dont la réponse relève de la sécurité, et OpenSSH la pose déjà correctement.
++
++Le coût, c'est que l'éditeur lance des processus au lieu d'appeler des fonctions. C'est pour ça que `ControlMaster` compte.
++
++## Pourquoi ControlMaster
++
++Sans lui, chaque commande ssh est une nouvelle connexion : poignée de main TCP, échange de clés, authentification — et, avec un mot de passe, une question, à chaque fois. Or l'éditeur ouvre un shell ici, lance un outil là, et fait un `stat` de chaque fichier ouvert toutes les secondes.
++
++`ControlMaster` fait de la première connexion le maître et laisse une socket Unix derrière elle ; chaque `ssh -S <socket>` suivant passe par cette connexion déjà authentifiée en quelques millisecondes, sans rien demander. L'éditeur se connecte donc une fois, au premier plan, **avant de prendre l'écran** — le seul moment où ssh peut poser une question sur le terminal — puis passe `BatchMode=yes` à tout ce qui suit, pour qu'un maître perdu échoue bruyamment au lieu d'afficher une demande de mot de passe par-dessus l'éditeur.
++
++`ControlPersist=60` garde le maître en vie une minute après son dernier utilisateur. L'éditeur tient le canal SFTP ouvert jusqu'à sa fermeture, donc cette minute ne compte qu'après un plantage : la connexion s'en va alors d'elle-même.
++
++Le coût, c'est Windows : son portage d'OpenSSH n'a pas de ControlMaster, et `Connect` y renvoie `ErrUnsupported`.
++
++## Pourquoi SFTP pour les fichiers, et pas des commandes shell
++
++Une fois la connexion partagée établie, la façon la moins chère en apparence de lire un fichier est `ssh … cat fichier`, et de lister un répertoire `ssh … ls`. Elle a été écartée pour deux raisons.
++
++La sortie de `ls` et de `stat` n'est pas portable — GNU et BSD divergent sur les options et les formats — et un surveillant de fichiers qui l'analyse casse au premier serveur macOS. Et un processus par opération, c'est un processus par fichier ouvert et par seconde rien que pour le surveillant.
++
++SFTP est le protocole qu'OpenSSH fournit précisément pour cela, sur un canal de la même connexion (`ssh -s … sftp`) : binaire, portable, et une requête par opération. Le client est `github.com/pkg/sftp`, la seule vraie dépendance ajoutée par la fonctionnalité. Écrire à la main la douzaine de messages SFTP dont l'éditeur a besoin a été envisagé et écarté : du code de protocole à maintenir, sans rien gagner.
++
++L'enregistrement atomique survit au voyage : le nouveau contenu est écrit dans un fichier temporaire à côté de la cible, puis renommé par-dessus avec `posix-rename@openssh.com`, qui remplace la cible en une étape, comme `rename(2)` en local.
++
++## Pourquoi toute commande distante est `/bin/sh -c '…'`
++
++ssh confie la commande qu'on lui donne au shell *de connexion* de l'utilisateur, qui peut être fish, ou tout autre shell qui ne lit pas `cd dir && exec …` comme sh. Toute commande envoyée est donc `exec /bin/sh -c '<script>'`, citée une fois pour le shell de connexion : la ligne de commande d'un outil signifie là-bas ce qu'elle signifie ici — `/bin/sh -c`, tubes et `&&` compris — et un terminal lance le shell de l'utilisateur avec `exec "${SHELL:-/bin/sh}" -l` depuis sh.
++
++## Ce qui est désactivé, et pourquoi
++
++- **Le serveur de langage.** Les serveurs qu'un éditeur sait trouver sont sur cette machine ; les fichiers sur lesquels on les interrogerait n'y sont pas. Lancer pylsp à distance sur la même connexion est possible, mais il faudrait alors traduire les chemins de ses réponses, et que le serveur soit installé là-bas. C'est laissé pour plus tard plutôt que fait à moitié.
++- **Les fenêtres d'agent.** Un agent est un programme de cette machine, qui lit et écrit les fichiers de cette machine. Un agent qui tournerait pendant que l'éditeur montre le projet distant éditerait un autre projet que celui à l'écran. Le menu Agent le dit au lieu de le proposer.
++
++## Alternatives écartées
++
++- **Monter avec sshfs.** Il faut macFUSE sous macOS, une extension du noyau que la personne doit installer et approuver, et les terminaux et outils restent locaux.
++- **Copier l'éditeur sur la machine et l'y lancer.** Le binaire est construit pour la machine de la personne — `darwin/arm64` — et le serveur est le plus souvent en `linux/amd64` ; et l'éditeur perdrait le presse-papiers local et les thèmes de la personne.
++- **Une interface passée à travers chaque paquet** au lieu de `fsys.Use`. Voir « Une seule porte pour les fichiers » ci-dessus.
++
++## Comment cela se relie au reste
++
++`fsys` se trouve sous tout ce qui touche un fichier du projet, sans dépendance à lui. `remote` ne l'importe même pas — son `FS` a les bonnes méthodes, c'est tout ce que demande une interface Go. Il se trouve à côté de `configrepo`, puisque tous deux pilotent une commande installée, et `app` ne le connaît qu'à travers l'interface `app.Remote` à trois méthodes, si bien que ses tests utilisent une doublure qui lance `/bin/sh` en local. Chaque éditeur ajoute le flag dans son `main.go` ; la référence est [remote](../reference/remote.md), et la recette [ajouter l'édition à distance](../how-to/add-remote-editing.md).

added docs/fr/how-to/add-remote-editing.md +82 -0 Viewed

new file mode 100644
@@ -0,0 +1,82 @@
	1	+# Comment ajouter l'édition à distance à un éditeur
	2	+
	3	+Ce guide donne à un éditeur bâti sur turbo-core un flag `-ssh user@machine[:répertoire]`, pour qu'il édite les fichiers d'une autre machine et y lance ses terminaux et ses outils. Il suppose que votre `main.go` a la forme de celui de [construire un éditeur](../tutorials/build-an-editor.md) : flags, `loadProjectSettings`, `newScreen`, `app.New`, `StartLanguageServer`, `Run`.
	4	+
	5	+## Étapes
	6	+
	7	+1. Importez les deux paquets :
	8	+
	9	+ ```go
	10	+ "rickub.com/turbo-editors/turbo-core/fsys"
	11	+ "rickub.com/turbo-editors/turbo-core/remote"
	12	+ ```
	13	+
	14	+2. Ajoutez le flag. Le paquet `flag` de Go accepte indifféremment `-ssh` et `--ssh` :
	15	+
	16	+ ```go
	17	+ flag.StringVar(&opts.ssh, "ssh", "", "edit the files of another machine over ssh: user@machine[:directory]")
	18	+ ```
	19	+
	20	+3. Ajoutez la fonction qui se connecte et fait passer toute lecture de fichier sur la machine :
	21	+
	22	+ ```go
	23	+ func connectRemote(target string) (*remote.Session, error) {
	24	+ if target == "" {
	25	+ return nil, nil
	26	+ }
	27	+ session, err := remote.Open(context.Background(), target)
	28	+ if err != nil {
	29	+ return nil, err
	30	+ }
	31	+ fsys.Use(session.FS())
	32	+ return session, nil
	33	+ }
	34	+ ```
	35	+
	36	+4. Appelez-la en premier dans `edit`, avant `newScreen` — ssh peut avoir besoin du terminal pour demander un mot de passe — et fermez-la en sortant :
	37	+
	38	+ ```go
	39	+ session, err := connectRemote(opts.ssh)
	40	+ if err != nil {
	41	+ return err
	42	+ }
	43	+ if session != nil {
	44	+ defer session.Close()
	45	+ }
	46	+ ```
	47	+
	48	+5. Lisez le répertoire du projet via `fsys`, pour que ce soit celui de la machine distante :
	49	+
	50	+ ```go
	51	+ project, err := fsys.Getwd() // au lieu de os.Getwd()
	52	+ ```
	53	+
	54	+6. Prévenez l'éditeur, et ne démarrez pas de serveur de langage local pour des fichiers distants :
	55	+
	56	+ ```go
	57	+ editor := app.New(screen, themeName, p)
	58	+ if session != nil {
	59	+ editor.UseRemote(session)
	60	+ }
	61	+ // …
	62	+ if !opts.noLSP && session == nil {
	63	+ editor.StartLanguageServer(ctx, app.ProjectRoot(p, opts.files))
	64	+ }
	65	+ ```
	66	+
	67	+7. Compilez, puis essayez contre la machine de démo de `turbo-editors/demo-remote-machine` (son README explique comment la démarrer) :
	68	+
	69	+ ```bash
	70	+ go build -o bin/turbo-x . && ./bin/turbo-x -ssh turbo-demo:workspace/hello-python
	71	+ ```
	72	+
	73	+## Variantes
	74	+
	75	+- Tester le flag sans machine. Découpez `parseFlags` en une fonction qui reçoit un `*flag.FlagSet` et les arguments, et donnez-lui `flag.NewFlagSet(nom, flag.ContinueOnError)` dans un test. Une cible invalide comme `-oProxyCommand=x` est refusée par `connectRemote` avant que quoi que ce soit ne s'exécute : on peut donc la tester sans ssh.
	76	+- Tester l'accès aux fichiers sans machine. `fsys.Use(fsystest.New("/remote/project"))` dans un test fait passer toutes les lectures et écritures en mémoire ; voir [fsys](../reference/fsys.md).
	77	+- Votre éditeur compile contre la bibliothèque publiée. `fsys` et `remote` sont arrivés après la v1.0.4 ; exigez la version qui les contient, ou utilisez un workspace — [tester sans publier](test-without-publishing.md).
	78	+
	79	+## Voir aussi
	80	+
	81	+- Toutes les fonctions utilisées ici : [remote](../reference/remote.md), [fsys](../reference/fsys.md), [l'API app](../reference/app.md)
	82	+- Ce qui change dans l'éditeur, et pourquoi : [l'édition à distance](../explanation/remote-editing.md)

++# Comment ajouter l'édition à distance à un éditeur
++
++Ce guide donne à un éditeur bâti sur turbo-core un flag `-ssh user@machine[:répertoire]`, pour qu'il édite les fichiers d'une autre machine et y lance ses terminaux et ses outils. Il suppose que votre `main.go` a la forme de celui de [construire un éditeur](../tutorials/build-an-editor.md) : flags, `loadProjectSettings`, `newScreen`, `app.New`, `StartLanguageServer`, `Run`.
++
++## Étapes
++
++1. Importez les deux paquets :
++
++   ```go
++   "rickub.com/turbo-editors/turbo-core/fsys"
++   "rickub.com/turbo-editors/turbo-core/remote"
++   ```
++
++2. Ajoutez le flag. Le paquet `flag` de Go accepte indifféremment `-ssh` et `--ssh` :
++
++   ```go
++   flag.StringVar(&opts.ssh, "ssh", "", "edit the files of another machine over ssh: user@machine[:directory]")
++   ```
++
++3. Ajoutez la fonction qui se connecte et fait passer toute lecture de fichier sur la machine :
++
++   ```go
++   func connectRemote(target string) (*remote.Session, error) {
++   	if target == "" {
++   		return nil, nil
++   	}
++   	session, err := remote.Open(context.Background(), target)
++   	if err != nil {
++   		return nil, err
++   	}
++   	fsys.Use(session.FS())
++   	return session, nil
++   }
++   ```
++
++4. Appelez-la en premier dans `edit`, **avant** `newScreen` — ssh peut avoir besoin du terminal pour demander un mot de passe — et fermez-la en sortant :
++
++   ```go
++   session, err := connectRemote(opts.ssh)
++   if err != nil {
++   	return err
++   }
++   if session != nil {
++   	defer session.Close()
++   }
++   ```
++
++5. Lisez le répertoire du projet via `fsys`, pour que ce soit celui de la machine distante :
++
++   ```go
++   project, err := fsys.Getwd() // au lieu de os.Getwd()
++   ```
++
++6. Prévenez l'éditeur, et ne démarrez pas de serveur de langage local pour des fichiers distants :
++
++   ```go
++   editor := app.New(screen, themeName, p)
++   if session != nil {
++   	editor.UseRemote(session)
++   }
++   // …
++   if !opts.noLSP && session == nil {
++   	editor.StartLanguageServer(ctx, app.ProjectRoot(p, opts.files))
++   }
++   ```
++
++7. Compilez, puis essayez contre la machine de démo de `turbo-editors/demo-remote-machine` (son README explique comment la démarrer) :
++
++   ```bash
++   go build -o bin/turbo-x . && ./bin/turbo-x -ssh turbo-demo:workspace/hello-python
++   ```
++
++## Variantes
++
++- **Tester le flag sans machine.** Découpez `parseFlags` en une fonction qui reçoit un `*flag.FlagSet` et les arguments, et donnez-lui `flag.NewFlagSet(nom, flag.ContinueOnError)` dans un test. Une cible invalide comme `-oProxyCommand=x` est refusée par `connectRemote` avant que quoi que ce soit ne s'exécute : on peut donc la tester sans ssh.
++- **Tester l'accès aux fichiers sans machine.** `fsys.Use(fsystest.New("/remote/project"))` dans un test fait passer toutes les lectures et écritures en mémoire ; voir [fsys](../reference/fsys.md).
++- **Votre éditeur compile contre la bibliothèque publiée.** `fsys` et `remote` sont arrivés après la v1.0.4 ; exigez la version qui les contient, ou utilisez un workspace — [tester sans publier](test-without-publishing.md).
++
++## Voir aussi
++
++- Toutes les fonctions utilisées ici : [remote](../reference/remote.md), [fsys](../reference/fsys.md), [l'API app](../reference/app.md)
++- Ce qui change dans l'éditeur, et pourquoi : [l'édition à distance](../explanation/remote-editing.md)

modified docs/fr/how-to/run-the-tests.md +11 -0 Viewed

@@ -57,6 +57,17 @@ make help
57	57
58	58	Utilisez `make race`, pas `make test`. Une course de données dans un constructeur qui démarre une goroutine s'est cachée ici pendant toute une fonctionnalité, parce qu'un shell met plus longtemps à produire une sortie qu'une affectation à s'exécuter.
59	59
	60	+### Vous avez modifié `remote`, et voulez un vrai sshd
	61	+
	62	+`go test ./remote/` n'a pas besoin du réseau : il fait tourner un vrai serveur SFTP à travers des tubes, et le binaire de test lui-même joue le rôle de ssh. Pour lancer le seul test qui parle à un vrai sshd, démarrez la machine de démo de `turbo-editors/demo-remote-machine` et donnez sa clé au test :
	63	+
	64	+```bash
	65	+(cd ../demo-remote-machine && ./make-key.sh && docker compose up -d --build)
	66	+TURBO_CORE_SSH_KEY=$PWD/../demo-remote-machine/keys/id_demo go test ./remote/ -run Real -v
	67	+```
	68	+
	69	+`TURBO_CORE_SSH_PORT` (par défaut `2222`) et `TURBO_CORE_SSH_TARGET` (par défaut `bob@127.0.0.1:workspace/hello-python`) le dirigent ailleurs. Sans `TURBO_CORE_SSH_KEY`, le test se saute lui-même.
	70	+
60	71	### Un test est passé dès que vous l'avez écrit
61	72
62	73	Cassez le code qu'il couvre et regardez-le échouer. Ce projet a plus d'un cas consigné de test qui passait parce qu'il ne testait rien — un rappel que personne n'avait branché, une étape que le test effectuait lui-même. Un nouveau test qui n'a jamais échoué n'a pas été testé.

  Utilisez `make race`, pas `make test`. Une course de données dans un constructeur qui démarre une goroutine s'est cachée ici pendant toute une fonctionnalité, parce qu'un shell met plus longtemps à produire une sortie qu'une affectation à s'exécuter.
++### Vous avez modifié `remote`, et voulez un vrai sshd
++
++`go test ./remote/` n'a pas besoin du réseau : il fait tourner un vrai serveur SFTP à travers des tubes, et le binaire de test lui-même joue le rôle de ssh. Pour lancer le seul test qui parle à un vrai sshd, démarrez la machine de démo de `turbo-editors/demo-remote-machine` et donnez sa clé au test :
++
++```bash
++(cd ../demo-remote-machine && ./make-key.sh && docker compose up -d --build)
++TURBO_CORE_SSH_KEY=$PWD/../demo-remote-machine/keys/id_demo go test ./remote/ -run Real -v
++```
++
++`TURBO_CORE_SSH_PORT` (par défaut `2222`) et `TURBO_CORE_SSH_TARGET` (par défaut `bob@127.0.0.1:workspace/hello-python`) le dirigent ailleurs. Sans `TURBO_CORE_SSH_KEY`, le test se saute lui-même.
++
  ### Un test est passé dès que vous l'avez écrit
  Cassez le code qu'il couvre et regardez-le échouer. Ce projet a plus d'un cas consigné de test qui passait parce qu'il ne testait rien — un rappel que personne n'avait branché, une étape que le test effectuait lui-même. Un nouveau test qui n'a jamais échoué n'a pas été testé.

modified docs/fr/reference/app.md +18 -0 Viewed

@@ -99,6 +99,23 @@ Sauvegarder maintient exact l'ensemble des documents que le serveur croit ouvert
99	99	\| `Message(text string)` \| Une note d'une ligne sur la barre d'état. \|
100	100	\| `ShowMessage(title, message string)` \| Une boîte modale. \|
101	101
	102	+## Une autre machine
	103	+
	104	+\| Méthode \| Description \|
	105	+\| --- \| --- \|
	106	+\| `UseRemote(r Remote)` \| Indique à l'éditeur que son projet est sur une autre machine. À appeler après `app.New`, `fsys` ayant déjà été basculé sur cette machine. Dès lors, les fenêtres terminal et les outils passent par `r`, la barre d'état commence par `⇄ <r.Name()>`, et les fenêtres d'agent sont refusées avec un message. \|
	107	+\| `Remote() Remote` \| La machine éditée, ou nil quand les fichiers sont locaux. \|
	108	+
	109	+`Remote` est une interface ; `*remote.Session` l'implémente.
	110	+
	111	+\| Méthode de `Remote` \| Sert à \|
	112	+\| --- \| --- \|
	113	+\| `Name() string` \| La barre d'état, et le titre d'une fenêtre terminal tant que le shell ne s'est pas nommé. \|
	114	+\| `ShellCommand(dir string) []string` \| L'argv de `New terminal` (F8) : un shell de connexion dans `dir`, le répertoire du fichier au premier plan ou du projet. Lancé depuis le répertoire de travail local de l'éditeur. \|
	115	+\| `RunCommand(dir, command string, withTerminal bool) []string` \| L'argv d'un outil : `withTerminal` vaut true pour `output = "terminal"`, false pour `popup` et `editor`, qui passent par `tools.StartProgram`. `dir` est le répertoire du projet. \|
	116	+
	117	+Ce que `UseRemote` ne fait pas : démarrer ou arrêter un serveur de langage (c'est la commande qui décide ; voir [ajouter l'édition à distance](../how-to/add-remote-editing.md)), ni changer l'endroit d'où sont lus les thèmes et les extraits de l'utilisateur.
	118	+
102	119	## Paramètres d'un outil
103	120
104	121	Une commande peut demander des valeurs avant de se lancer, en écrivant `{{libellé}}` à l'endroit où la valeur va. `app.RunTool` ouvre une boîte pour elles ; rien ici ne dessine quoi que ce soit.
@@ -131,3 +148,4 @@ Une commande peut demander des valeurs avant de se lancer, en écrivant `{{libel
131	148
132	149	- [Construire un éditeur](../tutorials/build-an-editor.md)
133	150	- [Référence profile](profile.md)
	151	+- [remote](remote.md), [fsys](fsys.md)

  | `Message(text string)` | Une note d'une ligne sur la barre d'état. |
  | `ShowMessage(title, message string)` | Une boîte modale. |
++## Une autre machine
++
++| Méthode | Description |
++| --- | --- |
++| `UseRemote(r Remote)` | Indique à l'éditeur que son projet est sur une autre machine. À appeler après `app.New`, `fsys` ayant déjà été basculé sur cette machine. Dès lors, les fenêtres terminal et les outils passent par `r`, la barre d'état commence par `⇄ <r.Name()>`, et les fenêtres d'agent sont refusées avec un message. |
++| `Remote() Remote` | La machine éditée, ou nil quand les fichiers sont locaux. |
++
++`Remote` est une interface ; `*remote.Session` l'implémente.
++
++| Méthode de `Remote` | Sert à |
++| --- | --- |
++| `Name() string` | La barre d'état, et le titre d'une fenêtre terminal tant que le shell ne s'est pas nommé. |
++| `ShellCommand(dir string) []string` | L'argv de `New terminal` (F8) : un shell de connexion dans `dir`, le répertoire du fichier au premier plan ou du projet. Lancé depuis le répertoire de travail local de l'éditeur. |
++| `RunCommand(dir, command string, withTerminal bool) []string` | L'argv d'un outil : `withTerminal` vaut true pour `output = "terminal"`, false pour `popup` et `editor`, qui passent par `tools.StartProgram`. `dir` est le répertoire du projet. |
++
++Ce que `UseRemote` ne fait pas : démarrer ou arrêter un serveur de langage (c'est la commande qui décide ; voir [ajouter l'édition à distance](../how-to/add-remote-editing.md)), ni changer l'endroit d'où sont lus les thèmes et les extraits de l'utilisateur.
++
  ## Paramètres d'un outil
  Une commande peut demander des valeurs avant de se lancer, en écrivant `{{libellé}}` à l'endroit où la valeur va. `app.RunTool` ouvre une boîte pour elles ; rien ici ne dessine quoi que ce soit.
  - [Construire un éditeur](../tutorials/build-an-editor.md)
  - [Référence profile](profile.md)
++- [remote](remote.md), [fsys](fsys.md)

added docs/fr/reference/fsys.md +84 -0 Viewed

new file mode 100644
@@ -0,0 +1,84 @@
	1	+# Référence : fsys
	2	+
	3	+> Description neutre du paquet `fsys`, la porte unique par laquelle l'éditeur atteint les fichiers du projet qu'il édite, et de `fsys/fsystest`, sa doublure en mémoire pour les tests.
	4	+
	5	+Chemin d'import : `rickub.com/turbo-editors/turbo-core/fsys`. Ne dépend que de la bibliothèque standard.
	6	+
	7	+## Ce qui passe par lui
	8	+
	9	+\| Passe par `fsys` \| Reste sur le disque local (paquet `os`) \|
	10	+\| --- \| --- \|
	11	+\| Les fichiers source ouverts, rechargés et enregistrés (`buffer`) \| Les thèmes de l'utilisateur (`theme`) \|
	12	+\| L'arborescence du projet (`filetree`) \| Le fichier d'extraits personnel de l'utilisateur (`snippets.UserPath`) \|
	13	+\| Les dialogues Ouvrir et Enregistrer sous (`app`) \| L'exécutable du serveur de langage (`lsp`) \|
	14	+\| `.turbo-<slug>/settings.toml`, `snippets.toml`, `tools.toml` (`settings`, `snippets`, `tools`, `projectfile`) \| Le fichier des agents, et ce que les agents lisent et écrivent (`acp`) \|
	15	+\| Le répertoire de travail que l'éditeur considère comme le projet (`app`) \| Le clone et la copie de `-load-config` (`configrepo`) \|
	16	+\| Le `stat` que le surveillant de fichiers fait chaque seconde (`app`) \| \|
	17	+
	18	+## Interface `FS`
	19	+
	20	+```go
	21	+type FS interface {
	22	+ ReadFile(name string) ([]byte, error)
	23	+ WriteFileAtomic(name string, data []byte, perm fs.FileMode) error
	24	+ ReadDir(name string) ([]fs.DirEntry, error)
	25	+ Stat(name string) (fs.FileInfo, error)
	26	+ MkdirAll(name string, perm fs.FileMode) error
	27	+ Getwd() (string, error)
	28	+}
	29	+```
	30	+
	31	+\| Méthode \| Contrat \|
	32	+\| --- \| --- \|
	33	+\| `ReadFile` \| Tout le contenu d'un fichier. \|
	34	+\| `WriteFileAtomic` \| Remplace un fichier par `data` avec le mode `perm`, de sorte qu'un lecteur voie l'ancien contenu ou le nouveau, jamais la moitié. Le répertoire doit exister. \|
	35	+\| `ReadDir` \| Les entrées d'un répertoire, triées par nom. \|
	36	+\| `Stat` \| Décrit un fichier, en suivant les liens symboliques. \|
	37	+\| `MkdirAll` \| Crée un répertoire et tous les parents manquants. \|
	38	+\| `Getwd` \| Le répertoire absolu d'où partent les chemins relatifs. \|
	39	+
	40	+Toute erreur signifiant « ce fichier n'existe pas » vérifie `errors.Is(err, fs.ErrNotExist)`. Les chemins relatifs sont relatifs à `Getwd`.
	41	+
	42	+## Fonctions
	43	+
	44	+\| Fonction \| Description \|
	45	+\| --- \| --- \|
	46	+\| `Use(f FS) (previous FS)` \| Fait de `f` le système de fichiers par lequel passent tous les paquets ; renvoie celui qu'il remplace. Sûr depuis n'importe quelle goroutine ; prévu pour être appelé une fois, au démarrage, avant l'ouverture de tout fichier. \|
	47	+\| `Current() FS` \| Le système de fichiers en service. \|
	48	+\| `IsLocal() bool` \| Si le système de fichiers en service est `Local`. \|
	49	+\| `ReadFile`, `WriteFileAtomic`, `ReadDir`, `Stat`, `MkdirAll`, `Getwd` \| Les méthodes de `FS`, sur `Current()`. \|
	50	+\| `Abs(path string) (string, error)` \| `path` rendu absolu par rapport à `Getwd()`, et nettoyé. L'équivalent de `filepath.Abs` qui tient compte d'une machine distante. \|
	51	+
	52	+## Type `Local`
	53	+
	54	+`Local{}` est la valeur par défaut : le disque de la machine où tourne l'éditeur, via le paquet `os`. `WriteFileAtomic` écrit `.<nom>.<aléa>` à côté de la cible, lui donne `perm`, et le renomme par-dessus la cible ; le fichier temporaire est supprimé à chaque échec.
	55	+
	56	+## Paquet `fsystest`
	57	+
	58	+Chemin d'import : `rickub.com/turbo-editors/turbo-core/fsys/fsystest`. Pour les tests uniquement.
	59	+
	60	+\| Fonction / méthode \| Description \|
	61	+\| --- \| --- \|
	62	+\| `New(working string) *Memory` \| Un `FS` en mémoire, vide, dont le répertoire de travail existe, ainsi que tous les répertoires au-dessus. Sûr en accès concurrent. \|
	63	+\| `(*Memory) AddFile(name, content string)` \| Crée ou remplace un fichier avec le mode `0644`, en créant ses répertoires. \|
	64	+\| `(*Memory) File(name string) (string, bool)` \| Le contenu d'un fichier, et s'il existe. \|
	65	+\| `(*Memory) Mode(name string) fs.FileMode` \| Les permissions d'un fichier, `0` s'il est absent. \|
	66	+
	67	+Chaque écriture avance la date de modification du fichier d'une nanoseconde, pour qu'un surveillant qui compare les estampilles voie chaque changement.
	68	+
	69	+## Exemple
	70	+
	71	+```go
	72	+memory := fsystest.New("/remote/project")
	73	+memory.AddFile("/remote/project/hello.py", "print('hello')\n")
	74	+
	75	+previous := fsys.Use(memory)
	76	+defer fsys.Use(previous)
	77	+
	78	+data, _ := fsys.ReadFile("hello.py") // "print('hello')\n"
	79	+```
	80	+
	81	+## Voir aussi
	82	+
	83	+- L'implémentation SFTP de `FS` : [remote](remote.md)
	84	+- Pourquoi les fichiers ont une seule porte : [l'édition à distance](../explanation/remote-editing.md)

++# Référence : fsys
++
++> Description neutre du paquet `fsys`, la porte unique par laquelle l'éditeur atteint les fichiers du projet qu'il édite, et de `fsys/fsystest`, sa doublure en mémoire pour les tests.
++
++Chemin d'import : `rickub.com/turbo-editors/turbo-core/fsys`. Ne dépend que de la bibliothèque standard.
++
++## Ce qui passe par lui
++
++| Passe par `fsys` | Reste sur le disque local (paquet `os`) |
++| --- | --- |
++| Les fichiers source ouverts, rechargés et enregistrés (`buffer`) | Les thèmes de l'utilisateur (`theme`) |
++| L'arborescence du projet (`filetree`) | Le fichier d'extraits personnel de l'utilisateur (`snippets.UserPath`) |
++| Les dialogues Ouvrir et Enregistrer sous (`app`) | L'exécutable du serveur de langage (`lsp`) |
++| `.turbo-<slug>/settings.toml`, `snippets.toml`, `tools.toml` (`settings`, `snippets`, `tools`, `projectfile`) | Le fichier des agents, et ce que les agents lisent et écrivent (`acp`) |
++| Le répertoire de travail que l'éditeur considère comme le projet (`app`) | Le clone et la copie de `-load-config` (`configrepo`) |
++| Le `stat` que le surveillant de fichiers fait chaque seconde (`app`) | |
++
++## Interface `FS`
++
++```go
++type FS interface {
++	ReadFile(name string) ([]byte, error)
++	WriteFileAtomic(name string, data []byte, perm fs.FileMode) error
++	ReadDir(name string) ([]fs.DirEntry, error)
++	Stat(name string) (fs.FileInfo, error)
++	MkdirAll(name string, perm fs.FileMode) error
++	Getwd() (string, error)
++}
++```
++
++| Méthode | Contrat |
++| --- | --- |
++| `ReadFile` | Tout le contenu d'un fichier. |
++| `WriteFileAtomic` | Remplace un fichier par `data` avec le mode `perm`, de sorte qu'un lecteur voie l'ancien contenu ou le nouveau, jamais la moitié. Le répertoire doit exister. |
++| `ReadDir` | Les entrées d'un répertoire, triées par nom. |
++| `Stat` | Décrit un fichier, en suivant les liens symboliques. |
++| `MkdirAll` | Crée un répertoire et tous les parents manquants. |
++| `Getwd` | Le répertoire absolu d'où partent les chemins relatifs. |
++
++Toute erreur signifiant « ce fichier n'existe pas » vérifie `errors.Is(err, fs.ErrNotExist)`. Les chemins relatifs sont relatifs à `Getwd`.
++
++## Fonctions
++
++| Fonction | Description |
++| --- | --- |
++| `Use(f FS) (previous FS)` | Fait de `f` le système de fichiers par lequel passent tous les paquets ; renvoie celui qu'il remplace. Sûr depuis n'importe quelle goroutine ; prévu pour être appelé une fois, au démarrage, avant l'ouverture de tout fichier. |
++| `Current() FS` | Le système de fichiers en service. |
++| `IsLocal() bool` | Si le système de fichiers en service est `Local`. |
++| `ReadFile`, `WriteFileAtomic`, `ReadDir`, `Stat`, `MkdirAll`, `Getwd` | Les méthodes de `FS`, sur `Current()`. |
++| `Abs(path string) (string, error)` | `path` rendu absolu par rapport à `Getwd()`, et nettoyé. L'équivalent de `filepath.Abs` qui tient compte d'une machine distante. |
++
++## Type `Local`
++
++`Local{}` est la valeur par défaut : le disque de la machine où tourne l'éditeur, via le paquet `os`. `WriteFileAtomic` écrit `.<nom>.<aléa>` à côté de la cible, lui donne `perm`, et le renomme par-dessus la cible ; le fichier temporaire est supprimé à chaque échec.
++
++## Paquet `fsystest`
++
++Chemin d'import : `rickub.com/turbo-editors/turbo-core/fsys/fsystest`. Pour les tests uniquement.
++
++| Fonction / méthode | Description |
++| --- | --- |
++| `New(working string) *Memory` | Un `FS` en mémoire, vide, dont le répertoire de travail existe, ainsi que tous les répertoires au-dessus. Sûr en accès concurrent. |
++| `(*Memory) AddFile(name, content string)` | Crée ou remplace un fichier avec le mode `0644`, en créant ses répertoires. |
++| `(*Memory) File(name string) (string, bool)` | Le contenu d'un fichier, et s'il existe. |
++| `(*Memory) Mode(name string) fs.FileMode` | Les permissions d'un fichier, `0` s'il est absent. |
++
++Chaque écriture avance la date de modification du fichier d'une nanoseconde, pour qu'un surveillant qui compare les estampilles voie chaque changement.
++
++## Exemple
++
++```go
++memory := fsystest.New("/remote/project")
++memory.AddFile("/remote/project/hello.py", "print('hello')\n")
++
++previous := fsys.Use(memory)
++defer fsys.Use(previous)
++
++data, _ := fsys.ReadFile("hello.py") // "print('hello')\n"
++```
++
++## Voir aussi
++
++- L'implémentation SFTP de `FS` : [remote](remote.md)
++- Pourquoi les fichiers ont une seule porte : [l'édition à distance](../explanation/remote-editing.md)

modified docs/fr/reference/packages.md +23 -15 Viewed

@@ -2,16 +2,19 @@
2	2
3	3	> Description neutre et exhaustive de ce que contient turbo-core.
4	4
5		-Dix-neuf paquets. Les dépendances vont strictement vers le bas ; il n'y a ni cycle ni indirection par interface pour en empêcher un.
	5	+Vingt-deux paquets. Les dépendances vont strictement vers le bas ; il n'y a ni cycle ni indirection par interface pour en empêcher un.
6	6
7	7	```
8		-app → {editor, ui, lsp, buffer, terminal, filetree, settings, snippets, tools, syntax, theme, profile, version}
	8	+app → {editor, ui, lsp, buffer, terminal, filetree, settings, snippets, tools, syntax, theme, profile, version, fsys}
	9	+ remote → github.com/pkg/sftp ← lance la commande ssh ; implémente fsys.FS sans importer fsys
9	10	editor → {buffer, syntax, ui, theme}
10	11	terminal → {ui, theme, tcell, golang.org/x/sys}
11		- filetree → {ui, theme, tcell}
12		- snippets → {toml, projectfile, profile}
13		- settings → {toml, projectfile, profile}
14		- tools → {toml, projectfile, profile}
	12	+ filetree → {ui, theme, tcell, fsys}
	13	+ snippets → {toml, projectfile, profile, fsys}
	14	+ settings → {toml, projectfile, profile, fsys}
	15	+ tools → {toml, projectfile, profile, fsys}
	16	+ buffer, projectfile → fsys
	17	+ fsys → bibliothèque standard seule
15	18	configrepo → {projectfile, profile} ← lance la commande git
16	19	syntax → theme
17	20	ui → theme
@@ -22,35 +25,39 @@ app → {editor, ui, lsp, buffer, terminal, filetree, settings, snippets, tools,
22	25	\| Paquet \| Ce qu'il contient \| Dépend de \|
23	26	\| --- \| --- \| --- \|
24	27	\| `profile` \| L'identité de l'éditeur : nom, slug, serveur de langage, modèles de départ, et les chemins qui en dérivent \| bibliothèque standard seule \|
25		-\| `buffer` \| Le texte d'un fichier : lignes de runes, curseur, sélection, annulation, recherche, chargement et sauvegarde \| bibliothèque standard seule \|
26		-\| `projectfile` \| Écritures atomiques des fichiers TOML qu'un projet garde dans le répertoire de l'éditeur \| bibliothèque standard seule \|
	28	+\| `fsys` \| La porte unique vers les fichiers du projet : l'interface `FS`, le disque local, et `Use` pour faire passer tous les paquets sur une autre machine \| bibliothèque standard seule \|
	29	+\| `fsys/fsystest` \| Un `fsys.FS` en mémoire, pour les tests \| `fsys` \|
	30	+\| `remote` \| Une autre machine via la commande `ssh` : une connexion ControlMaster, les fichiers en SFTP, les lignes de commande des shells et outils distants (`-ssh`) \| `github.com/pkg/sftp`, la commande `ssh` ; son `FS` satisfait `fsys.FS` sans importer `fsys` \|
	31	+\| `buffer` \| Le texte d'un fichier : lignes de runes, curseur, sélection, annulation, recherche, chargement et sauvegarde \| `fsys` \|
	32	+\| `projectfile` \| Écritures atomiques des fichiers TOML qu'un projet garde dans le répertoire de l'éditeur \| `fsys` \|
27	33	\| `configrepo` \| Un répertoire de configuration partagé, rapporté depuis l'URL d'une forge (rickub, GitHub, GitLab, Codeberg) par un clone git superficiel, pour le `-load-config` d'un éditeur \| `projectfile`, `profile`, la commande `git` \|
28	34	\| `version` \| De quelle construction de lui-même un binaire est issu : marquage par l'éditeur de liens, puis informations de build Go \| bibliothèque standard seule \|
29	35	\| `jsonrpc` \| JSON-RPC 2.0 sur un flux cadré : appels, notifications, requêtes entrantes auxquelles on peut répondre plus tard \| bibliothèque standard seule \|
30	36	\| `lsp` \| Le cadrage LSP, les méthodes, et le processus fils \| `jsonrpc`, `profile` \|
31	37	\| `theme` \| Du TOML vers des styles tcell ; onze thèmes embarqués plus ceux de l'utilisateur ; deux sortes d'héritage \| `tcell`, `toml` \|
32	38	\| `syntax` \| La coloration : neuf langages intégrés, le registre où un éditeur ajoute le sien, et la boîte à outils d'analyse \| `theme` \|
33		-\| `settings` \| Le `settings.toml` d'un projet : charger, créer, réécrire une clé sur place \| `toml`, `projectfile`, `profile` \|
34		-\| `snippets` \| Les textes réutilisables du `snippets.toml` d'un projet et de celui de l'utilisateur, groupés pour un menu \| `toml`, `projectfile`, `profile` \|
35		-\| `tools` \| Les commandes qu'un projet lance sur lui-même, et dans quel menu chacune se trouve \| `toml`, `projectfile`, `profile` \|
	39	+\| `settings` \| Le `settings.toml` d'un projet : charger, créer, réécrire une clé sur place \| `toml`, `projectfile`, `profile`, `fsys` \|
	40	+\| `snippets` \| Les textes réutilisables du `snippets.toml` d'un projet et de celui de l'utilisateur, groupés pour un menu \| `toml`, `projectfile`, `profile`, `fsys` \|
	41	+\| `tools` \| Les commandes qu'un projet lance sur lui-même, et dans quel menu chacune se trouve ; `Start` passe par le shell local, `StartProgram` lance un argv tel qu'une commande distante \| `toml`, `projectfile`, `profile`, `fsys` \|
36	42	\| `ui` \| Les composants Turbo Vision : peintre, bureau, fenêtre, menu, dialogue, contrôles, barre d'état \| `theme`, `tcell` \|
37	43	\| `editor` \| Le composant d'édition : cadrage, défilement, touches, souris, insertion d'extraits \| `buffer`, `syntax`, `theme`, `ui` \|
38	44	\| `terminal` \| Un shell dans une fenêtre : pseudo-terminal, émulateur VT/ANSI, grille d'écran, le composant \| `theme`, `ui`, `tcell`, `golang.org/x/sys` \|
39		-\| `filetree` \| Les fichiers d'un projet en arborescence dépliable, et la fenêtre qui l'affiche \| `theme`, `ui`, `tcell` \|
	45	+\| `filetree` \| Les fichiers d'un projet en arborescence dépliable, et la fenêtre qui l'affiche \| `theme`, `ui`, `tcell`, `fsys` \|
40	46	\| `acp` \| Un agent de code dans une fenêtre : l'Agent Client Protocol, la conversation, le widget \| `jsonrpc`, `profile`, `projectfile`, `syntax`, `theme`, `ui`, `tcell`, `toml` \|
41		-\| `app` \| L'assemblage : menus, dialogues, routage des événements, popup de complétion, cycle de vie du serveur de langage \| tout ce qui précède \|
	47	+\| `app` \| L'assemblage : menus, dialogues, routage des événements, popup de complétion, cycle de vie du serveur de langage, shells et outils distants (`UseRemote`) \| tout ce qui précède sauf `remote`, qu'il ne connaît qu'à travers l'interface `app.Remote` \|
42	48
43	49	## Dépendances externes
44	50
45		-Trois, et seulement trois :
	51	+Quatre directes :
46	52
47	53	\| Module \| Pourquoi \|
48	54	\| --- \| --- \|
49	55	\| `github.com/gdamore/tcell/v2` \| le terminal \|
50	56	\| `github.com/BurntSushi/toml` \| tous les fichiers de configuration que l'éditeur lit \|
51	57	\| `golang.org/x/sys` \| les ioctls du pseudo-terminal sous Linux et macOS ; les appels de pseudo-console, de processus et de job object sous Windows \|
	58	+\| `github.com/pkg/sftp` \| le client SFTP avec lequel `remote` lit et écrit les fichiers d'une machine, sur le canal qu'ouvre ssh ; il amène `github.com/kr/fs` et `golang.org/x/crypto` en dépendances indirectes \|
52	59
53		-L'analyseur lexical, le client JSON-RPC, le cadrage LSP et l'émulateur VT/ANSI sont écrits à la main.
	60	+L'analyseur lexical, le client JSON-RPC, le cadrage LSP et l'émulateur VT/ANSI sont écrits à la main. SSH lui-même n'est pas dans le binaire : `remote` lance la commande `ssh` installée.
54	61
55	62	## Le diagramme
56	63
@@ -59,3 +66,4 @@ L'analyseur lexical, le client JSON-RPC, le cadrage LSP et l'émulateur VT/ANSI
59	66	## Voir aussi
60	67
61	68	- Pourquoi le graphe a cette forme : [architecture](../explanation/architecture.md)
	69	+- Les deux paquets de l'édition à distance : [fsys](fsys.md), [remote](remote.md)

  > Description neutre et exhaustive de ce que contient turbo-core.
--Dix-neuf paquets. Les dépendances vont strictement vers le bas ; il n'y a ni cycle ni indirection par interface pour en empêcher un.
++Vingt-deux paquets. Les dépendances vont strictement vers le bas ; il n'y a ni cycle ni indirection par interface pour en empêcher un.
  ```
--app → {editor, ui, lsp, buffer, terminal, filetree, settings, snippets, tools, syntax, theme, profile, version}
++app → {editor, ui, lsp, buffer, terminal, filetree, settings, snippets, tools, syntax, theme, profile, version, fsys}
++       remote   → github.com/pkg/sftp   ← lance la commande ssh ; implémente fsys.FS sans importer fsys
         editor   → {buffer, syntax, ui, theme}
         terminal → {ui, theme, tcell, golang.org/x/sys}
--       filetree → {ui, theme, tcell}
++       filetree → {ui, theme, tcell, fsys}
--       snippets → {toml, projectfile, profile}
++       snippets → {toml, projectfile, profile, fsys}
--       settings → {toml, projectfile, profile}
++       settings → {toml, projectfile, profile, fsys}
--       tools    → {toml, projectfile, profile}
++       tools    → {toml, projectfile, profile, fsys}
++       buffer, projectfile → fsys
++       fsys     → bibliothèque standard seule
         configrepo → {projectfile, profile}   ← lance la commande git
         syntax   → theme
         ui       → theme
  | Paquet | Ce qu'il contient | Dépend de |
  | --- | --- | --- |
  | `profile` | L'identité de l'éditeur : nom, slug, serveur de langage, modèles de départ, et les chemins qui en dérivent | **bibliothèque standard seule** |
--| `buffer` | Le texte d'un fichier : lignes de runes, curseur, sélection, annulation, recherche, chargement et sauvegarde | **bibliothèque standard seule** |
++| `fsys` | La porte unique vers les fichiers du projet : l'interface `FS`, le disque local, et `Use` pour faire passer tous les paquets sur une autre machine | **bibliothèque standard seule** |
--| `projectfile` | Écritures atomiques des fichiers TOML qu'un projet garde dans le répertoire de l'éditeur | **bibliothèque standard seule** |
++| `fsys/fsystest` | Un `fsys.FS` en mémoire, pour les tests | `fsys` |
++| `remote` | Une autre machine via la commande `ssh` : une connexion ControlMaster, les fichiers en SFTP, les lignes de commande des shells et outils distants (`-ssh`) | `github.com/pkg/sftp`, la commande `ssh` ; son `FS` satisfait `fsys.FS` sans importer `fsys` |
++| `buffer` | Le texte d'un fichier : lignes de runes, curseur, sélection, annulation, recherche, chargement et sauvegarde | `fsys` |
++| `projectfile` | Écritures atomiques des fichiers TOML qu'un projet garde dans le répertoire de l'éditeur | `fsys` |
  | `configrepo` | Un répertoire de configuration partagé, rapporté depuis l'URL d'une forge (rickub, GitHub, GitLab, Codeberg) par un clone git superficiel, pour le `-load-config` d'un éditeur | `projectfile`, `profile`, la commande `git` |
  | `version` | De quelle construction de lui-même un binaire est issu : marquage par l'éditeur de liens, puis informations de build Go | **bibliothèque standard seule** |
  | `jsonrpc` | JSON-RPC 2.0 sur un flux cadré : appels, notifications, requêtes entrantes auxquelles on peut répondre plus tard | **bibliothèque standard seule** |
  | `lsp` | Le cadrage LSP, les méthodes, et le processus fils | `jsonrpc`, `profile` |
  | `theme` | Du TOML vers des styles tcell ; onze thèmes embarqués plus ceux de l'utilisateur ; deux sortes d'héritage | `tcell`, `toml` |
  | `syntax` | La coloration : neuf langages intégrés, le registre où un éditeur ajoute le sien, et la boîte à outils d'analyse | `theme` |
--| `settings` | Le `settings.toml` d'un projet : charger, créer, réécrire une clé sur place | `toml`, `projectfile`, `profile` |
++| `settings` | Le `settings.toml` d'un projet : charger, créer, réécrire une clé sur place | `toml`, `projectfile`, `profile`, `fsys` |
--| `snippets` | Les textes réutilisables du `snippets.toml` d'un projet et de celui de l'utilisateur, groupés pour un menu | `toml`, `projectfile`, `profile` |
++| `snippets` | Les textes réutilisables du `snippets.toml` d'un projet et de celui de l'utilisateur, groupés pour un menu | `toml`, `projectfile`, `profile`, `fsys` |
--| `tools` | Les commandes qu'un projet lance sur lui-même, et dans quel menu chacune se trouve | `toml`, `projectfile`, `profile` |
++| `tools` | Les commandes qu'un projet lance sur lui-même, et dans quel menu chacune se trouve ; `Start` passe par le shell local, `StartProgram` lance un argv tel qu'une commande distante | `toml`, `projectfile`, `profile`, `fsys` |
  | `ui` | Les composants Turbo Vision : peintre, bureau, fenêtre, menu, dialogue, contrôles, barre d'état | `theme`, `tcell` |
  | `editor` | Le composant d'édition : cadrage, défilement, touches, souris, insertion d'extraits | `buffer`, `syntax`, `theme`, `ui` |
  | `terminal` | Un shell dans une fenêtre : pseudo-terminal, émulateur VT/ANSI, grille d'écran, le composant | `theme`, `ui`, `tcell`, `golang.org/x/sys` |
--| `filetree` | Les fichiers d'un projet en arborescence dépliable, et la fenêtre qui l'affiche | `theme`, `ui`, `tcell` |
++| `filetree` | Les fichiers d'un projet en arborescence dépliable, et la fenêtre qui l'affiche | `theme`, `ui`, `tcell`, `fsys` |
  | `acp` | Un agent de code dans une fenêtre : l'Agent Client Protocol, la conversation, le widget | `jsonrpc`, `profile`, `projectfile`, `syntax`, `theme`, `ui`, `tcell`, `toml` |
--| `app` | L'assemblage : menus, dialogues, routage des événements, popup de complétion, cycle de vie du serveur de langage | tout ce qui précède |
++| `app` | L'assemblage : menus, dialogues, routage des événements, popup de complétion, cycle de vie du serveur de langage, shells et outils distants (`UseRemote`) | tout ce qui précède sauf `remote`, qu'il ne connaît qu'à travers l'interface `app.Remote` |
  ## Dépendances externes
--Trois, et seulement trois :
++Quatre directes :
  | Module | Pourquoi |
  | --- | --- |
  | `github.com/gdamore/tcell/v2` | le terminal |
  | `github.com/BurntSushi/toml` | tous les fichiers de configuration que l'éditeur lit |
  | `golang.org/x/sys` | les ioctls du pseudo-terminal sous Linux et macOS ; les appels de pseudo-console, de processus et de job object sous Windows |
++| `github.com/pkg/sftp` | le client SFTP avec lequel `remote` lit et écrit les fichiers d'une machine, sur le canal qu'ouvre ssh ; il amène `github.com/kr/fs` et `golang.org/x/crypto` en dépendances indirectes |
--L'analyseur lexical, le client JSON-RPC, le cadrage LSP et l'émulateur VT/ANSI sont écrits à la main.
++L'analyseur lexical, le client JSON-RPC, le cadrage LSP et l'émulateur VT/ANSI sont écrits à la main. SSH lui-même n'est pas dans le binaire : `remote` lance la commande `ssh` installée.
  ## Le diagramme
  ## Voir aussi
  - Pourquoi le graphe a cette forme : [architecture](../explanation/architecture.md)
++- Les deux paquets de l'édition à distance : [fsys](fsys.md), [remote](remote.md)

added docs/fr/reference/remote.md +115 -0 Viewed

new file mode 100644
@@ -0,0 +1,115 @@
	1	+# Référence : remote
	2	+
	3	+> Description neutre du paquet `remote`, qui atteint une autre machine via la commande `ssh` installée : une connexion partagée, les fichiers en SFTP, et les lignes de commande des shells et outils distants.
	4	+
	5	+Chemin d'import : `rickub.com/turbo-editors/turbo-core/remote`. Dépend de `github.com/pkg/sftp`, et de la commande `ssh` à l'exécution. Son `FS` satisfait `fsys.FS` sans importer `fsys`.
	6	+
	7	+## Type `Target`
	8	+
	9	+Ce que nomme `-ssh` : `[user@]host[:path]`, comme `scp` écrit un emplacement distant.
	10	+
	11	+\| Champ \| Description \|
	12	+\| --- \| --- \|
	13	+\| `User` \| Sous quel utilisateur se connecter. Vide, c'est ssh qui décide (`User` dans `~/.ssh/config`, sinon le nom de l'utilisateur local). \|
	14	+\| `Host` \| Un nom, une adresse, ou un alias `Host` de `~/.ssh/config`. Une adresse IPv6 s'écrit entre crochets : `bob@[2001:db8::1]:/srv`. \|
	15	+\| `Path` \| Le répertoire à ouvrir. Vide ou `~` désigne le home distant ; `~/x` et un chemin relatif sont relatifs à lui. \|
	16	+
	17	+\| Fonction / méthode \| Description \|
	18	+\| --- \| --- \|
	19	+\| `ParseTarget(argument string) (Target, error)` \| Lit `[user@]host[:path]`. L'utilisateur est tout ce qui précède le dernier `@`. \|
	20	+\| `(Target) Destination() string` \| `user@host`, ou `host` quand aucun utilisateur n'est nommé : ce qu'on donne à ssh. \|
	21	+\| `(Target) String() string` \| La cible réécrite telle qu'on la tape. \|
	22	+
	23	+`ParseTarget` renvoie une erreur qui enveloppe `ErrBadTarget` pour : un hôte ou un utilisateur vide, un hôte ou un utilisateur commençant par `-` (ssh le lirait comme une option), une espace, une tabulation, un saut de ligne ou un `/` dans l'hôte ou l'utilisateur, et des `[…]` non fermés ou mal placés.
	24	+
	25	+La syntaxe n'a pas de port ; un port se met dans `~/.ssh/config` sous un alias `Host`.
	26	+
	27	+## Se connecter
	28	+
	29	+\| Fonction \| Description \|
	30	+\| --- \| --- \|
	31	+\| `Open(ctx, argument string) (*Session, error)` \| `ParseTarget`, puis affiche `Connecting to <cible>…` sur la sortie d'erreur, puis `Connect` avec les `Options` par défaut. C'est ce qu'appelle le flag `-ssh` d'un éditeur. \|
	32	+\| `Connect(ctx, target Target, options Options) (*Session, error)` \| Se connecte, ouvre le canal des fichiers, résout le répertoire. Doit être appelé avant que l'éditeur ne prenne le terminal. \|
	33	+
	34	+`Options` :
	35	+
	36	+\| Champ \| Défaut \| Description \|
	37	+\| --- \| --- \| --- \|
	38	+\| `Program` \| `"ssh"` trouvé dans le `PATH` \| La commande ssh à lancer. \|
	39	+
	40	+Ce que lance `Connect`, dans l'ordre :
	41	+
	42	+\| Étape \| Commande \| Remarques \|
	43	+\| --- \| --- \| --- \|
	44	+\| Connexion \| `ssh -o ControlMaster=yes -o ControlPath=<socket> -o ControlPersist=60 -N -f -- <destination>` \| Au premier plan, sur le terminal : c'est là que ssh demande un mot de passe, une passphrase, ou s'il faut faire confiance à une nouvelle clé d'hôte. Rend la main une fois connecté ; la connexion reste derrière la socket. \|
	45	+\| Fichiers \| `ssh -S <socket> -o ControlMaster=no -o BatchMode=yes -s -- <destination> sftp` \| Un seul canal SFTP, ouvert jusqu'à `Close`. \|
	46	+\| Répertoire \| `realpath` puis `stat` SFTP de `Path` \| Doit être un répertoire existant. \|
	47	+
	48	+La socket est `<tmp>/turbo-ssh-XXXX/control`, où `<tmp>` est `os.TempDir()`, ou `/tmp` s'il dépasse 60 octets (le chemin d'une socket Unix est limité à une centaine).
	49	+
	50	+## Type `Session`
	51	+
	52	+\| Méthode \| Description \|
	53	+\| --- \| --- \|
	54	+\| `FS() *FS` \| Les fichiers distants, enracinés dans le répertoire édité. Ce que la commande passe à `fsys.Use`. \|
	55	+\| `Target() Target` \| Ce à quoi on s'est connecté. \|
	56	+\| `Name() string` \| `Destination()` : comment la machine est affichée. \|
	57	+\| `ShellCommand(dir string) []string` \| L'argv d'un shell de connexion interactif dans `dir` : `ssh -S … -t -- <destination> "exec /bin/sh -c 'cd <dir> && exec \"${SHELL:-/bin/sh}\" -l'"`. \|
	58	+\| `RunCommand(dir, command string, withTerminal bool) []string` \| L'argv qui lance une ligne de commande avec `/bin/sh` dans `dir` : `ssh -S … -t\|-T -- <destination> "exec /bin/sh -c 'cd <dir> && <command>'"`. `-t` si `withTerminal`, sinon `-T`. \|
	59	+\| `Close() error` \| Ferme le canal des fichiers, lance `ssh -S … -O exit -- <destination>`, supprime le répertoire de la socket. Les terminaux et outils qui passent par la connexion s'arrêtent avec elle. Peut être appelé deux fois. \|
	60	+
	61	+`Session` implémente `app.Remote`.
	62	+
	63	+Toute commande après la connexion passe `ControlMaster=no` et `BatchMode=yes` : elle n'ouvre jamais de connexion à elle et ne pose jamais de question, parce qu'à ce moment-là l'éditeur occupe le terminal.
	64	+
	65	+## Type `FS`
	66	+
	67	+Les fichiers distants en SFTP ; implémente `fsys.FS`. Les chemins sont séparés par des `/` (`path`, pas `path/filepath`), relatifs au répertoire édité.
	68	+
	69	+\| Méthode \| Requêtes SFTP \|
	70	+\| --- \| --- \|
	71	+\| `ReadFile` \| `open`, `read`…, `close` \|
	72	+\| `WriteFileAtomic` \| `open` de `.<nom>.<aléa>` avec `O_EXCL`, `write`…, `close`, `setstat` (mode), `posix-rename@openssh.com` par-dessus la cible ; `remove` du temporaire en cas d'échec \|
	73	+\| `ReadDir` \| `opendir`, `readdir`… ; trié par nom \|
	74	+\| `Stat` \| `stat` \|
	75	+\| `MkdirAll` \| `stat` / `mkdir` à chaque niveau ; l'umask distant décide du mode \|
	76	+\| `Getwd` \| aucune : le répertoire résolu par `Connect` \|
	77	+
	78	+Le statut « fichier inexistant » d'un serveur est enveloppé pour que `errors.Is(err, fs.ErrNotExist)` soit vrai.
	79	+
	80	+## Erreurs
	81	+
	82	+\| Erreur \| Cause \|
	83	+\| --- \| --- \|
	84	+\| `ErrBadTarget` \| L'argument de `-ssh` n'est pas `[user@]host[:path]`, ou ssh le lirait comme une option. \|
	85	+\| `ErrNoSSH` \| Pas de commande ssh dans le `PATH`. \|
	86	+\| `ErrUnsupported` \| Windows : son portage d'OpenSSH n'a pas de ControlMaster. \|
	87	+\| `ssh <destination>: exit status 255` \| La connexion a échoué ; ssh a déjà dit pourquoi sur le terminal. \|
	88	+\| `opening the file channel to <destination>: … (<ce qu'a dit ssh>)` \| Le serveur a refusé le sous-système `sftp`. \|
	89	+\| `finding <path> on the remote machine: …` / `opening … : …` \| Le répertoire n'existe pas. \|
	90	+\| `<path> on the remote machine is not a directory: invalid argument` \| Le chemin désigne un fichier. \|
	91	+
	92	+## Voisin : `tools.StartProgram`
	93	+
	94	+```go
	95	+func StartProgram(command string, argv []string, onLine func()) (*tools.Run, error)
	96	+```
	97	+
	98	+Lance `argv` sans shell local intermédiaire ; `command` est le nom de l'exécution (`Run.Command()`, le titre du dialogue). Sorties fusionnées, arrêt avec `Stop`, comme `tools.Start`. Un `argv` vide est une erreur. C'est ainsi qu'un outil capturé s'exécute via ssh : `tools.StartProgram(command, session.RunCommand(dir, command, false), wake)`.
	99	+
	100	+## Exemple
	101	+
	102	+```go
	103	+session, err := remote.Open(ctx, "bob@build-box:/srv/app")
	104	+if err != nil {
	105	+ return err
	106	+}
	107	+defer session.Close()
	108	+fsys.Use(session.FS())
	109	+```
	110	+
	111	+## Voir aussi
	112	+
	113	+- L'interface qu'il implémente : [fsys](fsys.md)
	114	+- Le brancher dans un éditeur : [ajouter l'édition à distance](../how-to/add-remote-editing.md)
	115	+- Pourquoi il pilote la commande ssh : [l'édition à distance](../explanation/remote-editing.md)

++# Référence : remote
++
++> Description neutre du paquet `remote`, qui atteint une autre machine via la commande `ssh` installée : une connexion partagée, les fichiers en SFTP, et les lignes de commande des shells et outils distants.
++
++Chemin d'import : `rickub.com/turbo-editors/turbo-core/remote`. Dépend de `github.com/pkg/sftp`, et de la commande `ssh` à l'exécution. Son `FS` satisfait `fsys.FS` sans importer `fsys`.
++
++## Type `Target`
++
++Ce que nomme `-ssh` : `[user@]host[:path]`, comme `scp` écrit un emplacement distant.
++
++| Champ | Description |
++| --- | --- |
++| `User` | Sous quel utilisateur se connecter. Vide, c'est ssh qui décide (`User` dans `~/.ssh/config`, sinon le nom de l'utilisateur local). |
++| `Host` | Un nom, une adresse, ou un alias `Host` de `~/.ssh/config`. Une adresse IPv6 s'écrit entre crochets : `bob@[2001:db8::1]:/srv`. |
++| `Path` | Le répertoire à ouvrir. Vide ou `~` désigne le home distant ; `~/x` et un chemin relatif sont relatifs à lui. |
++
++| Fonction / méthode | Description |
++| --- | --- |
++| `ParseTarget(argument string) (Target, error)` | Lit `[user@]host[:path]`. L'utilisateur est tout ce qui précède le **dernier** `@`. |
++| `(Target) Destination() string` | `user@host`, ou `host` quand aucun utilisateur n'est nommé : ce qu'on donne à ssh. |
++| `(Target) String() string` | La cible réécrite telle qu'on la tape. |
++
++`ParseTarget` renvoie une erreur qui enveloppe `ErrBadTarget` pour : un hôte ou un utilisateur vide, un hôte ou un utilisateur commençant par `-` (ssh le lirait comme une option), une espace, une tabulation, un saut de ligne ou un `/` dans l'hôte ou l'utilisateur, et des `[…]` non fermés ou mal placés.
++
++La syntaxe n'a pas de port ; un port se met dans `~/.ssh/config` sous un alias `Host`.
++
++## Se connecter
++
++| Fonction | Description |
++| --- | --- |
++| `Open(ctx, argument string) (*Session, error)` | `ParseTarget`, puis affiche `Connecting to <cible>…` sur la sortie d'erreur, puis `Connect` avec les `Options` par défaut. C'est ce qu'appelle le flag `-ssh` d'un éditeur. |
++| `Connect(ctx, target Target, options Options) (*Session, error)` | Se connecte, ouvre le canal des fichiers, résout le répertoire. Doit être appelé avant que l'éditeur ne prenne le terminal. |
++
++`Options` :
++
++| Champ | Défaut | Description |
++| --- | --- | --- |
++| `Program` | `"ssh"` trouvé dans le `PATH` | La commande ssh à lancer. |
++
++Ce que lance `Connect`, dans l'ordre :
++
++| Étape | Commande | Remarques |
++| --- | --- | --- |
++| Connexion | `ssh -o ControlMaster=yes -o ControlPath=<socket> -o ControlPersist=60 -N -f -- <destination>` | Au premier plan, sur le terminal : c'est là que ssh demande un mot de passe, une passphrase, ou s'il faut faire confiance à une nouvelle clé d'hôte. Rend la main une fois connecté ; la connexion reste derrière la socket. |
++| Fichiers | `ssh -S <socket> -o ControlMaster=no -o BatchMode=yes -s -- <destination> sftp` | Un seul canal SFTP, ouvert jusqu'à `Close`. |
++| Répertoire | `realpath` puis `stat` SFTP de `Path` | Doit être un répertoire existant. |
++
++La socket est `<tmp>/turbo-ssh-XXXX/control`, où `<tmp>` est `os.TempDir()`, ou `/tmp` s'il dépasse 60 octets (le chemin d'une socket Unix est limité à une centaine).
++
++## Type `Session`
++
++| Méthode | Description |
++| --- | --- |
++| `FS() *FS` | Les fichiers distants, enracinés dans le répertoire édité. Ce que la commande passe à `fsys.Use`. |
++| `Target() Target` | Ce à quoi on s'est connecté. |
++| `Name() string` | `Destination()` : comment la machine est affichée. |
++| `ShellCommand(dir string) []string` | L'argv d'un shell de connexion interactif dans `dir` : `ssh -S … -t -- <destination> "exec /bin/sh -c 'cd <dir> && exec \"${SHELL:-/bin/sh}\" -l'"`. |
++| `RunCommand(dir, command string, withTerminal bool) []string` | L'argv qui lance une ligne de commande avec `/bin/sh` dans `dir` : `ssh -S … -t|-T -- <destination> "exec /bin/sh -c 'cd <dir> && <command>'"`. `-t` si `withTerminal`, sinon `-T`. |
++| `Close() error` | Ferme le canal des fichiers, lance `ssh -S … -O exit -- <destination>`, supprime le répertoire de la socket. Les terminaux et outils qui passent par la connexion s'arrêtent avec elle. Peut être appelé deux fois. |
++
++`Session` implémente `app.Remote`.
++
++Toute commande après la connexion passe `ControlMaster=no` et `BatchMode=yes` : elle n'ouvre jamais de connexion à elle et ne pose jamais de question, parce qu'à ce moment-là l'éditeur occupe le terminal.
++
++## Type `FS`
++
++Les fichiers distants en SFTP ; implémente `fsys.FS`. Les chemins sont séparés par des `/` (`path`, pas `path/filepath`), relatifs au répertoire édité.
++
++| Méthode | Requêtes SFTP |
++| --- | --- |
++| `ReadFile` | `open`, `read`…, `close` |
++| `WriteFileAtomic` | `open` de `.<nom>.<aléa>` avec `O_EXCL`, `write`…, `close`, `setstat` (mode), `posix-rename@openssh.com` par-dessus la cible ; `remove` du temporaire en cas d'échec |
++| `ReadDir` | `opendir`, `readdir`… ; trié par nom |
++| `Stat` | `stat` |
++| `MkdirAll` | `stat` / `mkdir` à chaque niveau ; l'umask distant décide du mode |
++| `Getwd` | aucune : le répertoire résolu par `Connect` |
++
++Le statut « fichier inexistant » d'un serveur est enveloppé pour que `errors.Is(err, fs.ErrNotExist)` soit vrai.
++
++## Erreurs
++
++| Erreur | Cause |
++| --- | --- |
++| `ErrBadTarget` | L'argument de `-ssh` n'est pas `[user@]host[:path]`, ou ssh le lirait comme une option. |
++| `ErrNoSSH` | Pas de commande ssh dans le `PATH`. |
++| `ErrUnsupported` | Windows : son portage d'OpenSSH n'a pas de ControlMaster. |
++| `ssh <destination>: exit status 255` | La connexion a échoué ; ssh a déjà dit pourquoi sur le terminal. |
++| `opening the file channel to <destination>: … (<ce qu'a dit ssh>)` | Le serveur a refusé le sous-système `sftp`. |
++| `finding <path> on the remote machine: …` / `opening … : …` | Le répertoire n'existe pas. |
++| `<path> on the remote machine is not a directory: invalid argument` | Le chemin désigne un fichier. |
++
++## Voisin : `tools.StartProgram`
++
++```go
++func StartProgram(command string, argv []string, onLine func()) (*tools.Run, error)
++```
++
++Lance `argv` sans shell local intermédiaire ; `command` est le nom de l'exécution (`Run.Command()`, le titre du dialogue). Sorties fusionnées, arrêt avec `Stop`, comme `tools.Start`. Un `argv` vide est une erreur. C'est ainsi qu'un outil capturé s'exécute via ssh : `tools.StartProgram(command, session.RunCommand(dir, command, false), wake)`.
++
++## Exemple
++
++```go
++session, err := remote.Open(ctx, "bob@build-box:/srv/app")
++if err != nil {
++	return err
++}
++defer session.Close()
++fsys.Use(session.FS())
++```
++
++## Voir aussi
++
++- L'interface qu'il implémente : [fsys](fsys.md)
++- Le brancher dans un éditeur : [ajouter l'édition à distance](../how-to/add-remote-editing.md)
++- Pourquoi il pilote la commande ssh : [l'édition à distance](../explanation/remote-editing.md)

modified filetree/README.md +1 -1 Viewed

@@ -2,7 +2,7 @@
2	2
3	3	A project's files as an expandable tree, and the widget that shows one.
4	4
5		-Depends on `ui` for its place on screen and `theme` for its colours, and on nothing above it. `app` opens and owns the window; this package knows nothing about menus, buffers or language servers.
	5	+Depends on `ui` for its place on screen, `theme` for its colours and `fsys` for the directories it lists — the remote machine's under `-ssh` — and on nothing above it. `app` opens and owns the window; this package knows nothing about menus, buffers or language servers.
6	6
7	7	## Two halves
8	8

  A project's files as an expandable tree, and the widget that shows one.
--Depends on `ui` for its place on screen and `theme` for its colours, and on nothing above it. `app` opens and owns the window; this package knows nothing about menus, buffers or language servers.
++Depends on `ui` for its place on screen, `theme` for its colours and `fsys` for the directories it lists — the remote machine's under `-ssh` — and on nothing above it. `app` opens and owns the window; this package knows nothing about menus, buffers or language servers.
  ## Two halves

added filetree/fsys_test.go +31 -0 Viewed

new file mode 100644
@@ -0,0 +1,31 @@
	1	+package filetree
	2	+
	3	+import (
	4	+ "testing"
	5	+
	6	+ "rickub.com/turbo-editors/turbo-core/fsys"
	7	+ "rickub.com/turbo-editors/turbo-core/fsys/fsystest"
	8	+)
	9	+
	10	+func TestTheTreeListsTheCurrentFileSystem(t *testing.T) {
	11	+ memory := fsystest.New("/remote/project")
	12	+ previous := fsys.Use(memory)
	13	+ t.Cleanup(func() { fsys.Use(previous) })
	14	+ memory.AddFile("/remote/project/main.py", "")
	15	+ memory.AddFile("/remote/project/pkg/util.py", "")
	16	+
	17	+ tree, err := New(".")
	18	+ if err != nil {
	19	+ t.Fatal(err)
	20	+ }
	21	+ if tree.Root().Path() != "/remote/project" {
	22	+ t.Errorf("root = %q, want the current file system's working directory", tree.Root().Path())
	23	+ }
	24	+ var names []string
	25	+ for _, row := range tree.Rows() {
	26	+ names = append(names, row.Node.Name())
	27	+ }
	28	+ if len(names) != 2 \|\| names[0] != "pkg" \|\| names[1] != "main.py" {
	29	+ t.Errorf("rows = %v, want [pkg main.py]", names)
	30	+ }
	31	+}

++package filetree
++
++import (
++	"testing"
++
++	"rickub.com/turbo-editors/turbo-core/fsys"
++	"rickub.com/turbo-editors/turbo-core/fsys/fsystest"
++)
++
++func TestTheTreeListsTheCurrentFileSystem(t *testing.T) {
++	memory := fsystest.New("/remote/project")
++	previous := fsys.Use(memory)
++	t.Cleanup(func() { fsys.Use(previous) })
++	memory.AddFile("/remote/project/main.py", "")
++	memory.AddFile("/remote/project/pkg/util.py", "")
++
++	tree, err := New(".")
++	if err != nil {
++		t.Fatal(err)
++	}
++	if tree.Root().Path() != "/remote/project" {
++		t.Errorf("root = %q, want the current file system's working directory", tree.Root().Path())
++	}
++	var names []string
++	for _, row := range tree.Rows() {
++		names = append(names, row.Node.Name())
++	}
++	if len(names) != 2 || names[0] != "pkg" || names[1] != "main.py" {
++		t.Errorf("rows = %v, want [pkg main.py]", names)
++	}
++}

modified filetree/tree.go +5 -4 Viewed

@@ -17,9 +17,10 @@ package filetree
17	17
18	18	import (
19	19	"fmt"
20		- "os"
21	20	"path/filepath"
22	21	"sort"
	22	+
	23	+ "rickub.com/turbo-editors/turbo-core/fsys"
23	24	)
24	25
25	26	// hiddenName is the one directory the tree never shows.
@@ -109,12 +110,12 @@ type Tree struct {
109	110	//
110	111	// tree, err := filetree.New("/src/myproject")
111	112	func New(root string) (*Tree, error) {
112		- absolute, err := filepath.Abs(root)
	113	+ absolute, err := fsys.Abs(root)
113	114	if err != nil {
114	115	return nil, fmt.Errorf("resolving %s: %w", root, err)
115	116	}
116	117
117		- info, err := os.Stat(absolute)
	118	+ info, err := fsys.Stat(absolute)
118	119	if err != nil {
119	120	return nil, fmt.Errorf("reading %s: %w", absolute, err)
120	121	}
@@ -200,7 +201,7 @@ func (n *Node) refresh() {
200	201	// unreadable directory in a project is not a reason to refuse to show the rest
201	202	// of it, and Refresh will pick it up if its permissions change.
202	203	func readChildren(directory string) []*Node {
203		- entries, err := os.ReadDir(directory)
	204	+ entries, err := fsys.ReadDir(directory)
204	205	if err != nil {
205	206	return nil
206	207	}

  import (
  	"fmt"
--	"os"
  	"path/filepath"
  	"sort"
++
++	"rickub.com/turbo-editors/turbo-core/fsys"
  )
  // hiddenName is the one directory the tree never shows.
  //
  //	tree, err := filetree.New("/src/myproject")
  func New(root string) (*Tree, error) {
--	absolute, err := filepath.Abs(root)
++	absolute, err := fsys.Abs(root)
  	if err != nil {
  		return nil, fmt.Errorf("resolving %s: %w", root, err)
  	}
--	info, err := os.Stat(absolute)
++	info, err := fsys.Stat(absolute)
  	if err != nil {
  		return nil, fmt.Errorf("reading %s: %w", absolute, err)
  	}
  // unreadable directory in a project is not a reason to refuse to show the rest
  // of it, and Refresh will pick it up if its permissions change.
  func readChildren(directory string) []*Node {
--	entries, err := os.ReadDir(directory)
++	entries, err := fsys.ReadDir(directory)
  	if err != nil {
  		return nil
  	}

added fsys/README.md +41 -0 Viewed

new file mode 100644
@@ -0,0 +1,41 @@
	1	+# fsys
	2	+
	3	+The one door through which the editor reaches the files of the project it edits: the source files, the project tree, the Open and Save As dialogs, and the project's own `settings.toml`, `snippets.toml` and `tools.toml`.
	4	+
	5	+Imports the standard library and nothing else.
	6	+
	7	+```go
	8	+data, err := fsys.ReadFile("main.go")
	9	+err = fsys.WriteFileAtomic("main.go", data, 0o644)
	10	+```
	11	+
	12	+## Why it exists
	13	+
	14	+So that the files can live on another machine. An editor started with `-ssh bob@machine` calls `fsys.Use(session.FS())` once, before anything reads; from then on `buffer`, `filetree`, `settings`, `snippets`, `tools`, `projectfile` and `app` read and write over SFTP, and none of them knows. Without that call nothing changes: the default is `Local{}`, the disk, through package `os`.
	15	+
	16	+It is package-level state, set once at start-up — the shape `syntax.Register` has, for the same reason: threading a file-system value through every package and call site would change half the library's signatures for a choice made once per process.
	17	+
	18	+## What stays out
	19	+
	20	+What belongs to the person rather than the project stays on the local disk, through `os`: the user's themes, the user's own snippets file, the language server's executable, coding agents and their files, and `-load-config`'s clone.
	21	+
	22	+## Public API
	23	+
	24	+\| Name \| What it does \|
	25	+\| --- \| --- \|
	26	+\| `FS` \| `ReadFile`, `WriteFileAtomic`, `ReadDir`, `Stat`, `MkdirAll`, `Getwd`. A missing file is always `errors.Is(err, fs.ErrNotExist)`. \|
	27	+\| `Local` \| The disk, through `os`. `WriteFileAtomic` writes `.<name>.<random>` beside the target, sets the mode, renames. \|
	28	+\| `Use(f) (previous)` \| Makes `f` current; returns the previous one so a test can put it back. \|
	29	+\| `Current()`, `IsLocal()` \| The file system in use; whether it is `Local`. \|
	30	+\| `ReadFile`, `WriteFileAtomic`, `ReadDir`, `Stat`, `MkdirAll`, `Getwd` \| The same, on `Current()`. \|
	31	+\| `Abs(path)` \| `filepath.Abs` against `Getwd()` — the remote working directory under `-ssh`. \|
	32	+
	33	+`fsystest.New(working)` is an in-memory `FS` for tests, with `AddFile`, `File` and `Mode`. A test that finds a file only in memory has proved the code under test went through `fsys`, because the disk never had it.
	34	+
	35	+## Tests
	36	+
	37	+```sh
	38	+go test ./fsys/...
	39	+```
	40	+
	41	+The packages that go through `fsys` each have an `fsys_test.go` that swaps in `fsystest.Memory` and checks the file arrived there, not on disk.

++# fsys
++
++The one door through which the editor reaches the files of the project it edits: the source files, the project tree, the Open and Save As dialogs, and the project's own `settings.toml`, `snippets.toml` and `tools.toml`.
++
++Imports the standard library and nothing else.
++
++```go
++data, err := fsys.ReadFile("main.go")
++err = fsys.WriteFileAtomic("main.go", data, 0o644)
++```
++
++## Why it exists
++
++So that the files can live on another machine. An editor started with `-ssh bob@machine` calls `fsys.Use(session.FS())` once, before anything reads; from then on `buffer`, `filetree`, `settings`, `snippets`, `tools`, `projectfile` and `app` read and write over SFTP, and none of them knows. Without that call nothing changes: the default is `Local{}`, the disk, through package `os`.
++
++It is package-level state, set once at start-up — the shape `syntax.Register` has, for the same reason: threading a file-system value through every package and call site would change half the library's signatures for a choice made once per process.
++
++## What stays out
++
++What belongs to the person rather than the project stays on the local disk, through `os`: the user's themes, the user's own snippets file, the language server's executable, coding agents and their files, and `-load-config`'s clone.
++
++## Public API
++
++| Name | What it does |
++| --- | --- |
++| `FS` | `ReadFile`, `WriteFileAtomic`, `ReadDir`, `Stat`, `MkdirAll`, `Getwd`. A missing file is always `errors.Is(err, fs.ErrNotExist)`. |
++| `Local` | The disk, through `os`. `WriteFileAtomic` writes `.<name>.<random>` beside the target, sets the mode, renames. |
++| `Use(f) (previous)` | Makes `f` current; returns the previous one so a test can put it back. |
++| `Current()`, `IsLocal()` | The file system in use; whether it is `Local`. |
++| `ReadFile`, `WriteFileAtomic`, `ReadDir`, `Stat`, `MkdirAll`, `Getwd` | The same, on `Current()`. |
++| `Abs(path)` | `filepath.Abs` against `Getwd()` — the remote working directory under `-ssh`. |
++
++`fsystest.New(working)` is an in-memory `FS` for tests, with `AddFile`, `File` and `Mode`. A test that finds a file only in memory has proved the code under test went through `fsys`, because the disk never had it.
++
++## Tests
++
++```sh
++go test ./fsys/...
++```
++
++The packages that go through `fsys` each have an `fsys_test.go` that swaps in `fsystest.Memory` and checks the file arrived there, not on disk.

added fsys/fsys.go +139 -0 Viewed

new file mode 100644
@@ -0,0 +1,139 @@
	1	+// Package fsys is the one door through which the editor reaches the files it
	2	+// edits: the source files, the project tree, the Open dialog, and the
	3	+// project's own settings, snippets and tools files.
	4	+//
	5	+// It exists so that those files can live somewhere else. An editor started
	6	+// with -ssh bob@machine calls Use once, before anything reads, with a file
	7	+// system that speaks SFTP to that machine; from then on every package that
	8	+// goes through here reads and writes over there, and none of them knows.
	9	+// Without that call, nothing changes: the default is the local disk, through
	10	+// package os.
	11	+//
	12	+// data, err := fsys.ReadFile("main.go")
	13	+// err = fsys.WriteFileAtomic("main.go", data, 0o644)
	14	+//
	15	+// What deliberately does not come through here is what belongs to the person
	16	+// rather than the project: the user's own themes, the language server's
	17	+// executable, a coding agent's configuration. Those stay on the machine the
	18	+// editor runs on.
	19	+//
	20	+// The current file system is package-level state, set once at start-up —
	21	+// the same shape syntax.Register has, for the same reason: threading a value
	22	+// through buffer, filetree, settings, snippets, tools and every call site in
	23	+// app would be a change to all of them, for a choice made once per process.
	24	+package fsys
	25	+
	26	+import (
	27	+ "io/fs"
	28	+ "path/filepath"
	29	+ "sync"
	30	+)
	31	+
	32	+// FS is what the editor needs from a file system. Paths are slash-separated
	33	+// on Unix, as package os expects; a relative path is relative to Getwd.
	34	+//
	35	+// Every error that means "there is no such file" must satisfy
	36	+// errors.Is(err, fs.ErrNotExist): opening a file that does not exist yet is
	37	+// how a new file is made, and callers tell that case apart this way.
	38	+type FS interface {
	39	+ // ReadFile returns the whole content of a file.
	40	+ ReadFile(name string) ([]byte, error)
	41	+ // WriteFileAtomic replaces a file with data, giving it perm, so that a
	42	+ // reader only ever sees the old content or the new one — never half.
	43	+ // The directory must exist.
	44	+ WriteFileAtomic(name string, data []byte, perm fs.FileMode) error
	45	+ // ReadDir lists a directory, sorted by name.
	46	+ ReadDir(name string) ([]fs.DirEntry, error)
	47	+ // Stat describes a file, following symbolic links.
	48	+ Stat(name string) (fs.FileInfo, error)
	49	+ // MkdirAll makes a directory and any parent it lacks.
	50	+ MkdirAll(name string, perm fs.FileMode) error
	51	+ // Getwd returns the absolute directory relative paths start from.
	52	+ Getwd() (string, error)
	53	+}
	54	+
	55	+var (
	56	+ mu sync.RWMutex
	57	+ current FS = Local{}
	58	+)
	59	+
	60	+// Use makes f the file system every package reads and writes through, and
	61	+// returns the one it replaces so a test can put it back.
	62	+//
	63	+// Call it at start-up, before the editor opens a file. It is safe to call from
	64	+// any goroutine, but swapping file systems under an editor that already has
	65	+// files open would leave it holding paths that mean something else.
	66	+//
	67	+// previous := fsys.Use(session.FS())
	68	+// defer fsys.Use(previous)
	69	+func Use(f FS) (previous FS) {
	70	+ mu.Lock()
	71	+ defer mu.Unlock()
	72	+ previous, current = current, f
	73	+ return previous
	74	+}
	75	+
	76	+// Current returns the file system in use.
	77	+func Current() FS {
	78	+ mu.RLock()
	79	+ defer mu.RUnlock()
	80	+ return current
	81	+}
	82	+
	83	+// IsLocal reports whether the file system in use is the local disk — which is
	84	+// what decides, for instance, whether a local language server can be pointed
	85	+// at the project.
	86	+func IsLocal() bool {
	87	+ _, local := Current().(Local)
	88	+ return local
	89	+}
	90	+
	91	+// ReadFile reads a file through the current file system.
	92	+//
	93	+// data, err := fsys.ReadFile(".turbo-go/settings.toml")
	94	+func ReadFile(name string) ([]byte, error) { return Current().ReadFile(name) }
	95	+
	96	+// WriteFileAtomic replaces a file through the current file system; see
	97	+// FS.WriteFileAtomic.
	98	+//
	99	+// err := fsys.WriteFileAtomic("main.go", []byte(text), 0o644)
	100	+func WriteFileAtomic(name string, data []byte, perm fs.FileMode) error {
	101	+ return Current().WriteFileAtomic(name, data, perm)
	102	+}
	103	+
	104	+// ReadDir lists a directory through the current file system.
	105	+//
	106	+// entries, err := fsys.ReadDir(".")
	107	+func ReadDir(name string) ([]fs.DirEntry, error) { return Current().ReadDir(name) }
	108	+
	109	+// Stat describes a file through the current file system.
	110	+//
	111	+// info, err := fsys.Stat("go.mod")
	112	+func Stat(name string) (fs.FileInfo, error) { return Current().Stat(name) }
	113	+
	114	+// MkdirAll makes a directory through the current file system.
	115	+//
	116	+// err := fsys.MkdirAll(".turbo-go", 0o755)
	117	+func MkdirAll(name string, perm fs.FileMode) error { return Current().MkdirAll(name, perm) }
	118	+
	119	+// Getwd returns the directory relative paths start from: the process's working
	120	+// directory locally, the directory given after the colon of -ssh remotely.
	121	+//
	122	+// project, err := fsys.Getwd()
	123	+func Getwd() (string, error) { return Current().Getwd() }
	124	+
	125	+// Abs makes a path absolute against Getwd, and cleans it. It is
	126	+// filepath.Abs for whichever machine the files are on — filepath.Abs itself
	127	+// would resolve a remote path against the local working directory.
	128	+//
	129	+// absolute, err := fsys.Abs("cmd/main.go")
	130	+func Abs(path string) (string, error) {
	131	+ if filepath.IsAbs(path) {
	132	+ return filepath.Clean(path), nil
	133	+ }
	134	+ working, err := Getwd()
	135	+ if err != nil {
	136	+ return "", err
	137	+ }
	138	+ return filepath.Join(working, path), nil
	139	+}

++// Package fsys is the one door through which the editor reaches the files it
++// edits: the source files, the project tree, the Open dialog, and the
++// project's own settings, snippets and tools files.
++//
++// It exists so that those files can live somewhere else. An editor started
++// with -ssh bob@machine calls Use once, before anything reads, with a file
++// system that speaks SFTP to that machine; from then on every package that
++// goes through here reads and writes over there, and none of them knows.
++// Without that call, nothing changes: the default is the local disk, through
++// package os.
++//
++//	data, err := fsys.ReadFile("main.go")
++//	err = fsys.WriteFileAtomic("main.go", data, 0o644)
++//
++// What deliberately does not come through here is what belongs to the person
++// rather than the project: the user's own themes, the language server's
++// executable, a coding agent's configuration. Those stay on the machine the
++// editor runs on.
++//
++// The current file system is package-level state, set once at start-up —
++// the same shape syntax.Register has, for the same reason: threading a value
++// through buffer, filetree, settings, snippets, tools and every call site in
++// app would be a change to all of them, for a choice made once per process.
++package fsys
++
++import (
++	"io/fs"
++	"path/filepath"
++	"sync"
++)
++
++// FS is what the editor needs from a file system. Paths are slash-separated
++// on Unix, as package os expects; a relative path is relative to Getwd.
++//
++// Every error that means "there is no such file" must satisfy
++// errors.Is(err, fs.ErrNotExist): opening a file that does not exist yet is
++// how a new file is made, and callers tell that case apart this way.
++type FS interface {
++	// ReadFile returns the whole content of a file.
++	ReadFile(name string) ([]byte, error)
++	// WriteFileAtomic replaces a file with data, giving it perm, so that a
++	// reader only ever sees the old content or the new one — never half.
++	// The directory must exist.
++	WriteFileAtomic(name string, data []byte, perm fs.FileMode) error
++	// ReadDir lists a directory, sorted by name.
++	ReadDir(name string) ([]fs.DirEntry, error)
++	// Stat describes a file, following symbolic links.
++	Stat(name string) (fs.FileInfo, error)
++	// MkdirAll makes a directory and any parent it lacks.
++	MkdirAll(name string, perm fs.FileMode) error
++	// Getwd returns the absolute directory relative paths start from.
++	Getwd() (string, error)
++}
++
++var (
++	mu      sync.RWMutex
++	current FS = Local{}
++)
++
++// Use makes f the file system every package reads and writes through, and
++// returns the one it replaces so a test can put it back.
++//
++// Call it at start-up, before the editor opens a file. It is safe to call from
++// any goroutine, but swapping file systems under an editor that already has
++// files open would leave it holding paths that mean something else.
++//
++//	previous := fsys.Use(session.FS())
++//	defer fsys.Use(previous)
++func Use(f FS) (previous FS) {
++	mu.Lock()
++	defer mu.Unlock()
++	previous, current = current, f
++	return previous
++}
++
++// Current returns the file system in use.
++func Current() FS {
++	mu.RLock()
++	defer mu.RUnlock()
++	return current
++}
++
++// IsLocal reports whether the file system in use is the local disk — which is
++// what decides, for instance, whether a local language server can be pointed
++// at the project.
++func IsLocal() bool {
++	_, local := Current().(Local)
++	return local
++}
++
++// ReadFile reads a file through the current file system.
++//
++//	data, err := fsys.ReadFile(".turbo-go/settings.toml")
++func ReadFile(name string) ([]byte, error) { return Current().ReadFile(name) }
++
++// WriteFileAtomic replaces a file through the current file system; see
++// FS.WriteFileAtomic.
++//
++//	err := fsys.WriteFileAtomic("main.go", []byte(text), 0o644)
++func WriteFileAtomic(name string, data []byte, perm fs.FileMode) error {
++	return Current().WriteFileAtomic(name, data, perm)
++}
++
++// ReadDir lists a directory through the current file system.
++//
++//	entries, err := fsys.ReadDir(".")
++func ReadDir(name string) ([]fs.DirEntry, error) { return Current().ReadDir(name) }
++
++// Stat describes a file through the current file system.
++//
++//	info, err := fsys.Stat("go.mod")
++func Stat(name string) (fs.FileInfo, error) { return Current().Stat(name) }
++
++// MkdirAll makes a directory through the current file system.
++//
++//	err := fsys.MkdirAll(".turbo-go", 0o755)
++func MkdirAll(name string, perm fs.FileMode) error { return Current().MkdirAll(name, perm) }
++
++// Getwd returns the directory relative paths start from: the process's working
++// directory locally, the directory given after the colon of -ssh remotely.
++//
++//	project, err := fsys.Getwd()
++func Getwd() (string, error) { return Current().Getwd() }
++
++// Abs makes a path absolute against Getwd, and cleans it. It is
++// filepath.Abs for whichever machine the files are on — filepath.Abs itself
++// would resolve a remote path against the local working directory.
++//
++//	absolute, err := fsys.Abs("cmd/main.go")
++func Abs(path string) (string, error) {
++	if filepath.IsAbs(path) {
++		return filepath.Clean(path), nil
++	}
++	working, err := Getwd()
++	if err != nil {
++		return "", err
++	}
++	return filepath.Join(working, path), nil
++}

added fsys/fsys_test.go +150 -0 Viewed

new file mode 100644
@@ -0,0 +1,150 @@
	1	+package fsys_test
	2	+
	3	+import (
	4	+ "errors"
	5	+ "fmt"
	6	+ "io/fs"
	7	+ "os"
	8	+ "path/filepath"
	9	+ "testing"
	10	+
	11	+ "rickub.com/turbo-editors/turbo-core/fsys"
	12	+ "rickub.com/turbo-editors/turbo-core/fsys/fsystest"
	13	+)
	14	+
	15	+// useMemory swaps an in-memory file system in for the test's duration.
	16	+func useMemory(t testing.T, working string) fsystest.Memory {
	17	+ t.Helper()
	18	+ memory := fsystest.New(working)
	19	+ previous := fsys.Use(memory)
	20	+ t.Cleanup(func() { fsys.Use(previous) })
	21	+ return memory
	22	+}
	23	+
	24	+func TestTheDefaultFileSystemIsTheLocalDisk(t *testing.T) {
	25	+ if !fsys.IsLocal() {
	26	+ t.Fatalf("Current() = %T, want fsys.Local", fsys.Current())
	27	+ }
	28	+}
	29	+
	30	+func TestUseReplacesTheFileSystemAndReturnsThePreviousOne(t *testing.T) {
	31	+ memory := fsystest.New("/remote")
	32	+ previous := fsys.Use(memory)
	33	+ defer fsys.Use(previous)
	34	+
	35	+ if _, ok := previous.(fsys.Local); !ok {
	36	+ t.Errorf("previous = %T, want fsys.Local", previous)
	37	+ }
	38	+ if fsys.Current() != memory {
	39	+ t.Errorf("Current() did not return the file system just given to Use")
	40	+ }
	41	+ if fsys.IsLocal() {
	42	+ t.Errorf("IsLocal() = true with a memory file system in use")
	43	+ }
	44	+}
	45	+
	46	+func TestPackageFunctionsGoThroughTheCurrentFileSystem(t *testing.T) {
	47	+ memory := useMemory(t, "/remote/project")
	48	+ memory.AddFile("/remote/project/main.py", "print(1)\n")
	49	+
	50	+ data, err := fsys.ReadFile("main.py")
	51	+ if err != nil \|\| string(data) != "print(1)\n" {
	52	+ t.Fatalf("ReadFile = %q, %v", data, err)
	53	+ }
	54	+ if err := fsys.MkdirAll("pkg/sub", 0o755); err != nil {
	55	+ t.Fatal(err)
	56	+ }
	57	+ if err := fsys.WriteFileAtomic("pkg/sub/a.py", []byte("x = 1\n"), 0o600); err != nil {
	58	+ t.Fatal(err)
	59	+ }
	60	+ if got, _ := memory.File("/remote/project/pkg/sub/a.py"); got != "x = 1\n" {
	61	+ t.Errorf("written file = %q", got)
	62	+ }
	63	+ info, err := fsys.Stat("pkg")
	64	+ if err != nil \|\| !info.IsDir() {
	65	+ t.Errorf("Stat(pkg) = %v, %v; want a directory", info, err)
	66	+ }
	67	+ entries, err := fsys.ReadDir(".")
	68	+ if err != nil \|\| len(entries) != 2 \|\| entries[0].Name() != "main.py" \|\| entries[1].Name() != "pkg" {
	69	+ t.Errorf("ReadDir(.) = %v, %v", entries, err)
	70	+ }
	71	+ if working, _ := fsys.Getwd(); working != "/remote/project" {
	72	+ t.Errorf("Getwd = %q", working)
	73	+ }
	74	+}
	75	+
	76	+func TestAbsResolvesAgainstTheCurrentFileSystemsWorkingDirectory(t *testing.T) {
	77	+ useMemory(t, "/home/bob/app")
	78	+
	79	+ cases := map[string]string{
	80	+ "main.py": "/home/bob/app/main.py",
	81	+ "../other/x.py": "/home/bob/other/x.py",
	82	+ "/etc/hosts": "/etc/hosts",
	83	+ "/srv//a/../b/c": "/srv/b/c",
	84	+ }
	85	+ for in, want := range cases {
	86	+ if got, err := fsys.Abs(in); err != nil \|\| got != want {
	87	+ t.Errorf("Abs(%q) = %q, %v; want %q", in, got, err, want)
	88	+ }
	89	+ }
	90	+}
	91	+
	92	+func TestLocalWriteFileAtomicReplacesTheContentWithTheGivenMode(t *testing.T) {
	93	+ directory := t.TempDir()
	94	+ target := filepath.Join(directory, "main.go")
	95	+ if err := os.WriteFile(target, []byte("old"), 0o644); err != nil {
	96	+ t.Fatal(err)
	97	+ }
	98	+
	99	+ if err := (fsys.Local{}).WriteFileAtomic(target, []byte("new"), 0o755); err != nil {
	100	+ t.Fatal(err)
	101	+ }
	102	+
	103	+ data, _ := os.ReadFile(target)
	104	+ if string(data) != "new" {
	105	+ t.Errorf("content = %q, want new", data)
	106	+ }
	107	+ info, _ := os.Stat(target)
	108	+ if info.Mode().Perm() != 0o755 {
	109	+ t.Errorf("mode = %v, want 0755", info.Mode().Perm())
	110	+ }
	111	+ entries, _ := os.ReadDir(directory)
	112	+ if len(entries) != 1 {
	113	+ t.Errorf("directory holds %d entries, want only the target: a temporary was left behind", len(entries))
	114	+ }
	115	+}
	116	+
	117	+func TestLocalWriteFileAtomicFailsInADirectoryThatDoesNotExist(t *testing.T) {
	118	+ target := filepath.Join(t.TempDir(), "missing", "main.go")
	119	+ err := (fsys.Local{}).WriteFileAtomic(target, []byte("x"), 0o644)
	120	+ if !errors.Is(err, fs.ErrNotExist) {
	121	+ t.Errorf("err = %v, want fs.ErrNotExist", err)
	122	+ }
	123	+}
	124	+
	125	+func TestAMissingFileIsReportedAsNotExistByBothImplementations(t *testing.T) {
	126	+ for name, system := range map[string]fsys.FS{
	127	+ "local": fsys.Local{},
	128	+ "memory": fsystest.New("/"),
	129	+ } {
	130	+ missing := filepath.Join(t.TempDir(), "nope")
	131	+ if _, err := system.ReadFile(missing); !errors.Is(err, fs.ErrNotExist) {
	132	+ t.Errorf("%s ReadFile: %v, want fs.ErrNotExist", name, err)
	133	+ }
	134	+ if _, err := system.Stat(missing); !errors.Is(err, fs.ErrNotExist) {
	135	+ t.Errorf("%s Stat: %v, want fs.ErrNotExist", name, err)
	136	+ }
	137	+ }
	138	+}
	139	+
	140	+func ExampleUse() {
	141	+ remote := fsystest.New("/home/bob/project")
	142	+ remote.AddFile("/home/bob/project/hello.py", "print('hello')\n")
	143	+
	144	+ previous := fsys.Use(remote)
	145	+ defer fsys.Use(previous)
	146	+
	147	+ data, _ := fsys.ReadFile("hello.py")
	148	+ fmt.Print(string(data))
	149	+ // Output: print('hello')
	150	+}

++package fsys_test
++
++import (
++	"errors"
++	"fmt"
++	"io/fs"
++	"os"
++	"path/filepath"
++	"testing"
++
++	"rickub.com/turbo-editors/turbo-core/fsys"
++	"rickub.com/turbo-editors/turbo-core/fsys/fsystest"
++)
++
++// useMemory swaps an in-memory file system in for the test's duration.
++func useMemory(t *testing.T, working string) *fsystest.Memory {
++	t.Helper()
++	memory := fsystest.New(working)
++	previous := fsys.Use(memory)
++	t.Cleanup(func() { fsys.Use(previous) })
++	return memory
++}
++
++func TestTheDefaultFileSystemIsTheLocalDisk(t *testing.T) {
++	if !fsys.IsLocal() {
++		t.Fatalf("Current() = %T, want fsys.Local", fsys.Current())
++	}
++}
++
++func TestUseReplacesTheFileSystemAndReturnsThePreviousOne(t *testing.T) {
++	memory := fsystest.New("/remote")
++	previous := fsys.Use(memory)
++	defer fsys.Use(previous)
++
++	if _, ok := previous.(fsys.Local); !ok {
++		t.Errorf("previous = %T, want fsys.Local", previous)
++	}
++	if fsys.Current() != memory {
++		t.Errorf("Current() did not return the file system just given to Use")
++	}
++	if fsys.IsLocal() {
++		t.Errorf("IsLocal() = true with a memory file system in use")
++	}
++}
++
++func TestPackageFunctionsGoThroughTheCurrentFileSystem(t *testing.T) {
++	memory := useMemory(t, "/remote/project")
++	memory.AddFile("/remote/project/main.py", "print(1)\n")
++
++	data, err := fsys.ReadFile("main.py")
++	if err != nil || string(data) != "print(1)\n" {
++		t.Fatalf("ReadFile = %q, %v", data, err)
++	}
++	if err := fsys.MkdirAll("pkg/sub", 0o755); err != nil {
++		t.Fatal(err)
++	}
++	if err := fsys.WriteFileAtomic("pkg/sub/a.py", []byte("x = 1\n"), 0o600); err != nil {
++		t.Fatal(err)
++	}
++	if got, _ := memory.File("/remote/project/pkg/sub/a.py"); got != "x = 1\n" {
++		t.Errorf("written file = %q", got)
++	}
++	info, err := fsys.Stat("pkg")
++	if err != nil || !info.IsDir() {
++		t.Errorf("Stat(pkg) = %v, %v; want a directory", info, err)
++	}
++	entries, err := fsys.ReadDir(".")
++	if err != nil || len(entries) != 2 || entries[0].Name() != "main.py" || entries[1].Name() != "pkg" {
++		t.Errorf("ReadDir(.) = %v, %v", entries, err)
++	}
++	if working, _ := fsys.Getwd(); working != "/remote/project" {
++		t.Errorf("Getwd = %q", working)
++	}
++}
++
++func TestAbsResolvesAgainstTheCurrentFileSystemsWorkingDirectory(t *testing.T) {
++	useMemory(t, "/home/bob/app")
++
++	cases := map[string]string{
++		"main.py":        "/home/bob/app/main.py",
++		"../other/x.py":  "/home/bob/other/x.py",
++		"/etc/hosts":     "/etc/hosts",
++		"/srv//a/../b/c": "/srv/b/c",
++	}
++	for in, want := range cases {
++		if got, err := fsys.Abs(in); err != nil || got != want {
++			t.Errorf("Abs(%q) = %q, %v; want %q", in, got, err, want)
++		}
++	}
++}
++
++func TestLocalWriteFileAtomicReplacesTheContentWithTheGivenMode(t *testing.T) {
++	directory := t.TempDir()
++	target := filepath.Join(directory, "main.go")
++	if err := os.WriteFile(target, []byte("old"), 0o644); err != nil {
++		t.Fatal(err)
++	}
++
++	if err := (fsys.Local{}).WriteFileAtomic(target, []byte("new"), 0o755); err != nil {
++		t.Fatal(err)
++	}
++
++	data, _ := os.ReadFile(target)
++	if string(data) != "new" {
++		t.Errorf("content = %q, want new", data)
++	}
++	info, _ := os.Stat(target)
++	if info.Mode().Perm() != 0o755 {
++		t.Errorf("mode = %v, want 0755", info.Mode().Perm())
++	}
++	entries, _ := os.ReadDir(directory)
++	if len(entries) != 1 {
++		t.Errorf("directory holds %d entries, want only the target: a temporary was left behind", len(entries))
++	}
++}
++
++func TestLocalWriteFileAtomicFailsInADirectoryThatDoesNotExist(t *testing.T) {
++	target := filepath.Join(t.TempDir(), "missing", "main.go")
++	err := (fsys.Local{}).WriteFileAtomic(target, []byte("x"), 0o644)
++	if !errors.Is(err, fs.ErrNotExist) {
++		t.Errorf("err = %v, want fs.ErrNotExist", err)
++	}
++}
++
++func TestAMissingFileIsReportedAsNotExistByBothImplementations(t *testing.T) {
++	for name, system := range map[string]fsys.FS{
++		"local":  fsys.Local{},
++		"memory": fsystest.New("/"),
++	} {
++		missing := filepath.Join(t.TempDir(), "nope")
++		if _, err := system.ReadFile(missing); !errors.Is(err, fs.ErrNotExist) {
++			t.Errorf("%s ReadFile: %v, want fs.ErrNotExist", name, err)
++		}
++		if _, err := system.Stat(missing); !errors.Is(err, fs.ErrNotExist) {
++			t.Errorf("%s Stat: %v, want fs.ErrNotExist", name, err)
++		}
++	}
++}
++
++func ExampleUse() {
++	remote := fsystest.New("/home/bob/project")
++	remote.AddFile("/home/bob/project/hello.py", "print('hello')\n")
++
++	previous := fsys.Use(remote)
++	defer fsys.Use(previous)
++
++	data, _ := fsys.ReadFile("hello.py")
++	fmt.Print(string(data))
++	// Output: print('hello')
++}

added fsys/fsystest/memory.go +186 -0 Viewed

new file mode 100644
@@ -0,0 +1,186 @@
	1	+// Package fsystest provides an in-memory fsys.FS, for tests that must prove a
	2	+// package reads and writes through fsys and not straight to the disk.
	3	+//
	4	+// A test that uses it swaps it in with fsys.Use and puts the previous one
	5	+// back; a file found only in memory is proof the code under test went through
	6	+// fsys, because the disk never had it.
	7	+//
	8	+// memory := fsystest.New("/remote/project")
	9	+// memory.AddFile("/remote/project/main.go", "package main\n")
	10	+// t.Cleanup(func() { fsys.Use(fsys.Use(memory)) })
	11	+package fsystest
	12	+
	13	+import (
	14	+ "io/fs"
	15	+ "path"
	16	+ "sort"
	17	+ "strings"
	18	+ "sync"
	19	+ "time"
	20	+)
	21	+
	22	+// Memory is a file system held in a map. It is safe for concurrent use.
	23	+type Memory struct {
	24	+ mu sync.Mutex
	25	+ working string
	26	+ files map[string]*file
	27	+ dirs map[string]bool
	28	+}
	29	+
	30	+// file is one regular file: its bytes, its mode and when it was last written.
	31	+type file struct {
	32	+ data []byte
	33	+ mode fs.FileMode
	34	+ modified time.Time
	35	+}
	36	+
	37	+// New returns an empty file system whose working directory is working, which
	38	+// exists, as does every directory above it.
	39	+func New(working string) *Memory {
	40	+ m := &Memory{working: path.Clean(working), files: map[string]*file{}, dirs: map[string]bool{"/": true}}
	41	+ m.mkdirAll(m.working)
	42	+ return m
	43	+}
	44	+
	45	+// AddFile creates or replaces a file with mode 0644, making its directories.
	46	+func (m *Memory) AddFile(name, content string) {
	47	+ m.mu.Lock()
	48	+ defer m.mu.Unlock()
	49	+ name = m.abs(name)
	50	+ m.mkdirAll(path.Dir(name))
	51	+ m.write(name, []byte(content), 0o644)
	52	+}
	53	+
	54	+// File returns a file's content and whether it exists.
	55	+func (m *Memory) File(name string) (string, bool) {
	56	+ m.mu.Lock()
	57	+ defer m.mu.Unlock()
	58	+ f, ok := m.files[m.abs(name)]
	59	+ if !ok {
	60	+ return "", false
	61	+ }
	62	+ return string(f.data), true
	63	+}
	64	+
	65	+// Mode returns a file's permissions, or zero when it does not exist.
	66	+func (m *Memory) Mode(name string) fs.FileMode {
	67	+ m.mu.Lock()
	68	+ defer m.mu.Unlock()
	69	+ if f, ok := m.files[m.abs(name)]; ok {
	70	+ return f.mode
	71	+ }
	72	+ return 0
	73	+}
	74	+
	75	+// ReadFile implements fsys.FS.
	76	+func (m *Memory) ReadFile(name string) ([]byte, error) {
	77	+ m.mu.Lock()
	78	+ defer m.mu.Unlock()
	79	+ f, ok := m.files[m.abs(name)]
	80	+ if !ok {
	81	+ return nil, &fs.PathError{Op: "open", Path: name, Err: fs.ErrNotExist}
	82	+ }
	83	+ return append([]byte(nil), f.data...), nil
	84	+}
	85	+
	86	+// WriteFileAtomic implements fsys.FS.
	87	+func (m *Memory) WriteFileAtomic(name string, data []byte, perm fs.FileMode) error {
	88	+ m.mu.Lock()
	89	+ defer m.mu.Unlock()
	90	+ name = m.abs(name)
	91	+ if !m.dirs[path.Dir(name)] {
	92	+ return &fs.PathError{Op: "write", Path: name, Err: fs.ErrNotExist}
	93	+ }
	94	+ m.write(name, data, perm)
	95	+ return nil
	96	+}
	97	+
	98	+// ReadDir implements fsys.FS.
	99	+func (m *Memory) ReadDir(name string) ([]fs.DirEntry, error) {
	100	+ m.mu.Lock()
	101	+ defer m.mu.Unlock()
	102	+ directory := m.abs(name)
	103	+ if !m.dirs[directory] {
	104	+ return nil, &fs.PathError{Op: "readdir", Path: name, Err: fs.ErrNotExist}
	105	+ }
	106	+
	107	+ var entries []fs.DirEntry
	108	+ for child, f := range m.files {
	109	+ if path.Dir(child) == directory {
	110	+ entries = append(entries, fs.FileInfoToDirEntry(fileInfo{name: path.Base(child), size: int64(len(f.data)), mode: f.mode, modified: f.modified}))
	111	+ }
	112	+ }
	113	+ for child := range m.dirs {
	114	+ if child != directory && path.Dir(child) == directory {
	115	+ entries = append(entries, fs.FileInfoToDirEntry(fileInfo{name: path.Base(child), mode: fs.ModeDir \| 0o755}))
	116	+ }
	117	+ }
	118	+ sort.Slice(entries, func(i, j int) bool { return entries[i].Name() < entries[j].Name() })
	119	+ return entries, nil
	120	+}
	121	+
	122	+// Stat implements fsys.FS.
	123	+func (m *Memory) Stat(name string) (fs.FileInfo, error) {
	124	+ m.mu.Lock()
	125	+ defer m.mu.Unlock()
	126	+ absolute := m.abs(name)
	127	+ if f, ok := m.files[absolute]; ok {
	128	+ return fileInfo{name: path.Base(absolute), size: int64(len(f.data)), mode: f.mode, modified: f.modified}, nil
	129	+ }
	130	+ if m.dirs[absolute] {
	131	+ return fileInfo{name: path.Base(absolute), mode: fs.ModeDir \| 0o755}, nil
	132	+ }
	133	+ return nil, &fs.PathError{Op: "stat", Path: name, Err: fs.ErrNotExist}
	134	+}
	135	+
	136	+// MkdirAll implements fsys.FS.
	137	+func (m *Memory) MkdirAll(name string, _ fs.FileMode) error {
	138	+ m.mu.Lock()
	139	+ defer m.mu.Unlock()
	140	+ m.mkdirAll(m.abs(name))
	141	+ return nil
	142	+}
	143	+
	144	+// Getwd implements fsys.FS.
	145	+func (m *Memory) Getwd() (string, error) { return m.working, nil }
	146	+
	147	+// abs resolves a path against the working directory. The caller holds mu.
	148	+func (m *Memory) abs(name string) string {
	149	+ if strings.HasPrefix(name, "/") {
	150	+ return path.Clean(name)
	151	+ }
	152	+ return path.Join(m.working, name)
	153	+}
	154	+
	155	+// mkdirAll records a directory and its parents. The caller holds mu.
	156	+func (m *Memory) mkdirAll(directory string) {
	157	+ for directory != "/" && directory != "." {
	158	+ m.dirs[directory] = true
	159	+ directory = path.Dir(directory)
	160	+ }
	161	+}
	162	+
	163	+// write stores a file, each write a nanosecond later than the last so that a
	164	+// watcher comparing stamps sees every change. The caller holds mu.
	165	+func (m *Memory) write(name string, data []byte, mode fs.FileMode) {
	166	+ stamp := time.Unix(0, 0)
	167	+ if previous, ok := m.files[name]; ok {
	168	+ stamp = previous.modified.Add(time.Nanosecond)
	169	+ }
	170	+ m.files[name] = &file{data: append([]byte(nil), data...), mode: mode, modified: stamp}
	171	+}
	172	+
	173	+// fileInfo is what Stat and ReadDir describe a file or directory with.
	174	+type fileInfo struct {
	175	+ name string
	176	+ size int64
	177	+ mode fs.FileMode
	178	+ modified time.Time
	179	+}
	180	+
	181	+func (i fileInfo) Name() string { return i.name }
	182	+func (i fileInfo) Size() int64 { return i.size }
	183	+func (i fileInfo) Mode() fs.FileMode { return i.mode }
	184	+func (i fileInfo) ModTime() time.Time { return i.modified }
	185	+func (i fileInfo) IsDir() bool { return i.mode.IsDir() }
	186	+func (i fileInfo) Sys() any { return nil }

++// Package fsystest provides an in-memory fsys.FS, for tests that must prove a
++// package reads and writes through fsys and not straight to the disk.
++//
++// A test that uses it swaps it in with fsys.Use and puts the previous one
++// back; a file found only in memory is proof the code under test went through
++// fsys, because the disk never had it.
++//
++//	memory := fsystest.New("/remote/project")
++//	memory.AddFile("/remote/project/main.go", "package main\n")
++//	t.Cleanup(func() { fsys.Use(fsys.Use(memory)) })
++package fsystest
++
++import (
++	"io/fs"
++	"path"
++	"sort"
++	"strings"
++	"sync"
++	"time"
++)
++
++// Memory is a file system held in a map. It is safe for concurrent use.
++type Memory struct {
++	mu      sync.Mutex
++	working string
++	files   map[string]*file
++	dirs    map[string]bool
++}
++
++// file is one regular file: its bytes, its mode and when it was last written.
++type file struct {
++	data     []byte
++	mode     fs.FileMode
++	modified time.Time
++}
++
++// New returns an empty file system whose working directory is working, which
++// exists, as does every directory above it.
++func New(working string) *Memory {
++	m := &Memory{working: path.Clean(working), files: map[string]*file{}, dirs: map[string]bool{"/": true}}
++	m.mkdirAll(m.working)
++	return m
++}
++
++// AddFile creates or replaces a file with mode 0644, making its directories.
++func (m *Memory) AddFile(name, content string) {
++	m.mu.Lock()
++	defer m.mu.Unlock()
++	name = m.abs(name)
++	m.mkdirAll(path.Dir(name))
++	m.write(name, []byte(content), 0o644)
++}
++
++// File returns a file's content and whether it exists.
++func (m *Memory) File(name string) (string, bool) {
++	m.mu.Lock()
++	defer m.mu.Unlock()
++	f, ok := m.files[m.abs(name)]
++	if !ok {
++		return "", false
++	}
++	return string(f.data), true
++}
++
++// Mode returns a file's permissions, or zero when it does not exist.
++func (m *Memory) Mode(name string) fs.FileMode {
++	m.mu.Lock()
++	defer m.mu.Unlock()
++	if f, ok := m.files[m.abs(name)]; ok {
++		return f.mode
++	}
++	return 0
++}
++
++// ReadFile implements fsys.FS.
++func (m *Memory) ReadFile(name string) ([]byte, error) {
++	m.mu.Lock()
++	defer m.mu.Unlock()
++	f, ok := m.files[m.abs(name)]
++	if !ok {
++		return nil, &fs.PathError{Op: "open", Path: name, Err: fs.ErrNotExist}
++	}
++	return append([]byte(nil), f.data...), nil
++}
++
++// WriteFileAtomic implements fsys.FS.
++func (m *Memory) WriteFileAtomic(name string, data []byte, perm fs.FileMode) error {
++	m.mu.Lock()
++	defer m.mu.Unlock()
++	name = m.abs(name)
++	if !m.dirs[path.Dir(name)] {
++		return &fs.PathError{Op: "write", Path: name, Err: fs.ErrNotExist}
++	}
++	m.write(name, data, perm)
++	return nil
++}
++
++// ReadDir implements fsys.FS.
++func (m *Memory) ReadDir(name string) ([]fs.DirEntry, error) {
++	m.mu.Lock()
++	defer m.mu.Unlock()
++	directory := m.abs(name)
++	if !m.dirs[directory] {
++		return nil, &fs.PathError{Op: "readdir", Path: name, Err: fs.ErrNotExist}
++	}
++
++	var entries []fs.DirEntry
++	for child, f := range m.files {
++		if path.Dir(child) == directory {
++			entries = append(entries, fs.FileInfoToDirEntry(fileInfo{name: path.Base(child), size: int64(len(f.data)), mode: f.mode, modified: f.modified}))
++		}
++	}
++	for child := range m.dirs {
++		if child != directory && path.Dir(child) == directory {
++			entries = append(entries, fs.FileInfoToDirEntry(fileInfo{name: path.Base(child), mode: fs.ModeDir | 0o755}))
++		}
++	}
++	sort.Slice(entries, func(i, j int) bool { return entries[i].Name() < entries[j].Name() })
++	return entries, nil
++}
++
++// Stat implements fsys.FS.
++func (m *Memory) Stat(name string) (fs.FileInfo, error) {
++	m.mu.Lock()
++	defer m.mu.Unlock()
++	absolute := m.abs(name)
++	if f, ok := m.files[absolute]; ok {
++		return fileInfo{name: path.Base(absolute), size: int64(len(f.data)), mode: f.mode, modified: f.modified}, nil
++	}
++	if m.dirs[absolute] {
++		return fileInfo{name: path.Base(absolute), mode: fs.ModeDir | 0o755}, nil
++	}
++	return nil, &fs.PathError{Op: "stat", Path: name, Err: fs.ErrNotExist}
++}
++
++// MkdirAll implements fsys.FS.
++func (m *Memory) MkdirAll(name string, _ fs.FileMode) error {
++	m.mu.Lock()
++	defer m.mu.Unlock()
++	m.mkdirAll(m.abs(name))
++	return nil
++}
++
++// Getwd implements fsys.FS.
++func (m *Memory) Getwd() (string, error) { return m.working, nil }
++
++// abs resolves a path against the working directory. The caller holds mu.
++func (m *Memory) abs(name string) string {
++	if strings.HasPrefix(name, "/") {
++		return path.Clean(name)
++	}
++	return path.Join(m.working, name)
++}
++
++// mkdirAll records a directory and its parents. The caller holds mu.
++func (m *Memory) mkdirAll(directory string) {
++	for directory != "/" && directory != "." {
++		m.dirs[directory] = true
++		directory = path.Dir(directory)
++	}
++}
++
++// write stores a file, each write a nanosecond later than the last so that a
++// watcher comparing stamps sees every change. The caller holds mu.
++func (m *Memory) write(name string, data []byte, mode fs.FileMode) {
++	stamp := time.Unix(0, 0)
++	if previous, ok := m.files[name]; ok {
++		stamp = previous.modified.Add(time.Nanosecond)
++	}
++	m.files[name] = &file{data: append([]byte(nil), data...), mode: mode, modified: stamp}
++}
++
++// fileInfo is what Stat and ReadDir describe a file or directory with.
++type fileInfo struct {
++	name     string
++	size     int64
++	mode     fs.FileMode
++	modified time.Time
++}
++
++func (i fileInfo) Name() string       { return i.name }
++func (i fileInfo) Size() int64        { return i.size }
++func (i fileInfo) Mode() fs.FileMode  { return i.mode }
++func (i fileInfo) ModTime() time.Time { return i.modified }
++func (i fileInfo) IsDir() bool        { return i.mode.IsDir() }
++func (i fileInfo) Sys() any           { return nil }

added fsys/fsystest/memory_test.go +46 -0 Viewed

new file mode 100644
@@ -0,0 +1,46 @@
	1	+package fsystest
	2	+
	3	+import (
	4	+ "errors"
	5	+ "io/fs"
	6	+ "testing"
	7	+)
	8	+
	9	+func TestEachWriteMovesTheModificationTimeOn(t *testing.T) {
	10	+ memory := New("/p")
	11	+ memory.AddFile("a", "1")
	12	+ before, _ := memory.Stat("a")
	13	+ if err := memory.WriteFileAtomic("a", []byte("2"), 0o644); err != nil {
	14	+ t.Fatal(err)
	15	+ }
	16	+ after, _ := memory.Stat("a")
	17	+ if !after.ModTime().After(before.ModTime()) {
	18	+ t.Errorf("ModTime did not move: %v then %v", before.ModTime(), after.ModTime())
	19	+ }
	20	+}
	21	+
	22	+func TestWritingIntoAMissingDirectoryFails(t *testing.T) {
	23	+ memory := New("/p")
	24	+ if err := memory.WriteFileAtomic("/p/nope/a", []byte("x"), 0o644); !errors.Is(err, fs.ErrNotExist) {
	25	+ t.Errorf("err = %v, want fs.ErrNotExist", err)
	26	+ }
	27	+}
	28	+
	29	+func TestModeIsWhatTheWriteAskedFor(t *testing.T) {
	30	+ memory := New("/p")
	31	+ if err := memory.WriteFileAtomic("a", []byte("x"), 0o600); err != nil {
	32	+ t.Fatal(err)
	33	+ }
	34	+ if memory.Mode("a") != 0o600 {
	35	+ t.Errorf("Mode = %v, want 0600", memory.Mode("a"))
	36	+ }
	37	+ if memory.Mode("missing") != 0 {
	38	+ t.Errorf("Mode of a missing file = %v, want 0", memory.Mode("missing"))
	39	+ }
	40	+}
	41	+
	42	+func TestReadDirOfAMissingDirectoryFails(t *testing.T) {
	43	+ if _, err := New("/p").ReadDir("/q"); !errors.Is(err, fs.ErrNotExist) {
	44	+ t.Errorf("err = %v, want fs.ErrNotExist", err)
	45	+ }
	46	+}

++package fsystest
++
++import (
++	"errors"
++	"io/fs"
++	"testing"
++)
++
++func TestEachWriteMovesTheModificationTimeOn(t *testing.T) {
++	memory := New("/p")
++	memory.AddFile("a", "1")
++	before, _ := memory.Stat("a")
++	if err := memory.WriteFileAtomic("a", []byte("2"), 0o644); err != nil {
++		t.Fatal(err)
++	}
++	after, _ := memory.Stat("a")
++	if !after.ModTime().After(before.ModTime()) {
++		t.Errorf("ModTime did not move: %v then %v", before.ModTime(), after.ModTime())
++	}
++}
++
++func TestWritingIntoAMissingDirectoryFails(t *testing.T) {
++	memory := New("/p")
++	if err := memory.WriteFileAtomic("/p/nope/a", []byte("x"), 0o644); !errors.Is(err, fs.ErrNotExist) {
++		t.Errorf("err = %v, want fs.ErrNotExist", err)
++	}
++}
++
++func TestModeIsWhatTheWriteAskedFor(t *testing.T) {
++	memory := New("/p")
++	if err := memory.WriteFileAtomic("a", []byte("x"), 0o600); err != nil {
++		t.Fatal(err)
++	}
++	if memory.Mode("a") != 0o600 {
++		t.Errorf("Mode = %v, want 0600", memory.Mode("a"))
++	}
++	if memory.Mode("missing") != 0 {
++		t.Errorf("Mode of a missing file = %v, want 0", memory.Mode("missing"))
++	}
++}
++
++func TestReadDirOfAMissingDirectoryFails(t *testing.T) {
++	if _, err := New("/p").ReadDir("/q"); !errors.Is(err, fs.ErrNotExist) {
++		t.Errorf("err = %v, want fs.ErrNotExist", err)
++	}
++}

added fsys/local.go +64 -0 Viewed

new file mode 100644
@@ -0,0 +1,64 @@
	1	+package fsys
	2	+
	3	+import (
	4	+ "io/fs"
	5	+ "os"
	6	+ "path/filepath"
	7	+)
	8	+
	9	+// Local is the disk of the machine the editor runs on, through package os.
	10	+// It is the default, and what every editor used before -ssh existed.
	11	+//
	12	+// fsys.Use(fsys.Local{})
	13	+type Local struct{}
	14	+
	15	+// ReadFile is os.ReadFile.
	16	+func (Local) ReadFile(name string) ([]byte, error) { return os.ReadFile(name) }
	17	+
	18	+// ReadDir is os.ReadDir.
	19	+func (Local) ReadDir(name string) ([]fs.DirEntry, error) { return os.ReadDir(name) }
	20	+
	21	+// Stat is os.Stat.
	22	+func (Local) Stat(name string) (fs.FileInfo, error) { return os.Stat(name) }
	23	+
	24	+// MkdirAll is os.MkdirAll.
	25	+func (Local) MkdirAll(name string, perm fs.FileMode) error { return os.MkdirAll(name, perm) }
	26	+
	27	+// Getwd is os.Getwd.
	28	+func (Local) Getwd() (string, error) { return os.Getwd() }
	29	+
	30	+// WriteFileAtomic writes to a temporary file beside name and renames it over
	31	+// name. The temporary shares the directory because a rename is only atomic
	32	+// within one file system; its name starts with a dot and the target's name so
	33	+// that one left behind by a crash is recognisable.
	34	+func (Local) WriteFileAtomic(name string, data []byte, perm fs.FileMode) error {
	35	+ temporary, err := os.CreateTemp(filepath.Dir(name), "."+filepath.Base(name)+".*")
	36	+ if err != nil {
	37	+ return err
	38	+ }
	39	+ temporaryName := temporary.Name()
	40	+
	41	+ // From here on every failure must remove the temporary file, or a failed
	42	+ // save would litter the user's directory. After the rename this is a no-op.
	43	+ defer os.Remove(temporaryName)
	44	+
	45	+ if err := writeAndClose(temporary, data); err != nil {
	46	+ return err
	47	+ }
	48	+ // CreateTemp makes the file readable by its owner only, and the rename
	49	+ // would carry that over to the file being replaced.
	50	+ if err := os.Chmod(temporaryName, perm); err != nil {
	51	+ return err
	52	+ }
	53	+ return os.Rename(temporaryName, name)
	54	+}
	55	+
	56	+// writeAndClose writes a file and closes it, closing it either way. The close
	57	+// is what reports a write that failed on its way out, so its error counts.
	58	+func writeAndClose(f *os.File, data []byte) error {
	59	+ if _, err := f.Write(data); err != nil {
	60	+ f.Close()
	61	+ return err
	62	+ }
	63	+ return f.Close()
	64	+}

++package fsys
++
++import (
++	"io/fs"
++	"os"
++	"path/filepath"
++)
++
++// Local is the disk of the machine the editor runs on, through package os.
++// It is the default, and what every editor used before -ssh existed.
++//
++//	fsys.Use(fsys.Local{})
++type Local struct{}
++
++// ReadFile is os.ReadFile.
++func (Local) ReadFile(name string) ([]byte, error) { return os.ReadFile(name) }
++
++// ReadDir is os.ReadDir.
++func (Local) ReadDir(name string) ([]fs.DirEntry, error) { return os.ReadDir(name) }
++
++// Stat is os.Stat.
++func (Local) Stat(name string) (fs.FileInfo, error) { return os.Stat(name) }
++
++// MkdirAll is os.MkdirAll.
++func (Local) MkdirAll(name string, perm fs.FileMode) error { return os.MkdirAll(name, perm) }
++
++// Getwd is os.Getwd.
++func (Local) Getwd() (string, error) { return os.Getwd() }
++
++// WriteFileAtomic writes to a temporary file beside name and renames it over
++// name. The temporary shares the directory because a rename is only atomic
++// within one file system; its name starts with a dot and the target's name so
++// that one left behind by a crash is recognisable.
++func (Local) WriteFileAtomic(name string, data []byte, perm fs.FileMode) error {
++	temporary, err := os.CreateTemp(filepath.Dir(name), "."+filepath.Base(name)+".*")
++	if err != nil {
++		return err
++	}
++	temporaryName := temporary.Name()
++
++	// From here on every failure must remove the temporary file, or a failed
++	// save would litter the user's directory. After the rename this is a no-op.
++	defer os.Remove(temporaryName)
++
++	if err := writeAndClose(temporary, data); err != nil {
++		return err
++	}
++	// CreateTemp makes the file readable by its owner only, and the rename
++	// would carry that over to the file being replaced.
++	if err := os.Chmod(temporaryName, perm); err != nil {
++		return err
++	}
++	return os.Rename(temporaryName, name)
++}
++
++// writeAndClose writes a file and closes it, closing it either way. The close
++// is what reports a write that failed on its way out, so its error counts.
++func writeAndClose(f *os.File, data []byte) error {
++	if _, err := f.Write(data); err != nil {
++		f.Close()
++		return err
++	}
++	return f.Close()
++}

modified go.mod +6 -3 Viewed

@@ -5,13 +5,16 @@ go 1.26.1
5	5	require (
6	6	github.com/BurntSushi/toml v1.6.0
7	7	github.com/gdamore/tcell/v2 v2.13.10
8		- golang.org/x/sys v0.38.0
	8	+ github.com/pkg/sftp v1.13.11
	9	+ golang.org/x/sys v0.47.0
9	10	)
10	11
11	12	require (
12	13	github.com/gdamore/encoding v1.0.1 // indirect
	14	+ github.com/kr/fs v0.1.0 // indirect
13	15	github.com/lucasb-eyer/go-colorful v1.3.0 // indirect
14	16	github.com/rivo/uniseg v0.4.7 // indirect
15		- golang.org/x/term v0.37.0 // indirect
16		- golang.org/x/text v0.31.0 // indirect
	17	+ golang.org/x/crypto v0.54.0 // indirect
	18	+ golang.org/x/term v0.45.0 // indirect
	19	+ golang.org/x/text v0.40.0 // indirect
17	20	)

  require (
  	github.com/BurntSushi/toml v1.6.0
  	github.com/gdamore/tcell/v2 v2.13.10
--	golang.org/x/sys v0.38.0
++	github.com/pkg/sftp v1.13.11
++	golang.org/x/sys v0.47.0
  )
  require (
  	github.com/gdamore/encoding v1.0.1 // indirect
++	github.com/kr/fs v0.1.0 // indirect
  	github.com/lucasb-eyer/go-colorful v1.3.0 // indirect
  	github.com/rivo/uniseg v0.4.7 // indirect
--	golang.org/x/term v0.37.0 // indirect
++	golang.org/x/crypto v0.54.0 // indirect
--	golang.org/x/text v0.31.0 // indirect
++	golang.org/x/term v0.45.0 // indirect
++	golang.org/x/text v0.40.0 // indirect
  )

modified go.sum +20 -6 Viewed

@@ -1,16 +1,28 @@
1	1	github.com/BurntSushi/toml v1.6.0 h1:dRaEfpa2VI55EwlIW72hMRHdWouJeRF7TPYhI+AUQjk=
2	2	github.com/BurntSushi/toml v1.6.0/go.mod h1:ukJfTF/6rtPPRCnwkur4qwRxa8vTRFBF0uk2lLoLwho=
	3	+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
	4	+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
3	5	github.com/gdamore/encoding v1.0.1 h1:YzKZckdBL6jVt2Gc+5p82qhrGiqMdG/eNs6Wy0u3Uhw=
4	6	github.com/gdamore/encoding v1.0.1/go.mod h1:0Z0cMFinngz9kS1QfMjCP8TY7em3bZYeeklsSDPivEo=
5	7	github.com/gdamore/tcell/v2 v2.13.10 h1:Afs3JKt83HnhuUKdZ3MnxUgOqQRWftj5JyDqv1LLynA=
6	8	github.com/gdamore/tcell/v2 v2.13.10/go.mod h1:+Wfe208WDdB7INEtCsNrAN6O2m+wsTPk1RAovjaILlo=
	9	+github.com/kr/fs v0.1.0 h1:Jskdu9ieNAYnjxsi0LbQp1ulIKZV1LAFgK1tWhpZgl8=
	10	+github.com/kr/fs v0.1.0/go.mod h1:FFnZGqtBN9Gxj7eW1uZ42v5BccTP0vu6NEaFoC2HwRg=
7	11	github.com/lucasb-eyer/go-colorful v1.3.0 h1:2/yBRLdWBZKrf7gB40FoiKfAWYQ0lqNcbuQwVHXptag=
8	12	github.com/lucasb-eyer/go-colorful v1.3.0/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
	13	+github.com/pkg/sftp v1.13.11 h1:0N92SLTB8JqASJB14ZLHHzFnBV8mG9zw4K7jghEFWuE=
	14	+github.com/pkg/sftp v1.13.11/go.mod h1:uNkH9roSXglNJqM+glJJi+TQXQUm0fXFWqCFmT8hsN0=
	15	+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
	16	+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
9	17	github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ=
10	18	github.com/rivo/uniseg v0.4.7/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88=
	19	+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
	20	+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
11	21	github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
12	22	golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
13	23	golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc=
	24	+golang.org/x/crypto v0.54.0 h1:YLIA59K4fiNzHzjnZt2tUJQjQtUWfWbeHBqKtk3eScw=
	25	+golang.org/x/crypto v0.54.0/go.mod h1:KWL8ny2AZdGR2cWmzeHrp2azQPGogOv+HeQaVEXC2dk=
14	26	golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4=
15	27	golang.org/x/mod v0.8.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
16	28	golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
@@ -26,22 +38,24 @@ golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBc
26	38	golang.org/x/sys v0.0.0-20220520151302-bc2c85ada10a/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
27	39	golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
28	40	golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
29		-golang.org/x/sys v0.38.0 h1:3yZWxaJjBmCWXqhN1qh02AkOnCQ1poK6oF+a7xWL6Gc=
30		-golang.org/x/sys v0.38.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
	41	+golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
	42	+golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
31	43	golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
32	44	golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8=
33	45	golang.org/x/term v0.5.0/go.mod h1:jMB1sMXY+tzblOD4FWmEbocvup2/aLOaQEp7JmGp78k=
34		-golang.org/x/term v0.37.0 h1:8EGAD0qCmHYZg6J17DvsMy9/wJ7/D/4pV/wfnld5lTU=
35		-golang.org/x/term v0.37.0/go.mod h1:5pB4lxRNYYVZuTLmy8oR2BH8dflOR+IbTYFD8fi3254=
	46	+golang.org/x/term v0.45.0 h1:NwWyBmoJCbfTHpxrWoZ9C6/VxOf7ic219I8xZZFdrf0=
	47	+golang.org/x/term v0.45.0/go.mod h1:9aqxs0blBcrm/n0L9QW0aRVD+ktan8ssZromtqJC43w=
36	48	golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
37	49	golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
38	50	golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=
39	51	golang.org/x/text v0.7.0/go.mod h1:mrYo+phRRbMaCq/xk9113O4dZlRixOauAjOtrjsXDZ8=
40	52	golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
41		-golang.org/x/text v0.31.0 h1:aC8ghyu4JhP8VojJ2lEHBnochRno1sgL6nEi9WGFGMM=
42		-golang.org/x/text v0.31.0/go.mod h1:tKRAlv61yKIjGGHX/4tP1LTbc13YSec1pxVEWXzfoeM=
	53	+golang.org/x/text v0.40.0 h1:Ub2Z6/xjgF1WrYQz2nuITOEegKFtiIy+rieRJ5lHZKs=
	54	+golang.org/x/text v0.40.0/go.mod h1:hpnzDAfGV753zIKo+wk3u1bVKCGPbrnF7+7LBF/UHVY=
43	55	golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
44	56	golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
45	57	golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc=
46	58	golang.org/x/tools v0.6.0/go.mod h1:Xwgl3UAJ/d3gWutnCtw505GrjyAbvKui8lOU390QaIU=
47	59	golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
	60	+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
	61	+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

  github.com/BurntSushi/toml v1.6.0 h1:dRaEfpa2VI55EwlIW72hMRHdWouJeRF7TPYhI+AUQjk=
  github.com/BurntSushi/toml v1.6.0/go.mod h1:ukJfTF/6rtPPRCnwkur4qwRxa8vTRFBF0uk2lLoLwho=
++github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
++github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
  github.com/gdamore/encoding v1.0.1 h1:YzKZckdBL6jVt2Gc+5p82qhrGiqMdG/eNs6Wy0u3Uhw=
  github.com/gdamore/encoding v1.0.1/go.mod h1:0Z0cMFinngz9kS1QfMjCP8TY7em3bZYeeklsSDPivEo=
  github.com/gdamore/tcell/v2 v2.13.10 h1:Afs3JKt83HnhuUKdZ3MnxUgOqQRWftj5JyDqv1LLynA=
  github.com/gdamore/tcell/v2 v2.13.10/go.mod h1:+Wfe208WDdB7INEtCsNrAN6O2m+wsTPk1RAovjaILlo=
++github.com/kr/fs v0.1.0 h1:Jskdu9ieNAYnjxsi0LbQp1ulIKZV1LAFgK1tWhpZgl8=
++github.com/kr/fs v0.1.0/go.mod h1:FFnZGqtBN9Gxj7eW1uZ42v5BccTP0vu6NEaFoC2HwRg=
  github.com/lucasb-eyer/go-colorful v1.3.0 h1:2/yBRLdWBZKrf7gB40FoiKfAWYQ0lqNcbuQwVHXptag=
  github.com/lucasb-eyer/go-colorful v1.3.0/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
++github.com/pkg/sftp v1.13.11 h1:0N92SLTB8JqASJB14ZLHHzFnBV8mG9zw4K7jghEFWuE=
++github.com/pkg/sftp v1.13.11/go.mod h1:uNkH9roSXglNJqM+glJJi+TQXQUm0fXFWqCFmT8hsN0=
++github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
++github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
  github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ=
  github.com/rivo/uniseg v0.4.7/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88=
++github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
++github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
  github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
  golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
  golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc=
++golang.org/x/crypto v0.54.0 h1:YLIA59K4fiNzHzjnZt2tUJQjQtUWfWbeHBqKtk3eScw=
++golang.org/x/crypto v0.54.0/go.mod h1:KWL8ny2AZdGR2cWmzeHrp2azQPGogOv+HeQaVEXC2dk=
  golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4=
  golang.org/x/mod v0.8.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
  golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
  golang.org/x/sys v0.0.0-20220520151302-bc2c85ada10a/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
  golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
  golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
--golang.org/x/sys v0.38.0 h1:3yZWxaJjBmCWXqhN1qh02AkOnCQ1poK6oF+a7xWL6Gc=
++golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
--golang.org/x/sys v0.38.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
++golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
  golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
  golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8=
  golang.org/x/term v0.5.0/go.mod h1:jMB1sMXY+tzblOD4FWmEbocvup2/aLOaQEp7JmGp78k=
--golang.org/x/term v0.37.0 h1:8EGAD0qCmHYZg6J17DvsMy9/wJ7/D/4pV/wfnld5lTU=
++golang.org/x/term v0.45.0 h1:NwWyBmoJCbfTHpxrWoZ9C6/VxOf7ic219I8xZZFdrf0=
--golang.org/x/term v0.37.0/go.mod h1:5pB4lxRNYYVZuTLmy8oR2BH8dflOR+IbTYFD8fi3254=
++golang.org/x/term v0.45.0/go.mod h1:9aqxs0blBcrm/n0L9QW0aRVD+ktan8ssZromtqJC43w=
  golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
  golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
  golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=
  golang.org/x/text v0.7.0/go.mod h1:mrYo+phRRbMaCq/xk9113O4dZlRixOauAjOtrjsXDZ8=
  golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
--golang.org/x/text v0.31.0 h1:aC8ghyu4JhP8VojJ2lEHBnochRno1sgL6nEi9WGFGMM=
++golang.org/x/text v0.40.0 h1:Ub2Z6/xjgF1WrYQz2nuITOEegKFtiIy+rieRJ5lHZKs=
--golang.org/x/text v0.31.0/go.mod h1:tKRAlv61yKIjGGHX/4tP1LTbc13YSec1pxVEWXzfoeM=
++golang.org/x/text v0.40.0/go.mod h1:hpnzDAfGV753zIKo+wk3u1bVKCGPbrnF7+7LBF/UHVY=
  golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
  golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
  golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc=
  golang.org/x/tools v0.6.0/go.mod h1:Xwgl3UAJ/d3gWutnCtw505GrjyAbvKui8lOU390QaIU=
  golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
++gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
++gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

modified projectfile/README.md +2 -0 Viewed

@@ -22,6 +22,8 @@ The write goes to a temporary file in the same directory as its destination,
22	22
23	23	The destination's directory is created if it is not there, so a caller does not have to.
24	24
	25	+Both the directory and the write go through `fsys` (`MkdirAll`, `WriteFileAtomic`), so under `-ssh` the file is written on the remote machine, with the same temporary-then-rename guarantee over SFTP.
	26	+
25	27	## Public API
26	28
27	29	\| Name \| What it does \|

  The destination's directory is created if it is not there, so a caller does not have to.
++Both the directory and the write go through `fsys` (`MkdirAll`, `WriteFileAtomic`), so under `-ssh` the file is written on the remote machine, with the same temporary-then-rename guarantee over SFTP.
++
  ## Public API
  | Name | What it does |

added projectfile/fsys_test.go +24 -0 Viewed

new file mode 100644
@@ -0,0 +1,24 @@
	1	+package projectfile
	2	+
	3	+import (
	4	+ "testing"
	5	+
	6	+ "rickub.com/turbo-editors/turbo-core/fsys"
	7	+ "rickub.com/turbo-editors/turbo-core/fsys/fsystest"
	8	+)
	9	+
	10	+func TestWriteGoesThroughTheCurrentFileSystemAndMakesTheDirectory(t *testing.T) {
	11	+ memory := fsystest.New("/remote/project")
	12	+ previous := fsys.Use(memory)
	13	+ t.Cleanup(func() { fsys.Use(previous) })
	14	+
	15	+ if err := Write("/remote/project/.turbo-test/tools.toml", []byte("[[tool]]\n")); err != nil {
	16	+ t.Fatal(err)
	17	+ }
	18	+ if got, ok := memory.File("/remote/project/.turbo-test/tools.toml"); !ok \|\| got != "[[tool]]\n" {
	19	+ t.Errorf("file = %q, %v", got, ok)
	20	+ }
	21	+ if mode := memory.Mode("/remote/project/.turbo-test/tools.toml"); mode != fileMode {
	22	+ t.Errorf("mode = %v, want %v", mode, fileMode)
	23	+ }
	24	+}

++package projectfile
++
++import (
++	"testing"
++
++	"rickub.com/turbo-editors/turbo-core/fsys"
++	"rickub.com/turbo-editors/turbo-core/fsys/fsystest"
++)
++
++func TestWriteGoesThroughTheCurrentFileSystemAndMakesTheDirectory(t *testing.T) {
++	memory := fsystest.New("/remote/project")
++	previous := fsys.Use(memory)
++	t.Cleanup(func() { fsys.Use(previous) })
++
++	if err := Write("/remote/project/.turbo-test/tools.toml", []byte("[[tool]]\n")); err != nil {
++		t.Fatal(err)
++	}
++	if got, ok := memory.File("/remote/project/.turbo-test/tools.toml"); !ok || got != "[[tool]]\n" {
++		t.Errorf("file = %q, %v", got, ok)
++	}
++	if mode := memory.Mode("/remote/project/.turbo-test/tools.toml"); mode != fileMode {
++		t.Errorf("mode = %v, want %v", mode, fileMode)
++	}
++}

modified projectfile/projectfile.go +6 -33 Viewed

@@ -13,8 +13,9 @@ package projectfile
13	13
14	14	import (
15	15	"fmt"
16		- "os"
17	16	"path/filepath"
	17	+
	18	+ "rickub.com/turbo-editors/turbo-core/fsys"
18	19	)
19	20
20	21	// fileMode is what a project's configuration file is created with: readable by
@@ -45,39 +46,11 @@ func Write(path string, data []byte) error {
45	46	return nil
46	47	}
47	48
48		-// write does the work, leaving the error to be named by Write.
	49	+// write does the work, leaving the error to be named by Write. It goes through
	50	+// fsys, so under -ssh the project's files are written on the remote machine.
49	51	func write(path string, data []byte) error {
50		- directory := filepath.Dir(path)
51		- if err := os.MkdirAll(directory, dirMode); err != nil {
52		- return err
53		- }
54		-
55		- temporary, err := os.CreateTemp(directory, ".projectfile-*.toml")
56		- if err != nil {
57		- return err
58		- }
59		- name := temporary.Name()
60		- defer os.Remove(name) // a no-op once the rename below has succeeded
61		-
62		- if err := writeAndClose(temporary, data); err != nil {
63		- return err
64		- }
65		- // CreateTemp makes the file readable by its owner only, and the rename
66		- // would carry that through to a file a team is meant to share.
67		- if err := os.Chmod(name, fileMode); err != nil {
68		- return err
69		- }
70		- return os.Rename(name, path)
71		-}
72		-
73		-// writeAndClose writes a file and closes it, closing it either way.
74		-//
75		-// The close is what reports a write that failed on its way out of the buffer,
76		-// so its error matters as much as the write's.
77		-func writeAndClose(f *os.File, data []byte) error {
78		- if _, err := f.Write(data); err != nil {
79		- f.Close()
	52	+ if err := fsys.MkdirAll(filepath.Dir(path), dirMode); err != nil {
80	53	return err
81	54	}
82		- return f.Close()
	55	+ return fsys.WriteFileAtomic(path, data, fileMode)
83	56	}

  import (
  	"fmt"
--	"os"
  	"path/filepath"
++
++	"rickub.com/turbo-editors/turbo-core/fsys"
  )
  // fileMode is what a project's configuration file is created with: readable by
  	return nil
  }
--// write does the work, leaving the error to be named by Write.
++// write does the work, leaving the error to be named by Write. It goes through
++// fsys, so under -ssh the project's files are written on the remote machine.
  func write(path string, data []byte) error {
--	directory := filepath.Dir(path)
++	if err := fsys.MkdirAll(filepath.Dir(path), dirMode); err != nil {
--	if err := os.MkdirAll(directory, dirMode); err != nil {
--		return err
--	}
--
--	temporary, err := os.CreateTemp(directory, ".projectfile-*.toml")
--	if err != nil {
--		return err
--	}
--	name := temporary.Name()
--	defer os.Remove(name) // a no-op once the rename below has succeeded
--
--	if err := writeAndClose(temporary, data); err != nil {
--		return err
--	}
--	// CreateTemp makes the file readable by its owner only, and the rename
--	// would carry that through to a file a team is meant to share.
--	if err := os.Chmod(name, fileMode); err != nil {
--		return err
--	}
--	return os.Rename(name, path)
--}
--
--// writeAndClose writes a file and closes it, closing it either way.
--//
--// The close is what reports a write that failed on its way out of the buffer,
--// so its error matters as much as the write's.
--func writeAndClose(f *os.File, data []byte) error {
--	if _, err := f.Write(data); err != nil {
--		f.Close()
  		return err
  	}
--	return f.Close()
++	return fsys.WriteFileAtomic(path, data, fileMode)
  }

modified release.env +1 -1 Viewed

@@ -6,5 +6,5 @@
6	6	#
7	7	# ./02-build-releases.sh v1.0.4 to see what the CI will stage, without
8	8	# publishing anything
9		-TAG="v1.0.4"
	9	+TAG="v1.0.5"
10	10	ABOUT="Turbo Core — a window's shadow hugs its frame again (#30); AsciiDoc is coloured, the ninth built-in language (#31); text is copied out of a terminal window and pasted into it — Ctrl-Ins, Shift-Ins, Shift-arrows and the mouse — and a shell that asked for bracketed paste gets its marks"

  #
  #   ./02-build-releases.sh v1.0.4    to see what the CI will stage, without
  #                                    publishing anything
--TAG="v1.0.4"
++TAG="v1.0.5"
  ABOUT="Turbo Core — a window's shadow hugs its frame again (#30); AsciiDoc is coloured, the ninth built-in language (#31); text is copied out of a terminal window and pasted into it — Ctrl-Ins, Shift-Ins, Shift-arrows and the mouse — and a shell that asked for bracketed paste gets its marks"

added remote/README.md +65 -0 Viewed

new file mode 100644
@@ -0,0 +1,65 @@
	1	+# remote
	2	+
	3	+Another machine, reached through the `ssh` command already installed: one shared connection, the files over SFTP, and the command lines that open a shell or run a tool over there. It is what every editor's `-ssh user@machine[:directory]` flag uses.
	4	+
	5	+```go
	6	+session, err := remote.Open(ctx, "bob@build-box:/srv/app")
	7	+if err != nil {
	8	+ return err
	9	+}
	10	+defer session.Close()
	11	+fsys.Use(session.FS())
	12	+editor.UseRemote(session)
	13	+```
	14	+
	15	+Imports the standard library and `github.com/pkg/sftp`. Its `FS` satisfies `fsys.FS` without importing `fsys`, and `Session` satisfies `app.Remote` without importing `app`.
	16	+
	17	+## Why the ssh command, not an SSH library
	18	+
	19	+The installed command already knows everything the person has set up: `~/.ssh/config` and its `Host` aliases, ports, `ProxyJump`, the agent, `known_hosts`, passphrases, passwords. A library would have to reimplement each of those, the host-key question first. The same reasoning made `configrepo` run `git`.
	20	+
	21	+## One login, then everything through it
	22	+
	23	+`Connect` runs `ssh -o ControlMaster=yes -o ControlPersist=60 -N -f` in the foreground, before the editor takes the terminal: that is where ssh asks for a password or whether to trust a new host. With `-f` it returns once logged in, leaving the connection behind a control socket in a private temporary directory.
	24	+
	25	+Everything afterwards passes `-S <socket> -o ControlMaster=no -o BatchMode=yes`: it goes through that connection, never opens its own, and never prompts — a prompt then would be drawn over the editor.
	26	+
	27	+- Files: one `ssh -s … sftp` channel for the whole session, spoken to with `pkg/sftp`. A save writes `.<name>.<random>` beside the target and renames it over with `posix-rename@openssh.com`.
	28	+- A terminal: `ssh -t … "exec /bin/sh -c 'cd <dir> && exec \"${SHELL:-/bin/sh}\" -l'"`.
	29	+- A tool: `ssh -T` (captured) or `-t` (in a terminal) `… "exec /bin/sh -c 'cd <dir> && <command>'"`. Always `/bin/sh`, whatever the user's login shell is, so a tools file means the same thing on both machines.
	30	+
	31	+`Close` closes the file channel, sends `-O exit` to the master, and removes the socket's directory.
	32	+
	33	+## Limits
	34	+
	35	+- Windows: its OpenSSH has no ControlMaster; `Connect` returns `ErrUnsupported`.
	36	+- No port in the target: put it in `~/.ssh/config` under a `Host` alias, as for scp.
	37	+- No language server and no agents over ssh; the editor switches both off. See `docs/*/explanation/remote-editing.md`.
	38	+
	39	+## Public API
	40	+
	41	+\| Name \| What it does \|
	42	+\| --- \| --- \|
	43	+\| `ParseTarget(arg) (Target, error)` \| `[user@]host[:path]`; refuses a host or user starting with `-` (`ErrBadTarget`) \|
	44	+\| `Target.Destination()`, `Target.String()` \| `user@host`; the target as typed \|
	45	+\| `Open(ctx, arg)` \| Parse, say `Connecting to …` on stderr, `Connect` \|
	46	+\| `Connect(ctx, target, Options)` \| Log in, open the file channel, resolve the directory \|
	47	+\| `Session.FS()` \| The remote files, an `fsys.FS` rooted at the directory \|
	48	+\| `Session.Name()`, `Session.Target()` \| How it is shown; what it connected to \|
	49	+\| `Session.ShellCommand(dir)`, `Session.RunCommand(dir, cmd, withTerminal)` \| The argv of a remote shell or tool \|
	50	+\| `Session.Close()` \| End it all; safe twice \|
	51	+\| `ErrBadTarget`, `ErrNoSSH`, `ErrUnsupported` \| Bad argument; no ssh; Windows \|
	52	+
	53	+## Tests
	54	+
	55	+```sh
	56	+go test ./remote/
	57	+```
	58	+
	59	+No network needed. The `FS` tests speak to a real SFTP server — `pkg/sftp`'s own — through in-memory pipes, serving a temporary directory. `Connect` and `Close` run end to end against the test binary itself standing in for ssh (`TestMain`): it logs every invocation, serves SFTP on `-s`, and can be told to fail the login or refuse the subsystem.
	60	+
	61	+Against a real sshd — the demo machine in `turbo-editors/demo-remote-machine`:
	62	+
	63	+```sh
	64	+TURBO_CORE_SSH_KEY=$PWD/../demo-remote-machine/keys/id_demo go test ./remote/ -run Real -v
	65	+```

++# remote
++
++Another machine, reached through the `ssh` command already installed: one shared connection, the files over SFTP, and the command lines that open a shell or run a tool over there. It is what every editor's `-ssh user@machine[:directory]` flag uses.
++
++```go
++session, err := remote.Open(ctx, "bob@build-box:/srv/app")
++if err != nil {
++	return err
++}
++defer session.Close()
++fsys.Use(session.FS())
++editor.UseRemote(session)
++```
++
++Imports the standard library and `github.com/pkg/sftp`. Its `FS` satisfies `fsys.FS` without importing `fsys`, and `Session` satisfies `app.Remote` without importing `app`.
++
++## Why the ssh command, not an SSH library
++
++The installed command already knows everything the person has set up: `~/.ssh/config` and its `Host` aliases, ports, `ProxyJump`, the agent, `known_hosts`, passphrases, passwords. A library would have to reimplement each of those, the host-key question first. The same reasoning made `configrepo` run `git`.
++
++## One login, then everything through it
++
++`Connect` runs `ssh -o ControlMaster=yes -o ControlPersist=60 -N -f` **in the foreground, before the editor takes the terminal**: that is where ssh asks for a password or whether to trust a new host. With `-f` it returns once logged in, leaving the connection behind a control socket in a private temporary directory.
++
++Everything afterwards passes `-S <socket> -o ControlMaster=no -o BatchMode=yes`: it goes through that connection, never opens its own, and never prompts — a prompt then would be drawn over the editor.
++
++- **Files**: one `ssh -s … sftp` channel for the whole session, spoken to with `pkg/sftp`. A save writes `.<name>.<random>` beside the target and renames it over with `posix-rename@openssh.com`.
++- **A terminal**: `ssh -t … "exec /bin/sh -c 'cd <dir> && exec \"${SHELL:-/bin/sh}\" -l'"`.
++- **A tool**: `ssh -T` (captured) or `-t` (in a terminal) `… "exec /bin/sh -c 'cd <dir> && <command>'"`. Always `/bin/sh`, whatever the user's login shell is, so a tools file means the same thing on both machines.
++
++`Close` closes the file channel, sends `-O exit` to the master, and removes the socket's directory.
++
++## Limits
++
++- **Windows**: its OpenSSH has no ControlMaster; `Connect` returns `ErrUnsupported`.
++- **No port in the target**: put it in `~/.ssh/config` under a `Host` alias, as for scp.
++- **No language server and no agents** over ssh; the editor switches both off. See `docs/*/explanation/remote-editing.md`.
++
++## Public API
++
++| Name | What it does |
++| --- | --- |
++| `ParseTarget(arg) (Target, error)` | `[user@]host[:path]`; refuses a host or user starting with `-` (`ErrBadTarget`) |
++| `Target.Destination()`, `Target.String()` | `user@host`; the target as typed |
++| `Open(ctx, arg)` | Parse, say `Connecting to …` on stderr, `Connect` |
++| `Connect(ctx, target, Options)` | Log in, open the file channel, resolve the directory |
++| `Session.FS()` | The remote files, an `fsys.FS` rooted at the directory |
++| `Session.Name()`, `Session.Target()` | How it is shown; what it connected to |
++| `Session.ShellCommand(dir)`, `Session.RunCommand(dir, cmd, withTerminal)` | The argv of a remote shell or tool |
++| `Session.Close()` | End it all; safe twice |
++| `ErrBadTarget`, `ErrNoSSH`, `ErrUnsupported` | Bad argument; no ssh; Windows |
++
++## Tests
++
++```sh
++go test ./remote/
++```
++
++No network needed. The `FS` tests speak to a real SFTP server — `pkg/sftp`'s own — through in-memory pipes, serving a temporary directory. `Connect` and `Close` run end to end against the test binary itself standing in for ssh (`TestMain`): it logs every invocation, serves SFTP on `-s`, and can be told to fail the login or refuse the subsystem.
++
++Against a real sshd — the demo machine in `turbo-editors/demo-remote-machine`:
++
++```sh
++TURBO_CORE_SSH_KEY=$PWD/../demo-remote-machine/keys/id_demo go test ./remote/ -run Real -v
++```

added remote/files.go +144 -0 Viewed

new file mode 100644
@@ -0,0 +1,144 @@
	1	+package remote
	2	+
	3	+import (
	4	+ "crypto/rand"
	5	+ "encoding/hex"
	6	+ "errors"
	7	+ "fmt"
	8	+ "io"
	9	+ "io/fs"
	10	+ "os"
	11	+ "path"
	12	+ "sort"
	13	+
	14	+ "github.com/pkg/sftp"
	15	+)
	16	+
	17	+// FS is a machine's files over SFTP: an fsys.FS whose relative paths start
	18	+// from the directory given after the colon of the target.
	19	+//
	20	+// Every method is one or a few SFTP requests on the session's one channel,
	21	+// which is what makes the editor's once-a-second look at its open files cheap
	22	+// enough to keep doing.
	23	+//
	24	+// fsys.Use(session.FS())
	25	+type FS struct {
	26	+ client *sftp.Client
	27	+ working string
	28	+}
	29	+
	30	+// newFS returns the files a client reaches, relative to working.
	31	+func newFS(client sftp.Client, working string) FS {
	32	+ return &FS{client: client, working: working}
	33	+}
	34	+
	35	+// abs resolves a path against the working directory. The remote machine is a
	36	+// Unix machine — an SFTP server's paths are slash-separated whatever the
	37	+// platform the editor runs on — so this is package path, not path/filepath.
	38	+func (f *FS) abs(name string) string {
	39	+ if path.IsAbs(name) {
	40	+ return path.Clean(name)
	41	+ }
	42	+ return path.Join(f.working, name)
	43	+}
	44	+
	45	+// Getwd returns the directory being edited.
	46	+func (f *FS) Getwd() (string, error) { return f.working, nil }
	47	+
	48	+// ReadFile returns a remote file's content.
	49	+func (f *FS) ReadFile(name string) ([]byte, error) {
	50	+ file, err := f.client.Open(f.abs(name))
	51	+ if err != nil {
	52	+ return nil, notExist(err)
	53	+ }
	54	+ defer file.Close()
	55	+ return io.ReadAll(file)
	56	+}
	57	+
	58	+// Stat describes a remote file, following symbolic links.
	59	+func (f *FS) Stat(name string) (fs.FileInfo, error) {
	60	+ info, err := f.client.Stat(f.abs(name))
	61	+ return info, notExist(err)
	62	+}
	63	+
	64	+// ReadDir lists a remote directory, sorted by name as os.ReadDir sorts.
	65	+func (f *FS) ReadDir(name string) ([]fs.DirEntry, error) {
	66	+ infos, err := f.client.ReadDir(f.abs(name))
	67	+ if err != nil {
	68	+ return nil, notExist(err)
	69	+ }
	70	+ sort.Slice(infos, func(i, j int) bool { return infos[i].Name() < infos[j].Name() })
	71	+
	72	+ entries := make([]fs.DirEntry, len(infos))
	73	+ for i, info := range infos {
	74	+ entries[i] = fs.FileInfoToDirEntry(info)
	75	+ }
	76	+ return entries, nil
	77	+}
	78	+
	79	+// MkdirAll makes a remote directory and its parents. SFTP's mkdir takes no
	80	+// permissions worth relying on, so the remote umask decides them, as it would
	81	+// for mkdir -p typed there.
	82	+func (f *FS) MkdirAll(name string, _ fs.FileMode) error {
	83	+ return f.client.MkdirAll(f.abs(name))
	84	+}
	85	+
	86	+// WriteFileAtomic writes to a temporary file beside name and renames it over
	87	+// name with OpenSSH's posix-rename, which replaces the target in one step as
	88	+// rename(2) does. A reader on the machine sees the old file or the new one.
	89	+func (f *FS) WriteFileAtomic(name string, data []byte, perm fs.FileMode) error {
	90	+ target := f.abs(name)
	91	+ temporary, err := temporaryBeside(target)
	92	+ if err != nil {
	93	+ return err
	94	+ }
	95	+
	96	+ file, err := f.client.OpenFile(temporary, os.O_WRONLY\|os.O_CREATE\|os.O_EXCL)
	97	+ if err != nil {
	98	+ return notExist(err)
	99	+ }
	100	+ // Every failure from here on must remove the temporary file, or a failed
	101	+ // save would litter the remote directory. After the rename, a no-op.
	102	+ defer f.client.Remove(temporary) //nolint:errcheck // best effort, see above
	103	+
	104	+ if err := writeAndClose(file, data); err != nil {
	105	+ return err
	106	+ }
	107	+ if err := f.client.Chmod(temporary, perm); err != nil {
	108	+ return err
	109	+ }
	110	+ return f.client.PosixRename(temporary, target)
	111	+}
	112	+
	113	+// temporaryBeside names a temporary file in the same directory as target:
	114	+// .<name>.<random>, as the local file system names its own.
	115	+func temporaryBeside(target string) (string, error) {
	116	+ random := make([]byte, 6)
	117	+ if _, err := rand.Read(random); err != nil {
	118	+ return "", fmt.Errorf("naming a temporary file: %w", err)
	119	+ }
	120	+ return path.Join(path.Dir(target), "."+path.Base(target)+"."+hex.EncodeToString(random)), nil
	121	+}
	122	+
	123	+// writeAndClose writes a remote file and closes it, closing it either way.
	124	+func writeAndClose(file *sftp.File, data []byte) error {
	125	+ if _, err := file.Write(data); err != nil {
	126	+ file.Close()
	127	+ return err
	128	+ }
	129	+ return file.Close()
	130	+}
	131	+
	132	+// notExist makes sure a missing file is reported as fs.ErrNotExist, which is
	133	+// how every caller of fsys recognises "a new file" — whatever form the SFTP
	134	+// server's status took on the way here.
	135	+func notExist(err error) error {
	136	+ if err == nil \|\| errors.Is(err, fs.ErrNotExist) {
	137	+ return err
	138	+ }
	139	+ var status *sftp.StatusError
	140	+ if errors.As(err, &status) && status.FxCode() == sftp.ErrSSHFxNoSuchFile {
	141	+ return fmt.Errorf("%w: %w", fs.ErrNotExist, err)
	142	+ }
	143	+ return err
	144	+}

++package remote
++
++import (
++	"crypto/rand"
++	"encoding/hex"
++	"errors"
++	"fmt"
++	"io"
++	"io/fs"
++	"os"
++	"path"
++	"sort"
++
++	"github.com/pkg/sftp"
++)
++
++// FS is a machine's files over SFTP: an fsys.FS whose relative paths start
++// from the directory given after the colon of the target.
++//
++// Every method is one or a few SFTP requests on the session's one channel,
++// which is what makes the editor's once-a-second look at its open files cheap
++// enough to keep doing.
++//
++//	fsys.Use(session.FS())
++type FS struct {
++	client  *sftp.Client
++	working string
++}
++
++// newFS returns the files a client reaches, relative to working.
++func newFS(client *sftp.Client, working string) *FS {
++	return &FS{client: client, working: working}
++}
++
++// abs resolves a path against the working directory. The remote machine is a
++// Unix machine — an SFTP server's paths are slash-separated whatever the
++// platform the editor runs on — so this is package path, not path/filepath.
++func (f *FS) abs(name string) string {
++	if path.IsAbs(name) {
++		return path.Clean(name)
++	}
++	return path.Join(f.working, name)
++}
++
++// Getwd returns the directory being edited.
++func (f *FS) Getwd() (string, error) { return f.working, nil }
++
++// ReadFile returns a remote file's content.
++func (f *FS) ReadFile(name string) ([]byte, error) {
++	file, err := f.client.Open(f.abs(name))
++	if err != nil {
++		return nil, notExist(err)
++	}
++	defer file.Close()
++	return io.ReadAll(file)
++}
++
++// Stat describes a remote file, following symbolic links.
++func (f *FS) Stat(name string) (fs.FileInfo, error) {
++	info, err := f.client.Stat(f.abs(name))
++	return info, notExist(err)
++}
++
++// ReadDir lists a remote directory, sorted by name as os.ReadDir sorts.
++func (f *FS) ReadDir(name string) ([]fs.DirEntry, error) {
++	infos, err := f.client.ReadDir(f.abs(name))
++	if err != nil {
++		return nil, notExist(err)
++	}
++	sort.Slice(infos, func(i, j int) bool { return infos[i].Name() < infos[j].Name() })
++
++	entries := make([]fs.DirEntry, len(infos))
++	for i, info := range infos {
++		entries[i] = fs.FileInfoToDirEntry(info)
++	}
++	return entries, nil
++}
++
++// MkdirAll makes a remote directory and its parents. SFTP's mkdir takes no
++// permissions worth relying on, so the remote umask decides them, as it would
++// for mkdir -p typed there.
++func (f *FS) MkdirAll(name string, _ fs.FileMode) error {
++	return f.client.MkdirAll(f.abs(name))
++}
++
++// WriteFileAtomic writes to a temporary file beside name and renames it over
++// name with OpenSSH's posix-rename, which replaces the target in one step as
++// rename(2) does. A reader on the machine sees the old file or the new one.
++func (f *FS) WriteFileAtomic(name string, data []byte, perm fs.FileMode) error {
++	target := f.abs(name)
++	temporary, err := temporaryBeside(target)
++	if err != nil {
++		return err
++	}
++
++	file, err := f.client.OpenFile(temporary, os.O_WRONLY|os.O_CREATE|os.O_EXCL)
++	if err != nil {
++		return notExist(err)
++	}
++	// Every failure from here on must remove the temporary file, or a failed
++	// save would litter the remote directory. After the rename, a no-op.
++	defer f.client.Remove(temporary) //nolint:errcheck // best effort, see above
++
++	if err := writeAndClose(file, data); err != nil {
++		return err
++	}
++	if err := f.client.Chmod(temporary, perm); err != nil {
++		return err
++	}
++	return f.client.PosixRename(temporary, target)
++}
++
++// temporaryBeside names a temporary file in the same directory as target:
++// .<name>.<random>, as the local file system names its own.
++func temporaryBeside(target string) (string, error) {
++	random := make([]byte, 6)
++	if _, err := rand.Read(random); err != nil {
++		return "", fmt.Errorf("naming a temporary file: %w", err)
++	}
++	return path.Join(path.Dir(target), "."+path.Base(target)+"."+hex.EncodeToString(random)), nil
++}
++
++// writeAndClose writes a remote file and closes it, closing it either way.
++func writeAndClose(file *sftp.File, data []byte) error {
++	if _, err := file.Write(data); err != nil {
++		file.Close()
++		return err
++	}
++	return file.Close()
++}
++
++// notExist makes sure a missing file is reported as fs.ErrNotExist, which is
++// how every caller of fsys recognises "a new file" — whatever form the SFTP
++// server's status took on the way here.
++func notExist(err error) error {
++	if err == nil || errors.Is(err, fs.ErrNotExist) {
++		return err
++	}
++	var status *sftp.StatusError
++	if errors.As(err, &status) && status.FxCode() == sftp.ErrSSHFxNoSuchFile {
++		return fmt.Errorf("%w: %w", fs.ErrNotExist, err)
++	}
++	return err
++}

added remote/files_test.go +182 -0 Viewed

new file mode 100644
@@ -0,0 +1,182 @@
	1	+package remote
	2	+
	3	+import (
	4	+ "errors"
	5	+ "io"
	6	+ "io/fs"
	7	+ "os"
	8	+ "path/filepath"
	9	+ "testing"
	10	+
	11	+ "github.com/pkg/sftp"
	12	+)
	13	+
	14	+// pipe joins two one-way pipes into the read-write stream an SFTP server
	15	+// talks over.
	16	+type pipe struct {
	17	+ io.Reader
	18	+ io.WriteCloser
	19	+}
	20	+
	21	+// newTestClient returns an SFTP client talking to a real SFTP server — the
	22	+// one pkg/sftp ships — through in-memory pipes. The server serves this
	23	+// machine's disk, so the test can check the outcome with package os.
	24	+func newTestClient(t testing.T) sftp.Client {
	25	+ t.Helper()
	26	+ toServer, fromClient := io.Pipe()
	27	+ toClient, fromServer := io.Pipe()
	28	+
	29	+ server, err := sftp.NewServer(pipe{toServer, fromServer}, sftp.WithServerWorkingDirectory(t.TempDir()))
	30	+ if err != nil {
	31	+ t.Fatal(err)
	32	+ }
	33	+ go server.Serve() //nolint:errcheck // ends when the client closes
	34	+
	35	+ client, err := sftp.NewClientPipe(toClient, fromClient)
	36	+ if err != nil {
	37	+ t.Fatal(err)
	38	+ }
	39	+ // The server goes first: closing its end is what lets the client's reading
	40	+ // goroutine see the end of the stream, and client.Close waits for it.
	41	+ t.Cleanup(func() { server.Close(); client.Close() })
	42	+ return client
	43	+}
	44	+
	45	+// newTestFS returns the remote file system rooted at a fresh directory.
	46	+func newTestFS(t testing.T) (FS, string) {
	47	+ t.Helper()
	48	+ root := t.TempDir()
	49	+ return newFS(newTestClient(t), root), root
	50	+}
	51	+
	52	+func TestReadFileReadsARemoteFileByRelativePath(t *testing.T) {
	53	+ files, root := newTestFS(t)
	54	+ if err := os.WriteFile(filepath.Join(root, "main.py"), []byte("print(1)\n"), 0o644); err != nil {
	55	+ t.Fatal(err)
	56	+ }
	57	+
	58	+ data, err := files.ReadFile("main.py")
	59	+ if err != nil \|\| string(data) != "print(1)\n" {
	60	+ t.Errorf("ReadFile = %q, %v", data, err)
	61	+ }
	62	+}
	63	+
	64	+func TestAMissingRemoteFileIsReportedAsNotExist(t *testing.T) {
	65	+ files, _ := newTestFS(t)
	66	+ if _, err := files.ReadFile("nope.py"); !errors.Is(err, fs.ErrNotExist) {
	67	+ t.Errorf("ReadFile: %v, want fs.ErrNotExist", err)
	68	+ }
	69	+ if _, err := files.Stat("nope.py"); !errors.Is(err, fs.ErrNotExist) {
	70	+ t.Errorf("Stat: %v, want fs.ErrNotExist", err)
	71	+ }
	72	+ if _, err := files.ReadDir("nope"); !errors.Is(err, fs.ErrNotExist) {
	73	+ t.Errorf("ReadDir: %v, want fs.ErrNotExist", err)
	74	+ }
	75	+}
	76	+
	77	+func TestWriteFileAtomicReplacesTheFileWithTheGivenModeAndLeavesNothingBehind(t *testing.T) {
	78	+ files, root := newTestFS(t)
	79	+ target := filepath.Join(root, "run.sh")
	80	+ if err := os.WriteFile(target, []byte("old"), 0o644); err != nil {
	81	+ t.Fatal(err)
	82	+ }
	83	+
	84	+ if err := files.WriteFileAtomic("run.sh", []byte("new"), 0o755); err != nil {
	85	+ t.Fatal(err)
	86	+ }
	87	+
	88	+ data, _ := os.ReadFile(target)
	89	+ if string(data) != "new" {
	90	+ t.Errorf("content = %q, want new", data)
	91	+ }
	92	+ info, _ := os.Stat(target)
	93	+ if info.Mode().Perm() != 0o755 {
	94	+ t.Errorf("mode = %v, want 0755", info.Mode().Perm())
	95	+ }
	96	+ entries, _ := os.ReadDir(root)
	97	+ if len(entries) != 1 {
	98	+ t.Errorf("%d entries in the directory, want 1: a temporary file was left behind", len(entries))
	99	+ }
	100	+}
	101	+
	102	+func TestWriteFileAtomicIntoAMissingDirectoryIsNotExist(t *testing.T) {
	103	+ files, _ := newTestFS(t)
	104	+ if err := files.WriteFileAtomic("missing/a.py", []byte("x"), 0o644); !errors.Is(err, fs.ErrNotExist) {
	105	+ t.Errorf("err = %v, want fs.ErrNotExist", err)
	106	+ }
	107	+}
	108	+
	109	+func TestReadDirListsSortedByName(t *testing.T) {
	110	+ files, root := newTestFS(t)
	111	+ for _, name := range []string{"b.py", "a.py", "c.py"} {
	112	+ if err := os.WriteFile(filepath.Join(root, name), nil, 0o644); err != nil {
	113	+ t.Fatal(err)
	114	+ }
	115	+ }
	116	+ if err := os.Mkdir(filepath.Join(root, "pkg"), 0o755); err != nil {
	117	+ t.Fatal(err)
	118	+ }
	119	+
	120	+ entries, err := files.ReadDir(".")
	121	+ if err != nil {
	122	+ t.Fatal(err)
	123	+ }
	124	+ var names []string
	125	+ for _, entry := range entries {
	126	+ names = append(names, entry.Name())
	127	+ }
	128	+ if len(names) != 4 \|\| names[0] != "a.py" \|\| names[3] != "pkg" \|\| !entries[3].IsDir() {
	129	+ t.Errorf("entries = %v", names)
	130	+ }
	131	+}
	132	+
	133	+func TestMkdirAllAndStatWorkOnTheRemoteSide(t *testing.T) {
	134	+ files, root := newTestFS(t)
	135	+ if err := files.MkdirAll(".turbo-python/deep", 0o755); err != nil {
	136	+ t.Fatal(err)
	137	+ }
	138	+ info, err := files.Stat(".turbo-python/deep")
	139	+ if err != nil \|\| !info.IsDir() {
	140	+ t.Errorf("Stat = %v, %v; want a directory", info, err)
	141	+ }
	142	+ if _, err := os.Stat(filepath.Join(root, ".turbo-python", "deep")); err != nil {
	143	+ t.Errorf("the directory is not on disk: %v", err)
	144	+ }
	145	+ if working, _ := files.Getwd(); working != root {
	146	+ t.Errorf("Getwd = %q, want %q", working, root)
	147	+ }
	148	+}
	149	+
	150	+func TestTheWorkingDirectoryIsResolvedFromTheTargetsPath(t *testing.T) {
	151	+ client := newTestClient(t)
	152	+ home, err := client.RealPath(".")
	153	+ if err != nil {
	154	+ t.Fatal(err)
	155	+ }
	156	+ if err := os.Mkdir(filepath.Join(home, "app"), 0o755); err != nil {
	157	+ t.Fatal(err)
	158	+ }
	159	+ if err := os.WriteFile(filepath.Join(home, "file.txt"), nil, 0o644); err != nil {
	160	+ t.Fatal(err)
	161	+ }
	162	+
	163	+ for path, want := range map[string]string{
	164	+ "": home,
	165	+ "~": home,
	166	+ "~/app": filepath.Join(home, "app"),
	167	+ "app": filepath.Join(home, "app"),
	168	+ filepath.Join(home, "app"): filepath.Join(home, "app"),
	169	+ filepath.Join(home, "app/.."): home,
	170	+ } {
	171	+ if got, err := workingDirectory(client, path); err != nil \|\| got != want {
	172	+ t.Errorf("workingDirectory(%q) = %q, %v; want %q", path, got, err, want)
	173	+ }
	174	+ }
	175	+
	176	+ if _, err := workingDirectory(client, "missing"); err == nil {
	177	+ t.Error("a missing directory was accepted")
	178	+ }
	179	+ if _, err := workingDirectory(client, "file.txt"); !errors.Is(err, fs.ErrInvalid) {
	180	+ t.Errorf("a file as the directory: %v, want fs.ErrInvalid", err)
	181	+ }
	182	+}

++package remote
++
++import (
++	"errors"
++	"io"
++	"io/fs"
++	"os"
++	"path/filepath"
++	"testing"
++
++	"github.com/pkg/sftp"
++)
++
++// pipe joins two one-way pipes into the read-write stream an SFTP server
++// talks over.
++type pipe struct {
++	io.Reader
++	io.WriteCloser
++}
++
++// newTestClient returns an SFTP client talking to a real SFTP server — the
++// one pkg/sftp ships — through in-memory pipes. The server serves this
++// machine's disk, so the test can check the outcome with package os.
++func newTestClient(t *testing.T) *sftp.Client {
++	t.Helper()
++	toServer, fromClient := io.Pipe()
++	toClient, fromServer := io.Pipe()
++
++	server, err := sftp.NewServer(pipe{toServer, fromServer}, sftp.WithServerWorkingDirectory(t.TempDir()))
++	if err != nil {
++		t.Fatal(err)
++	}
++	go server.Serve() //nolint:errcheck // ends when the client closes
++
++	client, err := sftp.NewClientPipe(toClient, fromClient)
++	if err != nil {
++		t.Fatal(err)
++	}
++	// The server goes first: closing its end is what lets the client's reading
++	// goroutine see the end of the stream, and client.Close waits for it.
++	t.Cleanup(func() { server.Close(); client.Close() })
++	return client
++}
++
++// newTestFS returns the remote file system rooted at a fresh directory.
++func newTestFS(t *testing.T) (*FS, string) {
++	t.Helper()
++	root := t.TempDir()
++	return newFS(newTestClient(t), root), root
++}
++
++func TestReadFileReadsARemoteFileByRelativePath(t *testing.T) {
++	files, root := newTestFS(t)
++	if err := os.WriteFile(filepath.Join(root, "main.py"), []byte("print(1)\n"), 0o644); err != nil {
++		t.Fatal(err)
++	}
++
++	data, err := files.ReadFile("main.py")
++	if err != nil || string(data) != "print(1)\n" {
++		t.Errorf("ReadFile = %q, %v", data, err)
++	}
++}
++
++func TestAMissingRemoteFileIsReportedAsNotExist(t *testing.T) {
++	files, _ := newTestFS(t)
++	if _, err := files.ReadFile("nope.py"); !errors.Is(err, fs.ErrNotExist) {
++		t.Errorf("ReadFile: %v, want fs.ErrNotExist", err)
++	}
++	if _, err := files.Stat("nope.py"); !errors.Is(err, fs.ErrNotExist) {
++		t.Errorf("Stat: %v, want fs.ErrNotExist", err)
++	}
++	if _, err := files.ReadDir("nope"); !errors.Is(err, fs.ErrNotExist) {
++		t.Errorf("ReadDir: %v, want fs.ErrNotExist", err)
++	}
++}
++
++func TestWriteFileAtomicReplacesTheFileWithTheGivenModeAndLeavesNothingBehind(t *testing.T) {
++	files, root := newTestFS(t)
++	target := filepath.Join(root, "run.sh")
++	if err := os.WriteFile(target, []byte("old"), 0o644); err != nil {
++		t.Fatal(err)
++	}
++
++	if err := files.WriteFileAtomic("run.sh", []byte("new"), 0o755); err != nil {
++		t.Fatal(err)
++	}
++
++	data, _ := os.ReadFile(target)
++	if string(data) != "new" {
++		t.Errorf("content = %q, want new", data)
++	}
++	info, _ := os.Stat(target)
++	if info.Mode().Perm() != 0o755 {
++		t.Errorf("mode = %v, want 0755", info.Mode().Perm())
++	}
++	entries, _ := os.ReadDir(root)
++	if len(entries) != 1 {
++		t.Errorf("%d entries in the directory, want 1: a temporary file was left behind", len(entries))
++	}
++}
++
++func TestWriteFileAtomicIntoAMissingDirectoryIsNotExist(t *testing.T) {
++	files, _ := newTestFS(t)
++	if err := files.WriteFileAtomic("missing/a.py", []byte("x"), 0o644); !errors.Is(err, fs.ErrNotExist) {
++		t.Errorf("err = %v, want fs.ErrNotExist", err)
++	}
++}
++
++func TestReadDirListsSortedByName(t *testing.T) {
++	files, root := newTestFS(t)
++	for _, name := range []string{"b.py", "a.py", "c.py"} {
++		if err := os.WriteFile(filepath.Join(root, name), nil, 0o644); err != nil {
++			t.Fatal(err)
++		}
++	}
++	if err := os.Mkdir(filepath.Join(root, "pkg"), 0o755); err != nil {
++		t.Fatal(err)
++	}
++
++	entries, err := files.ReadDir(".")
++	if err != nil {
++		t.Fatal(err)
++	}
++	var names []string
++	for _, entry := range entries {
++		names = append(names, entry.Name())
++	}
++	if len(names) != 4 || names[0] != "a.py" || names[3] != "pkg" || !entries[3].IsDir() {
++		t.Errorf("entries = %v", names)
++	}
++}
++
++func TestMkdirAllAndStatWorkOnTheRemoteSide(t *testing.T) {
++	files, root := newTestFS(t)
++	if err := files.MkdirAll(".turbo-python/deep", 0o755); err != nil {
++		t.Fatal(err)
++	}
++	info, err := files.Stat(".turbo-python/deep")
++	if err != nil || !info.IsDir() {
++		t.Errorf("Stat = %v, %v; want a directory", info, err)
++	}
++	if _, err := os.Stat(filepath.Join(root, ".turbo-python", "deep")); err != nil {
++		t.Errorf("the directory is not on disk: %v", err)
++	}
++	if working, _ := files.Getwd(); working != root {
++		t.Errorf("Getwd = %q, want %q", working, root)
++	}
++}
++
++func TestTheWorkingDirectoryIsResolvedFromTheTargetsPath(t *testing.T) {
++	client := newTestClient(t)
++	home, err := client.RealPath(".")
++	if err != nil {
++		t.Fatal(err)
++	}
++	if err := os.Mkdir(filepath.Join(home, "app"), 0o755); err != nil {
++		t.Fatal(err)
++	}
++	if err := os.WriteFile(filepath.Join(home, "file.txt"), nil, 0o644); err != nil {
++		t.Fatal(err)
++	}
++
++	for path, want := range map[string]string{
++		"":                            home,
++		"~":                           home,
++		"~/app":                       filepath.Join(home, "app"),
++		"app":                         filepath.Join(home, "app"),
++		filepath.Join(home, "app"):    filepath.Join(home, "app"),
++		filepath.Join(home, "app/.."): home,
++	} {
++		if got, err := workingDirectory(client, path); err != nil || got != want {
++			t.Errorf("workingDirectory(%q) = %q, %v; want %q", path, got, err, want)
++		}
++	}
++
++	if _, err := workingDirectory(client, "missing"); err == nil {
++		t.Error("a missing directory was accepted")
++	}
++	if _, err := workingDirectory(client, "file.txt"); !errors.Is(err, fs.ErrInvalid) {
++		t.Errorf("a file as the directory: %v, want fs.ErrInvalid", err)
++	}
++}

added remote/integration_test.go +99 -0 Viewed

new file mode 100644
@@ -0,0 +1,99 @@
	1	+package remote
	2	+
	3	+import (
	4	+ "context"
	5	+ "os"
	6	+ "os/exec"
	7	+ "path/filepath"
	8	+ "strings"
	9	+ "testing"
	10	+)
	11	+
	12	+// The real thing, against a real sshd: the demo machine of
	13	+// turbo-editors/demo-remote-machine, or any machine laid out like it.
	14	+// Skipped unless TURBO_CORE_SSH_KEY names the private key it accepts:
	15	+//
	16	+// cd demo-remote-machine && ./make-key.sh && docker compose up -d --build
	17	+// TURBO_CORE_SSH_KEY=$PWD/keys/id_demo go test ./remote -run Real -v
	18	+//
	19	+// TURBO_CORE_SSH_PORT (default 2222) and TURBO_CORE_SSH_TARGET (default
	20	+// bob@127.0.0.1:workspace/hello-python) point it elsewhere.
	21	+func TestRealConnectionToTheDemoMachine(t *testing.T) {
	22	+ key := os.Getenv("TURBO_CORE_SSH_KEY")
	23	+ if key == "" {
	24	+ t.Skip("set TURBO_CORE_SSH_KEY to run against a real sshd (see the comment above)")
	25	+ }
	26	+ target, err := ParseTarget(envOr("TURBO_CORE_SSH_TARGET", "bob@127.0.0.1:workspace/hello-python"))
	27	+ if err != nil {
	28	+ t.Fatal(err)
	29	+ }
	30	+ program := sshWithConfig(t, key, envOr("TURBO_CORE_SSH_PORT", "2222"))
	31	+
	32	+ session, err := Connect(context.Background(), target, Options{Program: program})
	33	+ if err != nil {
	34	+ t.Fatal(err)
	35	+ }
	36	+ defer session.Close()
	37	+
	38	+ files := session.FS()
	39	+ working, _ := files.Getwd()
	40	+ if !strings.HasSuffix(working, "/"+filepath.Base(target.Path)) {
	41	+ t.Errorf("working directory = %q", working)
	42	+ }
	43	+ if err := files.WriteFileAtomic("from_the_test.py", []byte("print('written over sftp')\n"), 0o644); err != nil {
	44	+ t.Fatal(err)
	45	+ }
	46	+ if data, err := files.ReadFile("from_the_test.py"); err != nil \|\| string(data) != "print('written over sftp')\n" {
	47	+ t.Errorf("read back %q, %v", data, err)
	48	+ }
	49	+
	50	+ argv := session.RunCommand(working, "python3 from_the_test.py && rm from_the_test.py && pwd", false)
	51	+ output, err := exec.Command(argv[0], argv[1:]...).CombinedOutput()
	52	+ if err != nil {
	53	+ t.Fatalf("running a command over the shared connection: %v\n%s", err, output)
	54	+ }
	55	+ if got := string(output); got != "written over sftp\n"+working+"\n" {
	56	+ t.Errorf("the command printed %q", got)
	57	+ }
	58	+
	59	+ controlPath := session.controlPath
	60	+ if err := session.Close(); err != nil {
	61	+ t.Errorf("Close: %v", err)
	62	+ }
	63	+ check := exec.Command(program, "-S", controlPath, "-O", "check", "--", target.Destination())
	64	+ if check.Run() == nil {
	65	+ t.Error("the shared connection is still up after Close")
	66	+ }
	67	+}
	68	+
	69	+// sshWithConfig writes a wrapper that runs ssh with the port, key and a
	70	+// throwaway known_hosts of its own, so the test changes nothing in ~/.ssh.
	71	+// That is the same thing a Host block in ~/.ssh/config does for a person.
	72	+func sshWithConfig(t *testing.T, key, port string) string {
	73	+ t.Helper()
	74	+ directory := t.TempDir()
	75	+ config := filepath.Join(directory, "config")
	76	+ contents := "Host *\n" +
	77	+ " Port " + port + "\n" +
	78	+ " IdentityFile " + key + "\n" +
	79	+ " IdentitiesOnly yes\n" +
	80	+ " UserKnownHostsFile " + filepath.Join(directory, "known_hosts") + "\n" +
	81	+ " StrictHostKeyChecking accept-new\n"
	82	+ if err := os.WriteFile(config, []byte(contents), 0o600); err != nil {
	83	+ t.Fatal(err)
	84	+ }
	85	+ wrapper := filepath.Join(directory, "ssh")
	86	+ script := "#!/bin/sh\nexec ssh -F " + quote(config) + ` "$@"` + "\n"
	87	+ if err := os.WriteFile(wrapper, []byte(script), 0o755); err != nil {
	88	+ t.Fatal(err)
	89	+ }
	90	+ return wrapper
	91	+}
	92	+
	93	+// envOr returns an environment variable, or fallback when it is unset.
	94	+func envOr(name, fallback string) string {
	95	+ if value := os.Getenv(name); value != "" {
	96	+ return value
	97	+ }
	98	+ return fallback
	99	+}

++package remote
++
++import (
++	"context"
++	"os"
++	"os/exec"
++	"path/filepath"
++	"strings"
++	"testing"
++)
++
++// The real thing, against a real sshd: the demo machine of
++// turbo-editors/demo-remote-machine, or any machine laid out like it.
++// Skipped unless TURBO_CORE_SSH_KEY names the private key it accepts:
++//
++//	cd demo-remote-machine && ./make-key.sh && docker compose up -d --build
++//	TURBO_CORE_SSH_KEY=$PWD/keys/id_demo go test ./remote -run Real -v
++//
++// TURBO_CORE_SSH_PORT (default 2222) and TURBO_CORE_SSH_TARGET (default
++// bob@127.0.0.1:workspace/hello-python) point it elsewhere.
++func TestRealConnectionToTheDemoMachine(t *testing.T) {
++	key := os.Getenv("TURBO_CORE_SSH_KEY")
++	if key == "" {
++		t.Skip("set TURBO_CORE_SSH_KEY to run against a real sshd (see the comment above)")
++	}
++	target, err := ParseTarget(envOr("TURBO_CORE_SSH_TARGET", "bob@127.0.0.1:workspace/hello-python"))
++	if err != nil {
++		t.Fatal(err)
++	}
++	program := sshWithConfig(t, key, envOr("TURBO_CORE_SSH_PORT", "2222"))
++
++	session, err := Connect(context.Background(), target, Options{Program: program})
++	if err != nil {
++		t.Fatal(err)
++	}
++	defer session.Close()
++
++	files := session.FS()
++	working, _ := files.Getwd()
++	if !strings.HasSuffix(working, "/"+filepath.Base(target.Path)) {
++		t.Errorf("working directory = %q", working)
++	}
++	if err := files.WriteFileAtomic("from_the_test.py", []byte("print('written over sftp')\n"), 0o644); err != nil {
++		t.Fatal(err)
++	}
++	if data, err := files.ReadFile("from_the_test.py"); err != nil || string(data) != "print('written over sftp')\n" {
++		t.Errorf("read back %q, %v", data, err)
++	}
++
++	argv := session.RunCommand(working, "python3 from_the_test.py && rm from_the_test.py && pwd", false)
++	output, err := exec.Command(argv[0], argv[1:]...).CombinedOutput()
++	if err != nil {
++		t.Fatalf("running a command over the shared connection: %v\n%s", err, output)
++	}
++	if got := string(output); got != "written over sftp\n"+working+"\n" {
++		t.Errorf("the command printed %q", got)
++	}
++
++	controlPath := session.controlPath
++	if err := session.Close(); err != nil {
++		t.Errorf("Close: %v", err)
++	}
++	check := exec.Command(program, "-S", controlPath, "-O", "check", "--", target.Destination())
++	if check.Run() == nil {
++		t.Error("the shared connection is still up after Close")
++	}
++}
++
++// sshWithConfig writes a wrapper that runs ssh with the port, key and a
++// throwaway known_hosts of its own, so the test changes nothing in ~/.ssh.
++// That is the same thing a Host block in ~/.ssh/config does for a person.
++func sshWithConfig(t *testing.T, key, port string) string {
++	t.Helper()
++	directory := t.TempDir()
++	config := filepath.Join(directory, "config")
++	contents := "Host *\n" +
++		"  Port " + port + "\n" +
++		"  IdentityFile " + key + "\n" +
++		"  IdentitiesOnly yes\n" +
++		"  UserKnownHostsFile " + filepath.Join(directory, "known_hosts") + "\n" +
++		"  StrictHostKeyChecking accept-new\n"
++	if err := os.WriteFile(config, []byte(contents), 0o600); err != nil {
++		t.Fatal(err)
++	}
++	wrapper := filepath.Join(directory, "ssh")
++	script := "#!/bin/sh\nexec ssh -F " + quote(config) + ` "$@"` + "\n"
++	if err := os.WriteFile(wrapper, []byte(script), 0o755); err != nil {
++		t.Fatal(err)
++	}
++	return wrapper
++}
++
++// envOr returns an environment variable, or fallback when it is unset.
++func envOr(name, fallback string) string {
++	if value := os.Getenv(name); value != "" {
++		return value
++	}
++	return fallback
++}

added remote/session.go +359 -0 Viewed

new file mode 100644
@@ -0,0 +1,359 @@
	1	+// Package remote lets an editor work on another machine over ssh: its files,
	2	+// its project tree, its terminals and its tools, as if they were local.
	3	+//
	4	+// It drives the ssh command already installed — not an SSH library — so that
	5	+// everything ssh knows is used as it is: ~/.ssh/config and its Host aliases,
	6	+// the agent, known_hosts, ProxyJump, a key's passphrase, a password. The first
	7	+// connection is made in the foreground before the editor takes the screen,
	8	+// which is where ssh asks for whatever it needs; it becomes a ControlMaster,
	9	+// and everything afterwards travels through that one authenticated connection
	10	+// without asking again:
	11	+//
	12	+// - the files, over one SFTP channel held open for the whole session, which
	13	+// is the fsys.FS the editor is told to Use;
	14	+// - each terminal window, as `ssh -t` running a login shell in the project;
	15	+// - each tool, as `ssh` running the command line with /bin/sh in the project.
	16	+//
	17	+// ControlMaster is an OpenSSH feature that Windows' port does not have, so
	18	+// Connect returns ErrUnsupported there.
	19	+//
	20	+// target, _ := remote.ParseTarget("bob@machine:/srv/app")
	21	+// session, err := remote.Connect(ctx, target, remote.Options{})
	22	+// if err != nil {
	23	+// return err
	24	+// }
	25	+// defer session.Close()
	26	+// fsys.Use(session.FS())
	27	+package remote
	28	+
	29	+import (
	30	+ "bytes"
	31	+ "context"
	32	+ "errors"
	33	+ "fmt"
	34	+ "io/fs"
	35	+ "os"
	36	+ "os/exec"
	37	+ "path/filepath"
	38	+ "runtime"
	39	+ "strings"
	40	+ "sync"
	41	+
	42	+ "github.com/pkg/sftp"
	43	+)
	44	+
	45	+// ErrUnsupported is returned by Connect on a platform whose ssh cannot share
	46	+// a connection — Windows.
	47	+var ErrUnsupported = errors.New("editing over ssh needs OpenSSH's ControlMaster, which this platform's ssh does not have")
	48	+
	49	+// ErrNoSSH is returned by Connect when there is no ssh command to run.
	50	+var ErrNoSSH = errors.New("no ssh command found on PATH")
	51	+
	52	+// controlPersist is how long the shared connection outlives its last user.
	53	+// Every session holds the SFTP channel open until Close, so this only matters
	54	+// after a crash: the connection then goes away on its own instead of lingering.
	55	+const controlPersist = "60"
	56	+
	57	+// Options change how Connect reaches the machine. The zero value is right for
	58	+// an editor.
	59	+type Options struct {
	60	+ // Program is the ssh command. Empty means "ssh", found on PATH.
	61	+ Program string
	62	+}
	63	+
	64	+// Session is a live connection to a machine, and the directory being edited
	65	+// on it.
	66	+type Session struct {
	67	+ target Target
	68	+ program string
	69	+ controlDir string
	70	+ controlPath string
	71	+
	72	+ sftpProcess *exec.Cmd
	73	+ sftpErrors *bytes.Buffer
	74	+ client *sftp.Client
	75	+ files *FS
	76	+
	77	+ closeOnce sync.Once
	78	+}
	79	+
	80	+// Connect logs in to the target, prompting on the terminal if ssh needs to,
	81	+// then opens the file channel and finds the directory to edit.
	82	+//
	83	+// It must be called before the editor takes over the terminal: ssh asks its
	84	+// questions — a password, a passphrase, whether to trust a new host key —
	85	+// on the terminal itself.
	86	+//
	87	+// The directory must exist: a mistyped path is reported here rather than
	88	+// becoming an empty project.
	89	+func Connect(ctx context.Context, target Target, options Options) (*Session, error) {
	90	+ if runtime.GOOS == "windows" {
	91	+ return nil, ErrUnsupported
	92	+ }
	93	+ program, err := findSSH(options.Program)
	94	+ if err != nil {
	95	+ return nil, err
	96	+ }
	97	+
	98	+ s := &Session{target: target, program: program}
	99	+ if err := s.makeControlDir(); err != nil {
	100	+ return nil, err
	101	+ }
	102	+ if err := s.startMaster(ctx); err != nil {
	103	+ s.removeControlDir()
	104	+ return nil, err
	105	+ }
	106	+ if err := s.openFiles(ctx); err != nil {
	107	+ s.Close()
	108	+ return nil, err
	109	+ }
	110	+ return s, nil
	111	+}
	112	+
	113	+// Open is what an editor's -ssh flag does: it reads the argument as a
	114	+// Target, says on standard error where it is connecting — ssh may be about to
	115	+// ask for a password, and the question should not come out of nowhere — and
	116	+// connects with the default Options.
	117	+//
	118	+// session, err := remote.Open(ctx, "bob@machine:/srv/app")
	119	+// if err != nil {
	120	+// return err
	121	+// }
	122	+// defer session.Close()
	123	+func Open(ctx context.Context, argument string) (*Session, error) {
	124	+ target, err := ParseTarget(argument)
	125	+ if err != nil {
	126	+ return nil, err
	127	+ }
	128	+ fmt.Fprintf(os.Stderr, "Connecting to %s…\n", target)
	129	+ return Connect(ctx, target, Options{})
	130	+}
	131	+
	132	+// findSSH resolves the ssh command.
	133	+func findSSH(program string) (string, error) {
	134	+ if program == "" {
	135	+ program = "ssh"
	136	+ }
	137	+ path, err := exec.LookPath(program)
	138	+ if err != nil {
	139	+ return "", fmt.Errorf("%w (%v)", ErrNoSSH, err)
	140	+ }
	141	+ return path, nil
	142	+}
	143	+
	144	+// makeControlDir makes a private directory for the control socket.
	145	+//
	146	+// A Unix socket's path is limited to about a hundred bytes, and macOS's
	147	+// per-user temporary directory is already most of that, so a short base is
	148	+// used when the usual one is too long.
	149	+func (s *Session) makeControlDir() error {
	150	+ base := os.TempDir()
	151	+ if len(base) > 60 {
	152	+ base = "/tmp"
	153	+ }
	154	+ dir, err := os.MkdirTemp(base, "turbo-ssh-")
	155	+ if err != nil {
	156	+ return fmt.Errorf("making a directory for the ssh control socket: %w", err)
	157	+ }
	158	+ s.controlDir = dir
	159	+ s.controlPath = filepath.Join(dir, "control")
	160	+ return nil
	161	+}
	162	+
	163	+// removeControlDir takes the control socket's directory away.
	164	+func (s *Session) removeControlDir() {
	165	+ if s.controlDir != "" {
	166	+ _ = os.RemoveAll(s.controlDir)
	167	+ }
	168	+}
	169	+
	170	+// startMaster makes the first, shared connection, in the foreground.
	171	+//
	172	+// -f is what makes ssh return once it has logged in, leaving the connection
	173	+// running behind the control socket: until then, it owns the terminal and
	174	+// asks there for whatever it needs.
	175	+func (s *Session) startMaster(ctx context.Context) error {
	176	+ command := exec.CommandContext(ctx, s.program, s.masterArgs()...)
	177	+ command.Stdin, command.Stdout, command.Stderr = os.Stdin, os.Stdout, os.Stderr
	178	+ if err := command.Run(); err != nil {
	179	+ return fmt.Errorf("ssh %s: %w", s.target.Destination(), err)
	180	+ }
	181	+ return nil
	182	+}
	183	+
	184	+// masterArgs are the arguments of the first connection.
	185	+func (s *Session) masterArgs() []string {
	186	+ return []string{
	187	+ "-o", "ControlMaster=yes",
	188	+ "-o", "ControlPath=" + s.controlPath,
	189	+ "-o", "ControlPersist=" + controlPersist,
	190	+ "-N", "-f",
	191	+ "--", s.target.Destination(),
	192	+ }
	193	+}
	194	+
	195	+// sharedArgs start every later ssh: through the control socket, never making
	196	+// a connection of its own, never asking anything — the editor owns the
	197	+// terminal by then, and a prompt would be drawn over it.
	198	+func (s *Session) sharedArgs() []string {
	199	+ return []string{
	200	+ s.program,
	201	+ "-S", s.controlPath,
	202	+ "-o", "ControlMaster=no",
	203	+ "-o", "BatchMode=yes",
	204	+ }
	205	+}
	206	+
	207	+// openFiles starts the SFTP channel and resolves the working directory.
	208	+func (s *Session) openFiles(ctx context.Context) error {
	209	+ args := append(s.sharedArgs(), "-s", "--", s.target.Destination(), "sftp")
	210	+ process := exec.CommandContext(ctx, args[0], args[1:]...)
	211	+ s.sftpErrors = &bytes.Buffer{}
	212	+ process.Stderr = s.sftpErrors
	213	+
	214	+ input, err := process.StdinPipe()
	215	+ if err != nil {
	216	+ return err
	217	+ }
	218	+ output, err := process.StdoutPipe()
	219	+ if err != nil {
	220	+ return err
	221	+ }
	222	+ if err := process.Start(); err != nil {
	223	+ return fmt.Errorf("starting the file channel: %w", err)
	224	+ }
	225	+ s.sftpProcess = process
	226	+
	227	+ client, err := sftp.NewClientPipe(output, input)
	228	+ if err != nil {
	229	+ return fmt.Errorf("opening the file channel to %s: %w%s", s.target.Destination(), err, s.channelErrors())
	230	+ }
	231	+ s.client = client
	232	+
	233	+ working, err := workingDirectory(client, s.target.Path)
	234	+ if err != nil {
	235	+ return err
	236	+ }
	237	+ s.files = newFS(client, working)
	238	+ return nil
	239	+}
	240	+
	241	+// channelErrors is what the file channel's ssh said on its way out, if
	242	+// anything, formatted to follow an error.
	243	+func (s *Session) channelErrors() string {
	244	+ said := strings.TrimSpace(s.sftpErrors.String())
	245	+ if said == "" {
	246	+ return ""
	247	+ }
	248	+ return " (" + said + ")"
	249	+}
	250	+
	251	+// workingDirectory turns the path of the target into an absolute directory
	252	+// that exists on the machine. "~" and "~/…" mean the home directory, which is
	253	+// where SFTP resolves a relative path from.
	254	+func workingDirectory(client *sftp.Client, path string) (string, error) {
	255	+ switch {
	256	+ case path == "" \|\| path == "~":
	257	+ path = "."
	258	+ case strings.HasPrefix(path, "~/"):
	259	+ path = strings.TrimPrefix(path, "~/")
	260	+ }
	261	+
	262	+ absolute, err := client.RealPath(path)
	263	+ if err != nil {
	264	+ return "", fmt.Errorf("finding %s on the remote machine: %w", path, err)
	265	+ }
	266	+ info, err := client.Stat(absolute)
	267	+ if err != nil {
	268	+ return "", fmt.Errorf("opening %s on the remote machine: %w", absolute, err)
	269	+ }
	270	+ if !info.IsDir() {
	271	+ return "", fmt.Errorf("%s on the remote machine is not a directory: %w", absolute, fs.ErrInvalid)
	272	+ }
	273	+ return absolute, nil
	274	+}
	275	+
	276	+// FS returns the remote files, rooted at the directory being edited — what
	277	+// the editor passes to fsys.Use.
	278	+func (s Session) FS() FS { return s.files }
	279	+
	280	+// Target returns what was connected to.
	281	+func (s *Session) Target() Target { return s.target }
	282	+
	283	+// Name is how the session is shown to the person: user@host.
	284	+func (s *Session) Name() string { return s.target.Destination() }
	285	+
	286	+// ShellCommand returns the command line that opens an interactive login shell
	287	+// on the machine, in dir, for a terminal window.
	288	+//
	289	+// The remote side is handed to /bin/sh explicitly, because ssh gives the
	290	+// command to the user's own login shell, which may be fish or anything else
	291	+// that does not read `cd … && exec …` the way sh does.
	292	+//
	293	+// argv := session.ShellCommand("/srv/app")
	294	+// // ["ssh", "-S", …, "-t", "--", "bob@machine", "exec /bin/sh -c 'cd …'"]
	295	+func (s *Session) ShellCommand(dir string) []string {
	296	+ script := "cd " + quote(dir) + ` && exec "${SHELL:-/bin/sh}" -l`
	297	+ return s.remoteCommand(true, script)
	298	+}
	299	+
	300	+// RunCommand returns the command line that runs one command line with
	301	+// /bin/sh on the machine, in dir — what a tool does.
	302	+//
	303	+// withTerminal asks for a pseudo-terminal on the far side: that is what a
	304	+// terminal window needs, so that a program there can read the keyboard and
	305	+// Ctrl-C reaches it. A captured run goes without one, so its output is the
	306	+// command's own and not a terminal's rendering of it.
	307	+//
	308	+// argv := session.RunCommand("/srv/app", "python3 -m pytest", false)
	309	+func (s *Session) RunCommand(dir, command string, withTerminal bool) []string {
	310	+ return s.remoteCommand(withTerminal, "cd "+quote(dir)+" && "+command)
	311	+}
	312	+
	313	+// remoteCommand wraps a /bin/sh script into an ssh command line.
	314	+func (s *Session) remoteCommand(withTerminal bool, script string) []string {
	315	+ terminalFlag := "-T"
	316	+ if withTerminal {
	317	+ terminalFlag = "-t"
	318	+ }
	319	+ args := append(s.sharedArgs(), terminalFlag, "--", s.target.Destination())
	320	+ return append(args, "exec /bin/sh -c "+quote(script))
	321	+}
	322	+
	323	+// Close ends the file channel and the shared connection, and removes the
	324	+// control socket. Terminals and tools still running over the connection end
	325	+// with it. Closing twice is safe.
	326	+func (s *Session) Close() error {
	327	+ var err error
	328	+ s.closeOnce.Do(func() {
	329	+ switch {
	330	+ case s.client != nil:
	331	+ err = s.client.Close() // closes ssh's input, which ends it
	332	+ case s.sftpProcess != nil:
	333	+ // The channel started but never spoke SFTP: nothing will close
	334	+ // its input, so waiting for it would wait for ever.
	335	+ _ = s.sftpProcess.Process.Kill()
	336	+ }
	337	+ if s.sftpProcess != nil {
	338	+ _ = s.sftpProcess.Wait()
	339	+ }
	340	+ s.stopMaster()
	341	+ s.removeControlDir()
	342	+ })
	343	+ return err
	344	+}
	345	+
	346	+// stopMaster asks the shared connection to end. A master that has already
	347	+// gone makes this fail, which is the outcome wanted anyway.
	348	+func (s *Session) stopMaster() {
	349	+ args := append(s.sharedArgs(), "-O", "exit", "--", s.target.Destination())
	350	+ stop := exec.Command(args[0], args[1:]...)
	351	+ _ = stop.Run()
	352	+}
	353	+
	354	+// quote makes s one word for /bin/sh, whatever it holds.
	355	+//
	356	+// quote("it's") // 'it'\''s'
	357	+func quote(s string) string {
	358	+ return "'" + strings.ReplaceAll(s, "'", `'\''`) + "'"
	359	+}

++// Package remote lets an editor work on another machine over ssh: its files,
++// its project tree, its terminals and its tools, as if they were local.
++//
++// It drives the ssh command already installed — not an SSH library — so that
++// everything ssh knows is used as it is: ~/.ssh/config and its Host aliases,
++// the agent, known_hosts, ProxyJump, a key's passphrase, a password. The first
++// connection is made in the foreground before the editor takes the screen,
++// which is where ssh asks for whatever it needs; it becomes a ControlMaster,
++// and everything afterwards travels through that one authenticated connection
++// without asking again:
++//
++//   - the files, over one SFTP channel held open for the whole session, which
++//     is the fsys.FS the editor is told to Use;
++//   - each terminal window, as `ssh -t` running a login shell in the project;
++//   - each tool, as `ssh` running the command line with /bin/sh in the project.
++//
++// ControlMaster is an OpenSSH feature that Windows' port does not have, so
++// Connect returns ErrUnsupported there.
++//
++//	target, _ := remote.ParseTarget("bob@machine:/srv/app")
++//	session, err := remote.Connect(ctx, target, remote.Options{})
++//	if err != nil {
++//		return err
++//	}
++//	defer session.Close()
++//	fsys.Use(session.FS())
++package remote
++
++import (
++	"bytes"
++	"context"
++	"errors"
++	"fmt"
++	"io/fs"
++	"os"
++	"os/exec"
++	"path/filepath"
++	"runtime"
++	"strings"
++	"sync"
++
++	"github.com/pkg/sftp"
++)
++
++// ErrUnsupported is returned by Connect on a platform whose ssh cannot share
++// a connection — Windows.
++var ErrUnsupported = errors.New("editing over ssh needs OpenSSH's ControlMaster, which this platform's ssh does not have")
++
++// ErrNoSSH is returned by Connect when there is no ssh command to run.
++var ErrNoSSH = errors.New("no ssh command found on PATH")
++
++// controlPersist is how long the shared connection outlives its last user.
++// Every session holds the SFTP channel open until Close, so this only matters
++// after a crash: the connection then goes away on its own instead of lingering.
++const controlPersist = "60"
++
++// Options change how Connect reaches the machine. The zero value is right for
++// an editor.
++type Options struct {
++	// Program is the ssh command. Empty means "ssh", found on PATH.
++	Program string
++}
++
++// Session is a live connection to a machine, and the directory being edited
++// on it.
++type Session struct {
++	target      Target
++	program     string
++	controlDir  string
++	controlPath string
++
++	sftpProcess *exec.Cmd
++	sftpErrors  *bytes.Buffer
++	client      *sftp.Client
++	files       *FS
++
++	closeOnce sync.Once
++}
++
++// Connect logs in to the target, prompting on the terminal if ssh needs to,
++// then opens the file channel and finds the directory to edit.
++//
++// It must be called before the editor takes over the terminal: ssh asks its
++// questions — a password, a passphrase, whether to trust a new host key —
++// on the terminal itself.
++//
++// The directory must exist: a mistyped path is reported here rather than
++// becoming an empty project.
++func Connect(ctx context.Context, target Target, options Options) (*Session, error) {
++	if runtime.GOOS == "windows" {
++		return nil, ErrUnsupported
++	}
++	program, err := findSSH(options.Program)
++	if err != nil {
++		return nil, err
++	}
++
++	s := &Session{target: target, program: program}
++	if err := s.makeControlDir(); err != nil {
++		return nil, err
++	}
++	if err := s.startMaster(ctx); err != nil {
++		s.removeControlDir()
++		return nil, err
++	}
++	if err := s.openFiles(ctx); err != nil {
++		s.Close()
++		return nil, err
++	}
++	return s, nil
++}
++
++// Open is what an editor's -ssh flag does: it reads the argument as a
++// Target, says on standard error where it is connecting — ssh may be about to
++// ask for a password, and the question should not come out of nowhere — and
++// connects with the default Options.
++//
++//	session, err := remote.Open(ctx, "bob@machine:/srv/app")
++//	if err != nil {
++//		return err
++//	}
++//	defer session.Close()
++func Open(ctx context.Context, argument string) (*Session, error) {
++	target, err := ParseTarget(argument)
++	if err != nil {
++		return nil, err
++	}
++	fmt.Fprintf(os.Stderr, "Connecting to %s…\n", target)
++	return Connect(ctx, target, Options{})
++}
++
++// findSSH resolves the ssh command.
++func findSSH(program string) (string, error) {
++	if program == "" {
++		program = "ssh"
++	}
++	path, err := exec.LookPath(program)
++	if err != nil {
++		return "", fmt.Errorf("%w (%v)", ErrNoSSH, err)
++	}
++	return path, nil
++}
++
++// makeControlDir makes a private directory for the control socket.
++//
++// A Unix socket's path is limited to about a hundred bytes, and macOS's
++// per-user temporary directory is already most of that, so a short base is
++// used when the usual one is too long.
++func (s *Session) makeControlDir() error {
++	base := os.TempDir()
++	if len(base) > 60 {
++		base = "/tmp"
++	}
++	dir, err := os.MkdirTemp(base, "turbo-ssh-")
++	if err != nil {
++		return fmt.Errorf("making a directory for the ssh control socket: %w", err)
++	}
++	s.controlDir = dir
++	s.controlPath = filepath.Join(dir, "control")
++	return nil
++}
++
++// removeControlDir takes the control socket's directory away.
++func (s *Session) removeControlDir() {
++	if s.controlDir != "" {
++		_ = os.RemoveAll(s.controlDir)
++	}
++}
++
++// startMaster makes the first, shared connection, in the foreground.
++//
++// -f is what makes ssh return once it has logged in, leaving the connection
++// running behind the control socket: until then, it owns the terminal and
++// asks there for whatever it needs.
++func (s *Session) startMaster(ctx context.Context) error {
++	command := exec.CommandContext(ctx, s.program, s.masterArgs()...)
++	command.Stdin, command.Stdout, command.Stderr = os.Stdin, os.Stdout, os.Stderr
++	if err := command.Run(); err != nil {
++		return fmt.Errorf("ssh %s: %w", s.target.Destination(), err)
++	}
++	return nil
++}
++
++// masterArgs are the arguments of the first connection.
++func (s *Session) masterArgs() []string {
++	return []string{
++		"-o", "ControlMaster=yes",
++		"-o", "ControlPath=" + s.controlPath,
++		"-o", "ControlPersist=" + controlPersist,
++		"-N", "-f",
++		"--", s.target.Destination(),
++	}
++}
++
++// sharedArgs start every later ssh: through the control socket, never making
++// a connection of its own, never asking anything — the editor owns the
++// terminal by then, and a prompt would be drawn over it.
++func (s *Session) sharedArgs() []string {
++	return []string{
++		s.program,
++		"-S", s.controlPath,
++		"-o", "ControlMaster=no",
++		"-o", "BatchMode=yes",
++	}
++}
++
++// openFiles starts the SFTP channel and resolves the working directory.
++func (s *Session) openFiles(ctx context.Context) error {
++	args := append(s.sharedArgs(), "-s", "--", s.target.Destination(), "sftp")
++	process := exec.CommandContext(ctx, args[0], args[1:]...)
++	s.sftpErrors = &bytes.Buffer{}
++	process.Stderr = s.sftpErrors
++
++	input, err := process.StdinPipe()
++	if err != nil {
++		return err
++	}
++	output, err := process.StdoutPipe()
++	if err != nil {
++		return err
++	}
++	if err := process.Start(); err != nil {
++		return fmt.Errorf("starting the file channel: %w", err)
++	}
++	s.sftpProcess = process
++
++	client, err := sftp.NewClientPipe(output, input)
++	if err != nil {
++		return fmt.Errorf("opening the file channel to %s: %w%s", s.target.Destination(), err, s.channelErrors())
++	}
++	s.client = client
++
++	working, err := workingDirectory(client, s.target.Path)
++	if err != nil {
++		return err
++	}
++	s.files = newFS(client, working)
++	return nil
++}
++
++// channelErrors is what the file channel's ssh said on its way out, if
++// anything, formatted to follow an error.
++func (s *Session) channelErrors() string {
++	said := strings.TrimSpace(s.sftpErrors.String())
++	if said == "" {
++		return ""
++	}
++	return " (" + said + ")"
++}
++
++// workingDirectory turns the path of the target into an absolute directory
++// that exists on the machine. "~" and "~/…" mean the home directory, which is
++// where SFTP resolves a relative path from.
++func workingDirectory(client *sftp.Client, path string) (string, error) {
++	switch {
++	case path == "" || path == "~":
++		path = "."
++	case strings.HasPrefix(path, "~/"):
++		path = strings.TrimPrefix(path, "~/")
++	}
++
++	absolute, err := client.RealPath(path)
++	if err != nil {
++		return "", fmt.Errorf("finding %s on the remote machine: %w", path, err)
++	}
++	info, err := client.Stat(absolute)
++	if err != nil {
++		return "", fmt.Errorf("opening %s on the remote machine: %w", absolute, err)
++	}
++	if !info.IsDir() {
++		return "", fmt.Errorf("%s on the remote machine is not a directory: %w", absolute, fs.ErrInvalid)
++	}
++	return absolute, nil
++}
++
++// FS returns the remote files, rooted at the directory being edited — what
++// the editor passes to fsys.Use.
++func (s *Session) FS() *FS { return s.files }
++
++// Target returns what was connected to.
++func (s *Session) Target() Target { return s.target }
++
++// Name is how the session is shown to the person: user@host.
++func (s *Session) Name() string { return s.target.Destination() }
++
++// ShellCommand returns the command line that opens an interactive login shell
++// on the machine, in dir, for a terminal window.
++//
++// The remote side is handed to /bin/sh explicitly, because ssh gives the
++// command to the user's own login shell, which may be fish or anything else
++// that does not read `cd … && exec …` the way sh does.
++//
++//	argv := session.ShellCommand("/srv/app")
++//	// ["ssh", "-S", …, "-t", "--", "bob@machine", "exec /bin/sh -c 'cd …'"]
++func (s *Session) ShellCommand(dir string) []string {
++	script := "cd " + quote(dir) + ` && exec "${SHELL:-/bin/sh}" -l`
++	return s.remoteCommand(true, script)
++}
++
++// RunCommand returns the command line that runs one command line with
++// /bin/sh on the machine, in dir — what a tool does.
++//
++// withTerminal asks for a pseudo-terminal on the far side: that is what a
++// terminal window needs, so that a program there can read the keyboard and
++// Ctrl-C reaches it. A captured run goes without one, so its output is the
++// command's own and not a terminal's rendering of it.
++//
++//	argv := session.RunCommand("/srv/app", "python3 -m pytest", false)
++func (s *Session) RunCommand(dir, command string, withTerminal bool) []string {
++	return s.remoteCommand(withTerminal, "cd "+quote(dir)+" && "+command)
++}
++
++// remoteCommand wraps a /bin/sh script into an ssh command line.
++func (s *Session) remoteCommand(withTerminal bool, script string) []string {
++	terminalFlag := "-T"
++	if withTerminal {
++		terminalFlag = "-t"
++	}
++	args := append(s.sharedArgs(), terminalFlag, "--", s.target.Destination())
++	return append(args, "exec /bin/sh -c "+quote(script))
++}
++
++// Close ends the file channel and the shared connection, and removes the
++// control socket. Terminals and tools still running over the connection end
++// with it. Closing twice is safe.
++func (s *Session) Close() error {
++	var err error
++	s.closeOnce.Do(func() {
++		switch {
++		case s.client != nil:
++			err = s.client.Close() // closes ssh's input, which ends it
++		case s.sftpProcess != nil:
++			// The channel started but never spoke SFTP: nothing will close
++			// its input, so waiting for it would wait for ever.
++			_ = s.sftpProcess.Process.Kill()
++		}
++		if s.sftpProcess != nil {
++			_ = s.sftpProcess.Wait()
++		}
++		s.stopMaster()
++		s.removeControlDir()
++	})
++	return err
++}
++
++// stopMaster asks the shared connection to end. A master that has already
++// gone makes this fail, which is the outcome wanted anyway.
++func (s *Session) stopMaster() {
++	args := append(s.sharedArgs(), "-O", "exit", "--", s.target.Destination())
++	stop := exec.Command(args[0], args[1:]...)
++	_ = stop.Run()
++}
++
++// quote makes s one word for /bin/sh, whatever it holds.
++//
++//	quote("it's") // 'it'\''s'
++func quote(s string) string {
++	return "'" + strings.ReplaceAll(s, "'", `'\''`) + "'"
++}

added remote/session_test.go +246 -0 Viewed

new file mode 100644
@@ -0,0 +1,246 @@
	1	+package remote
	2	+
	3	+import (
	4	+ "context"
	5	+ "errors"
	6	+ "fmt"
	7	+ "os"
	8	+ "path/filepath"
	9	+ "runtime"
	10	+ "slices"
	11	+ "strings"
	12	+ "testing"
	13	+
	14	+ "github.com/pkg/sftp"
	15	+)
	16	+
	17	+// The environment variables that turn the test binary into a fake ssh.
	18	+const (
	19	+ fakeSSHEnv = "TURBO_REMOTE_FAKE_SSH" // set: behave as ssh
	20	+ fakeHomeEnv = "TURBO_REMOTE_FAKE_HOME" // the "remote" home directory
	21	+ fakeLogEnv = "TURBO_REMOTE_FAKE_LOG" // where each invocation is recorded
	22	+ fakeFailEnv = "TURBO_REMOTE_FAKE_FAIL_LOG" // set: the login fails
	23	+)
	24	+
	25	+// TestMain lets the test binary stand in for ssh, so that Connect and Close
	26	+// run end to end — processes, pipes, a real SFTP conversation — without a
	27	+// network or a second machine.
	28	+func TestMain(m *testing.M) {
	29	+ if os.Getenv(fakeSSHEnv) != "" {
	30	+ os.Exit(fakeSSH(os.Args[1:]))
	31	+ }
	32	+ os.Exit(m.Run())
	33	+}
	34	+
	35	+// fakeSSH does what ssh would for the three invocations Session makes: log in
	36	+// (-N), open the SFTP subsystem (-s), and stop the master (-O exit).
	37	+func fakeSSH(args []string) int {
	38	+ if log := os.Getenv(fakeLogEnv); log != "" {
	39	+ f, err := os.OpenFile(log, os.O_APPEND\|os.O_CREATE\|os.O_WRONLY, 0o644)
	40	+ if err == nil {
	41	+ fmt.Fprintln(f, strings.Join(args, " "))
	42	+ f.Close()
	43	+ }
	44	+ }
	45	+ switch {
	46	+ case slices.Contains(args, "-N"):
	47	+ if os.Getenv(fakeFailEnv) != "" {
	48	+ fmt.Fprintln(os.Stderr, "Permission denied (publickey,password).")
	49	+ return 255
	50	+ }
	51	+ return 0
	52	+ case slices.Contains(args, "-s") && os.Getenv("TURBO_REMOTE_FAKE_NO_SFTP") != "":
	53	+ fmt.Fprintln(os.Stderr, "subsystem request failed on channel 0")
	54	+ return 1
	55	+ case slices.Contains(args, "-s"):
	56	+ server, err := sftp.NewServer(pipe{os.Stdin, os.Stdout}, sftp.WithServerWorkingDirectory(os.Getenv(fakeHomeEnv)))
	57	+ if err != nil {
	58	+ return 1
	59	+ }
	60	+ _ = server.Serve()
	61	+ return 0
	62	+ default:
	63	+ return 0
	64	+ }
	65	+}
	66	+
	67	+// fakeSession points Connect at the fake ssh, with a home directory holding
	68	+// an app/ directory, and returns where invocations are logged.
	69	+func fakeSession(t *testing.T) (home, log string) {
	70	+ t.Helper()
	71	+ if runtime.GOOS == "windows" {
	72	+ t.Skip("Connect is unsupported on Windows")
	73	+ }
	74	+ home = t.TempDir()
	75	+ if err := os.Mkdir(filepath.Join(home, "app"), 0o755); err != nil {
	76	+ t.Fatal(err)
	77	+ }
	78	+ log = filepath.Join(t.TempDir(), "ssh.log")
	79	+ t.Setenv(fakeSSHEnv, "1")
	80	+ t.Setenv(fakeHomeEnv, home)
	81	+ t.Setenv(fakeLogEnv, log)
	82	+ return home, log
	83	+}
	84	+
	85	+// invocations returns what the fake ssh was asked to do, one line each.
	86	+func invocations(t *testing.T, log string) []string {
	87	+ t.Helper()
	88	+ data, err := os.ReadFile(log)
	89	+ if err != nil {
	90	+ t.Fatal(err)
	91	+ }
	92	+ return strings.Split(strings.TrimSpace(string(data)), "\n")
	93	+}
	94	+
	95	+func TestConnectLogsInOpensTheFilesAndCloseStopsTheMaster(t *testing.T) {
	96	+ home, log := fakeSession(t)
	97	+
	98	+ session, err := Connect(context.Background(), Target{User: "bob", Host: "machine", Path: "app"}, Options{Program: os.Args[0]})
	99	+ if err != nil {
	100	+ t.Fatal(err)
	101	+ }
	102	+ if working, _ := session.FS().Getwd(); working != filepath.Join(home, "app") {
	103	+ t.Errorf("working directory = %q, want %q", working, filepath.Join(home, "app"))
	104	+ }
	105	+ if err := session.FS().WriteFileAtomic("hello.py", []byte("print('hi')\n"), 0o644); err != nil {
	106	+ t.Fatal(err)
	107	+ }
	108	+ if data, _ := os.ReadFile(filepath.Join(home, "app", "hello.py")); string(data) != "print('hi')\n" {
	109	+ t.Errorf("the file on the far side holds %q", data)
	110	+ }
	111	+ controlDir := session.controlDir
	112	+
	113	+ if err := session.Close(); err != nil {
	114	+ t.Errorf("Close: %v", err)
	115	+ }
	116	+ if err := session.Close(); err != nil {
	117	+ t.Errorf("a second Close: %v", err)
	118	+ }
	119	+
	120	+ calls := invocations(t, log)
	121	+ if len(calls) != 3 {
	122	+ t.Fatalf("ssh was run %d times, want 3 (log in, files, stop):\n%s", len(calls), strings.Join(calls, "\n"))
	123	+ }
	124	+ if !strings.Contains(calls[0], "-N -f -- bob@machine") \|\| !strings.Contains(calls[0], "ControlMaster=yes") {
	125	+ t.Errorf("the login was %q", calls[0])
	126	+ }
	127	+ if !strings.HasSuffix(calls[1], "-s -- bob@machine sftp") \|\| !strings.Contains(calls[1], "BatchMode=yes") {
	128	+ t.Errorf("the file channel was %q", calls[1])
	129	+ }
	130	+ if !strings.Contains(calls[2], "-O exit -- bob@machine") {
	131	+ t.Errorf("the stop was %q", calls[2])
	132	+ }
	133	+ if _, err := os.Stat(controlDir); !errors.Is(err, os.ErrNotExist) {
	134	+ t.Errorf("the control socket's directory is still there after Close")
	135	+ }
	136	+}
	137	+
	138	+func TestAFailedLoginIsReportedAndLeavesNothingBehind(t *testing.T) {
	139	+ fakeSession(t)
	140	+ t.Setenv(fakeFailEnv, "1")
	141	+ before, _ := filepath.Glob(filepath.Join(os.TempDir(), "turbo-ssh-*"))
	142	+
	143	+ _, err := Connect(context.Background(), Target{User: "bob", Host: "machine"}, Options{Program: os.Args[0]})
	144	+ if err == nil \|\| !strings.Contains(err.Error(), "ssh bob@machine") {
	145	+ t.Errorf("err = %v, want one naming the destination", err)
	146	+ }
	147	+ after, _ := filepath.Glob(filepath.Join(os.TempDir(), "turbo-ssh-*"))
	148	+ if len(after) != len(before) {
	149	+ t.Errorf("a control directory was left behind: %v", after)
	150	+ }
	151	+}
	152	+
	153	+func TestConnectRefusesADirectoryThatIsNotThere(t *testing.T) {
	154	+ fakeSession(t)
	155	+ _, err := Connect(context.Background(), Target{User: "bob", Host: "machine", Path: "nope"}, Options{Program: os.Args[0]})
	156	+ if err == nil \|\| !strings.Contains(err.Error(), "nope") {
	157	+ t.Errorf("err = %v, want one naming the missing directory", err)
	158	+ }
	159	+}
	160	+
	161	+func TestConnectWithoutSSHSaysSo(t *testing.T) {
	162	+ if runtime.GOOS == "windows" {
	163	+ t.Skip("Connect is unsupported on Windows")
	164	+ }
	165	+ _, err := Connect(context.Background(), Target{Host: "machine"}, Options{Program: "no-such-ssh-anywhere"})
	166	+ if !errors.Is(err, ErrNoSSH) {
	167	+ t.Errorf("err = %v, want ErrNoSSH", err)
	168	+ }
	169	+}
	170	+
	171	+// commandSession is a session with nothing behind it, for checking the
	172	+// command lines it writes.
	173	+func commandSession() *Session {
	174	+ return &Session{target: Target{User: "bob", Host: "machine"}, program: "ssh", controlPath: "/tmp/turbo-ssh-1/control"}
	175	+}
	176	+
	177	+func TestShellCommandOpensALoginShellInTheDirectoryThroughTheSharedConnection(t *testing.T) {
	178	+ got := commandSession().ShellCommand("/home/bob/my app")
	179	+ want := []string{
	180	+ "ssh", "-S", "/tmp/turbo-ssh-1/control", "-o", "ControlMaster=no", "-o", "BatchMode=yes",
	181	+ "-t", "--", "bob@machine",
	182	+ `exec /bin/sh -c 'cd '\''/home/bob/my app'\'' && exec "${SHELL:-/bin/sh}" -l'`,
	183	+ }
	184	+ if !slices.Equal(got, want) {
	185	+ t.Errorf("ShellCommand =\n%q\nwant\n%q", got, want)
	186	+ }
	187	+}
	188	+
	189	+func TestRunCommandRunsTheCommandLineWithShInTheDirectory(t *testing.T) {
	190	+ s := commandSession()
	191	+
	192	+ captured := s.RunCommand("/srv/app", "python3 main.py \| tee out", false)
	193	+ if captured[7] != "-T" {
	194	+ t.Errorf("a captured run asks for %q, want -T (no terminal)", captured[7])
	195	+ }
	196	+ if last := captured[len(captured)-1]; last != `exec /bin/sh -c 'cd '\''/srv/app'\'' && python3 main.py \| tee out'` {
	197	+ t.Errorf("remote command = %s", last)
	198	+ }
	199	+
	200	+ inTerminal := s.RunCommand("/srv/app", "python3", true)
	201	+ if inTerminal[7] != "-t" {
	202	+ t.Errorf("a run in a terminal asks for %q, want -t", inTerminal[7])
	203	+ }
	204	+}
	205	+
	206	+func TestQuoteMakesAnyStringOneShellWord(t *testing.T) {
	207	+ cases := map[string]string{
	208	+ "plain": "'plain'",
	209	+ "with space": "'with space'",
	210	+ "it's": `'it'\''s'`,
	211	+ "$HOME;rm": "'$HOME;rm'",
	212	+ "": "''",
	213	+ }
	214	+ for in, want := range cases {
	215	+ if got := quote(in); got != want {
	216	+ t.Errorf("quote(%q) = %s, want %s", in, got, want)
	217	+ }
	218	+ }
	219	+}
	220	+
	221	+func TestNameIsUserAtHost(t *testing.T) {
	222	+ if got := commandSession().Name(); got != "bob@machine" {
	223	+ t.Errorf("Name = %q", got)
	224	+ }
	225	+}
	226	+
	227	+func TestOpenRefusesABadTargetWithoutRunningSSH(t *testing.T) {
	228	+ _, log := fakeSession(t)
	229	+ if _, err := Open(context.Background(), "-oProxyCommand=evil"); !errors.Is(err, ErrBadTarget) {
	230	+ t.Errorf("err = %v, want ErrBadTarget", err)
	231	+ }
	232	+ if _, err := os.Stat(log); !errors.Is(err, os.ErrNotExist) {
	233	+ t.Error("ssh was run for a target that was refused")
	234	+ }
	235	+}
	236	+
	237	+func TestAChannelThatNeverSpeaksSFTPIsReportedAndCloseDoesNotHang(t *testing.T) {
	238	+ fakeSession(t)
	239	+ // The fake then refuses the subsystem, as a server with no sftp does.
	240	+ t.Setenv("TURBO_REMOTE_FAKE_NO_SFTP", "1")
	241	+
	242	+ _, err := Connect(context.Background(), Target{User: "bob", Host: "machine"}, Options{Program: os.Args[0]})
	243	+ if err == nil {
	244	+ t.Fatal("Connect succeeded without a file channel")
	245	+ }
	246	+}

++package remote
++
++import (
++	"context"
++	"errors"
++	"fmt"
++	"os"
++	"path/filepath"
++	"runtime"
++	"slices"
++	"strings"
++	"testing"
++
++	"github.com/pkg/sftp"
++)
++
++// The environment variables that turn the test binary into a fake ssh.
++const (
++	fakeSSHEnv  = "TURBO_REMOTE_FAKE_SSH"      // set: behave as ssh
++	fakeHomeEnv = "TURBO_REMOTE_FAKE_HOME"     // the "remote" home directory
++	fakeLogEnv  = "TURBO_REMOTE_FAKE_LOG"      // where each invocation is recorded
++	fakeFailEnv = "TURBO_REMOTE_FAKE_FAIL_LOG" // set: the login fails
++)
++
++// TestMain lets the test binary stand in for ssh, so that Connect and Close
++// run end to end — processes, pipes, a real SFTP conversation — without a
++// network or a second machine.
++func TestMain(m *testing.M) {
++	if os.Getenv(fakeSSHEnv) != "" {
++		os.Exit(fakeSSH(os.Args[1:]))
++	}
++	os.Exit(m.Run())
++}
++
++// fakeSSH does what ssh would for the three invocations Session makes: log in
++// (-N), open the SFTP subsystem (-s), and stop the master (-O exit).
++func fakeSSH(args []string) int {
++	if log := os.Getenv(fakeLogEnv); log != "" {
++		f, err := os.OpenFile(log, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o644)
++		if err == nil {
++			fmt.Fprintln(f, strings.Join(args, " "))
++			f.Close()
++		}
++	}
++	switch {
++	case slices.Contains(args, "-N"):
++		if os.Getenv(fakeFailEnv) != "" {
++			fmt.Fprintln(os.Stderr, "Permission denied (publickey,password).")
++			return 255
++		}
++		return 0
++	case slices.Contains(args, "-s") && os.Getenv("TURBO_REMOTE_FAKE_NO_SFTP") != "":
++		fmt.Fprintln(os.Stderr, "subsystem request failed on channel 0")
++		return 1
++	case slices.Contains(args, "-s"):
++		server, err := sftp.NewServer(pipe{os.Stdin, os.Stdout}, sftp.WithServerWorkingDirectory(os.Getenv(fakeHomeEnv)))
++		if err != nil {
++			return 1
++		}
++		_ = server.Serve()
++		return 0
++	default:
++		return 0
++	}
++}
++
++// fakeSession points Connect at the fake ssh, with a home directory holding
++// an app/ directory, and returns where invocations are logged.
++func fakeSession(t *testing.T) (home, log string) {
++	t.Helper()
++	if runtime.GOOS == "windows" {
++		t.Skip("Connect is unsupported on Windows")
++	}
++	home = t.TempDir()
++	if err := os.Mkdir(filepath.Join(home, "app"), 0o755); err != nil {
++		t.Fatal(err)
++	}
++	log = filepath.Join(t.TempDir(), "ssh.log")
++	t.Setenv(fakeSSHEnv, "1")
++	t.Setenv(fakeHomeEnv, home)
++	t.Setenv(fakeLogEnv, log)
++	return home, log
++}
++
++// invocations returns what the fake ssh was asked to do, one line each.
++func invocations(t *testing.T, log string) []string {
++	t.Helper()
++	data, err := os.ReadFile(log)
++	if err != nil {
++		t.Fatal(err)
++	}
++	return strings.Split(strings.TrimSpace(string(data)), "\n")
++}
++
++func TestConnectLogsInOpensTheFilesAndCloseStopsTheMaster(t *testing.T) {
++	home, log := fakeSession(t)
++
++	session, err := Connect(context.Background(), Target{User: "bob", Host: "machine", Path: "app"}, Options{Program: os.Args[0]})
++	if err != nil {
++		t.Fatal(err)
++	}
++	if working, _ := session.FS().Getwd(); working != filepath.Join(home, "app") {
++		t.Errorf("working directory = %q, want %q", working, filepath.Join(home, "app"))
++	}
++	if err := session.FS().WriteFileAtomic("hello.py", []byte("print('hi')\n"), 0o644); err != nil {
++		t.Fatal(err)
++	}
++	if data, _ := os.ReadFile(filepath.Join(home, "app", "hello.py")); string(data) != "print('hi')\n" {
++		t.Errorf("the file on the far side holds %q", data)
++	}
++	controlDir := session.controlDir
++
++	if err := session.Close(); err != nil {
++		t.Errorf("Close: %v", err)
++	}
++	if err := session.Close(); err != nil {
++		t.Errorf("a second Close: %v", err)
++	}
++
++	calls := invocations(t, log)
++	if len(calls) != 3 {
++		t.Fatalf("ssh was run %d times, want 3 (log in, files, stop):\n%s", len(calls), strings.Join(calls, "\n"))
++	}
++	if !strings.Contains(calls[0], "-N -f -- bob@machine") || !strings.Contains(calls[0], "ControlMaster=yes") {
++		t.Errorf("the login was %q", calls[0])
++	}
++	if !strings.HasSuffix(calls[1], "-s -- bob@machine sftp") || !strings.Contains(calls[1], "BatchMode=yes") {
++		t.Errorf("the file channel was %q", calls[1])
++	}
++	if !strings.Contains(calls[2], "-O exit -- bob@machine") {
++		t.Errorf("the stop was %q", calls[2])
++	}
++	if _, err := os.Stat(controlDir); !errors.Is(err, os.ErrNotExist) {
++		t.Errorf("the control socket's directory is still there after Close")
++	}
++}
++
++func TestAFailedLoginIsReportedAndLeavesNothingBehind(t *testing.T) {
++	fakeSession(t)
++	t.Setenv(fakeFailEnv, "1")
++	before, _ := filepath.Glob(filepath.Join(os.TempDir(), "turbo-ssh-*"))
++
++	_, err := Connect(context.Background(), Target{User: "bob", Host: "machine"}, Options{Program: os.Args[0]})
++	if err == nil || !strings.Contains(err.Error(), "ssh bob@machine") {
++		t.Errorf("err = %v, want one naming the destination", err)
++	}
++	after, _ := filepath.Glob(filepath.Join(os.TempDir(), "turbo-ssh-*"))
++	if len(after) != len(before) {
++		t.Errorf("a control directory was left behind: %v", after)
++	}
++}
++
++func TestConnectRefusesADirectoryThatIsNotThere(t *testing.T) {
++	fakeSession(t)
++	_, err := Connect(context.Background(), Target{User: "bob", Host: "machine", Path: "nope"}, Options{Program: os.Args[0]})
++	if err == nil || !strings.Contains(err.Error(), "nope") {
++		t.Errorf("err = %v, want one naming the missing directory", err)
++	}
++}
++
++func TestConnectWithoutSSHSaysSo(t *testing.T) {
++	if runtime.GOOS == "windows" {
++		t.Skip("Connect is unsupported on Windows")
++	}
++	_, err := Connect(context.Background(), Target{Host: "machine"}, Options{Program: "no-such-ssh-anywhere"})
++	if !errors.Is(err, ErrNoSSH) {
++		t.Errorf("err = %v, want ErrNoSSH", err)
++	}
++}
++
++// commandSession is a session with nothing behind it, for checking the
++// command lines it writes.
++func commandSession() *Session {
++	return &Session{target: Target{User: "bob", Host: "machine"}, program: "ssh", controlPath: "/tmp/turbo-ssh-1/control"}
++}
++
++func TestShellCommandOpensALoginShellInTheDirectoryThroughTheSharedConnection(t *testing.T) {
++	got := commandSession().ShellCommand("/home/bob/my app")
++	want := []string{
++		"ssh", "-S", "/tmp/turbo-ssh-1/control", "-o", "ControlMaster=no", "-o", "BatchMode=yes",
++		"-t", "--", "bob@machine",
++		`exec /bin/sh -c 'cd '\''/home/bob/my app'\'' && exec "${SHELL:-/bin/sh}" -l'`,
++	}
++	if !slices.Equal(got, want) {
++		t.Errorf("ShellCommand =\n%q\nwant\n%q", got, want)
++	}
++}
++
++func TestRunCommandRunsTheCommandLineWithShInTheDirectory(t *testing.T) {
++	s := commandSession()
++
++	captured := s.RunCommand("/srv/app", "python3 main.py | tee out", false)
++	if captured[7] != "-T" {
++		t.Errorf("a captured run asks for %q, want -T (no terminal)", captured[7])
++	}
++	if last := captured[len(captured)-1]; last != `exec /bin/sh -c 'cd '\''/srv/app'\'' && python3 main.py | tee out'` {
++		t.Errorf("remote command = %s", last)
++	}
++
++	inTerminal := s.RunCommand("/srv/app", "python3", true)
++	if inTerminal[7] != "-t" {
++		t.Errorf("a run in a terminal asks for %q, want -t", inTerminal[7])
++	}
++}
++
++func TestQuoteMakesAnyStringOneShellWord(t *testing.T) {
++	cases := map[string]string{
++		"plain":      "'plain'",
++		"with space": "'with space'",
++		"it's":       `'it'\''s'`,
++		"$HOME;rm":   "'$HOME;rm'",
++		"":           "''",
++	}
++	for in, want := range cases {
++		if got := quote(in); got != want {
++			t.Errorf("quote(%q) = %s, want %s", in, got, want)
++		}
++	}
++}
++
++func TestNameIsUserAtHost(t *testing.T) {
++	if got := commandSession().Name(); got != "bob@machine" {
++		t.Errorf("Name = %q", got)
++	}
++}
++
++func TestOpenRefusesABadTargetWithoutRunningSSH(t *testing.T) {
++	_, log := fakeSession(t)
++	if _, err := Open(context.Background(), "-oProxyCommand=evil"); !errors.Is(err, ErrBadTarget) {
++		t.Errorf("err = %v, want ErrBadTarget", err)
++	}
++	if _, err := os.Stat(log); !errors.Is(err, os.ErrNotExist) {
++		t.Error("ssh was run for a target that was refused")
++	}
++}
++
++func TestAChannelThatNeverSpeaksSFTPIsReportedAndCloseDoesNotHang(t *testing.T) {
++	fakeSession(t)
++	// The fake then refuses the subsystem, as a server with no sftp does.
++	t.Setenv("TURBO_REMOTE_FAKE_NO_SFTP", "1")
++
++	_, err := Connect(context.Background(), Target{User: "bob", Host: "machine"}, Options{Program: os.Args[0]})
++	if err == nil {
++		t.Fatal("Connect succeeded without a file channel")
++	}
++}

added remote/target.go +121 -0 Viewed

new file mode 100644
@@ -0,0 +1,121 @@
	1	+package remote
	2	+
	3	+import (
	4	+ "errors"
	5	+ "fmt"
	6	+ "strings"
	7	+)
	8	+
	9	+// ErrBadTarget is what ParseTarget returns for something that is not
	10	+// user@machine[:path].
	11	+var ErrBadTarget = errors.New("not a remote target; expected user@machine or user@machine:/path")
	12	+
	13	+// Target is the machine an editor was asked to work on, and where on it.
	14	+//
	15	+// target, err := remote.ParseTarget("bob@build-box:/srv/app")
	16	+// // target.User == "bob", target.Host == "build-box", target.Path == "/srv/app"
	17	+type Target struct {
	18	+ // User is who to log in as. Empty leaves it to ssh: the User line of
	19	+ // ~/.ssh/config for that host, or the local user name.
	20	+ User string
	21	+ // Host is the machine: a name, an address, or a Host alias from
	22	+ // ~/.ssh/config — ssh resolves it, so every alias there works here.
	23	+ Host string
	24	+ // Path is the directory to open. Empty means the remote home directory;
	25	+ // a relative path is relative to it, as with scp.
	26	+ Path string
	27	+}
	28	+
	29	+// ParseTarget reads the argument of -ssh, which is written the way scp writes
	30	+// a remote location: [user@]host[:path]. An IPv6 address goes in brackets:
	31	+// bob@[2001:db8::1]:/srv.
	32	+//
	33	+// A port is not part of the syntax — scp has none either. Put it in
	34	+// ~/.ssh/config under a Host alias, and give the alias here.
	35	+//
	36	+// A host beginning with "-" is refused: ssh would read it as an option, and
	37	+// an option is the one thing that must never come from a target.
	38	+//
	39	+// remote.ParseTarget("bob@machine") // home directory
	40	+// remote.ParseTarget("bob@machine:~/app") // ~/app
	41	+// remote.ParseTarget("demo:/srv/app") // a Host alias from ~/.ssh/config
	42	+func ParseTarget(argument string) (Target, error) {
	43	+ var target Target
	44	+
	45	+ rest := argument
	46	+ if at := strings.LastIndex(rest, "@"); at >= 0 {
	47	+ target.User, rest = rest[:at], rest[at+1:]
	48	+ if target.User == "" {
	49	+ return Target{}, fmt.Errorf("%q: %w", argument, ErrBadTarget)
	50	+ }
	51	+ }
	52	+
	53	+ host, path, err := splitHostPath(rest)
	54	+ if err != nil {
	55	+ return Target{}, fmt.Errorf("%q: %w", argument, err)
	56	+ }
	57	+ target.Host, target.Path = host, path
	58	+
	59	+ if err := target.validate(); err != nil {
	60	+ return Target{}, fmt.Errorf("%q: %w", argument, err)
	61	+ }
	62	+ return target, nil
	63	+}
	64	+
	65	+// splitHostPath separates host from path, allowing a bracketed IPv6 host.
	66	+func splitHostPath(rest string) (host, path string, err error) {
	67	+ if strings.HasPrefix(rest, "[") {
	68	+ end := strings.Index(rest, "]")
	69	+ if end < 0 {
	70	+ return "", "", ErrBadTarget
	71	+ }
	72	+ host, rest = rest[1:end], rest[end+1:]
	73	+ if rest != "" && !strings.HasPrefix(rest, ":") {
	74	+ return "", "", ErrBadTarget
	75	+ }
	76	+ return host, strings.TrimPrefix(rest, ":"), nil
	77	+ }
	78	+
	79	+ host, path, _ = strings.Cut(rest, ":")
	80	+ return host, path, nil
	81	+}
	82	+
	83	+// validate refuses what ssh would misread or what cannot be a machine.
	84	+func (t Target) validate() error {
	85	+ switch {
	86	+ case t.Host == "":
	87	+ return ErrBadTarget
	88	+ case strings.HasPrefix(t.Host, "-"), strings.HasPrefix(t.User, "-"):
	89	+ return fmt.Errorf("a host or user may not begin with '-': %w", ErrBadTarget)
	90	+ case strings.ContainsAny(t.Host+t.User, " \t\r\n/"):
	91	+ return ErrBadTarget
	92	+ }
	93	+ return nil
	94	+}
	95	+
	96	+// Destination is what ssh is given to connect to: user@host, or host alone
	97	+// when no user was named.
	98	+//
	99	+// remote.Target{User: "bob", Host: "machine"}.Destination() // "bob@machine"
	100	+func (t Target) Destination() string {
	101	+ if t.User == "" {
	102	+ return t.Host
	103	+ }
	104	+ return t.User + "@" + t.Host
	105	+}
	106	+
	107	+// String writes the target back the way it is typed: user@host[:path].
	108	+func (t Target) String() string {
	109	+ host := t.Host
	110	+ if strings.Contains(host, ":") {
	111	+ host = "[" + host + "]"
	112	+ }
	113	+ written := host
	114	+ if t.User != "" {
	115	+ written = t.User + "@" + host
	116	+ }
	117	+ if t.Path != "" {
	118	+ written += ":" + t.Path
	119	+ }
	120	+ return written
	121	+}

++package remote
++
++import (
++	"errors"
++	"fmt"
++	"strings"
++)
++
++// ErrBadTarget is what ParseTarget returns for something that is not
++// user@machine[:path].
++var ErrBadTarget = errors.New("not a remote target; expected user@machine or user@machine:/path")
++
++// Target is the machine an editor was asked to work on, and where on it.
++//
++//	target, err := remote.ParseTarget("bob@build-box:/srv/app")
++//	// target.User == "bob", target.Host == "build-box", target.Path == "/srv/app"
++type Target struct {
++	// User is who to log in as. Empty leaves it to ssh: the User line of
++	// ~/.ssh/config for that host, or the local user name.
++	User string
++	// Host is the machine: a name, an address, or a Host alias from
++	// ~/.ssh/config — ssh resolves it, so every alias there works here.
++	Host string
++	// Path is the directory to open. Empty means the remote home directory;
++	// a relative path is relative to it, as with scp.
++	Path string
++}
++
++// ParseTarget reads the argument of -ssh, which is written the way scp writes
++// a remote location: [user@]host[:path]. An IPv6 address goes in brackets:
++// bob@[2001:db8::1]:/srv.
++//
++// A port is not part of the syntax — scp has none either. Put it in
++// ~/.ssh/config under a Host alias, and give the alias here.
++//
++// A host beginning with "-" is refused: ssh would read it as an option, and
++// an option is the one thing that must never come from a target.
++//
++//	remote.ParseTarget("bob@machine")         // home directory
++//	remote.ParseTarget("bob@machine:~/app")   // ~/app
++//	remote.ParseTarget("demo:/srv/app")       // a Host alias from ~/.ssh/config
++func ParseTarget(argument string) (Target, error) {
++	var target Target
++
++	rest := argument
++	if at := strings.LastIndex(rest, "@"); at >= 0 {
++		target.User, rest = rest[:at], rest[at+1:]
++		if target.User == "" {
++			return Target{}, fmt.Errorf("%q: %w", argument, ErrBadTarget)
++		}
++	}
++
++	host, path, err := splitHostPath(rest)
++	if err != nil {
++		return Target{}, fmt.Errorf("%q: %w", argument, err)
++	}
++	target.Host, target.Path = host, path
++
++	if err := target.validate(); err != nil {
++		return Target{}, fmt.Errorf("%q: %w", argument, err)
++	}
++	return target, nil
++}
++
++// splitHostPath separates host from path, allowing a bracketed IPv6 host.
++func splitHostPath(rest string) (host, path string, err error) {
++	if strings.HasPrefix(rest, "[") {
++		end := strings.Index(rest, "]")
++		if end < 0 {
++			return "", "", ErrBadTarget
++		}
++		host, rest = rest[1:end], rest[end+1:]
++		if rest != "" && !strings.HasPrefix(rest, ":") {
++			return "", "", ErrBadTarget
++		}
++		return host, strings.TrimPrefix(rest, ":"), nil
++	}
++
++	host, path, _ = strings.Cut(rest, ":")
++	return host, path, nil
++}
++
++// validate refuses what ssh would misread or what cannot be a machine.
++func (t Target) validate() error {
++	switch {
++	case t.Host == "":
++		return ErrBadTarget
++	case strings.HasPrefix(t.Host, "-"), strings.HasPrefix(t.User, "-"):
++		return fmt.Errorf("a host or user may not begin with '-': %w", ErrBadTarget)
++	case strings.ContainsAny(t.Host+t.User, " \t\r\n/"):
++		return ErrBadTarget
++	}
++	return nil
++}
++
++// Destination is what ssh is given to connect to: user@host, or host alone
++// when no user was named.
++//
++//	remote.Target{User: "bob", Host: "machine"}.Destination() // "bob@machine"
++func (t Target) Destination() string {
++	if t.User == "" {
++		return t.Host
++	}
++	return t.User + "@" + t.Host
++}
++
++// String writes the target back the way it is typed: user@host[:path].
++func (t Target) String() string {
++	host := t.Host
++	if strings.Contains(host, ":") {
++		host = "[" + host + "]"
++	}
++	written := host
++	if t.User != "" {
++		written = t.User + "@" + host
++	}
++	if t.Path != "" {
++		written += ":" + t.Path
++	}
++	return written
++}

added remote/target_test.go +68 -0 Viewed

new file mode 100644
@@ -0,0 +1,68 @@
	1	+package remote
	2	+
	3	+import (
	4	+ "errors"
	5	+ "testing"
	6	+)
	7	+
	8	+func TestParseTargetReadsUserHostAndPath(t *testing.T) {
	9	+ cases := map[string]Target{
	10	+ "bob@machine": {User: "bob", Host: "machine"},
	11	+ "bob@machine:/srv/app": {User: "bob", Host: "machine", Path: "/srv/app"},
	12	+ "bob@machine:app": {User: "bob", Host: "machine", Path: "app"},
	13	+ "bob@machine:~/app": {User: "bob", Host: "machine", Path: "~/app"},
	14	+ "demo": {Host: "demo"},
	15	+ "demo:/srv": {Host: "demo", Path: "/srv"},
	16	+ "bob@192.168.1.10:/home": {User: "bob", Host: "192.168.1.10", Path: "/home"},
	17	+ "bob@[::1]:/srv": {User: "bob", Host: "::1", Path: "/srv"},
	18	+ "bob@[2001:db8::1]": {User: "bob", Host: "2001:db8::1"},
	19	+ "a@b@machine": {User: "a@b", Host: "machine"},
	20	+ }
	21	+ for argument, want := range cases {
	22	+ got, err := ParseTarget(argument)
	23	+ if err != nil \|\| got != want {
	24	+ t.Errorf("ParseTarget(%q) = %+v, %v; want %+v", argument, got, err, want)
	25	+ }
	26	+ }
	27	+}
	28	+
	29	+func TestParseTargetRefusesWhatIsNotAMachine(t *testing.T) {
	30	+ for _, argument := range []string{
	31	+ "",
	32	+ "bob@",
	33	+ "@machine",
	34	+ ":/srv",
	35	+ "-oProxyCommand=evil",
	36	+ "bob@-oProxyCommand=evil",
	37	+ "-bob@machine",
	38	+ "bob@ma chine",
	39	+ "bob@[::1",
	40	+ "bob@[::1]x",
	41	+ "bob@host/name",
	42	+ } {
	43	+ if _, err := ParseTarget(argument); !errors.Is(err, ErrBadTarget) {
	44	+ t.Errorf("ParseTarget(%q) error = %v, want ErrBadTarget", argument, err)
	45	+ }
	46	+ }
	47	+}
	48	+
	49	+func TestDestinationIsWhatSSHConnectsTo(t *testing.T) {
	50	+ if got := (Target{User: "bob", Host: "machine", Path: "/x"}).Destination(); got != "bob@machine" {
	51	+ t.Errorf("Destination = %q", got)
	52	+ }
	53	+ if got := (Target{Host: "demo"}).Destination(); got != "demo" {
	54	+ t.Errorf("Destination without a user = %q", got)
	55	+ }
	56	+}
	57	+
	58	+func TestStringWritesTheTargetBackAsItIsTyped(t *testing.T) {
	59	+ for _, typed := range []string{"bob@machine", "bob@machine:/srv", "demo", "bob@[::1]:/srv"} {
	60	+ target, err := ParseTarget(typed)
	61	+ if err != nil {
	62	+ t.Fatal(err)
	63	+ }
	64	+ if target.String() != typed {
	65	+ t.Errorf("String() = %q, want %q", target.String(), typed)
	66	+ }
	67	+ }
	68	+}

++package remote
++
++import (
++	"errors"
++	"testing"
++)
++
++func TestParseTargetReadsUserHostAndPath(t *testing.T) {
++	cases := map[string]Target{
++		"bob@machine":            {User: "bob", Host: "machine"},
++		"bob@machine:/srv/app":   {User: "bob", Host: "machine", Path: "/srv/app"},
++		"bob@machine:app":        {User: "bob", Host: "machine", Path: "app"},
++		"bob@machine:~/app":      {User: "bob", Host: "machine", Path: "~/app"},
++		"demo":                   {Host: "demo"},
++		"demo:/srv":              {Host: "demo", Path: "/srv"},
++		"bob@192.168.1.10:/home": {User: "bob", Host: "192.168.1.10", Path: "/home"},
++		"bob@[::1]:/srv":         {User: "bob", Host: "::1", Path: "/srv"},
++		"bob@[2001:db8::1]":      {User: "bob", Host: "2001:db8::1"},
++		"a@b@machine":            {User: "a@b", Host: "machine"},
++	}
++	for argument, want := range cases {
++		got, err := ParseTarget(argument)
++		if err != nil || got != want {
++			t.Errorf("ParseTarget(%q) = %+v, %v; want %+v", argument, got, err, want)
++		}
++	}
++}
++
++func TestParseTargetRefusesWhatIsNotAMachine(t *testing.T) {
++	for _, argument := range []string{
++		"",
++		"bob@",
++		"@machine",
++		":/srv",
++		"-oProxyCommand=evil",
++		"bob@-oProxyCommand=evil",
++		"-bob@machine",
++		"bob@ma chine",
++		"bob@[::1",
++		"bob@[::1]x",
++		"bob@host/name",
++	} {
++		if _, err := ParseTarget(argument); !errors.Is(err, ErrBadTarget) {
++			t.Errorf("ParseTarget(%q) error = %v, want ErrBadTarget", argument, err)
++		}
++	}
++}
++
++func TestDestinationIsWhatSSHConnectsTo(t *testing.T) {
++	if got := (Target{User: "bob", Host: "machine", Path: "/x"}).Destination(); got != "bob@machine" {
++		t.Errorf("Destination = %q", got)
++	}
++	if got := (Target{Host: "demo"}).Destination(); got != "demo" {
++		t.Errorf("Destination without a user = %q", got)
++	}
++}
++
++func TestStringWritesTheTargetBackAsItIsTyped(t *testing.T) {
++	for _, typed := range []string{"bob@machine", "bob@machine:/srv", "demo", "bob@[::1]:/srv"} {
++		target, err := ParseTarget(typed)
++		if err != nil {
++			t.Fatal(err)
++		}
++		if target.String() != typed {
++			t.Errorf("String() = %q, want %q", target.String(), typed)
++		}
++	}
++}

modified settings/README.md +1 -1 Viewed

@@ -2,7 +2,7 @@
2	2
3	3	Reads, creates and updates a project's own editor settings: `settings.toml` inside the editor's own directory — `.turbo-go` for Turbo Go, `.turbo-rust` for Turbo Rust. Which directory that is comes from the `profile.Profile` every function here takes.
4	4
5		-Imports the standard library, the TOML parser and `profile`, and nothing else — no tcell, no `ui`, no `app`. It is tested by writing files and reading them back, with no screen and no event loop.
	5	+Imports the standard library, the TOML parser, `profile` and `fsys` — through which the file is read and written, so under `-ssh` it is the remote project's — and nothing else — no tcell, no `ui`, no `app`. It is tested by writing files and reading them back, with no screen and no event loop.
6	6
7	7	## Where it looks
8	8

  Reads, creates and updates a project's own editor settings: `settings.toml` inside the editor's own directory — `.turbo-go` for Turbo Go, `.turbo-rust` for Turbo Rust. Which directory that is comes from the `profile.Profile` every function here takes.
--Imports the standard library, the TOML parser and `profile`, and nothing else — no tcell, no `ui`, no `app`. It is tested by writing files and reading them back, with no screen and no event loop.
++Imports the standard library, the TOML parser, `profile` and `fsys` — through which the file is read and written, so under `-ssh` it is the remote project's — and nothing else — no tcell, no `ui`, no `app`. It is tested by writing files and reading them back, with no screen and no event loop.
  ## Where it looks

modified settings/create.go +2 -2 Viewed

@@ -2,8 +2,8 @@ package settings
2	2
3	3	import (
4	4	"fmt"
5		- "os"
6	5
	6	+ "rickub.com/turbo-editors/turbo-core/fsys"
7	7	"rickub.com/turbo-editors/turbo-core/profile"
8	8	"rickub.com/turbo-editors/turbo-core/projectfile"
9	9	)
@@ -49,7 +49,7 @@ func Create(p profile.Profile, projectDir, themeName string) (string, error) {
49	49	//
50	50	// settings.SetTheme(settings.Path("."), "turbo-dark")
51	51	func SetTheme(path, themeName string) error {
52		- data, err := os.ReadFile(path)
	52	+ data, err := fsys.ReadFile(path)
53	53	if err != nil {
54	54	return fmt.Errorf("reading %s: %w", path, err)
55	55	}

  import (
  	"fmt"
--	"os"
++	"rickub.com/turbo-editors/turbo-core/fsys"
  	"rickub.com/turbo-editors/turbo-core/profile"
  	"rickub.com/turbo-editors/turbo-core/projectfile"
  )
  //
  //	settings.SetTheme(settings.Path("."), "turbo-dark")
  func SetTheme(path, themeName string) error {
--	data, err := os.ReadFile(path)
++	data, err := fsys.ReadFile(path)
  	if err != nil {
  		return fmt.Errorf("reading %s: %w", path, err)
  	}

added settings/fsys_test.go +31 -0 Viewed

new file mode 100644
@@ -0,0 +1,31 @@
	1	+package settings
	2	+
	3	+import (
	4	+ "testing"
	5	+
	6	+ "rickub.com/turbo-editors/turbo-core/fsys"
	7	+ "rickub.com/turbo-editors/turbo-core/fsys/fsystest"
	8	+)
	9	+
	10	+func TestSettingsAreReadAndWrittenThroughTheCurrentFileSystem(t *testing.T) {
	11	+ memory := fsystest.New("/remote/project")
	12	+ previous := fsys.Use(memory)
	13	+ t.Cleanup(func() { fsys.Use(previous) })
	14	+ memory.AddFile("/remote/project/.turbo-test/settings.toml", "[editor]\ntheme = \"turbo-dark\"\n")
	15	+
	16	+ p := testProfile()
	17	+ if !Exists(p, "/remote/project") {
	18	+ t.Fatal("Exists = false for a settings file that is only in the current file system")
	19	+ }
	20	+ loaded, err := Load(p, "/remote/project")
	21	+ if err != nil \|\| loaded.Theme != "turbo-dark" {
	22	+ t.Fatalf("Load = %+v, %v", loaded, err)
	23	+ }
	24	+
	25	+ if err := SetTheme(Path(p, "/remote/project"), "turbo-classic"); err != nil {
	26	+ t.Fatal(err)
	27	+ }
	28	+ if got, _ := memory.File("/remote/project/.turbo-test/settings.toml"); got != "[editor]\ntheme = \"turbo-classic\"\n" {
	29	+ t.Errorf("after SetTheme the file holds %q", got)
	30	+ }
	31	+}

++package settings
++
++import (
++	"testing"
++
++	"rickub.com/turbo-editors/turbo-core/fsys"
++	"rickub.com/turbo-editors/turbo-core/fsys/fsystest"
++)
++
++func TestSettingsAreReadAndWrittenThroughTheCurrentFileSystem(t *testing.T) {
++	memory := fsystest.New("/remote/project")
++	previous := fsys.Use(memory)
++	t.Cleanup(func() { fsys.Use(previous) })
++	memory.AddFile("/remote/project/.turbo-test/settings.toml", "[editor]\ntheme = \"turbo-dark\"\n")
++
++	p := testProfile()
++	if !Exists(p, "/remote/project") {
++		t.Fatal("Exists = false for a settings file that is only in the current file system")
++	}
++	loaded, err := Load(p, "/remote/project")
++	if err != nil || loaded.Theme != "turbo-dark" {
++		t.Fatalf("Load = %+v, %v", loaded, err)
++	}
++
++	if err := SetTheme(Path(p, "/remote/project"), "turbo-classic"); err != nil {
++		t.Fatal(err)
++	}
++	if got, _ := memory.File("/remote/project/.turbo-test/settings.toml"); got != "[editor]\ntheme = \"turbo-classic\"\n" {
++		t.Errorf("after SetTheme the file holds %q", got)
++	}
++}

modified settings/settings.go +5 -4 Viewed

@@ -18,12 +18,13 @@ package settings
18	18	import (
19	19	"errors"
20	20	"fmt"
21		- "os"
	21	+ "io/fs"
22	22	"path/filepath"
23	23	"time"
24	24
25	25	"github.com/BurntSushi/toml"
26	26
	27	+ "rickub.com/turbo-editors/turbo-core/fsys"
27	28	"rickub.com/turbo-editors/turbo-core/profile"
28	29	)
29	30
@@ -88,7 +89,7 @@ func Path(p profile.Profile, projectDir string) string {
88	89	// A directory in its place counts as absent: it is not something Load could
89	90	// have read, and saying otherwise would only move the error later.
90	91	func Exists(p profile.Profile, projectDir string) bool {
91		- info, err := os.Stat(Path(p, projectDir))
	92	+ info, err := fsys.Stat(Path(p, projectDir))
92	93	return err == nil && info.Mode().IsRegular()
93	94	}
94	95
@@ -108,9 +109,9 @@ func Exists(p profile.Profile, projectDir string) bool {
108	109	func Load(p profile.Profile, projectDir string) (Settings, error) {
109	110	path := Path(p, projectDir)
110	111
111		- data, err := os.ReadFile(path)
	112	+ data, err := fsys.ReadFile(path)
112	113	if err != nil {
113		- if errors.Is(err, os.ErrNotExist) {
	114	+ if errors.Is(err, fs.ErrNotExist) {
114	115	return Settings{}, fmt.Errorf("%w: %s", ErrNotFound, path)
115	116	}
116	117	return Settings{}, fmt.Errorf("reading %s: %w", path, err)

  import (
  	"errors"
  	"fmt"
--	"os"
++	"io/fs"
  	"path/filepath"
  	"time"
  	"github.com/BurntSushi/toml"
++	"rickub.com/turbo-editors/turbo-core/fsys"
  	"rickub.com/turbo-editors/turbo-core/profile"
  )
  // A directory in its place counts as absent: it is not something Load could
  // have read, and saying otherwise would only move the error later.
  func Exists(p profile.Profile, projectDir string) bool {
--	info, err := os.Stat(Path(p, projectDir))
++	info, err := fsys.Stat(Path(p, projectDir))
  	return err == nil && info.Mode().IsRegular()
  }
  func Load(p profile.Profile, projectDir string) (Settings, error) {
  	path := Path(p, projectDir)
--	data, err := os.ReadFile(path)
++	data, err := fsys.ReadFile(path)
  	if err != nil {
--		if errors.Is(err, os.ErrNotExist) {
++		if errors.Is(err, fs.ErrNotExist) {
  			return Settings{}, fmt.Errorf("%w: %s", ErrNotFound, path)
  		}
  		return Settings{}, fmt.Errorf("reading %s: %w", path, err)

modified snippets/README.md +1 -1 Viewed

@@ -2,7 +2,7 @@
2	2
3	3	Reads the reusable pieces of text a project and a user keep in TOML, and groups them for a menu to show.
4	4
5		-Imports the standard library and the TOML parser, and nothing else — no tcell, no `ui`, no `app`. It is tested by writing files and reading them back.
	5	+Imports the standard library, the TOML parser and `fsys`, and nothing else — no tcell, no `ui`, no `app`. The project's file is read through `fsys`, so under `-ssh` it is the remote project's; the user's own file is read with `os`, on this machine, because habits follow the person. It is tested by writing files and reading them back.
6	6
7	7	## Two files, and why the project wins
8	8

  Reads the reusable pieces of text a project and a user keep in TOML, and groups them for a menu to show.
--Imports the standard library and the TOML parser, and nothing else — no tcell, no `ui`, no `app`. It is tested by writing files and reading them back.
++Imports the standard library, the TOML parser and `fsys`, and nothing else — no tcell, no `ui`, no `app`. The project's file is read through `fsys`, so under `-ssh` it is the remote project's; the user's own file is read with `os`, on this machine, because habits follow the person. It is tested by writing files and reading them back.
  ## Two files, and why the project wins

modified snippets/create.go +2 -2 Viewed

@@ -2,8 +2,8 @@ package snippets
2	2
3	3	import (
4	4	"fmt"
5		- "os"
6	5
	6	+ "rickub.com/turbo-editors/turbo-core/fsys"
7	7	"rickub.com/turbo-editors/turbo-core/profile"
8	8	"rickub.com/turbo-editors/turbo-core/projectfile"
9	9	)
@@ -53,6 +53,6 @@ func Exists(p profile.Profile, projectDir string) bool {
53	53	// exists reports whether a path is a regular file. A directory in its place
54	54	// counts as absent: it is not something Load could have read.
55	55	func exists(path string) bool {
56		- info, err := os.Stat(path)
	56	+ info, err := fsys.Stat(path)
57	57	return err == nil && info.Mode().IsRegular()
58	58	}

  import (
  	"fmt"
--	"os"
++	"rickub.com/turbo-editors/turbo-core/fsys"
  	"rickub.com/turbo-editors/turbo-core/profile"
  	"rickub.com/turbo-editors/turbo-core/projectfile"
  )
  // exists reports whether a path is a regular file. A directory in its place
  // counts as absent: it is not something Load could have read.
  func exists(path string) bool {
--	info, err := os.Stat(path)
++	info, err := fsys.Stat(path)
  	return err == nil && info.Mode().IsRegular()
  }

added snippets/fsys_test.go +37 -0 Viewed

new file mode 100644
@@ -0,0 +1,37 @@
	1	+package snippets
	2	+
	3	+import (
	4	+ "os"
	5	+ "path/filepath"
	6	+ "testing"
	7	+
	8	+ "rickub.com/turbo-editors/turbo-core/fsys"
	9	+ "rickub.com/turbo-editors/turbo-core/fsys/fsystest"
	10	+)
	11	+
	12	+// The project's snippets live with the project, wherever that is; the user's
	13	+// live with the user, on this machine. Under -ssh they come from two places.
	14	+func TestTheProjectsSnippetsComeFromTheCurrentFileSystemAndTheUsersFromThisMachine(t *testing.T) {
	15	+ p := testProfile()
	16	+ userDir := t.TempDir()
	17	+ t.Setenv(p.SnippetDirEnvVar(), userDir)
	18	+ if err := os.WriteFile(filepath.Join(userDir, FileName), []byte("[[snippet]]\nname = \"mine\"\nbody = \"m\"\n"), 0o644); err != nil {
	19	+ t.Fatal(err)
	20	+ }
	21	+
	22	+ memory := fsystest.New("/remote/project")
	23	+ previous := fsys.Use(memory)
	24	+ t.Cleanup(func() { fsys.Use(previous) })
	25	+ memory.AddFile(ProjectPath(p, "/remote/project"), "[[snippet]]\nname = \"theirs\"\nbody = \"t\"\n")
	26	+
	27	+ list, err := Load(p, "/remote/project")
	28	+ if err != nil {
	29	+ t.Fatal(err)
	30	+ }
	31	+ if list.Len() != 2 {
	32	+ t.Errorf("Len() = %d, want the user's snippet and the project's", list.Len())
	33	+ }
	34	+ if !Exists(p, "/remote/project") {
	35	+ t.Error("Exists = false for a snippets file that is only in the current file system")
	36	+ }
	37	+}

++package snippets
++
++import (
++	"os"
++	"path/filepath"
++	"testing"
++
++	"rickub.com/turbo-editors/turbo-core/fsys"
++	"rickub.com/turbo-editors/turbo-core/fsys/fsystest"
++)
++
++// The project's snippets live with the project, wherever that is; the user's
++// live with the user, on this machine. Under -ssh they come from two places.
++func TestTheProjectsSnippetsComeFromTheCurrentFileSystemAndTheUsersFromThisMachine(t *testing.T) {
++	p := testProfile()
++	userDir := t.TempDir()
++	t.Setenv(p.SnippetDirEnvVar(), userDir)
++	if err := os.WriteFile(filepath.Join(userDir, FileName), []byte("[[snippet]]\nname = \"mine\"\nbody = \"m\"\n"), 0o644); err != nil {
++		t.Fatal(err)
++	}
++
++	memory := fsystest.New("/remote/project")
++	previous := fsys.Use(memory)
++	t.Cleanup(func() { fsys.Use(previous) })
++	memory.AddFile(ProjectPath(p, "/remote/project"), "[[snippet]]\nname = \"theirs\"\nbody = \"t\"\n")
++
++	list, err := Load(p, "/remote/project")
++	if err != nil {
++		t.Fatal(err)
++	}
++	if list.Len() != 2 {
++		t.Errorf("Len() = %d, want the user's snippet and the project's", list.Len())
++	}
++	if !Exists(p, "/remote/project") {
++		t.Error("Exists = false for a snippets file that is only in the current file system")
++	}
++}

modified snippets/snippets.go +19 -7 Viewed

@@ -16,11 +16,13 @@ package snippets
16	16	import (
17	17	"errors"
18	18	"fmt"
	19	+ "io/fs"
19	20	"os"
20	21	"path/filepath"
21	22
22	23	"github.com/BurntSushi/toml"
23	24
	25	+ "rickub.com/turbo-editors/turbo-core/fsys"
24	26	"rickub.com/turbo-editors/turbo-core/profile"
25	27	)
26	28
@@ -155,11 +157,21 @@ func UserPath(p profile.Profile) string {
155	157	func Load(p profile.Profile, projectDir string) (List, error) {
156	158	var list List
157	159
158		- for _, path := range []string{UserPath(p), ProjectPath(p, projectDir)} {
159		- if path == "" {
	160	+ // The user's file is on this machine, wherever the project is: habits
	161	+ // follow the person. The project's is read through fsys, so under -ssh it
	162	+ // is the remote project's.
	163	+ sources := []struct {
	164	+ path string
	165	+ read func(string) ([]byte, error)
	166	+ }{
	167	+ {UserPath(p), os.ReadFile},
	168	+ {ProjectPath(p, projectDir), fsys.ReadFile},
	169	+ }
	170	+ for _, source := range sources {
	171	+ if source.path == "" {
160	172	continue
161	173	}
162		- read, err := loadFile(path)
	174	+ read, err := loadFile(source.path, source.read)
163	175	if err != nil {
164	176	return List{}, err
165	177	}
@@ -198,11 +210,11 @@ type file struct {
198	210	Snippet []Snippet `toml:"snippet"`
199	211	}
200	212
201		-// loadFile reads one snippets file, treating a missing one as empty.
202		-func loadFile(path string) ([]Snippet, error) {
203		- data, err := os.ReadFile(path)
	213	+// loadFile reads one snippets file with read, treating a missing one as empty.
	214	+func loadFile(path string, read func(string) ([]byte, error)) ([]Snippet, error) {
	215	+ data, err := read(path)
204	216	if err != nil {
205		- if errors.Is(err, os.ErrNotExist) {
	217	+ if errors.Is(err, fs.ErrNotExist) {
206	218	return nil, nil
207	219	}
208	220	return nil, fmt.Errorf("reading %s: %w", path, err)

  import (
  	"errors"
  	"fmt"
++	"io/fs"
  	"os"
  	"path/filepath"
  	"github.com/BurntSushi/toml"
++	"rickub.com/turbo-editors/turbo-core/fsys"
  	"rickub.com/turbo-editors/turbo-core/profile"
  )
  func Load(p profile.Profile, projectDir string) (List, error) {
  	var list List
--	for _, path := range []string{UserPath(p), ProjectPath(p, projectDir)} {
++	// The user's file is on this machine, wherever the project is: habits
--		if path == "" {
++	// follow the person. The project's is read through fsys, so under -ssh it
++	// is the remote project's.
++	sources := []struct {
++		path string
++		read func(string) ([]byte, error)
++	}{
++		{UserPath(p), os.ReadFile},
++		{ProjectPath(p, projectDir), fsys.ReadFile},
++	}
++	for _, source := range sources {
++		if source.path == "" {
  			continue
  		}
--		read, err := loadFile(path)
++		read, err := loadFile(source.path, source.read)
  		if err != nil {
  			return List{}, err
  		}
  	Snippet []Snippet `toml:"snippet"`
  }
--// loadFile reads one snippets file, treating a missing one as empty.
++// loadFile reads one snippets file with read, treating a missing one as empty.
--func loadFile(path string) ([]Snippet, error) {
++func loadFile(path string, read func(string) ([]byte, error)) ([]Snippet, error) {
--	data, err := os.ReadFile(path)
++	data, err := read(path)
  	if err != nil {
--		if errors.Is(err, os.ErrNotExist) {
++		if errors.Is(err, fs.ErrNotExist) {
  			return nil, nil
  		}
  		return nil, fmt.Errorf("reading %s: %w", path, err)

modified tools/README.md +3 -1 Viewed

@@ -2,7 +2,7 @@
2	2
3	3	Reads the commands a project runs on itself — its formatter, its linter, its build, its tests — from `tools.toml` inside the editor's own directory — `.turbo-go` for Turbo Go, `.turbo-rust` for Turbo Rust — and runs one.
4	4
5		-Imports the standard library, the TOML parser and `projectfile`, and nothing else: no tcell, no `ui`. The file half is tested by writing files and reading them back; the running half by running real commands and comparing what came out.
	5	+Imports the standard library, the TOML parser, `projectfile` and `fsys` (the tools file is read through it, so under `-ssh` it is the remote project's), and nothing else: no tcell, no `ui`. The file half is tested by writing files and reading them back; the running half by running real commands and comparing what came out.
6	6
7	7	## One file, and no user-level one
8	8
@@ -45,6 +45,8 @@ Two things about it are deliberate:
45	45	- `onLine` is a parameter of `Start`, not a field. `Start` begins the goroutine that calls it, so a field assigned afterwards would be a data race — the exact one `terminal.ViewOptions` was created to fix, and not one to reintroduce in a new package.
46	46	- Output is capped at 10000 lines, oldest first, with `Dropped()` reporting how many went. A runaway command would otherwise grow a dialog until it grew the editor; the tail of a failing build is the part that matters, so the head is what goes, and the caller is told rather than quietly shown less.
47	47
	48	+`StartProgram(command, argv, onLine)` is the same without the local shell: it runs `argv` as given, under the name `command`. It exists for a tool run on another machine — `app` passes it `session.RunCommand(dir, command, false)`, which is `ssh … /bin/sh -c …` — so the dialog is titled after the command line in the tools file, not after ssh.
	49	+
48	50	`output = "terminal"` does not come through here at all: `app` hands that to `terminal` instead, using `Shell()` and `ShellArgs()` from this package so both spell the shell the same way.
49	51
50	52	Stopping a command stops what it started. On Unix the command gets a process group of its own (`Setpgid`) and `Stop` kills the group; on Windows it is assigned to a job object created with `KILL_ON_JOB_CLOSE`, and `Stop` terminates the job. The Windows assignment happens after the process has started, so a child spawned in those first milliseconds escapes — `exec.Cmd` has no way to start a process suspended. Both live behind the `group` interface in `run.go`; `shell_unix.go`, `shell_windows.go` and `group_other.go` are the three implementations.

  Reads the commands a project runs on itself — its formatter, its linter, its build, its tests — from `tools.toml` inside the editor's own directory — `.turbo-go` for Turbo Go, `.turbo-rust` for Turbo Rust — and runs one.
--Imports the standard library, the TOML parser and `projectfile`, and nothing else: no tcell, no `ui`. The file half is tested by writing files and reading them back; the running half by running real commands and comparing what came out.
++Imports the standard library, the TOML parser, `projectfile` and `fsys` (the tools file is read through it, so under `-ssh` it is the remote project's), and nothing else: no tcell, no `ui`. The file half is tested by writing files and reading them back; the running half by running real commands and comparing what came out.
  ## One file, and no user-level one
  - **`onLine` is a parameter of `Start`, not a field.** `Start` begins the goroutine that calls it, so a field assigned afterwards would be a data race — the exact one `terminal.ViewOptions` was created to fix, and not one to reintroduce in a new package.
  - **Output is capped at 10000 lines**, oldest first, with `Dropped()` reporting how many went. A runaway command would otherwise grow a dialog until it grew the editor; the tail of a failing build is the part that matters, so the head is what goes, and the caller is told rather than quietly shown less.
++**`StartProgram(command, argv, onLine)`** is the same without the local shell: it runs `argv` as given, under the name `command`. It exists for a tool run on another machine — `app` passes it `session.RunCommand(dir, command, false)`, which is `ssh … /bin/sh -c …` — so the dialog is titled after the command line in the tools file, not after ssh.
++
  `output = "terminal"` does not come through here at all: `app` hands that to `terminal` instead, using `Shell()` and `ShellArgs()` from this package so both spell the shell the same way.
  **Stopping a command stops what it started.** On Unix the command gets a process group of its own (`Setpgid`) and `Stop` kills the group; on Windows it is assigned to a **job object** created with `KILL_ON_JOB_CLOSE`, and `Stop` terminates the job. The Windows assignment happens after the process has started, so a child spawned in those first milliseconds escapes — `exec.Cmd` has no way to start a process suspended. Both live behind the `group` interface in `run.go`; `shell_unix.go`, `shell_windows.go` and `group_other.go` are the three implementations.

added tools/fsys_test.go +24 -0 Viewed

new file mode 100644
@@ -0,0 +1,24 @@
	1	+package tools
	2	+
	3	+import (
	4	+ "testing"
	5	+
	6	+ "rickub.com/turbo-editors/turbo-core/fsys"
	7	+ "rickub.com/turbo-editors/turbo-core/fsys/fsystest"
	8	+)
	9	+
	10	+func TestToolsAreReadThroughTheCurrentFileSystem(t *testing.T) {
	11	+ memory := fsystest.New("/remote/project")
	12	+ previous := fsys.Use(memory)
	13	+ t.Cleanup(func() { fsys.Use(previous) })
	14	+ memory.AddFile("/remote/project/.turbo-test/tools.toml", "[[tool]]\nname = \"Run\"\ncommand = \"python3 main.py\"\n")
	15	+
	16	+ p := testProfile()
	17	+ if !Exists(p, "/remote/project") {
	18	+ t.Fatal("Exists = false for a tools file that is only in the current file system")
	19	+ }
	20	+ list, err := Load(p, "/remote/project")
	21	+ if err != nil \|\| list.Len() != 1 \|\| list.Tools()[0].Command != "python3 main.py" {
	22	+ t.Errorf("Load = %+v, %v", list.Tools(), err)
	23	+ }
	24	+}

++package tools
++
++import (
++	"testing"
++
++	"rickub.com/turbo-editors/turbo-core/fsys"
++	"rickub.com/turbo-editors/turbo-core/fsys/fsystest"
++)
++
++func TestToolsAreReadThroughTheCurrentFileSystem(t *testing.T) {
++	memory := fsystest.New("/remote/project")
++	previous := fsys.Use(memory)
++	t.Cleanup(func() { fsys.Use(previous) })
++	memory.AddFile("/remote/project/.turbo-test/tools.toml", "[[tool]]\nname = \"Run\"\ncommand = \"python3 main.py\"\n")
++
++	p := testProfile()
++	if !Exists(p, "/remote/project") {
++		t.Fatal("Exists = false for a tools file that is only in the current file system")
++	}
++	list, err := Load(p, "/remote/project")
++	if err != nil || list.Len() != 1 || list.Tools()[0].Command != "python3 main.py" {
++		t.Errorf("Load = %+v, %v", list.Tools(), err)
++	}
++}

modified tools/group_other.go +3 -0 Viewed

@@ -32,3 +32,6 @@ func newGroup(process *os.Process) group { return loneProcess{process: process}
32	32	func (g loneProcess) kill() { _ = g.process.Kill() }
33	33
34	34	func (loneProcess) release() {}
	35	+
	36	+// programAttributes asks for nothing on a platform without process groups.
	37	+func programAttributes() *syscall.SysProcAttr { return nil }

  func (g loneProcess) kill() { _ = g.process.Kill() }
  func (loneProcess) release() {}
++
++// programAttributes asks for nothing on a platform without process groups.
++func programAttributes() *syscall.SysProcAttr { return nil }

added tools/program_test.go +43 -0 Viewed

new file mode 100644
@@ -0,0 +1,43 @@
	1	+//go:build unix
	2	+
	3	+package tools
	4	+
	5	+import (
	6	+ "slices"
	7	+ "testing"
	8	+)
	9	+
	10	+func TestStartProgramRunsTheArgumentsAsGivenUnderTheNameGiven(t *testing.T) {
	11	+ // The argument holding a space and a quote would be split or mangled by a
	12	+ // shell in between; given as one argument, it arrives as one.
	13	+ run, err := StartProgram("greet", []string{"/bin/sh", "-c", `printf '%s\n' "$0"; exit 3`, "it's one word"}, nil)
	14	+ if err != nil {
	15	+ t.Fatal(err)
	16	+ }
	17	+ waitUntilDone(t, run)
	18	+
	19	+ if run.Command() != "greet" {
	20	+ t.Errorf("Command() = %q, want the name given", run.Command())
	21	+ }
	22	+ if got := run.Lines(); !slices.Equal(got, []string{"it's one word"}) {
	23	+ t.Errorf("Lines() = %q", got)
	24	+ }
	25	+ if _, code := run.Done(); code != 3 {
	26	+ t.Errorf("exit code = %d, want 3", code)
	27	+ }
	28	+}
	29	+
	30	+func TestStartProgramRefusesAnEmptyCommandLine(t *testing.T) {
	31	+ if _, err := StartProgram("nothing", nil, nil); err == nil {
	32	+ t.Error("StartProgram with no program returned no error")
	33	+ }
	34	+}
	35	+
	36	+func TestStartProgramCanBeStopped(t *testing.T) {
	37	+ run, err := StartProgram("sleeper", []string{"/bin/sh", "-c", "sleep 30"}, nil)
	38	+ if err != nil {
	39	+ t.Fatal(err)
	40	+ }
	41	+ run.Stop()
	42	+ waitUntilDone(t, run)
	43	+}

++//go:build unix
++
++package tools
++
++import (
++	"slices"
++	"testing"
++)
++
++func TestStartProgramRunsTheArgumentsAsGivenUnderTheNameGiven(t *testing.T) {
++	// The argument holding a space and a quote would be split or mangled by a
++	// shell in between; given as one argument, it arrives as one.
++	run, err := StartProgram("greet", []string{"/bin/sh", "-c", `printf '%s\n' "$0"; exit 3`, "it's one word"}, nil)
++	if err != nil {
++		t.Fatal(err)
++	}
++	waitUntilDone(t, run)
++
++	if run.Command() != "greet" {
++		t.Errorf("Command() = %q, want the name given", run.Command())
++	}
++	if got := run.Lines(); !slices.Equal(got, []string{"it's one word"}) {
++		t.Errorf("Lines() = %q", got)
++	}
++	if _, code := run.Done(); code != 3 {
++		t.Errorf("exit code = %d, want 3", code)
++	}
++}
++
++func TestStartProgramRefusesAnEmptyCommandLine(t *testing.T) {
++	if _, err := StartProgram("nothing", nil, nil); err == nil {
++		t.Error("StartProgram with no program returned no error")
++	}
++}
++
++func TestStartProgramCanBeStopped(t *testing.T) {
++	run, err := StartProgram("sleeper", []string{"/bin/sh", "-c", "sleep 30"}, nil)
++	if err != nil {
++		t.Fatal(err)
++	}
++	run.Stop()
++	waitUntilDone(t, run)
++}

modified tools/run.go +25 -0 Viewed

@@ -77,6 +77,31 @@ func Start(command, dir string, onLine func()) (*Run, error) {
77	77	process := exec.Command(Shell(), ShellArgs(command)...)
78	78	process.Dir = dir
79	79	process.SysProcAttr = childAttributes(process, command)
	80	+ return start(command, process, onLine)
	81	+}
	82	+
	83	+// StartProgram runs a program with its arguments as given, no local shell in
	84	+// between, and returns it in flight. command is what the run is called — what
	85	+// Command returns and a dialog shows — which is how a tool run on another
	86	+// machine through `ssh … /bin/sh -c 'command'` is still called by the command
	87	+// line the tools file holds.
	88	+//
	89	+// Everything else is as for Start: output merged, onLine a wake-up only, Stop
	90	+// ending the program and whatever it started.
	91	+//
	92	+// argv := session.RunCommand("/srv/app", "pytest", false)
	93	+// run, err := tools.StartProgram("pytest", argv, wakeTheEventLoop)
	94	+func StartProgram(command string, argv []string, onLine func()) (*Run, error) {
	95	+ if len(argv) == 0 {
	96	+ return nil, fmt.Errorf("running %s: no program to run", command)
	97	+ }
	98	+ process := exec.Command(argv[0], argv[1:]...)
	99	+ process.SysProcAttr = programAttributes()
	100	+ return start(command, process, onLine)
	101	+}
	102	+
	103	+// start starts a prepared process, collecting its output.
	104	+func start(command string, process exec.Cmd, onLine func()) (Run, error) {
80	105	process.WaitDelay = stopGrace
81	106
82	107	output, err := process.StdoutPipe()

  	process := exec.Command(Shell(), ShellArgs(command)...)
  	process.Dir = dir
  	process.SysProcAttr = childAttributes(process, command)
++	return start(command, process, onLine)
++}
++
++// StartProgram runs a program with its arguments as given, no local shell in
++// between, and returns it in flight. command is what the run is called — what
++// Command returns and a dialog shows — which is how a tool run on another
++// machine through `ssh … /bin/sh -c 'command'` is still called by the command
++// line the tools file holds.
++//
++// Everything else is as for Start: output merged, onLine a wake-up only, Stop
++// ending the program and whatever it started.
++//
++//	argv := session.RunCommand("/srv/app", "pytest", false)
++//	run, err := tools.StartProgram("pytest", argv, wakeTheEventLoop)
++func StartProgram(command string, argv []string, onLine func()) (*Run, error) {
++	if len(argv) == 0 {
++		return nil, fmt.Errorf("running %s: no program to run", command)
++	}
++	process := exec.Command(argv[0], argv[1:]...)
++	process.SysProcAttr = programAttributes()
++	return start(command, process, onLine)
++}
++
++// start starts a prepared process, collecting its output.
++func start(command string, process *exec.Cmd, onLine func()) (*Run, error) {
  	process.WaitDelay = stopGrace
  	output, err := process.StdoutPipe()

modified tools/shell_unix.go +6 -0 Viewed

@@ -45,3 +45,9 @@ func (g processGroup) kill() {
45	45
46	46	// release has nothing to give back: a process group is not a resource.
47	47	func (processGroup) release() {}
	48	+
	49	+// programAttributes puts a program started by StartProgram in a process group
	50	+// of its own, for the same reason childAttributes does.
	51	+func programAttributes() *syscall.SysProcAttr {
	52	+ return &syscall.SysProcAttr{Setpgid: true}
	53	+}

  // release has nothing to give back: a process group is not a resource.
  func (processGroup) release() {}
++
++// programAttributes puts a program started by StartProgram in a process group
++// of its own, for the same reason childAttributes does.
++func programAttributes() *syscall.SysProcAttr {
++	return &syscall.SysProcAttr{Setpgid: true}
++}

modified tools/shell_windows.go +7 -0 Viewed

@@ -97,3 +97,10 @@ func (g jobObject) release() {
97	97	windows.CloseHandle(g.job)
98	98	}
99	99	}
	100	+
	101	+// programAttributes gives a program started by StartProgram a process group
	102	+// of its own. Unlike childAttributes it leaves the command line to exec: the
	103	+// program is not cmd.exe, and the C runtime's quoting is what it expects.
	104	+func programAttributes() *syscall.SysProcAttr {
	105	+ return &syscall.SysProcAttr{CreationFlags: windows.CREATE_NEW_PROCESS_GROUP}
	106	+}

  		windows.CloseHandle(g.job)
  	}
  }
++
++// programAttributes gives a program started by StartProgram a process group
++// of its own. Unlike childAttributes it leaves the command line to exec: the
++// program is not cmd.exe, and the C runtime's quoting is what it expects.
++func programAttributes() *syscall.SysProcAttr {
++	return &syscall.SysProcAttr{CreationFlags: windows.CREATE_NEW_PROCESS_GROUP}
++}

modified tools/tools.go +5 -4 Viewed

@@ -18,12 +18,13 @@ package tools
18	18	import (
19	19	"errors"
20	20	"fmt"
21		- "os"
	21	+ "io/fs"
22	22	"path/filepath"
23	23	"strings"
24	24
25	25	"github.com/BurntSushi/toml"
26	26
	27	+ "rickub.com/turbo-editors/turbo-core/fsys"
27	28	"rickub.com/turbo-editors/turbo-core/profile"
28	29	)
29	30
@@ -157,7 +158,7 @@ func Path(p profile.Profile, projectDir string) string {
157	158	// A directory in its place counts as absent: it is not something Load could
158	159	// have read.
159	160	func Exists(p profile.Profile, projectDir string) bool {
160		- info, err := os.Stat(Path(p, projectDir))
	161	+ info, err := fsys.Stat(Path(p, projectDir))
161	162	return err == nil && info.Mode().IsRegular()
162	163	}
163	164
@@ -179,9 +180,9 @@ func Load(p profile.Profile, projectDir string) (List, error) {
179	180	path := Path(p, projectDir)
180	181	defaultMenu := DefaultMenuName(p)
181	182
182		- data, err := os.ReadFile(path)
	183	+ data, err := fsys.ReadFile(path)
183	184	if err != nil {
184		- if errors.Is(err, os.ErrNotExist) {
	185	+ if errors.Is(err, fs.ErrNotExist) {
185	186	return List{defaultMenu: defaultMenu}, nil
186	187	}
187	188	return List{defaultMenu: defaultMenu}, fmt.Errorf("reading %s: %w", path, err)

  import (
  	"errors"
  	"fmt"
--	"os"
++	"io/fs"
  	"path/filepath"
  	"strings"
  	"github.com/BurntSushi/toml"
++	"rickub.com/turbo-editors/turbo-core/fsys"
  	"rickub.com/turbo-editors/turbo-core/profile"
  )
  // A directory in its place counts as absent: it is not something Load could
  // have read.
  func Exists(p profile.Profile, projectDir string) bool {
--	info, err := os.Stat(Path(p, projectDir))
++	info, err := fsys.Stat(Path(p, projectDir))
  	return err == nil && info.Mode().IsRegular()
  }
  	path := Path(p, projectDir)
  	defaultMenu := DefaultMenuName(p)
--	data, err := os.ReadFile(path)
++	data, err := fsys.ReadFile(path)
  	if err != nil {
--		if errors.Is(err, os.ErrNotExist) {
++		if errors.Is(err, fs.ErrNotExist) {
  			return List{defaultMenu: defaultMenu}, nil
  		}
  		return List{defaultMenu: defaultMenu}, fmt.Errorf("reading %s: %w", path, err)

📦 Turbo Core — a window's shadow hugs its frame again (#30); AsciiDoc is coloured, the ninth built-in language (#31); text is copied out of a terminal window and pasted into it — Ctrl-Ins, Shift-Ins, Shift-arrows and the mouse — and a shell that asked for bracketed paste gets its marks