adapters

Documentation

Index

• Constants
• Variables
• type Adapter
• type AdapterDetection
• type AttachRequest
• type Descriptor
• type DetachRequest
• type DetectedTarget
• type FileOperation
• type ImportRequest
• type InstallMode
• type OperationKind
• type Registry
  • func NewRegistry(ctx context.Context, opts RegistryOptions) (*Registry, error)
  • func (r *Registry) BuiltIn(id string) (Adapter, bool)
  • func (r *Registry) Get(id string) (Adapter, bool)
  • func (r *Registry) GlobalCustom(id string) (Adapter, bool)
  • func (r *Registry) List() []Descriptor
  • func (r *Registry) ProjectCustom(id string) (Adapter, bool)
• type RegistryOptions
• type Scope
• type Source
• type SupportLevel
• type SupportMatrix
• type TargetKind

Constants

const (
	IDClaudeCode = "claude"
	IDCodexCLI   = "codex"
	IDOpenCode   = "opencode"
)

Variables

var ErrUnsupported = errors.New("unsupported adapter operation")

Types

type Adapter

type Adapter interface {
	ID() string
	Detect(ctx context.Context, projectPath string) (AdapterDetection, error)
	Support(kind components.Kind, scope Scope) SupportLevel
	PlanAttach(ctx context.Context, req AttachRequest) ([]FileOperation, error)
	PlanDetach(ctx context.Context, req DetachRequest) ([]FileOperation, error)
	Import(ctx context.Context, req ImportRequest) ([]components.Component, error)
}

Adapter maps normalized ContextCart components to one agent's native files.

type AdapterDetection

type AdapterDetection struct {
	AdapterID   string           `json:"adapterId" yaml:"adapterId"`
	ProjectPath string           `json:"projectPath,omitempty" yaml:"projectPath,omitempty"`
	Detected    bool             `json:"detected" yaml:"detected"`
	Targets     []DetectedTarget `json:"targets,omitempty" yaml:"targets,omitempty"`
	Warnings    []string         `json:"warnings,omitempty" yaml:"warnings,omitempty"`
}

AdapterDetection summarizes read-only discovery for one adapter.

type AttachRequest

type AttachRequest struct {
	ProjectPath  string               `json:"projectPath" yaml:"projectPath"`
	Scope        Scope                `json:"scope" yaml:"scope"`
	Component    components.Component `json:"-" yaml:"-"`
	ComponentDir string               `json:"componentDir,omitempty" yaml:"componentDir,omitempty"`
	OperationID  string               `json:"operationId,omitempty" yaml:"operationId,omitempty"`
	Options      map[string]string    `json:"options,omitempty" yaml:"options,omitempty"`
	Env          map[string]string    `json:"env,omitempty" yaml:"env,omitempty"`
}

AttachRequest gives adapters enough normalized data to render native file operations without knowing about stores or writers.

type Descriptor

type Descriptor struct {
	ID          string        `json:"id" yaml:"id"`
	Name        string        `json:"name,omitempty" yaml:"name,omitempty"`
	Description string        `json:"description,omitempty" yaml:"description,omitempty"`
	Source      Source        `json:"source" yaml:"source"`
	Path        string        `json:"path,omitempty" yaml:"path,omitempty"`
	Overrides   []Source      `json:"overrides,omitempty" yaml:"overrides,omitempty"`
	Support     SupportMatrix `json:"support,omitempty" yaml:"support,omitempty"`
}

Descriptor is a stable registry listing record.

type DetachRequest

type DetachRequest struct {
	ProjectPath string         `json:"projectPath" yaml:"projectPath"`
	Scope       Scope          `json:"scope" yaml:"scope"`
	Component   components.Ref `json:"component" yaml:"component"`
	TargetPath  string         `json:"targetPath,omitempty" yaml:"targetPath,omitempty"`
	TargetKey   string         `json:"targetKey,omitempty" yaml:"targetKey,omitempty"`
	OperationID string         `json:"operationId,omitempty" yaml:"operationId,omitempty"`
}

DetachRequest is intentionally narrow until the writer lockfile schema lands.

type DetectedTarget

type DetectedTarget struct {
	Scope      Scope        `json:"scope" yaml:"scope"`
	Kind       TargetKind   `json:"kind" yaml:"kind"`
	Path       string       `json:"path" yaml:"path"`
	Exists     bool         `json:"exists" yaml:"exists"`
	Readable   bool         `json:"readable" yaml:"readable"`
	WriteLevel SupportLevel `json:"writeLevel" yaml:"writeLevel"`
	Notes      []string     `json:"notes,omitempty" yaml:"notes,omitempty"`
}

DetectedTarget is one native file or directory that an adapter can inspect.

type FileOperation

type FileOperation struct {
	Kind        OperationKind  `json:"kind" yaml:"kind"`
	AdapterID   string         `json:"adapterId" yaml:"adapterId"`
	Component   components.Ref `json:"component" yaml:"component"`
	Scope       Scope          `json:"scope" yaml:"scope"`
	TargetKind  TargetKind     `json:"targetKind" yaml:"targetKind"`
	TargetPath  string         `json:"targetPath" yaml:"targetPath"`
	TargetKey   string         `json:"targetKey,omitempty" yaml:"targetKey,omitempty"`
	SourcePath  string         `json:"sourcePath,omitempty" yaml:"sourcePath,omitempty"`
	Content     []byte         `json:"content,omitempty" yaml:"content,omitempty"`
	Format      string         `json:"format,omitempty" yaml:"format,omitempty"`
	InstallMode InstallMode    `json:"installMode,omitempty" yaml:"installMode,omitempty"`
	Summary     string         `json:"summary,omitempty" yaml:"summary,omitempty"`
	Warning     string         `json:"warning,omitempty" yaml:"warning,omitempty"`
}

FileOperation is a deterministic adapter render result. Adapters produce operations only; writer code is responsible for backups, atomic writes, and lockfile updates.

type ImportRequest

type ImportRequest struct {
	ProjectPath string            `json:"projectPath,omitempty" yaml:"projectPath,omitempty"`
	Scope       Scope             `json:"scope,omitempty" yaml:"scope,omitempty"`
	SourcePath  string            `json:"sourcePath,omitempty" yaml:"sourcePath,omitempty"`
	Format      string            `json:"format,omitempty" yaml:"format,omitempty"`
	Options     map[string]string `json:"options,omitempty" yaml:"options,omitempty"`
}

ImportRequest asks an adapter to read existing native config and return normalized component candidates. Import remains read-only until the importer commit step saves returned components.

type InstallMode

type InstallMode string

InstallMode records how a component is expected to be represented in a project file or directory.

const (
	InstallManagedMarkdownBlock InstallMode = "managed-markdown-block"
	InstallManagedConfigKey     InstallMode = "managed-config-key"
	InstallManagedLineBlock     InstallMode = "managed-line-block"
	InstallSymlink              InstallMode = "symlink"
	InstallCopy                 InstallMode = "copy"
)

type OperationKind

type OperationKind string

OperationKind is the adapter-facing file operation vocabulary. The planner can later lift these into richer collision-aware plans without adapters writing files directly.

const (
	OperationCreate  OperationKind = "create"
	OperationModify  OperationKind = "modify"
	OperationSymlink OperationKind = "symlink"
	OperationCopy    OperationKind = "copy"
	OperationRemove  OperationKind = "remove"
	OperationNoop    OperationKind = "noop"
)

type Registry

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

Registry keeps built-ins and user overrides in separate maps while exposing project-local > global-custom > built-in lookup precedence.

func NewRegistry

func NewRegistry(ctx context.Context, opts RegistryOptions) (*Registry, error)

NewRegistry loads built-in adapters plus global and optional project-local custom adapter manifests.

func (*Registry) BuiltIn

func (r *Registry) BuiltIn(id string) (Adapter, bool)

BuiltIn returns the unmodified built-in adapter, even when overridden.

func (*Registry) Get

func (r *Registry) Get(id string) (Adapter, bool)

Get returns the effective adapter for id using project-local, global-custom, then built-in precedence.

func (*Registry) GlobalCustom

func (r *Registry) GlobalCustom(id string) (Adapter, bool)

GlobalCustom returns a user-scoped custom adapter, if one exists.

func (*Registry) List

func (r *Registry) List() []Descriptor

List returns effective adapter descriptors in deterministic ID order.

func (*Registry) ProjectCustom

func (r *Registry) ProjectCustom(id string) (Adapter, bool)

ProjectCustom returns a project-local custom adapter, if one exists.

type RegistryOptions

type RegistryOptions struct {
	Home        string
	ProjectPath string
}

RegistryOptions controls custom adapter loading.

type Scope

type Scope string

Scope names where an adapter target lives. Attach/detach writes are project-scoped in v1; user and global scopes are for audit/import metadata.

const (
	ScopeProject Scope = "project"
	ScopeUser    Scope = "user"
	ScopeGlobal  Scope = "global"
)

type Source

type Source string

Source names where an adapter definition came from.

const (
	SourceBuiltIn       Source = "built-in"
	SourceGlobalCustom  Source = "global-custom"
	SourceProjectCustom Source = "project-custom"
)

type SupportLevel

type SupportLevel string

SupportLevel captures how far ContextCart can safely go for one adapter target today.

const (
	SupportUnsupported SupportLevel = "unsupported"
	SupportAuditOnly   SupportLevel = "audit-only"
	SupportPlanOnly    SupportLevel = "plan-only"
	SupportWrite       SupportLevel = "write"
)

type SupportMatrix

type SupportMatrix map[components.Kind]map[Scope]SupportLevel

SupportMatrix records support by component kind and scope.

type TargetKind

type TargetKind string

TargetKind groups native adapter files by the normalized component feature they serve.

const (
	TargetRules       TargetKind = "rules"
	TargetSkills      TargetKind = "skills"
	TargetMCP         TargetKind = "mcp"
	TargetIgnore      TargetKind = "ignore"
	TargetPermissions TargetKind = "permissions"
)