platform

type Capabilities struct {
	Sync   bool     `json:"sync"`
	Hooks  bool     `json:"hooks"`
	MCP    bool     `json:"mcp"`
	Spawn  bool     `json:"spawn"`
	Scopes ScopeSet `json:"scopes"`
}

type HookScope int

type HookStatus struct {
	Installed bool   `json:"installed"`
	UpToDate  bool   `json:"up_to_date"`
	Command   string `json:"command,omitempty"`
}

type MCPStatus struct {
	Installed bool     `json:"installed"`
	UpToDate  bool     `json:"up_to_date"`
	Approved  *bool    `json:"approved,omitempty"`
	Command   string   `json:"command,omitempty"`
	Args      []string `json:"args,omitempty"`
}

type Platform interface {

	// Name returns the canonical slug used to look this adapter up in
	// the registry and in user-facing config (e.g. "claude").
	Name() string

	// Capabilities reports which features and scopes the adapter
	// supports. The CLI uses it to render precise error messages and
	// to power `brainjar platform list`.
	Capabilities() Capabilities

	// Sync writes prompt into the platform's managed section inside
	// projectRoot. Idempotent: if the managed section already matches,
	// Sync makes no filesystem change. Content outside the managed
	// section is preserved byte-for-byte.
	Sync(ctx context.Context, prompt string, projectRoot string) error

	// InstallHooks registers brainjar-owned hook entries in the
	// platform's settings file at the scope requested. User-authored
	// hooks and unrelated settings are preserved. Re-invoking with the
	// same binary is a no-op; re-invoking after the binary path
	// changes upserts. projectRoot is used when scope is
	// HookScopeProject or HookScopeLocal and ignored when scope is
	// HookScopeUser.
	InstallHooks(ctx context.Context, scope HookScope, projectRoot string) error

	// RemoveHooks strips only brainjar-owned entries from the
	// platform's settings file at the requested scope. User hooks and
	// other settings survive.
	RemoveHooks(ctx context.Context, scope HookScope, projectRoot string) error

	// HooksStatus reports whether brainjar hooks are installed at the
	// requested scope and whether the installed command matches what
	// InstallHooks would write now.
	HooksStatus(ctx context.Context, scope HookScope, projectRoot string) (HookStatus, error)

	// InstallMCP registers brainjar as an MCP server in the platform's
	// config at the given scope. projectRoot is used when scope needs
	// it; home is the resolved --home value baked into the registered
	// command args so the server targets the right brainjar workspace.
	InstallMCP(ctx context.Context, scope HookScope, projectRoot, home string) error

	// RemoveMCP strips only brainjar-owned MCP entries at the given
	// scope. Other entries are preserved.
	RemoveMCP(ctx context.Context, scope HookScope, projectRoot string) error

	// MCPStatus reports whether brainjar is registered at the given
	// scope and whether the installed command + args match what
	// InstallMCP would write now for the given home. Pass the same
	// home that would be used for a re-install so UpToDate reflects
	// real drift (e.g. the user changed --home since install).
	MCPStatus(ctx context.Context, scope HookScope, projectRoot, home string) (MCPStatus, error)

	// Spawn returns an *exec.Cmd ready to start the platform's agent
	// binary with prompt injected as its session system prompt. The
	// caller runs the Cmd, wires stdio, forwards signals, and
	// propagates the exit code.
	//
	// Prompt injection is platform-specific (--append-system-prompt for
	// Claude, --system-prompt for Codex, …). Adapters choose the flag,
	// the binary name, and any mandatory positional args.
	//
	// extraArgs are appended after the platform's injection flag so the
	// user can still pass agent-native flags (--model, --add-dir, …).
	//
	// Adapters that have no CLI injection surface return
	// ErrUnsupportedByPlatform. The CLI maps that to exit 2 with a
	// user-facing hint.
	//
	// Spawn does not touch the filesystem and does not preconfigure
	// stdio — the caller wires Stdin/Stdout/Stderr. exec.LookPath runs
	// when the caller Start()s the Cmd, so an absent binary surfaces
	// as exec.ErrNotFound at that point.
	Spawn(ctx context.Context, prompt string, extraArgs []string) (*exec.Cmd, error)

	// MapModelPrefs translates a generic ModelPrefs into a params map
	// the platform's runtime understands (e.g. Claude model IDs).
	MapModelPrefs(prefs *models.ModelPrefs) map[string]any
}

type ScopeSet struct {
	Project bool `json:"project"`
	Local   bool `json:"local"`
	User    bool `json:"user"`
}