# Developer guide

Use Python 3.11+ and requirements.txt. Run `python -m samsara.main` from the repository root. The desktop requires a Qt-capable graphical session; tests run offscreen.

## UI and orchestration

Analyze is the default page. Source and OS selection are visible together; Auto-detect is the default. The OS selector is disabled for saved inventories and fixed synthetic samples because their OS is recorded in the input. Windows and RHEL version profiles are explicit user intent, not promises of live collector availability.

`CollectionJob` runs detection and collection outside the GUI thread, then delivers stage, result or failure signals. OS mismatches and unsupported collectors preserve the previous result. Cancellation uses QThread interruption and the Linux runner's polling callback. All source/profile controls are locked while collecting. Closing an active worker is deferred to avoid destroying a running thread.

Results are initially empty. Successful assessments create session history records; choosing one restores its inventory and derived assessment. Reports always use the displayed assessment. Successful analysis opens the dedicated Summary page. Its first tab shows retirement risk, OS/version, a capped list of workload software hints and enabled scheduled work. Comprehensive tabs lazily load searchable inventory and evidence tables. The same compact summary is included in HTML reports; all inventory remains exported. Scrollable pages and fixed-size form cards preserve legibility at smaller window sizes.

## OS detection

`core/detection.py` reads local platform metadata and `/etc/os-release`, recognizes RHEL-related families and validates explicit major-version profiles. It does not resolve names or contact remote systems. Other Linux distributions may use Auto-detect. Windows desktop build numbers are not treated as Windows Server edition evidence. Saved inventories use their metadata and skip local OS detection.

## Linux backend

`collectors/linux.py` executes fixed arguments from system binary directories with a restricted environment, no shell or user hostname, suppressed command diagnostics and no sudo. Commands are polled for cancellation, an eight-second limit and 10 MiB output bound, then killed/reaped on failure. Overall command collection is limited to approximately 60 seconds. Reads are limited to local OS/proc metadata; remote mounts are not traversed. The headless CLI uses only the standard library and creates new output files exclusively.

Report source is included in locally collected server metadata. Import removes that field and treats source assertions as unverified. Inventory import validates schemas/inventory-v1.schema.json, caps size, strips diagnostic strings and command fields, and recalculates assessment results. Tighten field definitions alongside future production collector contracts.

## Analysis

Each finding has classification, supporting evidence, severity and points. Score is capped at 100: 0 informational, 1–29 low, 30–59 medium, 60–89 high, 90–100 critical. This is demonstration heuristic logic, not a validated production risk model. Known Linux application service names receive potential-dependency findings; other running services remain unknown rather than all being classified as application workloads. Incomplete checks and observation limits always require review.

## Verification

Run `python -m unittest discover -s tests -v`. Coverage includes profiles/detection, synthetic isolation, real-source labels, RPM/dpkg parsing, IPv4/IPv6, missing commands, cancellation/timeouts, no automatic assessments, history restoration, imports, UI selection and HTML escaping/export. Offscreen snapshots can verify geometry at standard and smaller resolutions; they do not replace native desktop testing.

A local Linux smoke collection has passed schema validation and HTML/JSON generation in the restricted development environment. Systemd/interface restrictions were recorded as failed checks. Real Windows and RHEL release validation, remote transports and packaging are still pending. Never replace missing checks with samples.

Summary presentation is derived by analyzers/summary.py without altering assessment scores. Higher numbers mean more retirement concerns. OS version uses explicit os_version or an OS-name version hint, never the kernel/build as a fallback. Software name rules omit obvious library/development/documentation packages; a running service without a matching package can still be highlighted. Unknown schedules and missing checks remain explicit. Linux scheduler metadata includes system timer calendars/next-run data and bounded readable /etc/crontab and /etc/cron.d entries. Cron command arguments, inline code and environment assignments never enter the collected data; safe script/executable names identify work. User crontabs, anacron, periodic-script contents and execution history remain outside coverage.

## Application branding

The supplied Samsara JPEG is bundled unchanged as `samsara/assets/samsara-logo.jpg`. `ui/branding.py` provides the shared Qt application/window icon and Windows taskbar application identity. The sidebar uses the same asset. Future packaged builds must include this asset; the original `App Logo` folder is not required at runtime. Icon loading was checked at 16–256 pixel sizes and the sidebar preview was reviewed offscreen. Native desktop/taskbar appearance still needs platform verification.

## Local Windows backend

`collectors/windows.py` implements supervised local execution; `powershell/Get-ServerInventory.ps1` dispatches independent section functions. Windows desktop detection routes through the verified CIM identity in the Windows backend, rather than inferring a Server edition from `platform.win32_ver()`. Explicit profiles are checked after the critical identity query and before other inventory work. No Windows module is executed on Linux.

The executable path comes from Windows GetSystemDirectoryW, with 64-bit Python required, never PATH/SystemRoot search. Argument lists use `-NoLogo -NoProfile -NonInteractive -File` with a trusted repository script and a fixed section enum. No shell, `-Command`, credential parameters, user-supplied command text, automatic elevation or execution-policy bypass. PSModulePath is limited to inbox modules. Native stdout is UTF-8 JSON; stderr/raw provider exceptions are excluded. Temporary stdout is bounded; each process is polled for cancellation/time/output limits and killed/reaped on exit paths. Provider services are not stopped or reconfigured.

Per-section default timeout is 45 seconds; overall budget is 300 seconds; per-section and accepted total inventory limits are 10 MiB. Timed-out/invalid sections are explicitly failed, remaining unattempted checks are not_collected when the overall budget expires, and successful observations survive. Cancellation rejects the new result and retains the previous UI assessment. The direct PowerShell `all` path emits the complete schema but has no Python timeout supervisor.

OS ProductType 2/3 plus build mapping gates Server 2016/2019/2022/2025. Workstation identities and unknown builds are rejected. A partial system check can be accepted only if the OS identity itself is verified; domain/IP failures remain explicit. Each section has start/end UTC timestamps, status, safe error codes/messages, access limitations and scope limitations. Complete means successful documented scope, not comprehensive dependency evidence. Non-elevated sensitive queries are conservatively partial. ACL-based silent filtering remains a manual verification concern.

`models/inventory.py` now owns the shared v1 validator and field allowlists. Metadata fields are additive and old demo/Linux results remain valid. Live Windows results are projected to safe fields; raw CIM instances are never serialized. Imported errors retain recognized categorical codes and timestamps but discard arbitrary diagnostic/permission text. Imports cannot assert the trusted local source label. Registry software covers both read-only machine uninstall views; services omit PathName; tasks emit safe action basenames and selected triggers rather than Arguments/XML; certificates never access private-key properties. Reports include all check statuses, timestamps and limitations.

Fixtures for all four Server releases live in tests/fixtures/windows. Python tests cover contract/identity/array handling, partial permission results, invalid output, process cancellation/reaping, timeouts, output bounds, secret-field exclusion, imports and the unchanged GUI/history/report flow. `tests/powershell/Test-Collectors.ps1` uses the native PowerShell AST parser and synthetic function/registry objects to test the scripts without querying the host; it runs automatically where PowerShell is present. This test is skipped in the current Linux environment. **No real Windows inventory has yet been produced here; do not mark the Windows milestone complete.** Use the README's explicit real-host validation command and review private reports before recording compatibility.