feat: implement remote shell bootstrapping for zsh and bash in execution flow

Author: Akagi201

README.md

@@ -115,6 +115,8 @@ echo "version = $VERSION"
 
 Using `@SHELL` for remote servers with non-bash default shells:
 
+Shellflow starts remote shells in login mode. For remote `zsh` and `bash` blocks, Shellflow also bootstraps `~/.zshrc` or `~/.bashrc` quietly before running your commands so tools initialized there, such as `mise`, remain available in non-interactive automation even if the rc file exits non-zero.
+
 ```bash
 #!/bin/bash
 

features/execution_contract.feature

@@ -26,4 +26,18 @@ Feature: Agent-facing execution contract
     Then the parse failure should exit with code 2
     And the missing SSH host failure should exit with code 3
     And the block execution failure should exit with code 1
-    And the timeout failure should exit with code 4
+    And the timeout failure should exit with code 4
+
+  Scenario: Remote zsh payload bootstraps zshrc before user commands
+    Given host "testhost" is configured in SSH config
+    And a script file with a remote "zsh" block
+    When I inspect the generated remote script payload
+    Then the output should contain "test -f ~/.zshrc && { source ~/.zshrc >/dev/null 2>&1 || true; }"
+    And the output should contain "bootstrap-check"
+
+  Scenario: Remote bash payload bootstraps bashrc before user commands
+    Given host "testhost" is configured in SSH config
+    And a script file with a remote "bash" block
+    When I inspect the generated remote script payload
+    Then the output should contain "test -f ~/.bashrc && { set +e; . ~/.bashrc >/dev/null 2>&1; set -e; }"
+    And the output should contain "bootstrap-check"

features/steps/shellflow_steps.py

@@ -721,6 +721,18 @@ def step_given_script_file_with_secret_like_export(context: Context) -> None:
     )
 
 
+@given('a script file with a remote "{shell_name}" block')
+def step_given_script_file_with_remote_shell_block(context: Context, shell_name: str) -> None:
+    given_script_file_with_content(
+        context,
+        f"""
+        # @REMOTE testhost
+        # @SHELL {shell_name}
+        echo "bootstrap-check"
+        """,
+    )
+
+
 @given("a script with content:")
 def step_given_script_with_content(context: Context) -> None:
     given_script_with_content(context, context.text)
@@ -736,6 +748,33 @@ def step_when_run_the_script(context: Context) -> None:
     when_run_the_script(context)
 
 
+@when("I inspect the generated remote script payload")
+def step_when_inspect_generated_remote_script_payload(context: Context) -> None:
+    script_content = getattr(context, "script_content", None)
+    if not script_content:
+        raise ValueError("No script content set. Did you call the Given step first?")
+
+    blocks = parse_script(script_content)
+    if len(blocks) != 1 or not blocks[0].is_remote:
+        raise AssertionError(f"Expected exactly one remote block, got: {blocks}")
+
+    block = blocks[0]
+    ssh_config = _read_ssh_config_for_context(context, block.host or "")
+    if ssh_config is None:
+        raise AssertionError(f"Remote host not configured for test: {block.host}")
+
+    mock_result = mock.Mock(returncode=0, stdout="", stderr="")
+    with mock.patch("shellflow.subprocess.run", return_value=mock_result) as mock_run:
+        result = execute_remote(block, ExecutionContext(), ssh_config)
+
+    if not result.success:
+        raise AssertionError(f"Expected execute_remote to succeed, got: {result}")
+
+    context.stdout = mock_run.call_args.kwargs["input"]
+    context.stderr = ""
+    context.exit_code = 0
+
+
 @when("I run the script with JSON output enabled")
 def step_when_run_the_script_with_json_output(context: Context) -> None:
     when_run_the_script_with_cli_args(context, "--json")

playbooks/arch_up.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+set -euo pipefail
+
+# @REMOTE sui
+# @SHELL zsh
+mise install go@latest

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "shellflow"
-version = "0.2.1"
+version = "0.2.2"
 description = "A minimal shell script orchestrator with SSH support"
 readme = "README.md"
 license = "Apache-2.0"

src/shellflow.py

@@ -619,15 +619,30 @@ def _build_executable_script(
     context: ExecutionContext,
     *,
     include_context_exports: bool,
+    shell: str | None = None,
 ) -> str:
     """Build a shell script payload for local or remote execution."""
     script_lines = ["set -e"]
     if include_context_exports:
         script_lines.extend(_build_context_exports(context))
+    script_lines.extend(_build_shell_bootstrap(shell))
     script_lines.extend(commands)
     return "\n".join(script_lines)
 
 
+def _build_shell_bootstrap(shell: str | None) -> list[str]:
+    """Build shell-specific bootstrap lines needed for non-interactive automation."""
+    if not shell:
+        return []
+
+    shell_name = Path(shell).name
+    if shell_name == "zsh":
+        return ["test -f ~/.zshrc && { source ~/.zshrc >/dev/null 2>&1 || true; }"]
+    if shell_name == "bash":
+        return ["test -f ~/.bashrc && { set +e; . ~/.bashrc >/dev/null 2>&1; set -e; }"]
+    return []
+
+
 def _build_context_exports(context: ExecutionContext) -> list[str]:
     """Build export statements for explicit shellflow context values only."""
     exports = [f"export SHELLFLOW_LAST_OUTPUT={_quote_shell_value(context.last_output)}"]
@@ -897,11 +912,12 @@ def execute_remote(
         ssh_args.extend(["-F", str(ssh_config_path)])
 
     shell = block.shell or "bash"
-    ssh_args.extend(["-o", "BatchMode=yes", host, shell, "-se"])
+    ssh_args.extend(["-o", "BatchMode=yes", host, shell, "-l", "-s", "-e"])
     remote_script = _build_executable_script(
         block.commands,
         context,
         include_context_exports=True,
+        shell=shell,
     )
     run_kwargs: dict[str, Any] = {
         "input": remote_script,

tests/test_shellflow.py

@@ -27,6 +27,7 @@
     RunResult,
     ShellflowError,
     SSHConfig,
+    _build_executable_script,
     _clean_commands,
     _is_valid_env_name,
     create_parser,
@@ -688,6 +689,43 @@ def test_ssh_config_used_in_command(
             assert "-i" in call_args
             assert "/path/to/key" in call_args
 
+    def test_custom_remote_shell_runs_as_login_shell(
+        self,
+        execution_context: ExecutionContext,
+    ) -> None:
+        """Test custom remote shells run in login mode so host PATH initialization is loaded."""
+        block = Block(target="REMOTE:myhost", commands=["mise --version"], shell="zsh")  # noqa: S604
+        ssh_config = SSHConfig(host="myhost")
+
+        mock_result = mock.Mock(returncode=0, stdout="2026.1.0\n", stderr="")
+
+        with mock.patch("shellflow.subprocess.run", return_value=mock_result) as mock_run:
+            result = execute_remote(block, execution_context, ssh_config)
+
+        assert result.success is True
+        call_args = mock_run.call_args[0][0]
+        assert call_args[-4:] == ["zsh", "-l", "-s", "-e"]
+
+    def test_remote_zsh_bootstraps_zshrc_before_commands(
+        self,
+        execution_context: ExecutionContext,
+    ) -> None:
+        """Test remote zsh execution sources ~/.zshrc so non-login PATH customizations are available."""
+        block = Block(target="REMOTE:myhost", commands=["mise --version"], shell="zsh")  # noqa: S604
+        ssh_config = SSHConfig(host="myhost")
+
+        mock_result = mock.Mock(returncode=0, stdout="2026.1.0\n", stderr="")
+
+        with mock.patch("shellflow.subprocess.run", return_value=mock_result) as mock_run:
+            result = execute_remote(block, execution_context, ssh_config)
+
+        assert result.success is True
+        sent_script = mock_run.call_args.kwargs["input"]
+        assert "test -f ~/.zshrc && { source ~/.zshrc >/dev/null 2>&1 || true; }" in sent_script
+        assert sent_script.index(
+            "test -f ~/.zshrc && { source ~/.zshrc >/dev/null 2>&1 || true; }"
+        ) < sent_script.index("mise --version")
+
     def test_remote_execution_only_exports_explicit_context(
         self,
         execution_context: ExecutionContext,
@@ -792,6 +830,68 @@ def test_no_ssh_config_uses_manual_lookup(
             assert "2222" in call_args
 
 
+class TestShellBootstrapIntegration:
+    """Integration-style tests for non-interactive shell bootstrap behavior."""
+
+    def test_zsh_bootstrap_ignores_nonzero_zshrc_and_keeps_path_customizations(self, tmp_path: Path) -> None:
+        """Test guarded zshrc bootstrap still exposes commands after a non-zero rc return."""
+        bin_dir = tmp_path / "bin"
+        bin_dir.mkdir()
+        fake_mise = bin_dir / "mise"
+        fake_mise.write_text("#!/bin/sh\necho fake-mise\n")
+        fake_mise.chmod(0o755)
+
+        (tmp_path / ".zshrc").write_text(f'export PATH="{bin_dir}:$PATH"\nfalse\n')
+
+        script = _build_executable_script(  # noqa: S604
+            ["command -v mise"],
+            ExecutionContext(),
+            include_context_exports=False,
+            shell="zsh",
+        )
+
+        result = subprocess.run(
+            ["/bin/zsh", "-l", "-s", "-e"],
+            input=script,
+            capture_output=True,
+            text=True,
+            env={"HOME": str(tmp_path), "PATH": "/usr/bin:/bin:/usr/sbin:/sbin"},
+            check=False,
+        )
+
+        assert result.returncode == 0
+        assert str(fake_mise) in result.stdout
+
+    def test_bash_bootstrap_ignores_nonzero_bashrc_and_keeps_path_customizations(self, tmp_path: Path) -> None:
+        """Test guarded bashrc bootstrap still exposes commands after a non-zero rc return."""
+        bin_dir = tmp_path / "bin"
+        bin_dir.mkdir()
+        fake_tool = bin_dir / "tool-from-bashrc"
+        fake_tool.write_text("#!/bin/sh\necho fake-bash-tool\n")
+        fake_tool.chmod(0o755)
+
+        (tmp_path / ".bashrc").write_text(f'export PATH="{bin_dir}:$PATH"\nfalse\n')
+
+        script = _build_executable_script(  # noqa: S604
+            ["command -v tool-from-bashrc"],
+            ExecutionContext(),
+            include_context_exports=False,
+            shell="bash",
+        )
+
+        result = subprocess.run(
+            ["/bin/bash", "-l", "-s", "-e"],
+            input=script,
+            capture_output=True,
+            text=True,
+            env={"HOME": str(tmp_path), "PATH": "/usr/bin:/bin:/usr/sbin:/sbin"},
+            check=False,
+        )
+
+        assert result.returncode == 0
+        assert str(fake_tool) in result.stdout
+
+
 # =============================================================================
 # parse_script Advanced Tests
 # =============================================================================