fix: add actionable guidance to SSH, API, and dependency error messages

[la14-1]

Summary

• Improve error messages in shared utilities (shared/common.sh) and 4 cloud providers that previously showed bare "Failed to..." messages without telling users how to fix the problem
• All changes add structured "How to fix" guidance with specific commands users can run to diagnose and resolve issues
• These error paths affect all SSH-based cloud providers through shared functions like generate_ssh_key_if_missing, get_ssh_fingerprint, generic_ssh_wait, and _report_api_failure

Changes

Shared (shared/common.sh)

• generate_ssh_key_if_missing: Handle ssh-keygen and mkdir failures with disk space/permission guidance
• get_ssh_fingerprint: Detect missing or corrupt public key files with regeneration instructions
• generic_ssh_wait: Structured "How to fix" with manual SSH test command and firewall/security group check
• _report_api_failure: Add DNS, firewall, and proxy guidance for network errors
• ensure_jq: Platform-specific install commands when no package manager is detected; hash -r hint after install
• get_openrouter_api_key_manual: Structured guidance after 3 failed attempts

Cloud providers

• Contabo: Actionable guidance for OAuth token and authentication failures
• Exoscale: Guidance for credential validation failures, CLI download failures
• Netcup: Network connectivity hint for API connection failures
• Scaleway: Structured guidance for project ID lookup failures

Test plan

• bash -n passes on all 5 changed .sh files
• bun test shows no new failures (pre-existing failures are unchanged)
• Manual verification: error messages are clear and actionable

-- refactor/ux-engineer

[louisgv]

Security Review

Verdict: APPROVED

Summary

This PR replaces terse error messages with actionable user guidance across 5 shell files. Changes are purely cosmetic (log output strings) with no logic changes except for a beneficial addition of input validation in get_ssh_fingerprint().

Findings

• [LOW] shared/common.sh:1060-1062 — $(dirname "${key_path}") used in log_error strings evaluates at expansion time, but key_path is already used in mkdir -p and ssh-keygen commands earlier in the same function, so this introduces no new attack surface. The value comes from the caller, not external input.

Security Improvements Noted

• Credential leak fix: contabo/lib/common.sh:38 — Previously logged raw $response which could contain OAuth tokens. The PR removes this, replacing it with static guidance text. This is a security improvement.
• Input validation: shared/common.sh:1070-1087 — get_ssh_fingerprint() now validates that the public key file exists and that the fingerprint was successfully extracted before returning, preventing silent failures.

Tests

• bash -n: PASS (all 5 files)
• bun test: N/A (test failures are pre-existing on main, not introduced by this PR; failures are identical in count and nature — missing picocolors package, network-dependent tests)
• curl|bash pattern: OK (all local-or-remote source fallback patterns intact)
• macOS compat: OK (no echo -e, no source <(), no ((var++)), no set -u, no local in subshells)

---

-- security/pr-reviewer

[la14-1]

Summary

• Improve error messages in shared utilities (shared/common.sh) and 4 cloud providers that previously showed bare "Failed to..." messages without telling users how to fix the problem
• All changes add structured "How to fix" guidance with specific commands users can run to diagnose and resolve issues
• These error paths affect all SSH-based cloud providers through shared functions like generate_ssh_key_if_missing, get_ssh_fingerprint, generic_ssh_wait, and _report_api_failure

Changes

Shared (shared/common.sh)

• generate_ssh_key_if_missing: Handle ssh-keygen and mkdir failures with disk space/permission guidance
• get_ssh_fingerprint: Detect missing or corrupt public key files with regeneration instructions
• generic_ssh_wait: Structured "How to fix" with manual SSH test command and firewall/security group check
• _report_api_failure: Add DNS, firewall, and proxy guidance for network errors
• ensure_jq: Platform-specific install commands when no package manager is detected; hash -r hint after install
• get_openrouter_api_key_manual: Structured guidance after 3 failed attempts

Cloud providers

• Contabo: Actionable guidance for OAuth token and authentication failures
• Exoscale: Guidance for credential validation failures, CLI download failures
• Netcup: Network connectivity hint for API connection failures
• Scaleway: Structured guidance for project ID lookup failures

Test plan

• bash -n passes on all 5 changed .sh files
• bun test shows no new failures (pre-existing failures are unchanged)
• Manual verification: error messages are clear and actionable

-- refactor/ux-engineer

[louisgv]

Security Review

Verdict: APPROVED

Summary

This PR replaces terse error messages with actionable user guidance across 5 shell files. Changes are purely cosmetic (log output strings) with no logic changes except for a beneficial addition of input validation in get_ssh_fingerprint().

Findings

• [LOW] shared/common.sh:1060-1062 — $(dirname "${key_path}") used in log_error strings evaluates at expansion time, but key_path is already used in mkdir -p and ssh-keygen commands earlier in the same function, so this introduces no new attack surface. The value comes from the caller, not external input.

Security Improvements Noted

• Credential leak fix: contabo/lib/common.sh:38 — Previously logged raw $response which could contain OAuth tokens. The PR removes this, replacing it with static guidance text. This is a security improvement.
• Input validation: shared/common.sh:1070-1087 — get_ssh_fingerprint() now validates that the public key file exists and that the fingerprint was successfully extracted before returning, preventing silent failures.

Tests

• bash -n: PASS (all 5 files)
• bun test: N/A (test failures are pre-existing on main, not introduced by this PR; failures are identical in count and nature — missing picocolors package, network-dependent tests)
• curl|bash pattern: OK (all local-or-remote source fallback patterns intact)
• macOS compat: OK (no echo -e, no source <(), no ((var++)), no set -u, no local in subshells)

---

-- security/pr-reviewer

[la14-1]

Summary

• Improve error messages in shared utilities (shared/common.sh) and 4 cloud providers that previously showed bare "Failed to..." messages without telling users how to fix the problem
• All changes add structured "How to fix" guidance with specific commands users can run to diagnose and resolve issues
• These error paths affect all SSH-based cloud providers through shared functions like generate_ssh_key_if_missing, get_ssh_fingerprint, generic_ssh_wait, and _report_api_failure

Changes

Shared (shared/common.sh)

• generate_ssh_key_if_missing: Handle ssh-keygen and mkdir failures with disk space/permission guidance
• get_ssh_fingerprint: Detect missing or corrupt public key files with regeneration instructions
• generic_ssh_wait: Structured "How to fix" with manual SSH test command and firewall/security group check
• _report_api_failure: Add DNS, firewall, and proxy guidance for network errors
• ensure_jq: Platform-specific install commands when no package manager is detected; hash -r hint after install
• get_openrouter_api_key_manual: Structured guidance after 3 failed attempts

Cloud providers

• Contabo: Actionable guidance for OAuth token and authentication failures
• Exoscale: Guidance for credential validation failures, CLI download failures
• Netcup: Network connectivity hint for API connection failures
• Scaleway: Structured guidance for project ID lookup failures

Test plan

• bash -n passes on all 5 changed .sh files
• bun test shows no new failures (pre-existing failures are unchanged)
• Manual verification: error messages are clear and actionable

-- refactor/ux-engineer

[louisgv]

Security Review

Verdict: APPROVED

Summary

This PR replaces terse error messages with actionable user guidance across 5 shell files. Changes are purely cosmetic (log output strings) with no logic changes except for a beneficial addition of input validation in get_ssh_fingerprint().

Findings

• [LOW] shared/common.sh:1060-1062 — $(dirname "${key_path}") used in log_error strings evaluates at expansion time, but key_path is already used in mkdir -p and ssh-keygen commands earlier in the same function, so this introduces no new attack surface. The value comes from the caller, not external input.

Security Improvements Noted

• Credential leak fix: contabo/lib/common.sh:38 — Previously logged raw $response which could contain OAuth tokens. The PR removes this, replacing it with static guidance text. This is a security improvement.
• Input validation: shared/common.sh:1070-1087 — get_ssh_fingerprint() now validates that the public key file exists and that the fingerprint was successfully extracted before returning, preventing silent failures.

Tests

• bash -n: PASS (all 5 files)
• bun test: N/A (test failures are pre-existing on main, not introduced by this PR; failures are identical in count and nature — missing picocolors package, network-dependent tests)
• curl|bash pattern: OK (all local-or-remote source fallback patterns intact)
• macOS compat: OK (no echo -e, no source <(), no ((var++)), no set -u, no local in subshells)

---

-- security/pr-reviewer

[la14-1]

Summary

• Improve error messages in shared utilities (shared/common.sh) and 4 cloud providers that previously showed bare "Failed to..." messages without telling users how to fix the problem
• All changes add structured "How to fix" guidance with specific commands users can run to diagnose and resolve issues
• These error paths affect all SSH-based cloud providers through shared functions like generate_ssh_key_if_missing, get_ssh_fingerprint, generic_ssh_wait, and _report_api_failure

Changes

Shared (shared/common.sh)

• generate_ssh_key_if_missing: Handle ssh-keygen and mkdir failures with disk space/permission guidance
• get_ssh_fingerprint: Detect missing or corrupt public key files with regeneration instructions
• generic_ssh_wait: Structured "How to fix" with manual SSH test command and firewall/security group check
• _report_api_failure: Add DNS, firewall, and proxy guidance for network errors
• ensure_jq: Platform-specific install commands when no package manager is detected; hash -r hint after install
• get_openrouter_api_key_manual: Structured guidance after 3 failed attempts

Cloud providers

• Contabo: Actionable guidance for OAuth token and authentication failures
• Exoscale: Guidance for credential validation failures, CLI download failures
• Netcup: Network connectivity hint for API connection failures
• Scaleway: Structured guidance for project ID lookup failures

Test plan

• bash -n passes on all 5 changed .sh files
• bun test shows no new failures (pre-existing failures are unchanged)
• Manual verification: error messages are clear and actionable

-- refactor/ux-engineer

[louisgv]

Security Review

Verdict: APPROVED

Summary

This PR replaces terse error messages with actionable user guidance across 5 shell files. Changes are purely cosmetic (log output strings) with no logic changes except for a beneficial addition of input validation in get_ssh_fingerprint().

Findings

• [LOW] shared/common.sh:1060-1062 — $(dirname "${key_path}") used in log_error strings evaluates at expansion time, but key_path is already used in mkdir -p and ssh-keygen commands earlier in the same function, so this introduces no new attack surface. The value comes from the caller, not external input.

Security Improvements Noted

• Credential leak fix: contabo/lib/common.sh:38 — Previously logged raw $response which could contain OAuth tokens. The PR removes this, replacing it with static guidance text. This is a security improvement.
• Input validation: shared/common.sh:1070-1087 — get_ssh_fingerprint() now validates that the public key file exists and that the fingerprint was successfully extracted before returning, preventing silent failures.

Tests

• bash -n: PASS (all 5 files)
• bun test: N/A (test failures are pre-existing on main, not introduced by this PR; failures are identical in count and nature — missing picocolors package, network-dependent tests)
• curl|bash pattern: OK (all local-or-remote source fallback patterns intact)
• macOS compat: OK (no echo -e, no source <(), no ((var++)), no set -u, no local in subshells)

---

-- security/pr-reviewer

[la14-1]

Summary

• Improve error messages in shared utilities (shared/common.sh) and 4 cloud providers that previously showed bare "Failed to..." messages without telling users how to fix the problem
• All changes add structured "How to fix" guidance with specific commands users can run to diagnose and resolve issues
• These error paths affect all SSH-based cloud providers through shared functions like generate_ssh_key_if_missing, get_ssh_fingerprint, generic_ssh_wait, and _report_api_failure

Changes

Shared (shared/common.sh)

• generate_ssh_key_if_missing: Handle ssh-keygen and mkdir failures with disk space/permission guidance
• get_ssh_fingerprint: Detect missing or corrupt public key files with regeneration instructions
• generic_ssh_wait: Structured "How to fix" with manual SSH test command and firewall/security group check
• _report_api_failure: Add DNS, firewall, and proxy guidance for network errors
• ensure_jq: Platform-specific install commands when no package manager is detected; hash -r hint after install
• get_openrouter_api_key_manual: Structured guidance after 3 failed attempts

Cloud providers

• Contabo: Actionable guidance for OAuth token and authentication failures
• Exoscale: Guidance for credential validation failures, CLI download failures
• Netcup: Network connectivity hint for API connection failures
• Scaleway: Structured guidance for project ID lookup failures

Test plan

• bash -n passes on all 5 changed .sh files
• bun test shows no new failures (pre-existing failures are unchanged)
• Manual verification: error messages are clear and actionable

-- refactor/ux-engineer

[louisgv]

Security Review

Verdict: APPROVED

Summary

This PR replaces terse error messages with actionable user guidance across 5 shell files. Changes are purely cosmetic (log output strings) with no logic changes except for a beneficial addition of input validation in get_ssh_fingerprint().

Findings

• [LOW] shared/common.sh:1060-1062 — $(dirname "${key_path}") used in log_error strings evaluates at expansion time, but key_path is already used in mkdir -p and ssh-keygen commands earlier in the same function, so this introduces no new attack surface. The value comes from the caller, not external input.

Security Improvements Noted

• Credential leak fix: contabo/lib/common.sh:38 — Previously logged raw $response which could contain OAuth tokens. The PR removes this, replacing it with static guidance text. This is a security improvement.
• Input validation: shared/common.sh:1070-1087 — get_ssh_fingerprint() now validates that the public key file exists and that the fingerprint was successfully extracted before returning, preventing silent failures.

Tests

• bash -n: PASS (all 5 files)
• bun test: N/A (test failures are pre-existing on main, not introduced by this PR; failures are identical in count and nature — missing picocolors package, network-dependent tests)
• curl|bash pattern: OK (all local-or-remote source fallback patterns intact)
• macOS compat: OK (no echo -e, no source <(), no ((var++)), no set -u, no local in subshells)

---

-- security/pr-reviewer

[la14-1]

Summary

• Improve error messages in shared utilities (shared/common.sh) and 4 cloud providers that previously showed bare "Failed to..." messages without telling users how to fix the problem
• All changes add structured "How to fix" guidance with specific commands users can run to diagnose and resolve issues
• These error paths affect all SSH-based cloud providers through shared functions like generate_ssh_key_if_missing, get_ssh_fingerprint, generic_ssh_wait, and _report_api_failure

Changes

Shared (shared/common.sh)

• generate_ssh_key_if_missing: Handle ssh-keygen and mkdir failures with disk space/permission guidance
• get_ssh_fingerprint: Detect missing or corrupt public key files with regeneration instructions
• generic_ssh_wait: Structured "How to fix" with manual SSH test command and firewall/security group check
• _report_api_failure: Add DNS, firewall, and proxy guidance for network errors
• ensure_jq: Platform-specific install commands when no package manager is detected; hash -r hint after install
• get_openrouter_api_key_manual: Structured guidance after 3 failed attempts

Cloud providers

• Contabo: Actionable guidance for OAuth token and authentication failures
• Exoscale: Guidance for credential validation failures, CLI download failures
• Netcup: Network connectivity hint for API connection failures
• Scaleway: Structured guidance for project ID lookup failures

Test plan

• bash -n passes on all 5 changed .sh files
• bun test shows no new failures (pre-existing failures are unchanged)
• Manual verification: error messages are clear and actionable

-- refactor/ux-engineer

[louisgv]

Security Review

Verdict: APPROVED

Summary

This PR replaces terse error messages with actionable user guidance across 5 shell files. Changes are purely cosmetic (log output strings) with no logic changes except for a beneficial addition of input validation in get_ssh_fingerprint().

Findings

• [LOW] shared/common.sh:1060-1062 — $(dirname "${key_path}") used in log_error strings evaluates at expansion time, but key_path is already used in mkdir -p and ssh-keygen commands earlier in the same function, so this introduces no new attack surface. The value comes from the caller, not external input.

Security Improvements Noted

• Credential leak fix: contabo/lib/common.sh:38 — Previously logged raw $response which could contain OAuth tokens. The PR removes this, replacing it with static guidance text. This is a security improvement.
• Input validation: shared/common.sh:1070-1087 — get_ssh_fingerprint() now validates that the public key file exists and that the fingerprint was successfully extracted before returning, preventing silent failures.

Tests

• bash -n: PASS (all 5 files)
• bun test: N/A (test failures are pre-existing on main, not introduced by this PR; failures are identical in count and nature — missing picocolors package, network-dependent tests)
• curl|bash pattern: OK (all local-or-remote source fallback patterns intact)
• macOS compat: OK (no echo -e, no source <(), no ((var++)), no set -u, no local in subshells)

---

-- security/pr-reviewer

[la14-1]

Summary

• Improve error messages in shared utilities (shared/common.sh) and 4 cloud providers that previously showed bare "Failed to..." messages without telling users how to fix the problem
• All changes add structured "How to fix" guidance with specific commands users can run to diagnose and resolve issues
• These error paths affect all SSH-based cloud providers through shared functions like generate_ssh_key_if_missing, get_ssh_fingerprint, generic_ssh_wait, and _report_api_failure

Changes

Shared (shared/common.sh)

• generate_ssh_key_if_missing: Handle ssh-keygen and mkdir failures with disk space/permission guidance
• get_ssh_fingerprint: Detect missing or corrupt public key files with regeneration instructions
• generic_ssh_wait: Structured "How to fix" with manual SSH test command and firewall/security group check
• _report_api_failure: Add DNS, firewall, and proxy guidance for network errors
• ensure_jq: Platform-specific install commands when no package manager is detected; hash -r hint after install
• get_openrouter_api_key_manual: Structured guidance after 3 failed attempts

Cloud providers

• Contabo: Actionable guidance for OAuth token and authentication failures
• Exoscale: Guidance for credential validation failures, CLI download failures
• Netcup: Network connectivity hint for API connection failures
• Scaleway: Structured guidance for project ID lookup failures

Test plan

• bash -n passes on all 5 changed .sh files
• bun test shows no new failures (pre-existing failures are unchanged)
• Manual verification: error messages are clear and actionable

-- refactor/ux-engineer

[louisgv]

Security Review

Verdict: APPROVED

Summary

This PR replaces terse error messages with actionable user guidance across 5 shell files. Changes are purely cosmetic (log output strings) with no logic changes except for a beneficial addition of input validation in get_ssh_fingerprint().

Findings

• [LOW] shared/common.sh:1060-1062 — $(dirname "${key_path}") used in log_error strings evaluates at expansion time, but key_path is already used in mkdir -p and ssh-keygen commands earlier in the same function, so this introduces no new attack surface. The value comes from the caller, not external input.

Security Improvements Noted

• Credential leak fix: contabo/lib/common.sh:38 — Previously logged raw $response which could contain OAuth tokens. The PR removes this, replacing it with static guidance text. This is a security improvement.
• Input validation: shared/common.sh:1070-1087 — get_ssh_fingerprint() now validates that the public key file exists and that the fingerprint was successfully extracted before returning, preventing silent failures.

Tests

• bash -n: PASS (all 5 files)
• bun test: N/A (test failures are pre-existing on main, not introduced by this PR; failures are identical in count and nature — missing picocolors package, network-dependent tests)
• curl|bash pattern: OK (all local-or-remote source fallback patterns intact)
• macOS compat: OK (no echo -e, no source <(), no ((var++)), no set -u, no local in subshells)

---

-- security/pr-reviewer

[la14-1]

Summary

• Improve error messages in shared utilities (shared/common.sh) and 4 cloud providers that previously showed bare "Failed to..." messages without telling users how to fix the problem
• All changes add structured "How to fix" guidance with specific commands users can run to diagnose and resolve issues
• These error paths affect all SSH-based cloud providers through shared functions like generate_ssh_key_if_missing, get_ssh_fingerprint, generic_ssh_wait, and _report_api_failure

Changes

Shared (shared/common.sh)

• generate_ssh_key_if_missing: Handle ssh-keygen and mkdir failures with disk space/permission guidance
• get_ssh_fingerprint: Detect missing or corrupt public key files with regeneration instructions
• generic_ssh_wait: Structured "How to fix" with manual SSH test command and firewall/security group check
• _report_api_failure: Add DNS, firewall, and proxy guidance for network errors
• ensure_jq: Platform-specific install commands when no package manager is detected; hash -r hint after install
• get_openrouter_api_key_manual: Structured guidance after 3 failed attempts

Cloud providers

• Contabo: Actionable guidance for OAuth token and authentication failures
• Exoscale: Guidance for credential validation failures, CLI download failures
• Netcup: Network connectivity hint for API connection failures
• Scaleway: Structured guidance for project ID lookup failures

Test plan

• bash -n passes on all 5 changed .sh files
• bun test shows no new failures (pre-existing failures are unchanged)
• Manual verification: error messages are clear and actionable

-- refactor/ux-engineer

[louisgv]

Security Review

Verdict: APPROVED

Summary

This PR replaces terse error messages with actionable user guidance across 5 shell files. Changes are purely cosmetic (log output strings) with no logic changes except for a beneficial addition of input validation in get_ssh_fingerprint().

Findings

• [LOW] shared/common.sh:1060-1062 — $(dirname "${key_path}") used in log_error strings evaluates at expansion time, but key_path is already used in mkdir -p and ssh-keygen commands earlier in the same function, so this introduces no new attack surface. The value comes from the caller, not external input.

Security Improvements Noted

• Credential leak fix: contabo/lib/common.sh:38 — Previously logged raw $response which could contain OAuth tokens. The PR removes this, replacing it with static guidance text. This is a security improvement.
• Input validation: shared/common.sh:1070-1087 — get_ssh_fingerprint() now validates that the public key file exists and that the fingerprint was successfully extracted before returning, preventing silent failures.

Tests

• bash -n: PASS (all 5 files)
• bun test: N/A (test failures are pre-existing on main, not introduced by this PR; failures are identical in count and nature — missing picocolors package, network-dependent tests)
• curl|bash pattern: OK (all local-or-remote source fallback patterns intact)
• macOS compat: OK (no echo -e, no source <(), no ((var++)), no set -u, no local in subshells)

---

-- security/pr-reviewer