agents

type AgentTarget interface {
	// ID returns this target's stable registry key.
	ID() TargetID

	// DisplayName returns the agent's human-readable name for CLI output
	// and the interactive multi-select (D-03).
	DisplayName() string

	// SupportsLocation reports whether this target accepts loc. Codex,
	// Antigravity, and Hermes are global-only and return false for
	// LocationLocal (D-03, D-05).
	SupportsLocation(loc Location) bool

	// Detect reports whether the agent is installed and whether
	// codegraph is already configured for it at loc, driving --target
	// auto's detected-only default (D-03).
	Detect(loc Location) DetectionResult

	// Install writes (or updates, idempotently) this agent's MCP config
	// entry and, for the 4 agents that get one, its marker-fenced
	// instructions file (D-01a, D-07).
	Install(loc Location, opts InstallOptions) WriteResult

	// Uninstall reverses everything Install wrote for this target/loc,
	// preserving every unrelated key/section in every file it touches
	// (D-02, D-07, D-08). Never errors on a target that was never
	// installed.
	Uninstall(loc Location) WriteResult

	// DescribePaths returns every config/instructions file path this
	// target reads or writes at loc, for --print-config-style reporting
	// and test assertions.
	DescribePaths(loc Location) []string
}

type DetectionResult struct {
	// Installed is true when the agent's own config dir/primary file
	// exists, independent of whether codegraph has been configured for it.
	Installed bool
	// AlreadyConfigured is true when the codegraph MCP entry (and/or
	// marker block) is already present for this target/location.
	AlreadyConfigured bool
	// ConfigPath is the primary config file path this detection checked,
	// surfaced for install/uninstall status reporting.
	ConfigPath string
}

type FileAction string

type FileResult struct {
	// Path is the file that was read/written (or would have been).
	Path string
	// Action is what happened to Path (D-07/D-08).
	Action FileAction
}

type InstallOptions struct {
	// AutoAllow, when true, additionally writes
	// permissions.allow += ["mcp__codegraph__*"] to Claude Code's
	// settings.json (Claude-only; a no-op for every other target, D-05).
	AutoAllow bool
	// ExecPath is the absolute path to the running codegraph binary,
	// resolved once by the CLI via os.Executable() and passed down so
	// every agent's MCP command entry launches the exact binary the user
	// ran `install` from, not a PATH guess (D-04).
	ExecPath string
}

type Location string

type TargetID string

type WriteResult struct {
	// Files lists every file this call touched, in the order they were
	// written.
	Files []FileResult
	// Notes carries agent-specific advisory text surfaced to the user
	// (e.g. Kiro's "enable MCP in Settings" reminder); empty for most
	// targets.
	Notes []string
	// Errors carries every I/O error encountered while writing/removing a
	// file this call attempted to touch — path context is included in
	// each error's message. A non-empty Errors means the corresponding
	// file's Install/Uninstall step did NOT complete, so the caller (the
	// CLI's install/uninstall commands) MUST surface these and report a
	// non-zero exit rather than a silent "unchanged"/"not-configured"
	// (CR-01: a swallowed write error must never look like a no-op).
	Errors []error
}