ts-pykeepass-wrapper/.memory/project.md

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.