core

type Action string

type Applied struct {
	Change *Change
	// ID is the resource's identifier after the operation, when it has one.
	ID string
	// Outcome is what was actually done: "created", "updated", "unchanged",
	// the kind's Destroy.Past, "already gone" — or "failed" or "interrupted",
	// with Err set.
	Outcome string
	Err     error
}

type Applier struct {
	Client Client
	Lock   *Lockfile
	// Report is told about each resource as soon as it has been applied, so a
	// long apply shows progress. Optional.
	Report func(Applied)
}

type Candidate struct {
	// Path is the file's absolute path.
	Path string
	// Markdown reports whether the file has a prose body as well as fields.
	Markdown bool
	// Prose is the markdown after the frontmatter, empty for a YAML file.
	Prose []byte
	// Fields are the declared fields: the frontmatter of a markdown file, or
	// the whole document of a YAML one. The `type` field is removed once the
	// file is classified.
	Fields map[string]any
	// Name is the default for a resource's `name`: the filename without its
	// extension, unless the Schema refines it while classifying.
	Name string
	// HasFrontmatter tells an empty frontmatter block apart from no
	// frontmatter at all: only the latter means the file is prose.
	HasFrontmatter bool
	// DecodeErr holds a frontmatter or YAML failure. It is fatal for a path the
	// user named but merely disqualifying for one we walked into, so it travels
	// with the Candidate instead of aborting the read.
	DecodeErr error
	// contains filtered or unexported fields
}

type Change struct {
	Key    string
	Kind   Kind
	Action Action

	// Source is the local definition. Nil for a destroy, whose file is gone.
	Source *Source
	// Entry is the lockfile record. Nil for a create.
	Entry *LockEntry

	// Desired is the request body apply will send, with references resolved.
	Desired map[string]any
	// Remote is the object as the server currently has it, when known.
	Remote map[string]any

	// Hash is the desired-state fingerprint to record on success.
	Hash string
	// Diff is the field-level detail shown under an update; nil otherwise.
	Diff *Diff
	// Reasons explains why this change exists, beyond the field diff — an
	// out-of-band edit, a dependency version bump, a recreated resource.
	Reasons []string
	// Sensitive marks dotted paths whose values must never be printed.
	Sensitive map[string]bool

	// Replaces is the ID of the tracked resource this create supersedes,
	// when one that was gone or archived has to be made again.
	Replaces string
	// Drift is set when the server's copy no longer matches what we recorded,
	// meaning somebody changed it outside this config.
	Drift bool
	// Blocked carries the reason apply must refuse to proceed.
	Blocked error
	// Unresolved marks a body containing "(known after apply)" placeholders.
	Unresolved bool
	// contains filtered or unexported fields
}

type Client interface {
	// Get returns the resource as decoded JSON, or an error wrapping
	// ErrNotFound when the server has no such resource.
	Get(ctx context.Context, kind Kind, id string) (map[string]any, error)
	// Create makes a resource and returns the server's answer, which must
	// carry the new resource's string "id". For a payload-backed kind the
	// answer may instead be the version just uploaded, with its identifier
	// under "version".
	Create(ctx context.Context, kind Kind, req Request) (map[string]any, error)
	// Update writes to an existing resource and returns the server's answer,
	// in the same shape Create returns.
	Update(ctx context.Context, kind Kind, id string, req Request) (map[string]any, error)
	// Destroy archives or deletes, per the kind's capabilities. An error
	// wrapping ErrNotFound means the resource was already gone.
	Destroy(ctx context.Context, kind Kind, id string) error
}

type Destroy struct {
	Verb string // "archive"
	Past string // "archived"
}

type Diff struct {
	Kind DiffKind
	// Fields holds the differing members of an object, by name.
	Fields map[string]*Diff
	// Items holds the differing elements of a list, in display order.
	Items []ItemDiff
	// Before is the server's value and After the desired one, for the leaf
	// kinds that carry them.
	Before, After any
}

type DiffKind int

type FetchedURL struct {
	// Dir is the local directory the URL was materialized into.
	Dir string
	URLPin
}

type Field struct {
	// Computed marks a value the server owns and the config does not set —
	// timestamps, IDs, status. It is stripped before comparing, so a missing
	// Computed marking shows up as drift that never clears.
	Computed bool
	// WriteOnly marks a value the server never returns. It cannot be compared,
	// and it must never be printed. A "[]" segment in the path means "every
	// element of this array".
	WriteOnly bool
	// Immutable marks a value fixed when the resource is created. Changing it
	// needs a replace, which core refuses to do on the user's behalf.
	Immutable bool
	// Clearable marks a value that deleting from the file should actually
	// remove, by sending an explicit null. Without it the field follows the
	// API's usual omit-to-preserve rule, which is the safe default: a server
	// that fills in its own value would otherwise be fought with forever.
	Clearable bool
	// Archived marks the server-owned field whose presence means the resource
	// was archived out of band. Archiving is a one-way door, so the planner
	// offers a replacement rather than an update.
	Archived bool
	// Shorthand names the sub-field a bare scalar stands for when the API
	// accepts either form and always answers with the object:
	// `model: x` and `model: {id: x, …}` then compare equal.
	Shorthand string
	// Summary marks a field worth showing under a create in the plan. The
	// whole body would bury the plan in prose; these identify the resource.
	Summary bool
	// MatchBy names the members that identify an element of this list field,
	// most telling first, so a plan can pair elements up before diffing them.
	// Unset means id, then name; position is always the last resort.
	MatchBy []string

	// Metadata marks a string-to-string bag the server patches key by key, so
	// core sends null for keys the file no longer declares.
	Metadata bool
	// Ref marks a field holding a reference to another resource, written in
	// the config as a file path and sent to the API as an ID.
	Ref *Ref
	// Include marks a list field whose entries may name a data file — YAML or
	// JSON, by path or glob relative to the declaring file — whose contents
	// are spliced into the list where the entry stood. It is for lists of
	// hand-written API objects that some other tool generates (a framework
	// emitting the custom tool specs it executes, say), so the definition
	// stays declarative without being copied in by hand. The file is data,
	// not a resource: it gets no lockfile entry, but what it contributes is
	// part of the body, so editing it plans an update like any other edit.
	Include bool
}

type Fields map[string]Field

type Found struct {
	Key  string
	Kind Kind
}

type GitHubFetcher struct {
	HTTPClient *http.Client
	// Token authenticates against private repositories. Read from GITHUB_TOKEN
	// or GH_TOKEN by NewGitHubFetcher.
	Token string
	// CacheDir holds extracted archives across applies.
	CacheDir string
	// contains filtered or unexported fields
}

type ItemDiff struct {
	Before, After int
	Diff          *Diff
}

type Kind string

type KindSpec struct {
	// Kind is the kind this spec describes.
	Kind Kind

	// IDPrefix is the leading token of the API's tagged IDs ("agent" in
	// "agent_01…"), used to tell an inline ID reference from a file path.
	IDPrefix string

	// VersionField is the response field holding the resource's version, if it
	// has one. Empty means the kind is unversioned, and drift can only be
	// detected by fingerprinting the whole object.
	VersionField string
	// VersionIsInt renders the version as a number rather than a string when
	// it is sent back to the API.
	VersionIsInt bool
	// UpdateNeedsVersion means update requires the caller to echo the current
	// version back, under `version` in the request body, which is how the API
	// rejects a racing writer.
	UpdateNeedsVersion bool

	// Destroy is what removal actually does, for plan output: most APIs
	// offer archive, delete, or only one of the two.
	Destroy Destroy

	// Fields describes the resource's fields, one entry per field, keyed by a
	// dotted path into the body. Everything the reconciler needs to know about
	// a field lives in its entry rather than being spread across parallel
	// lists, so one line says everything about a field such as `description`.
	Fields Fields

	// Build turns a parsed file into a request body. Required for every kind a
	// Schema can classify from a file. Leave it nil for a kind whose content
	// travels as a Payload: core then refuses to load one from a file, and
	// reads a write's version from the version object the upload answers with.
	Build func(c *Candidate) (map[string]any, error)
	// contains filtered or unexported fields
}

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

type LockEntry struct {
	Kind Kind   `json:"kind"`
	ID   string `json:"id"`
	// Version is the resource version at last apply: an integer for some
	// kinds, an epoch string for others, empty for kinds that don't version.
	// Kept as a string so both round-trip losslessly.
	Version string `json:"version,omitempty"`
	// Hash fingerprints the desired state we last sent. A mismatch means the
	// local files changed.
	Hash string `json:"hash"`
	// RemoteHash fingerprints the normalized remote object as it looked right
	// after that apply. A mismatch means somebody changed it out of band —
	// this is the only drift signal available for kinds with no version field.
	RemoteHash string `json:"remote_hash,omitempty"`
	// Revision and Subpath are the commit a URL-sourced resource was pinned
	// to and where in it the resource lives.
	Revision string `json:"revision,omitempty"`
	Subpath  string `json:"subpath,omitempty"`
	// contains filtered or unexported fields
}

type Lockfile struct {
	Path      string
	Resources map[string]*LockEntry
	// Origin is where these resources live; nil until the first apply
	// records it, and in lockfiles written before it existed.
	Origin *Origin
	// contains filtered or unexported fields
}

type Origin struct {
	BaseURL        string `json:"base_url,omitempty"`
	OrganizationID string `json:"organization_id,omitempty"`
	WorkspaceID    string `json:"workspace_id,omitempty"`
}

type Payload interface {
	// Fingerprint identifies the payload's content. Two payloads with the same
	// fingerprint are treated as unchanged.
	Fingerprint() (string, error)
	// Describe is a short human summary for plan output, e.g. "3 files".
	Describe() string
}

type Plan struct {
	Changes  []*Change
	Warnings []string
	// LockfilePath is where state will be written.
	LockfilePath string
	// LockfileExisted reports whether state was found or is being started.
	LockfileExisted bool
	// contains filtered or unexported fields
}

type Planner struct {
	// Registry supplies the kinds this planner understands.
	Registry *Registry
	Client   Client
	Lock     *Lockfile

	// Force proceeds even when a resource changed out of band.
	Force bool
	// Prune destroys resources that are in the lockfile but no longer on disk.
	Prune bool
	// Concurrency bounds parallel reads of remote state. Zero or less means 8.
	Concurrency int
	// contains filtered or unexported fields
}

type Ref struct {
	// To restricts what the reference may name.
	To []Kind
	// List marks a field holding several references rather than one.
	List bool
	// As renders a resolved target into the body. Nil writes the bare ID.
	As func(Target) any
}

type RefSlot struct {
	Path string
	Ref
}

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

type Request struct {
	Body    map[string]any
	Payload Payload
}

type Result struct {
	Created   int
	Updated   int
	Destroyed int
	Unchanged int
}

type Schema interface {
	// Classify names the kind a parsed file declares. Returning ("", nil) means
	// "not a resource": a directory walk must tolerate that, since a repository
	// is full of prose and CI config. walked reports whether the file was found
	// by walking rather than named outright, which is usually the difference
	// between skipping something and complaining about it. Classify may read
	// the `type` field to decide; core drops that field from c.Fields
	// afterwards, so a Build never sees it.
	Classify(c *Candidate, walked bool) (Kind, error)
	// IsResourceDir reports whether a directory is itself a resource rather
	// than a folder of them. It is asked often, so it must be cheap — a stat,
	// not a walk.
	IsResourceDir(dir string) (Kind, bool)
	// LoadDir loads a directory IsResourceDir accepted.
	LoadDir(dir string) (Kind, map[string]any, Payload, error)
	// ResourceDirOf maps a file that stands in for a directory-backed resource
	// to that directory — a marker file to its folder.
	ResourceDirOf(path string) (string, bool)
	// LockfileName is the state file's conventional name. A directory walk
	// skips it, and discovery looks for it walking up.
	LockfileName() string
}

type Source struct {
	// Key is the stable identity used in the lockfile and in plan output:
	// a root-relative slash path prefixed with "./", or the verbatim URL for
	// a URL-sourced resource.
	Key  string
	Kind Kind

	// Path is the absolute path of the defining file. Empty when the resource
	// came from a URL.
	Path string
	// Dir is set when the resource is declared by a directory rather than a
	// file.
	Dir string
	// Payload is the non-JSON content of a directory-backed resource.
	Payload Payload
	// URL is set when the resource was fetched from a URL rather than read
	// from the working tree, and Pin records what it resolved to.
	URL string
	Pin URLPin

	// Body is the declared request body, minus apply-only directives.
	Body map[string]any
}

type Target struct {
	Kind Kind
	ID   string
	// Version is the referenced resource's version in its JSON form: an
	// integer for some kinds, an epoch string for others. Nil when there is
	// none to pin yet.
	Version any
	// Pinned is false when the user asked to always track latest, in which
	// case EncodeObject omits the version and lets the server resolve it.
	Pinned bool
	// Versioned reports whether the target's kind has a version at all;
	// pinning is meaningless for one that does not.
	Versioned bool
	// Known is false at plan time for a resource that does not exist yet, so
	// its ID and version are "known after apply".
	Known bool
}

type URLFetcher interface {
	// Fetch downloads rawURL. When pin carries a revision the fetcher must
	// return exactly that rather than whatever the URL's branch currently
	// points at.
	Fetch(ctx context.Context, rawURL string, pin URLPin) (*FetchedURL, error)
}

type URLPin struct {
	// Revision is the immutable identifier the URL resolved to — a commit SHA
	// for GitHub.
	Revision string
	// Subpath is where in that revision the resource lives. A tree URL does
	// not say where the branch name ends and the path begins; this records
	// the answer so a pinned fetch need not rediscover it.
	Subpath string
}