docs: update README with current feature set and prerequisites

2026-08-26 15:45:58 +02:00
parent deba9a419d
commit 569777ce8a
2 changed files with 55 additions and 4 deletions
@@ -0,0 +1,51 @@
+# AGENTS.md — decky-vaultwarden
+
+## What this is
+
+Decky Loader plugin for Steam Deck. Provides a Bitwarden/Vaultwarden password manager client in the Decky quick access panel.
+
+**Two-language architecture:**
+- **Python backend** (`main.py`, `bitwarden_client.py`, `crypto.py`, `clipboard.py`, `totp.py`) — crypto, API calls, vault decryption. Loaded by Decky Loader.
+- **TypeScript/React frontend** (`src/`) — UI rendered in Decky panel. Calls Python backend via Decky's `call()` API.
+
+## Build commands
+
+| Command | What it does |
+|---------|-------------|
+| `npm run build` | Rollup compiles TS to `dist/`, then packages everything (dist + Python files + `py_modules/` + plugin.json) into `out/Vaultwarden.zip` |
+| `npm run watch` | Rollup watch mode (frontend only) |
+| `npm run typecheck` | `tsc --noEmit` — type checking, no emit |
+| `npm run bundle-deps` | Downloads Python wheels into `py_modules/` (see below) |
+
+**No test, lint, or formatter commands exist.** No CI workflows.
+
+## Python dependency bundling
+
+`py_modules/` contains pre-compiled manylinux wheels (x86_64) for Python 3.11. These are checked into git.
+
+To regenerate: `npm run bundle-deps` (runs `scripts/bundle-deps.sh`). Downloads wheels from PyPI and extracts them into `py_modules/`.
+
+The bundled packages include: aiohttp, cryptography, argon2, pyotp, cffi, and transitive deps.
+
+## Key entrypoints
+
+- **Plugin entry (Python):** `main.py` — `Plugin` class. All methods here are callable from frontend via `call()`.
+- **Plugin entry (TS):** `src/index.tsx` — `definePlugin()`. Renders `VaultwardenPlugin` component.
+- **API bridge:** `src/api/backend.ts` — `VaultApi` class wraps all `call()` invocations to Python.
+- **State management:** `src/hooks/useVault.ts` — manages vault state machine (logged_out → loading → unlocked, etc).
+
+## Build output
+
+`out/Vaultwarden.zip` is the installable Decky plugin. Created by `npm run build`. Contains:
+- `dist/` (compiled frontend JS)
+- All Python files
+- `py_modules/` (bundled deps)
+- `plugin.json`, `defaults/settings.json`
+
+## Gotchas
+
+- **No `node_modules` rebuild needed for Python changes.** The Python files are copied as-is into the zip.
+- **`py_modules/` is checked into git** with pre-compiled wheels. If you modify Python deps in `requirements.txt`, re-run `npm run bundle-deps` and commit the updated `py_modules/`.
+- **Clipboard has two paths:** Python `clipboard.py` (xclip/xsel with auto-clear) and frontend `navigator.clipboard`. They serve different purposes — don't confuse them.
+- **Target platform:** x86_64 Linux (Steam Deck). Python wheels are platform-specific.
+- **`src/utils/`** exists but is empty.