@grove-dev/astro 0.4.1 → 0.5.0-next.2

package/src/server/directory.ts

@@ -38,7 +38,13 @@ import { fileURLToPath } from "node:url";
 import { dirname, resolve } from "node:path";
 import { marked } from "marked";
 import sanitizeHtml from "sanitize-html";
+import { createHighlighter } from "shiki";
 import { prettySlug } from "../lib/display.js";
+import {
+  readContentFile,
+  stripFrontmatter,
+  uniqueSlug,
+} from "@grove-dev/core";
 import type {
   ProjectRecord,
   ResourceRecord,
@@ -287,13 +293,299 @@ export const fullProjects: ProjectRecord[] = fullRecords.filter(
 // missing. No page module needs to import `node:fs` anymore.
 
 const here = dirname(fileURLToPath(import.meta.url));
-function resolveContentPath(contentPath: string): string {
-  const candidates = [
-    resolve(here, "..", "..", contentPath),
-    resolve(here, "..", "..", "..", contentPath),
-    resolve(process.cwd(), contentPath),
-  ];
-  return candidates.find((p) => existsSync(p)) ?? "";
+
+// ── Markdown rendering ────────────────────────────────────────────────
+//
+// Record bodies and consumer-authored pages both go through the
+// same pipeline:
+//
+//   body  →  marked.parse(body)  →  sanitizeHtml(html, allowlist)
+//
+// The differences are:
+//   - record bodies use the wide `RECORD_BODY_ALLOWLIST` (tables,
+//     images, task-list inputs, details/summary, kbd/mark/sub/sup,
+//     …) so a curated `.md` sidecar can use the full surface.
+//   - page bodies use the narrower `PAGE_BODY_ALLOWLIST` so a
+//     page-author's `.md` stays in a conservative prose-only space.
+//
+// Both paths run at module load so `getContentHtml(slug)` and
+// `getPageContentHtml(name)` return pre-sanitized HTML with no
+// per-request work.
+
+/** Wide allowlist used for `ProjectRecord.content` Markdown bodies. */
+const RECORD_BODY_ALLOWLIST = [
+  // Headings — full depth.
+  "h1", "h2", "h3", "h4", "h5", "h6",
+  // Block-level content.
+  "p", "br", "hr", "div", "blockquote",
+  // Lists.
+  "ul", "ol", "li",
+  // Definition lists.
+  "dl", "dt", "dd",
+  // Tables (GFM).
+  "table", "thead", "tbody", "tfoot", "tr", "th", "td",
+  "caption", "colgroup", "col",
+  // Inline formatting.
+  "strong", "em", "b", "i", "u", "s", "del", "ins",
+  "mark", "small", "sub", "sup", "kbd", "abbr",
+  // `<span>` is only here for Shiki's per-token wrappers inside
+  // highlighted code blocks. Sanitize-html's default is to strip
+  // any tag not in this list, so without `span` here the syntax
+  // highlights silently disappear from fenced code.
+  "span",
+  // Links + images.
+  "a", "img",
+  // Code.
+  "code", "pre",
+  // Forms (task-list checkboxes only).
+  "input", "label",
+  // Collapsibles and semantic blocks.
+  "details", "summary",
+  "figure", "figcaption",
+  "time",
+];
+
+/** Narrow allowlist used for `content/pages/<page>.md`. */
+const PAGE_BODY_ALLOWLIST = [
+  "h1", "h2", "h3", "h4",
+  "p", "br", "hr",
+  "ul", "ol", "li",
+  "strong", "em", "b", "i", "u", "s", "del",
+  "a", "code", "pre", "blockquote", "img",
+];
+
+/**
+ * Attributes the sanitizer keeps per tag. The shared `* → ["id", "class"]`
+ * rule preserves the heading anchors the renderer adds and the
+ * Shiki syntax-highlighting classes (`shiki`, `language-bash`,
+ * …) on `<pre>` and `<code>` blocks. Image `loading/decoding`
+ * get forced to lazy/async to keep page weight down; `<input>`
+ * becomes a hardened disabled checkbox for GFM task lists.
+ */
+const COMMON_BODY_ATTRIBUTES = {
+  a: ["href", "title", "rel", "target"],
+  img: ["src", "alt", "title", "width", "height", "loading", "decoding"],
+  th: ["scope", "colspan", "rowspan", "align"],
+  td: ["colspan", "rowspan", "align"],
+  col: ["span", "align"],
+  input: ["type", "checked", "disabled"],
+  label: ["for"],
+  abbr: ["title"],
+  time: ["datetime"],
+  details: ["open"],
+  div: ["class"], // table-wrap div the renderer injects
+  span: ["style"], // Shiki emits inline `--shiki-light` / `--shiki-dark` CSS variables
+  pre: ["class", "style"], // Shiki also tags the outer `<pre>` with theme classes
+  code: ["class"],
+  "*": ["id"],
+};
+
+/** `<a>` tag normalization — open in a new tab, no opener. */
+const ANCHOR_TRANSFORM = sanitizeHtml.simpleTransform(
+  "a",
+  { rel: "noopener noreferrer", target: "_blank" },
+  true,
+);
+
+/** Hardens `<img>` to lazy-load + async-decode. */
+const IMG_TRANSFORM = (
+  tagName: string,
+  attribs: Record<string, string>,
+) => ({
+  tagName,
+  attribs: {
+    ...attribs,
+    loading: attribs.loading ?? "lazy",
+    decoding: attribs.decoding ?? "async",
+  },
+});
+
+/** Forces `<input type="checkbox">` to be disabled so task lists
+ *  render read-only at runtime (no on-page state to persist). */
+const INPUT_TRANSFORM = (
+  tagName: string,
+  attribs: Record<string, string>,
+) => ({
+  tagName,
+  attribs: {
+    ...attribs,
+    type: "checkbox",
+    disabled: "",
+    ...(attribs.checked !== undefined ? { checked: "" } : {}),
+  },
+});
+
+/**
+ * GitHub-style slug for a heading. Matches `core/extractToc` so the
+ * IDs the renderer emits line up with the IDs a TOC consumer reads
+ * out of the same body — keeping deep links in lockstep.
+ */
+function headingSlug(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[‘’]/g, "")
+    .replace(/[^a-z0-9\s-]/g, "")
+    .replace(/\s+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-+$/g, "");
+}
+
+/**
+ * Render a Markdown string to sanitized HTML. The renderer is
+ * configured once (heading IDs + table wrap) and reused for both
+ * record and page bodies.
+ *
+ * Why pass `body` rather than a slug: this is a pure transform; the
+ * caller owns where the body came from (file, in-memory cache, …).
+ * `getContentHtml(slug)` is the per-record wrapper that reads the
+ * file and calls this.
+ */
+export function renderMarkdownToSafeHtml(
+  body: string,
+  options: { allowlist?: string[] } = {},
+): string {
+  const allowlist = options.allowlist ?? RECORD_BODY_ALLOWLIST;
+  // Configure marked. GFM is on by default in v18 but set explicitly
+  // so the intent is visible; `breaks: false` keeps single newlines
+  // from becoming `<br>` per CommonMark.
+  //
+  // We register a small extension that:
+  //   1. Adds a stable `id` to every h2–h6 so the TOC sidebar can
+  //      deep-link into the rendered body.
+  //   2. Wraps GFM tables in `<div class="grove-prose-table-wrap">`
+  //      so the column-width overflow is contained inside a rounded
+  //      border instead of breaking the layout.
+  marked.use({
+    gfm: true,
+    breaks: false,
+    renderer: {
+      heading({ tokens, depth }) {
+        const inline = this.parser.parseInline(tokens);
+        const plain = tokens
+          .map((t: { text?: string; raw?: string }) => t.text ?? t.raw ?? "")
+          .join("");
+        const id = depth === 1 ? "" : ` id="${uniqueSlug(headingSlug(plain) || "section", headingIds)}"`;
+        return `<h${depth}${id}>${inline}</h${depth}>\n`;
+      },
+      table(token: {
+        header: Array<{ tokens: unknown[] }>;
+        rows: Array<Array<{ tokens: unknown[] }>>;
+      }) {
+        const head = token.header
+          .map((cell) => `<th>${this.parser.parseInline(cell.tokens)}</th>`)
+          .join("");
+        const body = token.rows
+          .map((row) =>
+            `<tr>${row
+              .map((cell) => `<td>${this.parser.parseInline(cell.tokens)}</td>`)
+              .join("")}</tr>`,
+          )
+          .join("");
+        return `<div class="grove-prose-table-wrap"><table><thead><tr>${head}</tr></thead><tbody>${body}</tbody></table></div>\n`;
+      },
+      // Fenced code blocks: route through Shiki instead of marked's
+      // default `<pre><code class="language-…">…</code></pre>`. The
+      // returned HTML already wraps in `<pre>` and `<code>`; we
+      // hand it to the sanitizer unchanged (Shiki's output is
+      // safe by construction — no script / event handlers).
+      code({ text, lang }) {
+        return highlightCode(text, lang ?? "") + "\n";
+      },
+    },
+  });
+
+  const rawHtml = marked.parse(body, { async: false }) as string;
+  return sanitizeHtml(rawHtml, {
+    allowedTags: allowlist,
+    allowedAttributes: COMMON_BODY_ATTRIBUTES,
+    allowedSchemes: ["http", "https", "mailto", "tel"],
+    allowedSchemesByTag: {
+      a: ["http", "https", "mailto", "tel"],
+      img: ["http", "https", "data"],
+    },
+    allowedSchemesAppliedToAttributes: ["href", "src"],
+    transformTags: {
+      a: ANCHOR_TRANSFORM,
+      img: IMG_TRANSFORM,
+      input: INPUT_TRANSFORM,
+    },
+    disallowedTagsMode: "discard",
+  });
+}
+
+/** Per-render counter so heading IDs don't collide within a body. */
+const headingIds = new Map<string, number>();
+
+// ── Shiki syntax highlighter ─────────────────────────────────────────
+//
+// Build-time tokenisation for fenced code blocks. Shiki returns a
+// string of HTML — `<pre class="shiki …"><code>…</code></pre>` —
+// and we drop it straight into the marked output where the code
+// block would otherwise be a flat `<pre><code class="language-…">`.
+//
+// Two themes (light + dark) are loaded; the `defaultColor: false`
+// flag asks Shiki to emit CSS variables (`--shiki-light`,
+// `--shiki-dark`) instead of inline `color:` declarations. The
+// selectors in `styles.css` then swap which set of variables wins
+// when the consumer toggles `.dark` on `<html>`. Net effect:
+// the same HTML is themed correctly in both modes without us
+// re-rendering at runtime.
+//
+// We use `github-dark-default` rather than `github-dark` for the
+// dark side: `github-dark` paints comments at `#6A737D`, which
+// fails WCAG AA contrast (3.72:1) against our `--color-ink-950`
+// `#171717` code-block background and trips the Lighthouse
+// accessibility audit on any record that contains a `# …` shell
+// comment. `github-dark-default` shifts comments to `#8B949E`,
+// which clears 4.5:1 against the same background (~6.3:1).
+//
+// `getSingletonHighlighter()` lazily loads the engine on first use
+// and caches it for every subsequent call — Shiki's WASM/grammar
+// load takes a few hundred ms, so we want to amortise across all
+// records in a build. The list of supported languages is curated
+// (not `ALL`) so the build doesn't pull Shiki's full grammar pack.
+const SUPPORTED_LANGS = [
+  "bash", "sh", "shell", "console",
+  "python", "py",
+  "javascript", "js", "jsx", "typescript", "ts", "tsx",
+  "json", "jsonc", "yaml", "yml", "toml",
+  "markdown", "md", "mdx",
+  "html", "css", "scss", "sass",
+  "sql", "graphql",
+  "dockerfile", "diff",
+  "rust", "go", "java", "kotlin", "swift", "ruby", "php",
+  "c", "cpp", "csharp", "objective-c",
+  "xml", "ini", "properties",
+];
+const highlighter = await createHighlighter({
+  themes: ["github-light", "github-dark-default"],
+  langs: SUPPORTED_LANGS,
+});
+
+/**
+ * Highlight a fenced code block with Shiki. Returns the Shiki HTML
+ * wrapped in our `<pre>`-equivalent class so the existing
+ * `.grove-prose pre` rules continue to apply (padding, border,
+ * scroll behaviour).
+ */
+function highlightCode(text: string, lang: string): string {
+  const normalized = lang?.toLowerCase() ?? "";
+  const safeLang = highlighter.getLoadedLanguages().includes(normalized)
+    ? normalized
+    : "text";
+  const html = highlighter.codeToHtml(text, {
+    lang: safeLang,
+    themes: { light: "github-light", dark: "github-dark-default" },
+    defaultColor: false,
+  });
+  // Strip the outer `<pre>`'s inline `background-color` so it doesn't
+  // fight our package's prose background. The per-token `<span>`
+  // `style="--shiki-light: …; --shiki-dark: …"` declarations must
+  // survive — they're what makes dual-theme work.
+  return html.replace(
+    /(<pre[^>]*?)\s+style="[^"]*"/g,
+    "$1",
+  );
 }
 
 const contentHtmlBySlug = new Map<string, string>();
@@ -301,36 +593,15 @@ for (const r of fullRecords) {
   if (r.kind !== "project") continue;
   const projectRecord = r as ProjectRecord;
   if (!projectRecord.content) continue;
-  const path = resolveContentPath(projectRecord.content);
-  if (!path) continue;
+  const read = readContentFile(projectRecord.content);
+  if (!read) continue;
+  // Each render needs a fresh headingIds map so the per-body
+  // collision counter starts at zero. Otherwise the second record
+  // in the loop would inherit the first record's counters and
+  // duplicate-heading IDs would collide across records.
+  headingIds.clear();
   try {
-    const text = readFileSync(path, "utf8");
-    // `async: false` keeps the call synchronous so we can populate
-    // the map at module-load time. (marked v18 defaults to
-    // Promise-returning; v9-17 also support this flag.)
-    const rawHtml = marked.parse(text, { async: false }) as string;
-    const safeHtml = sanitizeHtml(rawHtml, {
-      allowedTags: [
-        "h1", "h2", "h3", "h4",
-        "p", "br", "hr",
-        "ul", "ol", "li",
-        "strong", "em", "b", "i", "u", "s", "del",
-        "a", "code", "pre", "blockquote",
-      ],
-      allowedAttributes: {
-        a: ["href", "title", "rel", "target"],
-      },
-      allowedSchemes: ["http", "https", "mailto", "tel"],
-      allowedSchemesByTag: { a: ["http", "https", "mailto", "tel"] },
-      transformTags: {
-        a: sanitizeHtml.simpleTransform("a", {
-          rel: "noopener noreferrer",
-          target: "_blank",
-        }, true),
-      },
-      disallowedTagsMode: "discard",
-    });
-    contentHtmlBySlug.set(r.slug, safeHtml);
+    contentHtmlBySlug.set(r.slug, renderMarkdownToSafeHtml(read.body));
   } catch {
     // Missing / unreadable / parse-failed content: skip the record
     // rather than render broken HTML. The page treats `null` as
@@ -364,35 +635,10 @@ export function getPageContentHtml(page: string): string | null {
   if (!path) return null;
 
   try {
-    const markdown = readFileSync(path, "utf8").replace(
-      /^---\r?\n[\s\S]*?\r?\n---\r?\n?/,
-      "",
-    );
-    const rawHtml = marked.parse(markdown, { async: false }) as string;
-    return sanitizeHtml(rawHtml, {
-      allowedTags: [
-        "h1", "h2", "h3", "h4",
-        "p", "br", "hr",
-        "ul", "ol", "li",
-        "strong", "em", "b", "i", "u", "s", "del",
-        "a", "code", "pre", "blockquote", "img",
-      ],
-      allowedAttributes: {
-        a: ["href", "title", "rel", "target"],
-        img: ["src", "alt", "title", "width", "height", "loading"],
-      },
-      allowedSchemes: ["http", "https", "mailto", "tel"],
-      allowedSchemesByTag: {
-        a: ["http", "https", "mailto", "tel"],
-        img: ["http", "https"],
-      },
-      transformTags: {
-        a: sanitizeHtml.simpleTransform("a", {
-          rel: "noopener noreferrer",
-          target: "_blank",
-        }, true),
-      },
-      disallowedTagsMode: "discard",
+    const markdown = stripFrontmatter(readFileSync(path, "utf8"));
+    headingIds.clear();
+    return renderMarkdownToSafeHtml(markdown, {
+      allowlist: PAGE_BODY_ALLOWLIST,
     });
   } catch {
     return null;

package/src/server/models.ts

@@ -6,13 +6,20 @@
  */
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
-import type { IndexFilters, IndexRecord, ProjectRecord } from "@grove-dev/core";
+import type {
+  IndexFilters,
+  IndexRecord,
+  ProjectRecord,
+  ReadingMetrics,
+  TocEntry,
+} from "@grove-dev/core";
 import {
   activeFilterChips,
   applySort,
   buildFacets,
   effectivePage,
   effectiveSort,
+  extractToc,
   filterRecords,
   filtersFromSearchParams,
   formatRelative,
@@ -20,6 +27,8 @@ import {
   getOwnerAndRepoFromRepoUrl,
   getOwnerAvatarUrl,
   projectStackIds,
+  readingMetrics,
+  readContentFile,
   statusDisplay,
   totalPages,
 } from "@grove-dev/core";
@@ -177,7 +186,10 @@ function configuredFacets(site?: DirectorySiteConfig) {
 
 export function getDirectoryIndexModel(searchParams: URLSearchParams, site?: DirectorySiteConfig) {
   const filters = filtersFromSearchParams(searchParams);
-  const rawFacets = buildFacets(items);
+  const rawFacets = buildFacets(items, {
+    curatedTagIds: site.taxonomy?.topics?.map((t) => t.id),
+    filters, // Intersection counts: each facet reflects all OTHER filters.
+  });
   const enabled = configuredFacets(site);
   const facets = {
     stacks: enabled.has("stacks") ? rawFacets.stacks.map((option) => ({ ...option, label: taxonomyLabel("stacks", option.value) })) : [],
@@ -206,7 +218,13 @@ export function getDirectoryIndexModel(searchParams: URLSearchParams, site?: Dir
 
 export function getContributorsPageModel(site: DirectorySiteConfig) {
   const contributors = loadDirectoryContributors();
-  const sorted = [...contributors].sort((a, b) =>
+  // Render-time guard: even if a stale `data/generated/contributors.json`
+  // was produced before the sync-time filter was added, never surface
+  // bot accounts (login ends with `[bot]`) on the public contributors
+  // page. The ContributorsGrid uses the same total for its heading, so
+  // the headline count always agrees with the rendered grid.
+  const human = contributors.filter((c) => !c.username.endsWith("[bot]"));
+  const sorted = [...human].sort((a, b) =>
     (b.contributions ?? 0) - (a.contributions ?? 0) || a.username.localeCompare(b.username)
   );
   const repo = site.repoUrl?.replace(/\/$/, "");
@@ -295,6 +313,8 @@ export function getRecordDetailModel(
   const language = github?.language ?? null;
   const licenseSpdx = github?.license?.spdx_id ?? null;
   const pushedAt = github?.pushed_at ?? null;
+  const isArchived = !!github?.archived;
+  const isDisabled = !!github?.disabled;
   const ownerRepo = repoUrl ? getOwnerAndRepoFromRepoUrl(repoUrl) : null;
   const avatarSrc = proj?.logoUrl ?? (ownerRepo ? getOwnerAvatarUrl(ownerRepo.owner, 80) : null);
   const rawScores = proj?.scores;
@@ -322,6 +342,9 @@ export function getRecordDetailModel(
   const languages = extras.github?.languages
     ? Object.entries(extras.github.languages).sort((a, b) => b[1] - a[1]).slice(0, 5)
     : [];
+const healthLabel = healthStatus ? statusDisplay(healthStatus) : null;
+const tags = record.tags ?? [];
+const tocBody = readContentFile(typeof record.content === "string" ? record.content : "");
 
   let jsonLd: Record<string, unknown>;
   if (isProject && proj) {
@@ -416,18 +439,168 @@ export function getRecordDetailModel(
     distribution: proj?.distribution?.channels ?? [],
     scores,
     curationLabels: record.curation?.labels ?? [],
-    tags: record.tags ?? [],
-    healthLabel: healthStatus ? statusDisplay(healthStatus) : null,
+    tags,
+    healthLabel,
     contentHtml: isProject ? getContentHtml(recordSlug) : null,
+    // Curated summary (Open Apps-written) takes priority over the
+    // raw `description` (typically copied from GitHub). Fall back to
+    // `description` when the curator has not written a summary yet.
+    summary: (record.summary && record.summary.trim()) || record.description || "",
+    sourceDescription: record.sourceDescription ?? record.description ?? "",
+    // Collection membership is populated by the consumer detail page
+    // after calling `findCollectionsFor`. Defaulting to [] keeps the
+    // model safe when the consumer doesn't wire it.
+    collectionMembership: [],
+    // Curated screenshots array. Defaulting to [] keeps the renderer
+    // safe; RecordHeader shows a gallery strip when non-empty.
+    screenshots: proj?.screenshots ?? [],
     monthlyCommits,
     maxMonthlyCommits: Math.max(1, ...monthlyCommits.map((item) => item.commits)),
     contributionSignals,
     languages,
     totalLanguageBytes: Math.max(1, languages.reduce((sum, [, bytes]) => sum + bytes, 0)),
+    // ── Sidebar-shape fields ────────────────────────────────
+    // Read once at model-build time so pages don't repeat the
+    // "is there data for this card?" logic.
+    activityBadge: computeActivityBadge({
+      pushedAt,
+      monthlyCommits,
+      isArchived,
+      isDisabled,
+    }),
+    sidebar: computeSidebarVisibility({
+      language,
+      licenseSpdx,
+      repo: github,
+      pushedAt,
+      isArchived,
+      healthLabel,
+      stacks,
+      platforms,
+      tags,
+      category: record.category,
+      contributionSignals,
+      reviewedAt: record.curation?.reviewedAt,
+    }),
+    // ── Body-derived fields ──────────────────────────────────
+    // Both depend on the sidecar Markdown; the body is re-read
+    // here even though it's also read for `contentHtml` upstream
+    // because the TOC + reading-time want the *body* (frontmatter
+    // stripped), not the HTML. Re-reading is cheap and keeps the
+    // pipeline self-documenting.
+    toc: tocBody ? extractToc(tocBody.body, { maxDepth: 2 }) : [],
+    readingMetrics: tocBody ? readingMetrics(tocBody.body) : { wordCount: 0, minutes: 1 },
     jsonLd,
   };
 }
 
+// ── Sidebar predicates ────────────────────────────────────────────
+
+/**
+ * Tone + label for the activity badge that appears in the header.
+ *
+ * Rules (intentionally explicit so a reader can predict the badge
+ * without consulting a weighting formula):
+ *
+ *   - Archived or disabled repo → "Archived"
+ *   - Recent monthly-commit total ≥ 50 → "Very active"
+ *   - ≥ 10 recent commits, or last push < 30d ago → "Active"
+ *   - ≥ 1 commit, or last push < 180d ago → "Maintained"
+ *   - last push 180d–365d → "Low activity"
+ *   - last push > 365d → "Stale"
+ *   - no push data and no commit data → null
+ *
+ * Returns `null` when neither GitHub push nor monthly commits are
+ * present (e.g. an un-synced record), so the badge simply doesn't
+ * render.
+ */
+export function computeActivityBadge(input: {
+  pushedAt: string | null;
+  monthlyCommits: Array<{ month: string; commits: number }>;
+  isArchived: boolean;
+  isDisabled: boolean;
+}): { label: string; tone: "fresh" | "ok" | "low" | "dead" } | null {
+  if (input.isArchived || input.isDisabled) {
+    return { label: "Archived", tone: "dead" };
+  }
+  const recentCommits = (input.monthlyCommits ?? [])
+    .slice(-3)
+    .reduce((sum, c) => sum + (c.commits ?? 0), 0);
+  if (recentCommits >= 50) return { label: "Very active", tone: "fresh" };
+  if (recentCommits >= 10) return { label: "Active", tone: "ok" };
+  if (recentCommits > 0) return { label: "Maintained", tone: "ok" };
+  if (input.pushedAt) {
+    const days =
+      (Date.now() - new Date(input.pushedAt).getTime()) / 86_400_000;
+    if (days < 30) return { label: "Active", tone: "ok" };
+    if (days < 180) return { label: "Maintained", tone: "ok" };
+    if (days < 365) return { label: "Low activity", tone: "low" };
+    return { label: "Stale", tone: "low" };
+  }
+  return null;
+}
+
+/**
+ * Visibility booleans for each sidebar card. Cards with no data
+ * suppress themselves entirely so the sidebar never shows "—" or
+ * "0" placeholders that confuse "we haven't fetched yet" with
+ * "the value is genuinely zero".
+ */
+export function computeSidebarVisibility(input: {
+  language: string | null;
+  licenseSpdx: string | null;
+  repo: Record<string, unknown> | null | undefined;
+  pushedAt: string | null;
+  isArchived: boolean;
+  healthLabel: string | null;
+  stacks: string[];
+  platforms: string[];
+  tags: string[];
+  category: string | undefined;
+  contributionSignals: Array<{ key: string; label: string; ok: boolean }>;
+  reviewedAt: string | undefined;
+}): {
+  showActivity: boolean;
+  showFreshness: boolean;
+  showEcosystem: boolean;
+  showSource: boolean;
+} {
+  const repoFields = input.repo ?? {};
+  const hasRepo =
+    typeof input.repo === "object" &&
+    input.repo !== null &&
+    Object.keys(repoFields).length > 0;
+  return {
+    showActivity:
+      hasRepo ||
+      !!input.language ||
+      !!input.licenseSpdx,
+    showFreshness:
+      hasRepo ||
+      !!input.pushedAt ||
+      !!input.healthLabel ||
+      input.isArchived,
+    showEcosystem:
+      input.stacks.length > 0 ||
+      input.platforms.length > 0 ||
+      input.tags.length > 0 ||
+      !!input.category ||
+      input.contributionSignals.length > 0,
+    showSource: !!input.reviewedAt,
+  };
+}
+
+/**
+ * `getStaticPaths()` body for the consumer's detail page. Centralized
+ * here so the CLI's scaffold and the example app share one definition.
+ */
+export function recordDetailPaths(site: DirectorySiteConfig) {
+  const dirSlug = site.blueprintConfig?.routeSlug ?? "items";
+  return fullItems.map((record) => ({
+    params: { slug: dirSlug, recordSlug: record.slug },
+  }));
+}
+
 export type DirectoryIndexModel = ReturnType<typeof getDirectoryIndexModel>;
 export type DirectoryHomeModel = ReturnType<typeof getHomePageModel>;
 export type SubmissionPageModel = ReturnType<typeof getSubmissionPageModel>;