52 lines
2.4 KiB
Markdown
52 lines
2.4 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.
|
|
- Coverage now includes `keyFile` payload propagation 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, and basic write persistence on a temporary copy 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.
|