@stacksjs/ts-cloud 0.2.21 → 0.2.23

package/dist/deploy/index.d.ts

@@ -2,6 +2,7 @@
  * Deployment Modules
  * High-level deployment functions for common AWS architectures
  */
+export * from './site-target';
 export * from './static-site';
 export * from './static-site-external-dns';
 export * from './static-site-helper';

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

@@ -0,0 +1,41 @@
+import type { CloudConfig, SiteConfig, SiteDeployTarget } from '@ts-cloud/core';
+/**
+ * The three resolved deployment kinds for a site:
+ *  - `'bucket'`        — upload built `root` to object storage + CDN.
+ *  - `'server-app'`    — `server` + `start`: dynamic app as a systemd service
+ *                        behind the Caddy reverse proxy.
+ *  - `'server-static'` — `server` + no `start` (has static `root`): a static
+ *                        site built and served on the box via Caddy `file_server`.
+ */
+export type SiteDeployKind = 'bucket' | 'server-app' | 'server-static';
+/**
+ * Resolve the explicit-or-inferred {@link SiteDeployTarget} for a site.
+ *
+ * Inference (backward compatible):
+ *  1. an explicit `site.deploy` always wins;
+ *  2. else if `start` is present → `'server'`;
+ *  3. else → `'bucket'`.
+ */
+export declare function resolveSiteDeployTarget(site: SiteConfig): SiteDeployTarget;
+/**
+ * Resolve the fine-grained {@link SiteDeployKind} for a site, combining the
+ * {@link resolveSiteDeployTarget} target with the presence of `start`.
+ *
+ * - `bucket`                       → `'bucket'`
+ * - `server` + `start`            → `'server-app'`
+ * - `server` + no `start`         → `'server-static'`
+ */
+export declare function resolveSiteKind(site: SiteConfig): SiteDeployKind;
+export interface DeploymentValidationResult {
+    errors: string[];
+    warnings: string[];
+}
+/**
+ * Validate the per-site deployment configuration up front, turning what used to
+ * be silent runtime failures (e.g. a `start` site with no compute server) into
+ * an explicit, actionable contract.
+ *
+ * Never throws — returns structured `{ errors, warnings }`. Callers should abort
+ * on any error and print warnings while continuing.
+ */
+export declare function validateDeploymentConfig(config: CloudConfig): DeploymentValidationResult;

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

@@ -117,6 +117,11 @@ export declare class HetznerClient {
         firewall: HetznerFirewall;
         actions: HetznerAction[];
     }>;
+    /**
+     * Replace a firewall's rule set in place. Used to keep an existing (reused)
+     * firewall's rules in sync with the desired config without recreating it.
+     */
+    setFirewallRules(firewallId: number, rules: HetznerFirewallRule[]): Promise<HetznerAction[]>;
     applyFirewallToResources(firewallId: number, applyTo: Array<{
         type: 'server';
         server: number;

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

@@ -7,6 +7,27 @@ export interface HetznerDriverOptions {
     sshUser?: string;
     location?: string;
     client?: HetznerClient;
+    /**
+     * After the server reports `running`, block until SSH is reachable and
+     * cloud-init has finished before returning from provisioning. Disable in
+     * tests (or fast-path provisioning) to avoid real network waits.
+     * @default true
+     */
+    waitForBoot?: boolean;
+    /**
+     * Tunables for the SSH-readiness / cloud-init wait loops. Overridable so
+     * tests can use tiny intervals.
+     */
+    bootWait?: {
+        /** Delay between SSH probe attempts (ms). @default 5000 */
+        sshIntervalMs?: number;
+        /** Max time to wait for SSH to accept connections (ms). @default 300000 */
+        sshTimeoutMs?: number;
+        /** Delay between `cloud-init status` polls (ms). @default 5000 */
+        cloudInitIntervalMs?: number;
+        /** Max time to wait for cloud-init to finish (ms). @default 600000 */
+        cloudInitTimeoutMs?: number;
+    };
 }
 export declare class HetznerDriver implements CloudDriver {
     readonly name: "hetzner";
@@ -16,6 +37,8 @@ export declare class HetznerDriver implements CloudDriver {
     private sshPublicKeyPath;
     private sshUser;
     private location;
+    private waitForBoot;
+    private bootWait;
     constructor(options?: HetznerDriverOptions);
     provisionComputeInfrastructure(options: ProvisionComputeOptions): Promise<ComputeStackOutputs>;
     getComputeOutputs(options: ProvisionComputeOptions): Promise<ComputeStackOutputs>;
@@ -29,6 +52,39 @@ export declare class HetznerDriver implements CloudDriver {
      * denied (publickey)" because the server has no authorized keys.
      */
     private ensureSshKey;
+    /** getServer that returns null instead of throwing when the server is gone. */
+    private tryGetServer;
+    /**
+     * Look up an existing ts-cloud server for this project/environment by labels
+     * (falling back to name match). Used for idempotency when local state is
+     * missing, so re-running deploy doesn't spin up a duplicate server.
+     */
+    private findExistingServer;
+    /**
+     * Idempotent firewall: reuse an existing firewall with the same name rather
+     * than creating a duplicate on every deploy. When found, its rules are
+     * updated to the desired set so config changes (new ports) still apply.
+     */
+    private ensureFirewall;
+    /**
+     * Collect the upstream app ports that must be reachable when no reverse proxy
+     * is fronting traffic (raw-port deploys). Drops 80/443 (handled separately).
+     */
+    private collectUpstreamPorts;
+    private sleep;
+    /**
+     * Probe SSH (a trivial `true` over the connection) with backoff until the box
+     * accepts connections. A freshly booted server refuses SSH for a few seconds
+     * while sshd starts; without this, the very next deploy command races it and
+     * fails with "Connection refused".
+     */
+    private waitForSshReady;
+    /**
+     * Block until cloud-init finishes (`cloud-init status --wait`). cloud-init is
+     * what installs the runtime + Caddy; deploying before it completes leaves the
+     * release pointing at a half-provisioned box (missing `bun`, no Caddy).
+     */
+    private waitForCloudInit;
     private outputsFromState;
     private sshBaseArgs;
     private scpToHost;

package/dist/drivers/index.d.ts

@@ -3,6 +3,6 @@ export { AwsDriver } from './aws/driver';
 export { HetznerDriver } from './hetzner/driver';
 export { HetznerClient, resolveHetznerApiToken } from './hetzner/client';
 export { generateUbuntuAppCloudInit, wrapCloudInitUserData } from './hetzner/cloud-init';
-export { buildCaddyfile } from './shared/caddyfile';
-export { buildAwsArtifactFetch, buildLocalArtifactFetch, buildSiteDeployScript, resolveExecStart, } from './shared/deploy-script';
+export { buildCaddyfile, buildCaddyfileFromProxy, isOnDemandDomain, proxyConfigFromSites, resolveCaddyfile, staticSiteServerRoot, } from './shared/caddyfile';
+export { buildAwsArtifactFetch, buildLocalArtifactFetch, buildSiteDeployScript, buildStaticSiteDeployScript, resolveExecStart, } from './shared/deploy-script';
 export { deployAllComputeSites, deploySiteRelease } from './shared/compute-deploy';

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

@@ -1,6 +1,46 @@
-import type { SiteConfig } from '@ts-cloud/core';
+import type { CaddyAppConfig, CaddyProxyConfig, SiteConfig } from '@ts-cloud/core';
+/** A domain is "on-demand" (needs lazy TLS) if it's a wildcard or bare catch-all. */
+export declare function isOnDemandDomain(domain: string): boolean;
+/**
+ * The on-server install path a static site's `root` is shipped to. Mirrors the
+ * release layout used by the systemd app deploy (`/var/www/<name>`), so a box
+ * can host both proxied apps and file-served static sites side by side.
+ */
+export declare function staticSiteServerRoot(name: string): string;
+/**
+ * Build a complete Caddyfile from a typed {@link CaddyProxyConfig}.
+ *
+ * Produces:
+ *  - a global options block (ACME email, on-demand TLS `ask`, staging CA, extras);
+ *  - one site block per unique domain set, each performing host-based routing to
+ *    its upstream app(s);
+ *  - `tls { on_demand }` inside any block whose domains are wildcards/catch-all.
+ *
+ * Returns `undefined` when there's nothing to route (no apps, no raw).
+ */
+export declare function buildCaddyfileFromProxy(proxy: CaddyProxyConfig): string | undefined;
+/**
+ * Derive a {@link CaddyProxyConfig} from the legacy `sites` map: every site
+ * that declares a `domain` + `port` becomes a Caddy app. Keeps single-app /
+ * sites-driven deploys working without an explicit `compute.proxy` block.
+ */
+export declare function proxyConfigFromSites(sites: Record<string, SiteConfig>): CaddyProxyConfig & {
+    apps: CaddyAppConfig[];
+};
+/**
+ * Resolve the final Caddyfile for a deploy. Prefers the typed `compute.proxy`
+ * config (merging in `sites`-derived apps when `proxy.apps` is omitted), and
+ * falls back to deriving everything from `sites`.
+ *
+ * Returns `undefined` when there's nothing to route.
+ */
+export declare function resolveCaddyfile(sites: Record<string, SiteConfig>, proxy?: CaddyProxyConfig): string | undefined;
 /**
  * Build a Caddyfile from site configs. Sites sharing a domain are grouped;
  * explicit paths are ordered before catch-all routes.
+ *
+ * @deprecated Prefer {@link resolveCaddyfile} / {@link buildCaddyfileFromProxy},
+ * which support multi-app host routing and on-demand TLS. Retained for
+ * backward compatibility.
  */
 export declare function buildCaddyfile(sites: Record<string, SiteConfig>): string | undefined;

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

@@ -20,6 +20,8 @@ export interface DeployAllSitesOptions {
     logger?: ComputeDeployLogger;
 }
 /**
- * Deploy every site that declares a `start` command.
+ * Deploy every site that targets the compute server — both dynamic apps
+ * (`server` + `start`, run as systemd services) and static sites (`server`
+ * without `start`, served by Caddy `file_server`). Bucket sites are skipped.
  */
 export declare function deployAllComputeSites(options: DeployAllSitesOptions): Promise<boolean>;

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

@@ -27,5 +27,25 @@ export interface BuildSiteDeployScriptOptions {
  * Build the remote shell commands that install/refresh a site on a compute target.
  */
 export declare function buildSiteDeployScript(options: BuildSiteDeployScriptOptions): string[];
+export interface BuildStaticSiteDeployScriptOptions {
+    siteName: string;
+    /** How the remote host obtains the release tarball */
+    artifactFetch: string[];
+    /** Target directory served by Caddy `file_server`. Default `/var/www/<site>`. */
+    appDir?: string;
+    /**
+     * Commands run inside `appDir` after extraction — e.g. build the docs/blog on
+     * the box itself (`bun install`, `bun run docs:build`) when the tarball ships
+     * source rather than a pre-built site.
+     */
+    preStartCommands?: string[];
+}
+/**
+ * Build the remote shell commands that install/refresh a STATIC site on a
+ * compute target. Unlike {@link buildSiteDeployScript}, there is no systemd
+ * service — the extracted files are served directly by Caddy `file_server`
+ * (Caddy is reloaded separately when the Caddyfile changes).
+ */
+export declare function buildStaticSiteDeployScript(options: BuildStaticSiteDeployScriptOptions): string[];
 export declare function buildAwsArtifactFetch(bucket: string, key: string, region: string, siteName: string): string[];
 export declare function buildLocalArtifactFetch(localPath: string, siteName: string): string[];

package/dist/index.d.ts

@@ -6,10 +6,12 @@ export { AWSClient, CloudFormationClient, CloudFormationClient as AWSCloudFormat
 export type { AWSRequestOptions, AWSClientConfig, AWSError, AWSCredentials as AWSClientCredentials, StackParameter, StackTag, CreateStackOptions, UpdateStackOptions, DescribeStacksOptions, StackEvent, Stack, InvalidationOptions, Distribution, S3SyncOptions, S3CopyOptions, S3ListOptions, S3Object, CertificateDetail, Certificate as ELBv2Certificate, RekognitionS3Object, RekognitionBoundingBox, TextractS3Object, TextractBoundingBox, CountryCode, ContactType, ContactDetail, KendraCreateDataSourceCommandInput, KendraCreateDataSourceCommandOutput, KendraListDataSourcesCommandInput, KendraListDataSourcesCommandOutput, InvokeModelCommandInput, InvokeModelCommandOutput, InvokeModelWithResponseStreamCommandInput, InvokeModelWithResponseStreamCommandOutput, CreateModelCustomizationJobCommandInput, CreateModelCustomizationJobCommandOutput, GetModelCustomizationJobCommandInput, GetModelCustomizationJobCommandOutput, ListFoundationModelsCommandInput, ListFoundationModelsCommandOutput, AttributeValue as DynamoDBAttributeValue, KeySchemaElement, AttributeDefinition as DynamoDBAttributeDefinition, } from './aws';
 export { createObjectStorageClient, providerEndpoint, resolveObjectStorage, } from './object-storage';
 export type { ObjectStorageConfig, ObjectStorageCredentials, ObjectStorageProvider, ResolvedObjectStorage, } from './object-storage';
+export { keyMatchesFilters, migrateObjectStorage, remapKey, } from './object-storage/migrate';
+export type { MigrateEndpoint, MigrateError, MigrateOptions, MigratePlanItem, MigrateProgress, MigrateResult, MigrateVerification, } from './object-storage/migrate';
 export * from './ssl';
-export { deployStaticSite, deployStaticSiteFull, uploadStaticFiles, invalidateCache, deleteStaticSite, generateStaticSiteTemplate, deployStaticSiteWithExternalDns, deployStaticSiteWithExternalDnsFull, generateExternalDnsStaticSiteTemplate, deploySite, } from './deploy';
-export type { StaticSiteConfig, DeployResult, UploadOptions, ExternalDnsStaticSiteConfig, ExternalDnsDeployResult, DeploySiteConfig, DeploySiteResult, StaticSiteDnsProvider, } from './deploy';
-export { createCloudDriver, CloudDriverFactory, cloudDrivers, AwsDriver, HetznerDriver, HetznerClient, resolveHetznerApiToken, generateUbuntuAppCloudInit, wrapCloudInitUserData, buildCaddyfile, buildSiteDeployScript, resolveExecStart, deployAllComputeSites, deploySiteRelease, } from './drivers';
+export { deployStaticSite, deployStaticSiteFull, uploadStaticFiles, invalidateCache, deleteStaticSite, generateStaticSiteTemplate, deployStaticSiteWithExternalDns, deployStaticSiteWithExternalDnsFull, generateExternalDnsStaticSiteTemplate, deploySite, resolveSiteDeployTarget, resolveSiteKind, validateDeploymentConfig, } from './deploy';
+export type { StaticSiteConfig, DeployResult, UploadOptions, ExternalDnsStaticSiteConfig, ExternalDnsDeployResult, DeploySiteConfig, DeploySiteResult, StaticSiteDnsProvider, SiteDeployKind, DeploymentValidationResult, } from './deploy';
+export { createCloudDriver, CloudDriverFactory, cloudDrivers, AwsDriver, HetznerDriver, HetznerClient, resolveHetznerApiToken, generateUbuntuAppCloudInit, wrapCloudInitUserData, buildCaddyfile, buildCaddyfileFromProxy, isOnDemandDomain, proxyConfigFromSites, resolveCaddyfile, staticSiteServerRoot, buildSiteDeployScript, buildStaticSiteDeployScript, resolveExecStart, deployAllComputeSites, deploySiteRelease, } from './drivers';
 export type { CreateCloudDriverOptions } from './drivers/factory';
 export { createDnsProvider, detectDnsProvider, DnsProviderFactory, dnsProviders, PorkbunProvider, GoDaddyProvider, Route53Provider, UnifiedDnsValidator, createPorkbunValidator, createGoDaddyValidator, createRoute53Validator, } from './dns';
 export type { DnsProvider, DnsProviderConfig, DnsRecord, DnsRecordType, DnsRecordResult, CreateRecordResult, DeleteRecordResult, ListRecordsResult, } from './dns';