Initial commit

.memory/project.md

@@ -0,0 +1,58 @@
+# kdbx-lib
+
+TypeScript wrapper around `pykeepass` for read-only access to KeePass `.kdbx` files.
+
+## Architecture
+
+- Public API: TypeScript
+- Runtime backend: Python 3
+- Bridge: `src/python/bridge.py`
+- Transport: JSON over stdin/stdout
+- Backend library: `pykeepass`
+
+## Requirements
+
+- Node.js or Bun
+- Python 3
+- `pykeepass` installed in the Python environment used by the bridge
+- A project-local `.venv` works well
+
+## Python setup
+
+Install dependencies with:
+
+```bash
+bun run setup:python
+```
+
+Manual alternative:
+
+```bash
+python3 -m pip install pykeepass
+```
+
+## Core behavior
+
+- Read-only library; it does not modify databases.
+- `openKeePassDatabase(path, options)` opens a database through the Python bridge.
+- `listEntries()` returns all entry fields exposed by the bridge: `title`, `username`, `password`, `url`, `notes`, `groupPath`, and `otp` when present.
+- `findEntries(query)` performs partial matching and returns full entries.
+- `listGroups()` returns group names and paths.
+- `close()` is currently a no-op.
+
+## Fixture facts
+
+- Bundled fixtures: `tests/fixtures/data.kdbx` and `tests/fixtures/empty.kdbx`
+- Fixture passwords and expected content live in companion JSON files
+- `data.kdbx` contains four entries: `root`, `otp1`, `f1-item1`, `f2-item1`
+- The fixture tree is `Racine/ -> root, otp1, Folder1/ -> f1-item1, Folder2/ -> f2-item1`
+- Integration tests cover entries, groups, and the `otp1` OTP/TOTP value
+- Canonical OTP value is the full `otpauth://...` URI returned by `pykeepass`
+
+## Notes
+
+- The bridge currently launches a Python process per call; simple but expensive.
+- Errors from the bridge are propagated to TypeScript, including exit code when available.
+- The API is still flatter than the real KeePass model.
+- More failure-path tests are needed.
+- Future improvement: a persistent Python process if performance becomes important.