agentinstall

type Action struct {
	Client Client `json:"client"`
	Kind   string `json:"kind"` // KindMCP, KindSkill, KindSetupSkill, KindInstructions, KindHooks
	Scope  string `json:"scope"`
	Target string `json:"target"` // config path, artifact path, or client executable
	Change string `json:"change"` // "installed", "updated", "removed", "unchanged", "skipped"
	DryRun bool   `json:"dry_run,omitempty"`
	Detail string `json:"detail,omitempty"`
}

type Client struct {
	Name    string `json:"name"`    // stable lowercase identity, e.g. "claude"
	Display string `json:"display"` // e.g. "Claude Code"
	Scope   string `json:"scope"`   // e.g. "user"
	Method  string `json:"method"`  // "cli" or "config"
}

type Environment interface {
	Reader
	Writer
}

type ExecRunner struct{}

type OSEnvironment struct {
	ExecRunner
}

type Options struct {
	Targets []string // explicit client names; empty or ["all"] means every supported client
	All     bool
	DryRun  bool
	// MCPOnly installs or removes only the MCP registration, never guidance.
	MCPOnly bool
	// Hooks opts in to the advisory, fail-open hooks of clients that document a
	// safe hook API. Uninstall always removes Grafo's hooks regardless.
	Hooks bool
	// Refresh updates only artifacts that are already present, so it never adds
	// a registration, skill, block, or hook that the user has not installed.
	Refresh bool
	// Announce receives the full planned action list before any mutation runs.
	Announce func(planned []Action)
	// contains filtered or unexported fields
}

type Reader interface {
	// LookPath resolves an executable on PATH.
	LookPath(file string) (string, error)
	// Output runs a read-only informational command (`--help`, `mcp list`).
	Output(ctx context.Context, name string, arguments ...string) ([]byte, error)
	// ReadFile reads a configuration file.
	ReadFile(name string) ([]byte, error)
	// Stat reports whether a path exists, following symlinks.
	Stat(name string) (fs.FileInfo, error)
	// Lstat reports on a path without following symlinks, so the installer can
	// refuse to write through one.
	Lstat(name string) (fs.FileInfo, error)
	// Readlink reads a symbolic link's target, so the installer can resolve a
	// path completely before deciding whether it stays inside the user's
	// configuration tree.
	Readlink(name string) (string, error)
	// GOOS reports the target operating system ("linux", "darwin", "windows").
	GOOS() string
	// HomeDir reports the current user's home directory.
	HomeDir() (string, error)
	// Getenv reads an environment variable.
	Getenv(key string) string
	// TempDir reports the directory used for temporary files.
	TempDir() string
}

type Receipt struct {
	Client         string `json:"client"`
	Kind           string `json:"kind"`
	Target         string `json:"target"`
	ResolvedTarget string `json:"resolved_target,omitempty"`
	Digest         string `json:"digest,omitempty"`
	// Commands are the exact command lines Grafo installed for a hook artifact,
	// in hookPhases order. Removal matches them exactly, so a user-authored
	// entry that merely resembles one is never claimed.
	Commands []string `json:"commands,omitempty"`
	Marker   string   `json:"marker,omitempty"`
	Guidance string   `json:"guidance_version,omitempty"`
	Grafo    string   `json:"grafo_version"`
	Updated  string   `json:"updated_at"`
}

type Runner interface {
	LookPath(file string) (string, error)
	Output(ctx context.Context, name string, arguments ...string) ([]byte, error)
	Run(ctx context.Context, name string, arguments ...string) ([]byte, error)
}

type Status struct {
	Client     Client `json:"client"`
	Installed  bool   `json:"installed"`      // the client itself was found
	Path       string `json:"path,omitempty"` // client executable or config file
	Registered bool   `json:"registered"`     // grafo is already registered
	Detail     string `json:"detail,omitempty"`
}

type Writer interface {
	// Run executes a client command that changes configuration.
	Run(ctx context.Context, name string, arguments ...string) ([]byte, error)
	// MkdirAll creates a configuration directory and its parents.
	MkdirAll(path string, perm fs.FileMode) error
	// WriteFileAtomic replaces path's contents by writing a temporary file in
	// the same directory and renaming it over path.
	WriteFileAtomic(path string, data []byte, perm fs.FileMode) error
	// Remove deletes one file or empty directory Grafo owns.
	Remove(path string) error
}