// Package target defines the application-facing seam implemented by configuration Targets.
package target

import (
	"context"

	"proxyctl/internal/profile"
)

// State is the detected state of a Target's actual configuration.
type State string

const (
	Enabled  State = "Enabled"
	Disabled State = "Disabled"
	External State = "External"
	Drifted  State = "Drifted"
)

// Description is display metadata for a Target. The structured operational
// facts let presentation layers establish a stable hierarchy without parsing
// prose; they do not participate in configuration or restoration behavior.
type Description struct {
	Name        string
	Summary     string
	Scope       string
	Permissions string
	Ownership   string
	RestartRisk string
	Details     string
}

type Availability struct {
	Available bool
	Evidence  string
}

type Inspection struct {
	State    State
	Evidence string
}

// Detection is one presentation-independent availability and configuration
// inspection outcome. Err distinguishes a failed check from a truthful
// unavailable or disabled result.
type Detection struct {
	Availability Availability
	Inspection   Inspection
	Err          error
}

// Detector is the optional structured detection seam. Targets which can
// preserve lower-level check failures implement it; legacy Targets continue to
// participate through Availability and Inspect.
type Detector interface {
	Detect(context.Context, *profile.Profile) Detection
}

// OperationResult reports the adapter's immediate operation outcome. When Err
// is non-nil, Inspection is advisory because it may have been captured before a
// partial write or command failure. The Application explicitly calls Inspect
// before publishing the final state of a failed operation.
type OperationResult struct {
	Inspection Inspection
	Err        error
}

// Check is one read-only diagnostic observation with the evidence behind it.
type Check struct {
	Name     string
	OK       bool
	Evidence string
}

// Diagnosable is the optional Target capability for command and write-authority
// checks which cannot be inferred from availability and inspection alone.
type Diagnosable interface {
	DiagnosticChecks(context.Context, *profile.Profile) []Check
}

// MutationAuthorizer optionally explains why a detected Target cannot be
// changed by the current process. It is read-only and presentation-independent.
type MutationAuthorizer interface {
	MutationAuthority(context.Context) Check
}

// Target hides platform paths and commands from the application and TUI.
type Target interface {
	ID() string
	Description() Description
	Availability(context.Context) Availability
	Inspect(context.Context, *profile.Profile) Inspection
	// Confirmation returns a warning that must be accepted before SetDesired.
	// An empty string means the operation needs no confirmation.
	Confirmation(enabled bool) string
	SetDesired(context.Context, bool, *profile.Profile) OperationResult
}