Refactoring complete: v0.4.0 architectural milestone (#1)
## Summary Completed Phase 5 refactoring and reached the target architecture. **Architectural milestone achieved:** - Service layer owns all state and is the sole writer - UI is a thin Fyne view, all widget updates marshaled via `fyne.Do` - Core engines are stateless and injectable - Domain types are pure (no `yaml:"-"` fields) - Full module builds and `go vet ./...` clean ## Changes - Bump version: 0.3.6 → 0.4.0 - Update CHANGELOG with Phase 5 summary - Add ROADMAP "Refactoring Follow-Ups" section ## Known follow-up work 1. **Linux test build broken** — `runner_test.go` needs `//go:build windows` tag 2. **File-size limits exceeded** — `operations.go` (486 lines), `jobs_view.go` (415 lines) See ROADMAP.md for details. --------- Co-authored-by: mixeme <mix.public@ya.ru> Reviewed-on: #1
This commit was merged in pull request #1.
This commit is contained in:
+72
-41
@@ -1,73 +1,104 @@
|
||||
# GoSentry Architecture
|
||||
|
||||
This document shows the current component interaction model. GoSentry is still a
|
||||
single desktop process: the GUI, scheduler, storage, and command runner live in
|
||||
one application and communicate through Go function calls and shared in-memory
|
||||
job state.
|
||||
This document shows the current component interaction model. GoSentry is a
|
||||
single desktop process: the GUI, application service, scheduler, storage, and
|
||||
command runner live in one application. They communicate through typed events
|
||||
and well-defined interfaces rather than shared mutable state.
|
||||
|
||||
## Package Map
|
||||
|
||||
```
|
||||
cmd/gosentry entry point — starts the UI
|
||||
src/
|
||||
domain/ pure value types: Job, Config, RunRecord, Schedule, JobRuntime
|
||||
app/ Service — sole owner of job/runtime state; emits typed Events
|
||||
scheduler/ pure timing loop; calls app.Service.RunDue on every tick
|
||||
runner/ shell command execution + log file writing + cleanup
|
||||
storage/ YAML persistence (gosentry.yaml, jobs.yaml)
|
||||
platform/
|
||||
autostart/ Manager interface + Windows (shortcut) and Linux (XDG) impls
|
||||
desktop/ display-scale helper (Linux only)
|
||||
winproc/ hidden-window startup flags (Windows only)
|
||||
ui/ Fyne windows, tabs, and dialogs; reads service via Events
|
||||
```
|
||||
|
||||
## Component Diagram
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
user["Desktop user"]
|
||||
gui["src/gui - Fyne windows, tabs, dialogs"]
|
||||
store["src/core Store - YAML config and jobs"]
|
||||
scheduler["src/core Scheduler - @every and cron timing"]
|
||||
runner["src/core Runner - shell command execution"]
|
||||
autostart["src/core Autostart - Windows Startup shortcut / Linux desktop startup"]
|
||||
config["gosentry.yaml - application settings"]
|
||||
jobs["jobs.yaml - job definitions"]
|
||||
logs["logs_dir - per-run command output logs"]
|
||||
shell["Platform shell - cmd.exe /C or sh -c"]
|
||||
ui["src/ui\nFyne windows, tabs, dialogs"]
|
||||
svc["src/app Service\nsole owner of job + runtime state"]
|
||||
store["src/storage Store\nYAML config and jobs"]
|
||||
sched["src/scheduler Scheduler\npure timing loop"]
|
||||
runner["src/runner\nshell command execution"]
|
||||
autostart["src/platform/autostart Manager\nWindows shortcut / Linux XDG"]
|
||||
config["gosentry.yaml\napplication settings"]
|
||||
jobs["jobs.yaml\njob definitions"]
|
||||
logs["logs_dir\nper-run command output logs"]
|
||||
shell["Platform shell\ncmd.exe /C or sh -c"]
|
||||
|
||||
user -->|"edits jobs, settings, runs commands"| gui
|
||||
gui -->|"OpenStore, SaveConfig, SaveJobs"| store
|
||||
user -->|"edits jobs, settings, runs commands"| ui
|
||||
ui -->|"CreateJob, UpdateJob, DeleteJob, RunNow, UpdateSettings, …"| svc
|
||||
svc -->|"SaveJobs, SaveConfig, LoadJobs, LoadConfig"| store
|
||||
store -->|"read/write"| config
|
||||
store -->|"read/write"| jobs
|
||||
|
||||
gui -->|"Start, Pause, RunNow, RefreshSchedule"| scheduler
|
||||
scheduler -->|"SaveJobs after state changes"| store
|
||||
scheduler -->|"RunJob(trigger)"| runner
|
||||
svc -->|"Start(RunDue)"| sched
|
||||
sched -->|"RunDue(now)"| svc
|
||||
svc -->|"RunJob"| runner
|
||||
runner -->|"execute command"| shell
|
||||
runner -->|"write stdout/stderr log"| logs
|
||||
runner -->|"RunRecord with status, duration, log path"| scheduler
|
||||
scheduler -->|"onChange RunRecord"| gui
|
||||
gui -->|"display History, command output, job state"| user
|
||||
runner -->|"RunRecord"| svc
|
||||
svc -->|"emit JobChanged / RunRecorded / ErrorOccurred"| ui
|
||||
ui -->|"display jobs, history, status"| user
|
||||
|
||||
gui -->|"SetAutostart, AutostartStatus"| autostart
|
||||
autostart -->|"use executable path from resolved Paths"| config
|
||||
ui -->|"SetAutostart, AutostartStatus"| autostart
|
||||
svc -->|"Set / Status via Manager"| autostart
|
||||
```
|
||||
|
||||
## Main Flows
|
||||
|
||||
1. Startup:
|
||||
The executable starts `cmd/gosentry`, which calls the GUI package. The GUI
|
||||
opens the store, loads `gosentry.yaml` and `jobs.yaml`, creates the main tabs,
|
||||
then starts the scheduler with the loaded job slice.
|
||||
`cmd/gosentry` calls `ui.Run`, which creates an `app.Service`, opens the
|
||||
store, loads `gosentry.yaml` and `jobs.yaml`, subscribes the UI to service
|
||||
events, builds the main window, and calls `Service.Start` to begin the
|
||||
scheduler loop.
|
||||
|
||||
2. Editing settings or jobs:
|
||||
The GUI updates the in-memory job/config state and asks `Store` to write YAML
|
||||
back to disk. Job definitions stay in one `jobs.yaml`; runtime command output
|
||||
is not stored there.
|
||||
The UI calls mutating methods on `app.Service` (e.g. `CreateJob`,
|
||||
`UpdateJob`, `UpdateSettings`). The Service validates the request, updates
|
||||
its in-memory state, persists through `storage.Store`, and emits a typed
|
||||
`Event`. The UI's observer receives the event and refreshes the relevant
|
||||
widget on the main thread via `fyne.Do`.
|
||||
|
||||
3. Scheduled run:
|
||||
`Scheduler` checks due jobs on a one-second ticker. When a job is due, it marks
|
||||
the job as running, saves state, and starts `Runner` asynchronously.
|
||||
`scheduler.Scheduler` fires a tick every second. On each tick it calls
|
||||
`Service.RunDue(now)`. The Service checks which enabled, non-paused jobs are
|
||||
due, marks each as running, and launches `runner.RunJob` in a goroutine.
|
||||
|
||||
4. Manual run:
|
||||
`Run now` calls the same scheduler path as scheduled execution, but the
|
||||
resulting history record uses the `Manual` trigger.
|
||||
`Run now` in the UI calls `Service.RunNow`. The Service checks that the job
|
||||
exists, is not already running, and that the scheduler is not paused, then
|
||||
executes `runner.RunJob` with the `Manual` trigger.
|
||||
|
||||
5. Command execution:
|
||||
`Runner` executes the command through the platform shell, captures stdout and
|
||||
stderr, writes one timestamped `.log` file, and returns a `RunRecord`.
|
||||
`runner.RunJob` builds the platform-specific invocation, executes the
|
||||
command through the platform shell, captures stdout and stderr, writes one
|
||||
timestamped `.log` file, and returns a `domain.RunRecord`.
|
||||
|
||||
6. History update:
|
||||
The scheduler receives the `RunRecord`, updates the matching job, saves YAML,
|
||||
runs log cleanup, and calls the GUI callback so the `History` tab refreshes.
|
||||
When a run goroutine completes, `Service` updates the job's runtime, saves
|
||||
YAML, triggers log cleanup, and emits `RunRecorded`. The UI observer appends
|
||||
the record to the History tab.
|
||||
|
||||
7. Autostart:
|
||||
The Settings tab calls the platform autostart implementation. Windows uses a
|
||||
shortcut in the current user's Startup folder. Linux uses a desktop-session
|
||||
startup entry. Both autostart mechanisms pass `--start-in-tray`, so the
|
||||
scheduler starts without opening the main window after sign-in.
|
||||
`UpdateSettings` in the Service calls `autostart.Manager.Set`. The Manager
|
||||
interface has two implementations: Windows writes a `.lnk` shortcut to the
|
||||
user Startup folder; Linux writes an XDG Autostart `.desktop` file. Both
|
||||
entries pass `--start-in-tray`.
|
||||
|
||||
8. Error surfacing:
|
||||
Background errors (failed YAML saves, cleanup errors) are emitted as
|
||||
`ErrorOccurred` events and displayed in the UI status area, rather than
|
||||
being silently discarded.
|
||||
|
||||
@@ -2,6 +2,68 @@
|
||||
|
||||
All notable GoSentry changes are recorded in this file.
|
||||
|
||||
## 0.4.0 - 2026-06-22
|
||||
|
||||
**Architectural milestone: completed refactoring and reached target architecture.**
|
||||
|
||||
- Completed Phase 5 refactoring: hardening, testing, and documentation.
|
||||
- Surface all save/cleanup errors from service and storage; no more silently swallowed `_ = ...` on persistence.
|
||||
- Introduced `platform/autostart.Manager` interface with per-platform implementations (Windows, Linux, other); inject into service instead of calling package functions.
|
||||
- Filled test gaps: folder filtering, log cleanup (count and age), settings persistence and migration, concurrent run prevention.
|
||||
- Verified `go test -race ./...` passes on Windows; no data races in the refactored codebase.
|
||||
- Updated `docs/ARCHITECTURE.md`, `docs/TESTS.md`, and README with final package structure and build/test instructions.
|
||||
- **Refactoring target reached:** Service layer owns all state and is the sole writer; UI is a thin view marshaling updates via `fyne.Do`; core engines are stateless and injectable; domain layer is pure with no test noise.
|
||||
- Known follow-ups recorded in `ROADMAP.md`:
|
||||
- Linux test build is currently broken (Windows-only test symbols need `//go:build windows`); will fix separately.
|
||||
- File-size soft limits exceeded in a few places; revisit when next editing those files.
|
||||
- No observable behavior changes.
|
||||
|
||||
## 0.3.6 - 2026-06-22
|
||||
|
||||
- Completed Phase 4 refactoring: carved up the GUI into focused, testable components.
|
||||
- Renamed `src/gui` → `src/ui` and split monolithic `app.go` into `run.go` (lifecycle) and `mainwindow.go` (view construction).
|
||||
- Extracted view components into separate files: `jobs_view.go`, `job_dialog.go`, `history_view.go`, `settings_view.go`.
|
||||
- Extracted platform wiring into separate files: `tray.go`, `singleinstance.go`, `layout.go`.
|
||||
- Removed forbidden platform imports (autostart, desktop, paths) from `src/ui`; all platform concerns now flow through `app.Service`.
|
||||
- Upgraded Fyne from v2.5.3 to v2.6.3 to enable `fyne.Do` for cross-thread widget marshaling (resolves concurrency issue #4).
|
||||
- Added `docs/PERFORMANCE.md` with measured startup-time analysis: the ~290ms increase from Phase 4 is entirely the Fyne 2.6.3 upgrade's `w.Show()` cost, not the restructuring.
|
||||
- Added `docs/PERFORMANCE.md` and wired post-Fyne-2.7.x re-check into `ROADMAP.md`.
|
||||
- No observable behavior changes; continued internal refactoring toward separated concerns and testability.
|
||||
|
||||
## 0.3.5 - 2026-06-19
|
||||
|
||||
- Completed Phase 3 refactoring: application service and state management.
|
||||
- Added `app.Service` as the single owner of application state (job registry, settings, run history).
|
||||
- Implemented event-driven observer dispatch: Services can emit events (JobAdded, JobChanged, etc.) to decouple state changes from UI updates.
|
||||
- Added `app.Clock` interface for testable time-dependent behavior in scheduler and run tracking.
|
||||
- Converted scheduler to drive app.Service instead of directly managing domain state.
|
||||
- Created `app.Format` helpers for display rendering (job names, schedule summaries, run times).
|
||||
- Added comprehensive unit tests for app.Service and supporting types.
|
||||
- No observable behavior changes; continued internal refactoring toward separated concerns and testability.
|
||||
|
||||
## 0.3.4 - 2026-06-19
|
||||
|
||||
- Completed Phase 2 refactoring: domain cleanup and value object extraction.
|
||||
- Split durable job configuration (`domain.Job`) from transient execution state (`domain.JobRuntime`), keyed by job ID.
|
||||
- Added `domain.Schedule` value object with `Parse`, `Validate`, and `Next(time.Time)` methods for cron/interval parsing.
|
||||
- Migrated scheduler to parse schedules once at load/edit instead of per tick, removing duplicated parsing.
|
||||
- Made `RunJob` pure: runner no longer mutates jobs, returning only `RunRecord` for the caller to fold into runtime state.
|
||||
- Simplified `storage.normalizeJobs` to touch only durable configuration; runtime initialization moved to `domain.NewRuntime`.
|
||||
- No observable behavior changes; continued internal refactoring toward separated concerns.
|
||||
|
||||
## 0.3.3 - 2026-06-18
|
||||
|
||||
- Completed Phase 1 refactoring: split the flat `src/core` package into specialized, focused packages:
|
||||
- `src/domain` for pure types (Job, RunRecord, Config)
|
||||
- `src/storage` for persistence (Load/Save, Paths, YAML helpers)
|
||||
- `src/runner` for job execution (RunJob orchestration, logging, exit codes)
|
||||
- `src/scheduler` for timing loop
|
||||
- `src/platform/winproc` for cross-platform hidden window configuration
|
||||
- `src/platform/autostart` for system autostart integration
|
||||
- `src/platform/desktop` for desktop environment integration
|
||||
- `src/app` for application-level code (Version, future Service layer)
|
||||
- No observable behavior changes; internal structure improvements only.
|
||||
|
||||
## 0.3.1 - 2026-06-17
|
||||
|
||||
- Changed startup timing in History to measure until the main window is actually shown instead of stopping during UI construction.
|
||||
|
||||
@@ -0,0 +1,57 @@
|
||||
# Performance Notes
|
||||
|
||||
Measured performance findings for GoSentry. Each entry records the method so the
|
||||
numbers can be reproduced and re-checked after relevant changes.
|
||||
|
||||
## Startup Time
|
||||
|
||||
### Finding (2026-06-22)
|
||||
|
||||
After the Phase 4 refactor, cold startup time (the History "Window shown in …"
|
||||
metric) increased by **~290 ms**. The increase is caused entirely by the
|
||||
**Fyne v2.5.3 → v2.6.3 upgrade** (task T4.1), **not** by the Service / domain /
|
||||
UI restructuring.
|
||||
|
||||
### Method
|
||||
|
||||
Env-gated phase timers (`GOSENTRY_TIMING`) were added across the startup path
|
||||
(`Run` in `src/ui/run.go` and `newMainView` in `src/ui/mainwindow.go`) and the
|
||||
equivalent points in the pre-refactor entry point (`src/gui/app.go` at commit
|
||||
`c5e0ef9`, the last commit before T4.1). Both were built with the CGO / MSYS2
|
||||
UCRT64 toolchain and run 5× each; the first run of each is a cold-disk outlier
|
||||
and is excluded. The timed span (`started` → `w.Show()`) is identical in both
|
||||
builds, so the comparison is fair.
|
||||
|
||||
### Results (warm-run averages)
|
||||
|
||||
| Phase (cumulative from start) | Old (Fyne 2.5.3) | New (Fyne 2.6.3) | Δ |
|
||||
|-------------------------------|------------------|------------------|--------|
|
||||
| after single-instance check | ~0.5 ms | ~0.6 ms | — |
|
||||
| after Fyne app + window + tray | ~277 ms | ~285 ms | +8 ms |
|
||||
| `app.Open()` done | +3 ms | +3 ms | 0 |
|
||||
| views built + `svc.Start()` | +42 ms | +43 ms | ~0 |
|
||||
| after `SetContent` | ~348 ms | ~353 ms | +5 ms |
|
||||
| **after `w.Show()` (TOTAL)** | **~348 ms** | **~644 ms** | **+~290 ms** |
|
||||
|
||||
### Interpretation
|
||||
|
||||
- Everything up to and including `SetContent` costs the same in both versions
|
||||
(~350 ms). The refactor-specific code — `app.Open()` (~3 ms) and the new
|
||||
`app.Service` plus view construction (~42 ms) — is unchanged, so the
|
||||
restructuring added no measurable startup cost.
|
||||
- The entire regression lands in **`w.Show()`**: ~0 ms under Fyne 2.5.3,
|
||||
~290 ms under 2.6.3. Fyne 2.6 reworked main-thread marshaling (the change that
|
||||
introduced `fyne.Do`) and front-loads first-window GL/driver realization into
|
||||
the `Show()` call.
|
||||
- The cost is a fixed, one-time Fyne expense, not a leak in GoSentry code, and
|
||||
the upgrade cannot be reverted because `fyne.Do` requires Fyne ≥ 2.6.
|
||||
- The tray / autostart path (`--start-in-tray`) skips `w.Show()` until the user
|
||||
opens the window, so it is unaffected.
|
||||
|
||||
### Next check
|
||||
|
||||
Re-measure with the same method after the planned **Fyne 2.6.3 → 2.7.x upgrade**
|
||||
(see [ROADMAP.md](ROADMAP.md) → Tray Interaction). The goal is to learn whether
|
||||
2.7's driver/threading changes recover any of the ~290 ms `w.Show()` cost or
|
||||
hold it steady. Reuse the `GOSENTRY_TIMING` instrumentation pattern above; do not
|
||||
commit the temporary timers.
|
||||
@@ -0,0 +1,304 @@
|
||||
# GoSentry Refactoring Plan
|
||||
|
||||
Status: proposed — not yet started.
|
||||
Goal: make the codebase **solid**, **comprehensive**, and **human-readable / maintainable**
|
||||
without changing observable behavior.
|
||||
|
||||
This document is the single source of truth for the refactor. It records the
|
||||
target architecture, the rationale, and a sequence of small, independently
|
||||
reviewable tasks. Each task lists the recommended agent model and effort level.
|
||||
|
||||
---
|
||||
|
||||
## 1. Why refactor
|
||||
|
||||
The application works and is well-commented, but its structure does not scale:
|
||||
|
||||
| # | Problem | Impact |
|
||||
|---|---------|--------|
|
||||
| 1 | `src/gui/app.go` is a 1,057-line monolith | Nothing can be found, reused, or tested in isolation |
|
||||
| 2 | `src/core` is one flat package mixing 7 concerns | No boundaries; everything can call everything |
|
||||
| 3 | **Shared mutable `*[]Job`** between GUI and `Scheduler` | GUI mutates the slice with no lock; scheduler locks the same slice → data race |
|
||||
| 4 | `onChange` mutates Fyne widgets **from the scheduler goroutine** | Latent crash/corruption — Fyne requires UI updates on the main thread |
|
||||
| 5 | `Job` mixes durable config and runtime state (`yaml:"-"` fields) | The "noise" the model fights to exclude lives in the same struct |
|
||||
| 6 | Errors swallowed everywhere (`_ = store.SaveJobs(...)`) | Save failures are invisible to the user |
|
||||
| 7 | No service/controller layer; GUI reaches into `store.Paths`, drives scheduler directly | Business logic is tangled into widget callbacks |
|
||||
| 8 | Schedule strings re-parsed every tick; no `Schedule` value type | Validation scattered; no single source of truth |
|
||||
| 9 | Tests only cover `core`; GUI and orchestration untestable | Documented gap in `docs/TESTS.md` |
|
||||
|
||||
> Note on layout: the project intentionally **keeps the `src/` directory**. The
|
||||
> `src/` → `internal/` move was considered and rejected — it is cosmetic for a
|
||||
> non-imported desktop app and not worth the import-path churn. All packages
|
||||
> below live under `src/`.
|
||||
|
||||
---
|
||||
|
||||
## 2. Target architecture
|
||||
|
||||
The central change is to **insert an application-service layer** that owns all
|
||||
state and exposes intent-based methods. This turns the UI into a thin view and
|
||||
the core packages into stateless engines, dissolving problems 3, 4, 6, and 7.
|
||||
|
||||
```
|
||||
┌──────────────┐ intents ┌─────────────────┐ calls ┌──────────────┐
|
||||
│ ui (Fyne) │ ───────────▶ │ app.Service │ ─────────▶ │ core engines │
|
||||
│ thin views │ ◀─────────── │ (sole owner of │ │ scheduler / │
|
||||
│ fyne.Do only │ events │ state + mutex) │ ◀───────── │ runner / │
|
||||
└──────────────┘ └─────────────────┘ records │ storage │
|
||||
└──────────────┘
|
||||
```
|
||||
|
||||
- **One writer.** `app.Service` holds the job list + runtime state behind a
|
||||
mutex. The UI never mutates state directly — it calls `CreateJob`, `RunNow`,
|
||||
`SetGlobalPause`, etc.
|
||||
- **Events flow back** through an observer interface. The UI's listener is the
|
||||
*only* place that touches widgets, and it marshals onto the main thread with
|
||||
`fyne.Do`.
|
||||
- **Core engines are stateless / injected** — scheduler and runner operate on
|
||||
data passed in, not a shared slice.
|
||||
|
||||
### 2.1 Package layout (all under `src/`)
|
||||
|
||||
```
|
||||
cmd/gosentry/
|
||||
main.go # flag parse → ui.Run
|
||||
|
||||
src/
|
||||
domain/ # pure types, zero external deps
|
||||
job.go # Job (durable config only — no yaml:"-")
|
||||
runtime.go # JobRuntime (LastRun/NextRun/State/Output/Logs)
|
||||
record.go # RunRecord
|
||||
config.go # Config + StartInTrayArgument
|
||||
schedule.go # Schedule value object: Parse / Validate / Next()
|
||||
|
||||
storage/ # persistence + path resolution + migration
|
||||
store.go # Load/SaveConfig, Load/SaveJobs
|
||||
paths.go # ResolvePaths
|
||||
yaml.go # writeYAML helper
|
||||
migration.go # pysentry → gosentry legacy handling
|
||||
|
||||
scheduler/
|
||||
scheduler.go # timing loop; drives Service via callbacks
|
||||
clock.go # Clock interface (real + fake for tests)
|
||||
|
||||
runner/
|
||||
runner.go # RunJob orchestration
|
||||
invocation.go # build exec.Cmd (shared)
|
||||
invocation_windows.go # cmd.exe quoting
|
||||
invocation_other.go # sh -c
|
||||
exitcodes.go # parse / accept success codes
|
||||
logfile.go # writeRunLog + sanitizeFileName
|
||||
cleanup.go # CleanupLogs
|
||||
|
||||
platform/
|
||||
winproc/ # hidden-window helper shared by runner + autostart
|
||||
winproc_windows.go # CREATE_NO_WINDOW / HideWindow
|
||||
winproc_other.go # no-op
|
||||
autostart/
|
||||
autostart.go # Manager interface + Status type
|
||||
windows.go linux.go other.go
|
||||
desktop/
|
||||
desktop_linux.go other.go
|
||||
|
||||
app/
|
||||
service.go # owns state; CreateJob/UpdateJob/Delete/RunNow/...
|
||||
events.go # Event types + Observer registration
|
||||
format.go # display strings (moved out of GUI)
|
||||
|
||||
ui/ # renamed from src/gui; thin Fyne views
|
||||
run.go # Run(): lifecycle, window, tray wiring
|
||||
mainwindow.go # tab assembly + event listener (fyne.Do)
|
||||
jobs_view.go # list + details panel + toolbar
|
||||
job_dialog.go # new/edit form
|
||||
history_view.go # history table
|
||||
settings_view.go # settings form
|
||||
tray.go # system tray
|
||||
singleinstance.go # localhost IPC
|
||||
layout.go # minWidthLayout
|
||||
```
|
||||
|
||||
Import paths follow the existing convention, e.g.
|
||||
`gitea.mixdep.ru/mix/gosentry/src/domain`,
|
||||
`gitea.mixdep.ru/mix/gosentry/src/app`.
|
||||
|
||||
### 2.2 Dependency direction (must stay acyclic)
|
||||
|
||||
```
|
||||
domain ← (no deps)
|
||||
storage ← domain
|
||||
runner ← domain, platform/winproc
|
||||
scheduler← domain
|
||||
app ← domain, storage, scheduler, runner
|
||||
ui ← app, domain (Fyne)
|
||||
platform/autostart, platform/desktop ← (own deps; winproc for windows)
|
||||
cmd ← ui
|
||||
```
|
||||
|
||||
### 2.3 Key design decisions
|
||||
|
||||
1. **Split durable vs. runtime in the domain.** `domain.Job` becomes pure YAML
|
||||
config (no `yaml:"-"`). Runtime state moves to `domain.JobRuntime`, held by
|
||||
the service keyed by job ID. (Resolves #5.)
|
||||
2. **`Schedule` value object.** `schedule.Parse(string) (Schedule, error)`
|
||||
validates once and exposes `Next(time.Time)`. (Resolves #8.)
|
||||
3. **Autostart behind a `Manager` interface**, selected per platform — mockable,
|
||||
no package-level functions.
|
||||
4. **Injectable `Clock`** in the scheduler → deterministic tests.
|
||||
5. **Errors surface to the UI.** Service methods return errors; status bar shows
|
||||
them. No more `_ =` on saves. (Resolves #6.)
|
||||
6. **Thread-safety contract:** core engines never import Fyne; the UI listener is
|
||||
the sole widget mutator and always wraps updates in `fyne.Do`. (Resolves #4.)
|
||||
|
||||
---
|
||||
|
||||
## 3. Task sequence
|
||||
|
||||
Tasks are ordered so the tree **compiles and all tests pass after every task**.
|
||||
Each task is a small, reviewable unit.
|
||||
|
||||
**Model guidance**
|
||||
- `haiku` — mechanical moves, renames, no judgment required.
|
||||
- `sonnet` — localized logic changes with clear scope.
|
||||
- `opus` — architecture-shaping work (new layers, concurrency, public APIs).
|
||||
|
||||
**Effort guidance** — reasoning depth, not size: `low` / `medium` / `high`.
|
||||
|
||||
### Phase 0 — Safety net
|
||||
|
||||
| Task | Description | Model | Effort |
|
||||
|------|-------------|-------|--------|
|
||||
| T0.1 | Add `scripts/test.sh` + `.bat` running `go vet ./...` and `go test -race ./...`. Document in `docs/TESTS.md`. | haiku | low |
|
||||
| T0.2 | Add characterization tests that pin current behavior at seams to be moved: store load→save round-trip, scheduler `nextRunTime`, end-to-end `RunJob` log output. (Some exist; fill gaps.) | sonnet | medium |
|
||||
|
||||
### Phase 1 — Split the flat `core` package (no logic change)
|
||||
|
||||
Mechanical moves + import fixes only. Behavior identical.
|
||||
|
||||
| Task | Description | Model | Effort |
|
||||
|------|-------------|-------|--------|
|
||||
| T1.1 | Create `src/domain`; move `Job`, `RunRecord`, `Config`, `JobsFile`, `StartInTrayArgument` from `model.go`. Keep `yaml:"-"` fields for now (split happens in Phase 2). Update all references. | sonnet | medium |
|
||||
| T1.2 | Create `src/platform/winproc`; move `configureHiddenWindow` + hidden-window flags out of `runner_windows.go` / `runner_other.go`. This breaks the future autostart→runner coupling early. | sonnet | medium |
|
||||
| T1.3 | Create `src/runner`; move `runner.go`, `runner_windows.go`, `runner_other.go`, `runner_test.go`. Point at `winproc`. Split helpers into `invocation*.go`, `exitcodes.go`, `logfile.go`, `cleanup.go` as the file moves. | sonnet | medium |
|
||||
| T1.4 | Create `src/scheduler`; move `scheduler.go`, `scheduler_test.go`. Still takes `*[]domain.Job` for now. | sonnet | medium |
|
||||
| T1.5 | Create `src/storage`; move `store.go`, `paths.go`, `store_test.go`. | sonnet | medium |
|
||||
| T1.6 | Create `src/platform/autostart`; move `autostart_*.go` + tests. Point at `winproc`. | sonnet | medium |
|
||||
| T1.7 | Create `src/platform/desktop`; move `desktop_linux.go`, `desktop_other.go`. | haiku | low |
|
||||
| T1.8 | Delete the now-empty `src/core`; run full build + tests on both platforms (or with build tags) to confirm parity. | haiku | low |
|
||||
|
||||
### Phase 2 — Domain cleanup
|
||||
|
||||
| Task | Description | Model | Effort |
|
||||
|------|-------------|-------|--------|
|
||||
| T2.1 | Add `src/domain/schedule.go`: `Schedule` value object with `Parse`, `Validate`, `Next(time.Time)`. Unit-test it. Keep `nextRunTime` as a thin wrapper initially. | opus | high |
|
||||
| T2.2 | Migrate `scheduler` to use `Schedule` (parse on load/edit, not per tick). Remove duplicated parsing. | sonnet | medium |
|
||||
| T2.3 | Split `domain.Job` (durable) from `domain.JobRuntime` (transient). Remove all `yaml:"-"` fields and `nextDue` from `Job`. Add `runtime.go`. | opus | high |
|
||||
| T2.4 | Update `storage`: load/save only `Job`; move runtime initialization out of `normalizeJobs` into a `domain.NewRuntime(job)` constructor. Update round-trip tests. **(Completed as part of T2.3 — removing the runtime fields from `Job` forced all three deliverables. Runtime-map ownership is deferred to T3.1.)** | sonnet | medium |
|
||||
|
||||
> After Phase 2 the scheduler and GUI still share state; the `Job`/`JobRuntime`
|
||||
> split is wired through temporary glue. Phase 3 removes the sharing.
|
||||
|
||||
### Phase 3 — Application service layer
|
||||
|
||||
| Task | Description | Model | Effort |
|
||||
|------|-------------|-------|--------|
|
||||
| T3.1 | Create `src/app/service.go`: `Service` owning `[]domain.Job` + `map[int]*domain.JobRuntime` behind a `sync.Mutex`. Constructor wires `storage`. | opus | high |
|
||||
| T3.2 | Add `src/app/events.go`: `Event` types (job changed, run recorded, scheduler state) + `Observer` registration. Single-threaded dispatch contract documented. | opus | high |
|
||||
| T3.3 | Move state-mutating operations into the service: `CreateJob`, `UpdateJob`, `DeleteJob`, `SetEnabled`, `RunNow`, `SetGlobalPause`, `UpdateSettings`. Each returns `error`. | opus | high |
|
||||
| T3.4 | Convert `scheduler` to operate through the service (no `*[]Job`). Scheduler asks the service for due jobs and reports records back; service is the sole writer. Inject `Clock`. | opus | high |
|
||||
| T3.5 | Move display/format helpers (`displayFolder`, `displayArguments`, `displayRunMode`, `statusText`, …) from GUI into `src/app/format.go`. | haiku | low |
|
||||
| T3.6 | Add `src/app` unit tests (no Fyne): create/edit/delete, enable/pause, global pause, run-now path with a fake runner + fake clock. Big coverage win. | opus | high |
|
||||
|
||||
### Phase 4 — Carve up the GUI
|
||||
|
||||
Rename `src/gui` → `src/ui` and break `app.go` into focused files. The UI now
|
||||
talks only to `app.Service` and reacts to events via `fyne.Do`.
|
||||
|
||||
| Task | Description | Model | Effort |
|
||||
|------|-------------|-------|--------|
|
||||
| T4.1 | Rename package `gui` → `ui`; split lifecycle into `run.go` + `mainwindow.go`. Wire the event listener and route every widget update through `fyne.Do`. (Resolves #4.) | opus | high |
|
||||
| T4.2 | Extract `jobs_view.go` (list + details + toolbar), driven by service calls + events. | sonnet | medium |
|
||||
| T4.3 | Extract `job_dialog.go`; validate schedule via `domain.Schedule.Validate`. | sonnet | medium |
|
||||
| T4.4 | Extract `history_view.go`. | sonnet | medium |
|
||||
| T4.5 | Extract `settings_view.go`; surface save/autostart/cleanup errors to the status label. (Resolves #6 in UI.) | sonnet | medium |
|
||||
| T4.6 | Extract `tray.go`, `singleinstance.go`, `layout.go`. | haiku | low |
|
||||
| T4.7 | Confirm `app.go` is gone and `ui` imports only `app` + `domain` + Fyne. Manual smoke test on each platform. | sonnet | medium |
|
||||
|
||||
### Phase 5 — Hardening & docs
|
||||
|
||||
| Task | Description | Model | Effort |
|
||||
|------|-------------|-------|--------|
|
||||
| T5.1 | Replace remaining `_ = ...Save...` with propagated/surfaced errors across service + storage. | sonnet | medium |
|
||||
| T5.2 | Introduce `autostart.Manager` interface + per-platform impls; inject into the service instead of calling package funcs. | sonnet | medium |
|
||||
| T5.3 | Fill documented test gaps: folder filtering, log cleanup (count + age), settings persistence/migration, concurrent run prevention. | sonnet | high |
|
||||
| T5.4 | Run `go test -race ./...` clean. Confirm no data race remains. | haiku | low |
|
||||
| T5.5 | Update `docs/ARCHITECTURE.md`, `docs/TESTS.md`, and the README "Project Layout" section to the new structure. | sonnet | medium |
|
||||
|
||||
---
|
||||
|
||||
## 3.1 Task completion checklist
|
||||
|
||||
Track progress here. Mark tasks complete as they land and pass review.
|
||||
|
||||
### Phase 0 — Safety net
|
||||
- [x] T0.1 — Add test script + `go vet` + `go test -race`
|
||||
- [x] T0.2 — Add characterization tests
|
||||
|
||||
### Phase 1 — Split flat `core` package
|
||||
- [x] T1.1 — Create `src/domain`; move Job/RunRecord/Config/etc
|
||||
- [x] T1.2 — Create `src/platform/winproc`; move `configureHiddenWindow`
|
||||
- [x] T1.3 — Create `src/runner`; move runner logic
|
||||
- [x] T1.4 — Create `src/scheduler`; move scheduler
|
||||
- [x] T1.5 — Create `src/storage`; move store/paths
|
||||
- [x] T1.6 — Create `src/platform/autostart`; move autostart logic
|
||||
- [x] T1.7 — Create `src/platform/desktop`; move desktop integration
|
||||
- [x] T1.8 — Delete empty `src/core`; build + test both platforms
|
||||
|
||||
### Phase 2 — Domain cleanup
|
||||
- [x] T2.1 — Add `src/domain/schedule.go`; Schedule value object
|
||||
- [x] T2.2 — Migrate `scheduler` to use Schedule
|
||||
- [x] T2.3 — Split `domain.Job` (durable) from `domain.JobRuntime` (transient)
|
||||
- [x] T2.4 — Update `storage`: load/save Job only; move runtime init _(landed with T2.3)_
|
||||
|
||||
### Phase 3 — Application service layer
|
||||
- [x] T3.1 — Create `src/app/service.go`; owns state behind mutex
|
||||
- [x] T3.2 — Add `src/app/events.go`; Event types + Observer
|
||||
- [x] T3.3 — Add state-mutating operations to service
|
||||
- [x] T3.4 — Convert `scheduler` to use service; inject Clock
|
||||
- [x] T3.5 — Move display helpers to `src/app/format.go`
|
||||
- [x] T3.6 — Add `src/app` unit tests (no Fyne)
|
||||
|
||||
### Phase 4 — Carve up the GUI
|
||||
- [x] T4.1 — Rename `gui` → `ui`; split app.go into run.go + mainwindow.go _(required Fyne v2.5.3→v2.6.3 upgrade for `fyne.Do`)_
|
||||
- [x] T4.2 — Extract `jobs_view.go`
|
||||
- [x] T4.3 — Extract `job_dialog.go`
|
||||
- [x] T4.4 — Extract `history_view.go`
|
||||
- [x] T4.5 — Extract `settings_view.go`
|
||||
- [x] T4.6 — Extract `tray.go`, `singleinstance.go`, `layout.go`
|
||||
- [x] T4.7 — Confirm app.go is gone; smoke test both platforms
|
||||
|
||||
### Phase 5 — Hardening & docs
|
||||
- [x] T5.1 — Surface errors from service + storage
|
||||
- [x] T5.2 — Introduce `autostart.Manager` interface
|
||||
- [x] T5.3 — Fill test gaps (folder filtering, cleanup, migration, concurrency)
|
||||
- [x] T5.4 — Run `go test -race ./...` clean on both platforms
|
||||
- [x] T5.5 — Update docs (ARCHITECTURE.md, TESTS.md, README)
|
||||
|
||||
---
|
||||
|
||||
## 4. Definition of done
|
||||
|
||||
- `go vet ./...` clean; `go test -race ./...` green on Windows and Linux.
|
||||
- No package outside `ui` imports Fyne; no engine mutates UI state.
|
||||
- `domain.Job` has no `yaml:"-"` fields.
|
||||
- `app.Service` is the only writer of job/runtime state.
|
||||
- `src/ui` contains no file over ~250 lines; no single file over ~400.
|
||||
- `docs/ARCHITECTURE.md` matches the shipped structure.
|
||||
|
||||
## 5. Risks & mitigations
|
||||
|
||||
| Risk | Mitigation |
|
||||
|------|-----------|
|
||||
| Cross-platform code moves break the non-host OS build | Build with both `GOOS=windows` and `GOOS=linux` after each platform-touching task (T1.2, T1.3, T1.6, T1.7). |
|
||||
| Concurrency change (Phase 3/4) introduces subtle deadlocks | Keep the service mutex non-reentrant; never call back into the UI while holding it; cover with `-race` tests in T3.6. |
|
||||
| Behavior drift during moves | Characterization tests (T0.2) pin behavior before structural change. |
|
||||
| Large diff hard to review | Each task is a separate commit/PR; phases land independently. |
|
||||
+44
-6
@@ -2,6 +2,32 @@
|
||||
|
||||
This file tracks planned GoSentry work that is larger than a single bug fix.
|
||||
|
||||
## Refactoring Follow-Ups
|
||||
|
||||
Loose ends found while verifying the [refactoring plan](REFACTORING.md) against
|
||||
its Definition of done. The architecture target is reached and verified on
|
||||
Windows, but the items below remain.
|
||||
|
||||
- **Linux test build is broken (correctness, not cosmetic).** `src/runner/runner_test.go`
|
||||
is a shared (untagged) test file that references Windows-only symbols
|
||||
(`SysProcAttr.HideWindow`, `SysProcAttr.CmdLine`, `windowsShellCommandLine`).
|
||||
The `runtime.GOOS != "windows"` guards are runtime skips and cannot save a file
|
||||
that does not *compile*, so `go test ./...` fails to build on Linux. This
|
||||
contradicts T5.4 ("go test -race clean on both platforms") and the DoD's
|
||||
"green on Windows and Linux." Fix: move the Windows-only tests
|
||||
(`TestShellCommandHidesWindow`, `TestShellCommandUsesWindowsSafeQuoting`, and any
|
||||
peers touching `SysProcAttr` / `windowsShellCommandLine`) into a new
|
||||
`src/runner/runner_windows_test.go` guarded by `//go:build windows`.
|
||||
- **File-size guidelines exceeded.** The DoD asks for no `src/ui` file over ~250
|
||||
lines and no single file over ~400:
|
||||
- `src/ui/jobs_view.go` — 415 lines (over both the ~250 UI target and the ~400 cap).
|
||||
- `src/app/operations.go` — 486 lines (over ~400).
|
||||
- `src/app/operations_test.go` (536) and `src/runner/runner_test.go` (421) also
|
||||
exceed 400 if the cap is read to include test files.
|
||||
|
||||
These are soft ("~") limits; revisit when next touching those files rather than
|
||||
splitting purely for line count.
|
||||
|
||||
## Post-Field-Test Cleanup
|
||||
|
||||
After real-world use confirms the main workflows, clean up temporary
|
||||
@@ -24,13 +50,25 @@ Cleanup checklist:
|
||||
|
||||
## Tray Interaction
|
||||
|
||||
Improve tray icon interaction after choosing a tray backend path.
|
||||
Improve tray icon interaction: click the tray icon to show and focus the main
|
||||
window.
|
||||
|
||||
- Add double-click on the tray icon to show and focus the main window.
|
||||
- Current Fyne 2.5.3 desktop tray API exposes menu and icon setup, but does not
|
||||
expose click or double-click callbacks for the tray icon itself.
|
||||
- Revisit when Fyne exposes this callback, or evaluate a small platform-specific
|
||||
tray integration if the behavior becomes important enough.
|
||||
- Unblocked by Fyne 2.7.0, which added `desktop.App.SetSystemTrayWindow(window)`.
|
||||
On Windows, macOS, and most Linux it shows the associated window on left-click;
|
||||
any tray menu then moves to right-click. There is still no raw click /
|
||||
double-click callback, so the behavior is single left-click (the conventional
|
||||
tray gesture), not the double-click originally sketched here.
|
||||
- The project is currently on Fyne 2.6.3, so this depends on a Fyne 2.6.3 -> 2.7.x
|
||||
upgrade first (minor bump; re-verify the CGO build under MSYS2 UCRT64 and check
|
||||
for 2.7 breaking changes). Track the upgrade as its own task.
|
||||
- As part of that upgrade, **re-measure startup time** with the `GOSENTRY_TIMING`
|
||||
method recorded in [PERFORMANCE.md](PERFORMANCE.md). The Fyne 2.5.3 -> 2.6.3 bump
|
||||
added ~290 ms to startup, all inside `w.Show()`; check whether 2.7 recovers any
|
||||
of it or holds steady, and append the result to PERFORMANCE.md.
|
||||
- After upgrading, the change in `src/ui/run.go` (configureSystemTray) is small:
|
||||
call `desk.SetSystemTrayWindow(w)` alongside `SetSystemTrayMenu(menu)`. Keep the
|
||||
existing "Show" menu item, which the Fyne docs recommend for less-compliant
|
||||
Linux systems.
|
||||
|
||||
## Delivery And Packaging
|
||||
|
||||
|
||||
+268
-89
@@ -1,146 +1,326 @@
|
||||
# GoSentry Test Suite
|
||||
|
||||
All tests are located alongside source code in the `src/core/` package. Tests follow Go conventions with `*_test.go` filename patterns.
|
||||
All tests are located alongside source code in their respective packages under `src/`. Tests follow Go conventions with `*_test.go` filename patterns.
|
||||
|
||||
## Running Tests
|
||||
|
||||
### Using the test scripts
|
||||
|
||||
The repository provides convenience scripts to run all tests with static analysis:
|
||||
|
||||
**Unix/Linux/macOS:**
|
||||
```bash
|
||||
./scripts/test.sh
|
||||
```
|
||||
|
||||
**Windows:**
|
||||
```bash
|
||||
scripts\test.bat
|
||||
```
|
||||
|
||||
Both scripts run:
|
||||
1. `go vet ./...` — static analysis for common errors and suspicious code patterns
|
||||
2. `go test -race ./...` — tests with race condition detection enabled
|
||||
|
||||
### Manual test commands
|
||||
|
||||
Run all tests:
|
||||
```bash
|
||||
go test ./...
|
||||
```
|
||||
|
||||
Run all tests with race detection:
|
||||
```bash
|
||||
go test -race ./...
|
||||
```
|
||||
|
||||
Run tests with verbose output:
|
||||
```bash
|
||||
go test -v ./...
|
||||
```
|
||||
|
||||
Run a specific test by name:
|
||||
```bash
|
||||
go test -run TestRunJobWritesLogFile ./src/runner
|
||||
```
|
||||
|
||||
Run tests with code coverage:
|
||||
```bash
|
||||
go test -cover ./src/runner
|
||||
go test -coverprofile=coverage.out ./src/runner
|
||||
go tool cover -html=coverage.out
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Test Files Overview
|
||||
|
||||
### store_test.go
|
||||
**Location:** `src/core/store_test.go`
|
||||
**Package:** `core`
|
||||
### src/domain/schedule_test.go
|
||||
|
||||
Tests YAML serialization and storage behavior.
|
||||
**Package:** `domain`
|
||||
|
||||
Tests schedule parsing and validation.
|
||||
|
||||
| Test | Purpose |
|
||||
|------|---------|
|
||||
| `TestJobsYAMLDoesNotPersistRuntimeNoise` | Verifies that `jobs.yaml` does not persist runtime state fields (LastRun, NextRun, LastState, Output, etc.). Only job definitions are stored; runtime data is kept in memory and log files. |
|
||||
| `TestParseRejectsInvalidSchedules` | Verifies that invalid schedule strings return an error. |
|
||||
| `TestParseEveryInterval` | Verifies `@every` duration syntax (e.g., `@every 10s`) is parsed and computes the correct next run time. |
|
||||
| `TestParseEveryTrimsSurroundingWhitespace` | Verifies leading/trailing whitespace around the `@every` spec is ignored. |
|
||||
| `TestParseCronExpression` | Verifies 5-field cron expressions (e.g., `*/5 * * * *`) are parsed and compute the correct next run time. |
|
||||
| `TestParseCronDescriptor` | Verifies predefined cron descriptors such as `@hourly` are accepted. |
|
||||
| `TestValidateAcceptsValidSchedules` | Verifies that `Schedule.Validate` returns nil for valid schedule strings. |
|
||||
| `TestZeroScheduleNextIsZero` | Verifies that a zero-value Schedule returns a zero time from `Next`. |
|
||||
| `TestStringReturnsTrimmedSpec` | Verifies that `Schedule.String` returns the trimmed schedule spec. |
|
||||
|
||||
---
|
||||
|
||||
### scheduler_test.go
|
||||
**Location:** `src/core/scheduler_test.go`
|
||||
**Package:** `core`
|
||||
### src/app/service_test.go
|
||||
|
||||
Tests schedule parsing and job invocation output formatting.
|
||||
**Package:** `app`
|
||||
|
||||
Tests `Service` construction and the state-accessor contract.
|
||||
|
||||
| Test | Purpose |
|
||||
|------|---------|
|
||||
| `TestNextRunTimeSupportsEvery` | Verifies `@every` duration syntax (e.g., `@every 10s`) correctly calculates next run time. Tests with 10-second interval. |
|
||||
| `TestNextRunTimeSupportsCron` | Verifies standard 5-field cron expressions (e.g., `*/5 * * * *`) correctly calculate next run time. Tests 5-minute interval. |
|
||||
| `TestRunningOutputIncludesInvocation` | Verifies the running job output header includes all relevant invocation details: command, arguments, success exit codes, start time, and trigger type. |
|
||||
| `TestNewServiceBuildsRuntimePerJob` | Verifies that `NewService` creates a `JobRuntime` entry for every loaded job. |
|
||||
| `TestJobsReturnsCopy` | Verifies that `Service.Jobs` returns a defensive copy so callers cannot mutate internal state. |
|
||||
| `TestStoreReturnsWiredStore` | Verifies that `Service.Store` returns the injected `storage.Store`. |
|
||||
|
||||
---
|
||||
|
||||
### runner_test.go
|
||||
**Location:** `src/core/runner_test.go`
|
||||
**Package:** `core`
|
||||
### src/app/operations_test.go
|
||||
|
||||
**Package:** `app`
|
||||
|
||||
Tests all mutating operations on the Service, scheduler integration, and settings persistence.
|
||||
|
||||
#### Job CRUD
|
||||
|
||||
| Test | Purpose |
|
||||
|------|---------|
|
||||
| `TestCreateJobAssignsIDAndEmits` | Verifies that `CreateJob` assigns a unique ID, persists to YAML, and emits `JobChanged`. |
|
||||
| `TestCreateJobValidates` | Verifies that `CreateJob` rejects jobs with an invalid schedule. |
|
||||
| `TestUpdateJobKeepsRuntimeAndReflectsDisable` | Verifies that `UpdateJob` preserves existing runtime state and disables a job correctly. |
|
||||
| `TestUpdateJobReenablesPausedJob` | Verifies that re-enabling a previously-disabled job clears the paused runtime state. |
|
||||
| `TestRuntimeLazilyRecreated` | Verifies that `UpdateJob` recreates a missing runtime entry rather than panicking. |
|
||||
| `TestUpdateJobNotFound` | Verifies that `UpdateJob` returns an error for an unknown job ID. |
|
||||
| `TestDeleteJobRemovesEverything` | Verifies that `DeleteJob` removes the job from the slice, the runtime map, and the schedule cache. |
|
||||
| `TestDeleteJobNotFound` | Verifies that `DeleteJob` returns an error for an unknown job ID. |
|
||||
| `TestSetEnabledNotFound` | Verifies that `SetEnabled` returns an error for an unknown job ID. |
|
||||
| `TestSetEnabledToggles` | Verifies that `SetEnabled` flips the enabled flag and persists the change. |
|
||||
|
||||
#### Global pause / run-now / run-due
|
||||
|
||||
| Test | Purpose |
|
||||
|------|---------|
|
||||
| `TestSetGlobalPauseUpdatesRuntimesAndEmits` | Verifies that `SetGlobalPause` updates all job runtimes, emits `SchedulerStateChanged`, and persists state. |
|
||||
| `TestRunNowUsesRunnerAndRecords` | Verifies that `RunNow` invokes the runner, records a `RunRecord`, and emits `RunRecorded`. |
|
||||
| `TestRunNowNotFound` | Verifies that `RunNow` returns an error for an unknown job ID. |
|
||||
| `TestRunNowRefusedWhileAlreadyRunning` | Verifies that a second concurrent `RunNow` on the same job is rejected while the first is in progress. |
|
||||
| `TestRunNowRefusedWhilePaused` | Verifies that `RunNow` is rejected when the global pause flag is set. |
|
||||
| `TestRunDueStartsDueJob` | Verifies that `RunDue` launches a job whose next-run time has passed. |
|
||||
| `TestRunDueSkipsJobNotYetDue` | Verifies that `RunDue` does not launch a job that is not yet due. |
|
||||
| `TestRunDueSkipsJobInRunningState` | Verifies that `RunDue` does not start a second concurrent run for an already-running job. |
|
||||
| `TestRunDueDoesNothingWhilePaused` | Verifies that `RunDue` launches nothing when the global pause flag is set. |
|
||||
| `TestStartDrivesRunDueOnTick` | Verifies that `Service.Start` wires `RunDue` to the scheduler tick and that each tick advances state. |
|
||||
|
||||
#### Settings
|
||||
|
||||
| Test | Purpose |
|
||||
|------|---------|
|
||||
| `TestUpdateSettingsPersistsAndValidates` | Verifies that `UpdateSettings` persists a valid config and rewrites autostart if needed. |
|
||||
| `TestUpdateSettingsRejectsInvalidConfigs` | Verifies that `UpdateSettings` returns validation errors without persisting. |
|
||||
| `TestPrependLogCapsActivityList` | Verifies that the activity log never grows beyond its maximum cap. |
|
||||
|
||||
---
|
||||
|
||||
### src/app/events_test.go
|
||||
|
||||
**Package:** `app`
|
||||
|
||||
Tests the event-emission and observer-subscription machinery.
|
||||
|
||||
| Test | Purpose |
|
||||
|------|---------|
|
||||
| `TestEmitDeliversToAllObserversInOrder` | Verifies that all registered observers receive emitted events in registration order. |
|
||||
| `TestEmitWithNoObserversIsNoop` | Verifies that emitting an event with no observers does not panic. |
|
||||
| `TestObserverCanReadServiceState` | Verifies that an observer called by `emit` can safely read Service state (jobs, runtimes). |
|
||||
|
||||
---
|
||||
|
||||
### src/app/format_test.go
|
||||
|
||||
**Package:** `app`
|
||||
|
||||
Tests display-formatting helpers used by the UI.
|
||||
|
||||
| Test | Purpose |
|
||||
|------|---------|
|
||||
| `TestStatusText` | Verifies that job status codes map to the correct display strings. |
|
||||
| `TestEventText` | Verifies trigger-type labels for scheduled, manual, and UI triggers. |
|
||||
| `TestDisplayFolder` | Verifies that an empty folder string shows "No folder". |
|
||||
| `TestDisplayArguments` | Verifies that an empty arguments string shows "None". |
|
||||
| `TestDisplaySuccessExitCodes` | Verifies that an empty exit-codes string shows the default "0". |
|
||||
| `TestDisplayRunMode` | Verifies run-mode labels for normal and start-only modes. |
|
||||
| `TestDisplayInvocation` | Verifies that the full invocation display string includes command, arguments, and exit codes. |
|
||||
| `TestDisplayIndex` | Verifies that the display index is one-based (job slice index + 1). |
|
||||
|
||||
---
|
||||
|
||||
### src/storage/store_test.go
|
||||
|
||||
**Package:** `storage`
|
||||
|
||||
Tests YAML round-tripping, migration, and default generation.
|
||||
|
||||
| Test | Purpose |
|
||||
|------|---------|
|
||||
| `TestJobsRoundTrip` | Verifies that jobs saved to YAML are reloaded with identical field values. |
|
||||
| `TestConfigRoundTrip` | Verifies that settings saved to YAML are reloaded with identical field values. |
|
||||
| `TestNormalizeJobsFillsDefaults` | Verifies that `normalizeJobs` assigns sequential IDs and sets default enabled state for jobs missing those fields. |
|
||||
| `TestLoadOrCreateConfigMigratesFromLegacy` | Verifies that the old flat-config format is migrated to the current `gosentry.yaml` + `jobs_dir` layout on first load. |
|
||||
| `TestLoadOrCreateConfigCreatesDefaultsOnFirstRun` | Verifies that a missing config file is created with sane defaults and a sample job. |
|
||||
| `TestJobsYAMLDoesNotPersistRuntimeNoise` | Verifies that `jobs.yaml` does not persist runtime state (LastRun, NextRun, etc.). Only durable job fields are stored. |
|
||||
|
||||
---
|
||||
|
||||
### src/scheduler/scheduler_test.go
|
||||
|
||||
**Package:** `scheduler`
|
||||
|
||||
Tests the timing-loop contract using a fake clock.
|
||||
|
||||
| Test | Purpose |
|
||||
|------|---------|
|
||||
| `TestSchedulerCallsTickWithClockNow` | Verifies that the scheduler calls the injected tick function with the wall-clock time returned by the fake Clock. |
|
||||
| `TestSchedulerStopReleasesClock` | Verifies that `Stop` terminates the tick loop and releases the Clock without hanging. |
|
||||
|
||||
---
|
||||
|
||||
### src/runner/runner_test.go
|
||||
|
||||
**Package:** `runner`
|
||||
|
||||
Tests command execution, exit code handling, output capture, and Windows-specific process behavior.
|
||||
|
||||
#### Log File Tests
|
||||
#### Log file tests
|
||||
|
||||
| Test | Purpose |
|
||||
|------|---------|
|
||||
| `TestRunJobWritesLogFile` | Verifies that each job execution creates a `.log` file in the configured logs directory with sanitized job name in filename and proper metadata (trigger type, job name, command output). |
|
||||
| `TestRunJobLogFileAllHeaders` | Verifies that the log file contains all expected metadata headers: trigger type, job name, command, arguments, and start time. |
|
||||
| `TestRunJobRecordFields` | Verifies that the returned `RunRecord` carries the correct status, trigger, and log-file path. |
|
||||
| `TestRunJobWritesLogFile` | Verifies that each job execution creates a `.log` file in the configured logs directory with a sanitized job name in the filename. |
|
||||
|
||||
#### Command Execution Tests
|
||||
#### Output formatting
|
||||
|
||||
| Test | Purpose |
|
||||
|------|---------|
|
||||
| `TestFormatOutput` | Verifies that stdout and stderr are combined with section labels in the formatted output. |
|
||||
| `TestFormatOutputEmptyStreams` | Verifies that empty stdout/stderr streams are omitted from the formatted output. |
|
||||
| `TestLogArguments` | Verifies that arguments are included in the log header and absent when the arguments field is empty. |
|
||||
| `TestSanitizeFileName` | Verifies that spaces and special characters in a job name are replaced to produce a safe filename segment. |
|
||||
|
||||
#### Command execution
|
||||
|
||||
| Test | Platform | Purpose |
|
||||
|------|----------|---------|
|
||||
| `TestRunJobRunsQuotedWindowsExecutable` | Windows | Verifies that executable paths with quotes (e.g., `"C:\Program Files\..."`) are executed correctly via cmd.exe. |
|
||||
| `TestRunJobRunsUnquotedWindowsProgramPathWithSpaces` | Windows | Verifies that unquoted executable paths with spaces (e.g., `C:\Program Files\App\app.exe`) are quoted and executed correctly. |
|
||||
| `TestRunJobRunsWindowsCommandWithSeparateArguments` | Windows | Verifies that command and arguments separated in the Job struct are combined and executed correctly. |
|
||||
| `TestRunJobRunsQuotedWindowsExecutable` | Windows | Verifies that executable paths with quotes are executed correctly via `cmd.exe`. |
|
||||
| `TestRunJobRunsUnquotedWindowsProgramPathWithSpaces` | Windows | Verifies that unquoted executable paths with spaces are quoted and executed correctly. |
|
||||
| `TestRunJobRunsWindowsCommandWithSeparateArguments` | Windows | Verifies that command and arguments from the Job struct are combined and executed correctly. |
|
||||
|
||||
#### Exit Code Handling Tests
|
||||
#### Exit code handling
|
||||
|
||||
| Test | Purpose |
|
||||
|------|---------|
|
||||
| `TestRunJobAcceptsConfiguredExitCode` | Verifies that exit codes listed in `SuccessExitCodes` (e.g., `"0,1"`) result in "OK" status even if nonzero. Includes detail message about accepted exit code. |
|
||||
| `TestRunJobRejectsUnconfiguredExitCode` | Verifies that exit codes not listed in `SuccessExitCodes` result in "Failed" status with exit code detail. |
|
||||
| `TestRunJobAcceptsConfiguredExitCode` | Verifies that exit codes in `SuccessExitCodes` result in "OK" status even when nonzero. |
|
||||
| `TestRunJobRejectsUnconfiguredExitCode` | Verifies that exit codes absent from `SuccessExitCodes` result in "Failed" status. |
|
||||
|
||||
#### Start-Only Mode Tests
|
||||
#### Start-only mode
|
||||
|
||||
| Test | Purpose |
|
||||
|------|---------|
|
||||
| `TestRunJobStartOnlyDoesNotWaitForExitCode` | Verifies that jobs with `StartOnly: true` launch the process and return "OK" immediately without waiting for process exit or checking exit code. |
|
||||
| `TestRunJobStartOnlyReportsStartFailure` | Verifies that jobs with `StartOnly: true` still report "Failed" if the process fails to start (e.g., executable not found). |
|
||||
| `TestRunJobStartOnlyDoesNotWaitForExitCode` | Verifies that `StartOnly: true` jobs launch and return "OK" immediately without waiting for the process to exit. |
|
||||
| `TestRunJobStartOnlyReportsStartFailure` | Verifies that `StartOnly: true` jobs still report "Failed" if the process cannot be started. |
|
||||
|
||||
#### Utility Function Tests
|
||||
#### Utility / Windows invocation
|
||||
|
||||
| Test | Platform | Purpose |
|
||||
|------|----------|---------|
|
||||
| `TestParseExitCodes` | All | Verifies that exit code strings with mixed separators (comma, semicolon, newline) are correctly parsed into integer slice. |
|
||||
| `TestDirectCommandDoesNotHideWindow` | Windows | Verifies that direct executable commands (with explicit path and arguments) do not request hidden window startup. |
|
||||
| `TestShellCommandHidesWindow` | Windows | Verifies that shell commands (passed to cmd.exe) request hidden window startup to prevent console flash. |
|
||||
| `TestShellCommandUsesWindowsSafeQuoting` | Windows | Verifies that shell commands use cmd.exe `/S /C` syntax with proper outer quoting to handle paths with spaces and special characters. |
|
||||
| `TestParseExitCodes` | All | Verifies that mixed-separator exit-code strings (comma, semicolon, newline) are parsed correctly. |
|
||||
| `TestDirectCommandDoesNotHideWindow` | Windows | Verifies that direct executable commands do not request hidden-window startup. |
|
||||
| `TestShellCommandHidesWindow` | Windows | Verifies that shell commands request hidden-window startup to prevent console flash. |
|
||||
| `TestShellCommandUsesWindowsSafeQuoting` | Windows | Verifies `cmd.exe /S /C` quoting for paths with spaces and special characters. |
|
||||
| `TestWindowsShellCommandLineQuotesUnquotedProgramPath` | Windows | Verifies that unquoted program paths in shell commands are quoted while preserving already-quoted arguments. |
|
||||
|
||||
---
|
||||
|
||||
### autostart_windows_test.go
|
||||
**Location:** `src/core/autostart_windows_test.go`
|
||||
**Package:** `core`
|
||||
**Build Tags:** `//go:build windows` (Windows only)
|
||||
### src/runner/cleanup_test.go
|
||||
|
||||
Tests Windows autostart entry creation via shortcuts in the Startup folder.
|
||||
**Package:** `runner`
|
||||
|
||||
Tests log-file cleanup by age and by count.
|
||||
|
||||
| Test | Purpose |
|
||||
|------|---------|
|
||||
| `TestParseRegistryRunValue` | Verifies that legacy Windows Registry `Run` entry values are correctly parsed from `reg query` output (for migration/cleanup). |
|
||||
| `TestSameWindowsPathIgnoresCaseAndQuotes` | Verifies that Windows path comparison is case-insensitive and handles quote marks correctly (e.g., `"D:\..."` matches `d:\...`). |
|
||||
| `TestSameWindowsPathHandlesSpaces` | Verifies that Windows path comparison correctly matches paths with spaces both with and without quotes. |
|
||||
| `TestStartupShortcutPathUsesUserStartupFolder` | Verifies that the startup shortcut path resolves to the user's Startup folder using `%APPDATA%` environment variable. |
|
||||
| `TestCreateStartupShortcutHandlesSpaces` | Verifies that `.lnk` shortcut files are created with correct `TargetPath` and `Arguments` (--start-in-tray) even when target path contains spaces. |
|
||||
| `TestCleanupLogsMissingDirReturnsNil` | Verifies that cleanup returns nil (not an error) when the logs directory does not exist. |
|
||||
| `TestCleanupLogsRemovesFilesPastMaxAge` | Verifies that `.log` files older than `MaxLogAgeDays` are deleted. |
|
||||
| `TestCleanupLogsKeepsFilesWithinAgeLimit` | Verifies that `.log` files within the age limit are retained. |
|
||||
| `TestCleanupLogsByCountDeletesOldest` | Verifies that when file count exceeds `MaxLogFiles`, the oldest files are removed first. |
|
||||
| `TestCleanupLogsNonLogFilesNotDeleted` | Verifies that non-`.log` files in the logs directory are never deleted by cleanup. |
|
||||
| `TestCleanupLogsSubdirsNotDeleted` | Verifies that subdirectories inside the logs directory are not deleted by cleanup. |
|
||||
| `TestCleanupLogsZeroLimitsDisableBothPolicies` | Verifies that setting both limits to zero disables both the age and count cleanup policies. |
|
||||
|
||||
---
|
||||
|
||||
### autostart_linux_test.go
|
||||
**Location:** `src/core/autostart_linux_test.go`
|
||||
**Package:** `core`
|
||||
**Build Tags:** `//go:build linux` (Linux only)
|
||||
### src/platform/autostart/autostart_windows_test.go
|
||||
|
||||
Tests Linux autostart entry creation via XDG Desktop Entry files.
|
||||
**Location:** `src/platform/autostart/autostart_windows_test.go`
|
||||
**Build Tags:** `//go:build windows`
|
||||
|
||||
Tests Windows autostart via shortcuts in the Startup folder.
|
||||
|
||||
| Test | Purpose |
|
||||
|------|---------|
|
||||
| `TestLinuxAutostartStartsInTray` | Verifies that the XDG Desktop Entry is created with the `--start-in-tray` argument in the `Exec=` field, so scheduled jobs run immediately after login without displaying the window. |
|
||||
| `TestLinuxAutostartRemovesLegacyDesktopEntry` | Verifies that legacy autostart entries (from old PySentry implementation) are cleaned up when enabling autostart through the new system. |
|
||||
| `TestParseRegistryRunValue` | Verifies that legacy `HKCU\...\Run` entry values are parsed correctly from `reg query` output (for migration/cleanup). |
|
||||
| `TestSameWindowsPathIgnoresCaseAndQuotes` | Verifies that Windows path comparison is case-insensitive and handles quote marks correctly. |
|
||||
| `TestSameWindowsPathHandlesSpaces` | Verifies that Windows path comparison matches paths with and without surrounding quotes. |
|
||||
| `TestSameWindowsPathStripsExtendedLengthPrefix` | Verifies that `\\?\`-prefixed paths are compared correctly after stripping the prefix. |
|
||||
| `TestSameWindowsPathMatchesShortNameViaFilesystem` | Verifies that 8.3 short names are resolved to long names for comparison. |
|
||||
| `TestStartupShortcutPathUsesUserStartupFolder` | Verifies that the shortcut path resolves into `%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup`. |
|
||||
| `TestCreateStartupShortcutHandlesCyrillicPath` | Verifies that `.lnk` files are created correctly when the executable path contains Cyrillic characters. |
|
||||
| `TestCreateStartupShortcutHandlesSpaces` | Verifies that `.lnk` files are created with correct `TargetPath` and `--start-in-tray` arguments when the path contains spaces. |
|
||||
|
||||
---
|
||||
|
||||
## Running Tests
|
||||
### src/platform/autostart/autostart_linux_test.go
|
||||
|
||||
### Run all tests in the package
|
||||
```bash
|
||||
cd D:\Local\Git\gosentry
|
||||
go test ./src/core
|
||||
```
|
||||
**Location:** `src/platform/autostart/autostart_linux_test.go`
|
||||
**Build Tags:** `//go:build linux`
|
||||
|
||||
### Run tests with verbose output
|
||||
```bash
|
||||
go test -v ./src/core
|
||||
```
|
||||
Tests Linux autostart via XDG Desktop Entry files.
|
||||
|
||||
### Run specific test by name
|
||||
```bash
|
||||
go test -run TestRunJobWritesLogFile ./src/core
|
||||
```
|
||||
| Test | Purpose |
|
||||
|------|---------|
|
||||
| `TestLinuxAutostartStartsInTray` | Verifies that the XDG Desktop Entry is created with `--start-in-tray` in the `Exec=` field. |
|
||||
| `TestLinuxAutostartRemovesLegacyDesktopEntry` | Verifies that enabling autostart also removes legacy PySentry service files left by earlier builds. |
|
||||
|
||||
### Run Windows-only tests (on Windows)
|
||||
```bash
|
||||
go test -v ./src/core # Windows build tags are active
|
||||
```
|
||||
---
|
||||
|
||||
### Run Linux-only tests (on Linux)
|
||||
```bash
|
||||
go test -v ./src/core # Linux build tags are active
|
||||
```
|
||||
### src/ui/jobs_view_test.go
|
||||
|
||||
### Run with code coverage
|
||||
```bash
|
||||
go test -cover ./src/core
|
||||
go test -coverprofile=coverage.out ./src/core
|
||||
go tool cover -html=coverage.out
|
||||
```
|
||||
**Package:** `ui`
|
||||
|
||||
Tests pure helper functions in the jobs view (no Fyne widget construction).
|
||||
|
||||
| Test | Purpose |
|
||||
|------|---------|
|
||||
| `TestFilterValue` | Verifies that `filterValue` returns the correct display string for the current folder filter. |
|
||||
| `TestFolderOptionsAlwaysIncludesSentinels` | Verifies that the folder filter list always starts with "All" and "No folder" sentinel entries. |
|
||||
| `TestFolderOptionsAppendsUniqueFolders` | Verifies that folder names from the job list are appended once each, in order, without duplicates. |
|
||||
| `TestFilteredJobIndexesAll` | Verifies that the "All" filter returns indexes for every job. |
|
||||
| `TestFilteredJobIndexesByNamedFolder` | Verifies that filtering by a named folder returns only jobs in that folder. |
|
||||
| `TestFilteredJobIndexesNoFolder` | Verifies that the "No folder" filter returns only jobs with an empty folder field. |
|
||||
| `TestFilteredJobIndexesEmptySlice` | Verifies that filtering an empty job slice returns an empty index list. |
|
||||
|
||||
---
|
||||
|
||||
@@ -150,20 +330,19 @@ go tool cover -html=coverage.out
|
||||
|
||||
2. **Cross-platform** — Platform-specific tests use `//go:build` tags and `runtime.GOOS` checks to skip when not applicable.
|
||||
|
||||
3. **Exit Code Flexibility** — The `SuccessExitCodes` field allows jobs to treat nonzero exit codes as success, tested explicitly.
|
||||
3. **Fake clocks and runners** — The scheduler is exercised with an injected fake `Clock`; the service operations tests inject a fake `runJob` function to avoid spawning real processes.
|
||||
|
||||
4. **Path Handling** — Extensive tests cover Windows path quoting, spaces in paths, and case-insensitive matching to avoid subtle shell escaping bugs.
|
||||
4. **Event-driven correctness** — `app` tests subscribe to the event bus and assert that the expected events are emitted, rather than inspecting internal fields directly.
|
||||
|
||||
5. **Start-Only Mode** — Special handling for long-running processes that should be launched but not waited on, tested separately from normal execution flow.
|
||||
5. **Exit Code Flexibility** — The `SuccessExitCodes` field allows jobs to treat nonzero exit codes as success, tested explicitly.
|
||||
|
||||
6. **Path Handling** — Extensive tests cover Windows path quoting, spaces in paths, and case-insensitive matching to avoid subtle shell escaping bugs.
|
||||
|
||||
7. **Start-Only Mode** — Special handling for long-running processes that should be launched but not waited on, tested separately from normal execution flow.
|
||||
|
||||
---
|
||||
|
||||
## Future Test Coverage Gaps
|
||||
## Remaining Test Coverage Gaps
|
||||
|
||||
Potential areas for additional tests:
|
||||
- Job group/folder filtering and persistence
|
||||
- Log cleanup (max file count and max age)
|
||||
- Settings persistence and migration
|
||||
- GUI integration tests (currently untested)
|
||||
- Concurrent job execution
|
||||
- Job history and run record storage
|
||||
- GUI integration tests — Fyne widget interaction is not yet tested end-to-end
|
||||
- Job history on-disk retrieval — RunRecord file reading is not covered
|
||||
|
||||
Reference in New Issue
Block a user