platform

type AuditPrinter interface {
	PrintAudit(w io.Writer, project, repoPath, agentsHome string)
}

type BranchSessionFinder interface {
	FindSessionsOnBranch(home, projectPath, branch string, maxResults int) []BranchSessionInfo
}

type BranchSessionInfo struct {
	SessionID    string
	Timestamp    string
	MessageCount int
}

type BrokenLink struct {
	// PlatformID identifies which platform owns this link (e.g. "cursor").
	PlatformID string
	// LinkPath is the display-friendly path to the broken link — typically
	// repo-relative for project links or home-relative for user-config links.
	LinkPath string
	// Dest is the raw target string returned by the OS (os.Readlink output
	// for symlinks/junctions; empty for hard links whose canonical source
	// could not be matched).
	Dest string
	// DisplayDest is Dest after path resolution and ~/-prefix formatting,
	// suitable for direct rendering by doctor/status.
	DisplayDest string
}

type BrokenLinkReporter interface {
	BrokenLinks(project, repoPath, agentsHome string) []BrokenLink
}

type CanonicalBucket string

type CanonicalBucketSpec struct {
	Name        CanonicalBucket
	Stage       int
	CountDirs   bool
	MarkerFile  string
	Description string
}

type CommitAttribution struct {
	CommitHash           string
	BranchName           string
	ScoredAt             string
	LinesAdded           int
	LinesDeleted         int
	ComposerLinesAdded   int
	ComposerLinesDeleted int
	HumanLinesAdded      int
	V2AIPercentage       float64
}

type DailyUsage struct {
	Date          string
	MessageCount  int
	SessionCount  int
	ToolCallCount int
}

type HookEmissionMode struct {
	Shape     HookShape
	Transport HookTransport
}

type HookPlatformOverride struct {
	Event   string `yaml:"event"`
	Matcher string `yaml:"matcher"`
	File    string `yaml:"file"`
}

type HookShape string

type HookSourceKind string

type HookSpec struct {
	Name         string
	Scope        string
	SourcePath   string
	SourceBucket string
	SourceKind   HookSourceKind
	Description  string
	When         string
	// WhenEvents, when non-empty, declares a multi-event hook. The
	// loader rejects manifests that set both `when` and `when_events`
	// (mutual exclusion) and manifests with duplicate or unknown
	// canonical events (P1c contract `when_events` rules). At render
	// time the spec is expanded into one rendered action per canonical
	// event the target platform documents.
	WhenEvents        []string
	MatchTools        []string
	MatchExpression   string
	Command           string
	TimeoutMS         int
	EnabledOn         []string
	RequiredOn        []string
	PlatformOverrides map[string]HookPlatformOverride
}

type HookTransport string

type LinkCounter interface {
	CountLinks(project, repoPath, agentsHome string) (ok, broken int)
}

type MCPFileSpec struct {
	Scope      string
	BaseName   string
	SourcePath string
}

type ModelTokenUsage struct {
	InputTokens              int
	OutputTokens             int
	CacheReadInputTokens     int
	CacheCreationInputTokens int
}

type OrphanCanonical struct {
	// Name is the entry basename as it appears under ~/.agents/<bucket>/.
	Name string
	// DisplayNote is either "" (plain orphan) or a pre-formatted suffix
	// describing the mis-pointed target. Callers concatenate it directly
	// when rendering.
	DisplayNote string
}

type OrphanCanonicalReporter interface {
	OrphanCanonicals(project, projectPath, agentsHome, bucket string) []OrphanCanonical
}

type Platform interface {
	// ID returns the platform identifier (e.g. "cursor", "claude").
	ID() string
	// DisplayName returns the human-readable name.
	DisplayName() string
	// IsInstalled checks if this platform is installed on the system.
	IsInstalled() bool
	// Version returns the detected version string, or empty string.
	Version() string
	// CreateLinks creates all managed links for a project in repoPath.
	CreateLinks(project, repoPath string) error
	// RemoveLinks removes all managed links for a project from repoPath.
	RemoveLinks(project, repoPath string) error
	// HasDeprecatedFormat checks if the project has deprecated config files.
	HasDeprecatedFormat(repoPath string) bool
	// DeprecatedDetails returns a description of the deprecated format.
	DeprecatedDetails(repoPath string) string
	// SharedTargetIntents returns the ResourceIntents this platform would write
	// to shared (cross-platform) repo-local targets such as .agents/skills/*.
	// These intents are aggregated by the command layer into a single
	// ResourcePlan so compatible targets are deduped and conflicts are caught
	// before any filesystem writes occur.
	SharedTargetIntents(project string) ([]ResourceIntent, error)
}

type PlatformBadge struct {
	// Name is the human-readable platform name shown in the badge row
	// (e.g. "Cursor", "Claude Code").
	Name string
	// Present is true when this platform has any managed state for the
	// inspected scope (project or user-home).
	Present bool
	// Broken is true when any of the platform's managed links are broken.
	Broken bool
}

type PlatformUsageStats struct {
	PlatformID        string
	TotalSessions     int
	TotalMessages     int
	TokensByModel     map[string]ModelTokenUsage
	DailyActivity     []DailyUsage
	RecentSessions    []SessionSummary
	CommitAttribution []CommitAttribution
}

type PluginKind string

type PluginMarketplace struct {
	Repo string   `yaml:"repo,omitempty"`
	Tags []string `yaml:"tags,omitempty"`
}

type PluginResources struct {
	Agents   []string `yaml:"agents,omitempty"`
	Skills   []string `yaml:"skills,omitempty"`
	Commands []string `yaml:"commands,omitempty"`
	Hooks    []string `yaml:"hooks,omitempty"`
	MCP      []string `yaml:"mcp,omitempty"`
}

type PluginSpec struct {
	SchemaVersion     int                       `yaml:"schema_version"`
	Kind              PluginKind                `yaml:"kind"`
	Name              string                    `yaml:"name"`
	Version           string                    `yaml:"version,omitempty"`
	DisplayName       string                    `yaml:"display_name,omitempty"`
	Description       string                    `yaml:"description,omitempty"`
	Authors           []string                  `yaml:"authors,omitempty"`
	Homepage          string                    `yaml:"homepage,omitempty"`
	License           string                    `yaml:"license,omitempty"`
	Platforms         []string                  `yaml:"platforms"`
	Resources         PluginResources           `yaml:"resources,omitempty"`
	Marketplace       PluginMarketplace         `yaml:"marketplace,omitempty"`
	Dependencies      map[string]any            `yaml:"dependencies,omitempty"`
	PlatformOverrides map[string]map[string]any `yaml:"platform_overrides,omitempty"`
	Dir               string                    `yaml:"-"`
	ManifestPath      string                    `yaml:"-"`
	Scope             string                    `yaml:"-"`
}

type ResourceIntent struct {
	IntentID      string                `json:"intent_id"`
	Project       string                `json:"project"`
	Bucket        string                `json:"bucket"`
	LogicalName   string                `json:"logical_name"`
	TargetPath    string                `json:"target_path"`
	Ownership     ResourceOwnership     `json:"ownership"`
	SourceRef     ResourceSourceRef     `json:"source_ref"`
	Shape         ResourceShape         `json:"shape"`
	Transport     ResourceTransport     `json:"transport"`
	Materializer  string                `json:"materializer"`
	ReplacePolicy ResourceReplacePolicy `json:"replace_policy"`
	PrunePolicy   ResourcePrunePolicy   `json:"prune_policy"`
	Provenance    ResourceProvenance    `json:"provenance"`
	Precedence    int                   `json:"precedence,omitempty"`
	ConflictKey   string                `json:"conflict_key,omitempty"`
	MarkerFiles   []string              `json:"marker_files,omitempty"`
	EnabledOn     []string              `json:"enabled_on,omitempty"`
	ReviewHint    string                `json:"review_hint,omitempty"`
}

type ResourceOwnership string

type ResourcePlan struct {
	Resources []plannedResource
}

type ResourceProvenance struct {
	Emitter   string `json:"emitter,omitempty"`
	Operation string `json:"operation,omitempty"`
	Detail    string `json:"detail,omitempty"`
}

type ResourcePrunePolicy string

type ResourceReplacePolicy string

type ResourceShape string

type ResourceSourceKind string

type ResourceSourceRef struct {
	Scope        string             `json:"scope"`
	Bucket       string             `json:"bucket"`
	RelativePath string             `json:"relative_path"`
	Kind         ResourceSourceKind `json:"kind"`
	Origin       string             `json:"origin,omitempty"`
}

type ResourceTransport string

type RuleFileSpec struct {
	Scope      string
	BaseName   string // full file name, e.g. rules.mdc
	SourcePath string
}

type SessionReader interface {
	// AIAgentPrefix returns the harness prefix used in the AI_AGENT env var
	// convention (e.g. "claude-code" for AI_AGENT=claude-code_2-1-138_agent).
	// Returns "" if this platform does not follow the AI_AGENT convention.
	AIAgentPrefix() string
	// SessionEnvs lists env var names (in preference order) that carry the
	// active session ID. First non-empty value wins.
	SessionEnvs() []string
	// EntrypointEnvs lists env var names for the session launch entrypoint.
	EntrypointEnvs() []string
	// ResolveModel scans the platform's session store for the model active in
	// the given session. Returns "" when unavailable or not yet implemented.
	ResolveModel(home, projectPath, sessionID string) string
}

type SessionSummary struct {
	ID        string
	Name      string
	UpdatedAt string
}

type SessionTokenMetrics struct {
	InputTokens         int
	OutputTokens        int
	CacheReadTokens     int
	CacheCreationTokens int
	ReasoningTokens     int     // Codex o-series reasoning tokens; 0 for Claude Code
	CacheHitRate        float64 // CacheReadTokens/(CacheReadTokens+CacheCreationTokens); 0 = unavailable
	MessageCount        int
}

type SessionTokenScanner interface {
	ScanSessionTokens(home, projectPath, sessionID, afterTimestamp string) SessionTokenMetrics
}

type SettingsFileSpec struct {
	Scope      string
	BaseName   string
	SourcePath string
}

type SingleFileLinkSpec struct {
	// LinkPath is the absolute path to the managed file link.
	LinkPath string
	// CanonicalPaths is the ordered list of acceptable sources. The first
	// hard-linked match wins; if none match and the link exists, the link
	// is reported as broken.
	CanonicalPaths []string
}

type StatsReader interface {
	ReadUsageStats(home string) *PlatformUsageStats
}

type StatusBadger interface {
	Badge(project, repoPath, agentsHome string) PlatformBadge
}

type UserConfigReporter interface {
	// UserBrokenLinks returns broken managed links under the user's home
	// directory for this platform. Consumer: doctor.collectBrokenUserLinks.
	UserBrokenLinks(home string) []BrokenLink
	// UserBadge returns the user-config badge for the platform. Consumer:
	// status.collectUserConfigPlatforms.
	UserBadge(home string) PlatformBadge
}