manifest

type Auth struct {
	// Kind is the flow facile runs: none, sso, oidc-device, password, device
	// or token. "token" means the credential is minted elsewhere and pasted
	// in. "device" is a tool's own headless endpoints; "oidc-device" is the
	// RFC 8628 grant at the shared identity provider, and the two are not the
	// same protocol — the prefix is there so the difference is visible here.
	Kind string `yaml:"kind"`

	// DefaultServerURL may be empty. A self-hosted appliance is right to refuse
	// to guess an address, so an empty default means facile must ask.
	DefaultServerURL string `yaml:"defaultServerUrl"`

	// APISuffix is appended when the user gives a bare origin. Some CLIs store
	// the API root rather than the site root and 404 on everything without it.
	APISuffix string `yaml:"apiSuffix"`

	// DiscoveryPath returns {sso_only, oidc_enabled} so facile can pick a flow
	// without asking the user what their instance is configured for.
	DiscoveryPath string `yaml:"discoveryPath"`

	// Flows and Env are grouped rather than listed so this struct stays under
	// filet's field cap as kinds are added. Both are inlined: the YAML is flat
	// and unchanged, and Go promotes the fields, so a.SSO and a.EnvToken still
	// read the way they always did.
	Flows `yaml:",inline"`

	// IdentityPath is fetched after login purely to name who signed in.
	IdentityPath string `yaml:"identityPath"`

	// TokenPath is the page where a human mints the credential by hand, for
	// the tools that have no login endpoint to drive. facile opens it rather
	// than telling the user to go and find it.
	TokenPath string `yaml:"tokenPath"`

	// Transport is how the credential is later presented: bearer or cookie.
	Transport  string `yaml:"transport"`
	CookieName string `yaml:"cookieName"`

	Env `yaml:",inline"`

	Store *Store `yaml:"store"`

	// Note explains a tool that cannot be logged into, so facile can say why
	// instead of pretending the command did something.
	Note string `yaml:"note"`
}

type DeviceFlow struct {
	StartPath string `yaml:"startPath"`
	PollPath  string `yaml:"pollPath"`
}

type Env struct {
	EnvToken string `yaml:"envToken"`
	EnvURL   string `yaml:"envUrl"`
}

type Flows struct {
	SSO        *SSOFlow        `yaml:"sso"`
	OIDCDevice *OIDCDeviceFlow `yaml:"oidcDevice"`
	Password   *PasswordFlow   `yaml:"password"`
	Device     *DeviceFlow     `yaml:"device"`
}

type Manifest struct {
	Version int    `yaml:"version"`
	Tools   []Tool `yaml:"tools"`
}

type OIDCDeviceFlow struct {
	// Issuer is the OIDC issuer. Endpoints come from its discovery document,
	// never from paths assembled here: on this provider a per-application
	// discovery path answers 200 with the single-page app's HTML, which is a
	// false positive that has already misled two investigations.
	Issuer string `yaml:"issuer"`

	// ClientID names a public client. A CLI ships on the user's machine and
	// cannot keep a secret, so there is none here and none is sent.
	ClientID string `yaml:"clientId"`

	// Scopes are space separated, as OAuth spells them. profile and email are
	// what the app needs to name the account behind the token.
	Scopes string `yaml:"scopes"`

	// ExchangePath trades the provider's access token for the tool's own
	// credential, because what the tool reads is its own session and not the
	// provider's — the same reason the loopback flow exchanges a code rather
	// than storing it. The prefix mirrors this tool's SSO exchange path: an
	// app serving its API under /api serves both under /api.
	ExchangePath string `yaml:"exchangePath"`
}

type PasswordFlow struct {
	Path string `yaml:"path"`

	// WithEmail distinguishes a multi-user login from a single instance password.
	WithEmail bool `yaml:"withEmail"`

	// TokenField is empty when the credential comes back as a Set-Cookie header.
	TokenField string `yaml:"tokenField"`
}

type SSOFlow struct {
	StartPath    string `yaml:"startPath"`
	PortParam    string `yaml:"portParam"`
	StateParam   string `yaml:"stateParam"`
	ExtraParams  string `yaml:"extraParams"`
	CallbackWith string `yaml:"callbackWith"`
	ExchangePath string `yaml:"exchangePath"`

	// CallbackPath is the loopback path the server redirects to, and it is not
	// the same everywhere: casier redirects to /callback, porte — and so
	// sablier — redirects to /. Empty means /callback.
	CallbackPath string `yaml:"callbackPath"`

	// RequireState is false only where the server does not echo the nonce back
	// yet. It is a defect to be fixed server-side, never a setting to prefer.
	RequireState bool `yaml:"requireState"`
}

type Store struct {
	Kind string `yaml:"kind"`

	KeychainService string `yaml:"keychainService"`
	KeychainAccount string `yaml:"keychainAccount"`

	Path       string   `yaml:"path"`
	Format     string   `yaml:"format"`
	TokenField string   `yaml:"tokenField"`
	URLField   string   `yaml:"urlField"`
	Mode       uint32   `yaml:"mode"`
	DirMode    uint32   `yaml:"dirMode"`
	Preserve   bool     `yaml:"preserve"`
	Extra      []string `yaml:"extra"`
}

type Tool struct {
	Name         string   `yaml:"name"`
	Summary      string   `yaml:"summary"`
	Repo         string   `yaml:"repo"`
	Branch       string   `yaml:"branch"`
	Bin          string   `yaml:"bin"`
	Build        string   `yaml:"build"`
	SrcSubdir    string   `yaml:"srcSubdir"`
	Asset        string   `yaml:"asset"`
	Skill        string   `yaml:"skill"`
	GoVersionVar string   `yaml:"goVersionVar"`
	Requires     []string `yaml:"requires"`
	Auth         *Auth    `yaml:"auth"`
}