Kitten

Technical Manual sections

While you work on Kitten, run the installer (./install) and use the kitten command to run what it installed. In your working copy, the installer builds Kitten from source (see How it works), so the kitten command runs your latest changes.

The build script creates the distribution in dist/. (The installer runs it for a development install.) It:

  1. Deletes and recreates dist/, and runs update-version.js, which writes dist/node-version and dist/version.json. version.json contains:

    • date: when the build ran.

    • versionStamp: the same moment in UTC, as a number (e.g., 20261103101500).

    • gitHash: the first six characters of the hash of the latest commit.

    • apiVersion: the major version in package.json.

    • nodeVersion: the version of the Node.js runtime that runs the build (kitten-node).

    • distributionHost: the value of KITTEN_DISTRIBUTION_HOST, or kittens.small-web.org if it isn’t set.

  2. Bundles the three entry points with esbuild: src/entry/main.ts as kitten-bundle.js, src/entry/update-guard.ts as update-guard.js, and src/entry/loader.js as loader-bundle.js. esbuild itself stays external, as the loader needs esbuild’s binary for the platform at run time. The build writes a package.json into the distribution that pins esbuild’s version, and the installer installs it.

  3. Installs the dependencies of the internal web app and copies it into dist/web/.

  4. Bundles src/lib/crypto.ts and src/lib/keyStore.ts for the browser, and copies, minifies, and compresses Kitten’s images and the client-side libraries from lib/ and node_modules/ into dist/web/🐱/.

  5. Copies these into dist/:

    • the launcher (build-templates/kitten)

    • the Kitten Process Manager (build-templates/kitten-process-manager.js)

    • the installer

    • the runtime checksums (build-templates/runtime-checksums)

    • the templates of kitten init (src/cli/commands/init/)

    • kitten-day.sixel

  6. Regenerates CONTRIBUTORS.md in the repository with contributors.js.

src/lib/Version.ts reads version.json at run time and calculates the version’s exactVersion, which the installer uses as the name of the version’s folder in versions/ (see step 3 of How it works).

You can also run the build script on its own and run the result with dist/kitten [path to serve]. Only do this if you have a specific reason to. During everyday development, run the installer.

  1. package runs the installer (which builds and installs the current source) and archives dist/ as packages/kitten-<exact version>.tar.xz. (On macOS, it needs GNU tar, as gtar.)

  2. deploy runs the package script, signs the package with sign-package.js, and checks that the signature verifies against PUBLIC_KEYS. Then it uploads the package, its signature, and the installer to the distribution server (kittens.small-web.org), with the upload token in the Authorization header.

The signing key and the upload token are in small-web.org/kittens/ in your XDG configuration home (~/.config/ by default): signing-key.pem and secret-token.txt. If you have deployment rights for Kitten, the distribution server’s settings page (_https://kittens.small-web.org/settings/_, which requires sign-in) shows the upload token and lets you reset it.

To release to the staging distribution server (staging.kittens.small-web.org) instead, run ./deploy --staging. The deploy script then exports that host as the KITTEN_DISTRIBUTION_HOST environment variable, so the build writes it into version.json. It also uploads an installer that downloads from that host, and reads the upload token from staging.kittens.small-web.org.secret-token.txt. (The deploy script only takes the host from its arguments, never from the environment, and it prints the host before it runs the package script.) Set LOCAL=true to upload to a distribution server on localhost, with the development token in the deploy script.

To create a signing key pair, run kitten-node generate-signing-key.js <name> (generate-signing-key.js). It writes <name>.pem and <name>.pub.pem to the same folder, refuses to overwrite either, and prints the public key. (sign-package.js uses signing-key.pem.)

The KittenPackage.stage() method only accepts packages signed with a key in the PUBLIC_KEYS of the Kitten that runs it (src/lib/packageSignature.ts). This covers automatic updates, the kitten update command, and the kitten deploy command. To move to a new signing key, add its public key to PUBLIC_KEYS and release that version, signed with the old key, before you sign with the new one.

Note that the installer does not check signatures. It downloads the package from the distribution server over HTTPS.

For each release, make a checklist from this one. Take the steps for every release, add the sections below that apply, and then add anything the release itself needs.

For every release, in this order:

  1. Reinstall Kitten from the release branch. In your working copy, switch to the release branch, check that the tree is clean and that no test suite is running, and run ./install. Then check that kitten --version includes the first six characters of the hash of the branch’s latest commit, and run the start-up benchmark (see Testing).

    The build uses the files in your working copy but takes gitHash from the latest commit (see Building), so a clean tree ensures that the hash matches what you install. (Installing also restarts the Kitten servers that are running in development, including those of a test suite.)

  2. Update and test our own apps (e.g., Catalyst and the Kitten site) against this build. Run each app with the installed Kitten and go through its main flows (sign-in, forms, uploads, and live pages). Watch the terminal for errors, warnings, and HTML validation failures. Commit your changes on the branch that the app’s server tracks (see Updates), but don’t push them until you have published the release in step 5.

    This is because a server installs a new head of its tracked branch with the newest Kitten release for the API version that the head declares. A head that you push before you publish runs on the previous release.

  3. Check the documentation against the change log. Check that this manual and the reference cover every change in the unreleased section of CHANGELOG.md.

  4. Set the release date in the change log. Replace the unreleased heading (e.g., ## 2026-10-?? [unreleased - breaking]) with the release date, in the form that released entries use (e.g., ## 2026-11-03). Commit, and push to the release branch.

    The update history in the Settings app links the Kitten version of each confirmed update to CHANGELOG.md at the commit of that version’s build. So the commit you build from must have the release date in the change log, with the section for the release as the first one.

  5. Publish the release with ./deploy (see Releasing). Then check that https://kittens.small-web.org/latest/<API version>/ responds with the new release, i.e., that its compatible.gitHash is the first six characters of the hash of the release branch’s latest commit.

  6. Merge the release branch into main (git switch main, git merge --ff-only <release branch>, and git push), only after you publish.

    This is because Catalyst installs Kitten on new servers with the installer on the default branch (_https://codeberg.org/kitten/app/raw/install_), and that installer downloads the newest package from the distribution server. If you merge first, new servers run the new installer on the previous release’s package, and the installer refuses a package that doesn’t have what it checks for (see step 2 of How it works).

  7. Tell app authors what changed: the breaking changes in the change log, and anything they must change in their apps (e.g., engines.kitten). Tell them to run kitten check before they set the engines.kitten field.

  8. Pick up the follow-ups that you noted during the release.

When the API version changes:

When the update code changes:

The rehearsal changes real machines and a real repository. On the rehearsal server, it replaces Kitten, its update records, and the systemd unit, deploys the test app, and deletes the test app’s earlier deployments and their data. One scenario reboots that server. It force-pushes and deletes main and release in the test repository. On the staging distribution server, the reset deletes all distributions and uploads, and the scenarios upload builds.

When the distribution server changes:

Kitten’s types are in src/types/:

The npm run typecheck script checks the server program and the client program separately (tsconfig.server.json and tsconfig.client.json), as each has its own kitten global. The npm run sync-types script (sync-types.js) regenerates the @small-web/kitten-types package in a types checkout beside the Kitten repository: it emits the declarations of src/types/index.ts with tsconfig.declaration.json, and copies the ambient declaration files.

Source code:

Like this? Fund us!

Small Technology Foundation is a tiny, independent not-for-profit.

We exist in part thanks to patronage by people like you. If you share our vision and want to support our work, please become a patron or donate to us today and help us continue to exist.