adapters

Documentation

Overview

Package adapters defines the ToolAdapter contract and the infrastructure (Registry, Factory) for registering and retrieving tool integrations.

Index

• Variables
• type AdapterStatus
• type InstallOpts
• type PromptStrategy
• type Registry
  • func (r *Registry) All() []ToolAdapter
  • func (r *Registry) Get(id string) (ToolAdapter, error)
  • func (r *Registry) Register(a ToolAdapter)
• type ToolAdapter
  • func NewAdapter(id string) (ToolAdapter, error)

Variables

var DefaultRegistry = &Registry{}

DefaultRegistry is the global adapter registry used by NewAdapter.

var ErrInstallFailed = errors.New("install failed")

ErrInstallFailed is returned when an adapter's Install() operation fails. The wrapped error provides the specific cause.

var ErrNotDetected = errors.New("adapter not detected")

ErrNotDetected is returned when the target AI tool is not detected on this system (e.g. binary not found, config dir missing).

var ErrUninstallFailed = errors.New("uninstall failed")

ErrUninstallFailed is returned when an adapter's Uninstall() operation fails. The wrapped error may contain multiple partial errors collected via errors.Join.

var ErrUnknownAdapter = errors.New("unknown adapter")

ErrUnknownAdapter is returned when an adapter ID is not registered in the Registry.

Types

type AdapterStatus

type AdapterStatus struct {
	// Installed reports whether Sequoia content is present for this tool.
	Installed bool
	// Version is the Sequoia version string present in the installation, or ""
	// if Sequoia has not been installed.
	Version string
	// Path is the absolute, OS-correct root installation path.
	Path string
}

AdapterStatus reports the current installation state of a tool adapter.

type InstallOpts

type InstallOpts struct {
	// Language is the ISO 639-1 or BCP 47 code (e.g. "en", "es", "pt-BR")
	// for the language to use when rendering templates and agent docs.
	Language string

	// Context is an optional context for cancellation propagation.
	// When set and cancelled, Install and Uninstall should abort early
	// and roll back any partial work. A nil Context means no cancellation
	// support (backwards-compatible with existing callers).
	Context context.Context
}

InstallOpts carries optional configuration for Install and Uninstall calls. It is designed to be extended with additional fields as needed without breaking the adapter interface (pass-by-value).

type PromptStrategy

type PromptStrategy int

PromptStrategy defines how Sequoia injects content into a tool's config.

const (
	// StrategyMarkdownSections injects a delimited section using start/end markers.
	StrategyMarkdownSections PromptStrategy = iota
	// StrategyFileReplace replaces the entire file, creating a backup first.
	StrategyFileReplace
	// StrategyConfigMerge injects a delimited section using start/end markers
	// for tools whose config format does not match Markdown sections but
	// still uses markers to delimit Sequoia content (e.g. Gemini CLI GEMINI.md).
	StrategyConfigMerge
	// StrategyTOMLMerge merges a [sequoia] TOML table into an existing TOML
	// config file, preserving all pre-existing keys and sections (e.g. Codex config.toml).
	StrategyTOMLMerge
)

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

Registry holds all registered ToolAdapters indexed by their ID. Use Register to add adapters — typically called from adapter init() functions, following the database/sql self-registration pattern.

Registry is safe for concurrent use.

func (*Registry) All

func (r *Registry) All() []ToolAdapter

All returns all registered adapters in registration order. The returned slice is a snapshot — subsequent Register calls do not affect it.

func (*Registry) Get

func (r *Registry) Get(id string) (ToolAdapter, error)

Get returns the adapter registered under id. If no adapter with that ID exists, it returns (nil, ErrUnknownAdapter).

func (*Registry) Register

func (r *Registry) Register(a ToolAdapter)

Register adds a to the registry. If an adapter with the same ID already exists, it is replaced. Replacement preserves the original registration order position.

type ToolAdapter

type ToolAdapter interface {
	// ID returns the unique machine-readable identifier (e.g. "claude-code").
	ID() string
	// Name returns the human-readable display name.
	Name() string
	// Detect reports whether the tool is installed on this machine.
	Detect() bool
	// IsInstalled reports whether Sequoia has already been installed for this tool.
	IsInstalled() bool
	// Install installs Sequoia files for this tool.
	// opts carries optional configuration such as the target language.
	Install(opts InstallOpts) error
	// Uninstall removes Sequoia files for this tool.
	// opts carries optional configuration such as the target language.
	Uninstall(opts InstallOpts) error
	// Status returns the current installation status.
	Status() AdapterStatus
	// SkillsPath returns the absolute path to the skills directory for this tool.
	SkillsPath() string
	// CommandsPath returns the absolute path to the commands directory for this tool.
	CommandsPath() string
	// SystemPromptPath returns the absolute path to the system prompt file for this tool.
	SystemPromptPath() string
	// PromptStrategy returns the injection strategy used by this adapter.
	PromptStrategy() PromptStrategy
}

ToolAdapter is the contract every tool integration must satisfy. Each concrete adapter lives in its own sub-package (e.g. adapters/claude) and self-registers via its init() function.

func NewAdapter

func NewAdapter(id string) (ToolAdapter, error)

NewAdapter returns the adapter registered under id in DefaultRegistry. It returns ErrUnknownAdapter (wrapped) if no adapter with that ID exists. This is a convenience wrapper around DefaultRegistry.Get.