@karaoke-cms/contracts 0.10.3

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@karaoke-cms/contracts",
+  "type": "module",
+  "version": "0.10.3",
+  "description": "Shared type contracts for karaoke-cms — interfaces for modules, themes, and configuration",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src/"
+  ],
+  "keywords": [
+    "astro",
+    "cms",
+    "karaoke-cms",
+    "types"
+  ],
+  "peerDependencies": {
+    "astro": ">=6.0.0"
+  },
+  "devDependencies": {
+    "astro": "^6.0.8"
+  }
+}

package/src/index.ts

@@ -0,0 +1,348 @@
+/**
+ * @karaoke-cms/contracts
+ *
+ * Shared type contracts for karaoke-cms.
+ *
+ * Every interface that crosses a package boundary lives here. All other packages
+ * (`@karaoke-cms/astro`, `@karaoke-cms/module-*`, `@karaoke-cms/theme-*`) import
+ * from this package rather than from each other.
+ *
+ * This package also exports `defineModule()` and `defineTheme()` — the factory
+ * functions module and theme authors use to declare their package. They have no
+ * Astro-specific runtime dependencies, only type-level references to `astro`.
+ */
+
+import type { AstroIntegration } from 'astro';
+
+// ── CSS contract ──────────────────────────────────────────────────────────────
+
+/**
+ * Metadata for a single CSS class slot in a module's contract.
+ *
+ * - `required: true`  — the theme MUST implement this class for the module to render correctly.
+ * - `required: false` — the class is optional / used for progressive enhancement.
+ */
+export interface CssContractSlot {
+  description: string;
+  required: boolean;
+}
+
+/**
+ * A record mapping CSS class names to their slot metadata.
+ *
+ * Module authors declare a `CssContract` in `src/css-contract.ts`; themes implement
+ * every class listed here. `required: true` slots must be styled.
+ *
+ * @example
+ * export const cssContract: CssContract = {
+ *   'blog-list': { description: 'Post list page wrapper', required: true },
+ *   'blog-card': { description: 'Individual post card',   required: true },
+ *   'blog-tag':  { description: 'Tag chip on card/post',  required: false },
+ * };
+ */
+export type CssContract = Record<string, CssContractSlot>;
+
+// ── Primitive named types ─────────────────────────────────────────────────────
+
+/** A single route injected by a module into the Astro site. */
+export interface RouteDefinition {
+  pattern: string;
+  entrypoint: string;
+}
+
+/**
+ * Metadata for a docs-style collection owned by a module instance.
+ * When present on a `ModuleInstance`, `karaoke()` code-generates per-instance
+ * page files instead of using static entrypoints.
+ */
+export interface CollectionSpec {
+  name: string;
+  folder: string;
+  label: string;
+  layout: string;
+  sidebarStyle: string;
+}
+
+/** A page file to copy into the user's `src/pages/` on first dev run. */
+export interface ScaffoldPage {
+  /** Absolute path to the source `.astro` file inside the npm package. */
+  src: string;
+  /** Destination path relative to `src/pages/` (e.g. `"blog/index.astro"`). */
+  dest: string;
+}
+
+// ── Module system ─────────────────────────────────────────────────────────────
+
+/** 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 call.
+ *
+ * Pass instances to `defineConfig({ modules: [...] })` in `karaoke.config.ts`.
+ */
+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: RouteDefinition[];
+  menuEntries: ModuleMenuEntry[];
+  /** CSS class names this module will use in its markup. Themes implement these classes. */
+  cssContract: CssContract;
+  hasDefaultCss: boolean;
+  /**
+   * When present, this module owns a docs-style collection.
+   * `karaoke()` code-generates per-instance `.astro` page files instead of
+   * using the static entrypoints in `routes`.
+   */
+  collection?: CollectionSpec;
+  scaffoldPages?: ScaffoldPage[];
+  /**
+   * 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;
+  /**
+   * Optional Astro integration provided by this module.
+   * `karaoke()` collects these and registers them alongside the theme integration.
+   * Use for Vite plugin registration, build hooks, etc.
+   */
+  integration?: AstroIntegration;
+}
+
+// ── Module factory ────────────────────────────────────────────────────────────
+
+/**
+ * Definition object passed to `defineModule()`.
+ * Describes a module's static shape; the factory call fills in runtime values.
+ */
+export interface ModuleDefinition {
+  id: string;
+  cssContract: CssContract;
+  /** Absolute path to a default CSS file. On first dev run, copied to `src/styles/{id}.css`. */
+  defaultCssPath?: string;
+  routes: (mount: string) => RouteDefinition[];
+  menuEntries: (mount: string, id: string) => ModuleMenuEntry[];
+  collection?: () => unknown;
+  scaffoldPages?: (mount: string) => ScaffoldPage[];
+  /** Optional Astro integration for this module (Vite plugins, build hooks, etc.). */
+  integration?: AstroIntegration;
+}
+
+/**
+ * Define a karaoke-cms module.
+ *
+ * Returns a factory function. Call the factory with `{ mount }` (and optionally
+ * `{ id }` for multi-instance support) to get a `ModuleInstance` that can be
+ * passed to `defineConfig({ modules: [...] })`.
+ *
+ * @example
+ * export const blog = defineModule({ id: 'blog', routes: (mount) => [...], ... })
+ * // In karaoke.config.ts:
+ * modules: [blog({ mount: '/blog' })]
+ */
+export function defineModule(def: ModuleDefinition) {
+  return function moduleFactory(config: { id?: string; mount?: string; enabled?: boolean } = {}): ModuleInstance {
+    const id = config.id ?? def.id;
+    const mount = (config.mount ?? '').replace(/\/$/, '');
+    const enabled = config.enabled ?? true;
+    return {
+      _type: 'module-instance',
+      id,
+      mount,
+      enabled,
+      routes: def.routes(mount),
+      menuEntries: def.menuEntries(mount, id),
+      cssContract: def.cssContract,
+      hasDefaultCss: !!def.defaultCssPath,
+      scaffoldPages: def.scaffoldPages?.(mount),
+      defaultCssPath: def.defaultCssPath,
+      integration: def.integration,
+    };
+  };
+}
+
+// ── Theme system ──────────────────────────────────────────────────────────────
+
+/**
+ * A resolved theme instance — returned by a `defineTheme()` factory call.
+ *
+ * Pass to `defineConfig({ theme: ... })` in `karaoke.config.ts`.
+ */
+export interface ThemeInstance {
+  _type: 'theme-instance';
+  id: string;
+  /** Module instances bundled or accepted by this theme (used for deduplication). */
+  implementedModules: ModuleInstance[];
+  toAstroIntegration: (activeModules?: ModuleInstance[]) => AstroIntegration;
+}
+
+// ── Theme factory ─────────────────────────────────────────────────────────────
+
+/**
+ * User-facing config for a theme factory. Themes may extend this interface
+ * to declare their own configuration fields.
+ */
+export interface ThemeFactoryConfig {}
+
+/**
+ * Definition object passed to `defineTheme()`.
+ */
+export interface ThemeDefinition {
+  id: string;
+  /**
+   * Module instances statically bundled with this theme.
+   * These are merged with `config.modules` by `karaoke()`, deduplicating by id
+   * (config wins). Themes that accept modules via factory config should set
+   * `implementedModules` dynamically inside `toAstroIntegration` instead.
+   */
+  implementedModules?: ModuleInstance[];
+  toAstroIntegration: (config: ThemeFactoryConfig, modules: ModuleInstance[]) => AstroIntegration;
+}
+
+/**
+ * Define a karaoke-cms theme.
+ *
+ * Returns a factory function. Call the factory (optionally with config) to get a
+ * `ThemeInstance` that can be passed to `defineConfig({ theme: ... })`. Modules are
+ * passed by the `karaoke()` integration at build time via `toAstroIntegration(modules)`.
+ *
+ * @example
+ * export const myTheme = defineTheme({
+ *   id: 'my-theme',
+ *   toAstroIntegration: (config, modules) => ({ name: '...', hooks: { ... } }),
+ * })
+ * // In karaoke.config.ts:
+ * theme: myTheme()
+ */
+export function defineTheme(def: ThemeDefinition) {
+  return function themeFactory(config: ThemeFactoryConfig = {}): ThemeInstance {
+    return {
+      _type: 'theme-instance',
+      id: def.id,
+      implementedModules: def.implementedModules ?? [],
+      toAstroIntegration: (modules: ModuleInstance[] = []) => def.toAstroIntegration(config, modules),
+    };
+  };
+}
+
+// ── Configuration types ───────────────────────────────────────────────────────
+
+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>;