@aria-cli/tools 1.0.10 → 1.0.12

package/dist-cjs/executors/deploy.d.ts

@@ -0,0 +1,169 @@
+/**
+ * @aria/tools - Deploy tool executor
+ *
+ * Deploys ARIA to a remote machine via SSH. Handles OS detection,
+ * Node.js installation, repo setup, keypair generation, TLS cert
+ * discovery/provisioning, firewall configuration, config writing,
+ * daemon startup, and health check.
+ */
+import type { ToolContext, ToolResult } from "../types.js";
+export interface DeployInput {
+    /** SSH target (e.g. "claude@10.0.0.1") */
+    target: string;
+    /** Git repo URL (default: current origin) */
+    repo_url?: string;
+    /** Branch to deploy (default: main) */
+    branch?: string;
+    /** Arion identity name (default: hostname of target) */
+    arion_name?: string;
+    /** Mesh coordination URL */
+    coordination_url?: string;
+    /** Path to SSH private key */
+    ssh_key_path?: string;
+    /** Git commit hash to checkout after clone (pins exact code version) */
+    commit_hash?: string;
+    /** Verify GPG signature on HEAD commit after checkout */
+    verify_signatures?: boolean;
+}
+export interface DeployOutput {
+    success: boolean;
+    host: string;
+    port: number | null;
+    fingerprint: string | null;
+    arionName: string;
+    tlsType: TlsType | null;
+}
+export type TlsType = "real-ca" | "letsencrypt" | "private-ca";
+export interface OSInfo {
+    os: "linux" | "darwin" | "windows" | "unknown";
+}
+export type LinuxDistro = "apt" | "dnf" | "apk";
+export type FirewallType = "ufw" | "iptables" | "firewalld" | "windows" | "none";
+export interface TlsDiscoveryResult {
+    found: boolean;
+    type?: TlsType;
+    cert?: string;
+    key?: string;
+}
+/**
+ * Detect OS type from `uname -s` output.
+ */
+export declare function detectOS(unameOutput: string): OSInfo;
+/**
+ * Detect Linux distribution from /etc/os-release content.
+ * Returns the package manager type to use.
+ */
+export declare function detectLinuxDistro(osReleaseContent: string): LinuxDistro;
+/**
+ * Get the shell command to install Node.js for a given OS and distro.
+ */
+export declare function getNodeInstallCommand(osInfo: OSInfo, distro: LinuxDistro): string;
+/**
+ * Generate firewall commands to open ARIA ports (443/tcp + 51820/udp).
+ */
+export declare function getFirewallCommands(firewallType: FirewallType): string;
+/**
+ * Parse TLS cert discovery output from the remote host.
+ * The discovery script outputs JSON: { found, type?, cert?, key? }
+ */
+export declare function discoverTlsCerts(sshOutput: string): TlsDiscoveryResult;
+/**
+ * Build the config JSON object for ~/.aria/config.json.
+ */
+export declare function buildConfigJson(params: {
+    arionName: string;
+    coordinationUrl?: string;
+    tlsCert?: string;
+    tlsKey?: string;
+}): Record<string, unknown>;
+/**
+ * Construct the health check URL for the deployed daemon.
+ */
+export declare function buildHealthCheckUrl(host: string, port?: number): string;
+/**
+ * Validate git repo URL — must be HTTPS with no shell metacharacters.
+ */
+export declare function validateRepoUrl(url: string): string | null;
+/**
+ * Validate branch name — alphanumeric, dots, slashes, hyphens, underscores.
+ * Rejects shell metacharacters and path traversal.
+ */
+export declare function validateBranch(branch: string): string | null;
+/**
+ * Validate arion name — alphanumeric, underscores, hyphens only.
+ */
+export declare function validateArionName(name: string): string | null;
+/**
+ * Validate SSH key path — reject traversal and shell metacharacters.
+ */
+export declare function validateSshKeyPath(keyPath: string): string | null;
+/**
+ * Validate git commit hash — must be 7-64 lowercase hex characters.
+ * Rejects non-hex, too-short, and shell injection attempts.
+ */
+export declare function validateCommitHash(hash: string): string | null;
+/**
+ * Pinned pnpm version — matches packageManager field in root package.json.
+ * Prevents unpinned `pnpm@latest` from pulling a compromised version.
+ */
+export declare const PINNED_PNPM_VERSION = "10.28.2";
+/**
+ * Represents a mutating deploy step that can be undone.
+ */
+export interface DeployStep {
+    /** Human-readable step name */
+    name: string;
+    /** Shell command to reverse this step (empty string = not reversible) */
+    undoCmd: string;
+}
+/**
+ * Get firewall undo commands to reverse port-opening rules.
+ */
+export declare function getFirewallUndoCommands(firewallType: FirewallType): string;
+/**
+ * Build rollback commands from recorded deploy steps.
+ * Returns commands in reverse order (last step undone first).
+ * Skips steps with empty undoCmd.
+ */
+export declare function buildRollbackCommands(steps: DeployStep[]): string[];
+/**
+ * Deep-merge two config objects. Preserves nested objects from existing config
+ * while applying updates. Does not mutate inputs.
+ */
+export declare function deepMergeConfig(existing: Record<string, unknown>, update: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Get chmod commands to restrict key and config file permissions to owner-only.
+ */
+export declare function getKeyPermissionCommands(): string;
+/**
+ * Execute a command on the remote host via SSH.
+ * Returns { stdout, stderr, exitCode }.
+ */
+export declare function sshExec(target: string, command: string, options?: {
+    sshKeyPath?: string;
+    timeoutMs?: number;
+    abortSignal?: AbortSignal;
+}): Promise<{
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}>;
+/**
+ * Deploy ARIA to a remote machine via SSH.
+ *
+ * Steps:
+ * 1. SSH connectivity check
+ * 2. OS detection (uname -s)
+ * 3. Linux distro detection (for package manager selection)
+ * 4. Install Node.js 20+ if missing
+ * 5. Enable corepack + pnpm
+ * 6. Clone or update repo
+ * 7. pnpm install && pnpm build
+ * 8. Generate Ed25519 signing keypair if not present
+ * 9. TLS cert discovery + optional provisioning
+ * 10. Firewall port opening (443/tcp + 51820/udp)
+ * 11. Write ~/.aria/config.json
+ * 12. Start daemon on port 443
+ * 13. Health check (curl endpoint)
+ */
+export declare function executeDeploy(input: DeployInput, ctx: ToolContext): Promise<ToolResult>;