qem 0.2.0__tar.gz

qem-0.2.0/.editorconfig

@@ -0,0 +1,14 @@
+# SPDX-FileCopyrightText: 2026 René de Hesselle <dehesselle@web.de>
+#
+# SPDX-License-Identifier: 0BSD
+
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+charset = utf-8
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false

qem-0.2.0/.gitattributes

@@ -0,0 +1,5 @@
+# SPDX-FileCopyrightText: 2026 René de Hesselle <dehesselle@web.de>
+#
+# SPDX-License-Identifier: 0BSD
+
+* text=auto eol=lf

qem-0.2.0/.github/workflows/build.yml

@@ -0,0 +1,152 @@
+# SPDX-FileCopyrightText: 2026 René de Hesselle <dehesselle@web.de>
+#
+# SPDX-License-Identifier: 0BSD
+
+name: Build
+on:
+  push:
+    branches: ["**"]
+    tags: ["v[0-9]*"]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  #-----------------------------------------------------------------------------
+
+  Lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+
+      # keep aligned with [tool.ruff] in pyproject.toml
+      - name: Check formatting
+        run: uvx --from 'ruff~=0.16.0' ruff format --check .
+
+      - name: Lint
+        run: uvx --from 'ruff~=0.16.0' ruff check .
+
+      - name: Check REUSE compliance
+        run: uvx reuse lint
+
+  #-----------------------------------------------------------------------------
+
+  Test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python: ["3.12"]
+        include:
+          - os: ubuntu-latest
+            python: "3.14"
+    runs-on: ${{ matrix.os }}
+    steps:
+      # full history for hatch-vcs
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: Run tests
+        run: uv run --locked pytest
+
+  #-----------------------------------------------------------------------------
+
+  Build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+
+      - name: Build project
+        run: uv build --no-sources
+
+      - name: Smoke-test wheel
+        run: |
+          uv run --isolated --no-project --with dist/*.whl python - <<'EOF'
+          import os
+          import qem
+          print(qem.__version__)
+          if os.environ["GITHUB_REF_TYPE"] == "tag":
+              expected = os.environ["GITHUB_REF_NAME"].removeprefix("v")
+              assert qem.__version__ == expected, (qem.__version__, expected)
+          EOF
+          uv run --isolated --no-project --with dist/*.whl qem --version
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: dist
+          path: dist/
+
+  #-----------------------------------------------------------------------------
+
+  Release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    needs:
+      - Lint
+      - Test
+      - Build
+    if: startsWith(github.ref, 'refs/tags/v')
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create draft release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: >-
+          gh release create "$GITHUB_REF_NAME" dist/*
+          --repo "$GITHUB_REPOSITORY"
+          --draft
+          --verify-tag
+          --generate-notes
+
+  #-----------------------------------------------------------------------------
+
+  PyPI:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    needs:
+      - Build
+      - Release
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment:
+      name: pypi
+      url: https://pypi.org/p/qem
+
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3

qem-0.2.0/.gitignore

@@ -0,0 +1,20 @@
+# SPDX-FileCopyrightText: 2026 René de Hesselle <dehesselle@web.de>
+#
+# SPDX-License-Identifier: 0BSD
+
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Generated by hatch-vcs
+src/qem/version.py
+
+# Local devbox helper
+justfile

qem-0.2.0/.python-version

@@ -0,0 +1 @@
+3.12

qem-0.2.0/CLAUDE.md

@@ -0,0 +1,19 @@
+# qem
+
+A Python library and CLI for NoMac cloud Macs that replaces the npm `nomac` CLI for
+sessions, jobs, ssh and sync.
+
+- Read docs/DESIGN.md before architectural changes and respect its core principles,
+  especially: the library never prints or exits, and the tunnel's stdout carries SSH
+  bytes only.
+- Read docs/protocol.md before touching API calls. Update it when the live service turns
+  out to differ.
+- docs/MANUAL.md documents every command, option and library call.
+
+@docs/DEVELOPMENT.md
+
+Documentation rules: the README stays short. A change to design, usage or behavior
+updates the matching document in docs/ in the same change. DESIGN.md is kept current and
+carries no project history.
+
+Never run `qem start` (it costs real credit) unless the user asks for it.

qem-0.2.0/LICENSE

@@ -0,0 +1,12 @@
+Copyright (C) 2026 by René de Hesselle
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

qem-0.2.0/LICENSES/0BSD.txt

@@ -0,0 +1,5 @@
+Copyright (C) 2026 by René de Hesselle
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

qem-0.2.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.5
+Name: qem
+Version: 0.2.0
+Summary: Python library and CLI for NoMac cloud Macs (nomac.app)
+Author-email: René de Hesselle <dehesselle@web.de>
+License-Expression: 0BSD
+License-File: LICENSE
+License-File: LICENSES/0BSD.txt
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: pathspec>=1.1.1
+Requires-Dist: platformdirs>=4
+Requires-Dist: pomona>=0.1
+Requires-Dist: websockets>=17.1
+Description-Content-Type: text/markdown
+
+# quick ephemeral mac
+
+`qem` is a Python library and command-line tool for
+[NoMac](https://nomac.app) cloud Macs. It can start a Mac, run commands on it, open SSH
+sessions and sync a project folder. It does this without Node or npm, and it runs natively
+on Windows as well as on macOS and Linux.
+
+It covers the session part of NoMac's official `nomac` CLI: login, start/stop, exec/jobs,
+ssh, sync/pull, and the Mac's desktop in a window. Every command is a thin layer over
+the library, so other Python programs can do the same things without the CLI.
+
+## Install and use
+
+Requirements are Python 3.12+ and OpenSSH, on Windows x86_64, macOS on Apple silicon or
+Linux x86_64 (the platforms that [pomona](https://pypi.org/project/pomona/), the desktop
+viewer, has wheels for).
+
+```sh
+uv tool install qem
+qem login          # approve the code in the browser
+qem start --max-duration 30m --max-cost 1
+qem sync .
+qem exec -- xcodebuild -version
+qem ssh
+qem stop
+```
+
+From Python, after `pip install qem`:
+
+```python
+from qem import Nomac
+
+with Nomac() as nm, nm.start(max_duration=1800, max_cost=1) as mac:
+    print(mac.exec(["sw_vers"]).stdout)
+```
+
+A running Mac is billed per minute, so always pass `--max-cost` and `--max-duration`.
+
+## Documentation
+
+- [docs/MANUAL.md](docs/MANUAL.md): every command and option, the library API, credentials
+  and local files.
+- [docs/DESIGN.md](docs/DESIGN.md): architecture and core principles.
+- [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md): setup, tests and the offline tunnel check.
+- [docs/protocol.md](docs/protocol.md): the NoMac API and SSH tunnel as qem uses them,
+  where each fact comes from, and which parts are not yet verified against the live
+  service.
+
+## AI disclosure
+
+Substantial parts of this code were generated with Opus 5.x. Generated code was
+tested, but not every line was reviewed in detail.
+
+## License
+
+[0BSD](LICENSE). qem is not affiliated with NoMac.

qem-0.2.0/README.md

@@ -0,0 +1,56 @@
+# quick ephemeral mac
+
+`qem` is a Python library and command-line tool for
+[NoMac](https://nomac.app) cloud Macs. It can start a Mac, run commands on it, open SSH
+sessions and sync a project folder. It does this without Node or npm, and it runs natively
+on Windows as well as on macOS and Linux.
+
+It covers the session part of NoMac's official `nomac` CLI: login, start/stop, exec/jobs,
+ssh, sync/pull, and the Mac's desktop in a window. Every command is a thin layer over
+the library, so other Python programs can do the same things without the CLI.
+
+## Install and use
+
+Requirements are Python 3.12+ and OpenSSH, on Windows x86_64, macOS on Apple silicon or
+Linux x86_64 (the platforms that [pomona](https://pypi.org/project/pomona/), the desktop
+viewer, has wheels for).
+
+```sh
+uv tool install qem
+qem login          # approve the code in the browser
+qem start --max-duration 30m --max-cost 1
+qem sync .
+qem exec -- xcodebuild -version
+qem ssh
+qem stop
+```
+
+From Python, after `pip install qem`:
+
+```python
+from qem import Nomac
+
+with Nomac() as nm, nm.start(max_duration=1800, max_cost=1) as mac:
+    print(mac.exec(["sw_vers"]).stdout)
+```
+
+A running Mac is billed per minute, so always pass `--max-cost` and `--max-duration`.
+
+## Documentation
+
+- [docs/MANUAL.md](docs/MANUAL.md): every command and option, the library API, credentials
+  and local files.
+- [docs/DESIGN.md](docs/DESIGN.md): architecture and core principles.
+- [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md): setup, tests and the offline tunnel check.
+- [docs/protocol.md](docs/protocol.md): the NoMac API and SSH tunnel as qem uses them,
+  where each fact comes from, and which parts are not yet verified against the live
+  service.
+
+## AI disclosure
+
+Substantial parts of this code were generated with Opus 5.x. Generated code was
+tested, but not every line was reviewed in detail.
+
+## License
+
+[0BSD](LICENSE). qem is not affiliated with NoMac.

qem-0.2.0/REUSE.toml

@@ -0,0 +1,12 @@
+version = 1
+
+# Files that can't carry an SPDX comment, or shouldn't: docs stay clean when
+# rendered, uv.lock is regenerated.
+[[annotations]]
+path = [
+    "**.md",
+    "uv.lock",
+    ".python-version",
+]
+SPDX-FileCopyrightText = "2026 René de Hesselle <dehesselle@web.de>"
+SPDX-License-Identifier = "0BSD"

qem-0.2.0/docs/DESIGN.md

@@ -0,0 +1,158 @@
+# Design
+
+This document describes how qem is built and the rules the code keeps.
+
+## Architecture
+
+qem has two layers.
+
+- **Library** (`qem`, everything outside `qem.cli`): talks to the NoMac REST API,
+  builds ssh command lines, moves files over ssh, and runs the SSH tunnel.
+  - `transport.Transport` is the only place that does HTTP. It adds the Bearer key, the
+    `Idempotency-Key` header and the `wait` long-poll parameter, and turns error envelopes
+    into `errors.ApiError` subclasses.
+  - `nomac.Nomac` covers the account: `me`, `credits`, `sessions`, `start`, `session`.
+  - `mac_session.MacSession` is one Mac: lifecycle, jobs, `prepare_ssh`/`ssh`, `sync`/`pull`,
+    and `password`/`desktop_tunnel`.
+  - `models` holds typed, read-only views of responses. Each keeps the full response in
+    `raw`.
+  - `ssh`, `tunnel`, `upload` (sync), `transfer` (Mac paths, pull) and `vnc` (desktop) are
+    free functions that `MacSession` puts together.
+- **CLI** (`qem.cli`): argparse in `cli/__init__.py`, handlers in `cli/commands.py`,
+  and the per-folder session store in `cli/project_store.py`.
+
+SSH never reaches the Mac directly. ssh runs `python -m qem proxy <id>` as its
+ProxyCommand, and that process carries the SSH bytes over a WebSocket to NoMac's gateway
+(see [protocol.md](protocol.md)).
+
+The desktop uses that ssh as well. An ssh port forward makes the Mac's Screen Sharing,
+which listens only on the Mac's own 127.0.0.1:5900, reachable on this computer.
+[pomona](https://pypi.org/project/pomona/), a dependency, signs in there with the
+session's login from `/password` and shows the screen in a window. It speaks Apple's
+Adaptive quality, which generic VNC viewers lack, so qem starts no external viewer.
+pomona is imported only when the window opens, so the other commands do not load its
+Rust extension. The nomac.app browser page is not used, because it needs the web login
+rather than the API key.
+
+Files move as tar streams over that ssh. Neither direction uses rsync.
+
+- **`pull`** runs `tar -c` on the Mac and unpacks the stream with Python's `tarfile`.
+- **`sync`** runs a small POSIX sh script on the Mac, over one ssh connection, using only
+  macOS's own tools. The exchange goes like this:
+  1. The script lists the project folder with `find` and `stat`.
+  2. qem compares the list with its own scan of the local folder.
+  3. qem writes the paths to delete, then a tar stream of the new and changed files.
+  4. The script reads the delete list with `read` and `dd bs=1`, which take no more than
+     they need, deletes, and hands the rest of stdin to `tar -x`.
+
+  Files are compared by type, size, whole-second modification time and permission bits.
+  `upload.ProjectFilter` holds the skip rules. It decides for local files and for paths
+  that exist only on the Mac, so `--delete` never removes what the rules leave out.
+  Secrets (`upload.SECRETS`) rank above `.gitignore`, so a project's own rules cannot
+  send them; only a `!` line in `.nomacignore` can. `.pem` and `.key` files count as
+  secrets only when their first 64 KiB hold a private key, so certificates and Keynote
+  documents still go. Names match in any case, as on Windows' and macOS's file systems.
+
+qem does not use rsync because Windows has no rsync that just works:
+
+- The native builds can't download from macOS's openrsync, which speaks only protocol 29.
+- The MSYS2 and Cygwin builds rewrite paths when they start Windows OpenSSH.
+
+[protocol.md](protocol.md) has the details. Without rsync there is one code path for
+every platform, and it needs only ssh. What is lost is rsync's transfer of just the
+changed parts of a file, which matters little for source code.
+
+## Core principles
+
+1. **The library never prints, prompts or calls `sys.exit`.** It returns values and
+   raises `NomacError` subclasses, because other programs embed it. Output, exit codes
+   and questions belong in `qem.cli`.
+2. **The library keeps no hidden per-project state.** Callers pass session ids, keys and
+   paths in. The map from project folder to session lives only in the CLI store, because
+   a program using the library decides on its own what a "current" Mac is. The only files
+   the library writes are SSH material in qem's folder (`config.home()`): generated
+   keys, pinned known_hosts, an empty ssh config, and the sockets ssh makes for shared
+   connections.
+   It also removes them again: `stop()` deletes the session's known_hosts and a key that
+   qem generated, and a start the API refuses deletes the key made for it. A key the
+   caller passed in is never deleted.
+3. **Commands are never run twice by accident.** `start` and `exec` always send an
+   `Idempotency-Key`. After a `NetworkError` the CLI prints the key to retry with, and the
+   library has no automatic retries. The API says to reuse a key and never retry with a
+   new one. A generated SSH key is named after the request key, so a retried start sends
+   the same body, and the key is kept after a `NetworkError`.
+4. **The tunnel's stdout carries SSH bytes and nothing else.** Every diagnostic goes to
+   stderr, because ssh reads stdout as the protocol stream.
+5. **Host keys are pinned, never trusted on first use.** The host key from the
+   `/access` call is written to a per-session known_hosts under the alias `qem-<id>`,
+   and ssh runs with `StrictHostKeyChecking=yes`. That alias is also the ssh hostname,
+   which is never resolved through DNS.
+6. **The access token and the Mac's password are never written to disk.** A parent that
+   already called `/access` passes the token to the ProxyCommand through
+   `QEM_TUNNEL_*` environment variables. On its own, `qem proxy` calls `/access` itself.
+   The password goes from memory to `pomona.connect`. `Login` keeps
+   it out of its repr. The token goes only to the gateway that `/access` named, and only
+   encrypted:
+   - `tunnel_url` accepts only a bare `https` origin, with no login, path or query.
+   - Plain `http` is accepted only for a loopback address, which the tests use.
+   - The session id is percent-encoded, so it cannot change the path.
+   - websockets drops the `Authorization` header when a redirect leads to another host.
+7. **Unknown response fields are tolerated.** The API has no published schema
+   ([protocol.md](protocol.md)). Models read fields defensively, unwrap `{"session": …}`
+   and `{"job": …}` when present, and keep `raw` so callers are not blocked by a missing
+   field.
+8. **Separate from the npm CLI.** Everything lives in qem's own folder, not `~/.nomac`,
+   and the command is `qem`. The npm CLI's file formats are undocumented, and both
+   tools may be installed side by side. The npm CLI is UNLICENSED: qem takes only
+   protocol facts from it (listed in [protocol.md](protocol.md)), never its code,
+   structure or wording. Names, defaults and behaviour come from NoMac's public docs, the
+   API or qem's own design. Timeouts rest on measured timings. qem does not imitate the
+   npm CLI where the service does not require it.
+
+## Platform choices
+
+- qem's folder is the user config folder from platformdirs, not a dot-folder in the
+  home folder. Everything goes in that one folder, keys and sockets included, so
+  `QEM_HOME` moves all of it. On Windows it is the local, non-roaming AppData, so
+  private keys are not copied between machines. The macOS folder contains a space
+  (`Application Support`), so every path qem writes into an ssh option or config,
+  including the `Include` line of `ssh-config`, is quoted when it has one.
+- Paths inside ssh options use forward slashes on Windows. Windows OpenSSH accepts them,
+  and MSYS ssh would otherwise lose the backslashes when it runs the ProxyCommand through
+  `/bin/sh`.
+- An empty file in qem's folder stands in for `/dev/null` (`-F`,
+  `GlobalKnownHostsFile`), because Windows OpenSSH does not understand `/dev/null`.
+- Windows OpenSSH stops writing its stdout in session 0 (ssh logins, services), so
+  there qem uses Git's ssh instead, found only next to the `git` on `PATH`. The session
+  comes from `ProcessIdToSessionId` through ctypes. qem replaces only Windows' own
+  OpenSSH and never searches the disk; `QEM_SSH` overrides the choice.
+- MSYS ssh runs the ProxyCommand through `$SHELL`, which in an ssh login to Windows is
+  that server's shell, often PowerShell. For an ssh with `sh.exe` beside it,
+  `prepare_ssh()` therefore sets `SHELL` to that `sh.exe` in ssh's environment.
+- ControlMaster multiplexing is used only off Windows, where OpenSSH supports it.
+  - Each Mac gets one socket in `mux/` in qem's folder, named by a 16-digit hash of the
+    session id.
+  - When that path is too long for a Unix socket (macOS allows 104 bytes, and ssh adds
+    17 for a temporary name), ssh runs without sharing.
+  - The shared connection closes 60 s after its last use. It is kept short because an
+    open connection may keep the Mac from counting as idle.
+  - A port forward always gets a connection of its own. Then the port closes when that
+    ssh ends, and a taken port fails it at once (`ExitOnForwardFailure`).
+- ssh sends keepalives every 15 s and gives up after 8 missed answers. The provider's
+  network can stall the tunnel for a while, so ssh should not give up sooner.
+  `ConnectTimeout=30` limits the wait for the Mac's SSH banner. The tunnel itself
+  gives up on the WebSocket handshake after 15 s.
+- On Windows, a generated private key gets an ACL that lists only the current user
+  (`icacls`). Windows OpenSSH ignores keys that anyone else may read, and MSYS
+  `ssh-keygen` adds an OWNER RIGHTS entry that counts as that.
+- `pull` unpacks with `tarfile`'s `data` filter, so an archive from the Mac cannot write
+  outside the target folder.
+- Windows has no executable bit, so there `sync` takes it from Git's index. Untracked
+  files count as executable when they start with `#!`. Other platforms use the file's
+  own permission bits.
+- The project folder on the Mac has the local folder's name, unchanged apart from NFC.
+  Every shell command quotes it, so no character needs replacing. Only an empty name (a
+  drive root) and one over macOS's 255 bytes are refused.
+- `sync` compares file names in Unicode NFC form. After `tar -x`, macOS listed a name
+  decomposed (NFD), while Windows keeps it composed, so the two spellings would never
+  match. Deletions use the name exactly as the Mac stores it.

qem-0.2.0/docs/DEVELOPMENT.md

@@ -0,0 +1,110 @@
+# Development
+
+This document covers setting up, testing, versioning and releasing qem.
+
+## Setup
+
+```sh
+uv sync                     # creates .venv, installs qem editable plus pytest
+uv run qem --help
+```
+
+The version comes from git tags through hatch-vcs and is written to the generated
+`src/qem/version.py`. Tag releases as `vX.Y.Z`. After a new commit or tag, run
+`uv sync --reinstall-package qem` to refresh that file.
+
+The project is REUSE compliant. A new file starts with the SPDX header that
+`reuse annotate --copyright "René de Hesselle <dehesselle@web.de>" --license 0BSD`
+writes. A file that can't carry a comment goes in `REUSE.toml` instead.
+
+## Tests
+
+```sh
+uv run pytest
+uvx --from 'ruff~=0.16.0' ruff format --check .
+uvx --from 'ruff~=0.16.0' ruff check .   # default rules; the generated version.py is excluded
+uvx reuse lint                           # every file has copyright and license information
+```
+
+- None of the tests touch the real NoMac service. `QEM_HOME` points at a temporary
+  folder and `NOMAC_API_KEY` is a dummy.
+- `tests/conftest.py` has `FakeApi`, a route table for `httpx.MockTransport`. Library tests
+  build `Nomac(http_client=…, sleep=…)` with it.
+- `test_library.py` runs the library on its own and fails if anything prints or calls
+  `sys.exit` (core principle 1 in [DESIGN.md](DESIGN.md)).
+- `test_cli.py` calls `qem.cli.main()` with `Nomac` patched to use the fake API, and
+  checks exit codes (including 75) and output.
+- `test_upload.py` covers `sync` without a Mac: the skip rules, the local scan, the
+  parsing of the Mac's file list, what gets sent and removed, and the tar stream. The
+  Mac-side shell script is checked only against the live service.
+- `test_vnc.py` covers the desktop without a Mac. A small Python process that opens the
+  port stands in for ssh, and the test checks that the tunnel waits for the port, reports
+  ssh's errors, and is closed afterwards. A stand-in `pomona` module checks the sign-in
+  and that a reconnect reopens a tunnel whose ssh ended. No test opens a window.
+- `test_tunnel.py` starts a local WebSocket server and runs `python -m qem proxy`
+  as a real subprocess. It checks that every byte value passes through unchanged, that
+  the Bearer header reaches the server, and that a refused handshake ends with exit code
+  255 and nothing on stdout. It also pins which gateway URLs `tunnel_url` refuses.
+- `test_ssh_transfer.py` checks the ssh command lines: host-key pinning, batch mode,
+  multiplexing and forwards. It also runs the real `ssh-keygen` when there is one.
+- `test_ssh_choice.py` covers which ssh qem runs (`QEM_SSH`, Git's ssh without a desktop
+  on Windows), on a fake Windows layout.
+- `test_device_login.py` covers the device login, including RFC 8628's `slow_down` and the
+  login's expiry.
+
+## CI and releases
+
+`.github/workflows/build.yml` runs on every push and pull request. It runs the format,
+lint and REUSE checks, the tests on Linux, Windows and macOS, and builds the sdist and
+wheel. It also installs the wheel and checks that `qem --version` runs.
+
+To release, push a `vX.Y.Z` tag. CI checks that the built version matches the tag,
+creates a draft GitHub release with the files from `dist/`, and publishes them to
+[PyPI](https://pypi.org/p/qem) through trusted publishing (the `pypi` environment). No
+token is stored. Publishing the draft release on GitHub is a manual step.
+
+## Checking ssh without a NoMac account
+
+The unit tests do not cover a real ssh client running the ProxyCommand. To check that
+part, run a local WebSocket server that bridges to any public SSH server (for example
+`github.com:22`). Then set `QEM_TUNNEL_SESSION`, `QEM_TUNNEL_GATEWAY`
+(`http://127.0.0.1:<port>`) and `QEM_TUNNEL_TOKEN`, write that server's host key with
+`qem.ssh.write_known_hosts`, and run `qem.ssh.ssh_argv(...)`.
+
+ssh should get as far as `Permission denied (publickey)`. That means the ProxyCommand,
+the tunnel and host-key pinning work. Try it with Windows OpenSSH (from PowerShell) and
+with Git's MSYS ssh (from Git Bash).
+
+On a Linux devbox, bridge to a throwaway `sshd -D -f <config>` on another port, with its
+own host key and an `AuthorizedKeysFile` holding a key from `generate_identity`. Set
+`ssh.USERNAME` to a user that exists there. Root needs `UsePAM yes` if its password is
+locked. With a key that is accepted, this also checks commands, binary stdin,
+connection sharing and `--forward`.
+
+On a Windows devbox, bridge to a Unix sshd (a Linux devbox's port 22 works), not to the
+box's own OpenSSH Server: its PowerShell login shell mangles binary stdin. Inside an ssh
+session (session 0), Windows OpenSSH 9.5 stops writing its stdout, even without qem, so
+qem picks Git's ssh there. To check Windows OpenSSH itself, run the check in a signed-in
+desktop session, for example as a scheduled task with `schtasks /IT`, or set `QEM_SSH`
+to it and expect the hang.
+
+## Against the live service
+
+The end-to-end check uses real credit. Cap it:
+
+```sh
+qem start --max-duration 30m --max-cost 1
+qem exec -- sw_vers
+qem exec --wait 5 -- sleep 20; qem job <JOB_ID> --wait 60
+qem ssh -- uname -a
+qem sync . && qem sync . && qem exec -- ls   # the second sync sends 0 files
+qem pull ./tmp-pull --from README.md
+qem password --copy
+qem desktop                 # pomona's window opens signed in; closing it ends the command
+qem stop
+```
+
+Record what the service actually returned in [protocol.md](protocol.md).
+
+On Windows, run this in PowerShell (Windows OpenSSH) and in Git Bash (MSYS ssh). In Git
+Bash, set `MSYS_NO_PATHCONV=1` for absolute Mac paths.