feat(cli,core): shell completions with live values from the service

`pdfs completions <shell>` prints a completion script for bash, zsh, fish,
elvish or PowerShell, built on clap_complete's dynamic engine: on Tab the
shell calls `pdfs` back, which completes commands and options and also the
values the running service knows, each with a description: paths in My
files, synced-folder and queue ids, computers, trash, albums, items shared
with me, invitations, bookmarks, conflict copies, and a file's versions or
a share's members and public link once its path is typed.

A completer that gets no answer from the service within two seconds offers
nothing rather than hanging the prompt. Listings that ask Proton are kept
for 30 s in $XDG_RUNTIME_DIR (0600), so repeated Tabs do not wait again.
Completion is triggered by PDFS_COMPLETE rather than clap's generic
COMPLETE, because the same binary runs the daemon.

Share roles are now checked by the CLI before the request. The package
recipes install the bash, zsh and fish scripts via packaging/completions.sh.

docs/CHANGELOG.md

@@ -29,6 +29,16 @@ Existing folders stay device backups. Older builds cannot open the upgraded data
   on Proton Drive is trashed or moved out of My files, syncing stops with an error and the local
   files stay. Attaching a folder is done from a terminal for now.
 
+- **Tab completion for `pdfs`** in bash, zsh and fish, installed by every package. Besides
+  commands and options it completes paths in My files (`pdfs pin Doc<Tab>`) and what the running
+  service knows, each with a description: synced folders, queued changes, computers, trash, albums,
+  items shared with you, invitations, bookmarks and conflict copies, and once a path is typed, the
+  file's versions or the share's members and link. Without the service it still completes commands
+  and options. Elvish and PowerShell load it from `pdfs completions SHELL`, and so does a source
+  build; the [command-line reference](CLI.md#shell-completion) has the line for each shell.
+  `pdfs share` and `pdfs share-role` now check the role (`viewer`, `editor` or `admin`) before
+  sending the request, and `pdfs public-link` does the same for `viewer` and `editor`.
+
 ### Fixed
 
 - **My files comes back after the service was killed for hanging** (B279). A killed service left

docs/CLI.md

@@ -8,6 +8,7 @@ talks to the running service (`proton-drive.service`); `login`, `logout`, `mount
 what the commands do in the app, see the [user guide](USER_GUIDE.md).
 
 - [Conventions](#conventions)
+- [Shell completion](#shell-completion)
 - [Account and service](#account-and-service)
 - [Files](#files)
 - [Available offline](#available-offline)
@@ -32,6 +33,36 @@ what the commands do in the app, see the [user guide](USER_GUIDE.md).
   service.
 - **Output** is English and stable enough for `grep`; use `--json` where it is available.
 
+## Shell completion
+
+Tab completes commands and options, and also the values the service knows. Paths complete
+from My files, and these complete with a description: synced-folder and queue ids, computers,
+trash items, albums, items shared with you, invitations, bookmarks, conflict copies, and a file's
+versions or a share's members and link once the path is typed. Values come from the running
+service. Without it, only commands, options and local paths complete.
+
+| Example | Completes |
+|---|---|
+| `pdfs pin Doc<Tab>` | `Documents/`; Tab again lists its contents |
+| `pdfs sync rm <Tab>` | `1  /home/me/Documents (mirror)` … |
+| `pdfs devices rm <Tab>` | computer uids, with their names |
+| `pdfs versions restore Documents/a.pdf <Tab>` | version ids, with date and size |
+
+The packages install completion for bash, zsh and fish, which these shells load by themselves. For
+a source build, or another shell, load the script that `pdfs completions <shell>` prints:
+
+| Shell | Add to |
+|---|---|
+| bash | `~/.bashrc`: `source <(pdfs completions bash)` |
+| zsh | `~/.zshrc`, after `compinit`: `source <(pdfs completions zsh)` |
+| fish | `~/.config/fish/config.fish`: `pdfs completions fish \| source` |
+| elvish | `~/.config/elvish/rc.elv`: `eval (pdfs completions elvish \| slurp)` |
+| PowerShell | `$PROFILE`: `pdfs completions powershell \| Out-String \| Invoke-Expression` |
+
+The script runs `pdfs` from `PATH` on every Tab, so it keeps working after an update. A
+`pdfs` that is not on `PATH` prints a script for its own location with
+`PDFS_COMPLETE=<shell> ./pdfs`.
+
 ## Account and service
 
 | Command | Description |
@@ -185,6 +216,7 @@ commands are for scripts and for cases where the mount is not available.
 | `pdfs cache inspect [--deep]` | Database size, reclaimable space, row counts, cache use against the limit. `--deep` also runs SQLite's integrity check (slow). |
 | `pdfs cache vacuum` | Compact the database. Needs free space for a second copy of it while it runs. |
 | `pdfs cache clear` | Delete cached file content. Files kept available offline stay. |
+| `pdfs completions SHELL` | Print the [shell completion](#shell-completion) script for bash, zsh, fish, elvish or powershell. |
 
 [Troubleshooting](TROUBLESHOOTING.md) explains when to use each of these.