Development and Releases

GearBeacon's source of truth is a small TypeScript server and framework-free browser interface. Keep changes aligned with its private, single-owner, self-hosted scope. Read CONTRIBUTING and the security policy before contributing.

Repository layout

Path	Purpose
backend/src / backend/dist	Server source and compiled CommonJS application
web	Browser dashboard and assets
launchers	Local, private-server, and offline demo startup scripts for source installations
docs	Getting-started guide, changelog, and release notes
deploy	Service installers, uninstallers, updaters, and hosting guidance
scripts	Version, integration, STARTTLS, packaging, and smoke tests
.github/workflows	Cross-platform CI, security scans, and releases
.github	Contribution/security policies, issue templates, and release checklist

Application runtime state belongs in the platform data directory or Docker /data, never in source control. backend/dist/index.js and backend/dist/email.js are intentionally committed generated output; change TypeScript and rebuild them rather than hand-editing generated files.

Development setup

Source runtime requires Node 22.13 or newer. CI currently uses Node 22.16.0 for its main test jobs; consult the workflow for the authoritative pin. Standalone packaging uses a separate newer Node version declared by its workflow, so passing source tests does not by itself validate a SEA package.

npm ci
npm run build
npm run check

The application itself uses the Node standard library; the lockfile installs development and release tooling. The browser contract preserves IDs shared between HTML/JavaScript, navigation order, keyboard/focus behavior, and responsive light/dark themes.

Choose validation for the change

Change / purpose	Command
TypeScript compilation	npm run build
Versions, schema, security and web contracts, syntax	npm run check
Backend, persistence, monitoring, notifications, migration and recovery	npm test
UI, responsive layout, themes, focus, keyboard and accessibility	npm run test:browser
Source launchers	npm run test:launchers
Installer/updater safety	npm run test:update-helpers
Explicit real-Store parser/catalog validation	npm run test:live-catalog
Container build	docker compose build

Browser testing needs Chrome/Chromium. Docker changes also need a mock-mode startup with temporary test storage. Validate shell syntax and PowerShell parsing for changed platform helpers. Use generated temporary data and fake credentials for tests; never point a test process at normal owner data or real notification accounts.

The live catalog canary contacts real UniFi Stores and stays read-only and credential-free. Run it for relevant catalog/parser/network changes, release validation, or explicit investigation; ordinary documentation work does not need it.

Architecture and behavioral contracts

The server compiles to CommonJS and uses built-in SQLite. Schema migrations are append-only, transactional, and protected by a validated safety backup. Notifications enter a durable bounded-retry queue before delivery. Catalog validation retains last-known-good state, confirms destructive changes twice, accepts complete restocks immediately, and excludes partial omissions from unlisting evidence.

The browser navigation is Watchlist, Browse, Activity, Settings. Settings subtabs are General, Notifications, Data, Security, Privacy, Operations. Preserve mobile reflow, 200% zoom, keyboard access, dialog focus restoration, visible focus, reduced motion, light/dark contrast, and readable product images. Old Operations navigation routes into Settings.

See API reference, monitoring, alerts, and security for owner-visible contracts.

Branches and documentation

Target normal changes at dev. main is reserved for reviewed stable work. Use semantic versions, record user-visible changes in the current changelog section, and keep package versions, compiled output, visible UI version, schema/manifest, release notes, package paths, and workflow examples consistent. npm run check enforces the core version and schema contract.

Keep the README focused on overview, installation choices, and links. Put detailed owner procedures and technical references in this wiki. Keep an offline quick-start in docs/START_HERE.txt, release history under docs/, and deployment script entry points in deploy/README.md. A changed release archive remains immutable; document layout differences rather than pretending older downloads changed.

The wiki is a separate Git repository (GearBeacon.wiki.git) with its own history. Update affected pages and navigation together; code pushes do not automatically publish wiki edits. Check page links, examples, configuration defaults, and recovery claims against the implementation when documenting behavior.

Release validation and publication

The release checklist is the source of truth for required gates. CI covers cross-platform installs/upgrades, mocks and failure scenarios, browser/axe checks, secure integrations, Compose isolation, and native packages. CodeQL scans source; Trivy gates repository secrets and high/critical image vulnerabilities. Describe checks actually run on the candidate, not just workflows available in the repository.

Before stable publication, the Candidate packages workflow can build a matching candidate such as 1.2.0-rc.1 as retained Actions artifacts without publishing a release. It uses the release packaging jobs, extracts and starts native executables, validates the source archive, generates SPDX SBOMs, and records attestations.

Prerelease tags belong on dev and do not move the stable latest container tag. A stable tag must match the exact reviewed main commit. Required gates include successful exact-commit CI/security results, consistent versions/notes/manifest, checksummed and rehearsed archives, amd64/arm64 images, SBOMs, and provenance. The release remains a draft until required publication steps succeed.

Real-host installation, upgrade, rollback, manual accessibility, and 24–48 hour soak testing are recommended additional validation, not release prerequisites. Missing optional evidence does not require a waiver; never report unperformed checks as passed.

Stable archives are currently unsigned and macOS packages are not notarized. Checksums, SBOMs, and artifact attestations have distinct purposes and do not constitute native application signing. See published releases for actual artifacts and Updates for owner-controlled installation.

Current dev regression coverage

npm test also runs scripts/views-alerts-test.mjs for named-view validation, revision conflicts, region boundaries, persistence/import, alert precedence, schedules, and actual queued jobs. Browser checks cover saved-view editing/applying/deleting, compact layout at desktop/mobile/200% equivalent widths, both themes, accessible explanations, Escape and focus restoration. npm run test:update-helpers uses temporary packages and mocked service/download/Compose commands to exercise successful updates and failures; on Windows it also requires Git Bash for Unix helper fixtures. These deterministic fixtures are not evidence of a real-host update or a Docker daemon deployment.