Skip to content

GITHUB.md

Latest commit

 

History

History
212 lines (163 loc) · 5.05 KB

GITHUB.md

File metadata and controls

212 lines (163 loc) · 5.05 KB
Raw

ExecuTrace - GitHub Repository

📦 Project Overview

ExecuTrace is a Python library and CLI tool that captures, records, and replays developer workflows reliably. This repository contains the complete source code for the project.

🚀 Available on PyPI

This project is published on PyPI and can be installed globally:

pip install exectrace-workflow

PyPI Link: https://pypi.org/project/exectrace-workflow/

📋 Latest Release

Version: 1.0.1
Release Date: April 6, 2026
PyPI: https://pypi.org/project/exectrace-workflow/1.0.1/

🎯 Core Features

Recording

  • Captures terminal commands from shell history (bash, zsh)
  • Tracks file system changes (create, modify, delete)
  • Saves workflow metadata (timestamps, user, environment)

Storage

  • Dual Format Support:
    • JSON (human-readable, version control friendly)
    • XML (structured, enterprise-compatible)
  • Flexible storage paths
  • Automatic backup support

Replay Modes

  • Dry-run: Preview changes without executing
  • Explain: Show what will happen step-by-step
  • Smart: Execute with intelligent error handling

CLI Interface

Commands available:

  • exectrace record <name> - Start recording a workflow
  • exectrace stop - Stop recording
  • exectrace replay <name> - Replay a workflow
  • exectrace list - Show all workflows
  • exectrace edit <name> - Edit a workflow
  • exectrace delete <name> - Delete a workflow

📁 Repository Structure

ExecuTrace/
├── exectrace/              # Main package
│   ├── cli.py             # CLI interface
│   ├── core/              # Core modules
│   │   ├── editor.py
│   │   ├── models.py
│   │   └── replayer.py
│   ├── recorder/          # Recording functionality
│   │   ├── command_capture.py
│   │   ├── fs_tracker.py
│   │   └── session.py
│   ├── storage/           # Storage backends
│   │   ├── json_storage.py
│   │   ├── xml_storage.py
│   │   └── factory.py
│   └── utils/             # Utility modules
│       ├── hash_utils.py
│       ├── logger.py
│       ├── sensitive_filter.py
│       └── time_utils.py
├── examples/              # Example usage
│   └── basic_usage.py
├── pyproject.toml         # Package configuration
├── README.md              # User documentation
└── GITHUB.md              # This file

🛠️ Development Setup

Prerequisites

  • Python 3.9 or higher
  • pip or pip3

Clone and Install

git clone https://github.com/Stalin-143/ExecuTrace.git
cd ExecuTrace
pip install -e .

Virtual Environment (Recommended)

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .

🧪 Testing

Run the test suite:

python -m pytest tests/

Or test individual modules:

python -c "from exectrace.cli import main; main()"

📝 Usage Examples

Record a Workflow

# Start recording
exectrace record my-setup

# Run your commands
npm install
python -m build

# Stop recording
exectrace stop

Replay a Workflow

# Dry run (preview)
exectrace replay my-setup --dry-run

# Explain mode (step-by-step)
exectrace replay my-setup --explain

# Smart mode (execute with error handling)
exectrace replay my-setup --smart

List All Workflows

exectrace list

Shows workflows with storage format tags:

my-setup [json]
build-process [xml]
deploy-prod [json]

🔧 Features & Architecture

Workflow Model

Each workflow contains:

  • Name: Unique identifier
  • Actions: List of recorded commands and file changes
  • Metadata: Timestamps, user info, environment variables
  • Format: JSON or XML storage

Storage Factory Pattern

Dynamic storage backend selection:

from exectrace.storage.factory import get_storage

# Get storage backend
storage = get_storage("json", "/path/to/workflows")

Interactive CLI

User-friendly prompts for:

  • Storage location selection
  • File format preference (JSON/XML)
  • Workflow editing
  • Confirmation dialogs

📊 Python Requirements

  • Minimum: Python 3.9
  • Tested: Python 3.9, 3.10, 3.11, 3.12
  • Dependencies: None (stdlib only)

📄 License

MIT License - See LICENSE for details.

🤝 Contributing

We welcome contributions! Please:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-thing)
  3. Commit your changes (git commit -m "Add amazing thing")
  4. Push to the branch (git push origin feature/amazing-thing)
  5. Open a Pull Request

📞 Support

For issues, questions, or suggestions:

🎓 Learn More

Version: 1.0.1
Last Updated: April 6, 2026
Status: Production Ready ✅