Development

Install Node.js 24 or newer, then run npm ci. The compiler and every tool are installed into the checkout: npx tsc --version reports the TypeScript version in use.

Command Purpose
npm run dev -- [options] Run Circle from the TypeScript source.
npm run typecheck Strict type check, no output files.
npm test The test suite, with Node’s test runner through tsx. On CI a failing run goes once more with only its failed tests (--test-rerun-failures); a test that passes only then does not fail the check, but is named as flaky: a flaky test warning for each of the first ten (GitHub shows them as annotations) and a table of all of them in the job summary. npm --prefix apps/desktop run test:runtime does the same for each stage and also lists them in the stage receipt.
npm run test:coverage The suite with Node’s coverage of src/; the table at the end of the log gives line, branch and function coverage per file. Pull requests run it in the coverage job of the Check workflow, which writes a summary and is not a required check.
npm run build Empty dist/, compile into it and copy the prompts and data files.
npm run check Type check, tests and build.
npm run format Format the TypeScript sources and the root JSON files with prettier.
npm run format:check Check the formatting, as CI does.
npm run release -- X.Y.Z Set the version and date the changelog. See Releasing.
npm run release:build Build the package with its own Node.js for the current platform.
npm run release:smoke Install, relocate and upgrade that package in a scratch home, install it to the default location there, reject a bad checksum, and run a real tool turn.

Use a scratch CIRCLE_HOME for every test and every interactive run. The tests create their own folders, local model gateways and fake credentials; they never need a model account or the network.

Every change in behaviour needs a test that shows it: the next model request, the stored history, files and processes. Text on screen alone does not show that the runtime is right. Do not weaken a failing test to get green.

A pull request runs npm run check on Linux and Windows and the format check on Linux, builds and smoke-tests the Linux package, and packages and starts the desktop application on Linux and Windows (.github/workflows/check.yml, apps/desktop/test/launch-smoke.mjs); the merge queue runs the check and the launch on Linux, Apple silicon macOS and Windows on the commit that becomes main, and merges once all six pass. That is the merge gate. On Linux the check job also writes the slowest test files to the run’s summary and keeps the suite’s junit report for two weeks. In the check jobs of check.yml, npm ci has 10 and the suite 15 of the job’s 20 minutes, so a step that stalls fails while the job still ends and keeps its log; when one fails or is cancelled, what the suite printed is kept for two weeks as test-output-<system>. A draft pull request runs no CI until it is marked ready. Pull requests run no macOS jobs at all: the organization has five macOS runners, shared with main and releases. Every push to main builds and smoke-tests the release packages on all six targets and packages and starts the desktop application on its four (.github/workflows/release.yml); it runs the whole check again only on the three targets the merge queue did not (Arm Linux, Intel macOS and Arm Windows), and the format check once. A push to main that changes the application (apps/, src/, the root package.json or package-lock.json) runs the desktop tests and journeys on Linux and both macOS architectures, in development and packaged, and on Windows (.github/workflows/workbench.yml); the release workflow leaves those to it on main and adds only the workbench tests and test:live on the Windows package. Each commit of main gets runs of its own in both workflows: a later push neither cancels nor replaces them. The desktop journeys also run on a pull request that changes the application; they do not gate the merge. A pull request runs the release workflow only when it changes the installers, the release scripts or the version, and then without its macOS targets. A tag’s run verifies the packages it publishes and does not test the code again (Releasing). A job that is configured is not a result: look at the run.

The English guides and reference in this folder are published at https://circle-platforms.github.io/circle/. .github/workflows/pages.yml builds the site. The TUI contract is in Chinese, and the desktop working notes are under docs/workbench/; both stay in the repository and are not pages on the site. Contributing, the security policy, the changelog, the design specifications index and the open-source readiness record stay in the repository too.

More: