@stacksjs/ts-cloud 0.5.35 → 0.6.0

package/dist/deploy/dashboard-database.d.ts

@@ -35,4 +35,29 @@ export declare function listDatabases(config: CloudConfig, environment: Environm
 }>;
 export declare function createDatabase(config: CloudConfig, environment: EnvironmentType, name: string): Promise<DbRunResult>;
 export declare function createDatabaseUser(config: CloudConfig, environment: EnvironmentType, input: CreateUserInput): Promise<DbRunResult>;
+/** Where per-database dumps are written on the box. */
+export declare const DB_BACKUP_DIR = "/var/backups/ts-cloud/databases";
+/**
+ * Script that dumps a single database to a timestamped, gzipped file. The name
+ * is a validated SQL identifier (no shell metacharacters), so it is safe to
+ * embed directly. The timestamp is computed on the box.
+ */
+export declare function buildBackupScript(engine: DbEngine, name: string, destDir?: string): string[];
+/** Script that lists the most recent dumps (newest first). */
+export declare function buildListBackupsScript(destDir?: string): string[];
+export declare function parseBackups(output: string): Array<{
+    file: string;
+    database: string;
+}>;
+/** Dump a single database to a gzipped file on the box. */
+export declare function backupDatabase(config: CloudConfig, environment: EnvironmentType, name: string): Promise<DbRunResult & {
+    database: string;
+}>;
+/** List the per-database dumps present on the box. */
+export declare function listDatabaseBackups(config: CloudConfig, environment: EnvironmentType): Promise<DbRunResult & {
+    backups: Array<{
+        file: string;
+        database: string;
+    }>;
+}>;
 export {};

package/dist/deploy/dashboard-operations.d.ts

@@ -46,3 +46,10 @@ export interface RunOperationOptions {
     to?: string;
 }
 export declare function runDashboardOperation(config: CloudConfig, environment: EnvironmentType, operation: DashboardOperation, options?: RunOperationOptions): Promise<DashboardOperationResult>;
+/**
+ * Run an arbitrary shell command on the app box (Forge-style "run command" /
+ * recipe runner). The dashboard is behind Basic auth and the caller must type a
+ * confirmation, so this is an operator affordance, not an open endpoint. Output
+ * is bounded and errors are captured rather than thrown.
+ */
+export declare function runServerShellCommand(config: CloudConfig, environment: EnvironmentType, command: string): Promise<DashboardOperationResult>;

package/dist/deploy/firewall-config-editor.d.ts

@@ -0,0 +1,15 @@
+export declare function isValidPort(port: number): boolean;
+export interface FirewallPortsInput {
+    configText: string;
+    /** The desired extra ports (SSH/80/443 stripped, deduped, sorted). */
+    ports: number[];
+}
+/** Normalize a port list: integers in range, minus the always-open set, unique + sorted. */
+export declare function normalizePorts(ports: number[]): number[];
+export declare function addFirewallPort(configText: string, port: number, existing?: number[]): string;
+export declare function removeFirewallPort(configText: string, port: number, existing?: number[]): string;
+/**
+ * Rewrite `compute.firewall.allowedPorts` to exactly `ports`. Creates the
+ * `firewall` object and/or the `allowedPorts` array if missing.
+ */
+export declare function setFirewallPorts(input: FirewallPortsInput): string;

package/dist/deploy/firewall-config-editor.test.d.ts

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

package/dist/deploy/index.d.ts

@@ -10,3 +10,4 @@ export { buildFunctionEnv, type CodeSource, deployServerlessApp, type DeployServ
 export { buildAndPushServerlessImage, type BuildImageOptions, type BuiltImage, } from './serverless-image';
 export { type DashboardData, resolveDashboardData, } from './dashboard-data';
 export { dashboardActions, resolveDashboardAction, sanitizeCloudConfig, startLocalDashboardServer, type DashboardAction, type LocalDashboardServer, type LocalDashboardServerOptions, } from './local-dashboard-server';
+export { buildManagementDashboardArtifact, DASHBOARD_CREDENTIALS_FILE, ensureManagementDashboard, type EnsureDashboardLogger, MANAGEMENT_DASHBOARD_SITE, resolveDashboardAuth, type ResolvedDashboardAuth, resolveUiSource, } from './management-dashboard';

package/dist/deploy/management-dashboard.d.ts

@@ -5,11 +5,15 @@
  * Resolves the UI directory (the repo's local `packages/ui/`, else the prebuilt
  * UI that ships inside the installed package at `dist/ui`), derives a `dashboard.<apex>`
  * host, and injects it into `config.sites` as a server-static site. It is served
- * behind htpasswd ONLY when `TS_CLOUD_UI_PASSWORD` is set; when it is not, the
- * dashboard is served without auth (no password is invented).
+ * SECURE BY DEFAULT: the dashboard is served behind htpasswd on every deploy.
+ * The password is resolved as: `TS_CLOUD_UI_PASSWORD` when set, else a strong
+ * auto-generated one (persisted to `.ts-cloud/dashboard-credentials.json` so it
+ * stays stable across deploys and printed once in the deploy log). Serving the
+ * dashboard publicly is an explicit, deliberate opt-in via `TS_CLOUD_UI_PUBLIC`.
  *
  * Env:
- * - `TS_CLOUD_UI_PASSWORD`  htpasswd password (unset ⇒ no auth)
+ * - `TS_CLOUD_UI_PASSWORD`  htpasswd password (unset ⇒ auto-generated + saved)
+ * - `TS_CLOUD_UI_PUBLIC`    set truthy to serve WITHOUT auth (opt-out, insecure)
  * - `TS_CLOUD_UI_USERNAME`  htpasswd user (default `admin`)
  * - `TS_CLOUD_UI_DOMAIN`    explicit dashboard host (else `dashboard.<apex>`)
  * - `TS_CLOUD_UI_REALM`     browser auth realm
@@ -18,6 +22,25 @@
 import type { CloudConfig } from '@ts-cloud/core';
 /** Site key under which the management dashboard is auto-injected. */
 export declare const MANAGEMENT_DASHBOARD_SITE = "dashboard";
+/** Where an auto-generated dashboard password is persisted (per project checkout). */
+export declare const DASHBOARD_CREDENTIALS_FILE: string;
+export interface ResolvedDashboardAuth {
+    /** The htpasswd password, or undefined when serving publicly (opt-out). */
+    password?: string;
+    /** How the password was resolved: explicit env, generated+saved, or public. */
+    source: 'env' | 'generated' | 'public';
+}
+/**
+ * Resolve the dashboard's Basic-auth password (secure by default):
+ *  1. `TS_CLOUD_UI_PASSWORD` when set → use it verbatim.
+ *  2. `TS_CLOUD_UI_PUBLIC` truthy → serve with NO auth (deliberate opt-out).
+ *  3. Otherwise → reuse a previously-generated password from
+ *     `.ts-cloud/dashboard-credentials.json`, or generate + persist a new one.
+ *
+ * Persisting the generated password keeps htpasswd stable across deploys (so a
+ * saved credential keeps working) and lets the operator retrieve it locally.
+ */
+export declare function resolveDashboardAuth(cwd: string, username: string, logger: EnsureDashboardLogger): ResolvedDashboardAuth;
 export interface EnsureDashboardLogger {
     info: (msg: string) => void;
     warn: (msg: string) => void;

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

@@ -0,0 +1,150 @@
+/**
+ * Mutating serverless (Vapor-style) operations for the management cockpit:
+ * redeploy, rollback, maintenance mode, Aurora scaling, CloudFront asset
+ * invalidation, SQS queue purge, dead-letter-queue viewing + redrive, and
+ * Secrets Manager editing.
+ *
+ * The catalog (`buildServerlessOperations`) is derived purely from the cloud
+ * config + resolved dashboard data so it is trivially unit-testable; the runner
+ * dispatches each op to the existing serverless-app helpers (which perform the
+ * real AWS calls) and returns a structured result (never throws on a remote
+ * failure). DLQ + secrets are exposed as dedicated helpers because they carry
+ * their own payloads (messages / values) rather than a fixed confirm token.
+ */
+import type { CloudConfig, EnvironmentType } from '@ts-cloud/core';
+export type ServerlessOperationGroup = 'deploy' | 'maintenance' | 'assets' | 'database' | 'queue';
+export interface ServerlessOperationInput {
+    name: string;
+    label: string;
+    placeholder?: string;
+}
+export interface ServerlessOperation {
+    id: string;
+    label: string;
+    group: ServerlessOperationGroup;
+    target: string;
+    mutates: boolean;
+    /** Token the operator must type to run a mutating operation. */
+    confirm: string;
+    /** Destructive operations rendered with a danger affordance. */
+    danger?: boolean;
+    /** Extra operator-supplied inputs (e.g. Aurora min/max ACUs). */
+    inputs?: ServerlessOperationInput[];
+}
+export interface ServerlessOperationResult {
+    operation: string;
+    command?: string;
+    ok: boolean;
+    stdout?: string;
+    error?: string;
+}
+/**
+ * Build the serverless operation catalog from config + live data. Pure: every
+ * operation here is runnable by {@link runServerlessOperation}.
+ */
+export declare function buildServerlessOperations(config: CloudConfig, environment: EnvironmentType, data: Record<string, any>): ServerlessOperation[];
+export declare function resolveServerlessOperation(id: string, config: CloudConfig, environment: EnvironmentType, data: Record<string, any>): ServerlessOperation | undefined;
+export interface RunServerlessOperationOptions {
+    /** For db:scale — the requested Aurora min/max ACUs. */
+    min?: number;
+    max?: number;
+}
+/**
+ * Run a serverless operation over the live AWS environment. Returns a structured
+ * result; a remote failure is captured as `{ ok: false, error }` rather than
+ * thrown, so the cockpit always renders an outcome.
+ */
+export declare function runServerlessOperation(config: CloudConfig, environment: EnvironmentType, operation: ServerlessOperation, options?: RunServerlessOperationOptions): Promise<ServerlessOperationResult>;
+/** Run an arbitrary app command via the CLI function (Vapor-style command runner). */
+export declare function runServerlessCommand(config: CloudConfig, environment: EnvironmentType, command: string): Promise<ServerlessOperationResult>;
+export interface DlqMessage {
+    id: string;
+    receiptHandle: string;
+    body: string;
+}
+/** Peek at DLQ messages (visibility restored quickly so they aren't consumed). */
+export declare function listDlqMessages(config: CloudConfig, environment: EnvironmentType, max?: number): Promise<{
+    ok: boolean;
+    messages: DlqMessage[];
+    error?: string;
+}>;
+/**
+ * Redrive up to `max` messages from the DLQ back onto a source queue (receive →
+ * send → delete). `targetQueue` is a configured queue short-name; it defaults to
+ * the first resolved queue for the app.
+ */
+export declare function redriveDlq(config: CloudConfig, environment: EnvironmentType, opts?: {
+    max?: number;
+    targetQueue?: string;
+}): Promise<ServerlessOperationResult>;
+/** Purge every message from the DLQ (destructive). */
+export declare function purgeDlq(config: CloudConfig, environment: EnvironmentType): Promise<ServerlessOperationResult>;
+/** The Secrets Manager ids the app references (from `app.secrets`). */
+export declare function configuredSecretIds(config: CloudConfig, environment: EnvironmentType): Array<{
+    key: string;
+    secretId: string;
+}>;
+/**
+ * Set (create or update) a Secrets Manager value. The change takes effect on the
+ * next deploy (function env is injected at deploy time), so the caller should
+ * surface that redeploy hint.
+ */
+export declare function setServerlessSecret(config: CloudConfig, environment: EnvironmentType, secretId: string, value: string): Promise<ServerlessOperationResult>;
+/** Delete a Secrets Manager entry (scheduled deletion; recoverable for 7 days). */
+export declare function deleteServerlessSecret(config: CloudConfig, environment: EnvironmentType, secretId: string): Promise<ServerlessOperationResult>;
+/**
+ * Update a function's memory and/or timeout. `mode` is one of the app's function
+ * modes (http/queue/cli). Memory takes effect immediately; the change is also
+ * re-applied on the next deploy from config.
+ */
+export declare function updateFunctionConfig(config: CloudConfig, environment: EnvironmentType, mode: string, opts: {
+    memory?: number;
+    timeout?: number;
+}): Promise<ServerlessOperationResult>;
+export interface AlarmMetricPreset {
+    key: string;
+    label: string;
+    namespace: string;
+    metricName: string;
+    statistic: 'Sum' | 'Average' | 'Maximum' | 'Minimum';
+    comparison: string;
+    /** Function mode this metric attaches to (http/queue/cli), or undefined for account-wide. */
+    fnMode?: 'http' | 'queue' | 'cli';
+    unit: string;
+}
+/** The alarm metrics an operator can arm from the dashboard. */
+export declare const ALARM_PRESETS: AlarmMetricPreset[];
+export declare function resolveAlarmPreset(key: string): AlarmMetricPreset | undefined;
+/** List the alarms ts-cloud manages for this environment (name-prefixed). */
+export declare function listAlarms(config: CloudConfig, environment: EnvironmentType): Promise<{
+    ok: boolean;
+    alarms: any[];
+    presets: AlarmMetricPreset[];
+    error?: string;
+}>;
+/** Create (or update) an alarm from a preset + threshold. */
+export declare function createAlarm(config: CloudConfig, environment: EnvironmentType, presetKey: string, threshold: number): Promise<ServerlessOperationResult>;
+/** Delete an alarm by name (guarded to this project's prefix). */
+export declare function deleteAlarm(config: CloudConfig, environment: EnvironmentType, alarmName: string): Promise<ServerlessOperationResult>;
+export interface ShapedTrace {
+    id: string;
+    durationMs: number;
+    responseMs: number;
+    status: 'ok' | 'error' | 'fault' | 'throttle';
+    method: string;
+    url: string;
+    httpStatus: number;
+}
+/**
+ * List recent X-Ray trace summaries for the app's HTTP function (falling back to
+ * all traces in the window when the service filter returns nothing). Requires
+ * tracing to be enabled on the functions; returns an empty, ok:false result with
+ * a hint otherwise.
+ */
+export declare function listTraces(config: CloudConfig, environment: EnvironmentType, minutes?: number): Promise<{
+    ok: boolean;
+    traces: ShapedTrace[];
+    error?: string;
+}>;
+/** Enable, disable, or run-now the serverless scheduler. */
+export declare function controlScheduler(config: CloudConfig, environment: EnvironmentType, action: 'enable' | 'disable' | 'run'): Promise<ServerlessOperationResult>;

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

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

package/dist/deploy/site-config-editor.d.ts

@@ -49,4 +49,10 @@ export declare function renderSslValue(ssl: boolean | {
 }): string;
 export declare function renderStringValue(value: string): string;
 export declare function renderEnvValue(env: Record<string, string>): string;
+/** A validated hostname (letters, digits, dots, hyphens; at least one dot). */
+export declare function isValidHostname(value: string): boolean;
+/** Render a site's `aliases` array (additional nginx `server_name` hostnames). */
+export declare function renderAliasesValue(aliases: string[]): string;
+/** Render a site's `redirects` map (`from` path/host → `to` URL). Both are quoted strings. */
+export declare function renderRedirectsValue(redirects: Record<string, string>): string;
 export declare function renderSiteSnippet(input: Omit<AddSiteConfigInput, 'configText'>): string;

package/dist/deploy/ssh-config-editor.d.ts

@@ -20,3 +20,4 @@ export interface ManagedSshKey {
 export declare function addSshKeyToCloudConfig(input: AddSshKeyInput): string;
 export declare function removeSshKeyFromCloudConfig(input: RemoveSshKeyInput): string;
 export declare function describeSshKeys(keys?: SshKeyConfig[]): ManagedSshKey[];
+export declare function findMatching(text: string, start: number, open: string, close: string): number;

package/dist/deploy/terminal-session.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A persistent shell session for the dashboard's web terminal. Spawns an
+ * interactive shell on the host the dashboard runs on (in box mode that is the
+ * provisioned server, matching Forge's web SSH) and streams its output back
+ * through `onData`. Input is written to the shell's stdin.
+ *
+ * This is a line-oriented shell over pipes, not a full PTY: cwd and environment
+ * persist across commands and long-running output streams, but curses-style
+ * full-screen programs (vim, htop) are not supported. It is gated behind the
+ * dashboard's Basic auth like every other control surface.
+ */
+export interface TerminalSession {
+    /** Write raw input (typically a command line ending in \n) to the shell. */
+    write: (data: string) => void;
+    /** Terminate the shell and release the streams. */
+    close: () => void;
+}
+export interface TerminalSessionOptions {
+    shell?: string;
+    cwd?: string;
+    onExit?: (code: number | null) => void;
+}
+export declare function createTerminalSession(onData: (chunk: string) => void, options?: TerminalSessionOptions): TerminalSession;

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, 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 { deployStaticSite, deployStaticSiteFull, uploadStaticFiles, invalidateCache, deleteStaticSite, generateStaticSiteTemplate, deployStaticSiteWithExternalDns, deployStaticSiteWithExternalDnsFull, generateExternalDnsStaticSiteTemplate, deploySite, resolveSiteDeployTarget, resolveSiteKind, validateDeploymentConfig, buildAndPushServerlessImage, buildFunctionEnv, deployServerlessApp, infraEnvFromOutputs, redeployServerlessApp, rollbackServerlessApp, runRemoteCommand, setMaintenance, buildManagementDashboardArtifact, DASHBOARD_CREDENTIALS_FILE, ensureManagementDashboard, MANAGEMENT_DASHBOARD_SITE, resolveDashboardAuth, resolveUiSource, } from './deploy';
+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, generateUbuntuAppCloudInit, wrapCloudInitUserData, buildSiteDeployScript, buildStaticSiteDeployScript, resolveExecStart, deployAllComputeSites, deploySiteRelease, } from './drivers';
 export type { CreateCloudDriverOptions } from './drivers/factory';
 export { dashboardActions, resolveDashboardAction, sanitizeCloudConfig, startLocalDashboardServer, } from './deploy/local-dashboard-server';