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

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.