`media/md_to_blog.py`

120 lines
#!/usr/bin/env python3
"""
md_to_blog.py — Transform any markdown file into a structured educational blog post.

Every blog MUST follow this structure:
1. What This Is
2. Why It Matters
3. How It Works
4. How You Can Build It Yourself
5. Security & Redaction Notes
6. Final Thoughts

Usage:
    python3 media/md_to_blog.py <source.md> <developer_name>
"""

import re
import sys
from pathlib import Path

BLOG_TEMPLATE = """# {title}

**By:** {developer}

## What This Is

{what_it_is}

## Why It Matters

{why_it_matters}

## How It Works

{how_it_works}

## How You Can Build It Yourself

{how_to_build}

## Security & Redaction Notes

This post intentionally excludes proprietary processes, vendor details,
pricing logic, internal credentials, and confidential operational data.
All examples are synthetic and generic. For redaction tooling, see
[snippets/redact_lint.py](../snippets/redact_lint.py).

## Final Thoughts

Build in public responsibly. Share the lessons, not the leverage.
"""


def extract_title(text: str) -> str:
    for line in text.split("\n"):
        if line.startswith("#"):
            return line.lstrip("#").strip()
    return "Untitled"


def extract_body(text: str) -> str:
    lines = text.split("\n")
    body_lines = []
    for line in lines[1:]:
        if line.startswith("**Intended date:") or line.startswith("**Author:"):
            continue
        body_lines.append(line)
    return "\n".join(body_lines).strip()


def extract_section(text: str, header: str) -> str:
    pattern = rf"##\s*{re.escape(header)}\s*\n(.*?)(?=\n##|\Z)"
    match = re.search(pattern, text, re.DOTALL | re.IGNORECASE)
    if match:
        return match.group(1).strip()
    return ""


def transform(md_path: str, developer: str) -> str:
    text = Path(md_path).read_text(encoding="utf-8")
    title = extract_title(text)
    body = extract_body(text)

    what_it_is = extract_section(text, "What I worked on") or body[:600]
    why_it_matters = extract_section(text, "What I learned") or (
        "Sharing systems thinking helps others build safely and efficiently."
    )
    how_it_works = extract_section(text, "What went wrong") or (
        "The system processes markdown into structured educational media."
    )

    return BLOG_TEMPLATE.format(
        title=title,
        developer=developer,
        what_it_is=what_it_is,
        why_it_matters=why_it_matters,
        how_it_works=how_it_works,
        how_to_build=(
            "1. Fork the [AgentAbrams/Public](https://github.com/AgentAbrams/Public) repository\n"
            "2. Install dependencies: `pip install -r requirements.txt`\n"
            "3. Write your markdown source file\n"
            "4. Run `aa build <your-file.md>` to generate all media outputs\n"
            "5. Review outputs in `media/output/` before publishing"
        ),
    )


def main():
    if len(sys.argv) < 3:
        print("Usage: md_to_blog.py <source.md> <developer_name>", file=sys.stderr)
        sys.exit(2)
    if not Path(sys.argv[1]).is_file():
        print(f"File not found: {sys.argv[1]}", file=sys.stderr)
        sys.exit(2)
    print(transform(sys.argv[1], sys.argv[2]))


if __name__ == "__main__":
    main()