"""
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
     Script Name      : bloomcore_formatter.py
     Placement        : Run locally or in any Python environment
     Type of Script   : Python CLI Tool
     Purpose          : Takes a raw Python script and reformats it into full
                        Bloomcore/QuarterBit documentation standard —
                        header block, inline comments on every line,
                        section labels, and Nimbis anchor note.
     Version          : 1.0
     Linked Objects   : None
     Dependencies     : anthropic (pip install anthropic)
     Last Updated     : 2026-03-08
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
"""

import anthropic                                                   # Anthropic SDK for Claude API calls
import sys                                                         # System module for reading CLI args and stdin
import os                                                          # OS module for file path operations

#==============================================================================
#  SETUP — BLOOMCORE FORMAT SYSTEM PROMPT
#==============================================================================

SYSTEM_PROMPT = """
You are the Bloomcore/QuarterBit Python script formatter for Nimbis.

Your job is to take a raw Python script and reformat it into the official
Bloomcore/QuarterBit documentation standard. 

RULES — follow every single one:
1. Add a full header block at the very top as a Python docstring like this:
\"\"\"
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
     Script Name      : [filename or best guess]
     Placement        : [where this script lives/runs]
     Type of Script   : [Python Script / Module / CLI Tool / Gradio App / etc]
     Purpose          : [short description of what it does]
     Version          : 1.0
     Linked Objects   : [any files, APIs, or assets it depends on]
     Dependencies     : [pip packages required]
     Last Updated     : 2026-03-08
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
\"\"\"

2. Add an inline comment on EVERY SINGLE LINE of code using #
   - Comment must describe what that specific line does
   - Keep comments concise but clear
   - Align comments neatly where possible

3. Add section dividers like this before logical groups:
#==============================================================================
#  SETUP — SECTION NAME
#==============================================================================

4. Add a final Nimbis anchor note at the bottom like this:
#==============================================================================
#  FINAL NOTE — NIMBIS
#==============================================================================
# NIMBIS: [brief summary of what the script does and any important notes]
# Do not rename things without updating the header.
# End of file.

5. Never change the actual logic or functionality — only add documentation
6. Never remove any existing code
7. Return ONLY the reformatted Python code — no explanation, no markdown fences
""".strip()                                                        # Strip leading/trailing whitespace from prompt

#==============================================================================
#  MAIN LOGIC — FORMAT FUNCTION
#==============================================================================

def format_script(raw_code: str, filename: str = "script.py") -> str:  # Takes raw code and returns formatted version
    client = anthropic.Anthropic()                                 # Init Anthropic client using ANTHROPIC_API_KEY env var

    message = client.messages.create(                             # Send formatting request to Claude
        model="claude-opus-4-5",                                   # Use Opus for best formatting quality
        max_tokens=8096,                                           # Allow long responses for large scripts
        system=SYSTEM_PROMPT,                                      # Inject Bloomcore formatting rules
        messages=[                                                 # Message array for the API call
            {                                                      # Single user message object
                "role": "user",                                    # User role
                "content": f"Format this script. Filename: {filename}\n\n{raw_code}"  # Pass filename + raw code
            }
        ]
    )

    return message.content[0].text                                 # Extract and return formatted text response

#==============================================================================
#  MAIN LOGIC — CLI ENTRY POINT
#==============================================================================

def main():                                                        # Main entry point for CLI usage
    if len(sys.argv) < 2:                                          # Check if a file argument was provided
        print("Usage: python bloomcore_formatter.py <script.py>")  # Print usage instructions
        print("       cat script.py | python bloomcore_formatter.py -")  # Show pipe usage option
        sys.exit(1)                                                # Exit with error code

    input_arg = sys.argv[1]                                        # Get the input argument

    if input_arg == "-":                                           # Check if reading from stdin pipe
        raw_code = sys.stdin.read()                                # Read raw code from stdin
        filename = "script.py"                                     # Default filename for piped input
    else:                                                          # Otherwise read from file
        if not os.path.exists(input_arg):                          # Check file exists
            print(f"Error: File not found — {input_arg}")          # Print error message
            sys.exit(1)                                            # Exit with error code
        with open(input_arg, "r", encoding="utf-8") as f:          # Open input file
            raw_code = f.read()                                    # Read full file content
        filename = os.path.basename(input_arg)                     # Extract just the filename

    print(f"🌀 Formatting {filename} into Bloomcore standard...")  # Status message to user

    formatted = format_script(raw_code, filename)                  # Call formatter with code and filename

    output_path = filename.replace(".py", "_bloomcore.py")         # Build output filename with _bloomcore suffix
    with open(output_path, "w", encoding="utf-8") as f:            # Open output file for writing
        f.write(formatted)                                         # Write formatted code to file

    print(f"✅ Done! Saved to: {output_path}")                     # Confirm success and show output path

#==============================================================================
#  FINAL NOTE — NIMBIS
#==============================================================================

# NIMBIS: This tool formats any raw Python script into Bloomcore/QuarterBit standard.
# Run it like: python bloomcore_formatter.py yourscript.py
# It will create yourscript_bloomcore.py with full header, inline comments, and sections.
# Requires ANTHROPIC_API_KEY set as environment variable.
# Do not rename without updating the header block above.
# End of file.

if __name__ == "__main__":                                         # Only run main() when executed directly
    main()                                                         # Call main entry point