forge

type AuthConfig struct {
	// StorageMode is set by the storage-mode selector. Defaults to
	// [credentials.ModeEnvVar] when the form presents the choice.
	StorageMode credentials.Mode

	// EnvVarName is the env var NAME recorded under <prefix>.auth.env in
	// env-var mode. Ignored in keychain/literal modes.
	EnvVarName string

	// FetchToken is true when the user wants the wizard to run OAuth (or the
	// manual fallback) on their behalf. Only relevant in env-var mode —
	// keychain/literal always need a token.
	FetchToken bool

	// Token is the captured token from OAuth / manual entry. Cleared after it
	// has been written (or displayed for env-var mode) so it does not linger in
	// the AuthConfig longer than necessary.
	Token string
}

type AuthFormOption func(*authFormConfig)

type ConfigureSSHKeyOption func(*configureSSHKeyConfig)

type CredentialShape int

type Display struct {
	// ID is the forge's feature identity, and the value --git-backend takes.
	ID props.FeatureID
	// Label is the human-facing forge name (e.g. "GitLab").
	Label string
	// Host is the default host, empty for a forge that has none. Gitea is the
	// case in point: every instance is self-hosted.
	Host string
	// RepoDescription and RepoPlaceholder describe the repository path this
	// forge expects.
	RepoDescription string
	RepoPlaceholder string
	// NestedNamespaces marks a forge whose owner segment may contain slashes,
	// as GitLab subgroups do.
	NestedNamespaces bool
}

type DualConfig struct {
	StorageMode credentials.Mode

	// Username and AppPassword hold the collected credentials for keychain and
	// literal modes. Unused in env-var mode.
	Username    string
	AppPassword string

	// UsernameEnvName and AppPasswordEnvName hold env-var names for env-var
	// mode. Default to the profile's fallback env-var names.
	UsernameEnvName    string
	AppPasswordEnvName string
}

type DualFormOption func(*dualFormConfig)

type GenerateKeyOption func(*generateKeyConfig)

type Initialiser struct {

	// SkipLogin suppresses the login stage of a single-token profile; it is
	// ignored by dual-credential profiles, which have no login step.
	//
	// SkipKey suppresses the SSH stage for any profile that offers it,
	// whatever its credential shape.
	SkipLogin bool
	SkipKey   bool
	// contains filtered or unexported fields
}

type InitialiserOption func(*Initialiser)

type Profile struct {
	// Provider is the forge registry key passed to [forgeapi.Lookup]
	// (e.g. "github").
	Provider string
	// ConfigPrefix is the config-key namespace (e.g. "github" →
	// "github.auth.env"). It reproduces each provider's existing key layout
	// exactly so pre-existing configs keep resolving.
	ConfigPrefix string
	// Label is the human-facing provider name used in prompts and errors
	// (e.g. "GitHub").
	Label string
	// DisplayName is the initialiser's Name() label shown by the setup
	// runner (e.g. "GitHub integration").
	DisplayName string
	// Feature is the feature flag that gates this initialiser.
	Feature props.FeatureID
	// Host is the default web host: the manual-token URL host and the forge
	// provider's release-source host.
	Host string
	// KeychainAccount is the account portion of the "<service>/<account>"
	// keychain reference (e.g. "github.auth").
	KeychainAccount string
	// Credential selects the single-token or dual-credential flow.
	Credential CredentialShape

	// FallbackEnv is the well-known token env var used by the single-token
	// flow's already-configured detection and env-var-name default
	// (e.g. "GITHUB_TOKEN"). SingleToken only.
	FallbackEnv string
	// OffersSSH enables the SSH key discovery/generation/upload stage.
	//
	// It is a capability claim — "this forge can accept an SSH key" — not a
	// statement about the credential shape. The stage takes a Profile and
	// nothing else, and runs from Configure for either shape.
	OffersSSH bool
	// OffersLogin enables the forge [forgeapi.Authenticator] login attempt
	// before the manual-token fallback. SingleToken only.
	OffersLogin bool

	// TokenCreateURLTemplate is the provider's "create a personal access token"
	// URL, with the literal "{host}" standing in for Host (so an Enterprise host
	// is substituted). Empty degrades the manual-token wizard to a generic
	// "create a personal access token on <host>" message — forge-specific URL
	// paths and scope names must live here, not hard-coded in the wizard.
	// SingleToken only.
	TokenCreateURLTemplate string
	// TokenScopes is the human-readable scope list shown alongside the URL
	// (e.g. "repo, read:org, gist"). Empty omits the line. SingleToken only.
	TokenScopes string

	// UserFallbackEnv / PassFallbackEnv are the well-known env-var-name
	// defaults for the dual flow (e.g. "BITBUCKET_USERNAME" /
	// "BITBUCKET_APP_PASSWORD"). DualUserPass only.
	UserFallbackEnv string
	PassFallbackEnv string

	// LoginClientID is an OAuth application client ID this framework ships for
	// the forge's device-flow login, applied only when the resolved API host
	// matches LoginClientIDHost and the user's config names no client ID of
	// its own.
	//
	// It is deliberately NOT shipped in the forge's embedded config bundle,
	// which would be simpler. An embedded default always populates the key, so
	// the adapter's Settings.ClientID would never be empty — which would (a)
	// dead-letter the provider's own well-known env-var fallback, and (b) send
	// a gitlab.com client ID to a self-hosted instance, where login fails as an
	// invalid client instead of degrading to the manual-token path. Gating on
	// the host keeps both behaviours intact. See spec 0185 D8.
	LoginClientID string
	// LoginClientIDHost is the API host LoginClientID is registered against.
	// Empty means "never apply it".
	LoginClientIDHost string

	// RepoDescription and RepoPlaceholder are the repository-field help text
	// and placeholder the project generator shows for this forge. They live
	// here, beside the forge's other definitional data, so adding a forge does
	// not also mean editing a table in internal/cmd/generate — see spec 0185
	// D5. They reach the generator through [DisplayFor], not through Profile
	// itself, which stays unexported.
	RepoDescription string
	RepoPlaceholder string
	// NestedNamespaces marks a forge whose owner segment may itself contain
	// slashes (GitLab subgroups). It selects the namespace-validation rules
	// and is the one structural difference between forges' repository paths.
	NestedNamespaces bool
}