Developer Guide

Developer guide

Build

Use a current stable Xcode compatible with the project’s assets and host macOS. This checkout was inspected with Xcode 27.0; an older Xcode minimum has not been verified. See Getting started for platform requirements and target differences.

git clone https://github.com/nobbbbby/Alertivity.git
cd Alertivity
open Alertivity.xcodeproj

Select Alertivity (Non-sandboxed) for process features or Alertivity for the sandboxed target. Configure development signing for your team, then Run. To build from Terminal:

xcodebuild \
  -project Alertivity.xcodeproj \
  -scheme 'Alertivity (Non-sandboxed)' \
  -configuration Release \
  -destination 'platform=macOS' \
  build

Validate

Run the Swift Testing and UI suites with:

xcodebuild \
  -project Alertivity.xcodeproj \
  -scheme 'Alertivity (Non-sandboxed)' \
  -testPlan Alertivity \
  -destination 'platform=macOS' \
  test

UI tests isolate app preferences and skip login registration. Onboarding coverage checks persisted outcomes, preference preservation, permission changes, explicit style application, and replay. Optional screenshots require ALERTIVITY_CAPTURE_ONBOARDING=1 in the test-runner environment; capture can fail on secondary displays.

For layout review, open Alertivity/OnboardingLayoutPreviews.swift in Xcode Canvas. Its sample readings do not start monitoring or change preferences. Equal-width preview columns keep the center divider fixed as values change.

Find the owning code

Behavior	Files in Alertivity/
Scenes, menu commands, login registration, indicator selection	AlertivityApp.swift
Sampling and process filtering	SystemMetricsProvider.swift
Sampling schedule and status transitions	ActivityMonitor.swift
Readings, severity, and explanations	ActivityMetrics.swift, ActivityStatus.swift
Threshold defaults and validation	MonitoringPreferences.swift
Persistence and onboarding outcome	SettingsStore.swift
Configuration and permission UI	SettingsView.swift, NotificationPermissionView.swift
Alert eligibility, dwell, throttle, and actions	NotificationManager.swift
Process actions	ProcessActions.swift
Onboarding and previews	OnboardingView.swift, OnboardingLayoutPreviews.swift
Review qualification and presentation	ReviewRequestStore.swift, ReviewSettingsView.swift
Logging and translations	AppLogger.swift, Localization.swift, Localizable.xcstrings

Preserve lifecycle behavior

Onboarding stores pending, completed, or skipped. Closing a pending guide records skipped; replay never resets preferences. A transient replay request distinguishes user intent from automatic scene creation. Window restoration is disabled for the guide, and an unsolicited restored guide dismisses before activation. The launch check runs once per process because SwiftUI can recreate menu labels.

Notification requests are serialized and refresh authorization first. Permission UI refreshes on app activation after external changes. Settings opens through native SwiftUI APIs; login registration uses SMAppService. System Settings opens by application bundle identifier with navigation guidance, avoiding undocumented pane URLs.

Use existing OSLog categories for significant transitions and failures, without sensitive process data. Keep tests focused on behavior and update the owning wiki page when behavior changes. See Design decisions for the trade-offs these mechanisms support and Maintaining the wiki for publication.