Distribution and updates

End users receive a standalone platform artifact — one self-contained executable. They do not need Node.js, npm, GitHub credentials, administrator privileges, or source-repository access. This page is the topology overview; Releasing tv is the operator runbook, Install tv is the end-user install page, and Trust boundaries owns the exact Ed25519 mechanism.

Implementation status: implemented and tested end-to-end (#12) — build, sign, manifest, publish, and the client verify/activate/rollback engine all exist. What has not happened is the one-time operator setup (creating the releases repository, generating the production key, cutting a first tag) that makes a release actually downloadable — see Current state.

Release topology

flowchart LR
    Tag[git tag v*] --> CI[GitHub Actions release.yml]
    CI --> Build[bun build --compile per platform]
    Build --> MacSign[macos-sign.mjs: Developer ID codesign]
    MacSign --> Manifest[sign-and-manifest.mjs: SHA256SUMS + Ed25519 manifest]
    Manifest --> Publish[publish.mjs: gh release, immutable per version]
    Publish --> ReleasesRepo[(thalixinc/thalix-vault-releases, source-free)]
    ReleasesRepo --> Updater[tv update / tv update --rollback]
    ReleasesRepo --> Site[Lovable /cli/install page]

The target matrix is macOS arm64, Linux x64, and Windows x64, built with Bun's bun build --compile --target=bun-<platform> cross-compilation from a single host, then smoke-tested on each artifact's own OS by the CI build matrix.

Trust model

See Trust boundaries for the authoritative mechanism. In summary: the CLI embeds the Ed25519 public verification key directly in source (never fetched at runtime); the signed manifest carries schema version, channel, CLI version, minimum supported version, publication time, release-notes URL, and each platform artifact's URL, size, and SHA-256; tv update verifies signature, platform, size, checksum, and rejects any downgrade before ever activating a new version. A published stable tag is immutable — see Failed release and rollback for what that means when a release turns out to be bad.

Installation

Installation is a single file, not a versioned-directory scheme: download the platform binary, chmod +x, and place it on PATH yourself (/usr/local/bin in the documented examples). There is no separate installer script or package-manager integration in MVP — see Install tv for the exact per-platform commands, checksum verification, and the current macOS-notarization/Windows-signing caveats.

Atomic updates

tv update [--json]
tv update --rollback [--json]

A standalone install's update fetches the current channel's signed manifest, verifies it fully, and atomically swaps in a newer version if one exists (already-up-to-date otherwise) — interruption, an invalid signature, a size/checksum mismatch, an unsupported platform, or a failed post-activation health check all leave the currently active version fully intact. Exactly one prior version is retained; --rollback restores it and re-verifies it boots correctly. tv update check is a read-only availability check: it reports whether a newer version is available without downloading or replacing any bytes. See Command reference.

A private-Git checkout install's tv update is a different, simpler operation entirely — a plain git pull --ff-only against its configured upstream, with no retained version and no rollback. See Install and update from a private Git checkout.

Hosting boundary

thalixinc/thalix-vault-releases is the artifact source of truth: a separate, source-free public repository, so a standalone install (or a compromise of the distribution channel) never exposes application source. TV_RELEASES_REPO controls which repository the CLI's own update engine and every release script target. The Lovable-hosted /cli/install page links to that repository's releases; it is not itself the artifact registry.