Development and Testing

Development and Testing

One-Bit Bureau is both an Omarchy plugin repository and an Omarchy theme-source repository. That dual role makes source safety, ownership, and exact public lifecycle testing part of the product contract.

Local development install

From a trusted source checkout:

bash setup --local

Local mode copies the plugin and theme into an isolated user installation path. It is for development only and is intentionally distinct from the canonical Git-managed public installation.

Use one-bit-bureau remove before changing installation modes.

Source layout

Experience.qml                 plugin panel composition
components/active-window/      bar widget
components/desktop/            desktop service, helpers, object assets, tests
components/dock/               dock, previews, icon manager, app switcher, tests
components/inspector/          shared bounded Inspector surface and tests
components/overview/           searchable overview, workspace board, and tests
themes/one-bit-bureau/         native Omarchy theme
fonts/                         pinned redistributable font binaries and licenses
branding/                      About, screensaver, and mark derivatives
artwork/                       generation masters and deterministic renderers
shortlink/                     public installer Worker and tests
release/                       verified local release installer
scripts/build-release-artifact immutable release archive builder
tests/                         source, setup, update, and coordinator tests
test/omarchy-acceptance.sh     disposable-guest graphical acceptance suite

The public theme-source payload contains ordinary data files only. Runtime helpers are invoked through explicit interpreters, so symlinks and executable file modes remain release blockers.

Short installer gate

The Worker dependencies contain executable tools and symlinks, so test them first and remove the generated dependency tree before validating the repository as a theme source:

npm --prefix shortlink ci
npm --prefix shortlink test
rm -rf shortlink/node_modules

The Worker gate covers generated Cloudflare types, TypeScript, routes, methods, response headers, canonical redirects, the retired shell endpoints, verified release presentation, tamper rejection, rollback, and already-installed handling.

Repository static gate

bash tests/static.sh

This gate covers:

• Omarchy plugin validation
• Shell and Python syntax
• Setup/uninstall round trips and rollback
• Theme-source ownership modes
• Update ownership and commit alignment
• Descriptor-relative install-state and command transactions, including exact and over-limit inputs, FIFO/symlink/hardlink refusal, identity/hash binding, durable replacement, and rollback
• GTK settings, backup, state, template, and theme-tree byte/entry/file/directory/depth budgets, including exhausted directory-cursor regression coverage
• Coordinator and motion behavior
• Desktop trust, preview, and path policy
• Desktop transaction, collision, journal, partial-result, and hash-proven Undo tests
• Shared Inspector normalization, lifecycle, keyboard, accessibility, and local-icon tests
• Dock model, Window Ledger, icon resolution, preview, keyboard, auto-hide, and helper tests
• Overview workspace ordering, occupancy, validated move, Inspector, and action-parity tests
• App-ID and bounded-state limits
• Font names and pinned checksums
• Branding assets
• Strict native theme validation
• Real Omarchy template rendering
• Navigation pass-through contracts

Graphical acceptance

Graphical acceptance runs inside a disposable x86_64 Omarchy guest:

bash test/omarchy-acceptance.sh

It covers the exact public Git add, adopt, activate, update, and remove lifecycle plus:

• Desktop objects, trusted and untrusted launchers, image previews, multi-selection, named routing, receipts, proven Undo, and multiple displays
• Desktop, dock-app, and overview-window Inspector states
• Dock seed, Window Ledger, pins, ordering, previews, auto-hide, monitor ownership, icons, and optional app switching
• Overview search, focus, close action, workspace board and moves, hot corner, and multi-monitor behavior
• Top-bar context and settings persistence
• Keyboard traversal, visible focus, assistive labels, and reduced motion
• Menu, launcher, clipboard, emoji, notifications, OSD, terminal palette, lock, branding, and unlock preview
• Disable behavior and stock-shell recovery
• Exact restoration of prior theme, bar, branding, and selected font state

SVG proofs and wallpaper crops never count as runtime evidence.

Public lifecycle contract

The release guest downloads the exact version’s GitHub release record, requires immutable: true, verifies the archive against the published SHA-256 asset digest, stages the recorded commit from the bundled tag, and runs the verified local installer. It repeats installation from an exact disabled checkout to cover interrupted-install recovery, then exercises one-bit-bureau status, one-bit-bureau update --yes, and one-bit-bureau remove.

The plugin and owned theme must resolve to the immutable release commit. Removal must restore the recorded baseline and leave documented user data intact. A changed digest, mutable release, mismatched tag, different commit, dirty checkout, or setup failure must stop before activation and roll back any checkout created by that transaction.

Visual evidence

Public release evidence includes a clean desktop, desktop photo behavior, the three Inspector noun types, route/receipt/Undo states, Window Ledger, workspace-board movement, dock and icon surfaces, overview, menu, terminal palette, notification, lock and unlock surfaces, a curated real-application tableau, and rollback captures.

The current interaction gallery comes from passed disposable x86_64 Omarchy run krlnvwgvq9 against public runtime commit bafae649 and Omarchy commit 2c593dbb. That run produced 45 review frames and passed the exact public add, activate, reduced-motion, update, remove, rollback, and user-data-preservation lifecycle. Before the real-application frame was admitted, the guest asserted exactly four intended windows, exactly three authored Files artifacts, a grayscale-only desk study, five rendered authored dock marks, and no delayed Chromium or LibreOffice first-run surface. The later documentation commit only packages those unchanged evidence pixels and copy.

A screenshot counts as evidence only when the same scene has an authoritative state assertion. OCR is not a substitute for layer, IPC, compositor, or filesystem postconditions. Stale captures are replaced when the tested behavior or visible surface changes.

Current user-facing runtime captures live under docs/screenshots/. The complete release checklist is docs/RELEASE-CHECKLIST.md.

Rebuilding artwork

Deterministic render helpers live under artwork/:

python3 artwork/render-app-icons.py
python3 artwork/render-bitmap-workbench.py
python3 artwork/render-branding.py
python3 artwork/render-crop-proof.py

Generated masters and accepted derivatives must keep their provenance notes. Imported code and font changes require a matching THIRD_PARTY_NOTICES.md update.

Release blockers

• Plugin/theme validation failure
• Plugin and theme ending at different commits
• Public install that does not start from the canonical repository
• Mutable release, missing asset digest, digest mismatch, or tag/commit mismatch
• Unsafe source files, symlinks, executables, secrets, or editor debris
• Stale or misleading preview assets
• Desktop/dock overlap or invisible input interception
• Keyboard traps, missing actionable focus, or inaccessible controls
• Helper processes surviving plugin unload
• Removal overwriting a later user edit
• Claims based only on static design proofs