importer

Documentation

Index

• Variables
• type Candidate
• type ComponentStore
• type Format
• type Importer
• type Options
• type Preview
• type Request
• type Result
• type SecretWarning
• type Service
  • func New() Service
  • func (Service) CommitImport(ctx context.Context, store ComponentStore, preview Preview, opts Options) (Result, error)
  • func (Service) PreviewImport(ctx context.Context, req Request) (Preview, error)
• type UnsafeSecretError
  • func (e *UnsafeSecretError) Error() string

Variables

var ErrUnsupportedTarget = errors.New("unsupported import target")

Types

type Candidate

type Candidate struct {
	Ref       components.Ref       `json:"ref"`
	Source    string               `json:"source"`
	Component components.Component `json:"component"`
	Warnings  []string             `json:"warnings,omitempty"`
	Secrets   []SecretWarning      `json:"secrets,omitempty"`
	Risk      components.Risk      `json:"risk,omitempty"`
	Metadata  components.Metadata  `json:"metadata"`
}

Candidate is one normalized component that could be saved into the store.

type ComponentStore

type ComponentStore interface {
	SaveComponent(ctx context.Context, component components.Component) error
	SaveComponentFrom(ctx context.Context, component components.Component, sourceDir string) error
}

ComponentStore is the minimal store contract needed to commit imported components without attaching them to any project.

type Format

type Format string

Format identifies an adapter-native import source.

const (
	FormatCodex    Format = "codex"
	FormatClaude   Format = "claude"
	FormatMCPJSON  Format = "mcp-json"
	FormatOpenCode Format = "opencode"
	FormatRule     Format = "rule"
	FormatSkill    Format = "skill"
)

type Importer

type Importer interface {
	PreviewImport(ctx context.Context, req Request) (Preview, error)
	CommitImport(ctx context.Context, store ComponentStore, preview Preview, opts Options) (Result, error)
}

Importer is the preview/commit contract used by CLI and future TUI wiring. The store is supplied at commit time so preview remains read-only and Service stays stateless.

type Options

type Options struct {
	AllowRawSecret bool `json:"allowRawSecret,omitempty"`
}

Options controls the later commit step. It is defined with the preview types so command code can share one contract when the CLI is wired.

type Preview

type Preview struct {
	SourcePath string          `json:"sourcePath"`
	Format     Format          `json:"format"`
	Candidates []Candidate     `json:"candidates"`
	Warnings   []string        `json:"warnings,omitempty"`
	Secrets    []SecretWarning `json:"secrets,omitempty"`
}

Preview is the read-only import result shown before any store writes.

type Request

type Request struct {
	SourcePath string `json:"sourcePath"`
	Format     Format `json:"format"`
}

Request asks the importer to read existing native config and normalize it into ContextCart component candidates. Preview import never writes files.

type Result

type Result struct {
	Imported []components.Ref `json:"imported,omitempty"`
	Skipped  []components.Ref `json:"skipped,omitempty"`
	Warnings []string         `json:"warnings,omitempty"`
}

Result is the later commit result shape used after confirmed store writes.

type SecretWarning

type SecretWarning struct {
	ComponentRef   components.Ref `json:"componentRef"`
	Key            string         `json:"key"`
	RedactedValue  string         `json:"redactedValue"`
	OriginalLength int            `json:"originalLength,omitempty"`
	Reasons        []string       `json:"reasons,omitempty"`
}

SecretWarning records a raw-looking value without exposing that value.

type Service

type Service struct{}

Service implements shared importer preview behavior.

func New

func New() Service

New returns an importer service.

func (Service) CommitImport

func (Service) CommitImport(ctx context.Context, store ComponentStore, preview Preview, opts Options) (Result, error)

CommitImport writes confirmed candidates to the ContextCart store only. It never attaches imported components to a project.

func (Service) PreviewImport

func (Service) PreviewImport(ctx context.Context, req Request) (Preview, error)

PreviewImport reads the source file and returns normalized components without writing to the ContextCart store or target project.

type UnsafeSecretError

type UnsafeSecretError struct {
	Findings []SecretWarning
}

UnsafeSecretError reports redacted raw-secret findings that require an explicit user override before import can write store records.

func (*UnsafeSecretError) Error

func (e *UnsafeSecretError) Error() string