@grove-dev/astro 0.3.2 → 0.4.0

package/src/components/ItemCard.astro

@@ -25,7 +25,7 @@
  */
 import type { IndexRecord, Resource, ProjectRecord, IndexProjectRecord } from "@grove-dev/core";
 import Icon from "./Icon.astro";
-import { getOwnerAndRepoFromRepoUrl, getOwnerAvatarUrl } from "@grove-dev/astro";
+import { getOwnerAndRepoFromRepoUrl, getOwnerAvatarUrl, projectStackIds } from "@grove-dev/astro";
 import { formatStars, formatRelative } from "@grove-dev/astro";
 import { statusDisplay } from "@grove-dev/astro";
 
@@ -126,12 +126,7 @@ const platforms = isProject ? (item as { platforms?: string[] }).platforms ?? []
 const visiblePlatforms = platforms.slice(0, 4);
 const platformOverflow = platforms.length - visiblePlatforms.length;
 
-const allStacks = isProject
-  ? [
-      (item as { stack?: string }).stack,
-      ...((item as { stacks?: string[] }).stacks ?? []),
-    ].filter((s): s is string => Boolean(s))
-  : [];
+const allStacks = isProject ? projectStackIds(item as ProjectRecord) : [];
 const visibleStacks = allStacks.slice(0, 3);
 const stackOverflow = allStacks.length - visibleStacks.length;
 
@@ -153,13 +148,7 @@ const category = (item as { category?: string }).category;
   class={`rounded-[calc(var(--radius)+0.25rem)] border-0 bg-muted shadow-none transition-colors hover:bg-secondary group relative flex h-full flex-col gap-3 p-4 ${className}`}
 >
   {/* Top row: logo + name + (optional) status + curated mark. */}
-  <header class="relative z-10 flex items-start gap-3">
-    <a
-      href={detailHref}
-      aria-label={`Open ${name} details`}
-      class="absolute inset-0 z-0 rounded-lg"
-    ></a>
-
+  <header class="flex items-start gap-3">
     {logoUrl ? (
       <img
         src={logoUrl}
@@ -183,11 +172,10 @@ const category = (item as { category?: string }).category;
       <h3
         class="m-0 truncate text-[0.9375rem] font-semibold tracking-tight text-ink-900 group-hover:underline dark:text-ink-100"
       >
-        {/* Name → detail page (not GitHub repo). Stacks above the
-            stretched link via z-index. */}
+        {/* Name → detail page (not GitHub repo). */}
         <a
           href={detailHref}
-          class="relative z-10 text-inherit no-underline"
+          class="inline-flex min-h-6 min-w-6 items-center text-inherit no-underline"
         >
           {name}
         </a>
@@ -203,7 +191,7 @@ const category = (item as { category?: string }).category;
                 data-event="external_repo_click"
                 data-event-source="card_owner"
                 data-event-item={slug}
-                class="relative z-10 font-mono text-ink-500 hover:text-ink-900 dark:text-ink-400 dark:hover:text-ink-100"
+                class="font-mono text-ink-500 hover:text-ink-900 dark:text-ink-400 dark:hover:text-ink-100"
               >
                 {/* `data-event` and `data-event-*` are forwarding hooks
                     for downstream analytics. Sites wire their own
@@ -215,7 +203,7 @@ const category = (item as { category?: string }).category;
                     "detail_owner" | "detail_view_github" | "detail_homepage"
                     | "detail_distribution"), and `data-event-item` is
                     the record slug. */}
-                <span class="text-ink-400 dark:text-ink-500">@</span>{owner}{repo ? <span class="text-ink-400 dark:text-ink-500">/{repo}</span> : ""}
+                <span class="text-ink-400">@</span>{owner}{repo ? <span class="text-ink-400">/{repo}</span> : ""}
               </a>
               <span class="mx-1 text-ink-300 dark:text-ink-700">·</span>
               {category}
@@ -257,7 +245,7 @@ const category = (item as { category?: string }).category;
   {/* Description */}
   {item.description && (
     <p
-      class="relative z-10 m-0 line-clamp-2 text-[0.8125rem] leading-relaxed text-ink-500 dark:text-ink-400"
+      class="m-0 line-clamp-2 text-[0.8125rem] leading-relaxed text-ink-500 dark:text-ink-400"
     >
       {item.description}
     </p>
@@ -266,7 +254,7 @@ const category = (item as { category?: string }).category;
   {/* Metadata row: stars · updated · license — the three signals
       that answer "is this alive and usable?" at a glance. */}
   {showMeta && (
-    <div class="relative z-10 flex flex-wrap items-center gap-x-3 gap-y-1 text-2xs text-ink-500 dark:text-ink-400">
+    <div class="flex flex-wrap items-center gap-x-3 gap-y-1 text-2xs text-ink-500 dark:text-ink-400">
       {starsLabel !== null && (
         <span class="inline-flex items-center gap-1" title={`${stars ?? 0} stars on GitHub`}>
           <svg viewBox="0 0 16 16" width="11" height="11" aria-hidden="true" fill="currentColor" class="text-amber-500">
@@ -293,7 +281,7 @@ const category = (item as { category?: string }).category;
 
   {/* Platform + stack chips, pushed to the bottom. */}
   {showChips && (
-    <div class="relative z-10 mt-auto flex flex-col gap-1.5">
+    <div class="mt-auto flex flex-col gap-1.5">
       {visiblePlatforms.length > 0 && (
         <div class="flex flex-wrap items-center gap-1.5">
           {visiblePlatforms.map((p) => (
@@ -303,7 +291,7 @@ const category = (item as { category?: string }).category;
             </span>
           ))}
           {platformOverflow > 0 && (
-            <span class="inline-flex min-h-5 items-center justify-center gap-1 rounded-full border border-transparent bg-secondary px-2 py-0.5 align-middle text-xs font-medium leading-none text-secondary-foreground text-ink-400 dark:text-ink-500">+{platformOverflow}</span>
+            <span class="inline-flex min-h-5 items-center justify-center gap-1 rounded-full border border-transparent bg-secondary px-2 py-0.5 align-middle text-xs font-medium leading-none text-secondary-foreground text-ink-400">+{platformOverflow}</span>
           )}
         </div>
       )}
@@ -316,7 +304,7 @@ const category = (item as { category?: string }).category;
             </span>
           ))}
           {stackOverflow > 0 && (
-            <span class="inline-flex min-h-5 items-center justify-center gap-1 rounded-full border border-transparent bg-secondary px-2 py-0.5 align-middle text-xs font-medium leading-none text-secondary-foreground !bg-muted !text-muted-foreground text-ink-400 dark:text-ink-500">+{stackOverflow}</span>
+            <span class="inline-flex min-h-5 items-center justify-center gap-1 rounded-full border border-transparent bg-secondary px-2 py-0.5 align-middle text-xs font-medium leading-none text-secondary-foreground !bg-muted !text-muted-foreground text-ink-400">+{stackOverflow}</span>
           )}
         </div>
       )}
@@ -324,7 +312,7 @@ const category = (item as { category?: string }).category;
   )}
 
   {/* Footer row: View repo + Details links. */}
-  <footer class="relative z-10 mt-1 flex items-center justify-between gap-2 border-t border-ink-100 pt-2 text-2xs dark:border-ink-900">
+  <footer class="mt-1 flex items-center justify-between gap-2 border-t border-ink-100 pt-2 text-2xs dark:border-ink-900">
     {externalHref && (
       <a
         href={externalHref}
@@ -333,7 +321,7 @@ const category = (item as { category?: string }).category;
         data-event="external_repo_click"
         data-event-source="card_view_repo"
         data-event-item={slug}
-        class="relative z-10 inline-flex items-center gap-1 font-medium text-ink-700 transition-colors hover:text-ink-900 dark:text-ink-300 dark:hover:text-ink-100"
+        class="inline-flex items-center gap-1 font-medium text-ink-700 transition-colors hover:text-ink-900 dark:text-ink-300 dark:hover:text-ink-100"
       >
         {repoHref ? "View repo" : "Visit source"}
         <svg viewBox="0 0 16 16" width="10" height="10" aria-hidden="true" fill="currentColor">
@@ -344,7 +332,7 @@ const category = (item as { category?: string }).category;
     )}
     <a
       href={detailHref}
-      class="relative z-10 inline-flex items-center gap-1 font-medium text-ink-500 transition-colors hover:text-ink-900 dark:text-ink-400 dark:hover:text-ink-100"
+      class="inline-flex items-center gap-1 font-medium text-ink-500 transition-colors hover:text-ink-900 dark:text-ink-400 dark:hover:text-ink-100"
     >
       Details →
     </a>

package/src/components/RefinePanel.astro

@@ -99,7 +99,7 @@ const groups: RenderedFilterGroup[] = baseGroups
   }));
 ---
 
-<section class:list={["flex flex-wrap items-center gap-2", className]} role="toolbar" aria-label="Filter items">
+<div class:list={["flex flex-wrap items-center gap-2", className]} role="toolbar" aria-label="Filter items">
     {groups.map((group) => <FilterGroupMenu {...group} />)}
 
     {!hide.includes("sort") && (
@@ -113,7 +113,7 @@ const groups: RenderedFilterGroup[] = baseGroups
         </svg>
       </label>
     )}
-</section>
+</div>
 
 <script is:inline define:vars={{ pathPrefix }}>
   (() => {

package/src/components/SmartLensTabs.astro

@@ -24,6 +24,8 @@ interface Props {
   class?: string;
   /** Override the visible lens list (defaults to LENSES). */
   lensIds?: string[];
+  /** Consumer noun for the unfiltered lens, e.g. "All apps". */
+  allLabel?: string;
 }
 
 const {
@@ -31,6 +33,7 @@ const {
   pathPrefix = "/",
   class: className = "",
   lensIds,
+  allLabel,
 } = Astro.props;
 
 // If `lensIds` is provided, filter LENSES to those ids in that order.
@@ -65,7 +68,7 @@ const lenses =
         data-event="lens_tab_click"
         data-event-source="smart_lens_tabs"
       >
-        {lensDisplay(lens.id)}
+        {lens.id === "all" && allLabel ? allLabel : lensDisplay(lens.id)}
       </a>
     );
   })}

package/src/layouts/BaseLayout.astro

@@ -11,8 +11,8 @@
  * own config (typically `data/generated/site-config.json` for the
  * showcase).
  *
- * Optional `gaId` adds a GA4 measurement snippet. Omit for
- * privacy-first deployments.
+ * GA4 can be configured once through `site.analytics.googleAnalyticsId`
+ * or overridden per page with `gaId`. Omit both for privacy-first deployments.
  */
 import "../styles.css";
 import Header from "./Header.astro";
@@ -61,6 +61,9 @@ interface Site {
   };
   repoUrl?: string;
   url?: string;
+  analytics?: {
+    googleAnalyticsId?: string;
+  };
   /** Optional directory-level stats — populated from site-config.json
    * at generate time. Components use it to render hero counts,
    * origin card stats, and footer summary lines. */
@@ -103,6 +106,7 @@ const {
 } = Astro.props;
 const directoryPath =
   searchPath ?? `/${site.blueprintConfig?.routeSlug ?? "items"}`;
+const effectiveGaId = gaId ?? site.analytics?.googleAnalyticsId;
 
 const favicon =
   "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Crect width='16' height='16' rx='3' fill='%2318181b'/%3E%3C/svg%3E";
@@ -130,14 +134,14 @@ const favicon =
       title="LLM usage guidance"
     />
 
-    {gaId && (
+    {effectiveGaId && (
       <>
         <script
           is:inline
           async
-          src={`https://www.googletagmanager.com/gtag/js?id=${gaId}`}
+          src={`https://www.googletagmanager.com/gtag/js?id=${effectiveGaId}`}
         />
-        <script is:inline define:vars={{ gaId }}>
+        <script is:inline define:vars={{ gaId: effectiveGaId }}>
           window.dataLayer = window.dataLayer || [];
           function gtag() {
             dataLayer.push(arguments);
@@ -290,8 +294,8 @@ const favicon =
 
     <slot name="body-end" />
 
-    {gaId && (
-      <script is:inline define:vars={{ gaId }}>
+    {effectiveGaId && (
+      <script is:inline define:vars={{ gaId: effectiveGaId }}>
         (function () {
           // GA4's `gtag('config', id)` call in the <head> already auto-pings
           // `page_view` on full navigations, so this block only needs to

package/src/layouts/Footer.astro

@@ -170,9 +170,9 @@ const resolvedLicenseLine = licenseLine ?? site.footer?.license;
 
     {columns.map((column) => (
       <div>
-        <h4 class="mb-3 text-2xs font-semibold uppercase tracking-wider text-ink-900 dark:text-ink-100">
+        <h2 class="mb-3 text-2xs font-semibold uppercase tracking-wider text-ink-900 dark:text-ink-100">
           {column.heading}
-        </h4>
+        </h2>
         <ul class="m-0 flex list-none flex-col gap-2 p-0">
           {column.items.map((item) => (
             <li>

package/src/lib/index.ts

@@ -24,3 +24,4 @@ export * from "./search.js";
 export * from "./scores.js";
 export * from "./taxonomy-counts.js";
 export * from "./display.js";
+export * from "./load-collections.js";

package/src/lib/load-collections.ts

@@ -0,0 +1,33 @@
+import { readFile, readdir } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { parse as parseYaml } from "yaml";
+import type { Collection } from "@grove-dev/core";
+
+/**
+ * Load all `Collection` YAML files from `<cwd>/data/collections/*.yml`.
+ *
+ * Returns an empty array if the directory does not exist, so callers can
+ * safely render an empty/loading state without having to guard each
+ * invocation site. Parse errors and other unexpected failures are NOT
+ * swallowed — they surface so real problems (malformed YAML, permission
+ * errors, etc.) are visible instead of silently producing empty output.
+ */
+export async function loadCollections(cwd: string): Promise<Collection[]> {
+  const dir = resolve(cwd, "data/collections");
+  let files: string[];
+  try {
+    files = await readdir(dir);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw err;
+  }
+  const out: Collection[] = [];
+  for (const f of files.filter((f) => f.endsWith(".yml"))) {
+    const raw = parseYaml(await readFile(join(dir, f), "utf8"));
+    if (!raw || typeof raw !== "object") {
+      throw new Error(`Invalid collection YAML: ${f}`);
+    }
+    out.push(raw as Collection);
+  }
+  return out;
+}

package/src/server/collections.test.ts

@@ -0,0 +1,190 @@
+import { describe, expect, it } from "vitest";
+import {
+  recordsToCollectionEntries,
+  getCollectionPageModel,
+  getCollectionIndexModel,
+  getCollectionTeaserModel,
+} from "./collections.js";
+import type { Collection, CollectionEntry } from "@grove-dev/core";
+
+describe("recordsToCollectionEntries", () => {
+  it("maps a full record to a CollectionEntry", () => {
+    const records = [
+      {
+        slug: "crewai",
+        name: "CrewAI",
+        description: "Agent framework",
+        stack: "python",
+        stacks: ["python"],
+        platforms: ["linux", "macos"],
+        license: "MIT",
+        visibility: "keep",
+        stars: 100,
+        pushedAt: "2026-01-15T00:00:00Z",
+        lastCommitAt: "2026-02-01T00:00:00Z",
+        category: "agents",
+        tags: ["multi-agent", "automation"],
+        scores: { curation: 0.8, activity: 0.7 },
+      },
+    ];
+    const entries = recordsToCollectionEntries(records as never, { routeSlug: "projects" });
+    expect(entries).toHaveLength(1);
+    expect(entries[0]).toMatchObject({
+      slug: "crewai",
+      title: "CrewAI",
+      description: "Agent framework",
+      url: "/projects/crewai/",
+      stack: "python",
+      platform: ["linux", "macos"],
+      license: "MIT",
+      status: "keep",
+      stars: 100,
+      pushedAt: "2026-01-15T00:00:00Z",
+      curationScore: 0.8,
+      activityScore: 0.7,
+      categories: expect.arrayContaining(["agents", "multi-agent", "automation"]),
+    });
+  });
+
+  it("filters out hidden records", () => {
+    const records = [
+      { slug: "a", name: "A", visibility: "keep" },
+      { slug: "b", name: "B", visibility: "hide" },
+    ];
+    const entries = recordsToCollectionEntries(records as never, { routeSlug: "projects" });
+    expect(entries.map((e) => e.slug)).toEqual(["a"]);
+  });
+
+  it("falls back to stacks[0] when stack is missing", () => {
+    const records = [{ slug: "x", name: "X", stacks: ["node"] }];
+    const entries = recordsToCollectionEntries(records as never, { routeSlug: "projects" });
+    expect(entries[0].stack).toBe("node");
+  });
+
+  it("prefers lastCommitAt when pushedAt is missing", () => {
+    const records = [{ slug: "x", name: "X", lastCommitAt: "2026-03-01T00:00:00Z" }];
+    const entries = recordsToCollectionEntries(records as never, { routeSlug: "projects" });
+    expect(entries[0].pushedAt).toBe("2026-03-01T00:00:00Z");
+  });
+
+  it("deduplicates categories when category is also in tags", () => {
+    const records = [{ slug: "x", name: "X", category: "agents", tags: ["agents", "x"] }];
+    const entries = recordsToCollectionEntries(records as never, { routeSlug: "projects" });
+    expect(entries[0].categories).toEqual(["agents", "x"]);
+  });
+
+  it("defaults routeSlug to 'projects' when not provided", () => {
+    const records = [{ slug: "x", name: "X" }];
+    const entries = recordsToCollectionEntries(records as never, {});
+    expect(entries[0].url).toBe("/projects/x/");
+  });
+});
+
+const collection: Collection = {
+  slug: "top-ai-agents",
+  kind: "curated",
+  title: "Top AI Agents",
+  description: "Best agent frameworks.",
+  query: { stacks: ["python"] },
+  ranking: { preset: "quality" },
+  seo: { index: true },
+  editorial: { selectionNote: "Ranked by activity and curation." },
+};
+
+const otherCollection: Collection = {
+  slug: "top-tools",
+  kind: "curated",
+  title: "Top Tools",
+  description: "All tools.",
+  query: { stacks: ["python"] },
+  ranking: { preset: "recency" },
+  seo: { index: true },
+};
+
+const emptyCollection: Collection = {
+  slug: "no-matches",
+  kind: "curated",
+  title: "No Matches",
+  description: "Won't match anything.",
+  query: { stacks: ["rust"] },
+  ranking: { preset: "recency" },
+  seo: { index: true },
+};
+
+const entries: CollectionEntry[] = [
+  {
+    slug: "crewai",
+    title: "CrewAI",
+    description: "Agent framework",
+    url: "/projects/crewai/",
+    stack: "python",
+    curationScore: 0.9,
+    activityScore: 0.8,
+  },
+  {
+    slug: "dify",
+    title: "Dify",
+    description: "LLM platform",
+    url: "/projects/dify/",
+    stack: "python",
+    curationScore: 0.7,
+    activityScore: 0.6,
+  },
+  {
+    slug: "flowise",
+    title: "Flowise",
+    description: "Node tool",
+    url: "/projects/flowise/",
+    stack: "node",
+    curationScore: 0.5,
+    activityScore: 0.4,
+  },
+];
+
+describe("getCollectionPageModel", () => {
+  it("returns ranked entries filtered by query", () => {
+    const model = getCollectionPageModel(collection, entries, [collection, otherCollection]);
+    expect(model.total).toBe(2);
+    expect(model.isEmpty).toBe(false);
+    expect(model.entries.map((e) => e.slug)).toEqual(["crewai", "dify"]);
+  });
+
+  it("exposes editorial selection note", () => {
+    const model = getCollectionPageModel(collection, entries, [collection]);
+    expect(model.collection.selectionNote).toBe("Ranked by activity and curation.");
+  });
+
+  it("returns related collections (max 4)", () => {
+    const model = getCollectionPageModel(collection, entries, [collection, otherCollection]);
+    expect(model.related).toHaveLength(1);
+    expect(model.related[0].slug).toBe("top-tools");
+  });
+
+  it("reports empty when no entries match", () => {
+    const model = getCollectionPageModel(emptyCollection, entries, [collection, otherCollection]);
+    expect(model.isEmpty).toBe(true);
+  });
+});
+
+describe("getCollectionIndexModel", () => {
+  it("counts entries per collection", () => {
+    const model = getCollectionIndexModel([collection, otherCollection], entries);
+    expect(model.total).toBe(2);
+    expect(model.collections).toHaveLength(2);
+    const agentCol = model.collections.find((c) => c.slug === "top-ai-agents");
+    expect(agentCol?.count).toBe(2);
+    expect(agentCol?.url).toBe("/collections/top-ai-agents/");
+  });
+});
+
+describe("getCollectionTeaserModel", () => {
+  it("respects the limit", () => {
+    const model = getCollectionTeaserModel([collection, otherCollection], entries, 1);
+    expect(model.collections).toHaveLength(1);
+  });
+
+  it("uses the project's route slug for entry URLs", () => {
+    const model = getCollectionTeaserModel([collection], entries, 5);
+    expect(model.collections[0].count).toBe(2);
+  });
+});

package/src/server/collections.ts

@@ -0,0 +1,197 @@
+import type { Collection, CollectionEntry } from "@grove-dev/core";
+import { findRelated, runCollection } from "@grove-dev/core";
+import { readFile, readdir } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { parse as parseYaml } from "yaml";
+
+interface RouteHint {
+  routeSlug?: string;
+  blueprintConfig?: { routeSlug?: string };
+}
+
+interface RawRecord {
+  slug?: string;
+  name?: string;
+  title?: string;
+  description?: string;
+  stack?: string;
+  stacks?: string[];
+  platforms?: string[];
+  license?: string;
+  visibility?: string;
+  stars?: number;
+  pushedAt?: string;
+  lastCommitAt?: string;
+  category?: string;
+  tags?: string[];
+  scores?: { curation?: number; activity?: number };
+}
+
+/**
+ * Map a list of full records (shape produced by `records.json`) to
+ * the lightweight `CollectionEntry` shape consumed by `runCollection`.
+ *
+ * - Skips records with `visibility === "hide"` — they should never
+ *   appear in any collection.
+ * - Combines `category` and `tags` into a `categories` array (deduplicated).
+ * - Falls back to `stacks[0]` when `stack` is missing.
+ * - Prefers `pushedAt`; falls back to `lastCommitAt`.
+ * - Constructs `url` as `${routeSlug}/${slug}/` so the value points
+ *   back to the consumer's detail page.
+ */
+export function recordsToCollectionEntries(
+  records: RawRecord[],
+  site: RouteHint,
+): CollectionEntry[] {
+  const routeSlug = site.routeSlug ?? site.blueprintConfig?.routeSlug ?? "projects";
+  const out: CollectionEntry[] = [];
+  for (const r of records) {
+    if (r.visibility === "hide") continue;
+    if (!r.slug) continue;
+    const categories = [
+      ...(r.category ? [r.category] : []),
+      ...(r.tags ?? []),
+    ].filter((value, index, self) => self.indexOf(value) === index);
+    out.push({
+      slug: r.slug,
+      title: r.name ?? r.title ?? r.slug,
+      description: r.description ?? "",
+      url: `/${routeSlug}/${r.slug}/`,
+      stack: r.stack ?? r.stacks?.[0],
+      platform: r.platforms,
+      license: r.license,
+      status: r.visibility,
+      stars: r.stars,
+      pushedAt: r.pushedAt ?? r.lastCommitAt,
+      curationScore: r.scores?.curation,
+      activityScore: r.scores?.activity,
+      categories: categories.length > 0 ? categories : undefined,
+    });
+  }
+  return out;
+}
+
+// ── Collection view-models ──────────────────────────────────────
+//
+// A Collection is a curated or generated grouping of records
+// (see `@grove-dev/core`'s `runCollection` engine). These view-models
+// produce the input the `CollectionPage`, `CollectionIndex`, and
+// `CollectionTeaser` components consume.
+
+export interface CollectionPageModel {
+  collection: {
+    slug: string;
+    title: string;
+    description: string;
+    kind: "curated" | "generated";
+    selectionNote?: string;
+    introduction?: string;
+  };
+  total: number;
+  isEmpty: boolean;
+  entries: CollectionEntry[];
+  related: Array<{ slug: string; title: string; url: string }>;
+}
+
+export interface CollectionIndexModel {
+  total: number;
+  collections: Array<{
+    slug: string;
+    title: string;
+    description: string;
+    kind: "curated" | "generated";
+    count: number;
+    url: string;
+  }>;
+}
+
+export interface CollectionTeaserModel {
+  total: number;
+  collections: CollectionIndexModel["collections"];
+}
+
+export function getCollectionPageModel(
+  collection: Collection,
+  entries: CollectionEntry[],
+  allCollections: Collection[],
+): CollectionPageModel {
+  const result = runCollection(collection, entries);
+  const related = findRelated(collection, allCollections, 4).map((c) => ({
+    slug: c.slug,
+    title: c.title,
+    url: `/collections/${c.slug}/`,
+  }));
+  return {
+    collection: {
+      slug: collection.slug,
+      title: collection.title,
+      description: collection.description,
+      kind: collection.kind,
+      selectionNote: collection.editorial?.selectionNote,
+      introduction: collection.editorial?.introduction,
+    },
+    total: result.entries.length,
+    isEmpty: result.isEmpty,
+    entries: result.entries,
+    related,
+  };
+}
+
+export function getCollectionIndexModel(
+  collections: Collection[],
+  entries: CollectionEntry[],
+): CollectionIndexModel {
+  return {
+    total: collections.length,
+    collections: collections.map((c) => {
+      const result = runCollection(c, entries);
+      return {
+        slug: c.slug,
+        title: c.title,
+        description: c.description,
+        kind: c.kind,
+        count: result.entries.length,
+        url: `/collections/${c.slug}/`,
+      };
+    }),
+  };
+}
+
+export function getCollectionTeaserModel(
+  collections: Collection[],
+  entries: CollectionEntry[],
+  limit = 3,
+): CollectionTeaserModel {
+  const full = getCollectionIndexModel(collections, entries);
+  return {
+    total: full.total,
+    collections: full.collections.slice(0, limit),
+  };
+}
+
+/**
+ * Load all `Collection` YAML files from `<cwd>/data/collections/*.yml`.
+ *
+ * Returns an empty array if the directory does not exist. Parse
+ * errors are NOT swallowed — they surface so real problems
+ * (malformed YAML, permission errors) are not hidden.
+ */
+export async function loadCollections(cwd: string): Promise<Collection[]> {
+  const dir = resolve(cwd, "data/collections");
+  let files: string[];
+  try {
+    files = await readdir(dir);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw err;
+  }
+  const out: Collection[] = [];
+  for (const f of files.filter((f) => f.endsWith(".yml"))) {
+    const raw = parseYaml(await readFile(join(dir, f), "utf8"));
+    if (!raw || typeof raw !== "object") {
+      throw new Error(`Invalid collection YAML: ${f}`);
+    }
+    out.push(raw as Collection);
+  }
+  return out;
+}

package/src/server/index.ts

@@ -1,2 +1,3 @@
 export * from "./directory.js";
 export * from "./models.js";
+export * from "./collections.js";