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

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.