deploy

type BuildRequest ¶

type BuildRequest struct {
	// Root is the absolute project root the build runs in. Required.
	Root string
	// Command is the starter manifest's build command (pkg/startermanifest
	// .Build). Required: a deploy with no build step has nothing to upload.
	Command string
	// BuildDir is the absolute directory the build produces its deployable
	// output in, resolved from the deploy config / manifest. Required; it is
	// handed to the target unchanged.
	BuildDir string
	// Project is the project name on the target. Required.
	Project string
	// Kind is preview or production. Empty is treated as preview by adapters.
	Kind DeploymentKind
	// Version identifies the build being shipped. Optional.
	Version string
}

BuildRequest is one build-and-upload: where to build, what command to run, and the built output to ship. Its fields are the resolved deploy config and starter manifest flattened to plain values, so this package depends on neither pkg/deployconfig nor pkg/starterstore (pkg/deployconfig imports this package, and the cycle must not form). The caller resolves the manifest and config (deployconfig.Resolve) and fills these in.

type BuildRunner ¶

type BuildRunner func(ctx context.Context, root, command string) error

BuildRunner runs a build command in the project root and reports whether it succeeded. It is the injectable seam over the workspace build: the default spawns a shell, and tests supply a stub so no process runs. A non-nil error means the build failed.

type Call ¶

type Call struct {
	// Method is the interface method name: "Deploy", "Status", "List",
	// "Rollback", or "PreviewURL".
	Method string
	// Project is the project the call concerned, when it concerned one.
	Project string
	// DeploymentID is the deployment the call concerned, when it concerned
	// one.
	DeploymentID string
}

Call records one method invocation on a FakeTarget. Method names the interface method and Args carries the salient input (the request's project, or the deployment id) for a test to assert on.

type CloudflareConfig ¶

type CloudflareConfig struct {
	// AccountID is the Cloudflare account id. Required.
	AccountID string
	// Project is the Pages project name for Pages deploys, or the Worker
	// name for Workers deploys. Required.
	Project string
}

CloudflareConfig names the account and project a Cloudflare adapter ships to. AccountID scopes Pages and Workers resources; Project is the Pages project (or the Worker name) the deployment belongs to and the key its history and rollback are registered under.

type CloudflareError ¶

type CloudflareError struct {
	Code    int
	Message string
}

CloudflareError is one entry from a Cloudflare API error response.

type CloudflarePages ¶

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

CloudflarePages implements DeployTarget against a Cloudflare Pages project.

func NewCloudflarePagesTarget(cfg CloudflareConfig, cred Credential, baseURL string, client *http.Client) (*CloudflarePages, error)

func (p *CloudflarePages) Deploy(req DeployRequest) (Deployment, error)

func (p *CloudflarePages) List(project string) ([]Deployment, error)

func (p *CloudflarePages) PreviewURL(d Deployment) (string, error)

func (p *CloudflarePages) Rollback(d Deployment) (Deployment, error)

func (p *CloudflarePages) Status(d Deployment) (StatusState, error)

type CloudflareRequestError ¶

type CloudflareRequestError struct {
	// Op names the call, e.g. "create deployment".
	Op string
	// StatusCode is the HTTP status of the response.
	StatusCode int
	// Errors are the API's structured errors, when present.
	Errors []CloudflareError
	// Message is a sanitized human-readable reason: Cloudflare's own error
	// messages with any credential-looking substring scrubbed, or a short
	// fallback when the body was not a Cloudflare envelope.
	Message string
}

CloudflareRequestError describes a failed Cloudflare API call. StatusCode is the HTTP status, and Errors carries the API's structured errors when the response body was a Cloudflare envelope. It never holds the request's auth header or URL, so it is safe to format into a log line or an error.

func (e *CloudflareRequestError) Error() string

func (e *CloudflareRequestError) Unwrap() error

type CloudflareTarget ¶

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

CloudflareTarget implements DeployTarget against Cloudflare. It is the entry point that hosts the shared HTTP plumbing; the Pages and Workers adapters embed it and supply the resource shape.

The token is held in an unexported Credential field: it is never a struct field a caller can read back, never part of any request value, and never formatted into an error or a log line. It reaches the wire only through the auth header the HTTP layer sets.

func (t *CloudflareTarget) PageURL() string

type CloudflareWorkers ¶

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

CloudflareWorkers implements DeployTarget against a Cloudflare Worker.

func NewCloudflareWorkersTarget(cfg CloudflareConfig, cred Credential, baseURL string, client *http.Client) (*CloudflareWorkers, error)

func (w *CloudflareWorkers) Deploy(req DeployRequest) (Deployment, error)

func (w *CloudflareWorkers) List(project string) ([]Deployment, error)

func (w *CloudflareWorkers) PreviewURL(d Deployment) (string, error)

func (w *CloudflareWorkers) Rollback(d Deployment) (Deployment, error)

func (w *CloudflareWorkers) Status(d Deployment) (StatusState, error)

type Confirmation ¶

type Confirmation struct {
	// Confirmed reports whether a user explicitly granted this deploy. Only
	// true lets a production deploy proceed; false (the zero value) refuses.
	Confirmed bool
	// ApprovedBy is who granted it — a user identifier, "cli", "ship-mode",
	// or the tool-approval channel. Carried for the audit trail; it does not
	// by itself satisfy the gate. Optional.
	ApprovedBy string
	// Note is a free-form remark from the confirmation (e.g. the prompt text
	// or approval ticket id). Optional; never consulted by the gate.
	Note string
}

Confirmation records that a user explicitly approved a production deploy, and how. It is the injectable seam the deploy path checks: a caller that obtained approval (the CLI prompt, the Ship mode action, a confirmed tool approval) fills it in, and BuildAndDeploy refuses a production request without it.

The zero value is unconfirmed (`Confirmed == false`), so confirmation fails closed: a caller that forgets to set it, or mishandles an all-zero value, cannot accidentally promote to production. Preview deploys ignore it entirely.

func (c Confirmation) DescribeApproval() string

func (c Confirmation) Grants() bool

type Credential ¶

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

Credential is a resolved deploy credential: the secret value plus the source it came from. The value is returned to the caller (the runtime or the target adapter); it must never be attached to DeployRequest, Deployment, or any other value that crosses to a model or a log.

The secret is held in an unexported field and the type marshals to JSON without it, so a Credential — even embedded in a larger struct — can never be serialized into a payload sent to a model, and an accidental %v/%#v renders a masked form. Reaching the secret requires the explicit Value() accessor, which keeps every use site deliberate.

func ResolveCredential(cfg DeployCredentialConfig) (Credential, error)

func (c Credential) GoString() string

func (c Credential) MarshalJSON() ([]byte, error)

func (c Credential) Source() CredentialSource

func (c Credential) String() string

func (c Credential) Value() string

type CredentialSource ¶

type CredentialSource string

CredentialSource names where a resolved deploy credential came from, for diagnostics and logs. It is deliberately a small closed set so a caller (and a test) can distinguish "the user stored it" from "the embedding environment supplied it" without ever seeing the secret itself.

const (
	// SourceStore means the secret came from the existing credential store
	// (the OS keyring or the encrypted file store). This is the preferred
	// source.
	SourceStore CredentialSource = "store"
	// SourceEnvironment means the secret came from an embedding-supplied
	// environment variable, used only when the store had none.
	SourceEnvironment CredentialSource = "environment"
)

func (s CredentialSource) String() string

type DeployCredentialConfig ¶

type DeployCredentialConfig struct {
	// Target is the deploy target adapter id from .sprout/deploy.json (e.g.
	// "cloudflare"). It is also the provider key used in the credential store.
	// Required.
	Target string
	// Project is the project name on the target. Optional; it is carried so a
	// caller can key a target-specific credential without inventing a parallel
	// lookup.
	Project string
	// EnvVar is the embedding-environment variable that may supply the token
	// as a fallback (e.g. "CLOUDFLARE_API_TOKEN"). Empty means "no
	// environment fallback": the resolver then only consults the store.
	EnvVar string
}

DeployCredentialConfig names the credential a deploy target needs. Callers build it from the deploy config (target, project) and the target adapter's declared token variable.

It carries no secret: only the provider key used to look a credential up in the store, and the environment variable name an embedding environment may supply as a fallback. The resolved secret is returned to the caller separately, never stored on this struct.

type DeployRequest ¶

type DeployRequest struct {
	// Project is the project name to deploy. Required.
	Project string
	// Kind is preview or production. Empty is treated as KindPreview by
	// adapters that make the distinction.
	Kind DeploymentKind
	// BuildDir is the directory holding the build output to upload, from
	// the starter manifest's build_output. Required.
	BuildDir string
	// Root is the project root the build ran in. Optional; an adapter that
	// needs a project file (a Workers adapter reading wrangler.toml) uses it,
	// and an adapter that does not ignores it.
	Root string
	// Version identifies the build being shipped (e.g. the starter version
	// or plan revision). Optional; adapters may fill a default.
	Version string
}

DeployRequest is the input to Deploy: what to ship and where it came from.

BuildDir is the directory the build produced its deployable output in, taken from the starter manifest's build_output. The adapter uploads that output; it never rebuilds. The field is deliberately a plain path string — resolving it against the manifest and the project root, and enforcing the "what was verified is what ships" gate, is later work.

type DeployResourceState ¶ added in v0.25.0

type DeployResourceState struct {
	// Version is the schema version of the file.
	Version int `json:"version"`
	// D1 maps a stable resource name to the D1 database id.
	D1 map[string]string `json:"d1,omitempty"`
	// KV maps a stable resource name to the KV namespace id.
	KV map[string]string `json:"kv,omitempty"`
	// R2 maps a stable resource name to the R2 bucket name.
	R2 map[string]string `json:"r2,omitempty"`
}

DeployResourceState records the account resources a project's Workers deploy created, so a re-run reuses them. It is keyed by the stable resource name (see stableResourceName), so a resource is found even if the display name changes.

func LoadDeployResourceState(root string) (*DeployResourceState, error)

type DeployTarget ¶

type DeployTarget interface {
	// Deploy ships the build described by req and returns the recorded
	// Deployment. It does not rebuild: it uploads the output in
	// req.BuildDir.
	Deploy(req DeployRequest) (Deployment, error)

	// Status returns the current state of a deployment previously returned
	// by Deploy. It returns ErrUnknownDeployment for a deployment this
	// target does not know.
	Status(d Deployment) (StatusState, error)

	// List returns the target's deployment history for a project, oldest
	// first. An unknown project yields an empty slice, not an error.
	List(project string) ([]Deployment, error)

	// Rollback reverts to the deployment preceding d and marks d as rolled
	// back, returning the now-live deployment. It returns
	// ErrNoPreviousDeployment when there is nothing earlier to revert to,
	// and ErrUnknownDeployment when d is unknown.
	Rollback(d Deployment) (Deployment, error)

	// PreviewURL returns the per-deployment preview address for d. It
	// returns ErrPreviewUnsupported when the target has no per-deployment
	// previews, and ErrUnknownDeployment when d is unknown.
	PreviewURL(d Deployment) (string, error)
}

DeployTarget is a destination a project can be shipped to. Adapters are small packages that implement it — the fake adapter (FakeTarget) is one, a real hosting adapter another.

The interface is shaped for later items to build on: Deploy records a deployment and returns it; Status and List read the history; Rollback reverts to the previous deployment; PreviewURL resolves a per-deployment preview address where the target supports one. Implementations must be safe for concurrent use.

func CloudflareTargetFor(deployTarget string, cfg CloudflareConfig, cred Credential, baseURL string, client *http.Client) (DeployTarget, error)

type Deployer ¶

type Deployer struct {
	// Target receives the built output. Required.
	Target DeployTarget
	// Run builds the project in the workspace. Nil uses DefaultBuildRunner.
	Run BuildRunner
	// Fingerprint computes the tree fingerprint. Nil uses
	// DefaultTreeFingerprint.
	Fingerprint TreeFingerprint
}

Deployer orchestrates a build-and-upload: gate on confirmation and verification, build in the workspace, hand the built output to a target. Its three collaborators are fields so a caller (and a test) wires them independently; nil Run and Fingerprint fall back to the real defaults, while a nil Target is an error (there is nowhere to ship).

func (d *Deployer) BuildAndDeploy(ctx context.Context, req BuildRequest, snap VerificationSnapshot, confirm Confirmation) (Deployment, error)

type Deployment ¶

type Deployment struct {
	// ID is the target-assigned deployment identifier. Unique within a
	// target and stable for the life of the deployment.
	ID string
	// Project is the project name the deployment belongs to. A target may
	// serve several projects; history is registered per project.
	Project string
	// Kind is whether this is a preview or a production deployment.
	Kind DeploymentKind
	// URL is the address the deployment is served at. For a preview
	// deployment this is the per-deployment preview URL.
	URL string
	// Version identifies what was built: the starter/plan version the
	// deployment was produced from. Opaque to this package.
	Version string
	// CreatedAt is when the deployment was recorded, in UTC.
	CreatedAt time.Time
	// Status is the deployment's lifecycle state (see StatusState).
	Status StatusState
}

Deployment is one recorded deploy of a project to a target: the identity (ID), what was deployed (Project, Version), where it landed (URL), the deploy shape (Kind), and its lifecycle state (Status).

A Deployment is an immutable value: adapters return copies and never hand out a reference callers can mutate. Rollback and PreviewURL take a Deployment and locate it by its ID (and Project), so a stale copy is still recognised as long as the id matches.

type DeploymentKind ¶

type DeploymentKind string

DeploymentKind distinguishes the two deploy shapes: a preview deployment (safe to run automatically once verification passes, with its own per-deployment URL) and a production deployment (the live site, which always needs explicit user confirmation).

const (
	// KindPreview is a per-deployment preview. Preview deploys may run
	// automatically once verification passes.
	KindPreview DeploymentKind = "preview"
	// KindProduction is the live production deployment. Production deploys
	// always require explicit user confirmation.
	KindProduction DeploymentKind = "production"
)

type FakeTarget ¶

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

FakeTarget is an in-memory DeployTarget for tests. It records every call, hands out deterministic ids and URLs, keeps a per-project deployment history, and implements rollback by restoring the deployment that preceded the one being rolled back.

It is an ordinary adapter: the interface it satisfies is the same one a real hosting adapter will satisfy, so tests written against FakeTarget describe the behaviour every target must provide. It makes no network calls and needs no credentials; it is safe for concurrent use.

Determinism: ids are "<project>-<n>" with n counting 1,2,3… per target (not per project), and URLs are derived from the id, so a test can assert exact values without a clock or a rand source. CreatedAt advances one second per deploy from a fixed epoch so history ordering is stable and comparable.

func NewFake() *FakeTarget

func (f *FakeTarget) Calls() []Call

func (f *FakeTarget) Deploy(req DeployRequest) (Deployment, error)

func (f *FakeTarget) List(project string) ([]Deployment, error)

func (f *FakeTarget) PreviewURL(d Deployment) (string, error)

func (f *FakeTarget) Rollback(d Deployment) (Deployment, error)

func (f *FakeTarget) Status(d Deployment) (StatusState, error)

type StatusState ¶

type StatusState string

StatusState is the lifecycle state of a deployment, as reported by Status and carried on Deployment.Status.

const (
	// StatusQueued means the deploy has been accepted but is not yet live.
	StatusQueued StatusState = "queued"
	// StatusDeploying means the deploy is in progress.
	StatusDeploying StatusState = "deploying"
	// StatusReady means the deploy is live and serving.
	StatusReady StatusState = "ready"
	// StatusFailed means the deploy did not complete.
	StatusFailed StatusState = "failed"
	// StatusRolledBack means the deploy was superseded by a rollback.
	StatusRolledBack StatusState = "rolled_back"
)

type TreeFingerprint ¶

type TreeFingerprint func(root string, skip ...string) (string, error)

TreeFingerprint computes a stable fingerprint of the project tree at root. Two calls over an unchanged tree return the same value; any file added, removed, resized, or retouched changes it. It is the injectable seam over "did the tree move since verification": the default hashes the sorted file list, and tests supply a stub so no directory walk runs.

skip names paths (relative to root or absolute) to leave out of the fingerprint. BuildAndDeploy always passes the request's BuildDir, because a build legitimately creates its own output: without excluding it, the post-build re-check would read the fresh artifact as a tree change. The gate therefore compares the source tree verification saw against the source tree the build ran over, not the artifact. A caller computing the snapshot at verification time must use the same function and skip set, or an unchanged tree can read as changed.

type VerificationSnapshot ¶

type VerificationSnapshot struct {
	// Passed reports whether verification passed on the tree. False means
	// there was no passing result (a nil result, or a failed run).
	Passed bool
	// Fingerprint is the tree fingerprint captured when verification passed.
	Fingerprint string
}

VerificationSnapshot is the verification outcome for one tree state: did verification pass, and what did the tree look like at that moment.

Fingerprint is the value returned by the TreeFingerprint seam over the project root when verification ran; BuildAndDeploy recomputes it and refuses when the two differ. Passed is verify.Result.Passed() — the caller builds it from the agent's last verification result, so this package stays independent of pkg/verify.

type WranglerConfig ¶ added in v0.25.0

type WranglerConfig struct {
	// Name is the worker name (`name`). It is the script name the adapter
	// uploads to and the anchor for the resource names it creates.
	Name string `toml:"name"`
	// Main is the worker entry point (`main`), relative to the project root.
	Main string `toml:"main"`
	// D1Databases are the declared [[d1_databases]] blocks.
	D1Databases []WranglerD1 `toml:"d1_databases"`
	// KVNamespaces are the declared [[kv_namespaces]] blocks.
	KVNamespaces []WranglerKV `toml:"kv_namespaces"`
	// R2Buckets are the declared [[r2_buckets]] blocks.
	R2Buckets []WranglerR2 `toml:"r2_buckets"`
}

WranglerConfig is the subset of wrangler.toml the Workers adapter needs: the worker name and entry point, and the bindings the project declares. Each slice holds exactly the blocks present in the file — an absent block is an empty slice, never a synthesized default.

func LoadWranglerConfig(root string) (*WranglerConfig, error)

type WranglerD1 ¶ added in v0.25.0

type WranglerD1 struct {
	Binding       string `toml:"binding"`
	DatabaseName  string `toml:"database_name"`
	DatabaseID    string `toml:"database_id"`
	MigrationsDir string `toml:"migrations_dir"`
}

WranglerD1 is one [[d1_databases]] block.

type WranglerKV ¶ added in v0.25.0

type WranglerKV struct {
	Binding string `toml:"binding"`
	ID      string `toml:"id"`
}

WranglerKV is one [[kv_namespaces]] block.

type WranglerR2 ¶ added in v0.25.0

type WranglerR2 struct {
	Binding    string `toml:"binding"`
	BucketName string `toml:"bucket_name"`
}

WranglerR2 is one [[r2_buckets]] block.