main.jac

"""Jaseci Blogs backend.

Walkers that parse markdown posts and author metadata from the content
directory and serve them as JSON to the editorial frontend.

Content layout (read-only from this app's perspective):
  content/posts/*.md       — published + draft posts (draft: true is filtered)
  content/authors.yml      — author profiles
  docs/assets/             — images; posts reference them relatively and the
                             renderer rewrites onto asset_base_url() (GitHub raw)

Posts identify by the `slug:` frontmatter field, not filename. Files starting
with `_` are skipped (templates).
"""

import os;
import re;
import yaml;
import json;
import time;
import uuid;
import base64;
import hashlib;
import requests;
import from urllib.request { Request, urlopen }
import from urllib.parse { urlparse, parse_qs }
import markdown as md;
import from cryptography.fernet { Fernet }
import from jaclang.scale.identity.user_manager { JacScaleUserManager }
import from datetime { date as date_cls }
import from pathlib { Path }


glob JACLANG_ZIP = "docs/playground/jaclang.zip";


cl {
    def:pub app(props: any) -> JsxElement {
        can with entry {
            document.title = "Jaseci Blogs · engineering writing from the Jaseci & Jac ecosystem";
            existing: any = document.querySelector("link[rel='icon']");
            if not existing {
                icon: any = document.createElement("link");
                icon.rel = "icon";
                icon.type = "image/png";
                icon.href = "https://www.jaseci.org/images/logo.png";
                document.head.appendChild(icon);  # jac:ignore[E1030]
            }
            # Google Analytics (gtag.js). Injected once at the app root so the
            # tag loads on every route. Idempotent guard keeps a remount from
            # double-adding it. GA4 enhanced measurement tracks SPA route
            # changes via History events, so no per-navigation page_view here.
            existing_ga: any = document.querySelector("script[data-ga='G-RCKQSQP438']");
            if not existing_ga {
                ga_loader: any = document.createElement("script");
                ga_loader.setAttribute("async", "");
                ga_loader.src = "https://www.googletagmanager.com/gtag/js?id=G-RCKQSQP438";
                ga_loader.setAttribute("data-ga", "G-RCKQSQP438");
                document.head.appendChild(ga_loader);  # jac:ignore[E1030]

                ga_init: any = document.createElement("script");
                ga_init.text = "window.dataLayer = window.dataLayer || [];\nfunction gtag(){dataLayer.push(arguments);}\ngtag('js', new Date());\ngtag('config', 'G-RCKQSQP438');";
                document.head.appendChild(ga_init);  # jac:ignore[E1030]
            }
        }
        return <>{props.children}</>;
    }
}


# Content roots. During the migration we read from the legacy docs/blog/
# location so the mkdocs site keeps working as a reference. Step 10 of the
# migration moves these to content/posts/ + content/authors.yml.
glob POSTS_DIR = "docs/blog/posts";
glob AUTHORS_PATH = "docs/blog/.authors.yml";
glob EXCERPT_MARKER = "<!-- more -->";
glob READING_WPM = 220;
glob PEEK_LINES = 3;


def:priv format_date_long(date_str: str) -> str {
    try {
        parsed = date_cls.fromisoformat(date_str);
        return parsed.strftime("%B %d, %Y");
    } except Exception {
        return date_str;
    }
}


def:priv format_date_short(date_str: str) -> str {
    try {
        parsed = date_cls.fromisoformat(date_str);
        return parsed.strftime("%b %d, %Y");
    } except Exception {
        return date_str;
    }
}


def:priv _add_md_attr(m: any) -> str {
    tag = m.group(1);
    attrs = m.group(2) or "";
    return "<" + str(tag) + str(attrs) + ' markdown="1">';
}


def:priv inject_markdown_attr(body: str) -> str {
    # Lets authors mix raw HTML with markdown inside divs / figures / anchors,
    # matching the python-markdown md_in_html behavior used by mkdocs-material.
    # Skip tags that already carry an explicit markdown="..." attribute — we
    # use markdown="0" on mermaid blocks so their source survives unmodified.
    def _maybe_inject(m: any) -> str {
        tag = m.group(1);
        attrs = m.group(2) or "";
        if "markdown=" in attrs {
            return m.group(0);
        }
        return "<" + str(tag) + str(attrs) + ' markdown="1">';
    }
    return re.sub(r"<(div|figure|a)(\s+[^>]*)?>", _maybe_inject, body);
}


def:priv _escape_html(text: str) -> str {
    return text.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;");
}


def:priv convert_mermaid_fences(body: str) -> str {
    # Replace ```mermaid …``` fenced blocks with raw HTML that survives the
    # python-markdown pipeline (markdown="0" tells md_in_html to leave the
    # body alone). The client then calls mermaid.run on .mermaid-block.
    def _replace(m: any) -> str {
        source = m.group(1);
        return f'<div class="mermaid-block" markdown="0">{_escape_html(source)}</div>';
    }
    return re.sub(r"(?ms)^[ \t]*```mermaid[ \t]*\n(.*?)\n[ \t]*```[ \t]*$", _replace, body);
}


def:priv rewrite_asset_paths(body: str) -> str {
    # Posts authored against the mkdocs layout use relative links like
    # ../../assets/foo.png (from docs/blog/posts/) or ../assets/foo.png; some
    # posts instead hardcode the root-relative /assets/foo.png. Both forms are
    # normalised onto asset_base_url() so a post renders the same either way.
    base = asset_base_url() + "/";
    body = re.sub(r"(!\[[^\]]*\]\()(?:\.\./)+assets/", r"\1" + base, body);
    body = re.sub(r"(<img[^>]+src=[\"'])(?:\.\./)+assets/", r"\1" + base, body);
    body = body.replace("](/assets/", f"]({base}");
    body = body.replace('src="/assets/', f'src="{base}');
    body = body.replace("src='/assets/", f"src='{base}");
    return body;
}


def:priv strip_markdown_inline(text: str) -> str {
    # Used when deriving plain-text titles from a markdown H1 — drops bold,
    # italic, inline-code, and link syntax while preserving the visible text.
    text = re.sub(r"\*\*([^*]+)\*\*", r"\1", text);
    text = re.sub(r"__([^_]+)__", r"\1", text);
    text = re.sub(r"(?<!\*)\*([^*]+)\*(?!\*)", r"\1", text);
    text = re.sub(r"(?<!_)_([^_]+)_(?!_)", r"\1", text);
    text = re.sub(r"`([^`]+)`", r"\1", text);
    text = re.sub(r"\[([^\]]+)\]\([^)]*\)", r"\1", text);
    return text.strip();
}


def:priv estimate_reading_minutes(body: str) -> int {
    word_count = len(re.findall(r"\w+", body));
    minutes = max(1, round(word_count / READING_WPM));
    return int(minutes);
}


def:priv split_excerpt(body: str) -> tuple[str, str] {
    # Returns (excerpt_md, full_md). The excerpt is everything before the
    # <!-- more --> marker, falling back to the first paragraph.
    if EXCERPT_MARKER in body {
        parts = body.split(EXCERPT_MARKER, 1);
        return (parts[0].strip(), body.replace(EXCERPT_MARKER, "").strip());
    }
    # Fallback: first non-heading paragraph.
    paragraphs = re.split(r"\n\s*\n", body.strip());
    for p in paragraphs {
        stripped = p.strip();
        if stripped and not stripped.startswith("#") {  # jac:ignore[E1032]
            return (stripped, body);
        }
    }
    return ("", body);
}


def:priv extract_peek_markdown(body: str) -> str {
    # Mirror of scripts/inject_excerpt_peek.py:_extract_peek_markdown — the
    # next PEEK_LINES non-blank, non-heading lines after the <!-- more -->
    # marker, used as a faded teaser on the index card.
    if EXCERPT_MARKER not in body {
        return "";
    }
    after = body.split(EXCERPT_MARKER, 1)[1];
    kept: list[str] = [];
    non_blank = 0;
    in_fence = False;
    for raw in after.split("\n") {
        line = raw.rstrip();
        stripped = line.strip();
        # Skip fenced code blocks entirely — a partial fence renders as raw
        # "```" text in the teaser, and code is noise in a prose peek anyway.
        if stripped.startswith("```") or stripped.startswith("~~~") {
            in_fence = not in_fence;
            continue;
        }
        if in_fence {
            continue;
        }
        if not stripped {
            if kept {
                kept.append("");
            }
            continue;
        }
        # Skip structural noise and HTML/markup-only lines.
        if stripped.startswith("---") or stripped.startswith("#") or stripped.startswith("<!--") or stripped.startswith("<") {
            continue;
        }
        kept.append(line);
        non_blank = non_blank + 1;
        if non_blank >= PEEK_LINES {
            break;
        }
    }
    return "\n".join(kept).strip();
}


# Exact prefix python-markdown + codehilite (Pygments) emits for every
# highlighted block. We splice the source language back onto each one — see
# tag_code_languages.
glob HL_MARKER = "<div class=\"highlight\"><pre><span></span><code>";


def:priv parse_info_lang(info: str) -> str {
    # Normalize a fence info string into a bare language name:
    #   "jac" -> "jac", "{.jac}" -> "jac", "python title=x" -> "python".
    parts = info.strip().split();
    if not parts {
        return "";
    }
    token = parts[0].strip("{}").lstrip(".");
    if not token or ("=" in token) {
        return "";
    }
    return token;
}


def:priv extract_fence_langs(body: str) -> list {
    # Languages of each fenced code block, in source order. codehilite emits
    # one HL_MARKER per fence in the same order, so the lists align 1:1.
    langs = [];
    in_fence = False;
    fence = "";
    for raw in body.split("\n") {
        line = raw.strip();
        if not in_fence {
            if line.startswith("```") or line.startswith("~~~") {
                in_fence = True;
                fence = line[:3];
                langs.append(parse_info_lang(line[3:]));
            }
        } elif line.startswith(fence) {
            in_fence = False;
            fence = "";
        }
    }
    return langs;
}


def:priv tag_code_languages(html: str, body: str) -> str {
    # codehilite drops the fence language from its output, leaving jac and
    # python blocks indistinguishable. Splice `language-<lang>` back onto the
    # wrapper div and inner <code> so the frontend can label + style each.
    langs = extract_fence_langs(body);
    parts = html.split(HL_MARKER);
    if len(parts) <= 1 {
        return html;
    }
    out = parts[0];
    for i in range(1, len(parts)) {
        lang = "";
        if (i - 1) < len(langs) {
            lang = str(langs[i - 1]);
        }
        if lang {
            out = out + f"<div class=\"highlight language-{lang}\"><pre><span></span><code class=\"language-{lang}\">" + parts[i];
        } else {
            out = out + HL_MARKER + parts[i];
        }
    }
    return out;
}


def:priv render_markdown(body: str) -> str {
    html = md.markdown(
        body,
        extensions=[
            "fenced_code",
            "codehilite",
            "tables",
            "attr_list",
            "md_in_html",
            "footnotes",
            "toc",
            "admonition",
        ],
        extension_configs={
            "codehilite": {"guess_lang": False, "css_class": "highlight"},
            "toc": {"permalink": True, "permalink_class": "headerlink"},
        },
    );
    return tag_code_languages(html, body);
}


def:priv load_authors() -> dict {
    path = Path(AUTHORS_PATH);
    if not path.exists() {
        return {};
    }
    try {
        text = path.read_text(encoding="utf-8");
        data = yaml.safe_load(text);
    } except Exception {
        return {};
    }
    if not isinstance(data, dict) {
        return {};
    }
    authors = data.get("authors", {});
    if not isinstance(authors, dict) {
        return {};
    }
    return authors;
}


def:priv normalize_avatar(avatar: str) -> str {
    # Absolute URLs and root-relative paths pass through. Bare "assets/..."
    # (or "./assets/...") from .authors.yml is resolved against asset_base_url()
    # so it works regardless of the current page path.
    if not avatar {
        return "";
    }
    if avatar.startswith("http://") or avatar.startswith("https://") or avatar.startswith("/") {
        return avatar;
    }
    cleaned = avatar;
    while cleaned.startswith("./") or cleaned.startswith("../") {
        cleaned = cleaned.split("/", 1)[1];
    }
    if cleaned.startswith("assets/") {
        cleaned = cleaned.split("/", 1)[1];
    }
    return asset_base_url() + "/" + cleaned;
}


def:priv resolve_authors(author_ids: list, registry: dict) -> list {
    resolved = [];
    for aid in author_ids {
        key = str(aid);
        entry = registry.get(key);
        if isinstance(entry, dict) {
            resolved.append({
                "id": key,
                "name": str(entry.get("name", key)),
                "description": str(entry.get("description", "")),
                "avatar": normalize_avatar(str(entry.get("avatar", ""))),
            });
        } else {
            resolved.append({"id": key, "name": key, "description": "", "avatar": ""});
        }
    }
    return resolved;
}


def:priv parse_post_file(path: Path, registry: dict) -> dict | None {
    try {
        text = path.read_text(encoding="utf-8");
    } except Exception {
        return None;
    }

    if not text.startswith("---") {
        return None;
    }

    parts = text.split("---", 2);
    if len(parts) < 3 {
        return None;
    }

    frontmatter_text = parts[1];
    raw_body = parts[2].strip();

    try {
        meta = yaml.safe_load(frontmatter_text);
    } except Exception {
        return None;
    }

    if not isinstance(meta, dict) {
        return None;
    }

    if meta.get("draft", False) {
        return None;
    }

    slug = str(meta.get("slug", path.stem));
    raw_date = str(meta.get("date", ""));

    author_ids = meta.get("authors", []);
    if not isinstance(author_ids, list) {
        author_ids = [author_ids];
    }
    authors = resolve_authors(author_ids, registry);

    categories = meta.get("categories", []);
    if not isinstance(categories, list) {
        categories = [categories];
    }
    categories = [str(c) for c in categories];

    (excerpt_md, full_md) = split_excerpt(raw_body);
    peek_md = extract_peek_markdown(raw_body);
    full_md = rewrite_asset_paths(full_md);
    excerpt_md = rewrite_asset_paths(excerpt_md);
    peek_md = rewrite_asset_paths(peek_md);
    # Replace ```mermaid fences with markdown="0" raw HTML so the source
    # survives through python-markdown to the browser.
    full_md = convert_mermaid_fences(full_md);
    excerpt_md = convert_mermaid_fences(excerpt_md);
    peek_md = convert_mermaid_fences(peek_md);
    full_md_html_ready = inject_markdown_attr(full_md);
    excerpt_md_html_ready = inject_markdown_attr(excerpt_md);
    peek_md_html_ready = inject_markdown_attr(peek_md);

    # Derive title from first H1 if frontmatter doesn't give one.
    title = str(meta.get("title", ""));
    if not title {
        h1_found = re.search(r"(?m)^#\s+(.+)$", raw_body);
        title = h1_found.group(1).strip() if h1_found else slug.replace("-", " ").title();
    }
    title = strip_markdown_inline(title);

    description = str(meta.get("description", ""));

    # Repost support: a post can be a short write-up that links out to an
    # external article. `repost: true` is the author-facing "checkbox"; the
    # external link lives in `repost_url`. A post only counts as a repost if it
    # actually carries a link — the checkbox alone does nothing.
    repost_url = str(meta.get("repost_url", "")).strip();
    is_repost = bool(meta.get("repost", False)) and bool(repost_url);
    repost_source = str(meta.get("repost_source", "")).strip();

    return {
        "slug": slug,
        "filename": path.stem,
        "title": title,
        "date": raw_date,
        "date_long": format_date_long(raw_date),
        "date_short": format_date_short(raw_date),
        "authors": authors,
        "categories": categories,
        "description": description,
        "excerpt_md": excerpt_md_html_ready,
        "peek_md": peek_md_html_ready,
        "body_md": full_md_html_ready,
        "reading_minutes": estimate_reading_minutes(raw_body),
        "cover": str(meta.get("cover", "")),
        "is_repost": is_repost,
        "repost_url": repost_url,
        "repost_source": repost_source,
    };
}


def:priv list_all_posts() -> list {
    dir_path = Path(POSTS_DIR);
    if not dir_path.exists() {
        return [];
    }
    registry = load_authors();
    items = [];
    for path in sorted(dir_path.glob("*.md")) {
        if path.name.startswith("_") {
            continue;
        }
        parsed = parse_post_file(path, registry);
        if parsed is None {
            continue;
        }
        items.append(parsed);
    }
    # Newest first.
    items.sort(key=lambda(x: dict) -> str { return x["date"]; }, reverse=True);
    return items;
}


def:priv post_summary(post: dict) -> dict {
    excerpt_html = md.markdown(
        post["excerpt_md"],
        extensions=["fenced_code", "attr_list", "md_in_html"],
    ) if post["excerpt_md"] else "";
    peek_html = md.markdown(
        post["peek_md"],
        extensions=["fenced_code", "attr_list", "md_in_html"],
    ) if post["peek_md"] else "";
    return {
        "slug": post["slug"],
        "title": post["title"],
        "date": post["date"],
        "date_long": post["date_long"],
        "date_short": post["date_short"],
        "authors": post["authors"],
        "categories": post["categories"],
        "description": post["description"],
        "excerpt_html": excerpt_html,
        "peek_html": peek_html,
        "reading_minutes": post["reading_minutes"],
        "cover": post["cover"],
        "is_repost": post["is_repost"],
        "repost_url": post["repost_url"],
        "repost_source": post["repost_source"],
    };
}


walker:pub GetPosts {
    has page: int = 1;
    has per_page: int = 10;
    has category: str = "";
    has author: str = "";

    can get with Root entry {
        all_posts = list_all_posts();

        if self.category {
            all_posts = [p for p in all_posts if self.category in p["categories"]];
        }
        if self.author {
            all_posts = [
                p for p in all_posts
                if any(a["id"] == self.author for a in p["authors"])
            ];
        }

        total = len(all_posts);
        per = max(1, self.per_page);
        page_num = max(1, self.page);
        start = (page_num - 1) * per;
        end = start + per;
        window = all_posts[start:end];

        report {
            "ok": True,
            "total": total,
            "page": page_num,
            "per_page": per,
            "has_prev": page_num > 1,
            "has_next": end < total,
            "posts": [post_summary(p) for p in window],
        };
    }
}


def:priv peek_unpublished(slug: str) -> dict | None {
    # parse_post_file drops drafts entirely (returns None), so GetPost can't
    # otherwise tell an unpublished post apart from a genuinely missing one.
    # This does a lightweight frontmatter-only scan for a draft whose slug
    # matches, returning just enough to render the "coming soon" page.
    dir_path = Path(POSTS_DIR);
    if not dir_path.exists() {
        return None;
    }
    for path in sorted(dir_path.glob("*.md")) {
        if path.name.startswith("_") {
            continue;
        }
        try {
            text = path.read_text(encoding="utf-8");
        } except Exception {
            continue;
        }
        if not text.startswith("---") {
            continue;
        }
        parts = text.split("---", 2);
        if len(parts) < 3 {
            continue;
        }
        try {
            meta = yaml.safe_load(parts[1]);
        } except Exception {
            continue;
        }
        if not isinstance(meta, dict) {
            continue;
        }
        if not meta.get("draft", False) {
            continue;  # published posts are served by the normal path
        }
        file_slug = str(meta.get("slug", path.stem));
        if file_slug != slug {
            continue;
        }
        raw_body = parts[2].strip();
        title = str(meta.get("title", ""));
        if not title {
            h1_found = re.search(r"(?m)^#\s+(.+)$", raw_body);
            title = h1_found.group(1).strip() if h1_found else slug.replace("-", " ").title();
        }
        return {"slug": slug, "title": strip_markdown_inline(title)};
    }
    return None;
}


walker:pub GetPost {
    has slug: str = "";
    has preview: str = "";

    can get with Root entry {
        if not self.slug {
            report {"ok": False, "status": "error", "error": "missing slug"};
            return;
        }

        # Shareable draft preview: a valid token serves the PR's post even though
        # it is still draft:true. The doc re-pulls the PR head's current content
        # on view (refresh_preview_doc; usually already fresh from the
        # GetPreview redirect seconds earlier), so a persistent link tracks the
        # branch instead of freezing at creation time.
        if self.preview {
            shared_root = root.shared;  # jac:ignore[E1030] runtime attr, no static stub
            doc = match_preview([shared_root -->][?:PreviewDoc], self.preview);
            if doc is not None {
                refresh_preview_doc(doc);
                if doc.slug == self.slug {
                    report doc.data;
                    return;
                }
            }
        }

        registry = load_authors();
        dir_path = Path(POSTS_DIR);
        if not dir_path.exists() {
            report {"ok": False, "status": "error", "error": "posts directory not found"};
            return;
        }

        found = None;
        for path in dir_path.glob("*.md") {
            if path.name.startswith("_") {
                continue;
            }
            parsed = parse_post_file(path, registry);
            if parsed is None {
                continue;
            }
            if parsed["slug"] == self.slug {
                found = parsed;
                break;
            }
        }

        if found is None {
            pending = peek_unpublished(self.slug);
            if pending is not None {
                report {
                    "ok": False,
                    "status": "coming_soon",
                    "slug": pending["slug"],
                    "title": pending["title"],
                    "error": "not yet published",
                };
                return;
            }
            report {"ok": False, "status": "not_found", "error": "not found"};
            return;
        }

        html = render_markdown(found["body_md"]);

        # For reposts, fetch the external article's card metadata (og:title,
        # description, image) so the page can render a rich link card up top on
        # first paint. link_meta is cached and never raises.
        repost_meta: dict = {};
        if found["is_repost"] and found["repost_url"] {
            repost_meta = link_meta(str(found["repost_url"]));
        }

        # Adjacent posts (prev/next by date).
        all_posts = list_all_posts();
        prev_post = None;
        next_post = None;
        for (i, p) in enumerate(all_posts) {
            if p["slug"] == found["slug"] {  # jac:ignore[E1040]
                if i + 1 < len(all_posts) {
                    nxt = all_posts[i + 1];
                    next_post = {
                        "slug": nxt["slug"],
                        "title": nxt["title"],
                        "date_short": nxt["date_short"],
                    };
                }
                if i > 0 {
                    prv = all_posts[i - 1];
                    prev_post = {
                        "slug": prv["slug"],
                        "title": prv["title"],
                        "date_short": prv["date_short"],
                    };
                }
                break;
            }
        }

        # Related: same primary category, excluding self, capped at 3.
        related = [];
        if found["categories"] {
            primary = found["categories"][0];
            for p in all_posts {
                if p["slug"] == found["slug"] {
                    continue;
                }
                if primary in p["categories"] {
                    related.append(post_summary(p));
                }
                if len(related) >= 3 {
                    break;
                }
            }
        }

        report {
            "ok": True,
            "slug": found["slug"],
            "title": found["title"],
            "date": found["date"],
            "date_long": found["date_long"],
            "authors": found["authors"],
            "categories": found["categories"],
            "description": found["description"],
            "cover": found["cover"],
            "reading_minutes": found["reading_minutes"],
            "html": html,
            "prev": prev_post,
            "next": next_post,
            "related": related,
            "is_repost": found["is_repost"],
            "repost_url": found["repost_url"],
            "repost_source": found["repost_source"],
            "repost_meta": repost_meta,
        };
    }
}


walker:pub GetAuthor {
    has id: str = "";

    can get with Root entry {
        if not self.id {
            report {"ok": False, "error": "missing author id"};
            return;
        }
        registry = load_authors();
        entry = registry.get(self.id);
        if not isinstance(entry, dict) {
            report {"ok": False, "error": "not found"};
            return;
        }
        all_posts = list_all_posts();
        authored = [
            post_summary(p) for p in all_posts
            if any(a["id"] == self.id for a in p["authors"])
        ];
        report {
            "ok": True,
            "id": self.id,
            "name": str(entry.get("name", self.id)),
            "description": str(entry.get("description", "")),
            "avatar": str(entry.get("avatar", "")),
            "posts": authored,
        };
    }
}


walker:pub GetCategories {
    can get with Root entry {
        all_posts = list_all_posts();
        counts: dict = {};
        for p in all_posts {
            for c in p["categories"] {
                counts[c] = counts.get(c, 0) + 1;
            }
        }
        items = [{"name": k, "count": v} for (k, v) in counts.items()];
        items.sort(key=lambda(x: dict) -> int { return x["count"]; }, reverse=True);
        report {"ok": True, "categories": items};
    }
}


walker:pub GetArchive {
    can get with Root entry {
        all_posts = list_all_posts();
        # Group by year.
        years: dict = {};
        for p in all_posts {
            year = p["date"][:4] if len(p["date"]) >= 4 else "Undated";  # jac:ignore[E1053]
            if year not in years {
                years[year] = [];
            }
            years[year].append({
                "slug": p["slug"],
                "title": p["title"],
                "date_short": p["date_short"],
                "categories": p["categories"],
            });
        }
        grouped = [
            {"year": y, "posts": years[y]}
            for y in sorted(years.keys(), reverse=True)
        ];
        report {"ok": True, "years": grouped, "total": len(all_posts)};
    }
}


# ───────────────────────── Community timeline ─────────────────────────
#
# /blog/community renders ONE chronological spine that interleaves two kinds of
# entry:
#   • event — curated, from docs/blog/.events.yml (hand-edited, like
#             .authors.yml — NOT bot-owned the way .schedule.yml is)
#   • post  — a published "Community" post that no event claims
#
# An event claims a post by listing its slug under `posts:`; a claimed post
# renders inside the event card rather than as its own spine entry, so a
# hackathon and its three write-ups read as one moment instead of four. Nothing
# has to be registered in .events.yml for a Community post to show up — the file
# only adds event scaffolding around posts that have some.

glob EVENTS_PATH = "docs/blog/.events.yml";
glob COMMUNITY_CATEGORY = "Community";


def:priv load_events() -> list {
    path = Path(EVENTS_PATH);
    if not path.exists() {
        return [];
    }
    try {
        data = yaml.safe_load(path.read_text(encoding="utf-8"));
    } except Exception {
        return [];
    }
    if not isinstance(data, dict) {
        return [];
    }
    items = data.get("events", []);
    if not isinstance(items, list) {
        return [];
    }
    return [e for e in items if isinstance(e, dict)];
}


def:priv event_asset(raw: str) -> str {
    # Event imagery lives in docs/assets alongside post imagery, so it has to be
    # served from the repo and not the pod's public/ mount — see asset_base_url()
    # for why. Differs from normalize_avatar() in that "/assets/…" is rewritten
    # too: an avatar may legitimately be a root-relative path, an event cover
    # never is.
    val = str(raw or "").strip();
    if not val {
        return "";
    }
    if val.startswith("http://") or val.startswith("https://") {
        return val;
    }
    while val.startswith("./") or val.startswith("../") {
        val = val.split("/", 1)[1];
    }
    val = val.lstrip("/");
    if val.startswith("assets/") {
        val = val.split("/", 1)[1];
    }
    return asset_base_url() + "/" + val;
}


def:priv event_sort_key(ev: dict) -> str {
    # Sortable YYYY-MM-DD. A month- or year-precision entry sorts to the END of
    # its period, so a dated post from the same month can't jump above the event
    # it belongs beside.
    raw = str(ev.get("start", "")).strip();
    if len(raw) == 7 {
        return raw + "-31";
    }
    if len(raw) == 4 {
        return raw + "-12-31";
    }
    return raw;
}


def:priv event_date_label(ev: dict) -> str {
    override = str(ev.get("date_label", "")).strip();
    if override {
        return override;
    }
    start = str(ev.get("start", "")).strip();
    end = str(ev.get("end", "")).strip();
    if len(start) == 4 {
        return start;
    }
    if len(start) == 7 {
        try {
            return date_cls.fromisoformat(start + "-01").strftime("%B %Y");
        } except Exception {
            return start;
        }
    }
    if not end or end == start {
        return format_date_long(start);
    }
    try {
        s = date_cls.fromisoformat(start);
        e = date_cls.fromisoformat(end);
    } except Exception {
        return format_date_long(start);
    }
    if s.year == e.year and s.month == e.month {
        return s.strftime("%B") + " " + str(s.day) + "–" + str(e.day) + ", " + str(s.year);
    }
    if s.year == e.year {
        return (
            s.strftime("%b") + " " + str(s.day) + " – "
            + e.strftime("%b") + " " + str(e.day) + ", " + str(e.year)
        );
    }
    return format_date_short(start) + " – " + format_date_short(end);
}


def:priv timeline_post_ref(p: dict) -> dict {
    # Deliberately lighter than post_summary(): the timeline links out to posts,
    # it never renders their bodies, so no excerpt/peek HTML is built.
    return {
        "slug": p["slug"],
        "title": p["title"],
        "date": p["date"],
        "date_long": p["date_long"],
        "date_short": p["date_short"],
        "description": p["description"],
        "authors": p["authors"],
        "categories": p["categories"],
        "reading_minutes": p["reading_minutes"],
        "is_repost": p["is_repost"],
        "repost_url": p["repost_url"],
        "repost_source": p["repost_source"],
    };
}


def:priv event_entry(ev: dict, by_slug: dict, claimed: dict) -> dict {
    raw_slugs = ev.get("posts", []);
    slugs: list = [];
    if isinstance(raw_slugs, list) {
        slugs = raw_slugs;
    } else {
        slugs = [raw_slugs];
    }
    refs: list = [];
    for s in slugs {
        key = str(s);
        post = by_slug.get(key);
        # A slug with no published post behind it (draft, renamed, taken down)
        # is skipped rather than rendered as a dead link.
        if post is None {
            continue;
        }
        claimed[key] = True;
        refs.append(timeline_post_ref(post));
    }
    refs.sort(key=lambda(x: dict) -> str { return str(x["date"]); }, reverse=True);

    raw_stats = ev.get("stats", []);
    stats: list = raw_stats if isinstance(raw_stats, list) else [];
    raw_gallery = ev.get("gallery", []);
    gallery: list = raw_gallery if isinstance(raw_gallery, list) else [raw_gallery];

    return {
        "type": "event",
        "id": str(ev.get("id", "")),
        "kind": str(ev.get("kind", "Event")),
        "title": str(ev.get("title", "")),
        "date_label": event_date_label(ev),
        "location": str(ev.get("location", "")),
        "url": str(ev.get("url", "")),
        "summary": str(ev.get("summary", "")).strip(),
        "cover": event_asset(str(ev.get("cover", ""))),
        "gallery": [event_asset(str(g)) for g in gallery if str(g).strip()],
        "stats": [
            {"label": str(s.get("label", "")), "value": str(s.get("value", ""))}
            for s in stats if isinstance(s, dict)
        ],
        "posts": refs,
        "post_count": len(refs),
    };
}


walker:pub GetCommunityTimeline {
    can get with Root entry {
        all_posts = list_all_posts();
        by_slug: dict = {};
        for p in all_posts {
            by_slug[p["slug"]] = p;
        }

        claimed: dict = {};
        entries: list = [];

        for ev in load_events() {
            entry = event_entry(ev, by_slug, claimed);
            entry["sort"] = event_sort_key(ev);
            entries.append(entry);
        }

        for p in all_posts {
            if p["slug"] in claimed {
                continue;
            }
            if COMMUNITY_CATEGORY not in p["categories"] {
                continue;
            }
            entries.append({
                "type": "post",
                "id": p["slug"],
                "sort": p["date"],
                "post": timeline_post_ref(p),
            });
        }

        entries.sort(key=lambda(x: dict) -> str { return str(x["sort"]); }, reverse=True);

        # Group under year headings for the rail, preserving the sorted order.
        years: list = [];
        seen_years: dict = {};
        for e in entries {
            sort_key = str(e["sort"]);
            y = sort_key[:4] if len(sort_key) >= 4 else "Undated";  # jac:ignore[E1053]
            if y not in seen_years {
                seen_years[y] = {"year": y, "entries": []};
                years.append(seen_years[y]);
            }
            seen_years[y]["entries"].append(e);
        }

        report {"ok": True, "years": years};
    }
}


walker:pub GetSearchIndex {
    can get with Root entry {
        all_posts = list_all_posts();
        index = [];
        for p in all_posts {
            # Plain-text body for indexing — strip the most common markdown.
            plain = re.sub(r"`[^`]*`", "", p["body_md"]);  # jac:ignore[E1054]
            plain = re.sub(r"!\[[^\]]*\]\([^)]*\)", "", plain);  # jac:ignore[E1054]
            plain = re.sub(r"\[([^\]]+)\]\([^)]*\)", r"\1", plain);  # jac:ignore[E1054]
            plain = re.sub(r"[#>*_~]+", " ", plain);  # jac:ignore[E1054]
            plain = re.sub(r"\s+", " ", plain).strip();  # jac:ignore[E1054]
            index.append({
                "slug": p["slug"],
                "title": p["title"],
                "description": p["description"],
                "categories": p["categories"],
                "authors": [a["name"] for a in p["authors"]],
                "date_short": p["date_short"],
                "body": plain[:8000],
            });
        }
        report {"ok": True, "documents": index};
    }
}


walker:pub GetRuntimeZip {
    # Serves the prebuilt jaclang.zip as base64 for the in-browser Pyodide
    # runner. Delivered via walker (not static) because the dev/static server
    # doesn't serve arbitrary public/ files and filters non-image extensions.
    can get with Root entry {
        path = Path(JACLANG_ZIP);
        if not path.exists() {
            report {"ok": False, "error": "runtime bundle not found"};
            return;
        }
        try {
            data = path.read_bytes();
            b64 = base64.b64encode(data).decode("ascii");
            report {"ok": True, "b64": b64};
        } except Exception as e {
            report {"ok": False, "error": str(e)};
        }
    }
}


# ───────────────────────── Blog submission portal ─────────────────────────
#
# A /submit page lets a GitHub-authenticated visitor open a blog-post PR
# (with images) without touching git. GitHub is the only datastore — there is
# no DB, and there is NO GitHub App: every GitHub action runs AS THE SIGNED-IN
# USER via their OAuth token. Submitting forks the repo to the user's account,
# commits to a branch on that fork, and opens a cross-fork PR upstream — exactly
# how any open-source contribution works. So a plain (personally-creatable)
# OAuth App with `public_repo` scope is all that's needed; no org-owned app, no
# installation approval.
#
# The session is a jac-scale JWT (the browser stores it as `jac_token`). The
# user's OAuth token is needed again at submit time, so it's returned ENCRYPTED
# (Fernet) and the browser only ever holds ciphertext, passing it back per
# request as `gh_enc` for the server to decrypt. Reviewers (repo write access,
# read live from GitHub) get a review dashboard; its write-actions (merge,
# schedule, take-down) run with the reviewer's OWN access — merge on the PR page,
# slash-commands pasted as a PR comment — so nothing here needs elevated perms.
#
# Required env (k8s secrets — see .github/SUBMIT_FLOW.md):
#   GH_OAUTH_CLIENT_ID / GH_OAUTH_CLIENT_SECRET  — the OAuth App (sign-in + acts as user)
#   JWT_SECRET                                   — jac-scale's session JWT signing key
#   SUBMIT_SESSION_SECRET                        — Fernet key for the GitHub token at rest
#   GH_REPO (default jaseci-labs/jaseci-blogs) / GH_BASE_BRANCH (default main)

glob ALLOWED_CATEGORIES = [
    "Engineering", "Tutorials", "Built with Jac",
    "Community", "Announcements",
];  # intent-based buckets; a post may carry several (they act as tags)
glob MAX_IMAGE_BYTES = 100 * 1024;
glob MAX_IMAGES = 8;
glob ALLOWED_IMAGE_EXT = ["png", "jpg", "jpeg", "gif", "webp", "svg"];
# Marker text stamped into each submission PR body; also the search term that
# finds submissions (we can't add a label as the contributor, so the body
# marker is the index instead).
glob SUBMISSION_TAG = "blog-submission";
# Same idea for edits to ALREADY-PUBLISHED posts: stamped into the edit PR's body
# so open edit PRs for a given slug are findable with one search (collision check).
glob EDIT_TAG = "blog-edit";
glob GH_API = "https://api.github.com";
glob PREVIEW_TTL = 60 * 60 * 24 * 30;  # a preview link expires 1 month after its last view
glob PREVIEW_REFRESH_WINDOW = 30.0;  # seconds a refreshed snapshot is served without re-pulling the PR


node PreviewDoc {
    # A persisted, public draft-preview snapshot — ONE per PR, reused across
    # CreatePreview calls so the link a reviewer shares stays stable. Hung off
    # the shared public root (root.shared) and granted WritePerm (the PostStat
    # pattern) so an anonymous view can refresh the snapshot in place: each view
    # re-pulls the PR head's current post file (copy-edits included) and falls
    # back to the stored snapshot when the branch is gone. Holds the
    # fully-rendered GetPost-shaped payload so the real post page renders it
    # with runnable code blocks, mermaid, etc. Expires PREVIEW_TTL after the
    # last successful refresh (sliding, so an active PR's link never dies).
    has token: str = "";
    has slug: str = "";
    has data: dict = {};
    has created_at: float = 0.0;
    # Where to re-pull the live content from. Empty on docs created before this
    # feature — those keep serving their frozen snapshot untouched.
    has pr_number: int = 0;
    has head_repo: str = "";
    has head_ref: str = "";
    has post_path: str = "";
    has refreshed_at: float = 0.0;
}


node PostStat {
    # One reading-analytics bucket per (slug, day), hung off the public shared
    # root and granted WritePerm so anonymous readers (who run ON root.shared)
    # AND signed-in readers (who run on their own root but address the shared
    # node) can both increment it. Concurrent first-views can race and create
    # duplicate buckets for the same (slug, day); that's harmless — GetAnalytics
    # sums across every bucket, so duplicates just add up. No per-reader rows and
    # no PII: `visitors` holds short one-way hashes of an anonymous client id.
    has slug: str = "";
    has day: str = "";                          # "YYYY-MM-DD" (UTC)
    has views: int = 0;                         # total opens (every mount += 1)
    has visitors: list = [];                    # hashed anon visitor ids (unique opens)
    has dwell_ms_sum: float = 0.0;              # summed active reading time
    has dwell_samples: int = 0;                 # number of engagement flushes (one per visit)
    has scroll_pct_sum: float = 0.0;            # summed deepest-scroll % (for a true average)
    has scroll_samples: int = 0;                # number of scroll samples
    has scroll_buckets: list = [0, 0, 0, 0];    # [0-25), [25-50), [50-75), [75-100] depth-reached counts
}


node LinkClick {
    # Outbound/in-article link clicks, one bucket per (slug, href, day) on the
    # shared root (same race-tolerant, no-PII model as PostStat). GetAnalytics
    # sums across days into per-(slug, href) totals.
    has slug: str = "";
    has href: str = "";
    has day: str = "";
    has clicks: int = 0;
}


def:priv today_utc() -> str {
    # Date bucket key in UTC so all deployments agree regardless of server TZ.
    t = time.gmtime();
    return f"{t.tm_year:04d}-{t.tm_mon:02d}-{t.tm_mday:02d}";
}


def:priv hash_visitor(v: str) -> str {
    # One-way, truncated hash of the anonymous client-side visitor id. We never
    # store the raw id, so this can't be reversed to anything identifying.
    if not v {
        return "";
    }
    return hashlib.sha256(v.encode("utf-8")).hexdigest()[:16];
}


def:priv scroll_bucket(p: int) -> int {
    if p >= 75 {
        return 3;
    }
    if p >= 50 {
        return 2;
    }
    if p >= 25 {
        return 1;
    }
    return 0;
}


def:priv match_day_stat(nodes: list, slug: str, day: str) -> any {
    for n in nodes {
        if n.slug == slug and n.day == day {
            return n;
        }
    }
    return None;
}


def:priv match_link_click(nodes: list, slug: str, href: str, day: str) -> any {
    for n in nodes {
        if n.slug == slug and n.href == href and n.day == day {
            return n;
        }
    }
    return None;
}


def:priv median_scroll(buckets: list) -> int {
    # Bucketed median: walk the cumulative distribution to the halfway point and
    # report that bucket's midpoint. Coarse by design (we only keep 4 buckets).
    total: int = 0;
    for b in buckets {
        total += int(b);
    }
    if total == 0 {
        return 0;
    }
    midpoints = [12, 37, 62, 88];
    half = total / 2.0;
    cum: int = 0;
    for i in range(4) {
        cum += int(buckets[i]);
        if cum >= half {
            return midpoints[i];
        }
    }
    return midpoints[3];
}


def:priv env_str(name: str, fallback: str = "") -> str {
    val = os.environ.get(name, fallback);
    if val is None {
        return fallback;
    }
    return str(val);
}


def:priv gh_repo() -> str {
    return env_str("GH_REPO", "jaseci-labs/jaseci-blogs");
}


def:priv gh_base_branch() -> str {
    return env_str("GH_BASE_BRANCH", "main");
}


def:priv public_site_url() -> str {
    return env_str("PUBLIC_SITE_URL", "https://blogs.jaseci.org").rstrip("/");
}


def:priv asset_base_url() -> str {
    # Where a PUBLISHED post's images are served from. Default: the repo itself on
    # GitHub raw, NOT the pod's own public/ mount.
    #
    # The pod never holds a durable copy of the repo — it pulls code through
    # code-sync -> RWO PVC -> tar -> HTTP -> emptyDir (.github/CODE_SYNC_RWO_FIX.md).
    # When that chain drops public/, EVERY image on the site 404s at once while the
    # posts themselves still render: posts are read from docs/, and images were the
    # only thing sitting behind the public/assets symlink. Serving images from the
    # repo takes the pod filesystem out of the path entirely, so a torn code sync
    # can no longer blank the site's images.
    #
    # Set ASSET_BASE_URL to override — notably ASSET_BASE_URL=/assets restores
    # local-disk serving, which is what you want when iterating on an image that is
    # not merged to the base branch yet.
    default = f"https://raw.githubusercontent.com/{gh_repo()}/{gh_base_branch()}/docs/assets";
    return env_str("ASSET_BASE_URL", default).rstrip("/");
}


def:priv fernet() -> any {
    # Symmetric cipher for the GitHub user token at rest in the session. Key is
    # derived from SUBMIT_SESSION_SECRET so no extra secret to manage.
    secret = env_str("SUBMIT_SESSION_SECRET") or "dev-only-insecure-secret";
    key = base64.urlsafe_b64encode(hashlib.sha256(secret.encode("utf-8")).digest());
    return Fernet(key);
}


def:priv encrypt_token(tok: str) -> str {
    if not tok {
        return "";
    }
    try {
        return fernet().encrypt(tok.encode("utf-8")).decode("ascii");
    } except Exception {
        return "";
    }
}


def:priv decrypt_gh(ct: str) -> str {
    # Decrypt the GitHub user token the browser hands back. The browser only ever
    # holds Fernet ciphertext; the server decrypts it per request to act on
    # GitHub as the user. jac-scale's bearer token handles WHO the caller is;
    # this ciphertext is the separate "act on GitHub" capability.
    if not ct {
        return "";
    }
    try {
        return str(fernet().decrypt(ct.encode("ascii")).decode("utf-8"));
    } except Exception {
        return "";
    }
}


def:priv mint_session_token(login: str) -> str {
    # Hand the session off to jac-scale instead of hand-rolling a JWT. Each
    # GitHub identity maps to a jac-scale user (created on first sign-in); we mint
    # a token for it. jac-scale signs/validates with JWT_SECRET — no key
    # management here. The user's password is random and never used: identity is
    # proven by GitHub OAuth, and we mint the token directly rather than via
    # /user/login.
    if not login {
        return "";
    }
    um = JacScaleUserManager(base_path="");
    user = um.find_user_by_identity(login);
    if user is not None {
        user_id = str(user.get("user_id", ""));
    } else {
        # Use the high-level convenience (username + password) rather than the
        # low-level create_user(identities=...): its signature differs across
        # jac-scale versions, so create_internal_user keeps us version-agnostic.
        created = um.create_internal_user(login, uuid.uuid4().hex);
        user_id = str(created.get("user_id", ""));
    }
    if not user_id {
        return "";
    }
    # include_role=False: skip the extra user-store role lookup — this app gates
    # on live GitHub repo permission (has_write_access), not jac-scale roles.
    return str(um.create_jwt_token(user_id, include_role=False));
}


def:priv gh_headers(token: str) -> dict {
    return {
        "Authorization": f"token {token}",
        "Accept": "application/vnd.github+json",
        "X-GitHub-Api-Version": "2022-11-28",
        "User-Agent": "jaseci-blogs-submit",
    };
}


def:priv gh_ok(r: any, what: str) -> dict {
    # Return the JSON dict on a 2xx; otherwise raise with the status + GitHub's
    # message so failures surface as "create blob failed [403] ..." instead of a
    # bare KeyError('sha') three calls later.
    try {
        data = r.json();
    } except Exception {
        data = {};
    }
    if r.status_code >= 200 and r.status_code < 300 {
        return data if isinstance(data, dict) else {"_data": data};
    }
    msg = str(data.get("message", "")) if isinstance(data, dict) else "";
    raise ValueError(f"{what} failed [{r.status_code}] {msg}");
}


def:priv oauth_exchange_code(code: str, redirect_uri: str) -> dict | None {
    client_id = env_str("GH_OAUTH_CLIENT_ID");
    client_secret = env_str("GH_OAUTH_CLIENT_SECRET");
    if not client_id or not client_secret or not code {
        return None;
    }
    body = {"client_id": client_id, "client_secret": client_secret, "code": code};
    if redirect_uri {
        body["redirect_uri"] = redirect_uri;
    }
    try {
        r = requests.post(
            "https://github.com/login/oauth/access_token",
            headers={"Accept": "application/json", "User-Agent": "jaseci-blogs-submit"},
            json=body, timeout=30,
        );
        tok = r.json().get("access_token", "");
        if not tok {
            return None;
        }
        u = requests.get(
            f"{GH_API}/user",
            headers={
                "Authorization": f"token {tok}",
                "Accept": "application/vnd.github+json",
                "User-Agent": "jaseci-blogs-submit",
            },
            timeout=30,
        ).json();
    } except Exception {
        return None;
    }
    if not isinstance(u, dict) or "login" not in u {
        return None;
    }
    return {
        "login": str(u.get("login", "")),
        "uid": int(u.get("id", 0)),
        "name": str(u.get("name") or u.get("login", "")),
        "avatar": str(u.get("avatar_url", "")),
        "token": str(tok),
    };
}


def:priv has_write_access(token: str) -> bool {
    # Ask GitHub what THIS user can do on the repo: GET /repos returns a
    # `permissions` block for the authenticated caller. push/maintain/admin = reviewer.
    if not token {
        return False;
    }
    try {
        r = requests.get(f"{GH_API}/repos/{gh_repo()}", headers=gh_headers(token), timeout=30);
        if r.status_code != 200 {
            return False;
        }
        perms = r.json().get("permissions", {});
        if not isinstance(perms, dict) {
            return False;
        }
        return bool(perms.get("admin") or perms.get("maintain") or perms.get("push"));
    } except Exception {
        return False;
    }
}


def:priv gh_user(token: str) -> dict {
    # The signed-in user's GitHub identity, read live from their own token (so
    # it's authoritative — used to authorize "edit/list your own submissions" and
    # to build the author entry). Replaces the profile that used to ride inside
    # the hand-rolled session JWT; shaped like oauth_exchange_code's profile.
    if not token {
        return {};
    }
    try {
        u = requests.get(f"{GH_API}/user", headers=gh_headers(token), timeout=30).json();
    } except Exception {
        return {};
    }
    if not isinstance(u, dict) or "login" not in u {
        return {};
    }
    return {
        "login": str(u.get("login", "")),
        "uid": int(u.get("id", 0)),
        "name": str(u.get("name") or u.get("login", "")),
        "avatar": str(u.get("avatar_url", "")),
    };
}


def:priv is_valid_slug(slug: str) -> bool {
    return bool(re.match(r"^[a-z0-9]+(?:-[a-z0-9]+)*$", slug));
}


def:priv slug_taken(slug: str) -> bool {
    dir_path = Path(POSTS_DIR);
    if not dir_path.exists() {
        return False;
    }
    for path in dir_path.glob("*.md") {
        if path.name.startswith("_") {
            continue;
        }
        try {
            text = path.read_text(encoding="utf-8");
        } except Exception {
            continue;
        }
        if not text.startswith("---") {
            continue;
        }
        parts = text.split("---", 2);
        if len(parts) < 3 {
            continue;
        }
        try {
            meta = yaml.safe_load(parts[1]);
        } except Exception {
            continue;
        }
        if isinstance(meta, dict) and str(meta.get("slug", path.stem)) == slug {
            return True;
        }
    }
    return False;
}


def:priv load_scheduled_slugs() -> dict {
    # Map slug -> publish_at for entries still queued (scheduled or held).
    path = Path("docs/blog/.schedule.yml");
    result: dict = {};
    if not path.exists() {
        return result;
    }
    try {
        data = yaml.safe_load(path.read_text(encoding="utf-8"));
    } except Exception {
        return result;
    }
    if not isinstance(data, dict) {
        return result;
    }
    entries = data.get("schedule", []);
    if not isinstance(entries, list) {
        return result;
    }
    for e in entries {
        if not isinstance(e, dict) {
            continue;
        }
        if e.get("status") in ["scheduled", "held"] {
            s = str(e.get("slug", ""));
            if s {
                result[s] = str(e.get("publish_at", ""));
            }
        }
    }
    return result;
}


glob TEAM_AUTHOR_ID = "jaseci-team";  # shared byline; reviewers only (see .authors.yml)


def:priv resolve_author_id(profile: dict, bio: str) -> tuple {
    # Returns (author_id, new_entry_or_None). Reuse an existing .authors.yml
    # entry whose avatar references this GitHub numeric id, or whose key matches
    # the login. Otherwise create a new entry keyed by the (sanitized) login.
    registry = load_authors();
    login = str(profile.get("login", "")).lower();
    uid = str(profile.get("uid", ""));
    for (key, entry) in registry.items() {
        if not isinstance(entry, dict) {
            continue;
        }
        avatar = str(entry.get("avatar", ""));
        if uid and f"/u/{uid}" in avatar {
            return (str(key), None);
        }
        if str(key).lower() == login {
            return (str(key), None);
        }
    }
    new_id = re.sub(r"[^a-z0-9-]", "-", login) or "contributor";
    new_entry = {
        "id": new_id,
        "name": str(profile.get("name", login)),
        "description": bio or "Contributor",
        "avatar": str(profile.get("avatar", "")),
    };
    return (new_id, new_entry);
}


def:priv is_http_url(u: str) -> bool {
    s = u.strip().lower();
    return s.startswith("http://") or s.startswith("https://");
}


def:priv decode_body_md(body_md: str, is_b64: bool) -> str {
    # The /submit client base64-encodes the post body so its raw markdown — shell
    # snippets like `curl … | bash`, URLs — doesn't trip the edge WAF's content
    # rules, which 403 the walker request before it ever reaches us. Decode it back
    # to real markdown here. Plain-text bodies (is_b64=False, e.g. an older client)
    # pass through untouched.
    if not is_b64 {
        return body_md;
    }
    try {
        return str(base64.b64decode(body_md.encode("ascii")).decode("utf-8"));
    } except Exception {
        return body_md;
    }
}


def:priv build_post_markdown(
    title: str, slug: str, categories: list, description: str,
    author_id: str, body: str,
    is_repost: bool = False, repost_url: str = "", repost_source: str = ""
) -> str {
    today = date_cls.today().isoformat();
    lines: list = ["---", f"date: {today}", "authors:", f"  - {author_id}", "categories:"];
    for c in categories {
        lines.append(f"  - {c}");
    }
    if description {
        lines.append(f"description: {json.dumps(description)}");
    }
    lines.append(f"slug: {slug}");
    # A repost links out to an external article via these keys (parsed back into
    # is_repost/repost_url/repost_source). Only emitted when a URL is present.
    if is_repost and repost_url.strip() {
        lines.append("repost: true");
        lines.append(f"repost_url: {json.dumps(repost_url.strip())}");
        if repost_source.strip() {
            lines.append(f"repost_source: {json.dumps(repost_source.strip())}");
        }
    }
    lines.append("draft: true");
    lines.append("---");
    fm = "\n".join(lines);
    body_text: str = body.strip();
    if not body_text.startswith("#") {
        body_text = f"# {title}\n\n{body_text}";
    }
    return f"{fm}\n\n{body_text}\n";
}


def:priv authors_yml_with(new_entry: dict) -> str | None {
    path = Path(AUTHORS_PATH);
    try {
        text = path.read_text(encoding="utf-8");
    } except Exception {
        return None;
    }
    block = (
        f"  {new_entry['id']}:\n"
        + f"    name: {json.dumps(new_entry['name'])}\n"
        + f"    description: {json.dumps(new_entry['description'])}\n"
        + f"    avatar: {json.dumps(new_entry['avatar'])}\n"
    );
    if not text.endswith("\n") {
        text = f"{text}\n";
    }
    return f"{text}{block}";
}


def:priv ensure_fork(token: str, login: str) -> str {
    # Fork the upstream repo into the user's account (idempotent — returns the
    # existing fork if present). Forking is ASYNC: GitHub returns the repo record
    # before the git objects are copied, so poll the branch *ref* (not just the
    # repo) until it resolves — that's when blobs/trees/commits will succeed.
    repo = gh_repo();
    base_branch = gh_base_branch();
    name = repo.split("/", 1)[1] if "/" in repo else repo;
    fork_full = f"{login}/{name}";
    h = gh_headers(token);
    gh_ok(requests.post(f"{GH_API}/repos/{repo}/forks", headers=h, timeout=30), "fork repo");
    i = 0;
    while i < 30 {
        r = requests.get(f"{GH_API}/repos/{fork_full}/git/ref/heads/{base_branch}", headers=h, timeout=30);
        if r.status_code == 200 and isinstance(r.json().get("object"), dict) {
            return fork_full;
        }
        time.sleep(2);
        i = i + 1;
    }
    raise ValueError("fork did not become ready in time — try again in a moment");
}


def:priv build_commit(token: str, repo_full: str, base_sha: str, files: list, message: str) -> str {
    # Create blobs/tree/commit on top of base_sha; return the new commit sha.
    # Text files go inline in the tree; images become base64 blobs first.
    h = gh_headers(token);
    base_commit = gh_ok(requests.get(f"{GH_API}/repos/{repo_full}/git/commits/{base_sha}", headers=h, timeout=30), "read base commit");
    base_tree = str(base_commit["tree"]["sha"]);

    tree_items = [];
    for f in files {
        if f.get("binary") {
            blob = gh_ok(requests.post(
                f"{GH_API}/repos/{repo_full}/git/blobs",
                headers=h, json={"content": f["content"], "encoding": "base64"}, timeout=30,  # jac:ignore[E1053]
            ), "create image blob");
            tree_items.append({"path": f["path"], "mode": "100644", "type": "blob", "sha": str(blob["sha"])});
        } else {
            tree_items.append({"path": f["path"], "mode": "100644", "type": "blob", "content": f["content"]});
        }
    }
    new_tree = gh_ok(requests.post(
        f"{GH_API}/repos/{repo_full}/git/trees",
        headers=h, json={"base_tree": base_tree, "tree": tree_items}, timeout=30,  # jac:ignore[E1053]
    ), "create tree");
    new_commit = gh_ok(requests.post(
        f"{GH_API}/repos/{repo_full}/git/commits",
        headers=h, json={"message": message, "tree": str(new_tree["sha"]), "parents": [base_sha]}, timeout=30,  # jac:ignore[E1053]
    ), "create commit");
    return str(new_commit["sha"]);
}


def:priv commit_to_repo(
    token: str, repo_full: str, branch: str, base_branch: str,
    files: list, message: str
) -> None {
    # First commit on a NEW branch (forked off base_branch).
    h = gh_headers(token);
    ref = gh_ok(requests.get(f"{GH_API}/repos/{repo_full}/git/ref/heads/{base_branch}", headers=h, timeout=30), "read base ref");
    new_sha = build_commit(token, repo_full, str(ref["object"]["sha"]), files, message);
    gh_ok(requests.post(
        f"{GH_API}/repos/{repo_full}/git/refs",
        headers=h, json={"ref": f"refs/heads/{branch}", "sha": new_sha}, timeout=30,
    ), "create branch");
}


def:priv commit_update(token: str, repo_full: str, branch: str, files: list, message: str) -> None {
    # Add a commit ON TOP of an existing branch (updates an open PR). Bases the
    # commit on the branch's current head and fast-forwards the ref.
    h = gh_headers(token);
    ref = gh_ok(requests.get(f"{GH_API}/repos/{repo_full}/git/ref/heads/{branch}", headers=h, timeout=30), "read branch ref");
    new_sha = build_commit(token, repo_full, str(ref["object"]["sha"]), files, message);
    gh_ok(requests.patch(
        f"{GH_API}/repos/{repo_full}/git/refs/heads/{branch}",
        headers=h, json={"sha": new_sha, "force": False}, timeout=30,
    ), "update branch");
}


def:priv suggestion_fence(content: str) -> str {
    # A ```suggestion block has to out-fence everything inside it, and blog posts
    # are full of ```jac / ```mermaid fences. Find the longest backtick run in the
    # content and go one longer.
    longest = 0;
    run = 0;
    for ch in content {
        if ch == "`" {
            run = run + 1;
            longest = run if run > longest else longest;
        } else {
            run = 0;
        }
    }
    return "`" * (longest + 1 if longest >= 3 else 3);
}


def:priv suggest_whole_file(
    token: str, pr_number: int, path: str, commit_id: str,
    new_content: str, line_count: int, note: str
) -> str {
    # Post an edit as a multi-line ```suggestion covering the file's entire
    # right-hand side, so the author applies it with one click. Legal only when
    # every line is in the PR diff (an ADDED file) — GitHub 422s a comment on a
    # line outside the diff. Returns the comment's html_url.
    fence = suggestion_fence(new_content);
    body = f"{note}\n\n{fence}suggestion\n{new_content.rstrip()}\n{fence}\n";
    payload = {
        "body": body,
        "commit_id": commit_id,
        "path": path,
        "line": line_count,
        "side": "RIGHT",
    };
    # start_line must be strictly less than line; a 1-line file is a single-line
    # comment instead.
    if line_count > 1 {
        payload["start_line"] = 1;
        payload["start_side"] = "RIGHT";
    }
    res = gh_ok(requests.post(
        f"{GH_API}/repos/{gh_repo()}/pulls/{pr_number}/comments",
        headers=gh_headers(token), json=payload, timeout=30,  # jac:ignore[E1053]
    ), "post suggestion");
    return str(res.get("html_url", ""));
}


def:priv comment_on_pr(token: str, pr_number: int, body: str) -> str {
    # Plain PR comment — the last-resort delivery route. Needs nothing beyond
    # read access to the repo, so it always works.
    res = gh_ok(requests.post(
        f"{GH_API}/repos/{gh_repo()}/issues/{pr_number}/comments",
        headers=gh_headers(token), json={"body": body}, timeout=30,
    ), "post comment");
    return str(res.get("html_url", ""));
}


def:priv deliver_edit(
    token: str, pr: dict, files: list, message: str, post_md: str, editor: str
) -> dict {
    # Deliver a REVIEWER's edit to someone else's submission by the strongest
    # route GitHub allows, degrading in order:
    #
    #   1. commit     — push straight onto the PR's branch on the author's fork.
    #      Needs "Allow edits by maintainers" AND that grant to extend to the Git
    #      Data API. GitHub documents the grant as push access to the branch and
    #      tightened REST authorization for maintainer fork collaborators in 2021
    #      without saying which endpoints survived, so blob/tree creation on the
    #      fork may 403. We attempt it rather than predict it.
    #   2. suggestion — a whole-file ```suggestion the author applies in one
    #      click. Needs the post file to be ADDED by the PR (every submission is).
    #   3. comment    — the proposed markdown as a plain PR comment.
    #
    # Only the commit route can carry images; the other two are markdown-only, so
    # they say so rather than silently dropping the uploads.
    n = int(pr["pr_number"]);
    why = "";
    if bool(pr["maintainer_can_modify"]) {
        try {
            commit_update(token, str(pr["head_repo"]), str(pr["head_ref"]), files, message);
            return {"mode": "commit", "url": str(pr["pr_url"]), "note": ""};
        } except Exception as e {
            why = f"pushing to the fork branch was refused (`{e}`)";
        }
    } else {
        why = "**Allow edits by maintainers** is off for this pull request";
    }

    extra = len(files) - 1;
    img_note = f"\n\n> ⚠️ {extra} image upload(s) could not be included — only the post markdown can travel this way. Re-upload them yourself, or turn on **Allow edits by maintainers**." if extra > 0 else "";
    note = (
        f"**Editorial revision from @{editor}.** Applying this replaces the post "
        f"with the reviewed version.\n\n"
        f"_Delivered as a suggestion because {why}._" + img_note
    );

    if str(pr["post_status"]) == "added" {
        try {
            url = suggest_whole_file(
                token, n, str(pr["post_path"]), str(pr["head_sha"]),
                post_md, len(post_md.rstrip().splitlines()), note,
            );
            return {"mode": "suggestion", "url": url, "note": why};
        } except Exception as e {
            why = f"{why}, and the suggestion was rejected (`{e}`)";
        }
    } else {
        why = f"{why}, and the post file is modified rather than added by this PR so a whole-file suggestion is not applicable";
    }

    fence = suggestion_fence(post_md);
    body = (
        f"**Editorial revision from @{editor}.**\n\n"
        f"_Posted as a comment because {why}._{img_note}\n\n"
        f"Copy this over `{pr['post_path']}` to apply it:\n\n"
        f"{fence}markdown\n{post_md.rstrip()}\n{fence}\n"
    );
    url = comment_on_pr(token, n, body);
    return {"mode": "comment", "url": url, "note": why};
}


def:priv submit_via_fork(
    token: str, login: str, branch: str, files: list, message: str,
    pr_title: str, pr_body: str
) -> dict {
    # Open the PR entirely AS THE USER: fork → sync fork's default branch →
    # commit to a branch on the fork → open a cross-fork PR to upstream. No app,
    # no privileged token — just the contributor's own public_repo access.
    base_branch = gh_base_branch();
    fork_full = ensure_fork(token, login);
    # Bring the fork's default branch up to date with upstream (no-op for a fresh
    # fork; matters for a returning contributor whose fork is stale).
    try {
        requests.post(
            f"{GH_API}/repos/{fork_full}/merge-upstream",
            headers=gh_headers(token), json={"branch": base_branch}, timeout=30,
        );
    } except Exception {
        _ignore = None;
    }
    commit_to_repo(token, fork_full, branch, base_branch, files, message);
    pr = gh_ok(requests.post(
        f"{GH_API}/repos/{gh_repo()}/pulls",
        headers=gh_headers(token),
        json={  # jac:ignore[E1053]
            "title": pr_title, "head": f"{login}:{branch}", "base": base_branch,
            "body": pr_body,
            # Explicit rather than relying on the API default: this is what lets a
            # reviewer commit a copy-edit straight onto the submission. The author
            # can still turn it off on the PR page.
            "maintainer_can_modify": True,
        },
        timeout=30,
    ), "open pull request");
    return pr;
}


def:priv rewrite_assets_to_raw(body: str, repo: str, sha: str) -> str {
    # For reviewer previews: point asset references at the raw blobs on the PR's
    # head ref, so images render before the post is merged + deployed.
    base = f"https://raw.githubusercontent.com/{repo}/{sha}/docs/assets/";
    body = re.sub(r"(!\[[^\]]*\]\()(?:\.\./)+assets/", r"\1" + base, body);
    body = re.sub(r"(<img[^>]+src=[\"'])(?:\.\./)+assets/", r"\1" + base, body);
    body = body.replace("](/assets/", f"]({base}");
    body = body.replace('src="/assets/', f'src="{base}');
    body = body.replace("src='/assets/", f"src='{base}");
    return body;
}


def:priv fetch_pr_authors(token: str, repo: str, sha: str) -> dict {
    # A PR that introduces a new author adds their entry to .authors.yml on its
    # own head ref. The deployed server only has main's copy, so resolve_authors
    # misses and the byline falls back to the raw author id ("thejoshbrod") with
    # no avatar. Read the file from the PR's ref instead — the same trick
    # rewrite_assets_to_raw uses for images that aren't on main yet.
    #
    # Best-effort by design, matching fetch_pr_post: any failure (no token, the
    # PR deletes the file, malformed yaml, a rate-limit object in place of the
    # blob) returns {} and the caller keeps main's registry, which is exactly
    # today's behaviour. A preview must never 500 over a byline.
    if not token or not repo or not sha {
        return {};
    }
    try {
        blob = requests.get(
            f"{GH_API}/repos/{repo}/contents/{AUTHORS_PATH}",
            headers=gh_headers(token), params={"ref": sha}, timeout=30,
        ).json();
        if not isinstance(blob, dict) {
            return {};
        }
        text = base64.b64decode(str(blob.get("content", ""))).decode("utf-8");
        data = yaml.safe_load(text);
    } except Exception {
        return {};
    }
    if not isinstance(data, dict) {
        return {};
    }
    authors = data.get("authors", {});
    if not isinstance(authors, dict) {
        return {};
    }
    return authors;
}


def:priv render_submitted_markdown(
    text: str, raw_repo: str, raw_sha: str, gh_token: str = ""
) -> dict {
    # Draft-tolerant render of a raw post file (parse_post_file drops drafts).
    # Reuses the same pipeline GetPost uses so previews match the live look.
    meta: dict = {};
    raw_body = text;
    if text.startswith("---") {
        parts = text.split("---", 2);
        if len(parts) >= 3 {
            try {
                loaded = yaml.safe_load(parts[1]);
                meta = loaded if isinstance(loaded, dict) else {};
            } except Exception {
                meta = {};
            }
            raw_body = parts[2].strip();
        }
    }
    registry = load_authors();
    # The PR's copy wins for the ids it defines, so a preview shows both a
    # brand-new author and an edit an existing author made to their own entry
    # in the same PR. Ids the PR doesn't mention still come from main.
    registry = {**registry, **fetch_pr_authors(gh_token, raw_repo, raw_sha)};
    author_ids = meta.get("authors", []);
    if not isinstance(author_ids, list) {
        author_ids = [author_ids];
    }
    authors = resolve_authors(author_ids, registry);
    categories = meta.get("categories", []);
    if not isinstance(categories, list) {
        categories = [categories];
    }
    categories = [str(c) for c in categories];
    title = str(meta.get("title", ""));
    if not title {
        h1 = re.search(r"(?m)^#\s+(.+)$", raw_body);
        title = h1.group(1).strip() if h1 else str(meta.get("slug", "")).replace("-", " ").title();
    }
    title = strip_markdown_inline(title);
    if raw_repo and raw_sha {
        body = rewrite_assets_to_raw(raw_body, raw_repo, raw_sha);
    } else {
        body = rewrite_asset_paths(raw_body);
    }
    body = convert_mermaid_fences(body);
    body = inject_markdown_attr(body);
    html = render_markdown(body);
    # Repost card: parse the frontmatter keys and fetch the external article's
    # metadata so previews show the same card the live post page renders.
    repost_url = str(meta.get("repost_url", "")).strip();
    is_repost = bool(meta.get("repost", False)) and bool(repost_url);
    repost_meta: dict = {};
    if is_repost {
        repost_meta = link_meta(repost_url);
    }
    return {
        "title": title,
        "slug": str(meta.get("slug", "")),
        "description": str(meta.get("description", "")),
        "authors": authors,
        "categories": categories,
        "draft": bool(meta.get("draft", False)),
        "reading_minutes": estimate_reading_minutes(raw_body),
        "html": html,
        "is_repost": is_repost,
        "repost_url": repost_url,
        "repost_source": str(meta.get("repost_source", "")),
        "repost_meta": repost_meta,
    };
}


def:priv fetch_pr_post(token: str, pr_number: int) -> dict | None {
    # Read the single post file a PR touches (from the PR's head ref). Defensive
    # by design: any malformed or error GitHub response — rate-limit object, a
    # deleted/inaccessible head fork, a transient 5xx — returns None instead of
    # raising, so callers report a clean "could not load that PR" rather than a
    # 500 that surfaces to the user as "Network error". Shared by the reviewer
    # preview, the shareable-preview creator, and the edit walkers.
    try {
        h = gh_headers(token);
        repo = gh_repo();
        pr = requests.get(f"{GH_API}/repos/{repo}/pulls/{pr_number}", headers=h, timeout=30).json();
        if not isinstance(pr, dict) or not isinstance(pr.get("head"), dict) {
            return None;
        }
        head = pr["head"];
        head_repo_obj = head.get("repo");
        if not isinstance(head_repo_obj, dict) {
            return None;
        }
        head_sha = str(head.get("sha", ""));
        head_repo = str(head_repo_obj.get("full_name", ""));
        owner_obj = head_repo_obj.get("owner");
        head_owner = str(owner_obj.get("login", "")) if isinstance(owner_obj, dict) else "";
        if not head_repo {
            return None;
        }
        files = requests.get(
            f"{GH_API}/repos/{repo}/pulls/{pr_number}/files",
            headers=h, params={"per_page": 100}, timeout=30,
        ).json();
        if not isinstance(files, list) {
            # e.g. a rate-limit / error object instead of the file array.
            return None;
        }
        post_path = "";
        post_status = "";
        for f in files {
            if not isinstance(f, dict) {
                continue;
            }
            fn = str(f.get("filename", ""));
            if fn.startswith("docs/blog/posts/") and fn.endswith(".md") {
                post_path = fn;
                # "added" (a new submission) means every line of the file is in
                # the diff, which is what makes a whole-file ```suggestion legal.
                post_status = str(f.get("status", ""));
                break;
            }
        }
        if not post_path {
            return None;
        }
        blob = requests.get(
            f"{GH_API}/repos/{head_repo}/contents/{post_path}",
            headers=h, params={"ref": head_sha}, timeout=30,
        ).json();
        if not isinstance(blob, dict) {
            return None;
        }
        content = base64.b64decode(str(blob.get("content", ""))).decode("utf-8");
    } except Exception {
        return None;
    }
    return {
        "content": content,
        "post_path": post_path,
        "post_status": post_status,
        "pr_number": pr_number,
        "head_repo": head_repo,
        "head_ref": str(head.get("ref", "")),
        "head_owner": head_owner,
        "head_sha": head_sha,
        "state": str(pr.get("state", "")),
        "merged": bool(pr.get("merged_at")),
        "pr_url": str(pr.get("html_url", "")),
        "mergeable": pr.get("mergeable"),
        "mergeable_state": str(pr.get("mergeable_state", "")),
        # The author's "Allow edits by maintainers" checkbox. Only settable on
        # PRs from user-owned forks, and revocable at any time — so reviewers'
        # edit routing reads it live per request, never from cache.
        "maintainer_can_modify": bool(pr.get("maintainer_can_modify")),
    };
}


def:priv preview_payload(rendered: dict) -> dict {
    # Shape render_submitted_markdown output into the GetPost-style payload the
    # post page expects, so a preview renders identically to a live post.
    return {
        "ok": True,
        "slug": str(rendered["slug"]),
        "title": str(rendered["title"]),
        "description": str(rendered["description"]),
        "authors": rendered["authors"],
        "categories": rendered["categories"],
        "date": "",
        "date_long": "Preview",
        "reading_minutes": rendered["reading_minutes"],
        "cover": "",
        "html": rendered["html"],
        "prev": None,
        "next": None,
        "related": [],
        "is_preview": True,
        "is_repost": bool(rendered["is_repost"]),
        "repost_url": str(rendered["repost_url"]),
        "repost_source": str(rendered["repost_source"]),
        "repost_meta": rendered["repost_meta"],
    };
}


def:priv refresh_preview_doc(doc: PreviewDoc) -> None {
    # Re-pull the PR head's current post file so a persistent preview link
    # always shows the branch's latest content, copy-edits included. Reads the
    # file from raw.githubusercontent.com — public forks need no token, which
    # matters because previews are opened anonymously. Best-effort by design:
    # any failure (branch deleted, PR merged, network, render error) leaves the
    # stored snapshot serving — stale beats broken. The refreshed_at window
    # keeps the GetPreview-redirect → GetPost pair from fetching twice per view.
    if not doc.head_repo or not doc.post_path {
        return;  # pre-feature doc: frozen snapshot, nothing to refresh from
    }
    now = float(time.time());
    if (now - doc.refreshed_at) < PREVIEW_REFRESH_WINDOW {
        return;
    }
    try {
        ref = doc.head_ref or "HEAD";
        resp = requests.get(
            f"https://raw.githubusercontent.com/{doc.head_repo}/{ref}/{doc.post_path}",
            timeout=10,
        );
        if resp.status_code != 200 {
            return;
        }
        rendered = render_submitted_markdown(resp.text, doc.head_repo, ref, "");
        # Reassign (not mutate) so jac-scale persists the change.
        doc.data = preview_payload(rendered);
        doc.slug = str(rendered["slug"]);
        doc.refreshed_at = now;
        doc.created_at = now;  # sliding TTL: an actively-viewed link never expires
    } except Exception {
        return;
    }
}


def:priv match_preview(docs: list, token: str) -> any {
    # Pick a non-expired PreviewDoc matching token from a pre-collected list
    # (the edge traversal happens in the walker ability where it's valid).
    if not token {
        return None;
    }
    now = float(time.time());
    for d in docs {
        if d.token == token and (now - d.created_at) <= PREVIEW_TTL {  # jac:ignore[E1055]
            return d;
        }
    }
    return None;
}


walker:priv CreatePreview {
    has gh_enc: str = "";
    has pr_number: int = 0;
    # The browser's current origin, so the shareable link points at THIS
    # deployment (localhost in dev, blogs.jaseci.org in prod) instead of the
    # hardcoded PUBLIC_SITE_URL fallback. Falls back to public_site_url() if
    # the caller doesn't pass one.
    has origin: str = "";

    can make with Root entry {
        gh_token = decrypt_gh(self.gh_enc);
        if not gh_token {
            report {"ok": False, "error": "not signed in"};
            return;
        }
        if not self.pr_number {
            report {"ok": False, "error": "missing pr_number"};
            return;
        }
        try {
            pr = fetch_pr_post(gh_token, self.pr_number);
        } except Exception as e {
            report {"ok": False, "error": f"could not load PR: {e}"};
            return;
        }
        if pr is None {
            report {"ok": False, "error": "no post file found in this PR"};
            return;
        }
        # Render + persist are wrapped so an infra failure (e.g. the shared-root
        # write layer dying because the pod's redis client is missing, Aug 2026)
        # surfaces to the reviewer as a message with the real exception instead
        # of an opaque 500 — RecordView/RecordEngagement swallow the same class
        # of error, so this walker is the canary for shared-root writes.
        try {
            rendered = render_submitted_markdown(
                str(pr["content"]), str(pr["head_repo"]), str(pr["head_sha"]), gh_token
            );
            now = float(time.time());
            shared_root = root.shared;  # jac:ignore[E1030] runtime attr, no static stub
            # One persistent link per PR: reuse the existing doc (same token, so
            # the URL a reviewer already shared keeps working) and just bring its
            # snapshot + refresh coordinates current. Docs created before the
            # per-PR feature have pr_number=0 and never match a real PR.
            existing = None;
            for d in [shared_root -->][?:PreviewDoc] {
                if d.pr_number == self.pr_number {
                    existing = d;
                    break;
                }
            }
            if existing is not None {
                existing.slug = str(rendered["slug"]);
                existing.data = preview_payload(rendered);
                existing.head_repo = str(pr["head_repo"]);
                existing.head_ref = str(pr["head_ref"]);
                existing.post_path = str(pr["post_path"]);
                existing.refreshed_at = now;
                existing.created_at = now;
                token = existing.token;
            } else {
                token = uuid.uuid4().hex;
                # Previews are public (opened anonymously via /preview/<token>), so
                # they live on the shared public root, not the caller's per-user
                # root. WritePerm (not ReadPerm) is the PostStat pattern: it lets an
                # anonymous view run refresh_preview_doc in place — the written
                # content only ever comes from the PR's file, never from the caller.
                # ++> mirrors its right-hand side: a single-node connect returns the
                # node itself, not a list — the old [0] unwrap raises TypeError.
                fresh = shared_root ++> PreviewDoc(
                    token=token, slug=str(rendered["slug"]),
                    data=preview_payload(rendered), created_at=now,
                    pr_number=self.pr_number, head_repo=str(pr["head_repo"]),
                    head_ref=str(pr["head_ref"]), post_path=str(pr["post_path"]),
                    refreshed_at=now,
                );
                grant(fresh, level=WritePerm);
            }
        } except Exception as e {
            report {"ok": False, "error": f"could not create preview: {e}"};
            return;
        }
        base = self.origin.rstrip("/") if self.origin else public_site_url();
        report {"ok": True, "token": token, "slug": str(rendered["slug"]), "url": f"{base}/preview/{token}"};
    }
}


walker:pub GetPreview {
    # Resolve a preview token -> slug, so /preview/<token> can redirect to the
    # real post page (which renders the snapshot with full enhancements).
    has token: str = "";

    can get with Root entry {
        shared_root = root.shared;  # jac:ignore[E1030] runtime attr, no static stub
        doc = match_preview([shared_root -->][?:PreviewDoc], self.token);
        if doc is None {
            report {"ok": False, "error": "This preview link is invalid or has expired."};
            return;
        }
        # Refresh before resolving the slug so a mid-PR slug rename still
        # redirects to the right post URL through the same persistent link.
        refresh_preview_doc(doc);
        report {"ok": True, "slug": doc.slug};
    }
}


# ── Reading analytics ────────────────────────────────────────────────────────
# Two public collectors (RecordView / RecordEngagement) write anonymous counters
# to per-(slug, day) PostStat buckets on the shared root; one private reader
# (GetAnalytics) rolls them up for the reviewer-only dashboard. All three address
# root.shared explicitly so anonymous and signed-in readers land in the SAME
# store (a :pub walker runs on root.shared for anon callers but on the caller's
# own root for signed-in ones — addressing .shared directly keeps data unified).

walker:pub RecordView {
    # Fired once per post page mount. Bumps the total open count and records the
    # anonymous visitor id (hashed) toward the unique-opens tally.
    has slug: str = "";
    has visitor: str = "";

    can rec with Root entry {
        if not self.slug {
            report {"ok": False};
            return;
        }
        try {
            shared_root = root.shared;  # jac:ignore[E1030] runtime attr, no static stub
            day = today_utc();
            vh = hash_visitor(self.visitor);
            stat = match_day_stat([shared_root -->][?:PostStat], self.slug, day);
            if stat is None {
                made = shared_root ++> PostStat(
                    slug=self.slug, day=day, views=1,
                    visitors=([vh] if vh else []),
                );
                grant(made, level=WritePerm);
            } else {
                stat.views += 1;
                if vh and (vh not in stat.visitors) {
                    # Reassign (not in-place append) so jac-scale persists the change.
                    stat.visitors = stat.visitors + [vh];  # jac:ignore[E1055]
                }
            }
            report {"ok": True};
        } except Exception {
            report {"ok": False};
        }
    }
}


walker:pub RecordEngagement {
    # Fired when a reader leaves a post (tab close / SPA navigation). Records one
    # reading sample: active time on the page and the deepest scroll % reached.
    has slug: str = "";
    has dwell_ms: float = 0.0;
    has scroll_pct: int = 0;

    can rec with Root entry {
        if not self.slug {
            report {"ok": False};
            return;
        }
        # Defense-in-depth against the same non-read samples the client filters
        # (sub-second bounces, React Strict-Mode phantom unmounts): ignore a
        # sample with negligible dwell AND no real scroll so it can't pollute
        # the scroll-depth buckets.
        if (self.dwell_ms < 1000) and (int(self.scroll_pct) < 25) {
            report {"ok": True, "skipped": True};
            return;
        }
        try {
            shared_root = root.shared;  # jac:ignore[E1030] runtime attr, no static stub
            day = today_utc();
            stat = match_day_stat([shared_root -->][?:PostStat], self.slug, day);
            if stat is None {
                made = shared_root ++> PostStat(slug=self.slug, day=day);
                grant(made, level=WritePerm);
                stat = made;
            }
            if self.dwell_ms > 0 {
                stat.dwell_ms_sum += self.dwell_ms;
                stat.dwell_samples += 1;
            }
            pct = int(self.scroll_pct);
            stat.scroll_pct_sum += float(pct);
            stat.scroll_samples += 1;
            b = scroll_bucket(pct);
            buckets = stat.scroll_buckets;
            buckets[b] += 1;
            stat.scroll_buckets = buckets;  # reassign so the mutation persists
            report {"ok": True};
        } except Exception {
            report {"ok": False};
        }
    }
}


walker:pub RecordLinkClick {
    # Fired when a reader clicks a link inside the article body.
    has slug: str = "";
    has href: str = "";

    can rec with Root entry {
        if not self.slug or not self.href {
            report {"ok": False};
            return;
        }
        try {
            shared_root = root.shared;  # jac:ignore[E1030] runtime attr, no static stub
            day = today_utc();
            lc = match_link_click([shared_root -->][?:LinkClick], self.slug, self.href, day);
            if lc is None {
                made = shared_root ++> LinkClick(slug=self.slug, href=self.href, day=day, clicks=1);
                grant(made, level=WritePerm);
            } else {
                lc.clicks += 1;
            }
            report {"ok": True};
        } except Exception {
            report {"ok": False};
        }
    }
}


walker:priv GetAnalytics {
    # Reviewer-only rollup of every PostStat bucket. Re-verifies repo write
    # access server-side (the client gate is UX only); rolls daily buckets up
    # into per-post totals plus a per-day views series for trend charts.
    has gh_enc: str = "";

    can get with Root entry {
        gh_token = decrypt_gh(self.gh_enc);
        if not has_write_access(gh_token) {
            report {"ok": False, "error": "Not authorized."};
            return;
        }
        shared_root = root.shared;  # jac:ignore[E1030] runtime attr, no static stub
        stats = [shared_root -->][?:PostStat];
        by_slug = {};
        for n in stats {
            s = n.slug;
            if s not in by_slug {
                by_slug[s] = {
                    "slug": s, "views": 0, "visitors": [],
                    "dwell_ms_sum": 0.0, "dwell_samples": 0,
                    "scroll_pct_sum": 0.0, "scroll_samples": 0,
                    "scroll_buckets": [0, 0, 0, 0], "days": {},
                };
            }
            agg = by_slug[s];
            agg["views"] += n.views;
            for vh in n.visitors {
                if vh not in agg["visitors"] {
                    agg["visitors"].append(vh);
                }
            }
            agg["dwell_ms_sum"] += float(n.dwell_ms_sum);
            agg["dwell_samples"] += int(n.dwell_samples);
            agg["scroll_pct_sum"] += float(n.scroll_pct_sum);
            agg["scroll_samples"] += int(n.scroll_samples);
            for i in range(4) {
                agg["scroll_buckets"][i] += int(n.scroll_buckets[i]);
            }
            agg["days"][n.day] = int(agg["days"].get(n.day, 0)) + int(n.views);
        }
        # Roll link clicks up into per-(slug, href) totals.
        links_by_slug = {};
        for lc in [shared_root -->][?:LinkClick] {
            s = lc.slug;
            if s not in links_by_slug {
                links_by_slug[s] = {};
            }
            m = links_by_slug[s];
            m[lc.href] = int(m.get(lc.href, 0)) + int(lc.clicks);
        }
        out = [];
        totals = {"views": 0, "uniques": 0};
        for s in by_slug {
            agg = by_slug[s];
            uniques = len(agg["visitors"]);  # jac:ignore[E1053]
            avg_dwell_ms = (agg["dwell_ms_sum"] / agg["dwell_samples"]) if agg["dwell_samples"] else 0.0;  # jac:ignore[E1055]
            avg_scroll = (agg["scroll_pct_sum"] / agg["scroll_samples"]) if agg["scroll_samples"] else 0.0;  # jac:ignore[E1055]
            totals["views"] += int(agg["views"]);
            totals["uniques"] += int(uniques);
            post_links = [];
            link_clicks = 0;
            if s in links_by_slug {
                for href in links_by_slug[s] {  # jac:ignore[E1022]
                    c = int(links_by_slug[s][href]);
                    link_clicks += c;
                    post_links.append({"href": href, "clicks": c});
                }
                post_links.sort(key=lambda(r: dict) -> int { return int(r["clicks"]); }, reverse=True);
            }
            out.append({
                "slug": s,
                "views": agg["views"],
                "uniques": uniques,
                "avg_read_sec": round(avg_dwell_ms / 1000.0, 1),
                "samples": agg["dwell_samples"],
                "scroll_buckets": agg["scroll_buckets"],
                "avg_scroll": round(avg_scroll),  # jac:ignore[E1054]
                "median_scroll": median_scroll(agg["scroll_buckets"]),  # jac:ignore[E1053]
                "links": post_links,
                "link_clicks": link_clicks,
                "days": agg["days"],
            });
        }
        out.sort(key=lambda(r: dict) -> int { return int(r["views"]); }, reverse=True);
        report {"ok": True, "posts": out, "totals": totals};
    }
}


walker:priv ResetAnalytics {
    # Reviewer-only: wipe every reading-analytics bucket and start fresh. Useful
    # after a measurement bug, or to clear test data on a dev deployment.
    has gh_enc: str = "";

    can clear with Root entry {
        gh_token = decrypt_gh(self.gh_enc);
        if not has_write_access(gh_token) {
            report {"ok": False, "error": "Not authorized."};
            return;
        }
        shared_root = root.shared;  # jac:ignore[E1030] runtime attr, no static stub
        removed = 0;
        for n in [shared_root -->][?:PostStat] {
            del n;
            removed += 1;
        }
        for lc in [shared_root -->][?:LinkClick] {
            del lc;
            removed += 1;
        }
        report {"ok": True, "removed": removed};
    }
}


walker:pub GithubOAuthConfig {
    # Hands the browser the OAuth client id so it can build the authorize URL.
    can get with Root entry {
        client_id = env_str("GH_OAUTH_CLIENT_ID");
        report {"ok": True, "client_id": client_id, "configured": bool(client_id)};
    }
}


walker:pub GithubOAuthExchange {
    has code: str = "";
    has redirect_uri: str = "";

    can get with Root entry {
        if not self.code {
            report {"ok": False, "error": "missing code"};
            return;
        }
        profile = oauth_exchange_code(self.code, self.redirect_uri);
        if profile is None {
            report {"ok": False, "error": "github authentication failed"};
            return;
        }
        gh_token = str(profile["token"]);
        token = mint_session_token(str(profile["login"]));
        if not token {
            report {"ok": False, "error": "could not start session"};
            return;
        }
        # token: jac-scale session JWT (the browser stores it as `jac_token`, the
        # runtime sends it as a Bearer on every walker call). gh_enc: the GitHub
        # token as Fernet ciphertext — the browser holds only this, and passes it
        # back per request so the server can act on GitHub as the user.
        report {
            "ok": True,
            "token": token,
            "gh_enc": encrypt_token(gh_token),
            "profile": {
                "login": profile["login"],
                "name": profile["name"],
                "avatar": profile["avatar"],
            },
            "is_reviewer": has_write_access(gh_token),
        };
    }
}


def:priv collect_images(images: list, slug: str) -> dict {
    # Validate + turn uploaded images into tree-file entries under the slug's
    # asset dir. Returns {"ok": True, "files": [...]} or {"ok": False, "error": ...}.
    if len(images) > MAX_IMAGES {
        return {"ok": False, "error": f"too many images (max {MAX_IMAGES})"};
    }
    out = [];
    for img in images {
        name = str(img.get("name", "")).strip();
        b64 = str(img.get("b64", ""));
        if not name or not b64 {
            continue;
        }
        ext = name.rsplit(".", 1)[-1].lower() if "." in name else "";
        if ext not in ALLOWED_IMAGE_EXT {
            return {"ok": False, "error": f"unsupported image type: {name}"};
        }
        try {
            raw = base64.b64decode(b64);
        } except Exception {
            return {"ok": False, "error": f"could not decode image: {name}"};
        }
        if len(raw) > MAX_IMAGE_BYTES {
            return {"ok": False, "error": f"image {name} exceeds 100KB"};
        }
        safe_name = re.sub(r"[^A-Za-z0-9._-]", "-", name);
        out.append({"path": f"docs/assets/{slug}/{safe_name}", "content": b64, "binary": True});
    }
    return {"ok": True, "files": out};
}


def:priv parse_post_for_edit(content: str) -> dict {
    # Split a stored post .md into the form fields for editing. Body keeps its
    # leading H1; slug/categories/description come from frontmatter.
    meta: dict = {};
    raw_body = content;
    if content.startswith("---") {
        parts = content.split("---", 2);
        if len(parts) >= 3 {
            try {
                loaded = yaml.safe_load(parts[1]);
                meta = loaded if isinstance(loaded, dict) else {};
            } except Exception {
                meta = {};
            }
            raw_body = parts[2].strip();
        }
    }
    categories = meta.get("categories", []);
    if not isinstance(categories, list) {
        categories = [categories];
    }
    author_ids = meta.get("authors", []);
    if not isinstance(author_ids, list) {
        author_ids = [author_ids];
    }
    title = str(meta.get("title", ""));
    if not title {
        h1 = re.search(r"(?m)^#\s+(.+)$", raw_body);
        title = strip_markdown_inline(h1.group(1).strip()) if h1 else "";
    }
    repost_url = str(meta.get("repost_url", "")).strip();
    return {
        "title": title,
        "slug": str(meta.get("slug", "")),
        "categories": [str(c) for c in categories],
        "authors": [str(a) for a in author_ids],
        "description": str(meta.get("description", "")),
        "body_md": raw_body,
        "is_repost": bool(meta.get("repost", False)) and bool(repost_url),
        "repost_url": repost_url,
        "repost_source": str(meta.get("repost_source", "")),
    };
}


def:priv find_post_path(slug: str) -> str | None {
    # Posts identify by their frontmatter `slug:`, NOT their filename (files are
    # snake_case, slugs kebab-case), so resolve the real repo path for a slug by
    # scanning the posts dir. Falls back to a filename-stem match.
    dir_path = Path(POSTS_DIR);
    if not slug or not dir_path.exists() {
        return None;
    }
    fallback = "";
    for path in sorted(dir_path.glob("*.md")) {
        if path.name.startswith("_") {
            continue;
        }
        if path.stem == slug {
            fallback = f"{POSTS_DIR}/{path.name}";
        }
        try {
            text = path.read_text(encoding="utf-8");
        } except Exception {
            continue;
        }
        if text.startswith("---") {
            parts = text.split("---", 2);
            if len(parts) >= 3 {
                try {
                    meta = yaml.safe_load(parts[1]);
                } except Exception {
                    meta = None;
                }
                if isinstance(meta, dict) and str(meta.get("slug", "")) == slug {
                    return f"{POSTS_DIR}/{path.name}";
                }
            }
        }
    }
    return fallback if fallback else None;
}


def:priv fetch_main_post(token: str, slug: str) -> dict | None {
    # Current markdown for a published post, read from the base branch (so a
    # recent edit on main isn't missed). The path is resolved by slug — see
    # find_post_path. Falls back to the local file if the API read is empty.
    path = find_post_path(slug);
    if path is None {
        return None;
    }
    content = "";
    try {
        blob = requests.get(
            f"{GH_API}/repos/{gh_repo()}/contents/{path}",
            headers=gh_headers(token), params={"ref": gh_base_branch()}, timeout=30,
        ).json();
        content = base64.b64decode(str(blob.get("content", ""))).decode("utf-8");
    } except Exception {
        content = "";
    }
    if not content {
        try {
            content = Path(path).read_text(encoding="utf-8");
        } except Exception {
            return None;
        }
    }
    return {"content": content, "post_path": path};
}


def:priv post_path_to_slug() -> dict[str, str] {
    # Map each post's repo-relative path -> its frontmatter slug, so a PR's
    # changed-file path can be associated back to a post (filename != slug).
    out: dict[str, str] = {};
    dir_path = Path(POSTS_DIR);
    if not dir_path.exists() {
        return out;
    }
    for path in sorted(dir_path.glob("*.md")) {
        if path.name.startswith("_") {
            continue;
        }
        slug = path.stem;
        try {
            text = path.read_text(encoding="utf-8");
            if text.startswith("---") {
                parts = text.split("---", 2);
                if len(parts) >= 3 {
                    meta = yaml.safe_load(parts[1]);
                    if isinstance(meta, dict) and meta.get("slug") {
                        slug = str(meta.get("slug"));
                    }
                }
            }
        } except Exception {
            _ignore = None;
        }
        out[f"{POSTS_DIR}/{path.name}"] = slug;
    }
    return out;
}


def:priv open_edit_prs_by_slug(token: str) -> dict[str, list] {
    # ALL open PRs that EDIT an existing post, grouped by the post's slug. Found by
    # the file a PR changes (not a marker), so it picks up edit PRs opened through
    # the portal AND directly on GitHub. (Submission PRs add a NEW file, which
    # isn't in the path map, so they don't match — only edits to live posts do.)
    grouped: dict[str, list] = {};
    path_to_slug = post_path_to_slug();
    try {
        prs = requests.get(
            f"{GH_API}/repos/{gh_repo()}/pulls",
            headers=gh_headers(token),
            params={"state": "open", "per_page": 100, "sort": "created", "direction": "desc"},
            timeout=30,
        ).json();
    } except Exception {
        return grouped;
    }
    if not isinstance(prs, list) {
        return grouped;
    }
    for pr in prs {
        n = int(pr.get("number", 0));
        try {
            files = requests.get(
                f"{GH_API}/repos/{gh_repo()}/pulls/{n}/files",
                headers=gh_headers(token), params={"per_page": 100}, timeout=30,
            ).json();
        } except Exception {
            continue;
        }
        if not isinstance(files, list) {
            continue;
        }
        touched: list = [];
        for f in files {
            fn = str(f.get("filename", ""));
            if fn in path_to_slug {
                s = str(path_to_slug[fn]);
                if s not in touched {
                    touched.append(s);
                }
            }
        }
        if not touched {
            continue;
        }
        user = pr.get("user");
        author = str(user.get("login", "")) if isinstance(user, dict) else "";
        entry = {
            "number": n,
            "url": str(pr.get("html_url", "")),
            "title": str(pr.get("title", "")),
            "author": author,
        };
        for s in touched {
            if s in grouped {
                grouped[s].append(entry);
            } else {
                grouped[s] = [entry];
            }
        }
    }
    return grouped;
}


def:priv find_open_edit_prs(token: str, slug: str) -> list {
    # Open edit PRs for one post — the collision check on the edit form.
    return open_edit_prs_by_slug(token).get(slug, []);
}


def:priv open_submission_prs(token: str) -> list {
    # ALL open PRs that ADD a NEW post (a docs/blog/posts/*.md that isn't already
    # a live post), found by the file the PR adds rather than a body marker — so
    # it picks up submissions opened through the portal AND directly on GitHub.
    # Edits to an existing post add no new file, so they don't match here; they
    # are surfaced separately by open_edit_prs_by_slug. Mirrors that function's
    # file-based detection so the review queue and the open-edits list stay
    # consistent about direct-GitHub PRs.
    out: list = [];
    path_to_slug = post_path_to_slug();
    try {
        prs = requests.get(
            f"{GH_API}/repos/{gh_repo()}/pulls",
            headers=gh_headers(token),
            params={"state": "open", "per_page": 100, "sort": "created", "direction": "desc"},
            timeout=30,
        ).json();
    } except Exception {
        return out;
    }
    if not isinstance(prs, list) {
        return out;
    }
    for pr in prs {
        n = int(pr.get("number", 0));
        try {
            files = requests.get(
                f"{GH_API}/repos/{gh_repo()}/pulls/{n}/files",
                headers=gh_headers(token), params={"per_page": 100}, timeout=30,
            ).json();
        } except Exception {
            continue;
        }
        if not isinstance(files, list) {
            continue;
        }
        adds_new_post = False;
        for f in files {
            fn = str(f.get("filename", ""));
            status = str(f.get("status", ""));
            name = fn.split("/")[-1];
            if (
                fn.startswith(f"{POSTS_DIR}/")
                and fn.endswith(".md")
                and not name.startswith("_")
                and fn not in path_to_slug
                and status == "added"
            ) {
                adds_new_post = True;
                break;
            }
        }
        if not adds_new_post {
            continue;
        }
        user = pr.get("user");
        author = str(user.get("login", "")) if isinstance(user, dict) else "";
        out.append({
            "title": str(pr.get("title", "")),
            "slug": "",
            "author": author,
            "pr_number": n,
            "pr_url": str(pr.get("html_url", "")),
            "created_at": str(pr.get("created_at", "")),
        });
    }
    return out;
}


def:priv build_edited_markdown(
    original_content: str, title: str, categories: list, description: str, body: str,
    is_repost: bool = False, repost_url: str = "", repost_source: str = "",
    author_override: str = ""
) -> str {
    # Rebuild a post's .md PRESERVING its frontmatter — date, authors, slug, and
    # crucially the draft state (a live post has no draft key, so the edit stays
    # live and deploys on merge) — while applying the edited categories,
    # description, and body. Contrast build_post_markdown, which is for NEW drafts
    # (date=today, draft:true).
    meta: dict = {};
    if original_content.startswith("---") {
        parts = original_content.split("---", 2);
        if len(parts) >= 3 {
            try {
                loaded = yaml.safe_load(parts[1]);
                meta = loaded if isinstance(loaded, dict) else {};
            } except Exception {
                meta = {};
            }
        }
    }
    meta["categories"] = [str(c) for c in categories];
    if description {
        meta["description"] = description;
    } else {
        meta.pop("description", None);
    }
    # Reviewer re-attribution: swap the byline to the shared team author.
    if author_override {
        meta["authors"] = [author_override];
    }
    # Toggle repost keys to match the form: set them when checked + a URL is
    # given, otherwise strip any that were there (the post is no longer a repost).
    if is_repost and repost_url.strip() {
        meta["repost"] = True;
        meta["repost_url"] = repost_url.strip();
        if repost_source.strip() {
            meta["repost_source"] = repost_source.strip();
        } else {
            meta.pop("repost_source", None);
        }
    } else {
        meta.pop("repost", None);
        meta.pop("repost_url", None);
        meta.pop("repost_source", None);
    }
    fm = str(yaml.safe_dump(meta, sort_keys=False, allow_unicode=True)).strip();
    body_text: str = body.strip();
    if not body_text.startswith("#") {
        body_text = f"# {title}\n\n{body_text}";
    }
    return f"---\n{fm}\n---\n\n{body_text}\n";
}


walker:priv SubmitPost {
    has gh_enc: str = "";
    has title: str = "";
    has slug: str = "";
    has categories: list = [];
    has description: str = "";
    has body_md: str = "";
    has body_b64: bool = False;  # body_md is base64 (client encodes it past the WAF)
    has author_bio: str = "";
    has images: list = [];
    has is_repost: bool = False;
    has repost_url: str = "";
    has repost_source: str = "";
    has as_team: bool = False;  # reviewers only: publish under the shared byline

    can submit with Root entry {
        gh_token = decrypt_gh(self.gh_enc);
        if not gh_token {
            report {"ok": False, "error": "session expired — please sign in again"};
            return;
        }
        profile = gh_user(gh_token);
        if not profile.get("login") {
            report {"ok": False, "error": "session expired — please sign in again"};
            return;
        }
        title = self.title.strip();
        slug = self.slug.strip().lower();
        body = decode_body_md(self.body_md, self.body_b64);

        if not title {
            report {"ok": False, "error": "title is required"};
            return;
        }
        if not is_valid_slug(slug) {
            report {"ok": False, "error": "slug must be kebab-case (lowercase letters, digits, hyphens)"};
            return;
        }
        if slug_taken(slug) {
            report {"ok": False, "error": f"slug '{slug}' is already taken"};
            return;
        }
        if len(body.strip()) < 50 {
            report {"ok": False, "error": "post body is too short"};
            return;
        }
        cats = [str(c) for c in self.categories if str(c) in ALLOWED_CATEGORIES];
        if not cats {
            report {"ok": False, "error": "select at least one valid category"};
            return;
        }
        repost_url = self.repost_url.strip();
        if self.is_repost and not repost_url {
            report {"ok": False, "error": "a repost needs the original article URL"};
            return;
        }
        if self.is_repost and not is_http_url(repost_url) {
            report {"ok": False, "error": "the repost URL must be an http(s) link"};
            return;
        }
        img_res = collect_images(self.images, slug);
        if not img_res["ok"] {
            report {"ok": False, "error": img_res["error"]};
            return;
        }
        image_files = img_res["files"];

        (author_id, new_entry) = resolve_author_id(profile, self.author_bio.strip());
        # Shared "Jaseci Team" byline — reviewers only. The shared entry already
        # lives in .authors.yml, so no new author entry is created.
        if self.as_team and has_write_access(gh_token) {
            author_id = TEAM_AUTHOR_ID;
            new_entry = None;
        }
        post_md = build_post_markdown(
            title, slug, cats, self.description.strip(), author_id, body,
            self.is_repost, repost_url, self.repost_source.strip(),
        );
        files = [{"path": f"docs/blog/posts/{slug}.md", "content": post_md, "binary": False}];
        files = files + image_files;  # jac:ignore[E1001]
        if new_entry is not None {
            updated = authors_yml_with(new_entry);
            if updated is not None {
                files.append({"path": "docs/blog/.authors.yml", "content": updated, "binary": False});
            }
        }

        branch = f"submit/{slug}-{int(time.time())}";
        marker = f"\n\n<!-- blog-submission slug={slug} by={profile['login']} -->";
        pr_body = (
            "Blog submission via the /submit form.\n\n"
            + f"**Title:** {title}\n"
            + f"**Author:** @{profile['login']} (`{author_id}`)\n"
            + f"**Categories:** {', '.join(cats)}\n\n"
            + "Opened from the author's fork via the /submit form. "
            + "`draft: true` is set; a reviewer will schedule publication."
            + marker
        );

        try {
            pr = submit_via_fork(gh_token, str(profile["login"]), branch, files, f"Add blog post: {title}", title, pr_body);
        } except Exception as e {
            report {"ok": False, "error": f"could not open PR: {e}"};
            return;
        }
        if not pr.get("number") {
            report {"ok": False, "error": "PR creation failed", "detail": pr};
            return;
        }
        report {"ok": True, "pr_number": pr["number"], "pr_url": pr.get("html_url", ""), "slug": slug};
    }
}


walker:priv GetSubmissionForEdit {
    has gh_enc: str = "";
    has pr_number: int = 0;

    can get with Root entry {
        gh_token = decrypt_gh(self.gh_enc);
        if not gh_token {
            report {"ok": False, "error": "not signed in"};
            return;
        }
        try {
            pr = fetch_pr_post(gh_token, self.pr_number);
        } except Exception as e {
            report {"ok": False, "error": f"could not load submission: {e}"};
            return;
        }
        if pr is None {
            report {"ok": False, "error": "no post file found in this PR"};
            return;
        }
        # Authors edit their own submission; reviewers (repo write) may also open
        # anyone's, to copy-edit it. How that edit gets DELIVERED depends on the
        # PR — see deliver_edit — so tell the client up front which route it'll take.
        is_own = str(pr["head_owner"]).lower() == str(gh_user(gh_token).get("login", "")).lower();
        if not is_own and not has_write_access(gh_token) {
            report {"ok": False, "error": "you can only edit your own submissions"};
            return;
        }
        if pr["state"] != "open" or pr["merged"] {
            report {"ok": False, "error": "this submission can no longer be edited (already merged or closed)"};
            return;
        }
        fields = parse_post_for_edit(str(pr["content"]));
        report {
            "ok": True,
            "pr_number": self.pr_number,
            "branch": str(pr["head_ref"]),
            "is_own": is_own,
            "author": str(pr["head_owner"]),
            # Best case only — the commit can still be refused at push time, which
            # is why deliver_edit falls back instead of trusting this.
            "can_commit": is_own or bool(pr["maintainer_can_modify"]),
            "can_suggest": str(pr["post_status"]) == "added",
            **fields,
        };
    }
}


walker:priv UpdatePost {
    has gh_enc: str = "";
    has pr_number: int = 0;
    has title: str = "";
    has slug: str = "";
    has categories: list = [];
    has description: str = "";
    has body_md: str = "";
    has body_b64: bool = False;  # body_md is base64 (client encodes it past the WAF)
    has images: list = [];
    has is_repost: bool = False;
    has repost_url: str = "";
    has repost_source: str = "";
    has as_team: bool = False;  # reviewers only: publish under the shared byline

    can update with Root entry {
        gh_token = decrypt_gh(self.gh_enc);
        if not gh_token {
            report {"ok": False, "error": "not signed in"};
            return;
        }
        profile = gh_user(gh_token);
        if not profile.get("login") {
            report {"ok": False, "error": "not signed in"};
            return;
        }
        try {
            pr = fetch_pr_post(gh_token, self.pr_number);
        } except Exception as e {
            report {"ok": False, "error": f"could not load submission: {e}"};
            return;
        }
        if pr is None {
            report {"ok": False, "error": "no post file found in this PR"};
            return;
        }
        login = str(profile["login"]);
        is_own = str(pr["head_owner"]).lower() == login.lower();
        is_reviewer = has_write_access(gh_token);
        if not is_own and not is_reviewer {
            report {"ok": False, "error": "you can only edit your own submissions"};
            return;
        }
        if pr["state"] != "open" or pr["merged"] {
            report {"ok": False, "error": "this submission can no longer be edited"};
            return;
        }

        title = self.title.strip();
        slug = self.slug.strip().lower();  # slug is fixed for an edit
        body = decode_body_md(self.body_md, self.body_b64);
        if not title {
            report {"ok": False, "error": "title is required"};
            return;
        }
        if len(body.strip()) < 50 {
            report {"ok": False, "error": "post body is too short"};
            return;
        }
        cats = [str(c) for c in self.categories if str(c) in ALLOWED_CATEGORIES];
        if not cats {
            report {"ok": False, "error": "select at least one valid category"};
            return;
        }
        repost_url = self.repost_url.strip();
        if self.is_repost and not is_http_url(repost_url) {
            report {"ok": False, "error": "a repost needs a valid http(s) article URL"};
            return;
        }
        img_res = collect_images(self.images, slug);
        if not img_res["ok"] {
            report {"ok": False, "error": img_res["error"]};
            return;
        }

        post_md: str = "";
        if is_own {
            # Resolve the author's id (reuses their existing .authors.yml entry);
            # don't re-touch .authors.yml on edit — the entry already exists.
            (author_id, _new) = resolve_author_id(profile, "");
            if self.as_team and is_reviewer {
                author_id = TEAM_AUTHOR_ID;
            }
            post_md = build_post_markdown(
                title, slug, cats, self.description.strip(), author_id, body,
                self.is_repost, repost_url, self.repost_source.strip(),
            );
        } else {
            # A reviewer copy-editing someone ELSE's submission must not become its
            # author: rebuild from the PR's own frontmatter so the contributor's
            # byline, date and `draft: true` survive untouched.
            post_md = build_edited_markdown(
                str(pr["content"]), title, cats, self.description.strip(), body,
                self.is_repost, repost_url, self.repost_source.strip(),
                TEAM_AUTHOR_ID if self.as_team else "",
            );
        }
        # Write back to the PR's ACTUAL file — a PR opened directly on GitHub can
        # use a filename that isn't the slug, and writing to `<slug>.md` would add
        # a second post rather than edit the one under review.
        files = [{"path": str(pr["post_path"]), "content": post_md, "binary": False}];
        files = files + img_res["files"];  # jac:ignore[E1001]

        if is_own {
            try {
                commit_update(gh_token, str(pr["head_repo"]), str(pr["head_ref"]), files, f"Update blog post: {title}");
            } except Exception as e {
                report {"ok": False, "error": f"could not save changes: {e}"};
                return;
            }
            report {"ok": True, "mode": "commit", "pr_number": self.pr_number, "pr_url": str(pr["pr_url"]), "url": str(pr["pr_url"]), "slug": slug};
            return;
        }

        try {
            outcome = deliver_edit(
                gh_token, pr, files, f"Editorial revision: {title}", post_md, login,
            );
        } except Exception as e {
            report {"ok": False, "error": f"could not deliver the edit: {e}"};
            return;
        }
        report {
            "ok": True,
            "mode": str(outcome["mode"]),
            "pr_number": self.pr_number,
            "pr_url": str(pr["pr_url"]),
            "url": str(outcome["url"]),
            "slug": slug,
            "fallback_reason": str(outcome["note"]),
        };
    }
}


walker:priv ListEditablePosts {
    # Published posts the caller may edit: reviewers (repo write) get every live
    # post; everyone else gets only posts they're a registered author of.
    has gh_enc: str = "";

    can get with Root entry {
        gh_token = decrypt_gh(self.gh_enc);
        if not gh_token {
            report {"ok": False, "error": "not signed in"};
            return;
        }
        is_reviewer = has_write_access(gh_token);
        my_author_id = "";
        if not is_reviewer {
            (my_author_id, _e) = resolve_author_id(gh_user(gh_token), "");
        }
        # All live posts come from the files on main (list_all_posts reads disk),
        # so this covers posts published through the app AND by direct push.
        # Open edit PRs are fetched once and attached per slug.
        prs_by_slug = open_edit_prs_by_slug(gh_token);
        out: list = [];
        for p in list_all_posts() {
            author_ids = [str(a["id"]) for a in p["authors"]];
            if is_reviewer or (my_author_id and my_author_id in author_ids) {
                slug = str(p["slug"]);
                out.append({
                    "slug": slug,
                    "title": str(p["title"]),
                    "date": str(p["date"]),
                    "authors": author_ids,
                    "edit_prs": prs_by_slug.get(slug, []),
                });
            }
        }
        report {"ok": True, "posts": out, "is_reviewer": is_reviewer};
    }
}


walker:priv GetPublishedPostForEdit {
    # Load a published post's current source into the edit form, and surface any
    # open edit PRs for it (collision check).
    has gh_enc: str = "";
    has slug: str = "";

    can get with Root entry {
        gh_token = decrypt_gh(self.gh_enc);
        if not gh_token {
            report {"ok": False, "error": "not signed in"};
            return;
        }
        if not self.slug {
            report {"ok": False, "error": "missing slug"};
            return;
        }
        main_post = fetch_main_post(gh_token, self.slug);
        if main_post is None {
            report {"ok": False, "error": "no published post with that slug"};
            return;
        }
        fields = parse_post_for_edit(str(main_post["content"]));
        if not has_write_access(gh_token) {
            (my_author_id, _e) = resolve_author_id(gh_user(gh_token), "");
            if not my_author_id or my_author_id not in fields["authors"] {
                report {"ok": False, "error": "you can only edit posts you authored"};
                return;
            }
        }
        report {"ok": True, "existing_prs": find_open_edit_prs(gh_token, self.slug), **fields};
    }
}


walker:priv EditPublishedPost {
    # Open a NEW PR editing a published post (or add a commit to the caller's own
    # open edit PR). The post stays live; frontmatter is preserved so merging just
    # ships the edit.
    has gh_enc: str = "";
    has slug: str = "";
    has title: str = "";
    has categories: list = [];
    has description: str = "";
    has body_md: str = "";
    has body_b64: bool = False;  # body_md is base64 (client encodes it past the WAF)
    has images: list = [];
    has pr_number: int = 0;  # >0 = continue the caller's own open edit PR
    has is_repost: bool = False;
    has repost_url: str = "";
    has repost_source: str = "";
    has as_team: bool = False;  # reviewers only: re-attribute to the shared byline

    can edit with Root entry {
        gh_token = decrypt_gh(self.gh_enc);
        if not gh_token {
            report {"ok": False, "error": "not signed in"};
            return;
        }
        profile = gh_user(gh_token);
        login = str(profile.get("login", ""));
        if not login {
            report {"ok": False, "error": "not signed in"};
            return;
        }
        slug = self.slug.strip().lower();
        body_md = decode_body_md(self.body_md, self.body_b64);
        main_post = fetch_main_post(gh_token, slug);
        if main_post is None {
            report {"ok": False, "error": "no published post with that slug"};
            return;
        }
        original = str(main_post["content"]);
        if not has_write_access(gh_token) {
            base_fields = parse_post_for_edit(original);
            (my_author_id, _e) = resolve_author_id(profile, "");
            if not my_author_id or my_author_id not in base_fields["authors"] {
                report {"ok": False, "error": "you can only edit posts you authored"};
                return;
            }
        }
        title = self.title.strip();
        if not title {
            report {"ok": False, "error": "title is required"};
            return;
        }
        cats = [str(c) for c in self.categories if str(c) in ALLOWED_CATEGORIES];
        if not cats {
            report {"ok": False, "error": "select at least one valid category"};
            return;
        }
        if len(body_md.strip()) < 50 {
            report {"ok": False, "error": "post body is too short"};
            return;
        }
        repost_url = self.repost_url.strip();
        if self.is_repost and not is_http_url(repost_url) {
            report {"ok": False, "error": "a repost needs a valid http(s) article URL"};
            return;
        }
        img_res = collect_images(self.images, slug);
        if not img_res["ok"] {
            report {"ok": False, "error": img_res["error"]};
            return;
        }
        author_override = "";
        if self.as_team and has_write_access(gh_token) {
            author_override = TEAM_AUTHOR_ID;
        }
        post_md = build_edited_markdown(
            original, title, cats, self.description.strip(), body_md,
            self.is_repost, repost_url, self.repost_source.strip(), author_override,
        );
        # Write back to the post's ACTUAL file (filename != slug), so the PR edits
        # the existing post instead of creating a new file.
        files = [{"path": str(main_post["post_path"]), "content": post_md, "binary": False}];
        files = files + img_res["files"];  # jac:ignore[E1001]

        if self.pr_number {
            # Continue the caller's OWN open edit PR (we can only push to own fork).
            pr = fetch_pr_post(gh_token, self.pr_number);
            if pr is None {
                report {"ok": False, "error": "could not load that PR"};
                return;
            }
            if str(pr["head_owner"]).lower() != login.lower() {
                report {"ok": False, "error": "you can only add to your own edit PR"};
                return;
            }
            if pr["state"] != "open" or pr["merged"] {
                report {"ok": False, "error": "that PR is already merged or closed"};
                return;
            }
            try {
                commit_update(gh_token, str(pr["head_repo"]), str(pr["head_ref"]), files, f"Edit blog post: {title}");
            } except Exception as e {
                report {"ok": False, "error": f"could not save changes: {e}"};
                return;
            }
            report {"ok": True, "pr_number": self.pr_number, "pr_url": str(pr["pr_url"]), "slug": slug};
            return;
        }

        branch = f"edit/{slug}-{int(time.time())}";
        marker = f"\n\n<!-- {EDIT_TAG} slug={slug} by={login} -->";
        pr_body = (
            "Edit to a published post via the /submit ▸ Edit a post form.\n\n"
            + f"**Post:** {title} (`{slug}`)\n"
            + f"**Editor:** @{login}\n\n"
            + "The post stays live; merging publishes the edit. Frontmatter (date, "
            + "authors, published status) is preserved."
            + marker
        );
        try {
            pr = submit_via_fork(gh_token, login, branch, files, f"Edit blog post: {title}", title, pr_body);
        } except Exception as e {
            report {"ok": False, "error": f"could not open edit PR: {e}"};
            return;
        }
        report {"ok": True, "pr_number": int(pr["number"]), "pr_url": str(pr["html_url"]), "slug": slug};
    }
}


walker:priv MySubmissions {
    has gh_enc: str = "";

    can get with Root entry {
        gh_token = decrypt_gh(self.gh_enc);
        if not gh_token {
            report {"ok": False, "error": "not signed in"};
            return;
        }
        login = str(gh_user(gh_token).get("login", ""));
        if not login {
            report {"ok": False, "error": "not signed in"};
            return;
        }
        try {
            q = f'repo:{gh_repo()} type:pr "{SUBMISSION_TAG}" in:body';
            r = requests.get(
                f"{GH_API}/search/issues",
                headers=gh_headers(gh_token),
                params={"q": q, "per_page": 50, "sort": "created", "order": "desc"},
                timeout=30,
            );
            data = r.json();
        } except Exception as e {
            report {"ok": False, "error": f"could not load submissions: {e}"};
            return;
        }
        items = data.get("items", []) if isinstance(data, dict) else [];
        live_slugs = {p["slug"] for p in list_all_posts()};
        scheduled = load_scheduled_slugs();
        out = [];
        for it in items {
            body = str(it.get("body", "") or "");
            bym = re.search(r"by=([A-Za-z0-9-]+)", body);
            if (bym.group(1) if bym else "") != login {
                continue;  # only this author's submissions
            }
            m = re.search(r"slug=([a-z0-9-]+)", body);
            slug = m.group(1) if m else "";
            state = str(it.get("state", "open"));
            pr_info = it.get("pull_request", {}) or {};
            merged = bool(pr_info.get("merged_at"));
            status: str = "in_review";
            published_url: str = "";
            schedule_at: str = "";
            if state == "open" {
                status = "in_review";
            } elif merged {
                if slug and slug in live_slugs {
                    status = "published";
                    published_url = f"{public_site_url()}/blog/posts/{slug}";
                } elif slug and slug in scheduled {
                    status = "scheduled";
                    schedule_at = scheduled[slug];
                } else {
                    status = "accepted";
                }
            } else {
                status = "declined";
            }
            out.append({
                "title": str(it.get("title", "")),
                "slug": slug,
                "pr_number": it.get("number"),
                "pr_url": str(it.get("html_url", "")),
                "status": status,
                "published_url": published_url,
                "schedule_at": schedule_at,
                "created_at": str(it.get("created_at", "")),
            });
        }
        # The author's own open edits to ALREADY-PUBLISHED posts (file-based, so
        # it also catches edit PRs opened directly on GitHub).
        my_edits: list = [];
        for (eslug, eprs) in open_edit_prs_by_slug(gh_token).items() {
            for epr in eprs {
                if str(epr["author"]).lower() == login.lower() {
                    my_edits.append({
                        "slug": eslug,
                        "number": epr["number"],
                        "url": epr["url"],
                        "title": epr["title"],
                    });
                }
            }
        }
        report {"ok": True, "submissions": out, "edits": my_edits};
    }
}


walker:priv ListSubmissions {
    has gh_enc: str = "";

    can get with Root entry {
        gh_token = decrypt_gh(self.gh_enc);
        if not has_write_access(gh_token) {
            report {"ok": False, "error": "reviewer access required"};
            return;
        }
        report {"ok": True, "submissions": open_submission_prs(gh_token)};
    }
}


walker:priv PreviewSubmission {
    has gh_enc: str = "";
    has pr_number: int = 0;

    can get with Root entry {
        gh_token = decrypt_gh(self.gh_enc);
        if not has_write_access(gh_token) {
            report {"ok": False, "error": "reviewer access required"};
            return;
        }
        if not self.pr_number {
            report {"ok": False, "error": "missing pr_number"};
            return;
        }
        try {
            h = gh_headers(gh_token);
            repo = gh_repo();
            pr = requests.get(f"{GH_API}/repos/{repo}/pulls/{self.pr_number}", headers=h, timeout=30).json();
            head_sha = str(pr["head"]["sha"]);
            head_repo = str(pr["head"]["repo"]["full_name"]);
            files = requests.get(
                f"{GH_API}/repos/{repo}/pulls/{self.pr_number}/files",
                headers=h, params={"per_page": 100}, timeout=30,
            ).json();
            post_path = "";
            for f in files {
                fn = str(f.get("filename", ""));
                if fn.startswith("docs/blog/posts/") and fn.endswith(".md") {
                    post_path = fn;
                    break;
                }
            }
            if not post_path {
                report {"ok": False, "error": "no post file found in this PR"};
                return;
            }
            blob = requests.get(
                f"{GH_API}/repos/{head_repo}/contents/{post_path}",
                headers=h, params={"ref": head_sha}, timeout=30,
            ).json();
            content = base64.b64decode(str(blob.get("content", ""))).decode("utf-8");
        } except Exception as e {
            report {"ok": False, "error": f"could not load PR content: {e}"};
            return;
        }
        rendered = render_submitted_markdown(content, head_repo, head_sha, gh_token);
        slug = str(rendered["slug"]);

        # Find the scheduling tracker issue (opened by post-ci-automation) for
        # this slug, so the dashboard can link straight to it.
        issue_url = "";
        try {
            iq = f'repo:{gh_repo()} type:issue label:blog-schedule "{slug}"';
            ir = requests.get(
                f"{GH_API}/search/issues", headers=h,
                params={"q": iq, "per_page": 5}, timeout=30,
            ).json();
            its = ir.get("items", []) if isinstance(ir, dict) else [];
            if its and len(its) > 0 {
                issue_url = str(its[0].get("html_url", ""));
            }
        } except Exception {
            _ignore = None;
        }

        report {
            "ok": True,
            "pr_number": self.pr_number,
            "pr_url": str(pr.get("html_url", "")),
            "issue_url": issue_url,
            "live_url": f"{public_site_url()}/blog/posts/{slug}" if slug else "",
            "mergeable": pr.get("mergeable"),
            "mergeable_state": str(pr.get("mergeable_state", "")),
            **rendered,
        };
    }
}


# --- Link reference cards ----------------------------------------------------
# The post body links out to GitHub repos, YouTube videos and external sites.
# FetchLinkMeta enriches a batch of URLs the client found in the rendered post
# so the right-margin reference rail can show a card per link. Metadata is
# cached in-process keyed by URL (the content set is small and slow-changing).

glob LINK_META_CACHE = {};
glob LINK_UA = "Mozilla/5.0 (compatible; JaseciBlogsBot/1.0; +https://blogs.jaseci.org)";


def:priv _http_get(url: str, accept: str = "") -> str {
    headers = {"User-Agent": LINK_UA};
    if accept {
        headers["Accept"] = accept;
    }
    req = Request(url, headers=headers);
    resp = urlopen(req, timeout=6.0);
    # Cap the read so a pathological page can't blow up memory.
    return str(resp.read()[:400000].decode("utf-8", "ignore"));
}


def:priv _meta_pat(html: str, prop: str) -> str {
    # Pull a <meta> content value for `prop`, tolerating either attribute order.
    # Inline (?i) keeps re.search to two args (the flags overload won't resolve
    # against the urllib-tainted Any types this module passes around).
    esc = str(re.escape(prop));
    p1 = '(?i)<meta[^>]+(?:property|name)=["\']' + esc + '["\'][^>]*content=["\']([^"\']*)["\']';
    m = re.search(p1, html);
    if m {
        return str(m.group(1) or "").strip();
    }
    p2 = '(?i)<meta[^>]+content=["\']([^"\']*)["\'][^>]+(?:property|name)=["\']' + esc + '["\']';
    m2 = re.search(p2, html);
    if m2 {
        return str(m2.group(1) or "").strip();
    }
    return "";
}


def:priv _gh_repo_meta(segs: list) -> dict {
    owner = str(segs[0]);
    repo = str(segs[1]);
    data = json.loads(_http_get(
        "https://api.github.com/repos/" + owner + "/" + repo,
        "application/vnd.github+json"
    )) as dict;
    owner_obj = (data.get("owner") or {}) as dict;
    return {
        "type": "github",
        "title": str(data.get("full_name") or (owner + "/" + repo)),
        "description": str(data.get("description") or ""),
        "stars": int(data.get("stargazers_count") or 0),
        "image": str(owner_obj.get("avatar_url") or ""),
    };
}


def:priv _yt_id(host: str, segs: list, query: str) -> str {
    if host == "youtu.be" and segs {
        return str(segs[0]);
    }
    if segs and (segs[0] in ["embed", "shorts", "v"]) and len(segs) >= 2 {
        return str(segs[1]);
    }
    q = parse_qs(query) as dict;
    if ("v" in q) and q["v"] {
        return str(q["v"][0]);
    }
    return "";
}


def:priv _yt_meta(vid: str) -> dict {
    title = "";
    try {
        data = json.loads(_http_get(
            "https://www.youtube.com/oembed?format=json&url=https://www.youtube.com/watch?v=" + vid
        )) as dict;
        title = str(data.get("title") or "");
    } except Exception {
        title = "";
    }
    return {
        "type": "youtube",
        "video_id": vid,
        "title": title,
        "description": "",
        "image": "https://i.ytimg.com/vi/" + vid + "/hqdefault.jpg",
    };
}


def:priv _og_meta(url: str) -> dict {
    html = _http_get(url, "text/html");
    title = _meta_pat(html, "og:title");
    if not title {
        tm = re.search("(?i)<title[^>]*>([^<]*)</title>", html);
        if tm {
            title = str(tm.group(1) or "").strip();
        }
    }
    desc = _meta_pat(html, "og:description");
    if not desc {
        desc = _meta_pat(html, "description");
    }
    return {
        "type": "link",
        "title": title,
        "description": desc,
        "image": _meta_pat(html, "og:image"),
    };
}


def:priv link_meta(url: str) -> dict {
    if url in LINK_META_CACHE {
        return LINK_META_CACHE[url] as dict;
    }
    result: dict = {"type": "link", "title": "", "description": "", "image": "", "url": url, "host": ""};
    try {
        parsed = urlparse(url);
        host = str(parsed.netloc or "").lower();
        if host.startswith("www.") {
            host = host[4:];
        }
        segs = [s for s in str(parsed.path or "").split("/") if s];
        if (host == "github.com") and (len(segs) >= 2) {
            result = {**result, **_gh_repo_meta(segs)};
        } elif host in ["youtube.com", "m.youtube.com", "youtu.be"] {
            vid = _yt_id(host, segs, str(parsed.query or ""));
            if vid {
                result = {**result, **_yt_meta(vid)};
            }
        } else {
            result = {**result, **_og_meta(url)};
        }
        result["url"] = url;
        result["host"] = host;
    } except Exception as e {
        result["error"] = str(e);
    }
    LINK_META_CACHE[url] = result;
    return result;
}


walker:pub FetchLinkMeta {
    # urls: the external hrefs the client extracted from the rendered post.
    has urls: list = [];

    can get with Root entry {
        out = [];
        for u in self.urls {
            out.append(link_meta(str(u)));
        }
        report {"ok": True, "meta": out};
    }
}