Documentation
¶
Overview ¶
Package agentcli is what devctl's agent-facing commands share: the JSON envelope every one of them prints as its only stdout output, the exit-code table, the clock that DEVCTL_TIME_SCALE speeds up for tests, the endpoint configuration read from the environment and the --progress writer.
An agent-facing command blocks, prints one JSON document on stdout when it finishes and nothing else, and exits with a code from the table below. Progress, when asked for with --progress, goes to stderr.
Index ¶
Constants ¶
const ( // EnvGitHubAPIURL is the GitHub REST API (https://api.github.com). EnvGitHubAPIURL = "DEVCTL_GITHUB_API_URL" // EnvGitHubOAuthURL is the host of GitHub's device-flow endpoints // (https://github.com). EnvGitHubOAuthURL = "DEVCTL_GITHUB_OAUTH_URL" // EnvCircleCIAPIURL is the CircleCI API v2 (https://circleci.com/api/v2). EnvCircleCIAPIURL = "DEVCTL_CIRCLECI_API_URL" // EnvCircleCIOAuthURL is CircleCI's OAuth issuer (https://app.circleci.com). EnvCircleCIOAuthURL = "DEVCTL_CIRCLECI_OAUTH_URL" // EnvRegistryPublic is the public registry, probed anonymously. EnvRegistryPublic = "DEVCTL_REGISTRY_PUBLIC" // EnvRegistryPrivate is the private registry, read with the docker keychain. EnvRegistryPrivate = "DEVCTL_REGISTRY_PRIVATE" // EnvRegistryInsecure set to 1 talks plain HTTP to the registries (tests only). EnvRegistryInsecure = "DEVCTL_REGISTRY_INSECURE" // EnvKeyringFile names a 0600 JSON file that replaces the OS keychain // (tests only). EnvKeyringFile = "DEVCTL_KEYRING_FILE" )
The environment variables that point an agent-facing command at another site or at a test double. Every default is the production endpoint.
const ( // ExitOK: the wait ended green, the merge happened, the release is available. ExitOK = 0 // ExitRed: a check is red or the tag's CI failed. ExitRed = 1 // ExitTimeout: the deadline passed; the document names what was unfinished. ExitTimeout = 2 // ExitNotApplicable: draft, closed, conflicting, behind a strict base, a // version that does not resolve. ExitNotApplicable = 3 // ExitRequiredMissing: a required context never reported. ExitRequiredMissing = 4 // ExitRefused: the command declines (another author, an opt-out). ExitRefused = 5 // ExitUsage: wrong usage or a tooling failure. ExitUsage = 7 // ExitAuthRequired: no usable token; the reason names `devctl auth login`. ExitAuthRequired = 8 )
The exit codes of every agent-facing command. 6 is unused.
const EnvTimeScale = "DEVCTL_TIME_SCALE"
EnvTimeScale multiplies every sleep and timeout of an agent-facing command. Production runs at 1; the e2e suite runs at 0.001 so a five-minute wait takes 300 milliseconds. Timestamps are never scaled.
const SchemaVersion = 1
SchemaVersion is the version of the envelope; a breaking change to any command's document bumps it.
Variables ¶
This section is empty.
Functions ¶
func Exit ¶
Exit maps err to the process exit code: 0 for nil, the code of an ExitCoder anywhere in the chain, ExitUsage for any other error.
func ProgressFlag ¶
ProgressFlag registers --progress on cmd, bound to v.
Types ¶
type Clock ¶
type Clock struct {
// contains filtered or unexported fields
}
Clock is the time source of a command: the current time, and sleeps and timeouts scaled by EnvTimeScale.
func NewClock ¶
NewClock is a clock with an explicit scale and time source; now nil means the wall clock.
func SystemClock ¶
SystemClock is the wall clock at the scale of EnvTimeScale (1 when unset).
func (Clock) Scaled ¶
Scaled is d at the clock's scale, never below one millisecond for a positive d.
type Endpoints ¶
type Endpoints struct {
GitHubAPIURL string
GitHubOAuthURL string
CircleCIAPIURL string
CircleCIOAuthURL string
RegistryPublic string
RegistryPrivate string
RegistryInsecure bool
// KeyringFile is empty for the OS keychain.
KeyringFile string
}
Endpoints is where the agent-facing commands talk to.
func DefaultEndpoints ¶
func DefaultEndpoints() Endpoints
DefaultEndpoints are the production endpoints.
func EndpointsFromEnv ¶
func EndpointsFromEnv() Endpoints
EndpointsFromEnv are the defaults with every set variable applied. URLs lose their trailing slash.
type Envelope ¶
type Envelope struct {
Command string `json:"command"`
SchemaVersion int `json:"schemaVersion"`
ExitCode int `json:"exitCode"`
Verdict Verdict `json:"verdict"`
Reason string `json:"reason"`
Warnings []string `json:"warnings"`
StartedAt time.Time `json:"startedAt"`
FinishedAt time.Time `json:"finishedAt"`
}
Envelope is the head of every command's JSON document. A command's document embeds it and adds its own fields.
func NewEnvelope ¶
NewEnvelope starts the envelope of command at now.
func (Envelope) Err ¶
Err is the error a command returns to cobra after emitting its document: nil on exit 0, otherwise an *ExitError carrying the envelope's code. The process exit code follows it; nothing is printed for it, the document was.
type ExitError ¶
ExitError is an outcome with its exit code: what a command returns after its document is written, and what any error of the table can be expressed as.
func NewExitError ¶
NewExitError returns an ExitError with a formatted reason.
func (*ExitError) ExitVerdict ¶
ExitVerdict implements ExitCoder.
type Progress ¶
type Progress struct {
// contains filtered or unexported fields
}
Progress writes one line per step to stderr when --progress is set and nothing otherwise. Stdout stays the document's.
func NewProgress ¶
NewProgress writes to w; a nil w or enabled false discards.
type Verdict ¶
type Verdict string
Verdict is the one-word outcome of a command.
const ( VerdictGreen Verdict = "green" VerdictRed Verdict = "red" VerdictTimeout Verdict = "timeout" VerdictNotApplicable Verdict = "not_applicable" VerdictRequiredMissing Verdict = "required_missing" VerdictRefused Verdict = "refused" VerdictAvailable Verdict = "available" VerdictCIFailed Verdict = "ci_failed" VerdictAuthRequired Verdict = "auth_required" VerdictUsage Verdict = "usage" )
The verdicts a command reports.
Source Files