platform

type Capabilities struct {
	Sync   bool     `json:"sync"`
	Hooks  bool     `json:"hooks"`
	MCP    bool     `json:"mcp"`
	Spawn  bool     `json:"spawn"`
	Skills bool     `json:"skills"`
	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 ModelCatalog interface {
	// List returns every model the adapter knows about. Static adapters
	// ignore ctx; a future dynamic-fetch adapter can use it.
	List(ctx context.Context) ([]ModelInfo, error)

	// Resolve maps a user-supplied name to a ModelInfo. The name may be
	// an alias ("opus", "opus-4", "flagship") or a literal ID
	// ("claude-opus-4-6"). Unknown names return (zero, false) — never
	// an error. Callers warn but don't fail.
	Resolve(name string) (ModelInfo, bool)
}

type ModelInfo struct {
	ID      string   `json:"id"`
	Aliases []string `json:"aliases,omitempty"`
	Family  string   `json:"family,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

	// SyncUser writes prompt into the platform's user-scope managed
	// section (e.g. ~/.claude/CLAUDE.md, $CODEX_HOME/AGENTS.md).
	// Idempotent. Adapters whose Capabilities.Scopes.User is false
	// return ErrUnsupportedByPlatform.
	SyncUser(ctx context.Context, prompt string) error

	// SyncRemove strips brainjar's managed section from the project's
	// sync target, preserving content outside the markers. If the file
	// becomes empty after removal, the file is deleted. Used when a
	// project has no project-scope override — leaving stale brainjar
	// content behind would be misleading.
	SyncRemove(ctx context.Context, 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)

	// EmitSkills writes each Skill in skills to the platform's skill
	// directory at the applicable scope. Skills carry their own
	// SkillScope (project vs user) — adapters route on it. Adapters
	// always prune brainjar-owned skill dirs not present in skills;
	// user-authored skill dirs (no .brainjar-managed marker) survive
	// untouched.
	//
	// projectRoot is required when any skill in skills has
	// SkillScopeProject. Adapters return a SkillEmitResult with
	// per-scope wrote / unchanged / pruned slug lists so the CLI can
	// report churn to the user.
	//
	// Adapters that return Capabilities.Skills == false return
	// ErrUnsupportedByPlatform from EmitSkills and SkillsStatus. The
	// CLI converts that to a one-line warning, not a hard failure —
	// sync should still write CLAUDE.md / AGENTS.md.
	EmitSkills(ctx context.Context, projectRoot string, skills []SkillEmit) (SkillEmitResult, error)

	// SkillsStatus reports brainjar-owned skills currently on disk
	// at each applicable scope. Used by `brainjar status --skills`
	// and by integration tests.
	SkillsStatus(ctx context.Context, projectRoot string) (SkillsStatus, error)

	// Catalog returns this adapter's model catalog. Always non-nil — an
	// adapter with no model namespace returns an empty catalog whose
	// List is empty and whose Resolve always returns (zero, false).
	Catalog() ModelCatalog

	// MapModelPrefs translates a generic ModelPrefs into a params map
	// the platform's runtime understands (e.g. Claude model IDs). The
	// canonical implementation is MapWithCatalog(c.Catalog(), prefs).
	MapModelPrefs(prefs *models.ModelPrefs) map[string]any

	// ModelArgs renders ModelPrefs as argv elements ready to prepend to
	// a Spawn invocation. Adapters whose runtime accepts model
	// selection on the CLI (Claude, Codex) emit "--model <id>" and
	// any related flags. Adapters where model selection is UI-bound
	// (Cursor) return nil. Empty prefs always produce nil.
	//
	// Callers prepend the result to user-supplied extra args so an
	// explicit `-- --model X` from the user wins over the brain's
	// stored preference.
	ModelArgs(prefs *models.ModelPrefs) []string
}

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

type SkillEmit struct {
	Slug        string
	Description string
	Body        string
	Triggers    []string
	Version     int
	Scope       SkillScope
	Files       []SkillFile

	// Raw, when non-empty, is the byte-for-byte SKILL.md content the
	// adapter should write instead of rendering frontmatter+body.
	// Brainjar's embedded guides set this so their on-disk bytes match
	// the source committed to the repo. User-content skills leave it
	// nil and let the adapter render through skillemit.Render.
	Raw []byte
}

type SkillEmitResult struct {
	Project SkillScopeResult `json:"project"`
	User    SkillScopeResult `json:"user"`
}

type SkillFile struct {
	Path    string
	Content []byte
}

type SkillOnDisk struct {
	Slug    string `json:"slug"`
	Version int    `json:"version"`
	Path    string `json:"path"`
}

type SkillScope string

type SkillScopeResult struct {
	Dir       string   `json:"dir,omitempty"`
	Wrote     []string `json:"wrote"`
	Unchanged []string `json:"unchanged"`
	Pruned    []string `json:"pruned"`
}

type SkillsStatus struct {
	Project []SkillOnDisk `json:"project"`
	User    []SkillOnDisk `json:"user"`
}

type SliceCatalog struct {
	Entries []ModelInfo
}