polen 0.11.0-next.2 → 0.11.0-next.20

package/src/api/config-resolver/config-resolver.ts

@@ -1,2 +1 @@
 export * from './resolve.js'
-export * from './vite.js'

package/src/api/config-resolver/resolve.ts

@@ -1,22 +1,26 @@
 import { debugPolen } from '#singletons/debug'
-import { type ConfigInput, normalizeInput } from '../config/configurator.js'
+import { FileSystem } from '@effect/platform/FileSystem'
+import { Effect } from 'effect'
+import type { ConfigInput } from '../config/$$.js'
+import { mergeInputs } from '../config/input.js'
 import { load, type LoadOptions } from '../config/load.js'
-import { mergeInputs } from '../config/merge.js'
-import { toViteUserConfig, type ViteUserConfigWithPolen } from './vite.js'
+import type { Config } from '../config/normalized.js'
+import { normalizeInput } from '../config/normalized.js'
 
 interface ResolveFromFileOptions extends LoadOptions {
-  overrides?: ConfigInput
+  overrides?: ConfigInput | undefined
 }
 
-export const fromFile = async (options: ResolveFromFileOptions): Promise<ViteUserConfigWithPolen> => {
-  const configInput = await load(options)
-  const configInputMerged = mergeInputs(configInput, options.overrides)
-  const config = await fromMemory(configInputMerged, options.dir)
-  debugPolen(`resolved config`, config)
-  return config
-}
+export const fromFile = (options: ResolveFromFileOptions): Effect.Effect<Config, Error, FileSystem> =>
+  Effect.gen(function*() {
+    const configInput = yield* load(options)
+    const configInputMerged = mergeInputs(configInput, options.overrides)
+    const config = yield* fromMemory(configInputMerged, options.dir)
+    debugPolen(`resolved config`, config)
+    return config
+  })
 
-export const fromMemory = async (
+export const fromMemory = (
   input: ConfigInput,
   /**
    * Refer to `baseRootDirPath` parameter on {@link normalizeInput}.
@@ -24,8 +28,6 @@ export const fromMemory = async (
    * @default `process.cwd()`
    */
   baseRootDirPath?: string,
-) => {
-  const configNormalized = await normalizeInput(input, baseRootDirPath ?? process.cwd())
-  const viteUserConfig = toViteUserConfig(configNormalized)
-  return viteUserConfig
+): Effect.Effect<Config, Error, never> => {
+  return normalizeInput(input, baseRootDirPath ?? process.cwd())
 }

package/src/api/config-template/template.ts

@@ -0,0 +1,77 @@
+import type { Api } from '#api/$'
+import { ExamplesConfigObject } from '#api/examples/config'
+import { ConfigSchema } from '#api/schema/config-schema'
+import type { Catalog } from '#lib/catalog/$'
+import { S } from '#lib/kit-temp/effect'
+import { Fn, Obj } from '@wollybeard/kit'
+import { Config } from '../config/normalized.js'
+
+export const resolve = (config: Config, data: {
+  examples?: Api.Examples.Catalog.Catalog | undefined
+  schemas?: Catalog.Catalog | undefined
+}): TemplateConfig => {
+  return {
+    ...Obj.omit(config, ['_input']),
+    schema: {
+      ...config.schema,
+      enabled: Boolean(config.schema.enabled ?? data.schemas),
+    },
+    examples: {
+      ...config.examples,
+      enabled: Boolean(config.examples.enabled ?? (data.examples && data.examples.examples.length > 0)),
+    },
+  }
+}
+
+// ============================================================================
+// Schema - Template Config
+// ============================================================================
+
+/**
+ * Template configuration with all feature flags resolved.
+ * This is the configuration that templates receive, where optional fields
+ * that control feature enablement have been resolved to concrete values.
+ */
+export const TemplateConfig = S.extend(
+  Config.pipe(S.omit('_input', 'schema', 'examples')),
+  S.Struct({
+    schema: S.extend(
+      ConfigSchema.pipe(S.omit('enabled')),
+      S.Struct({
+        enabled: S.Boolean,
+      }),
+    ),
+    examples: S.extend(
+      ExamplesConfigObject.pipe(S.omit('enabled')),
+      S.Struct({
+        enabled: S.Boolean,
+      }),
+    ),
+  }),
+).annotations({
+  identifier: 'TemplateConfig',
+  title: 'Template Configuration',
+  description: 'Fully resolved configuration for template consumption with all feature flags determined',
+})
+
+export type TemplateConfig = S.Schema.Type<typeof TemplateConfig>
+
+// ============================================================================
+// Constructors
+// ============================================================================
+
+export const makeTemplateConfig = Fn.identity(TemplateConfig)
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+export const isTemplateConfig = S.is(TemplateConfig)
+
+// ============================================================================
+// Codecs
+// ============================================================================
+
+export const decodeTemplateConfig = S.decode(TemplateConfig)
+export const encodeTemplateConfig = S.encode(TemplateConfig)
+export const encodeSyncTemplateConfig = S.encodeSync(TemplateConfig)

package/src/api/content/$$.ts

@@ -1,3 +1,4 @@
+export * from './mdx-compiler.js'
 export * from './metadata.js'
 export * from './navbar.js'
 export * from './page.js'

package/src/api/content/$.test.ts

@@ -1,5 +1,9 @@
+import { S } from '#lib/kit-temp/effect'
+import * as NodeFileSystem from '@effect/platform-node/NodeFileSystem'
 import { Fs, Path } from '@wollybeard/kit'
+import { Effect, Either } from 'effect'
 import { afterEach, beforeEach, describe, expect, test } from 'vitest'
+import { Test } from '../../../tests/unit/helpers/test.js'
 import { Content } from './$.js'
 
 describe('content', () => {
@@ -15,34 +19,22 @@ describe('content', () => {
     }
   })
 
-  describe('MetadataSchema', () => {
-    test('validates metadata correctly', () => {
-      const valid = Content.MetadataSchema.safeParse({
-        description: 'Test page description',
-        hidden: true,
-      })
-      expect(valid.success).toBe(true)
-      expect(valid.data).toEqual({
-        description: 'Test page description',
-        hidden: true,
-      })
-    })
-
-    test('applies default values', () => {
-      const result = Content.MetadataSchema.safeParse({
-        description: 'Just a description',
-      })
-      expect(result.success).toBe(true)
-      expect(result.data?.hidden).toBe(false)
-    })
-
-    test('rejects invalid values', () => {
-      const result = Content.MetadataSchema.safeParse({
-        hidden: 'not a boolean',
-        invalid_field: 123,
-      })
-      expect(result.success).toBe(false)
-    })
+  // dprint-ignore
+  Test.suite<{ input: unknown; isValid: boolean; expected?: { description?: string; hidden?: boolean } }>('MetadataSchema', [
+    { name: 'validates metadata correctly',                                                              input: { description: 'Test page description', hidden: true },                                     isValid: true,  expected: { description: 'Test page description', hidden: true } },
+    { name: 'applies default values',                                                                    input: { description: 'Just a description' },                                                      isValid: true,  expected: { description: 'Just a description', hidden: false } },
+    { name: 'rejects invalid values',                                                                    input: { hidden: 'not a boolean', invalid_field: 123 },                                           isValid: false },
+  ], ({ input, isValid, expected }) => {
+    const result = S.decodeUnknownEither(Content.MetadataSchema)(input)
+    
+    if (isValid) {
+      expect(Either.isRight(result)).toBe(true)
+      if (Either.isRight(result) && expected) {
+        expect(result.right).toEqual(expected)
+      }
+    } else {
+      expect(Either.isLeft(result)).toBe(true)
+    }
   })
 
   describe('scan', () => {
@@ -56,10 +48,14 @@ description: Page description
 Content`,
       })
 
-      const result = await Content.scan({
-        dir: testDir,
-        glob: '**/*.md',
-      })
+      const result = await Effect.runPromise(
+        Content.scan({
+          dir: testDir,
+          glob: '**/*.md',
+        }).pipe(
+          Effect.provide(NodeFileSystem.layer),
+        ),
+      )
 
       expect(result.list).toHaveLength(1)
       expect(result.list[0]?.metadata).toEqual({

package/src/api/content/mdx-compiler.ts

@@ -0,0 +1,74 @@
+import { compile } from '@mdx-js/mdx'
+import { recmaCodeHike, remarkCodeHike } from 'codehike/mdx'
+import remarkFrontmatter from 'remark-frontmatter'
+import remarkGfm from 'remark-gfm'
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+/**
+ * Core MDX configuration used across Polen.
+ * This ensures consistent MDX processing for all content types.
+ */
+export const MDX_CONFIG = {
+  jsxImportSource: 'polen/react',
+  providerImportSource: 'polen/mdx',
+  codeHike: {
+    components: { code: 'CodeBlock' },
+    syntaxHighlighting: {
+      theme: 'github-light',
+    },
+  },
+} as const
+
+// ============================================================================
+// Plugin Configuration
+// ============================================================================
+
+/**
+ * Create standard remark and recma plugins configuration for MDX processing.
+ * This ensures consistent plugin usage across all MDX compilation.
+ */
+export const createMdxPlugins = () => ({
+  remarkPlugins: [
+    remarkFrontmatter,
+    remarkGfm,
+    [remarkCodeHike, MDX_CONFIG.codeHike] as any,
+  ],
+  recmaPlugins: [
+    [recmaCodeHike, MDX_CONFIG.codeHike] as any,
+  ],
+})
+
+// ============================================================================
+// Compilation Functions
+// ============================================================================
+
+/**
+ * Compile MDX content to function body format.
+ * Used for runtime compilation of MDX content (e.g., example index files).
+ *
+ * @param content - The MDX content to compile
+ * @returns Compiled MDX as a function body string
+ */
+export const compileMdxToFunctionBody = async (content: string) => {
+  return compile(content, {
+    ...MDX_CONFIG,
+    ...createMdxPlugins(),
+    outputFormat: 'function-body',
+    development: false,
+  })
+}
+
+/**
+ * Get configuration for @mdx-js/rollup plugin.
+ * Used for build-time compilation of MDX pages.
+ *
+ * @returns Configuration object for mdx rollup plugin
+ */
+export const getMdxRollupConfig = () => ({
+  ...MDX_CONFIG,
+  ...createMdxPlugins(),
+  rehypePlugins: [],
+})

package/src/api/content/metadata.ts

@@ -1,11 +1,11 @@
-import { z } from 'zod'
+import { S } from '#lib/kit-temp/effect'
 
 /**
  * Schema for validating front matter content
  */
-export const MetadataSchema = z.object({
-  description: z.string().optional(),
-  hidden: z.boolean().default(false),
+export const MetadataSchema = S.Struct({
+  description: S.optional(S.String),
+  hidden: S.optionalWith(S.Boolean, { default: () => false }),
 })
 
-export type Metadata = z.infer<typeof MetadataSchema>
+export type Metadata = S.Schema.Type<typeof MetadataSchema>

package/src/api/content/navbar.test.ts

@@ -25,13 +25,13 @@ describe('createNavbar', () => {
   it('excludes hidden pages', () => {
     const pages = [createPage(['visible'], 'index', false), createPage(['hidden'], 'index', true)]
     const result = createNavbar(pages)
-    expect(result).toEqual([{ pathExp: '/visible', title: 'Visible' }])
+    expect(result).toEqual([{ pathExp: '/visible', title: 'Visible', position: 'right' }])
   })
 
   it('includes directories with index pages', () => {
     const pages = [createPage(['guide'], 'index'), createPage(['guide', 'intro'], 'intro')]
     const result = createNavbar(pages)
-    expect(result).toEqual([{ pathExp: '/guide', title: 'Guide' }])
+    expect(result).toEqual([{ pathExp: '/guide', title: 'Guide', position: 'right' }])
   })
 
   it('excludes directories without index pages', () => {
@@ -43,7 +43,7 @@ describe('createNavbar', () => {
   it('includes single top-level pages', () => {
     const pages = [createPage(['about'], 'about')]
     const result = createNavbar(pages)
-    expect(result).toEqual([{ pathExp: '/about', title: 'About' }])
+    expect(result).toEqual([{ pathExp: '/about', title: 'About', position: 'right' }])
   })
 
   it('sorts results alphabetically', () => {

package/src/api/content/navbar.ts

@@ -4,6 +4,7 @@ import type { Page } from './page.js'
 export interface NavbarItem {
   pathExp: string
   title: string
+  position?: 'left' | 'right'
 }
 
 /**
@@ -50,6 +51,7 @@ export const createNavbar = (pages: Page[]): NavbarItem[] => {
       navbarItems.push({
         pathExp,
         title,
+        position: 'right',
       })
     }
   })

package/src/api/content/page.ts

@@ -1,4 +1,4 @@
-import type { FileRouter } from '#lib/file-router/index'
+import type { FileRouter } from '#lib/file-router'
 import type { Metadata } from './metadata.js'
 
 export type { Metadata }

package/src/api/content/scan.ts

@@ -1,5 +1,8 @@
-import { FileRouter } from '#lib/file-router/index'
+import { FileRouter } from '#lib/file-router'
+import { S } from '#lib/kit-temp/effect'
+import { FileSystem } from '@effect/platform'
 import { Fs, Path, Tree } from '@wollybeard/kit'
+import { Effect, Either } from 'effect'
 import matter from 'gray-matter'
 import { MetadataSchema } from './metadata.js'
 import type { Page } from './page.js'
@@ -14,104 +17,109 @@ export interface ScanResult {
  * Scan a directory for pages and extract metadata from their front matter
  * By default, hidden pages are filtered out from both the pages list and route tree.
  */
-export const scan = async (options: {
+export const scan = (options: {
   dir: string
   glob?: string
   /** Include hidden pages in the result (useful for debugging or admin interfaces) */
   includeHidden?: boolean
-}): Promise<ScanResult> => {
-  // Scan for routes
-  const routeScanResult = await FileRouter.scan({
-    dir: options.dir,
-    glob: options.glob ?? `**/*.{md,mdx}`,
-  })
+}): Effect.Effect<ScanResult, Error, FileSystem.FileSystem> =>
+  Effect.gen(function*() {
+    // Scan for routes
+    const routeScanResult = yield* FileRouter.scan({
+      dir: options.dir,
+      glob: options.glob ?? `**/*.{md,mdx}`,
+    })
+
+    // Create pages with metadata (id/parentId now come from route)
+    const allPages = yield* Effect.all(
+      routeScanResult.routes.map(route => readRoute(route)),
+    )
+
+    // Apply filtering if needed
+    const pages = options.includeHidden
+      ? allPages
+      : allPages.filter(page => !page.metadata.hidden)
+
+    // Build tree from pages using Tree.fromList
+    // Transform pages to include id/parentId at the top level for Tree.fromList
+    const pagesWithIds = pages.map(page => ({
+      ...page,
+      id: page.route.id,
+      parentId: page.route.parentId,
+    }))
 
-  // Create pages with metadata (id/parentId now come from route)
-  const allPages = await Promise.all(
-    routeScanResult.routes.map(route => readRoute(route)),
-  )
-
-  // Apply filtering if needed
-  const pages = options.includeHidden
-    ? allPages
-    : allPages.filter(page => !page.metadata.hidden)
-
-  // Build tree from pages using Tree.fromList
-  // Transform pages to include id/parentId at the top level for Tree.fromList
-  const pagesWithIds = pages.map(page => ({
-    ...page,
-    id: page.route.id,
-    parentId: page.route.parentId,
-  }))
-
-  // Handle cases where there might be multiple root nodes
-  // If all pages are at root level (no parentId), create a virtual root
-  const hasMultipleRoots = pagesWithIds.filter(p => !p.parentId).length > 1
-
-  let tree: Tree.Tree<Page>
-  if (hasMultipleRoots) {
-    // Create a virtual root node to hold all root-level pages
-    const virtualRoot: Page & { id: string; parentId: null } = {
-      route: {
-        id: `__virtual_root__`,
-        parentId: null,
-        file: {
-          path: {
-            absolute: Path.parse(``),
-            relative: Path.parse(``),
+    // Handle cases where there might be multiple root nodes
+    // If all pages are at root level (no parentId), create a virtual root
+    const hasMultipleRoots = pagesWithIds.filter(p => !p.parentId).length > 1
+
+    let tree: Tree.Tree<Page>
+    if (hasMultipleRoots) {
+      // Create a virtual root node to hold all root-level pages
+      const virtualRoot: Page & { id: string; parentId: null } = {
+        route: {
+          id: `__virtual_root__`,
+          parentId: null,
+          file: {
+            path: {
+              absolute: Path.parse(``),
+              relative: Path.parse(``),
+            },
+          },
+          logical: {
+            path: [],
           },
         },
-        logical: {
-          path: [],
-        },
-      },
-      metadata: { hidden: true },
-      id: `__virtual_root__`,
-      parentId: null,
-    }
+        metadata: { hidden: true },
+        id: `__virtual_root__`,
+        parentId: null,
+      }
 
-    // Update pages to have virtual root as parent if they don't have one
-    const pagesWithVirtualRoot = pagesWithIds.map(page => ({
-      ...page,
-      parentId: page.parentId ?? `__virtual_root__`,
-    }))
+      // Update pages to have virtual root as parent if they don't have one
+      const pagesWithVirtualRoot = pagesWithIds.map(page => ({
+        ...page,
+        parentId: page.parentId ?? `__virtual_root__`,
+      }))
 
-    tree = Tree.fromList([virtualRoot, ...pagesWithVirtualRoot])
-  } else {
-    tree = Tree.fromList(pagesWithIds)
-  }
+      tree = Tree.fromList([virtualRoot, ...pagesWithVirtualRoot])
+    } else {
+      tree = Tree.fromList(pagesWithIds)
+    }
 
-  return {
-    list: pages,
-    tree,
-    diagnostics: routeScanResult.diagnostics,
-  }
-}
+    return {
+      list: pages,
+      tree,
+      diagnostics: routeScanResult.diagnostics,
+    }
+  })
 
 /**
  * Read a single route file and extract metadata from its front matter
  */
-const readRoute = async (route: FileRouter.Route): Promise<Page> => {
-  const filePath = Path.format(route.file.path.absolute)
-  const fileContent = await Fs.read(filePath)
-
-  // Empty files still get default metadata (not hidden by default)
-  // This allows placeholder pages to exist in the navigation
-  if (!fileContent) {
-    return { route, metadata: { hidden: false } }
-  }
+const readRoute = (route: FileRouter.Route): Effect.Effect<Page, Error, FileSystem.FileSystem> =>
+  Effect.gen(function*() {
+    const fs = yield* FileSystem.FileSystem
+    const filePath = Path.format(route.file.path.absolute)
+    const fileContent = yield* fs.readFileString(filePath).pipe(
+      Effect.mapError(error => new Error(`Failed to read file ${filePath}: ${error}`)),
+    )
+
+    // Empty files still get default metadata (not hidden by default)
+    // This allows placeholder pages to exist in the navigation
+    if (!fileContent) {
+      return { route, metadata: { hidden: false } }
+    }
 
-  // Parse front matter
-  const { data } = matter(fileContent)
+    // Parse front matter
+    const { data } = matter(fileContent)
 
-  // Validate and parse the data
-  const parsed = MetadataSchema.safeParse(data)
+    // Validate and parse the data
+    const parsed = S.decodeUnknownEither(MetadataSchema)(data)
 
-  if (!parsed.success) {
-    // Log warning but continue with defaults
-    console.warn(`Invalid front matter in ${filePath}:`, parsed.error.issues)
-  }
+    if (Either.isLeft(parsed)) {
+      // Log warning but continue with defaults
+      console.warn(`Invalid front matter in ${filePath}:`, parsed.left)
+    }
 
-  const metadata = parsed.success ? parsed.data : { hidden: false }
-  return { route, metadata }
-}
+    const metadata = Either.isRight(parsed) ? parsed.right : { hidden: false }
+    return { route, metadata }
+  })

package/src/api/content/sidebar.ts

@@ -1,5 +1,6 @@
-import { FileRouter } from '#lib/file-router/index'
+import { FileRouter } from '#lib/file-router'
 import { Str } from '@wollybeard/kit'
+import { Array } from 'effect'
 import type { Page } from './page.js'
 import type { ScanResult } from './scan.js'
 
@@ -101,7 +102,7 @@ export type SidebarIndex = Record<string, Sidebar>
  *
  * @example
  * ```ts
- * const scanResult = await Content.scan({ dir: './pages' })
+ * const scanResult = await Effect.runPromise(Content.scan({ dir: './pages' }))
  * const sidebars = buildSidebarIndex(scanResult)
  * // Returns: {
  * //   '/guide': { items: [...] },
@@ -129,10 +130,9 @@ export const buildSidebarIndex = (scanResult: ScanResult): SidebarIndex => {
 
   // Build sidebar for each directory that has an index page
   for (const [topLevelDir, pages] of pagesByTopLevelDir) {
-    const hasIndexPage = pages.some(page =>
+    const hasIndexPage = Array.some(pages, page =>
       page.route.logical.path.length === 1
-      && FileRouter.routeIsFromIndexFile(page.route)
-    )
+      && FileRouter.routeIsFromIndexFile(page.route))
 
     // Skip directories without index pages
     if (!hasIndexPage) continue