git-alchemist 1.0.0__py3-none-any.whl

git_alchemist-1.0.0.dist-info/METADATA

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: git-alchemist
+Version: 1.0.0
+Summary: A unified AI stack to optimize, describe, and architect your GitHub repositories.
+Author: abduznik
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: google-genai
+Requires-Dist: rich
+Requires-Dist: python-dotenv
+Requires-Dist: requests
+Dynamic: license-file
+
+# Git-Alchemist ⚗️
+
+**Git-Alchemist ⚗️** is a unified AI-powered CLI tool for automating GitHub repository management. It consolidates multiple technical utilities into a single, intelligent system powered by Google's Gemini 3 and Gemma 3 models.
+
+### 🌐 [Visit the Official Site](https://abduznik.github.io/Git-Alchemist/)
+
+---
+
+## Features
+
+*   **Smart Profile Generator:** Intelligently generates or updates your GitHub Profile README.
+*   **Topic Generator:** Auto-tag your repositories with AI-suggested topics for better discoverability.
+*   **Description Refiner:** Automatically generates repository descriptions by analyzing your README content.
+*   **Issue Drafter:** Translates loose ideas into structured, technical GitHub Issue drafts.
+*   **Architect (Scaffold):** Generates and executes project scaffolding commands in a safe, temporary workspace.
+*   **Fix & Explain:** Apply AI-powered patches to specific files or get concise technical explanations for complex code.
+*   **Gold Score Audit:** Measure your repository's professional quality and health.
+*   **The Sage:** Contextual codebase chat to answer deep technical questions about your code.
+*   **Commit Alchemist:** Automated semantic commit message suggestions from staged changes.
+
+## Model Tiers
+
+Git-Alchemist features a dynamic fallback system to ensure you never hit a quota wall:
+
+*   **Fast Mode (Default):** Utilizes **Gemma 3 (27B)** and **Gemini 3 Flash**. Optimized for speed and high-volume tasks.
+*   **Smart Mode (`--smart`):** Utilizes **Gemini 3 Pro** and **Gemini 2.5 Pro**. Optimized for complex architecture and deep code analysis.
+
+## Installation
+
+1.  **Clone the repository:**
+    ```bash
+    git clone https://github.com/abduznik/Git-Alchemist.git
+    cd Git-Alchemist
+    ```
+
+2.  **Install as a Global Library:**
+    ```bash
+    pip install .
+    ```
+
+3.  **Set up your Environment:**
+    Create a `.env` file in the directory or export it in your shell:
+    ```env
+    GEMINI_API_KEY=your_actual_api_key_here
+    ```
+
+## Usage
+
+Once installed, you can run the `alchemist` command from **any directory**:
+
+```bash
+# Audit a repository
+alchemist audit
+
+# Optimize repository topics
+alchemist topics
+
+# Generate semantic commit messages
+alchemist commit
+
+# Ask the Sage a question
+alchemist sage "How does the audit scoring work?"
+
+# Scaffold a new project (Safe Mode)
+alchemist scaffold "A FastAPI backend with a React frontend" --smart
+```
+
+## Requirements
+
+*   Python 3.10+
+*   GitHub CLI (`gh`) installed and authenticated (`gh auth login`).
+*   A Google Gemini API Key.
+
+## Migration Note
+
+This tool replaces and consolidates the following legacy scripts:
+*   `AI-Gen-Profile`
+*   `AI-Gen-Topics`
+*   `AI-Gen-Description`
+*   `AI-Gen-Issue`
+*   `Ai-Pro-Arch`
+
+---
+*Created by [abduznik](https://github.com/abduznik)*

git_alchemist-1.0.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+git_alchemist-1.0.0.dist-info/licenses/LICENSE,sha256=m0_AWYEhbGuv2DeqHpVotJvfJSbWafyGQwivleB3tUI,1065
+src/architect.py,sha256=zt9nqjeLJhj_98rT5GHDH1rj0s0-j1CQav7NbVPPkQA,5481
+src/audit.py,sha256=fuIuoxRk1yC4-2vy2qqgz1EkTavQvyHHFRxuJQjpc3s,2788
+src/cli.py,sha256=-_NksBB4jG2NKZmg-5OYfkPbqIQKhOKFORfdWiu0czQ,3688
+src/committer.py,sha256=O9KFavCgJa8mbsFGZoLBdtMEccwlN7yKNuaxhPtdQ-c,2249
+src/core.py,sha256=mwz5QgTIyIMKVHvfcP2Ndol_DHdZz5azx-zT_FE3VOY,1806
+src/issue_gen.py,sha256=Sdn2DKnihWIDwRJIRmrql-9q8mqLy7LscEuk4celt0c,2474
+src/profile_gen.py,sha256=i6N-gTE0rM1hIxWfN8sEBLItm1gu2_6xE94YaeHRa7g,6772
+src/promote.py,sha256=nSmFywPI5mmHJO15dTpwZ2TO_IZT9w04XOJWF3BE0xM,3224
+src/repo_tools.py,sha256=QGkCDYRBsl4g1DAecNJtOj91nLYZkJriadY3rCLfzE4,3929
+src/sage.py,sha256=nxUEc146pKO_6TR4nBONKkRdREY08NEa2ir4BF--vX8,2227
+src/utils.py,sha256=Ncz4vczfIXcQGgXaFa-8bL3SD3Sykg46yiHDScV8-CA,1187
+git_alchemist-1.0.0.dist-info/METADATA,sha256=McyH9frbTwtCOm1B22_fpGZ012iDyPmisr8mk92oBEI,3219
+git_alchemist-1.0.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+git_alchemist-1.0.0.dist-info/entry_points.txt,sha256=OcOmJI8khwZFsdRSUGGppfKdVfdGOKRRkwcSlZ-rJTI,43
+git_alchemist-1.0.0.dist-info/top_level.txt,sha256=74rtVfumQlgAPzR5_2CgYN24MB0XARCg0t-gzk6gTrM,4
+git_alchemist-1.0.0.dist-info/RECORD,,

git_alchemist-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

git_alchemist-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+alchemist = src.cli:main

git_alchemist-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 abduznik
+
+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.

git_alchemist-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+src

src/architect.py

@@ -0,0 +1,149 @@
+import os
+import json
+import shutil
+import tempfile
+import subprocess
+from rich.console import Console
+from rich.prompt import Confirm
+from .core import generate_content
+from .utils import run_shell
+
+console = Console()
+
+def scaffold_project(instruction, mode="fast"):
+    """
+    Generates shell commands to scaffold a project in a temporary directory.
+    """
+    console.print(f"[cyan]Architecting solution for: {instruction} ({mode} mode)...[/cyan]")
+    
+    # Create temp env
+    temp_dir = tempfile.mkdtemp(prefix="git_alchemist_scaffold_")
+    console.print(f"[gray]Created temporary workspace: {temp_dir}[/gray]")
+    
+    prompt = f"""
+Task: Project Scaffolding.
+User Goal: "{instruction}"
+Operating System: Linux/Unix (Termux)
+Constraint: Return ONLY a JSON object with a single key "commands" containing an array of shell strings.
+The commands should assume they are running INSIDE the project root.
+Example: {{"commands": ["mkdir src", "touch src/main.py", "echo 'print(1)' > src/main.py"]}}
+Do NOT use markdown blocks.
+"""
+
+    result = generate_content(prompt, mode=mode)
+    if not result:
+        shutil.rmtree(temp_dir)
+        return
+
+    try:
+        clean_result = result.replace("```json", "").replace("```", "").strip()
+        data = json.loads(clean_result)
+        commands = data.get("commands", [])
+        
+        console.print("[green]Generated Plan:[/green]")
+        for cmd in commands:
+            console.print(f"  > {cmd}")
+            
+        if Confirm.ask("Execute these commands in the temporary workspace?"):
+            # Execute in temp dir
+            cwd = os.getcwd()
+            os.chdir(temp_dir)
+            try:
+                for cmd in commands:
+                    console.print(f"[cyan]Running:[/cyan] {cmd}")
+                    run_shell(cmd)
+                
+                console.print("[green]Scaffolding complete in temporary workspace.[/green]")
+                console.print(f"[gray]Contents of {temp_dir}:[/gray]")
+                run_shell("ls -R")
+                
+                if Confirm.ask("Keep these files? (Moves them to current directory)"):
+                    # Move files from temp_dir to cwd
+                    # We iterate over items in temp_dir and move them
+                    for item in os.listdir(temp_dir):
+                        s = os.path.join(temp_dir, item)
+                        d = os.path.join(cwd, item)
+                        if os.path.exists(d):
+                            console.print(f"[yellow]Warning:[/yellow] {item} already exists in current directory. Skipping.")
+                        else:
+                            shutil.move(s, d)
+                    console.print("[green]Files moved successfully.[/green]")
+                else:
+                    console.print("[yellow]Discarding workspace.[/yellow]")
+                    
+            except Exception as e:
+                console.print(f"[red]Execution failed:[/red] {e}")
+            finally:
+                os.chdir(cwd)
+        
+    except json.JSONDecodeError:
+        console.print(f"[red]Failed to parse AI response:[/red] {result}")
+    finally:
+        if os.path.exists(temp_dir):
+            shutil.rmtree(temp_dir)
+            console.print("[gray]Temporary workspace cleaned up.[/gray]")
+
+def fix_code(file_path, instruction, mode="fast"):
+    """
+    Reads a file, applies an AI fix, and optionally creates a PR.
+    """
+    if not os.path.exists(file_path):
+        console.print(f"[red]File not found:[/red] {file_path}")
+        return
+
+    console.print(f"[cyan]Reading {file_path} ({mode} mode)...[/cyan]")
+    with open(file_path, "r", encoding="utf-8") as f:
+        content = f.read()
+
+    prompt = f"""
+Task: Fix/Modify Code.
+User Instructions:
+'''
+{instruction}
+'''
+
+Target File Content:
+'''
+{content}
+'''
+
+Goal: Return ONLY the complete, corrected file content based on the User Instructions. Do not use markdown blocks.
+"""
+    
+    console.print(f"[magenta]Consulting Gemini ({mode} mode)...[/magenta]")
+    result = generate_content(prompt, mode=mode)
+    if not result:
+        return
+
+    clean_result = result.replace("```python", "").replace("```", "").strip() # Generic cleanup
+    
+    # Backup
+    backup_path = f"{file_path}.bak"
+    shutil.copy(file_path, backup_path)
+    console.print(f"[gray]Backup created: {backup_path}[/gray]")
+    
+    with open(file_path, "w", encoding="utf-8") as f:
+        f.write(clean_result)
+        
+    console.print(f"[green]File updated.[/green]")
+    
+    if Confirm.ask("Create a PR for this fix?"):
+        # This assumes we are in a git repo
+        try:
+            branch_name = f"fix/ai-{os.urandom(4).hex()}"
+            run_shell(f"git checkout -b {branch_name}")
+            run_shell(f"git add {file_path}")
+            run_shell(f'git commit -m "AI Fix: {instruction}"')
+            run_shell(f"git push -u origin {branch_name}")
+            run_shell(f'gh pr create --title "AI Fix: {instruction}" --body "Automated fix." --web')
+        except Exception as e:
+            console.print(f"[red]PR creation failed:[/red] {e}")
+
+def explain_code(context, mode="fast"):
+    """
+    Explains a concept or code snippet.
+    """
+    prompt = f"Task: Explain Concept/Code. Context: '{context}'. Keep it concise and technical."
+    result = generate_content(prompt, mode=mode)
+    if result:
+        console.print(f"\n[bold white]--- Explanation ---[/bold white]\n{result}\n[bold white]-------------------[/bold white]")

src/audit.py

@@ -0,0 +1,61 @@
+import os
+import json
+from rich.console import Console
+from rich.table import Table
+from rich.progress import Progress
+from .utils import run_shell, check_gh_auth
+
+console = Console()
+
+def run_audit(user=None, repo_name=None):
+    """
+    Audits a repository for 'Gold Standard' items and returns a score.
+    """
+    username = user or check_gh_auth()
+    if not username:
+        console.print("[red]Not authenticated with gh CLI.[/red]")
+        return
+
+    # Use current directory if no repo specified
+    target_repo = repo_name or run_shell("gh repo view --json name --jq .name", check=False)
+    if not target_repo:
+        console.print("[yellow]Not inside a Git repository. Auditing current directory files only.[/yellow]")
+        repo_data = {}
+    else:
+        console.print(f"[cyan]Auditing Repository:[/cyan] [bold]{username}/{target_repo}[/bold]")
+        repo_data_raw = run_shell(f"gh repo view {username}/{target_repo} --json description,repositoryTopics,licenseInfo", check=False)
+        repo_data = json.loads(repo_data_raw) if repo_data_raw else {}
+
+    checks = {
+        "README.md": {"score": 20, "found": os.path.exists("README.md")},
+        "LICENSE": {"score": 10, "found": bool(repo_data.get("licenseInfo")) or any(os.path.exists(f) for f in ["LICENSE", "LICENSE.md", "LICENSE.txt"])},
+        "CONTRIBUTING.md": {"score": 10, "found": any(os.path.exists(f) for f in ["CONTRIBUTING.md", "CONTRIBUTING"])},
+        "Metadata: Description": {"score": 20, "found": bool(repo_data.get("description"))},
+        "Metadata: Topics": {"score": 20, "found": len(repo_data.get("repositoryTopics", [])) >= 3},
+        "CI/CD: GitHub Actions": {"score": 20, "found": os.path.exists(".github/workflows")},
+    }
+
+    total_score = sum(c["score"] for c in checks.values() if c["found"])
+    
+    # Display Table
+    table = Table(title=f"Repository Audit: {target_repo or 'Local'}", border_style="blue")
+    table.add_column("Criterion", style="cyan")
+    table.add_column("Status", justify="center")
+    table.add_column("Weight", justify="right")
+
+    for name, data in checks.items():
+        status = "[green]GOLD[/green]" if data["found"] else "[red]LEAD[/red]"
+        table.add_row(name, status, f"{data['score']}")
+
+    console.print(table)
+    
+    # Final Score Display
+    color = "green" if total_score >= 80 else "yellow" if total_score >= 50 else "red"
+    console.print(f"\n[bold]Transmutation Score:[/bold] [{color}]{total_score}%[/{color}]")
+    
+    if total_score < 100:
+        console.print(f"\n[italic gray]The Alchemist suggests adding the missing components to reach 100% Gold.[/italic gray]")
+    else:
+        console.print(f"\n[bold yellow]✨ Pure Gold! This repository is optimized for the community.[/bold yellow]")
+
+    return total_score

src/cli.py

@@ -0,0 +1,84 @@
+import argparse
+import sys
+from rich.console import Console
+from .profile_gen import generate_profile
+from .architect import scaffold_project, fix_code, explain_code
+from .repo_tools import optimize_topics, generate_descriptions
+from .issue_gen import create_issue
+from .audit import run_audit
+from .sage import ask_sage
+from .committer import suggest_commits
+
+console = Console()
+
+def main():
+    parser = argparse.ArgumentParser(description="Git-Alchemist: AI-powered Git Operations")
+    parser.add_argument("--smart", action="store_true", help="Use high-end Gemini Pro models (slower/lower quota)")
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+    
+    # Commit Command
+    commit_parser = subparsers.add_parser("commit", help="Generate semantic commit messages from changes")
+
+    # Sage Command
+    sage_parser = subparsers.add_parser("sage", help="Ask the Sage questions about your codebase")
+    sage_parser.add_argument("question", help="The question about your code")
+
+    # Audit Command
+    audit_parser = subparsers.add_parser("audit", help="Check repository 'Gold' status and metadata")
+    audit_parser.add_argument("--repo", help="Specific repository name to audit")
+
+    # Profile Generator Command
+    profile_parser = subparsers.add_parser("profile", help="Generate or update GitHub Profile README")
+    profile_parser.add_argument("--force", action="store_true", help="Force full regeneration")
+    profile_parser.add_argument("--user", help="GitHub username (optional, detects automatically)")
+
+    # Repo Tools
+    topics_parser = subparsers.add_parser("topics", help="Optimize repository topics/tags")
+    topics_parser.add_argument("--user", help="GitHub username")
+
+    describe_parser = subparsers.add_parser("describe", help="Generate missing repository descriptions")
+    describe_parser.add_argument("--user", help="GitHub username")
+
+    # Issue Generator
+    issue_parser = subparsers.add_parser("issue", help="Draft a technical issue from an idea")
+    issue_parser.add_argument("idea", help="The feature or bug idea")
+
+    # Architect Commands
+    scaffold_parser = subparsers.add_parser("scaffold", help="Generate a new project structure (safe mode)")
+    scaffold_parser.add_argument("instruction", help="What to build (e.g., 'A Flask app with Docker')")
+
+    fix_parser = subparsers.add_parser("fix", help="Modify a file using AI")
+    fix_parser.add_argument("file", help="Path to the file to fix")
+    fix_parser.add_argument("instruction", help="What to change")
+
+    explain_parser = subparsers.add_parser("explain", help="Explain code or concepts")
+    explain_parser.add_argument("context", help="The code or concept to explain")
+
+    args = parser.parse_args()
+    mode = "smart" if args.smart else "fast"
+    
+    if args.command == "profile":
+        generate_profile(args.user, args.force, mode=mode)
+    elif args.command == "topics":
+        optimize_topics(args.user, mode=mode)
+    elif args.command == "describe":
+        generate_descriptions(args.user, mode=mode)
+    elif args.command == "issue":
+        create_issue(args.idea, mode=mode)
+    elif args.command == "scaffold":
+        scaffold_project(args.instruction, mode=mode)
+    elif args.command == "fix":
+        fix_code(args.file, args.instruction, mode=mode)
+    elif args.command == "explain":
+        explain_code(args.context, mode=mode)
+    elif args.command == "audit":
+        run_audit(repo_name=args.repo)
+    elif args.command == "sage":
+        ask_sage(args.question, mode=mode)
+    elif args.command == "commit":
+        suggest_commits(mode=mode)
+    else:
+        parser.print_help()
+
+if __name__ == "__main__":
+    main()

src/committer.py

@@ -0,0 +1,70 @@
+import os
+from rich.console import Console
+from rich.prompt import Prompt
+from .core import generate_content
+from .utils import run_shell
+
+console = Console()
+
+def get_staged_diff():
+    """Returns the diff of staged changes."""
+    return run_shell("git diff --cached", check=False)
+
+def suggest_commits(mode="fast"):
+    """
+    Analyzes staged changes and suggests 3 semantic commit messages.
+    """
+    diff = get_staged_diff()
+    
+    if not diff:
+        console.print("[yellow]No staged changes found.[/yellow]")
+        if Prompt.ask("Stage all changes now? (git add .)", choices=["y", "n"], default="y") == "y":
+            run_shell("git add .")
+            diff = get_staged_diff()
+        else:
+            return
+
+    console.print("[cyan]Analyzing changes for the perfect commit message...[/cyan]")
+    
+    prompt = f"""
+Task: Suggest 3 professional, semantic commit messages based on the git diff below.
+Format: <type>(<scope>): <subject>
+Types: feat, fix, docs, style, refactor, test, chore
+
+DIFF:
+'''
+{diff[:5000]}
+'''
+
+Instructions:
+1. Return ONLY a numbered list of 3 options.
+2. No explanations or extra text.
+3. Ensure they are concise and accurate.
+"""
+
+    result = generate_content(prompt, mode=mode)
+    if not result:
+        return
+
+    options = [line.strip() for line in result.strip().split("\n") if line.strip()]
+    # Remove numbering if AI added it (e.g., "1. feat: ...")
+    clean_options = []
+    for opt in options:
+        # Match "1. ", "1) ", etc.
+        import re
+        clean_opt = re.sub(r'^\d+[\.\)]\s*', '', opt).strip()
+        if clean_opt:
+            clean_options.append(clean_opt)
+
+    console.print("\n[bold green]Recommended Transmutations:[/bold green]")
+    for i, opt in enumerate(clean_options, 1):
+        console.print(f"  [bold cyan]{i}.[/bold cyan] {opt}")
+    
+    choice = Prompt.ask("\nSelect a message to commit (or 'c' to cancel)", choices=[str(i) for i in range(1, len(clean_options)+1)] + ["c"])
+    
+    if choice != "c":
+        selected_msg = clean_options[int(choice)-1]
+        console.print(f"[green]Committing with message:[/green] {selected_msg}")
+        run_shell(f'git commit -m "{selected_msg}"')
+    else:
+        console.print("[yellow]Commit aborted.[/yellow]")

src/core.py

@@ -0,0 +1,59 @@
+import os
+import sys
+import time
+from google import genai
+from dotenv import load_dotenv
+from rich.console import Console
+
+console = Console()
+
+# Define model tiers based on your available list
+SMART_MODELS = [
+    "gemini-3-pro-preview",
+    "gemini-2.5-pro",
+    "gemini-1.5-pro", # Fallback to stable if preview fails
+]
+
+FAST_MODELS = [
+    "gemma-3-27b-it",
+    "gemma-3-12b-it",
+    "gemini-3-flash-preview",
+    "gemini-2.0-flash",
+]
+
+def get_gemini_client():
+    load_dotenv()
+    api_key = os.getenv("GEMINI_API_KEY")
+    if not api_key:
+        console.print("[bold red]Error:[/bold red] GEMINI_API_KEY not found.")
+        sys.exit(1)
+    return genai.Client(api_key=api_key, http_options={'api_version':'v1alpha'})
+
+def generate_content(prompt, mode="fast"):
+    """
+    Generates content with automatic fallback.
+    Mode: 'fast' (Gemma/Flash) or 'smart' (Pro/3-Pro)
+    """
+    client = get_gemini_client()
+    models = SMART_MODELS if mode == "smart" else FAST_MODELS
+    
+    for model_name in models:
+        try:
+            console.print(f"[gray]Attempting with {model_name}...[/gray]")
+            response = client.models.generate_content(
+                model=model_name,
+                contents=prompt
+            )
+            if response and response.text:
+                return response.text
+        except Exception as e:
+            err_msg = str(e)
+            if "429" in err_msg or "RESOURCE_EXHAUSTED" in err_msg:
+                console.print(f"[yellow]Quota hit for {model_name}. Trying next...[/yellow]")
+                continue
+            else:
+                console.print(f"[red]Error with {model_name}:[/red] {err_msg}")
+                continue
+                
+    console.print("[bold red]Critical:[/bold red] All models exhausted or failed.")
+    return None

src/issue_gen.py

@@ -0,0 +1,76 @@
+import json
+import tempfile
+import os
+from rich.console import Console
+from .core import generate_content
+from .utils import run_shell
+
+console = Console()
+
+def create_issue(idea, mode="fast"):
+    """
+    Translates an idea into a technical GitHub issue.
+    """
+    console.print(f"[cyan]Drafting technical issue for: {idea} ({mode} mode)...[/cyan]")
+    
+    prompt = f"""
+You are a Senior Tech Lead.
+User Input: '{idea}'
+TASK: Translate this into a technical implementation plan.
+STRUCTURE:
+- **Context**: 1 sentence explaining WHY.
+- **Directives**: Bullet points of EXACTLY what to change.
+OUTPUT FORMAT: Return ONLY a JSON object with keys: "title", "body", "label", "easy" (boolean).
+No markdown blocks.
+"""
+
+    result = generate_content(prompt, mode=mode)
+    if not result: return
+
+    try:
+        clean_json = result.replace("```json", "").replace("```", "").strip()
+        issue = json.loads(clean_json)
+        
+        title = f"[DRAFT] {issue['title']}"
+        body = f"{issue['body']}\n\n> Automated by Git-Alchemist"
+        label = issue.get('label', 'enhancement')
+        
+        console.print(f"[yellow]Uploading Draft: {title}[/yellow]")
+        
+        # Create labels if they don't exist
+        run_shell('gh label create "automated" --color "505050" 2>/dev/null', check=False)
+        run_shell('gh label create "status: draft" --color "333333" 2>/dev/null', check=False)
+        run_shell(f'gh label create "{label}" 2>/dev/null', check=False)
+
+        with tempfile.NamedTemporaryFile(mode='w', suffix='.md', delete=False) as tf:
+            tf.write(body)
+            temp_name = tf.name
+
+        cmd = [
+            'gh',
+            'issue',
+            'create',
+            '--title',
+            f'"{title}"',
+            '--body-file',
+            f'"{temp_name}"',
+            '--label',
+            '"status: draft"',
+            '--label',
+            '"automated"',
+            '--label',
+            f'"{label}"'
+        ]
+        
+        if issue.get('easy'):
+            run_shell('gh label create "good first issue" --color "7057ff" 2>/dev/null', check=False)
+            cmd.extend(['--label', '"good first issue"'])
+
+        run_shell(" ".join(cmd))
+        os.unlink(temp_name)
+        
+        console.print("[green]Success! Issue created as draft.[/green]")
+        
+    except Exception as e:
+        console.print(f"[red]Failed to create issue:[/red] {e}")
+        console.print(f"[gray]Raw Output:[/gray] {result}")

src/profile_gen.py

@@ -0,0 +1,197 @@
+import os
+import json
+import tempfile
+import shutil
+import re
+from pathlib import Path
+from rich.console import Console
+from rich.prompt import Confirm
+from .core import generate_content
+from .utils import run_shell, check_gh_auth, get_user_email
+
+console = Console()
+
+def fetch_repos(username):
+    """
+    Fetches public repositories for the user.
+    """
+    console.print("[cyan]Fetching repositories...[/cyan]")
+    cmd = 'gh repo list --visibility=public --limit 100 --json name,description,url,isPrivate,isArchived,stargazerCount'
+    try:
+        output = run_shell(cmd)
+        return json.loads(output)
+    except Exception as e:
+        console.print(f"[red]Failed to fetch repos:[/red] {e}")
+        return []
+
+def filter_repos(repos, username, strategy="FULL_GEN", existing_content=""):
+    """
+    Filters out junk, private, archived, and irrelevant repos (like Awesome lists).
+    """
+    candidates = []
+    
+    # Blocklist for low-value repos
+    junk_patterns = ["test", "export", "WPy64", "PROFILE_DRAFT.md", "temp", "awesome-"]
+    
+    for r in repos:
+        name = r['name']
+        
+        # Basic filters
+        if name == username: continue
+        if r.get('isPrivate'): continue
+        if r.get('isArchived'): continue
+        if any(p in name.lower() for p in junk_patterns): continue
+        if name.endswith(".exe"): continue
+        
+        # Strategy filter
+        if strategy == "SMART_UPDATE":
+            # Check if name or URL exists in current profile content
+            if name in existing_content or r['url'] in existing_content:
+                continue
+        
+        candidates.append(r)
+        
+    return candidates
+
+def generate_profile(username, force=False, mode="fast"):
+    """
+    Main function to generate or update the profile.
+    """
+    if not username:
+        username = check_gh_auth()
+        if not username:
+            console.print("[red]Not logged into GitHub CLI. Run 'gh auth login' first.[/red]")
+            return
+
+    console.print(f"[green]Authenticated as: {username}[/green]")
+    
+    # Discovery
+    current_content = ""
+    strategy = "FULL_GEN"
+    
+    try:
+        console.print("[cyan]Checking for existing profile...[/cyan]")
+        current_content = run_shell(f'gh api "repos/{username}/{username}/readme" --headers "Accept: application/vnd.github.raw"', check=False)
+        if current_content and len(current_content) > 200 and not force:
+            console.print("[green]Found existing robust profile. Switching to SMART_UPDATE.[/green]")
+            strategy = "SMART_UPDATE"
+        else:
+             console.print("[yellow]Profile basic or missing. Using FULL_GEN.[/yellow]")
+    except:
+        pass
+
+    # Fetch & Filter
+    repos = fetch_repos(username)
+    candidates = filter_repos(repos, username, strategy, current_content)
+    
+    if not candidates:
+        console.print("[green]No new repositories to add.[/green]")
+        return
+
+    # Prompt Engineering
+    candidates_str = "\n".join([f"- Name: {r['name']}\n  Desc: {r['description'] or ''}\n  URL: {r['url']}" for r in candidates])
+    
+    prompt = ""
+    if strategy == "SMART_UPDATE":
+        prompt = f"""
+Task: Update a GitHub Profile README.
+Existing Markdown:
+'''
+{current_content}
+'''
+
+New Projects to Add:
+{candidates_str}
+
+Instructions:
+1. Integrate the 'New Projects' into the 'Existing Markdown' naturally.
+2. Place them under appropriate categories.
+3. PRESERVE THE EXISTING STRUCTURE: Do not delete existing sections, badges, or headers.
+4. MANDATORY LINKING: Use the provided URL for each project in the format '- **[Name](URL)** - Description'.
+5. MATCH THE STYLE: If the existing list uses bullets, stick to it.
+6. STRICTLY NO EMOJIS in new additions.
+7. Output the FULL updated Markdown content.
+"""
+    else:
+        # Full Gen
+        prompt = f"""
+Task: Generate a professional Project Showcase for a GitHub Profile.
+Username: {username}
+
+Projects List:
+{candidates_str}
+
+Instructions:
+1. Group projects into 3-6 meaningful categories (e.g., '## AI & Automation', '## Hardware').
+2. MANDATORY LINKING: Use the format '- **[Name](URL)** - Description'.
+3. Use a clean, professional header at the top.
+4. STRICTLY NO EMOJIS.
+5. Output the FULL Markdown.
+"""
+
+    console.print(f"[magenta]Generating content with Gemini ({mode} mode)...[/magenta]")
+    result = generate_content(prompt, mode=mode)
+    
+    if not result:
+        return
+
+    # Post-processing
+    final_md = result.replace("```markdown", "").replace("```", "").strip()
+    
+    # Ensure branding is preserved but clean
+    footer = "\n\n---\n*Generated by Git-Alchemist ⚗️*"
+    if "*Generated by Git-Alchemist*" not in final_md:
+        final_md += footer
+
+    # Save Draft
+    with open("PROFILE_DRAFT.md", "w", encoding="utf-8") as f:
+        f.write(final_md)
+    console.print(f"[magenta]Draft saved to PROFILE_DRAFT.md[/magenta]")
+    
+    # Deploy (Strictly PR)
+    if Confirm.ask("Deploy these changes via Pull Request?"):
+        deploy_profile(username, final_md)
+
+def deploy_profile(username, content):
+    """
+    Clones the profile repo, updates README, and opens a PR.
+    """
+    temp_dir = tempfile.mkdtemp(prefix="git_alchemist_")
+    try:
+        console.print("[cyan]Cloning profile repository...[/cyan]")
+        run_shell(f'gh repo clone {username}/{username} {temp_dir}')
+        
+        # Determine the target dir (sometimes gh clones into a subdir, sometimes not)
+        repo_dir = Path(temp_dir)
+        if (repo_dir / username).exists():
+            repo_dir = repo_dir / username
+            
+        # Write file
+        readme_path = repo_dir / "README.md"
+        with open(readme_path, "w", encoding="utf-8") as f:
+            f.write(content)
+            
+        # Git ops
+        cwd = os.getcwd()
+        os.chdir(repo_dir)
+        
+        branch_name = f"profile-update-{os.urandom(2).hex()}"
+        run_shell(f'git checkout -b {branch_name}')
+        
+        user_email = get_user_email() or f"{username}@users.noreply.github.com"
+        run_shell(f'git config user.name "{username}"')
+        run_shell(f'git config user.email "{user_email}"')
+        
+        run_shell('git add README.md')
+        run_shell(f'git commit -m "docs: Update profile README via Git-Alchemist"')
+        run_shell(f'git push -u origin {branch_name} --force')
+        
+        console.print("[green]Opening PR...[/green]")
+        run_shell(f'gh pr create --title "AI Profile Update" --body "Automated profile update generated by Git-Alchemist. Added missing repo links and organized new projects."')
+        
+        os.chdir(cwd)
+        
+    except Exception as e:
+        console.print(f"[red]Deployment failed:[/red] {e}")
+    finally:
+        shutil.rmtree(temp_dir, ignore_errors=True)

src/promote.py

@@ -0,0 +1,74 @@
+import os
+import requests
+from rich.console import Console
+
+console = Console()
+
+STORY = """
+I’ve been working on this tool for a couple of months now. It actually started as a 
+collection of loose PowerShell scripts I wrote to handle my own GitHub maintenance 
+(updating my profile, tagging repos, etc.). 
+
+I finally decided to combine them all into a unified project. I ported everything to 
+Python and built Git-Alchemist. It uses Gemini 3 and Gemma 3 to automate the boring 
+parts of Git management—like writing descriptions or scaffolding project structures 
+in safe, temporary workspaces. I'm really happy with how the consolidation turned out 
+and wanted to share it with the community.
+"""
+
+def post_to_devto(api_key):
+    """Automates posting to Dev.to"""
+    url = "https://dev.to/api/articles"
+    headers = {"api-key": api_key}
+    
+    article = {
+        "article": {
+            "title": "I consolidated my Git automation scripts into a unified AI stack: Git-Alchemist",
+            "published": True,
+            "body_markdown": f"# Git-Alchemist ⚗️\n\n{STORY}\n\nCheck it out here: [https://github.com/abduznik/Git-Alchemist](https://github.com/abduznik/Git-Alchemist)\n\nLanding Page: [https://abduznik.github.io/Git-Alchemist/](https://abduznik.github.io/Git-Alchemist/)",
+            "tags": ["python", "github", "ai", "opensource"],
+            "series": "Git Automation"
+        }
+    }
+    
+    try:
+        response = requests.post(url, json=article, headers=headers)
+        if response.status_code == 201:
+            console.print("[green]Successfully posted to Dev.to![/green]")
+        else:
+            console.print(f"[red]Failed to post to Dev.to:[/red] {response.text}")
+    except Exception as e:
+        console.print(f"[red]Error:[/red] {e}")
+
+def generate_manual_submissions():
+    """Generates text for manual form submissions"""
+    submissions = {
+        "Hackaday (https://hackaday.com/submit-a-tip/)": {
+            "Subject": "AI-Powered GitHub Maintenance: Git-Alchemist",
+            "Message": f"Hi Hackaday! I thought you might find this interesting. {STORY}\nRepo: https://github.com/abduznik/Git-Alchemist"
+        },
+        "TLDR Newsletter (https://tldr.tech/submit)": {
+            "Link": "https://github.com/abduznik/Git-Alchemist",
+            "Description": "A unified AI stack for GitHub repository management and project scaffolding."
+        },
+        "Console.dev (Newsletter for Dev Tools)": {
+            "Email": "hello@console.dev",
+            "Subject": "Tool Submission: Git-Alchemist",
+            "Body": f"Hi Console team, {STORY}\nRepo: https://github.com/abduznik/Git-Alchemist"
+        }
+    }
+    
+    console.print("\n[bold cyan]--- Manual Submission Drafts ---[/bold cyan]")
+    for platform, data in submissions.items():
+        console.print(f"\n[bold yellow]{platform}[/bold yellow]")
+        for k, v in data.items():
+            console.print(f"[bold]{k}:[/bold] {v}")
+
+if __name__ == "__main__":
+    devto_key = os.getenv("DEVTO_API_KEY")
+    if devto_key:
+        post_to_devto(devto_key)
+    else:
+        console.print("[yellow]No DEVTO_API_KEY found. Skipping automated post.[/yellow]")
+    
+    generate_manual_submissions()

src/repo_tools.py

@@ -0,0 +1,111 @@
+import json
+import time
+from rich.console import Console
+from .core import generate_content
+from .utils import run_shell, check_gh_auth
+
+console = Console()
+
+def optimize_topics(user=None, mode="fast"):
+    """
+    Analyzes repositories and adds relevant topics using Gemini.
+    """
+    username = user or check_gh_auth()
+    if not username:
+        console.print("[red]Not authenticated with gh CLI.[/red]")
+        return
+
+    console.print(f"[cyan]Optimizing topics for {username} ({mode} mode)...[/cyan]")
+    repos_raw = run_shell('gh repo list --visibility=public --limit 100 --json name,description,repositoryTopics')
+    repos = json.loads(repos_raw)
+
+    count = 0
+    for repo in repos:
+        name = repo['name']
+        desc = repo.get('description') or "No description provided"
+        
+        # Safe access to topics
+        raw_topics = repo.get('repositoryTopics')
+        if raw_topics is None:
+            existing = []
+        else:
+            existing = [t['name'] for t in raw_topics]
+        
+        if len(existing) >= 5:
+            continue
+
+        console.print(f"[white]Analyzing {name}...[/white]")
+        
+        prompt = f"""
+Task: Suggest search-friendly GitHub topics for project "{name}". 
+Description: "{desc}". 
+Existing Topics: {existing}. 
+Return ONLY a JSON array of strings (max 5 total topics). 
+Focus on technical keywords like 'python', 'api', 'automation', 'cli'.
+Output Example: ["python", "automation"]
+"""
+        result = generate_content(prompt, mode=mode)
+        if not result: continue
+
+        try:
+            clean_json = result.replace("```json", "").replace("```", "").strip()
+            new_tags = json.loads(clean_json)
+            
+            # Filter out existing
+            to_add = [t for t in new_tags if t not in existing]
+            
+            if to_add:
+                tag_str = ",".join(to_add)
+                console.print(f"  [green]Adding tags:[/green] {tag_str}")
+                run_shell(f'gh repo edit {username}/{name} --add-topic "{tag_str}"')
+                count += 1
+                time.sleep(0.5)
+        except:
+            console.print(f"  [red]Failed to parse topics for {name}[/red]")
+
+    console.print(f"[cyan]Done! Optimized {count} repositories.[/cyan]")
+
+def generate_descriptions(user=None, mode="fast"):
+    """
+    Generates descriptions for repositories that are missing them.
+    """
+    username = user or check_gh_auth()
+    if not username: return
+
+    console.print(f"[cyan]Generating descriptions for {username} ({mode} mode)...[/cyan]")
+    repos_raw = run_shell('gh repo list --visibility=public --limit 100 --json name,description')
+    repos = json.loads(repos_raw)
+
+    count = 0
+    for repo in repos:
+        name = repo['name']
+        if name == username: continue # Skip profile repo
+        if repo.get('description'): continue # Skip if already has desc
+
+        console.print(f"[white]Analyzing {name}...[/white]")
+        
+        # Fetch Readme
+        try:
+            readme = run_shell(f'gh repo view {username}/{name} --json body -q .body', check=False)
+            context = readme[:1500] if readme else "No readme available."
+        except:
+            context = "No readme available."
+
+        prompt = f"""
+Task: Generate a GitHub repository description for project "{name}". 
+Readme Context: "{context}". 
+Constraint: Max 20 words. Start with an action verb. 
+Output ONLY the description. No quotes.
+"""
+        result = generate_content(prompt, mode=mode)
+        if not result: continue
+
+        new_desc = result.strip().replace('"', '').replace("'", "")
+        if len(new_desc) > 200: new_desc = new_desc[:197] + "..."
+
+        console.print(f"  [green]New Desc:[/green] {new_desc}")
+        run_shell(f'gh repo edit {username}/{name} --description "{new_desc}"')
+        count += 1
+        time.sleep(0.5)
+
+    console.print(f"[cyan]Done! Updated {count} descriptions.[/cyan]")

src/sage.py

@@ -0,0 +1,71 @@
+import os
+from rich.console import Console
+from .core import generate_content
+from .utils import run_shell
+
+console = Console()
+
+def get_codebase_context():
+    """
+    Scans the repository and aggregates source code into a single context string.
+    """
+    context = []
+    # Extensions to include
+    extensions = {'.py', '.md', '.ps1', '.sh', '.js', '.ts', '.c', '.cpp', '.h', '.yml', '.yaml', '.Dockerfile'}
+    # Folders to ignore
+    ignore_dirs = {'__pycache__', '.git', 'venv', 'node_modules', '.tmp', 'docs'}
+
+    for root, dirs, files in os.walk("."):
+        # Filter directories in-place
+        dirs[:] = [d for d in dirs if d not in ignore_dirs]
+        
+        for file in files:
+            ext = os.path.splitext(file)[1]
+            if ext in extensions:
+                path = os.path.join(root, file)
+                try:
+                    with open(path, "r", encoding="utf-8") as f:
+                        content = f.read()
+                        context.append(f"--- FILE: {path} ---\n{content}\n")
+                except Exception:
+                    continue
+                    
+    return "\n".join(context)
+
+def ask_sage(question, mode="fast"):
+    """
+    Queries Gemini using the aggregated codebase as context.
+    """
+    console.print("[cyan]The Sage is meditating on your codebase...[/cyan]")
+    
+    code_context = get_codebase_context()
+    
+    if not code_context:
+        console.print("[yellow]Warning: No source files found to analyze.[/yellow]")
+        code_context = "No code found in repository."
+
+    prompt = f"""
+You are "The Sage", an expert software architect and technical lead. 
+Below is the source code context for the current project. 
+Use this context to answer the user's question precisely and technically.
+
+CONTEXT:
+'''
+{code_context}
+'''
+
+USER QUESTION:
+{question}
+
+Instructions:
+1. Base your answer ONLY on the provided code.
+2. Be concise but deep.
+3. If the answer isn't in the code, say so.
+"""
+
+    result = generate_content(prompt, mode=mode)
+    
+    if result:
+        console.print("\n[bold fuchsia]--- The Sage's Wisdom ---[/bold fuchsia]")
+        console.print(result)
+        console.print("[bold fuchsia]-----------------------[/bold fuchsia]")

src/utils.py

@@ -0,0 +1,47 @@
+import subprocess
+import json
+import shutil
+from rich.console import Console
+
+console = Console()
+
+def run_shell(command, check=True, capture_output=True):
+    """
+    Runs a shell command and returns the result.
+    """
+    try:
+        result = subprocess.run(
+            command,
+            shell=True,
+            check=check,
+            capture_output=capture_output,
+            text=True
+        )
+        return result.stdout.strip()
+    except subprocess.CalledProcessError as e:
+        if check:
+            console.print(f"[bold red]Command Failed:[/bold red] {command}")
+            console.print(f"[red]Error:[/red] {e.stderr}")
+            raise e
+        return None
+
+def check_gh_auth():
+    """
+    Checks if the user is authenticated with GitHub CLI.
+    Returns the username if authenticated, else None.
+    """
+    try:
+        user_login = run_shell('gh api user -q ".login"')
+        return user_login
+    except:
+        return None
+
+def get_user_email():
+    """
+    Gets the user email from GitHub CLI.
+    """
+    try:
+        email = run_shell('gh api user -q ".email"', check=False)
+        return email if email else None
+    except:
+        return None