refactor: Improve error messages for missing API tokens

Enhanced error messages across all cloud providers to be more actionable:
- Changed generic "API token/key is required" to "cannot be empty"
- Added specific authentication failure messages with provider URLs
- Included permission verification hints
- Added non-interactive mode environment variable suggestions

Benefits:
- Users get clear guidance on how to fix authentication issues
- Error messages now include direct links to token management pages
- Better UX for both interactive and non-interactive usage

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

digitalocean/lib/common.sh

@@ -72,7 +72,8 @@ ensure_do_token() {
 
     local token=$(safe_read "Enter your DigitalOcean API token: ") || return 1
     if [[ -z "$token" ]]; then
-        log_error "API token is required"
+        log_error "API token cannot be empty"
+        log_warn "For non-interactive usage, set: DO_API_TOKEN=your-token"
         return 1
     fi
 
@@ -82,7 +83,9 @@ ensure_do_token() {
     if echo "$test_response" | grep -q '"id"'; then
         log_info "API token validated"
     else
-        log_error "Invalid API token"
+        log_error "Authentication failed: Invalid DigitalOcean API token"
+        log_warn "Verify your token at: https://cloud.digitalocean.com/account/api/tokens"
+        log_warn "Ensure the token has read/write permissions"
         unset DO_API_TOKEN
         return 1
     fi
@@ -149,30 +152,7 @@ get_server_name() {
     echo "$server_name"
 }
 
-# Generate cloud-init userdata YAML
-get_cloud_init_userdata() {
-    cat << 'CLOUD_INIT_EOF'
-#cloud-config
-package_update: true
-packages:
-  - curl
-  - unzip
-  - git
-  - zsh
-
-runcmd:
-  # Install Bun
-  - su - root -c 'curl -fsSL https://bun.sh/install | bash'
-  # Install Claude Code
-  - su - root -c 'curl -fsSL https://claude.ai/install.sh | bash'
-  # Configure PATH in .bashrc
-  - echo 'export PATH="$HOME/.claude/local/bin:$HOME/.bun/bin:$PATH"' >> /root/.bashrc
-  # Configure PATH in .zshrc
-  - echo 'export PATH="$HOME/.claude/local/bin:$HOME/.bun/bin:$PATH"' >> /root/.zshrc
-  # Signal completion
-  - touch /root/.cloud-init-complete
-CLOUD_INIT_EOF
-}
+# get_cloud_init_userdata is now defined in shared/common.sh
 
 # Create a DigitalOcean droplet with cloud-init
 create_server() {

hetzner/lib/common.sh

@@ -70,7 +70,8 @@ ensure_hcloud_token() {
 
     local token=$(safe_read "Enter your Hetzner API token: ") || return 1
     if [[ -z "$token" ]]; then
-        log_error "API token is required"
+        log_error "API token cannot be empty"
+        log_warn "For non-interactive usage, set: HCLOUD_TOKEN=your-token"
         return 1
     fi
 
@@ -78,7 +79,9 @@ ensure_hcloud_token() {
     export HCLOUD_TOKEN="$token"
     local test_response=$(hetzner_api GET "/servers?per_page=1")
     if echo "$test_response" | grep -q '"error"'; then
-        log_error "Invalid API token"
+        log_error "Authentication failed: Invalid Hetzner API token"
+        log_warn "Verify your token at: https://console.hetzner.cloud/projects → API Tokens"
+        log_warn "Ensure the token has read/write permissions"
         unset HCLOUD_TOKEN
         return 1
     fi
@@ -145,30 +148,7 @@ get_server_name() {
     echo "$server_name"
 }
 
-# Generate cloud-init userdata YAML
-get_cloud_init_userdata() {
-    cat << 'CLOUD_INIT_EOF'
-#cloud-config
-package_update: true
-packages:
-  - curl
-  - unzip
-  - git
-  - zsh
-
-runcmd:
-  # Install Bun
-  - su - root -c 'curl -fsSL https://bun.sh/install | bash'
-  # Install Claude Code
-  - su - root -c 'curl -fsSL https://claude.ai/install.sh | bash'
-  # Configure PATH in .bashrc
-  - echo 'export PATH="$HOME/.claude/local/bin:$HOME/.bun/bin:$PATH"' >> /root/.bashrc
-  # Configure PATH in .zshrc
-  - echo 'export PATH="$HOME/.claude/local/bin:$HOME/.bun/bin:$PATH"' >> /root/.zshrc
-  # Signal completion
-  - touch /root/.cloud-init-complete
-CLOUD_INIT_EOF
-}
+# get_cloud_init_userdata is now defined in shared/common.sh
 
 # Create a Hetzner server with cloud-init
 create_server() {

linode/lib/common.sh

@@ -46,12 +46,22 @@ ensure_linode_token() {
     echo ""; log_warn "Linode API Token Required"
     echo -e "${YELLOW}Get your token from: https://cloud.linode.com/profile/tokens${NC}"; echo ""
     local token=$(safe_read "Enter your Linode API token: ") || return 1
-    if [[ -z "$token" ]]; then log_error "API token is required"; return 1; fi
+    if [[ -z "$token" ]]; then
+        log_error "API token cannot be empty"
+        log_warn "For non-interactive usage, set: LINODE_API_TOKEN=your-token"
+        return 1
+    fi
     export LINODE_API_TOKEN="$token"
     local test_response=$(linode_api GET "/profile")
     if echo "$test_response" | grep -q '"username"'; then
         log_info "API token validated"
-    else log_error "Invalid API token"; unset LINODE_API_TOKEN; return 1; fi
+    else
+        log_error "Authentication failed: Invalid Linode API token"
+        log_warn "Verify your token at: https://cloud.linode.com/profile/tokens"
+        log_warn "Ensure the token has read/write permissions"
+        unset LINODE_API_TOKEN
+        return 1
+    fi
     mkdir -p "$config_dir"
     cat > "$config_file" << EOF
 {

vultr/lib/common.sh

@@ -54,7 +54,8 @@ ensure_vultr_token() {
     echo ""
     local api_key=$(safe_read "Enter your Vultr API key: ") || return 1
     if [[ -z "$api_key" ]]; then
-        log_error "API key is required"
+        log_error "API key cannot be empty"
+        log_warn "For non-interactive usage, set: VULTR_API_KEY=your-key"
         return 1
     fi
     export VULTR_API_KEY="$api_key"
@@ -62,7 +63,9 @@ ensure_vultr_token() {
     if echo "$test_response" | grep -q '"account"'; then
         log_info "API key validated"
     else
-        log_error "Invalid API key"
+        log_error "Authentication failed: Invalid Vultr API key"
+        log_warn "Verify your API key at: https://my.vultr.com/settings/#settingsapi"
+        log_warn "Ensure the key has appropriate permissions"
         unset VULTR_API_KEY
         return 1
     fi