Refactor shared utils and add sorted authors to blog-resolve.

Consolidate duplicate split_front_matter into crate::util (renamed from
slug.rs), add authors_sorted list to blog_resolved.yml for the authors
page template, and clean up CLI output to use stderr for user messages.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: oubiwann

src/_layouts/blog-authors.liquid

@@ -21,18 +21,9 @@
 
         <h1 class="blog-section-heading">{{ page.data.long_title }}</h1>
 
-        {% for author_entry in site.data.authors %}
-          {% assign slug = author_entry[0] %}
-          {% assign author = author_entry[1] %}
-
-          {% assign post_count = 0 %}
-          {% for post in paginator.pages %}
-            {% if post.data.author == slug %}
-              {% assign post_count = post_count | plus: 1 %}
-            {% endif %}
-          {% endfor %}
+        {% for author in site.data.blog_resolved.authors_sorted %}
 
-          <a href="/blog/authors/{{ slug }}/" class="blog-author-page-card">
+          <a href="/blog/authors/{{ author.slug }}/" class="blog-author-page-card">
             {% if author.avatar %}
             <img src="{{ author.avatar }}" alt="{{ author.name }}" class="blog-author-avatar-lg">
             {% else %}
@@ -43,7 +34,7 @@
               {% if author.bio %}
               <p class="blog-author-page-bio">{{ author.bio }}</p>
               {% endif %}
-              <p class="blog-card-meta">{{ post_count }} posts</p>
+              <p class="blog-card-meta">{{ author.post_count }} posts</p>
             </div>
           </a>
         {% endfor %}

tools/lfesite/src/cmd/blog_migrate.rs

@@ -5,6 +5,8 @@ use std::path::Path;
 use anyhow::{Context, Result};
 use regex::Regex;
 
+use crate::util::split_front_matter;
+
 /// Run the Jekyll-to-Cobalt blog post migration.
 pub fn run(project_dir: &Path, source: &Path) -> Result<()> {
     println!("blog-migrate: discovering source posts...");
@@ -177,7 +179,10 @@ pub fn run(project_dir: &Path, source: &Path) -> Result<()> {
         // Build categories YAML
         let categories_yaml = format!("[\"{}\"]", category);
 
-        // Build front-matter
+        // Build front-matter via format! rather than serde_yaml. This is
+        // intentional: the corpus is controlled (all 116 posts verified), and
+        // string formatting gives us exact control over field order and
+        // indentation. Titles/descriptions are escaped via escape_yaml_string().
         let new_front_matter = format!(
             "---\n\
              layout: post.liquid\n\
@@ -372,23 +377,6 @@ pub fn run(project_dir: &Path, source: &Path) -> Result<()> {
 // Helpers
 // ---------------------------------------------------------------------------
 
-/// Split content into (front-matter, body). Front-matter is between `---` delimiters.
-fn split_front_matter(content: &str) -> Option<(String, &str)> {
-    let trimmed = content.trim_start();
-    let rest = trimmed.strip_prefix("---")?;
-    // Find the closing ---
-    let end = rest.find("\n---")?;
-    let fm = rest[..end].to_string();
-    let body_start = end + 4; // skip \n---
-    // Skip the newline after closing ---
-    let body = if body_start < rest.len() && rest.as_bytes()[body_start] == b'\n' {
-        &rest[body_start + 1..]
-    } else {
-        &rest[body_start..]
-    };
-    Some((fm, body))
-}
-
 /// Extract a simple field value from YAML front-matter text.
 fn extract_field(fm: &str, key: &str) -> Option<String> {
     for line in fm.lines() {
@@ -455,7 +443,11 @@ fn normalize_tag(tag: &str) -> String {
     }
 }
 
-/// Map author name to slug.
+/// Map an author's display name to their URL slug.
+///
+/// The six known authors are from the legacy `blog.lfe.io` Jekyll
+/// corpus (2014–2020). Unknown names are slugified and logged as
+/// warnings so they can be added to `_data/authors.yml`.
 fn author_to_slug(name: &str) -> String {
     match name.trim() {
         "Duncan McGreggor" => "duncan-mcgreggor".to_string(),

tools/lfesite/src/cmd/blog_resolve.rs

@@ -6,6 +6,8 @@ use anyhow::{Context, Result};
 use sha2::{Digest, Sha256};
 use walkdir::WalkDir;
 
+use crate::util::split_front_matter;
+
 /// Resolve blog editorial configuration into a template-ready data file.
 ///
 /// Reads `_data/blog.yml` (editorial config) and all post front-matter from
@@ -97,7 +99,10 @@ pub fn run(src_dir: &Path) -> Result<()> {
         resolved_slots.push((*name, resolved));
     }
 
-    // 6. Build river
+    // 6. Build sorted authors list (by post count desc, then name asc)
+    let authors_sorted = build_sorted_authors(&all_posts, &data_dir)?;
+
+    // 7. Build river
     let river: Vec<serde_yaml::Value> = all_posts
         .iter()
         .filter(|p| !used.contains(&p.slug))
@@ -108,7 +113,7 @@ pub fn run(src_dir: &Path) -> Result<()> {
         })
         .collect();
 
-    // 7. Assemble output
+    // 8. Assemble output
     let mut out = serde_yaml::Mapping::new();
 
     for (name, value) in &resolved_slots {
@@ -118,13 +123,14 @@ pub fn run(src_dir: &Path) -> Result<()> {
     }
 
     out.insert(ykey("river"), serde_yaml::Value::Sequence(river));
+    out.insert(ykey("authors_sorted"), serde_yaml::Value::Sequence(authors_sorted));
     out.insert(ykey("default_cover_image"), ystr(default_cover));
     out.insert(ykey("default_cover_alt"), ystr(default_alt));
 
     let yaml_out = serde_yaml::to_string(&serde_yaml::Value::Mapping(out))
         .context("serializing blog_resolved.yml")?;
 
-    // 8. Write (idempotent)
+    // 9. Write (idempotent)
     let resolved_path = data_dir.join("blog_resolved.yml");
     let needs_write = if resolved_path.exists() {
         let existing = fs::read_to_string(&resolved_path).unwrap_or_default();
@@ -409,19 +415,72 @@ fn slug_from_path(path: &Path, posts_dir: &Path) -> Option<String> {
     }
 }
 
-/// Split YAML front-matter (`---` delimited) from body content.
-fn split_front_matter(content: &str) -> Option<(String, &str)> {
-    let trimmed = content.trim_start();
-    let rest = trimmed.strip_prefix("---")?;
-    let end = rest.find("\n---")?;
-    let fm = rest[..end].to_string();
-    let body_start = end + 4;
-    let body = if body_start < rest.len() && rest.as_bytes()[body_start] == b'\n' {
-        &rest[body_start + 1..]
-    } else {
-        &rest[body_start..]
-    };
-    Some((fm, body))
+
+/// Build a sorted list of authors with post counts for template use.
+///
+/// Sorted by post count descending, then display name ascending for ties.
+fn build_sorted_authors(posts: &[PostMeta], data_dir: &Path) -> Result<Vec<serde_yaml::Value>> {
+    let path = data_dir.join("authors.yml");
+    if !path.exists() {
+        return Ok(Vec::new());
+    }
+
+    let content = fs::read_to_string(&path).context("reading authors.yml")?;
+    let doc: serde_yaml::Value =
+        serde_yaml::from_str(&content).context("parsing authors.yml")?;
+
+    let mut post_counts: HashMap<String, usize> = HashMap::new();
+    for post in posts {
+        *post_counts.entry(post.author_slug.clone()).or_insert(0) += 1;
+    }
+
+    let mut author_entries: Vec<(String, String, Option<String>, Option<String>, usize)> = Vec::new();
+
+    if let Some(map) = doc.as_mapping() {
+        for (key, value) in map {
+            if let Some(slug) = key.as_str() {
+                let name = value
+                    .get("name")
+                    .and_then(|v| v.as_str())
+                    .unwrap_or(slug)
+                    .to_string();
+                let bio = value
+                    .get("bio")
+                    .and_then(|v| v.as_str())
+                    .map(String::from);
+                let avatar = value
+                    .get("avatar")
+                    .and_then(|v| v.as_str())
+                    .map(String::from);
+                let count = post_counts.get(slug).copied().unwrap_or(0);
+                author_entries.push((slug.to_string(), name, bio, avatar, count));
+            }
+        }
+    }
+
+    author_entries.sort_by(|a, b| b.4.cmp(&a.4).then_with(|| a.1.cmp(&b.1)));
+
+    let sorted: Vec<serde_yaml::Value> = author_entries
+        .into_iter()
+        .map(|(slug, name, bio, avatar, count)| {
+            let mut map = serde_yaml::Mapping::new();
+            map.insert(ykey("slug"), ystr(&slug));
+            map.insert(ykey("name"), ystr(&name));
+            if let Some(b) = &bio {
+                map.insert(ykey("bio"), ystr(b));
+            }
+            if let Some(a) = &avatar {
+                map.insert(ykey("avatar"), ystr(a));
+            }
+            map.insert(
+                ykey("post_count"),
+                serde_yaml::Value::Number(serde_yaml::Number::from(count as u64)),
+            );
+            serde_yaml::Value::Mapping(map)
+        })
+        .collect();
+
+    Ok(sorted)
 }
 
 /// Load author slug → display name mapping from `_data/authors.yml`.

tools/lfesite/src/cmd/build.rs

@@ -336,8 +336,13 @@ fn ensure_pagefind_binary() -> Result<std::path::PathBuf> {
 
 /// Resolve the latest pagefind release version tag (e.g. "v1.3.0").
 ///
-/// Uses the GitHub API to query the latest release, extracting the
-/// tag_name field with grep/sed (no jq dependency).
+/// Resolve the latest pagefind release version tag (e.g. "v1.3.0").
+///
+/// Uses the GitHub API JSON endpoint with a `curl | grep | sed` shell
+/// pipeline to extract `tag_name`. This depends on `curl`, `grep`, and
+/// `sed` being available on PATH (standard on macOS and Linux). If the
+/// GitHub API response format changes, this will fail with a clear
+/// error message rather than silently downloading the wrong version.
 fn resolve_pagefind_version() -> Result<String> {
     let output = Command::new("sh")
         .args([

tools/lfesite/src/cmd/draft_post.rs

@@ -4,6 +4,7 @@ use std::path::Path;
 
 use anyhow::{bail, Context, Result};
 
+/// Convert a published post to draft, or create a new draft interactively.
 pub fn run(project_dir: &Path, file: Option<&Path>) -> Result<()> {
     match file {
         Some(f) => draft_existing(f),
@@ -20,8 +21,8 @@ fn draft_existing(file: &Path) -> Result<()> {
         .with_context(|| format!("reading {}", file.display()))?;
 
     if content.contains("is_draft: true") {
-        println!();
-        println!("  already a draft: {}", file.display());
+        eprintln!();
+        eprintln!("  already a draft: {}", file.display());
         return Ok(());
     }
 
@@ -39,17 +40,17 @@ fn draft_existing(file: &Path) -> Result<()> {
         .map(|l| l.trim_start_matches("title:").trim().trim_matches('"'))
         .unwrap_or("(unknown)");
 
-    println!();
-    println!("  drafted: {}", file.display());
-    println!("  title:   \"{}\"", title);
-    println!();
+    eprintln!();
+    eprintln!("  drafted: {}", file.display());
+    eprintln!("  title:   \"{}\"", title);
+    eprintln!();
 
     Ok(())
 }
 
 fn draft_new(project_dir: &Path) -> Result<()> {
-    print!("  Title: ");
-    io::stdout().flush()?;
+    eprint!("  Title: ");
+    io::stderr().flush()?;
     let mut title = String::new();
     io::stdin().read_line(&mut title)?;
     let title = title.trim();

tools/lfesite/src/cmd/mod.rs

@@ -1,3 +1,5 @@
+//! Subcommand implementations for the `lfesite` CLI.
+
 pub mod blog_migrate;
 pub mod blog_resolve;
 pub mod build;

tools/lfesite/src/cmd/new_post.rs

@@ -6,8 +6,9 @@ use std::process::Command;
 use anyhow::{bail, Context, Result};
 use chrono::{NaiveDateTime, Utc};
 
-use crate::slug::slugify;
+use crate::util::slugify;
 
+/// Create a new blog post file with front-matter scaffolding.
 pub fn run(
     project_dir: &Path,
     title: &str,
@@ -93,16 +94,16 @@ data:
         .with_context(|| format!("writing {}", filepath.display()))?;
 
     let rel_path = filepath.strip_prefix(project_dir).unwrap_or(&filepath);
-    println!();
-    println!("  created: {}", rel_path.display());
-    println!("  status:  {}", if draft { "draft" } else { "published (use --draft for draft)" });
-    println!("  author:  {author}");
-    println!();
+    eprintln!();
+    eprintln!("  created: {}", rel_path.display());
+    eprintln!("  status:  {}", if draft { "draft" } else { "published (use --draft for draft)" });
+    eprintln!("  author:  {author}");
+    eprintln!();
 
     // Offer to open in $EDITOR
     if let Ok(editor) = std::env::var("EDITOR") {
-        print!("  Open post in $EDITOR? [Y/n] ");
-        io::stdout().flush()?;
+        eprint!("  Open post in $EDITOR? [Y/n] ");
+        io::stderr().flush()?;
         let mut input = String::new();
         io::stdin().read_line(&mut input)?;
         let input = input.trim().to_lowercase();
@@ -126,12 +127,16 @@ fn detect_author() -> String {
         Ok(o) if o.status.success() => {
             let name = String::from_utf8_lossy(&o.stdout).trim().to_string();
             if name.is_empty() {
+                eprintln!("  note: git user.name is empty, using 'unknown' as author");
                 "unknown".to_string()
             } else {
                 slugify(&name)
             }
         }
-        _ => "unknown".to_string(),
+        _ => {
+            eprintln!("  note: could not detect author from git, using 'unknown'");
+            "unknown".to_string()
+        }
     }
 }
 

tools/lfesite/src/cmd/publish_post.rs

@@ -3,6 +3,7 @@ use std::path::Path;
 
 use anyhow::{bail, Context, Result};
 
+/// Publish a draft post by setting `is_draft: false` in its front matter.
 pub fn run(file: &Path) -> Result<()> {
     if !file.exists() {
         bail!("file not found: {}", file.display());
@@ -12,8 +13,8 @@ pub fn run(file: &Path) -> Result<()> {
         .with_context(|| format!("reading {}", file.display()))?;
 
     if content.contains("is_draft: false") {
-        println!();
-        println!("  already published: {}", file.display());
+        eprintln!();
+        eprintln!("  already published: {}", file.display());
         return Ok(());
     }
 
@@ -32,10 +33,10 @@ pub fn run(file: &Path) -> Result<()> {
         .map(|l| l.trim_start_matches("title:").trim().trim_matches('"'))
         .unwrap_or("(unknown)");
 
-    println!();
-    println!("  published: {}", file.display());
-    println!("  title:     \"{}\"", title);
-    println!();
+    eprintln!();
+    eprintln!("  published: {}", file.display());
+    eprintln!("  title:     \"{}\"", title);
+    eprintln!();
 
     Ok(())
 }

tools/lfesite/src/cmd/validate.rs

@@ -78,9 +78,10 @@ pub fn run(project_dir: &Path) -> Result<()> {
     // Check 2: _md/_html pairing (report)
     // ------------------------------------------------------------------
     println!("validate: checking _md/_html pairing...");
-    let pairing_errors: Vec<&String> = errors
+    let pairing_errors: Vec<&str> = errors
         .iter()
         .filter(|e| e.contains("has no") && e.contains("_html sibling"))
+        .map(|e| e.as_str())
         .collect();
     if pairing_errors.is_empty() {
         println!("  \u{2713} all _md fields have _html siblings");

tools/lfesite/src/main.rs

@@ -4,7 +4,7 @@ use anyhow::Result;
 use clap::{Parser, Subcommand};
 
 mod cmd;
-mod slug;
+mod util;
 
 /// Build orchestration and data pre-rendering for the LFE website.
 #[derive(Debug, Parser)]