Add Wormhole tentacle with internal UI and transfer preferences

wormhole/README.md

@@ -0,0 +1,151 @@
+# Wormhole
+
+An experimental Magic Wormhole Tentacle for Cthulhu-Go. Suggested shortcut:
+**Cthulhu+Alt+Shift+W**, on desktop and laptop layouts. It opens the reader's
+internal **Wormhole menu**, preserving the underlying application's focus.
+
+Install the `magic-wormhole` CLI using your distribution's package manager.
+Clipboard operations require `xclip` on Xorg. Missing `wormhole` does not stop
+reader startup: the shortcut speaks and brailles **Magic wormhole is not
+installed**, with speech protected from ordinary interruption. Lock, shutdown,
+disable and the reader's explicit stop policy still take precedence.
+
+Use Up/Down and Enter in lists. Tab/Shift+Tab move through forms, Space toggles
+checkboxes, and Escape closes the UI. Entries support editing, selection, Ctrl+C,
+Ctrl+X and Ctrl+V. A transfer's Escape or Cancel transfer stops its process.
+Changing native focus closes the UI and cancels the transfer. Only one transfer
+runs at a time; keep the transfer UI open until it completes.
+
+The menu offers:
+
+- **Send focused item**: send one current text line, preserving spacing and
+  replacing line breaks with spaces. Password fields are excluded. A reliably
+  exposed local file URI/path is sent as one file or folder. File icons/list
+  items/table rows without a path are rejected; a filename never silently
+  becomes a text message. Flat review without an exact text range is unavailable.
+- **Send from clipboard**: send text as a message, preserving its line breaks.
+  A local file URI from a file manager sends the file or folder. Exactly one
+  item is required; multiple files are rejected. Plain text that resembles a
+  path remains a text message. If the clipboard supplies PNG data, create a
+  private temporary `clipboard.png`, send it, and remove it after completion or
+  cancellation. A missing file path without any file data cannot be reconstructed.
+- **Receive**: type/paste a code in the internal Wormhole code entry, then press
+  Enter. Files and folders are saved in `~/Downloads`, which is created if
+  needed. Existing destinations are refused rather than overwritten. Text is
+  read automatically when the transfer completes.
+- **Preferences**: two independent checkboxes, both unchecked by default:
+  **Save received text messages to clipboard** and **Copy send code to clipboard**.
+  Checked means both speak and copy the respective text/code. Unchecked means
+  speak it and preserve the clipboard. Save persists both choices in
+  `$XDG_CONFIG_HOME/cthulhu-tentacles/wormhole.json` (normally `~/.config/...`).
+  Escape discards changes.
+
+Transfer controls offer **Read transfer status**, **Copy code**, and **Cancel
+transfer**. Generated codes are automatically spoken and shown on braille, and
+copied only when the preference is enabled. Copy code performs an explicit copy
+regardless of that preference. There is no per-packet progress chatter. Errors
+report failure, not success, and do not copy partial received messages.
+
+File managers such as Thunar, PCManFM, Caja and Nautilus do not have a common
+AT-SPI method that guarantees the selected file's full URI. The portable path
+is to select one file/folder, press Ctrl+C, open the menu and choose **Send from
+clipboard**. Direct selected-file sending without that copy remains unavailable
+when the application does not expose an exact path. No path is guessed from a
+window title, status bar, or filename.
+
+Text transfers currently have an 8 KiB input limit; received text has an 8,000
+byte limit so its complete announcement fits the reader's bounded output.
+Oversized data is rejected, not silently truncated. Clipboard PNG data has a
+32 MiB limit. Clipboard support currently uses Xorg; on Wayland a missing
+clipboard service reports an unavailable item. The Wormhole CLI manages the
+network protocol, directory archive and transport; the tentacle never executes
+received text or launches a shell for transfers. Consult the
+[Magic Wormhole documentation](https://magic-wormhole.readthedocs.io/en/latest/welcome.html).
+
+## Build and local launch
+
+Keep this repository beside the matching `cthulhu-go` checkout:
+
+```sh
+make build
+make check
+```
+
+The binary is `wormhole/bin/wormhole-tentacle`. The current reader must support
+`interaction` grants; an older presentation-only host will reject it.
+Use a local launch entry with both grants:
+
+```json
+[
+  {
+    "ID": "wormhole",
+    "Program": ["/home/angus/devel/cthulhu-tentacles/wormhole/bin/wormhole-tentacle"],
+    "Presentation": true,
+    "Interaction": true
+  }
+]
+```
+
+Development launches use `--tentacles /absolute/launch.json` and the existing
+contained launcher. Alternatively, add a local entry to the reader's version-1
+`tentacles.toml` beside its settings file (normally
+`~/.local/share/cthulhu/tentacles.toml`), preserving existing entries:
+
+```toml
+[[tentacles]]
+id = "wormhole"
+program = ["/home/angus/devel/cthulhu-tentacles/wormhole/bin/wormhole-tentacle"]
+enabled = true
+presentation = true
+interaction = true
+```
+
+The normal installation path is global Preferences → Tentacles → Add repository
+with `https://git.stormux.org/storm/cthulhu-tentacles`, followed by selecting
+Wormhole and Install and enable. Version 0.1.0 test downloads are served from an
+immutable commit on the separate `packages/wormhole-0.1.0` branch. The manifest
+requests presentation and interaction permissions. Local metadata above is an
+optional development path.
+Prepare amd64/arm64 archives with
+`python3 -B tools/package.py --tentacle wormhole`. Generated `dist/catalog.toml`
+preserves other catalog entries. Nothing is published by that command.
+
+## Live verification
+
+After configuring the local entry:
+
+1. Quit Cthulhu with Cthulhu+Q. Press Ctrl+Escape, then Shift+G. These are
+   separate key presses. Shift+G rebuilds the reader and braille helper.
+2. Focus an ordinary multiline text field. Open Cthulhu+Alt+Shift+W. Expect
+   “Wormhole menu. Send focused item” in speech and the menu option on braille.
+   Native application focus must stay on the original field. Send it to a
+   second Wormhole endpoint; the recipient must get exactly the current line.
+3. Open Preferences. Tab and Shift+Tab across both checkboxes and Save; Space
+   toggles each. Enable Copy send code to clipboard and Save. Send text from
+   the clipboard; expect the generated code spoken and shown on braille.
+   The clipboard must contain that exact code. Cancel the transfer. Disable
+   the preference and repeat; the original clipboard text must remain.
+4. In a file manager, copy exactly one file with Ctrl+C. Choose Send from
+   clipboard. Receive it at another endpoint and compare the contents.
+   Repeat with one folder, then multiple selected files: multiple items must
+   be refused. Sending a file icon without a usable path must give the copy
+   instruction and must not send its filename as text.
+5. Receive a file with the code entry. Test typing, cursor movement and Ctrl+V.
+   After completion, expect “Wormhole transfer received in Downloads” and the
+   actual file in Downloads. Repeat with an existing filename: expect failure
+   and unchanged original contents. Test a folder too.
+6. Receive text containing line breaks, quotes, backslashes and Unicode. With
+   Save received text messages to clipboard off, expect the complete message
+   spoken/shown and the previous clipboard preserved. Enable it and repeat:
+   expect the exact original text in the clipboard. Restart and verify both
+   checkbox choices persist.
+7. Cancel a waiting transfer with Escape and with Cancel transfer. Ordinary
+   typing must return to the original application, with no remaining modal
+   key capture. Test focus change, reader quit, and tentacle disable during
+   a waiting transfer. Check ordinary actions, learn mode, reading, and braille
+   afterward.
+
+Report the exact speech and braille, the focused control, the clipboard contents,
+and any key that behaved differently. Unexpected results should be diagnosed
+from `~/devel/cthulhu-go.log`. Automated and private Xorg checks do not establish
+physical speech, keyboard or braille acceptance.