@stacksjs/ts-cloud 0.12.9 → 0.12.11

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

@@ -0,0 +1,86 @@
+/**
+ * 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; empty when unset. */
+export declare function resolveSshLan(config?: CloudConfig, explicit?: SshLanConfig): SshLanConfig;
+/** 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: 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

@@ -27,7 +27,7 @@ export * from './generators';
 export { validateTemplate, validateTemplateSize, validateResourceLimits } from './validation';
 export type { ValidationError as TemplateValidationError, ValidationResult as TemplateValidationResult, } from './validation';
 export { AWSClient, CloudFormationClient, CloudFormationClient as AWSCloudFormationClient, CloudFrontClient, CloudFrontClient as AWSCloudFrontClient, EC2Client, S3Client, Route53Client, Route53DomainsClient, ACMClient, ACMDnsValidator, ECRClient, ECSClient, STSClient, SSMClient, SecretsManagerClient, SESClient, EmailClient, SNSClient, SQSClient, LambdaClient, CloudWatchLogsClient, ConnectClient, ELBv2Client, RDSClient, DynamoDBClient, OpenSearchClient, TranscribeClient, BedrockClient, BedrockRuntimeClient, ComprehendClient, RekognitionClient, TextractClient, PollyClient, TranslateClient, PersonalizeClient, KendraClient, EventBridgeClient, ElastiCacheClient, SchedulerClient, IAMClient, ApplicationAutoScalingClient, SmsClient, VoiceClient, SupportClient, EFSClient, setupSmsInfrastructure, getSmsInfrastructureStatus, createSmsInfrastructure, SmsVoiceClient, } from './aws';
-export type { SmsSetupConfig, SmsSetupResult, OriginationPhoneNumber, DescribePhoneNumbersParams, DescribePhoneNumbersResult, } from './aws';
+export type { SmsSetupConfig, SmsSetupResult, OriginationPhoneNumber, DescribePhoneNumbersParams, DescribePhoneNumbersResult, SandboxPhone, AddSandboxPhoneResult, VerifySandboxPhoneResult, } from './aws';
 export type { AWSRequestOptions, AWSClientConfig, AWSError, AWSCredentials as AWSClientCredentials, StackParameter, StackTag, CreateStackOptions, UpdateStackOptions, DescribeStacksOptions, StackEvent, Stack, InvalidationOptions, Distribution, S3SyncOptions, S3CopyOptions, S3ListOptions, S3Object, CertificateDetail, Certificate as ELBv2Certificate, RekognitionS3Object, RekognitionBoundingBox, TextractS3Object, TextractBoundingBox, CountryCode, ContactType, ContactDetail, KendraCreateDataSourceCommandInput, KendraCreateDataSourceCommandOutput, KendraListDataSourcesCommandInput, KendraListDataSourcesCommandOutput, InvokeModelCommandInput, InvokeModelCommandOutput, InvokeModelWithResponseStreamCommandInput, InvokeModelWithResponseStreamCommandOutput, CreateModelCustomizationJobCommandInput, CreateModelCustomizationJobCommandOutput, GetModelCustomizationJobCommandInput, GetModelCustomizationJobCommandOutput, ListFoundationModelsCommandInput, ListFoundationModelsCommandOutput, AttributeValue as DynamoDBAttributeValue, KeySchemaElement, AttributeDefinition as DynamoDBAttributeDefinition, } from './aws';
 export { createObjectStorageClient, providerEndpoint, resolveObjectStorage } from './object-storage';
 export type { ObjectStorageConfig, ObjectStorageCredentials, ObjectStorageProvider, ResolvedObjectStorage, } from './object-storage';
@@ -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';