plugin

type AuthReply struct {
	Status AuthStatus
	Err    string
}

type AuthStatus struct {
	OK     bool
	Detail string // how it's configured, or why it isn't usable
}

type DeployInfo struct {
	ID     string
	Status string
}

type DeployReply struct {
	Result DeployResult
	Err    string
}

type DeployRequest struct {
	ImageRef  string            // the pushed image, e.g. "registry.acme.app/team/my-app:1720000000"
	Name      string            // service name (sanitized)
	Port      int               // the container port the app listens on
	PlainEnv  map[string]string // non-sensitive env vars
	SecretEnv map[string]string // sensitive env vars (store as the cloud's secrets, not plain)
	// Shape is the deploy shape the host resolved for this project (from the user's intent
	// + analyzer). It tells the plugin AT DEPLOY TIME whether a URL is wanted: for a
	// non-HTTP shape (worker/cron) the plugin may skip allocating a public URL and return
	// DeployResult{URL:""}. Empty ⇒ ShapeWeb (a URL is expected). A plugin that only
	// serves web can ignore this field.
	Shape DeployShape
}

type DeployResult struct {
	ID   string // cloud resource id
	Name string
	URL  string // the public https URL (empty for a URL-less worker/cron shape)
	// Shape lets the plugin echo the shape it ACTUALLY deployed, overriding the host's
	// requested DeployRequest.Shape when the plugin is authoritative (e.g. a sandbox
	// runtime that runs an analyzer-classified "web" project as a URL-less worker). Empty
	// ⇒ the host keeps its requested shape. When it resolves to a non-HTTP shape the host
	// records a URL-less success and skips the liveness probe.
	Shape DeployShape
}

type DeployShape string

type ErrReply struct{ Err string }

type Meta struct {
	Name             string   // display name, e.g. "Acme Cloud"
	Aliases          []string // lowercase natural-language matches, e.g. "acme", "acme-cloud"
	DomainSuffix     string   // default hostname suffix, e.g. ".acme.app" (framework host allow-lists)
	SupportsRollback bool
	// Shapes are the deploy shapes this provider can serve. Empty ⇒ {ShapeWeb} (a
	// URL-serving web service — the back-compatible default, so plugins predating this
	// field behave exactly as before). Declare ShapeWorker/ShapeMCPServer here to tell the
	// host you may deploy a URL-less agent/worker; the host then relaxes its URL
	// requirement for a non-HTTP shape instead of failing "returned no URL".
	Shapes []DeployShape
}

type MetaReply struct {
	Meta Meta
	Err  string
}

type NoArgs struct{}

type PrevArgs struct{ AppName string }

type PrevReply struct {
	Info DeployInfo
	Err  string
}

type Provider interface {
	// Metadata describes the platform: display name, natural-language aliases, the
	// hostname suffix for framework host allow-lists, and capabilities. Called first.
	Metadata(ctx context.Context) (Meta, error)

	// RegistryInfo returns where and how the host should push the built image. The
	// host runs the docker build+push with these credentials; the plugin then deploys
	// from the resulting image reference.
	RegistryInfo(ctx context.Context, project string) (RegistryInfo, error)

	// CheckAuth reports whether the user's credentials for this cloud are usable, so
	// prod can fail fast with a clear message before building.
	CheckAuth(ctx context.Context) (AuthStatus, error)

	// Deploy creates or updates the service from a pushed image and returns it once
	// serving. It owns all cloud-specific work: the service create/update, secrets,
	// public access, and readiness polling.
	Deploy(ctx context.Context, req DeployRequest) (DeployResult, error)

	// PreviousDeployment returns the deployment to roll back to (the one before the
	// current), or an empty ID if there's nothing to roll back to. Optional — a
	// provider without rollback returns an empty result and sets Meta.SupportsRollback
	// false.
	PreviousDeployment(ctx context.Context, appName string) (DeployInfo, error)

	// Rollback reverts the app to targetID (from PreviousDeployment). Optional.
	Rollback(ctx context.Context, appName, targetID string) error
}

type ProviderPlugin struct{ Impl Provider }

type RegistryArgs struct{ Project string }

type RegistryInfo struct {
	Host       string // registry host, e.g. "registry.acme.app"
	Repository string // namespaced repository for this app, e.g. "team/my-app"
	Username   string
	Token      string
}

type RegistryReply struct {
	Info RegistryInfo
	Err  string
}

type RollbackArgs struct{ AppName, TargetID string }