Skip to content

Make the first local run work on any Node.js and stop cleanly on Ctrl+C - #25

Merged
erickkkyt merged 3 commits into
mainfrom
codex/first-run-polish
Oct 23, 2026
Merged

erickkkyt merged 3 commits into
mainfrom
codex/first-run-polish

Conversation

@erickkkyt

Copy link
Copy Markdown
Contributor

Fixes the friction found by a fresh-clone first-run test of the no-login local edition.

Changes

  • Node.js 24 comes with the project. devEngines.runtime makes pnpm download the pinned Node.js 24.22.1, checksummed per platform in the lockfile. Every pnpm local:* command uses it, whatever Node.js the system has. On a fresh clone, pnpm local:doctor installs dependencies first. The README prerequisites are now Git, pnpm 12.4.1 and Chrome.
  • Ctrl+C stops services in order. A terminal's Ctrl+C reached the bundled PostgreSQL directly, and embedded-postgres (via async-exit-hook) stops the database on any SIGINT/SIGTERM it sees. The worker lost its connections mid-shutdown, and pnpm printed ERR_PNPM_RECURSIVE_EXEC_FIRST_FAIL / exit 130. Now:
    • the launcher and its database run in their own process group;
    • the outer process asks them to stop over IPC;
    • the web app and worker run as single direct processes, so the database waits for them;
    • closing the terminal triggers the same ordered stop.
  • First-run guidance.
    • The quick start connects Chrome before adding a website.
    • It explains the extension's debugger and all-sites permissions.
    • It says what to do when another BeatBrowser version is already running.
    • A non-browser request to the workspace now says the app is running.

Checks

  • Lint, type check, pnpm test (11 tasks), script tests (18/18), integration tests (47/47).
  • Fresh clone of this branch on system Node 22 (pnpm local:doctor, local:setup, local:start):
    • the workspace opens without login;
    • a website can be added;
    • Ctrl+C exits 0 with no errors;
    • after a restart the website is still listed.
  • Ctrl+C simulated as a terminal does (SIGINT to the whole foreground group): exit 0, no database errors, the worker logs "Worker stopped", in 3 of 3 runs. SIGHUP (terminal closed) stops every service with no warning.

devEngines.runtime downloads the pinned Node.js 24 into the project, so a
machine with another Node.js version can run every pnpm command; the doctor
and setup errors now point at running through pnpm.
A terminal's Ctrl+C reached the bundled PostgreSQL, and embedded-postgres also
stops it on any SIGINT, so the worker lost its connections mid-shutdown and
pnpm reported exit 130. The launcher now runs in its own process group and is
asked to stop over IPC; the web app and worker run as single direct processes
so the database waits for them. Closing the terminal stops them the same way.
The quick start connects Chrome first, explains the extension's debugger and
all-sites permissions, and says what to do when another BeatBrowser version
is already running. A non-browser request to the workspace now says the app
is running instead of reading like an error.
@erickkkyt
erickkkyt merged commit ad0bbb6 into main Oct 23, 2026
3 checks passed
@erickkkyt
erickkkyt deleted the codex/first-run-polish branch October 23, 2026 11:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant