foreign

Documentation

Overview

Package foreign discovers inert extension metadata installed for supported coding-agent hosts. Discovery never activates an extension or executes code.

Index

• func TransferMCPActivation(s MCPServer, vault *foreignactivation.Vault) (foreignactivation.Descriptor, bool)
• type Catalog
  • func Scan(ctx context.Context, options Options) (Catalog, error)
• type Classification
• type Host
• type HostCatalog
  • func ScanClaude(ctx context.Context, options Options) (HostCatalog, error)
  • func ScanClaudeWithActivations(ctx context.Context, options Options, vault *foreignactivation.Vault) (HostCatalog, error)
  • func ScanCodex(ctx context.Context, options Options) (HostCatalog, error)
  • func ScanCodexWithActivations(ctx context.Context, options Options, vault *foreignactivation.Vault) (HostCatalog, error)
  • func ScanCopilot(ctx context.Context, options Options) (HostCatalog, error)
  • func ScanCopilotWithActivations(ctx context.Context, options Options, vault *foreignactivation.Vault) (HostCatalog, error)
• type InertPermissions
• type MCPServer
• type MetadataEntry
• type Options
• type Provenance
• type Scope
• type Skill
  • func (s Skill) SourceDigest() string
• type Template
  • func (t Template) SourceDigest() string
• type ToolPattern
• type Trust

Functions

func TransferMCPActivation

func TransferMCPActivation(s MCPServer, vault *foreignactivation.Vault) (foreignactivation.Descriptor, bool)

TransferMCPActivation copies a runtime descriptor only into Plasmid's internal activation capability. External consumers cannot construct one.

Types

type Catalog

type Catalog struct {
	Hosts    []HostCatalog     `json:"hosts"`
	Skills   []Skill           `json:"skills"`
	Warnings []warning.Warning `json:"warnings"`
}

Catalog exposes normalized skills and independent host source views without defining cross-host precedence.

func Scan

func Scan(ctx context.Context, options Options) (Catalog, error)

Scan discovers all supported hosts while retaining their independent precedence. Unqualified names shared by hosts are reported as ambiguous.

type Classification

type Classification string

Classification distinguishes supported contracts from compatibility input.

const (
	ClassificationDocumented    Classification = "documented"
	ClassificationCompatibility Classification = "compatibility"
	ClassificationPreview       Classification = "preview"
)

type Host

type Host string

Host identifies one independently ordered foreign ecosystem.

const (
	HostClaude  Host = "claude"
	HostCodex   Host = "codex"
	HostCopilot Host = "copilot"
)

type HostCatalog

type HostCatalog struct {
	Host       Host              `json:"host"`
	Skills     []Skill           `json:"skills"`
	Templates  []Template        `json:"templates"`
	MCPServers []MCPServer       `json:"mcp_servers"`
	Warnings   []warning.Warning `json:"warnings"`
}

HostCatalog retains one host's independent ordering and precedence.

func ScanClaude

func ScanClaude(ctx context.Context, options Options) (HostCatalog, error)

ScanClaude discovers Claude Code extensions without activating them.

func ScanClaudeWithActivations

func ScanClaudeWithActivations(ctx context.Context, options Options, vault *foreignactivation.Vault) (HostCatalog, error)

ScanClaudeWithActivations transfers runtime descriptors into an internal capability while keeping the returned normalized catalog secret-free.

func ScanCodex

func ScanCodex(ctx context.Context, options Options) (HostCatalog, error)

ScanCodex discovers Codex extension metadata without activating it.

func ScanCodexWithActivations

func ScanCodexWithActivations(ctx context.Context, options Options, vault *foreignactivation.Vault) (HostCatalog, error)

ScanCodexWithActivations transfers runtime descriptors into an internal capability while keeping the returned normalized catalog secret-free.

func ScanCopilot

func ScanCopilot(ctx context.Context, options Options) (HostCatalog, error)

ScanCopilot discovers GitHub Copilot extension metadata without activating it.

func ScanCopilotWithActivations

func ScanCopilotWithActivations(ctx context.Context, options Options, vault *foreignactivation.Vault) (HostCatalog, error)

ScanCopilotWithActivations transfers runtime descriptors into an internal capability while keeping the returned normalized catalog secret-free.

type InertPermissions

type InertPermissions struct {
	Allowed []ToolPattern `json:"allowed"`
	Denied  []ToolPattern `json:"denied"`
}

InertPermissions retains foreign allow and deny declarations for inspection.

type MCPServer

type MCPServer struct {
	Name          string       `json:"name"`
	QualifiedName string       `json:"qualified_name"`
	Transport     string       `json:"transport"`
	Inert         bool         `json:"inert"`
	Provenance    []Provenance `json:"provenance"`
	// contains filtered or unexported fields
}

MCPServer is inert discovery metadata. It deliberately excludes credentials, environment values, headers, and executable arguments.

type MetadataEntry

type MetadataEntry struct {
	Name  string `json:"name"`
	Value string `json:"value"`
}

MetadataEntry is one portable Agent Skills metadata value.

type Options

type Options struct {
	HomeDir              string
	WorkingDir           string
	RepositoryRoot       string
	CodexHome            string
	AdminSkillsDir       string
	ProjectTrusted       bool
	EnableCopilotPreview bool
	MaxEntries           int
	MaxFileBytes         int64
}

Options selects filesystem roots and bounded discovery behavior.

type Provenance

type Provenance struct {
	Host           Host           `json:"host"`
	Scope          Scope          `json:"scope"`
	SourcePath     string         `json:"source_path"`
	PluginID       string         `json:"plugin_id"`
	PluginVersion  string         `json:"plugin_version"`
	Enabled        bool           `json:"enabled"`
	Trust          Trust          `json:"trust"`
	Classification Classification `json:"classification"`
	PluginRoot     string         `json:"-"`
	PluginData     string         `json:"-"`
}

Provenance records every source collapsed into one catalog record.

type Scope

type Scope string

Scope identifies where a host found an extension.

const (
	ScopeProject Scope = "project"
	ScopeLocal   Scope = "local"
	ScopeUser    Scope = "user"
	ScopeAdmin   Scope = "admin"
)

type Skill

type Skill struct {
	Name           string           `json:"name"`
	QualifiedName  string           `json:"qualified_name"`
	Description    string           `json:"description"`
	License        string           `json:"license"`
	Compatibility  string           `json:"compatibility"`
	Metadata       []MetadataEntry  `json:"metadata"`
	Permissions    InertPermissions `json:"inert_permissions"`
	Arguments      []string         `json:"arguments"`
	Globs          []string         `json:"globs"`
	UserInvocable  bool             `json:"user_invocable"`
	ModelInvocable bool             `json:"model_invocable"`
	RestrictsTools bool             `json:"restricts_tools"`
	Provenance     []Provenance     `json:"provenance"`
	// contains filtered or unexported fields
}

Skill is the portable Agent Skills core. Host permission fields are omitted.

func (Skill) SourceDigest

func (s Skill) SourceDigest() string

SourceDigest returns the discovery-time content identity used for lazy, digest-checked activation. It contains no source bytes or credentials.

type Template

type Template struct {
	Name           string           `json:"name"`
	QualifiedName  string           `json:"qualified_name"`
	Arguments      []string         `json:"arguments"`
	Permissions    InertPermissions `json:"inert_permissions"`
	UserInvocable  bool             `json:"user_invocable"`
	ModelInvocable bool             `json:"model_invocable"`
	RestrictsTools bool             `json:"restricts_tools"`
	Provenance     []Provenance     `json:"provenance"`
	// contains filtered or unexported fields
}

Template is an explicit-invocation legacy command or prompt.

func (Template) SourceDigest

func (t Template) SourceDigest() string

SourceDigest returns the template's discovery-time content identity.

type ToolPattern

type ToolPattern struct {
	Tool     string `json:"tool"`
	Argument string `json:"argument"`
}

ToolPattern is retained foreign permission metadata. Discovery never grants the permission or turns it into a Plasmid tool policy.

type Trust

type Trust string

Trust records host-supplied repository trust without granting authority.

const (
	TrustUnknown   Trust = "unknown"
	TrustTrusted   Trust = "trusted"
	TrustUntrusted Trust = "untrusted"
)