Contributing to TallyUI

Local setup

TallyUI uses RxDB Premium (ADR-031, ADR-044). The rxdb-premium package's install script downloads and decrypts the licensed plugins, so pnpm install needs a licence token. Without one, the install fails.

Never publish the decrypted plugins. This repo is public, and its Actions caches and artifacts can be read from fork PRs. So:

• CI never caches the pnpm store or node_modules;
• sideEffectsCache stays false in pnpm-workspace.yaml, and CI checks it;
• CI uploads no build output, trace or HTML report that could contain the worker bundle.

1. Put the token in your environment before installing. The installer reads the RXDB_PREMIUM environment variable:

   export RXDB_PREMIUM=<token>

   On the agent host (the Mac mini), the token is in the keychain:

   export RXDB_PREMIUM="$(security find-generic-password -s rxdb-premium -w)"

   Alternatively, put RXDB_PREMIUM=<token> in a .env file at the repo root. .env is git-ignored, and the installer searches parent directories for it. Never write the token to a committed file, and never use package.json accessTokens.

2. Install and build:

   pnpm install --frozen-lockfile
   pnpm build

3. Run the tests with at most two workers:

   pnpm vitest run --maxWorkers=2

   The Playwright e2e suite (pnpm test:e2e:web) starts its web servers on ports derived from the worktree's path, so two worktrees never test each other's servers; node e2e/ports.ts prints them. E2E_WEB_PORT and E2E_SQLITE_PORT override them, and E2E_REUSE=1 reuses a server already running on those ports. Without E2E_REUSE=1, a port that is already taken fails the run before any test, naming the process that holds it: stop that process, or set E2E_REUSE=1 to test its server. Then, before the first test, the server-identity setup project fails the run unless each server's process was started from this worktree (skipped under CI and with E2E_REUSE=1). CI keeps 8081 and 8090.

The installer prints the token in its output. Don't paste install logs anywhere public.

Lint

pnpm lint runs apps/web's Next lint through turbo and the shared config over packages/ and connectors/ (pnpm lint:code). New violations fail; existing ones are listed per file in eslint-suppressions.json. After fixing grandfathered violations, run pnpm lint:code --prune-suppressions and commit the smaller file. Never add new entries with --suppress-all to get a PR through.

pnpm knip reports unused files, exports, dependencies and binaries; new ones fail. Known dead code is listed in knip.jsonc under baseline comments; remove an entry when its code is fixed. Never add an ignore just to get a PR through: a new permanent ignore needs a one-line reason comment.

Versions

rxdb and rxdb-premium are pinned to the same exact version (currently 17.5.0; ADR-031). Upgrade them together, in one PR.

Releasing

See RELEASING.md.