@stacksjs/ts-cloud 0.2.26 → 0.2.27

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

@@ -0,0 +1,76 @@
+/**
+ * Generate an nginx server block (vhost) for a Forge-style site and the shell
+ * commands that install it.
+ *
+ * Site `type` drives the template:
+ *  - `laravel` / `statamic` / `wordpress` — `public/` web root, `index.php`,
+ *    `try_files … /index.php?$query_string`, and a `fastcgi_pass` to the site's
+ *    php-fpm socket (see {@link import('./php-provision').phpFpmSocketPath}).
+ *  - `php` — generic PHP app behind php-fpm, web root at the release root.
+ *  - `static` — plain files, `try_files … =404`.
+ *  - `spa` — SPA fallback to `/index.html`.
+ *
+ * The block listens on :80 only; TLS (the `:443` block + redirect) is layered
+ * on by certbot in the SSL step, so this stays stable across cert renewals.
+ */
+import type { SiteConfig } from '@ts-cloud/core';
+export type NginxSiteType = NonNullable<SiteConfig['type']>;
+export interface NginxVhostOptions {
+    /** Site key — names the config file (`/etc/nginx/sites-available/<siteName>`). */
+    siteName: string;
+    /** Primary hostname (`server_name`). */
+    domain: string;
+    /** Additional hostnames added to `server_name`. */
+    aliases?: string[];
+    /** Site type — selects the template. @default 'laravel' */
+    type?: NginxSiteType;
+    /**
+     * Directory the vhost serves from. For zero-downtime sites this is the
+     * `current` symlink (`/var/www/<site>/current`); the web root appends
+     * {@link webDirectory}.
+     */
+    appDir: string;
+    /** Web root relative to {@link appDir}. Defaults per type (see {@link defaultWebDirectory}). */
+    webDirectory?: string;
+    /** PHP version selecting the php-fpm socket. @default '8.3' */
+    phpVersion?: string;
+    /** `from path` → `to URL` 301 redirects. */
+    redirects?: Record<string, string>;
+    /**
+     * Serve TLS directly from this vhost using operator-provided certs. When set,
+     * the :80 block becomes an HTTPS redirect and a :443 `ssl` block serves the
+     * site. Used for the `custom` SSL provider; for Let's Encrypt, certbot
+     * rewrites the :80 block itself (leave this unset).
+     */
+    ssl?: {
+        certPath: string;
+        keyPath: string;
+    };
+    /**
+     * HTTP Basic auth (htpasswd). When set, the vhost requires auth and the
+     * generated script writes the htpasswd file. The `realm` is shown in the
+     * browser prompt.
+     */
+    auth?: {
+        username: string;
+        password: string;
+        realm?: string;
+    };
+}
+/** Path of the htpasswd file for a site. */
+export declare function htpasswdPath(siteName: string): string;
+/** Whether a site type is served by php-fpm. */
+export declare function isPhpSiteType(type: NginxSiteType): boolean;
+/** Default web root (relative to the release dir) for a site type. */
+export declare function defaultWebDirectory(type: NginxSiteType): string;
+/**
+ * Build the nginx server block text for a site. With `options.ssl`, emits a
+ * :80 → HTTPS redirect plus a :443 `ssl` block (the `custom` cert path);
+ * otherwise a single :80 block (certbot upgrades it for Let's Encrypt).
+ */
+export declare function buildNginxVhost(options: NginxVhostOptions): string;
+/**
+ * Build the shell commands that write the vhost, enable it, validate the nginx
+ * config, and reload. Re-runnable (overwrites the config + refreshes the symlink).
+ */
+export declare function buildNginxVhostScript(options: NginxVhostOptions): string[];

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

@@ -0,0 +1,40 @@
+/**
+ * Send deploy / SSL / health-check / backup notifications to the configured
+ * channels (Slack, Discord, Telegram, email, generic webhook), mirroring
+ * Forge's notification system.
+ *
+ * Two surfaces:
+ *  - {@link sendNotifications} — called from the TS deploy orchestrator for
+ *    deploy success/failure (and other events ts-cloud drives locally).
+ *  - {@link buildNotifierScript} — generates an on-box `ts-cloud-notify`
+ *    helper that cron-driven events (certbot renewal, backups) can call.
+ */
+import type { NotifyEvent, NotificationsConfig } from '@ts-cloud/core';
+/** Fetch implementation (injectable for tests). */
+export type FetchLike = (input: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+}>;
+export interface SendNotificationsOptions {
+    /** Override the fetch implementation (default: global `fetch`). */
+    fetchImpl?: FetchLike;
+}
+/**
+ * Send `message` for `event` to every configured + subscribed channel. Errors
+ * on individual channels are swallowed (a flaky webhook must not fail a deploy);
+ * returns the list of channels that were attempted.
+ */
+export declare function sendNotifications(config: NotificationsConfig | undefined, event: NotifyEvent, message: string, options?: SendNotificationsOptions): Promise<string[]>;
+/** Resolve the effective notifications config for a site (site overrides project). */
+export declare function resolveNotifications(project: NotificationsConfig | undefined, site: NotificationsConfig | undefined): NotificationsConfig | undefined;
+/**
+ * Generate an on-box `ts-cloud-notify` script that POSTs `$1` (a message) to
+ * the webhook channels. Used by cron-driven hooks (certbot renew, backups) so
+ * server-side events also reach Slack/Discord/etc. Returns `[]` when no
+ * webhook-style channel is configured.
+ */
+export declare function buildNotifierScript(config: NotificationsConfig | undefined): string[];

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

@@ -0,0 +1,38 @@
+/**
+ * Generate the apt provisioning script for a Forge-style PHP box: nginx,
+ * one or more PHP-FPM versions (via `ppa:ondrej/php`), the standard Laravel
+ * extension set, and Composer.
+ *
+ * Returns an array of shell command lines (matching the convention of
+ * {@link import('./rpx-gateway').buildRpxProvisionScript}) so it can be spliced
+ * into the Ubuntu cloud-init bootstrap. Each requested PHP version installs its
+ * own `phpX.Y-fpm` pool so different sites can pin different versions and nginx
+ * can `fastcgi_pass` to the matching unix socket
+ * (`/run/php/phpX.Y-fpm.sock`).
+ */
+/**
+ * Baseline PHP extension package suffixes installed for every version
+ * (`phpX.Y-<suffix>`). Covers Laravel's documented requirements plus the
+ * common drivers (mysql/pgsql/sqlite/redis) and image/locale/number stack.
+ */
+export declare const LARAVEL_PHP_EXTENSIONS: readonly string[];
+export interface PhpProvisionOptions {
+    /** PHP versions to install (e.g. `['8.3', '8.2']`). @default ['8.3'] */
+    versions?: string[];
+    /** Default PHP version (sets the `php` CLI alternative). @default first of `versions` */
+    default?: string;
+    /** Extra extension suffixes beyond {@link LARAVEL_PHP_EXTENSIONS} (e.g. `['imagick']`). */
+    extensions?: string[];
+    /** Install + enable nginx. @default true */
+    installNginx?: boolean;
+    /** Install Composer to `/usr/local/bin/composer`. @default true */
+    installComposer?: boolean;
+}
+/** Per-version apt package names for the given extension suffixes. */
+export declare function phpPackagesForVersion(version: string, extensions: readonly string[]): string[];
+/** Absolute php-fpm unix socket path for a version (matches ondrej's layout). */
+export declare function phpFpmSocketPath(version: string): string;
+/**
+ * Build the shell command lines that provision PHP-FPM, nginx, and Composer.
+ */
+export declare function buildPhpProvisionScript(options?: PhpProvisionOptions): string[];

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

@@ -0,0 +1,52 @@
+/**
+ * Zero-downtime atomic release management for Forge-style git deploys.
+ *
+ * Directory layout under a site's base (`/var/www/<site>`):
+ *   releases/<id>/   one checkout per deploy
+ *   shared/          files persisted across releases (storage, .env, …)
+ *   current ->       symlink to the active release
+ *
+ * A deploy clones into `releases/<id>`, symlinks the shared paths in, runs the
+ * deploy script, then atomically repoints `current`. Old releases are pruned
+ * to a retention count for rollback. These map to Forge's deploy macros:
+ *   $CREATE_RELEASE   → {@link buildEnsureReleaseLayout} + git clone + {@link buildLinkSharedPaths}
+ *   $ACTIVATE_RELEASE → {@link buildActivateRelease} (+ {@link buildPruneReleases})
+ */
+/** Paths that are always shared across releases (Forge shares `.env` implicitly). */
+export declare const DEFAULT_SHARED_PATHS: readonly string[];
+/** Default number of past releases to retain for rollback. */
+export declare const DEFAULT_KEEP_RELEASES = 4;
+export interface ReleasePaths {
+    /** Site base directory (`/var/www/<site>`). */
+    base: string;
+    /** Releases parent (`<base>/releases`). */
+    releases: string;
+    /** Shared parent (`<base>/shared`). */
+    shared: string;
+    /** Active-release symlink (`<base>/current`). */
+    current: string;
+    /** This deploy's release dir (`<base>/releases/<id>`). */
+    release: string;
+}
+/** Resolve the standard release layout paths for a site + release id. */
+export declare function releasePaths(base: string, releaseId: string): ReleasePaths;
+/**
+ * Ensure the releases/ and shared/ skeleton exist, including the Laravel
+ * `storage` tree and an empty shared `.env` so symlinks never dangle.
+ */
+export declare function buildEnsureReleaseLayout(paths: ReleasePaths, sharedPaths?: readonly string[]): string[];
+/**
+ * Symlink every shared path from `shared/` into the freshly checked-out release,
+ * replacing whatever the checkout shipped (e.g. the repo's empty `storage`).
+ */
+export declare function buildLinkSharedPaths(paths: ReleasePaths, sharedPaths?: readonly string[]): string[];
+/**
+ * Atomically repoint `current` at the new release. Writes a temp symlink and
+ * `mv -T`s it over `current` so there is no window where `current` is missing.
+ */
+export declare function buildActivateRelease(paths: ReleasePaths): string[];
+/**
+ * Remove all but the newest `keep` releases (by mtime). `current` always points
+ * at the newest, so it is never pruned.
+ */
+export declare function buildPruneReleases(paths: ReleasePaths, keep?: number): string[];

package/dist/drivers/shared/ssh-keys.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Declaratively manage operator SSH keys in the box's `authorized_keys`.
+ *
+ * Keys are written inside a ts-cloud-managed block (delimited by marker
+ * comments) so the set can be reconciled on every provision/deploy without
+ * disturbing keys added out-of-band: the whole block is rewritten from the
+ * config each time. Adding an SSH key is therefore "add an entry + redeploy".
+ */
+import type { SshKeyConfig } from '@ts-cloud/core';
+/** Default authorized_keys path (root deploy user). */
+export declare const DEFAULT_AUTHORIZED_KEYS = "/root/.ssh/authorized_keys";
+export interface AuthorizedKeysOptions {
+    /** authorized_keys file to manage. @default '/root/.ssh/authorized_keys' */
+    path?: string;
+}
+/**
+ * Build the commands that reconcile the managed key block in authorized_keys.
+ * Strips any previous ts-cloud block, then appends the current set. Returns `[]`
+ * when there are no keys to manage.
+ */
+export declare function buildAuthorizedKeysScript(keys?: SshKeyConfig[], options?: AuthorizedKeysOptions): string[];

package/dist/drivers/shared/ubuntu-bootstrap.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The canonical Ubuntu provisioning recipe for a ts-cloud compute box.
+ *
+ * This single bash builder is used in three places so there is exactly one
+ * source of truth (and zero per-provider divergence):
+ *  - **cold boot** — Hetzner cloud-init / AWS EC2 UserData run it on first boot.
+ *  - **image bake** — the golden-image pipeline runs it to pre-install the
+ *    stack, then snapshots the box into a Hetzner snapshot / AWS AMI.
+ *  - **baked boot** — when a box boots from a pre-provisioned image, pass
+ *    `baked: true` to skip the install-heavy steps (apt/runtime/php/services)
+ *    that are already in the image, keeping only cheap per-boot setup.
+ *
+ * Targets Ubuntu (apt) — Forge's platform — on every provider, so the apt
+ * provisioning, nginx vhosts, php-fpm sockets, and deploy scripts are identical
+ * for Hetzner and AWS.
+ */
+export interface UbuntuBootstrapOptions {
+    runtime?: 'bun' | 'node' | 'deno' | 'php';
+    runtimeVersion?: string;
+    systemPackages?: string[];
+    database?: 'sqlite' | 'mysql' | 'postgres';
+    /**
+     * Shell commands that install PHP-FPM + nginx + Composer, built by
+     * {@link import('./php-provision').buildPhpProvisionScript}. Spliced
+     * after the base packages so Laravel/PHP sites have their runtime ready
+     * before any deploy. Used when `runtime === 'php'` (or `compute.php` is set).
+     */
+    phpProvision?: string[];
+    /**
+     * Shell commands that install on-box services (database engine, redis,
+     * memcached, meilisearch) and create the app database + user, built by
+     * {@link import('./db-provision')}. Spliced after the PHP provision.
+     */
+    servicesProvision?: string[];
+    caddyfile?: string;
+    /**
+     * Shell commands that install + start the rpx reverse-proxy gateway, built by
+     * {@link import('./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[];
+    /**
+     * The box boots from a pre-provisioned (golden) image that already has the
+     * runtime + PHP + services + base packages installed. Skip those install
+     * steps — only do the cheap per-boot setup (dirs, gateway config). Makes
+     * boot near-instant. @default false
+     */
+    baked?: boolean;
+}
+/**
+ * Build the Ubuntu provisioning bash script (with `#!/bin/bash` shebang).
+ */
+export declare function buildUbuntuBootstrapScript(options?: UbuntuBootstrapOptions): string;

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

@@ -0,0 +1,17 @@
+/**
+ * Host firewall (UFW) provisioning, mirroring Forge's per-server firewall.
+ *
+ * Defaults to deny-incoming / allow-outgoing, with SSH (OpenSSH), HTTP (80),
+ * and HTTPS (443) always open so deploys and web traffic keep working, plus
+ * any extra ports the config lists (e.g. a Reverb/websocket port). On Hetzner
+ * this is layered on top of the cloud firewall; on a bare box it's the primary
+ * line of defence.
+ */
+import type { ComputeFirewallConfig } from '@ts-cloud/core';
+/** Ports always allowed so SSH deploys + web traffic are never locked out. */
+export declare const UFW_BASE_PORTS: readonly number[];
+/**
+ * Build the UFW provisioning commands. Idempotent: `ufw allow` is a no-op when
+ * a rule already exists, and `--force enable` is safe to re-run.
+ */
+export declare function buildUfwScript(firewall?: ComputeFirewallConfig): string[];