@stacksjs/ts-cloud 0.12.10 → 0.12.12

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

@@ -0,0 +1,121 @@
+export type SshHostKeyPolicy = 'pin' | 'accept-new' | 'insecure';
+export interface SshTransportOptions {
+    user: string;
+    /** @default 22 */
+    port?: number;
+    /** Private key passed as `-i`. */
+    identityFile: string;
+    /**
+     * `'insecure'` disables host-key checking (the cloud drivers' behaviour).
+     * Otherwise the policy plus the known_hosts file it reads and writes.
+     */
+    hostKey: 'insecure' | {
+        policy: 'pin' | 'accept-new';
+        knownHostsFile: string;
+    };
+    /** @default 30 */
+    connectTimeoutSec?: number;
+    /**
+     * How a script is executed on the host once it arrives over stdin. Defaults
+     * to {@link remoteScriptRunner} without sudo; `exec` can pick the sudo
+     * variant per call.
+     */
+    runner?: string;
+}
+export interface SshExecOptions {
+    /**
+     * Run the script through `sudo -n`. Unset: the transport's configured
+     * runner. A deploy user that is not root needs it for everything except
+     * the preflight, which must run as the user to find out whether sudo works.
+     */
+    sudo?: boolean;
+}
+export interface SshHostKeyResult {
+    /** `SHA256:...`, empty when the key could not be learned (insecure policy, scan failed). */
+    fingerprint: string;
+    /** True when this call is what recorded the key. */
+    pinnedNow: boolean;
+}
+export interface SshTransport {
+    /** Run `script` on `host`; resolves with stdout, rejects with a redacted failure. */
+    exec(host: string, script: string, options?: SshExecOptions): Promise<string>;
+    /** Copy one local file to `remotePath` on `host`. */
+    scp(host: string, localPath: string, remotePath: string): Promise<void>;
+    /** Whether sshd on `host` accepts a connection right now. */
+    probe(host: string): Promise<boolean>;
+    /** Learn (and, when pinning, record) the host key before the first real command. */
+    ensureHostKey(host: string): Promise<SshHostKeyResult>;
+}
+export interface CommandResult {
+    code: number;
+    signal?: string | null;
+    stdout: string;
+    stderr: string;
+}
+/** Runs a command; `input`, when given, is piped to stdin. Injectable for tests. */
+export type CommandRunner = (command: string[], input?: string) => Promise<CommandResult>;
+export declare const runCommand: CommandRunner;
+/**
+ * Host-key options for a box the provider API identifies: never check, never
+ * remember. Byte-for-byte what the Hetzner driver passes.
+ */
+export declare const SSH_INSECURE_HOST_KEY_OPTS: readonly string[];
+/**
+ * Keepalive + connect timeout for every ssh/scp. Without these a connection
+ * that stalls mid-transfer (a flaky network, an sshd hiccup) hangs the deploy
+ * FOREVER. ServerAlive probes abort a silent connection after ~60s (15s x 4)
+ * so the transfer fails loudly (and, for scp, is retried) instead of wedging.
+ */
+export declare const SSH_KEEPALIVE_OPTS: readonly string[];
+/**
+ * The `ssh` arguments (everything after the binary, ending in `user@host`)
+ * for `options`. `extra` is spliced in before the destination so a caller can
+ * add a one-off `-o`. Pure, for tests.
+ */
+export declare function buildSshArgsFor(options: SshTransportOptions, host: string, extra?: string[]): string[];
+/** The `scp` arguments for copying `localPath` to `host:remotePath`. Pure, for tests. */
+export declare function buildScpArgsFor(options: SshTransportOptions, host: string, localPath: string, remotePath: string): string[];
+/** `SHA256:...` fingerprint of a base64 host key, as `ssh-keygen -l` prints it. */
+export declare function sshHostKeyFingerprint(key: string): string;
+export interface ScannedHostKey {
+    algorithm: string;
+    key: string;
+}
+/**
+ * Ask the host for its ed25519 key with `ssh-keyscan`. Bounded (`-T 10`) so an
+ * unreachable host fails in seconds rather than at the TCP timeout.
+ */
+export declare function scanHostKey(host: string, port?: number, run?: CommandRunner): Promise<ScannedHostKey>;
+/** The host field ssh looks up in known_hosts: `host` on port 22, `[host]:port` otherwise. */
+export declare function knownHostsToken(host: string, port?: number): string;
+/** The known_hosts entry recorded for `host` (one line, no trailing newline). */
+export declare function knownHostsLine(host: string, port: number, key: ScannedHostKey): string;
+/**
+ * The recorded key for `host`, or null when the file has no plain entry for
+ * it. Hashed entries (`|1|...`) cannot be matched and are ignored, which is
+ * fine: this transport only ever writes plain ones.
+ */
+export declare function findKnownHostKey(content: string, host: string, port?: number): ScannedHostKey | null;
+/** Where the ssh driver keeps the host keys it pinned: `<stateDir>/ssh/known_hosts`. */
+export declare function sshKnownHostsPath(cwd?: string): string;
+export interface SystemSshTransportDeps {
+    run?: CommandRunner;
+    scan?: typeof scanHostKey;
+    readKnownHosts?: (file: string) => Promise<string>;
+    appendKnownHosts?: (file: string, line: string) => Promise<void>;
+}
+/** {@link SshTransport} on the system `ssh`, `scp` and `ssh-keyscan` binaries. */
+export declare class SystemSshTransport implements SshTransport {
+    private readonly options;
+    private readonly run;
+    private readonly scan;
+    private readonly readKnownHosts;
+    private readonly appendKnownHosts;
+    constructor(options: SshTransportOptions, deps?: SystemSshTransportDeps);
+    /** The runner a script is fed to; see {@link SshExecOptions.sudo}. */
+    runnerFor(options?: SshExecOptions): string;
+    exec(host: string, script: string, options?: SshExecOptions): Promise<string>;
+    scp(host: string, localPath: string, remotePath: string): Promise<void>;
+    probe(host: string): Promise<boolean>;
+    ensureHostKey(host: string): Promise<SshHostKeyResult>;
+}

package/dist/drivers/ssh/bootstrap.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The bootstrap for a bring-your-own host.
+ *
+ * The recipe is the Hetzner driver's, composed the same way from the same
+ * builders (the rpx gateway, the machine provisioning, the Ubuntu bootstrap),
+ * so an adopted Pi and a cloud box end up running the same stack from the
+ * same code. What differs is the machine it lands on:
+ *
+ * - It may run MORE than once. cloud-init on a Pi has an upstream bug that
+ *   reruns modules on every boot, an operator may `cloud ssh:bootstrap` twice,
+ *   and a deploy calls the adopt on every run. So the whole script is guarded
+ *   by a version marker: once `/var/lib/ts-cloud/bootstrap.v<N>` exists, only
+ *   the gateway fragment is refreshed. Bumping {@link SSH_BOOTSTRAP_VERSION}
+ *   is how a changed recipe gets applied to hosts bootstrapped by an older one.
+ * - It may run before the clock is right. A Pi 5 has no battery-backed RTC,
+ *   and apt refuses Release files "from the future" while ACME refuses a
+ *   skewed clock outright. Time sync is awaited before anything touches apt.
+ * - It may run as a user that is not root. The scripts arrive through the
+ *   sudo runner, so they ARE root, but the deploy user still has to be able
+ *   to scp into the artifact and staging directories, and the operator keys
+ *   belong in that user's `authorized_keys`, not root's.
+ * - It may run on a small SD card. The raspberry-pi profile halves the
+ *   swapfile and bounds the journal.
+ */
+import type { CloudConfig, EnvironmentType } from '@ts-cloud/core';
+import type { SshLanConfig, SshProfile } from './config';
+import type { SshPreflightFacts } from './preflight';
+/** Bump when the recipe changes in a way an already-bootstrapped host must pick up. */
+export declare const SSH_BOOTSTRAP_VERSION = 1;
+/** Where the bootstrap records that it ran. */
+export declare const SSH_BOOTSTRAP_MARKER_DIR = "/var/lib/ts-cloud";
+export declare function sshBootstrapMarkerPath(version?: number): string;
+/** Swap the raspberry-pi profile provisions when `compute.swapGb` is unset. */
+export declare const RASPBERRY_PI_DEFAULT_SWAP_GB = 1;
+export interface SshBootstrapOptions {
+    config: CloudConfig;
+    environment: EnvironmentType;
+    profile: SshProfile;
+    /**
+     * Preflight facts, when the host has been probed. `arch` gates x86_64-only
+     * services; `lanIp` becomes the LAN certificate's iPAddress SAN.
+     */
+    facts?: Pick<SshPreflightFacts, 'arch'> & Partial<Pick<SshPreflightFacts, 'lanIp'>>;
+    /**
+     * The non-root deploy user, when there is one. Makes the artifact and
+     * staging directories group-writable for it and manages its
+     * `authorized_keys` rather than root's.
+     */
+    sudoUser?: string;
+    /** LAN settings; recorded in the script header and wired into the gateway's local CA. */
+    lan?: SshLanConfig;
+    /**
+     * The box's LAN address, when the caller knows one that is not in `facts`
+     * (the configured ssh host, when that host is an IP literal). Wins over
+     * `facts.lanIp`. Never guessed: an address absent here is simply left off
+     * the certificate.
+     */
+    lanIp?: string;
+}
+/**
+ * Refuse a config that asks for something this host's architecture cannot
+ * run. Vitess publishes x86_64 release tarballs only, so on an arm64 host the
+ * provision would fail minutes in on a download URL; say so before contact.
+ * The raspberry-pi profile is arm64 by definition, so it needs no facts.
+ */
+export declare function assertArchSupported(config: CloudConfig, profile: SshProfile, arch?: string): void;
+/**
+ * Build the bootstrap script for an adopted host. See the module comment for
+ * what makes it different from the cloud drivers' first-boot script.
+ */
+export declare function buildSshBootstrapScript(options: SshBootstrapOptions): string;

package/dist/drivers/ssh/config.d.ts

@@ -0,0 +1,94 @@
+/**
+ * The single place ssh-provider settings are resolved.
+ *
+ * Same shape and the same precedence as `../hetzner/config`, for the same
+ * reason: every value can come from several sources, and resolving them
+ * ad-hoc at each call site is how the driver, a CLI command and the dashboard
+ * end up disagreeing about which host a deploy goes to.
+ *
+ *   1. an explicit argument (a driver option or CLI flag: the caller means it)
+ *   2. `cloud.config.ts` -> `ssh.*` (checked into the repo, reviewable)
+ *   3. environment (`TS_CLOUD_SSH_*`) for per-machine overrides
+ *   4. the documented default in {@link SSH_DEFAULTS}
+ *
+ * Config beats environment deliberately: a value written in `cloud.config.ts`
+ * is the reviewed intent for the project, and a stray shell export must not
+ * silently redirect a deploy to another machine.
+ */
+import type { CloudConfig, SshConfig, SshHostConfig } from '@ts-cloud/core';
+export type SshProfile = NonNullable<SshConfig['profile']>;
+export type SshHostKeyPolicyName = NonNullable<SshConfig['hostKey']>;
+export type SshLanConfig = NonNullable<SshConfig['lan']>;
+/** The documented defaults. These are the only place an ssh default lives. */
+export declare const SSH_DEFAULTS: {
+    readonly user: 'root';
+    readonly port: 22;
+    readonly privateKeyPath: '~/.ssh/id_ed25519';
+    readonly hostKey: 'pin';
+    readonly profile: 'generic';
+    readonly publicIp: 'auto';
+};
+/**
+ * The hosts to deploy to: explicit, else `ssh.hosts`, else the single host
+ * named by `TS_CLOUD_SSH_HOST`. Throws when none is configured, because a
+ * driver without a host has nothing it can honestly do.
+ */
+export declare function resolveSshHosts(config?: CloudConfig, explicit?: SshHostConfig[]): SshHostConfig[];
+/** SSH user for deploy commands. Per host: the value lives on the `ssh.hosts[]` entry. */
+export declare function resolveSshUser(host?: SshHostConfig, explicit?: string): string;
+/** SSH port. A non-numeric or out-of-range value is a configuration error, not port 22. */
+export declare function resolveSshPort(host?: SshHostConfig, explicit?: number): number;
+/** Absolute path to the SSH private key used for deploy commands. */
+export declare function resolveSshPrivateKeyPath(host?: SshHostConfig, explicit?: string): string;
+/** How the host key is trusted; see `SshConfig.hostKey`. */
+export declare function resolveSshHostKeyPolicy(config?: CloudConfig, explicit?: string): SshHostKeyPolicyName;
+/**
+ * Whether remote scripts run through `sudo -n`. Explicit, else `ssh.sudo`,
+ * else on for any user that is not root: a deploy user that cannot become
+ * root cannot install the stack.
+ */
+export declare function resolveSshSudo(config?: CloudConfig, user?: string, explicit?: boolean): boolean;
+/** Host profile; see `SshConfig.profile`. */
+export declare function resolveSshProfile(config?: CloudConfig, explicit?: string): SshProfile;
+/** The public IP DNS should point at: `'auto'` or a literal address. */
+export declare function resolveSshPublicIp(config?: CloudConfig, explicit?: string): string;
+/**
+ * LAN access settings, or `undefined` when the project configured none.
+ *
+ * This used to answer `{}` for "unset", which reads as a LAN with defaults
+ * once anything acts on it: with the gateway now wired to `lan`, that sentinel
+ * would give every adopted host a local certificate authority for
+ * `<slug>.local` that nobody asked for. Absent has to be absent.
+ */
+export declare function resolveSshLan(config?: CloudConfig, explicit?: SshLanConfig): SshLanConfig | undefined;
+/** One host with every per-host value resolved. */
+export interface ResolvedSshHost {
+    host: string;
+    user: string;
+    port: number;
+    privateKeyPath: string;
+    role: 'app';
+}
+/** Every resolved ssh setting, for a driver or a diagnostic to read at once. */
+export interface ResolvedSshSettings {
+    hosts: ResolvedSshHost[];
+    hostKey: SshHostKeyPolicyName;
+    sudo: boolean;
+    profile: SshProfile;
+    publicIp: string;
+    /** LAN access settings, or `undefined` when this project configured none. */
+    lan?: SshLanConfig;
+}
+export interface SshOverrides {
+    hosts?: SshHostConfig[];
+    user?: string;
+    port?: number;
+    privateKeyPath?: string;
+    hostKey?: string;
+    sudo?: boolean;
+    profile?: string;
+    publicIp?: string;
+    lan?: SshLanConfig;
+}
+/** Resolve the full ssh settings for `config`, applying `overrides` first. */
+export declare function resolveSshSettings(config?: CloudConfig, overrides?: SshOverrides): ResolvedSshSettings;

package/dist/drivers/ssh/config.test.d.ts

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

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

@@ -0,0 +1,107 @@
+/**
+ * The ssh compute driver: deploy to a Linux host you already own.
+ *
+ * Where the cloud drivers CREATE a box and then deploy to it, this one ADOPTS
+ * one. `provisionComputeInfrastructure` therefore means: trust the host key,
+ * wait for sshd, run the preflight and refuse a host that cannot work, wait
+ * out a cloud-init first boot if one is still going, run the bootstrap (which
+ * is idempotent, so a deploy can call this every time), and record what was
+ * done. `destroyCompute` forgets the host and touches nothing on it.
+ *
+ * Everything after adoption is the Hetzner driver's SSH deploy path verbatim
+ * (the content-addressed artifact cache, the nonce-scoped staging upload, the
+ * per-target deploy with redacted failures), on an injectable transport.
+ */
+import type { CloudConfig, CloudDriver, ComputeStackOutputs, ComputeTarget, FindComputeTargetsOptions, ProvisionComputeOptions, RemoteDeployResult, RunRemoteDeployOptions, SshHostConfig, UploadReleaseOptions, UploadReleaseResult } from '@ts-cloud/core';
+import type { ValidationFinding } from '../../fleet';
+import type { SshTransport } from '../shared/ssh-transport';
+import type { ResolvedSshSettings, SshLanConfig } from './config';
+import type { SshPreflightFacts } from './preflight';
+/** Where releases are staged and cached on the host; the same paths as every other SSH-style driver. */
+export declare const SSH_DEPLOY_STORAGE_PATH = "/var/ts-cloud/staging";
+/** Set to `1` to skip the bootstrap when local state says the current version already ran. */
+export declare const SSH_SKIP_BOOTSTRAP_ENV = "TS_CLOUD_SSH_SKIP_BOOTSTRAP";
+export interface SshDriverOptions {
+    hosts?: SshHostConfig[];
+    user?: string;
+    port?: number;
+    privateKeyPath?: string;
+    hostKey?: string;
+    sudo?: boolean;
+    profile?: string;
+    publicIp?: string;
+    lan?: SshLanConfig;
+    /** Injected transport (tests, or a caller with its own SSH stack). */
+    transport?: SshTransport;
+    /** Tunables for the SSH-readiness / cloud-init wait loops; tiny in tests. */
+    bootWait?: {
+        /** @default 5000 */
+        sshIntervalMs?: number;
+        /** @default 300000 */
+        sshTimeoutMs?: number;
+        /** @default 5000 */
+        cloudInitIntervalMs?: number;
+        /** @default 600000 */
+        cloudInitTimeoutMs?: number;
+    };
+    /** Project root: where state and the pinned host keys live. @default process.cwd() */
+    cwd?: string;
+}
+/**
+ * The config problems the ssh provider refuses, and the keys it merely ignores.
+ *
+ * Throws for anything that would make the deploy mean something other than
+ * what the config says; returns a warning per sizing key that has no effect
+ * here, so an operator who copied a Hetzner config learns which lines are
+ * inert instead of wondering why the box did not grow.
+ */
+export declare function assertSshComputeConfig(config: CloudConfig, settings: Pick<ResolvedSshSettings, 'hosts' | 'profile'>): string[];
+export declare class SshDriver implements CloudDriver {
+    readonly name: 'ssh';
+    readonly usesCloudFormation = false;
+    private readonly settings;
+    private readonly cwd;
+    private readonly bootWait;
+    private transportInstance?;
+    constructor(options?: SshDriverOptions);
+    /** The one host this driver deploys to. */
+    private get host();
+    private get transport();
+    /** Run a script on the host as root (through sudo when the user is not root). */
+    private exec;
+    findComputeTargets(options: FindComputeTargetsOptions): Promise<ComputeTarget[]>;
+    getComputeOutputs(): Promise<ComputeStackOutputs>;
+    uploadRelease(options: UploadReleaseOptions): Promise<UploadReleaseResult>;
+    runRemoteDeploy(options: RunRemoteDeployOptions): Promise<RemoteDeployResult>;
+    /** The configured host name or address, for a caller that wants to print it. */
+    targetHost(): string;
+    /** Learn (and, when pinning, record) the host key. The adopt does this first; the preflight command too. */
+    ensureHostKey(host?: string): Promise<{
+        fingerprint: string;
+        pinnedNow: boolean;
+    }>;
+    /**
+     * Probe the host as the deploy user and judge the result. Public so the
+     * `ssh:preflight` command and the adopt share one definition of "ready".
+     */
+    preflight(host?: string): Promise<{
+        facts: SshPreflightFacts;
+        findings: ValidationFinding[];
+    }>;
+    /**
+     * Adopt the host: pin, wait, check, bootstrap, record. Idempotent, and
+     * cheap after the first run because the bootstrap guards itself.
+     */
+    provisionComputeInfrastructure(options: ProvisionComputeOptions): Promise<ComputeStackOutputs>;
+    /**
+     * Forget the host. Nothing on it is removed: it was never ts-cloud's to
+     * remove, and a teardown that wiped an operator's Pi would be a much worse
+     * surprise than one that left a gateway running.
+     */
+    destroyCompute(options: ProvisionComputeOptions): Promise<{
+        destroyed: string[];
+    }>;
+    private sleep;
+    private waitForSshReady;
+    private waitForCloudInit;
+}

package/dist/drivers/ssh/factory-wiring.test.d.ts

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

package/dist/drivers/ssh/first-boot.d.ts

@@ -0,0 +1,38 @@
+export type FirstBootOs = 'raspberry-pi-os' | 'ubuntu';
+export interface FirstBootWifi {
+    ssid: string;
+    passphrase: string;
+    /** ISO 3166-1 alpha-2 regulatory domain, e.g. `DE`. Required: without it the radio stays off. */
+    country: string;
+}
+export interface FirstBootIdentity {
+    /** The hostname; also the mDNS name (`<hostname>.local`) the instructions point at. */
+    hostname: string;
+    /** The deploy user cloud-init creates, with passwordless sudo and the key below. */
+    user: string;
+    /** One public key line (`ssh-ed25519 AAAA... comment`). */
+    publicKey: string;
+    /** IANA timezone, e.g. `Europe/Berlin`. */
+    timezone?: string;
+    /** System locale, e.g. `en_US.UTF-8`. */
+    locale?: string;
+    wifi?: FirstBootWifi;
+}
+export interface FirstBootBundle {
+    /** File name (as it must appear on the boot partition) to content. */
+    files: Record<string, string>;
+    /** What to do with the files, for the terminal. */
+    instructions: string;
+}
+export interface FirstBootOptions {
+    os: FirstBootOs;
+}
+/** Where the bootstrap is written on the host; the same place the adopt flow's marker lives beside. */
+export declare const FIRST_BOOT_SCRIPT_PATH = "/var/lib/ts-cloud/bootstrap.sh";
+/** The boot partition label each OS uses, so the instructions can name the volume. */
+export declare const BOOT_PARTITION_LABEL: Record<FirstBootOs, string>;
+/**
+ * Build the three cloud-init files for `identity`, embedding `bootstrapScript`
+ * (from `buildSshBootstrapScript`) so it runs at the end of the first boot.
+ */
+export declare function buildCloudInitFirstBoot(identity: FirstBootIdentity, bootstrapScript: string, options: FirstBootOptions): FirstBootBundle;

package/dist/drivers/ssh/preflight.d.ts

@@ -0,0 +1,76 @@
+/**
+ * What ts-cloud checks about a bring-your-own host before touching it.
+ *
+ * The cloud drivers never need this: they chose the image, the size and the
+ * region, so they know what they are logging into. An adopted host is
+ * whatever the operator installed, and the bootstrap's failure modes on the
+ * wrong machine are slow and misleading (an apt run that never finishes on
+ * an unsynced clock, a 404 from an x86_64-only download on an ARM board).
+ * One probe, run as the deploy user, answers every question the bootstrap
+ * would otherwise discover the hard way.
+ */
+import type { ValidationFinding } from '../../fleet';
+import type { SshProfile } from './config';
+/** The facts the preflight script reports, as JSON on its last line. */
+export interface SshPreflightFacts {
+    /** `PRETTY_NAME` from /etc/os-release. */
+    os: string;
+    /** `ID` from /etc/os-release, e.g. `debian`, `ubuntu`, `raspbian`. */
+    osId: string;
+    /** `ID_LIKE` from /etc/os-release, e.g. `debian` on Ubuntu. */
+    osIdLike: string;
+    /** `VERSION_ID` from /etc/os-release, e.g. `13`, `24.04`. */
+    osVersionId: string;
+    /** `uname -m`: `aarch64`, `x86_64`, `armv7l`, ... */
+    arch: string;
+    cpuCores: number;
+    memoryBytes: number;
+    diskBytes: number;
+    diskFreeBytes: number;
+    dnsOk: boolean;
+    /** Whether the `cloud-init` binary exists on the host. */
+    cloudInitPresent: boolean;
+    /** First line of `cloud-init status`, empty when absent. */
+    cloudInitStatus: string;
+    /** `timedatectl` reports the clock as NTP-synchronised. */
+    timeSynced: boolean;
+    /** An HTTPS request to github.com succeeded (downloads will work). */
+    httpsOk: boolean;
+    /** `sudo -n true` succeeded for the deploy user. */
+    sudoOk: boolean;
+    /** `getconf LONG_BIT`: 64 on every supported host. */
+    kernelBits: number;
+    /** `/proc/device-tree/model`, e.g. `Raspberry Pi 5 Model B Rev 1.0`; empty elsewhere. */
+    piModel: string;
+    /** First address from `hostname -I`. */
+    lanIp: string;
+    tools: {
+        curl: boolean;
+        tar: boolean;
+    };
+    privilege: 'sudo' | 'user';
+}
+/**
+ * The probe. Runs as the deploy user WITHOUT sudo, on purpose: `sudoOk` is a
+ * question, and a script that already needed sudo to run could not ask it.
+ * Every command tolerates absence (a `false`, a `0`, an empty string) so the
+ * JSON is always complete and the findings, not a shell error, say what is
+ * missing. The last line of stdout is the JSON document.
+ */
+export declare const SSH_PREFLIGHT_SCRIPT: string;
+/** Parse the probe's stdout: the last non-empty line is the JSON document. */
+export declare function parsePreflightFacts(output: string): SshPreflightFacts;
+export interface PreflightContext {
+    /** The deploy user; root needs no sudo. */
+    user: string;
+    profile: SshProfile;
+}
+/**
+ * Turn facts into findings. An `error` finding stops the adopt; a `warning`
+ * is printed and the adopt continues; `info` is context worth showing.
+ */
+export declare function evaluatePreflight(facts: SshPreflightFacts, context: PreflightContext): ValidationFinding[];
+/** True when any finding is an error. */
+export declare function preflightFailed(findings: readonly ValidationFinding[]): boolean;
+/** A plain-text table of findings, one per line, for a terminal or an error message. */
+export declare function formatPreflightFindings(findings: readonly ValidationFinding[]): string;

package/dist/index.d.ts

@@ -39,8 +39,9 @@ export { collectServerDnsDomains, hostAcceptsIpv6, IPV6_EXCLUDED_HOST_LABELS, no
 export type { AddressRecordReport } from './deploy/server-dns';
 export * from './cdn';
 export type { EnsureDashboardLogger, ResolvedDashboardAuth, 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, normalizeSshPublicKey, ensureFirewall, ensureServer, ensureSshKey, serverPublicIpv4, sshExec, sshExecOrThrow, scpUpload, waitForSsh, waitForCloudInit, buildSshArgs, generateUbuntuAppCloudInit, wrapCloudInitUserData, buildHostCleanupScript, buildSiteDeployScript, buildStaticSiteDeployScript, resolveExecStart, deployAllComputeSites, deploySiteRelease, reloadRpxGateway, renewRpxCertificates, gatewayHostnames, hasAutoWwwVariant, } from './drivers';
+export { createCloudDriver, CloudDriverFactory, cloudDrivers, AwsDriver, HetznerDriver, SshDriver, SystemSshTransport, resolveSshSettings, buildSshBootstrapScript, SSH_BOOTSTRAP_VERSION, evaluatePreflight, formatPreflightFindings, parsePreflightFacts, preflightFailed, SSH_PREFLIGHT_SCRIPT, buildCloudInitFirstBoot, driverStatePath, readDriverState, writeDriverState, HetznerClient, resolveHetznerApiToken, normalizeSshPublicKey, ensureFirewall, ensureServer, ensureSshKey, serverPublicIpv4, sshExec, sshExecOrThrow, scpUpload, waitForSsh, waitForCloudInit, buildSshArgs, generateUbuntuAppCloudInit, wrapCloudInitUserData, buildHostCleanupScript, buildSiteDeployScript, buildStaticSiteDeployScript, resolveExecStart, deployAllComputeSites, deploySiteRelease, reloadRpxGateway, renewRpxCertificates, gatewayHostnames, hasAutoWwwVariant, } from './drivers';
 export type { CreateCloudDriverOptions } from './drivers/factory';
+export type { DriverState, FirstBootBundle, FirstBootIdentity, FirstBootOs, ResolvedSshSettings, SshDriverOptions, SshDriverState, SshPreflightFacts, SshTransport, SshTransportOptions, } from './drivers';
 export { dashboardActions, resolveDashboardAction, sanitizeCloudConfig, startLocalDashboardServer, } from './deploy/local-dashboard-server';
 export type { DashboardAction, LocalDashboardServer, LocalDashboardServerOptions, } from './deploy/local-dashboard-server';
 export { createDnsProvider, detectDnsProvider, DnsProviderFactory, dnsProviders, PorkbunProvider, GoDaddyProvider, Route53Provider, CloudflareProvider, policyTag, qualifyName, reconcileDeclaredRecords, resolveDeclaredRecords, UnifiedDnsValidator, createPorkbunValidator, createGoDaddyValidator, createRoute53Validator, } from './dns';