bkper-cli: Instructions file for Codex

AGENTS.md - Bkper CLI Development Guide

Overview

Bkper CLI is a command-line client for Bkper (financial accounting platform). The project uses TypeScript, Bun, Mocha for testing, and gts (Google TypeScript Setup) for code style enforcement.

README file

The README.md file is the main documentation for the project, its showed at github and npm, as well as serving as the content for the app listing on the Bkper website and main Dashboard. It should be kept up to date with the latest features and usage instructions, and should be clear and concise for users of all levels. In the high level it should be divided in a session user will see, and an expandable session for developers, more technical, with reference documentation and more detailed instructions. Its a public facing document, so it should be written for a general audience, with a focus on clarity and ease of use.

README restrictions

• NEVER add internal technical or SDLC workflow details to README.md
• NEVER document release labels, release automation, publishing policy, CI/CD flow, branch strategy, or maintainer-only procedures in README.md
• Keep maintainer and contributor workflow details in CONTRIBUTING.md, AGENTS.md, or internal docs instead
• If in doubt, prefer removing internal process detail from README.md rather than adding it

Build Commands

# Full build (clean, compile, copy assets)
bun run build

# Development with TypeScript watch
bun run dev

Note: The CLI builds worker bundles only (bkper app build). Client tooling (Vite) is owned by the app template and configured via vite.config.ts. The template's npm run dev runs both Vite and bkper app dev concurrently, and npm run build runs both vite build and bkper app build.

Test Commands

# Run all tests
bun run test:all

# Run unit tests only
bun run test:unit

# Run integration tests only
bun run test:integration

# Run a single test file (the mocha configs have no spec, so only the given files run)
TS_NODE_TRANSPILE_ONLY=true TS_NODE_PROJECT=tsconfig.test.json npx mocha --config .mocharc.json test/unit/commands/apps/list.test.ts

# Run a single test (grep pattern)
TS_NODE_TRANSPILE_ONLY=true TS_NODE_PROJECT=tsconfig.test.json npx mocha --config .mocharc.json --grep "should return proper" 'test/unit/**/*.test.ts'