routine-workflow 10.0.0

Automated routine workflow runner for repository hygiene, backups, and dumps orchestration and much more.

Routine Workflow

Production-grade automation for repository hygiene: code reformatting, cache cleaning, backups, dumps orchestration, and security auditing.

routine_workflow is a robust, "batteries-included" Python tool designed to automate the mundane but critical maintenance tasks of your repository. Whether running in a CI pipeline or on a local developer machine, it ensures your project stays clean, secure, and well-formatted with a single command.

---

🚀 Quick Start

Prerequisites

• Python 3.9+
• pip

Installation

Install from PyPI with a single command:

pip install routine-workflow

Tip For an enhanced CLI experience with rich formatting and colors, install with the rich extra: pip install "routine-workflow[rich]"

Usage Example

Run the default workflow in safe mode (Dry-Run):

routine-workflow

Execute the full workflow (Real Run):

routine-workflow -nd -y

Run specific steps using Aliases:

routine-workflow -s reformat clean backup -nd

---

✨ Key Features

• 🛡️ Safe by Default: Ships with dry-run enabled to prevent accidental changes.
• 🧠 Interactive Mode: Guided wizard to configure steps and options on the fly.
• ⚙️ Extensible Step Runner: Run steps in any order, repeat them, or run a custom selection.
• 🧩 Alias-Driven: Use intuitive aliases like reformat, clean, pytest, or audit.
• ⚡ Parallel Execution: Utilizes multi-core processing for supported tasks to save time.
• ✅ Integrated Testing: Run your pytest suite as part of the hygiene workflow.
• 🔒 Concurrency Safe: Robust file-based locking prevents multiple instances from stepping on each other.
• 🔍 Security & Auditing: God Level integration of security scans (bandit, safety) and dependency auditing.
• 📊 Performance Profiling: Built-in --profile mode to analyze step execution times.
• 🪝 Pre-commit Ready: Easily install as a pre-commit hook with --install-pre-commit.
• 📝 Advanced Logging: JSON output, log rotation, and configurable verbosity levels.
• ✍️ Git Integration: Automatically commit and push a hygiene snapshot after a successful run.

---

⚙️ Configuration & Advanced Usage

Environment Variables

You can configure defaults via environment variables or a .env file (if supported by your environment loader).

Variable	Description	Default
PROJECT_ROOT	Root directory of the project.	CWD
LOG_DIR	Directory for log files.	/sdcard/tools/logs
LOCK_DIR	Directory for the lock file.	/tmp/routine_workflow.lock
LOCK_TTL	Lock time-to-live in seconds.	3600
WORKFLOW_TIMEOUT	Overall workflow timeout in seconds.	0 (Disabled)
FAIL_ON_BACKUP	Set to 1 to fail if backup fails.	0
GIT_PUSH	Set to 1 to enable git push.	0
ENABLE_SECURITY	Set to 1 to enable security scans.	0
ENABLE_DEP_AUDIT	Set to 1 to enable dependency audit.	0
LOG_LEVEL	Logging verbosity (DEBUG, INFO, etc.).	INFO
LOG_FORMAT	Log format (text or json).	text

CLI Arguments

Below is the complete list of arguments available in routine-workflow:

Flag	Description	Default
-p, --project-root	Path to the project root.	CWD
-l, --log-dir	Directory to write logs.	/sdcard/tools/logs
--log-file	Optional single log file path.	None
--lock-dir	Directory for lock file.	/tmp/routine_workflow.lock
--lock-ttl	Lock eviction TTL in seconds (0=disable).	3600
--log-level	Logging verbosity (DEBUG, INFO, etc.).	INFO
--log-format	Log format (text or json).	text
--log-rotation-max-bytes	Max bytes per log file before rotation.	5MB
--log-rotation-backup-count	Number of backup log files to keep.	5
--fail-on-backup	Exit if backup step fails.	False
-y, --yes	Auto-confirm prompts.	False
-d, --dry-run	Dry-run mode (default).	True
-nd, --no-dry-run	Disable dry-run (perform real execution).	False
-w, --workers	Parallel workers.	min(8, CPU)
-t, --workflow-timeout	Overall timeout in seconds.	0
-s, --steps	Specific steps/aliases to run.	All
--test-cov-threshold	Pytest coverage threshold.	85
--git-push	Enable git commit/push in step 6.	False
-es, --enable-security	Enable security scan (step 3.5).	False
-eda, --enable-dep-audit	Enable dependency audit (step 6.5).	False
--profile	Profile execution time of steps.	False
--install-pre-commit	Install routine-workflow hook.	False
-i, --interactive	Enter interactive configuration mode.	False
--create-dump-run-cmd	Override create-dump run command.	None
--exclude-patterns	Override default exclude patterns.	None
--version	Show program's version.	N/A

---

🏗️ Architecture

The routine-workflow follows a clean src/ layout with modular components.

src/routine_workflow/
├── __init__.py
├── banner.py           # CLI Banner & Art
├── cli.py              # Entry point & Argument Parsing
├── config.py           # Configuration Dataclass
├── defaults.py         # Default Settings
├── lock.py             # Concurrency Control
├── runner.py           # Workflow Orchestrator
├── steps/              # Modular Step Definitions
│   ├── step1.py        # Delete Dumps
│   ├── step2.py        # Reformat Code
│   ├── step2_5.py      # Pytest Runner
│   ├── step3.py        # Clean Caches
│   ├── step3_5.py      # Security Scan
│   ├── step4.py        # Backup
│   ├── step5.py        # Create Dumps
│   ├── step6.py        # Git Operations
│   └── step6_5.py      # Dependency Audit
└── utils.py            # Helpers

Core Flow:

1. Config Loading: Loads defaults, env vars, and CLI args into a WorkflowConfig object.
2. Lock Acquisition: Ensures only one instance runs via lock.py.
3. Step Resolution: Maps requested aliases (e.g., audit) to step modules (e.g., step6_5.py).
4. Execution: The WorkflowRunner executes steps sequentially, handling logging and errors.
5. Report: Generates a summary of the run.

---

🗺️ Roadmap

Upcoming vs. Completed Features:

✅ Completed

• Core Essentials: CLI entrypoint, step runner, reformatting (ruff, isort), cache cleaning, and concurrency locking.
• Integration: pytest integration, backup orchestration, and git snapshotting.
• Security: Security scanning (bandit, safety) and dependency auditing.
• Advanced Usage: Interactive mode, performance profiling, and pre-commit hook generation.
• Observability: Advanced JSON logging and rotation.

🔮 Upcoming

• Ecosystem: 3rd party plugins architecture and official Docker image.
• Integrations: Webhook notifications (Slack/Discord) and CI/CD blueprints.
• Visionary: AI-powered code analysis and automated refactoring.
• Sandbox: Gamification and experimental "chaos mode" features.

---

🤝 Contributing & License

We welcome contributions! Please see CONTRIBUTING.md (if available) or open a PR.

License: This project is licensed under the MIT License.