1432 Exports Skill 27a130ea

# Report Exporter Skill

## Overview
Exports TechStackReport from JSON format to alternative formats including Markdown, HTML, and PDF for different consumption needs and audiences.

## Metadata
- **Skill ID**: report_exporter
- **Version**: 1.0.0
- **Category**: Report Generation
- **Phase**: 5 (Report Generation)
- **Agent**: report_generation_agent
- **Execution Mode**: Sequential (last in report generation phase)

## Purpose
Converts structured JSON reports into human-readable formats optimized for different use cases: Markdown for documentation, HTML for web viewing, and PDF for formal presentations.

## Input Requirements

### Required Inputs
```json
{
  "report": {
    /* Complete TechStackReport JSON */
  },
  "export_format": "markdown|html|pdf",
  "output_path": "string (optional, defaults to outputs/techstack_reports/)"
}
```

### Optional Inputs
- `template`: Custom template for HTML/PDF generation
- `style`: Styling options (color scheme, fonts, etc.)
- `include_sections`: Array of sections to include (default: all)
- `exclude_low_confidence`: Boolean to hide low-confidence findings

## Operations

### Operation: export_to_markdown
Converts JSON report to Markdown format for documentation and version control.

**Input Parameters**:
- `report`: TechStackReport JSON
- `output_path`: Destination directory

**Markdown Structure**:
```markdown
# Technology Stack Report: {Company Name}

**Generated:** {Date}
**Primary Domain:** {Domain}
**Analysis Depth:** {Depth}
**Overall Confidence:** {Score} ({Rating})

---

## Executive Summary

This report identifies {N} technologies across {M} categories with an overall confidence score of {X}/1.0.

**Confidence Distribution:**
- High Confidence: {N} technologies ({X}%)
- Medium Confidence: {N} technologies ({X}%)
- Low Confidence: {N} technologies ({X}%)

---

## Discovered Assets

### Domains
- example.com
- www.example.com

### Subdomains
- api.example.com
- admin.example.com
- cdn.example.com

### IP Addresses
| IP Address | Provider | ASN | Region |
|------------|----------|-----|--------|
| 1.2.3.4 | AWS | AS16509 | us-east-1 |

### SSL/TLS Certificates
- **Common Name:** example.com
  - **Issuer:** Let's Encrypt
  - **Valid Until:** 2024-04-20
  - **SANs:** example.com, www.example.com, api.example.com

---

## Technologies Identified

### Frontend Technologies

#### React ⚡ **High Confidence**
- **Version:** 18.x
- **Category:** Framework

**Evidence:**
1. **JavaScript DOM Analysis** 🔍
   - Finding: React global object detected in window scope
   - Details: window.React and window.ReactDOM globals found
   - URL: https://example.com
   - Strength: Strong
   - Date: 2024-01-20

2. **HTML Content Analysis** 🔍
   - Finding: React-specific DOM attributes detected
   - Details: data-reactroot and data-reactid attributes found
   - Strength: Strong

3. **Job Posting Analysis** 💼
   - Finding: React mentioned in 5 job postings
   - Details: "Experience with React and Redux required"
   - Strength: Medium

---

### Backend Technologies

#### PostgreSQL 🔸 **Medium Confidence**
- **Category:** Database

**Evidence:**
1. **Job Posting Analysis** 💼
   - Finding: PostgreSQL mentioned in 8 job postings
   - Strength: Medium

⚠️ **Confidence Limitations:**
- No technical signals detected - based solely on job posting analysis
- Recommend verification via database error messages or connection strings

---

## Confidence Summary

| Category | High | Medium | Low | Avg Score |
|----------|------|--------|-----|-----------|
| Frontend | 12 | 5 | 1 | 0.82 |
| Backend | 8 | 9 | 3 | 0.65 |
| Infrastructure | 15 | 3 | 2 | 0.85 |
| Security | 5 | 2 | 1 | 0.73 |
| DevOps | 3 | 2 | 1 | 0.68 |
| Third-Party | 2 | 2 | 0 | 0.75 |

---

## Recommendations

1. Manually verify 8 low-confidence technologies
2. Consider additional analysis for medium-confidence findings
3. Review admin subdomain for separate technology stack

---

## Metadata

- **Intelligence Domains Queried:** 17
- **Total Signals Collected:** 247
- **Execution Time:** 145 seconds
- **Analysis Completeness:** 0.87

**Phase Durations:**
- Asset Discovery: 25s
- Data Collection: 60s
- Tech Inference: 35s
- Correlation: 15s
- Report Generation: 10s

---

*Report ID: {uuid}*
*Generated by Tech Stack Identification Agent v1.0*
```

**Process**:
1. **Parse JSON report**
2. **Generate markdown sections** (executive summary, assets, technologies)
3. **Format tables** for structured data
4. **Add emoji indicators** for confidence levels
5. **Include evidence** with citations
6. **Add recommendations** section
7. **Save to file**

**Output**:
```json
{
  "status": "success",
  "export_format": "markdown",
  "output_file": "outputs/techstack_reports/Acme_Corporation_20240120_100000.md",
  "file_size_bytes": 12456,
  "generation_time_ms": 450
}
```

### Operation: export_to_html
Converts JSON report to styled HTML for web viewing and sharing.

**Input Parameters**:
- `report`: TechStackReport JSON
- `output_path`: Destination directory
- `template`: HTML template (optional, defaults to built-in)

**HTML Structure**:
```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Tech Stack Report - {Company}</title>
    <style>
        /* Responsive CSS styling */
        body {
            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
            line-height: 1.6;
            max-width: 1200px;
            margin: 0 auto;
            padding: 20px;
            background: #f5f5f5;
        }
        .header {
            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
            color: white;
            padding: 40px;
            border-radius: 10px;
            margin-bottom: 30px;
        }
        .confidence-high { color: #10b981; font-weight: bold; }
        .confidence-medium { color: #f59e0b; font-weight: bold; }
        .confidence-low { color: #ef4444; font-weight: bold; }
        .technology-card {
            background: white;
            border-radius: 8px;
            padding: 20px;
            margin-bottom: 20px;
            box-shadow: 0 2px 4px rgba(0,0,0,0.1);
        }
        .evidence-item {
            border-left: 3px solid #667eea;
            padding-left: 15px;
            margin: 10px 0;
        }
        table {
            width: 100%;
            border-collapse: collapse;
            background: white;
        }
        th, td {
            padding: 12px;
            text-align: left;
            border-bottom: 1px solid #e5e7eb;
        }
        th {
            background: #f9fafb;
            font-weight: 600;
        }
    </style>
</head>
<body>
    <div class="header">
        <h1>Technology Stack Report</h1>
        <h2>{Company Name}</h2>
        <p><strong>Domain:</strong> {primary_domain}</p>
        <p><strong>Generated:</strong> {timestamp}</p>
        <p><strong>Overall Confidence:</strong> {score}/1.0 ({rating})</p>
    </div>

    <section id="executive-summary">
        <h2>Executive Summary</h2>
        <p>This report identifies {N} technologies with {X}% high confidence.</p>
        <div class="confidence-chart">
            <div class="confidence-high">{N} High Confidence ({X}%)</div>
            <div class="confidence-medium">{N} Medium Confidence ({X}%)</div>
            <div class="confidence-low">{N} Low Confidence ({X}%)</div>
        </div>
    </section>

    <section id="technologies">
        <h2>Technologies Identified</h2>

        <h3>Frontend Technologies</h3>
        <div class="technology-card">
            <h4 class="confidence-high">React <span class="badge">High Confidence</span></h4>
            <p><strong>Version:</strong> 18.x</p>

            <h5>Evidence</h5>
            <div class="evidence-item">
                <p><strong>Source:</strong> JavaScript DOM Analysis</p>
                <p><strong>Finding:</strong> React global object detected</p>
                <p><strong>Details:</strong> window.React and window.ReactDOM globals found</p>
                <p><strong>URL:</strong> <a href="https://example.com">https://example.com</a></p>
                <p><strong>Strength:</strong> Strong</p>
            </div>
        </div>
    </section>

    <section id="assets">
        <h2>Discovered Assets</h2>
        <table>
            <thead>
                <tr>
                    <th>IP Address</th>
                    <th>Provider</th>
                    <th>ASN</th>
                    <th>Region</th>
                </tr>
            </thead>
            <tbody>
                <tr>
                    <td>1.2.3.4</td>
                    <td>AWS</td>
                    <td>AS16509</td>
                    <td>us-east-1</td>
                </tr>
            </tbody>
        </table>
    </section>

    <section id="metadata">
        <h2>Analysis Metadata</h2>
        <ul>
            <li>Intelligence Domains: 17</li>
            <li>Signals Collected: 247</li>
            <li>Execution Time: 145s</li>
        </ul>
    </section>

    <footer>
        <p><small>Report ID: {uuid}</small></p>
        <p><small>Generated by Tech Stack Identification Agent v1.0</small></p>
    </footer>
</body>
</html>
```

**Features**:
- **Responsive design** (mobile-friendly)
- **Interactive navigation** (anchor links)
- **Color-coded confidence levels** (green/yellow/red)
- **Collapsible sections** (JavaScript accordion)
- **Print-optimized CSS** (@media print)

**Process**:
1. **Load HTML template**
2. **Parse JSON report**
3. **Populate template** with report data
4. **Generate CSS styles** based on theme
5. **Add interactive elements** (collapsible, tooltips)
6. **Validate HTML** (well-formed)
7. **Save to file**

**Output**:
```json
{
  "status": "success",
  "export_format": "html",
  "output_file": "outputs/techstack_reports/Acme_Corporation_20240120_100000.html",
  "file_size_bytes": 34567,
  "generation_time_ms": 850
}
```

### Operation: export_to_pdf
Converts JSON report to PDF format for formal presentations and archival.

**Input Parameters**:
- `report`: TechStackReport JSON
- `output_path`: Destination directory
- `template`: PDF template configuration

**PDF Features**:
- **Professional layout** with headers/footers
- **Table of contents** with page numbers
- **Color-coded sections** by technology category
- **Embedded hyperlinks** (evidence URLs)
- **Page numbers** and report metadata in footer

**Process**:
1. **Generate HTML version** (intermediate)
2. **Apply PDF-specific styling** (page breaks, margins)
3. **Render HTML to PDF** (using headless browser or library)
4. **Add PDF metadata** (title, author, keywords)
5. **Optimize file size** (compress images if any)
6. **Save to file**

**PDF Libraries** (implementation options):
- **wkhtmltopdf** - HTML to PDF converter
- **Playwright/Puppeteer** - Headless browser rendering
- **ReportLab** - Python PDF generation
- **WeasyPrint** - CSS-aware PDF rendering

**Output**:
```json
{
  "status": "success",
  "export_format": "pdf",
  "output_file": "outputs/techstack_reports/Acme_Corporation_20240120_100000.pdf",
  "file_size_bytes": 156789,
  "page_count": 12,
  "generation_time_ms": 3450
}
```

### Operation: export_multiple_formats
Exports report to multiple formats in a single operation.

**Input Parameters**:
- `report`: TechStackReport JSON
- `formats`: Array of formats ["markdown", "html", "pdf"]

**Process**:
1. **Iterate through requested formats**
2. **Call format-specific export** for each
3. **Collect output paths**
4. **Return all generated files**

**Output**:
```json
{
  "status": "success",
  "exports": [
    {
      "format": "markdown",
      "file": "outputs/techstack_reports/Acme_Corporation_20240120_100000.md",
      "size_bytes": 12456
    },
    {
      "format": "html",
      "file": "outputs/techstack_reports/Acme_Corporation_20240120_100000.html",
      "size_bytes": 34567
    },
    {
      "format": "pdf",
      "file": "outputs/techstack_reports/Acme_Corporation_20240120_100000.pdf",
      "size_bytes": 156789
    }
  ],
  "total_generation_time_ms": 4750
}
```

## Template System

### Custom Templates
Users can provide custom templates for HTML/PDF generation:

```json
{
  "template_type": "html",
  "template_path": "templates/custom_report.html",
  "variables": {
    "company_logo": "https://example.com/logo.png",
    "brand_color": "#667eea",
    "include_footer": true
  }
}
```

**Template Variables** (mustache-style):
- `{{company}}`
- `{{primary_domain}}`
- `{{generated_at}}`
- `{{overall_score}}`
- `{{technologies}}` (loop)
- `{{evidence}}` (nested loop)

### Built-in Templates
- **default**: Standard template with all sections
- **executive**: Executive summary focus, minimal technical details
- **technical**: Detailed technical evidence, all signals included
- **minimal**: Technologies and confidence only, no evidence details

## Output Formats Comparison

| Format | Use Case | File Size | Generation Time | Interactivity |
|--------|----------|-----------|-----------------|---------------|
| **JSON** | Programmatic access, storage | Small | Fast | None |
| **Markdown** | Documentation, version control | Small | Fast | None |
| **HTML** | Web viewing, sharing | Medium | Medium | High |
| **PDF** | Formal reports, printing | Large | Slow | Low |

## Output Format

### Success Output
```json
{
  "status": "success",
  "export_format": "html",
  "output_file": "outputs/techstack_reports/Acme_Corporation_20240120_100000.html",
  "file_size_bytes": 34567,
  "generation_time_ms": 850,
  "includes_sections": ["summary", "assets", "technologies", "confidence", "metadata"]
}
```

### Error Output
```json
{
  "status": "error",
  "error_code": "PDF_GENERATION_FAILED",
  "error_message": "PDF renderer not available - install wkhtmltopdf",
  "attempted_format": "pdf",
  "fallback_available": "html"
}
```

## Error Handling

### Missing Dependencies
- **IF PDF renderer not available** → Error with installation instructions
- **IF template file not found** → Fall back to default template
- **IF output directory not writable** → Error with permission details

### Malformed Report Data
- **IF report missing required fields** → Skip section, log warning
- **IF evidence array empty** → Display "No evidence recorded"
- **IF URLs invalid** → Format as plain text (no hyperlink)

### Generation Failures
- **IF HTML generation fails** → Return error with partial HTML
- **IF PDF rendering fails** → Suggest HTML export instead
- **IF file write fails** → Check disk space, permissions

## Dependencies

### Required Skills
- json_report_generator (provides JSON report)

### Required Libraries
- Markdown generation: Native string formatting
- HTML generation: Template engine (Jinja2, Mustache)
- PDF generation: wkhtmltopdf, Playwright, or WeasyPrint

### External Tools
- **wkhtmltopdf** (optional, for PDF export)
- **Chrome/Chromium** (optional, for PDF via Playwright)

## Configuration

### Settings (from settings.json)
```json
{
  "report_export": {
    "default_formats": ["json", "markdown", "html"],
    "output_directory": "outputs/techstack_reports/",
    "markdown_include_emoji": true,
    "html_template": "default",
    "html_theme": "professional",
    "pdf_renderer": "wkhtmltopdf",
    "pdf_page_size": "A4",
    "pdf_orientation": "portrait"
  }
}
```

## Usage Example

```json
{
  "operation": "export_to_html",
  "inputs": {
    "report": { /* TechStackReport JSON */ },
    "output_path": "outputs/techstack_reports/"
  },
  "options": {
    "template": "default",
    "exclude_low_confidence": false
  }
}
```

## Best Practices

1. **Keep JSON as source of truth** - Export from JSON, never edit exports directly
2. **Use appropriate format** - HTML for sharing, Markdown for docs, PDF for formal
3. **Test templates** - Validate with sample data before production use
4. **Optimize file sizes** - Compress images, minify HTML/CSS
5. **Version templates** - Track template changes separately

## Accessibility Considerations

### HTML Export
- **Semantic HTML** (proper heading hierarchy)
- **ARIA labels** for interactive elements
- **Alt text** for images (if used)
- **Keyboard navigation** support
- **Screen reader friendly** structure

### PDF Export
- **Tagged PDF** for accessibility
- **Proper heading hierarchy**
- **Readable font sizes** (minimum 10pt)
- **High contrast** text and backgrounds

## Limitations

- **PDF generation requires external tools** (not pure Python/JS)
- **Large reports may have slow PDF rendering** (3-5 seconds)
- **Custom templates require HTML/CSS knowledge**
- **Markdown has limited styling** (no colors, basic formatting only)
- **HTML requires modern browser** (may not work in IE11)

## Security Considerations

- **Sanitize all URLs** (prevent XSS in HTML export)
- **Validate file paths** (prevent directory traversal)
- **Escape HTML entities** (prevent injection in templates)
- **Set safe file permissions** (644 for exports)
- **No external resource loading** (inline all CSS/JS)

## Performance Optimization

### For Large Reports (>100 technologies)
- **Paginate HTML** (sections on separate pages)
- **Lazy load evidence** (collapsible, load on demand)
- **Compress PDF** (reduce file size)
- **Cache templates** (reuse for multiple exports)

### Parallel Export
```json
{
  "operation": "export_multiple_formats",
  "parallel": true,
  "formats": ["markdown", "html", "pdf"]
}
```

## Version History

- **1.0.0** (2024-01-20): Initial implementation with Markdown, HTML, and PDF export