plugin

Documentation

Overview

Package plugin owns the bitgit plugin protocol: discovery on disk, match-rule evaluation, JSON-RPC stdio transport, and hook dispatch.

Plugins are subprocesses, language-agnostic. The protocol is JSON-RPC 2.0 over stdin/stdout. See docs/plugin-protocol.md for the wire spec.

Index

• func Dispatch(ctx context.Context, manifests []Manifest, hookCtx Context, ...) error
• func IsVeto(err error) bool
• type Client
  • func Spawn(ctx context.Context, m Manifest) (*Client, error)
  • func (c *Client) Call(ctx context.Context, method string, params any, out any) error
  • func (c *Client) Close() error
• type Context
• type HookResult
• type Manifest
  • func Discover(pluginsDir string) ([]Manifest, error)
  • func (m Manifest) Matches(ctx Context) bool
• type Match
• type VetoError
  • func (e *VetoError) Error() string

Functions

func Dispatch

func Dispatch(
	ctx context.Context,
	manifests []Manifest,
	hookCtx Context,
	payload map[string]any,
) error

Dispatch fires a hook across every matching plugin sequentially.

Sequential by design: plugin A's mutation must be visible to plugin B. First veto wins — remaining plugins are not consulted. Each plugin's mutation is shallow-merged into payload before the next call.

payload is mutated in place. Callers should pass a copy if they need the original.

func IsVeto

func IsVeto(err error) bool

IsVeto reports whether err is a plugin veto.

Types

type Client

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

Client is a JSON-RPC 2.0 stdio client for a single plugin subprocess.

One Client per plugin per bitgit invocation. Lifetimes are short: spawn, invoke a few hooks, close. The protocol is documented in docs/plugin-protocol.md.

This is the chassis transport. The dispatcher (Dispatch) is the higher-level API verbs should use; Client is exposed for advanced cases and tests.

func Spawn

func Spawn(ctx context.Context, m Manifest) (*Client, error)

Spawn starts a plugin subprocess from a manifest.

func (*Client) Call

func (c *Client) Call(ctx context.Context, method string, params any, out any) error

Call invokes a JSON-RPC method on the plugin and decodes result into out.

func (*Client) Close

func (c *Client) Close() error

Close terminates the plugin subprocess.

type Context

type Context struct {
	RemoteURL  string // e.g. "https://bitbucket.example.com/scm/PLAT/api.git"
	ProjectKey string // e.g. "PLAT" — caller-resolved when known
	RepoSlug   string // e.g. "api"
	Branch     string // current branch
	Hook       string // e.g. "pre-pr-create"
}

Context describes the operation a hook is being evaluated for. Plugins receive this; the matcher uses it to decide attachment.

type HookResult

type HookResult struct {
	Allow  bool           `json:"allow"`
	Reason string         `json:"reason,omitempty"`
	Mutate map[string]any `json:"mutate,omitempty"`
}

HookResult is the canonical response shape from a plugin hook.

allow: false     → veto. bitgit aborts with Reason.
mutate: non-nil  → bitgit replaces the matching field of the operation
                   with the mutated value (verb-specific schema).

type Manifest

type Manifest struct {
	Name       string   `toml:"name"`
	Version    string   `toml:"version"`
	Entrypoint string   `toml:"entrypoint"` // path or command, resolved against Dir
	Hooks      []string `toml:"hooks"`      // e.g. ["pre-pr-create", "pre-commit"]
	Match      Match    `toml:"match"`
	Dir        string   `toml:"-"`
}

Manifest describes a plugin loaded from <dir>/plugin.toml.

func Discover

func Discover(pluginsDir string) ([]Manifest, error)

Discover scans pluginsDir for <name>/plugin.toml manifests. Missing dir returns (nil, nil) — not an error.

func (Manifest) Matches

func (m Manifest) Matches(ctx Context) bool

Matches reports whether m attaches to ctx.

Rules:

• Empty Match → always attaches (universal plugin).
• Otherwise the union of any non-empty rule set must contain a match.
• Multiple rule kinds (host + project + branch) are OR-ed: any hit attaches.

This is the Empire convention; plugins MAY layer their own ANDs internally.

type Match

type Match struct {
	RemoteHost   []string `toml:"remote_host"`   // exact host, e.g. "bitbucket.example.com"
	RemoteRegex  []string `toml:"remote_regex"`  // RE2 against full remote URL
	ProjectKey   []string `toml:"project_key"`   // Bitbucket DC project key, e.g. "PLATFORM"
	RepoSlug     []string `toml:"repo_slug"`     // Bitbucket repo slug
	BranchPrefix []string `toml:"branch_prefix"` // current branch starts with one of these
}

Match is the auto-attach rule set. A plugin attaches when ANY rule fires. All fields are optional; an empty Match means "always attach".

type VetoError

type VetoError struct {
	Plugin string
	Hook   string
	Reason string
}

VetoError is returned by Dispatch when any plugin returned Allow=false.

func (*VetoError) Error

func (e *VetoError) Error() string