Skip to content
theme-agent

Development

Workspace context

Section titled “Workspace context”

The Rust 2021 workspace has an MSRV of Rust 1.88. The release profile optimizes for binary size, enables LTO, strips symbols, and aborts on panic.

Use the supported just recipes so local checks match CI intent:

Terminal window
just test                 # cargo test --workspace
just test-core            # pure core tests
just test-agent           # binary crate tests
just test-one NAME        # one named test with --nocapture
just fmt-check
just clippy               # all targets and features; warnings denied
just clippy-headless      # no-default-features build
just clippy-linux         # Linux backend/tests; target must be installed
just clippy-windows       # Windows backend/tests; target must be installed
just ci                   # version, format, clippy, tests
just ci-full              # also headless and cross-target checks
just build
just build-release
just build-headless

Test ownership

Section titled “Test ownership”

Choose the narrowest suite that owns the contract:

  • theme-core tests the full resolver input matrix, configuration defaults and validation, TOML round trips, NOAA solar calculations, polar cases, DST boundaries, and protocol/event serialization.
  • theme-agent unit tests own CLI parsing, structured errors, mock parsing, service labels, and platform-specific argument construction.
  • crates/theme-agent/tests/daemon_cli.rs starts the real binary over a temporary socket and covers startup, status, mode changes, OS-application recording, subscriptions, sun state, configuration reload, shutdown, and unavailable-daemon behavior.
  • Platform mapping tests compile on every target and execute on their native OS. Linux and Windows target checks require their Rust targets and supporting cross-compilation environment.
  • macOS native notifications and launchd lifecycle, the tray’s autostart/live behavior, and the headless Neovim plugin have also been runtime-verified on macOS.

For a behavior change, run the narrow test that owns the state or wire contract, then exercise the affected end-to-end path. Changes to default features or platform modules must also preserve just clippy-headless and relevant target compilation.

Repository ownership

Section titled “Repository ownership”

Keep pure, synchronous, platform-neutral domain logic in theme-core. Put Tokio orchestration, filesystem and socket I/O, native APIs, service management, CLI presentation, and GUI code in theme-agent. The detailed path map is in Architecture.

Before changing behavior, identify the owning module, inspect its neighboring tests and conventions, and verify both the pure transition and user-visible path when both exist.

Versioning

Section titled “Versioning”

The root [workspace.package] version is the single SemVer source. Workspace crates inherit it with version.workspace = true, and Cargo.lock remains synchronized for reproducible builds.

Terminal window
just version                 # print current workspace version
just version-check           # validate SemVer and manifest/lock synchronization
just version-set 0.2.0-beta.1
just version-patch           # prerelease -> stable, otherwise PATCH += 1
just version-minor           # MINOR += 1; clear lower/pre-release/build fields
just version-major           # MAJOR += 1; clear lower/pre-release/build fields

Versions use MAJOR.MINOR.PATCH. Standard prerelease identifiers such as 0.2.0-beta.1 and build metadata such as 0.2.0+ci.5 are accepted. A patch bump from a prerelease promotes it to the matching stable release. Minor and major bumps clear prerelease/build metadata and reset lower components. Both just ci and just ci-full run version-check first.

See the versioning policy source and supported recipes.