@stacksjs/ts-cloud 0.2.20 → 0.2.22

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

@@ -91,10 +91,12 @@ export interface CreateSshKeyOptions {
     publicKey: string;
     labels?: Record<string, string>;
 }
+/** Minimal fetch signature the client relies on (always called with a string URL). */
+export type HetznerFetch = (url: string, init?: RequestInit) => Promise<Response>;
 export interface HetznerClientOptions {
     apiToken: string;
     baseUrl?: string;
-    fetchImpl?: typeof fetch;
+    fetchImpl?: HetznerFetch;
 }
 export declare class HetznerClient {
     readonly name = "hetzner";
@@ -115,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/cloud-init.d.ts

@@ -13,5 +13,12 @@ export interface UbuntuBootstrapOptions {
 export declare function generateUbuntuAppCloudInit(options?: UbuntuBootstrapOptions): string;
 /**
  * Wrap a bash bootstrap script as Hetzner cloud-init user_data (#cloud-config).
+ *
+ * The script is written to disk via `write_files` and then executed through an
+ * explicit `bash` invocation in `runcmd`. cloud-init runs bare `runcmd` entries
+ * with `/bin/sh` (dash on Ubuntu), which chokes on bash-only syntax like
+ * `set -o pipefail` and aborts the whole bootstrap — so embedding the script
+ * inline under `runcmd:` silently breaks bun/caddy installation. Writing the
+ * file (shebang preserved) and running `bash <file>` guarantees a bash shell.
  */
 export declare function wrapCloudInitUserData(bootstrapScript: string): string;

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

@@ -15,10 +15,37 @@ export interface BuildSiteDeployScriptOptions {
     execStart: string;
     envEntries: Record<string, string>;
     port?: number;
+    /**
+     * Commands run inside `appDir` after extraction + `.env` write, before the
+     * systemd unit is (re)written and started. Typically dependency install
+     * and/or build steps (e.g. `bun install --frozen-lockfile`, `bun run build`)
+     * so the release tarball can omit `node_modules`.
+     */
+    preStartCommands?: string[];
 }
 /**
  * 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

@@ -7,9 +7,9 @@ export type { AWSRequestOptions, AWSClientConfig, AWSError, AWSCredentials as AW
 export { createObjectStorageClient, providerEndpoint, resolveObjectStorage, } from './object-storage';
 export type { ObjectStorageConfig, ObjectStorageCredentials, ObjectStorageProvider, ResolvedObjectStorage, } from './object-storage';
 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';