# 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.