config

type AuthMode string

type BlockDecl struct {
	Slug string `json:"slug"`
	// InterfaceName is "" for a block that declares none; Payload then derives
	// the GraphQL type name from the slug itself.
	InterfaceName string `json:"interface_name,omitempty"`
	// Fields are the entries of this block's own `fields:` array literal, in
	// source order. They exist for ONE fact GraphQL cannot supply: Payload
	// generates no INPUT_OBJECT for a block type (the blocks mutation argument
	// is a JSON scalar), so the NON_NULL trick that recovers required-ness for
	// a collection field has nothing to read. The config on disk is the only
	// place `required: true` is written down.
	Fields []BlockFieldDecl `json:"fields,omitempty"`
	// FieldsComplete is true only when EVERY element of the `fields:` array
	// was an object literal carrying a `name:` string literal. A helper call
	// (`linkGroup({…})`), a spread, or a computed field makes it false, and a
	// false here is what keeps a missing entry reading as "unknown" instead of
	// "not required" — the exact guess this whole type exists to refuse.
	FieldsComplete bool `json:"fields_complete,omitempty"`

	// LabelSingular and LabelPlural are the block's own `labels:` literals
	// ({ singular: 'Call to Action', plural: 'Calls to Action' }). They are
	// the human name of the block and, like every other fact here, exist only
	// when the project's authors wrote them; "" is "not declared", never a
	// title-cased guess at the slug.
	LabelSingular string `json:"label_singular,omitempty"`
	LabelPlural   string `json:"label_plural,omitempty"`

	// Description is the one-sentence statement of what this block is FOR.
	//
	// Payload blocks have NO standard field for it — verified: a Block's
	// `admin` accepts only components/custom/disableBlockName/group/images/jsx
	// and `tsc --noEmit` rejects `admin: { description }` on a Block — so the
	// text lives in `custom`, Payload's sanctioned arbitrary-metadata escape
	// hatch, under whatever key the project chose. DescriptionKey records
	// which one it was so the output is honest about where the words came from
	// instead of implying a standard field exists.
	Description string `json:"description,omitempty"`
	// DescriptionKey is the literal config path the text was read from:
	// "custom.description", "custom.docs", "custom.summary" or
	// "admin.description". Empty exactly when Description is empty.
	DescriptionKey string `json:"description_key,omitempty"`
}

type BlockFieldDecl struct {
	Name string `json:"name"`
	// Type is the `type:` literal ('richText', 'upload', 'select', …). It is
	// the only source that can tell lexical richText from a json field and a
	// select from a radio, both of which compile to the SAME GraphQL shape.
	Type string `json:"type,omitempty"`
	// Required is the literal `required: true` / `required: false`, or nil
	// when the key was absent or not a boolean literal.
	Required *bool `json:"required,omitempty"`

	// Description is the field's own human instruction, read from
	// `admin: { description: '…' }` — which, unlike a Block's admin, Payload
	// DOES support on a field and is exactly where a per-field "pass a media
	// document id" belongs. `custom.description` is accepted as well, for the
	// same reason it is on a block.
	Description string `json:"description,omitempty"`
	// DescriptionKey is the literal config path the text was read from
	// ("admin.description", "custom.description", …), empty when Description
	// is empty.
	DescriptionKey string `json:"description_key,omitempty"`
}

type CacheSection struct {
	Dir          string `toml:"dir,omitempty"`
	DiscoveryTTL string `toml:"discovery_ttl,omitempty"`
	AccessTTL    string `toml:"access_ttl,omitempty"`
	SchemaTTL    string `toml:"schema_ttl,omitempty"`
	IdentityTTL  string `toml:"identity_ttl,omitempty"`
	SkillsTTL    string `toml:"skills_ttl,omitempty"`
}

type Defaults struct {
	Output         string `toml:"output,omitempty"`
	Depth          *int   `toml:"depth,omitempty"`
	Limit          *int   `toml:"limit,omitempty"`
	Timeout        string `toml:"timeout,omitempty"`
	Deadline       string `toml:"deadline,omitempty"`
	MaxRetries     *int   `toml:"max_retries,omitempty"`
	Concurrency    *int   `toml:"concurrency,omitempty"`
	Redact         *bool  `toml:"redact,omitempty"`
	AcceptLanguage string `toml:"accept_language,omitempty"`
	MaxBulk        *int   `toml:"max_bulk,omitempty"`
	ConfirmWrites  *bool  `toml:"confirm_writes,omitempty"`
	Locale         string `toml:"locale,omitempty"`
	FallbackLocale string `toml:"fallback_locale,omitempty"`
	ErrorsTo       string `toml:"errors_to,omitempty"`
}

type Env map[string]string

type FieldDoc struct {
	Description string `json:"description"`
	// Key is the literal config path — "admin.description" in the normal case.
	Key string `json:"key"`
}

type File struct {
	Version        int                `toml:"version,omitempty"`
	DefaultProfile string             `toml:"default_profile,omitempty"`
	Defaults       Defaults           `toml:"defaults,omitempty"`
	Cache          CacheSection       `toml:"cache,omitempty"`
	Logging        LoggingSection     `toml:"logging,omitempty"`
	Update         UpdateSection      `toml:"update,omitempty"`
	Profiles       map[string]Profile `toml:"profiles,omitempty"`

	// APIKey is not a legal key anywhere (§4.2); it is decoded only so the
	// hard error can name it.
	//nolint:gosec // G117: decode-only. Encode() clears it; see
	// TestEncodeNeverEmitsAPIKey and TestAPIKeyInConfigIsFatal.
	APIKey string `toml:"api_key,omitempty"`

	// Path is where the file came from; it is what `pay config explain`
	// prints as "user:/abs/config.toml" or "project:/abs/pay.toml" (§4.5).
	Path string `toml:"-"`
	// Exists is false for a file that was absent, which is not an error.
	Exists bool `toml:"-"`
	// Kind is "user" or "project"; it prefixes the source string.
	Kind string `toml:"-"`
	// UnknownKeys are decoded-but-unrecognised keys, surfaced as warnings so a
	// typo like `base_ur1` is visible without being fatal.
	UnknownKeys []string `toml:"-"`
}

type Flags struct {
	Profile          string
	BaseURL          string
	APIPath          string
	GraphQLPath      string
	GraphQLRoute     string
	AuthCollection   string
	AuthMode         string
	AuthHeaderScheme string

	Output         string
	ErrorsTo       string
	Path           string
	Locale         string
	FallbackLocale string
	AcceptLanguage string

	Timeout  string
	Deadline string
	CacheTTL string

	Depth       *int
	Limit       *int
	MaxDocs     *int
	MaxRetries  *int
	Concurrency *int

	Redact             *bool
	InsecureSkipVerify *bool
	NoCache            *bool
	Refresh            *bool
	Yes                *bool
	DryRun             *bool
	NoAudit            *bool
	Quiet              *bool
	Verbose            *bool

	LogLevel  string
	LogFormat string
}

type Input struct {
	Flags   Flags
	Env     Env
	Project *File
	User    *File
}

type KeyringMode string

type LoggingSection struct {
	Level  string `toml:"level,omitempty"`
	Format string `toml:"format,omitempty"`
}

type Paths struct {
	ConfigDir  string
	CacheDir   string
	StateDir   string
	ConfigFile string

	Sources map[string]string
	// contains filtered or unexported fields
}

type Profile struct {
	BaseURL            string              `toml:"base_url,omitempty"`
	APIPath            string              `toml:"api_path,omitempty"`
	GraphQLRoute       string              `toml:"graphql_route,omitempty"`
	GraphQLPath        string              `toml:"graphql_path,omitempty"`
	AuthCollection     string              `toml:"auth_collection,omitempty"`
	AuthMode           string              `toml:"auth_mode,omitempty"`
	AuthHeaderScheme   string              `toml:"auth_header_scheme,omitempty"`
	Label              string              `toml:"label,omitempty"`
	APIKeyEnv          string              `toml:"api_key_env,omitempty"`
	CredentialHelper   string              `toml:"credential_helper,omitempty"`
	InsecureSkipVerify *bool               `toml:"insecure_skip_verify,omitempty"`
	Headers            map[string]string   `toml:"headers,omitempty"`
	Blocks             map[string][]string `toml:"blocks,omitempty"`

	// Optional pins. Each one turns a discovered-or-unknown value into a
	// configured one and flips the matching *_source to "configured" (§4.2).
	IDType          string   `toml:"id_type,omitempty"`
	Locales         []string `toml:"locales,omitempty"`
	PayloadVersion  string   `toml:"payload_version,omitempty"`
	DBAdapter       string   `toml:"db_adapter,omitempty"`
	EchoCheckIgnore []string `toml:"echo_check_ignore,omitempty"`
	CustomEndpoints []string `toml:"custom_endpoints,omitempty"`

	// APIKey is never a legal key (§4.2); see File.Validate.
	APIKey string `toml:"api_key,omitempty"`
}

type Project struct {
	// Dir is the directory that anchored the discovery — the first one going
	// up that contained any marker at all.
	Dir string
	// ConfigPath is ./pay.toml, the committed project config (§4.3).
	ConfigPath string
	// PackageJSON is the nearest package.json (§7.11 source 2).
	PackageJSON string
	// PayloadConfig is the nearest payload.config.ts / .js / .mjs, at the root
	// or under src/ (§7.10).
	PayloadConfig string
	// SrcDir is the payload config's directory when it lives in src/.
	SrcDir string
	// GitRoot is the directory holding .git; the walk stops after it.
	GitRoot string
	// Start is the directory the walk began in.
	Start string
	// contains filtered or unexported fields
}

type Resolved struct {
	Profile        string
	ProfileDefined bool
	Label          string

	BaseURL          string
	APIPath          string
	GraphQLRoute     string
	GraphQLPath      string
	AuthCollection   string
	AuthMode         AuthMode
	AuthHeaderScheme string
	APIKeyEnv        string
	CredentialHelper string
	Headers          map[string]string
	KeyringMode      KeyringMode

	Output         string
	ErrorsTo       string
	Path           string
	Locale         string
	FallbackLocale string
	AcceptLanguage string

	Timeout     time.Duration
	Deadline    time.Duration
	Depth       int
	Limit       int
	MaxDocs     int
	MaxRetries  int
	Concurrency int
	MaxBulk     int

	Redact             bool
	ConfirmWrites      bool
	InsecureSkipVerify bool
	NoCache            bool
	Refresh            bool
	CacheTTL           time.Duration
	Yes                bool
	DryRun             bool
	NoAudit            bool
	Quiet              bool
	Verbose            bool

	CacheDir     string
	DiscoveryTTL time.Duration
	AccessTTL    time.Duration
	SchemaTTL    time.Duration
	IdentityTTL  time.Duration
	SkillsTTL    time.Duration

	LogLevel  string
	LogFormat string

	UpdateAuto    bool
	UpdateChannel string

	// Optional pins (§4.2). An empty value means "not configured"; the
	// matching *Source entry says so explicitly.
	IDType          string
	Locales         []string
	PayloadVersion  string
	DBAdapter       string
	EchoCheckIgnore []string
	CustomEndpoints []string
	Blocks          map[string][]string

	// ConcurrencyClamped is true when the requested concurrency exceeded
	// MaxConcurrency and was lowered.
	ConcurrencyClamped bool
	// Warnings are non-fatal configuration observations for the caller to put
	// in the envelope (§10): a moved base_url credential, an unset ${ENV} in a
	// header, an unknown key in a config file.
	Warnings []string
	// Sources maps a setting name to its §4.5 provenance string.
	Sources map[string]string
	// contains filtered or unexported fields
}

type ScanResult struct {
	Root string `json:"root,omitempty"`

	PayloadVersion       string `json:"payload_version,omitempty"`
	PayloadVersionSource string `json:"payload_version_source"`
	PackageJSON          string `json:"package_json,omitempty"`

	// DBAdapter is inferred from the project's @payloadcms/db-* dependency.
	// §7.11 only defines "configured" and "inferred" for this field, so a
	// package.json match reports "inferred" — which deliberately does NOT
	// unlock §9.3's client-side operator block, since that requires
	// "configured".
	DBAdapter       string `json:"db_adapter"`
	DBAdapterSource string `json:"db_adapter_source"`

	BlockSlugs     []string          `json:"blocks,omitempty"`
	BlocksSource   string            `json:"blocks_source"`
	BlockSlugFiles []string          `json:"block_slug_files,omitempty"`
	SlugFile       map[string]string `json:"-"`

	// BlockDecls are the (slug, interfaceName) pairs §7.10 harvests, in scan
	// order. The pair is the load-bearing fact: GraphQL publishes a blocks
	// field's union as interfaceNames (CallToActionBlock) while the REST API
	// only ever accepts the slug (cta), so neither half alone can turn the
	// per-field union into something writable.
	BlockDecls []BlockDecl `json:"block_decls,omitempty"`
	// SlugByInterface is BlockDecls indexed by interfaceName. Blocks that
	// declare no interfaceName are absent: there is nothing to key them by.
	SlugByInterface map[string]string `json:"-"`

	// FieldDocs are the per-field `admin: { description: '…' }` instructions
	// declared by the project's COLLECTIONS and GLOBALS, keyed by entity slug
	// and then by field name.
	//
	// They cover a collection's TOP-LEVEL `fields:` array only. A field nested
	// inside a group, an array or a tab is not reached — the scanner adopts
	// only the direct elements of the array it can attribute — and is reported
	// as undocumented rather than being given a path this scanner would have
	// had to guess.
	//
	// An entity whose config was read but documents nothing is present with an
	// EMPTY map. The key's presence is the fact "PayCLI read this entity's
	// config"; its absence is "there is none on disk", which is what a
	// plugin-provided collection looks like.
	FieldDocs map[string]map[string]FieldDoc `json:"field_docs,omitempty"`
	// FieldDocFiles are the absolute paths FieldDocs were read from, keyed by
	// entity slug, so the answer can always name its own source file.
	FieldDocFiles map[string]string `json:"field_doc_files,omitempty"`

	FilesScanned int   `json:"files_scanned"`
	BytesScanned int64 `json:"bytes_scanned"`
	Truncated    bool  `json:"truncated,omitempty"`
}

type Setting struct {
	Value  any    `json:"value"`
	Source string `json:"source"`
}

type UpdateSection struct {
	Auto    *bool  `toml:"auto,omitempty"`
	Channel string `toml:"channel,omitempty"`
}