From 89ba04d61afe69db5859c6d07da31b1979679af4 Mon Sep 17 00:00:00 2001 From: MatMoul Date: Sun, 10 May 2026 00:06:54 +0200 Subject: [PATCH] docs: clarify Python bridge runtime and test behavior --- .memory/project.md | 67 ++++++++++++++++++++++++++++++++-------------- .memory/state.md | 14 ++++++---- README.md | 14 +++++----- 3 files changed, 63 insertions(+), 32 deletions(-) diff --git a/.memory/project.md b/.memory/project.md index be385a0..030aaef 100644 --- a/.memory/project.md +++ b/.memory/project.md @@ -1,20 +1,47 @@ -{ - "name": "kdbx-lib", - "packageManager": "bun@1.0.0", - "version": "0.1.0", - "private": true, - "type": "module", - "scripts": { - "example": "bun run src/example.ts", - "validate": "bun run test", - "test": "bun test", - "test:unit": "bun test", - "test:integration": "bun run src/test-integration.ts", - "setup:python": "python3 -m venv .venv && .venv/bin/pip install pykeepass" - }, - "dependencies": {}, - "devDependencies": { - "typescript": "^5.5.0", - "bun-types": "^1.1.0" - } -} +# Project + +## Goal +Provide a small read-only TypeScript wrapper around KeePass `.kdbx` databases using a Python bridge powered by `pykeepass`. + +## 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. + +## Public API +- `openKeePassDatabase(path, options)` +- `KeePassDatabase.listEntries()` +- `KeePassDatabase.findEntries(query)` +- `KeePassDatabase.listGroups()` +- `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. + diff --git a/.memory/state.md b/.memory/state.md index 9307470..da7d6cc 100644 --- a/.memory/state.md +++ b/.memory/state.md @@ -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. diff --git a/README.md b/README.md index 5981297..7001819 100644 --- a/README.md +++ b/README.md @@ -9,14 +9,14 @@ This project uses: - Python as the runtime backend - `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 - Node.js or Bun - Python 3 - `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 @@ -32,7 +32,7 @@ If you prefer manual installation: 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 @@ -62,7 +62,7 @@ bun run src/example.ts Creates a database wrapper. #### Options -- `password`: KeePass master password, read from the fixture JSON in examples/tests when applicable +- `password`: KeePass master password - `keyFile`: optional key file path ### `listEntries()` @@ -81,7 +81,7 @@ No-op for now. - The bridge currently launches a Python process per call. - 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. -- 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. -- Integration tests validate the bundled `data.kdbx` entry-by-entry and group-by-group against `tests/fixtures/data.kdbx.json`. +- 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`, and may skip cleanly when `pykeepass` is unavailable.