@dsbasko/cookbook-engine 0.1.0

package/src/lib/readme-toc.ts

@@ -0,0 +1,69 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import type { Course, Module, Lesson } from './course';
+import { type Lang } from './lang';
+
+export interface GenerateTocOptions {
+  /** Active language. EN tries to link to `i18n/en/README.md` and falls back to RU with a marker. */
+  lang: Lang;
+  /** Path prefix used in markdown link targets (relative to the README that will embed the TOC). Default: 'lectures'. */
+  linkPrefix?: string;
+  /** Filesystem root used to probe which translations exist. Default: same as linkPrefix. */
+  lecturesRoot?: string;
+}
+
+const RU_ONLY_MARKER = ' *(RU only)*';
+
+export function generateReadmeToc(course: Course, options: GenerateTocOptions): string {
+  const linkPrefix = options.linkPrefix ?? 'lectures';
+  const fsRoot = options.lecturesRoot ?? linkPrefix;
+  const sections = course.modules.map((mod) =>
+    renderModule(mod, options.lang, linkPrefix, fsRoot),
+  );
+  return sections.join('\n\n').replace(/\s+$/, '') + '\n';
+}
+
+function renderModule(mod: Module, lang: Lang, linkPrefix: string, fsRoot: string): string {
+  const moduleNumber = leadingNumber(mod.id);
+  const heading = `### ${moduleNumber} — ${mod.title}`;
+  const description = mod.description.trim();
+  const bullets = mod.lessons
+    .map((lesson) => renderLesson(mod.id, moduleNumber, lesson, lang, linkPrefix, fsRoot))
+    .join('\n');
+  return [heading, '', description, '', bullets].join('\n');
+}
+
+function renderLesson(
+  moduleId: string,
+  moduleNumber: string,
+  lesson: Lesson,
+  lang: Lang,
+  linkPrefix: string,
+  fsRoot: string,
+): string {
+  const enFile = path.join(fsRoot, moduleId, lesson.slug, 'i18n', 'en', 'README.md');
+  const hasEn = existsSync(enFile);
+  const targetLang: Lang = lang === 'en' && !hasEn ? 'ru' : lang;
+  const linkTarget = `${linkPrefix}/${moduleId}/${lesson.slug}/i18n/${targetLang}/README.md`;
+  const label = buildLessonLabel(moduleNumber, lesson);
+  const marker = lang === 'en' && !hasEn ? RU_ONLY_MARKER : '';
+  return `- [${label}](${linkTarget})${marker}`;
+}
+
+function buildLessonLabel(moduleNumber: string, lesson: Lesson): string {
+  const lessonNum = leadingLessonNumber(lesson.slug);
+  if (!lessonNum) return lesson.title;
+  return `${moduleNumber}-${lessonNum} — ${lesson.title}`;
+}
+
+function leadingNumber(id: string): string {
+  const m = id.match(/^(\d{2})/);
+  return m ? m[1] : id;
+}
+
+function leadingLessonNumber(slug: string): string | null {
+  const nested = slug.match(/^\d{2}-(\d{2})-/);
+  if (nested) return nested[1];
+  const flat = slug.match(/^(\d{2})-/);
+  return flat ? flat[1] : null;
+}

package/src/lib/site-url.ts

@@ -0,0 +1,33 @@
+const DEFAULT_SITE_URL = 'https://dsbasko.github.io';
+
+/**
+ * Returns the basePath that matches Next.js routing in the current runtime.
+ * In production (and any non-development NODE_ENV) this is the configured
+ * `course.basePath` (e.g. `/kafka-cookbook`). In dev `next.config.mjs`
+ * disables basePath, so internal links and assets must point at the root —
+ * otherwise rewritten markdown URLs 404 against the dev server.
+ */
+export function getRuntimeBasePath(coursePath: string): string {
+  return process.env.NODE_ENV === 'development' ? '' : coursePath;
+}
+
+export function getSiteUrl(): string {
+  const raw = process.env.NEXT_PUBLIC_SITE_URL;
+  const value = raw && raw.trim().length > 0 ? raw.trim() : DEFAULT_SITE_URL;
+  return value.replace(/\/+$/, '');
+}
+
+export function buildSiteUrl(basePath: string, segments: string[] = []): string {
+  const root = getSiteUrl();
+  const normalizedBase = basePath.replace(/\/+$/, '');
+  const path = segments.filter(Boolean).join('/');
+  const tail = path.length > 0 ? `/${path}/` : '/';
+  return `${root}${normalizedBase}${tail}`;
+}
+
+export function buildAssetUrl(basePath: string, asset: string): string {
+  const root = getSiteUrl();
+  const normalizedBase = basePath.replace(/\/+$/, '');
+  const normalizedAsset = asset.startsWith('/') ? asset : `/${asset}`;
+  return `${root}${normalizedBase}${normalizedAsset}`;
+}

package/src/lib/sitemap.ts

@@ -0,0 +1,112 @@
+import type { MetadataRoute } from 'next';
+import { flattenLessons, type Course } from './course';
+import { DEFAULT_LANG, LANGS } from './lang';
+import { buildSiteUrl } from './site-url';
+
+export interface BuildSitemapOptions {
+  now?: Date;
+}
+
+type SitemapEntry = MetadataRoute.Sitemap[number];
+type LanguageMap = NonNullable<NonNullable<SitemapEntry['alternates']>['languages']>;
+
+// `lesson.hasTranslation` must reflect the EN README (load the course via
+// `loadCourse('en')`). RU READMEs are guaranteed by the i18n migration, so
+// every RU URL is always emitted. Missing EN lesson pages still render with
+// noindex metadata — they just stay out of the sitemap.
+export function buildSitemap(
+  course: Course,
+  options: BuildSitemapOptions = {},
+): MetadataRoute.Sitemap {
+  const now = options.now ?? new Date();
+  const entries: MetadataRoute.Sitemap = [];
+
+  const homeLangs = buildLangMap(course.basePath, []);
+  for (const lang of LANGS) {
+    entries.push({
+      url: buildSiteUrl(course.basePath, [lang]),
+      lastModified: now,
+      changeFrequency: 'weekly',
+      priority: 1,
+      alternates: { languages: { ...homeLangs } },
+    });
+  }
+
+  for (const mod of course.modules) {
+    const moduleLangs = buildLangMap(course.basePath, [mod.id]);
+    for (const lang of LANGS) {
+      entries.push({
+        url: buildSiteUrl(course.basePath, [lang, mod.id]),
+        lastModified: now,
+        changeFrequency: 'monthly',
+        priority: 0.8,
+        alternates: { languages: { ...moduleLangs } },
+      });
+    }
+  }
+
+  for (const entry of flattenLessons(course)) {
+    const lessonLangs = buildLessonLangMap(
+      course.basePath,
+      entry.moduleId,
+      entry.lesson.slug,
+      entry.lesson.hasTranslation,
+    );
+    const ruUrl = buildSiteUrl(course.basePath, ['ru', entry.moduleId, entry.lesson.slug]);
+    const enUrl = buildSiteUrl(course.basePath, ['en', entry.moduleId, entry.lesson.slug]);
+
+    entries.push({
+      url: ruUrl,
+      lastModified: now,
+      changeFrequency: 'monthly',
+      priority: 0.6,
+      alternates: { languages: { ...lessonLangs } },
+    });
+
+    if (entry.lesson.hasTranslation) {
+      entries.push({
+        url: enUrl,
+        lastModified: now,
+        changeFrequency: 'monthly',
+        priority: 0.6,
+        alternates: { languages: { ...lessonLangs } },
+      });
+    }
+  }
+
+  return entries;
+}
+
+// Build the hreflang `languages` map for a "simple" route (home `/[lang]/`
+// or module `/[lang]/[module]/`) — both language URLs always exist there, so
+// `x-default` points at the DEFAULT_LANG variant.
+export function buildLangMap(basePath: string, tail: string[]): LanguageMap {
+  const map: LanguageMap = {};
+  for (const lang of LANGS) {
+    map[lang] = buildSiteUrl(basePath, [lang, ...tail]);
+  }
+  map['x-default'] = buildSiteUrl(basePath, [DEFAULT_LANG, ...tail]);
+  return map;
+}
+
+// Build the hreflang `languages` map for a lesson route. When EN README is
+// missing the EN page renders a noindex fallback (RU content + banner); we
+// match `buildSitemap`'s rule and omit it from `languages` so crawlers don't
+// see a non-reciprocal alternate.
+export function buildLessonLangMap(
+  basePath: string,
+  moduleId: string,
+  slug: string,
+  hasEn: boolean,
+): LanguageMap {
+  const ruUrl = buildSiteUrl(basePath, ['ru', moduleId, slug]);
+  const map: LanguageMap = { ru: ruUrl };
+  if (hasEn) {
+    const enUrl = buildSiteUrl(basePath, ['en', moduleId, slug]);
+    map.en = enUrl;
+    map['x-default'] = enUrl;
+  } else {
+    map['x-default'] = ruUrl;
+  }
+  return map;
+}

package/src/lib/slug.ts

@@ -0,0 +1,15 @@
+const SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+export function normalizeSlug(input: string): string {
+  return input
+    .trim()
+    .toLowerCase()
+    .replace(/[_\s]+/g, '-')
+    .replace(/[^a-z0-9-]/g, '')
+    .replace(/-+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+export function isValidSlug(input: string): boolean {
+  return typeof input === 'string' && input.length > 0 && SLUG_PATTERN.test(input);
+}

package/src/lib/theme.ts

@@ -0,0 +1,78 @@
+export type ThemePreference = 'light' | 'dark' | 'paper';
+export type ResolvedTheme = ThemePreference;
+
+export const THEME_STORAGE_KEY = 'kafka-cookbook-theme';
+export const THEME_PREFERENCES = ['light', 'paper', 'dark'] as const;
+
+export function isThemePreference(value: unknown): value is ThemePreference {
+  return value === 'light' || value === 'dark' || value === 'paper';
+}
+
+export function getSystemTheme(): 'light' | 'dark' {
+  if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') {
+    return 'light';
+  }
+  return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+}
+
+export function resolveTheme(preference: ThemePreference): ResolvedTheme {
+  return preference;
+}
+
+/**
+ * Returns the stored preference or — when nothing valid is stored —
+ * silently picks light/dark from `prefers-color-scheme`. This preserves the
+ * old "system" auto-detect for first-time visitors and for users migrating
+ * from previously-stored `'system'` without exposing it as a UI choice.
+ */
+export function readStoredPreference(): ThemePreference {
+  if (typeof window === 'undefined') return 'light';
+  try {
+    const raw = window.localStorage.getItem(THEME_STORAGE_KEY);
+    if (isThemePreference(raw)) return raw;
+    return getSystemTheme();
+  } catch {
+    return 'light';
+  }
+}
+
+export function writeStoredPreference(preference: ThemePreference): void {
+  if (typeof window === 'undefined') return;
+  try {
+    window.localStorage.setItem(THEME_STORAGE_KEY, preference);
+  } catch {
+    /* storage may be unavailable (private mode, quota); ignore. */
+  }
+}
+
+export function applyResolvedTheme(theme: ResolvedTheme): void {
+  if (typeof document === 'undefined') return;
+  document.documentElement.dataset.theme = theme;
+}
+
+export function applyPreference(preference: ThemePreference): ResolvedTheme {
+  const resolved = resolveTheme(preference);
+  applyResolvedTheme(resolved);
+  return resolved;
+}
+
+/**
+ * Inline script string injected into <head> before hydration.
+ * Reads stored preference (or system query) and sets `data-theme` on <html>
+ * synchronously, eliminating FOUC.
+ */
+export const THEME_INIT_SCRIPT = `(() => {
+  try {
+    var key = ${JSON.stringify(THEME_STORAGE_KEY)};
+    var stored = null;
+    try { stored = window.localStorage.getItem(key); } catch (_) {}
+    var resolved = (stored === 'light' || stored === 'dark' || stored === 'paper') ? stored : null;
+    if (!resolved) {
+      var mq = window.matchMedia('(prefers-color-scheme: dark)');
+      resolved = mq && mq.matches ? 'dark' : 'light';
+    }
+    document.documentElement.dataset.theme = resolved;
+  } catch (_) {
+    document.documentElement.dataset.theme = 'light';
+  }
+})();`;

package/src/lib/use-i18n.ts

@@ -0,0 +1,25 @@
+'use client';
+
+import { useParams } from 'next/navigation';
+import { DEFAULT_LANG, isLang, type Lang } from './lang';
+import { getDict, type UIDict } from './i18n';
+
+/**
+ * Reads the active language from the `[lang]` segment of the URL. Falls
+ * back to DEFAULT_LANG if the param is missing or invalid — happens on
+ * the root layout before the language-prefixed route mounts.
+ */
+export function useLang(): Lang {
+  const params = useParams();
+  const raw = params && (params as Record<string, string | string[] | undefined>).lang;
+  const value = Array.isArray(raw) ? raw[0] : raw;
+  return isLang(value) ? value : DEFAULT_LANG;
+}
+
+/**
+ * Client-side translation accessor. Returns the full dictionary for the
+ * active language so component code reads `t.something` directly.
+ */
+export function useT(): UIDict {
+  return getDict(useLang());
+}

package/src/og/icon.tsx

@@ -0,0 +1,40 @@
+import { ImageResponse } from 'next/og';
+import { resolveBrandGlyph } from '@/lib/course';
+import { loadCourse } from '@/lib/course-loader';
+import { DEFAULT_LANG } from '@/lib/lang';
+
+export const size = { width: 32, height: 32 };
+export const contentType = 'image/png';
+
+export function generateStaticParams() {
+  return [{ __metadata_id__: [] }];
+}
+
+export default function Icon() {
+  const glyph = resolveBrandGlyph(loadCourse(DEFAULT_LANG));
+  return new ImageResponse(
+    (
+      <div
+        style={{
+          width: '100%',
+          height: '100%',
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          background: '#1a1a1a',
+          color: '#faf7f2',
+          fontSize: 22,
+          fontWeight: 700,
+          fontFamily: 'sans-serif',
+          letterSpacing: -1,
+          borderRadius: 6,
+        }}
+      >
+        {glyph}
+      </div>
+    ),
+    {
+      ...size,
+    },
+  );
+}

package/src/og/opengraph-image.tsx

@@ -0,0 +1,126 @@
+import { ImageResponse } from 'next/og';
+import {
+  getTotalLessons,
+  resolveBrandGlyph,
+  resolveBrandName,
+  resolveOgFooterTag,
+} from '@/lib/course';
+import { loadCourse } from '@/lib/course-loader';
+import { formatLessonCount, formatModuleCount } from '@/lib/format';
+import { getDict } from '@/lib/i18n';
+import { DEFAULT_LANG } from '@/lib/lang';
+
+export const alt =
+  loadCourse(DEFAULT_LANG).brand?.ogImage?.alt ?? getDict(DEFAULT_LANG).ogImageAlt;
+export const size = { width: 1200, height: 630 };
+export const contentType = 'image/png';
+
+export function generateStaticParams() {
+  return [{ __metadata_id__: [] }];
+}
+
+export default function OpengraphImage() {
+  const course = loadCourse(DEFAULT_LANG);
+  const description = course.description.replace(/\s+/g, ' ').trim();
+  const truncated =
+    description.length > 180 ? `${description.slice(0, 179).trimEnd()}…` : description;
+  const moduleCount = course.modules.length;
+  const lessonCount = getTotalLessons(course);
+  const stats = `${formatModuleCount(moduleCount, DEFAULT_LANG)} · ${formatLessonCount(lessonCount, DEFAULT_LANG)}`;
+  const glyph = resolveBrandGlyph(course);
+  const wordmark = resolveBrandName(course);
+  const title = course.brand?.ogImage?.title ?? course.title;
+  const subtitle = course.brand?.ogImage?.subtitle ?? truncated;
+  const footerTag = resolveOgFooterTag(course);
+
+  return new ImageResponse(
+    (
+      <div
+        style={{
+          width: '100%',
+          height: '100%',
+          display: 'flex',
+          flexDirection: 'column',
+          justifyContent: 'space-between',
+          padding: '72px 80px',
+          background: 'linear-gradient(135deg, #faf7f2 0%, #f3efe7 100%)',
+          fontFamily: 'sans-serif',
+          color: '#1a1a1a',
+        }}
+      >
+        <div style={{ display: 'flex', alignItems: 'center', gap: 24 }}>
+          <div
+            style={{
+              width: 96,
+              height: 96,
+              borderRadius: 48,
+              background: '#1a1a1a',
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              color: '#faf7f2',
+              fontSize: 60,
+              fontWeight: 700,
+              letterSpacing: -2,
+            }}
+          >
+            {glyph}
+          </div>
+          <span
+            style={{
+              fontSize: 32,
+              fontWeight: 500,
+              color: '#5b5750',
+              letterSpacing: -0.5,
+            }}
+          >
+            {wordmark}
+          </span>
+        </div>
+
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 28 }}>
+          <div
+            style={{
+              fontSize: 96,
+              fontWeight: 700,
+              lineHeight: 1.05,
+              letterSpacing: -3,
+              color: '#1a1a1a',
+            }}
+          >
+            {title}
+          </div>
+          <div
+            style={{
+              fontSize: 32,
+              fontWeight: 400,
+              lineHeight: 1.35,
+              color: '#5b5750',
+              maxWidth: 980,
+            }}
+          >
+            {subtitle}
+          </div>
+        </div>
+
+        <div
+          style={{
+            display: 'flex',
+            justifyContent: 'space-between',
+            alignItems: 'center',
+            paddingTop: 32,
+            borderTop: '2px solid #e6e0d3',
+          }}
+        >
+          <span style={{ fontSize: 28, color: '#8a857b' }}>{stats}</span>
+          <span style={{ fontSize: 28, color: '#2a6fdb', fontWeight: 600 }}>
+            {footerTag}
+          </span>
+        </div>
+      </div>
+    ),
+    {
+      ...size,
+    },
+  );
+}

package/src/pages/home.tsx

@@ -0,0 +1,66 @@
+import type { Metadata } from 'next';
+import { notFound } from 'next/navigation';
+import { HomePage } from '@/components/HomePage';
+import { resolveBrandLevel } from '@/lib/course';
+import { loadCourse } from '@/lib/course-loader';
+import { getDict } from '@/lib/i18n';
+import { isLang, LANGS, type Lang } from '@/lib/lang';
+import { buildLangMap } from '@/lib/sitemap';
+import { buildAssetUrl, buildSiteUrl } from '@/lib/site-url';
+
+type LangPageProps = {
+  params: { lang: string };
+};
+
+export function generateStaticParams(): Array<{ lang: Lang }> {
+  return LANGS.map((lang) => ({ lang }));
+}
+
+export function generateMetadata({ params }: LangPageProps): Metadata {
+  if (!isLang(params.lang)) return {};
+  // Root layout hardcodes DEFAULT_LANG values for canonical/og:url/og:locale/
+  // description; without an override the /ru/ home would point crawlers at
+  // /en/ as canonical and ship an EN description. Build a per-lang block
+  // that matches the actual route.
+  const lang = params.lang as Lang;
+  const t = getDict(lang);
+  const course = loadCourse(lang);
+  const description = course.description.replace(/\s+/g, ' ').trim();
+  const url = buildSiteUrl(course.basePath, [lang]);
+  const ogImage = {
+    url: buildAssetUrl(course.basePath, '/opengraph-image'),
+    width: 1200,
+    height: 630,
+    alt: course.brand?.ogImage?.alt ?? t.ogImageAlt,
+  };
+  // Next.js' metadata resolution overrides `alternates` wholesale rather than
+  // merging — without re-specifying `languages` here, the root layout's
+  // hreflang map is dropped from /ru/ and /en/ pages.
+  const languages = buildLangMap(course.basePath, []);
+  return {
+    title: course.title,
+    description,
+    alternates: { canonical: url, languages },
+    openGraph: {
+      type: 'website',
+      siteName: course.title,
+      title: course.title,
+      description,
+      url,
+      locale: lang === 'ru' ? 'ru_RU' : 'en_US',
+      images: [ogImage],
+    },
+    twitter: {
+      card: 'summary_large_image',
+      title: course.title,
+      description,
+      images: [ogImage.url],
+    },
+  };
+}
+
+export default function Page({ params }: LangPageProps) {
+  if (!isLang(params.lang)) notFound();
+  const course = loadCourse(params.lang as Lang);
+  return <HomePage course={course} level={resolveBrandLevel(course)} />;
+}