@stacksjs/ts-cloud 0.5.16 → 0.5.18

package/dist/deploy/hooks.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Deploy lifecycle hooks (`config.hooks`): `beforeBuild` / `afterBuild` /
+ * `beforeDeploy` / `afterDeploy`. Each hook is either a shell command (string,
+ * run on the deploying machine) or an async function called with the config.
+ * Mirrors Forge/Envoyer-style deploy hooks, but they run locally around the
+ * `cloud deploy` lifecycle (server-side steps belong in `site.deployScript`).
+ */
+import type { CloudConfig } from '@ts-cloud/core';
+export type LifecycleHook = string | ((config: CloudConfig) => void | Promise<void>) | undefined;
+export type HookName = 'beforeBuild' | 'afterBuild' | 'beforeDeploy' | 'afterDeploy';
+export interface HookLogger {
+    step?: (message: string) => void;
+    error?: (message: string) => void;
+}
+/**
+ * Run a single lifecycle hook. A string is executed as a shell command (inherits
+ * stdio, runs in `cwd`); a function is awaited. Throws if a string hook exits
+ * non-zero so the caller can abort the deploy. No-op when the hook is unset.
+ */
+export declare function runHook(hook: LifecycleHook, config: CloudConfig, name: HookName, logger?: HookLogger, cwd?: string): Promise<void>;
+/**
+ * Run a named hook from `config.hooks`, returning false if a string hook fails
+ * (so the deploy command can stop). Logs the failure via `logger.error`.
+ */
+export declare function runConfigHook(config: CloudConfig, name: HookName, logger?: HookLogger, cwd?: string): Promise<boolean>;

package/dist/deploy/quick-deploy.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Quick Deploy (Forge's push-to-deploy): generate a CI pipeline for the app's
+ * git provider that runs `cloud deploy` on push to the deploy branch. ts-cloud
+ * deploys from the operator's machine/CI (git-clone-on-server), so the modern
+ * equivalent of Forge's deploy webhook is a provider-native pipeline rather than
+ * an inbound webhook — keyed off `site.repository.provider`.
+ */
+import type { CloudConfig } from '@ts-cloud/core';
+export interface QuickDeployFile {
+    /** Repo-relative path to write the pipeline to. */
+    path: string;
+    /** File contents. */
+    content: string;
+    /** Resolved git provider. */
+    provider: 'github' | 'gitlab' | 'bitbucket';
+    /** Branch the pipeline triggers on. */
+    branch: string;
+}
+/**
+ * Build the CI pipeline file for the config's git provider, or `null` when no
+ * site has a github/gitlab/bitbucket repository (the `custom` provider and
+ * webhook-less setups have no native pipeline to generate). `environment`
+ * selects which `cloud deploy <env>` runs.
+ */
+export declare function buildQuickDeployCi(config: CloudConfig, environment?: string): QuickDeployFile | null;

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

@@ -108,7 +108,7 @@ export declare class HetznerDriver implements CloudDriver {
      * `/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".
+     * `REMOTE HOST IDENTIFICATION HAS CHANGED`.
      */
     private static readonly SSH_HOST_KEY_OPTS;
     private sshBaseArgs;

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

@@ -26,3 +26,15 @@ export interface BackupProvisionOptions {
  * disabled. Assumes the box can install Bun (to run `ts-backups`).
  */
 export declare function buildBackupProvisionScript(options: BackupProvisionOptions): string[];
+export interface BackupRestoreOptions {
+    /** Specific dump file on the box (absolute path). Default: newest matching dump. */
+    from?: string;
+}
+/**
+ * Build the commands that restore a database from a ts-backups dump on the box.
+ * With no `from`, the newest dump under {@link BACKUP_OUTPUT_DIR} matching the
+ * database name is used. Handles plain `.sql` and gzipped `.sql.gz`. MySQL/
+ * MariaDB restore over the root unix socket; Postgres via `psql -U postgres`.
+ * Returns `[]` when the database has no name.
+ */
+export declare function buildBackupRestoreScript(database: DatabaseConfig | undefined, options?: BackupRestoreOptions): string[];

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

@@ -7,7 +7,7 @@
  * with the shared generators, and runs it on every box — mirroring how
  * {@link import('./compute-deploy').deploySiteRelease} drives a deploy.
  */
-import type { CloudDriver, EnvironmentType, RemoteDeployInstanceResult } from '@ts-cloud/core';
+import type { CloudDriver, DatabaseConfig, EnvironmentType, RemoteDeployInstanceResult } from '@ts-cloud/core';
 export interface ComputeOpsLogger {
     info(message: string): void;
     warn(message: string): void;
@@ -57,3 +57,12 @@ export declare function runComputeRecipe(ctx: ComputeOpsContext, options: {
     script: string[];
     user?: string;
 }): Promise<ComputeOpsResult>;
+/**
+ * Restore a database from a ts-backups dump on the box (Forge's backup restore).
+ * Runs the restore on the project's servers; with no `from`, the newest matching
+ * dump is used. Returns per-server output.
+ */
+export declare function restoreDatabaseBackup(ctx: ComputeOpsContext, options: {
+    database: DatabaseConfig | undefined;
+    from?: string;
+}): Promise<ComputeOpsResult>;

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

@@ -40,6 +40,14 @@ export interface LaravelDeployOptions {
  * Composer `auth.json` and/or `.npmrc`. Quoted heredocs keep tokens literal.
  */
 export declare function buildCredentialFiles(releaseDir: string, creds?: SiteCredentialsConfig): string[];
+/**
+ * Post-deploy health check (Forge-style): once the release is live, hit the
+ * site through nginx on localhost (with the site's `Host` header) and fail the
+ * deploy if it doesn't return 2xx/3xx within a few retries. A redirect (e.g.
+ * the certbot HTTP→HTTPS 301) counts as healthy — nginx is up and routing.
+ * Returns `[]` when no `healthCheck.path` (or domain) is configured.
+ */
+export declare function buildHealthCheckScript(site: SiteConfig): string[];
 /**
  * Build the full remote shell script for a PHP/Laravel git deploy, expanding the
  * release macros. Requires `site.repository` to be set.

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

@@ -1,15 +1,23 @@
 /**
- * Lightweight server monitoring, mirroring Forge's basic server metrics.
+ * Lightweight server monitoring + resource alerts, mirroring Forge's server
+ * metrics and notifications.
  *
- * Dependency-free: a small shell collector reads load average, memory, and
- * disk usage and writes a JSON snapshot to `/var/lib/ts-cloud/metrics.json`
- * every minute via a systemd timer. The ts-cloud UI (and any operator tooling)
- * can read that file for at-a-glance server health.
+ * Dependency-free: a small shell collector reads load average, memory, swap,
+ * disk, uptime, network throughput, and per-service TCP health, then writes a
+ * JSON snapshot to {@link METRICS_PATH} every minute via a systemd timer. The
+ * ts-cloud UI (and any operator tooling) reads that file for at-a-glance health.
+ *
+ * When alert thresholds are configured (CPU load per core, memory %, disk %),
+ * the collector calls the on-box `ts-cloud-notify` helper on each OK→alert
+ * transition (and once more on recovery), so channels aren't spammed every
+ * minute the box stays hot.
  */
+import type { ComputeMonitoringConfig } from '@ts-cloud/core';
 /** Where the metrics snapshot is written. */
 export declare const METRICS_PATH = "/var/lib/ts-cloud/metrics.json";
 /**
  * Build the commands that install the metrics collector + systemd timer.
- * Idempotent. Returns `[]` when disabled.
+ * Accepts `true`/`false` or a {@link ComputeMonitoringConfig} (with alert
+ * thresholds). Idempotent. Returns `[]` when disabled.
  */
-export declare function buildMonitoringScript(enabled?: boolean): string[];
+export declare function buildMonitoringScript(monitoring?: boolean | ComputeMonitoringConfig): string[];

package/dist/drivers/shared/nginx-vhost.d.ts

@@ -41,6 +41,12 @@ export interface NginxVhostOptions {
     webDirectory?: string;
     /** PHP version selecting the php-fpm socket. @default '8.3' */
     phpVersion?: string;
+    /**
+     * Override the `fastcgi_pass` target (e.g. an isolated site's dedicated
+     * php-fpm pool — see {@link import('./php-fpm-pool').phpFpmPoolListen}).
+     * Defaults to the shared php-fpm listen address for {@link phpVersion}.
+     */
+    fastcgiPass?: string;
     /** `from path` → `to URL` 301 redirects. */
     redirects?: Record<string, string>;
     /**
@@ -71,6 +77,19 @@ export interface NginxVhostOptions {
     serverSnippet?: string[];
     /** `client_max_body_size` override for this vhost (e.g. `'256M'`). */
     clientMaxBodySize?: string;
+    /** Emit an HSTS header. `true` = 1yr + includeSubDomains; object customizes. */
+    hsts?: boolean | {
+        maxAge?: number;
+        includeSubDomains?: boolean;
+        preload?: boolean;
+    };
+    /** `ssl_protocols` for the custom-cert :443 block. */
+    tlsProtocols?: string[];
+    /** Per-site IP allow/deny (Forge "Security Rules"). */
+    security?: {
+        allow?: string[];
+        deny?: string[];
+    };
 }
 /** Path of the htpasswd file for a site. */
 export declare function htpasswdPath(siteName: string): string;

package/dist/drivers/shared/php-fpm-pool.d.ts

@@ -0,0 +1,34 @@
+/** Directory pantry's php-fpm master scans for extra pool configs (`include`). */
+export declare const PHP_FPM_POOL_DIR = "/var/lib/pantry/php-fpm/pool.d";
+/** Dedicated Linux user (and group) the site's php-fpm pool runs as. */
+export declare function siteUser(siteName: string): string;
+/**
+ * Deterministic per-site php-fpm listen port in `[9100, 9499]`. Stable for a
+ * given site name (stateless generation), so redeploys reuse the same port.
+ */
+export declare function phpFpmPoolPort(siteName: string): number;
+/** The `fastcgi_pass` target for an isolated site's dedicated pool. */
+export declare function phpFpmPoolListen(siteName: string): string;
+export interface PhpFpmPoolOptions {
+    /** Site key — names the pool, user, and config file. */
+    siteName: string;
+    /** Site root (`/var/www/<site>`) — owned by the site user and the open_basedir jail. */
+    appBase: string;
+    /** Max worker processes for the pool. @default 10 */
+    maxChildren?: number;
+}
+/**
+ * Render the php-fpm pool config for an isolated site: a named pool running as
+ * the site's dedicated user, listening on its per-site port, jailed to its own
+ * directory tree (`open_basedir`) plus `/tmp`.
+ */
+export declare function buildPhpFpmPoolConf(options: PhpFpmPoolOptions): string;
+/**
+ * Build the shell commands that set up an isolated site's php-fpm pool: create
+ * the dedicated system user/group, give www-data (nginx) group access so it can
+ * still read static files, take ownership of the site tree, write the pool conf
+ * into pantry's pool include dir, and restart php-fpm so the pool comes up.
+ *
+ * Idempotent — re-runnable on every deploy.
+ */
+export declare function buildPhpFpmPoolScript(options: PhpFpmPoolOptions): string[];