feat: Comprehensive Package Restructure and Protocol Implementation

.claude/hooks.json

@@ -0,0 +1,7 @@
+{
+  "hooks": {
+    "stop": {
+      "shell": "python massgen/hooks/lint_and_typecheck.py"
+    }
+  }
+}

.claude/tdd-guard/data/test.json

@@ -0,0 +1,89 @@
+{
+  "testModules": [
+    {
+      "moduleId": "tests/test_mcp_security.py",
+      "tests": [
+        {
+          "name": "test_sanitize_input_sql_injection",
+          "fullName": "tests/test_mcp_security.py::TestSecurityFeatures::test_sanitize_input_sql_injection",
+          "state": "passed"
+        },
+        {
+          "name": "test_sanitize_input_length_limit",
+          "fullName": "tests/test_mcp_security.py::TestSecurityFeatures::test_sanitize_input_length_limit",
+          "state": "passed"
+        },
+        {
+          "name": "test_sanitize_input_multiple_patterns",
+          "fullName": "tests/test_mcp_security.py::TestSecurityFeatures::test_sanitize_input_multiple_patterns",
+          "state": "passed"
+        },
+        {
+          "name": "test_sanitize_input_xp_sp_patterns",
+          "fullName": "tests/test_mcp_security.py::TestSecurityFeatures::test_sanitize_input_xp_sp_patterns",
+          "state": "passed"
+        },
+        {
+          "name": "test_sanitize_input_preserves_safe_content",
+          "fullName": "tests/test_mcp_security.py::TestSecurityFeatures::test_sanitize_input_preserves_safe_content",
+          "state": "passed"
+        },
+        {
+          "name": "test_sanitize_empty_input",
+          "fullName": "tests/test_mcp_security.py::TestSecurityFeatures::test_sanitize_empty_input",
+          "state": "passed"
+        },
+        {
+          "name": "test_canopy_query_output_schema",
+          "fullName": "tests/test_mcp_security.py::TestStructuredOutput::test_canopy_query_output_schema",
+          "state": "passed"
+        },
+        {
+          "name": "test_canopy_query_output_validation",
+          "fullName": "tests/test_mcp_security.py::TestStructuredOutput::test_canopy_query_output_validation",
+          "state": "passed"
+        },
+        {
+          "name": "test_analysis_result_schema",
+          "fullName": "tests/test_mcp_security.py::TestStructuredOutput::test_analysis_result_schema",
+          "state": "passed"
+        },
+        {
+          "name": "test_analysis_result_complex_data",
+          "fullName": "tests/test_mcp_security.py::TestStructuredOutput::test_analysis_result_complex_data",
+          "state": "passed"
+        },
+        {
+          "name": "test_schema_validation_errors",
+          "fullName": "tests/test_mcp_security.py::TestStructuredOutput::test_schema_validation_errors",
+          "state": "passed"
+        },
+        {
+          "name": "test_json_serialization",
+          "fullName": "tests/test_mcp_security.py::TestStructuredOutput::test_json_serialization",
+          "state": "passed"
+        },
+        {
+          "name": "test_field_descriptions",
+          "fullName": "tests/test_mcp_security.py::TestStructuredOutput::test_field_descriptions",
+          "state": "passed"
+        },
+        {
+          "name": "test_sanitize_unicode_input",
+          "fullName": "tests/test_mcp_security.py::TestEdgeCases::test_sanitize_unicode_input",
+          "state": "passed"
+        },
+        {
+          "name": "test_canopy_output_edge_values",
+          "fullName": "tests/test_mcp_security.py::TestEdgeCases::test_canopy_output_edge_values",
+          "state": "passed"
+        },
+        {
+          "name": "test_analysis_result_empty_collections",
+          "fullName": "tests/test_mcp_security.py::TestEdgeCases::test_analysis_result_empty_collections",
+          "state": "passed"
+        }
+      ]
+    }
+  ]
+}

.env.example

@@ -0,0 +1,16 @@
+# MassGen API Keys Configuration
+# Copy this file to .env and add your actual API keys
+
+# OpenRouter - Recommended for multi-model access
+OPENROUTER_API_KEY=your_openrouter_api_key_here
+
+# Individual Provider Keys (optional if using OpenRouter)
+OPENAI_API_KEY=your_openai_api_key_here
+ANTHROPIC_API_KEY=your_anthropic_api_key_here
+GEMINI_API_KEY=your_gemini_api_key_here
+XAI_API_KEY=your_xai_api_key_here
+
+# Additional Configuration
+MASSGEN_LOG_LEVEL=INFO
+MASSGEN_TRACE_ENABLED=true
+MASSGEN_TRACE_DB_PATH=./traces.db

.flake8

@@ -0,0 +1,32 @@
+[flake8]
+max-line-length = 120
+extend-ignore = E203, W503, E501
+exclude =
+    .git,
+    __pycache__,
+    docs/source/conf.py,
+    old,
+    build,
+    dist,
+    .eggs,
+    .tox,
+    .venv,
+    venv,
+    env,
+    future_mass,
+    massgen/orchestrator.py,
+    massgen/agent.py,
+    massgen/agents.py,
+    massgen/backends/,
+    massgen/main.py,
+    massgen/streaming_display.py,
+    massgen/tools.py,
+    massgen/utils.py,
+    massgen/logging.py
+per-file-ignores =
+    __init__.py:F401
+    massgen/algorithms/*.py:F401
+max-complexity = 10
+count = True
+statistics = True
+show-source = True

.github/SETUP_SECRETS.md

@@ -0,0 +1,59 @@
+# GitHub Actions Secret Setup
+
+This document explains how to set up the required secrets for GitHub Actions.
+
+## Required Secrets
+
+### API Keys (for Integration Tests)
+
+These secrets are optional but recommended for running integration tests:
+
+- `OPENAI_API_KEY`: Your OpenAI API key
+- `GEMINI_API_KEY`: Your Google Gemini API key
+- `GROK_API_KEY`: Your Grok/X.AI API key
+
+### Code Coverage (Optional)
+
+- `CODECOV_TOKEN`: Token for uploading coverage reports to Codecov
+
+## How to Add Secrets
+
+1. Go to your repository on GitHub
+2. Click on "Settings" tab
+3. In the left sidebar, click "Secrets and variables" → "Actions"
+4. Click "New repository secret"
+5. Add each secret with its name and value
+
+## Security Best Practices
+
+1. **Never commit secrets to the repository**
+2. **Use minimal permissions** - Only grant the minimum required access
+3. **Rotate secrets regularly** - Update API keys periodically
+4. **Monitor usage** - Check your API usage dashboards regularly
+5. **Use environment-specific keys** - Don't use production keys for testing
+
+## Local Development
+
+For local development, create a `.env` file in the project root:
+
+```bash
+OPENAI_API_KEY=your_key_here
+GEMINI_API_KEY=your_key_here
+GROK_API_KEY=your_key_here
+```
+
+Make sure `.env` is in your `.gitignore` (it already is).
+
+## GitHub Actions Security
+
+The workflows are configured with minimal permissions:
+- Most jobs only have `contents: read`
+- Only the release workflow has `contents: write`
+- No workflows have access to other permissions unless explicitly needed
+
+## Monitoring
+
+You can monitor secret usage in:
+- GitHub Settings → Secrets → "Repository secrets" (shows last used)
+- Your API provider dashboards (OpenAI, Google Cloud, X.AI)
+- GitHub Actions logs (secrets are masked automatically)