docs: clarify Python bridge runtime and test behavior

This commit is contained in:
2026-05-10 00:06:54 +02:00
parent 9496c07049
commit 89ba04d61a
3 changed files with 63 additions and 32 deletions
+9 -5
View File
@@ -1,7 +1,7 @@
# State
## Current focus
Read-only TypeScript wrapper around `pykeepass` via a Python JSON bridge.
Read-only TypeScript wrapper around KeePass `.kdbx` databases through a Python JSON bridge.
## Current API
- `openKeePassDatabase(path, options)`
@@ -11,14 +11,18 @@ Read-only TypeScript wrapper around `pykeepass` via a Python JSON bridge.
- `close()` is a no-op
## Runtime model
- TypeScript starts the Python bridge
- TypeScript spawns Python per request
- Python uses `pykeepass`
- JSON is exchanged over stdin/stdout
- Bridge errors and empty/invalid JSON are surfaced to TypeScript
- Errors from the bridge, missing files, invalid JSON, and backend exceptions are surfaced to TypeScript
- Python defaults to `.venv/bin/python3`, overridable with `PYTHON_PATH`
## Current fixture/test status
- Bundled fixtures: `tests/fixtures/data.kdbx` and `tests/fixtures/empty.kdbx`
- Integration tests validate entries, groups, and OTP/TOTP output for `data.kdbx`
- `tests/fixtures/data.kdbx.json` stores the password and expected tree/content
- Unit tests mock `node:child_process.spawn`
- Integration tests validate entries, groups, partial search, and OTP/TOTP output for `data.kdbx`
- Integration tests skip when `pykeepass` is unavailable
## Next step
Keep tightening failure-path coverage and improve the API shape only if needed.
Keep tightening failure-path coverage and keep the API minimal unless a concrete need appears.