Korijn
diff --git a/‎.github/workflows/ci.yml‎
Lines changed: 85 additions & 7 deletions b/‎.github/workflows/ci.yml‎
Lines changed: 85 additions & 7 deletions
diff --git a/‎CLAUDE.md‎
Lines changed: 46 additions & 0 deletions b/‎CLAUDE.md‎
Lines changed: 46 additions & 0 deletions
diff --git a/‎README.md‎
Lines changed: 38 additions & 1 deletion b/‎README.md‎
Lines changed: 38 additions & 1 deletion
diff --git a/‎keycmd/conf.py‎
Lines changed: 6 additions & 1 deletion b/‎keycmd/conf.py‎
Lines changed: 6 additions & 1 deletion
diff --git a/‎pyproject.toml‎
Lines changed: 3 additions & 0 deletions b/‎pyproject.toml‎
Lines changed: 3 additions & 0 deletions
@@ -54,18 +54,31 @@ jobs:
   test:
     name: Test on ${{ matrix.name }}
     runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
     strategy:
       fail-fast: false
       matrix:
         include:
-          # the test suite exercises a real OS keyring, which is only
-          # available unattended on Windows runners
-          - name: Windows py313
-            os: windows-latest
-            pyversion: "3.13"
+          # every platform on the latest python, plus a single job on the
+          # oldest supported one to catch anything newer than it allows
+          - name: Linux py314
+            os: ubuntu-latest
+            pyversion: "3.14"
+          - name: macOS py314
+            os: macos-latest
+            pyversion: "3.14"
           - name: Windows py314
             os: windows-latest
             pyversion: "3.14"
+          - name: Linux py313
+            os: ubuntu-latest
+            pyversion: "3.13"
+    env:
+      # the test suite exercises a real OS keyring; this makes it fail
+      # instead of skipping those tests if the setup below breaks
+      KEYCMD_REQUIRE_OS_KEYRING: "1"
+      # the keyrings created below only ever hold test credentials
+      KEYCMD_KEYRING_PASSWORD: keycmd-test
     steps:
       - uses: actions/checkout@v7
       - name: Install uv and Python ${{ matrix.pyversion }}
@@ -77,8 +90,73 @@ jobs:
           cache-suffix: py${{ matrix.pyversion }}
       - name: Install dependencies
         run: uv sync
+      # windows runners expose the credential manager to the session out of
+      # the box; the other two need a keyring that unlocks without a prompt
+      - name: Install gnome-keyring
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install --yes --no-install-recommends gnome-keyring dbus-x11
+      - name: Create a keychain
+        if: runner.os == 'macOS'
+        run: |
+          security create-keychain -p "$KEYCMD_KEYRING_PASSWORD" "$KEYCHAIN"
+          # no auto lock, neither on a timeout nor on sleep
+          security set-keychain-settings "$KEYCHAIN"
+          security unlock-keychain -p "$KEYCMD_KEYRING_PASSWORD" "$KEYCHAIN"
+          # the keyring package talks to the default keychain
+          security list-keychains -d user -s "$KEYCHAIN" login.keychain
+          security default-keychain -s "$KEYCHAIN"
+        env:
+          KEYCHAIN: keycmd-test.keychain
+      # the secret service is bound to a d-bus session, so the tests have to
+      # run inside one, with the keyring daemon unlocked and running in it
+      - name: Test in a d-bus session
+        if: runner.os == 'Linux'
+        run: |
+          dbus-run-session -- bash -c '
+            printf "%s" "$KEYCMD_KEYRING_PASSWORD" |
+              gnome-keyring-daemon --unlock --components=secrets
+            uv run --no-sync pytest -v --cov=keycmd --cov-report=term-missing \
+              --cov-fail-under=95 tests
+          '
+      - name: Test
+        if: runner.os != 'Linux'
+        run: >
+          uv run --no-sync pytest -v --cov=keycmd --cov-report=term-missing
+          --cov-fail-under=95 tests
+
+  test-wsl:
+    name: Test on WSL
+    runs-on: windows-latest
+    timeout-minutes: 20
+    env:
+      KEYCMD_REQUIRE_OS_KEYRING: "1"
+      KEYCMD_TEST_WSL: "1"
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv and Python 3.14
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          python-version: "3.14"
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
+          cache-suffix: py3.14
+      - name: Install dependencies
+        run: uv sync
+      # WSL only provides the shell keycmd is invoked from; keycmd itself
+      # runs as a windows process, reading the windows credential manager
+      - name: Install WSL
+        uses: Vampire/setup-wsl@d1da7f2c0322a5ee4f24975344f67fc0f5baf364 # v7.0.0
+        with:
+          # the smallest distribution, on the WSL version that needs no
+          # virtual machine: the tests only need a shell on the other side
+          # of the interop boundary, and provisioning WSLv2 with a store
+          # distribution has taken anywhere from one to twenty minutes
+          distribution: Alpine-3.23
+          wsl-version: 1
       - name: Test
-        run: uv run --no-sync pytest -v --cov=keycmd --cov-report=term-missing tests
+        run: uv run --no-sync pytest -v tests/test_wsl.py
 
   build:
     name: Build and test wheel
@@ -100,7 +178,7 @@ jobs:
   publish:
     name: Publish to Github and Pypi
     runs-on: ubuntu-latest
-    needs: [lint, typecheck, test, build]
+    needs: [lint, typecheck, test, test-wsl, build]
     if: success() && startsWith(github.ref, 'refs/tags/v')
     permissions:
       contents: write
 
@@ -0,0 +1,46 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+`keycmd` runs a command with secrets from the OS keyring exposed as environment variables, so that credentials never have to live in a `.env` file. It supports Windows, macOS and Linux.
+
+## Commands
+
+```bash
+uv sync                         # create the virtual environment
+uv run pre-commit install       # the hooks run everything below on commit
+
+uv run ruff check --fix
+uv run ruff format
+uv run ty check --error-on-warning
+uv run pytest tests
+
+uv run pytest tests/test_conf.py::test_load_conf     # a single test
+uv run pytest -k "run_cmd and bash"                  # a single shell's parameters
+```
+
+## Testing
+
+The tests that read and write credentials need an OS keyring that unlocks without user interaction. They skip themselves with a message when there is none, so the rest of the suite still runs; `KEYCMD_REQUIRE_OS_KEYRING=1` turns those skips into failures, and CI sets it. Windows needs no setup, macOS needs an unlocked keychain, and Linux needs the tests to run inside a d-bus session with `gnome-keyring` unlocked (see the Testing section of the README for the exact commands). `PYTHON_KEYRING_BACKEND=keyrings.alt.file.PlaintextKeyring` with `uv run --with keyrings.alt` avoids the OS keyring entirely.
+
+`tests/test_wsl.py` covers calling the Windows install of keycmd from a shell inside WSL, and is opt in through `KEYCMD_TEST_WSL=1` on a Windows machine with WSL installed.
+
+Things that bite in this suite:
+
+- **Never assume a shell.** The `shell` fixture in `tests/conftest.py` parametrizes over every shell of the platform that is installed, so a test using it runs three times. Ask the `Shell` object for the dialect (`env_var`, `unset_env_var`, `command_not_found_statuses`) instead of branching on the platform. Shells that are not installed locally are covered by asserting on the command line keycmd builds for them.
+- **`wsl.exe` mangles its command line**: backslashes disappear and quotes are stripped before the distribution sees them. Pass paths translated to `/mnt/...` by `wsl_path`, unquoted and free of spaces, and keep remote scripts on one line.
+- Warnings are errors (`filterwarnings` in `pyproject.toml`), so a deprecation in a new Python release fails the suite rather than scrolling past.
+
+## Architecture
+
+`cli.main` wires the three halves together: `load_conf` produces the configuration, `get_env` turns it into an environment, and `run_cmd`/`run_shell` hand that environment to a shell. Errors reach the user through `logs.error`, which exits with status 1; `logs.vlog` output only appears under `--verbose` and is the first thing to reach for when debugging a configuration.
+
+**`conf.py` — where the configuration comes from.** Later sources win, merged deeply by `merge_conf`: defaults, then `~/.keycmd`, then every `.keycmd` found walking up from the working directory (outermost first), then the first `pyproject.toml` found walking up, whose `[tool.keycmd]` table is used. `find_file` stops at a `.git` directory, at the home folder, and at the root of the file system, so the walk never escapes a repository. `USERPROFILE` is a module attribute so tests can point the user config elsewhere. The merged result is `cast` to `Conf` rather than validated: it is user authored, and `get_env` reports violations as user errors.
+
+**`creds.py` — configuration to environment.** `get_env` copies `os.environ` and adds a variable per entry of `[keys]`, looking each credential up in the keyring; `[aliases]` re-expose an existing key under another name with different `b64`/`format` options, without a second keyring lookup. `expose` applies `format` first and `b64` second, which is what makes `{username}:{password}` basic auth work.
+
+**`shell.py` — where the platform differences live.** `get_shell` asks shellingham which shell invoked the process and falls back to `$SHELL` or `%COMSPEC%`. `cmd` takes `/C` and keeps the command's arguments separate; every other shell takes `-c` and a single joined string. `exec` replaces the process with `execvpe` on posix, but runs a subprocess on Windows, which has no equivalent; `USE_SUBPROCESS` and the `IS_WINDOWS`/`IS_POSIX` flags are module attributes so tests can drive both paths on either platform.
+
+## Conventions
+
+The package is fully annotated and ships a `py.typed` marker, so `ANN` rules apply to `keycmd/` while the test suite is exempt. `ty` is configured with `python-version = "3.13"`, the oldest supported release, so it catches typing features that are newer than `requires-python` allows. CI matches that split: the latest Python on all three platforms, plus a single job on the oldest.
@@ -417,7 +417,44 @@ uv run ty check
 uv run pytest tests
 ```
 
-Note that the test suite exercises a real OS keyring, so it needs a keyring backend that can be unlocked without user interaction. On Windows that works out of the box, which is why CI runs the tests there. On other platforms you can point keyring at a file-based backend instead:
+### Testing
+
+CI runs the test suite on Windows, macOS and Linux on the latest Python, plus one job on the oldest supported Python to catch anything newer than it allows. The suite adapts to the platform it runs on: it exercises every shell of the platform that is installed (`sh`, `bash` and `zsh` on posix, `cmd`, `powershell` and `pwsh` on Windows), and it skips the process replacement tests on Windows, which has no `execvpe`.
+
+The tests that read and write credentials need a real OS keyring that can be unlocked without user interaction. They are skipped with a message if there is no such keyring, so the rest of the suite still runs. Set `KEYCMD_REQUIRE_OS_KEYRING=1` to turn those skips into failures instead; CI sets it so that a broken keyring setup can't quietly reduce the coverage of a run.
+
+* **Windows**: the credential manager is available to your session out of the box, no setup needed.
+* **macOS**: your login keychain works as long as it is unlocked. CI instead creates a throwaway keychain and makes it the default:
+
+  ```bash
+  security create-keychain -p keycmd-test keycmd-test.keychain
+  security set-keychain-settings keycmd-test.keychain
+  security unlock-keychain -p keycmd-test keycmd-test.keychain
+  security list-keychains -d user -s keycmd-test.keychain login.keychain
+  security default-keychain -s keycmd-test.keychain
+  ```
+
+* **Linux**: the secret service is bound to a d-bus session, so the tests have to run inside one, with an unlocked keyring daemon (install `gnome-keyring` and `dbus-x11` first):
+
+  ```bash
+  dbus-run-session -- bash -c '
+    printf "%s" keycmd-test | gnome-keyring-daemon --unlock --components=secrets
+    uv run pytest tests
+  '
+  ```
+
+### Testing WSL
+
+The [WSL setup](#wsl-installation) has two halves. Working *inside* WSL, keycmd is a posix process like any other, talking to whichever keyring backend the distro provides; that is the Linux job above, keyring daemon and all. The other half, calling the Windows install of keycmd from a WSL shell to reach the Windows credential manager, crosses the interop boundary, and that is what `tests/test_wsl.py` covers: a credential in the credential manager, a shell inside WSL, and the Windows install of keycmd in between.
+
+Those tests are opt in, because installing WSL takes a CI job of its own. On a Windows machine that has WSL installed:
+
+```powershell
+$env:KEYCMD_TEST_WSL = 1
+uv run pytest tests/test_wsl.py
+```
+
+If you would rather not involve your OS keyring at all, point keyring at a file-based backend:
 
 ```bash
 uv run --with keyrings.alt pytest tests
 
@@ -40,7 +40,12 @@ def load_toml(path: Path) -> dict[str, Any]:
         try:
             return tomllib.load(fh)
         except tomllib.TOMLDecodeError as err:
-            raise tomllib.TOMLDecodeError(f"invalid TOML in {path}:\n{err}") from err
+            # name the offending file in the error, by rewriting the message
+            # of the original rather than raising a new one: the single
+            # argument constructor is deprecated as of python 3.14, and the
+            # structured one that replaces it does not exist before it
+            err.args = (f"invalid TOML in {path}:\n{err}",)
+            raise
 
 
 def load_pyproj(path: Path) -> dict[str, Any]:
 
@@ -84,6 +84,9 @@ python-version = "3.13"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+# deprecations are the way python announces what will break in a release
+# or two, so treat them as the failures they are about to become
+filterwarnings = ["error"]
 
 # example config for development and testing
 [tool.keycmd.keys]