@karaoke-cms/astro 0.6.2 → 0.9.0

package/src/index.ts

@@ -1,21 +1,40 @@
 import type { AstroIntegration } from 'astro';
-import { fileURLToPath } from 'url';
-import { join } from 'path';
+import { fileURLToPath, pathToFileURL } from 'url';
+import { resolve, isAbsolute } from 'path';
+import { createRequire } from 'module';
 import { wikiLinkPlugin } from 'remark-wiki-link';
 import sitemap from '@astrojs/sitemap';
-import { getTheme, validateModules } from './validate-config.js';
+import { validateModules } from './validate-config.js';
 import { resolveModules } from './utils/resolve-modules.js';
 import { resolveLayout } from './utils/resolve-layout.js';
-import type { KaraokeConfig, ResolvedModules, ResolvedLayout } from './types.js';
+import { resolveCollections } from './utils/resolve-collections.js';
+import { resolveMenus } from './utils/resolve-menus.js';
+import type { KaraokeConfig, ResolvedModules, ResolvedLayout, ResolvedCollections, ResolvedMenus } from './types.js';
 
-const __dirname = fileURLToPath(new URL('.', import.meta.url));
+/**
+ * Resolve a theme config value to an npm package name.
+ * Bare strings ('default', 'minimal') map to @karaoke-cms/theme-* with a deprecation warning.
+ */
+function resolveThemePkg(theme: string | undefined): string {
+  const raw = theme ?? '@karaoke-cms/theme-default';
+  if (raw === 'default' || raw === 'minimal') {
+    console.warn(
+      `[karaoke-cms] theme: '${raw}' is deprecated. Use theme: '@karaoke-cms/theme-${raw}' instead.`,
+    );
+    return `@karaoke-cms/theme-${raw}`;
+  }
+  return raw;
+}
 
 /**
  * karaoke() — the main Astro integration for karaoke-cms.
  *
- * Injects all routes (/, /blog, /blog/[slug], /docs, /docs/[slug],
- * /tags, /tags/[tag], /rss.xml, /404), sets up the @theme CSS alias,
- * enables wikilinks, and provides a virtual module with your resolved config.
+ * Loads the active theme package (an Astro integration) and registers it
+ * as a nested integration. The theme owns all content routes (/, /blog, /docs,
+ * etc.), the @theme CSS alias, and its own 404 page.
+ *
+ * Core always registers: /rss.xml, /karaoke-cms/[...slug] (dev only), wikilinks,
+ * sitemap, and the virtual:karaoke-cms/config module.
  *
  * @example
  * // astro.config.mjs
@@ -27,50 +46,66 @@ const __dirname = fileURLToPath(new URL('.', import.meta.url));
  *   site: 'https://your-site.pages.dev',
  *   integrations: [karaoke(karaokeConfig)],
  * });
- *
- * Module slots (contract for Base.astro — extensible in v0.7+):
- *   'nav'         — rendered in the nav bar (e.g., Search)
- *   'post-footer' — rendered after post content (e.g., Comments)
  */
 export default function karaoke(config: KaraokeConfig = {}): AstroIntegration {
-  const themesDir = join(__dirname, 'themes');
-  const theme = getTheme(config, themesDir);
   validateModules(config);
   const resolved = resolveModules(config);
   const layout = resolveLayout(config);
 
+  let _resolvedCollections: ResolvedCollections | undefined;
+
   return {
     name: '@karaoke-cms/astro',
     hooks: {
-      'astro:config:setup'({ injectRoute, updateConfig }) {
-        // ── Inject all framework routes ──────────────────────────────────
-        injectRoute({ pattern: '/', entrypoint: '@karaoke-cms/astro/pages/index.astro' });
-        injectRoute({ pattern: '/blog', entrypoint: '@karaoke-cms/astro/pages/blog/index.astro' });
-        injectRoute({ pattern: '/blog/[slug]', entrypoint: '@karaoke-cms/astro/pages/blog/[slug].astro' });
-        injectRoute({ pattern: '/docs', entrypoint: '@karaoke-cms/astro/pages/docs/index.astro' });
-        injectRoute({ pattern: '/docs/[slug]', entrypoint: '@karaoke-cms/astro/pages/docs/[slug].astro' });
-        injectRoute({ pattern: '/tags', entrypoint: '@karaoke-cms/astro/pages/tags/index.astro' });
-        injectRoute({ pattern: '/tags/[tag]', entrypoint: '@karaoke-cms/astro/pages/tags/[tag].astro' });
-        injectRoute({ pattern: '/404', entrypoint: '@karaoke-cms/astro/pages/404.astro' });
+      async 'astro:config:setup'({ injectRoute, updateConfig, command, config: astroConfig }) {
+        const rootDir = fileURLToPath(astroConfig.root);
+        const vaultDir = config.vault
+          ? (isAbsolute(config.vault) ? config.vault : resolve(rootDir, config.vault))
+          : rootDir;
+        const isProd = command === 'build';
+        _resolvedCollections = resolveCollections(vaultDir, isProd, config.collections);
+        const _resolvedMenus = resolveMenus(vaultDir);
+
+        // ── Load active theme as a nested Astro integration ───────────────
+        // Resolve the theme package from the user's project root, not from
+        // this package's location, so the user's node_modules is searched.
+        const themePkg = resolveThemePkg(config.theme);
+        const projectRequire = createRequire(new URL('package.json', astroConfig.root));
+        let resolvedThemePath: string;
+        try {
+          resolvedThemePath = projectRequire.resolve(themePkg);
+        } catch {
+          throw new Error(
+            `[karaoke-cms] Theme package "${themePkg}" is not installed.\n` +
+            `Run: pnpm add ${themePkg}`,
+          );
+        }
+        // Use new Function to bypass Vite's import() interception —
+        // this runs the native Node.js ESM loader, not Vite's module runner.
+        const nativeImport: (specifier: string) => Promise<unknown> =
+          new Function('specifier', 'return import(specifier)');
+        const themeModule = await nativeImport(pathToFileURL(resolvedThemePath).href) as {
+          default: (cfg: KaraokeConfig) => AstroIntegration;
+        };
+        const themeIntegration = themeModule.default(config);
+
+        // ── Core routes — always present regardless of theme ─────────────
         injectRoute({ pattern: '/rss.xml', entrypoint: '@karaoke-cms/astro/pages/rss.xml.ts' });
 
+        // Handbook routes — dev only
+        if (_resolvedCollections['karaoke-cms']?.enabled) {
+          injectRoute({ pattern: '/karaoke-cms', entrypoint: '@karaoke-cms/astro/pages/karaoke-cms/index.astro' });
+          injectRoute({ pattern: '/karaoke-cms/[...slug]', entrypoint: '@karaoke-cms/astro/pages/karaoke-cms/[...slug].astro' });
+        }
+
         updateConfig({
-          integrations: [sitemap()],
+          integrations: [sitemap(), themeIntegration],
           vite: {
-            resolve: {
-              alias: {
-                // @theme → packages/astro/src/themes/<active-theme>/
-                '@theme': join(themesDir, theme),
-              },
-            },
-            plugins: [virtualConfigPlugin(config, resolved, layout)],
+            plugins: [virtualConfigPlugin(config, resolved, layout, _resolvedCollections, _resolvedMenus)],
           },
           markdown: {
             remarkPlugins: [
               [wikiLinkPlugin, {
-                // [[blog/hello-world]] → /blog/hello-world/
-                // [[docs/getting-started]] → /docs/getting-started/
-                // [[blog/hello-world|Hello World]] → link text "Hello World"
                 pageResolver: (name: string) => [name.toLowerCase().replace(/ /g, '-')],
                 hrefTemplate: (permalink: string) => `/${permalink}/`,
                 aliasDivider: '|',
@@ -79,6 +114,19 @@ export default function karaoke(config: KaraokeConfig = {}): AstroIntegration {
           },
         });
       },
+
+      'astro:build:done'({ pages }) {
+        if (!_resolvedCollections?.docs?.enabled) return;
+        // pages is { pathname: string }[] — check if any /docs page was rendered
+        const hasDocsRoute = (pages ?? []).some(p => p.pathname?.startsWith('docs'));
+        if (!hasDocsRoute) {
+          console.warn(
+            '[karaoke-cms] Your vault has a docs collection enabled but the active theme ' +
+            'has no /docs route. Published docs entries will not be accessible. ' +
+            'Consider using @karaoke-cms/theme-default which includes /docs routes.',
+          );
+        }
+      },
     },
   };
 }
@@ -87,7 +135,13 @@ export default function karaoke(config: KaraokeConfig = {}): AstroIntegration {
  * Vite plugin providing `virtual:karaoke-cms/config`.
  * Base.astro and ModuleLoader.astro import from it at build time.
  */
-function virtualConfigPlugin(config: KaraokeConfig, resolved: ResolvedModules, layout: ResolvedLayout) {
+function virtualConfigPlugin(
+  config: KaraokeConfig,
+  resolved: ResolvedModules,
+  layout: ResolvedLayout,
+  resolvedCollections: ResolvedCollections,
+  resolvedMenus: ResolvedMenus,
+) {
   const VIRTUAL_ID = 'virtual:karaoke-cms/config';
   const RESOLVED_ID = '\0' + VIRTUAL_ID;
 
@@ -103,10 +157,12 @@ export const siteTitle = ${JSON.stringify(config.title ?? 'Karaoke')};
 export const siteDescription = ${JSON.stringify(config.description ?? '')};
 export const resolvedModules = ${JSON.stringify(resolved)};
 export const resolvedLayout = ${JSON.stringify(layout)};
+export const resolvedCollections = ${JSON.stringify(resolvedCollections)};
+export const resolvedMenus = ${JSON.stringify(resolvedMenus)};
 `;
       }
     },
   };
 }
 
-export type { KaraokeConfig, ResolvedModules, ResolvedLayout, RegionComponent } from './types.js';
+export type { KaraokeConfig, ResolvedModules, ResolvedLayout, ResolvedCollections, RegionComponent, ResolvedMenus, ResolvedMenu, ResolvedMenuEntry } from './types.js';

package/src/layouts/Base.astro

@@ -1,8 +1,7 @@
 ---
 import '@theme/styles.css';
 import RegionRenderer from '../components/RegionRenderer.astro';
-import { resolvedModules, resolvedLayout } from 'virtual:karaoke-cms/config';
-import { SITE_TITLE } from '../consts';
+import { siteTitle, resolvedModules, resolvedLayout } from 'virtual:karaoke-cms/config';
 
 interface Props {
   title: string;
@@ -28,14 +27,14 @@ const hasRight = Astro.slots.has('right') || layout.regions.right.components.len
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <link rel="icon" href="/favicon.ico" />
     <meta name="generator" content={Astro.generator} />
-    <title>{title === SITE_TITLE ? title : `${title} — ${SITE_TITLE}`}</title>
+    <title>{title === siteTitle ? title : `${title} — ${siteTitle}`}</title>
     {description && <meta name="description" content={description} />}
     <meta property="og:title" content={title} />
     <meta property="og:type" content={type} />
     <meta property="og:url" content={canonicalUrl} />
     {description && <meta property="og:description" content={description} />}
     <meta name="twitter:card" content="summary" />
-    <link rel="alternate" type="application/rss+xml" title={SITE_TITLE} href="/rss.xml" />
+    <link rel="alternate" type="application/rss+xml" title={siteTitle} href="/rss.xml" />
   </head>
   <body>
     <header>
@@ -65,9 +64,11 @@ const hasRight = Astro.slots.has('right') || layout.regions.right.components.len
       )}
     </div>
     <footer>
-      <slot name="bottom">
-        <RegionRenderer components={layout.regions.bottom.components} {searchEnabled} />
-      </slot>
+      <div class="footer-inner">
+        <slot name="bottom">
+          <RegionRenderer components={layout.regions.bottom.components} {searchEnabled} />
+        </slot>
+      </div>
     </footer>
   </body>
 </html>

package/src/pages/karaoke-cms/[...slug].astro

@@ -0,0 +1,44 @@
+---
+import { getCollection, render } from 'astro:content';
+import Base from '../../layouts/Base.astro';
+import { SITE_TITLE } from '../../consts';
+
+// Handbook is dev-only — this route is never injected in production.
+export async function getStaticPaths() {
+  const entries = await getCollection('karaoke-cms');
+  return entries.map(entry => ({
+    params: { slug: entry.id },
+    props: { entry },
+  }));
+}
+
+const { entry } = Astro.props;
+const { Content } = await render(entry);
+---
+
+<Base title={`${entry.data.title} — ${SITE_TITLE}`} description={entry.data.description}>
+  <article>
+    <div class="post-header">
+      <span class="handbook-badge">Handbook — dev only</span>
+      <h1>{entry.data.title}</h1>
+    </div>
+    <div class="prose">
+      <Content />
+    </div>
+    <div class="post-footer">
+      <a href="/karaoke-cms">← Handbook</a>
+    </div>
+  </article>
+</Base>
+
+<style>
+  .handbook-badge {
+    display: inline-block;
+    font-size: 0.75rem;
+    background: var(--color-accent, #f59e0b);
+    color: #000;
+    padding: 0.1rem 0.5rem;
+    border-radius: 999px;
+    margin-bottom: 0.5rem;
+  }
+</style>

package/src/pages/karaoke-cms/index.astro

@@ -0,0 +1,43 @@
+---
+import { getCollection } from 'astro:content';
+import Base from '../../layouts/Base.astro';
+import { SITE_TITLE } from '../../consts';
+
+// Handbook is dev-only — this route is never injected in production.
+// Show all entries (no publish filter — handbook pages are always visible in dev).
+const entries = (await getCollection('karaoke-cms'))
+  .sort((a, b) => (a.data.title ?? '').localeCompare(b.data.title ?? ''));
+---
+
+<Base title={`Handbook — ${SITE_TITLE}`}>
+  <div class="listing-header">
+    <h1>Handbook</h1>
+    <p class="handbook-badge">dev only</p>
+  </div>
+  {entries.length > 0 ? (
+    <ul class="post-list">
+      {entries.map(entry => (
+        <li>
+          <a href={`/karaoke-cms/${entry.id}`}>{entry.data.title}</a>
+        </li>
+      ))}
+    </ul>
+  ) : (
+    <div class="empty-state">
+      <p>No handbook pages found.</p>
+      <p>Add Markdown files to <code>content/karaoke-cms/</code> in your vault.</p>
+    </div>
+  )}
+</Base>
+
+<style>
+  .handbook-badge {
+    display: inline-block;
+    font-size: 0.75rem;
+    background: var(--color-accent, #f59e0b);
+    color: #000;
+    padding: 0.1rem 0.5rem;
+    border-radius: 999px;
+    margin-top: 0.25rem;
+  }
+</style>

package/src/types.ts

@@ -1,6 +1,30 @@
 export type RegionComponent = 'header' | 'main-menu' | 'search' | 'recent-posts' | 'footer';
 
+export type CollectionMode = 'dev' | 'prod';
+
+export interface CollectionConfig {
+  modes?: CollectionMode[];
+  label?: string;
+}
+
+export interface ResolvedCollection {
+  modes: CollectionMode[];
+  label: string;
+  enabled: boolean;
+}
+
+export type ResolvedCollections = Record<string, ResolvedCollection>;
+
 export interface KaraokeConfig {
+  /**
+   * Path to the Obsidian vault root (where content/ lives).
+   * Absolute, or relative to the Astro project root.
+   * Defaults to the project root (vault and project are the same directory).
+   * Typically set via KARAOKE_VAULT in .env (gitignored) with .env.default as fallback.
+   */
+  vault?: string;
+  /** Per-collection mode overrides. Merges with collections.yaml; this field takes precedence. */
+  collections?: Record<string, CollectionConfig>;
   /** Site title — displayed in the browser tab and nav bar. Defaults to 'Karaoke'. */
   title?: string;
   /** Site description — used in RSS feed and OG meta tags. */
@@ -49,3 +73,37 @@ export interface ResolvedLayout {
     bottom: { components: RegionComponent[] };
   };
 }
+
+// ── Menu types ─────────────────────────────────────────────────────────────────
+
+/** Raw shape of one entry in menus.yaml (used to type the parsed YAML). */
+export interface MenuEntryConfig {
+  text: string;
+  href?: string;
+  weight?: number;
+  /** Visibility condition — only 'collection:name' supported in v1. */
+  when?: string;
+  entries?: MenuEntryConfig[];
+}
+
+/** Raw shape of one menu block in menus.yaml. */
+export interface MenuConfig {
+  orientation?: 'horizontal' | 'vertical';
+  entries?: MenuEntryConfig[];
+}
+
+export interface ResolvedMenuEntry {
+  text: string;
+  href?: string;
+  weight: number;
+  when?: string;
+  entries: ResolvedMenuEntry[];
+}
+
+export interface ResolvedMenu {
+  name: string;
+  orientation: 'horizontal' | 'vertical';
+  entries: ResolvedMenuEntry[];
+}
+
+export type ResolvedMenus = Record<string, ResolvedMenu>;

package/src/utils/load-env.ts

@@ -0,0 +1,37 @@
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { fileURLToPath } from 'url';
+
+function parseEnvFile(filePath: string): Record<string, string> {
+  try {
+    const content = readFileSync(filePath, 'utf8');
+    const result: Record<string, string> = {};
+    for (const line of content.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith('#')) continue;
+      const eq = trimmed.indexOf('=');
+      if (eq === -1) continue;
+      const key = trimmed.slice(0, eq).trim();
+      const val = trimmed.slice(eq + 1).trim().replace(/^["']|["']$/g, '');
+      if (key) result[key] = val;
+    }
+    return result;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Load env vars from .env.default (committed defaults) and .env (local overrides).
+ * .env takes precedence over .env.default.
+ * Missing files are silently skipped.
+ *
+ * @param dir - URL or path of the directory containing the .env files.
+ */
+export function loadEnv(dir: URL | string): Record<string, string> {
+  const dirPath = dir instanceof URL ? fileURLToPath(dir) : dir;
+  return {
+    ...parseEnvFile(join(dirPath, '.env.default')),
+    ...parseEnvFile(join(dirPath, '.env')),
+  };
+}

package/src/utils/resolve-collections.ts

@@ -0,0 +1,83 @@
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { parse } from 'yaml';
+import type { CollectionConfig, CollectionMode, ResolvedCollections } from '../types.js';
+
+// Hardcoded defaults — used when collections.yaml is absent or unreadable.
+// karaoke-cms is dev-only so it never enters the production build graph.
+const DEFAULTS: Record<string, { modes: CollectionMode[]; label: string }> = {
+  blog: { modes: ['dev', 'prod'], label: 'Blog' },
+  docs: { modes: ['dev', 'prod'], label: 'Docs' },
+  'karaoke-cms': { modes: ['dev'], label: 'Handbook' },
+};
+
+interface YamlShape {
+  collections?: Record<string, { modes?: string[]; label?: string }>;
+}
+
+/**
+ * Resolve the active content collections for the current build mode.
+ *
+ * Data flow:
+ *   DEFAULTS
+ *     ← merged with collections.yaml  (YAML overrides defaults per-key)
+ *     ← merged with configCollections (karaoke.config.ts overrides per-key)
+ *     → filter by isProd
+ *     → ResolvedCollections
+ *
+ * @param rootDir  Absolute path to the vault root (where blog/, docs/, karaoke-cms/ live).
+ * @param isProd   True during `astro build`, false during `astro dev`.
+ * @param configCollections  Optional overrides from karaoke.config.ts `collections` field.
+ */
+export function resolveCollections(
+  rootDir: string,
+  isProd: boolean,
+  configCollections?: Record<string, CollectionConfig>,
+): ResolvedCollections {
+  // 1. Read and parse collections.yaml (graceful fallback to defaults if absent)
+  let yamlCollections: Record<string, { modes?: CollectionMode[]; label?: string }> = {};
+  try {
+    const yamlPath = join(rootDir, 'karaoke-cms/config/collections.yaml');
+    const raw = readFileSync(yamlPath, 'utf8');
+    const parsed = parse(raw) as YamlShape;
+    if (parsed?.collections && typeof parsed.collections === 'object') {
+      for (const [name, val] of Object.entries(parsed.collections)) {
+        yamlCollections[name] = {
+          modes: Array.isArray(val?.modes)
+            ? (val.modes.filter(m => m === 'dev' || m === 'prod') as CollectionMode[])
+            : undefined,
+          label: typeof val?.label === 'string' ? val.label : undefined,
+        };
+      }
+    }
+  } catch {
+    // File absent or unreadable — use hardcoded defaults
+  }
+
+  // 2. Merge: DEFAULTS ← yaml ← configCollections
+  const allNames = new Set([
+    ...Object.keys(DEFAULTS),
+    ...Object.keys(yamlCollections),
+    ...(configCollections ? Object.keys(configCollections) : []),
+  ]);
+
+  const result: ResolvedCollections = {};
+  for (const name of allNames) {
+    const base = DEFAULTS[name];
+    const yaml = yamlCollections[name];
+    const cfg = configCollections?.[name];
+
+    const modes: CollectionMode[] =
+      cfg?.modes ?? yaml?.modes ?? base?.modes ?? ['dev', 'prod'];
+    const label: string =
+      cfg?.label ?? yaml?.label ?? base?.label ?? name;
+
+    result[name] = {
+      modes,
+      label,
+      enabled: isProd ? modes.includes('prod') : modes.includes('dev'),
+    };
+  }
+
+  return result;
+}

package/src/utils/resolve-menus.ts

@@ -0,0 +1,95 @@
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { parse } from 'yaml';
+import type { MenuConfig, MenuEntryConfig, ResolvedMenuEntry, ResolvedMenu, ResolvedMenus } from '../types.js';
+
+/** Reject javascript: and data: hrefs to prevent stored XSS via menus.yaml. */
+function sanitizeHref(href: string): string | undefined {
+  const lower = href.trim().toLowerCase();
+  if (lower.startsWith('javascript:') || lower.startsWith('data:')) return undefined;
+  return href;
+}
+
+function normalizeEntries(raw: MenuEntryConfig[], depth = 0): ResolvedMenuEntry[] {
+  // Guard against YAML anchor cycles (e.g., entries: &loop ... entries: *loop).
+  if (depth > 10) return [];
+  return (raw ?? [])
+    .map(e => ({
+      text: String(e?.text ?? ''),
+      href: typeof e?.href === 'string' ? sanitizeHref(e.href) : undefined,
+      weight: typeof e?.weight === 'number' ? e.weight : 0,
+      when: typeof e?.when === 'string' ? e.when : undefined,
+      entries: Array.isArray(e?.entries) ? normalizeEntries(e.entries, depth + 1) : [],
+    }))
+    .sort((a, b) => a.weight - b.weight);
+}
+
+function defaultMain(): ResolvedMenu {
+  return {
+    name: 'main',
+    orientation: 'horizontal',
+    entries: [
+      { text: 'Blog', href: '/blog', weight: 10, when: 'collection:blog', entries: [] },
+      { text: 'Docs', href: '/docs', weight: 20, when: 'collection:docs', entries: [] },
+      { text: 'Tags', href: '/tags', weight: 30, entries: [] },
+    ],
+  };
+}
+
+function defaultFooter(): ResolvedMenu {
+  return {
+    name: 'footer',
+    orientation: 'horizontal',
+    entries: [
+      { text: 'RSS', href: '/rss.xml', weight: 10, entries: [] },
+    ],
+  };
+}
+
+/**
+ * Resolve menus from {vault}/karaoke-cms/config/menus.yaml.
+ *
+ * Always ensures `main` and `footer` exist in the result — generating defaults
+ * when absent so that MainMenu.astro and SiteFooter.astro always have something
+ * to render. ENOENT (no menus.yaml) is the normal zero-config case; all other
+ * errors warn and fall back to defaults.
+ */
+export function resolveMenus(vaultDir: string): ResolvedMenus {
+  try {
+    const path = join(vaultDir, 'karaoke-cms/config/menus.yaml');
+    const raw = readFileSync(path, 'utf8');
+    const parsed = parse(raw) as { menus?: Record<string, MenuConfig> };
+
+    if (!parsed?.menus || typeof parsed.menus !== 'object') {
+      return { main: defaultMain(), footer: defaultFooter() };
+    }
+
+    const result: ResolvedMenus = {};
+    for (const [name, cfg] of Object.entries(parsed.menus)) {
+      if (
+        cfg?.orientation !== undefined &&
+        cfg.orientation !== 'horizontal' &&
+        cfg.orientation !== 'vertical'
+      ) {
+        console.warn(
+          `[karaoke-cms] menus.yaml: menu "${name}" has invalid orientation "${cfg.orientation}". Using "horizontal".`,
+        );
+      }
+      result[name] = {
+        name,
+        orientation: cfg?.orientation === 'vertical' ? 'vertical' : 'horizontal',
+        entries: normalizeEntries(cfg?.entries ?? []),
+      };
+    }
+    if (!result.main) result.main = defaultMain();
+    if (!result.footer) result.footer = defaultFooter();
+    return result;
+  } catch (err: unknown) {
+    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
+      console.warn(
+        `[karaoke-cms] Failed to parse menus.yaml: ${(err as Error).message}. Using default menus.`,
+      );
+    }
+    return { main: defaultMain(), footer: defaultFooter() };
+  }
+}

package/src/validate-config.js

@@ -4,18 +4,6 @@
  * Extracted here so the logic is unit-testable separately from astro.config.mjs.
  */
 
-import { readdirSync, statSync } from 'fs'
-import { join } from 'path'
-
-/**
- * Resolve the active theme name from karaoke.config.
- * Falls back to 'default' if config is absent.
- * Throws a clear error if the named theme folder doesn't exist.
- *
- * @param {import('../karaoke.config').KaraokeConfig | null | undefined} config
- * @param {string} themesDir - absolute path to the src/themes directory
- * @returns {string} the resolved theme name
- */
 /**
  * Validate module config at build time.
  * Throws a clear error if comments is enabled but required fields are missing.
@@ -36,24 +24,3 @@ export function validateModules(config) {
   }
 }
 
-export function getTheme(config, themesDir) {
-  const theme = config?.theme ?? 'default'
-  let available
-  try {
-    available = readdirSync(themesDir)
-  } catch {
-    throw new Error(
-      `karaoke-cms: src/themes/ directory not found at ${themesDir} — is this a karaoke-cms repo?`
-    )
-  }
-  available = available.filter(d => {
-    try { return statSync(join(themesDir, d)).isDirectory() } catch { return false }
-  })
-  if (!available.includes(theme)) {
-    throw new Error(
-      `karaoke-cms: theme "${theme}" not found in src/themes/. ` +
-      `Available: ${available.join(', ')}`
-    )
-  }
-  return theme
-}

package/src/pages/404.astro

@@ -1,14 +0,0 @@
----
-import Base from '../layouts/Base.astro';
-import { SITE_TITLE } from '../consts';
----
-
-<Base title={`Page not found — ${SITE_TITLE}`}>
-  <div class="post-header">
-    <h1>Page not found</h1>
-    <p class="post-meta">The page you're looking for doesn't exist or hasn't been published.</p>
-  </div>
-  <div class="prose">
-    <p><a href="/">Go home →</a></p>
-  </div>
-</Base>