launchd

README

launchd

Go package (package launchd) that renders parameterised macOS launchd agent definitions from a Job spec via the embedded job.plist.tmpl, and writes them to a LaunchAgents directory idempotently. The per-vault Job specs are built in install (VaultJobs); install also bootstraps them via launchctl.

Jobs and TCC

The stock per-vault jobs (install.VaultJobs):

Job	Program[0]	Schedule	What it runs
web	hebb	RunAtLoad, KeepAlive	hebb serve (the local web UI).
daily-digest	hebb	weekdays 08:00	hebb digest (index refresh + digest note, pure Go).
action-review	python3	Sundays 07:03	generate-action-review.py.
update-check	hebb	Mondays 09:00	hebb update --check.

Every job's Program[0] is a grantable binary (the hebb binary or an absolute python3), never a shell script or interpreter shim. macOS TCC attributes a job's Full Disk Access grant to Program[0]: a shell wrapper has no grantable identity, so its child interpreter blocks indefinitely on reads into protected vault folders. hebb doctor's launchd-tcc check lints installed plists for this. install prefers a stable symlink (e.g. /opt/homebrew/bin/hebb) over a versioned Homebrew Cellar path so the grant survives an upgrade.

See ../ARCHITECTURE.md for how this fits the install flow.

Documentation

Overview

Package launchd renders parameterised macOS launchd job definitions (plist files) and writes them to a LaunchAgents directory. It is the mechanism; callers supply the per-vault Job specs.

Index

• func Render(j Job) ([]byte, error)
• func WriteJobs(jobs []Job, dstDir string) ([]string, error)
• type CalInterval
• type EnvVar
• type Job

Functions

func Render

func Render(j Job) ([]byte, error)

Render produces the plist bytes for a job.

func WriteJobs

func WriteJobs(jobs []Job, dstDir string) ([]string, error)

WriteJobs renders each job to <dstDir>/<label>.plist, creating dstDir if needed. It returns the labels whose plist was created or changed (idempotent: unchanged files are left alone).

Types

type CalInterval

type CalInterval struct {
	Weekday, Hour, Minute int
}

CalInterval is one StartCalendarInterval entry. A field set to -1 is omitted, so {Weekday: -1, Hour: 7, Minute: 3} means "07:03 every day".

type EnvVar

type EnvVar struct {
	Key, Value string
}

EnvVar is one EnvironmentVariables entry. A slice (not a map) keeps rendering deterministic for idempotent writes.

type Job

type Job struct {
	Label      string
	Program    []string // ProgramArguments
	WorkingDir string
	EnvVars    []EnvVar
	RunAtLoad  bool
	KeepAlive  bool
	Throttle   int           // ThrottleInterval seconds; 0 omits the key
	Schedule   []CalInterval // 0 = none, 1 = single dict, >1 = array
	LogPath    string
}

Job is a single launchd agent definition.