exist-shell 0.1.2__tar.gz → 0.2.0__tar.gz

{exist_shell-0.1.2 → exist_shell-0.2.0}/.github/workflows/docs.yml

@@ -16,10 +16,10 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Set up Python
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
         with:
           python-version: "3.13"
 

{exist_shell-0.1.2 → exist_shell-0.2.0}/.github/workflows/e2e.yml

@@ -14,7 +14,7 @@ jobs:
     outputs:
       flags: ${{ steps.list.outputs.flags }}
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
       - name: Build image matrix from --list-images
         id: list
         run: |
@@ -31,9 +31,9 @@ jobs:
         flag: ${{ fromJson(needs.matrix.outputs.flags) }}
       fail-fast: false
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
       - run: sudo apt-get install -y libxml2-utils
-      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           enable-cache: true
       - run: uv sync
@@ -88,7 +88,7 @@ jobs:
             done
           } > comment.md
           cat comment.md
-      - uses: marocchino/sticky-pull-request-comment@0ea0beb66eb9baf113663a64ec522f60e49231c0 # v2
+      - uses: marocchino/sticky-pull-request-comment@5770ad5eb8f42dd2c4f34da00c94c5381e49af88 # v2
         with:
           header: e2e
           path: comment.md

{exist_shell-0.1.2 → exist_shell-0.2.0}/.github/workflows/release.yml

@@ -15,7 +15,7 @@ jobs:
     if: github.actor == 'ambs'
     environment: release
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Verify signed tag
         run: |
@@ -24,7 +24,7 @@ jobs:
         env:
           GPG_PUBLIC_KEY: ${{ secrets.GPG_PUBLIC_KEY }}
 
-      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           enable-cache: true
 

{exist_shell-0.1.2 → exist_shell-0.2.0}/.github/workflows/ruff.yml

@@ -12,8 +12,8 @@ jobs:
   ruff:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           enable-cache: true
       - run: uv sync
@@ -37,7 +37,7 @@ jobs:
               echo '```'
             } > comment.md
           fi
-      - uses: marocchino/sticky-pull-request-comment@0ea0beb66eb9baf113663a64ec522f60e49231c0 # v2
+      - uses: marocchino/sticky-pull-request-comment@5770ad5eb8f42dd2c4f34da00c94c5381e49af88 # v2
         if: github.event_name == 'pull_request'
         with:
           header: ruff

{exist_shell-0.1.2 → exist_shell-0.2.0}/.github/workflows/tests.yml

@@ -12,8 +12,8 @@ jobs:
   test:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           enable-cache: true
       - run: uv sync
@@ -34,7 +34,7 @@ jobs:
             echo "**${test_line}**  "
             echo "**Coverage: ${coverage}**"
           } > comment.md
-      - uses: marocchino/sticky-pull-request-comment@0ea0beb66eb9baf113663a64ec522f60e49231c0 # v2
+      - uses: marocchino/sticky-pull-request-comment@5770ad5eb8f42dd2c4f34da00c94c5381e49af88 # v2
         if: github.event_name == 'pull_request'
         with:
           header: tests

{exist_shell-0.1.2 → exist_shell-0.2.0}/.github/workflows/ty.yml

@@ -12,15 +12,15 @@ jobs:
   typecheck:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           enable-cache: true
       - run: uv sync
       - name: Run ty
         id: ty
         continue-on-error: true
-        run: uv run ty check src/ 2>&1 | tee ty.log
+        run: uv run ty check src/ tests/ 2>&1 | tee ty.log
       - name: Build PR comment
         if: github.event_name == 'pull_request'
         run: |
@@ -37,7 +37,7 @@ jobs:
               echo '```'
             } > comment.md
           fi
-      - uses: marocchino/sticky-pull-request-comment@0ea0beb66eb9baf113663a64ec522f60e49231c0 # v2
+      - uses: marocchino/sticky-pull-request-comment@5770ad5eb8f42dd2c4f34da00c94c5381e49af88 # v2
         if: github.event_name == 'pull_request'
         with:
           header: ty

{exist_shell-0.1.2 → exist_shell-0.2.0}/.gitignore

@@ -8,3 +8,5 @@ dist/
 .ty/
 .coverage
 coverage.xml
+plans/
+CLAUDE.local.md

exist_shell-0.2.0/CHANGELOG.md

@@ -0,0 +1,83 @@
+# Changelog
+
+## 0.2.0 - 2026-07-28
+
+### Fixes
+
+- `config.toml` (which stores server passwords in plaintext) was written with default umask permissions — typically world-readable on multi-user machines. It is now written `0600` with the config directory at `0700`, and `exsh` warns on stderr when an existing config file is group/world-readable
+- Non-401/404 HTTP errors (most notably `403 Forbidden`) leaked a raw `httpx` traceback; they now exit cleanly with a one-line error message. `cp` local→remote also gained the XML well-formedness check that `put` and `sync` already had
+- The sync manifest was keyed only by the remote path, so syncing the same remote collection against two different local directories shared one manifest and silently corrupted each other's per-file state (false conflicts, wrong skip decisions). The manifest key now includes the resolved local directory; existing manifests are re-keyed via a one-time full recheck on the next sync
+- A single failed transfer during sync left the rest of the queue finishing silently in the background with no progress output, ending in a generic unattributed error. Failures are now reported per file (`! <path>  (error: ...)`) as they happen, the remaining queue keeps draining, the summary shows a `failed` count, and sync exits non-zero when anything failed
+- `is_remote()` classified any argument containing `:` as a `nick:path` remote target, so Windows paths (`C:\data\doc.xml`) and any local path with a colon in a directory component were always misparsed as a remote nick. A prefix is now only treated as a nick when it matches a configured collection, isn't a single-letter drive prefix (`C:\`, `C:/`), and doesn't itself contain a path separator. Server/collection nicks must now be at least 2 characters, guaranteeing a configured nick can never collide with a Windows drive letter
+- `mv` of a collection onto itself (`exsh mv nick:/a nick:/a`) or into itself via a trailing slash (`exsh mv nick:/a nick:/a/`) copied the contents onto/into the source and then recursively deleted it, destroying the data. `mv` now aborts with an error when the target is the same as, or nested inside, the source, for both collections and single documents
+- `cat`/`cp`/`mv`/`edit`/`sync` downloading an executable resource (`.xql`, `.xqm`) ran the query on the server and returned its result instead of the document's raw source
+- The above fix relied on eXist's `_source=yes` REST parameter, which requires the path to be explicitly allowlisted in the server's `descriptor.xml` — not the default for anything under `/db`, regardless of the caller's own read permission. This returned `403 Forbidden` for every executable-resource download (`.xq`, `.xql`, `.xqm`, `.xquery`, `.xqy`, `.xqws`) on an unconfigured (i.e. most) server. These resources are now fetched via `util:binary-doc()`, which only needs the read + query-eval permission already required to execute them
+- `rm <nick>:<path>` on a path that is a collection silently deleted the entire subtree with no confirmation, since eXist's `DELETE` is recursive on collections. `rm` now refuses a collection target unless `--recursive`/`-r` is given, and prompts for confirmation unless `--yes`/`-y` is also passed
+- `create_collection`, `is_collection`, and `move_document` embedded paths/names into generated XQuery without escaping `"`/`&`, unlike every other client method — a path or name containing either broke the query (or, in `move_document`, changed its meaning)
+- `rm` and `find --remove` never invalidated the completion cache after deleting, so deleted documents kept appearing in tab completion until the cache TTL expired
+
+### Enhancements
+
+- **Independent client timeouts**: connect (10s), read (30s), and write (10s) now have separate budgets instead of one flat 30s timeout for every phase, and timeout errors say which phase failed — "Cannot connect to ..." for handshake failures vs "Server at ... did not respond in time" for read/write timeouts.
+- **Faster, correct bash tab-completion for `nick:path` targets**: the generated bash completion script now handles the `:` word-break correctly (no more `dlp:dlp:...` insertions), completing a collection no longer needs an extra backspace before continuing into it, and completion listings are filtered and capped server-side and cached per prefix so progressive typing reuses a single fetch. Re-run `exsh --install-completion bash` after upgrading to pick up the new script.
+- **Exit code 130 on Ctrl+C** for the whole CLI (previously sync-only), including during shell completion itself, which Typer/click don't handle on their own.
+- **Parallel sync (`--jobs N`)**: uploads, downloads, and remote directory listings now run concurrently. The `--jobs N` flag (default: 4) controls the number of parallel workers. Use `--jobs 1` to restore fully sequential behaviour.
+- **Clean Ctrl+C handling**: interrupting a sync now exits with code 130, saves the manifest (so the next run can resume), and prints a single `Interrupted.` message instead of a Python traceback.
+- **`exsh find`**: locate documents by XPath expression anywhere in their content (`exsh find <nick>[:<path>] --query 'foo[@type="draft"]'`), with `--remove`/`--yes` to delete every match in one step.
+- **`exsh exec --resource <nick>:<path.xql>`**: execute a stored `.xql`/`.xqm` resource in place (a plain `GET`, matching how eXist runs these resources natively) instead of downloading it and re-running it locally. Repeat `-p/--param NAME=VALUE` to forward query-string parameters as external variables.
+- **`exsh sync --exclude`**: repeatable glob patterns to skip paths on both sides of a sync (`--exclude '*.tmp' --exclude build`). A pattern with `/` matches that relative path and its subtree; one without `/` matches any path segment at any depth. Patterns persist in the sync manifest per (server, remote path, local folder), so later runs keep excluding without the flag; new patterns merge into the stored list and `--clear-exclude` resets it. Excluded paths are never transferred and never deleted by `--delete`. Files synced before becoming excluded are deleted on both sides after confirmation (`--yes` skips the prompt, declining keeps the files, `--keep-excluded` keeps them without asking); either way they stop being tracked.
+
+## 0.1.2 - 2026-06-23
+
+### Documentation
+
+- Document installing `exsh` from PyPI (`uv tool install`, `pipx install`, `uvx --from`); the existing `git+https://...` instructions are kept as an alternative for tracking unreleased commits
+
+## 0.1.1 - 2026-06-23
+
+### Fixes
+
+- Complete PyPI project metadata: `readme`, `license` (MIT), `authors`, `classifiers`, `project.urls`, and `keywords` were all missing, leaving the 0.1.0 PyPI listing with no description, license, or links
+- Add `LICENSE` file (MIT)
+
+## 0.1.0 - 2026-06-23
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `server add / ls / rm` | Register, list, and remove eXist-db server configurations; `rm` cascade-removes associated collections |
+| `server rename <old> <new>` | Rename a server nick; all registered collections are updated automatically |
+| `collection add / new / ls / rm` | Manage named collection shortcuts; `new` creates the collection on the server and registers it in one step (idempotent: no-op if already exists) |
+| `ls [path]` | List documents and sub-collections at a remote path; `--sort name\|time`, `--reverse`, `--names-only` |
+| `cat <path>` | Print a remote document to stdout; `--raw` skips binary detection |
+| `put <path>` | Upload a document from stdin or a local file; auto-detects MIME type |
+| `cp <src> <dst>` | Copy documents local↔remote or remote↔remote |
+| `rm <path...>` | Delete one or more remote documents |
+| `mkdir <path>` | Create a remote collection (idempotent) |
+| `edit <path>` | Download, open in `$VISUAL`/`$EDITOR`, re-upload if changed |
+| `sync push/pull <dir> <path>` | Sync a local directory tree with a remote collection; supports `--delete`, `--dry-run`, `--force` |
+| `mv <src> <dst>` | Move or rename a document or collection; trailing `/` on dest moves into that collection; cross-server moves not supported |
+| `exec <nick>[:<path>]` | Read an XQuery script from a file or stdin, optionally preprocess it (version declaration, functx import), validate locally with BaseX or Saxon (auto-detected via PATH), then execute against eXist and print the result; supports `--no-fix`, `--no-validate`, `--validator`, `--list-validators` |
+| `user ls` | List user accounts and their groups; accepts `@server` positional |
+| `user add <user[@server]>` | Create a user account (prompts for password) |
+| `user rm <user[@server]>` | Remove a user account |
+| `user info <user[@server]>` | Show user account details |
+| `user passwd <user[@server]>` | Change a user's password; `--stdin` for scripting |
+| `group ls` | List groups and their members; accepts `@server` positional |
+| `group add <group[@server]>` | Create a group |
+| `group rm <group[@server]>` | Remove a group |
+| `chown <spec> <path>` | Change owner and/or group of a document or collection; `--recursive / -R` for collections; spec forms: `owner`, `:group`, `owner:group` |
+| `chmod <mode> <path>` | Change POSIX permissions of a document or collection; `--recursive / -R` for collections; accepts octal (`0755`) or symbolic (`u+x`, `go-w`, `a=rw`) modes |
+
+### Infrastructure
+
+- Shell completion for collection/document paths (with TTL cache)
+- `<name>@<server>` syntax for ad-hoc server targeting in `collection add`, `collection new`, `user *`, and `group *`
+- `--server` option on all commands completes registered server nicks
+- Shell completion for `<name>@<server>` and `@<server>` argument forms
+- Path traversal validation and URL encoding
+- Google-style docstrings enforced via ruff
+- CI: pytest + coverage (Codecov), ruff, ty, e2e test suite against live eXist-db in Docker
+- CI: sticky PR comments for tests (counts + coverage), ruff, ty, and e2e workflows
+- CI: e2e workflow with dynamic image matrix from `--list-images`; `fail-fast: false`

{exist_shell-0.1.2 → exist_shell-0.2.0}/Makefile

@@ -9,7 +9,7 @@ test: ## Run tests
 	uv run pytest
 
 ruff: ## Lint with ruff
-	uv run ruff check src/
+	uv run ruff check src/ tests/
 
 ty: ## Type-check with ty
-	uv run ty check src/
+	uv run ty check src/ tests/

{exist_shell-0.1.2 → exist_shell-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: exist-shell
-Version: 0.1.2
+Version: 0.2.0
 Summary: Command-line tool to interact with eXist-db via REST
 Project-URL: Homepage, https://github.com/ambs/exist-shell
 Project-URL: Repository, https://github.com/ambs/exist-shell
@@ -135,11 +135,13 @@ Configuration is stored at `~/.config/exsh/config.toml`.
 | `exsh put <file> <nick>:<path>` | Upload a local file to a collection |
 | `exsh cp <src> <dst>` | Copy a document (local ↔ remote or remote ↔ remote) |
 | `exsh edit <nick>:<path>` | Open a document in `$EDITOR`, re-upload if changed |
-| `exsh rm <nick>:<path>...` | Delete one or more documents |
+| `exsh rm <nick>:<path>...` | Delete one or more documents; `--recursive`/`-r` (with `--yes`/`-y`) to delete a collection |
 | `exsh mkdir <nick>:<path>` | Create a collection |
 | `exsh sync <local> <nick>[:<path>]` | Push a local folder to a remote collection |
 | `exsh sync <nick>[:<path>] <local>` | Pull a remote collection to a local folder |
 | `exsh exec <nick>[:<path>]` | Execute an XQuery script on a server |
+| `exsh exec --resource <nick>:<path.xql>` | Execute a stored resource in place, forwarding `-p name=value` params |
+| `exsh find <nick>[:<path>] --query <xpath>` | Find documents matching an XPath expression, with optional `--remove` |
 | `exsh server add <host>` | Register a server |
 | `exsh server ls` | List registered servers |
 | `exsh server rm <nick>` | Remove a server (and its collections) |
@@ -185,6 +187,9 @@ exsh rm mydata:reports/2025/old.xml
 # Delete multiple documents
 exsh rm mydata:reports/2025/a.xml mydata:reports/2025/b.xml
 
+# Delete a whole collection (prompts unless --yes is also given)
+exsh rm --recursive mydata:reports/2025
+
 # Create a subcollection
 exsh mkdir mydata:reports/2026
 
@@ -200,6 +205,18 @@ exsh exec mydata:/ --no-fix -f query.xq
 # List locally available XQuery validators
 exsh exec --list-validators
 
+# Execute a stored .xql/.xqm resource in place, rather than downloading it first
+exsh exec --resource mydata:/report.xql
+
+# ...forwarding query-string parameters as external variables
+exsh exec --resource mydata:/report.xql -p from=2026-01-01 -p to=2026-12-31
+
+# List documents containing a matching element anywhere in their tree
+exsh find mydata:reports --query 'foo[@type="draft"]'
+
+# Delete every match, skipping the confirmation prompt
+exsh find mydata:reports --query 'foo[@type="draft"]' --remove --yes
+
 # Push a local folder to the server (only transfers changed files)
 exsh sync ./reports mydata:reports
 
@@ -212,6 +229,9 @@ exsh sync --dry-run ./reports mydata:reports
 # Push and remove files on the server that no longer exist locally
 exsh sync --delete ./reports mydata:reports
 
+# Sync everything except temp files and the build folder (remembered for later runs)
+exsh sync --exclude '*.tmp' --exclude build ./reports mydata:reports
+
 # Change owner and group of a document
 exsh chown alice:editors mydata:reports/annual.xml
 
@@ -238,13 +258,26 @@ exsh chmod -R 0644 mydata:data
 
 **Conflicts** (both sides changed since last sync) are reported and skipped — use `--force` to override.
 
+**Excludes:** `--exclude`/`-e <pattern>` (repeatable) skips matching paths on both sides of the sync — they are neither transferred nor ever deleted by `--delete`. Patterns are `fnmatch`-style (`*`, `?`, `[seq]`), matched against the path relative to the sync root:
+
+- A pattern containing `/` matches that relative path and everything below it (`build/sub` also excludes `build/sub/x.xml`). Note that `*` in such a pattern also crosses `/` (plain `fnmatch`, unlike gitignore): `build/*.xml` matches `build/sub/x.xml` too.
+- A pattern without `/` matches any single path segment at any depth — `build` excludes `build/`, `a/build/`, and their contents; `*.tmp` excludes temp files everywhere.
+
+Patterns are persisted in the sync manifest, per (server, remote path, local folder), so later runs keep excluding without repeating the flag. New `--exclude` patterns are merged into the stored list; `--clear-exclude` wipes it (combine both to replace the list in one run). Files that were synced before becoming excluded are deleted **on both sides** after a confirmation prompt — `--yes` skips the prompt, declining (or running non-interactively without `--yes`) keeps the files, and `--keep-excluded` keeps them without asking. In every case they stop being tracked.
+
 **Options:**
 
 | Flag | Effect |
 |------|--------|
 | `--force` / `-f` | Transfer all files, bypassing change detection |
 | `--dry-run` / `-n` | Show what would happen without transferring |
+| `--fail-fast` | Stop on the first conflict, invalid XML, or transfer error (runs sequentially; the manifest is saved so the run can resume) |
+| `--jobs N` / `-j` | Number of parallel transfer workers (default: 4); `--jobs 1` for fully sequential behaviour |
 | `--delete` | Remove files and empty folders on the destination that no longer exist on the source |
+| `--exclude PATTERN` / `-e` | Skip matching paths on both sides (repeatable); merged into the list stored for this sync pair |
+| `--clear-exclude` | Wipe the stored exclude list before applying any `--exclude` given in the same run |
+| `--keep-excluded` | Keep previously synced copies of newly excluded paths; only stop tracking them |
+| `--yes` / `-y` | Skip the confirmation prompt when deleting previously synced, newly excluded files |
 | `--verbose` / `-v` | Also print unchanged (skipped) files |
 | `--checkpoint-every N` | Flush the manifest every N files (default: 100); allows interrupted syncs to resume near the point of failure |
 
@@ -263,6 +296,8 @@ exsh --install-completion zsh
 exsh --install-completion fish
 ```
 
+Upgrading? Re-run `exsh --install-completion bash` to pick up fixes to the generated script — it's written once to `~/.bash_completions/` (or equivalent) and isn't updated automatically.
+
 ## Development
 
 ```bash

{exist_shell-0.1.2 → exist_shell-0.2.0}/README.md

@@ -104,11 +104,13 @@ Configuration is stored at `~/.config/exsh/config.toml`.
 | `exsh put <file> <nick>:<path>` | Upload a local file to a collection |
 | `exsh cp <src> <dst>` | Copy a document (local ↔ remote or remote ↔ remote) |
 | `exsh edit <nick>:<path>` | Open a document in `$EDITOR`, re-upload if changed |
-| `exsh rm <nick>:<path>...` | Delete one or more documents |
+| `exsh rm <nick>:<path>...` | Delete one or more documents; `--recursive`/`-r` (with `--yes`/`-y`) to delete a collection |
 | `exsh mkdir <nick>:<path>` | Create a collection |
 | `exsh sync <local> <nick>[:<path>]` | Push a local folder to a remote collection |
 | `exsh sync <nick>[:<path>] <local>` | Pull a remote collection to a local folder |
 | `exsh exec <nick>[:<path>]` | Execute an XQuery script on a server |
+| `exsh exec --resource <nick>:<path.xql>` | Execute a stored resource in place, forwarding `-p name=value` params |
+| `exsh find <nick>[:<path>] --query <xpath>` | Find documents matching an XPath expression, with optional `--remove` |
 | `exsh server add <host>` | Register a server |
 | `exsh server ls` | List registered servers |
 | `exsh server rm <nick>` | Remove a server (and its collections) |
@@ -154,6 +156,9 @@ exsh rm mydata:reports/2025/old.xml
 # Delete multiple documents
 exsh rm mydata:reports/2025/a.xml mydata:reports/2025/b.xml
 
+# Delete a whole collection (prompts unless --yes is also given)
+exsh rm --recursive mydata:reports/2025
+
 # Create a subcollection
 exsh mkdir mydata:reports/2026
 
@@ -169,6 +174,18 @@ exsh exec mydata:/ --no-fix -f query.xq
 # List locally available XQuery validators
 exsh exec --list-validators
 
+# Execute a stored .xql/.xqm resource in place, rather than downloading it first
+exsh exec --resource mydata:/report.xql
+
+# ...forwarding query-string parameters as external variables
+exsh exec --resource mydata:/report.xql -p from=2026-01-01 -p to=2026-12-31
+
+# List documents containing a matching element anywhere in their tree
+exsh find mydata:reports --query 'foo[@type="draft"]'
+
+# Delete every match, skipping the confirmation prompt
+exsh find mydata:reports --query 'foo[@type="draft"]' --remove --yes
+
 # Push a local folder to the server (only transfers changed files)
 exsh sync ./reports mydata:reports
 
@@ -181,6 +198,9 @@ exsh sync --dry-run ./reports mydata:reports
 # Push and remove files on the server that no longer exist locally
 exsh sync --delete ./reports mydata:reports
 
+# Sync everything except temp files and the build folder (remembered for later runs)
+exsh sync --exclude '*.tmp' --exclude build ./reports mydata:reports
+
 # Change owner and group of a document
 exsh chown alice:editors mydata:reports/annual.xml
 
@@ -207,13 +227,26 @@ exsh chmod -R 0644 mydata:data
 
 **Conflicts** (both sides changed since last sync) are reported and skipped — use `--force` to override.
 
+**Excludes:** `--exclude`/`-e <pattern>` (repeatable) skips matching paths on both sides of the sync — they are neither transferred nor ever deleted by `--delete`. Patterns are `fnmatch`-style (`*`, `?`, `[seq]`), matched against the path relative to the sync root:
+
+- A pattern containing `/` matches that relative path and everything below it (`build/sub` also excludes `build/sub/x.xml`). Note that `*` in such a pattern also crosses `/` (plain `fnmatch`, unlike gitignore): `build/*.xml` matches `build/sub/x.xml` too.
+- A pattern without `/` matches any single path segment at any depth — `build` excludes `build/`, `a/build/`, and their contents; `*.tmp` excludes temp files everywhere.
+
+Patterns are persisted in the sync manifest, per (server, remote path, local folder), so later runs keep excluding without repeating the flag. New `--exclude` patterns are merged into the stored list; `--clear-exclude` wipes it (combine both to replace the list in one run). Files that were synced before becoming excluded are deleted **on both sides** after a confirmation prompt — `--yes` skips the prompt, declining (or running non-interactively without `--yes`) keeps the files, and `--keep-excluded` keeps them without asking. In every case they stop being tracked.
+
 **Options:**
 
 | Flag | Effect |
 |------|--------|
 | `--force` / `-f` | Transfer all files, bypassing change detection |
 | `--dry-run` / `-n` | Show what would happen without transferring |
+| `--fail-fast` | Stop on the first conflict, invalid XML, or transfer error (runs sequentially; the manifest is saved so the run can resume) |
+| `--jobs N` / `-j` | Number of parallel transfer workers (default: 4); `--jobs 1` for fully sequential behaviour |
 | `--delete` | Remove files and empty folders on the destination that no longer exist on the source |
+| `--exclude PATTERN` / `-e` | Skip matching paths on both sides (repeatable); merged into the list stored for this sync pair |
+| `--clear-exclude` | Wipe the stored exclude list before applying any `--exclude` given in the same run |
+| `--keep-excluded` | Keep previously synced copies of newly excluded paths; only stop tracking them |
+| `--yes` / `-y` | Skip the confirmation prompt when deleting previously synced, newly excluded files |
 | `--verbose` / `-v` | Also print unchanged (skipped) files |
 | `--checkpoint-every N` | Flush the manifest every N files (default: 100); allows interrupted syncs to resume near the point of failure |
 
@@ -232,6 +265,8 @@ exsh --install-completion zsh
 exsh --install-completion fish
 ```
 
+Upgrading? Re-run `exsh --install-completion bash` to pick up fixes to the generated script — it's written once to `~/.bash_completions/` (or equivalent) and isn't updated automatically.
+
 ## Development
 
 ```bash

{exist_shell-0.1.2 → exist_shell-0.2.0}/docs/commands.md

@@ -181,11 +181,20 @@ EDITOR=nano exsh edit mydata:config.xml
 Delete one or more documents from an eXist collection.
 
 ```
-exsh rm <nick>:<path>...
+exsh rm [--recursive] [--yes] <nick>:<path>...
 ```
 
 Multiple paths can be supplied in a single invocation. Deletion is permanent — there is no undo.
 
+A target that is itself a collection is refused by default (`Error: '<nick>:<path>' is a collection; use -r/--recursive to delete it and everything under it.`) rather than silently deleting the whole subtree. Pass `--recursive` to allow it; unless `--yes` is also given, `rm` first prompts for confirmation naming the collection being removed.
+
+### Options
+
+| Flag | Effect |
+|------|--------|
+| `--recursive / -r` | Allow a target that is a collection to be deleted, along with everything under it. |
+| `--yes / -y` | Skip the confirmation prompt when deleting a collection. |
+
 ### Examples
 
 ```bash
@@ -194,6 +203,12 @@ exsh rm mydata:reports/2025/old.xml
 
 # Delete multiple documents at once
 exsh rm mydata:reports/2025/a.xml mydata:reports/2025/b.xml
+
+# Delete a whole collection (prompts for confirmation)
+exsh rm --recursive mydata:reports/2025
+
+# Delete a whole collection without prompting
+exsh rm --recursive --yes mydata:reports/2025
 ```
 
 ---
@@ -271,6 +286,7 @@ Execute an XQuery script on an eXist-db server and print the result to stdout.
 
 ```
 exsh exec <nick>[:<path>] [-f FILE] [--no-fix] [--no-validate] [--validator NAME]
+exsh exec --resource <nick>:<path.xql> [-p NAME=VALUE ...]
 ```
 
 The query is read from `--file` or from stdin. Before sending, `exsh` optionally preprocesses the source and validates it locally:
@@ -291,10 +307,18 @@ The first installed validator found on `PATH` is used automatically. Use `--vali
 
 Run `exsh exec --list-validators` to see which validators are available on the current machine.
 
+### Executing a stored resource
+
+`--resource <nick>:<path.xql>` runs a `.xql`/`.xqm` script that's already stored on the server in place, instead of sending local source. This is a plain `GET` on the resource — the same mechanism eXist uses to execute these MIME types automatically — so it relies on the resource being invoked in its own stored collection context, which matters for scripts that assume that context (e.g. relative `doc()`/`collection()` lookups).
+
+`--resource` is mutually exclusive with the `<nick>[:<path>]` argument, and skips local preprocessing/validation entirely, since there's no local source to fix up or check. Repeat `-p/--param NAME=VALUE` to forward query-string parameters, which the resource can read as external variables.
+
 ### Options
 
 | Flag | Description |
 |------|-------------|
+| `--resource <nick>:<path.xql>` | Execute a stored resource in place instead of local code. |
+| `-p / --param NAME=VALUE` | Query-string parameter to forward with `--resource` (repeatable). |
 | `-f / --file FILE` | XQuery file to execute. When omitted, stdin is read. |
 | `--no-fix` | Skip preprocessing (version declaration, namespace imports). |
 | `--no-validate` | Skip local validation even if a validator is installed. |
@@ -324,6 +348,58 @@ exsh exec mydata:/ --validator basex -f query.xq
 
 # Check which validators are available locally
 exsh exec --list-validators
+
+# Execute a stored resource in place, rather than downloading it first
+exsh exec --resource mydata:/report.xql
+
+# ...forwarding query-string parameters as external variables
+exsh exec --resource mydata:/report.xql -p from=2026-01-01 -p to=2026-12-31
+```
+
+---
+
+## find
+
+Locate documents whose content matches an XPath expression, and optionally delete every match in one step.
+
+```
+exsh find <nick>[:<path>] --query <xpath> [--remove] [--yes]
+```
+
+The expression given to `--query` is evaluated recursively under the target collection (equivalent to `collection(...)//(QUERY)`), and each matching document is printed as a `<nick>:<path>` target — the same format `rm` and every other command accepts. Because `rm` takes its targets as arguments (not from standard input), pipe `find` output through `xargs` to feed it into `rm`:
+
+```bash
+exsh find mydata:reports --query 'foo[@type="draft"]' | xargs -r exsh rm
+```
+
+Deleting matches directly with `--remove` is usually simpler; the pipe form is useful when you want to filter the list first.
+
+Without `--remove`, `find` only lists matches — this is inherently a dry run. With `--remove`, matches are deleted as they're printed; unless `--yes` is also given, `find` first prompts for confirmation showing the number of matching documents. If a document reported by the search has already disappeared by the time it is deleted, `find` warns and continues, then exits non-zero.
+
+> **Security note:** the `--query` expression is embedded into a server-side XQuery without validation or sandboxing, so it can execute arbitrary XQuery with your configured server credentials (the same trust model as `exsh exec`). Only pass expressions from a trusted source.
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `--query / -q XPATH` | XPath expression to match, evaluated recursively under the target (required). |
+| `--remove` | Delete matching documents instead of just listing them. |
+| `--yes / -y` | Skip the confirmation prompt when used with `--remove`. |
+
+### Examples
+
+```bash
+# List documents containing a matching element anywhere in their tree
+exsh find mydata:reports --query 'foo[@type="draft"]'
+
+# Match on an attribute nested deeper in the document
+exsh find mydata:/ --query 'section/foo[@type="draft"]'
+
+# Delete every match, with a confirmation prompt showing the match count
+exsh find mydata:reports --query 'foo[@type="draft"]' --remove
+
+# Delete every match, skipping the confirmation prompt
+exsh find mydata:reports --query 'foo[@type="draft"]' --remove --yes
 ```
 
 ---

{exist_shell-0.1.2 → exist_shell-0.2.0}/docs/sync.md

@@ -3,7 +3,7 @@
 Synchronise a local directory tree with a remote eXist collection, transferring only files that have actually changed.
 
 ```
-exsh sync <source> <dest> [--force] [--fail-fast] [--dry-run] [--delete] [--verbose] [--checkpoint-every N]
+exsh sync <source> <dest> [--force] [--fail-fast] [--dry-run] [--delete] [--verbose] [--jobs N] [--checkpoint-every N]
 ```
 
 ## Direction
@@ -78,6 +78,7 @@ Use `--force` to override conflict detection and transfer the source uncondition
 | `--dry-run / -n` | Print what would happen without moving any data |
 | `--delete` | Remove files and empty folders on the destination that no longer exist on the source |
 | `--verbose / -v` | Also print unchanged (skipped) files |
+| `--jobs N / -j N` | Number of parallel transfer workers (default: 4); set to 1 for sequential |
 | `--checkpoint-every N` | Flush the manifest to disk every N files (default: 100) |
 
 ## Output
@@ -126,6 +127,29 @@ exsh sync --delete ./reports mydata:reports
 exsh sync --force ./reports mydata:reports
 ```
 
+## Parallelism
+
+By default `exsh sync` runs up to **4 transfers concurrently** — both for file uploads/downloads and for the initial remote directory listing (BFS walk). This significantly reduces wall-clock time when syncing collections with many small files over a high-latency connection.
+
+```bash
+# Use 8 workers for a large collection
+exsh sync --jobs 8 ./data myserver:data
+
+# Restore sequential behaviour (one file at a time)
+exsh sync --jobs 1 ./data myserver:data
+```
+
+`--fail-fast` always runs sequentially regardless of `--jobs`, to guarantee that no file after the first failure is transferred.
+
+### Interrupting a sync
+
+Pressing **Ctrl+C** during a sync:
+
+- Cancels any pending (not yet started) transfers immediately.
+- Waits for at most `--jobs` in-flight transfers to finish (they cannot be interrupted mid-request).
+- Saves the manifest so the next run resumes from where it stopped.
+- Exits with code **130** (the POSIX convention for Ctrl+C).
+
 ## Large collections and resumability
 
 For collections with many files, the manifest is flushed to disk every 100 files by default. If a sync is interrupted (network failure, process kill, etc.), the next run reads the saved manifest and skips files that were already transferred, restarting near the point of failure rather than from scratch.

{exist_shell-0.1.2 → exist_shell-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "exist-shell"
-version = "0.1.2"
+version = "0.2.0"
 description = "Command-line tool to interact with eXist-db via REST"
 readme = "README.md"
 license = "MIT"
@@ -41,7 +41,7 @@ Issues = "https://github.com/ambs/exist-shell/issues"
 Changelog = "https://github.com/ambs/exist-shell/blob/main/CHANGELOG.md"
 
 [project.scripts]
-exsh = "exist_shell.main:app"
+exsh = "exist_shell.main:cli"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/exist_shell"]
@@ -54,9 +54,9 @@ convention = "google"
 
 [dependency-groups]
 dev = [
-    "pytest>=8",
+    "pytest>=9.1.1",
     "pytest-cov>=5",
     "pytest-httpx>=0.30",
-    "ruff>=0.15.16",
-    "ty>=0.0.46",
+    "ruff>=0.15.18",
+    "ty>=0.0.54",
 ]

{exist_shell-0.1.2 → exist_shell-0.2.0}/scripts/e2e/sections/T05_put.sh

@@ -8,6 +8,7 @@ section_T05_put() {
     # Prepare local files (persist for T06+)
     printf '<hello>world</hello>' > "${TMPDIR_E2E}/hello.xml"
     printf '\x00\x01\x02\x03'   > "${TMPDIR_E2E}/data.bin"
+    printf 'xquery version "3.1";\n<computed>{2 + 2}</computed>' > "${TMPDIR_E2E}/script.xq"
 
     # T05.1 — upload XML from file
     assert_exit0 "T05.1 put XML file" \
@@ -67,4 +68,10 @@ section_T05_put() {
     # T05.12 — binary file is uploaded without XML validation
     assert_exit0 "T05.12 put binary skips XML validation" \
         "${EXSH[@]}" put testcol:/data.bin -f "${TMPDIR_E2E}/data.bin" --mime application/octet-stream
+
+    # T05.13 — .xq file stored as application/xquery (eXist's executable resource type;
+    # --mime is required since exsh has no built-in guess for this extension). Regression
+    # coverage for #141/#144: cat/cp must return the source below, not the query's output.
+    assert_exit0 "T05.13 put .xq file as application/xquery" \
+        "${EXSH[@]}" put testcol:/script.xq -f "${TMPDIR_E2E}/script.xq" --mime application/xquery
 }