exist-shell 0.1.0__tar.gz

exist_shell-0.1.0/.gitguardian.yaml

@@ -0,0 +1,5 @@
+paths-ignore:
+  - "tests/**"
+  - "tests"
+  - "scripts/e2e/**"
+  - "scripts/e2e"

exist_shell-0.1.0/.github/dependabot.yml

@@ -0,0 +1,17 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    cooldown:
+      default-days: 14
+
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    cooldown:
+      default-days: 14

exist_shell-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,30 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: "3.13"
+
+      - name: Install MkDocs
+        run: pip install mkdocs-material
+
+      - name: Deploy to GitHub Pages
+        run: mkdocs gh-deploy --force

exist_shell-0.1.0/.github/workflows/e2e.yml

@@ -0,0 +1,104 @@
+name: e2e
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  pull-requests: write
+
+jobs:
+  matrix:
+    runs-on: ubuntu-latest
+    outputs:
+      flags: ${{ steps.list.outputs.flags }}
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - name: Build image matrix from --list-images
+        id: list
+        run: |
+          flags=$(bash scripts/e2e.sh --list-images \
+            | awk '/^\s+--/{print $1}' \
+            | jq -R . | jq -sc .)
+          echo "flags=${flags}" >> "$GITHUB_OUTPUT"
+
+  e2e:
+    needs: matrix
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        flag: ${{ fromJson(needs.matrix.outputs.flags) }}
+      fail-fast: false
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - run: sudo apt-get install -y libxml2-utils
+      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          enable-cache: true
+      - run: uv sync
+      - name: Run e2e tests (${{ matrix.flag }})
+        id: run
+        continue-on-error: true
+        run: bash scripts/e2e.sh ${{ matrix.flag }} 2>&1 | tee e2e.log
+      - name: Save result artifact
+        if: always()
+        run: |
+          flag="${{ matrix.flag }}"
+          slug="${flag#--}"
+          image=$(grep "^Using image:" e2e.log | awk '{print $3}' || echo "$flag")
+          summary=$(grep -E "[0-9]+ passed, [0-9]+ failed" e2e.log | tail -1 | xargs || echo "no summary")
+          if grep -qF "FAILURES DETECTED" e2e.log 2>/dev/null; then
+            outcome="failure"
+          else
+            outcome="success"
+          fi
+          printf '%s\n%s\n%s\n' "${outcome}" "${image}" "${summary}" \
+            > "result-${slug}.txt"
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        if: always()
+        with:
+          name: e2e-result-${{ matrix.flag }}
+          path: result-*.txt
+
+  post-comment:
+    needs: [e2e]
+    runs-on: ubuntu-latest
+    if: always() && github.event_name == 'pull_request'
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          pattern: e2e-result-*
+          merge-multiple: true
+      - name: Build PR comment
+        run: |
+          {
+            echo "## 🐋 e2e Tests"
+            echo ""
+            echo "| Image | Result | Tests |"
+            echo "|-------|--------|-------|"
+            for f in result-*.txt; do
+              [[ -f "$f" ]] || continue
+              mapfile -t lines < "$f"
+              status="${lines[0]}"
+              image="${lines[1]}"
+              summary="${lines[2]}"
+              [[ "$status" == "success" ]] && icon="✅" || icon="❌"
+              echo "| \`${image}\` | ${icon} | ${summary} |"
+            done
+          } > comment.md
+          cat comment.md
+      - uses: marocchino/sticky-pull-request-comment@0ea0beb66eb9baf113663a64ec522f60e49231c0 # v2
+        with:
+          header: e2e
+          path: comment.md
+      - name: Fail if any image had test failures
+        run: |
+          for f in result-*.txt; do
+            [[ -f "$f" ]] || continue
+            read -r status _ < "$f"
+            if [[ "$status" != "success" ]]; then
+              echo "::error::E2E failures detected — see the comment above for details."
+              exit 1
+            fi
+          done

exist_shell-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,34 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    if: github.actor == 'ambs'
+    environment: release
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+
+      - name: Verify signed tag
+        run: |
+          gpg --import <<< "$GPG_PUBLIC_KEY"
+          git verify-tag "${{ github.ref_name }}"
+        env:
+          GPG_PUBLIC_KEY: ${{ secrets.GPG_PUBLIC_KEY }}
+
+      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          enable-cache: true
+
+      - run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0

exist_shell-0.1.0/.github/workflows/ruff.yml

@@ -0,0 +1,47 @@
+name: Ruff
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  pull-requests: write
+
+jobs:
+  ruff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          enable-cache: true
+      - run: uv sync
+      - name: Run Ruff
+        id: ruff
+        continue-on-error: true
+        run: uv run ruff check src/ 2>&1 | tee ruff.log
+      - name: Build PR comment
+        if: github.event_name == 'pull_request'
+        run: |
+          status="${{ steps.ruff.outcome }}"
+          if [[ "$status" == "success" ]]; then
+            echo "## 🔍 Ruff — ✅ No issues" > comment.md
+          else
+            count=$(grep -cE "\.py:[0-9]" ruff.log 2>/dev/null || echo 0)
+            {
+              echo "## 🔍 Ruff — ❌ ${count} violation(s)"
+              echo ""
+              echo '```'
+              cat ruff.log
+              echo '```'
+            } > comment.md
+          fi
+      - uses: marocchino/sticky-pull-request-comment@0ea0beb66eb9baf113663a64ec522f60e49231c0 # v2
+        if: github.event_name == 'pull_request'
+        with:
+          header: ruff
+          path: comment.md
+      - name: Propagate failure
+        if: steps.ruff.outcome == 'failure'
+        run: exit 1

exist_shell-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,49 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  pull-requests: write
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          enable-cache: true
+      - run: uv sync
+      - name: Run tests
+        id: pytest
+        continue-on-error: true
+        run: uv run pytest --cov=exist_shell --cov-report=xml --cov-report=term 2>&1 | tee pytest.log
+      - name: Build PR comment
+        if: github.event_name == 'pull_request'
+        run: |
+          status="${{ steps.pytest.outcome }}"
+          [[ "$status" == "success" ]] && icon="✅ Passed" || icon="❌ Failed"
+          test_line=$(grep -oE "[0-9]+ (passed|failed|error(s)?)[^,=]*" pytest.log | tr '\n' ', ' | sed 's/, $//' || echo "—")
+          coverage=$(grep "^TOTAL" pytest.log | awk '{print $NF}' || echo "—")
+          {
+            echo "## 🧪 Tests — ${icon}"
+            echo ""
+            echo "**${test_line}**  "
+            echo "**Coverage: ${coverage}**"
+          } > comment.md
+      - uses: marocchino/sticky-pull-request-comment@0ea0beb66eb9baf113663a64ec522f60e49231c0 # v2
+        if: github.event_name == 'pull_request'
+        with:
+          header: tests
+          path: comment.md
+      - uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: coverage.xml
+          fail_ci_if_error: false
+      - name: Propagate failure
+        if: steps.pytest.outcome == 'failure'
+        run: exit 1

exist_shell-0.1.0/.github/workflows/ty.yml

@@ -0,0 +1,47 @@
+name: ty
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  pull-requests: write
+
+jobs:
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        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
+      - name: Build PR comment
+        if: github.event_name == 'pull_request'
+        run: |
+          status="${{ steps.ty.outcome }}"
+          if [[ "$status" == "success" ]]; then
+            echo "## 🔎 ty — ✅ No errors" > comment.md
+          else
+            count=$(grep -cE "^error\[" ty.log 2>/dev/null || echo 0)
+            {
+              echo "## 🔎 ty — ❌ ${count} error(s)"
+              echo ""
+              echo '```'
+              cat ty.log
+              echo '```'
+            } > comment.md
+          fi
+      - uses: marocchino/sticky-pull-request-comment@0ea0beb66eb9baf113663a64ec522f60e49231c0 # v2
+        if: github.event_name == 'pull_request'
+        with:
+          header: ty
+          path: comment.md
+      - name: Propagate failure
+        if: steps.ty.outcome == 'failure'
+        run: exit 1

exist_shell-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+dist/
+.pytest_cache/
+.ruff_cache/
+.ty/
+.coverage
+coverage.xml

exist_shell-0.1.0/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+## unreleased
+
+## 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.0/CLAUDE.md

@@ -0,0 +1,108 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project
+
+`exsh` — a command-line tool to interact with an eXist-db server via its REST API. Subcommand structure (like git). Designed to work with shell pipes for scripting.
+
+## Dev setup
+
+Dependencies are managed with [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv sync                        # install all deps including dev group
+exsh --help
+exsh --version
+```
+
+## Commands
+
+```bash
+make checks                    # run ruff, ty and tests
+make test                      # run tests
+make ruff                      # lint with ruff
+make ty                        # type-check with ty
+```
+
+## Branching and pull requests
+
+All changes must go through a pull request — never commit directly to `main`.
+
+1. Create a feature branch: `git checkout -b feature/<short-description>`
+2. Make changes, commit with a signed commit (`git commit -S`)
+3. Before opening a PR, always fetch and rebase onto the latest `main`:
+   ```bash
+   git fetch origin main
+   git rebase origin/main
+   ```
+4. Push the branch and open a PR via `gh pr create`
+5. Do not merge without the PR being reviewed and all CI checks passing
+
+### Pull request descriptions
+
+- Never include unticked checkboxes in a PR description.
+- Run all relevant tests before opening the PR (or ask the user to run them if that is not possible).
+- Only create the PR once everything passes — with all checklist items already ticked.
+
+## File discipline
+
+Never stage or commit files that were not explicitly created as part of the current task or explicitly requested by the user. This includes cache directories, build artifacts, lock files, and any other files that appear as a side effect of running tools.
+
+## Linting
+
+Never run `ruff --fix` across the whole project. Only apply it to a specific file, and only when a manual edit has already failed to resolve the issue.
+
+## Docstrings
+
+Every public module, class, and method must have a docstring. Use Google style:
+
+```python
+def my_method(self, path: str) -> list[str]:
+    """Short one-line summary.
+
+    Args:
+        path: The collection path under /db/.
+
+    Returns:
+        List of item names found at the path.
+
+    Raises:
+        ExistNotFoundError: If the path does not exist.
+        ExistAuthError: If authentication fails.
+    """
+```
+
+- `Args` section required whenever the method has parameters beyond `self`.
+- `Returns` section required whenever the return type is not `None`.
+- `Raises` section required whenever the method raises documented exceptions.
+- Ruff enforces this via `select = ["D"]` with `convention = "google"`.
+
+## Code conventions
+
+- Python 3.11+. Never import from `typing` when a builtin works (`list`, `dict`, `str | None`, etc.).
+- Every function parameter and return type must be explicitly annotated.
+- Use direct Typer option assignment (`x: bool = typer.Option(...)`) over `Annotated` unless reuse across commands justifies it.
+- `ExistClient` is the single HTTP facade — all REST calls go through it. Commands receive a client via `typer.Context.obj`.
+- Shell completion for collection/document paths lives in `completions.py`.
+
+## Testing conventions
+
+- Always use `patch.object(module, 'attr')` instead of the string form `patch("module.path.attr")`. Only fall back to string-based `patch()` when `patch.object` is genuinely not applicable (e.g. patching a name in `builtins`).
+
+## Architecture
+
+```
+src/exist_shell/
+  main.py        # Typer app, global callback, subcommand registration
+  client/        # ExistClient — layered mixin package over the eXist REST API
+                 #   _base.py, _queries.py, _collections.py, _documents.py, _users.py
+  completions.py # shell completion (hits server at tab time)
+  cache.py       # TTL cache for completions
+  config.py      # server/collection config persistence
+  exceptions.py  # custom exceptions
+  models.py      # Pydantic API response models
+  utils.py       # shared utilities
+  xquery.py      # XQuery preprocessing and validation
+  commands/      # one module per subcommand: cat, collection, cp, edit, exec, ls, mkdir, put, rm, server, sync
+```

exist_shell-0.1.0/Makefile

@@ -0,0 +1,15 @@
+.PHONY: help ruff ty test checks
+
+help: ## Show available targets
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  %-8s %s\n", $$1, $$2}'
+
+checks: ruff ty test ## Run ruff, ty and tests
+
+test: ## Run tests
+	uv run pytest
+
+ruff: ## Lint with ruff
+	uv run ruff check src/
+
+ty: ## Type-check with ty
+	uv run ty check src/

exist_shell-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: exist-shell
+Version: 0.1.0
+Summary: Command-line tool to interact with eXist-db via REST
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: platformdirs>=4.10.0; sys_platform == 'win32'
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: tomlkit>=0.15.0
+Requires-Dist: typer>=0.26.7