fix: add debug option for SSH remote shell wrapper to assist with troubleshooting

README.md

@@ -31,6 +31,9 @@ jobs:
           ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
           ssh-host: ${{ secrets.SSH_HOST }}
           ssh-user: ${{ secrets.SSH_USER }}
+          # Optional: enable debug mode to print the temp script and its
+          # contents on the runner for troubleshooting "no output" cases.
+          debug-shell-wrapper: 'true'
       
       - name: Run remote commands with custom shell
         shell: ssh-remote {0}
@@ -137,6 +140,7 @@ jobs:
 | `strict-host-key-checking` | Enable strict host key checking (`yes`/`no`/`accept-new`) | No | `accept-new` |
 | `use-shell-wrapper` | Create shell wrapper for remote execution (enables `shell: ssh-remote {0}`) | No | `true` |
 | `remote-shell` | Shell to use on remote server (`bash`, `sh`, `zsh`, etc.) | No | `bash` |
+| `debug-shell-wrapper` | Print script path and contents before executing remote commands (for debugging only) | No | `false` |
 
 ## Outputs
 
@@ -170,6 +174,8 @@ Use `shell: ssh-remote {0}` in any step to execute the entire script on the remo
 - Works like a local shell
 - No need to wrap commands in SSH
 
+⚠️ Note: Enabling `debug-shell-wrapper: 'true'` will print the contents of the temporary script and the exit code to the job logs. This can help diagnose "no output" runs, but may leak secrets or other sensitive data — only enable on trusted runs.
+
 ### 2. SSH Host Alias (Direct)
 
 
@@ -220,6 +226,34 @@ Add the output to a GitHub secret named `SSH_KNOWN_HOSTS`.
 
 ## Troubleshooting
 
+### Debugging no output from custom shell
+
+If a step using `shell: ssh-remote {0}` shows no output but reports success:
+
+- Enable `debug-shell-wrapper: 'true'` in the `Setup SSH` step. This will tell the wrapper to print the temp script path and the first 200 lines of the script it executes. Example:
+
+```yaml
+- name: Setup SSH
+  uses: your-username/setup-ssh-client@v1
+  with:
+    ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
+    ssh-host: ${{ secrets.SSH_HOST }}
+    ssh-user: ${{ secrets.SSH_USER }}
+    debug-shell-wrapper: 'true'
+```
+
+- Re-run the job — the logs from subsequent steps will include the script path and contents; confirm the commands you expect are present.
+- If the script looks correct, try a direct SSH command from a `run:` step to verify remote side:
+
+```yaml
+- name: Direct SSH smoke test
+  run: ssh github-action-host "echo hello; whoami; pwd"
+```
+
+- If the direct test shows output but the wrapper step still shows nothing, examine whether your remote shell sets PATH or environment differently for non-interactive shells — you may need to force a login shell or source shell rc files with `shell: ssh-remote {0}` and `run: | source ~/.bashrc; your commands` or set `remote-shell: 'bash -l'`.
+
+Note: Don't forget to disable `debug-shell-wrapper` when done; it prints the script contents into logs which may reveal secrets.
+
 ### Connection Timeout
 
 If the connection test fails with a timeout: