@stacksjs/ts-cloud 0.2.26 → 0.3.0

package/dist/deploy/serverless-app.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Serverless application deploy orchestrator (Laravel-Vapor-equivalent).
+ *
+ * Drives the full pipeline for `environments.<env>.app`:
+ *   build hooks → package → ensure artifact bucket → upload artifact →
+ *   deploy/update CloudFormation stack → update function code + env →
+ *   sync assets → run deploy hooks → health check.
+ *
+ * Plus the operational verbs: redeploy (no rebuild), rollback (previous
+ * release), and maintenance mode (down/up).
+ */
+import type { CloudConfig, EnvironmentType, ServerlessAppConfig } from '@ts-cloud/core';
+export interface DeployServerlessOptions {
+    /** Project root for entry resolution + build hooks. @default process.cwd() */
+    projectRoot?: string;
+    /** Skip the local build hooks (already run). */
+    skipBuild?: boolean;
+    /** Skip running the post-deploy `deploy` hooks. */
+    skipDeployHooks?: boolean;
+    /** Skip the post-deploy HTTP health check. */
+    skipHealthCheck?: boolean;
+}
+export interface ResolvedContext {
+    app: ServerlessAppConfig;
+    slug: string;
+    region: string;
+    stackName: string;
+    artifactBucket: string;
+    assetsBucket: string;
+}
+/**
+ * Derive framework env vars (DB/Redis hosts) from the deployed stack outputs so
+ * a Laravel app connects to the Aurora/RDS-Proxy/ElastiCache resources the
+ * composer created. Returns an empty map when nothing data-related is attached.
+ */
+export declare function infraEnvFromOutputs(app: ServerlessAppConfig, outputs: Record<string, string>): Record<string, string>;
+/** Build the complete environment for one function. Exported for testing. */
+export declare function buildFunctionEnv(app: ServerlessAppConfig, ctx: ResolvedContext, environment: EnvironmentType, mode: 'http' | 'queue' | 'cli', secrets: Record<string, string>, assetUrl: string | undefined, queueName: string | undefined, infraEnv?: Record<string, string>): Record<string, string>;
+/** Code source for a function update: an S3 zip or an ECR image. */
+export type CodeSource = {
+    kind: 'zip';
+    bucket: string;
+    key: string;
+} | {
+    kind: 'image';
+    imageUri: string;
+};
+export declare function deployServerlessApp(config: CloudConfig, environment: EnvironmentType, opts?: DeployServerlessOptions): Promise<void>;
+export declare function redeployServerlessApp(config: CloudConfig, environment: EnvironmentType): Promise<void>;
+export declare function rollbackServerlessApp(config: CloudConfig, environment: EnvironmentType): Promise<void>;
+export declare function setMaintenance(config: CloudConfig, environment: EnvironmentType, enabled: boolean, bypassSecret?: string): Promise<void>;
+/** Invoke the CLI function with an arbitrary command (e.g. `cloud command "migrate"`). */
+export declare function runRemoteCommand(config: CloudConfig, environment: EnvironmentType, command: string): Promise<string>;

package/dist/deploy/serverless-app.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/deploy/serverless-image.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Container-image build + push for serverless apps using `packaging: 'image'`.
+ *
+ * Stages a Docker build context (app files + a generated Dockerfile, plus the
+ * PHP runtime assets for PHP apps), builds the image, ensures an ECR repository,
+ * logs in, and pushes a content-tagged image. Returns the image URI the deploy
+ * orchestrator passes to CloudFormation + UpdateFunctionCode.
+ */
+import type { ServerlessAppConfig } from '@ts-cloud/core';
+export interface BuildImageOptions {
+    app: ServerlessAppConfig;
+    projectRoot: string;
+    region: string;
+    /** ECR repository name (created if missing). */
+    repository: string;
+    /** Skip local build hooks. */
+    skipBuild?: boolean;
+    onStep?: (m: string) => void;
+}
+export interface BuiltImage {
+    /** Full image URI including the content tag (repoUri:tag). */
+    imageUri: string;
+    /** The content tag (artifact hash). */
+    tag: string;
+    /** Lambda handler strings per function. */
+    handlers: {
+        http: string;
+        queue: string;
+        cli: string;
+    };
+}
+export declare function buildAndPushServerlessImage(opts: BuildImageOptions): Promise<BuiltImage>;

package/dist/deploy/site-target.d.ts

@@ -7,7 +7,13 @@ import type { CloudConfig, SiteConfig, SiteDeployTarget } from '@ts-cloud/core';
  *                        site built and shipped to `/var/www/<site>` on the box
  *                        (served by the operator's own proxy, e.g. rpx + tlsx).
  */
-export type SiteDeployKind = 'bucket' | 'server-app' | 'server-static';
+export type SiteDeployKind = 'bucket' | 'server-app' | 'server-static' | 'server-php';
+/**
+ * A PHP/Laravel site: deployed to the compute box via git clone into atomic
+ * release directories and served by nginx + php-fpm. Identified by a PHP
+ * `type` (laravel/php/statamic/wordpress).
+ */
+export declare function isPhpSite(site: SiteConfig): boolean;
 /**
  * Resolve the explicit-or-inferred {@link SiteDeployTarget} for a site.
  *

package/dist/drivers/aws/driver.d.ts

@@ -8,9 +8,30 @@ export declare class AwsDriver implements CloudDriver {
     private region;
     constructor(options?: AwsDriverOptions);
     private resolveRegion;
+    /**
+     * Provision a single Ubuntu EC2 box for the Forge/PHP path — mirroring the
+     * Hetzner driver, bypassing the heavy CloudFormation stack. Boots the shared
+     * Ubuntu bootstrap (or a baked golden AMI), fronted by a security group, and
+     * tagged so deploys (SSM) find it. Idempotent: reuses a running instance.
+     *
+     * NOTE: deploys run over SSM, so the instance needs the SSM agent + an IAM
+     * instance profile granting AmazonSSMManagedInstanceCore. Provide it via
+     * `compute.server.iamInstanceProfile` (live-verified step).
+     */
+    provisionComputeInfrastructure(options: ProvisionComputeOptions): Promise<ComputeStackOutputs>;
+    /** Terminate the lightweight EC2 box + delete its security group. */
+    destroyCompute(options: ProvisionComputeOptions): Promise<{
+        destroyed: string[];
+    }>;
     getComputeOutputs(options: ProvisionComputeOptions): Promise<ComputeStackOutputs>;
     uploadRelease(options: UploadReleaseOptions): Promise<UploadReleaseResult>;
     findComputeTargets(options: FindComputeTargetsOptions): Promise<ComputeTarget[]>;
+    /**
+     * SSM AWS-RunShellScript executes the joined commands with `/bin/sh` (dash on
+     * Ubuntu), which rejects bash-only syntax like `set -o pipefail`. Our deploy
+     * scripts are bash, so run them through a bash heredoc.
+     */
+    private bashWrap;
     runRemoteDeploy(options: RunRemoteDeployOptions): Promise<RemoteDeployResult>;
     private pollSsmCommand;
 }

package/dist/drivers/aws/provision.d.ts

@@ -0,0 +1,41 @@
+/**
+ * AWS EC2 provisioning composition for the Forge/PHP path — the pure, testable
+ * pieces shared by {@link import('./driver').AwsDriver.provisionComputeInfrastructure}.
+ *
+ * Mirrors the Hetzner path: boot a single **Ubuntu** box (same base as Hetzner,
+ * so the apt provisioning + nginx vhosts + php-fpm sockets are identical) with
+ * the shared bootstrap as UserData, fronted by a security group. The live API
+ * orchestration (AMI resolve, VPC/subnet, runInstances, wait) lives in the
+ * driver; this module builds the inputs.
+ */
+import type { CloudConfig } from '@ts-cloud/core';
+/**
+ * SSM public parameter for the latest Canonical Ubuntu 24.04 (Noble) AMI —
+ * region-agnostic, so we never hardcode region-specific AMI ids.
+ */
+export declare const UBUNTU_AMI_SSM_PARAM = "/aws/service/canonical/ubuntu/server/24.04/stable/current/amd64/hvm/ebs-gp3/ami-id";
+/** A security-group ingress rule. */
+export interface AwsIngressRule {
+    port: number;
+    protocol: 'tcp';
+    cidr: string;
+}
+/**
+ * Ingress rules for a PHP/app box: SSH (deploy fallback), HTTP, HTTPS, and any
+ * extra app ports any site declares. Deploys themselves run over SSM.
+ */
+export declare function awsComputeIngressRules(config: CloudConfig): AwsIngressRule[];
+/**
+ * Build the EC2 UserData (raw bash, not yet base64) from the shared Ubuntu
+ * bootstrap — the exact same recipe Hetzner uses. Honors a baked golden image
+ * (`compute.bakedImage`) by skipping the install-heavy steps.
+ */
+export declare function buildAwsUserData(config: CloudConfig): string;
+/** Base64-encode UserData for the EC2 RunInstances API. */
+export declare function encodeUserData(userData: string): string;
+/**
+ * Resolve the AMI to boot: an explicit `compute.image` (a golden AMI), else the
+ * caller resolves {@link UBUNTU_AMI_SSM_PARAM} via SSM. Returns the explicit id
+ * or `null` to signal "resolve Ubuntu via SSM".
+ */
+export declare function resolveAwsImageId(config: CloudConfig): string | null;

package/dist/drivers/hetzner/client.d.ts

@@ -76,6 +76,44 @@ export interface CreateServerOptions {
     firewalls?: Array<{
         firewall: number;
     }>;
+    /** Private networks to attach the server to (fleet topology). */
+    networks?: number[];
+}
+export interface HetznerNetwork {
+    id: number;
+    name: string;
+    ip_range: string;
+}
+export interface HetznerLoadBalancer {
+    id: number;
+    name: string;
+    public_net?: {
+        ipv4?: {
+            ip?: string;
+        };
+    };
+}
+export interface CreateNetworkOptions {
+    name: string;
+    ipRange?: string;
+    labels?: Record<string, string>;
+}
+export interface CreateLoadBalancerOptions {
+    name: string;
+    /** LB type (e.g. 'lb11'). @default 'lb11' */
+    type?: string;
+    location?: string;
+    networkZone?: string;
+    network?: number;
+    labels?: Record<string, string>;
+    /** Listener services (e.g. 80→80, 443→443). */
+    services: Array<{
+        listenPort: number;
+        destinationPort: number;
+        protocol?: 'tcp' | 'http';
+    }>;
+    /** Target app servers by label selector (e.g. `ts-cloud/role=app`). */
+    labelSelector: string;
 }
 export interface CreateFirewallOptions {
     name: string;
@@ -111,6 +149,12 @@ export declare class HetznerClient {
         server: HetznerServer;
         action: HetznerAction;
     }>;
+    listNetworks(): Promise<HetznerNetwork[]>;
+    createNetwork(options: CreateNetworkOptions): Promise<HetznerNetwork>;
+    deleteNetwork(id: number): Promise<void>;
+    listLoadBalancers(): Promise<HetznerLoadBalancer[]>;
+    createLoadBalancer(options: CreateLoadBalancerOptions): Promise<HetznerLoadBalancer>;
+    deleteLoadBalancer(id: number): Promise<void>;
     deleteServer(id: number): Promise<HetznerAction>;
     listFirewalls(): Promise<HetznerFirewall[]>;
     createFirewall(options: CreateFirewallOptions): Promise<{
@@ -122,6 +166,8 @@ export declare class HetznerClient {
      * firewall's rules in sync with the desired config without recreating it.
      */
     setFirewallRules(firewallId: number, rules: HetznerFirewallRule[]): Promise<HetznerAction[]>;
+    /** Delete a firewall. A firewall still applied to a server cannot be deleted. */
+    deleteFirewall(firewallId: number): Promise<void>;
     applyFirewallToResources(firewallId: number, applyTo: Array<{
         type: 'server';
         server: number;

package/dist/drivers/hetzner/cloud-init.d.ts

@@ -1,23 +1,12 @@
 /**
- * Ubuntu cloud-init bootstrap for Hetzner compute targets.
- * Mirrors Compute.UserData.generateBunAppScript but uses apt instead of dnf
- * and omits AWS CLI (deploys use SCP + SSH).
+ * Hetzner cloud-init: wraps the shared Ubuntu bootstrap as #cloud-config.
+ *
+ * The provisioning recipe itself lives in
+ * {@link import('../shared/ubuntu-bootstrap')} (shared with the AWS path and
+ * the golden-image bake). `generateUbuntuAppCloudInit` is kept as a back-compat
+ * alias for the shared builder.
  */
-export interface UbuntuBootstrapOptions {
-    runtime?: 'bun' | 'node' | 'deno';
-    runtimeVersion?: string;
-    systemPackages?: string[];
-    database?: 'sqlite' | 'mysql' | 'postgres';
-    caddyfile?: string;
-    /**
-     * Shell commands that install + start the rpx reverse-proxy gateway, built by
-     * {@link import('../shared/rpx-gateway').buildRpxProvisionScript}. Appended
-     * after the runtime is installed so `bun add -g @stacksjs/rpx` works. Mutually
-     * exclusive with `caddyfile` (the box runs one gateway).
-     */
-    rpxProvision?: string[];
-}
-export declare function generateUbuntuAppCloudInit(options?: UbuntuBootstrapOptions): string;
+export { buildUbuntuBootstrapScript as generateUbuntuAppCloudInit, type UbuntuBootstrapOptions } from '../shared/ubuntu-bootstrap';
 /**
  * Wrap a bash bootstrap script as Hetzner cloud-init user_data (#cloud-config).
  *

package/dist/drivers/hetzner/driver.d.ts

@@ -41,6 +41,21 @@ export declare class HetznerDriver implements CloudDriver {
     private bootWait;
     constructor(options?: HetznerDriverOptions);
     provisionComputeInfrastructure(options: ProvisionComputeOptions): Promise<ComputeStackOutputs>;
+    /**
+     * Provision a load-balanced fleet: a private network, a dedicated services
+     * box (DB/cache/search), N app servers (nginx + php-fpm), and a load
+     * balancer fronting the app servers. App servers connect to the services box
+     * over the private network (wired into their `.env` at deploy time).
+     */
+    private provisionFleet;
+    /**
+     * Tear down the compute — single server or full fleet (load balancer, all
+     * app + services servers, firewalls, and the private network) — and clear
+     * local state.
+     */
+    destroyCompute(options: ProvisionComputeOptions): Promise<{
+        destroyed: string[];
+    }>;
     getComputeOutputs(options: ProvisionComputeOptions): Promise<ComputeStackOutputs>;
     uploadRelease(options: UploadReleaseOptions): Promise<UploadReleaseResult>;
     findComputeTargets(options: FindComputeTargetsOptions): Promise<ComputeTarget[]>;
@@ -87,6 +102,15 @@ export declare class HetznerDriver implements CloudDriver {
      */
     private waitForCloudInit;
     private outputsFromState;
+    /**
+     * SSH options for connecting to freshly-created cloud servers. Host-key
+     * pinning is disabled (`StrictHostKeyChecking=no` + `UserKnownHostsFile`
+     * `/dev/null`): the box is identified + trusted via the Hetzner API, and
+     * providers recycle public IPs, so a stale `known_hosts` entry from a prior
+     * (now-deleted) server would otherwise abort the deploy with
+     * "REMOTE HOST IDENTIFICATION HAS CHANGED".
+     */
+    private static readonly SSH_HOST_KEY_OPTS;
     private sshBaseArgs;
     private scpToHost;
     private sshExec;

package/dist/drivers/hetzner/state.d.ts

@@ -1,12 +1,18 @@
 export interface HetznerDriverState {
     provider: 'hetzner';
     stackName: string;
-    serverId: number;
-    serverName: string;
+    /** Absent after teardown (destroyCompute clears it). */
+    serverId?: number;
+    serverName?: string;
     firewallId?: number;
     publicIp?: string;
     deployStoragePath?: string;
     sshUser?: string;
+    /** Fleet: network/LB ids + the services box private IP, for deploy + teardown. */
+    networkId?: number;
+    loadBalancerId?: number;
+    servicesServerId?: number;
+    servicesPrivateIp?: string;
 }
 export declare function driverStatePath(stackName: string): string;
 export declare function readDriverState(stackName: string): Promise<HetznerDriverState | null>;

package/dist/drivers/shared/backups.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Scheduled database backups powered by `ts-backups`, synced to object storage.
+ *
+ * On the box we generate a `ts-backups` config from the ts-cloud database
+ * config, install the tool (Bun + `ts-backups`), and add a cron job that runs
+ * the backup and syncs the output directory to an S3-compatible bucket
+ * (AWS S3 or Hetzner object storage). `ts-backups` handles dump + local
+ * retention; ts-cloud handles the off-box copy.
+ */
+import type { ComputeBackupConfig, DatabaseConfig } from '@ts-cloud/core';
+/** Where backups are written on the box before being synced off. */
+export declare const BACKUP_OUTPUT_DIR = "/var/backups/ts-cloud";
+/** Generated ts-backups config location. */
+export declare const BACKUP_CONFIG_PATH = "/etc/ts-cloud/backups.config.ts";
+/** Cron file + runner paths. */
+export declare const BACKUP_CRON_PATH = "/etc/cron.d/ts-cloud-backups";
+export declare const BACKUP_RUNNER_PATH = "/usr/local/bin/ts-cloud-backup.sh";
+/** Generate the `ts-backups` config file content from the database config. */
+export declare function buildBackupsConfigTs(database: DatabaseConfig | undefined, backups: ComputeBackupConfig): string;
+export interface BackupProvisionOptions {
+    database?: DatabaseConfig;
+    backups: ComputeBackupConfig;
+}
+/**
+ * Build the commands that install + schedule backups. Returns `[]` when
+ * disabled. Assumes the box can install Bun (to run `ts-backups`).
+ */
+export declare function buildBackupProvisionScript(options: BackupProvisionOptions): string[];

package/dist/drivers/shared/certbot.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Let's Encrypt TLS for nginx vhosts via certbot — issuance + automatic
+ * renewal, mirroring Forge's SSL handling.
+ *
+ * `certbot --nginx` reads the site's :80 server block, obtains a certificate
+ * for its `server_name`s, and rewrites the vhost to serve :443 + redirect
+ * :80 → :443. The apt `certbot` package installs a `certbot.timer` that renews
+ * twice daily; we add a deploy-hook so nginx reloads after a renewal.
+ *
+ * For the `custom` provider the vhost is rendered with the operator's cert
+ * directly (see nginx-vhost's `ssl` option), so certbot is not involved.
+ */
+import type { SiteConfig } from '@ts-cloud/core';
+/** Resolve the effective SSL provider for a site (Let's Encrypt by default when it has a domain). */
+export declare function resolveSslProvider(site: SiteConfig): 'letsencrypt' | 'custom' | 'none';
+/** Install certbot + the nginx plugin and ensure the auto-renew timer is enabled. */
+export declare function buildCertbotInstallScript(): string[];
+export interface CertbotIssueOptions {
+    /** Primary domain. */
+    domain: string;
+    /** Additional SANs (site aliases). */
+    aliases?: string[];
+    /** Contact email for registration / expiry notices. */
+    email?: string;
+    /** Redirect HTTP → HTTPS (Forge default). @default true */
+    redirect?: boolean;
+}
+/**
+ * Issue (or expand) a Let's Encrypt cert for the domain via the nginx plugin.
+ * Idempotent: `--keep-until-expiring` reuses a valid cert, so re-running on
+ * every deploy is safe.
+ */
+export declare function buildCertbotIssueScript(options: CertbotIssueOptions): string[];
+/**
+ * Full SSL script for a site, dispatched on its provider. Returns `[]` for
+ * `custom`/`none` (custom certs are baked into the vhost already).
+ */
+export declare function buildSslScript(site: SiteConfig): string[];

package/dist/drivers/shared/compute-deploy.d.ts

@@ -15,7 +15,7 @@ export interface DeployAllSitesOptions {
     environment: EnvironmentType;
     driver: CloudDriver;
     sha: string;
-    runtime: 'bun' | 'node' | 'deno';
+    runtime: 'bun' | 'node' | 'deno' | 'php';
     tarballForSite: (siteName: string) => string;
     logger?: ComputeDeployLogger;
 }

package/dist/drivers/shared/compute-provision.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Compose the full machine-provisioning scripts for a compute box from a
+ * CloudConfig — PHP/nginx/Composer, on-box services + app database, host
+ * firewall, auto-updates, monitoring, SSH keys, notifier, and scheduled
+ * backups.
+ *
+ * Single source of truth shared by:
+ *  - the **driver cold-boot** path (Hetzner cloud-init / AWS UserData), and
+ *  - the **golden-image bake** (which runs the same provisioning then snapshots),
+ * so a baked image and a cold boot install exactly the same stack.
+ */
+import type { CloudConfig } from '@ts-cloud/core';
+export interface ComputeProvisionScripts {
+    /** Effective runtime to install (bun/node/deno/php). */
+    runtime: 'bun' | 'node' | 'deno' | 'php';
+    /** Pinned runtime version (or 'latest'). */
+    runtimeVersion: string;
+    /** Whether this box runs PHP (drives UFW/auto-updates/monitoring defaults). */
+    phpBox: boolean;
+    /** nginx + php-fpm + Composer install commands (undefined for non-PHP boxes). */
+    phpProvision?: string[];
+    /** services + db + firewall + updates + monitoring + ssh + notifier + backups. */
+    servicesProvision?: string[];
+}
+/**
+ * Build the machine provisioning scripts from a CloudConfig. Returns the
+ * pieces the Ubuntu bootstrap (and the image bake) splice in.
+ */
+export declare function buildComputeProvisionScripts(config: CloudConfig): ComputeProvisionScripts;

package/dist/drivers/shared/db-provision.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Provision on-box managed services (Forge single-server model) via **pantry**:
+ * the database engine, cache, and search are installed from the pantry registry
+ * and run as boot-time systemd services, plus the application database + user
+ * are created. When the app points at a managed/external database instead,
+ * install nothing and just wire `.env` — see {@link buildManagedDbEnv}.
+ *
+ * pantry services listen on TCP localhost ports (mysql/mariadb 3306, postgres
+ * 5432, redis 6379, memcached 11211, meilisearch 7700); DB setup connects over
+ * TCP, and the engine clients are on PATH via `pantry env`.
+ */
+import type { ComputeServicesConfig, DatabaseConfig } from '@ts-cloud/core';
+/**
+ * Build pantry install + enable/start commands for each requested on-box
+ * service. Idempotent (pantry install/enable/start are no-ops when satisfied).
+ * `options.bindPrivate` is accepted for fleet compatibility; pantry's services
+ * already bind all interfaces behind the firewall.
+ */
+export declare function buildServicesProvisionScript(services?: ComputeServicesConfig, _options?: {
+    bindPrivate?: boolean;
+}): string[];
+/**
+ * Build the commands that create the application database + user on the on-box
+ * engine. Idempotent (uses IF NOT EXISTS / existence guards). Returns `[]` when
+ * the database points at a managed host or lacks a name. The engine client is
+ * put on PATH via `pantry env` and connects over TCP localhost.
+ */
+export declare function buildDatabaseSetupScript(database: DatabaseConfig | undefined, services?: ComputeServicesConfig): string[];
+/**
+ * `.env` key/value pairs wiring a Laravel app at the (on-box or managed)
+ * database. Merge into a site's `env` so `DB_*` is set without hand-copying
+ * credentials. Returns `{}` when there's nothing to wire.
+ */
+export declare function buildManagedDbEnv(database: DatabaseConfig | undefined): Record<string, string>;

package/dist/drivers/shared/deploy-script.d.ts

@@ -1,6 +1,3 @@
-/**
- * Shared deploy script helpers for Forge-style compute deploys.
- */
 /**
  * Translate a `start` command (e.g. "bun run server.ts") into an absolute
  * systemd ExecStart by swapping the leading runtime word for its absolute path.

package/dist/drivers/shared/env-file.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Encode an environment map as a `.env` file body that round-trips correctly
+ * through PHP dotenv (Laravel) and Bun's `.env` loader.
+ *
+ * Values are double-quoted with the standard dotenv escapes (`\\`, `\"`, `\n`,
+ * `\r`, `\t`) so secrets/keys containing spaces, `#`, `=`, quotes, backslashes,
+ * or newlines survive intact. (The previous `JSON.stringify` approach
+ * over-escaped some values and corrupted multi-line ones.)
+ */
+export declare function formatEnvFile(env: Record<string, string>): string;
+/** Double-quote + escape a single `.env` value. */
+export declare function quoteEnvValue(value: string): string;

package/dist/drivers/shared/fleet.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Resolve a Forge-style fleet topology from a compute config, and wire app
+ * servers at a dedicated services box.
+ *
+ * Roles:
+ *  - `app`      — runs nginx + php-fpm, the app is deployed to every app server.
+ *  - `services` — a dedicated box running the database/cache/search.
+ *  - `lb`       — the load balancer fronting the app servers.
+ *
+ * Single-server (the common case) resolves to one `app` box with services
+ * co-located. A multi-app fleet (`appServers > 1`) gets a load balancer, a
+ * private network, and (required) a dedicated services box so every app server
+ * shares one database/cache.
+ */
+import type { ComputeConfig, DatabaseConfig } from '@ts-cloud/core';
+export type FleetRole = 'app' | 'services' | 'lb';
+export interface FleetTopology {
+    /** Number of application servers. */
+    appServers: number;
+    /** Provision a load balancer in front of the app servers. */
+    loadBalancer: boolean;
+    /** Provision a dedicated services box (DB/cache/search off the app servers). */
+    dedicatedServices: boolean;
+    /** Whether the app servers should install services locally (single-box only). */
+    servicesOnApp: boolean;
+}
+/** Resolve the fleet topology from the compute config. */
+export declare function resolveFleetTopology(compute?: ComputeConfig): FleetTopology;
+/**
+ * Build the `.env` overrides that point a PHP app at a dedicated services box
+ * over the private network (DB + Redis + Meilisearch all live there). Merge
+ * under `site.env` (explicit values win).
+ */
+export declare function buildFleetServicesEnv(servicesPrivateIp: string, database?: DatabaseConfig): Record<string, string>;

package/dist/drivers/shared/git-deploy.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Forge-style git-clone-on-server deploys: the box clones the site's repository
+ * into a fresh release directory rather than receiving a tarball over SCP.
+ *
+ * The clone is shallow (`--depth 1`) on the configured branch for speed. When a
+ * specific commit is requested, it is fetched and checked out so deploys are
+ * reproducible. The resolved commit SHA is written to `<release>/.ts-cloud-sha`
+ * so later steps (and rollbacks) can identify the release.
+ */
+import type { SiteRepositoryConfig } from '@ts-cloud/core';
+export interface GitCheckoutOptions {
+    /** Repository to clone. */
+    repository: SiteRepositoryConfig;
+    /** Absolute release directory to clone into (`<base>/releases/<id>`). */
+    releaseDir: string;
+    /**
+     * Specific commit to deploy. When omitted, the branch tip is used (Forge's
+     * push-to-deploy behaviour).
+     */
+    commit?: string;
+}
+/** Default branch when the repository config omits one. */
+export declare const DEFAULT_DEPLOY_BRANCH = "main";
+/** Default tag glob when `strategy: 'tag'` and no explicit tag is set. */
+export declare const DEFAULT_TAG_PATTERN = "v*";
+/**
+ * Build the shell commands that clone + checkout the repository into the
+ * release directory. Assumes `git` is installed (the bootstrap installs it).
+ *
+ * Strategy is taken from `repository.strategy`:
+ *  - `'push'` (default) — clone the branch tip (or a pinned `commit`).
+ *  - `'tag'` — clone a version tag: the explicit `repository.tag`, else the
+ *    highest tag matching `repository.tagPattern`, resolved on the box via
+ *    `git ls-remote --sort=-v:refname`.
+ */
+export declare function buildGitCheckoutScript(options: GitCheckoutOptions): string[];

package/dist/drivers/shared/image-recipe.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Golden-image bake recipe.
+ *
+ * Produces the bash script Packer (or a manual snapshot run) executes on a base
+ * Ubuntu box to pre-install the full ts-cloud stack (nginx, php-fpm, Composer,
+ * services, hardening). The box is then snapshotted into a Hetzner snapshot /
+ * AWS AMI and referenced via `compute.image` + `compute.bakedImage: true`, so
+ * production boots are near-instant.
+ *
+ * Because it reuses {@link buildComputeProvisionScripts} + the shared
+ * {@link buildUbuntuBootstrapScript}, a baked image and a cold boot install the
+ * exact same stack — there is no separate, drift-prone image definition.
+ */
+import type { CloudConfig } from '@ts-cloud/core';
+export interface ImageRecipeOptions {
+    /**
+     * Exclude per-app/per-deploy state from the image so it stays generic and
+     * reusable across projects: SSH keys, the app database creation, and
+     * scheduled backups are applied at boot/deploy instead of baked in.
+     * @default true
+     */
+    generic?: boolean;
+    /**
+     * Append an image-minimization pass (clear apt/composer caches, logs, tmp;
+     * reset machine-id + cloud-init so clones boot fresh; trim free space). Keeps
+     * the published snapshot/AMI as small as possible. @default true
+     */
+    optimize?: boolean;
+}
+/**
+ * Image-minimization commands appended after provisioning so the published
+ * snapshot/AMI is as small as possible. Safe to run at the end of a bake (the
+ * box is snapshotted immediately after).
+ */
+export declare function buildImageCleanupScript(): string[];
+/**
+ * Build the bake recipe (a bash script) for a config. Runs the full
+ * provisioning with `baked: false` so everything is installed into the image.
+ */
+export declare function buildImageRecipe(config: CloudConfig, options?: ImageRecipeOptions): string;