gitops-by-veera 1.0.0__tar.gz

gitops_by_veera-1.0.0/.gitignore

@@ -0,0 +1,48 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+.env
+.venv
+venv/
+env/
+ENV/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Type checking
+.mypy_cache/
+.ruff_cache/
+
+# Editors
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+~/.gitpilot_by_veera.log
+
+# GitPilot runtime
+.gitpilot.lock
+~/.gitpilot_by_veera_config.json
+~/.gitpilot_by_veera.lock
+
+# Distribution
+*.tar.gz
+*.whl

gitops_by_veera-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Veerakumar C B
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gitops_by_veera-1.0.0/PKG-INFO

@@ -0,0 +1,269 @@
+Metadata-Version: 2.4
+Name: gitops-by-veera
+Version: 1.0.0
+Summary: Conversational autonomous Git and GitHub operations coordinator using Groq-hosted LLMs.
+Project-URL: Homepage, https://github.com/vkprince6/gitops-by-veera
+Project-URL: Repository, https://github.com/vkprince6/gitops-by-veera
+Project-URL: Bug Tracker, https://github.com/vkprince6/gitops-by-veera/issues
+Author: Veera
+License: MIT License
+        
+        Copyright (c) 2026 Veerakumar C B
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: automation,cli,git,github,groq,llm
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1.7
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: typing-extensions>=4.12.0
+Description-Content-Type: text/markdown
+
+# gitops-by-veera
+
+A production-ready, security-hardened, conversational autonomous Git and GitHub operations coordinator. Convert natural language into safe, validated local Git commands and GitHub REST API calls — powered by Groq-hosted LLMs.
+
+---
+
+## Features
+
+- **Natural language to Git/GitHub actions** — describe what you want, GitOps plans and executes it
+- **Dual-domain operations** — local Git commands and GitHub cloud API calls in a single pipeline
+- **Security-first architecture** — command injection prevention, path traversal blocking, shell injection defense, and prompt injection resistance
+- **Model cascading** — automatic fallback across three Groq-hosted model tiers
+- **Self-healing remediation** — failed operations trigger AI-generated fix suggestions (capped at 2 cycles)
+- **Direct evaluation bypass** — trivial commands (`git status`, `git diff`, `git log`) skip the LLM entirely for speed
+- **Structured JSON contracts** — all LLM output is parsed into strict Pydantic models
+- **Session telemetry** — detailed execution metrics available with `--debug`
+- **Colab/Jupyter compatible** — runs in notebooks, cloud runtimes, and local terminals
+
+---
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install gitops-by-veera
+```
+
+### From source
+
+```bash
+git clone https://github.com/vkprince6/gitops-by-veera.git
+cd gitops-by-veera
+pip install -e ".[dev]"
+```
+
+### Google Colab
+
+```python
+!pip install gitops-by-veera
+import subprocess
+subprocess.run(["git-ops", "setup"])
+```
+
+---
+
+## Credentials & Security
+
+GitOps requires two API credentials:
+
+| Credential | Environment Variable | Description |
+|---|---|---|
+| Groq API Key | `GROQ_API_KEY` | From [console.groq.com](https://console.groq.com) |
+| GitHub Token | `GITHUB_TOKEN` | Fine-grained PAT with repo read/write scopes |
+
+> **IMPORTANT:** Classic admin GitHub tokens are strictly prohibited.
+> You MUST use [fine-grained Personal Access Tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)
+> scoped to specific repositories with only the permissions required for your workflow.
+
+Credentials are stored at `~/.gitops_by_veera_config.json` with `chmod 600` permissions. They are **never** logged or printed to the terminal.
+
+---
+
+## Setup
+
+```bash
+git-ops setup
+```
+
+You will be prompted (via `getpass`) for your Groq API key and GitHub token. Alternatively, set environment variables:
+
+```bash
+export GROQ_API_KEY="gsk_..."
+export GITHUB_TOKEN="github_pat_..."
+```
+
+---
+
+## Usage
+
+### Run a natural language pipeline
+
+```bash
+git-ops run "Stage all files, commit with message 'feat: initial setup', and push to origin main"
+```
+
+### Dry-run (plan and validate only — no execution)
+
+```bash
+git-ops run "Create a branch called feature-xyz and push it" --dry-run
+```
+
+### Debug mode with telemetry
+
+```bash
+git-ops run "Open a PR from feature-xyz to main with title 'New Feature'" --debug
+```
+
+---
+
+## Supported Operations
+
+### Local Git
+
+| Operation | Risk Level |
+|---|---|
+| `git status`, `git diff`, `git log` | Safe |
+| `git add`, `git commit`, `git fetch`, `git pull` | Safe |
+| `git push`, `git branch`, `git checkout`, `git switch` | Safe |
+| `git reset --hard`, `git clean -fd`, `git push --force` | Warning — requires confirmation |
+| `git rebase`, `git cherry-pick`, `git stash clear` | Warning — requires confirmation |
+| `git filter-branch`, `git reflog expire`, `git gc --prune=now` | **Blocked** |
+
+### GitHub Cloud (via REST API)
+
+- Create repositories (`/user/repos`, `/orgs/{org}/repos`)
+- Manage branches and refs (`/repos/{owner}/{repo}/git/refs`)
+- Open, list, and update Pull Requests (`/repos/{owner}/{repo}/pulls`)
+- Merge Pull Requests (`/repos/{owner}/{repo}/pulls/{number}/merge`)
+- Create and update Issues (`/repos/{owner}/{repo}/issues`)
+- Trigger GitHub Actions workflows (`/repos/{owner}/{repo}/actions/workflows/{id}/dispatches`)
+
+> All `DELETE` requests and repository-level destructive endpoints are strictly blocked.
+
+---
+
+## Example Workflows
+
+```bash
+# View repository status (bypasses LLM entirely for speed)
+git-ops run "show status"
+
+# Full branch + commit + PR workflow
+git-ops run "Create branch feature-auth, commit staged files with message 'feat: add auth', push, and open a PR to main"
+
+# Create a GitHub issue
+git-ops run "Create an issue titled 'Bug: login fails on mobile' with a description"
+
+# Trigger a workflow dispatch
+git-ops run "Trigger the deploy.yml workflow on the main branch"
+```
+
+---
+
+## Google Colab Integration
+
+```python
+!pip install gitops-by-veera
+
+import os
+os.environ["GROQ_API_KEY"] = "gsk_..."      # or use Colab secrets
+os.environ["GITHUB_TOKEN"] = "github_pat_..."
+
+import subprocess
+result = subprocess.run(
+    ["git-ops", "run", "show git status", "--dry-run"],
+    capture_output=True, text=True
+)
+print(result.stdout)
+```
+
+---
+
+## Architecture
+
+```
+User prompt
+    │
+    ├── Direct Evaluation Router (regex bypass for trivial commands)
+    │       └── Returns plan immediately, skips LLM
+    │
+    └── LLM Cascade (Groq API)
+            ├── Tier 1: openai/gpt-oss-120b
+            ├── Tier 2: openai/gpt-oss-20b
+            └── Tier 3: llama-3.1-8b-instant (also used for remediation)
+                    │
+                    └── Pydantic-validated ExecutionPlan
+                            │
+                            └── Multi-stage Validator
+                                    ├── Binary whitelist enforcement
+                                    ├── Shell injection detection
+                                    ├── Path traversal blocking
+                                    ├── GitHub endpoint whitelist
+                                    └── Payload field sanitization
+                                            │
+                                            └── Sequential Executor
+                                                    ├── Local: subprocess.run (shell=False)
+                                                    └── Cloud: requests → GitHub REST API
+                                                            │
+                                                            └── Self-Healing Remediation (≤2 cycles)
+```
+
+---
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+
+# Run tests
+pytest --cov=src/gitops_by_veera --cov-report=term-missing
+
+# Type checking
+mypy src/
+
+# Linting
+ruff check src/ tests/
+```
+
+---
+
+## License
+
+MIT License — see [LICENSE](LICENSE).
+
+---
+
+## Security
+
+See [SECURITY.md](SECURITY.md) for the full security architecture and responsible disclosure policy.

gitops_by_veera-1.0.0/README.md

@@ -0,0 +1,220 @@
+# gitops-by-veera
+
+A production-ready, security-hardened, conversational autonomous Git and GitHub operations coordinator. Convert natural language into safe, validated local Git commands and GitHub REST API calls — powered by Groq-hosted LLMs.
+
+---
+
+## Features
+
+- **Natural language to Git/GitHub actions** — describe what you want, GitOps plans and executes it
+- **Dual-domain operations** — local Git commands and GitHub cloud API calls in a single pipeline
+- **Security-first architecture** — command injection prevention, path traversal blocking, shell injection defense, and prompt injection resistance
+- **Model cascading** — automatic fallback across three Groq-hosted model tiers
+- **Self-healing remediation** — failed operations trigger AI-generated fix suggestions (capped at 2 cycles)
+- **Direct evaluation bypass** — trivial commands (`git status`, `git diff`, `git log`) skip the LLM entirely for speed
+- **Structured JSON contracts** — all LLM output is parsed into strict Pydantic models
+- **Session telemetry** — detailed execution metrics available with `--debug`
+- **Colab/Jupyter compatible** — runs in notebooks, cloud runtimes, and local terminals
+
+---
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install gitops-by-veera
+```
+
+### From source
+
+```bash
+git clone https://github.com/vkprince6/gitops-by-veera.git
+cd gitops-by-veera
+pip install -e ".[dev]"
+```
+
+### Google Colab
+
+```python
+!pip install gitops-by-veera
+import subprocess
+subprocess.run(["git-ops", "setup"])
+```
+
+---
+
+## Credentials & Security
+
+GitOps requires two API credentials:
+
+| Credential | Environment Variable | Description |
+|---|---|---|
+| Groq API Key | `GROQ_API_KEY` | From [console.groq.com](https://console.groq.com) |
+| GitHub Token | `GITHUB_TOKEN` | Fine-grained PAT with repo read/write scopes |
+
+> **IMPORTANT:** Classic admin GitHub tokens are strictly prohibited.
+> You MUST use [fine-grained Personal Access Tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)
+> scoped to specific repositories with only the permissions required for your workflow.
+
+Credentials are stored at `~/.gitops_by_veera_config.json` with `chmod 600` permissions. They are **never** logged or printed to the terminal.
+
+---
+
+## Setup
+
+```bash
+git-ops setup
+```
+
+You will be prompted (via `getpass`) for your Groq API key and GitHub token. Alternatively, set environment variables:
+
+```bash
+export GROQ_API_KEY="gsk_..."
+export GITHUB_TOKEN="github_pat_..."
+```
+
+---
+
+## Usage
+
+### Run a natural language pipeline
+
+```bash
+git-ops run "Stage all files, commit with message 'feat: initial setup', and push to origin main"
+```
+
+### Dry-run (plan and validate only — no execution)
+
+```bash
+git-ops run "Create a branch called feature-xyz and push it" --dry-run
+```
+
+### Debug mode with telemetry
+
+```bash
+git-ops run "Open a PR from feature-xyz to main with title 'New Feature'" --debug
+```
+
+---
+
+## Supported Operations
+
+### Local Git
+
+| Operation | Risk Level |
+|---|---|
+| `git status`, `git diff`, `git log` | Safe |
+| `git add`, `git commit`, `git fetch`, `git pull` | Safe |
+| `git push`, `git branch`, `git checkout`, `git switch` | Safe |
+| `git reset --hard`, `git clean -fd`, `git push --force` | Warning — requires confirmation |
+| `git rebase`, `git cherry-pick`, `git stash clear` | Warning — requires confirmation |
+| `git filter-branch`, `git reflog expire`, `git gc --prune=now` | **Blocked** |
+
+### GitHub Cloud (via REST API)
+
+- Create repositories (`/user/repos`, `/orgs/{org}/repos`)
+- Manage branches and refs (`/repos/{owner}/{repo}/git/refs`)
+- Open, list, and update Pull Requests (`/repos/{owner}/{repo}/pulls`)
+- Merge Pull Requests (`/repos/{owner}/{repo}/pulls/{number}/merge`)
+- Create and update Issues (`/repos/{owner}/{repo}/issues`)
+- Trigger GitHub Actions workflows (`/repos/{owner}/{repo}/actions/workflows/{id}/dispatches`)
+
+> All `DELETE` requests and repository-level destructive endpoints are strictly blocked.
+
+---
+
+## Example Workflows
+
+```bash
+# View repository status (bypasses LLM entirely for speed)
+git-ops run "show status"
+
+# Full branch + commit + PR workflow
+git-ops run "Create branch feature-auth, commit staged files with message 'feat: add auth', push, and open a PR to main"
+
+# Create a GitHub issue
+git-ops run "Create an issue titled 'Bug: login fails on mobile' with a description"
+
+# Trigger a workflow dispatch
+git-ops run "Trigger the deploy.yml workflow on the main branch"
+```
+
+---
+
+## Google Colab Integration
+
+```python
+!pip install gitops-by-veera
+
+import os
+os.environ["GROQ_API_KEY"] = "gsk_..."      # or use Colab secrets
+os.environ["GITHUB_TOKEN"] = "github_pat_..."
+
+import subprocess
+result = subprocess.run(
+    ["git-ops", "run", "show git status", "--dry-run"],
+    capture_output=True, text=True
+)
+print(result.stdout)
+```
+
+---
+
+## Architecture
+
+```
+User prompt
+    │
+    ├── Direct Evaluation Router (regex bypass for trivial commands)
+    │       └── Returns plan immediately, skips LLM
+    │
+    └── LLM Cascade (Groq API)
+            ├── Tier 1: openai/gpt-oss-120b
+            ├── Tier 2: openai/gpt-oss-20b
+            └── Tier 3: llama-3.1-8b-instant (also used for remediation)
+                    │
+                    └── Pydantic-validated ExecutionPlan
+                            │
+                            └── Multi-stage Validator
+                                    ├── Binary whitelist enforcement
+                                    ├── Shell injection detection
+                                    ├── Path traversal blocking
+                                    ├── GitHub endpoint whitelist
+                                    └── Payload field sanitization
+                                            │
+                                            └── Sequential Executor
+                                                    ├── Local: subprocess.run (shell=False)
+                                                    └── Cloud: requests → GitHub REST API
+                                                            │
+                                                            └── Self-Healing Remediation (≤2 cycles)
+```
+
+---
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+
+# Run tests
+pytest --cov=src/gitops_by_veera --cov-report=term-missing
+
+# Type checking
+mypy src/
+
+# Linting
+ruff check src/ tests/
+```
+
+---
+
+## License
+
+MIT License — see [LICENSE](LICENSE).
+
+---
+
+## Security
+
+See [SECURITY.md](SECURITY.md) for the full security architecture and responsible disclosure policy.

gitops_by_veera-1.0.0/SECURITY.md

@@ -0,0 +1,121 @@
+# Security Policy — gitops-by-veera
+
+## Overview
+
+GitOps is designed with a security-first architecture at every layer. This document describes the protective mechanisms in place and how to report vulnerabilities responsibly.
+
+---
+
+## Credential Protection
+
+### Storage
+- Credentials are stored in `~/.gitops_by_veera_config.json` with `chmod 600` permissions (owner read/write only).
+- The file contains only `github_token` and `groq_api_key`. No other data is persisted.
+
+### Priority & Environment Variables
+- Credentials are loaded in priority order: environment variables (`GITHUB_TOKEN`, `GROQ_API_KEY`) first, then the config file.
+- Environment variables are never written to disk by GitOps.
+
+### Secret Redaction
+- A `SecretRedactionFilter` is applied to all log handlers. It scrubs:
+  - Known token patterns (`ghp_...`, `github_pat_...`, `ghs_...`, `gho_...`, `ghu_...`, `gsk_...`)
+  - `Authorization: Bearer ...` header content
+  - Exact runtime values of loaded credentials
+- Credentials never appear in log files, stack traces, standard error, or console output.
+
+---
+
+## Command Injection Prevention
+
+### Shell Execution Policy
+- `shell=True` is **never used** in any subprocess call. All commands are executed via `subprocess.run(..., shell=False)` with an explicit argument list.
+- The `cd` shell state mutation is never executed as a process. Directory context is passed exclusively via the `cwd` parameter of `subprocess.run`.
+
+### Binary Whitelist
+Only these executables are permitted: `git`, `pwd`, `mkdir`, `ls`. Any other binary is immediately rejected with a `ForbiddenBinaryError`.
+
+### Prohibited Token Detection
+The following characters and strings are blocked in all arguments:
+```
+; && || | > >> < $ ` $( sudo rm chmod chown curl wget python bash sh zsh powershell cmd.exe
+```
+Any argument containing these tokens raises a `CommandInjectionError` before execution.
+
+### Path Traversal Protection
+All arguments containing `..` are resolved and verified to remain within the detected repository root or current working directory. Escape attempts raise a `PathTraversalError`.
+
+---
+
+## Prompt Injection Defense
+
+### Untrusted Context Separation
+The system prompt explicitly instructs the LLM to treat all local workspace context — repository files, commit messages, issue bodies, README content, CI configuration, branch names — as **untrusted input**.
+
+### Policy Sovereignty
+The system enforces an absolute security boundary. The LLM is instructed to completely reject any directive that conflicts with the established execution policy, regardless of origin. No repository artifact can override the system's security constraints.
+
+### Structured Output Enforcement
+All LLM outputs are parsed into strict Pydantic models. Free-form text responses, markdown-wrapped JSON, and schema-mismatched outputs are rejected immediately, triggering model cascade fallback. No unvalidated loose dictionary parsing is performed.
+
+---
+
+## GitHub API Security
+
+### Endpoint Whitelist
+Only the following GitHub REST API endpoints are permitted:
+- `GET/POST /user/repos`
+- `POST /orgs/{org}/repos`
+- `GET/POST/PATCH /repos/{owner}/{repo}/issues[/{number}]`
+- `GET/POST/PATCH /repos/{owner}/{repo}/pulls[/{number}]`
+- `POST /repos/{owner}/{repo}/pulls/{number}/reviews`
+- `PUT /repos/{owner}/{repo}/pulls/{number}/merge`
+- `POST /repos/{owner}/{repo}/actions/workflows/{id}/dispatches`
+- `GET/POST /repos/{owner}/{repo}/git/refs[/{ref}]`
+
+Any endpoint not matching this whitelist raises a `CloudEndpointViolationError`.
+
+### DELETE Method Block
+All `DELETE` HTTP requests are unconditionally rejected with a `SecurityViolationError`. Repository deletion and any other destructive resource removal is impossible.
+
+### Payload Sanitization
+Cloud operation payloads are sanitized against per-endpoint field allowlists. Unknown, suspicious, or excessively nested keys are stripped before transmission. This prevents parameter injection via LLM-generated payloads.
+
+---
+
+## Git History Rewrite Safeguards
+
+The following operations are **strictly blocked** and cannot be executed under any circumstances:
+- `git filter-branch`
+- `git reflog expire`
+- `git gc --prune=now`
+
+The following operations require **explicit user confirmation** at runtime:
+- `git reset --hard`
+- `git clean -fd`
+- `git branch -D`
+- `git push --force` / `git push -f`
+- `git rebase`
+- `git cherry-pick`
+- `git stash clear`
+
+---
+
+## Concurrency Safety
+
+A PID-based lockfile prevents multiple simultaneous GitOps instances from running in the same repository. Stale locks (from crashed processes) are detected via OS-level PID existence checks and cleaned up automatically.
+
+---
+
+## Token Requirements
+
+GitOps requires **fine-grained Personal Access Tokens** only. Classic admin tokens are explicitly prohibited in documentation and enforced through user-facing warnings during setup. Fine-grained tokens should be scoped to:
+- Specific repositories (not all repositories)
+- Minimum required permissions (Contents: Read & Write, Pull Requests: Read & Write, Issues: Read & Write, Actions: Read & Write)
+
+---
+
+## Responsible Disclosure
+
+If you discover a security vulnerability, please report it privately by opening a [GitHub Security Advisory](https://docs.github.com/en/code-security/security-advisories) on this repository rather than filing a public issue. Do not include proof-of-concept exploit code in the initial report.
+
+We will acknowledge receipt within 72 hours and aim to release a patch within 14 days for critical vulnerabilities.