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 ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
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.
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.
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 ¶
Discover scans pluginsDir for <name>/plugin.toml manifests. Missing dir returns (nil, nil) — not an error.
func (Manifest) Matches ¶
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".
Source Files