52 lines
2.6 KiB
Markdown
52 lines
2.6 KiB
Markdown
# 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.
|