components

Documentation

Index

• Constants
• func ValidateComponent(ctx context.Context, component Component, componentDir string) error
• func ValidateID(id string) error
• type Component
  • func NormalizeComponent(component Component) (Component, error)
• type ComponentSummary
• type EnvVarReference
• type Filter
• type HTTPTransport
• type IgnoreSpec
• type IgnoreTargetKind
• type IgnoreTemplate
  • func (i IgnoreTemplate) ComponentID() string
  • func (i IgnoreTemplate) ComponentKind() Kind
  • func (i IgnoreTemplate) ComponentMetadata() Metadata
  • func (i IgnoreTemplate) Normalize() IgnoreTemplate
• type Kind
  • func ParseKind(raw string) (Kind, error)
  • func (k Kind) RefPrefix() string
• type MCPServer
  • func (m MCPServer) ComponentID() string
  • func (m MCPServer) ComponentKind() Kind
  • func (m MCPServer) ComponentMetadata() Metadata
  • func (m MCPServer) Normalize() MCPServer
• type MCPSpec
• type MCPTransports
• type ManagedBlock
• type Metadata
• type Ref
  • func ParseRef(raw string) (Ref, error)
  • func (r Ref) IsZero() bool
  • func (r Ref) MarshalJSON() ([]byte, error)
  • func (r Ref) MarshalText() ([]byte, error)
  • func (r Ref) MarshalYAML() (any, error)
  • func (r Ref) String() string
  • func (r *Ref) UnmarshalJSON(data []byte) error
  • func (r *Ref) UnmarshalText(text []byte) error
  • func (r *Ref) UnmarshalYAML(unmarshal func(any) error) error
• type Risk
• type Rule
  • func (r Rule) ComponentID() string
  • func (r Rule) ComponentKind() Kind
  • func (r Rule) ComponentMetadata() Metadata
  • func (r Rule) Normalize() Rule
• type RuleSpec
• type Skill
  • func (s Skill) ComponentID() string
  • func (s Skill) ComponentKind() Kind
  • func (s Skill) ComponentMetadata() Metadata
  • func (s Skill) Normalize() Skill
• type SkillFileRef
• type SkillSpec
• type Source
• type StdioTransport

Constants

const APIVersion = "contextcart.dev/v1"

Functions

func ValidateComponent

func ValidateComponent(ctx context.Context, component Component, componentDir string) error

ValidateComponent verifies schema fields, required payload files, and safety constraints for a component rooted at componentDir.

func ValidateID

func ValidateID(id string) error

ValidateID verifies that a component ID is stable and path-safe.

Types

type Component

type Component interface {
	ComponentKind() Kind
	ComponentID() string
	ComponentMetadata() Metadata
}

Component is the common contract implemented by normalized component records.

func NormalizeComponent

func NormalizeComponent(component Component) (Component, error)

NormalizeComponent fills deterministic schema fields and returns a value type.

type ComponentSummary

type ComponentSummary struct {
	Ref         Ref      `json:"ref" yaml:"ref"`
	Name        string   `json:"name,omitempty" yaml:"name,omitempty"`
	Description string   `json:"description,omitempty" yaml:"description,omitempty"`
	Tags        []string `json:"tags,omitempty" yaml:"tags,omitempty"`
	Source      Source   `json:"source,omitempty" yaml:"source,omitempty"`
	Risk        Risk     `json:"risk,omitempty" yaml:"risk,omitempty"`
}

ComponentSummary is a compact component listing record.

type EnvVarReference

type EnvVarReference struct {
	Required  bool   `json:"required,omitempty" yaml:"required,omitempty"`
	ValueFrom string `json:"valueFrom" yaml:"valueFrom"`
	Name      string `json:"name,omitempty" yaml:"name,omitempty"`
	Default   string `json:"default,omitempty" yaml:"default,omitempty"`
}

EnvVarReference records an environment-backed value without storing a raw secret.

type Filter

type Filter struct {
	Kind  Kind     `json:"kind,omitempty" yaml:"kind,omitempty"`
	Tags  []string `json:"tags,omitempty" yaml:"tags,omitempty"`
	Query string   `json:"query,omitempty" yaml:"query,omitempty"`
}

Filter selects components in the local store.

type HTTPTransport

type HTTPTransport struct {
	URL     string                     `json:"url" yaml:"url"`
	Headers map[string]EnvVarReference `json:"headers,omitempty" yaml:"headers,omitempty"`
}

HTTPTransport describes a remote HTTP MCP server.

type IgnoreSpec

type IgnoreSpec struct {
	TargetKind      IgnoreTargetKind `json:"targetKind" yaml:"targetKind"`
	TargetFiles     []string         `json:"targetFiles,omitempty" yaml:"targetFiles,omitempty"`
	IncludePatterns []string         `json:"includePatterns" yaml:"includePatterns"`
	ExcludePatterns []string         `json:"excludePatterns,omitempty" yaml:"excludePatterns,omitempty"`
	Adapters        []string         `json:"adapters,omitempty" yaml:"adapters,omitempty"`
}

IgnoreSpec describes adapter-compatible ignore patterns.

type IgnoreTargetKind

type IgnoreTargetKind string

IgnoreTargetKind names the supported ignore-template export target family.

const (
	IgnoreTargetConfigKey        IgnoreTargetKind = "config-key"
	IgnoreTargetManagedLineBlock IgnoreTargetKind = "managed-line-block"
)

type IgnoreTemplate

type IgnoreTemplate struct {
	APIVersion string     `json:"apiVersion" yaml:"apiVersion"`
	Kind       Kind       `json:"kind" yaml:"kind"`
	Metadata   Metadata   `json:"metadata" yaml:"metadata"`
	Source     Source     `json:"source,omitempty" yaml:"source,omitempty"`
	Spec       IgnoreSpec `json:"spec" yaml:"spec"`
	Risk       Risk       `json:"risk,omitempty" yaml:"risk,omitempty"`
}

IgnoreTemplate is the normalized store record for traversal-hygiene patterns.

func (IgnoreTemplate) ComponentID

func (i IgnoreTemplate) ComponentID() string

ComponentID returns the stable metadata ID.

func (IgnoreTemplate) ComponentKind

func (i IgnoreTemplate) ComponentKind() Kind

ComponentKind returns the schema kind for IgnoreTemplate.

func (IgnoreTemplate) ComponentMetadata

func (i IgnoreTemplate) ComponentMetadata() Metadata

ComponentMetadata returns shared component metadata.

func (IgnoreTemplate) Normalize

func (i IgnoreTemplate) Normalize() IgnoreTemplate

Normalize fills stable schema fields that are deterministic for ignore records.

type Kind

type Kind string

Kind names the normalized ContextCart record type.

const (
	KindMCP     Kind = "MCPServer"
	KindSkill   Kind = "Skill"
	KindRule    Kind = "Rule"
	KindIgnore  Kind = "IgnoreTemplate"
	KindLoadout Kind = "Loadout"
)

func ParseKind

func ParseKind(raw string) (Kind, error)

ParseKind parses a user-facing kind token.

func (Kind) RefPrefix

func (k Kind) RefPrefix() string

RefPrefix returns the stable prefix used in typed refs.

type MCPServer

type MCPServer struct {
	APIVersion string   `json:"apiVersion" yaml:"apiVersion"`
	Kind       Kind     `json:"kind" yaml:"kind"`
	Metadata   Metadata `json:"metadata" yaml:"metadata"`
	Source     Source   `json:"source,omitempty" yaml:"source,omitempty"`
	Spec       MCPSpec  `json:"spec" yaml:"spec"`
	Risk       Risk     `json:"risk,omitempty" yaml:"risk,omitempty"`
}

MCPServer is the normalized store record for a Model Context Protocol server.

func (MCPServer) ComponentID

func (m MCPServer) ComponentID() string

ComponentID returns the stable metadata ID.

func (MCPServer) ComponentKind

func (m MCPServer) ComponentKind() Kind

ComponentKind returns the schema kind for MCPServer.

func (MCPServer) ComponentMetadata

func (m MCPServer) ComponentMetadata() Metadata

ComponentMetadata returns shared component metadata.

func (MCPServer) Normalize

func (m MCPServer) Normalize() MCPServer

Normalize fills stable schema fields that are deterministic for MCP records.

type MCPSpec

type MCPSpec struct {
	Transports         MCPTransports     `json:"transports" yaml:"transports"`
	PreferredTransport map[string]string `json:"preferredTransport,omitempty" yaml:"preferredTransport,omitempty"`
}

MCPSpec defines all known transports and adapter preferences for an MCP.

type MCPTransports

type MCPTransports struct {
	Stdio *StdioTransport `json:"stdio,omitempty" yaml:"stdio,omitempty"`
	HTTP  *HTTPTransport  `json:"http,omitempty" yaml:"http,omitempty"`
}

MCPTransports stores supported MCP transport definitions.

type ManagedBlock

type ManagedBlock struct {
	ID          string            `json:"id,omitempty" yaml:"id,omitempty"`
	Title       string            `json:"title,omitempty" yaml:"title,omitempty"`
	Description string            `json:"description,omitempty" yaml:"description,omitempty"`
	Attributes  map[string]string `json:"attributes,omitempty" yaml:"attributes,omitempty"`
}

ManagedBlock stores ownership metadata used for Markdown block rendering.

type Metadata

type Metadata struct {
	ID            string     `json:"id" yaml:"id"`
	Name          string     `json:"name,omitempty" yaml:"name,omitempty"`
	Description   string     `json:"description,omitempty" yaml:"description,omitempty"`
	Tags          []string   `json:"tags,omitempty" yaml:"tags,omitempty"`
	Compatibility []string   `json:"compatibility,omitempty" yaml:"compatibility,omitempty"`
	CreatedAt     *time.Time `json:"createdAt,omitempty" yaml:"createdAt,omitempty"`
	UpdatedAt     *time.Time `json:"updatedAt,omitempty" yaml:"updatedAt,omitempty"`
}

Metadata contains fields shared by all normalized component records.

type Ref

type Ref struct {
	Kind Kind   `json:"kind" yaml:"kind"`
	ID   string `json:"id" yaml:"id"`
}

Ref identifies a component or loadout by kind-qualified ID, such as "mcp:firecrawl" or "loadout:wordpress-builder".

func ParseRef

func ParseRef(raw string) (Ref, error)

ParseRef parses a typed component reference.

func (Ref) IsZero

func (r Ref) IsZero() bool

IsZero reports whether the reference is empty.

func (Ref) MarshalJSON

func (r Ref) MarshalJSON() ([]byte, error)

MarshalJSON writes refs as canonical strings, such as "skill:browser-qa".

func (Ref) MarshalText

func (r Ref) MarshalText() ([]byte, error)

MarshalText returns the canonical typed reference for text-based formats.

func (Ref) MarshalYAML

func (r Ref) MarshalYAML() (any, error)

MarshalYAML writes refs as canonical strings.

func (Ref) String

func (r Ref) String() string

String returns the canonical typed reference.

func (*Ref) UnmarshalJSON

func (r *Ref) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts refs as canonical strings.

func (*Ref) UnmarshalText

func (r *Ref) UnmarshalText(text []byte) error

UnmarshalText parses a canonical typed reference from text-based formats.

func (*Ref) UnmarshalYAML

func (r *Ref) UnmarshalYAML(unmarshal func(any) error) error

UnmarshalYAML accepts refs as canonical strings.

type Risk

type Risk struct {
	Network    bool     `json:"network,omitempty" yaml:"network,omitempty"`
	LocalExec  bool     `json:"localExec,omitempty" yaml:"localExec,omitempty"`
	Filesystem bool     `json:"filesystem,omitempty" yaml:"filesystem,omitempty"`
	Browser    bool     `json:"browser,omitempty" yaml:"browser,omitempty"`
	Unpinned   bool     `json:"unpinnedPackage,omitempty" yaml:"unpinnedPackage,omitempty"`
	RawSecrets bool     `json:"secrets,omitempty" yaml:"secrets,omitempty"`
	SecretRefs []string `json:"secretRefs,omitempty" yaml:"secretRefs,omitempty"`
	Notes      []string `json:"notes,omitempty" yaml:"notes,omitempty"`
}

Risk is worst-case component metadata across all declared transports and files.

type Rule

type Rule struct {
	APIVersion string   `json:"apiVersion" yaml:"apiVersion"`
	Kind       Kind     `json:"kind" yaml:"kind"`
	Metadata   Metadata `json:"metadata" yaml:"metadata"`
	Source     Source   `json:"source,omitempty" yaml:"source,omitempty"`
	Spec       RuleSpec `json:"spec" yaml:"spec"`
	Risk       Risk     `json:"risk,omitempty" yaml:"risk,omitempty"`
}

Rule is the normalized store record for a reusable Markdown instruction block.

func (Rule) ComponentID

func (r Rule) ComponentID() string

ComponentID returns the stable metadata ID.

func (Rule) ComponentKind

func (r Rule) ComponentKind() Kind

ComponentKind returns the schema kind for Rule.

func (Rule) ComponentMetadata

func (r Rule) ComponentMetadata() Metadata

ComponentMetadata returns shared component metadata.

func (Rule) Normalize

func (r Rule) Normalize() Rule

Normalize fills stable schema fields that are deterministic for rule records.

type RuleSpec

type RuleSpec struct {
	EntryPath    string       `json:"entryPath" yaml:"entryPath"`
	Block        ManagedBlock `json:"block" yaml:"block"`
	TargetHints  []string     `json:"targetHints,omitempty" yaml:"targetHints,omitempty"`
	Dependencies []Ref        `json:"dependencies,omitempty" yaml:"dependencies,omitempty"`
}

RuleSpec describes the Markdown entry file and managed block metadata.

type Skill

type Skill struct {
	APIVersion string    `json:"apiVersion" yaml:"apiVersion"`
	Kind       Kind      `json:"kind" yaml:"kind"`
	Metadata   Metadata  `json:"metadata" yaml:"metadata"`
	Source     Source    `json:"source,omitempty" yaml:"source,omitempty"`
	Spec       SkillSpec `json:"spec" yaml:"spec"`
	Risk       Risk      `json:"risk,omitempty" yaml:"risk,omitempty"`
}

Skill is the normalized store record for an agent skill directory.

func (Skill) ComponentID

func (s Skill) ComponentID() string

ComponentID returns the stable metadata ID.

func (Skill) ComponentKind

func (s Skill) ComponentKind() Kind

ComponentKind returns the schema kind for Skill.

func (Skill) ComponentMetadata

func (s Skill) ComponentMetadata() Metadata

ComponentMetadata returns shared component metadata.

func (Skill) Normalize

func (s Skill) Normalize() Skill

Normalize fills stable schema fields that are deterministic for skill records.

type SkillFileRef

type SkillFileRef struct {
	Path        string `json:"path" yaml:"path"`
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
}

SkillFileRef names a file inside the skill component directory.

type SkillSpec

type SkillSpec struct {
	EntryPath   string         `json:"entryPath" yaml:"entryPath"`
	References  []SkillFileRef `json:"references,omitempty" yaml:"references,omitempty"`
	Examples    []SkillFileRef `json:"examples,omitempty" yaml:"examples,omitempty"`
	InstallMode string         `json:"installMode,omitempty" yaml:"installMode,omitempty"`
}

SkillSpec describes the entrypoint and optional files for a skill.

type Source

type Source struct {
	Type        string `json:"type,omitempty" yaml:"type,omitempty"`
	Name        string `json:"name,omitempty" yaml:"name,omitempty"`
	URL         string `json:"url,omitempty" yaml:"url,omitempty"`
	Version     string `json:"version,omitempty" yaml:"version,omitempty"`
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
}

Source records where a component came from without making it executable.

type StdioTransport

type StdioTransport struct {
	Command string                     `json:"command" yaml:"command"`
	Args    []string                   `json:"args,omitempty" yaml:"args,omitempty"`
	Env     map[string]EnvVarReference `json:"env,omitempty" yaml:"env,omitempty"`
	CWD     string                     `json:"cwd,omitempty" yaml:"cwd,omitempty"`
}

StdioTransport describes a local command-based MCP server.