@karaoke-cms/astro 0.6.2 → 0.9.0

package/README.md

@@ -0,0 +1,94 @@
+# @karaoke-cms/astro
+
+Core Astro integration for karaoke-cms. Every karaoke-cms project depends on this package.
+
+## Where it belongs
+
+`packages/astro/` in the monorepo. Users install it as a dependency and register it in `astro.config.mjs`:
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import karaoke from '@karaoke-cms/astro';
+import karaokeConfig from './karaoke.config.ts';
+
+export default defineConfig({
+  site: 'https://your-site.pages.dev',
+  integrations: [karaoke(karaokeConfig)],
+});
+```
+
+## What it does
+
+`karaoke(config)` is an Astro integration that wires up the full karaoke-cms runtime at build time:
+
+- **Loads the active theme** as a nested Astro integration (resolves by package name from `config.theme`)
+- **Injects core routes**: `/rss.xml` always; `/karaoke-cms` and `/karaoke-cms/[...slug]` in dev mode only
+- **Exposes a virtual module** (`virtual:karaoke-cms/config`) with all resolved config — title, description, collections, menus, layout, modules
+- **Registers wikilinks** via `remark-wiki-link` (`[[note]]` → `/note/`, `[[note|text]]` with alias)
+- **Registers sitemap** via `@astrojs/sitemap`
+
+### Virtual module
+
+Every page and component in the framework reads config from `virtual:karaoke-cms/config`:
+
+```ts
+import {
+  siteTitle,          // string
+  siteDescription,    // string
+  resolvedCollections, // Record<string, ResolvedCollection>
+  resolvedMenus,      // Record<string, ResolvedMenu>
+  resolvedLayout,     // { regions: { top, left, right, bottom } }
+  resolvedModules,    // { search: { enabled }, comments: { enabled, ... } }
+} from 'virtual:karaoke-cms/config';
+```
+
+Add to your `src/env.d.ts` to get TypeScript types:
+
+```ts
+/// <reference types="@karaoke-cms/astro/client" />
+```
+
+### Collections
+
+`makeCollections()` creates Astro content collections from the vault:
+
+```ts
+// src/content.config.ts
+import { makeCollections } from '@karaoke-cms/astro/collections';
+import { loadEnv } from '@karaoke-cms/astro/env';
+
+const { KARAOKE_VAULT } = loadEnv(new URL('..', import.meta.url));
+export const collections = makeCollections(import.meta.url, KARAOKE_VAULT);
+```
+
+Collections are glob-loaded from `{vault}/blog/`, `{vault}/docs/`, and `{vault}/karaoke-cms/`. Only files with `publish: true` are included in production builds.
+
+### Menus
+
+`resolveMenus(vaultDir)` reads `{vault}/karaoke-cms/config/menus.yaml` and returns `ResolvedMenus`. When the file is absent, defaults are generated: a `main` menu with Blog/Docs/Tags (each hidden when the collection is empty) and a `footer` menu with the RSS link.
+
+The `Menu.astro` and `MenuItems.astro` components render named menus with `when: collection:name` visibility guards evaluated at render time via `getCollection()`.
+
+### Layout regions
+
+The `Base.astro` layout renders four configurable regions (top, left, right, bottom) using `RegionRenderer.astro`. Each region's component list is set in `karaoke.config.ts`:
+
+```ts
+layout: {
+  regions: {
+    top: { components: ['header', 'main-menu'] },
+    bottom: { components: ['footer'] },
+  }
+}
+```
+
+Available region components: `'header'`, `'main-menu'`, `'search'`, `'recent-posts'`, `'footer'`.
+
+## How it changes the behavior of the system
+
+- Without this package there is no karaoke-cms site — it is the root of the dependency graph.
+- It is the only place where vault config (`.env`, `collections.yaml`, `menus.yaml`) is read and compiled into the virtual module. Everything else reads from that module at build time.
+- It controls which pages exist: core routes (RSS, handbook) are always present; all other routes come from the active theme.
+- Privacy enforcement flows through `makeCollections()`: the `publish: true` filter is applied at the collection level, so unpublished content is never passed to Astro's static generator.
+- Theme loading uses a native `import()` bypass to avoid Vite interception, which is why theme packages ship `.astro` source files instead of pre-compiled output.

package/client.d.ts

@@ -6,7 +6,7 @@
  */
 
 declare module 'virtual:karaoke-cms/config' {
-  import type { ResolvedModules, ResolvedLayout } from '@karaoke-cms/astro';
+  import type { ResolvedModules, ResolvedLayout, ResolvedCollections, ResolvedMenus } from '@karaoke-cms/astro';
 
   /** Site title from karaoke.config.ts */
   export const siteTitle: string;
@@ -16,4 +16,8 @@ declare module 'virtual:karaoke-cms/config' {
   export const resolvedModules: ResolvedModules;
   /** Resolved layout config (defaults filled in) */
   export const resolvedLayout: ResolvedLayout;
+  /** Resolved collections with enabled/disabled status for current build mode */
+  export const resolvedCollections: ResolvedCollections;
+  /** Resolved menus from menus.yaml (defaults to main + footer when absent) */
+  export const resolvedMenus: ResolvedMenus;
 }

package/package.json

@@ -1,22 +1,20 @@
 {
   "name": "@karaoke-cms/astro",
   "type": "module",
-  "version": "0.6.2",
-  "description": "Astro integration for karaoke-cms — ships all routes, themes, and modules",
+  "version": "0.9.0",
+  "description": "Core Astro integration for karaoke-cms — virtual config, wikilinks, handbook routes",
   "main": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
     "./client": "./client.d.ts",
     "./collections": "./src/collections.ts",
-    "./pages/index.astro": "./src/pages/index.astro",
-    "./pages/blog/index.astro": "./src/pages/blog/index.astro",
-    "./pages/blog/[slug].astro": "./src/pages/blog/[slug].astro",
-    "./pages/docs/index.astro": "./src/pages/docs/index.astro",
-    "./pages/docs/[slug].astro": "./src/pages/docs/[slug].astro",
-    "./pages/tags/index.astro": "./src/pages/tags/index.astro",
-    "./pages/tags/[tag].astro": "./src/pages/tags/[tag].astro",
-    "./pages/404.astro": "./src/pages/404.astro",
-    "./pages/rss.xml.ts": "./src/pages/rss.xml.ts"
+    "./env": "./src/utils/load-env.ts",
+    "./layouts/Base.astro": "./src/layouts/Base.astro",
+    "./consts": "./src/consts.ts",
+    "./components/ModuleLoader.astro": "./src/components/ModuleLoader.astro",
+    "./pages/rss.xml.ts": "./src/pages/rss.xml.ts",
+    "./pages/karaoke-cms/index.astro": "./src/pages/karaoke-cms/index.astro",
+    "./pages/karaoke-cms/[...slug].astro": "./src/pages/karaoke-cms/[...slug].astro"
   },
   "files": [
     "src/",
@@ -34,13 +32,15 @@
   "dependencies": {
     "@astrojs/rss": "^4.0.17",
     "@astrojs/sitemap": "^3.7.1",
-    "remark-wiki-link": "^2.0.1"
+    "remark-wiki-link": "^2.0.1",
+    "yaml": "^2.7.0",
+    "zod": "^4.0.0"
   },
   "devDependencies": {
     "vitest": "^4.1.1",
     "astro": "^6.0.8"
   },
   "scripts": {
-    "test": "vitest run test/validate-config.test.js test/resolve-modules.test.js test/resolve-layout.test.js"
+    "test": "vitest run test/validate-config.test.js test/theme-loading.test.js test/resolve-modules.test.js test/resolve-layout.test.js test/resolve-collections.test.js test/collections.test.js test/load-env.test.js test/resolve-menus.test.js"
   }
 }

package/src/blog-schema.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+
+/**
+ * Optional frontmatter schema extension for blog-theme-compatible posts.
+ * Pass as `opts.blogSchema` to `makeCollections()` when using @karaoke-cms/theme-blog.
+ *
+ * All fields are optional — posts without them validate fine against the base schema.
+ */
+export const blogThemeExtension = z.object({
+  cover_image: z.string().optional(),
+  featured:    z.boolean().optional().default(false),
+  abstract:    z.string().optional(),
+});

package/src/collections.ts

@@ -1,7 +1,10 @@
 import { defineCollection, z } from 'astro:content';
 import { glob } from 'astro/loaders';
 import { fileURLToPath } from 'url';
-import { join } from 'path';
+import { join, resolve, isAbsolute } from 'path';
+import { resolveCollections } from './utils/resolve-collections.js';
+import type { CollectionConfig } from './types.js';
+export { blogThemeExtension } from './blog-schema.js';
 
 const baseSchema = z.object({
   title: z.string(),
@@ -15,28 +18,97 @@ const baseSchema = z.object({
   related: z.array(z.string()).optional(),
 });
 
+// Relaxed schema for handbook / custom collections — title is optional
+const relaxedSchema = z.object({
+  title: z.string().optional().default('Untitled'),
+  publish: z.boolean().optional().default(false),
+  date: z.coerce.date().optional(),
+  author: z.union([z.string(), z.array(z.string())]).optional(),
+  tags: z.array(z.string()).optional(),
+  description: z.string().optional(),
+  reading_time: z.number().optional(),
+  related: z.array(z.string()).optional(),
+});
+
+export interface MakeCollectionsOptions {
+  /** Per-collection overrides from karaoke.config.ts. */
+  collections?: Record<string, CollectionConfig>;
+  /** Zod schema extension merged into the blog collection schema. Use with @karaoke-cms/theme-blog. */
+  blogSchema?: z.ZodObject<z.ZodRawShape>;
+}
+
 /**
  * Create Astro content collections for karaoke-cms.
  *
- * @param root - URL pointing to the project root (where content/ lives).
- *   Typically: `new URL('../..', import.meta.url)` from src/content.config.ts
+ * Reads collections.yaml from the vault to determine which collections are
+ * active for the current build mode. The `karaoke-cms` collection (handbook)
+ * is dev-only and never enters the production build graph.
+ *
+ * @param root - URL pointing to the Astro project root (where astro.config.mjs lives).
+ *   Typically: `new URL('..', import.meta.url)` from src/content.config.ts
+ * @param vault - Path to the Obsidian vault root (where content/ lives).
+ *   Absolute, or relative to `root`. Defaults to `root` when omitted (vault = project).
+ *   Typically sourced from `loadEnv(new URL('..', import.meta.url)).KARAOKE_VAULT`.
+ * @param opts - Optional config: collection overrides and blog schema extension.
  *
  * @example
  * // src/content.config.ts
  * import { makeCollections } from '@karaoke-cms/astro/collections';
- * export const collections = makeCollections(new URL('../..', import.meta.url));
+ * import { loadEnv } from '@karaoke-cms/astro/env';
+ * const env = loadEnv(new URL('..', import.meta.url));
+ * export const collections = makeCollections(new URL('..', import.meta.url), env.KARAOKE_VAULT);
+ *
+ * @example With blog theme schema extension:
+ * import { makeCollections, blogThemeExtension } from '@karaoke-cms/astro/collections';
+ * export const collections = makeCollections(root, vault, { blogSchema: blogThemeExtension });
  */
-export function makeCollections(root: URL) {
+export function makeCollections(
+  root: URL,
+  vault?: string,
+  opts?: MakeCollectionsOptions,
+) {
   const rootDir = fileURLToPath(root);
-  return {
-    // base paths are absolute, resolving content/ relative to the project root
-    blog: defineCollection({
-      loader: glob({ pattern: '**/*.md', base: join(rootDir, 'content/blog') }),
-      schema: baseSchema.extend({ comments: z.boolean().optional().default(true) }),
-    }),
-    docs: defineCollection({
-      loader: glob({ pattern: '**/*.md', base: join(rootDir, 'content/docs') }),
+  const vaultDir = vault
+    ? (isAbsolute(vault) ? vault : resolve(rootDir, vault))
+    : rootDir;
+  const isProd = import.meta.env.PROD;
+  const resolved = resolveCollections(vaultDir, isProd, opts?.collections);
+
+  const collections: Record<string, ReturnType<typeof defineCollection>> = {};
+
+  if (resolved.blog?.enabled) {
+    const blogExt = opts?.blogSchema
+      ? baseSchema.merge(opts.blogSchema).extend({ comments: z.boolean().optional().default(true) })
+      : baseSchema.extend({ comments: z.boolean().optional().default(true) });
+    collections.blog = defineCollection({
+      loader: glob({ pattern: '**/*.md', base: join(vaultDir, 'blog') }),
+      schema: blogExt,
+    });
+  }
+
+  if (resolved.docs?.enabled) {
+    collections.docs = defineCollection({
+      loader: glob({ pattern: '**/*.md', base: join(vaultDir, 'docs') }),
       schema: baseSchema.extend({ comments: z.boolean().optional().default(false) }),
-    }),
-  };
+    });
+  }
+
+  if (resolved['karaoke-cms']?.enabled) {
+    collections['karaoke-cms'] = defineCollection({
+      loader: glob({ pattern: '**/*.md', base: join(vaultDir, 'karaoke-cms') }),
+      schema: relaxedSchema,
+    });
+  }
+
+  // Custom collections defined in yaml or configCollections
+  for (const [name, col] of Object.entries(resolved)) {
+    if (!collections[name] && col.enabled) {
+      collections[name] = defineCollection({
+        loader: glob({ pattern: '**/*.md', base: join(vaultDir, name) }),
+        schema: relaxedSchema,
+      });
+    }
+  }
+
+  return collections;
 }

package/src/components/Menu.astro

@@ -0,0 +1,71 @@
+---
+import { resolvedCollections, resolvedMenus } from 'virtual:karaoke-cms/config';
+import { getCollection } from 'astro:content';
+import MenuItems from './MenuItems.astro';
+import type { ResolvedMenuEntry } from '../types.js';
+
+interface Props {
+  name: string;
+  class?: string;
+}
+
+const { name, class: className } = Astro.props;
+const pathname = Astro.url.pathname;
+const menu = resolvedMenus[name];
+if (!menu) return;
+
+// Evaluate `when: collection:name` visibility at render time.
+// getCollection() is Astro's per-build cached function — no extra filesystem reads.
+const collectionEmpty: Record<string, boolean> = {};
+
+async function isVisible(entry: ResolvedMenuEntry): Promise<boolean> {
+  if (!entry.when) return true;
+  if (!entry.when.startsWith('collection:')) {
+    if (import.meta.env.DEV) {
+      console.warn(
+        `[karaoke-cms] Unknown when: condition "${entry.when}" on menu entry "${entry.text}". ` +
+        `Only "collection:name" is supported in v1. Entry will always show.`,
+      );
+    }
+    return true;
+  }
+  const colName = entry.when.slice('collection:'.length);
+  if (!resolvedCollections[colName]?.enabled) return false;
+  if (!(colName in collectionEmpty)) {
+    try {
+      // colName is a runtime string from YAML, not a literal type.
+      // resolvedCollections[colName]?.enabled check above ensures it's a known collection.
+      // getCollection() throws if the collection is unknown — caught below.
+      const entries = await getCollection(colName as any, ({ data }: any) => data.publish === true);
+      collectionEmpty[colName] = entries.length === 0;
+    } catch {
+      collectionEmpty[colName] = true;
+    }
+  }
+  return !collectionEmpty[colName];
+}
+
+// Apply when: guards recursively so nested submenu entries also respect visibility.
+async function filterVisible(entries: ResolvedMenuEntry[]): Promise<ResolvedMenuEntry[]> {
+  const results = await Promise.all(
+    entries.map(async e => {
+      if (!(await isVisible(e))) return null;
+      const visibleChildren = await filterVisible(e.entries);
+      return { ...e, entries: visibleChildren };
+    })
+  );
+  return results.filter((e): e is ResolvedMenuEntry => e !== null);
+}
+
+const visibleEntries = await filterVisible(menu.entries);
+---
+
+{visibleEntries.length > 0 && (
+  <nav
+    class:list={['karaoke-menu', className]}
+    data-orientation={menu.orientation}
+    aria-label={name}
+  >
+    <MenuItems entries={visibleEntries} pathname={pathname} />
+  </nav>
+)}

package/src/components/MenuItems.astro

@@ -0,0 +1,28 @@
+---
+import type { ResolvedMenuEntry } from '../types.js';
+
+interface Props {
+  entries: ResolvedMenuEntry[];
+  pathname: string;
+}
+
+const { entries, pathname } = Astro.props;
+---
+
+<ul>
+  {entries.map(entry => (
+    <li class:list={{ 'has-submenu': entry.entries.length > 0 }}>
+      {entry.href ? (
+        <a
+          href={entry.href}
+          aria-current={pathname === entry.href || pathname.startsWith(entry.href + '/') ? 'page' : undefined}
+        >{entry.text}</a>
+      ) : (
+        <span>{entry.text}</span>
+      )}
+      {entry.entries.length > 0 && (
+        <Astro.self entries={entry.entries} pathname={pathname} />
+      )}
+    </li>
+  ))}
+</ul>

package/src/components/regions/MainMenu.astro

@@ -1,22 +1,4 @@
 ---
-const pathname = Astro.url.pathname;
+import Menu from '../Menu.astro';
 ---
-<nav>
-  <ul>
-    <li>
-      <a href="/blog" aria-current={pathname.startsWith('/blog') ? 'page' : undefined}>
-        Blog
-      </a>
-    </li>
-    <li>
-      <a href="/docs" aria-current={pathname.startsWith('/docs') ? 'page' : undefined}>
-        Docs
-      </a>
-    </li>
-    <li>
-      <a href="/tags" aria-current={pathname.startsWith('/tags') ? 'page' : undefined}>
-        Tags
-      </a>
-    </li>
-  </ul>
-</nav>
+<Menu name="main" />

package/src/components/regions/RecentPosts.astro

@@ -1,9 +1,17 @@
 ---
 import { getCollection } from 'astro:content';
 
-const posts = (await getCollection('blog', ({ data }) => data.publish === true))
+const LIMIT = 5;
+
+// Detect which collection we're in and exclude the current page
+const pathname = Astro.url.pathname.replace(/\/$/, '');
+const collection = pathname.startsWith('/docs/') ? 'docs' : 'blog';
+const currentSlug = pathname.split('/').at(-1) ?? '';
+
+const posts = (await getCollection(collection, ({ data }) => data.publish === true))
   .sort((a, b) => (b.data.date?.valueOf() ?? 0) - (a.data.date?.valueOf() ?? 0))
-  .slice(0, 5);
+  .filter(post => post.id !== currentSlug)
+  .slice(0, LIMIT);
 ---
 
 {posts.length > 0 && (
@@ -12,7 +20,7 @@ const posts = (await getCollection('blog', ({ data }) => data.publish === true))
     <ul class="sidebar-list">
       {posts.map(post => (
         <li>
-          <a href={`/blog/${post.id}`}>{post.data.title}</a>
+          <a href={`/${collection}/${post.id}`}>{post.data.title}</a>
           {post.data.date && (
             <span class="post-date">{post.data.date.toISOString().slice(0, 10)}</span>
           )}

package/src/components/regions/SiteFooter.astro

@@ -1,7 +1,7 @@
 ---
+import Menu from '../Menu.astro';
 ---
-<div>
-  <a href="/rss.xml">RSS</a> · Built with
-  <a href="https://obsidian.md" rel="noopener">Obsidian</a> +
-  <a href="https://astro.build" rel="noopener">Astro</a>
+<Menu name="footer" />
+<div class="footer-attr">
+  Built with <a href="https://karaoke-cms.org">karaoke-cms</a>
 </div>