diff --git a/app/notes/files-mutations.md b/app/notes/files-mutations.md new file mode 100644 index 00000000..5f659a84 --- /dev/null +++ b/app/notes/files-mutations.md @@ -0,0 +1,118 @@ +# Files panel: rename, move and delete + +## Behaviour + +- Every row and tile in the chat Files panel has an action menu (`File actions` + / `Folder actions`): Open and Download for a file, then **Rename…**, + **Move…** and **Delete…** for files and folders alike (Delete is marked + destructive on the Cupertino sheet). +- **Rename…** opens a dialog with the name prefilled; a file's stem is selected + so typing replaces the name and keeps the extension, a folder or dot-file is + selected whole. Save is disabled while the name is unchanged or invalid: + empty, `.`/`..`, containing `/` or `\`, or over 255 characters (the same + rules the server applies, shown inline). Enter saves. +- **Move…** opens the shared folder picker (`ui/folder_picker`) at the shown + folder with the title `Move “name”`, the line `Move to ~/…` and a + **Move here** button. Back climbs one folder, breadcrumbs include `~` (home), + folder rows navigate. The entry's own folder (its current location) is not + offered, and a folder being moved cannot be entered or chosen, nor can + anything below it (`FolderPickerPurpose.excludedPath`). The picker's existing + "Start chat here" use is unchanged (`FolderPickerPurpose.startChat`). +- **Delete…** asks `Delete “name”?` first. A file or empty folder is removed on + confirmation. When the server answers that a folder `is not empty`, a second + dialog `Delete “name” and its contents?` with **Delete all** sends the + recursive request; the first refusal is treated as that question, not as an + error. +- **Drag and drop**: press and hold any entry (`LongPressDraggable`, so a touch + scroll stays a scroll; with a mouse hold ~0.5 s), carry it over a folder row + or tile, which highlights as the drop target, and release to move it there. + Dropping onto a file, onto itself or a folder into its own subtree is not + accepted (`canDropEntryOn`). A same-named target is left to the server, whose + refusal is shown. +- Every operation shows a progress strip (`Renaming…`, `Moving…`, `Deleting…`) + and reloads the shown folder afterwards, whether it succeeded or not (a + refusal such as "does not exist" means the listing was stale). A refusal is + shown in the panel's notice in the server's words until dismissed + (`… already exists`, `… is not empty`, `… cannot be moved into itself`, + `… is outside the home directory …`, `… does not exist`, + `permission denied: …`), beside and separate from upload refusals. + +## Server + +`internal/server/home_files_mutate.go`, dispatched beside `list_directory` +in `websocket.go`, answered from its own goroutine: + +- `rename_path {path, name}`, `move_path {path, into}`, + `delete_path {path, recursive}` → `path_mutated {path}` or an `error` frame. +- Paths are absolute or `~`-based (`expandHomePath`). The entry's **parent** + folder and the move destination are resolved through symlinks and must stay + inside the operator's home (`resolveInsideHome`); the entry's own name is + `Lstat`ed, never followed, so a symlink is renamed, moved or removed as a + link and its target is untouched (also when it points outside home). + `os.RemoveAll` unlinks symlinks it meets rather than descending into them. +- Refused: the home directory itself (by `~`, path or trailing slash), any + path outside home (absolute, `..`, or through an escaping symlink), pseudo + filesystems (`specialFilesystem`), relative paths, a name with separators or + `.`/`..`, an existing target name (rename and move; a case-only rename of the + same entry is allowed), moving a folder into itself or a descendant, moving + into a file or a missing folder, and deleting a folder with contents without + `recursive`. +- Documented in `docs/cli.md` next to `list_directory`. + +## Limits + +- Moves use `os.Rename`, so a move across filesystems (a different mount + inside home) fails with the OS error shown as `… is not available: …`; no + copy-and-delete fallback. +- The client recognises the not-empty refusal by the phrase `is not empty` + (`protocol.FolderNotEmpty`); other refusals are displayed, not interpreted. +- No undo. No multi-select; one entry per operation. +- Only verified in widget tests and Go tests; no browser capture or device run + in this change, so rendered behaviour on web and Android is unverified. + +## Files + +- `app/lib/features/chat/files/files_mutations.dart` (RPC calls, name rules), + `files_rename_dialog.dart`, `files_delete_dialog.dart`, + `files_entry_actions.dart` (the three flows), `files_drag.dart` + (`FilesDraggableEntry`), `files_entries.dart` (menus on folders, drag + wrapping, target highlight), `files_controller.dart` (`rename`, `move`, + `delete`, `mutationLabel`, `mutationError`), `files_upload_notice.dart` + (progress and refusal for uploads and mutations), `files_models.dart` + (`canDropEntryOn`), `files_panel.dart` (menu actions, drop handler). +- `app/lib/features/chat/ui/folder_picker/folder_picker_purpose.dart` and the + `purpose` parameter on `showFolderPicker`, `FolderPickerPage`, + `FolderPickerController`, `FolderStartBar`; `folder_picker_list.dart` + disables rows the purpose excludes. +- `internal/protocol/directories.go`, `internal/protocol/message.go`, + `internal/server/home_files_mutate.go`, `internal/server/websocket.go`. +- Tests: `app/test/features/chat/files/files_panel_mutations_test.dart` + (rename with validation and cancel, move through the picker, subtree + exclusion, delete confirmation, not-empty then recursive, drag onto a folder + with highlight, refusal shown and dismissed, `canDropEntryOn`); + `internal/server/home_files_mutate_test.go` (each operation, every refusal + including `..`, outside, escaping-symlink and home-itself cases, symlink + handling, websocket round trip). + +## Verification + +From `app/`: + +``` +$ tool/memwatch/full.sh test/features/chat/files +memwatch: PASS: 46 passed, 0 failed, 0 skipped; peak 1653 MB; 5s; exit 0 (test/features/chat/files) +$ tool/memwatch/full.sh test/features/chat/ui/folder_picker +memwatch: PASS: 9 passed, 0 failed, 0 skipped; peak 964 MB; 5s; exit 0 (test/features/chat/ui/folder_picker) +$ tool/analyze.sh +analyze: clean; 5s; exit 0 +``` + +From the repository root: + +``` +$ gofmt -l internal/ # no output +$ go vet ./internal/server/ ./internal/protocol/ +$ go test ./internal/server/... ./internal/protocol/... -count=1 +ok git.a-wan.net/alan/pipelines/internal/server 62.981s +ok git.a-wan.net/alan/pipelines/internal/protocol 0.252s +```