larksuite__cli/extension/platform/builder.go

// Copyright (c) 2026 Lark Technologies Pte. Ltd.
// SPDX-License-Identifier: MIT

package platform

import (
	"errors"
	"fmt"
	"regexp"
)

// Builder is the ergonomic constructor for Plugin. Use it from init():
//
//	func init() {
//	    platform.Register(
//	        platform.NewPlugin("audit", "0.1.0").
//	            Observer(platform.After, "log", platform.All(), auditFn).
//	            FailOpen().
//	            MustBuild())
//	}
//
// The lower-level Plugin interface remains available for cases that
// need finer control (state on a struct, complex Install logic). The
// Builder enforces:
//
//   - Name format (^[a-z0-9][a-z0-9-]*$)
//   - hookName format and uniqueness within a plugin
//   - Restricts ↔ FailClosed consistency (calling Restrict() implies
//     FailClosed, so plugin authors cannot accidentally ship a policy
//     plugin under FailOpen)
//   - EmbeddedSkills ↔ FailClosed consistency (declaring distribution
//     assets is a build-integrity commitment; falling back to host defaults
//     is never allowed)
//   - Rule validation via ValidateRule analogues (delegated to
//     internal/cmdpolicy at install time; Builder only fast-fails
//     blatantly bad input)
type Builder struct {
	name    string
	version string
	caps    Capabilities

	actions       []func(Registrar)
	rules         []*Rule
	skillsOverlay *SkillsOverlay

	hookNames map[string]bool
	errs      []error
}

var pluginNamePattern = regexp.MustCompile(`^[a-z0-9][a-z0-9-]*$`)

// NewPlugin starts a Builder. Name format is validated lazily — errors
// surface at Build()/MustBuild() time, allowing chained calls without
// intermediate error handling.
func NewPlugin(name, version string) *Builder {
	b := &Builder{
		name:      name,
		version:   version,
		hookNames: map[string]bool{},
	}
	if !pluginNamePattern.MatchString(name) {
		b.errs = append(b.errs, fmt.Errorf("invalid plugin name %q: must match ^[a-z0-9][a-z0-9-]*$", name))
	}
	return b
}

// RequireCLI sets Capabilities.RequiredCLIVersion (semver constraint,
// e.g. ">=1.1.0"). Empty string means no requirement.
func (b *Builder) RequireCLI(constraint string) *Builder {
	b.caps.RequiredCLIVersion = constraint
	return b
}

// FailOpen sets Capabilities.FailurePolicy = FailOpen. Default when
// neither FailOpen nor FailClosed is called and neither Restrict nor
// EmbeddedSkills is used. Build rejects a final FailOpen state after either
// safety-sensitive contribution.
func (b *Builder) FailOpen() *Builder {
	b.caps.FailurePolicy = FailOpen
	return b
}

// FailClosed sets Capabilities.FailurePolicy = FailClosed. Implicit when
// Restrict() or EmbeddedSkills() is called.
func (b *Builder) FailClosed() *Builder {
	b.caps.FailurePolicy = FailClosed
	return b
}

// Observer registers an Observer. Multiple calls accumulate.
func (b *Builder) Observer(when When, hookName string, sel Selector, fn Observer) *Builder {
	if !b.validateHookName(hookName, "observer") {
		return b
	}
	// Capture by value so the action closure doesn't share state with
	// subsequent Observer() calls (Go ≥1.22 already gives each call
	// its own copies of parameter values, but pinning is explicit).
	w, n, s, f := when, hookName, sel, fn
	b.actions = append(b.actions, func(r Registrar) {
		r.Observe(w, n, s, f)
	})
	return b
}

// Wrap registers a Wrapper. Multiple calls accumulate; the host
// composes them in registration order (outermost first).
func (b *Builder) Wrap(hookName string, sel Selector, wrap Wrapper) *Builder {
	if !b.validateHookName(hookName, "wrap") {
		return b
	}
	n, s, w := hookName, sel, wrap
	b.actions = append(b.actions, func(r Registrar) {
		r.Wrap(n, s, w)
	})
	return b
}

// On registers a LifecycleHandler.
func (b *Builder) On(event LifecycleEvent, hookName string, fn LifecycleHandler) *Builder {
	if !b.validateHookName(hookName, "on") {
		return b
	}
	e, n, f := event, hookName, fn
	b.actions = append(b.actions, func(r Registrar) {
		r.On(e, n, f)
	})
	return b
}

// Restrict contributes a pruning Rule. Calling Restrict implicitly
// sets Restricts=true and FailurePolicy=FailClosed (the framework
// requires both to coexist; the builder enforces the pairing so the
// plugin author cannot accidentally ship a policy plugin under
// FailOpen). It may be called more than once; each call adds one scoped
// Rule and the engine OR-combines them.
func (b *Builder) Restrict(rule *Rule) *Builder {
	if rule == nil {
		b.errs = append(b.errs, errors.New("Restrict(nil): rule must not be nil"))
		return b
	}
	b.caps.Restricts = true
	b.caps.FailurePolicy = FailClosed
	// Defensive clone: capture an independent snapshot so a caller that
	// reuses and mutates the same *Rule across multiple Restrict calls
	// gets distinct entries (mirrors the staging registrar's clone).
	cp := *rule
	cp.Allow = append([]string(nil), rule.Allow...)
	cp.Deny = append([]string(nil), rule.Deny...)
	cp.Identities = append([]Identity(nil), rule.Identities...)
	b.rules = append(b.rules, &cp)
	return b
}

// EmbeddedSkills contributes a SkillsOverlay (see SkillsOverlay) customizing
// the CLI's embedded skill content. It implies FailClosed: although skill
// content is not a command-enforcement boundary, the overlay is a distribution
// build-integrity declaration. Silently skipping it could republish host
// defaults that the distribution explicitly removed or replaced.
//
// Calling FailOpen before EmbeddedSkills is allowed; EmbeddedSkills overrides
// it to FailClosed, matching Restrict. Calling FailOpen afterward leaves an
// invalid final state that Build rejects. A later FailClosed restores a valid
// final state. A plugin owns at most one SkillsOverlay, so calling
// EmbeddedSkills more than once is a build error.
func (b *Builder) EmbeddedSkills(spec *SkillsOverlay) *Builder {
	if spec == nil {
		b.errs = append(b.errs, errors.New("EmbeddedSkills(nil): spec must not be nil"))
		return b
	}
	if b.skillsOverlay != nil {
		b.errs = append(b.errs, errors.New("EmbeddedSkills() called more than once; a plugin owns at most one SkillsOverlay"))
		return b
	}
	b.caps.FailurePolicy = FailClosed
	b.skillsOverlay = cloneSkillsOverlay(spec)
	return b
}

// cloneSkillsOverlay snapshots the caller's spec so a later mutation of the
// same *SkillsOverlay cannot alter the staged copy. Selection and remap slices
// are copied; Overlay/Base are fs.FS handles retained by reference (an fs.FS is
// a read-only view, not caller-mutable state).
func cloneSkillsOverlay(spec *SkillsOverlay) *SkillsOverlay {
	cp := *spec
	cp.Allow = append([]string(nil), spec.Allow...)
	cp.Remove = append([]string(nil), spec.Remove...)
	cp.ReferenceRemaps = append([]SkillRefRemap(nil), spec.ReferenceRemaps...)
	return &cp
}

// Build returns the configured Plugin, or an error if any builder
// step found a fault. MustBuild panics on the same error.
//
// FailOpen mismatches are checked against the final builder state, not in the
// chained setters, because FailOpen/FailClosed and the contributing methods may
// be called in either order.
func (b *Builder) Build() (Plugin, error) {
	if len(b.rules) > 0 && b.caps.FailurePolicy == FailOpen {
		b.errs = append(b.errs, errors.New(
			"Restrict() requires FailClosed; do not call FailOpen() after Restrict()"))
	}
	if b.skillsOverlay != nil && b.caps.FailurePolicy == FailOpen {
		b.errs = append(b.errs, errors.New(
			"EmbeddedSkills() requires FailClosed; do not call FailOpen() after EmbeddedSkills()"))
	}
	if len(b.errs) > 0 {
		return nil, errors.Join(b.errs...)
	}
	return &builtPlugin{
		name:          b.name,
		version:       b.version,
		caps:          b.caps,
		actions:       b.actions,
		rules:         b.rules,
		skillsOverlay: b.skillsOverlay,
	}, nil
}

// MustBuild panics if Build() would return an error. Designed for
// init():
//
//	func init() { platform.Register(platform.NewPlugin(...).MustBuild()) }
//
// A panic in init runs before the framework's recover guard is
// installed and will crash the binary. That is the intended
// behaviour: a misconfigured plugin must NOT be silently registered.
func (b *Builder) MustBuild() Plugin {
	p, err := b.Build()
	if err != nil {
		panic(fmt.Sprintf("plugin %q: %v", b.name, err))
	}
	return p
}

// validateHookName checks the grammar and uniqueness; returns false
// when the name was rejected (caller skips the action).
func (b *Builder) validateHookName(hookName, kind string) bool {
	if !pluginNamePattern.MatchString(hookName) {
		b.errs = append(b.errs, fmt.Errorf(
			"%s %q: hookName must match ^[a-z0-9][a-z0-9-]*$", kind, hookName))
		return false
	}
	if b.hookNames[hookName] {
		b.errs = append(b.errs, fmt.Errorf(
			"%s %q: hookName already used in this plugin", kind, hookName))
		return false
	}
	b.hookNames[hookName] = true
	return true
}

// builtPlugin is the Plugin implementation the builder emits.
type builtPlugin struct {
	name          string
	version       string
	caps          Capabilities
	actions       []func(Registrar)
	rules         []*Rule
	skillsOverlay *SkillsOverlay
}

func (p *builtPlugin) Name() string               { return p.name }
func (p *builtPlugin) Version() string            { return p.version }
func (p *builtPlugin) Capabilities() Capabilities { return p.caps }
func (p *builtPlugin) Install(r Registrar) error {
	for _, rule := range p.rules {
		r.Restrict(rule)
	}
	if p.skillsOverlay != nil {
		sr, ok := r.(EmbeddedSkillsRegistrar)
		if !ok {
			// Fail closed: a declared skill customization must never be
			// silently dropped by a host that cannot honour it.
			return errors.New("host registrar does not support EmbeddedSkills")
		}
		sr.EmbeddedSkills(p.skillsOverlay)
	}
	for _, action := range p.actions {
		action(r)
	}
	return nil
}