fiscalm
GitHub
Pe această pagină

Development

Verified development host: Linux/amd64. WSL2 and other hosts have not been verified by this release audit. Prerequisites: Linux, Bash 4.3+, Git, Python 3.11+, uv, Node.js 22 and npm. setsid comes from util-linux. Java 17+ is optional for the official invoice-validator tests; those checks skip when the validator artifacts are absent. All examples use invented firms. Never point development at an installation's data or secrets.

Clean clone, fixtures and hot reload

git clone https://github.com/GeorgeFL7/fiscalm.git
cd fiscalm
git switch dev
bin/dev fixtures

The public clone above is available only after publication. Until then, authorized evaluators clone GeorgeFL7/finance-recon and select contahub/dev instead. Likewise use origin/contahub/dev for changed-test selection and PR targets in the private preparation repository. bin/dev installs locked Python and app dependencies, generates fixtures and starts Next.js at http://localhost:3000. Use localhost, not 127.0.0.1. Edit app/src/ and the page reloads. Reads come from synthetic JSON; actions simulate answers without changing the engine. Ctrl-C stops the processes and removes the temporary data directory.

App with a local engine, in shadow

From the same clone:

bin/dev engine

Open https://localhost:3000 and accept the temporary localhost certificate for this session. A loopback HTTPS proxy sends app assets to Next.js on 3001 and /web/ and /auth/ requests to the real engine on 8765. It pins the Host and replaces all forwarded headers itself; the browser cookie keeps its Secure and __Host- protections. The launcher prints a one-time setup link for the first administrator. No account or session is accepted through a path token.

There are two invented firms and an empty document ledger. App edits reload immediately; the engine restarts after Python edits under src/finrec/. Temporary FINREC_HOME, FINREC_SECRETS, backups and the one-day localhost certificate stay under ~/scratch/fiscalm-dev.*; no installation credentials or LIVE marker are used. Ctrl-C stops all three process groups and discards the temporary data. Ports 3000, 3001 and 8765 must be free; stop only processes started for this session. openssl is required for the temporary certificate.

Shadow mode allows local work and refuses outward effects, including usable payment files. Do not add a LIVE marker for development. The trusted proxy is loopback-only and belongs to this temporary engine; do not expose it or copy its setting to a deployment.

Checks

After bin/dev has installed dependencies, from the repository root:

nice -n 10 env FINREC_TEST_WORKERS=2 bin/test.sh full
nice -n 10 env FINREC_TEST_WORKERS=2 bin/test.sh quick
cd app
nice -n 10 npm run lint
nice -n 10 npm run typecheck
nice -n 10 npm test -- --maxWorkers=2
nice -n 10 npm run build

full runs the public engine suite (and private tests when present) and records the impact map. quick selects affected tests and checks changed Python with Ruff; without a map it runs everything. Always run full on the final head before merging. For the app while editing, nice -n 10 npx vitest run --changed origin/dev --maxWorkers=2 selects affected tests. See testing for test design and the release scan. Shared machines use at most two test workers; do not run heavy suites and builds concurrently.

Where a change goes

  • src/finrec/: engine rules and storage. Use the existing product area: bank/, commerce/, settlements/, invoicing/, efactura/, mail/ or payments/.
  • src/finrec/api/: app/public API projections, actions and HTTP transport. Generate docs/openapi.json from api.schema.openapi() when the contract changes.
  • app/src/: rendering and interaction. Business decisions stay in the engine. Formatting lives in app/src/lib/format.ts.
  • tests/ and app/test/: synthetic fixtures and behaviour tests. Never commit generated app fixtures or real company data.
  • bin/ and deploy/: local tools and installation. Runtime data stays outside the clone.

The code and Romanian copy rules are in AGENTS.md; the app-specific guide is app/README.md. New user-facing wording needs maintainer approval. Keep API field descriptions in the generator, not a second field reference.

First PR

Read CONTRIBUTING.md and CLA.md, pick a small issue, branch from dev, and change one behaviour with its relevant test. Run the checks above, open a draft PR targeting dev, and include results and proposed wording. UI changes include before/after screenshots at about 390 and 1280 px with synthetic data. Sign the CLA with the approved comment when prompted; address blocking review findings before marking ready.