moosey-cms 0.3.0__py3-none-any.whl

moosey_cms/helpers.py

@@ -0,0 +1,313 @@
+"""
+Copyright (c) 2026 Anthony Mugendi
+
+This software is released under the MIT License.
+https://opensource.org/licenses/MIT
+"""
+
+import os
+import frontmatter
+from pathlib import Path
+from typing import List, Dict, Any, Optional
+from jinja2 import TemplateNotFound
+from jinja2.sandbox import SandboxedEnvironment 
+from datetime import datetime
+from slugify import slugify
+from inflection import singularize
+from pprint import pprint
+from markupsafe import Markup
+
+from .models import Dirs
+from .md import parse_markdown
+from .cache import cache, cache_fn
+
+from .seo import seo_tags
+from . import filters
+
+# We initialize this once. It denies access to dangerous attributes like __class__
+_safe_env = SandboxedEnvironment(
+    trim_blocks=True,
+    lstrip_blocks=True
+)
+
+cache_debug = True
+
+
+def validate_model(MyModel, data):
+    if not isinstance(data, MyModel):
+        MyModel(**data)
+    return data
+
+@cache_fn(debug=cache_debug)
+def template_exists(templates, name: str) -> bool:
+    try:
+        templates.get_template(name)
+        return True
+    except TemplateNotFound as e:
+        return False
+
+
+@cache_fn(debug=cache_debug)
+def get_secure_target(user_path: str, relative_to_path: Path) -> Path:
+    """
+    Safely resolves a user-provided path against the relative_to_path.
+
+    1. Checks for null bytes (C-string exploit).
+    2. Resolves '..' and symlinks to finding the absolute path.
+    3. Ensures the resolved path is still inside relative_to_path.
+    """
+    # Prevent Null Byte Injection
+    if "\0" in user_path:
+        raise ValueError("Security Alert: Null byte detected in path.")
+
+    # Convert to path and strip leading slashes to ensure it joins correctly
+    # e.g., "/etc/passwd" becomes "etc/passwd" (relative)
+    clean_path = user_path.strip("/")
+
+    # Create the naive path
+    naive_path = relative_to_path / clean_path
+
+    try:
+        # Resolve: This converts symlinks and '..' to their real physical location
+        resolved_path = naive_path.resolve()
+    except OSError:
+        # Happens on Windows if path contains illegal chars like < > :
+        raise ValueError("Invalid characters in path.")
+
+    # The Firewall: strict check if the result is inside the jail
+    if not resolved_path.is_relative_to(relative_to_path):
+        raise ValueError(f"Path Traversal Attempt: {user_path}")
+
+    return resolved_path
+
+
+@cache_fn(debug=cache_debug)
+def find_best_template(templates, path_str: str, is_index_file: bool = False, frontmatter: Optional[dict] = None) -> str:
+    """
+    Determines the best template based on hierarchy or Frontmatter override.
+    """
+    
+    # 0. Check Frontmatter Override First
+    if frontmatter and frontmatter.get('template'):
+        candidate = frontmatter.get('template')
+        # Ensure it ends with .html if user forgot
+        if not candidate.endswith('.html'):
+            candidate += '.html'
+        
+        if template_exists(templates, candidate):
+            return candidate
+
+    parts = [p for p in path_str.strip("/").split("/") if p]
+
+    if len(parts) == 0:
+        index_candidate = 'index.html'
+        if template_exists(templates, index_candidate):
+            return index_candidate
+
+    # 1. Exact Match
+    if not is_index_file:
+        candidate = "/".join(parts) + ".html"
+        if template_exists(templates, candidate):
+            return candidate
+        if parts:
+            parts.pop()
+
+    # 2. Recursive Parent Search
+    while len(parts) > 0:
+        current_folder = parts[-1]
+        parent_path = parts[:-1]
+
+        # A. Singular Check
+        if not is_index_file:
+            singular_name = singularize(current_folder)
+            singular_candidate = "/".join(parent_path + [singular_name]) + ".html"
+            if template_exists(templates, singular_candidate):
+                return singular_candidate
+
+        # B. Plural/Folder Check
+        plural_candidate = "/".join(parts) + ".html"
+        if template_exists(templates, plural_candidate):
+            return plural_candidate
+
+        parts.pop()
+
+    # 3. Final Fallback
+    return "page.html"
+
+
+@cache_fn(debug=cache_debug)
+def parse_markdown_file(file):
+    data = frontmatter.load(file)
+    stats = file.stat()
+    
+    # Ensure date metadata exists
+    if "date" not in data.metadata or not isinstance(data.metadata["date"], dict):
+        data.metadata["date"] = {}
+        
+    data.metadata["date"]["updated"] = datetime.fromtimestamp(stats.st_mtime)
+    data.metadata["date"]["created"] = datetime.fromtimestamp(stats.st_ctime)
+    data.metadata["slug"] = slugify(str(file.stem))
+
+    data.html = parse_markdown(data.content)
+    return data
+
+
+# We need the sandbox to have the same filters (fancy_date, etc) as the main app
+def ensure_sandbox_filters(main_templates):
+    if not _safe_env.filters:
+        _safe_env.filters.update(main_templates.env.filters)
+        # Also copy globals if they are safe data (like site_data)
+        # BUT be careful not to copy 'request' or 'app' objects
+        safe_globals = {
+            k: v for k, v in main_templates.env.globals.items() 
+            if k in ['site_data', 'site_code', 'mode'] # Whitelist specific globals
+        }
+        _safe_env.globals.update(safe_globals)
+
+# template_render_content only in sandbox mode
+@cache_fn(debug=cache_debug) 
+def template_render_content(templates, content, data, safe=True):
+    if not content: return ""
+
+    try:
+        # Sync filters/globals from the main app to our sandbox
+        ensure_sandbox_filters(templates)
+        
+        # Use the SAFE environment, not the main one
+        template = _safe_env.from_string(content)
+        
+        # Render
+        rendered = template.render(**data)
+        return Markup(rendered) if safe else rendered
+    except Exception as e:
+        print(f"⚠️ Template Rendering Error: {e}")
+        # Fallback: Return raw content if injection fails, rather than crashing
+        return content
+
+@cache_fn(debug=cache_debug)
+def get_directory_navigation(
+    physical_folder: Path, current_url: str, relative_to_path: Path, mode: str = "production"
+) -> List[Dict[str, Any]]:
+    """
+    Scans folder for sidebar menu. Supports advanced frontmatter features.
+    """
+    if not physical_folder.exists() or not physical_folder.is_dir():
+        return []
+
+    items = []
+    try:
+        for entry in physical_folder.iterdir():
+            if entry.name.startswith("."): continue
+            if entry.name == "index.md": continue  
+            if entry.is_dir() and not (entry / 'index.md').exists(): continue
+
+            # Determine Metadata Source
+            meta_file = entry / 'index.md' if entry.is_dir() else entry
+            
+            # Defaults
+            sort_order = 9999
+            display_title = entry.stem.replace("-", " ").title()
+            nav_group = None
+            external_url = None
+            is_visible = True
+            target = "_self"
+
+            try:
+                # Load minimal metadata
+                post = frontmatter.load(meta_file)
+                meta = post.metadata
+
+                # 1. Visibility & Draft Check
+                if meta.get('visible') is False:
+                    is_visible = False
+                
+                if meta.get('draft') is True and mode != 'development':
+                    is_visible = False
+
+                
+                if not is_visible:
+                    continue
+
+                # 2. Ordering
+                if 'order' in meta: sort_order = int(meta['order'])
+                
+                # 3. Titles & Grouping
+                if 'nav_title' in meta: display_title = meta['nav_title']
+                elif 'title' in meta: display_title = meta['title']
+                
+                nav_group = meta.get('group') or "" 
+
+                # 4. External Links
+                if 'external_link' in meta:
+                    external_url = meta['external_link']
+                    target = "_blank"
+                elif 'redirect' in meta:
+                    external_url = meta['redirect']
+
+            except Exception:
+                pass 
+
+            # Build URL
+            if external_url:
+                entry_url = external_url
+                is_active = False # External links are never 'active' page
+            else:
+                try:
+                    rel_path = entry.relative_to(relative_to_path)
+                    url_slug = str(rel_path).replace(".md", "").replace("\\", "/")
+                    entry_url = f"/{url_slug}"
+                    is_active = (entry_url == current_url)
+                except ValueError:
+                    continue
+
+            items.append({
+                "name": display_title,
+                "url": entry_url,
+                "is_active": is_active,
+                "is_dir": entry.is_dir(),
+                "order": sort_order,
+                "group": nav_group,
+                "target": target
+            })
+            
+        # Sorting: order first, then Name
+        # items.sort(key=lambda x: (x['order'], x['name']))
+        group_min_orders = {}
+    
+        for item in items:
+            g = item['group']
+            w = item['order']
+            # If we haven't seen this group, or if this item is lighter (more important)
+            if g not in group_min_orders or w < group_min_orders[g]:
+                group_min_orders[g] = w
+
+        # 2. Sort the list with a Tuple Key
+        items.sort(key=lambda x: (
+            # Primary: Group order (Groups with important items float to top)
+            group_min_orders[x['group']], 
+            
+            # Secondary: Group Name (Keep groups clustered together)
+            x['group'], 
+            
+            # Tertiary: Item order (Sort items inside the group)
+            x['order'],
+            
+            # Quaternary: Item Name (Alphabetical fallback)
+            x['name']
+        ))
+
+    except OSError:
+        pass 
+
+    return items
+
+
+@cache_fn(debug=cache_debug)
+def get_breadcrumbs(url_path: str) -> List[Dict[str, str]]:
+    parts = [p for p in url_path.strip("/").split("/") if p]
+    crumbs = [{"name": "Home", "url": "/"}]
+    current = ""
+    for p in parts:
+        current += f"/{p}"
+        crumbs.append({"name": p.replace("-", " ").title(), "url": current})
+    return crumbs

moosey_cms/hot_reload_script.py

@@ -0,0 +1,91 @@
+"""
+Copyright (c) 2026 Anthony Mugendi
+
+This software is released under the MIT License.
+https://opensource.org/licenses/MIT
+"""
+
+from pathlib import Path
+from fastapi import FastAPI, Request, Response
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.types import ASGIApp
+
+
+class ScriptInjectorMiddleware(BaseHTTPMiddleware):
+    def __init__(self, app: ASGIApp, script: str):
+        super().__init__(app)
+        self.script = script
+
+    async def dispatch(self, request: Request, call_next):
+        # Process the request and get the response
+        response = await call_next(request)
+
+        # We only want to touch HTML pages, not JSON APIs or Images
+        content_type = response.headers.get("content-type", "")
+        # get content length
+        content_length = response.headers.get("content-length")
+
+        # Skip if not HTML
+        if "text/html" not in content_type:
+            return response
+
+        # Skip if too big (e.g. > 20KB) to prevent Memory DoS
+        if content_length and int(content_length) > 20 * 1024 :
+            return response
+
+
+        # Read the response body
+        # Note: Response body is a stream, we must consume it to modify it
+        response_body = [section async for section in response.body_iterator]
+        full_body = b"".join(response_body)
+
+        # Prepare the injection
+        # Encode the script to bytes
+        injection = self.script.encode("utf-8")
+
+        # Inject the script
+        # We look for the closing body tag
+        if b"</body>" in full_body:
+            full_body = full_body.replace(b"</body>", injection + b"</body>")
+        else:
+            # Fallback: Just append if no body tag found
+            full_body += injection
+
+        # Create a NEW Response object
+        # We cannot modify the existing response easily because Content-Length
+        # would be wrong. Creating a new one recalculates headers.
+        new_response = Response(
+            content=full_body,
+            status_code=response.status_code,
+            headers=dict(response.headers),
+            media_type=response.media_type,
+        )
+
+        # Remove Content-Length so Starlette recalculates it automatically
+        if "content-length" in new_response.headers:
+            del new_response.headers["content-length"]
+
+        return new_response
+
+
+def inject_script_middleware(app, host, port):
+    # Your custom script to inject
+    package_root = Path(__file__).resolve().parent
+    javascript_file = package_root / "static" / "js" / "reload-script.js"
+
+    if not javascript_file.exists():
+        print(f"⚠️  CMS Error: Hot reload script not found at: {js_file}")
+        return
+
+    with open(javascript_file, encoding="utf-8") as f:
+        content = f.read()
+
+    script_data = content.replace(
+        "{{host}}",
+        f"{host}:{port}",
+    )
+
+    # Add the middleware
+    app.add_middleware(
+        ScriptInjectorMiddleware, script=f"<script>{script_data}</script>"
+    )

moosey_cms/main.py

@@ -0,0 +1,283 @@
+"""
+Copyright (c) 2026 Anthony Mugendi
+
+This software is released under the MIT License.
+https://opensource.org/licenses/MIT
+"""
+
+import asyncio
+from pathlib import Path
+from inflection import singularize
+from fastapi import APIRouter, Request
+from pprint import pprint
+
+from fastapi.templating import Jinja2Templates
+
+
+from . import filters
+from . import helpers
+
+from .cache import clear_cache_on_file_change, clear_cache
+from .file_watcher import start_watching
+from .hot_reload_script import inject_script_middleware
+
+
+from fastapi import WebSocket, WebSocketDisconnect
+
+
+class ConnectionManager:
+    def __init__(self):
+        self.active_connections: list[WebSocket] = []
+
+    async def connect(self, websocket: WebSocket):
+        await websocket.accept()
+        self.active_connections.append(websocket)
+
+    def disconnect(self, websocket: WebSocket):
+        if websocket in self.active_connections:
+            self.active_connections.remove(websocket)
+
+    async def broadcast(self, message: str):
+        # Iterate over a copy to avoid modification errors
+        for connection in self.active_connections[:]:
+            try:
+                await connection.send_text(message)
+            except Exception:
+                self.disconnect(connection)
+
+
+from .models import CMSConfig, Dirs,  SiteData
+
+
+def init_cms(
+    app,
+    host: str,
+    port: int,
+    dirs: Dirs,
+    mode: str,
+    site_data: SiteData = {},
+):
+
+    # validate dirs inputs
+    CMSConfig(
+        host=host,
+        port=port,
+        dirs=dirs,
+        mode=mode,
+        site_data=site_data
+    )
+
+    # resolve paths
+    dirs = {k: p.resolve() for k, p in dirs.items()}
+
+    # create templates
+    # templates = Jinja2Templates(directory=str(dirs["templates"]))
+    templates = Jinja2Templates(directory=str(dirs["templates"]), extensions=[])
+
+    # Important for filters like seo to access them
+    app.state.site_data = site_data
+    app.state.mode = mode
+
+    # This ensures site_data is available in 404.html and base.html automatically
+    templates.env.globals["site_data"] = site_data
+    templates.env.globals["mode"] = mode
+
+    # Register all custom filters once
+    filters.register_filters(templates.env)
+
+    # We need to capture the current event loop to schedule the broadcast
+    loop = asyncio.get_event_loop()
+
+    # we want to watch even in production mode
+    # The logic is if one does a 'git pull' we want the site content to update
+    def on_change_callback(file_path, event_type):
+        # 1. Clear the cache (Sync)
+        clear_cache_on_file_change(file_path, event_type)
+
+        # 2. Trigger WebSocket Broadcast (Thread-safe Async call)
+        # This tells FastAPI loop to run the broadcast coroutine
+        if loop.is_running():
+            asyncio.run_coroutine_threadsafe(reloader.broadcast("reload"), loop)
+
+    # start watching dirs with the NEW combined callback
+    for d in dirs:
+        start_watching(dirs[d], on_change_callback)
+
+    reloader = None
+    # init manage hot reloading
+    if mode == "development":
+        reloader = ConnectionManager()
+        inject_script_middleware(app, host, port)
+
+    init_routes(app=app, dirs=dirs, templates=templates, reloader=reloader, mode=mode)
+
+    return app
+
+
+def init_routes(app, dirs: Dirs, templates, mode, reloader):
+
+    # init router
+    router = APIRouter()
+
+    # middleware to add security headers
+    @app.middleware("http")
+    async def add_security_headers(request: Request, call_next):
+        response = await call_next(request)
+        # Prevent MIME-sniffing
+        response.headers["X-Content-Type-Options"] = "nosniff"
+        # Enable XSS protection in older browsers
+        response.headers["X-XSS-Protection"] = "1; mode=block"
+        # Prevent clickjacking
+        response.headers["X-Frame-Options"] = "DENY"
+        return response
+
+    # only init hot reload websocket route in dvt mode
+    if mode == "development":
+
+        @app.websocket("/ws/hot-reload")
+        async def websocket_endpoint(websocket: WebSocket):
+            await reloader.connect(websocket)
+            try:
+                while True:
+                    # Keep connection open. We don't really care what the client sends
+                    # but we must await receive to keep the socket alive.
+                    await websocket.receive_text()
+            except WebSocketDisconnect:
+                reloader.disconnect(websocket)
+
+    @router.get("/{full_path:path}", include_in_schema=False)
+    async def catch_all(request: Request, full_path: str):
+
+        app = request.app
+
+        mode = app.state.mode
+
+        # if dvt mode, no caches
+        if mode == "development":
+            clear_cache()
+
+        # 1. Normalize Path
+        clean_path = full_path.strip("/")
+        if clean_path == "":
+            clean_path = "index"
+
+        # 2. Security: Resolve Path
+        try:
+            target_path_base = helpers.get_secure_target(
+                clean_path, relative_to_path=dirs["content"]
+            )
+        except ValueError:
+            # Path traversal detected or invalid chars
+            return templates.TemplateResponse(
+                "404.html", {"request": request}, status_code=404
+            )
+
+        # 3. File Resolution Logic
+        target_file: Path = None
+        is_index: bool = False
+
+        if target_path_base.is_dir():
+            target_file = target_path_base / "index.md"
+            is_index = True
+        else:
+            try:
+                target_file = helpers.get_secure_target(
+                    f"{clean_path}.md", relative_to_path=dirs["content"]
+                )
+                is_index = False
+            except ValueError:
+                return templates.TemplateResponse(
+                    "404.html", {"request": request}, status_code=404
+                )
+
+        # 4. Existence Check
+        if not target_file.exists():
+            return templates.TemplateResponse(
+                "404.html", {"request": request}, status_code=404
+            )
+
+        # 5. Load Content
+        # We use utf-8 strictly.
+        html_content = None
+
+        # Base template data (globals will be merged by Jinja automatically)
+        template_data = {}
+
+        try:
+            md_data = helpers.parse_markdown_file(target_file)
+            front_matter = md_data.metadata
+
+            # never render drafts in production
+            if front_matter.get("draft") is True and mode != "development":
+                return templates.TemplateResponse(
+                    "404.html", {"request": request}, status_code=404
+                )
+
+            # Merge front matter
+            template_data = {
+                **template_data,
+                **front_matter,
+                "site_data": app.state.site_data
+            }
+
+            # Render jinja inside frontmatter strings
+            for k in front_matter:
+                if isinstance(front_matter[k], str):
+                    front_matter[k] = helpers.template_render_content(
+                        templates, front_matter[k], template_data, False
+                    )
+
+            html_content = md_data.html
+
+            # Render jinja inside markdown body
+            html_content = helpers.template_render_content(
+                templates, html_content, template_data, False
+            )
+
+        except Exception as e:
+            print(f"Error rendering content: {e}")
+            return templates.TemplateResponse(
+                "404.html", {"request": request}, status_code=404
+            )
+
+        # 6. Determine Context Data (Nav, Breadcrumbs)
+        nav_folder = target_file.parent
+        current_url = f"/{clean_path}" if clean_path != "index" else "/"
+        nav_items = helpers.get_directory_navigation(
+            physical_folder=nav_folder,
+            current_url=current_url,
+            relative_to_path=dirs["content"],
+            mode=mode,
+        )
+        breadcrumbs = helpers.get_breadcrumbs(full_path)
+
+        # 7. Find Template
+        search_path = "" if clean_path == "index" else clean_path
+        template_name = helpers.find_best_template(
+            templates, search_path, is_index_file=is_index, frontmatter=front_matter
+        )
+
+        template_data = {**template_data, **md_data}
+
+        # pprint(nav_items)
+
+        # 8. Render
+        return templates.TemplateResponse(
+            template_name,
+            {
+                "app_state": request.app.state,
+                "request": request,
+                "content": html_content,
+                "title": template_data.get(
+                    "title", clean_path.split("/")[-1].replace("-", " ").title()
+                ),
+                "breadcrumbs": breadcrumbs,
+                "nav_items": nav_items,
+                "debug_template_used": template_name,
+                **template_data,
+            },
+        )
+
+    app.include_router(router, prefix="")
+
+    return router