@karaoke-cms/astro 0.9.8 → 0.10.3

package/src/types.ts

@@ -1,155 +1,40 @@
-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 CommentsConfig {
-  enabled?: boolean;
-  /** GitHub repo in "owner/repo" format */
-  repo?: string;
-  repoId?: string;
-  category?: string;
-  categoryId?: string;
-}
-
-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. */
-  description?: string;
-  /** Theme — package name string (legacy) or a ThemeInstance from defineTheme(). */
-  theme?: string | ThemeInstance;
-  /** Modules to activate. Each is a ModuleInstance from defineModule(). */
-  modules?: ModuleInstance[];
-  /** Giscus comments configuration. */
-  comments?: CommentsConfig;
-  layout?: {
-    regions?: {
-      top?:    { components?: RegionComponent[] };
-      left?:   { components?: RegionComponent[] };
-      right?:  { components?: RegionComponent[] };
-      bottom?: { components?: RegionComponent[] };
-    };
-  };
-}
-
-/** Resolved (defaults filled in) modules config — available at build time via virtual module. */
-export interface ResolvedModules {
-  comments: {
-    enabled: boolean;
-    repo: string;
-    repoId: string;
-    category: string;
-    categoryId: string;
-  };
-}
-
-/** Resolved (defaults filled in) layout config — available at build time via virtual module. */
-export interface ResolvedLayout {
-  regions: {
-    top:    { components: RegionComponent[] };
-    left:   { components: RegionComponent[] };
-    right:  { components: RegionComponent[] };
-    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>;
-
-// ── Module system types ────────────────────────────────────────────────────────
-
-/** A menu entry registered by a module instance. */
-export interface ModuleMenuEntry {
-  id: string;
-  name: string;
-  path: string;
-  section: string;
-  weight: number;
-}
-
-/** A resolved module instance — returned by a defineModule() factory. */
-export interface ModuleInstance {
-  _type: 'module-instance';
-  id: string;
-  mount: string;
-  /** When false, karaoke() skips route injection and menu entries for this module. Defaults to true. */
-  enabled: boolean;
-  routes: Array<{ pattern: string; entrypoint: string }>;
-  menuEntries: ModuleMenuEntry[];
-  cssContract: readonly string[];
-  hasDefaultCss: boolean;
-  /**
-   * Page files to copy into the user's src/pages/ on first dev run.
-   * Only copied if the destination does not already exist.
-   * src: absolute path to the source .astro file in the npm package.
-   * dest: path relative to src/pages/ (e.g. "blog/index.astro").
-   */
-  scaffoldPages?: Array<{ src: string; dest: string }>;
-  /**
-   * Absolute path to the module's default CSS file.
-   * On first dev run, copied to src/styles/{id}.css and imported into global.css.
-   */
-  defaultCssPath?: string;
-}
-
-/** A resolved theme instance — returned by a defineTheme() factory. */
-export interface ThemeInstance {
-  _type: 'theme-instance';
-  id: string;
-  implementedModuleIds: string[];
-  implementedModules: ModuleInstance[];
-  toAstroIntegration: (activeModules?: ModuleInstance[]) => import('astro').AstroIntegration;
-}
+/**
+ * All shared types now live in @karaoke-cms/contracts.
+ *
+ * This file re-exports them for backwards compatibility — internal callers
+ * that import from './types.js' continue to work unchanged.
+ */
+export type {
+  // CSS contract
+  CssContractSlot,
+  CssContract,
+  // Primitive named types
+  RouteDefinition,
+  CollectionSpec,
+  ScaffoldPage,
+  // Module system
+  ModuleMenuEntry,
+  ModuleInstance,
+  // Theme system
+  ThemeInstance,
+  ThemeFactoryConfig,
+  // Factory definitions
+  ModuleDefinition,
+  ThemeDefinition,
+  // Configuration
+  RegionComponent,
+  CollectionMode,
+  CollectionConfig,
+  ResolvedCollection,
+  ResolvedCollections,
+  CommentsConfig,
+  KaraokeConfig,
+  ResolvedModules,
+  ResolvedLayout,
+  // Menu
+  MenuEntryConfig,
+  MenuConfig,
+  ResolvedMenuEntry,
+  ResolvedMenu,
+  ResolvedMenus,
+} from '@karaoke-cms/contracts';

package/src/utils/resolve-menus.ts

@@ -38,10 +38,13 @@ function defaultMain(modules: ModuleInstance[]): ResolvedMenu {
       }))
     );
 
-  // Theme-owned entries (Docs, Tags) are always present.
+  // Only inject the hardcoded Docs fallback when no module owns a docs collection.
+  // When modules supply their own docs sections (via docs() factory), those appear
+  // in moduleMainEntries and the hardcoded entry would produce a duplicate.
+  const hasDocsModule = modules.some(m => m.collection != null);
   const themeEntries: ResolvedMenuEntry[] = [
-    { text: 'Docs', href: '/docs', weight: 20, when: 'collection:docs', entries: [] },
-    { text: 'Tags', href: '/tags', weight: 30, entries: [] },
+    ...(!hasDocsModule ? [{ text: 'Docs', href: '/docs', weight: 20, when: 'collection:docs', entries: [] as ResolvedMenuEntry[] }] : []),
+    { text: 'Tags', href: '/tags', weight: 30, entries: [] as ResolvedMenuEntry[] },
   ];
 
   // If no modules provide main entries, fall back to hardcoded Blog default.

package/src/validate-config.js

@@ -6,20 +6,96 @@
 
 /**
  * Validate module config at build time.
- * Throws a clear error if comments is enabled but required fields are missing.
+ * Throws a clear error if comments is enabled but required fields are missing,
+ * or if multiple docs instances share the same id, mount, folder, or collection name.
  *
  * @param {import('../karaoke.config').KaraokeConfig | null | undefined} config
  */
 export function validateModules(config) {
   const comments = config?.comments
-  if (!comments?.enabled) return
+  if (comments?.enabled) {
+    const required = ['repo', 'repoId', 'category', 'categoryId']
+    const missing = required.filter(k => !comments[k])
+    if (missing.length > 0) {
+      throw new Error(
+        `karaoke-cms: comments.enabled is true but the following required fields are missing: ` +
+        `${missing.join(', ')}. Get these values from https://giscus.app`
+      )
+    }
+  }
+
+  // Gather all active docs instances from config.modules and theme.implementedModules.
+  const configModules = config?.modules ?? []
+  const themeModules =
+    config?.theme?._type === 'theme-instance'
+      ? (config.theme.implementedModules ?? [])
+      : []
+
+  const configDocs = configModules.filter(m => m.collection != null && m.enabled !== false)
+  const themeDocs  = themeModules.filter(m => m.collection != null && m.enabled !== false)
+
+  // Check for duplicate ids WITHIN each source — an id appearing twice in config.modules
+  // (or twice in theme.implementedModules) is always an error.
+  function checkDupIds(arr, source) {
+    const ids = arr.map(m => m.id)
+    const dups = ids.filter((v, i) => ids.indexOf(v) !== i)
+    if (dups.length > 0) {
+      throw new Error(
+        `karaoke-cms: duplicate docs module id(s) in ${source}: ${[...new Set(dups)].join(', ')}. ` +
+        `Each docs() instance must have a unique id.`
+      )
+    }
+  }
+  checkDupIds(configDocs, 'config.modules')
+  checkDupIds(themeDocs, 'theme.implementedModules')
+
+  // Combine with dedup by id — config wins (same as runtime).
+  // Cross-source duplicates (same id in config AND theme) are silently merged.
+  const seenIds = new Set()
+  const allDocsInstances = [...configDocs, ...themeDocs].filter(m => {
+    if (seenIds.has(m.id)) return false
+    seenIds.add(m.id)
+    return true
+  })
+
+  // Validate mount paths for all instances (single or multiple).
+  const MOUNT_RE = /^\/[a-z0-9\-_/]*$/i
+  for (const inst of allDocsInstances) {
+    if (!MOUNT_RE.test(inst.mount)) {
+      throw new Error(
+        `karaoke-cms: docs() mount "${inst.mount}" contains invalid characters. ` +
+        `Use a simple path like "/docs" or "/api-docs" (no Astro route syntax, no trailing slash).`
+      )
+    }
+  }
+
+  if (allDocsInstances.length < 2) return
+
+  const mounts = allDocsInstances.map(m => m.mount)
+  const folders = allDocsInstances.map(m => m.collection.folder)
+  const collectionNames = allDocsInstances.map(m => m.collection.name)
+
+  const dupMounts = mounts.filter((v, i) => mounts.indexOf(v) !== i)
+  if (dupMounts.length > 0) {
+    throw new Error(
+      `karaoke-cms: duplicate docs module mount(s): ${[...new Set(dupMounts)].join(', ')}. ` +
+      `Each docs() instance must have a unique mount path.`
+    )
+  }
+
+  const dupFolders = folders.filter((v, i) => folders.indexOf(v) !== i)
+  if (dupFolders.length > 0) {
+    throw new Error(
+      `karaoke-cms: duplicate docs module folder(s): ${[...new Set(dupFolders)].join(', ')}. ` +
+      `Each docs() instance must read from a different vault folder.`
+    )
+  }
 
-  const required = ['repo', 'repoId', 'category', 'categoryId']
-  const missing = required.filter(k => !comments[k])
-  if (missing.length > 0) {
+  const dupNames = collectionNames.filter((v, i) => collectionNames.indexOf(v) !== i)
+  if (dupNames.length > 0) {
     throw new Error(
-      `karaoke-cms: comments.enabled is true but the following required fields are missing: ` +
-      `${missing.join(', ')}. Get these values from https://giscus.app`
+      `karaoke-cms: duplicate docs collection name(s): ${[...new Set(dupNames)].join(', ')}. ` +
+      `Each docs() instance must use a unique collection name.`
     )
   }
 }