config

type AuthMode int

type Branch struct {
	// Template shapes the name from {prefix}, {key} and {slug}; empty keeps the
	// default "{prefix}/{key}-{slug}". It must contain {key}, because everything
	// the interface derives from a branch reads the issue key back out of it.
	Template string `json:"template"`
	// Prefixes maps an issue type to its branch prefix, such as {"bug": "bugfix"};
	// the type is matched without regard to case. A type not listed takes
	// DefaultPrefix. Configuring this replaces the built-in map rather than adding
	// to it, so what the file says is the whole rule.
	Prefixes map[string]string `json:"prefixes"`
	// DefaultPrefix is the prefix for a type not in Prefixes; empty keeps "feat".
	DefaultPrefix string `json:"default_prefix"`
	// SlugLimit caps the summary slug in a branch name, in characters; zero keeps
	// the built-in 48.
	SlugLimit int `json:"slug_limit"`
}

type Commit struct {
	// DefaultScope pre-fills the scope field when no kept draft has one. It must
	// be a scope a Conventional Commit subject would accept, or the composer would
	// open already flagged.
	DefaultScope string `json:"default_scope"`
	// Types are the commit types the composer offers and validates against, in the
	// order to offer them; empty keeps the built-in Conventional Commit types.
	// Each is a lowercase word, matched as a branch prefix too.
	Types []string `json:"types"`
	// SubjectLimit is the longest a subject may be, in characters; zero keeps the
	// built-in 72.
	SubjectLimit int `json:"subject_limit"`
	// RefsTrailer labels the issue trailer added to a commit body, such as
	// "Closes"; empty keeps "Refs". It is a single trailer word, no colon.
	RefsTrailer string `json:"refs_trailer"`
}

type Config struct {
	// Version is the file format's version; empty means the current one. It is
	// first so `config init` writes it at the top of the file.
	Version     string      `json:"version"`
	Jira        Jira        `json:"jira"`
	Messaging   Messaging   `json:"messaging"`
	Forge       Forge       `json:"forge"`
	UI          UI          `json:"ui"`
	Timing      Timing      `json:"timing"`
	Branch      Branch      `json:"branch"`
	Commit      Commit      `json:"commit"`
	PullRequest PullRequest `json:"pull_request"`
	Store       Store       `json:"store"`
	Taskwarrior Taskwarrior `json:"taskwarrior"`
	Issues      Issues      `json:"issues"`
	// Path is the file a save of this configuration writes: the repository's
	// file when there is one, otherwise the home directory's. It is not part of
	// the file format.
	Path string `json:"-"`
	// Files are the files this configuration was read from, the repository's
	// layered over the home directory's. Not part of the file format either.
	Files Files `json:"-"`
}

type Credential string

type Edit struct {
	// Files are the configuration files the read was made from.
	Files Files
	// Read is the configuration the editor was seeded from, unmasked.
	Read Config
	// Over is the revision of the files the read found.
	Over Revision
	// Edited is what the editor holds: a credential left masked or empty
	// stands for Read's.
	Edited Config
	// Removed are the credentials the editor removed: each is written empty,
	// whatever Edited holds for it.
	Removed []Credential
	// PlaceSlackCredentials keeps a Slack user token's secrets, typed into the
	// editor, where the configuration keeps them, and answers the configuration
	// to write. Nil keeps them in the file.
	PlaceSlackCredentials func(Config) (Config, error)
	// KeepJiraToken keeps a Jira token typed into the editor in the OS
	// keychain, under the item service names, so the file written reads it
	// from there. Nil, where no keychain is wired, keeps it in the file.
	KeepJiraToken func(service, secret string) error
}

type FieldError struct {
	Key string
	Err error
}

type Files struct {
	Home string
	Repo string
}

type Forge struct {
	// Kind is "github" or "gitlab", and is needed only for an on-premises host
	// whose name says neither — a GitHub Enterprise Server and a self-managed
	// GitLab look identical from a git remote, and their APIs differ.
	Kind string `json:"kind"`
	// Host is the host Kind and Token were written for, such as
	// git.example.com.
	Host string `json:"host"`
	// Token is a GitHub or GitLab personal access token, consulted only when
	// neither the environment nor the forge's own CLI supplies one.
	//
	// It is deliberately absent from Missing(). Reporting it as missing would
	// fail `workflow doctor` for everyone correctly relying on `gh auth login`,
	// which is the common case and the one worth encouraging.
	Token Secret `json:"token"`
	// CLI routes forge API calls through the forge's own command-line tool — gh
	// for GitHub, glab for GitLab — instead of over HTTP directly, so the login
	// those tools already hold carries the request. This is what reaches a forge
	// behind an SSO gateway a bare token cannot. It falls back to HTTP when the
	// tool is not installed.
	CLI bool `json:"cli"`
}

type Issues struct {
	// Forge adds the issues assigned to you on the repository's own forge,
	// GitHub or GitLab, to the list beside Jira's: for a repository whose
	// project tracks its work there. It is set per repository, in that
	// repository's file, over the home file's default. With no Jira, the
	// forge's issues are the whole list whatever it says.
	Forge bool `json:"forge"`
}

type Jira struct {
	// BaseURL is the root of the Jira instance, e.g. https://jira.example.com.
	BaseURL string `json:"base_url"`
	// Token is a personal access token. Leave it empty to take the token from
	// TokenCommand or TokenEnv instead, so the file holds no secret.
	Token Secret `json:"token"`
	// TokenCommand is a program that prints the token, such as
	// "pass show jira/token"; TokenEnv is an environment variable that holds it.
	// Only the home directory's file may set either.
	TokenCommand string `json:"token_command"`
	TokenEnv     string `json:"token_env"`
	// Keychain reads the token from the OS keychain item KeychainService names
	// for BaseURL, so the file holds no secret. It names no program and reads
	// only the item for the address in effect, so any file may set it, and a
	// repository's file that moves BaseURL keeps it: it then reads the item
	// for its own address, never the one for the home file's.
	Keychain bool `json:"keychain"`
	// User is optional. Leave it empty for token (Bearer) authentication; set it
	// to authenticate with HTTP Basic instead.
	User string `json:"user"`
	// Headers are extra HTTP headers sent with every Jira request, added after
	// the token, for a Jira reached through a proxy that wants one of its own —
	// an SSO gateway checking a header, say. A value may be a secret, so each
	// is a Secret, masked wherever the configuration is shown.
	Headers map[string]Secret `json:"headers"`
	// Views are named issue lists the pane can move between, each a label and its
	// JQL. Empty keeps the one built-in list: open issues assigned to you.
	Views []JiraView `json:"views"`
	// Project is the Jira project key, such as "PROJ". When set, only a branch
	// naming a key in that project is read as an issue, so a name like
	// fix/UTF-8-decoding is not mistaken for one. Empty falls back to a looser
	// guard that rejects common technical tokens (UTF, SHA, CVE) by shape alone.
	Project string `json:"project"`
	// MarkdownComments rewrites a comment written in Markdown as the wiki markup
	// Jira renders before posting it, so headings, emphasis, code and links come
	// out formatted rather than literal. On by default; false posts a comment
	// unchanged, for one already written in wiki markup.
	MarkdownComments bool `json:"markdown_comments"`
	// ReviewStatus is the status an issue moves to once its pull request is open,
	// e.g. "In Review". Opening a pull request offers the change to this status by
	// name — "in review" and "in progress" share a category, so the loop cannot
	// pick it out on its own. Empty makes no offer.
	ReviewStatus string `json:"review_status"`
}

type JiraView struct {
	Name string `json:"name"`
	JQL  string `json:"jql"`
}

type Messaging struct {
	// Kind is the service posts go to: "slack" (the default when empty),
	// "teams", "discord", or a plain "webhook". It decides the body and the link
	// markup the notifier sends.
	Kind MessagingKind `json:"kind"`
	// ClientID is the Slack app's client ID, which a rotating user token is
	// refreshed with. It is no secret; `workflow slack login` writes it.
	ClientID string `json:"client_id"`
	// ClientSecret, RefreshToken, AccessToken and ExpiresAt are the Slack user
	// token's rotating credentials when this file is where they are kept — on
	// Linux and Windows, or on macOS once they are put here — rather than in
	// the keychain. workflow rewrites the last three after every refresh. The
	// access token starts "xoxe.xoxp-", the refresh token "xoxe-1-"; ExpiresAt
	// is RFC 3339 UTC.
	ClientSecret Secret `json:"client_secret"`
	RefreshToken Secret `json:"refresh_token"`
	AccessToken  Secret `json:"access_token"`
	ExpiresAt    string `json:"expires_at"`
	// WebhookURL is an incoming webhook. It is a credential in its own right —
	// anyone holding it can post to that channel — so it is masked wherever a
	// token would be.
	WebhookURL Secret `json:"webhook_url"`
	// Channel is the channel updates are posted to, e.g. "#dev-workflow". It
	// applies to a Slack user token only; a webhook carries its own channel.
	Channel string `json:"channel"`
	// Channels are further channels a user-token post may be routed to at post
	// time, for a change that concerns another team. The default Channel is
	// always available too.
	Channels []string `json:"channels"`
	// Announcement shapes the Slack review message from named placeholders —
	// {author}, {noun}, {title}, {url}, {key}, {summary}, {issue_url}. Empty, or
	// any non-Slack kind, uses the built-in message. Substituted values are
	// always escaped.
	Announcement string `json:"announcement"`
	// AutoAnnounce arms the announcement of a pull request the terminal or
	// --web opens, to post once its CI passes. On by default; false arms
	// nothing, as a repository with no CI may want, while asking to announce
	// once CI passes still waits.
	AutoAnnounce bool `json:"auto_announce"`
}

type MessagingKind string

type MessagingMode int

type PullRequest struct {
	// TitleSource decides where a pull request's title comes from: "commit" (the
	// default) takes the branch's oldest commit, "issue" takes the issue it names.
	TitleSource string `json:"title_source"`
}

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

type Secret string

type Store struct {
	// Disabled turns the store off, so workflow keeps nothing between
	// sessions: nothing the user decides, and none of the conveniences, which
	// it works out afresh each time. No announcement tags anyone, since who is
	// whom cannot be kept: the terminal's ready-for-review preview lists each
	// code owner as not linked and offers no link, and workflow announce and
	// the web tag no one. No favorites are kept. For a machine where no
	// workflow state should touch the disk.
	Disabled bool `json:"disabled"`
}

type Taskwarrior struct {
	// Program is the task program to run: a name looked up on PATH, or a path.
	// Only the home directory's file may set it.
	// Empty tries every task in an absolute PATH directory, in order, and keeps
	// the first that answers as Taskwarrior — go-task, the Taskfile runner, is
	// also called task.
	Program string `json:"program"`
	// Disabled turns the integration off even where Taskwarrior is installed.
	Disabled bool `json:"disabled"`
}

type Timing struct {
	// RequestTimeout bounds each request to a service. The default is
	// DefaultRequestTimeout.
	RequestTimeout string `json:"request_timeout"`
	// CIInterval is how often CI is asked about while it runs, and how often
	// the web page's stream asks the forge about the branch. The default is
	// DefaultCIInterval.
	CIInterval string `json:"ci_interval"`
}

type UI struct {
	// Mouse captures the mouse, so a click focuses a pane or selects a row.
	// Capturing it takes away the terminal's own click-and-drag selection,
	// which is why it can be turned off here, and toggled with m in a session.
	Mouse bool `json:"mouse"`
	// ASCII draws borders and glyphs in plain ASCII, for a terminal or font
	// without box-drawing characters, and so the live line a command keeps
	// while it waits. There is no reliable way to detect that, so it is a
	// setting rather than a guess.
	ASCII bool `json:"ascii"`
	// Color is whether to draw the system hues: empty (auto) draws them when the
	// terminal allows, "never" turns them off while keeping bold, faint and the
	// reverse-video cursor, which carry meaning without color.
	Color string `json:"color"`
	// Motion is whether the terminal interface, and the live line a command
	// keeps while it waits, move: empty turns the in-flight mark, fills a
	// stage's rule as it completes and springs the CI bar; "reduce" draws
	// every state still, for anyone motion distracts or harms.
	Motion string `json:"motion"`
	// Accessible hands each multi-field form in the terminal the whole
	// terminal as a series of plain prompts, one question at a time, which a
	// screen reader reads as it would any command's, instead of drawing it
	// over the screen. The ACCESSIBLE environment variable, set to anything,
	// does the same.
	Accessible bool `json:"accessible"`
	// Notify rings the terminal, and sends a desktop notification where the
	// terminal relays one, when CI finishes — and the --web page says so in its
	// header — so a developer who stepped away is told rather than having to
	// check back. Off unless set.
	Notify bool `json:"notify"`
	// CommentsShown is how many of an issue's most recent comments the detail
	// pane draws. Zero keeps the built-in default.
	CommentsShown int `json:"comments_shown"`
	// Keys rebinds the interface's keys. Each entry maps an action to the single
	// key that should trigger it, e.g. {"commit": "C", "comment": "ctrl+e"}; the
	// help then shows the new key. An action left out keeps its default. The
	// interface refuses to start on a map that names an action it does not know,
	// moves jump-to-pane (its keys are the pane numbers, which no one key can
	// stand in for), or binds two actions in the same context to one key. The
	// actions it can rebind are listed under "Rebinding keys" in
	// docs/content/docs/configuration.md, which a terminal test holds to the
	// bound ones.
	Keys map[string]string `json:"keys"`
	// WebShortcuts turns on the --web page's single-key shortcuts — the
	// terminal's keys, ui.keys applied, pressed outside a text field. Off
	// unless set, since a character key that acts on its own surprises a
	// screen reader or speech user, who presses keys for other reasons (WCAG
	// 2.1.4). The ? sheet and the command palette, on ctrl+k or cmd+k, work
	// either way.
	WebShortcuts bool `json:"web_shortcuts"`
}