plugin

Documentation

Overview

Package plugin provides lifecycle operations for OpenCode plugins: clone/fetch/checkout (git), build commands, and pin management. All external commands go through internal/subprocess.Run.

Index

• func CapturePin(ctx context.Context, p config.Plugin) (string, error)
• func Checkout(ctx context.Context, checkout, ref string) error
• func Clone(ctx context.Context, repo, dir, branch string) error
• func Fetch(ctx context.Context, checkout string) error
• func Prepare(ctx context.Context, p config.Plugin) error
• func ReadDriftCache(path string, ttl time.Duration) (DriftCacheStatus, DriftCache, error)
• func RemoteOriginURL(ctx context.Context, checkout string) (string, error)
• func RenderLiteral(source string) string
• func RevParseHEAD(ctx context.Context, checkout string) (string, error)
• func RunBuild(ctx context.Context, p config.Plugin) error
• func StatusClean(ctx context.Context, checkout string) (bool, error)
• func ValidateNPMSource(source string) (string, error)
• func WriteDriftCache(path string, results []DriftResult) error
• func WritePin(tomlFile, pluginName string, p config.Plugin, sha string) (bool, error)
• type DriftCache
• type DriftCacheStatus
• type DriftResult
  • func Probe(ctx context.Context, name string, p config.Plugin, opts ProbeOptions) (DriftResult, error)
  • func ProbeAll(ctx context.Context, plugins config.PluginsSection, selected map[string]bool, ...) ([]DriftResult, error)
• type DriftStatus
• type ProbeOptions

Functions

func CapturePin

func CapturePin(ctx context.Context, p config.Plugin) (string, error)

CapturePin returns the current HEAD SHA of a git-sourced plugin's checkout. Returns ("", nil) for npm-source plugins (no capture needed). The returned SHA is a 40-character hex string.

func Checkout

func Checkout(ctx context.Context, checkout, ref string) error

Checkout runs git checkout {ref} in the checkout directory. The ref is validated before invocation; invalid refs return an error without touching the working tree.

func Clone

func Clone(ctx context.Context, repo, dir, branch string) error

Clone runs git clone {repo} into {dir}. If branch is non-empty, passes --branch {branch} --single-branch. Returns an error if the subprocess fails, the directory already exists, or the branch ref fails validation.

func Fetch

func Fetch(ctx context.Context, checkout string) error

Fetch runs git fetch in the checkout directory. Fetches all remotes.

func Prepare

func Prepare(ctx context.Context, p config.Plugin) error

Prepare orchestrates clone-or-pull + build for a single plugin.

Flow:

1. Skip npm-source plugins (no git operations).
2. Skip disabled plugins (enabled == false).
3. If checkout directory missing → Clone into it.
4. If checkout exists and dirty → abort with remediation guidance (AC29).
5. If checkout exists and clean → Fetch + Checkout ref.
6. If plugin declares build commands → RunBuild.

Ref defaults to "trunk" when empty (matching OCA convention per AC27).

func ReadDriftCache

func ReadDriftCache(path string, ttl time.Duration) (DriftCacheStatus, DriftCache, error)

func RemoteOriginURL

func RemoteOriginURL(ctx context.Context, checkout string) (string, error)

RemoteOriginURL returns the configured `remote.origin.url` for the checkout. Used to detect drift between stack.toml `source` and the already-cloned remote so users do not silently keep an old remote when they edit the source URL in stack.toml.

func RenderLiteral

func RenderLiteral(source string) string

RenderLiteral strips the "npm:" prefix from an npm source string, producing the "pkg@version" literal that fits into opencode.json's flat plugin string array (confirmed in discovery D6).

func RevParseHEAD

func RevParseHEAD(ctx context.Context, checkout string) (string, error)

RevParseHEAD returns the full SHA of HEAD in the checkout directory.

func RunBuild

func RunBuild(ctx context.Context, p config.Plugin) error

RunBuild executes each build command from the plugin's Build field sequentially in the checkout directory. Commands are invoked via "sh -c <cmd>" so shell features (pipes, &&, etc.) work naturally.

Environment (per jc-pnpm1 resolution):

• CI=true, DEBIAN_FRONTEND=noninteractive, npm_config_yes=true are merged onto the inherited process environment.
• --frozen-lockfile is the caller's responsibility in the build command string itself.

On failure, the captured combined output is included in the error message for remediation per AC29.

func StatusClean

func StatusClean(ctx context.Context, checkout string) (bool, error)

StatusClean reports whether the working tree has no uncommitted changes. Returns true when the checkout is clean, false when dirty.

func ValidateNPMSource

func ValidateNPMSource(source string) (string, error)

ValidateNPMSource checks that source is a valid "npm:pkg@version" string. Returns the extracted package name (without version) on success. The npm: prefix must be followed by a non-empty package name with a version.

func WriteDriftCache

func WriteDriftCache(path string, results []DriftResult) error

func WritePin

func WritePin(tomlFile, pluginName string, p config.Plugin, sha string) (bool, error)

WritePin updates [plugins.<name>].ref in the TOML file to the given SHA. It reads the file as a generic map, updates the nested key, and writes the whole file back (TOML round-trip).

Returns (false, nil) when:

• the plugin is npm-sourced (no-op)
• the current ref already matches sha (idempotent no-op)

Returns (true, nil) when the file was rewritten with the new ref.

Types

type DriftCache

type DriftCache struct {
	GeneratedAt time.Time     `json:"generated_at"`
	Results     []DriftResult `json:"results"`
}

type DriftCacheStatus

type DriftCacheStatus string

const (
	DriftCacheFresh   DriftCacheStatus = "fresh"
	DriftCacheMissing DriftCacheStatus = "missing"
	DriftCacheStale   DriftCacheStatus = "stale"
	DriftCacheCorrupt DriftCacheStatus = "corrupt"
)

type DriftResult

type DriftResult struct {
	Name      string      `json:"name"`
	Ref       string      `json:"ref"`
	LocalSHA  string      `json:"local_sha,omitempty"`
	RemoteSHA string      `json:"remote_sha,omitempty"`
	Status    DriftStatus `json:"status"`
	Error     string      `json:"error,omitempty"`
}

func Probe

func Probe(ctx context.Context, name string, p config.Plugin, opts ProbeOptions) (DriftResult, error)

func ProbeAll

func ProbeAll(ctx context.Context, plugins config.PluginsSection, selected map[string]bool, opts ProbeOptions) ([]DriftResult, error)

type DriftStatus

type DriftStatus string

const (
	DriftUpToDate        DriftStatus = "up_to_date"
	DriftUpdateAvailable DriftStatus = "update_available"
	DriftPinned          DriftStatus = "pinned"
	DriftUnknown         DriftStatus = "unknown"
)

type ProbeOptions

type ProbeOptions struct {
	TimeoutPerPlugin time.Duration
	TimeoutGlobal    time.Duration
	Parallelism      int
}