Refactor code structure and remove redundant code blocks for improved readability and maintainability

Author: Akagi201

.gitignore

@@ -0,0 +1,42 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+
+# Virtual environment
+.venv/
+venv/
+env/
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# Ruff
+.ruff_cache/
+
+# ty
+.ty/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment variables
+.env
+.env.local

.python-version

@@ -0,0 +1 @@
+3.13

.rumdl.toml

@@ -0,0 +1,24 @@
+# rumdl configuration file
+
+# Global configuration options
+[global]
+# List of rules to disable (uncomment and modify as needed)
+disable = ["MD013", "MD033", "MD041", "MD036"]
+
+# List of file/directory patterns to exclude from linting
+exclude = [
+    # Common directories to exclude
+    ".git",
+    ".github",
+    "node_modules",
+    "vendor",
+    "dist",
+    "build",
+    ".venv",
+    "venv",
+    "__pycache__",
+    "*.egg-info",
+
+    # Specific files or patterns
+    "CHANGELOG.md",
+]

AGENTS.md

@@ -0,0 +1,67 @@
+# Shellflow Agent Instructions
+
+## Project Overview
+
+Shellflow is a minimal shell script orchestrator with SSH support. It allows users to write shell scripts that execute across local and remote environments using simple comment markers.
+
+## Project Structure
+
+```text
+shellflow/
+├── src/shellflow.py    # Main module with all functionality
+├── tests/               # Unit tests (pytest)
+├── features/            # BDD acceptance tests (behave)
+│   ├── parser.feature
+│   ├── runner.feature
+│   ├── steps/shellflow_steps.py
+│   └── environment.py
+├── behave_runner.py     # Wrapper for running behave
+├── pyproject.toml       # Project configuration
+├── README.md            # Documentation
+└── AGENTS.md           # This file
+```
+
+## Core Concepts
+
+### Script Block Markers
+
+- `# @LOCAL` - Start a local execution block
+- `# @REMOTE <host>` - Start a remote execution block
+
+### Key Modules
+
+- `Block` - Represents an execution block (local or remote)
+- `ExecutionContext` - Passes state between block executions
+- `ExecutionResult` - Result of executing a single block
+- `RunResult` - Result of running a complete script
+- `SSHConfig` - SSH configuration for remote hosts
+
+### CLI Commands
+
+```bash
+shellflow run <script>    # Run a shellflow script
+shellflow run <script> -v # Run with verbose output
+shellflow --version       # Show version
+```
+
+## Development Commands
+
+```bash
+just format      # Format code with ruff
+just lint        # Lint with ruff
+just test        # Run pytest
+just bdd         # Run behave BDD tests
+just test-all   # Run format, lint, test, and bdd
+just typecheck  # Type check with ty
+```
+
+## Testing
+
+- Unit tests: `pytest` under `tests/`
+- BDD tests: `behave` under `features/`
+- Run all: `just test-all`
+
+## Dependencies
+
+- Runtime: `paramiko>=3.0.0`
+- Dev: `pytest`, `behave`, `ruff`, `ty`, `hypothesis`

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

Justfile

@@ -0,0 +1,85 @@
+# Default recipe to display help
+default:
+  @just --list
+
+# Sync all dependencies
+sync:
+  uv sync --all-groups
+
+# Format all code
+format:
+  rumdl fmt .
+  uv run ruff format .
+  uv run ruff check --fix .
+
+# Auto-fix linting issues
+fix:
+  rumdl check --fix .
+  uv run ruff check --fix .
+
+# Run all lints
+lint:
+  typos
+  rumdl check .
+  uv run ruff check .
+  uv run ruff format --check .
+  uv run ty check src tests
+
+# Run tests
+test:
+  uv run pytest
+
+# Run BDD scenarios
+bdd:
+  uv run behave
+
+# Run both TDD and BDD suites
+test-all:
+  uv run pytest
+  uv run behave
+
+# Run tests with coverage
+test-coverage:
+  uv run pytest --cov=uv_app --cov-report=term-missing --cov-report=html
+
+# Run benchmarks
+bench:
+  uv run pytest -m benchmark --benchmark-only
+
+# Build the package
+build:
+  uv build
+
+# Type check with ty
+typecheck:
+  uv run ty check src tests
+
+# Check for Chinese characters
+check-cn:
+  rg --line-number --column "\p{Han}"
+
+# Full CI check
+ci: lint test-all build
+
+# ============================================================
+# Maintenance & Tools
+# ============================================================
+
+# Clean build artifacts
+clean:
+  rm -rf dist/ .pytest_cache/ .ruff_cache/ htmlcov/ .coverage
+  find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+  find . -type d -name "*.egg-info" -exec rm -rf {} + 2>/dev/null || true
+
+# Install all required development tools
+setup:
+  uv sync --all-groups
+  cargo install typos-cli
+
+# Lock dependencies
+lock:
+  uv lock
+
+# Update all dependencies
+update:
+  uv lock --upgrade

README.md

@@ -0,0 +1,163 @@
+# Shellflow
+
+A minimal shell script orchestrator with SSH support. Shellflow allows you to write shell scripts that execute across local and remote environments using simple comment markers.
+
+## Features
+
+- **Block-based execution**: Use comment markers to define local and remote execution blocks
+- **SSH support**: Automatically reads SSH configuration from `~/.ssh/config`
+- **Fail-fast execution**: Stops on first error with clear error reporting
+- **Context passing**: The previous block output is passed via `SHELLFLOW_LAST_OUTPUT`
+- **CLI interface**: Simple command-line tool for running scripts
+
+## Installation
+
+```bash
+# Install the package and dependencies
+uv sync --all-groups
+
+# Install in development mode
+uv pip install -e .
+```
+
+## Usage
+
+### Writing Scripts
+
+Shellflow scripts use comment markers to define execution blocks:
+
+```bash
+# @LOCAL
+echo "Running locally"
+
+# @REMOTE myserver
+echo "Running on myserver"
+
+# @LOCAL
+echo "Back to local"
+```
+
+### Running Scripts
+
+```bash
+# Run a script
+shellflow run script.sh
+
+# Run with verbose output
+shellflow run script.sh --verbose
+shellflow run script.sh -v
+
+# Use a non-default SSH config file
+shellflow run script.sh --ssh-config ./ssh_config
+```
+
+### SSH Configuration
+
+Shellflow reads SSH configuration from `~/.ssh/config`. The following options are supported:
+
+```ssh
+Host myserver
+    HostName 192.168.1.100
+    User admin
+    Port 2222
+    IdentityFile ~/.ssh/myserver_key
+```
+
+If `paramiko` is installed, it will be used for parsing. Otherwise, a basic parser is used as fallback.
+
+### Execution Model
+
+Blocks are intentionally stateless. Shell state such as `cd`, shell variables, and `export` commands do not persist into the next block. If you need to pass data forward, use the previous block output via `SHELLFLOW_LAST_OUTPUT`:
+
+```bash
+# @LOCAL
+echo "Step 1 output"
+
+# @LOCAL
+echo "Previous output was: $SHELLFLOW_LAST_OUTPUT"
+```
+
+Lines before the first marker, such as a shebang or shared shell options, are prepended to every block. That lets you define common guardrails once:
+
+```bash
+#!/bin/bash
+set -euo pipefail
+
+# @LOCAL
+echo "runs with the shared prelude"
+
+# @REMOTE myserver
+echo "remote block gets the same prelude"
+```
+
+## Testing
+
+### Unit Tests (pytest)
+
+Run unit tests with pytest:
+
+```bash
+# Run all tests
+just test
+
+# Run specific test file
+uv run pytest tests/test_shellflow.py
+
+# Run with coverage
+uv run pytest --cov=shellflow --cov-report=term-missing
+```
+
+### BDD Tests (behave)
+
+Run acceptance tests with behave:
+
+```bash
+# Run BDD tests
+just bdd
+
+# Or directly
+uv run behave
+```
+
+### Running All Tests
+
+```bash
+# Run format, lint, test, and BDD
+just test-all
+```
+
+## Development Commands
+
+```bash
+just format      # Format code with ruff
+just lint        # Lint with ruff
+just test        # Run pytest
+just bdd         # Run behave BDD tests
+just test-all   # Run format, lint, test, and bdd
+just typecheck  # Type check with ty
+```
+
+## Project Structure
+
+```text
+shellflow/
+├── src/shellflow.py    # Main module
+├── tests/              # Unit tests
+├── features/           # BDD feature files
+│   ├── parser.feature
+│   └── runner.feature
+├── pyproject.toml      # Project configuration
+└── README.md
+```
+
+## CLI Reference
+
+```text
+shellflow run <script>    # Run a shellflow script
+shellflow run <script> -v # Run with verbose output
+shellflow --version       # Show version
+```
+
+## License
+
+Apache-2.0