polen 0.9.1-next.2 → 0.10.0-next.11

package/src/api/config/configurator.ts

@@ -1,9 +1,9 @@
 import type { Vite } from '#dep/vite/index'
 import { assertPathAbsolute } from '#lib/kit-temp'
+import { type PackagePaths, packagePaths } from '#package-paths'
 import { Path } from '@wollybeard/kit'
 import { z } from 'zod'
 import type { SchemaAugmentation } from '../../api/schema-augmentation/index.ts'
-import { type PackagePaths, packagePaths } from '../../package-paths.ts'
 import type { Schema } from '../schema/index.ts'
 
 export const BuildArchitectureEnum = {
@@ -124,7 +124,13 @@ export interface TemplateVariables {
 
 const buildPaths = (rootDir: string): Config[`paths`] => {
   if (!Path.isAbsolute(rootDir)) throw new Error(`Root dir path must be absolute: ${rootDir}`)
-  const ensureAbsolute = Path.ensureAbsoluteWith(rootDir)
+  const rootAbsolute = Path.ensureAbsoluteWith(rootDir)
+
+  const buildAbsolutePath = rootAbsolute(`build`)
+  const buildAbsolute = Path.ensureAbsoluteWith(buildAbsolutePath)
+
+  const publicAbsolutePath = rootAbsolute(`public`)
+  const publicAbsolute = Path.ensureAbsoluteWith(publicAbsolutePath)
   return {
     project: {
       rootDir,
@@ -137,14 +143,22 @@ const buildPaths = (rootDir: string): Config[`paths`] => {
           },
         },
         pages: `pages`,
+        public: {
+          root: 'public',
+          logo: 'logo.svg',
+        },
       },
       absolute: {
+        pages: rootAbsolute(`pages`),
         build: {
-          root: ensureAbsolute(`build`),
-          serverEntrypoint: ensureAbsolute(`build/app.js`),
-          assets: ensureAbsolute(`build/assets`),
+          root: buildAbsolute('.'),
+          serverEntrypoint: buildAbsolute(`app.js`),
+          assets: buildAbsolute(`assets`),
+        },
+        public: {
+          root: publicAbsolute('.'),
+          logo: publicAbsolute('logo.svg'),
         },
-        pages: ensureAbsolute(`pages`),
       },
     },
     framework: packagePaths,
@@ -178,6 +192,10 @@ export interface Config {
           }
         }
         pages: string
+        public: {
+          root: string
+          logo: string
+        }
       }
       absolute: {
         build: {
@@ -186,6 +204,10 @@ export interface Config {
           serverEntrypoint: string
         }
         pages: string
+        public: {
+          root: string
+          logo: string
+        }
       }
     }
     framework: PackagePaths

package/src/api/config/load.ts

@@ -1,7 +1,7 @@
 import type { SelfContainedModeHooksData } from '#cli/_/self-contained-mode'
 import { assertOptionalPathAbsolute, pickFirstPathExisting } from '#lib/kit-temp'
 import { packagePaths } from '#package-paths'
-import { debug } from '#singletons/debug'
+import { debugPolen } from '#singletons/debug'
 import type { Prom } from '@wollybeard/kit'
 import { Path } from '@wollybeard/kit'
 import * as Module from 'node:module'
@@ -20,7 +20,7 @@ export interface LoadOptions {
 let isSelfContainedModeRegistered = false
 
 export const load = async (options: LoadOptions): Promise<ConfigInput> => {
-  const _debug = debug.sub(`load`)
+  const debug = debugPolen.sub(`load`)
   assertOptionalPathAbsolute(options.dir)
 
   //
@@ -35,7 +35,7 @@ export const load = async (options: LoadOptions): Promise<ConfigInput> => {
     const initializeData: SelfContainedModeHooksData = {
       projectDirPathExp: options.dir,
     }
-    _debug(`register node module hooks`, { data: initializeData })
+    debug(`register node module hooks`, { data: initializeData })
     // TODO: would be simpler to use sync hooks
     // https://nodejs.org/api/module.html#synchronous-hooks-accepted-by-moduleregisterhooks
     // Requires NodeJS 22.15+ -- which is not working with PW until its next release.
@@ -67,7 +67,7 @@ export const load = async (options: LoadOptions): Promise<ConfigInput> => {
       // eslint-disable-next-line
       module = await import(filePath)
     }
-    _debug(`imported config module`)
+    debug(`imported config module`)
 
     //       // Use dynamic import with file URL to support Windows
     //       const configUrl = pathToFileURL(configPath).href
@@ -97,7 +97,7 @@ export const load = async (options: LoadOptions): Promise<ConfigInput> => {
     configInput.advanced.isSelfContainedMode = true
   }
 
-  _debug(`loaded config input`, configInput)
+  debug(`loaded config input`, configInput)
 
   return configInput
 }

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

@@ -1,4 +1,4 @@
-import { debug } from '#singletons/debug'
+import { debugPolen } from '#singletons/debug'
 import { type ConfigInput, normalizeInput } from '../config/configurator.ts'
 import { load, type LoadOptions } from '../config/load.ts'
 import { mergeInputs } from '../config/merge.ts'
@@ -12,7 +12,7 @@ export const fromFile = async (options: ResolveFromFileOptions): Promise<ViteUse
   const configInput = await load(options)
   const configInputMerged = mergeInputs(configInput, options.overrides)
   const config = await fromMemory(configInputMerged, options.dir)
-  debug(`resolved config`, config)
+  debugPolen(`resolved config`, config)
   return config
 }
 

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

@@ -0,0 +1,6 @@
+export * from './metadata.ts'
+export * from './navbar.ts'
+export * from './page.ts'
+export * from './scan.ts'
+export * from './sidebar.ts'
+export * from './utils.ts'

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

@@ -0,0 +1,72 @@
+import { Fs, Path } from '@wollybeard/kit'
+import { afterEach, beforeEach, describe, expect, test } from 'vitest'
+import { Content } from './$.ts'
+
+describe('content', () => {
+  let testDir: string
+
+  beforeEach(async () => {
+    testDir = await Fs.makeTemporaryDirectory()
+  })
+
+  afterEach(async () => {
+    if (testDir && await Fs.exists(testDir)) {
+      await Fs.remove(testDir)
+    }
+  })
+
+  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)
+    })
+  })
+
+  describe('scan', () => {
+    test('scans directory and extracts metadata', async () => {
+      const filePath = Path.join(testDir, 'page.md')
+      await Fs.write({
+        path: filePath,
+        content: `---
+description: Page description
+---
+Content`,
+      })
+
+      const result = await Content.scan({
+        dir: testDir,
+        glob: '**/*.md',
+      })
+
+      expect(result.list).toHaveLength(1)
+      expect(result.list[0]?.metadata).toEqual({
+        description: 'Page description',
+        hidden: false,
+      })
+      expect(result.diagnostics).toEqual([])
+    })
+  })
+})

package/src/api/content/$.ts

@@ -0,0 +1 @@
+export * as Content from './$$.ts'

package/src/api/content/metadata.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod/v4'
+
+/**
+ * Schema for validating front matter content
+ */
+export const MetadataSchema = z.object({
+  description: z.string().optional(),
+  hidden: z.boolean().default(false),
+})
+
+export type Metadata = z.infer<typeof MetadataSchema>

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

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest'
+import { createNavbar } from './navbar.ts'
+import type { Page } from './page.ts'
+
+const createPage = (path: string[], fileName = 'index', hidden = false): Page => ({
+  route: {
+    id: path.join('/'),
+    parentId: path.length > 1 ? path.slice(0, -1).join('/') : null,
+    logical: { path },
+    file: {
+      path: {
+        absolute: { root: '/', dir: `/pages/${path.join('/')}`, base: `${fileName}.md`, ext: '.md', name: fileName },
+        relative: { root: '', dir: path.join('/'), base: `${fileName}.md`, ext: '.md', name: fileName },
+      },
+    },
+  },
+  metadata: { description: undefined, hidden },
+})
+
+describe('createNavbar', () => {
+  it('returns empty for empty input', () => {
+    expect(createNavbar([])).toEqual([])
+  })
+
+  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' }])
+  })
+
+  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' }])
+  })
+
+  it('excludes directories without index pages', () => {
+    const pages = [createPage(['guide', 'intro'], 'intro')]
+    const result = createNavbar(pages)
+    expect(result).toEqual([])
+  })
+
+  it('includes single top-level pages', () => {
+    const pages = [createPage(['about'], 'about')]
+    const result = createNavbar(pages)
+    expect(result).toEqual([{ pathExp: '/about', title: 'About' }])
+  })
+
+  it('sorts results alphabetically', () => {
+    const pages = [createPage(['zebra'], 'zebra'), createPage(['alpha'], 'alpha')]
+    const result = createNavbar(pages)
+    expect(result[0]!.title).toBe('Alpha')
+    expect(result[1]!.title).toBe('Zebra')
+  })
+})

package/src/api/content/navbar.ts

@@ -0,0 +1,61 @@
+import { Str } from '@wollybeard/kit'
+import type { Page } from './page.ts'
+
+export interface NavbarItem {
+  pathExp: string
+  title: string
+}
+
+/**
+ * Generate navbar items from a list of pages
+ */
+export const createNavbar = (pages: Page[]): NavbarItem[] => {
+  const navbarItems: NavbarItem[] = []
+
+  // Group pages by their top-level directory/segment
+  const topLevelGroups = new Map<string, Page[]>()
+
+  pages.forEach(page => {
+    // Skip hidden pages
+    if (page.metadata.hidden) return
+
+    const firstSegment = page.route.logical.path[0]
+    if (firstSegment) {
+      if (!topLevelGroups.has(firstSegment)) {
+        topLevelGroups.set(firstSegment, [])
+      }
+      topLevelGroups.get(firstSegment)!.push(page)
+    }
+  })
+
+  // Add each top-level group to navbar
+  topLevelGroups.forEach((pages, segment) => {
+    // For directories, check if there's an index page
+    const indexPage = pages.find(p =>
+      p.route.logical.path.length === 1
+      && p.route.file.path.relative.name === 'index'
+    )
+
+    // For single non-index files at top level
+    const singlePage = pages.length === 1 && pages[0]!.route.logical.path.length === 1
+      && pages[0]!.route.file.path.relative.name !== 'index'
+
+    // Include in navbar if:
+    // 1. It's a directory with an index page, OR
+    // 2. It's a single top-level page (not index)
+    if (indexPage || singlePage) {
+      const title = Str.titlizeSlug(segment)
+      const pathExp = `/${segment}`
+
+      navbarItems.push({
+        pathExp,
+        title,
+      })
+    }
+  })
+
+  // Sort navbar items alphabetically for consistency
+  navbarItems.sort((a, b) => a.title.localeCompare(b.title))
+
+  return navbarItems
+}

package/src/api/content/page.ts

@@ -0,0 +1,12 @@
+import type { FileRouter } from '#lib/file-router/index'
+import type { Metadata } from './metadata.ts'
+
+export type { Metadata }
+
+/**
+ * A route with its associated metadata
+ */
+export interface Page {
+  route: FileRouter.Route
+  metadata: Metadata
+}

package/src/api/content/scan.ts

@@ -0,0 +1,117 @@
+import { FileRouter } from '#lib/file-router/index'
+import { Fs, Path, Tree } from '@wollybeard/kit'
+import matter from 'gray-matter'
+import { MetadataSchema } from './metadata.ts'
+import type { Page } from './page.ts'
+
+export interface ScanResult {
+  list: Page[]
+  tree: Tree.Tree<Page>
+  diagnostics: FileRouter.Diagnostic[]
+}
+
+/**
+ * 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: {
+  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}',
+  })
+
+  // 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(''),
+          },
+        },
+        logical: {
+          path: [],
+        },
+      },
+      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__',
+    }))
+
+    tree = Tree.fromList([virtualRoot, ...pagesWithVirtualRoot])
+  } else {
+    tree = Tree.fromList(pagesWithIds)
+  }
+
+  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 } }
+  }
+
+  // Parse front matter
+  const { data } = matter(fileContent)
+
+  // Validate and parse the data
+  const parsed = MetadataSchema.safeParse(data)
+
+  if (!parsed.success) {
+    // Log warning but continue with defaults
+    console.warn(`Invalid front matter in ${filePath}:`, parsed.error.issues)
+  }
+
+  const metadata = parsed.success ? parsed.data : { hidden: false }
+  return { route, metadata }
+}