Versions and verification

This page explains how Firenook’s releases are numbered and tagged, how to install one on purpose, and how to check the package and the engine you have.

Releases

The current release is 0.2.0, the first for public use. Before it came the previews, 0.2.0-next.1 to 0.2.0-next.8. Each release is listed, with what it changed and what it passed, on the releases page and in the changelog.

Releases before the rename were published as @fireside-dev/cli, up to 0.1.0-next.9; see former name. firenook@0.0.0 only held the name before the first release and contains no emulator.

Channels

npm has two tags for Firenook. latest is the release to install, 0.2.0 today; npm install firenook and a bare npx firenook get it on any Node from 20 up. next carries previews, which keep their own -next versions. npm view firenook dist-tags shows where each tag points.

Install and upgrade

Install Firenook in your project and commit the lockfile, so every machine and every CI run gets the same release until you upgrade:

npm install --save-dev firenook

npm records it as ^0.2.0: an update can take a later 0.2 release, never 0.3 or a preview. To install one release in particular, name it, as in npm install --save-dev firenook@0.2.0.

Firenook never upgrades itself. In a terminal, it asks the npm registry for the version tags at most once a day, in the background, and the next start shows a newer release on your channel with the install command for your package manager. The check is off in CI, in the plain output, and with FIRENOOK_NO_UPDATE_CHECK=1 or NO_UPDATE_NOTIFIER=1.

To upgrade, stop the emulators first, then install the new release with npm install --save-dev firenook@latest. Never replace the package while the emulators run. Saved data stays where it is, and each release’s notes say whether it changes how data is stored.

Data between releases

Data kept with --keep-data moves between 0.2.0 and the last preview in both directions:

• The first 0.2.0 start of data an earlier release saved builds the ordered field index once, with one read of every document: 7.4 s for 211,202 documents and 49 s for 2.7 million on the benchmark server. Every start after that opens the data at once.
• 0.2.0-next.8 opens data 0.2.0 saved, and rebuilds its own index the same way on its first start.

The plain log says when the index is built:

firenook: indexed the top-level fields of 1000 Firestore documents in 0.0 s

What you installed

The firenook package is a small launcher. The engine, the native program that serves the emulators, comes in a second package for your platform, such as @firenook/cli-darwin-arm64. Both carry the same version, and the engine is built from one exact commit of the engine repository. --version prints both:

$ npx firenook --version
0.2.0 (engine source 7a9614bea49f8208f96d2126b29ef11ee2f2810b)

The launcher records the engine it expects in release.json:

node_modules/firenook/release.json

{
  "engineRevision": "7a9614bea49f8208f96d2126b29ef11ee2f2810b",
  "rustToolchain": "1.98.0",
  "platforms": {
    "darwin-arm64": "aarch64-apple-darwin",
    "darwin-x64": "x86_64-apple-darwin",
    "linux-x64": "x86_64-unknown-linux-gnu",
    "linux-arm64": "aarch64-unknown-linux-gnu",
    "win32-x64": "x86_64-pc-windows-msvc"
  }
}

The platform package carries a receipt with the SHA-256 of its binary, here cut short:

node_modules/@firenook/cli-darwin-arm64/receipt.json

{
  "version": "0.2.0",
  "platform": "darwin-arm64",
  "target": "aarch64-apple-darwin",
  "engineRevision": "7a9614bea49f8208f96d2126b29ef11ee2f2810b",
  "sha256": "…"
}

Check the engine with binary-path

Before every start, the launcher checks that the platform package matches it: the package name and version, the receipt’s engine revision, platform and target, and the binary’s SHA-256. binary-path runs the same check and prints where the binary is:

$ npx firenook binary-path
~/demo-shop/node_modules/@firenook/cli-darwin-arm64/bin/firenook

When something does not match, it refuses, and so does every command that starts the engine:

Firenook platform package identity mismatch; reinstall the pinned CLI and its optional dependencies.
Firenook binary checksum mismatch; refusing execution.

Tools can run the same check from code: import { binaryPath } from 'firenook/binary'.

Provenance and signatures

Releases are published from the engine repository’s GitHub Actions, with npm provenance. npm can check the registry signatures and the provenance attestations of what you installed:

$ npm audit signatures
audited 2 packages in 0s

2 packages have verified registry signatures

2 packages have verified attestations

The receipts above are integrity checks between the launcher and the engine. They do not replace npm’s provenance or your lockfile.

What a release has passed

Each release on GitHub, tagged npm-v0.2.0 and so on, names its engine revision and the CI runs it passed, and carries:

• the published tarballs, the launcher’s and each platform’s;
• a manifest per platform with each tarball’s SHA-256 and npm integrity;
• the results of installing the packed packages with npm and with Bun, and of running the whole suite from them, on all five platforms;
• release-source.json, which names the build and publication run.

You can compare what npm serves with the manifest. npm pack downloads the tarball, and its SHA-256 must match the manifest’s:

npm pack firenook@0.2.0
shasum -a 256 firenook-0.2.0.tgz

A platform is supported for a release only when that release’s run passed on it. Behaviour is pinned to recordings of the official emulator that every change replays. The performance figures come from a recorded run whose record is linked from benchmarks.

Next

Moving from the packages published as Fireside? See former name.