Close Markdown migration follow-ups

Author: adewale

.github/workflows/verify.yml

@@ -0,0 +1,39 @@
+name: Verify
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - name: Install dependencies
+        run: uv sync --all-groups
+      - name: Start local Worker for browser checks
+        run: |
+          uv run --group workers pywrangler dev --port 9696 > /tmp/pythonbyexample-ci.log 2>&1 &
+          for i in $(seq 1 180); do
+            if grep -q 'Ready on http://localhost:9696' /tmp/pythonbyexample-ci.log; then
+              exit 0
+            fi
+            if grep -E 'failed to start|FileNotFoundError|Traceback|Address already' /tmp/pythonbyexample-ci.log; then
+              cat /tmp/pythonbyexample-ci.log
+              exit 1
+            fi
+            sleep 1
+          done
+          cat /tmp/pythonbyexample-ci.log
+          exit 1
+      - name: Verify
+        run: |
+          make verify
+          scripts/check_example_migration_parity.py
+          scripts/format_examples.py --check
+          make verify-python-version VERSION=3.13
+          git diff --check

README.md

@@ -2,7 +2,7 @@
 
 Python By Example is a Go By Example-inspired learning site for Python 3.13. It presents small literate examples with prose, source fragments, expected output, official Python documentation links, and an editable runner.
 
-Production: <https://pythonbyexample.adewale-883.workers.dev>
+Production: <https://www.pythonbyexample.dev> (`workers.dev` remains enabled as a fallback).
 
 ## Features
 
@@ -40,7 +40,10 @@ Python documentation links point to the official [Python documentation](https://
 - `src/main.py` is the Cloudflare Worker entrypoint.
 - FastAPI handles request routing through the Cloudflare ASGI bridge.
 - `src/app.py` renders pages from simple placeholder templates in `src/templates/`.
-- `src/examples.py` contains the example catalog and expected outputs.
+- `src/example_sources/*.md` contains the human-editable examples.
+- `src/example_loader.py` parses Markdown examples into the runtime catalog.
+- `src/examples.py` is a compatibility shim for the loaded catalog.
+- `src/example_sources_data.py` is generated embedded source data for Cloudflare Workers.
 - `public/` contains static assets served by Workers Assets.
 - `python_modules/` is generated by the Workers tooling and intentionally ignored by Git.
 
@@ -77,10 +80,10 @@ http://localhost:9696
 Run the main checks before deploying or pushing:
 
 ```bash
-make test
-make seo-cache-lint
-make browser-layout-test
-uv run ruff check src tests scripts
+make verify
+scripts/check_example_migration_parity.py
+scripts/format_examples.py --check
+make verify-python-version VERSION=3.13
 ```
 
 `make seo-cache-lint` verifies that:
@@ -105,10 +108,10 @@ public/syntax-highlight.js
 public/editor.js
 ```
 
-Before tests/deploy, regenerate fingerprinted asset copies and the Python manifest:
+Before tests/deploy, regenerate embedded example data, fingerprinted asset copies, and Python manifests:
 
 ```bash
-scripts/fingerprint_assets.py
+make build
 ```
 
 This writes files such as:
@@ -150,15 +153,33 @@ make deploy
 
 ## Updating examples or Python version
 
-Edit `src/examples.py`:
+Edit Markdown files under `src/example_sources/`.
+
+Each example has:
+
+- TOML frontmatter with `slug`, `title`, `section`, `summary`, and `doc_path`
+- exactly one `:::program` block for the full editable source
+- one or more `:::cell` blocks for verified prose/source/output teaching cells
+- optional `:::note` blocks
+
+After editing examples, run:
 
-- update `PYTHON_VERSION` for the docs/runtime target
-- add, remove, or revise entries in `EXAMPLES`
-- keep examples self-contained
-- keep `expected_output` deterministic
-- link `doc_url` to `https://docs.python.org/3.13/` or the active supported version
+```bash
+make build
+make verify-examples
+scripts/format_examples.py --check
+scripts/check_example_migration_parity.py
+```
+
+`src/example_sources_data.py` is generated and committed so Cloudflare Workers can load examples in production. Do not edit it by hand.
+
+For a Python version migration, update `python_version` and `docs_base_url` in `src/example_sources/manifest.toml`, then run:
+
+```bash
+make verify-python-version VERSION=3.13
+```
 
-Then update tests first, run them red, implement, refactor, and regenerate fingerprints.
+Use the active Cloudflare-supported Python version.
 
 ## Cloudflare notes
 

docs/example-source-format-spec.md

@@ -455,13 +455,14 @@ Build requirements:
 
 ## Formatter
 
-`format_examples.py` should make Markdown examples stable without rewriting author voice.
+`format_examples.py` makes Markdown examples stable without rewriting author voice.
 
 Required behavior:
 
 - Preserve prose text, except for trimming trailing whitespace and normalizing blank lines.
+- Parse TOML frontmatter and reserialize it deterministically.
 - Sort frontmatter keys in this order: `slug`, `title`, `section`, `summary`, `doc_path`, then optional version fields.
-- Normalize frontmatter to TOML with quoted strings.
+- Normalize frontmatter to TOML with quoted strings and lowercase booleans.
 - Normalize code fences to exactly `````python` and `````output`.
 - Ensure each file ends with one newline.
 - Leave Python code semantics unchanged; do not run Black over snippets unless the command can prove output is unchanged.
@@ -530,6 +531,36 @@ The command should fail if:
 
 `verify-python-version` is only meaningful when `uv` can run the requested Python version. Until Cloudflare exposes the same runtime locally, the migration also requires a Worker smoke test for representative examples and at least one POST execution through Dynamic Workers.
 
+## Golden fixture policy
+
+`tests/fixtures/golden_examples.py` is temporary but intentional migration safety infrastructure.
+
+Rules:
+
+- Keep the golden fixture checked in while Markdown remains new.
+- Do not update the golden fixture in the same change as ordinary content edits.
+- If changing intended teaching structure, update Markdown first and let parity fail; then update the golden fixture in a separate explicit fixture-refresh commit after review.
+- Remove the golden fixture only after at least one stable production release cycle, CI coverage for `make verify` and `make check-generated`, and an explicit cleanup PR.
+- Until cleanup, `scripts/check_example_migration_parity.py` must be a required verification command.
+
+## CI policy
+
+GitHub Actions must run the same checks expected locally:
+
+```bash
+make verify
+scripts/check_example_migration_parity.py
+scripts/format_examples.py --check
+make verify-python-version VERSION=3.13
+git diff --check
+```
+
+CI must start `pywrangler dev --port 9696` before `make verify` so `browser-layout-test` exercises a real Worker runtime. CI must fail if generated files are stale.
+
+## Contributor documentation policy
+
+The README must describe Markdown example editing, `:::program`, `:::cell`, generated embedded source data, `make build`, `make verify-examples`, and the parity check. Contributors should not need to edit `src/examples.py` or `src/example_sources_data.py` by hand.
+
 ## Worker bundling policy
 
 Default policy:
@@ -549,6 +580,8 @@ Do not replace this with a native Wrangler data-file approach unless a spike pro
 
 The attempted migration failed at Worker startup because Markdown files were not present under `/session/metadata/`. That failure mode must remain covered by a local Worker startup check.
 
+Native Markdown bundling remains unproven and is not on the production path. The accepted solution is embedded source data generated by `scripts/embed_example_sources.py`. A future native bundling change must be isolated as a spike and prove local dev, production deploy, imports, cache fingerprinting, and failure behavior before replacing embedded data.
+
 ## Golden parity script
 
 Add a dedicated migration script before switching the app:

scripts/format_examples.py

@@ -3,19 +3,48 @@
 from __future__ import annotations
 
 import argparse
+import tomllib
 from pathlib import Path
+from typing import Any
 
 ROOT = Path(__file__).resolve().parents[1]
 SOURCE_DIR = ROOT / "src" / "example_sources"
+FRONTMATTER_ORDER = ["slug", "title", "section", "summary", "doc_path", "min_python", "version_sensitive", "version_notes"]
 
 
-def normalize_text(text: str) -> str:
+def toml_value(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, str):
+        return '"' + value.replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n") + '"'
+    if isinstance(value, list):
+        if all(isinstance(item, str) for item in value):
+            if len(value) == 0:
+                return "[]"
+            inner = "\n".join(f"  {toml_value(item)}," for item in value)
+            return "[\n" + inner + "\n]"
+    raise TypeError(f"Unsupported TOML value: {value!r}")
+
+
+def ordered_keys(data: dict[str, Any]) -> list[str]:
+    known = [key for key in FRONTMATTER_ORDER if key in data]
+    unknown = sorted(key for key in data if key not in FRONTMATTER_ORDER)
+    return known + unknown
+
+
+def dump_toml(data: dict[str, Any]) -> str:
+    return "\n".join(f"{key} = {toml_value(data[key])}" for key in ordered_keys(data)) + "\n"
+
+
+def normalize_body(text: str) -> str:
     lines = [line.rstrip() for line in text.replace("\r\n", "\n").split("\n")]
     out: list[str] = []
     blank = False
     in_fence = False
     for line in lines:
         if line.startswith("```"):
+            if line == "```py":
+                line = "```python"
             in_fence = not in_fence
         if not in_fence and line == "":
             if blank:
@@ -24,17 +53,46 @@ def normalize_text(text: str) -> str:
         else:
             blank = False
         out.append(line)
-    return "\n".join(out).strip() + "\n"
+    return "\n".join(out).strip()
+
+
+def split_frontmatter(text: str, path: Path) -> tuple[dict[str, Any], str]:
+    normalized = text.replace("\r\n", "\n")
+    if not normalized.startswith("+++\n"):
+        raise ValueError(f"{path}: expected +++ frontmatter")
+    marker = "\n+++\n"
+    end = normalized.find(marker, 4)
+    if end < 0:
+        raise ValueError(f"{path}: missing closing +++")
+    frontmatter = tomllib.loads(normalized[4:end])
+    return frontmatter, normalized[end + len(marker) :]
+
+
+def format_markdown(path: Path) -> str:
+    frontmatter, body = split_frontmatter(path.read_text(), path)
+    return "+++\n" + dump_toml(frontmatter) + "+++\n\n" + normalize_body(body) + "\n"
+
+
+def format_manifest(path: Path) -> str:
+    data = tomllib.loads(path.read_text())
+    sections = [
+        f"python_version = {toml_value(data['python_version'])}",
+        f"docs_base_url = {toml_value(data['docs_base_url'])}",
+        "",
+        f"order = {toml_value(data['order'])}",
+    ]
+    return "\n".join(sections) + "\n"
 
 
 def main() -> int:
     parser = argparse.ArgumentParser()
     parser.add_argument("--check", action="store_true")
     args = parser.parse_args()
     changed: list[Path] = []
-    for path in [SOURCE_DIR / "manifest.toml", *sorted(SOURCE_DIR.glob("*.md"))]:
+    paths = [SOURCE_DIR / "manifest.toml", *sorted(SOURCE_DIR.glob("*.md"))]
+    for path in paths:
         original = path.read_text()
-        formatted = normalize_text(original)
+        formatted = format_manifest(path) if path.name == "manifest.toml" else format_markdown(path)
         if formatted != original:
             changed.append(path)
             if not args.check:

tests/test_markdown_migration_prereqs.py

@@ -4,6 +4,8 @@
 ROOT = Path(__file__).resolve().parents[1]
 SPEC = ROOT / "docs" / "example-source-format-spec.md"
 INVESTIGATION = ROOT / "docs" / "markdown-cell-migration-investigation.md"
+README = ROOT / "README.md"
+CI = ROOT / ".github" / "workflows" / "verify.yml"
 
 
 class MarkdownMigrationPrereqTests(unittest.TestCase):
@@ -82,6 +84,26 @@ def test_spec_captures_successful_migration_and_rollback_rehearsal(self):
         self.assertIn("revert the migration, deploy the rollback", spec)
         self.assertIn("re-apply the migration and repeat verification", spec)
 
+    def test_remaining_operational_lessons_are_documented_and_verified(self):
+        spec = SPEC.read_text()
+        readme = README.read_text()
+        workflow = CI.read_text()
+        for phrase in [
+            "Golden fixture policy",
+            "CI policy",
+            "Contributor documentation policy",
+            "Native Markdown bundling remains unproven",
+            "reserialize it deterministically",
+        ]:
+            with self.subTest(phrase=phrase):
+                self.assertIn(phrase, spec)
+        for phrase in ["src/example_sources/", ":::program", ":::cell", "make build", "make verify-examples"]:
+            with self.subTest(readme=phrase):
+                self.assertIn(phrase, readme)
+        for phrase in ["make verify", "check_example_migration_parity.py", "format_examples.py --check", "verify-python-version"]:
+            with self.subTest(workflow=phrase):
+                self.assertIn(phrase, workflow)
+
 
 if __name__ == "__main__":
     unittest.main()