hostfn 0.1.1 → 0.1.2

package/_conduct/specs/1.v0.spec.md

@@ -1,1041 +0,0 @@
-# Specification: hostfn - Universal Application Deployment CLI
-
-**Spec ID:** 1  
-**Version:** v0  
-**Created:** 2025-11-14  
-**Status:** Draft  
-**LOE:** Large (8-12 hours)  
-**Initial Release:** Node.js support  
-**Future:** Multi-language/runtime support
-
----
-
-## Overview
-
-**hostfn** is a zero-config, cloud-agnostic deployment CLI for server applications. It abstracts away the complexity of server provisioning, SSH configuration, process management, reverse proxy setup, and continuous deployments—allowing developers to deploy any application to any VPS with a single command.
-
-**Initial Release (v1.0):** Full Node.js support with PM2 process management  
-**Future Releases:** Python, Go, Ruby, Rust, PHP, and other languages/runtimes
-
-### Philosophy
-
-- **Zero Config, Smart Defaults:** Works out-of-the-box by detecting project structure
-- **Cloud Agnostic:** Works on any Linux VPS (Ubuntu, Debian, Amazon Linux, CentOS, etc.)
-- **Local & CI/CD:** Single CLI for both local and automated deployments
-- **Language Agnostic Architecture:** Pluggable runtime system for any language/framework
-- **Production Ready:** Built-in health checks, rollbacks, zero-downtime deploys
-
----
-
-## Problem Statement
-
-Current deployment options fall into two extremes:
-
-1. **Platform-as-a-Service (Vercel, Railway, Fly.io):**
-   - ✅ Simple, one-command deploys
-   - ❌ Vendor lock-in, limited control, expensive at scale
-   - ❌ Can't use existing VPS infrastructure
-
-2. **Manual VPS Deployment:**
-   - ✅ Full control, cost-effective
-   - ❌ Complex bash scripts, manual SSH setup
-   - ❌ Not CI/CD friendly, hard to maintain
-
-**hostfn bridges this gap:** PaaS-like simplicity with VPS control and economics.
-
----
-
-## Target Users
-
-1. **Solo Developers:** Need quick deploys without DevOps complexity
-2. **Startups:** Want to use affordable VPS ($5-20/mo) instead of expensive PaaS
-3. **Teams:** Need consistent deployment process across projects and languages
-4. **Side Projects:** Quick deployment for hackathons, MVPs, experiments
-
-## Language/Runtime Support
-
-### V1.0 (Initial Release) - Node.js
-- ✅ Full support for Node.js applications
-- ✅ PM2 process management
-- ✅ Framework detection (Express, Hono, Next.js, Fastify, etc.)
-- ✅ npm/yarn/pnpm package managers
-- ✅ Built-in health checks for HTTP services
-
-### Future Releases - Multi-Language Support
-- 🔮 **Python:** Flask, FastAPI, Django (systemd/gunicorn/uvicorn)
-- 🔮 **Go:** Compiled binaries (systemd service)
-- 🔮 **Ruby:** Rails, Sinatra (systemd/puma)
-- 🔮 **Rust:** Compiled binaries (systemd service)
-- 🔮 **PHP:** Laravel, Symfony (php-fpm + Nginx)
-- 🔮 **Java/Kotlin:** Spring Boot (systemd service)
-- 🔮 **Docker:** Multi-runtime via containers
-
-**Architecture Design:** The CLI is built with a pluggable runtime system, making it straightforward to add new language support by implementing runtime adapters.
-
----
-
-## Core Features
-
-### 1. Server Provisioning (`hostfn server setup`)
-
-**Command:**
-```bash
-hostfn server setup <user@host> [--env production]
-```
-
-**What it does:**
-- Auto-detects OS (Ubuntu/Debian/Amazon Linux/CentOS)
-- Installs Node.js via nvm (configurable version)
-- Installs PM2 process manager globally
-- Configures Nginx as reverse proxy
-- Sets up firewall (UFW or firewalld)
-- Optionally installs Redis
-- Creates deployment directories
-- Configures PM2 to auto-start on reboot
-- Generates deployment keys for CI/CD
-
-**Example:**
-```bash
-# Setup production server
-hostfn server setup ubuntu@123.45.67.89 --env production --node-version 18
-
-# Setup staging on same server
-hostfn server setup ubuntu@123.45.67.89 --env staging --port 3001
-```
-
-**Output:**
-```
-✅ Server setup complete!
-   - Node.js v18.19.0 installed
-   - PM2 v5.3.0 ready
-   - Nginx configured (port 80 → 3000)
-   - Firewall enabled (22, 80, 443)
-   
-🔑 Add this to CI/CD secrets:
-   DEPLOY_HOST=ubuntu@123.45.67.89
-   DEPLOY_KEY=<generated-ssh-key>
-```
-
----
-
-### 2. Project Initialization (`hostfn init`)
-
-**Command:**
-```bash
-hostfn init
-```
-
-**What it does:**
-- Auto-detects project type from `package.json`
-- Creates `hostfn.config.json` with smart defaults
-- Prompts for missing configuration
-- Sets up deployment scripts
-- Configures environment variable templates
-
-**Auto-Detection Logic:**
-- Checks `package.json` for framework dependencies
-- Identifies build/start commands
-- Detects ports from code or env files
-- Determines if monorepo (workspace packages)
-
-**Example Configuration Generated:**
-```json
-{
-  "name": "my-app",
-  "runtime": "node",
-  "version": "18",
-  "environments": {
-    "production": {
-      "server": "ubuntu@prod-server.com",
-      "port": 3000,
-      "instances": "max",
-      "domain": "api.example.com"
-    },
-    "staging": {
-      "server": "ubuntu@staging.example.com",
-      "port": 3001,
-      "instances": 2
-    }
-  },
-  "build": {
-    "command": "npm run build",
-    "directory": "dist",
-    "node_modules": "production"
-  },
-  "start": {
-    "command": "npm start",
-    "entry": "dist/index.js"
-  },
-  "health": {
-    "path": "/health",
-    "timeout": 60,
-    "retries": 10
-  },
-  "env": {
-    "required": ["DATABASE_URL", "JWT_SECRET"],
-    "optional": ["REDIS_URL", "EMAIL_PROVIDER"]
-  }
-}
-```
-
----
-
-### 3. Local Deployment (`hostfn deploy`)
-
-**Command:**
-```bash
-hostfn deploy [environment]
-```
-
-**What it does:**
-1. **Pre-flight checks:**
-   - Validates `hostfn.config.json`
-   - Checks SSH connectivity
-   - Verifies required env vars exist on server
-   
-2. **File transfer:**
-   - Syncs source code via rsync (excludes node_modules, .git, etc.)
-   - Syncs monorepo dependencies if detected
-   
-3. **Remote build:**
-   - Runs `npm ci --production` on server
-   - Executes build command
-   - Validates build artifacts exist
-   
-4. **Backup:**
-   - Creates timestamped backup of current deployment
-   - Keeps last N backups (configurable)
-   
-5. **Deploy:**
-   - Updates PM2 process (reload for zero-downtime)
-   - Starts new process if first deployment
-   
-6. **Health check:**
-   - Polls health endpoint until success
-   - Auto-rollback on failure
-   
-7. **Post-deploy:**
-   - Shows deployment summary
-   - Outputs logs command
-   - Displays app URL
-
-**Example:**
-```bash
-# Deploy to production
-hostfn deploy production
-
-# Deploy to staging
-hostfn deploy staging
-
-# Deploy with specific host (override config)
-hostfn deploy --host ubuntu@123.45.67.89
-
-# Dry run (show what would be deployed)
-hostfn deploy production --dry-run
-```
-
-**Output:**
-```
-🚀 Deploying to production...
-
-✓ Pre-flight checks passed
-✓ Files synced (245 files, 12.3 MB)
-✓ Dependencies installed (23s)
-✓ Build completed (8s)
-✓ Backup created: /var/www/backups/20251114_143022
-✓ PM2 reloaded: account-service
-✓ Health check passed (3 attempts)
-
-✅ Deployment successful!
-   Environment: production
-   Server: ubuntu@prod.example.com
-   Version: v1.2.3 (commit: abc1234)
-   URL: https://api.example.com
-   Time: 45s
-
-View logs: hostfn logs production
-```
-
----
-
-### 4. CI/CD Deployment (`hostfn deploy --ci`)
-
-**GitHub Actions Example:**
-```yaml
-name: Deploy to Production
-
-on:
-  push:
-    branches: [main]
-
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 18
-      
-      - name: Install hostfn
-        run: npm install -g hostfn
-      
-      - name: Deploy
-        run: hostfn deploy production --ci
-        env:
-          HOSTFN_SSH_KEY: ${{ secrets.DEPLOY_SSH_KEY }}
-          HOSTFN_HOST: ${{ secrets.DEPLOY_HOST }}
-          DATABASE_URL: ${{ secrets.DATABASE_URL }}
-          JWT_SECRET: ${{ secrets.JWT_SECRET }}
-```
-
-**What `--ci` flag does:**
-- Uses environment variables for credentials
-- Non-interactive mode (no prompts)
-- Enhanced logging for CI logs
-- Exits with proper error codes
-- Supports GitHub/GitLab/Bitbucket annotations
-
----
-
-### 5. Environment Management
-
-**Commands:**
-```bash
-# View environment variables on server
-hostfn env list production
-
-# Add/update environment variable
-hostfn env set production DATABASE_URL "postgresql://..."
-
-# Set from .env file
-hostfn env push production .env.production
-
-# Download environment variables
-hostfn env pull production > .env.production
-
-# Validate required env vars
-hostfn env validate production
-```
-
-**Security Features:**
-- Env vars stored in `.env` file on server (not in PM2 config)
-- Never logs sensitive values
-- Encrypted transfer over SSH
-- Local `.env.*` files in `.gitignore` by default
-
----
-
-### 6. Logs & Monitoring
-
-**Commands:**
-```bash
-# Stream logs (like pm2 logs)
-hostfn logs production
-
-# Show last N lines
-hostfn logs production --lines 100
-
-# Show only errors
-hostfn logs production --errors
-
-# Export logs to file
-hostfn logs production --output logs.txt
-```
-
----
-
-### 7. Rollback & Recovery
-
-**Commands:**
-```bash
-# List available backups
-hostfn backups list production
-
-# Rollback to previous deployment
-hostfn rollback production
-
-# Rollback to specific backup
-hostfn rollback production --to 20251114_143022
-
-# Restore from backup (manual)
-hostfn restore production 20251114_143022
-```
-
-**Auto-rollback:**
-- Triggered automatically if health checks fail after deployment
-- Reverts to last known-good deployment
-- Logs rollback reason
-
----
-
-### 8. Domain & SSL Setup
-
-**Commands:**
-```bash
-# Configure domain in Nginx
-hostfn domain add production api.example.com
-
-# Setup SSL with Let's Encrypt
-hostfn ssl setup production api.example.com --email admin@example.com
-
-# Renew SSL (auto-renewal setup by default)
-hostfn ssl renew production
-```
-
----
-
-### 9. Multi-Service Support
-
-For monorepos or multiple services on one server:
-
-**Configuration:**
-```json
-{
-  "services": {
-    "api": {
-      "port": 3000,
-      "path": "services/api",
-      "domain": "api.example.com"
-    },
-    "worker": {
-      "port": 3001,
-      "path": "services/worker",
-      "domain": "worker.example.com"
-    }
-  }
-}
-```
-
-**Commands:**
-```bash
-# Deploy specific service
-hostfn deploy production --service api
-
-# Deploy all services
-hostfn deploy production --all
-
-# Status of all services
-hostfn status production
-```
-
----
-
-## Technical Architecture
-
-### CLI Structure
-
-```
-hostfn/
-├── packages/
-│   ├── cli/                    # Main CLI package
-│   │   ├── src/
-│   │   │   ├── commands/       # Command implementations
-│   │   │   │   ├── init.ts
-│   │   │   │   ├── deploy.ts
-│   │   │   │   ├── server/
-│   │   │   │   │   ├── setup.ts
-│   │   │   │   │   └── info.ts
-│   │   │   │   ├── env.ts
-│   │   │   │   ├── logs.ts
-│   │   │   │   ├── rollback.ts
-│   │   │   │   └── domain.ts
-│   │   │   ├── core/           # Core business logic
-│   │   │   │   ├── ssh.ts      # SSH connection manager
-│   │   │   │   ├── rsync.ts    # File sync
-│   │   │   │   ├── pm2.ts      # PM2 manager
-│   │   │   │   ├── nginx.ts    # Nginx config generator
-│   │   │   │   ├── health.ts   # Health check
-│   │   │   │   └── backup.ts   # Backup manager
-│   │   │   ├── runtimes/       # Runtime adapters (pluggable)
-│   │   │   │   ├── base.ts     # Base runtime interface
-│   │   │   │   ├── registry.ts # Runtime registry
-│   │   │   │   └── nodejs/     # Node.js runtime adapter (v1.0)
-│   │   │   │       ├── index.ts
-│   │   │   │       ├── detector.ts
-│   │   │   │       ├── frameworks/
-│   │   │   │       │   ├── express.ts
-│   │   │   │       │   ├── hono.ts
-│   │   │   │       │   ├── nextjs.ts
-│   │   │   │       │   └── generic.ts
-│   │   │   │       └── pm2.ts  # PM2 manager
-│   │   │   ├── config/         # Config management
-│   │   │   │   ├── schema.ts   # Zod schemas
-│   │   │   │   ├── loader.ts
-│   │   │   │   └── validator.ts
-│   │   │   ├── utils/
-│   │   │   │   ├── logger.ts   # Pretty console output
-│   │   │   │   ├── spinner.ts
-│   │   │   │   └── git.ts
-│   │   │   └── index.ts        # CLI entry point
-│   │   ├── templates/          # Config templates
-│   │   │   ├── hostfn.config.json
-│   │   │   ├── nginx.conf
-│   │   │   ├── ecosystem.config.js
-│   │   │   └── .github/
-│   │   │       └── workflows/
-│   │   │           └── deploy.yml
-│   │   └── package.json
-│   │
-│   └── scripts/                # Server-side scripts (optional package)
-│       ├── setup-server.sh     # Generated dynamically
-│       └── deploy-remote.sh
-│
-├── examples/                   # Example projects
-│   ├── express-api/
-│   ├── hono-api/
-│   └── nextjs-app/
-│
-├── docs/                       # Documentation
-│   ├── getting-started.md
-│   ├── configuration.md
-│   ├── ci-cd.md
-│   └── examples/
-│
-├── package.json               # Monorepo root
-├── turbo.json                 # Turborepo config
-└── README.md
-```
-
----
-
-## Implementation Plan
-
-### Phase 1: Core Infrastructure (4-5 hours)
-
-**1.1 Project Setup**
-- [x] Create monorepo structure at `~/dev/functions/hostfn`
-- [x] Setup Turborepo with `packages/cli`
-- [x] Initialize TypeScript with strict config
-- [x] Setup CLI framework (Commander.js or Yargs)
-- [x] Add dependencies: ssh2, node-rsync, inquirer, chalk, ora
-
-**1.2 Config System**
-- [ ] Define `hostfn.config.json` Zod schema
-- [ ] Implement config loader with validation
-- [ ] Create config generator for `hostfn init`
-- [ ] Add config override via CLI flags and env vars
-
-**1.3 SSH Connection Manager**
-- [ ] Implement SSH connection pool using ssh2
-- [ ] Add SSH key authentication (file-based and agent)
-- [ ] Handle connection errors and retries
-- [ ] Support for password authentication (fallback)
-
-**1.4 Project Detectors**
-- [ ] Generic Node.js detector (reads package.json)
-- [ ] Framework-specific detectors:
-  - Express.js (detects express dependency)
-  - Hono (detects hono dependency)
-  - Next.js (detects next dependency)
-  - Fastify, Koa, etc.
-- [ ] Extract build/start commands from scripts
-- [ ] Detect monorepo structure (workspaces)
-
----
-
-### Phase 2: Server Setup (2-3 hours)
-
-**2.1 `hostfn server setup` Command**
-- [ ] OS detection script (Ubuntu/Debian/Amazon Linux/CentOS)
-- [ ] Runtime-specific installation (pluggable):
-  - [ ] Node.js via nvm (v1.0 - parametrized version)
-  - [ ] Runtime installer interface for future languages
-- [ ] Process manager installation (runtime-specific):
-  - [ ] PM2 for Node.js (v1.0)
-  - [ ] systemd for compiled languages (future)
-- [ ] Nginx installation and basic config
-- [ ] Firewall setup (ufw or firewalld)
-- [ ] Create deployment directories
-- [ ] Generate SSH keys for CI/CD
-- [ ] Process manager startup configuration
-
-**2.2 Nginx Configuration Generator**
-- [ ] Generate reverse proxy config for service
-- [ ] Support multiple services on same server
-- [ ] Health check endpoint routing
-- [ ] WebSocket support (upgrade headers)
-- [ ] Static file serving (if needed)
-
-**2.3 Server Info Command**
-- [ ] `hostfn server info` - Show server details
-- [ ] Display installed versions (Node, PM2, Nginx)
-- [ ] Show running services
-- [ ] Disk space, memory usage
-
----
-
-### Phase 3: Deployment Engine (3-4 hours)
-
-**3.1 `hostfn deploy` Command**
-- [ ] Pre-flight validation (SSH, config, health endpoint)
-- [ ] File sync with rsync (excludes: node_modules, .git, dist, .env)
-- [ ] Remote dependency installation (`npm ci --production`)
-- [ ] Remote build execution (npm run build)
-- [ ] Backup creation with timestamp
-- [ ] PM2 process management:
-  - [ ] Start new process if not exists
-  - [ ] Reload existing process (zero-downtime)
-  - [ ] Handle errors during reload
-- [ ] Health check polling (configurable timeout/retries)
-- [ ] Auto-rollback on failure
-- [ ] Deployment summary output
-
-**3.2 Environment Variable Management**
-- [ ] `hostfn env set` - Add/update env var
-- [ ] `hostfn env push` - Upload .env file
-- [ ] `hostfn env pull` - Download .env file
-- [ ] `hostfn env list` - Show env vars (masked)
-- [ ] `hostfn env validate` - Check required vars
-- [ ] Secure transfer and storage
-
-**3.3 CI/CD Mode**
-- [ ] `--ci` flag for non-interactive mode
-- [ ] Use env vars for credentials:
-  - HOSTFN_SSH_KEY
-  - HOSTFN_HOST
-  - HOSTFN_ENV_*
-- [ ] Enhanced logging for CI
-- [ ] Exit codes for CI
-- [ ] Support GitHub Actions annotations
-
----
-
-### Phase 4: Monitoring & Management (1-2 hours)
-
-**4.1 Logs**
-- [ ] `hostfn logs` - Stream logs via PM2
-- [ ] `--lines N` - Show last N lines
-- [ ] `--errors` - Filter errors only
-- [ ] `--output file.txt` - Export logs
-
-**4.2 Status & Info**
-- [ ] `hostfn status` - Show service status
-- [ ] Display: uptime, memory, CPU, restart count
-- [ ] Show deployment history
-- [ ] Show current version/commit
-
-**4.3 Rollback**
-- [ ] `hostfn backups list` - List backups
-- [ ] `hostfn rollback` - Rollback to previous
-- [ ] `hostfn rollback --to <timestamp>` - Specific backup
-- [ ] Auto-cleanup old backups (keep last N)
-
----
-
-### Phase 5: Advanced Features (Optional, 2-3 hours)
-
-**5.1 Domain & SSL**
-- [ ] `hostfn domain add` - Configure domain in Nginx
-- [ ] `hostfn ssl setup` - Let's Encrypt integration
-- [ ] `hostfn ssl renew` - Manual renewal
-- [ ] Auto-renewal setup (cron job)
-
-**5.2 Multi-Service Support**
-- [ ] Deploy multiple services from monorepo
-- [ ] `--service <name>` flag
-- [ ] `--all` flag for all services
-- [ ] Service dependency management
-
-**5.3 Database Migrations**
-- [ ] Detect migration commands in package.json
-- [ ] `hostfn migrate` - Run migrations
-- [ ] Auto-run migrations on deploy (optional)
-
-**5.4 Health Check Customization**
-- [ ] Support custom health check commands
-- [ ] TCP-based health checks (non-HTTP)
-- [ ] Multiple health check strategies
-
----
-
-## Technology Stack
-
-### CLI Package
-- **CLI Framework:** Commander.js (lightweight, popular)
-- **Config Validation:** Zod
-- **SSH:** ssh2 (pure JS SSH client)
-- **File Sync:** node-rsync (wrapper around rsync command)
-- **Prompts:** inquirer
-- **Styling:** chalk (colors), ora (spinners), boxen (boxes)
-- **Testing:** Vitest
-- **Architecture:** Pluggable runtime adapter system
-
-### Server-Side (V1.0 - Node.js)
-- **Process Manager:** PM2 (Node.js specific)
-- **Reverse Proxy:** Nginx (all runtimes)
-- **SSL:** Certbot / Let's Encrypt (all runtimes)
-- **Runtime Manager:** nvm (Node.js specific)
-
-### Future Server-Side Components
-- **Process Managers:** systemd (Go, Rust, Python), gunicorn (Python), puma (Ruby)
-- **Runtime Managers:** pyenv (Python), rbenv (Ruby), rustup (Rust)
-
----
-
-## Configuration Schema
-
-### `hostfn.config.json`
-
-```typescript
-interface HostfnConfig {
-  name: string;
-  runtime: 'nodejs' | 'python' | 'go' | 'ruby' | 'rust'; // Extensible
-  version: string; // Runtime version (e.g., Node 18, Python 3.11)
-  
-  environments: {
-    [env: string]: {
-      server: string; // user@host
-      port: number;
-      instances?: number | 'max';
-      domain?: string;
-      sslEmail?: string;
-    };
-  };
-  
-  build?: {
-    command: string;
-    directory: string;
-    nodeModules: 'all' | 'production' | 'none';
-  };
-  
-  start: {
-    command: string;
-    entry?: string;
-  };
-  
-  health?: {
-    path: string;
-    timeout: number;
-    retries: number;
-    interval?: number;
-  };
-  
-  env: {
-    required: string[];
-    optional?: string[];
-  };
-  
-  sync?: {
-    exclude?: string[];
-    include?: string[];
-  };
-  
-  backup?: {
-    keep: number; // Keep last N backups
-  };
-  
-  services?: {
-    [name: string]: {
-      port: number;
-      path: string; // Path in monorepo
-      domain?: string;
-    };
-  };
-}
-```
-
----
-
-## Example Usage Scenarios
-
-### Scenario 1: Fresh VPS Setup
-
-```bash
-# 1. Setup server (one-time)
-hostfn server setup ubuntu@123.45.67.89 --env production
-
-# 2. Initialize project
-cd my-node-app
-hostfn init
-# Prompts for server details, auto-detects settings
-
-# 3. Deploy
-hostfn deploy production
-
-# 4. Setup SSL
-hostfn ssl setup production api.example.com --email admin@example.com
-```
-
----
-
-### Scenario 2: Existing Project Migration
-
-```bash
-# Already have PM2 running on server
-cd existing-app
-
-# Initialize hostfn config
-hostfn init --import-pm2
-
-# Deploy (will detect existing PM2 process)
-hostfn deploy production
-```
-
----
-
-### Scenario 3: Monorepo with Multiple Services
-
-```bash
-# hostfn.config.json
-{
-  "services": {
-    "api": { "port": 3000, "path": "services/api" },
-    "worker": { "port": 3001, "path": "services/worker" },
-    "admin": { "port": 3002, "path": "services/admin" }
-  }
-}
-
-# Deploy all services
-hostfn deploy production --all
-
-# Deploy only API
-hostfn deploy production --service api
-```
-
----
-
-### Scenario 4: CI/CD Setup
-
-```bash
-# Generate GitHub Actions workflow
-hostfn init --ci github
-
-# This creates .github/workflows/deploy.yml
-# Add secrets to GitHub repo:
-# - DEPLOY_SSH_KEY
-# - DEPLOY_HOST
-# - DATABASE_URL (and other env vars)
-
-# Push to main → auto-deploys
-git push origin main
-```
-
----
-
-## Success Metrics
-
-1. **Developer Experience:**
-   - First deployment in < 5 minutes (after server setup)
-   - Zero-downtime deployments
-   - Clear error messages and rollback on failure
-
-2. **Reliability:**
-   - Health checks prevent bad deployments
-   - Auto-rollback on failure
-   - Backup system for easy recovery
-
-3. **Flexibility:**
-   - Works with any Node.js framework
-   - Supports any Linux VPS provider
-   - Customizable via config file
-
-4. **Production Ready:**
-   - SSL support out-of-the-box
-   - Environment variable management
-   - Monitoring and logging
-
----
-
-## Future Enhancements (v2+)
-
-1. **Multi-Language Support (Priority):**
-   - Python runtime adapter (Flask, FastAPI, Django)
-   - Go runtime adapter (compiled binaries + systemd)
-   - Ruby runtime adapter (Rails, Sinatra + puma)
-   - Rust runtime adapter (compiled binaries + systemd)
-   - PHP runtime adapter (Laravel, Symfony + php-fpm)
-   - Docker runtime adapter (universal container support)
-
-2. **Multi-Cloud Support:**
-   - Auto-provision VPS on AWS Lightsail, DigitalOcean, Linode
-   - `hostfn provision aws --size 1gb` → creates and configures VPS
-
-3. **Load Balancing:**
-   - Deploy to multiple servers
-   - Automatic Nginx load balancer setup
-   - Health-check based routing
-
-4. **Database Management:**
-   - Built-in PostgreSQL/MySQL setup
-   - Automated backups
-   - Connection pooling configuration
-
-5. **Monitoring Dashboard:**
-   - Web UI for deployment history
-   - Real-time logs and metrics
-   - Alerts on deployment failures
-
-6. **Plugin System:**
-   - Custom deployment hooks
-   - Runtime-specific optimizations
-   - Third-party integrations
-   - Community runtime adapters
-
----
-
-## Testing Strategy
-
-### Unit Tests
-- Config validation
-- SSH connection mocking
-- Deployment logic (dry-run mode)
-- Health check logic
-
-### Integration Tests
-- Deploy to test VPS
-- Multi-service deployment
-- Rollback scenarios
-- Environment variable management
-
-### E2E Tests
-- Full deployment flow
-- CI/CD workflow simulation
-- Multi-environment setup
-
----
-
-## Documentation Plan
-
-1. **Getting Started Guide:**
-   - Installation
-   - First deployment tutorial
-   - Common use cases
-
-2. **Configuration Reference:**
-   - All config options explained
-   - Examples for different frameworks
-
-3. **CI/CD Integration:**
-   - GitHub Actions
-   - GitLab CI
-   - Bitbucket Pipelines
-   - Generic CI setup
-
-4. **Troubleshooting:**
-   - Common errors
-   - SSH issues
-   - Deployment failures
-   - Performance tuning
-
-5. **API Reference:**
-   - All CLI commands
-   - Options and flags
-   - Exit codes
-
----
-
-## Open Questions
-
-1. **Runtime Adapter API:** What should the minimal interface be for a runtime adapter?
-2. **Build Optimization:** Should we support building locally and deploying artifacts only?
-3. **Multi-Region:** How to handle multi-region deployments?
-4. **Secrets Management:** Integration with vault services (AWS Secrets Manager, HashiCorp Vault)?
-5. **Monitoring:** Should we integrate with monitoring services (Sentry, DataDog)?
-6. **Polyglot Projects:** How to handle projects with multiple runtimes (e.g., Node.js + Python workers)?
-
----
-
-## Dependencies
-
-### CLI Package
-```json
-{
-  "dependencies": {
-    "commander": "^11.0.0",
-    "chalk": "^5.3.0",
-    "ora": "^7.0.1",
-    "inquirer": "^9.2.0",
-    "zod": "^3.22.0",
-    "ssh2": "^1.15.0",
-    "node-rsync": "^0.6.1",
-    "dotenv": "^16.3.0",
-    "execa": "^8.0.1"
-  },
-  "devDependencies": {
-    "typescript": "^5.3.0",
-    "vitest": "^1.0.0",
-    "@types/node": "^20.0.0",
-    "@types/ssh2": "^1.15.0",
-    "@types/inquirer": "^9.0.0"
-  }
-}
-```
-
----
-
-## Risks & Mitigations
-
-| Risk | Impact | Mitigation |
-|------|--------|------------|
-| SSH authentication failures | High | Support multiple auth methods, clear error messages |
-| Network timeouts during deployment | Medium | Configurable timeouts, retry logic |
-| PM2 process conflicts | Medium | Detect existing processes, graceful handling |
-| Nginx config errors | High | Validate config before applying, backup original |
-| Health check false negatives | Medium | Configurable retries, multiple check strategies |
-| Rollback failures | High | Keep backups separate, test rollback in CI |
-
----
-
-## Success Criteria
-
-**MVP (Minimum Viable Product):**
-- ✅ Can setup fresh server with one command
-- ✅ Can deploy Node.js app (Express/Hono) with zero-downtime
-- ✅ Health checks prevent bad deployments
-- ✅ Auto-rollback on failure
-- ✅ Environment variable management
-- ✅ CI/CD mode works in GitHub Actions
-- ✅ Clear documentation and examples
-
-**V1.0 Ready:**
-- ✅ All MVP features
-- ✅ SSL setup with Let's Encrypt
-- ✅ Multi-service support (monorepos)
-- ✅ Comprehensive logging
-- ✅ Tested on Ubuntu, Debian, Amazon Linux
-- ✅ 90%+ test coverage
-- ✅ Production-ready documentation
-
----
-
-## Timeline Estimate
-
-- **Phase 1 (Core):** 4-5 hours
-- **Phase 2 (Server Setup):** 2-3 hours
-- **Phase 3 (Deployment):** 3-4 hours
-- **Phase 4 (Monitoring):** 1-2 hours
-- **Phase 5 (Advanced):** 2-3 hours (optional)
-- **Testing & Docs:** 2-3 hours
-
-**Total MVP:** 12-17 hours  
-**Total V1.0:** 15-20 hours
-
----
-
-## Conclusion
-
-**hostfn** will democratize VPS deployments by providing PaaS-like simplicity with full control and economics. It fills a critical gap between expensive managed platforms and complex manual deployments, making it accessible for solo developers while being powerful enough for production applications.
-
-The **pluggable runtime adapter architecture** ensures extensibility across languages and frameworks, while maintaining the zero-config philosophy that keeps the initial learning curve minimal. Starting with Node.js support in v1.0, the foundation is built to easily expand to Python, Go, Ruby, Rust, and beyond.
-
----
-
-**Next Steps:**
-1. Review and approve this specification
-2. Setup monorepo structure at `~/dev/functions/hostfn`
-3. Begin Phase 1 implementation
-4. Create example projects for testing
-5. Write comprehensive documentation
-
----
-
-**Questions? Feedback?**
-Please review and provide feedback on:
-- Architecture decisions
-- Command structure
-- Configuration schema
-- Missing features
-- Priority of phases