Skip to content

Workflow & Checks

Branch Purpose
main Released code (Stable updater channel). Updated only via release pull requests from dev.
dev Integration branch (Nightly updater channel). All feature and fix PRs branch from and target dev.
<area>/<topic> Feature or fix branches (for example networks/signal, ui/inbox, docs/starlight).
  • Never commit directly to main or dev.
  • Stack dependent work on its prerequisite branch and target that branch until it merges.
  • Every pull request requires passing checks and an independent review.

Give each branch its own worktree under .worktrees/ (gitignored) so multiple branches can run simultaneously:

Terminal window
git fetch origin
git worktree add -b networks/signal .worktrees/signal origin/dev
cd .worktrees/signal
pnpm install && pnpm dev --setup

Remove the worktree once its PR merges:

Terminal window
git worktree remove .worktrees/signal

Run the full check suite from the repository root before opening a pull request:

Terminal window
pnpm check

pnpm check mirrors .github/workflows/checks.yml:

  1. pnpm typecheck
  2. pnpm lint (oxlint with type-aware checks, Convex plugin rules, and design system rules)
  3. pnpm test (Vitest across all TypeScript packages and convex-test)
  4. pnpm test:scripts (Node test runner for scripts/)
  5. go vet ./... and go test ./... inside apps/bridge-host

pnpm lint enforces three custom rules (scripts/lint/design-system.mjs) in apps/desktop and packages/ui:

Rule Scope Requirement
trioditis/no-literal-colour apps/desktop, packages/ui No hex, rgb(), or hsl() literals—always use design tokens from packages/ui/src/styles/tokens.css
trioditis/no-raw-control apps/desktop Use @trioditis/ui primitives instead of raw <button>, <input>, <select>, or <textarea>
trioditis/ui-imports apps/desktop Import one component at a time (e.g. @trioditis/ui/button)

Only disable a rule for a single line with an inline explanation: // eslint-disable-next-line trioditis/no-raw-control -- reason

  • TypeScript ↔ Go: Any change to the Sealed Storage Spec or Bridge Protocol must update both TypeScript (packages/crypto, packages/core, packages/backend, apps/gateway) and Go (apps/bridge-host) in the same pull request, including shared test vectors.
  • No plaintext leaks: Never write plaintext message bodies, chat names, or contact names to Convex, logs, or unencrypted disk.
  • No auto-retry after ambiguity: Always surface the unknown delivery state rather than silently resending.
  • Release notes: User-visible changes add a short note under release-notes/, which the server updater surfaces in Admin settings → Updates.

A desktop release is tagged on a release merge commit on main (which matches what servers on the Stable update channel run):

Terminal window
git fetch origin && git tag v0.1.0 origin/main
git push origin v0.1.0

Pushing a v<version> tag triggers .github/workflows/desktop-release.yml, building native installers on macOS (Apple Silicon and Intel, ad-hoc signed), Windows (x64), and Linux (AppImage and .deb) and publishing them with SHA-256 checksums to GitHub Releases. Pre-release tags (such as v0.2.0-beta.1) publish as GitHub prereleases without moving the releases/latest download links. Note that electron-builder.yml packages only the Electron shell and server picker—the web app comes directly from your Trioditis server.

apps/
bridge-host/ Go: bridgev2 MatrixConnector, 12 connectors, sealing, journal, login-browser
desktop/ Web & Electron desktop app (Vite + TanStack Router/Query)
docs/ Astro Starlight documentation site (all project docs live in src/content/docs/)
gateway/ Node: bridge host ↔ Convex pipeline & sign-in browser proxy
site/ Project landing page
assets/
brand/ Generated brand SVGs, PNGs, favicon, and social card
packages/
backend/ Convex schema, queries, mutations, Better Auth, MCP server
brand/ Brand asset generator (pnpm --filter @trioditis/brand generate)
config/ Shared TypeScript configuration
core/ Shared domain types and bridge protocol wire types
crypto/ Sealed storage, key wrapping, Argon2id password derivation
ui/ Design tokens, Wordmark, and UI component primitives
deploy/
compose/ Docker Compose bundle, Caddyfile, network overlays
docker/ Pinned Dockerfiles (web, node, bridge-host, login-browser)
install/ install.sh and proxmox.sh
scripts/ Key generation, encrypted backups, admin CLI, migrations, updater agent
test/ Automated deployment bundle test suite
release-notes/ Per-change release notes shown by the updater
scripts/ Dev stack and CI check runner