@stacksjs/ts-cloud 0.9.3 → 0.10.0

package/dist/dns/cloudflare.d.ts

@@ -104,6 +104,33 @@ export declare class CloudflareProvider implements DnsProvider {
      * List all domains (zones) managed by this Cloudflare account
      */
     listDomains(): Promise<string[]>;
+    /**
+     * Create a zone in this account, or return the one already there.
+     *
+     * Idempotent on purpose. A zone migration is re-run far more often than it
+     * succeeds first time — a too-narrow token, a half-imported record set, a
+     * nameserver flip that has not propagated — and every one of those reruns
+     * would otherwise die on Cloudflare's "zone already exists" (code 1061)
+     * before reaching the import that actually needed fixing.
+     *
+     * `accountId` is required by the API for anything but a single-account token,
+     * so it falls back to {@link CloudflareProviderOptions.accountId} and fails
+     * loudly rather than letting Cloudflare pick an account for you.
+     *
+     * The returned `nameServers` are the pair the registrar has to be pointed at.
+     * They are assigned at creation and never change for the life of the zone, so
+     * they can be read once here and used to drive the registrar update.
+     */
+    createZone(domain: string, options?: {
+        accountId?: string;
+        jumpStart?: boolean;
+    }): Promise<{
+        id: string;
+        name: string;
+        status: string;
+        nameServers: string[];
+        created: boolean;
+    }>;
     /**
      * Get zone details (Cloudflare-specific)
      */

package/dist/dns/godaddy.d.ts

@@ -49,7 +49,24 @@ export declare class GoDaddyProvider implements DnsProvider {
         expires?: string;
     } | null>;
     /**
-     * Update nameservers for a domain (GoDaddy-specific)
+     * Read the nameservers the REGISTRY has this domain delegated to.
+     *
+     * Note this is the delegation, not the zone's own `NS` records. The two can
+     * disagree — that is exactly the state a half-finished migration leaves
+     * behind — and only the delegation decides who actually answers queries.
+     */
+    getNameServers(domain: string): Promise<string[]>;
+    /**
+     * Delegate a domain to a different set of nameservers.
+     *
+     * This PATCHes the DOMAIN, which is the registrar operation that changes the
+     * delegation at the registry. The obvious-looking alternative —
+     * `PUT /v1/domains/{domain}/records/NS` — writes `NS` records into GoDaddy's
+     * own hosted zone instead. That call succeeds, returns 200, and changes
+     * nothing about who is authoritative: the registry still points at the old
+     * provider. For a migration whose whole purpose is the cutover, that is the
+     * worst possible failure, because every check short of an external `dig +trace`
+     * reports success.
      */
     updateNameServers(domain: string, nameservers: string[]): Promise<boolean>;
     /**

package/dist/dns/index.d.ts

@@ -9,6 +9,8 @@ export { CloudflareProvider } from './cloudflare';
 export type { DeclaredRecord, DeclaredRecordInput, DeclaredRecordOutcome, DeclaredRecordsReport, } from './declared-records';
 export { policyTag, qualifyName, reconcileDeclaredRecords, resolveDeclaredRecords, } from './declared-records';
 export { Route53Provider } from './route53-adapter';
+export type { MigratedRecord, SkippedRecord, ZoneMigrationPlan, ZoneMigrationReport, ZoneParityReport, } from './zone-migration';
+export { applyZoneMigration, exportRoute53Zone, planZoneMigration, verifyZoneParity, } from './zone-migration';
 export { UnifiedDnsValidator, createPorkbunValidator, createGoDaddyValidator, createRoute53Validator, } from './validator';
 import type { DnsProvider, DnsProviderConfig } from './types';
 /**

package/dist/dns/index.js

@@ -1,41 +1 @@
-import {
-  CloudflareProvider,
-  DnsProviderFactory,
-  GoDaddyProvider,
-  PROXIABLE_RECORD_TYPES,
-  PorkbunProvider,
-  Route53Provider,
-  UnifiedDnsValidator,
-  createDnsProvider,
-  createGoDaddyValidator,
-  createPorkbunValidator,
-  createRoute53Validator,
-  detectDnsProvider,
-  dnsProviders,
-  policyTag,
-  qualifyName,
-  reconcileDeclaredRecords,
-  resolveDeclaredRecords
-} from "../chunk-qr803fye.js";
-import"../chunk-32e7ya18.js";
-import"../chunk-zqtpg06c.js";
-import"../chunk-v0bahtg2.js";
-export {
-  resolveDeclaredRecords,
-  reconcileDeclaredRecords,
-  qualifyName,
-  policyTag,
-  dnsProviders,
-  detectDnsProvider,
-  createRoute53Validator,
-  createPorkbunValidator,
-  createGoDaddyValidator,
-  createDnsProvider,
-  UnifiedDnsValidator,
-  Route53Provider,
-  PorkbunProvider,
-  PROXIABLE_RECORD_TYPES,
-  GoDaddyProvider,
-  DnsProviderFactory,
-  CloudflareProvider
-};
+import{Af as e,Bf as f,Cf as g,Df as h,Ef as i,Ff as j,Gf as k,Hf as l,If as m,Jf as n,Kf as o,Lf as p,Mf as q,Nf as r,Of as s,Pf as t,Qf as u,vf as a,wf as b,xf as c,zf as d}from"../chunk-2p89vt3b.js";import"../chunk-xd6w0c11.js";import"../chunk-cp54a0qn.js";import"../chunk-77t2ctwn.js";export{d as CloudflareProvider,t as DnsProviderFactory,c as GoDaddyProvider,a as PROXIABLE_RECORD_TYPES,b as PorkbunProvider,i as Route53Provider,n as UnifiedDnsValidator,l as applyZoneMigration,r as createDnsProvider,p as createGoDaddyValidator,o as createPorkbunValidator,q as createRoute53Validator,s as detectDnsProvider,u as dnsProviders,j as exportRoute53Zone,k as planZoneMigration,e as policyTag,f as qualifyName,h as reconcileDeclaredRecords,g as resolveDeclaredRecords,m as verifyZoneParity};

package/dist/dns/zone-migration.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Zone migration — move a whole zone onto another provider, record for record.
+ *
+ * This exists because the interesting part of a nameserver migration is not the
+ * nameserver change, it is everything that silently fails to come with it. A
+ * deploy derives the address records for the sites it owns; it knows nothing
+ * about mail, domain-verification tokens, certificate-validation CNAMEs or the
+ * service records a calendar client autodiscovers with. Those are exactly the
+ * records nobody notices are gone until someone reports that mail stopped, and
+ * by then the old zone may already have been deleted.
+ *
+ * So the flow here is deliberately: **export everything → translate → import →
+ * diff → only then flip the nameservers.** The diff is the point. A migration
+ * that reports "imported 91 records" without comparing against the source is
+ * indistinguishable from one that dropped seven of them.
+ */
+import type { DnsProvider, DnsRecord, DnsRecordType } from './types';
+import type { ResourceRecordSet, Route53Client } from '../aws/route53';
+/** A record as it will exist at the destination. */
+export interface MigratedRecord extends DnsRecord {
+    name: string;
+    type: DnsRecordType;
+    content: string;
+    /**
+     * Set when this record is not a faithful copy but a translation — an ALIAS
+     * flattened to a CNAME, for instance. Carried through to the report so the
+     * operator sees which records changed shape rather than having to spot it.
+     */
+    translatedFrom?: string;
+}
+export interface SkippedRecord {
+    name: string;
+    type: string;
+    reason: string;
+}
+export interface ZoneMigrationPlan {
+    zone: string;
+    records: MigratedRecord[];
+    skipped: SkippedRecord[];
+    warnings: string[];
+}
+export interface ZoneMigrationReport {
+    applied: MigratedRecord[];
+    failed: Array<{
+        record: MigratedRecord;
+        message: string;
+    }>;
+}
+export interface ZoneParityReport {
+    /** Planned records confirmed present at the destination. */
+    matched: MigratedRecord[];
+    /** Planned records absent, or present with different content. */
+    missing: Array<{
+        record: MigratedRecord;
+        found?: string;
+    }>;
+    ok: boolean;
+}
+/**
+ * Read every record set in a Route53 hosted zone.
+ *
+ * Paginates to exhaustion rather than taking the first page. Route53 returns
+ * 100 record sets by default and a zone that has quietly grown past that is
+ * precisely the zone whose tail records — added last, so most likely to be the
+ * recent mail or verification entries — would be dropped by a single call.
+ */
+export declare function exportRoute53Zone(client: Route53Client, hostedZoneId: string): Promise<ResourceRecordSet[]>;
+/**
+ * Translate a Route53 zone into records another provider can hold.
+ *
+ * Nothing is written here. The plan is the reviewable artifact — a migration
+ * that cannot be read before it runs is one that gets run twice.
+ */
+export declare function planZoneMigration(sets: ResourceRecordSet[], zone: string): ZoneMigrationPlan;
+/**
+ * Write a plan to the destination provider.
+ *
+ * Upserts rather than creates, so a half-finished migration can simply be run
+ * again. Failures are collected instead of thrown: one rejected record should
+ * not strand the other ninety, and the parity check afterwards is what decides
+ * whether the migration is actually complete.
+ */
+export declare function applyZoneMigration(provider: DnsProvider, plan: ZoneMigrationPlan): Promise<ZoneMigrationReport>;
+/**
+ * Compare what was planned against what the destination actually holds.
+ *
+ * This is the step that makes a migration safe to act on. Provider writes
+ * report success far more reliably than they take effect — a silently coerced
+ * value, a record rejected by a rule, a name written into the wrong zone — and
+ * the only way to know the new zone can replace the old one is to read it back.
+ */
+export declare function verifyZoneParity(provider: DnsProvider, plan: ZoneMigrationPlan): Promise<ZoneParityReport>;

package/dist/dns/zone-migration.test.d.ts

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

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

@@ -1,4 +1,4 @@
-import type { CloudDriver, ComputeStackOutputs, ComputeTarget, FindComputeTargetsOptions, ProvisionComputeOptions, RemoteDeployResult, RunRemoteDeployOptions, UploadReleaseOptions, UploadReleaseResult } from '@ts-cloud/core';
+import type { CloudDriver, ComputeStackOutputs, ComputeTarget, FindComputeTargetsOptions, ProvisionComputeOptions, ReachableResource, RemoteDeployResult, RunRemoteDeployOptions, UploadReleaseOptions, UploadReleaseResult } from '@ts-cloud/core';
 import { HetznerClient } from './client';
 export declare function formatSshFailure(error: unknown): string;
 export interface HetznerDriverOptions {
@@ -102,6 +102,13 @@ export declare class HetznerDriver implements CloudDriver {
      * even when several unrelated managed boxes exist in the Hetzner project.
      */
     private attachToComputeInfrastructure;
+    /**
+     * Every server this token can see. On Hetzner that is every server in the
+     * provider project, because a Cloud API token is project-scoped with Read or
+     * Read & Write and no per-resource scoping — so "can see" and "can delete"
+     * are the same set, and the count is the honest blast radius.
+     */
+    listReachableResources(): Promise<ReachableResource[]>;
     runRemoteDeploy(options: RunRemoteDeployOptions): Promise<RemoteDeployResult>;
     /**
      * Ensure the local SSH public key is registered in the Hetzner project and

package/dist/drivers/index.js

@@ -1,154 +1 @@
-import {
-  AwsBoxProvisioner,
-  AwsDriver,
-  CloudDriverFactory,
-  DEFAULT_RPX_CERTS_DIR,
-  HetznerBoxProvisioner,
-  HetznerClient,
-  HetznerDriver,
-  LocalBoxDriver,
-  MANAGED_CACHE_POLICY_DISABLED,
-  MANAGED_CACHE_POLICY_OPTIMIZED,
-  MANAGED_ORIGIN_REQUEST_POLICY_ALL_VIEWER,
-  RPX_DIR,
-  RPX_LAUNCHER_PATH,
-  RPX_SERVICE_NAME,
-  UBUNTU_2404_AMI_PARAM,
-  acquireResizeLock,
-  applyHetznerHostOptimization,
-  buildAwsArtifactFetch,
-  buildBoxUserData,
-  buildCloudFrontOriginConfig,
-  buildHetznerHostOptimizationScript,
-  buildHostCleanupScript,
-  buildLocalArtifactFetch,
-  buildRpxConfig,
-  buildRpxFragmentRefreshScript,
-  buildRpxLbConfig,
-  buildRpxProvisionScript,
-  buildSiteDeployScript,
-  buildSshArgs,
-  buildStaticSiteDeployScript,
-  buildUbuntuBootstrapScript,
-  cloudDrivers,
-  collectHetznerHostOptimizationReport,
-  collectHetznerResizeManifest,
-  createBoxProvisioner,
-  createCloudDriver,
-  deployAllComputeSites,
-  deploySiteRelease,
-  deriveRouteId,
-  ensureFirewall,
-  ensureServer,
-  ensureSshKey,
-  executeHetznerServerResize,
-  gatewayHostnames,
-  hasAutoWwwVariant,
-  isBoxMode,
-  isHetznerCapacityError,
-  normalizeRoutePath,
-  normalizeSshPublicKey,
-  planHetznerServerResize,
-  prepareHetznerResize,
-  readResizeCheckpoint,
-  releaseTarballTmpPath,
-  reloadRpxGateway,
-  renderRpxLauncher,
-  renewRpxCertificates,
-  resizeCheckpointPath,
-  resizeLockPath,
-  resolveExecStart,
-  resolveHetznerApiToken,
-  resolveHetznerHostOptimizationPlan,
-  scpUpload,
-  serverPublicIpv4,
-  sshExec,
-  sshExecOrThrow,
-  verifyHetznerHostOptimization,
-  verifyHetznerResize,
-  waitForCloudInit,
-  waitForSsh,
-  wrapCloudInitUserData,
-  writeResizeCheckpoint
-} from "../chunk-1c8dbv57.js";
-import"../chunk-7m60qnc8.js";
-import"../chunk-4cjrg98a.js";
-import"../chunk-rds0sy87.js";
-import"../chunk-zqtpg06c.js";
-import"../chunk-va2yd85b.js";
-import"../chunk-aa2dkn7b.js";
-import"../chunk-050r7ycy.js";
-import"../chunk-v0bahtg2.js";
-export {
-  writeResizeCheckpoint,
-  wrapCloudInitUserData,
-  waitForSsh,
-  waitForCloudInit,
-  verifyHetznerResize,
-  verifyHetznerHostOptimization,
-  sshExecOrThrow,
-  sshExec,
-  serverPublicIpv4,
-  scpUpload,
-  resolveHetznerHostOptimizationPlan,
-  resolveHetznerApiToken,
-  resolveExecStart,
-  resizeLockPath,
-  resizeCheckpointPath,
-  renewRpxCertificates,
-  renderRpxLauncher,
-  reloadRpxGateway,
-  releaseTarballTmpPath,
-  readResizeCheckpoint,
-  prepareHetznerResize,
-  planHetznerServerResize,
-  normalizeSshPublicKey,
-  normalizeRoutePath,
-  isHetznerCapacityError,
-  isBoxMode,
-  hasAutoWwwVariant,
-  buildUbuntuBootstrapScript as generateUbuntuAppCloudInit,
-  gatewayHostnames,
-  executeHetznerServerResize,
-  ensureSshKey,
-  ensureServer,
-  ensureFirewall,
-  deriveRouteId,
-  deploySiteRelease,
-  deployAllComputeSites,
-  createCloudDriver,
-  createBoxProvisioner,
-  collectHetznerResizeManifest,
-  collectHetznerHostOptimizationReport,
-  cloudDrivers,
-  buildStaticSiteDeployScript,
-  buildSshArgs,
-  buildSiteDeployScript,
-  buildRpxProvisionScript,
-  buildRpxLbConfig,
-  buildRpxFragmentRefreshScript,
-  buildRpxConfig,
-  buildLocalArtifactFetch,
-  buildHostCleanupScript,
-  buildHetznerHostOptimizationScript,
-  buildCloudFrontOriginConfig,
-  buildBoxUserData,
-  buildAwsArtifactFetch,
-  applyHetznerHostOptimization,
-  acquireResizeLock,
-  UBUNTU_2404_AMI_PARAM,
-  RPX_SERVICE_NAME,
-  RPX_LAUNCHER_PATH,
-  RPX_DIR,
-  MANAGED_ORIGIN_REQUEST_POLICY_ALL_VIEWER,
-  MANAGED_CACHE_POLICY_OPTIMIZED,
-  MANAGED_CACHE_POLICY_DISABLED,
-  LocalBoxDriver,
-  HetznerDriver,
-  HetznerClient,
-  HetznerBoxProvisioner,
-  DEFAULT_RPX_CERTS_DIR,
-  CloudDriverFactory,
-  AwsDriver,
-  AwsBoxProvisioner
-};
+import{$g as K,Ag as k,Ah as ia,Bg as l,Bh as ja,Cg as m,Dg as n,Eg as o,Gg as p,Hg as q,Ig as r,Jg as s,Jh as ka,Kg as t,Kh as la,Lg as u,Lh as ma,Mg as v,Mh as na,Ng as w,Nh as oa,Og as x,Oh as pa,Pg as y,Ph as qa,Qg as z,Qh as ra,Rg as A,Sg as B,Tg as C,Ug as D,Vg as E,Wg as F,Xg as G,Yg as H,Zg as I,_g as J,ah as L,bh as M,ch as N,dh as O,eh as P,fh as Q,gh as R,hh as S,ih as T,jh as U,kh as V,lh as W,mh as X,nh as Y,oh as Z,ph as _,qg as a,qh as aa,rg as b,rh as ba,sg as c,sh as ca,tg as d,ug as e,vg as f,vh as da,wg as g,wh as ea,xg as h,xh as fa,yg as i,yh as ga,zg as j,zh as ha}from"../chunk-hhdx5k96.js";import"../chunk-zmxffmmq.js";import"../chunk-e1666vjv.js";import"../chunk-snak8s7m.js";import"../chunk-cp54a0qn.js";import"../chunk-xtwjt370.js";import"../chunk-cd0zpxhf.js";import"../chunk-06jk7ba9.js";import"../chunk-77t2ctwn.js";export{ba as AwsBoxProvisioner,o as AwsDriver,x as CloudDriverFactory,a as DEFAULT_RPX_CERTS_DIR,aa as HetznerBoxProvisioner,p as HetznerClient,t as HetznerDriver,u as LocalBoxDriver,pa as MANAGED_CACHE_POLICY_DISABLED,oa as MANAGED_CACHE_POLICY_OPTIMIZED,qa as MANAGED_ORIGIN_REQUEST_POLICY_ALL_VIEWER,i as RPX_DIR,j as RPX_LAUNCHER_PATH,k as RPX_SERVICE_NAME,Z as UBUNTU_2404_AMI_PARAM,U as acquireResizeLock,N as applyHetznerHostOptimization,ha as buildAwsArtifactFetch,_ as buildBoxUserData,ra as buildCloudFrontOriginConfig,M as buildHetznerHostOptimizationScript,ja as buildHostCleanupScript,ia as buildLocalArtifactFetch,f as buildRpxConfig,m as buildRpxFragmentRefreshScript,g as buildRpxLbConfig,l as buildRpxProvisionScript,ea as buildSiteDeployScript,C as buildSshArgs,fa as buildStaticSiteDeployScript,y as cloudDrivers,O as collectHetznerHostOptimizationReport,I as collectHetznerResizeManifest,ca as createBoxProvisioner,w as createCloudDriver,la as deployAllComputeSites,ka as deploySiteRelease,e as deriveRouteId,W as ensureFirewall,X as ensureServer,V as ensureSshKey,B as executeHetznerServerResize,c as gatewayHostnames,n as generateUbuntuAppCloudInit,b as hasAutoWwwVariant,v as isBoxMode,A as isHetznerCapacityError,d as normalizeRoutePath,r as normalizeSshPublicKey,z as planHetznerServerResize,J as prepareHetznerResize,S as readResizeCheckpoint,ga as releaseTarballTmpPath,ma as reloadRpxGateway,h as renderRpxLauncher,na as renewRpxCertificates,Q as resizeCheckpointPath,R as resizeLockPath,da as resolveExecStart,q as resolveHetznerApiToken,L as resolveHetznerHostOptimizationPlan,F as scpUpload,Y as serverPublicIpv4,D as sshExec,E as sshExecOrThrow,P as verifyHetznerHostOptimization,K as verifyHetznerResize,H as waitForCloudInit,G as waitForSsh,s as wrapCloudInitUserData,T as writeResizeCheckpoint};

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

@@ -19,11 +19,23 @@ export interface ComputeProvisionScripts {
     phpBox: boolean;
     /** nginx + php-fpm + Composer install commands (undefined for non-PHP boxes). */
     phpProvision?: string[];
-    /** services + db + firewall + updates + monitoring + ssh + notifier + backups. */
+    /** services + db + mail + firewall + updates + monitoring + ssh + notifier + backups. */
     servicesProvision?: string[];
 }
+/** Which environment the box is being provisioned for. See {@link buildComputeProvisionScripts}. */
+export interface ComputeProvisionOptions {
+    /**
+     * The environment name, e.g. `'production'`.
+     *
+     * Only mail reads it today, and it reads it for a reason worth stating: an
+     * omitted environment resolves to a mail **catcher**, never a server. The
+     * caller that forgets to pass it gets a box that traps its own mail rather
+     * than one that offers SMTP to the internet.
+     */
+    environment?: string;
+}
 /**
  * Build the machine provisioning scripts from a CloudConfig. Returns the
  * pieces the Ubuntu bootstrap (and the image bake) splice in.
  */
-export declare function buildComputeProvisionScripts(config: CloudConfig): ComputeProvisionScripts;
+export declare function buildComputeProvisionScripts(config: CloudConfig, options?: ComputeProvisionOptions): ComputeProvisionScripts;

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

@@ -10,7 +10,7 @@
  * are on PATH via `pantry env`. Admin commands (db setup, dumps, restores)
  * connect over the engine's local unix socket — see {@link pgAdminCommand}.
  */
-import type { ComputeServicesConfig, DatabaseConfig } from '@ts-cloud/core';
+import type { ComputeServicesConfig, DatabaseConfig, ResolvedMailService } from '@ts-cloud/core';
 /**
  * True when the database is co-located with the box (the managed-services
  * engine): no host configured, or an explicit loopback host. Anything else is
@@ -42,8 +42,9 @@ export declare function pgAdminCommand(database: DatabaseConfig | undefined, too
  * `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;
+    mail?: ResolvedMailService;
 }): string[];
 /**
  * Build the commands that create the application database + user on the on-box

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

@@ -0,0 +1,116 @@
+/**
+ * Mail server provisioning — `mail`, the Zig SMTP/IMAP server, installed from
+ * pantry and run as a systemd unit, with its own webmail UI.
+ *
+ * ## One binary, two jobs
+ *
+ * Development mail traps and production mail servers are conventionally two
+ * different programs, and that difference is where mail breaks: a message that
+ * renders in mailpit has been through a parser nothing in production will ever
+ * run, and a `From` that mailpit accepts is one no MTA would. The bugs that
+ * costs are the ones nobody can reproduce locally.
+ *
+ * So a `'catcher'` here is not a different program. It is the same binary with
+ * delivery switched off, authentication switched off, bound to loopback, on
+ * mailpit's ports — one parser, one Maildir, one UI, all the way from a
+ * developer's laptop to production. See {@link ResolvedMailService}.
+ *
+ * ## What is deliberately not automated
+ *
+ * **DNS.** The MX, SPF and DMARC records, and the DKIM record for the key
+ * generated below, are printed rather than published. They belong to a zone
+ * this provisioner may not own, and a wrong MX does not fail — it silently
+ * routes somebody's mail somewhere else, which is discovered days later by the
+ * person who did not get it. {@link mailDnsRecords} returns them so the CLI
+ * and the dashboard can show the same set.
+ *
+ * **The DKIM private key is generated once and never rewritten.** Regenerating
+ * it on every provision would invalidate every signature already in flight,
+ * so the key is created only when the file is absent.
+ */
+import type { ResolvedMailService } from '@ts-cloud/core';
+/** Where the generated config, environment file and DKIM keys live. */
+export declare const MAIL_CONFIG_DIR = "/etc/mail";
+/** The unprivileged account the mail server runs as. */
+export declare const MAIL_USER = "mail-server";
+/** systemd unit name, so callers can restart it without re-deriving the string. */
+export declare const MAIL_UNIT = "mail";
+/** The package spec to install, honouring a pinned version. */
+export declare function mailPackages(mail: ResolvedMailService): string[];
+/** Absolute path of a domain's DKIM private key. */
+export declare function dkimKeyPath(mail: ResolvedMailService, domain: string): string;
+/**
+ * The mail server's `config.toml`.
+ *
+ * Only the keys the server actually reads (`packages/zig/src/core/config.zig`)
+ * are written. Everything the TOML has no section for — webmail, IMAP, DKIM
+ * keys, delivery method — goes in the environment file instead; see
+ * {@link buildMailEnvFile}. Splitting them is not a choice, it is where the
+ * server looks.
+ */
+export declare function buildMailConfigToml(mail: ResolvedMailService): string;
+/**
+ * The systemd `EnvironmentFile`.
+ *
+ * Everything the server configures through the environment rather than the
+ * TOML: the webmail listener, IMAP and submission ports, DKIM keys, the
+ * delivery method, and the database path.
+ */
+export declare function buildMailEnvFile(mail: ResolvedMailService): string;
+/** The systemd unit that runs the server. */
+export declare function buildMailUnit(mail: ResolvedMailService): string;
+/** A DNS record an operator has to publish for mail to work. */
+export interface MailDnsRecord {
+    type: 'MX' | 'TXT' | 'CNAME';
+    /** Record name, e.g. `example.com` or `default._domainkey.example.com`. */
+    name: string;
+    /**
+     * Record value. For DKIM this is a placeholder — the real one is derived
+     * from the public key on the box, which does not exist until provisioning
+     * has run. The shell prints the actual value; see {@link buildDkimScript}.
+     */
+    value: string;
+    /** MX preference, when the type is MX. */
+    priority?: number;
+    /** Why this record exists, shown beside it wherever it is presented. */
+    note: string;
+}
+/**
+ * The records an operator has to publish. Returned rather than created: see
+ * the module comment for why DNS is not automated here.
+ */
+export declare function mailDnsRecords(mail: ResolvedMailService): MailDnsRecord[];
+/**
+ * Generate a DKIM key per domain, once, and print the record to publish.
+ *
+ * Guarded on the file's absence rather than on a flag: a re-provision that
+ * regenerated the key would invalidate every signature already in flight, and
+ * the mail affected is mail that was already accepted by somebody's server and
+ * is now failing verification at their end.
+ */
+export declare function buildDkimScript(mail: ResolvedMailService): string[];
+/**
+ * Create the declared mailboxes.
+ *
+ * Both `create` and `change-password` run, unconditionally, and that is not
+ * belt-and-braces. `mail user:local create` on an existing account prints
+ * "already exists" and **exits 0**, so a `create || change-password` chain
+ * would never reach the second command — an operator who rotated a password in
+ * the config and redeployed would get a box that kept the old one and reported
+ * success. Running both means the declaration is the truth on every deploy.
+ *
+ * Each is tolerated failing so one bad account cannot abort a provision that
+ * has already installed and started the server, and each runs as the service
+ * account with the server's own `SMTP_DB_PATH` — as root it would create a
+ * second database beside the one the server reads, and the accounts would
+ * exist in a file nothing opens.
+ */
+export declare function buildMailAccountScript(mail: ResolvedMailService): string[];
+/**
+ * The whole provisioning sequence for the mail service.
+ *
+ * Idempotent throughout: every step is guarded, so this runs on a cold boot,
+ * on a golden-image bake, and on every redeploy with the same result. Returns
+ * `[]` when mail is not declared.
+ */
+export declare function buildMailProvisionScript(mail: ResolvedMailService): string[];

package/dist/drivers/shared/mail-provision.test.d.ts

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

package/dist/drivers/shared/managed-services-probe.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Check that a box actually runs the on-box services a project declares.
+ *
+ * This exists for attach mode (`cloud.attachTo`). A project that attaches rides
+ * a box its OWNER provisioned, and attach mode deliberately provisions nothing:
+ * installing engines on someone else's server is not a tenant's business. But
+ * the tenant's config still carries `managedServices`, and ts-cloud used to act
+ * on it regardless — creating a role and database against an engine that was
+ * never there. The result was a deploy that shipped every release and then
+ * failed at the database step, with no statement anywhere that the two settings
+ * are structurally incompatible.
+ *
+ * A declared service is considered present when its binary is on PATH (pantry
+ * puts the engines there) OR something is listening on its port. Either alone
+ * is enough on purpose: a stopped service and an engine installed outside
+ * pantry are both "the owner has this", and a preflight that fails on those
+ * would block deploys it has no business blocking. The case worth catching is
+ * the unambiguous one — no binary, no listener, no engine.
+ */
+import type { ComputeServicesConfig } from '@ts-cloud/core';
+/**
+ * The service names a config declares, in a stable order. Unknown keys are
+ * skipped rather than guessed at: a service this module cannot recognize is one
+ * it cannot honestly report as missing.
+ */
+export declare function declaredManagedServices(services: ComputeServicesConfig | undefined): string[];
+/**
+ * Shell that reports which of `names` the box provides, one `ts-cloud-service:`
+ * line each. Always exits 0 — a missing service is a finding to report, not a
+ * remote command failure to guess at.
+ */
+export declare function buildManagedServicesProbeScript(names: readonly string[]): string[];
+/**
+ * The declared services the box reported as missing.
+ *
+ * A service the probe said nothing about is NOT reported missing: silence means
+ * the probe did not run (an older box, a truncated capture), and inventing a
+ * failure from missing evidence would block deploys that are perfectly fine.
+ */
+export declare function parseMissingManagedServices(output: string | undefined, declared: readonly string[]): string[];
+/**
+ * The message an operator gets when the host does not provide what the tenant
+ * declared. Names the setting, the owner, the host, and the two ways out —
+ * because the one thing that is NOT an option is waiting for ts-cloud to
+ * install it.
+ */
+export declare function formatMissingManagedServicesError(missing: readonly string[], ownerSlug: string, host: string | undefined): string;

package/dist/drivers/shared/managed-services-probe.test.d.ts

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

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

@@ -32,6 +32,7 @@ export declare const PANTRY_PACKAGES: {
     readonly redis: 'redis.io';
     readonly memcached: 'memcached.org';
     readonly meilisearch: 'meilisearch.com';
+    readonly mail: 'github.com/mail-os/mail';
     readonly git: 'git-scm.com';
     readonly certbot: 'certbot.eff.org';
     readonly bun: 'bun.sh';

package/dist/drivers/shared/remote-failure.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Turn per-instance remote-execution results into ONE operator-facing error.
+ *
+ * Both drivers used to collapse a failed remote run to a fixed sentence —
+ * "One or more SSH deploy commands failed" — while the thing that explains the
+ * failure (the remote command's stderr) sat right there in `perInstance`. The
+ * operator was left with a deploy that had failed for no stated reason, and no
+ * flag, not even `--verbose`, would print it: nothing had kept it.
+ *
+ * The remote output is already redacted where it is captured (the deploy script
+ * embeds a here-document with the full runtime environment; see
+ * `formatSshFailure`), so this only has to decide what is worth showing.
+ */
+import type { RemoteDeployInstanceResult } from '@ts-cloud/core';
+/**
+ * Build the `error` for a {@link import('@ts-cloud/core').RemoteDeployResult}
+ * whose run did not fully succeed. `summary` is the one-line what-failed (e.g.
+ * "One or more SSH deploy commands failed"); the detail of each failing
+ * instance is appended beneath it.
+ */
+export declare function summarizeRemoteFailures(perInstance: readonly RemoteDeployInstanceResult[], summary: string): string;

package/dist/drivers/shared/remote-failure.test.d.ts

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