49 lines
2.0 KiB
Markdown
49 lines
2.0 KiB
Markdown
# Project
|
|
|
|
## Goal
|
|
Provide a TypeScript library for reading and writing KeePass `.kdbx` databases.
|
|
|
|
## Architecture
|
|
- Public API is TypeScript.
|
|
- 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)`
|
|
- `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
|
|
- 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.
|
|
- 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`
|
|
- Compatibility helpers may be added later if needed.
|
|
|
|
## Current direction
|
|
Implement native KDBX read/write support in TypeScript and validate behavior against `pykeepass` as the reference implementation.
|