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

feat: add native KDBX scaffolding and in-memory KeePass API

Browse Source
This commit is contained in:
MatMoul
2026-05-10 01:17:53 +02:00
parent 210f7b414b
commit 15332896fe
25 changed files with 437 additions and 713 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.memory/project.md
+12 -16
View File
@@ -1,16 +1,14 @@
# Project
## Goal
Provide a TypeScript wrapper around KeePass `.kdbx` databases using a Python bridge powered by `pykeepass`.
Provide a TypeScript library for reading and writing KeePass `.kdbx` databases.
## Architecture
- Public API is TypeScript.
- `src/python/bridge.py` is the runtime backend and uses `pykeepass`.
- TypeScript spawns a Python process per request; there is no persistent worker yet.
- JSON is exchanged over stdin/stdout.
- Bridge errors, empty output, invalid JSON, missing files, and backend exceptions are surfaced as TypeScript errors.
- Bridge error reporting now distinguishes invalid KeePass requests from backend errors.
- Coverage now includes `keyFile` payload propagation, nested group payload shaping, and core API smoke checks.
- The runtime backend is native TypeScript/JavaScript.
- Python is used only as a compatibility reference during development and testing.
- Keep the implementation split between KDBX format handling, domain model mapping, and the public API.
- Read/write support must remain deterministic and easy to validate against `pykeepass`.
## Public API
- `openKeePassDatabase(path, options)`
@@ -29,24 +27,22 @@ Provide a TypeScript wrapper around KeePass `.kdbx` databases using a Python bri
- 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.
- The library should run without Python in production.
- Python may still be required for compatibility tests and fixture generation.
- Prefer Bun for scripts and tests.
## 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, command forwarding, and payload shaping.
- Integration tests in `tests/integration/` use `data.kdbx` to verify entries, groups, partial search, OTP/TOTP output, write persistence on a temporary copy, and nested group creation when `pykeepass` is installed.
- The integration test runner checks for `pykeepass` and skips cleanly when it is unavailable.
- Tests should compare the native implementation against `pykeepass` when available.
- Keep temporary-copy write tests and nested group behavior tests.
- Memory tracking files: `.memory/state.md` and `.memory/todo.md`.
## Main scripts
- `bun run test` / `bun test`
- `bun run src/example.ts`
- `bun run src/test-integration.ts`
- `bun run setup:python`
- Compatibility helpers may be added later if needed.
## Current direction
Keep improving failure-path coverage, keep write support minimal and predictable, and continue validating persistence on temporary copies and nested group behavior.
Implement native KDBX read/write support in TypeScript and validate behavior against `pykeepass` as the reference implementation.