@stacksjs/ts-cloud 0.2.27 → 0.3.1

package/dist/deploy/index.d.ts

@@ -6,3 +6,5 @@ export * from './site-target';
 export * from './static-site';
 export * from './static-site-external-dns';
 export * from './static-site-helper';
+export { buildFunctionEnv, type CodeSource, deployServerlessApp, type DeployServerlessOptions, infraEnvFromOutputs, redeployServerlessApp, type ResolvedContext, rollbackServerlessApp, runRemoteCommand, setMaintenance, } from './serverless-app';
+export { buildAndPushServerlessImage, type BuildImageOptions, type BuiltImage, } from './serverless-image';

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

@@ -0,0 +1,53 @@
+/**
+ * Serverless application deploy orchestrator (Laravel-Vapor-equivalent).
+ *
+ * Drives the full pipeline for `environments.<env>.app`:
+ *   build hooks → package → ensure artifact bucket → upload artifact →
+ *   deploy/update CloudFormation stack → update function code + env →
+ *   sync assets → run deploy hooks → health check.
+ *
+ * Plus the operational verbs: redeploy (no rebuild), rollback (previous
+ * release), and maintenance mode (down/up).
+ */
+import type { CloudConfig, EnvironmentType, ServerlessAppConfig } from '@ts-cloud/core';
+export interface DeployServerlessOptions {
+    /** Project root for entry resolution + build hooks. @default process.cwd() */
+    projectRoot?: string;
+    /** Skip the local build hooks (already run). */
+    skipBuild?: boolean;
+    /** Skip running the post-deploy `deploy` hooks. */
+    skipDeployHooks?: boolean;
+    /** Skip the post-deploy HTTP health check. */
+    skipHealthCheck?: boolean;
+}
+export interface ResolvedContext {
+    app: ServerlessAppConfig;
+    slug: string;
+    region: string;
+    stackName: string;
+    artifactBucket: string;
+    assetsBucket: string;
+}
+/**
+ * Derive framework env vars (DB/Redis hosts) from the deployed stack outputs so
+ * a Laravel app connects to the Aurora/RDS-Proxy/ElastiCache resources the
+ * composer created. Returns an empty map when nothing data-related is attached.
+ */
+export declare function infraEnvFromOutputs(app: ServerlessAppConfig, outputs: Record<string, string>): Record<string, string>;
+/** Build the complete environment for one function. Exported for testing. */
+export declare function buildFunctionEnv(app: ServerlessAppConfig, ctx: ResolvedContext, environment: EnvironmentType, mode: 'http' | 'queue' | 'cli', secrets: Record<string, string>, assetUrl: string | undefined, queueName: string | undefined, infraEnv?: Record<string, string>): Record<string, string>;
+/** Code source for a function update: an S3 zip or an ECR image. */
+export type CodeSource = {
+    kind: 'zip';
+    bucket: string;
+    key: string;
+} | {
+    kind: 'image';
+    imageUri: string;
+};
+export declare function deployServerlessApp(config: CloudConfig, environment: EnvironmentType, opts?: DeployServerlessOptions): Promise<void>;
+export declare function redeployServerlessApp(config: CloudConfig, environment: EnvironmentType): Promise<void>;
+export declare function rollbackServerlessApp(config: CloudConfig, environment: EnvironmentType): Promise<void>;
+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>;

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,32 @@
+/**
+ * Container-image build + push for serverless apps using `packaging: 'image'`.
+ *
+ * Stages a Docker build context (app files + a generated Dockerfile, plus the
+ * PHP runtime assets for PHP apps), builds the image, ensures an ECR repository,
+ * logs in, and pushes a content-tagged image. Returns the image URI the deploy
+ * orchestrator passes to CloudFormation + UpdateFunctionCode.
+ */
+import type { ServerlessAppConfig } from '@ts-cloud/core';
+export interface BuildImageOptions {
+    app: ServerlessAppConfig;
+    projectRoot: string;
+    region: string;
+    /** ECR repository name (created if missing). */
+    repository: string;
+    /** Skip local build hooks. */
+    skipBuild?: boolean;
+    onStep?: (m: string) => void;
+}
+export interface BuiltImage {
+    /** Full image URI including the content tag (repoUri:tag). */
+    imageUri: string;
+    /** The content tag (artifact hash). */
+    tag: string;
+    /** Lambda handler strings per function. */
+    handlers: {
+        http: string;
+        queue: string;
+        cli: string;
+    };
+}
+export declare function buildAndPushServerlessImage(opts: BuildImageOptions): Promise<BuiltImage>;

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

@@ -1,25 +1,29 @@
 /**
- * Provision on-box managed services (Forge single-server model): the database
- * engine, cache, and search, plus create the application database + user.
+ * Provision on-box managed services (Forge single-server model) via **pantry**:
+ * the database engine, cache, and search are installed from the pantry registry
+ * and run as boot-time systemd services, plus the application database + user
+ * are created. When the app points at a managed/external database instead,
+ * install nothing and just wire `.env` — see {@link buildManagedDbEnv}.
  *
- * These run at bootstrap (cloud-init), not on deploy, since installing an
- * engine is a machine-level, one-time operation. The app's database
- * credentials are referenced from the site's `.env` (`DB_*`). When the app
- * points at a managed/external database instead, install nothing and just wire
- * `.env` — see {@link buildManagedDbEnv}.
+ * pantry services listen on TCP localhost ports (mysql/mariadb 3306, postgres
+ * 5432, redis 6379, memcached 11211, meilisearch 7700); DB setup connects over
+ * TCP, and the engine clients are on PATH via `pantry env`.
  */
 import type { ComputeServicesConfig, DatabaseConfig } from '@ts-cloud/core';
 /**
- * Build apt install + enable commands for each requested on-box service.
- * Idempotent: apt install is a no-op when already present.
+ * Build pantry install + enable/start commands for each requested on-box
+ * service. Idempotent (pantry install/enable/start are no-ops when satisfied).
+ * `options.bindPrivate` is accepted for fleet compatibility; pantry's services
+ * already bind all interfaces behind the firewall.
  */
-export declare function buildServicesProvisionScript(services?: ComputeServicesConfig, options?: {
+export declare function buildServicesProvisionScript(services?: ComputeServicesConfig, _options?: {
     bindPrivate?: boolean;
 }): string[];
 /**
  * Build the commands that create the application database + user on the on-box
  * engine. Idempotent (uses IF NOT EXISTS / existence guards). Returns `[]` when
- * the database points at a managed host or lacks a name.
+ * the database points at a managed host or lacks a name. The engine client is
+ * put on PATH via `pantry env` and connects over TCP localhost.
  */
 export declare function buildDatabaseSetupScript(database: DatabaseConfig | undefined, services?: ComputeServicesConfig): string[];
 /**

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

@@ -74,3 +74,15 @@ export declare function buildNginxVhost(options: NginxVhostOptions): string;
  * config, and reload. Re-runnable (overwrites the config + refreshes the symlink).
  */
 export declare function buildNginxVhostScript(options: NginxVhostOptions): string[];
+/** Wrapper that runs the pantry-installed nginx binary inside pantry's env. */
+export declare const NGINX_WRAPPER = "/usr/local/bin/ts-cloud-nginx";
+/**
+ * Set up ts-cloud-managed nginx on top of the pantry-installed nginx binary:
+ * a wrapper that runs nginx within `pantry env` (so it + its shared libs
+ * resolve), a full `/etc/nginx/nginx.conf` that `include`s the per-site vhosts,
+ * and a systemd unit on :80/:443. Replaces apt's nginx service (pantry's own
+ * nginx service serves a minimal :8080 default and isn't started here).
+ *
+ * Run once at provision time, after the nginx binary is installed.
+ */
+export declare function buildNginxServiceScript(projectDir?: string): string[];

package/dist/drivers/shared/package-manager.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Pantry-based package manager for provisioned servers.
+ *
+ * Every server dependency ts-cloud installs — PHP, nginx, Composer, the
+ * databases/caches/search engines, and the language runtimes — comes from the
+ * pantry registry (`registry.pantry.dev`, Hetzner-backed object storage) via
+ * the `pantry` CLI instead of apt/ppa/curl installers. Long-running services
+ * are managed by pantry's own systemd integration, which runs in **system
+ * scope** when provisioning as root (units under `/etc/systemd/system`, started
+ * at boot) — see `PANTRY_SERVICE_SCOPE` in pantry's service controller.
+ *
+ * This module is the single chokepoint for "install package X" / "run service
+ * Y" so the Hetzner and AWS bootstrap paths share one implementation. It only
+ * emits shell command lines (the convention used across `drivers/shared`); the
+ * caller splices them into the Ubuntu cloud-init / SSM bootstrap.
+ */
+/**
+ * Pantry package domains for the dependencies ts-cloud provisions. Domains
+ * (not aliases) are used because aliases aren't guaranteed in every released
+ * pantry binary. The recipes live in pantry's `src/packages/*` (e.g. `php.net`
+ * is a source build carrying the full Laravel extension matrix).
+ */
+export declare const PANTRY_PACKAGES: {
+    readonly php: "php.net";
+    readonly nginx: "nginx.org";
+    readonly composer: "getcomposer.org";
+    readonly mysql: "mysql.com";
+    readonly mariadb: "mariadb.org";
+    readonly postgres: "postgresql.org";
+    readonly redis: "redis.io";
+    readonly memcached: "memcached.org";
+    readonly meilisearch: "meilisearch.com";
+    readonly git: "git-scm.com";
+    readonly certbot: "certbot.eff.org";
+    readonly bun: "bun.sh";
+    readonly node: "nodejs.org";
+    readonly deno: "deno.land";
+};
+/** Logical package key (`'php'`, `'nginx'`, …). */
+export type PantryPackageKey = keyof typeof PANTRY_PACKAGES;
+/** A fully-qualified pantry package domain (`'php.net'`, `'nginx.org'`, …). */
+export type PantryPackageDomain = (typeof PANTRY_PACKAGES)[PantryPackageKey];
+/** A package to install: a known domain, optionally pinned with `@<version>`. */
+export type PantrySpec = PantryPackageDomain | `${PantryPackageDomain}@${string}`;
+/** Where the `pantry` binary itself is installed (on PATH for all later steps). */
+export declare const PANTRY_INSTALL_DIR = "/usr/local/bin";
+/**
+ * Server-side pantry project root. `pantry install` is project-scoped — it
+ * writes packages under `<root>/pantry/` and exposes their binaries via
+ * `<root>/pantry/.bin`. Provisioning installs everything into this one fixed
+ * project so the env (and thus PATH) is stable across deploy/systemd steps.
+ */
+export declare const PANTRY_PROJECT_DIR = "/opt/pantry";
+export interface PantryBootstrapOptions {
+    /** Pin the pantry CLI version (e.g. `'0.9.39'`). @default latest release */
+    version?: string;
+}
+/**
+ * Bootstrap the `pantry` CLI on a fresh server (idempotent — skips when already
+ * present). Installs to {@link PANTRY_INSTALL_DIR} and selects system-scope
+ * service management so `pantry enable/start` provisions boot-time systemd
+ * units rather than the per-user units that can't run headlessly.
+ */
+export declare function buildPantryBootstrapScript(options?: PantryBootstrapOptions): string[];
+/**
+ * Shell snippet that puts the project's pantry-installed binaries (php,
+ * composer, …) on PATH for a deploy step. `pantry env` is project-scoped, so it
+ * is evaluated from {@link PANTRY_PROJECT_DIR}. Returns a single line to
+ * `eval`/source before invoking those binaries.
+ */
+export declare function pantryEnvActivation(): string;
+/**
+ * Install one or more pantry packages in a single resolve pass. Accepts known
+ * domains (optionally `domain@version`). Returns `[]` for an empty list.
+ */
+export declare function buildPantryInstallScript(specs: readonly PantrySpec[]): string[];
+/**
+ * Enable (start on boot) and start pantry-managed services now. Service names
+ * are pantry's own (`'php-fpm'`, `'nginx'`, `'mysql'`, `'redis'`, …), not the
+ * package domains.
+ */
+export declare function buildPantryServiceScript(services: readonly string[]): string[];
+/** Resolve a logical key (or an explicit domain) to its package domain. */
+export declare function pantryDomain(pkg: PantryPackageKey | PantryPackageDomain): PantryPackageDomain;

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

@@ -1,38 +1,36 @@
 /**
- * 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.
+ * The baseline Laravel PHP extensions. pantry's `php.net` is a single source
+ * build that already bundles these, so unlike apt there are no per-extension
+ * packages to install — this list documents the expectation and is asserted
+ * against `php -m` in tests.
  */
 export declare const LARAVEL_PHP_EXTENSIONS: readonly string[];
 export interface PhpProvisionOptions {
-    /** PHP versions to install (e.g. `['8.3', '8.2']`). @default ['8.3'] */
+    /** PHP versions to install (first is the default). pantry runs one php-fpm. @default ['8.3'] */
     versions?: string[];
-    /** Default PHP version (sets the `php` CLI alternative). @default first of `versions` */
+    /** Default PHP version. @default first of `versions` */
     default?: string;
-    /** Extra extension suffixes beyond {@link LARAVEL_PHP_EXTENSIONS} (e.g. `['imagick']`). */
+    /** Extra extensions — informational; pantry's php build is fixed. */
     extensions?: string[];
-    /** Install + enable nginx. @default true */
+    /** Install the nginx binary (the vhost/service is wired separately). @default true */
     installNginx?: boolean;
-    /** Install Composer to `/usr/local/bin/composer`. @default true */
+    /** Install 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;
+/** 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";
+/**
+ * php-fpm `fastcgi_pass` target. The `version` arg is accepted for API
+ * compatibility with the old per-version unix sockets; pantry runs a single
+ * php-fpm on {@link PHP_FPM_LISTEN}.
+ */
+export declare function phpFpmSocketPath(_version?: string): string;
+/** Resolve the default PHP version from the requested set. */
+export declare function resolveDefaultPhpVersion(options?: PhpProvisionOptions): string;
 /**
- * Build the shell command lines that provision PHP-FPM, nginx, and Composer.
+ * 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
+ * {@link import('./package-manager').buildPantryBootstrapScript}).
  */
 export declare function buildPhpProvisionScript(options?: PhpProvisionOptions): string[];

package/dist/index.d.ts

@@ -9,8 +9,8 @@ export type { ObjectStorageConfig, ObjectStorageCredentials, ObjectStorageProvid
 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, resolveSiteDeployTarget, resolveSiteKind, validateDeploymentConfig, } from './deploy';
-export type { StaticSiteConfig, DeployResult, UploadOptions, ExternalDnsStaticSiteConfig, ExternalDnsDeployResult, DeploySiteConfig, DeploySiteResult, StaticSiteDnsProvider, SiteDeployKind, DeploymentValidationResult, } from './deploy';
+export { deployStaticSite, deployStaticSiteFull, uploadStaticFiles, invalidateCache, deleteStaticSite, generateStaticSiteTemplate, deployStaticSiteWithExternalDns, deployStaticSiteWithExternalDnsFull, generateExternalDnsStaticSiteTemplate, deploySite, resolveSiteDeployTarget, resolveSiteKind, validateDeploymentConfig, buildAndPushServerlessImage, buildFunctionEnv, deployServerlessApp, infraEnvFromOutputs, redeployServerlessApp, rollbackServerlessApp, runRemoteCommand, setMaintenance, } from './deploy';
+export type { StaticSiteConfig, DeployResult, UploadOptions, ExternalDnsStaticSiteConfig, ExternalDnsDeployResult, DeploySiteConfig, DeploySiteResult, StaticSiteDnsProvider, SiteDeployKind, DeploymentValidationResult, BuildImageOptions, BuiltImage, CodeSource, DeployServerlessOptions, ResolvedContext, } from './deploy';
 export { createCloudDriver, CloudDriverFactory, cloudDrivers, AwsDriver, HetznerDriver, HetznerClient, resolveHetznerApiToken, generateUbuntuAppCloudInit, wrapCloudInitUserData, 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';