Building from source

Building from source

Useful if you would rather not run an unsigned binary, want to contribute, or need to build for a platform CI does not cover.

---

Prerequisites

• Node.js 22 or newer
• Docker Desktop, running
• git

Clone and install

git clone https://github.com/PKrunal26/openfoam-studio.git

cd openfoam-studio && npm install

Run in development

npm run dev

Starts the Vite dev server and Electron together, with the renderer hot-reloading and the backend running from TypeScript sources.

Build an installer

npm run build:mac

npm run build:win

Installers land in dist/releases/. Note that asar is disabled, so each unpacked app bundle is around 520 MB — a macOS build covering both architectures needs roughly 5 GB of free disk while it works.

---

Tests

The suites are stage-gated: run them in order and stop at the first failure. A later stage passing means nothing if an earlier one is broken.

npm run test:stage0

Command	What it covers	Time	Needs Docker
test:stage0	Docker and OpenFOAM environment	~5 min	yes
test:stage1	File generation	~10 s	no
test:stage2	Mesh quality	~60 s	yes
test:stage3	Solver execution	~3 min	yes
test:stage4	Ghia benchmark physics validation	~8 min	yes
test:stage5	Conversation and error recovery	varies	yes
test:unit	All unit tests — agent, post-processing, paths, health, renderer	~2 s	no

For a quick check while developing, npm run test:unit and npm run typecheck:renderer need neither Docker nor an API key.

Stage 4 is the physics gate: the lid-driven cavity velocity profile must match Ghia et al. (1982) within tolerance. If that fails, the app produces plausible-looking wrong answers, which is the worst possible outcome for a CFD tool.

---

Layout

Path	Contents
core/	Agent loop, tools, knowledge index, file generation, Docker runner, error recovery
demo/server.ts	Local HTTP + SSE server, port 3456
demo/electron-main.cjs	Electron entry point
renderer/	React + Vite UI
wiki/	CFD knowledge base, bundled into the app
tests/	Staged suites

core/ is pure Node and never imports Electron. renderer/ talks to the server over HTTP/SSE and never touches the filesystem or Docker directly.

---

Contributing

Read CONTRIBUTING.md first. House rules that will come up in review:

• path.join() always — never string concatenation for paths
• LF line endings for every OpenFOAM file, enforced in the writer
• All Docker commands through the allowlist in core/docker/CommandRunner.ts
• No raw shell access exposed to the agent, ever
• Tests before implementation. The staged suites exist because a CFD tool that silently produces wrong physics is worse than one that crashes.

Anything the app reads from the repo at runtime — the wiki/ knowledge base, the optional docs cache — must be listed in the electron-builder files globs, resolved through resolveAppRoot() rather than fixed ../.. hops, and present in both release workflows' path filters. Miss any of the three and packaged builds silently ship without it.

Issues and pull requests: github.com/PKrunal26/openfoam-studio