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.

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.

• 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

# 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.

# 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
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_PROJECT=tsconfig.test.json npx mocha --config .mocharc.json --grep "should return proper" test/unit/**/*.test.ts

• Extends Google TypeScript Setup (gts/tsconfig-google.json)
• Strict mode enabled (strict: true)
• ESM modules ("type": "module")
• Target: ES2015, Module: ESNext
• Declaration files generated (.d.ts and .d.ts.map)

// Standard import style
import { something } from './local-module.js';
import { namedExport } from 'external-package';

// Default import
import program from 'commander';

// Side-effect import (when needed)
import './some-module.js';

// Use .js extension in imports for ESM compatibility

• Interfaces: PascalCase (e.g., GetBookParams, GroupNode)
• Functions: camelCase (e.g., buildHierarchicalStructure)
• Variables: camelCase (e.g., rootGroups)
• Constants: SCREAMING_SNAKE_CASE for config constants, camelCase for others
• Files: kebab-case.ts (e.g., local-auth-service.ts)
• Classes: PascalCase (e.g., TransactionMergeOperation)

• NEVER use as any - Use proper types or unknown with type guards
• Use interfaces for object shapes, types for unions/primitives
• Enable strict null checks - check for undefined/null before access
• Use async/await for all asynchronous operations

// CLI command error pattern
try {
    await someOperation();
} catch (err) {
    console.error('Error doing operation:', err);
    process.exit(1);
}

• Source files: src/ directory
• Tests: test/unit/ and test/integration/ directories
• Build output: lib/ directory
• Domain logic: src/domain/ for reusable business logic
• Use named exports for functions that will be imported
• Group related functionality in dedicated directories

• Use Mocha with Chai (expect from 'chai')
• Test files mirror source structure: test/unit/commands/apps/list.test.ts for src/commands/apps/list.ts
• Helper utilities in test/unit/helpers/
• Mock data fixtures in test/unit/fixtures/
• Use setupTestEnvironment() and getTestPaths(import.meta.url) in tests

src/
├── auth/           # Authentication services
├── commands/       # CLI command implementations
│   └── auth/       # Auth commands (login, logout, token)
├── domain/         # Domain-specific operations (reusable business logic)
│   └── transaction/ # Transaction merge operation
├── render/         # Output formatting (table, key-value, JSON)
└── cli.ts          # Main CLI entry point

1. Add command to src/cli.ts
2. Implement logic in src/commands/
3. Add tests in test/unit/commands/
4. Run bun run build to compile

These rules are mandatory for coding agents working on this repository.

• Start from latest main and use a short-lived feature branch.
• Keep PRs small, scoped, and single-purpose.
• Do not bundle unrelated refactors with feature/fix work.

Releases are published by GitHub Actions (Trusted Publisher with OIDC), not from local machines.

• Merge work into main normally; release timing is decoupled from PRs.
• When ready to release from a clean, up-to-date main, run one of:
  • bun run release:patch
  • bun run release:minor
  • bun run release:major
• Push the resulting commit and tag with git push origin main --follow-tags
• CI publishes only from version tags matching v*.*.*

• Dependabot tracks @mariozechner/pi-coding-agent.
• Pi update PRs stay standard dependency PRs and can be auto-merged if checks pass.
• Do not add release labels or version bumps on Dependabot PR branches.

Before requesting merge, always run:

bun run build
bun run test:unit

• Never publish manually from local environment unless explicitly instructed.
• Publishing is performed by CI on version tag pushes, with Trusted Publisher (OIDC).
• If publish fails, fix root cause and re-run through the tag-based release flow; do not bypass with ad-hoc changes.