m/ts-pykeepass-wrapper
1
0
Fork 0
Code Issues Actions Wiki Activity

docs: clarify Python bridge runtime and test behavior

Browse Source
This commit is contained in:
MatMoul
2026-05-10 00:06:54 +02:00
parent 9496c07049
commit 89ba04d61a
3 changed files with 63 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.memory/project.md
+47 -20
View File
@@ -1,20 +1,47 @@
{ # Project
"name": "kdbx-lib",
"packageManager": "bun@1.0.0", ## Goal
"version": "0.1.0", Provide a small read-only TypeScript wrapper around KeePass `.kdbx` databases using a Python bridge powered by `pykeepass`.
"private": true,
"type": "module", ## Architecture
"scripts": { - Public API is TypeScript.
"example": "bun run src/example.ts", - `src/python/bridge.py` is the runtime backend and uses `pykeepass`.
"validate": "bun run test", - TypeScript spawns a Python process per request; there is no persistent worker yet.
"test": "bun test", - JSON is exchanged over stdin/stdout.
"test:unit": "bun test", - Bridge errors, empty output, invalid JSON, missing files, and backend exceptions are surfaced as TypeScript errors.
"test:integration": "bun run src/test-integration.ts",
"setup:python": "python3 -m venv .venv && .venv/bin/pip install pykeepass" ## Public API
}, - `openKeePassDatabase(path, options)`
"dependencies": {}, - `KeePassDatabase.listEntries()`
"devDependencies": { - `KeePassDatabase.findEntries(query)`
"typescript": "^5.5.0", - `KeePassDatabase.listGroups()`
"bun-types": "^1.1.0" - `KeePassDatabase.close()` is a no-op.
}
} ## Types
- Entries expose: `title`, `username`, `password`, `url`, `notes`, optional `groupPath`, optional `otp`.
- Groups expose: `name`, `path`.
- Open options support `password` and optional `keyFile`.
- Find queries support partial matching on `title`, `username`, `url`, and `groupPath`.
## Runtime details
- Python path defaults to `.venv/bin/python3`.
- It can be overridden with `PYTHON_PATH`.
- `bun run setup:python` creates `.venv` if needed and installs `pykeepass`.
- The bridge also works with an existing project-local virtual environment.
## Fixtures and tests
- Bundled fixtures: `tests/fixtures/data.kdbx` and `tests/fixtures/empty.kdbx`.
- Companion JSON fixture: `tests/fixtures/data.kdbx.json` stores the password and expected content.
- Unit tests in `tests/unit/` mock the child process and validate bridge parsing/error handling.
- Integration tests in `tests/integration/` use `data.kdbx` to verify entries, groups, partial search, and OTP/TOTP output when `pykeepass` is installed.
- The integration test runner checks for `pykeepass` and skips cleanly when it is unavailable.
## Main scripts
- `bun run test` / `bun test`
- `bun run src/example.ts`
- `bun run src/test-integration.ts`
- `bun run setup:python`
## Current direction
Keep improving failure-path coverage and keep the API minimal unless a concrete need appears.
.memory/state.md
+9 -5
View File
@@ -1,7 +1,7 @@
# State # State
## Current focus ## 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 ## Current API
- `openKeePassDatabase(path, options)` - `openKeePassDatabase(path, options)`
@@ -11,14 +11,18 @@ Read-only TypeScript wrapper around `pykeepass` via a Python JSON bridge.
- `close()` is a no-op - `close()` is a no-op
## Runtime model ## Runtime model
- TypeScript starts the Python bridge - TypeScript spawns Python per request
- Python uses `pykeepass` - Python uses `pykeepass`
- JSON is exchanged over stdin/stdout - 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 ## Current fixture/test status
- Bundled fixtures: `tests/fixtures/data.kdbx` and `tests/fixtures/empty.kdbx` - 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 ## 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.
README.md
+7 -7
View File
@@ -9,14 +9,14 @@ This project uses:
- Python as the runtime backend - Python as the runtime backend
- `pykeepass` to read KeePass databases - `pykeepass` to read KeePass databases
The TypeScript layer launches a Python bridge and exchanges JSON through stdin/stdout. The TypeScript layer launches a Python bridge per request and exchanges JSON through stdin/stdout.
## Requirements ## Requirements
- Node.js or Bun - Node.js or Bun
- Python 3 - Python 3
- `pykeepass` installed in the Python environment used by the bridge (the project provides `bun run setup:python`) - `pykeepass` installed in the Python environment used by the bridge (the project provides `bun run setup:python`)
- The bridge defaults to `.venv/bin/python3` when available, or you can override with `PYTHON_PATH` - The bridge defaults to `.venv/bin/python3`, or you can override with `PYTHON_PATH`
## Python setup ## Python setup
@@ -32,7 +32,7 @@ If you prefer manual installation:
python3 -m venv .venv && .venv/bin/pip install pykeepass python3 -m venv .venv && .venv/bin/pip install pykeepass
``` ```
The bridge also works with a project-local virtual environment such as `.venv` and the tests will use it when present. The bridge also works with a project-local virtual environment such as `.venv`.
## Usage ## Usage
@@ -62,7 +62,7 @@ bun run src/example.ts
Creates a database wrapper. Creates a database wrapper.
#### Options #### Options
- `password`: KeePass master password, read from the fixture JSON in examples/tests when applicable - `password`: KeePass master password
- `keyFile`: optional key file path - `keyFile`: optional key file path
### `listEntries()` ### `listEntries()`
@@ -81,7 +81,7 @@ No-op for now.
- The bridge currently launches a Python process per call. - The bridge currently launches a Python process per call.
- This is simple and robust for a first version. - This is simple and robust for a first version.
- Errors from the Python bridge are propagated to the TypeScript API with the bridge exit code when available. - Errors from the Python bridge are propagated to the TypeScript API, including invalid or empty output.
- A persistent Python process can be added later if needed. - A persistent Python process can be added later if needed.
- Bundled fixtures include `tests/fixtures/data.kdbx` and `tests/fixtures/empty.kdbx`; their companion JSON files store the password and expected content for tests/examples. - Bundled fixtures include `tests/fixtures/data.kdbx` and `tests/fixtures/empty.kdbx`; the companion JSON file stores the password and expected content for tests/examples.
- Integration tests validate the bundled `data.kdbx` entry-by-entry and group-by-group against `tests/fixtures/data.kdbx.json`. - Integration tests validate the bundled `data.kdbx` entry-by-entry and group-by-group against `tests/fixtures/data.kdbx.json`, and may skip cleanly when `pykeepass` is unavailable.