deploy

type AzureProvisioner struct{}

type BootstrapParams struct {
	Identifier string
	DBEngine   DBEngine
	DBName     string
	DBUser     string
	// DBOnly provisions only the DB engine (--db) + the paired agent + connection
	// (and applies the schema); it skips the generated app, Docker, and Caddy. The
	// database is then managed entirely through nuzur.
	DBOnly bool
	// ExternalDB means the app/agent connect to a caller-supplied existing DB
	// (--db-dsn, local or remote, MySQL or Postgres) instead of a self-hosted one.
	// The bootstrap skips DB install + DB/user creation + backups; DBHost/
	// DBPort/DBPassword/DBParams/DBDSN carry the connection.
	ExternalDB bool
	DBHost     string
	DBPort     string
	DBPassword string // external only; self-hosted generates its own on the box
	DBParams   string // DSN query params (e.g. parseTime=true / sslmode=require)
	DBDSN      string // external only: the raw DSN used for the agent connection
	// DBSchema is the agent connection's default schema — set for Postgres (a
	// namespace like `public`), empty for MySQL where the database is the schema.
	DBSchema    string
	GRPCEnabled bool
	// JWTAuth means the generated app uses the JWT auth server, which reads its
	// signing key from config (auth.jwt.key). The generated base.yaml ships a
	// placeholder, so the bootstrap generates a real random key into prod.yaml —
	// without it token creation is broken.
	JWTAuth bool
	// Domain, when set, makes Caddy serve HTTPS/443 with an automatic Let's
	// Encrypt cert for this project's site. Empty means IP-only: the project gets
	// its own auto-assigned public port on the host IP (plain HTTP), so multiple
	// projects can coexist without domains.
	Domain string
	// GRPCDomain and AuthDomain are OPTIONAL extra hostnames for the same box,
	// each rendered as its own site block in this project's Caddy snippet — and
	// therefore each getting its own automatic Let's Encrypt cert. Both stay on
	// 80/443, so neither changes the firewall.
	//
	// They are ADDITIONS, never a replacement. The site Domain names still routes
	// everything by Content-Type (gRPC vs HTTP) on one hostname, which is the
	// arrangement every existing deployment runs; with both of these empty the
	// snippet is byte-identical to what it has always been.
	//
	// GRPCDomain fronts the gRPC port directly (h2c), so it is rendered only when
	// the app actually serves gRPC. AuthDomain is a hostname ALIAS onto the same
	// process — a VM runs one binary serving both the API and the JWT endpoints,
	// unlike the k8s path where the auth server is a second deployment — so it
	// proxies to the same HTTP port.
	GRPCDomain string
	AuthDomain string
	// Host is the box IP/hostname the CLI connected to; used to compose the
	// IP-only public URL (http://{host}:{publicPort}) written back for the report.
	Host              string
	InnoDBBufferMB    int
	ProjectDir        string // per-project dir, e.g. /etc/nuzur/{identifier} (holds secrets + url)
	ConfigDir         string // per-project config, e.g. /etc/nuzur/{identifier}/config
	RemoteSrcDir      string // where generated source was copied
	ImageName         string
	ContainerName     string
	ProvisioningToken string
	// ConnUUID/ConnName register the localhost DB as a named agent connection
	// (locally, --no-publish) so the daemon serves it by UUID; the deploy
	// command publishes the catalog to nuzur with the user's token.
	ConnUUID string
	ConnName string
	// CLIInstallCmd optionally overrides how the nuzur CLI is installed on the
	// box. When empty, the bootstrap downloads the matching Linux binary from
	// the nuzur-cli GitHub releases. A custom command must leave the binary at
	// NuzurBin.
	CLIInstallCmd string
	// CLIVersion PINS which nuzur-cli release the box installs; it defaults to the
	// version of the CLI driving this deploy. Two reasons, both structural:
	//
	//   - box CLI == driving CLI, so the agent on the box is never a different
	//     version from the CLI that paired it and published its connection;
	//   - a release published WHILE a deploy runs can no longer break it. The URL
	//     used to be `releases/latest/download/...`, which resolves at curl time to
	//     whatever Release exists at that instant — and a GitHub Release exists from
	//     the moment it is created, seconds before goreleaser finishes uploading its
	//     assets. Every in-flight deploy 404s during that window, at the very end of
	//     the expensive part (VM, Docker, database and app image all already paid
	//     for). Pinning removes the dependency on what was published minutes ago.
	//
	// A dev/unreleased version still tries the pinned URL: the bootstrap's curl
	// failure names the version AND the exact URL it tried, so the log says plainly
	// that this version has no published assets rather than failing as a generic
	// 404. --cli-install-cmd remains the escape hatch — for boxes that cannot reach
	// GitHub, and for deliberately pinning some other version.
	CLIVersion string
	// NuzurBin is the absolute path to the installed nuzur binary (used in the
	// agent systemd unit).
	NuzurBin string
	// S3* configure the generated app's file-upload endpoints (/upload, /sign).
	// Unlike the DB password, these credentials are resolved from the team's
	// ObjectStore (KMS) and passed IN, then written into prod.yaml (0600) — like
	// the external --db-dsn path, the secret does travel through the bootstrap.
	S3Enabled bool
	S3Region  string
	S3Bucket  string
	S3Key     string
	S3Secret  string
}

type CIWaitOptions struct {
	RepoRoot   string
	SHA        string
	Workflow   string        // workflow filename
	Timeout    time.Duration // total budget
	Poll       time.Duration // interval between checks
	OnProgress func(string)  // optional status line, called on each state change
}

type ClusterTools struct {
	Helm    string
	Kubectl string
}

type DBEngine string

type Deployment struct {
	ID                 string   `json:"id"`
	Provider           Provider `json:"provider"`
	ProviderInstanceID string   `json:"provider_instance_id,omitempty"` // cloud VM/instance id (for destroy); empty for BYO-SSH
	// ProviderResourceName is the name nuzur minted for the VM, written to disk
	// BEFORE the provider create call. If a deploy dies during that call, the id
	// never comes back and this name is the only handle left on a VM that may be
	// running and billing — destroy resolves it via Provisioner.FindInstanceByName.
	ProviderResourceName string `json:"provider_resource_name,omitempty"`
	// Provisioning marks a deployment whose VM is still being created. It is set
	// before the create call and cleared once the deploy completes, so a record left
	// with it set is a deploy that died in flight and may have leaked a VM.
	Provisioning bool   `json:"provisioning,omitempty"`
	Region       string `json:"region,omitempty"` // cloud region the VM lives in
	// Namespace, ReleaseName, ChartVersion and ImageRef describe a Kubernetes
	// deployment (Provider == ProviderK8s); empty for every other provider.
	// Destroy needs the first two to uninstall the release, and --release-only
	// reads the last two back so it can re-release without regenerating or
	// waiting on CI.
	Namespace          string   `json:"namespace,omitempty"`
	ReleaseName        string   `json:"release_name,omitempty"`
	ChartVersion       string   `json:"chart_version,omitempty"`
	ImageRef           string   `json:"image_ref,omitempty"`
	Host               string   `json:"host"`
	User               string   `json:"user"`
	Port               int      `json:"port"`
	Identifier         string   `json:"identifier"`
	ProjectUUID        string   `json:"project_uuid"`
	ProjectVersionUUID string   `json:"project_version_uuid"`
	LocalAgentUUID     string   `json:"local_agent_uuid"`
	ConnUUID           string   `json:"conn_uuid,omitempty"`
	DBEngine           DBEngine `json:"db_engine"`
	ExternalDB         bool     `json:"external_db,omitempty"` // --db-dsn: an existing DB, not self-hosted (never dropped on destroy)
	// WorkspaceDir is the persistent app-source WORKSPACE ROOT (e.g.
	// ./nuzur-<identifier>), the directory resolveWorkspace reuses on a
	// re-deploy. Distinct from Spec.SourceDir, which is the app directory
	// INSIDE the workspace (where the Dockerfile lives) — recording that here
	// instead once sent a retried deploy generating into its own app dir. The
	// json key stays source_dir so existing records keep working.
	WorkspaceDir string `json:"source_dir,omitempty"`
	Domain       string `json:"domain,omitempty"` // set when deployed with --domain (HTTPS site)
	// AuthDomain and GRPCDomain are the OTHER hostnames this deployment was given
	// — --auth-domain (the JWT auth server) and --grpc-domain (the gRPC front
	// door) — recorded for the same reason Domain is, and read back by the same
	// code: applyDeploymentSelector adopts all three when the next run does not
	// state them.
	//
	// Recording them is not bookkeeping. On the k8s path a host that this run
	// cannot see is a host the values file does not enable, and the chart's own
	// default is `ingress.enabled: false` — so a re-deploy that simply forgot the
	// flag made `helm upgrade` DELETE a live Ingress and took the site offline.
	// Domain was half-protected by being in the record; these two were not stored
	// anywhere, so they were lost on EVERY re-deploy. On the VM path they name the
	// extra Caddy sites (see BootstrapParams), which are dropped the same way.
	AuthDomain     string    `json:"auth_domain,omitempty"`
	GRPCDomain     string    `json:"grpc_domain,omitempty"`
	APIURL         string    `json:"api_url,omitempty"`    // resolved front-door URL
	PublicURL      string    `json:"public_url,omitempty"` // same as APIURL; explicit alias
	DataManagerURL string    `json:"data_manager_url,omitempty"`
	CreatedAt      time.Time `json:"created_at"`

	// LastCompletedStep is how far the LAST run of this deployment got: one of the
	// Step* constants below, or "" for a record written before checkpoints existed
	// (or by a run that died before its first checkpoint).
	//
	// It exists because every question the next run asks about a half-finished
	// deploy — did it pair an agent, did it get as far as creating the VM, is this
	// record a live deployment or the debris of one — was previously answered by
	// INFERRING from which fields happened to be empty. An empty LocalAgentUUID
	// meaning "died in flight" is that inference, and it is what turned an
	// interrupted re-deploy into a second record for the same box.
	//
	// The values are self-describing strings rather than an integer, because the
	// file is read by humans debugging exactly this situation.
	//
	// MONOTONE WITHIN A RUN, AND DELIBERATELY NOT ACROSS RUNS. A re-deploy
	// rewrites `finalized` → `box_recorded` → `agent_paired` → `finalized`, so
	// for the middle of every re-deploy this record describes a healthy, serving
	// box as half-deployed. That is the field's definition working — the last run
	// IS the one in progress — but it is worth writing down, because it is the
	// one place a concurrent reader (a second CLI, a crash-recovery path, a human
	// reading the file) can take a true value and draw a false conclusion.
	//
	// Blanking it at the start of a run was considered and rejected. "" is the
	// sentinel for "predates checkpoints", so a re-deploy interrupted after
	// blanking would be indistinguishable from an old record — losing precisely
	// the adoption decision the checkpoint exists to make, which is the bug that
	// used to mint a second record for one box. Reporting less than the truth is
	// not more honest than reporting a truth that has to be read carefully.
	// Telling "in flight" from "got this far" properly needs a second, in-flight
	// marker; it is not a different value of this one.
	//
	// Both directions are pinned: TestDeployRecordSequenceManagedFirstDeploy for
	// within a run, and TestRedeployPreservesURLsMidRun (which observes
	// box_recorded on a record seeded finalized) for across them.
	LastCompletedStep string `json:"last_completed_step,omitempty"`
	// LastError is the error the last run of this deployment ended with, or "" if
	// it finished cleanly. Cleared by the finalizing write, so a record carrying
	// one is a deployment that is currently in a bad state rather than one that
	// once was.
	LastError string `json:"last_error,omitempty"`
}

type DigitalOceanProvisioner struct{}

type FirewallRule struct {
	Port    int
	PortEnd int // inclusive range end; 0 → single port
}

type GCPProvisioner struct{}

type GitRepo struct {
	Root   string // absolute path to the repository root
	Branch string // currently checked-out branch
	// RelPath is the workspace's path relative to Root, or "." when they are the
	// same directory. It is what `git add` is scoped to.
	RelPath string
}

type HetznerProvisioner struct{}

type InstanceRef struct {
	InstanceID   string
	Region       string
	Host         string
	ResourceName string
}

type K8sProvisioner struct{}

type LinodeProvisioner struct{}

type Provider string

type ProviderConfig struct {
	Region     string // provider region/location (e.g. "nyc3", "nbg1")
	Size       string // instance size/type (provider-specific; empty → adapter default)
	Image      string // OS image (empty → adapter default, an Ubuntu LTS)
	SSHKeyName string // name/id of an SSH key already registered with the provider;

}

type Provisioned struct {
	Target     Target
	InstanceID string // provider VM/instance id
	Region     string // provider region the VM lives in
}

type Provisioner interface {
	// Provision returns a reachable, SSH-ready Target. BYO-SSH validates and
	// returns the user-supplied host; a cloud provider creates a VM, waits for
	// SSH, and returns its address + instance id.
	Provision(ctx context.Context, spec Spec) (Provisioned, error)
	// ConfigureFirewall restricts inbound to the given TCP rules (SSH + the Caddy
	// front doors). BYO-SSH is a no-op (the box's ufw does it); cloud adapters
	// create a provider security group/firewall for the instance.
	ConfigureFirewall(ctx context.Context, p Provisioned, rules []FirewallRule) error
	// Destroy tears down provider-created infrastructure. BYO-SSH is a no-op
	// (the user owns the box); a cloud provider deletes the VM by instance id.
	Destroy(ctx context.Context, p Provisioned) error
	// FindInstanceByName resolves a provider-side resource name to an instance id,
	// returning "" (and no error) when nothing matches. This is the last-resort
	// recovery path: a deploy killed DURING the create call leaves a VM whose id was
	// never returned to us, and the name — minted and persisted before the call — is
	// then the only handle on it. BYO-SSH returns "" (nothing is ours to find).
	FindInstanceByName(ctx context.Context, name, region string) (string, error)
}

type ReleaseOptions struct {
	Release   string
	Namespace string
	ChartDir  string // path ON THE HOST
	// ValuesFiles are applied in order, so later files win. The generated one
	// comes first and any user --chart-values file last, letting an operator
	// override anything deploy decided.
	ValuesFiles []string
	// Wait blocks until the release's pods are Ready. Without it helm returns as
	// soon as the objects are accepted, and a deploy would report success while
	// the pods are still in ImagePullBackOff.
	Wait        bool
	TimeoutSecs int
}

type RemoteRunner interface {
	Ping(ctx context.Context) error
	RunCommand(ctx context.Context, command string) error
	// RunScript runs a script on the box. label names WHICH script, and is the
	// noun the failure is reported with — see the ScriptBootstrap/ScriptTeardown
	// constants and RunScript's own doc.
	RunScript(ctx context.Context, label, script string) error
	Capture(ctx context.Context, command string) (string, error)
	CopyDir(ctx context.Context, localDir, remotePath string) error
	// SetSudo runs privileged remote work through `sudo` (see SSHRunner.Sudo).
	// A method rather than a field so the interface can carry it.
	SetSudo(sudo bool)
}

type SSHProvisioner struct{}

type SSHRunner struct {
	Target Target
	// Sudo runs the bootstrap script through `sudo` (for non-root SSH users on
	// hosts with passwordless sudo). The DB copy still lands in a user-writable
	// path, so only the privileged bootstrap needs it.
	Sudo bool
	// Stderr, when set, receives live command stderr (progress). Defaults to
	// os.Stderr. An io.Writer rather than an *os.File so the app layer can point
	// it at the CLI's own stderr sink (outputtools.Stderr), which a test can swap.
	Stderr io.Writer
}

type ScalewayProvisioner struct{}

type Spec struct {
	Provider           Provider
	Target             Target
	ProviderConfig     ProviderConfig // managed-provisioning inputs (cloud providers only)
	Identifier         string         // app identifier (image/service name, DB name)
	ProjectUUID        string
	ProjectVersionUUID string
	DBEngine           DBEngine
	// ProvisioningToken is minted by the caller (product IssueProvisioningToken)
	// and placed on the box for headless agent pairing.
	ProvisioningToken string
	// SourceDir is the local directory of generated app source (from the
	// go-code-gen extension) that gets copied to the box and built there.
	SourceDir string
	// ResourceName is the provider-side name for everything this deploy creates.
	// The CALLER mints it (providerResourceName) rather than the adapter, so it can
	// be written to local state BEFORE the create call: a VM whose id we never
	// learned is still findable — and so deletable — by name. Adapters given an
	// empty value mint their own, so direct and test callers still work.
	ResourceName string
	// OnInstanceCreated, when set, is called by a managed provisioner the instant the
	// provider acknowledges the VM — BEFORE waiting for it to become reachable, which
	// takes minutes. That wait is the bulk of the window in which a killed deploy
	// would otherwise strand a running, billing VM that nothing on disk knows about,
	// so this is what makes the VM recoverable. Implementations must be quick and
	// must not error the deploy.
	OnInstanceCreated func(InstanceRef)
}

type Target struct {
	Host string // IP or hostname
	User string // SSH user (e.g. root)
	Port int    // SSH port (default 22)
	// KeyPath is an optional explicit private key; empty uses the ssh-agent /
	// ~/.ssh/config resolution.
	KeyPath string
}

type TeardownParams struct {
	Identifier    string
	ContainerName string
	ImageName     string
	ProjectDir    string // /etc/nuzur/{identifier}
	DBEngine      DBEngine
	DBName        string
	DBUser        string
	ConnUUID      string // this project's agent connection to remove from the shared agent
	NuzurBin      string
	Purge         bool
	// IsLastProject: this is the only project left on the box, so also remove the
	// shared agent (nuzur-agent.service + pairing creds) and the main Caddyfile.
	// When false, the shared agent is kept for the surviving projects.
	IsLastProject bool
}

type VultrProvisioner struct{}