stack-site-builder 1.10.0

package/src/lib/assets.ts

@@ -0,0 +1,19 @@
+/**
+ * Helpers for the `logo` / `logoDark` frontmatter fields, which accept an
+ * absolute URL, a /public path, or an emoji/text glyph (e.g. "🚅").
+ */
+
+/** True when `ref` is an image reference — an absolute URL or a /public path —
+ *  rather than an emoji/text glyph. */
+export function isImageRef(ref?: string): ref is string {
+  return !!ref && (/^https?:\/\//.test(ref) || ref.startsWith('/'));
+}
+
+/** Resolve an image reference to a browser-usable URL: absolute URLs pass
+ *  through; /public paths get the deploy base (a GitHub project-page subpath)
+ *  prefixed. Call only with image refs — an emoji would resolve to nonsense. */
+export function resolveImageUrl(ref?: string): string | undefined {
+  if (!ref) return undefined;
+  if (/^https?:\/\//.test(ref)) return ref;
+  return import.meta.env.BASE_URL.replace(/\/$/, '') + '/' + ref.replace(/^\//, '');
+}

package/src/lib/category-tree.ts

@@ -0,0 +1,64 @@
+import type { Lang } from 'stack-site-builder/i18n/ui';
+
+/**
+ * A category node, nestable into subcategories to any depth. Reused for several
+ * taxonomies (tools, concepts, articles): each builds its own tree of these and
+ * runs it through `buildTree` for the lookup helpers. `id` must be unique within
+ * its own tree (it keys the category URL and the content's `category` field).
+ */
+export interface Category {
+  id: string;
+  label: Record<Lang, string>;
+  /** Short one-liner for cards / section headers / subcategory summaries. */
+  description: Record<Lang, string>;
+  /** Longer blurb for the category's own page (falls back to `description`). */
+  detail?: Record<Lang, string>;
+  children?: Category[];
+}
+
+export interface CategoryTree {
+  roots: Category[];
+  map: Map<string, Category>;
+  allIds: string[];
+  /** Root → node chain for an id (its breadcrumb path). Empty if unknown. */
+  pathOf(id: string): Category[];
+  /** Direct children of a node (empty for leaves). */
+  childrenOf(id: string): Category[];
+  /** A node's id plus all descendant ids (for subtree roll-up). */
+  descendantIds(id: string): string[];
+}
+
+/** Index a category tree into id/parent maps + path/children/descendant helpers. */
+export function buildTree(roots: Category[]): CategoryTree {
+  const map = new Map<string, Category>();
+  const parentOf = new Map<string, string | null>();
+  (function index(nodes: Category[], parent: string | null) {
+    for (const c of nodes) {
+      map.set(c.id, c);
+      parentOf.set(c.id, parent);
+      if (c.children) index(c.children, c.id);
+    }
+  })(roots, null);
+
+  const pathOf = (id: string): Category[] => {
+    const out: Category[] = [];
+    let cur: string | null = id;
+    while (cur) {
+      const c = map.get(cur);
+      if (!c) break;
+      out.unshift(c);
+      cur = parentOf.get(cur) ?? null;
+    }
+    return out;
+  };
+  const childrenOf = (id: string): Category[] => map.get(id)?.children ?? [];
+  const descendantIds = (id: string): string[] => {
+    const node = map.get(id);
+    if (!node) return [id];
+    const out = [id];
+    for (const child of node.children ?? []) out.push(...descendantIds(child.id));
+    return out;
+  };
+
+  return { roots, map, allIds: [...map.keys()], pathOf, childrenOf, descendantIds };
+}

package/src/lib/concepts.ts

@@ -0,0 +1,35 @@
+import { getCollection, type CollectionEntry } from 'astro:content';
+import type { Lang } from '../i18n/ui';
+
+export type ConceptEntry = CollectionEntry<'concepts'>;
+
+/** The url slug of a concept, i.e. its id with the `<lang>/` prefix removed. */
+export function conceptSlugOf(entry: ConceptEntry): string {
+  return entry.id.replace(/^[a-z]{2}\//, '');
+}
+
+/** Published concepts for one locale, by `order` then title. */
+export async function getConcepts(lang: Lang): Promise<ConceptEntry[]> {
+  const all = await getCollection('concepts');
+  return all
+    .filter((e) => e.id.startsWith(`${lang}/`) && !e.data.draft)
+    .sort(
+      (a, b) =>
+        (a.data.order ?? 999) - (b.data.order ?? 999) ||
+        a.data.title.localeCompare(b.data.title),
+    );
+}
+
+/** Every tool slug a concept references, flattened across its role groups. */
+export function conceptToolSlugs(entry: ConceptEntry): string[] {
+  return entry.data.tools.flatMap((g) => g.tools);
+}
+
+/**
+ * Backlinks: concepts in a locale that use `toolSlug` (in any role group), so a
+ * tool's detail page can list the patterns it appears in.
+ */
+export async function getConceptsForTool(lang: Lang, toolSlug: string): Promise<ConceptEntry[]> {
+  const concepts = await getConcepts(lang);
+  return concepts.filter((c) => conceptToolSlugs(c).includes(toolSlug));
+}

package/src/lib/dates.ts

@@ -0,0 +1,21 @@
+import type { Lang } from '../i18n/ui';
+
+/**
+ * Human-facing date in the reader's locale (e.g. "June 28, 2026" / "2026년 6월
+ * 28일"). Use UTC so a YYYY-MM-DD in frontmatter renders as that exact calendar
+ * day regardless of the build machine's timezone. Pair with an ISO `datetime`
+ * attribute on the surrounding `<time>` for machines.
+ */
+export function formatDate(d: Date, lang: Lang): string {
+  return new Intl.DateTimeFormat(lang === 'ko' ? 'ko-KR' : 'en-US', {
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric',
+    timeZone: 'UTC',
+  }).format(d);
+}
+
+/** ISO YYYY-MM-DD, for `datetime` attributes. */
+export function isoDate(d: Date): string {
+  return d.toISOString().slice(0, 10);
+}

package/src/lib/facets.ts

@@ -0,0 +1,57 @@
+import { pricingTags } from './pricing';
+import { pricingLabels, licenseLabel, useTranslations, type Lang } from '../i18n/ui';
+import type { StackEntry } from './stacks';
+
+export interface FacetOption {
+  value: string;
+  label: string;
+}
+export interface Facet {
+  key: string;
+  label: string;
+  options: FacetOption[];
+}
+
+/**
+ * Filter facet options (pricing / license / language), derived from a locale's
+ * stack entries. Shared by the homepage and the category pages — both feed it
+ * the WHOLE catalog so the controls are identical everywhere and a sort/filter
+ * carried in from another page can always be restored.
+ */
+export function deriveFacets(entries: StackEntry[], lang: Lang): Facet[] {
+  const t = useTranslations(lang);
+
+  const pricingOrder = ['completely-free', 'open-source', 'free-tier', 'paid', 'free'];
+  const usedPricing = new Set<string>(entries.flatMap((e) => pricingTags(e.data.pricing)));
+
+  const langSet = new Set(
+    entries.flatMap((e) =>
+      (e.data.language ?? '')
+        .split('/')
+        .map((s) => s.trim())
+        .filter(Boolean),
+    ),
+  );
+
+  return [
+    {
+      key: 'pricing',
+      label: t('detail.pricing'),
+      options: pricingOrder
+        .filter((p) => usedPricing.has(p))
+        .map((p) => ({ value: p, label: pricingLabels[lang][p] ?? p })),
+    },
+    {
+      key: 'license',
+      label: t('detail.license'),
+      options: [...new Set(entries.map((e) => e.data.license).filter(Boolean))]
+        .sort()
+        .map((l) => ({ value: l as string, label: licenseLabel(lang, l as string) })),
+    },
+    {
+      key: 'language',
+      label: t('detail.language'),
+      options: [...langSet].sort().map((l) => ({ value: l, label: l })),
+    },
+  ];
+}

package/src/lib/github.ts

@@ -0,0 +1,186 @@
+import { site } from '@aas-data/site';
+/**
+ * Build-time GitHub stats. Given a repo URL, fetch star count and the latest
+ * release/tag from the GitHub API so cards/detail reflect the project's real
+ * state as of the last build — no manual entry.
+ *
+ * Results are memoized per repo for the process, so the same repo is fetched
+ * once even though it appears across locales and on both card + detail. Any
+ * failure (offline, rate limit, no repo) degrades gracefully to `null`.
+ *
+ * In CI, set GITHUB_TOKEN to lift the unauthenticated 60 req/hour limit.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+
+export interface RepoStats {
+  stars: number;
+  version?: string;
+  releasedAt?: string; // ISO date of the latest release (YYYY-MM-DD usable via slice)
+}
+
+const cache = new Map<string, Promise<RepoStats | null>>();
+
+// On-disk cache so values survive rate-limited builds and so we only hit the
+// API ~once a day per repo. A fresh entry (< TTL) is used as-is without
+// fetching; a stale entry is refreshed but kept as a fallback on failure.
+type CachedStats = RepoStats & { fetchedAt: number };
+const ONE_DAY = 24 * 60 * 60 * 1000;
+const CACHE_DIR = '.aas-cache';
+const CACHE_FILE = `${CACHE_DIR}/github.json`;
+let disk: Record<string, CachedStats> = {};
+try {
+  disk = JSON.parse(readFileSync(CACHE_FILE, 'utf8'));
+} catch {
+  /* no cache yet */
+}
+function strip(c: CachedStats): RepoStats {
+  return { stars: c.stars, version: c.version, releasedAt: c.releasedAt };
+}
+function persist() {
+  try {
+    if (!existsSync(CACHE_DIR)) mkdirSync(CACHE_DIR, { recursive: true });
+    writeFileSync(CACHE_FILE, JSON.stringify(disk));
+  } catch {
+    /* read-only fs — skip */
+  }
+}
+
+function parseRepo(url?: string): { owner: string; repo: string } | null {
+  if (!url) return null;
+  const m = url.match(/github\.com\/([^/]+)\/([^/#?]+)/i);
+  if (!m) return null;
+  return { owner: m[1], repo: m[2].replace(/\.git$/, '') };
+}
+
+function headers(): Record<string, string> {
+  const h: Record<string, string> = {
+    Accept: 'application/vnd.github+json',
+    'User-Agent': site.buildUserAgent,
+  };
+  const token = process.env.GITHUB_TOKEN;
+  if (token) h.Authorization = `Bearer ${token}`;
+  return h;
+}
+
+/** Normalize a tag like "0.2.1" or "v0.2.1" to a displayed "v0.2.1". */
+function normalizeVersion(tag?: string): string | undefined {
+  if (!tag) return undefined;
+  const t = tag.trim();
+  return /^v\d/i.test(t) ? t : /^\d/.test(t) ? `v${t}` : t;
+}
+
+type FetchedStats = RepoStats & {
+  // False when the release/tag lookups errored (rate limit, network) — the
+  // version fields are then *unknown*, not known-absent, and must not
+  // overwrite a previously cached version.
+  versionResolved: boolean;
+};
+
+async function fetchStats(owner: string, repo: string): Promise<FetchedStats | null> {
+  try {
+    const res = await fetch(`https://api.github.com/repos/${owner}/${repo}`, { headers: headers() });
+    if (!res.ok) return null;
+    const data = (await res.json()) as { stargazers_count?: number };
+    const stars = typeof data.stargazers_count === 'number' ? data.stargazers_count : 0;
+
+    let version: string | undefined;
+    let releasedAt: string | undefined;
+    let versionResolved = false;
+    const rel = await fetch(`https://api.github.com/repos/${owner}/${repo}/releases/latest`, {
+      headers: headers(),
+    });
+    if (rel.ok) {
+      const data = await rel.json();
+      version = normalizeVersion(data.tag_name);
+      releasedAt = data.published_at; // e.g. "2026-05-12T09:00:00Z"
+      versionResolved = true;
+    } else if (rel.status === 404) {
+      // 404 = the repo genuinely has no releases — fall back to the most
+      // recent tag. Anything else (403 rate limit, 5xx) means we don't know,
+      // so skip the fallback and leave versionResolved false.
+      // Tags carry no date, so fetch the commit they point to for the date.
+      const tags = await fetch(`https://api.github.com/repos/${owner}/${repo}/tags?per_page=1`, {
+        headers: headers(),
+      });
+      if (tags.ok) {
+        versionResolved = true;
+        const tag = (await tags.json())[0];
+        version = normalizeVersion(tag?.name);
+        if (tag?.commit?.url) {
+          const commit = await fetch(tag.commit.url, { headers: headers() });
+          if (commit.ok) {
+            const c = await commit.json();
+            releasedAt = c.commit?.committer?.date ?? c.commit?.author?.date;
+          }
+        }
+      }
+    }
+    return { stars, version, releasedAt, versionResolved };
+  } catch {
+    return null;
+  }
+}
+
+export function getRepoStats(repoUrl?: string): Promise<RepoStats | null> {
+  const slug = parseRepo(repoUrl);
+  if (!slug) return Promise.resolve(null);
+  const key = `${slug.owner}/${slug.repo}`;
+  if (!cache.has(key)) {
+    const cached = disk[key];
+    if (cached && Date.now() - cached.fetchedAt < ONE_DAY) {
+      // Fresh enough — use the cache, skip the network (refreshes ~daily).
+      cache.set(key, Promise.resolve(strip(cached)));
+    } else {
+      cache.set(
+        key,
+        fetchStats(slug.owner, slug.repo).then((stats) => {
+          if (stats) {
+            const { versionResolved, ...fresh } = stats;
+            if (!versionResolved && cached?.version) {
+              // Partial refresh (stars OK, release lookup rate-limited):
+              // keep the last known release info instead of clobbering it.
+              fresh.version = cached.version;
+              fresh.releasedAt = cached.releasedAt;
+            }
+            disk[key] = { ...fresh, fetchedAt: Date.now() };
+            persist();
+            return fresh;
+          }
+          return cached ? strip(cached) : null; // rate-limited/offline → last known
+        }),
+      );
+    }
+  }
+  return cache.get(key)!;
+}
+
+const SIX_MONTHS = 182 * ONE_DAY;
+const ONE_YEAR = 365 * ONE_DAY;
+
+/** How long since a project's last release: fresh, aging (6m+), or stale (1y+). */
+export type Staleness = 'fresh' | 'aging' | 'stale';
+
+/**
+ * Tier the given date by age — a "no recent updates" signal. Fed the latest
+ * release/tag date (the same date shown in the UI), so the warning is
+ * consistent with what users see: `stale` past a year (stronger), `aging` past
+ * six months (milder). Unknown or unparseable dates are treated as fresh.
+ */
+export function stalenessOf(date?: string): Staleness {
+  if (!date) return 'fresh';
+  const t = Date.parse(date);
+  if (Number.isNaN(t)) return 'fresh';
+  const age = Date.now() - t;
+  if (age > ONE_YEAR) return 'stale';
+  if (age > SIX_MONTHS) return 'aging';
+  return 'fresh';
+}
+
+/** Compact star count, one decimal: 1234 → "1.2k", 35456 → "35.5k",
+ *  1200000 → "1.2M". The k→M cutover sits where k would round to "1000.0k". */
+export function formatStars(n: number): string {
+  if (n < 1000) return String(n);
+  const k = n / 1000;
+  if (k < 999.95) return k.toFixed(1) + 'k';
+  return (n / 1_000_000).toFixed(1) + 'M';
+}

package/src/lib/inline-md.ts

@@ -0,0 +1,30 @@
+/**
+ * Render a *tiny* inline-Markdown subset to safe HTML, for short strings shown
+ * outside the Markdown pipeline — frontmatter `description` fields in detail
+ * headers and cards. Supports `` `code` ``, `**bold**`, and `*italic*` only;
+ * everything else (including any HTML in the source) is escaped.
+ *
+ * Keep `<meta>`/OG tags on the raw string — those must stay plain text.
+ */
+const ESCAPE: Record<string, string> = { '&': '&amp;', '<': '&lt;', '>': '&gt;' };
+const OPEN = '';
+const CLOSE = '';
+
+function escapeHtml(s: string): string {
+  return s.replace(/[&<>]/g, (c) => ESCAPE[c]);
+}
+
+export function inlineMd(input: string): string {
+  // Pull inline code out first — escape it and shield it from bold/italic with
+  // private-use sentinels that can't occur in prose.
+  const codes: string[] = [];
+  let s = input.replace(/`([^`]+)`/g, (_, code) => {
+    codes.push(`<code>${escapeHtml(code)}</code>`);
+    return `${OPEN}${codes.length - 1}${CLOSE}`;
+  });
+  s = escapeHtml(s);
+  // Bold before italic so `**` isn't consumed by the single-`*` rule.
+  s = s.replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>');
+  s = s.replace(/(?<!\*)\*(?!\s)([^*]+?)(?<!\s)\*(?!\*)/g, '<em>$1</em>');
+  return s.replace(new RegExp(`${OPEN}(\\d+)${CLOSE}`, 'g'), (_, i) => codes[Number(i)]);
+}

package/src/lib/pricing.ts

@@ -0,0 +1,22 @@
+/**
+ * Pricing tags. The stored `pricing` values are open-source / free-tier / paid /
+ * free; on top of those we derive a synthetic "completely free" tag for tools
+ * that cost nothing at all — open source with no paid or hosted free-tier
+ * gating, or the standalone `free` (non-OSS) marker.
+ */
+export const COMPLETELY_FREE = 'completely-free';
+
+/** True when a tool is free to use outright, with no paid option. */
+export function isCompletelyFree(pricing: string[]): boolean {
+  if (pricing.includes('free')) return true;
+  return (
+    pricing.includes('open-source') &&
+    !pricing.includes('paid') &&
+    !pricing.includes('free-tier')
+  );
+}
+
+/** Display/filter tokens for a tool: prepend the 완전 무료 tag when it applies. */
+export function pricingTags(pricing: string[]): string[] {
+  return isCompletelyFree(pricing) ? [COMPLETELY_FREE, ...pricing] : pricing;
+}