feat(core): add run-on-startup option for jobs (#436)

## Summary

Add optional `run-on-startup` parameter that executes jobs immediately
when the scheduler starts, before regular cron scheduling begins.

- Add `RunOnStartup` field to `BareJob` struct (applies to all job
types: exec, run, local, service-run, compose)
- Add `ShouldRunOnStartup()` method to `Job` interface
- Add `runStartupJobs()` method to Scheduler that runs startup jobs in
goroutines for non-blocking execution
- Include `RunOnStartup` in job hash for change detection

### Configuration Example

```ini
[job-exec "backup"]
schedule = @daily
container = my-container
command = /backup.sh
run-on-startup = true
```

### Design Decisions

1. **Non-blocking**: Startup jobs run in goroutines to prevent blocking
other job registrations and scheduler start
2. **All job types**: The option is in `BareJob`, so it works for exec,
run, local, service-run, and compose jobs
3. **Default false**: Existing configurations are unaffected (backward
compatible)

## Test Plan

- [x] Verify job with `run-on-startup=true` executes on scheduler start
- [x] Verify job with `run-on-startup=false` does NOT run on startup
- [x] Verify multiple startup jobs run concurrently (non-blocking)
- [x] Verify `Start()` returns immediately (non-blocking verification)
- [x] Verify config parsing works for all job types
- [x] Verify triggered-only jobs (`@triggered`) with
`run-on-startup=true` work correctly
- [x] All existing tests pass
- [x] Lint passes

Closes #347

Author: CybotTM

cli/config_parsing_test.go

@@ -304,6 +304,156 @@ command = echo hello
 	}
 }
 
+// TestBuildFromString_RunOnStartup tests parsing of run-on-startup option
+func TestBuildFromString_RunOnStartup(t *testing.T) {
+	t.Parallel()
+	tests := []struct {
+		name           string
+		config         string
+		wantRunOnStart bool
+		wantSchedule   string
+	}{
+		{
+			name: "run-on-startup_true",
+			config: `
+[job-exec "startup-job"]
+schedule = @every 1h
+container = my-container
+command = echo hello
+run-on-startup = true
+`,
+			wantRunOnStart: true,
+			wantSchedule:   "@every 1h",
+		},
+		{
+			name: "run-on-startup_false",
+			config: `
+[job-exec "no-startup-job"]
+schedule = @every 1h
+container = my-container
+command = echo hello
+run-on-startup = false
+`,
+			wantRunOnStart: false,
+			wantSchedule:   "@every 1h",
+		},
+		{
+			name: "run-on-startup_default",
+			config: `
+[job-exec "default-job"]
+schedule = @every 1h
+container = my-container
+command = echo hello
+`,
+			wantRunOnStart: false, // Default is false
+			wantSchedule:   "@every 1h",
+		},
+		{
+			name: "run-on-startup_with_triggered_schedule",
+			config: `
+[job-exec "triggered-job"]
+schedule = @triggered
+container = my-container
+command = echo hello
+run-on-startup = true
+`,
+			wantRunOnStart: true,
+			wantSchedule:   "@triggered",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			logger := test.NewTestLogger()
+			cfg, err := BuildFromString(tt.config, logger)
+			if err != nil {
+				t.Fatalf("BuildFromString failed: %v", err)
+			}
+
+			if len(cfg.ExecJobs) != 1 {
+				t.Fatalf("Expected 1 exec job, got %d", len(cfg.ExecJobs))
+			}
+
+			for _, job := range cfg.ExecJobs {
+				if job.RunOnStartup != tt.wantRunOnStart {
+					t.Errorf("RunOnStartup = %v, want %v", job.RunOnStartup, tt.wantRunOnStart)
+				}
+				if job.Schedule != tt.wantSchedule {
+					t.Errorf("Schedule = %v, want %v", job.Schedule, tt.wantSchedule)
+				}
+			}
+		})
+	}
+}
+
+// TestBuildFromString_RunOnStartupAllJobTypes tests run-on-startup works for all job types
+func TestBuildFromString_RunOnStartupAllJobTypes(t *testing.T) {
+	t.Parallel()
+	configStr := `
+[job-exec "exec-startup"]
+schedule = @every 1h
+container = test-container
+command = echo exec
+run-on-startup = true
+
+[job-run "run-startup"]
+schedule = @every 1h
+image = alpine
+command = echo run
+run-on-startup = true
+
+[job-local "local-startup"]
+schedule = @every 1h
+command = echo local
+run-on-startup = true
+
+[job-service-run "service-startup"]
+schedule = @every 1h
+image = nginx
+command = echo service
+run-on-startup = true
+
+[job-compose "compose-startup"]
+schedule = @every 1h
+command = up -d
+run-on-startup = true
+`
+
+	logger := test.NewTestLogger()
+	cfg, err := BuildFromString(configStr, logger)
+	if err != nil {
+		t.Fatalf("BuildFromString failed: %v", err)
+	}
+
+	// Verify all job types have run-on-startup enabled
+	for _, job := range cfg.ExecJobs {
+		if !job.RunOnStartup {
+			t.Errorf("ExecJob %q: RunOnStartup = false, want true", job.Name)
+		}
+	}
+	for _, job := range cfg.RunJobs {
+		if !job.RunOnStartup {
+			t.Errorf("RunJob %q: RunOnStartup = false, want true", job.Name)
+		}
+	}
+	for _, job := range cfg.LocalJobs {
+		if !job.RunOnStartup {
+			t.Errorf("LocalJob %q: RunOnStartup = false, want true", job.Name)
+		}
+	}
+	for _, job := range cfg.ServiceJobs {
+		if !job.RunOnStartup {
+			t.Errorf("ServiceJob %q: RunOnStartup = false, want true", job.Name)
+		}
+	}
+	for _, job := range cfg.ComposeJobs {
+		if !job.RunOnStartup {
+			t.Errorf("ComposeJob %q: RunOnStartup = false, want true", job.Name)
+		}
+	}
+}
+
 // TestResolveConfigFiles tests the resolveConfigFiles function
 func TestResolveConfigFiles(t *testing.T) {
 	t.Parallel()

core/bare_job.go

@@ -7,9 +7,13 @@ import (
 )
 
 type BareJob struct {
-	Schedule         string   `hash:"true"`
-	Name             string   `hash:"true"`
-	Command          string   `hash:"true"`
+	Schedule string `hash:"true"`
+	Name     string `hash:"true"`
+	Command  string `hash:"true"`
+	// RunOnStartup controls whether the job is executed once immediately when the scheduler starts,
+	// before regular cron-based scheduling begins. This is a boolean flag with a default value of false.
+	// Startup executions are dispatched in non-blocking goroutines so they do not delay scheduler startup.
+	RunOnStartup     bool     `default:"false" gcfg:"run-on-startup" mapstructure:"run-on-startup" hash:"true"`
 	HistoryLimit     int      `default:"10"`
 	MaxRetries       int      `default:"0"`                                  // Maximum number of retry attempts (0 = no retries)
 	RetryDelayMs     int      `default:"1000"`                               // Initial retry delay in milliseconds
@@ -40,6 +44,11 @@ func (j *BareJob) GetCommand() string {
 	return j.Command
 }
 
+// ShouldRunOnStartup returns true if the job should run immediately when the scheduler starts.
+func (j *BareJob) ShouldRunOnStartup() bool {
+	return j.RunOnStartup
+}
+
 func (j *BareJob) Running() int32 {
 	return atomic.LoadInt32(&j.running)
 }

core/common.go

@@ -25,6 +25,7 @@ type Job interface {
 	GetName() string
 	GetSchedule() string
 	GetCommand() string
+	ShouldRunOnStartup() bool
 	Middlewares() []Middleware
 	Use(...Middleware)
 	Run(*Context) error

core/common_extra3_test.go

@@ -37,8 +37,8 @@ func TestBareJobHashValue(t *testing.T) {
 		Name:     "name",
 		Command:  "cmd",
 	}
-	// Expect "schednamecmd"
-	want := "schednamecmd"
+	// Expect "schednamecmdfalse" (includes RunOnStartup=false)
+	want := "schednamecmdfalse"
 	got, err := job.Hash()
 	if err != nil {
 		t.Fatalf("hash error: %v", err)

core/context_log_test.go

@@ -45,6 +45,7 @@ type stubJob struct {
 func (j *stubJob) GetName() string           { return j.name }
 func (j *stubJob) GetSchedule() string       { return "" }
 func (j *stubJob) GetCommand() string        { return "" }
+func (j *stubJob) ShouldRunOnStartup() bool  { return false }
 func (j *stubJob) Middlewares() []Middleware { return nil }
 func (j *stubJob) Use(...Middleware)         {}
 func (j *stubJob) Run(*Context) error        { return nil }

core/scheduler.go

@@ -322,9 +322,32 @@ func (s *Scheduler) Start() error {
 	s.mu.Unlock()
 	s.Logger.Debugf("Starting scheduler")
 	s.cron.Start()
+
+	// Run jobs marked with run-on-startup
+	s.runStartupJobs()
+
 	return nil
 }
 
+// runStartupJobs executes jobs that have run-on-startup=true.
+// Each job runs in its own goroutine to avoid blocking the scheduler.
+func (s *Scheduler) runStartupJobs() {
+	s.mu.RLock()
+	jobs := make([]Job, 0)
+	for _, j := range s.Jobs {
+		if j.ShouldRunOnStartup() {
+			jobs = append(jobs, j)
+		}
+	}
+	s.mu.RUnlock()
+
+	for _, job := range jobs {
+		s.Logger.Noticef("Running startup job: %s", job.GetName())
+		wrapper := &jobWrapper{s: s, j: job}
+		go wrapper.Run()
+	}
+}
+
 // DefaultStopTimeout is the default timeout for graceful shutdown.
 const DefaultStopTimeout = 30 * time.Second
 

core/scheduler_test.go

@@ -198,3 +198,142 @@ func TestSchedulerWithCronClock(t *testing.T) {
 	_ = sc.Stop()
 	assert.False(t, sc.IsRunning())
 }
+
+func TestSchedulerRunOnStartup(t *testing.T) {
+	t.Parallel()
+
+	job := &TestJob{}
+	job.Schedule = "@every 1h" // Long interval so it won't fire during test
+	job.RunOnStartup = true
+
+	sc := NewSchedulerWithOptions(&TestLogger{}, nil, 10*time.Millisecond)
+	err := sc.AddJob(job)
+	require.NoError(t, err)
+
+	jobCompleted := make(chan struct{}, 1)
+	sc.SetOnJobComplete(func(_ string, _ bool) {
+		select {
+		case jobCompleted <- struct{}{}:
+		default:
+		}
+	})
+
+	_ = sc.Start()
+
+	// Job should run immediately on startup
+	select {
+	case <-jobCompleted:
+		// Success - job ran on startup
+	case <-time.After(500 * time.Millisecond):
+		t.Fatal("Startup job should have run immediately")
+	}
+
+	assert.Equal(t, 1, job.Called())
+
+	_ = sc.Stop()
+}
+
+func TestSchedulerRunOnStartupDisabled(t *testing.T) {
+	t.Parallel()
+
+	job := &TestJob{}
+	job.Schedule = "@every 1h" // Long interval so it won't fire during test
+	job.RunOnStartup = false   // Explicitly disabled
+
+	sc := NewSchedulerWithOptions(&TestLogger{}, nil, 10*time.Millisecond)
+	err := sc.AddJob(job)
+	require.NoError(t, err)
+
+	_ = sc.Start()
+
+	// Wait a bit to ensure job doesn't run
+	time.Sleep(150 * time.Millisecond)
+
+	// Job should NOT have run since RunOnStartup is false
+	assert.Equal(t, 0, job.Called())
+
+	_ = sc.Stop()
+}
+
+func TestSchedulerRunOnStartupMultipleJobs(t *testing.T) {
+	t.Parallel()
+
+	job1 := &TestJob{}
+	job1.Name = "startup-job-1"
+	job1.Schedule = "@every 1h"
+	job1.RunOnStartup = true
+
+	job2 := &TestJob{}
+	job2.Name = "startup-job-2"
+	job2.Schedule = "@every 1h"
+	job2.RunOnStartup = true
+
+	job3 := &TestJob{}
+	job3.Name = "no-startup-job"
+	job3.Schedule = "@every 1h"
+	job3.RunOnStartup = false
+
+	sc := NewSchedulerWithOptions(&TestLogger{}, nil, 10*time.Millisecond)
+	require.NoError(t, sc.AddJob(job1))
+	require.NoError(t, sc.AddJob(job2))
+	require.NoError(t, sc.AddJob(job3))
+
+	jobsCompleted := make(chan string, 3)
+	sc.SetOnJobComplete(func(jobName string, _ bool) {
+		select {
+		case jobsCompleted <- jobName:
+		default:
+		}
+	})
+
+	_ = sc.Start()
+
+	// Wait for both startup jobs to complete
+	completedCount := 0
+	timeout := time.After(500 * time.Millisecond)
+	for completedCount < 2 {
+		select {
+		case <-jobsCompleted:
+			completedCount++
+		case <-timeout:
+			t.Fatalf("Expected 2 startup jobs to complete, got %d", completedCount)
+		}
+	}
+
+	// Give a bit more time to ensure job3 didn't run
+	time.Sleep(100 * time.Millisecond)
+
+	assert.Equal(t, 1, job1.Called(), "job1 should have run once on startup")
+	assert.Equal(t, 1, job2.Called(), "job2 should have run once on startup")
+	assert.Equal(t, 0, job3.Called(), "job3 should not have run (no startup)")
+
+	_ = sc.Stop()
+}
+
+func TestSchedulerRunOnStartupNonBlocking(t *testing.T) {
+	t.Parallel()
+
+	// Create a job that takes a while to run
+	job := &TestJob{}
+	job.Schedule = "@every 1h"
+	job.RunOnStartup = true
+
+	sc := NewSchedulerWithOptions(&TestLogger{}, nil, 10*time.Millisecond)
+	err := sc.AddJob(job)
+	require.NoError(t, err)
+
+	// Start() should return quickly even though startup job takes 50ms
+	startTime := time.Now()
+	_ = sc.Start()
+	elapsed := time.Since(startTime)
+
+	// Start() should complete quickly (non-blocking)
+	// The startup job runs in a goroutine, so Start() returns immediately
+	assert.Less(t, elapsed, 30*time.Millisecond, "Start() should be non-blocking")
+
+	// Wait for job to complete
+	time.Sleep(150 * time.Millisecond)
+	assert.Equal(t, 1, job.Called())
+
+	_ = sc.Stop()
+}