ghasetup

type Catalog struct {
	Version int    `json:"version"`
	Tools   []Tool `json:"tools"`
}

type Detect struct {
	// Always marks a tool that works on any repository: the SBOM producers,
	// the secret scanners, the multi-language SAST engines.
	Always bool `json:"always,omitempty"`

	// Files are basenames or directory names that must exist somewhere in the
	// tree. A match on any one of them selects the tool.
	Files []string `json:"files,omitempty"`

	// Extensions are file suffixes, matched the same way.
	Extensions []string `json:"extensions,omitempty"`

	// Manual keeps a tool out of --detect entirely. These are the ones that
	// need something the repository cannot supply: a licence key (Snyk), or a
	// live target the operator must nominate (ZAP, Nuclei). Selecting one by
	// name still works.
	Manual bool `json:"manual,omitempty"`
}

type Options struct {
	// SelfHostedLabels, when set, replaces `ubuntu-latest` on every job.
	SelfHostedLabels []string
	// OrgID is written into the publish job's env as a literal only when the
	// caller explicitly asks; otherwise the secret reference is used, which is
	// what almost every repository wants.
	OrgIDLiteral string

	// Triggers are the workflow's `on:` events. Empty means push +
	// workflow_dispatch, which is what this command has always written.
	//
	// It is worth choosing deliberately once a repository runs more than a
	// handful of scanners: a full detected set is twenty-odd jobs, and on a
	// small runner pool "on every push" turns a two-minute build into an hour
	// of queue for everyone else.
	Triggers []string

	// ScheduleCron is the five-field expression used when Triggers includes
	// "schedule". Leave it empty and the expression is derived from RepoSlug,
	// which is what staggers the fleet; set it only to pin one repository to a
	// time somebody actually cares about.
	ScheduleCron string

	// RepoSlug is "owner/repo", used to derive the schedule when ScheduleCron
	// is empty. Empty falls back to DefaultScheduleCron.
	RepoSlug string
}

type Remote struct {
	// URL is the raw origin URL, empty when there is no origin.
	URL string
	// Host is the parsed host ("github.com", "gitlab.com", …), empty when the
	// URL could not be parsed.
	Host string
	// Slug is "owner/repo" when the URL could be parsed.
	Slug string
	// IsGitHub reports whether this is github.com or a GitHub Enterprise host.
	IsGitHub bool
}

type RepoSignals struct {
	Files      map[string]bool
	Extensions map[string]bool
}

type Step struct {
	Name string `json:"name,omitempty"`
	ID   string `json:"id,omitempty"`
	// If is a GitHub expression written verbatim into the step's `if:`. A step
	// that cannot run everywhere is gated on a preceding detection step rather
	// than left to hang the job on a runner that cannot support it.
	If   string            `json:"if,omitempty"`
	Uses string            `json:"uses,omitempty"`
	Run  string            `json:"run,omitempty"`
	With map[string]any    `json:"with,omitempty"`
	Env  map[string]string `json:"env,omitempty"`
	// TimeoutMinutes caps one step. The job cap cannot rescue a step that
	// blocks on a prompt that never arrives: the job spends its whole budget
	// inside setup and dies having run no scanner at all.
	TimeoutMinutes int `json:"timeoutMinutes,omitempty"`
}

type Tool struct {
	ID          string   `json:"id"`
	Name        string   `json:"name"`
	JobName     string   `json:"jobName"`
	Category    string   `json:"category"`
	Description string   `json:"description"`
	Artifact    string   `json:"artifact"`
	Paths       []string `json:"paths"`
	Note        string   `json:"note,omitempty"`

	// TimeoutMinutes overrides DefaultJobTimeoutMinutes for this tool.
	//
	// Set it only where the measured runtime says the default is wrong: too
	// tight and a legitimate slow scan is killed, too loose and a hung one
	// holds a runner until GitHub's six-hour ceiling. Zero means "use the
	// default", which is the right answer for almost every scanner.
	TimeoutMinutes int `json:"timeoutMinutes,omitempty"`

	Detect Detect `json:"detect"`
	Steps  []Step `json:"steps"`
}