matmoul
5fa30414d7
Distinguish invalid KeePass requests from backend failures in the Python bridge, improve nested group path resolution, and add coverage for nested group creation plus payload forwarding.
53 lines
2.5 KiB
Markdown
53 lines
2.5 KiB
Markdown
# Project
|
|
|
|
## Goal
|
|
Provide a 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.
|
|
- 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.
|
|
|
|
## Public API
|
|
- `openKeePassDatabase(path, options)`
|
|
- `KeePassDatabase.listEntries()`
|
|
- `KeePassDatabase.findEntries(query)`
|
|
- `KeePassDatabase.listGroups()`
|
|
- `KeePassDatabase.createEntry(entry)`
|
|
- `KeePassDatabase.createGroup(group)`
|
|
- `KeePassDatabase.save()`
|
|
- `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, 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.
|
|
- 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`
|
|
|
|
## Current direction
|
|
Keep improving failure-path coverage, keep write support minimal and predictable, and continue validating persistence on temporary copies and nested group behavior.
|