contexts

type ClientEntry struct {
	Strategy string
	// Target is the absolute path gridctl wrote to.
	Target string
	// InstalledHash is the managed-region hash exactly as written.
	InstalledHash string
	// CanonicalHash is the canonical file's hash at sync time.
	CanonicalHash string
	// CreatedFile records whether gridctl created the target file itself
	// (unsync then removes the whole file, not just the managed region).
	CreatedFile bool
	// InputHashes records, for a compiled fragments-mode target, each
	// input fragment's hash at sync time so staleness can name which
	// fragment moved. Absent outside fragments mode.
	InputHashes map[string]string
	SyncedAt    time.Time
}

type ClientStatus struct {
	Slug       string `json:"slug"`
	Name       string `json:"name"`
	Supported  bool   `json:"supported"`
	Available  bool   `json:"available"`
	Unofficial bool   `json:"unofficial,omitempty"`
	Strategy   string `json:"strategy,omitempty"`
	// Mode is how this client receives the context: single-file (the
	// pre-fragments default), compiled, or multi-file. Omitted while
	// fragments mode is off so pre-fragments consumers see no new field.
	Mode       string     `json:"mode,omitempty"`
	TargetPath string     `json:"target_path,omitempty"`
	State      string     `json:"state"`
	Detail     string     `json:"detail,omitempty"`
	SyncedAt   *time.Time `json:"synced_at,omitempty"`
	// Fragments lists every non-synced fragment with its own state, for
	// multi-file targets only. The aggregate State/Detail keep their
	// worst-state-wins prose (a drifted fragment would otherwise hide a
	// stale one from any structured consumer).
	Fragments []FragmentStatus `json:"fragments,omitempty"`
}

type Fragment struct {
	// Name is the file base without .md; FileName includes it.
	Name     string
	FileName string
	// Description and Paths are the only modeled frontmatter keys. Paths
	// are glob strings passed to clients as metadata; gridctl never
	// evaluates them (the Copilot applyTo transform is the one rewrite).
	Description string
	Paths       []string
	Extra       []FragmentExtraField
	Body        string
	Raw         []byte
}

type FragmentAddResult struct {
	// Migrated is true when this call activated fragments mode by moving
	// the canonical AGENTS.md to fragments/00-default.md.
	Migrated bool
	// MigratedBackup is the canonical file's backup path when Migrated.
	MigratedBackup string
	// CreatedPath is the new fragment's path.
	CreatedPath string
}

type FragmentEntry struct {
	// Target is the absolute path gridctl wrote.
	Target string
	// InstalledHash is the hash of the bytes exactly as written (drift).
	InstalledHash string
	// CanonicalHash is the source fragment's hash at sync time (staleness).
	CanonicalHash string
	// Pack tags the projection with the pack that applied it.
	Pack     string
	SyncedAt time.Time
}

type FragmentExtraField struct {
	Key   string
	Value *yaml.Node
}

type FragmentLockFile struct {
	// Projections maps fragment name -> client slug -> record.
	Projections map[string]map[string]*FragmentEntry
}

type FragmentStatus struct {
	Name  string `json:"name"`
	State string `json:"state"`
	// Pack names the pack that applied this fragment projection; empty
	// for projections made outside a pack. Additive provenance for UI
	// chips. Whole-document (single-file and compiled) context entries
	// record no pack tag, so provenance is per-fragment only.
	Pack string `json:"pack,omitempty"`
}

type LockFile struct {
	Version int
	// Scope is "global" today, recorded as the engine entry's source.
	Scope   string
	Clients map[string]*ClientEntry
}

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

type ScanEntry struct {
	Slug   string `json:"slug"`
	Name   string `json:"name"`
	Path   string `json:"path"`
	Exists bool   `json:"exists"`
	Size   int64  `json:"size"`
}

type Strategy string

type SyncOptions struct {
	// Force overwrites drifted targets and repairs corrupt blocks.
	Force bool
	// DryRun renders and diffs without writing anything.
	DryRun bool
	// Pack tags recorded fragment projections with the applying pack.
	// Empty keeps any existing tag.
	Pack string
	// PackRules limits the Pack tag to these fragment names. A pack apply
	// projects the whole fragment set (composition is global), but must
	// only claim ownership of the fragments it shipped; tagging a user
	// fragment would let pack remove retract it.
	PackRules []string
}

type SyncResult struct {
	Slug       string `json:"slug"`
	Name       string `json:"name"`
	Strategy   string `json:"strategy"`
	Mode       string `json:"mode,omitempty"`
	Fragment   string `json:"fragment,omitempty"`
	TargetPath string `json:"target_path"`
	Action     string `json:"action"`
	// Detail carries honest render loss: frontmatter a client's dialect
	// cannot express, named rather than silently dropped.
	Detail     string `json:"detail,omitempty"`
	BackupPath string `json:"backup_path,omitempty"`
	Diff       string `json:"diff,omitempty"`
	Error      string `json:"error,omitempty"`
}

type Target struct {
	Slug     string
	Name     string
	Strategy Strategy
	// Paths is the write target per OS. A missing key means the client
	// has no known global context path on that platform.
	Paths map[string]string
	// ImportPaths is where a user's pre-existing hand-written global
	// context most likely lives, for `ctx init --import`. Defaults to
	// Paths when empty.
	ImportPaths map[string]string
	// DetectDirs mark the client as initialized on this machine when any
	// of them exists. Sync refuses to create client config trees
	// wholesale, so these gate every write.
	DetectDirs []string
	// Frontmatter is prepended verbatim to dedicated files for clients
	// whose rules format requires it (e.g. VS Code *.instructions.md).
	Frontmatter string
	// MaxChars caps the rendered target file size; 0 means unlimited.
	// Windsurf enforces a 6,000-character limit on global_rules.md.
	MaxChars int
	// Unofficial marks targets whose path rests on unofficial sourcing
	// rather than published client documentation. The projection is
	// supported; the path may move without an upstream release note.
	// Surfaced in status output so the caveat is never silent.
	Unofficial bool
}

type UnsupportedClient struct {
	Slug   string
	Name   string
	Reason string
}

type UnsyncResult struct {
	Slug       string `json:"slug"`
	TargetPath string `json:"target_path"`
	Fragment   string `json:"fragment,omitempty"`
	// Action is "removed-file", "removed-region", or "already-gone".
	Action string `json:"action"`
}