@stacksjs/ts-cloud 0.5.0 → 0.5.2

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

@@ -51,3 +51,10 @@ export declare function rollbackServerlessApp(config: CloudConfig, environment:
 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>;
+/**
+ * Run a SQL statement against a (private, in-VPC) serverless database via the CLI
+ * function — no bastion needed. Requires the `tscloud/serverless` PHP bridge
+ * (`tscloud:db-query`). The SQL is base64-encoded so it survives the runtime's
+ * whitespace argument parsing.
+ */
+export declare function runDbQuery(config: CloudConfig, environment: EnvironmentType, sql: string): Promise<string>;

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

@@ -10,11 +10,13 @@
  * 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';
+import type { SiteConfig, SslDnsConfig } 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[];
+/** Path of the certbot credentials INI for a DNS provider. */
+export declare function dnsCredentialsPath(provider: SslDnsConfig['provider']): string;
+/** Install certbot (+ optional DNS plugin) and ensure the auto-renew timer is enabled. */
+export declare function buildCertbotInstallScript(dns?: SslDnsConfig): string[];
 export interface CertbotIssueOptions {
     /** Primary domain. */
     domain: string;
@@ -24,15 +26,27 @@ export interface CertbotIssueOptions {
     email?: string;
     /** Redirect HTTP → HTTPS (Forge default). @default true */
     redirect?: boolean;
+    /** Issue `*.<domain>` + `<domain>` (requires `dns`). */
+    wildcard?: boolean;
+    /** DNS-01 validation via a certbot DNS plugin (required for wildcard). */
+    dns?: SslDnsConfig;
 }
 /**
- * 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.
+ * Build the commands that write a DNS provider's certbot credentials INI
+ * (root-only) so certbot can create the `_acme-challenge` records. Returns `[]`
+ * when there are no credentials (e.g. route53 using instance-role creds).
+ */
+export declare function buildDnsCredentialsScript(dns: SslDnsConfig): string[];
+/**
+ * Issue (or expand) a Let's Encrypt cert. Uses the nginx (HTTP-01) plugin by
+ * default; with `dns` set, uses DNS-01 via the provider plugin (the only way to
+ * get a wildcard). Idempotent: `--keep-until-expiring` reuses a valid cert.
  */
 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).
+ * `custom`/`none` (custom certs are baked into the vhost already). A wildcard
+ * request without a DNS config is impossible (HTTP-01 can't do wildcards), so
+ * it's skipped.
  */
 export declare function buildSslScript(site: SiteConfig): string[];

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

@@ -0,0 +1,59 @@
+/**
+ * Forge-style operational commands for a provisioned compute fleet, run over
+ * the active driver (SSH/SSM): roll a site back to a previous release, read a
+ * site's deployment history, and run a reusable server recipe across servers.
+ *
+ * Each finds the project's targets via the driver, builds a small shell script
+ * 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';
+export interface ComputeOpsLogger {
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+    step(message: string): void;
+    success(message: string): void;
+}
+export interface ComputeOpsContext {
+    driver: CloudDriver;
+    slug: string;
+    environment: EnvironmentType;
+    /** Target role label. @default 'app' */
+    role?: string;
+    logger?: ComputeOpsLogger;
+}
+export interface ComputeOpsResult {
+    success: boolean;
+    error?: string;
+    perInstance?: RemoteDeployInstanceResult[];
+}
+/**
+ * Roll a site back to a previous release (Forge-style). With `to`, points
+ * `current` at `releases/<to>`; otherwise the most recent prior release. After
+ * flipping the symlink, php-fpm is restarted and queue workers are signalled so
+ * they pick up the rolled-back code.
+ */
+export declare function rollbackComputeSite(ctx: ComputeOpsContext, options: {
+    siteName: string;
+    to?: string;
+}): Promise<ComputeOpsResult>;
+/**
+ * Read a site's on-box deployment history (the log written by
+ * {@link import('./releases').buildDeployHistoryHeader}). Returns the per-server
+ * output so the caller can print the most recent deploys.
+ */
+export declare function getComputeDeployHistory(ctx: ComputeOpsContext, options: {
+    siteName: string;
+    limit?: number;
+}): Promise<ComputeOpsResult>;
+/**
+ * Run a reusable server recipe (a bash script) across the project's servers as
+ * a chosen user (Forge's Recipes). The recipe runs through a login shell so
+ * pantry's env is loaded; output is captured per server.
+ */
+export declare function runComputeRecipe(ctx: ComputeOpsContext, options: {
+    name: string;
+    script: string[];
+    user?: string;
+}): Promise<ComputeOpsResult>;

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

@@ -14,7 +14,7 @@
  * (not-yet-live) release, so a failure leaves the previous release serving —
  * the Envoyer zero-downtime guarantee.
  */
-import type { SiteConfig } from '@ts-cloud/core';
+import type { SiteConfig, SiteCredentialsConfig } from '@ts-cloud/core';
 export declare const MACRO_CREATE_RELEASE = "$CREATE_RELEASE";
 export declare const MACRO_ACTIVATE_RELEASE = "$ACTIVATE_RELEASE";
 export declare const MACRO_RESTART_QUEUES = "$RESTART_QUEUES";
@@ -35,6 +35,11 @@ export interface LaravelDeployOptions {
     /** PHP version selecting the `phpX.Y` binary. @default `site.phpVersion` ?? '8.3' */
     defaultPhpVersion?: string;
 }
+/**
+ * Write private-registry credential files into the release before build:
+ * Composer `auth.json` and/or `.npmrc`. Quoted heredocs keep tokens literal.
+ */
+export declare function buildCredentialFiles(releaseDir: string, creds?: SiteCredentialsConfig): 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/nginx-vhost.d.ts

@@ -13,8 +13,15 @@
  * 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';
+import type { SiteConfig, SiteNginxConfig } from '@ts-cloud/core';
 export type NginxSiteType = NonNullable<SiteConfig['type']>;
+/**
+ * Resolve the nginx directive lines for a site's vhost from its
+ * {@link SiteNginxConfig} and the server's reusable templates: the referenced
+ * template's lines first, then the per-site `serverSnippet`. Unknown template
+ * names resolve to nothing. Returns `[]` when there's no customization.
+ */
+export declare function resolveNginxSnippet(nginx: SiteNginxConfig | undefined, templates: Record<string, string[]> | undefined): string[];
 export interface NginxVhostOptions {
     /** Site key — names the config file (`/etc/nginx/sites-available/<siteName>`). */
     siteName: string;
@@ -56,6 +63,14 @@ export interface NginxVhostOptions {
         password: string;
         realm?: string;
     };
+    /**
+     * Custom nginx directive lines injected into the server block (after the
+     * managed directives) — a resolved reusable template plus per-site snippet.
+     * See {@link import('@ts-cloud/core').SiteNginxConfig}.
+     */
+    serverSnippet?: string[];
+    /** `client_max_body_size` override for this vhost (e.g. `'256M'`). */
+    clientMaxBodySize?: string;
 }
 /** Path of the htpasswd file for a site. */
 export declare function htpasswdPath(siteName: string): string;

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

@@ -16,7 +16,21 @@ export interface PhpProvisionOptions {
     installNginx?: boolean;
     /** Install Composer. @default true */
     installComposer?: boolean;
+    /**
+     * Apply production OPcache + php.ini tuning (Forge's "Optimize for
+     * Production"). @default true
+     */
+    optimizeForProduction?: boolean;
+    /** Extra `php.ini` directives merged on top of (or instead of) the tuning. */
+    ini?: Record<string, string>;
 }
+/**
+ * The production OPcache + runtime tuning Forge applies via "Optimize for
+ * Production". Timestamp validation is off because every deploy restarts
+ * php-fpm (so a fresh release is always recompiled); the larger buffers and
+ * realpath cache cut per-request overhead.
+ */
+export declare const PRODUCTION_PHP_INI: Readonly<Record<string, string>>;
 /** PHP-FPM listen address for nginx `fastcgi_pass` (pantry's php-fpm is TCP). */
 export declare const PHP_FPM_LISTEN = "127.0.0.1:9074";
 /**
@@ -27,10 +41,20 @@ export declare const PHP_FPM_LISTEN = "127.0.0.1:9074";
 export declare function phpFpmSocketPath(_version?: string): string;
 /** Resolve the default PHP version from the requested set. */
 export declare function resolveDefaultPhpVersion(options?: PhpProvisionOptions): string;
+/** Resolve the effective php.ini directives for the given options. */
+export declare function resolvePhpIni(options?: PhpProvisionOptions): Record<string, string>;
+/**
+ * Write a ts-cloud-managed `php.ini` drop-in with the resolved directives and
+ * restart php-fpm so it takes effect. PHP's ini layout is discovered at runtime
+ * via `php -i` (works regardless of pantry's compiled paths): the additional-ini
+ * scan dir is used when present, otherwise a managed marker block is merged into
+ * the loaded `php.ini`. Returns `[]` when there's nothing to set.
+ */
+export declare function buildPhpTuningScript(options?: PhpProvisionOptions): string[];
 /**
  * Build the shell command lines that install PHP-FPM + Composer (+ the nginx
- * binary) via pantry and start php-fpm as a system service. Assumes the pantry
- * CLI is already bootstrapped (see
+ * binary) via pantry, start php-fpm as a system service, and apply production
+ * php.ini tuning. Assumes the pantry CLI is already bootstrapped (see
  * {@link import('./package-manager').buildPantryBootstrapScript}).
  */
 export declare function buildPhpProvisionScript(options?: PhpProvisionOptions): string[];

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

@@ -16,6 +16,14 @@
 export declare const DEFAULT_SHARED_PATHS: readonly string[];
 /** Default number of past releases to retain for rollback. */
 export declare const DEFAULT_KEEP_RELEASES = 4;
+/** Number of per-deploy output logs to keep on the box. */
+export declare const DEFAULT_KEEP_DEPLOY_LOGS = 20;
+/** ts-cloud metadata dir for a site (deploy history + per-deploy logs). */
+export declare function deployMetaDir(base: string): string;
+/** Append-only deploy history log path for a site. */
+export declare function deployHistoryPath(base: string): string;
+/** Per-deploy output log path for a release. */
+export declare function deployLogPath(base: string, releaseId: string): string;
 export interface ReleasePaths {
     /** Site base directory (`/var/www/<site>`). */
     base: string;
@@ -45,8 +53,39 @@ export declare function buildLinkSharedPaths(paths: ReleasePaths, sharedPaths?:
  * `mv -T`s it over `current` so there is no window where `current` is missing.
  */
 export declare function buildActivateRelease(paths: ReleasePaths): string[];
+/**
+ * Roll the active release back to a previous one (Forge-style rollback). With
+ * `to` set, points `current` at `releases/<to>`; otherwise picks the most recent
+ * release that isn't the one `current` resolves to. Atomic (temp symlink + `mv
+ * -T`), and a no-op-safe guard fails loudly if the target is missing rather than
+ * leaving `current` dangling. The caller appends the engine reload
+ * (php-fpm/queues) — see {@link import('./laravel-deploy')}.
+ */
+export declare function buildRollbackScript(paths: ReleasePaths, options?: {
+    to?: string;
+}): 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[];
+export interface DeployHistoryOptions {
+    /** This deploy's release id. */
+    releaseId: string;
+    /** Commit SHA being deployed (recorded in the history line). */
+    commit?: string;
+    /** Branch being deployed. */
+    branch?: string;
+    /** Per-deploy logs to retain. @default {@link DEFAULT_KEEP_DEPLOY_LOGS} */
+    keepLogs?: number;
+}
+/**
+ * Header lines that record deployment history + capture per-deploy output
+ * (Forge's deployment log). Emitted near the top of the deploy script: it tees
+ * all stdout/stderr to `<base>/.ts-cloud/deploys/<releaseId>.log` and installs
+ * an EXIT trap that appends a `<ts>\t<releaseId>\t<commit>\t<status>` line to
+ * `<base>/.ts-cloud/deploy-history.log` — so both successful and failed deploys
+ * are recorded (the trap reads `$?`). Requires bash (the deploy script already
+ * uses `set -euo pipefail`).
+ */
+export declare function buildDeployHistoryHeader(base: string, options: DeployHistoryOptions): string[];

package/dist/drivers/shared/server-recipes.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Server "recipes" — reusable bash scripts run on demand across one or more
+ * provisioned servers, as a chosen user (Forge's Recipes feature). The driver
+ * fans a recipe out over the target servers (SSH/SSM); this module builds the
+ * single wrapped script that runs on each box: it sets a strict shell, runs the
+ * recipe body as the requested user with a login shell (so PATH/pantry env are
+ * loaded), and prints clear begin/end markers + the exit code so captured
+ * output is easy to scan.
+ */
+export interface ServerRecipeOptions {
+    /** Recipe name (shown in the output markers). */
+    name: string;
+    /** The recipe body — bash command lines run on the server. */
+    script: string[];
+    /**
+     * User to run the recipe as. Defaults to `root`. A non-root user is invoked
+     * via `runuser -l` so it gets a login shell (profile + PATH, incl. pantry).
+     */
+    user?: string;
+}
+/**
+ * Build the wrapped recipe script run on a server. The body is written to a
+ * temp file and executed as `user`; the wrapper captures the exit code and
+ * prints `__TS_CLOUD_RECIPE_*__` markers around the run for the driver to parse.
+ */
+export declare function buildServerRecipeScript(options: ServerRecipeOptions): string[];