moosey-cms 0.1.0__py3-none-any.whl

moosey_cms/helpers.py

@@ -0,0 +1,256 @@
+"""
+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
+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) -> str:
+    """
+    Determines the best template based on the path hierarchy.
+    path_str: The clean relative path (e.g. 'posts/stories/my-story')
+    is_index_file: True if we are rendering a directory index (e.g. 'posts/stories/index.md')
+    """
+
+    parts = [p for p in path_str.strip("/").split("/") if p]
+
+    # use index,html for home...
+    if len(parts)==0:
+        index_candidate = 'index.html'
+        if template_exists(templates, index_candidate):
+            return index_candidate
+
+
+    # 1. Exact Match (Specific File Override)
+    # We skip this for index files, as their "Exact Match" is essentially
+    # the folder name check in step 2B.
+    if not is_index_file:
+        candidate = "/".join(parts) + ".html"
+
+        if template_exists(templates, candidate):
+            return candidate
+
+        # If we didn't find specific 'my-story.html',
+        # pop the filename so we start searching from parent 'stories'
+        if parts:
+            parts.pop()
+
+    # 2. Recursive Parent Search
+    while len(parts) > 0:
+        current_folder = parts[-1]  # e.g. "stories"
+        parent_path = parts[:-1]  # e.g. ["posts"]
+
+        # A. Singular Check (The "Item" Template)
+        # e.g. "posts/story.html"
+        # Only valid if we are NOT rendering a directory list (index file)
+        if not is_index_file:
+            singular_name = singularize(current_folder)
+            singular_candidate = "/".join(parent_path + [singular_name]) + ".html"
+
+            print('>>>>parts', parts)
+
+            if template_exists(templates, singular_candidate):
+                return singular_candidate
+
+        # B. Plural/Folder Check (The "Section" Template)
+        # e.g. "posts/stories.html"
+        plural_candidate = "/".join(parts) + ".html"
+        if template_exists(templates, plural_candidate):
+            return plural_candidate
+
+        # Traverse up
+        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()
+    # Last date
+    data.metadata["date"] = {
+        "updated": datetime.fromtimestamp(stats.st_mtime),
+        "created": datetime.fromtimestamp(stats.st_ctime),
+    }
+    # add slug
+    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
+) -> List[Dict[str, Any]]:
+    """
+    Scans the folder containing the current file to generate a sidebar menu.
+    """
+    if not physical_folder.exists() or not physical_folder.is_dir():
+        return []
+
+    items = []
+    try:
+        # Iterate over files in the folder
+        for entry in sorted(
+            physical_folder.iterdir(), key=lambda x: (not x.is_dir(), x.name)
+        ):
+            if entry.name.startswith("."):
+                continue  # Skip hidden
+
+            # Skip self-reference if inside index
+            if entry.name == "index.md":
+                continue  
+
+            # if dir only list if it has an index.md
+            if  entry.is_dir() and not (entry / 'index.md').exists() :
+                continue
+
+
+            # Build URL
+            try:
+                rel_path = entry.relative_to(relative_to_path)
+                # Strip .md for URL, keep pure for directories
+                url_slug = str(rel_path).replace(".md", "").replace("\\", "/")
+                entry_url = f"/{url_slug}"
+            except ValueError:
+                continue
+
+            items.append(
+                {
+                    "name": entry.stem.replace("-", " ").title(),
+                    "url": entry_url,
+                    "is_active": entry_url == current_url,
+                    "is_dir": entry.is_dir(),
+                }
+            )
+    except OSError:
+        pass  # Ignore permission errors
+
+    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,281 @@
+"""
+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, SiteCode, SiteData
+
+
+def init_cms(
+    app,
+    host: str,
+    port: int,
+    dirs: Dirs,
+    mode: str,
+    site_data: SiteData = {},
+    site_code: SiteCode = {},
+):
+
+    # validate dirs inputs
+    CMSConfig(
+        host=host,
+        port=port,
+        dirs=dirs,
+        mode=mode,
+        site_data=site_data,
+        site_code=site_code,
+    )
+
+    # 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_code = site_code
+    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["site_code"] = site_code
+    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
+
+            # Merge front matter
+            template_data = {
+                **template_data,
+                **front_matter,
+                "site_data": app.state.site_data,
+                "site_code": app.state.site_code,
+            }
+
+
+            # 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"],
+        )
+        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
+        )
+
+        template_data = {**template_data, **md_data}
+
+        # 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