// Package fallbacksync manages the scheduled job that runs
// `glab minder audit sync --all` when agent hooks fail to sync a session.
package fallbacksync
import (
"bytes"
"context"
"encoding/json"
"encoding/xml"
"errors"
"fmt"
"io"
"io/fs"
"os"
"os/exec"
"path/filepath"
"strconv"
"strings"
"time"
"gitlab.com/gitlab-org/cli/internal/api"
"gitlab.com/gitlab-org/cli/internal/cmdutils"
"gitlab.com/gitlab-org/cli/internal/commands/govern/internal/claudehooks"
"gitlab.com/gitlab-org/cli/internal/commands/govern/internal/gaig"
"gitlab.com/gitlab-org/cli/internal/commands/govern/internal/opencodeplugin"
"gitlab.com/gitlab-org/cli/internal/commands/version"
)
const (
launchdLabel = "com.gitlab.glab-govern-audit-sync"
systemdServiceName = "glab-govern-audit-sync.service"
systemdTimerName = "glab-govern-audit-sync.timer"
// Interval is how often the scheduled job runs.
Interval = 30 * time.Minute
)
// ErrUnsupportedOS is returned on platforms without launchd or systemd.
var ErrUnsupportedOS = errors.New("fallback periodic sync is supported only on macOS and Linux")
// Unit is a file that makes up the scheduled job.
type Unit struct {
Path string
Content string
}
// Job is what the scheduled job runs.
type Job struct {
GlabPath string
// ConfigDir is passed to the job as GLAB_CONFIG_DIR. launchd and systemd
// start jobs without the user's shell environment, so without it a
// custom GLAB_CONFIG_DIR or XDG_CONFIG_HOME would point the job at a
// different directory from the hooks.
ConfigDir string
}
// Supported reports whether the scheduled job can be installed on goos.
func Supported(goos string) bool {
return goos == "darwin" || goos == "linux"
}
// Units returns the files that define the scheduled job on goos.
func Units(goos, home string, job Job) ([]Unit, error) {
switch goos {
case "darwin":
return []Unit{{Path: launchdPlistPath(home), Content: launchdPlist(job)}}, nil
case "linux":
dir := systemdDir(home)
return []Unit{
{Path: filepath.Join(dir, systemdServiceName), Content: systemdService(job)},
{Path: filepath.Join(dir, systemdTimerName), Content: systemdTimer()},
}, nil
default:
return nil, ErrUnsupportedOS
}
}
// Description names the scheduled job for prompts and help text.
func Description(goos string) string {
switch goos {
case "darwin":
return fmt.Sprintf("a launchd agent (%s)", launchdPlistPath("~"))
case "linux":
return fmt.Sprintf("a systemd user timer (%s)", filepath.Join(systemdDir("~"), systemdTimerName))
default:
return "a scheduled job"
}
}
func launchdPlistPath(home string) string {
return filepath.Join(home, "Library", "LaunchAgents", launchdLabel+".plist")
}
func systemdDir(home string) string {
return filepath.Join(home, ".config", "systemd", "user")
}
func xmlEscape(s string) string {
var b strings.Builder
_ = xml.EscapeText(&b, []byte(s))
return b.String()
}
func launchdPlist(job Job) string {
return fmt.Sprintf(`
Label
%s
ProgramArguments
%s
minder
audit
sync
--all
--silent
EnvironmentVariables
GLAB_CONFIG_DIR
%s
StartInterval
%d
RunAtLoad
`, launchdLabel, xmlEscape(job.GlabPath), xmlEscape(job.ConfigDir), int(Interval.Seconds()))
}
// systemdQuoter escapes a value for a double-quoted systemd unit setting.
// systemd expands % specifiers even within quotes.
var systemdQuoter = strings.NewReplacer(`\`, `\\`, `"`, `\"`, "%", "%%")
var systemdUnquoter = strings.NewReplacer(`\\`, `\`, `\"`, `"`, "%%", "%")
func systemdService(job Job) string {
return fmt.Sprintf(`[Unit]
Description=GitLab AI agent governance fallback sync
[Service]
Type=oneshot
Environment="GLAB_CONFIG_DIR=%s"
ExecStart="%s" minder audit sync --all --silent
`, systemdQuoter.Replace(job.ConfigDir), systemdQuoter.Replace(job.GlabPath))
}
func systemdTimer() string {
return fmt.Sprintf(`[Unit]
Description=GitLab AI agent governance fallback sync timer
[Timer]
OnBootSec=5min
OnUnitActiveSec=%dmin
[Install]
WantedBy=timers.target
`, int(Interval.Minutes()))
}
// Install writes the job's files and loads the job, replacing any existing one.
func Install(ctx context.Context, executor cmdutils.Executor, goos, home string, job Job, uid int) error {
units, err := Units(goos, home, job)
if err != nil {
return err
}
for _, u := range units {
if err := os.MkdirAll(filepath.Dir(u.Path), 0o755); err != nil {
return fmt.Errorf("could not create %s: %w", filepath.Dir(u.Path), err)
}
if err := os.WriteFile(u.Path, []byte(u.Content), 0o644); err != nil {
return fmt.Errorf("could not write %s: %w", u.Path, err)
}
}
if err := load(ctx, executor, goos, units, uid); err != nil {
// Leaving the files would make doctor report a half-installed job,
// for example where there is no user launchd domain or systemd bus.
for _, u := range units {
if rmErr := os.Remove(u.Path); rmErr != nil && !errors.Is(rmErr, fs.ErrNotExist) {
err = errors.Join(err, rmErr)
}
}
return err
}
return nil
}
func load(ctx context.Context, executor cmdutils.Executor, goos string, units []Unit, uid int) error {
switch goos {
case "darwin":
// bootstrap fails if the label is already loaded, and bootout fails if it is not.
_, _ = executor.ExecWithCombinedOutput(ctx, "launchctl", []string{"bootout", launchdTarget(uid)}, nil)
return run(ctx, executor, "launchctl", "bootstrap", fmt.Sprintf("gui/%d", uid), units[0].Path)
default:
if err := run(ctx, executor, "systemctl", "--user", "daemon-reload"); err != nil {
return err
}
return run(ctx, executor, "systemctl", "--user", "enable", "--now", systemdTimerName)
}
}
// Uninstall unloads the job and removes its files. It reports whether any
// files were removed.
func Uninstall(ctx context.Context, executor cmdutils.Executor, goos, home string, uid int) (bool, error) {
units, err := Units(goos, home, Job{})
if err != nil {
return false, err
}
// Unloading fails when the job is not loaded, which is the state we want.
switch goos {
case "darwin":
_, _ = executor.ExecWithCombinedOutput(ctx, "launchctl", []string{"bootout", launchdTarget(uid)}, nil)
default:
_, _ = executor.ExecWithCombinedOutput(ctx, "systemctl", []string{"--user", "disable", "--now", systemdTimerName}, nil)
}
removed := false
for _, u := range units {
err := os.Remove(u.Path)
switch {
case err == nil:
removed = true
case errors.Is(err, fs.ErrNotExist):
default:
return removed, fmt.Errorf("could not remove %s: %w", u.Path, err)
}
}
if removed && goos == "linux" {
if err := run(ctx, executor, "systemctl", "--user", "daemon-reload"); err != nil {
return removed, err
}
}
return removed, nil
}
func launchdTarget(uid int) string {
return fmt.Sprintf("gui/%d/%s", uid, launchdLabel)
}
func run(ctx context.Context, executor cmdutils.Executor, name string, args ...string) error {
if out, err := executor.ExecWithCombinedOutput(ctx, name, args, nil); err != nil {
return fmt.Errorf("%s %s: %w\n%s", name, strings.Join(args, " "), err, out)
}
return nil
}
// ErrNotInstalled is returned by ReadInstalled and InstalledBinary when the
// job's files are absent.
var ErrNotInstalled = errors.New("fallback periodic sync is not installed")
// InstalledBinary returns the glab path that the installed job runs.
func InstalledBinary(goos, home string) (string, error) {
job, err := ReadInstalled(goos, home)
return job.GlabPath, err
}
// Installed describes the installed job.
type Installed struct {
// GlabPath is the glab that the job runs.
GlabPath string
// Legacy reports whether the job runs glab govern, as jobs that glab
// versions before the rename to glab minder installed do.
Legacy bool
}
// ReadInstalled reads the installed job.
func ReadInstalled(goos, home string) (Installed, error) {
units, err := Units(goos, home, Job{})
if err != nil {
return Installed{}, err
}
data, err := os.ReadFile(units[0].Path)
if errors.Is(err, fs.ErrNotExist) {
return Installed{}, ErrNotInstalled
}
if err != nil {
return Installed{}, err
}
if goos == "darwin" {
path, err := plistProgram(data)
return Installed{GlabPath: path, Legacy: strings.Contains(string(data), "govern")}, err
}
for line := range strings.Lines(string(data)) {
rest, ok := strings.CutPrefix(line, `ExecStart="`)
if !ok {
continue
}
if path, ok := cutQuoted(rest); ok {
legacy := strings.HasPrefix(rest[len(path)+1:], " govern audit sync ")
return Installed{GlabPath: systemdUnquoter.Replace(path), Legacy: legacy}, nil
}
break
}
return Installed{}, fmt.Errorf("could not find ExecStart in %s", units[0].Path)
}
// cutQuoted returns s up to its first unescaped double quote.
func cutQuoted(s string) (string, bool) {
for i := 0; i < len(s); i++ {
switch s[i] {
case '\\':
i++
case '"':
return s[:i], true
}
}
return "", false
}
func plistProgram(data []byte) (string, error) {
var doc struct {
Dict struct {
Keys []string `xml:"key"`
Arrays []struct {
Strings []string `xml:"string"`
} `xml:"array"`
} `xml:"dict"`
}
if err := xml.Unmarshal(data, &doc); err != nil {
return "", fmt.Errorf("could not parse plist: %w", err)
}
if len(doc.Dict.Arrays) == 0 || len(doc.Dict.Arrays[0].Strings) == 0 {
return "", errors.New("plist has no ProgramArguments")
}
return doc.Dict.Arrays[0].Strings[0], nil
}
// JobState is what the system reports about the installed job.
type JobState struct {
Loaded bool
// Ran reports whether the job has finished at least once since it was loaded.
Ran bool
ExitCode int
}
// State asks launchd or systemd whether the job is loaded and how its last
// run exited. It catches runs that fail before they can write a Status, such
// as a glab binary that does not support --all.
func State(ctx context.Context, executor cmdutils.Executor, goos string, uid int) (JobState, error) {
switch goos {
case "darwin":
out, err := executor.ExecWithCombinedOutput(ctx, "launchctl", []string{"print", launchdTarget(uid)}, nil)
if exited(err) {
// launchctl print exits non-zero when the label is not loaded.
return JobState{}, nil
}
if err != nil {
return JobState{}, fmt.Errorf("launchctl print: %w", err)
}
return launchdState(string(out)), nil
case "linux":
_, err := executor.ExecWithCombinedOutput(ctx, "systemctl", []string{"--user", "is-active", "--quiet", systemdTimerName}, nil)
if exited(err) {
return JobState{}, nil
}
if err != nil {
return JobState{}, fmt.Errorf("systemctl --user is-active: %w", err)
}
out, err := executor.ExecWithCombinedOutput(ctx, "systemctl", []string{"--user", "show", systemdServiceName, "--property=ExecMainStartTimestampMonotonic,ExecMainStatus"}, nil)
if err != nil {
return JobState{}, fmt.Errorf("systemctl --user show %s: %w\n%s", systemdServiceName, err, out)
}
return systemdState(string(out)), nil
default:
return JobState{}, ErrUnsupportedOS
}
}
// exited reports whether err is a command exiting with a non-zero status, as
// opposed to the command failing to start.
func exited(err error) bool {
var exitErr *exec.ExitError
return errors.As(err, &exitErr)
}
func launchdState(out string) JobState {
state := JobState{Loaded: true}
for line := range strings.Lines(out) {
value, ok := strings.CutPrefix(strings.TrimSpace(line), "last exit code = ")
if !ok {
continue
}
// The value is "(never exited)" before the first run.
first, _, _ := strings.Cut(value, " ")
if code, err := strconv.Atoi(first); err == nil {
state.Ran = true
state.ExitCode = code
}
break
}
return state
}
func systemdState(out string) JobState {
state := JobState{Loaded: true}
for line := range strings.Lines(out) {
key, value, _ := strings.Cut(strings.TrimSpace(line), "=")
switch key {
case "ExecMainStartTimestampMonotonic":
state.Ran = value != "" && value != "0"
case "ExecMainStatus":
state.ExitCode, _ = strconv.Atoi(value)
}
}
return state
}
// Status records the outcome of the most recent `glab minder audit sync --all` run.
type Status struct {
StartedAt time.Time `json:"started_at"`
FinishedAt time.Time `json:"finished_at"`
Paused []string `json:"paused,omitempty"`
// GovernanceNotEnabled lists the projects, as host/path, whose sessions
// were not synced because GitLab has AI agent governance turned off for
// them. These are expected for a user who works in many projects, so they
// are not errors.
GovernanceNotEnabled []string `json:"governance_not_enabled,omitempty"`
// ProjectNotFound lists the projects, as host/path, that GitLab answered
// 404 for: deleted, renamed, or not visible to the user. Like
// GovernanceNotEnabled, these are expected and are not errors.
ProjectNotFound []string `json:"project_not_found,omitempty"`
// NoToken lists the GitLab hosts the run found no token for and could not
// sync a session on. It looked up their projects anonymously, so their
// private projects are in ProjectNotFound too.
NoToken []string `json:"no_token,omitempty"`
// AgentTypeNotSupported lists agent types a GitLab host does not accept
// yet, as " on ". Their sessions are not uploaded, then or
// after an upgrade.
AgentTypeNotSupported []string `json:"agent_type_not_supported,omitempty"`
// Skipped explains why discovered sessions were not synced, for example
// a Cursor workspace that matches several directories.
Skipped []string `json:"skipped,omitempty"`
SessionsSynced int `json:"sessions_synced"`
SessionsCompleted int `json:"sessions_completed"`
EventsPosted int `json:"events_posted"`
// EventsTooLarge counts events skipped because GitLab cannot accept them.
EventsTooLarge int `json:"events_too_large,omitempty"`
Errors []string `json:"errors,omitempty"`
}
// ErrNoStatus is returned by ReadStatus when no run has been recorded.
var ErrNoStatus = errors.New("no fallback sync run recorded")
func statusPath() string {
return filepath.Join(gaig.StateDir(), "fallback-sync-status.json")
}
// WriteStatus replaces the recorded status of the last run.
func WriteStatus(s Status) error {
path := statusPath()
if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
return err
}
data, err := json.Marshal(s) //nolint:forbidigo // writing to disk, not stdout
if err != nil {
return err
}
return os.WriteFile(path, data, 0o600)
}
// ReadStatus returns the recorded status of the last run.
func ReadStatus() (*Status, error) {
data, err := os.ReadFile(statusPath())
if errors.Is(err, fs.ErrNotExist) {
return nil, ErrNoStatus
}
if err != nil {
return nil, err
}
var s Status
if err := json.Unmarshal(data, &s); err != nil {
return nil, fmt.Errorf("could not parse fallback sync status: %w", err)
}
return &s, nil
}
// DiscoverableAgents are the agents whose sessions the scheduled job can find
// by scanning their transcripts, without hooks.
var DiscoverableAgents = []string{"codex", "cursor"}
// HookAgents are the agents that glab installs a hook or plugin for, which
// syncs their sessions as they run.
var HookAgents = []string{"claude-code", "opencode"}
func discoveredAgentsPath() string {
return filepath.Join(gaig.StateDir(), "discovered-agents.json")
}
func hookAgentsPath() string {
return filepath.Join(gaig.StateDir(), "hook-agents.json")
}
// SetDiscoveredAgents replaces the agents whose sessions the scheduled job
// discovers.
func SetDiscoveredAgents(agents []string) error {
return writeJSON(discoveredAgentsPath(), agents)
}
// agentsListError is an error reading a file in which setup lists the agents
// it set up. Uninstalling removes those files.
type agentsListError struct{ err error }
func (e *agentsListError) Error() string { return e.err.Error() }
func (e *agentsListError) Unwrap() error { return e.err }
// AgentsReadFix says how to fix err, an error working out which agents are set
// up. Uninstalling only helps when setup's own lists are unreadable, because
// it doesn't change the Claude Code settings or the OpenCode plugin.
func AgentsReadFix(err error) string {
if errors.As(err, new(*agentsListError)) {
return "fix it, or run 'glab minder setup --uninstall' to start again"
}
return "fix it, then run 'glab minder setup' again"
}
// DiscoveredAgents returns the agents whose sessions the scheduled job
// discovers. None are discovered until setup enables them.
func DiscoveredAgents() ([]string, error) {
agents, _, err := readAgents(discoveredAgentsPath())
return agents, err
}
// SetHookAgents records the agents setup installed a hook or plugin for.
func SetHookAgents(agents []string) error {
return writeJSON(hookAgentsPath(), agents)
}
// ForgetHookAgents forgets the agents recorded by SetHookAgents.
func ForgetHookAgents() error {
return ignoreNotExist(os.Remove(hookAgentsPath()))
}
// RecordedHookAgents returns the agents setup recorded with SetHookAgents, and
// false if setup has recorded nothing. ResolvedHookAgents also covers glab
// versions that did not record them.
func RecordedHookAgents() ([]string, bool, error) {
return readAgents(hookAgentsPath())
}
// ResolvedHookAgents returns the agents that setup has set up a hook or plugin
// for. glab versions that did not record them are judged by what is installed:
// the Claude Code hooks in the settings file at claudeSettings, and the
// OpenCode plugin.
func ResolvedHookAgents(claudeSettings string) ([]string, error) {
agents, recorded, err := RecordedHookAgents()
if err != nil || recorded {
return agents, err
}
agents = []string{}
claude, err := claudehooks.SyncHookInstalled(claudeSettings)
if err != nil {
return nil, err
}
if claude {
agents = append(agents, "claude-code")
}
plugin, err := opencodeplugin.Path()
if err != nil {
return nil, err
}
switch state, err := opencodeplugin.Check(plugin); {
case err != nil:
return nil, err
case state == opencodeplugin.Current, state == opencodeplugin.Outdated:
agents = append(agents, "opencode")
}
return agents, nil
}
// DefaultHookAgents returns the agents a setup without --agents sets up: those
// set up earlier, or Claude Code when no agent is set up at all.
func DefaultHookAgents(setUp, discovered []string) []string {
if len(setUp) == 0 && len(discovered) == 0 {
return []string{"claude-code"}
}
return setUp
}
// AgentSetup records when setup first set up an agent.
type AgentSetup struct {
SetUpAt time.Time `json:"set_up_at"`
// History reports that the user agreed to upload the agent's activity
// from before SetUpAt too.
History bool `json:"history,omitempty"`
}
// AgentSetups are the recorded setups, by agent. Agents set up by glab
// versions that did not record them are missing.
type AgentSetups map[string]AgentSetup
// UploadsFrom returns the time from which agent's activity is uploaded, or the
// zero time when there is no such limit: the user opted in to its history, or
// setup did not record it. Uploading history for an agent set up before glab
// recorded setups keeps what that user agreed to, until they run setup again.
func (s AgentSetups) UploadsFrom(agent string) time.Time {
setup, ok := s[agent]
if !ok || setup.History {
return time.Time{}
}
return setup.SetUpAt
}
func agentSetupsPath() string {
return filepath.Join(gaig.StateDir(), "agent-setups.json")
}
// ReadAgentSetups returns the recorded agent setups.
func ReadAgentSetups() (AgentSetups, error) {
setups := AgentSetups{}
if _, err := readJSON(agentSetupsPath(), &setups); err != nil {
return nil, err
}
return setups, nil
}
// SetAgentSetups replaces the recorded agent setups.
func SetAgentSetups(setups AgentSetups) error {
return writeJSON(agentSetupsPath(), setups)
}
func readAgents(path string) ([]string, bool, error) {
var agents []string
recorded, err := readJSON(path, &agents)
if err != nil {
return nil, false, err
}
return agents, recorded, nil
}
func writeJSON(path string, v any) error {
if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
return err
}
data, err := json.Marshal(v) //nolint:forbidigo // writing to disk, not stdout
if err != nil {
return err
}
return gaig.WriteFileAtomic(path, data)
}
func ignoreNotExist(err error) error {
if errors.Is(err, fs.ErrNotExist) {
return nil
}
return err
}
// readJSON decodes the file at path into v, and reports false if there is no
// such file.
func readJSON(path string, v any) (bool, error) {
data, err := os.ReadFile(path)
if errors.Is(err, fs.ErrNotExist) {
return false, nil
}
if err != nil {
return false, &agentsListError{err}
}
if err := json.Unmarshal(data, v); err != nil {
return false, &agentsListError{fmt.Errorf("could not parse %s: %w", path, err)}
}
return true, nil
}
// BuildVersion returns what `glab version` prints for the build described by
// info.
func BuildVersion(info api.BuildInfo) string {
return strings.TrimSpace(version.Scheme(info.Version, info.Commit))
}
// BinaryVersion runs `glab version` with the glab binary at path.
func BinaryVersion(ctx context.Context, executor cmdutils.Executor, path string) (string, error) {
var stdout bytes.Buffer
if err := executor.ExecWithIO(ctx, path, []string{"version"}, nil, nil, &stdout, io.Discard); err != nil {
return "", err
}
return strings.TrimSpace(stdout.String()), nil
}