Feature/589 windows start when available

[hollowhemlock]

Mostly generated with ai from a script that I had to solve the same issue. First time with a go repository.

[coderabbitai]

Walkthrough

This pull request adds a Windows-only scheduling configuration option schedule-start-when-available that enables a missed scheduled task to start immediately when the system becomes available. The feature propagates through configuration parsing, schedule abstraction, and Windows Task Scheduler integration layers with supporting tests and documentation.

Changes

Cohort / File(s)	Summary
Configuration layer config/profile.go, config/schedule.go	Added ScheduleStartWhenAvailable field (type maybe.Bool) to ScheduleBaseSection and StartWhenAvailable field to ScheduleBaseConfig with initialization in init() and propagation in applyOverrides()
Schedule abstraction schedule/config.go, schedule_jobs.go	Added StartWhenAvailable bool field to schedule.Config struct and populated it from configuration in scheduleToConfig()
Windows Task Scheduler implementation schtasks/config.go, schtasks/taskscheduler.go	Added StartWhenAvailable bool field to schtasks.Config and mapped it to task.Settings.StartWhenAvailable in createTaskDefinition()
Windows handler schedule/handler_windows.go	Updated CreateJob() to pass StartWhenAvailable from job configuration to schtasks.Config
Windows integration tests schedule/handler_windows_test.go, schtasks/taskscheduler_test.go	Added new test functions TestStartWhenAvailableOption() to validate feature functionality at both handler and task scheduler levels
Documentation docs/content/schedules/configuration.md, docs/content/schedules/task_scheduler/index.md	Added configuration documentation section describing the Windows-only option, its behaviour, and YAML usage examples

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Review field threading consistency across all configuration layers (config → schedule → schtasks)
• Verify test coverage adequately validates the feature at both Windows handler and Task Scheduler levels
• Confirm documentation accurately reflects Windows-only scope and expected behaviour

Possibly related PRs

• feat(schedule): introduce schtasks-hide-window option #541: Adds parallel Windows-only schedule options with similar multi-layer configuration changes and test additions

Suggested labels

enhancement

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: adding a Windows-specific feature for starting scheduled tasks when the system becomes available.
Description check	✅ Passed	The description is somewhat vague but is related to the changeset, acknowledging it was generated with AI assistance for implementing a specific feature.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[hollowhemlock]

For feature #589

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

docs/content/schedules/configuration.md (1)

204-211: Consider minor grammar improvement.

The documentation is clear and helpful. However, consider adding a comma before "but" in line 208 for improved readability.

🔎 Proposed fix

-For example, if a backup is scheduled for 3:00 AM but the computer is off, enabling this option will run the backup when the computer is next available.
+For example, if a backup is scheduled for 3:00 AM, but the computer is off, enabling this option will run the backup when the computer is next available.

📜 Review details

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 2c47715 and aa43377.

📒 Files selected for processing (11)

• config/profile.go (1 hunks)
• config/schedule.go (3 hunks)
• docs/content/schedules/configuration.md (1 hunks)
• docs/content/schedules/task_scheduler/index.md (1 hunks)
• schedule/config.go (1 hunks)
• schedule/handler_windows.go (1 hunks)
• schedule/handler_windows_test.go (1 hunks)
• schedule_jobs.go (1 hunks)
• schtasks/config.go (1 hunks)
• schtasks/taskscheduler.go (1 hunks)
• schtasks/taskscheduler_test.go (1 hunks)

🧰 Additional context used

🧠 Learnings (1)

📚 Learning: 2025-07-29T16:14:02.636Z

Learnt from: zumm
Repo: creativeprojects/resticprofile PR: 541
File: schtasks/taskscheduler.go:60-67
Timestamp: 2025-07-29T16:14:02.636Z
Learning: In the schtasks package, `config.Command` is guaranteed to be just a path to executable, making single quotes sufficient for wrapping in command construction.

Applied to files:

• schedule/handler_windows.go
• schtasks/config.go

🧬 Code graph analysis (5)

schedule/handler_windows.go (2)

shell/command.go (1)

• Command (37-51)

schtasks/principal.go (1)

• RunLevel (30-30)

config/profile.go (1)

util/maybe/bool.go (1)

• Bool (11-13)

schtasks/taskscheduler_test.go (4)

schtasks/config.go (1)

• Config (5-14)

calendar/event.go (2)

• NewEvent (27-42)
• Event (15-24)

schtasks/task.go (2)

• RegistrationInfo (16-22)
• Task (24-33)

schtasks/settings.go (1)

• Settings (9-27)

schtasks/taskscheduler.go (1)

schtasks/settings.go (1)

• Settings (9-27)

config/schedule.go (1)

util/maybe/bool.go (1)

• Bool (11-13)

🪛 LanguageTool

docs/content/schedules/configuration.md

[uncategorized] ~208-~208: Use a comma before ‘but’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...le, if a backup is scheduled for 3:00 AM but the computer is off, enabling this opti...

(COMMA_COMPOUND_SENTENCE_2)

🔇 Additional comments (12)

schtasks/config.go (1)

13-13: LGTM!

The StartWhenAvailable field is correctly added to the Config struct and aligns with the Windows Task Scheduler's Settings structure.

config/profile.go (1)

329-329: LGTM!

The ScheduleStartWhenAvailable field is correctly configured with appropriate tags and follows the established pattern for optional Windows-specific schedule settings.

schtasks/taskscheduler.go (1)

187-187: LGTM!

The assignment correctly maps the configuration value to the Windows Task Scheduler settings.

schedule/handler_windows.go (1)

79-88: LGTM!

The StartWhenAvailable field is correctly propagated from the job configuration to the schtasks.Config structure. The alignment adjustments maintain code consistency.

schedule/config.go (1)

28-28: LGTM!

The StartWhenAvailable field is appropriately added to the scheduling configuration structure.

config/schedule.go (3)

50-50: LGTM!

The StartWhenAvailable field is correctly added to ScheduleBaseConfig with appropriate type and tags.

---

104-106: LGTM!

The initialisation logic for StartWhenAvailable follows the established pattern for optional boolean fields.

---

123-123: LGTM!

The override logic correctly propagates the StartWhenAvailable value from the section configuration.

schedule_jobs.go (1)

242-242: LGTM!

The StartWhenAvailable field is correctly populated by converting the maybe.Bool value to a boolean using IsTrue(), consistent with the HideWindow field pattern.

docs/content/schedules/task_scheduler/index.md (1)

38-49: LGTM! Clear and helpful documentation.

The documentation clearly explains the purpose of the schedule-start-when-available option and provides a practical example. The mapping to Windows Task Scheduler terminology is helpful for users familiar with that interface.

schtasks/taskscheduler_test.go (1)

291-343: LGTM! Thorough test coverage.

The test properly verifies that the StartWhenAvailable setting:

1. Is correctly applied when creating the task definition (line 316)
2. Persists when the task is created in Windows Task Scheduler (line 322)
3. Is correctly exported back from Task Scheduler (line 342)

The test follows the established pattern and includes proper cleanup.

schedule/handler_windows_test.go (1)

82-108: LGTM! Appropriate integration test.

The test follows the established pattern from TestHideWindowOption and properly verifies that a job can be created with the StartWhenAvailable option. The detailed verification of the setting itself is appropriately handled at the schtasks layer (in TestStartWhenAvailableOption in taskscheduler_test.go), whilst this test ensures the integration works correctly.

[creativeprojects]

Mostly generated with ai from a script that I had to solve the same issue. First time with a go repository.

At first glance it didn't do too badly. Which model did you use?

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 81.04%. Comparing base (2c47715) to head (aa43377).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #590      +/-   ##
==========================================
+ Coverage   81.00%   81.04%   +0.04%     
==========================================
  Files         137      137              
  Lines       11083    11089       +6     
==========================================
+ Hits         8977     8986       +9     
+ Misses       1680     1677       -3     
  Partials      426      426              

Flag	Coverage Δ
unittests	81.04% <100.00%> (+0.04%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[hollowhemlock]

claude opus 4.5