deploy

package
v1.5.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 2, 2026 License: Apache-2.0 Imports: 13 Imported by: 1

Documentation

Overview

Package deploy provides deployment state persistence for PromptKit arenas.

Index

Constants

View Source
const LoginCapability = "login"

LoginCapability is the ProviderInfo capability string an adapter advertises when it implements LoginProvider (browser-based autoconfigure).

Variables

This section is empty.

Functions

func AdapterBinaryName

func AdapterBinaryName(provider string) string

AdapterBinaryName returns the expected binary name for a provider.

func ComputePackChecksum

func ComputePackChecksum(data []byte) string

ComputePackChecksum computes a sha256 checksum of pack data.

Types

type Action

type Action string

Action represents the type of change to a resource.

const (
	ActionCreate   Action = "CREATE"
	ActionUpdate   Action = "UPDATE"
	ActionDelete   Action = "DELETE"
	ActionNoChange Action = "NO_CHANGE"
	ActionDrift    Action = "DRIFT"
)

Possible resource actions.

type AdapterClient

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

AdapterClient launches an adapter binary and communicates with it via JSON-RPC 2.0 over stdio. It implements the Provider interface so callers can use it interchangeably with an in-process provider.

func NewAdapterClient deprecated

func NewAdapterClient(binaryPath string) (*AdapterClient, error)

NewAdapterClient starts the adapter binary at the given path and returns a client ready for JSON-RPC calls. The process is kept alive for the lifetime of the client; call Close when done.

Deprecated: Use NewAdapterClientWithContext to pass a context that controls the subprocess lifetime.

func NewAdapterClientIO

func NewAdapterClientIO(r io.Reader, w io.WriteCloser) *AdapterClient

NewAdapterClientIO creates an AdapterClient backed by the given reader and writer instead of a subprocess. Useful for testing.

func NewAdapterClientWithContext added in v1.3.10

func NewAdapterClientWithContext(ctx context.Context, binaryPath string) (*AdapterClient, error)

NewAdapterClientWithContext starts the adapter binary at the given path, using ctx to control the subprocess lifetime. If ctx is canceled, the subprocess is killed. Call Close when done.

func (*AdapterClient) Apply

func (c *AdapterClient) Apply(ctx context.Context, req *PlanRequest, callback ApplyCallback) (string, error)

Apply executes the deployment. The adapter protocol returns all events in the final response rather than streaming them; this method replays those events to the callback (if non-nil) in order before returning. The returned string is the opaque adapter state.

func (*AdapterClient) Close

func (c *AdapterClient) Close() error

Close shuts down the adapter process. It closes stdin (signaling EOF) and waits for the process to exit.

func (*AdapterClient) CompleteLogin added in v1.5.3

CompleteLogin hands the adapter the captured callback params and returns the resolved deploy profile and scoped token.

func (*AdapterClient) Destroy

func (c *AdapterClient) Destroy(ctx context.Context, req *DestroyRequest, callback DestroyCallback) error

Destroy tears down the deployment.

func (*AdapterClient) GetLoginURL added in v1.5.3

func (c *AdapterClient) GetLoginURL(ctx context.Context, req *LoginURLRequest) (*LoginURLResponse, error)

GetLoginURL asks the adapter for the provider's browser authorize URL. A method-not-found error means the adapter does not implement login.

func (*AdapterClient) GetProviderInfo

func (c *AdapterClient) GetProviderInfo(ctx context.Context) (*ProviderInfo, error)

GetProviderInfo returns metadata about the adapter.

func (*AdapterClient) Import

Import imports a pre-existing resource into the deployment state.

func (*AdapterClient) Plan

func (c *AdapterClient) Plan(ctx context.Context, req *PlanRequest) (*PlanResponse, error)

Plan generates a deployment plan showing what would change.

func (*AdapterClient) Status

Status returns the current deployment status.

func (*AdapterClient) ValidateConfig

func (c *AdapterClient) ValidateConfig(ctx context.Context, req *ValidateRequest) (*ValidateResponse, error)

ValidateConfig validates provider-specific configuration.

type AdapterManager

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

AdapterManager discovers and manages deploy adapter binaries.

func NewAdapterManager

func NewAdapterManager(projectDir string) *AdapterManager

NewAdapterManager creates a manager that searches for adapters relative to the given project directory.

func (*AdapterManager) Discover

func (m *AdapterManager) Discover(provider string) (string, error)

Discover finds the adapter binary for the given provider. Search precedence:

  1. .promptarena/adapters/ (project-local)
  2. ~/.promptarena/adapters/ (user-level)
  3. $PATH (system-installed)

Returns the full path to the binary or an error if not found.

type ApplyCallback

type ApplyCallback func(event *ApplyEvent) error

ApplyCallback is called for each ApplyEvent during Apply.

type ApplyEvent

type ApplyEvent struct {
	Type     string          `json:"type"` // "progress", "resource", "error", "complete"
	Message  string          `json:"message,omitempty"`
	Resource *ResourceResult `json:"resource,omitempty"`
}

ApplyEvent is a streaming event during Apply.

type CompleteLoginRequest added in v1.5.3

type CompleteLoginRequest struct {
	Params map[string]string `json:"params"`
	// Config is the current deploy config as JSON (may be partial or empty),
	// carrying provider-specific coordinates the adapter needs to exchange the
	// callback (e.g. the Omnia api_endpoint for the back-channel call).
	Config string `json:"config,omitempty"`
}

CompleteLoginRequest hands the adapter the opaque query parameters captured from the browser's loopback callback (e.g. code, state). The adapter knows which it needs and how to exchange them.

type CompleteLoginResponse added in v1.5.3

type CompleteLoginResponse struct {
	Profile map[string]interface{} `json:"profile"`
	Token   string                 `json:"token,omitempty"`
}

CompleteLoginResponse is the result of a completed login: the deploy profile to merge into the arena config (same shape as a dashboard-exported profile) and the scoped secret token to store outside the config file.

type DestroyCallback

type DestroyCallback func(event *DestroyEvent) error

DestroyCallback is called for each DestroyEvent during Destroy.

type DestroyEvent

type DestroyEvent struct {
	Type     string          `json:"type"` // "progress", "resource", "error", "complete"
	Message  string          `json:"message,omitempty"`
	Resource *ResourceResult `json:"resource,omitempty"`
}

DestroyEvent is a streaming event during Destroy.

type DestroyRequest

type DestroyRequest struct {
	DeployConfig string `json:"deploy_config"`
	Environment  string `json:"environment,omitempty"`
	PriorState   string `json:"prior_state,omitempty"`
}

DestroyRequest is the input to Destroy.

type ImportRequest

type ImportRequest struct {
	ResourceType string `json:"resource_type"`
	ResourceName string `json:"resource_name"`
	Identifier   string `json:"identifier"`
	DeployConfig string `json:"deploy_config"`
	Environment  string `json:"environment,omitempty"`
	PriorState   string `json:"prior_state,omitempty"`
}

ImportRequest is the input to Import.

type ImportResponse

type ImportResponse struct {
	Resource ResourceStatus `json:"resource"`
	State    string         `json:"state"`
}

ImportResponse is the output of Import.

type Locker

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

Locker provides file-based locking for deploy operations. It uses OS-level file locking to prevent concurrent deploys from different processes targeting the same project directory.

func NewLocker

func NewLocker(baseDir string) *Locker

NewLocker creates a Locker for the given project directory.

func (*Locker) Lock

func (l *Locker) Lock() error

Lock acquires an exclusive file lock. Returns an error if the lock is already held by another process or if the locker already holds a lock.

func (*Locker) Unlock

func (l *Locker) Unlock() error

Unlock releases the lock and removes the lock file. If no lock is held, Unlock is a no-op and returns nil.

type LoginProvider added in v1.5.3

type LoginProvider interface {
	GetLoginURL(ctx context.Context, req *LoginURLRequest) (*LoginURLResponse, error)
	CompleteLogin(ctx context.Context, req *CompleteLoginRequest) (*CompleteLoginResponse, error)
}

LoginProvider is the OPTIONAL deploy capability for browser-based autoconfigure. Adapters that implement it advertise LoginCapability in ProviderInfo.Capabilities. The adaptersdk exposes get_login_url / complete_login only for providers that satisfy this interface, and the CLI degrades gracefully (method not found) for those that don't.

type LoginURLRequest added in v1.5.3

type LoginURLRequest struct {
	CallbackURL string `json:"callback_url"`
	State       string `json:"state"`
	// Config is the current deploy config as JSON (may be partial or empty). The
	// adapter reads provider-specific coordinates from it — e.g. the Omnia
	// adapter needs api_endpoint to build the authorize URL.
	Config string `json:"config,omitempty"`
}

LoginURLRequest asks the adapter for the provider's authorize URL to open in the browser. The CLI supplies the loopback callback it is listening on and a CSRF state nonce.

type LoginURLResponse added in v1.5.3

type LoginURLResponse struct {
	AuthorizeURL string `json:"authorize_url"`
}

LoginURLResponse carries the provider-specific authorize URL the CLI opens.

type PlanRequest

type PlanRequest struct {
	PackJSON     string `json:"pack_json"`
	DeployConfig string `json:"deploy_config"`          // JSON provider config
	ArenaConfig  string `json:"arena_config,omitempty"` // JSON-serialized config.Config with loaded resources
	Environment  string `json:"environment,omitempty"`
	PriorState   string `json:"prior_state,omitempty"` // Opaque adapter state from last deploy
}

PlanRequest is the input to Plan.

type PlanResponse

type PlanResponse struct {
	Changes []ResourceChange `json:"changes"`
	Summary string           `json:"summary"`
	// Warnings are non-blocking advisories surfaced to the user before the
	// plan changes (e.g. a config that deploys but behaves surprisingly).
	Warnings []string `json:"warnings,omitempty"`
}

PlanResponse is the output of Plan.

type Provider

type Provider interface {
	GetProviderInfo(ctx context.Context) (*ProviderInfo, error)
	ValidateConfig(ctx context.Context, req *ValidateRequest) (*ValidateResponse, error)
	Plan(ctx context.Context, req *PlanRequest) (*PlanResponse, error)
	Apply(ctx context.Context, req *PlanRequest, callback ApplyCallback) (adapterState string, err error)
	Destroy(ctx context.Context, req *DestroyRequest, callback DestroyCallback) error
	Status(ctx context.Context, req *StatusRequest) (*StatusResponse, error)
	Import(ctx context.Context, req *ImportRequest) (*ImportResponse, error)
}

Provider defines the interface that deploy adapters must implement.

type ProviderInfo

type ProviderInfo struct {
	Name         string   `json:"name"`
	Version      string   `json:"version"`
	Capabilities []string `json:"capabilities,omitempty"`
	ConfigSchema string   `json:"config_schema,omitempty"` // JSON Schema for provider config
}

ProviderInfo describes a deploy adapter's capabilities.

type ResourceChange

type ResourceChange struct {
	Type   string `json:"type"`             // Resource type (e.g., "agent_runtime", "a2a_endpoint")
	Name   string `json:"name"`             // Resource name
	Action Action `json:"action"`           // CREATE, UPDATE, DELETE, NO_CHANGE
	Detail string `json:"detail,omitempty"` // Human-readable description
}

ResourceChange describes a single resource modification.

type ResourceResult

type ResourceResult struct {
	Type   string `json:"type"`
	Name   string `json:"name"`
	Action Action `json:"action"`
	Status string `json:"status"` // "created", "updated", "deleted", "failed"
	Detail string `json:"detail,omitempty"`
}

ResourceResult describes the outcome of a resource operation.

type ResourceStatus

type ResourceStatus struct {
	Type   string `json:"type"`
	Name   string `json:"name"`
	Status string `json:"status"` // "healthy", "unhealthy", "missing"
	Detail string `json:"detail,omitempty"`
}

ResourceStatus describes the current state of a resource.

type SavedPlan

type SavedPlan struct {
	Version      int           `json:"version"`
	CreatedAt    string        `json:"created_at"`
	Provider     string        `json:"provider"`
	Environment  string        `json:"environment"`
	PackChecksum string        `json:"pack_checksum"`
	Plan         *PlanResponse `json:"plan"`
	Request      *PlanRequest  `json:"request"`
}

SavedPlan is a serialized deployment plan that can be applied later.

func NewSavedPlan

func NewSavedPlan(provider, environment, packChecksum string, plan *PlanResponse, request *PlanRequest) *SavedPlan

NewSavedPlan creates a SavedPlan with current timestamp.

type State

type State struct {
	Version        int    `json:"version"`
	Provider       string `json:"provider"`
	Environment    string `json:"environment"`
	LastDeployed   string `json:"last_deployed"`
	PackVersion    string `json:"pack_version"`
	PackChecksum   string `json:"pack_checksum"`
	AdapterVersion string `json:"adapter_version"`
	LastRefreshed  string `json:"last_refreshed,omitempty"`
	State          string `json:"state,omitempty"` // Opaque base64 adapter state
}

State represents the persisted deployment state.

func NewState

func NewState(provider, environment, packVersion, packChecksum, adapterVersion string) *State

NewState creates a new State with the given parameters and current timestamp.

type StateStore

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

StateStore manages deploy state persistence.

func NewStateStore

func NewStateStore(baseDir string) *StateStore

NewStateStore creates a StateStore rooted at the given directory.

func (*StateStore) Delete

func (s *StateStore) Delete() error

Delete removes the state file.

func (*StateStore) DeletePlan

func (s *StateStore) DeletePlan() error

DeletePlan removes the saved plan file. Returns nil if not found.

func (*StateStore) Load

func (s *StateStore) Load() (*State, error)

Load reads the deploy state from disk. Returns nil, nil if the state file does not exist.

func (*StateStore) LoadPlan

func (s *StateStore) LoadPlan() (*SavedPlan, error)

LoadPlan reads a saved plan from disk. Returns nil, nil if not found.

func (*StateStore) Save

func (s *StateStore) Save(state *State) error

Save writes the deploy state to disk, creating directories as needed.

func (*StateStore) SavePlan

func (s *StateStore) SavePlan(plan *SavedPlan) error

SavePlan persists a deployment plan to disk.

type StatusRequest

type StatusRequest struct {
	DeployConfig string `json:"deploy_config"`
	Environment  string `json:"environment,omitempty"`
	PriorState   string `json:"prior_state,omitempty"`
}

StatusRequest is the input to Status.

type StatusResponse

type StatusResponse struct {
	Status    string           `json:"status"` // "deployed", "not_deployed", "degraded", "unknown"
	Resources []ResourceStatus `json:"resources,omitempty"`
	State     string           `json:"state,omitempty"` // Opaque adapter state
}

StatusResponse describes the current deployment status.

type ValidateRequest

type ValidateRequest struct {
	Config string `json:"config"` // JSON provider config
}

ValidateRequest is the input to ValidateConfig.

type ValidateResponse

type ValidateResponse struct {
	Valid  bool     `json:"valid"`
	Errors []string `json:"errors,omitempty"`
	// Warnings are non-blocking advisories surfaced to the user. Unlike
	// Errors, they do not make Valid false; the deployment proceeds.
	Warnings []string `json:"warnings,omitempty"`
}

ValidateResponse is the output of ValidateConfig.

Directories

Path Synopsis
Package adaptersdk provides a lightweight SDK for building deploy adapters.
Package adaptersdk provides a lightweight SDK for building deploy adapters.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL