cron

Documentation

Index

• func AppendHistory(entry RunEntry) error
• func LastRun(entries []RunEntry, taskName string) time.Time
• func Register(e *sdk.Extension)
• func RotateHistory() error
• func Run(ctx context.Context, opts RunOptions) error
• func SaveConfig(cfg Config) error
• type Config
  • func DefaultConfig() Config
  • func LoadConfig() Config
• type DailySchedule
  • func (s DailySchedule) Next(from time.Time) time.Time
  • func (s DailySchedule) ShouldRun(lastRun time.Time) bool
  • func (s DailySchedule) String() string
• type ExecuteResult
  • func Execute(ctx context.Context, name string, task TaskConfig) ExecuteResult
• type IntervalSchedule
  • func (s IntervalSchedule) Next(from time.Time) time.Time
  • func (s IntervalSchedule) ShouldRun(lastRun time.Time) bool
  • func (s IntervalSchedule) String() string
• type Lock
  • func Acquire() (*Lock, error)
  • func (l *Lock) Release()
• type RunEntry
  • func ReadHistory() ([]RunEntry, error)
• type RunOptions
• type Schedule
  • func ParseSchedule(spec ScheduleSpec) (Schedule, error)
• type ScheduleSpec
• type TaskConfig
  • func (t TaskConfig) IsEnabled() bool
• type TaskSummary
  • func ListTasks() ([]TaskSummary, error)
• type WeeklySchedule
  • func (s WeeklySchedule) Next(from time.Time) time.Time
  • func (s WeeklySchedule) ShouldRun(lastRun time.Time) bool
  • func (s WeeklySchedule) String() string

Functions

func AppendHistory

func AppendHistory(entry RunEntry) error

AppendHistory atomically appends a run entry to the JSONL file.

func LastRun

func LastRun(entries []RunEntry, taskName string) time.Time

LastRun returns the most recent successful run time for a task. Returns zero time if no successful run found.

func Register

func Register(e *sdk.Extension)

Register registers the cron extension's commands, tools, and event handlers.

func RotateHistory

func RotateHistory() error

RotateHistory trims the history file to maxHistoryLines. Called after appending, only when line count exceeds threshold.

func Run

func Run(ctx context.Context, opts RunOptions) error

Run executes the cron cycle: load config, check schedules, execute due tasks.

func SaveConfig

func SaveConfig(cfg Config) error

SaveConfig writes the config to ~/.config/piglet/extensions/cron/schedules.yaml atomically.

Types

type Config

type Config struct {
	Tasks map[string]TaskConfig `yaml:"tasks"`
}

Config is the top-level schedules.yaml structure.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns an empty config (no tasks).

func LoadConfig

func LoadConfig() Config

LoadConfig loads schedules.yaml from ~/.config/piglet/.

type DailySchedule

type DailySchedule struct {
	Hour   int
	Minute int
}

DailySchedule runs once per day at a specific time.

func (DailySchedule) Next

func (s DailySchedule) Next(from time.Time) time.Time

func (DailySchedule) ShouldRun

func (s DailySchedule) ShouldRun(lastRun time.Time) bool

func (DailySchedule) String

func (s DailySchedule) String() string

type ExecuteResult

type ExecuteResult struct {
	Success    bool
	DurationMs int64
	Error      string
	Output     string // truncated stdout/stderr for shell, response for webhook
}

ExecuteResult holds the outcome of a task execution.

func Execute

func Execute(ctx context.Context, name string, task TaskConfig) ExecuteResult

Execute runs a task's action with the given context and timeout.

type IntervalSchedule

type IntervalSchedule struct {
	Interval time.Duration
}

IntervalSchedule runs every fixed duration.

func (IntervalSchedule) Next

func (s IntervalSchedule) Next(from time.Time) time.Time

func (IntervalSchedule) ShouldRun

func (s IntervalSchedule) ShouldRun(lastRun time.Time) bool

func (IntervalSchedule) String

func (s IntervalSchedule) String() string

type Lock

type Lock struct {
	// contains filtered or unexported fields
}

Lock represents a file lock.

func Acquire

func Acquire() (*Lock, error)

Acquire attempts to get an exclusive lock. Returns error if already locked.

func (*Lock) Release

func (l *Lock) Release()

Release releases the file lock.

type RunEntry

type RunEntry struct {
	Task       string `json:"task"`
	RanAt      string `json:"ran_at"` // RFC3339
	Success    bool   `json:"success"`
	DurationMs int64  `json:"duration_ms"`
	Error      string `json:"error,omitempty"`
}

RunEntry is a single line in cron-history.jsonl.

func ReadHistory

func ReadHistory() ([]RunEntry, error)

ReadHistory reads all entries from cron-history.jsonl.

type RunOptions

type RunOptions struct {
	Verbose  bool
	TaskName string // empty = run all due tasks
	Force    bool   // bypass schedule check
}

RunOptions configures a cron run.

type Schedule

type Schedule interface {
	ShouldRun(lastRun time.Time) bool
	Next(from time.Time) time.Time
	String() string
}

Schedule determines when a task should run.

func ParseSchedule

func ParseSchedule(spec ScheduleSpec) (Schedule, error)

ParseSchedule converts a ScheduleSpec into a Schedule.

type ScheduleSpec

type ScheduleSpec struct {
	Every   string `yaml:"every"`    // duration string: "10m", "1h"
	DailyAt string `yaml:"daily_at"` // "HH:MM" in local time
	Weekly  string `yaml:"weekly"`   // "monday 09:00"
}

ScheduleSpec holds the schedule definition from YAML. Exactly one field should be set.

type TaskConfig

type TaskConfig struct {
	Action   string            `yaml:"action"`  // "shell", "prompt", "webhook"
	Command  string            `yaml:"command"` // for action=shell
	Prompt   string            `yaml:"prompt"`  // for action=prompt
	URL      string            `yaml:"url"`     // for action=webhook
	Method   string            `yaml:"method"`  // HTTP method for webhook (default POST)
	Body     string            `yaml:"body"`    // HTTP body for webhook
	Headers  map[string]string `yaml:"headers"` // HTTP headers for webhook
	Schedule ScheduleSpec      `yaml:"schedule"`
	Timeout  string            `yaml:"timeout"`  // duration string, default "5m"
	Enabled  *bool             `yaml:"enabled"`  // nil = true (enabled by default)
	WorkDir  string            `yaml:"work_dir"` // for action=shell
	Env      map[string]string `yaml:"env"`      // extra env vars for shell
}

TaskConfig defines a single scheduled task.

func (TaskConfig) IsEnabled

func (t TaskConfig) IsEnabled() bool

IsEnabled returns whether the task is enabled (default true).

type TaskSummary

type TaskSummary struct {
	Name     string
	Action   string
	Schedule string
	Enabled  bool
	LastRun  time.Time
	NextRun  time.Time
	Overdue  bool
}

TaskSummary provides a view of a task's state.

func ListTasks

func ListTasks() ([]TaskSummary, error)

ListTasks returns a summary of all configured tasks with their last run info.

type WeeklySchedule

type WeeklySchedule struct {
	Weekday time.Weekday
	Hour    int
	Minute  int
}

WeeklySchedule runs once per week on a specific day and time.

func (WeeklySchedule) Next

func (s WeeklySchedule) Next(from time.Time) time.Time

func (WeeklySchedule) ShouldRun

func (s WeeklySchedule) ShouldRun(lastRun time.Time) bool

func (WeeklySchedule) String

func (s WeeklySchedule) String() string