Metadata-Version: 2.4
Name: masterchief
Version: 2.2.8
Summary: Enterprise DevOps Automation Platform
Home-page: https://github.com/jbalestrine/masterchief
Author: MasterChief Team
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Systems Administration
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: flask>=3.0.0
Requires-Dist: flask-cors>=4.0.0
Requires-Dist: Flask-Login>=0.6.0
Requires-Dist: Flask-SocketIO>=5.0.0
Requires-Dist: werkzeug>=3.0.0
Requires-Dist: python-socketio>=5.0.0
Requires-Dist: python-engineio>=4.0.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: requests>=2.31.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: click>=8.1.0
Requires-Dist: rich>=13.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: cryptography>=46.0.5
Requires-Dist: cffi>=2.0.0
Requires-Dist: PyJWT>=2.8.0
Requires-Dist: authlib>=1.3.0
Requires-Dist: jsonschema>=4.17.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: bcrypt>=4.0.0
Requires-Dist: python-jose>=3.3.0
Requires-Dist: apscheduler>=3.10.0
Requires-Dist: sqlalchemy>=2.0.0
Requires-Dist: gitpython>=3.1.0
Requires-Dist: git-filter-repo>=2.47.0
Requires-Dist: irc>=20.0.0
Requires-Dist: gunicorn>=21.0.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: Pillow>=10.0.0
Requires-Dist: prometheus-client>=0.19.0
Provides-Extra: cloud
Requires-Dist: azure-identity>=1.15.0; extra == "cloud"
Requires-Dist: azure-mgmt-resource>=23.0.0; extra == "cloud"
Requires-Dist: azure-mgmt-compute>=30.0.0; extra == "cloud"
Requires-Dist: azure-mgmt-storage>=21.0.0; extra == "cloud"
Requires-Dist: azure-core>=1.29.0; extra == "cloud"
Requires-Dist: azure-devops>=7.1.0b4; extra == "cloud"
Requires-Dist: boto3>=1.34.0; extra == "cloud"
Requires-Dist: kubernetes>=28.0.0; extra == "cloud"
Requires-Dist: docker>=7.0.0; extra == "cloud"
Requires-Dist: hvac>=2.0.0; extra == "cloud"
Requires-Dist: paramiko>=3.4.0; extra == "cloud"
Requires-Dist: python-gitlab>=4.0.0; extra == "cloud"
Requires-Dist: PyGithub>=2.1.0; extra == "cloud"
Provides-Extra: ansible
Requires-Dist: ansible>=9.0.0; extra == "ansible"
Provides-Extra: ai
Requires-Dist: torch>=2.0.0; extra == "ai"
Requires-Dist: torchaudio>=2.0.0; extra == "ai"
Requires-Dist: torchvision>=0.15.0; extra == "ai"
Requires-Dist: transformers>=4.35.0; extra == "ai"
Requires-Dist: diffusers>=0.21.0; extra == "ai"
Requires-Dist: accelerate>=0.25.0; extra == "ai"
Requires-Dist: peft>=0.6.0; extra == "ai"
Requires-Dist: safetensors>=0.4.0; extra == "ai"
Requires-Dist: sentence-transformers>=2.2.0; extra == "ai"
Requires-Dist: faiss-cpu>=1.7.4; extra == "ai"
Requires-Dist: huggingface-hub>=0.19.0; extra == "ai"
Requires-Dist: tokenizers>=0.15.0; extra == "ai"
Requires-Dist: llama-cpp-python>=0.2.0; python_version < "3.14" and extra == "ai"
Requires-Dist: gguf>=0.1.0; extra == "ai"
Requires-Dist: numpy>=1.24.0; extra == "ai"
Requires-Dist: scipy>=1.10.0; extra == "ai"
Requires-Dist: scikit-learn>=1.3.0; extra == "ai"
Provides-Extra: audio
Requires-Dist: pyttsx3>=2.90; extra == "audio"
Requires-Dist: openai-whisper>=20231117; extra == "audio"
Requires-Dist: sounddevice>=0.4.6; extra == "audio"
Requires-Dist: soundfile>=0.12.1; extra == "audio"
Requires-Dist: librosa>=0.10.0; extra == "audio"
Requires-Dist: pygame>=2.5.0; extra == "audio"
Requires-Dist: webrtcvad>=2.0.10; extra == "audio"
Requires-Dist: openwakeword>=0.5.0; extra == "audio"
Requires-Dist: TTS>=0.22.0; extra == "audio"
Provides-Extra: async
Requires-Dist: aiokafka>=0.10.0; extra == "async"
Requires-Dist: pika>=1.3.0; extra == "async"
Requires-Dist: aiohttp>=3.9.0; extra == "async"
Requires-Dist: eventlet>=0.33.0; extra == "async"
Provides-Extra: database
Requires-Dist: redis>=5.0.0; extra == "database"
Requires-Dist: psycopg2-binary>=2.9.0; extra == "database"
Requires-Dist: asyncpg>=0.29.0; extra == "database"
Requires-Dist: aiomysql>=0.2.0; extra == "database"
Requires-Dist: aiosqlite>=0.19.0; extra == "database"
Requires-Dist: motor>=3.3.0; extra == "database"
Requires-Dist: alembic>=1.13.0; extra == "database"
Requires-Dist: influxdb-client>=1.38.0; extra == "database"
Provides-Extra: extras
Requires-Dist: watchdog>=3.0.0; extra == "extras"
Requires-Dist: ollama>=0.1.0; extra == "extras"
Requires-Dist: croniter>=1.3.0; extra == "extras"
Requires-Dist: ruff>=0.1.0; extra == "extras"
Requires-Dist: statsd>=4.0.1; extra == "extras"
Requires-Dist: celery>=5.3.0; extra == "extras"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-mock>=3.12.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.1.0; extra == "dev"
Requires-Dist: mypy>=1.7.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: pylint>=3.0.0; extra == "dev"
Requires-Dist: types-PyYAML>=6.0.0; extra == "dev"
Requires-Dist: sphinx>=7.2.0; extra == "dev"
Requires-Dist: sphinx-rtd-theme>=2.0.0; extra == "dev"
Requires-Dist: ipython>=8.18.0; extra == "dev"
Requires-Dist: pre-commit>=3.6.0; extra == "dev"
Requires-Dist: build>=1.2.2; extra == "dev"
Requires-Dist: twine>=6.0.0; extra == "dev"
Provides-Extra: all
Requires-Dist: azure-identity>=1.15.0; extra == "all"
Requires-Dist: azure-mgmt-resource>=23.0.0; extra == "all"
Requires-Dist: azure-mgmt-compute>=30.0.0; extra == "all"
Requires-Dist: azure-mgmt-storage>=21.0.0; extra == "all"
Requires-Dist: azure-core>=1.29.0; extra == "all"
Requires-Dist: azure-devops>=7.1.0b4; extra == "all"
Requires-Dist: boto3>=1.34.0; extra == "all"
Requires-Dist: kubernetes>=28.0.0; extra == "all"
Requires-Dist: docker>=7.0.0; extra == "all"
Requires-Dist: hvac>=2.0.0; extra == "all"
Requires-Dist: paramiko>=3.4.0; extra == "all"
Requires-Dist: python-gitlab>=4.0.0; extra == "all"
Requires-Dist: PyGithub>=2.1.0; extra == "all"
Requires-Dist: ansible>=9.0.0; extra == "all"
Requires-Dist: torch>=2.0.0; extra == "all"
Requires-Dist: torchaudio>=2.0.0; extra == "all"
Requires-Dist: torchvision>=0.15.0; extra == "all"
Requires-Dist: transformers>=4.35.0; extra == "all"
Requires-Dist: diffusers>=0.21.0; extra == "all"
Requires-Dist: accelerate>=0.25.0; extra == "all"
Requires-Dist: peft>=0.6.0; extra == "all"
Requires-Dist: safetensors>=0.4.0; extra == "all"
Requires-Dist: sentence-transformers>=2.2.0; extra == "all"
Requires-Dist: faiss-cpu>=1.7.4; extra == "all"
Requires-Dist: huggingface-hub>=0.19.0; extra == "all"
Requires-Dist: tokenizers>=0.15.0; extra == "all"
Requires-Dist: llama-cpp-python>=0.2.0; python_version < "3.14" and extra == "all"
Requires-Dist: gguf>=0.1.0; extra == "all"
Requires-Dist: numpy>=1.24.0; extra == "all"
Requires-Dist: scipy>=1.10.0; extra == "all"
Requires-Dist: scikit-learn>=1.3.0; extra == "all"
Requires-Dist: pyttsx3>=2.90; extra == "all"
Requires-Dist: openai-whisper>=20231117; extra == "all"
Requires-Dist: sounddevice>=0.4.6; extra == "all"
Requires-Dist: soundfile>=0.12.1; extra == "all"
Requires-Dist: librosa>=0.10.0; extra == "all"
Requires-Dist: pygame>=2.5.0; extra == "all"
Requires-Dist: webrtcvad>=2.0.10; extra == "all"
Requires-Dist: openwakeword>=0.5.0; extra == "all"
Requires-Dist: TTS>=0.22.0; extra == "all"
Requires-Dist: aiokafka>=0.10.0; extra == "all"
Requires-Dist: pika>=1.3.0; extra == "all"
Requires-Dist: aiohttp>=3.9.0; extra == "all"
Requires-Dist: eventlet>=0.33.0; extra == "all"
Requires-Dist: redis>=5.0.0; extra == "all"
Requires-Dist: psycopg2-binary>=2.9.0; extra == "all"
Requires-Dist: asyncpg>=0.29.0; extra == "all"
Requires-Dist: aiomysql>=0.2.0; extra == "all"
Requires-Dist: aiosqlite>=0.19.0; extra == "all"
Requires-Dist: motor>=3.3.0; extra == "all"
Requires-Dist: alembic>=1.13.0; extra == "all"
Requires-Dist: influxdb-client>=1.38.0; extra == "all"
Requires-Dist: watchdog>=3.0.0; extra == "all"
Requires-Dist: ollama>=0.1.0; extra == "all"
Requires-Dist: croniter>=1.3.0; extra == "all"
Requires-Dist: ruff>=0.1.0; extra == "all"
Requires-Dist: statsd>=4.0.1; extra == "all"
Requires-Dist: celery>=5.3.0; extra == "all"
Requires-Dist: pytest>=7.4.0; extra == "all"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "all"
Requires-Dist: pytest-cov>=4.1.0; extra == "all"
Requires-Dist: pytest-mock>=3.12.0; extra == "all"
Requires-Dist: black>=23.0.0; extra == "all"
Requires-Dist: flake8>=6.1.0; extra == "all"
Requires-Dist: mypy>=1.7.0; extra == "all"
Requires-Dist: isort>=5.12.0; extra == "all"
Requires-Dist: pylint>=3.0.0; extra == "all"
Requires-Dist: types-PyYAML>=6.0.0; extra == "all"
Requires-Dist: sphinx>=7.2.0; extra == "all"
Requires-Dist: sphinx-rtd-theme>=2.0.0; extra == "all"
Requires-Dist: ipython>=8.18.0; extra == "all"
Requires-Dist: pre-commit>=3.6.0; extra == "all"
Requires-Dist: build>=1.2.2; extra == "all"
Requires-Dist: twine>=6.0.0; extra == "all"
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# MasterChief V4 Recovery / Restoration Guide

MasterChief is a modular platform for DevOps, automation, dashboards, addon hosting, and AI-assisted operational workflows. This repository represents the recovered and stabilized state of the app after a major restoration pass, with route inventory corrected, dashboard navigation rebuilt, diagnostics repaired, additive feature wiring restored, and the app brought back to a working, navigable condition.

This README is meant to be both a working developer guide and a fail-safe operational document. It specifically emphasizes how to protect the current working state, create safe release branches, and roll back quickly if a deployment or code change causes issues.

## Current Recovery Status

The current branch state is intended to preserve a usable, repaired project while keeping a clean rollback path.

Key restoration areas include:
- core dashboard startup and runtime initialization
- route mapping and route inventory recovery
- UI and menu restoration
- diagnostics and system health API recovery
- gallery and metadata operations
- addon/module loading and dynamic route safety
- Echo chat and voice command support
- general project stability and route coverage

This repo should be treated as a working operational platform, not a throwaway prototype. The project has been repaired, extended, and stabilized enough to be used and released with caution.

## Critical Safety Principle

Do not push directly from the active working directory unless you have verified the branch, commit set, and release scope.

The safest process is:
- keep the current live project directory as-is
- create a dedicated release branch for the recovered work
- back up the project directory before major changes
- tag and push only the intended release branch
- keep the old version available as a reference and rollback target

## Recommended Branch Strategy

Use a separate release branch so the old version remains available for restore.

Suggested pattern:
- masterchief-V4: recovered and stabilized release branch
- legacy/backups: preserved old version branch or archived copy

Example:

```powershell
git checkout -b masterchief-V4
```

If you want to preserve an older branch for posterity instead of touching it:

```powershell
git checkout -b retro-version
```

This keeps the older version intact while allowing the recovered version to move forward cleanly.

## Backup Before Any Risky Move

Before any commit, tag, or push, create a backup of the working directory.

### Windows backup example

```powershell
Copy-Item -Recurse -Force "C:\Users\Echo\masterchief" "C:\Users\Echo\masterchief-backup-$(Get-Date -Format yyyyMMdd-HHmmss)"
```

### Alternative archive example

```powershell
Compress-Archive -Path "C:\Users\Echo\masterchief" -DestinationPath "C:\Users\Echo\masterchief-backup-$(Get-Date -Format yyyyMMdd-HHmmss).zip" -Force
```

This is the safest fail-safe if anything goes wrong during a release or branch change.

## Fast Fail-Safe Rollback

If something breaks after a push, tag, merge, or release attempt, use the following rollback path.

### Option 1: Roll back to the last good commit

```powershell
git log --oneline --decorate --max-count=20
git checkout <last-good-commit>
```

or if you want to reset the current branch cleanly:

```powershell
git reset --hard <last-good-commit>
```

### Option 2: Revert a recent bad commit

```powershell
git revert <commit-sha>
```

### Option 3: Restore from backup folder

If the repo or working directory becomes unsafe:

```powershell
Copy-Item -Recurse -Force "C:\Users\Echo\masterchief-backup-<timestamp>" "C:\Users\Echo\masterchief"
```

or if you archived it:

```powershell
Expand-Archive -Path "C:\Users\Echo\masterchief-backup-<timestamp>.zip" -DestinationPath "C:\Users\Echo"
```

## Safe Release Workflow

Before pushing, do not use broad staging commands such as:

```powershell
git add .
```

Instead, stage intentionally:

```powershell
git status
git add -p
git diff --cached --name-only
```

Then review exactly what is being included.

### Example release tag

```powershell
git tag -a v0.9.0 -m "MasterChief V4 recovery release"
git push origin masterchief-V4 --follow-tags
```

This creates a clean, recordable version marker for the recovered build.

## Fresh Setup

Install Python 3.10 or newer and Git first. From the parent folder, paste the one-line command for your shell; it clones the repository, installs the base app and bundled modules into a virtual environment, registers the CLI, and starts the web app.

### Windows PowerShell

```powershell
git clone https://github.com/jbalestrine/masterchief.git; if ($LASTEXITCODE -ne 0) { throw 'Clone failed' }; Set-Location masterchief; Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned; .\MasterchiefRun.ps1
```

### Linux or macOS

```bash
git clone https://github.com/jbalestrine/masterchief.git && cd masterchief && bash scripts/start.sh
```

If the repository is already cloned, run `.\MasterchiefRun.ps1` in PowerShell or `bash scripts/start.sh` on Linux/macOS. For prompted profiles and advanced options, use [MASTER_SETUP.ps1](MASTER_SETUP.ps1). Optional AI, audio, and cloud dependencies are available through `requirements-optional.txt` or the package extras.

For a prebuilt Python package install, use `python -m pip install masterchief` and then `masterchief --help`. See [QUICKSTART.md](QUICKSTART.md) for additional setup options.

## Release PyPI and Chocolatey Together

The single release entry point is [CHOCO_PYPI_DEPLOY.ps1](CHOCO_PYPI_DEPLOY.ps1). First update `setup.py` to a new version, commit the intended source, create and push a matching `v*` tag, then run from that tagged checkout. Tag pushes run package-build validation only; they do not publish separately.

In `/secrets`, add encrypted entries named `TWINE_PASSWORD` and `CHOCOLATEY_API_KEY`. Choose `API Key` for `TWINE_PASSWORD` and `Chocolatey API Key` for `CHOCOLATEY_API_KEY`. Then run:

```powershell
.\CHOCO_PYPI_DEPLOY.ps1 -DryRun
.\CHOCO_PYPI_DEPLOY.ps1 -UseVault
```

The script reads the secrets from the local encrypted Vault, builds both packages from the exact tag, verifies availability and metadata, uploads Chocolatey first and PyPI second, then clears any Vault-loaded values from its process environment. Registry uploads are not atomic: if the PyPI upload fails after Chocolatey accepts the package, fix PyPI and check both package pages before retrying.

## Core Application Layout

This project is organized around a central Flask app and modular runtime components.

### Main entry points
- main.py: application bootstrap, routes, UI shell, and app wiring
- templates/: dashboard and HTML shell assets
- blueprints/: modular route groups and feature surfaces
- features/: feature registration and manager logic
- data/: persistent app data and uploaded/generated content
- echo/: echo chat, prompt flow, and runtime logic
- addons/, modules/, scripts/: extension and automation surfaces

## Notable Functional Areas Restored

- route inventory and app shell recovery
- dashboard navigation and menu system restoration
- diagnostics and system route health checks
- gallery screens and upload workflow
- module loading and dynamic route startup safety
- Echo chat and voice command UI interactions
- internal feature manager and plugin-style registration
- platform configuration and runtime safe fallback behavior

## Do Not Do This Without Verifying

Avoid the following when preparing a release:
- force-pushing without a backup
- staging every changed file indiscriminately
- pushing from a dirty working tree without review
- replacing an old branch with a new one unless you deliberately intend to do so
- deleting the old version before preserving a restore copy

## Release Checklist

Before a push, confirm all of the following:
- project backup has been created
- working tree is reviewed
- only intended files are staged
- branch is a dedicated recovery/release branch
- version tag is created
- push is limited to the release branch and tags
- rollback path is documented and preserved

## Example Safe Commands

```powershell
# 1) create backup
Copy-Item -Recurse -Force "C:\Users\Echo\masterchief" "C:\Users\Echo\masterchief-backup-$(Get-Date -Format yyyyMMdd-HHmmss)"

# 2) branch cleanly
git checkout -b masterchief-V4

# 3) stage intentionally
git add -p

git diff --cached --name-only

# 4) commit
git commit -m "Restore app stability and dashboard functionality"

# 5) tag
git tag -a v0.9.0 -m "MasterChief V4 recovery release"

# 6) push
git push origin masterchief-V4 --follow-tags
```

## Troubleshooting Notes

If the app fails to start or route pages stop working:
1. restore from the latest backup
2. verify the app entrypoint is still main.py
3. confirm required runtime files still exist under data/ and templates/
4. check for stale artifact directories or local generated folders that may have drifted
5. revert only the last bad commit instead of a broad rollback

## Recommended Operating Principle

Treat this repository as a living operational system with a documented rollback path. The key to preserving progress is to keep old versions intact, create new release branches, and always have a backup ready before changing the repo state.

## License

This project should be treated according to the repository's existing licensing terms. See the included LICENSE file if present in the project root.

## Final Notes

This V4 recovery version is a meaningful milestone: the app is functional again, the key route structure is restored, and the system has been repaired enough to continue forward safely. The safest release is not the fastest push; it is the one that preserves the old version and allows a clean rollback if the new version has issues.
