polen 0.9.1-next.1 → 0.10.0-next.10

package/src/api/vite/plugins/pages.ts

@@ -1,36 +1,34 @@
 import type { Config } from '#api/config/index'
+import { Content } from '#api/content/$'
+import { createNavbar } from '#api/content/navbar'
 import type { NavbarDataRegistry } from '#api/vite/data/navbar'
 import { polenVirtual } from '#api/vite/vi'
 import type { Vite } from '#dep/vite/index'
 import { reportDiagnostics } from '#lib/file-router/diagnostic-reporter'
 import { FileRouter } from '#lib/file-router/index'
-import { Tree } from '#lib/tree/index'
-import { debug } from '#singletons/debug'
+import { debugPolen } from '#singletons/debug'
 import { superjson } from '#singletons/superjson'
 import mdx from '@mdx-js/rollup'
 import rehypeShiki from '@shikijs/rehype'
-import { Path, Str } from '@wollybeard/kit'
+import { Arr, Cache, Path, Str } from '@wollybeard/kit'
+import remarkFrontmatter from 'remark-frontmatter'
 import remarkGfm from 'remark-gfm'
 
-const _debug = debug.sub(`vite-plugin-pages`)
+const debug = debugPolen.sub(`vite-plugin-pages`)
 
-export const viProjectPages = polenVirtual([`project`, `pages.jsx`], { allowPluginProcessing: true })
-export const viProjectPagesData = polenVirtual([`project`, `data`, 'pages.jsonsuper'], { allowPluginProcessing: true })
+export const viProjectRoutes = polenVirtual([`project`, `routes.jsx`], { allowPluginProcessing: true })
+export const viProjectPagesCatalog = polenVirtual([`project`, `data`, 'pages-catalog.jsonsuper'], {
+  allowPluginProcessing: true,
+})
 
-export interface PagesTreePluginOptions {
+export interface Options {
   config: Config.Config
   navbarData?: NavbarDataRegistry
-  onPagesChange?: (pages: FileRouter.ScanResult) => void
-  onTreeChange?: (tree: FileRouter.RouteTreeNode) => void
 }
 
-export interface ProjectDataPages {
-  sidebarIndex: SidebarIndex
-  pagesScanResult: FileRouter.ScanResult
-}
-
-export interface SidebarIndex {
-  [pathExpression: string]: FileRouter.Sidebar.Sidebar
+export interface ProjectPagesCatalog {
+  sidebarIndex: Content.SidebarIndex
+  pages: Content.Page[]
 }
 
 /**
@@ -39,77 +37,53 @@ export interface SidebarIndex {
 export const Pages = ({
   config,
   navbarData,
-  onPagesChange,
-  onTreeChange,
-}: PagesTreePluginOptions): Vite.Plugin[] => {
-  let currentPagesData: FileRouter.ScanResult | null = null
-  let currentTreeData: FileRouter.RouteTreeNode | null = null
-
-  // State management
-  let pagesCache: FileRouter.ScanResult | null = null
-  let treeCache: FileRouter.RouteTreeNode | null = null
-
-  // Helper functions
-  const scanPages = async () => {
-    if (!pagesCache) {
-      _debug(`Scanning pages - cache is null, loading fresh data`)
-      pagesCache = await FileRouter.scan({
-        dir: config.paths.project.absolute.pages,
-        glob: `**/*.{md,mdx}`,
-      })
-      _debug(`Found ${String(pagesCache.routes.length)} pages`)
-    } else {
-      _debug(`Using cached pages`)
+}: Options): Vite.Plugin[] => {
+  const scanPages = Cache.memoize(debug.trace(async function scanPages() {
+    const result = await Content.scan({
+      dir: config.paths.project.absolute.pages,
+      glob: `**/*.{md,mdx}`,
+    })
+    return result
+  }))
+
+  const invalidateVirtualModules = (server: Vite.ViteDevServer) => {
+    const routesModule = server.moduleGraph.getModuleById(viProjectRoutes.id)
+    if (routesModule) {
+      server.moduleGraph.invalidateModule(routesModule)
+      debug(`Invalidated routes virtual module`)
     }
-    return pagesCache
-  }
 
-  const scanTree = async () => {
-    if (!treeCache) {
-      _debug(`Scanning tree - cache is null, loading fresh data`)
-      const result = await FileRouter.scanTree({
-        dir: config.paths.project.absolute.pages,
-        glob: `**/*.{md,mdx}`,
-      })
-      treeCache = result.routeTree
-      _debug(`Built route tree`)
-    } else {
-      _debug(`Using cached tree`)
+    const catalogModule = server.moduleGraph.getModuleById(viProjectPagesCatalog.id)
+    if (catalogModule) {
+      server.moduleGraph.invalidateModule(catalogModule)
+      debug(`Invalidated pages catalog virtual module`)
     }
-    return treeCache
-  }
-
-  const clearCache = () => {
-    _debug(`Clearing pages and tree cache`)
-    pagesCache = null
-    treeCache = null
   }
 
-  const isPageFile = (file: string) => {
-    return (file.endsWith(`.md`) || file.endsWith(`.mdx`))
-      && file.includes(config.paths.project.absolute.pages)
-  }
-
-  const generatePagesModule = (pagesScanResult: FileRouter.ScanResult): string => {
+  const generateRoutesModule = (pages: Content.Page[]): string => {
     const $ = {
-      pages: `pages`,
+      routes: `routes`,
     }
 
     const s = Str.Builder()
-    s`export const ${$.pages} = []`
+    s`export const ${$.routes} = []`
 
     // Generate imports and route objects
-    for (const route of pagesScanResult.routes) {
+    for (const { route, metadata } of pages) {
       const filePathExp = Path.format(route.file.path.absolute)
       const pathExp = FileRouter.routeToPathExpression(route)
-      const ident = Str.Case.camel(`page ` + Str.titlizeSlug(pathExp))
+      const $$ = {
+        ...$,
+        Component: Str.Case.camel(`page ` + Str.titlizeSlug(pathExp)),
+      }
 
       s`
-        import ${ident} from '${filePathExp}'
+        import ${$$.Component} from '${filePathExp}'
 
-        ${$.pages}.push({
+        ${$$.routes}.push({
           path: '${pathExp}',
-          Component: ${ident}
+          Component: ${$$.Component},
+          metadata: ${JSON.stringify(metadata)}
         })
       `
     }
@@ -123,7 +97,11 @@ export const Pages = ({
       enforce: `pre` as const,
       ...mdx({
         jsxImportSource: `polen/react`,
-        remarkPlugins: [remarkGfm],
+        remarkPlugins: [
+          // Parse frontmatter blocks so they're removed from content
+          remarkFrontmatter,
+          remarkGfm,
+        ],
         rehypePlugins: [
           [
             rehypeShiki,
@@ -150,66 +128,77 @@ export const Pages = ({
       // Dev server configuration
       configureServer(server) {
         // Add pages directory to watcher
-        _debug(`configureServer: watch pages directory`, config.paths.project.absolute.pages)
+        debug(`configureServer: watch pages directory`, config.paths.project.absolute.pages)
         server.watcher.add(config.paths.project.absolute.pages)
-      },
 
-      // Hot update handling
-      async handleHotUpdate({ file, server, modules }) {
-        _debug(`handleHotUpdate`, file)
-        if (!isPageFile(file)) return
+        // Handle file additions and deletions
+        const handleFileStructureChange = async (file: string, event: 'add' | 'unlink') => {
+          if (!Content.isPageFile(file, config.paths.project.absolute.pages)) return
 
-        _debug(`Page file changed:`, file)
+          debug(`Page file ${event === 'add' ? 'added' : 'deleted'}:`, file)
 
-        // Check if this is a content-only change to an existing page
-        const oldPages = pagesCache
+          // Clear cache and rescan
+          scanPages.clear()
+          const newScanResult = await scanPages()
 
-        // Clear cache and rescan
-        clearCache()
-        const newPages = await scanPages()
-        currentPagesData = newPages
-
-        // Check if page structure changed (added/removed pages)
-        const structureChanged = !oldPages
-          || oldPages.routes.length !== newPages.routes.length
-          || !oldPages.routes.every((oldRoute, i) =>
-            oldRoute.file.path.absolute === newPages.routes[i]?.file.path.absolute
-          )
-
-        if (structureChanged) {
-          _debug(`Page structure changed, triggering full reload`)
-
-          // Invalidate virtual module
-          const mod = server.moduleGraph.getModuleById(viProjectPages.id)
-          if (mod) {
-            server.moduleGraph.invalidateModule(mod)
-            _debug(`Invalidated pages virtual module`)
-          }
+          // Invalidate virtual modules
+          invalidateVirtualModules(server)
 
-          // Notify about changes
-          if (onPagesChange) {
-            reportDiagnostics(newPages.diagnostics)
-            onPagesChange(newPages)
-          }
+          // Report any diagnostics
+          reportDiagnostics(newScanResult.diagnostics)
 
-          if (onTreeChange) {
-            const tree = await scanTree()
-            onTreeChange(tree)
-            currentTreeData = tree
-          }
+          // Trigger full reload to ensure routes are updated
+          server.ws.send({ type: 'full-reload' })
+        }
+
+        server.watcher.on('add', (file) => handleFileStructureChange(file, 'add'))
+        server.watcher.on('unlink', (file) => handleFileStructureChange(file, 'unlink'))
+      },
 
-          // Trigger full reload for structure changes
-          server.ws.send({ type: `full-reload` })
-          return []
-        } else {
-          _debug(`Page content changed, allowing HMR`)
+      // Hot update handling for existing files
+      async handleHotUpdate({ file, server, modules }) {
+        debug(`handleHotUpdate`, file)
+        if (!Content.isPageFile(file, config.paths.project.absolute.pages)) return
+
+        debug(`Page file changed:`, file)
+
+        // Get current pages before clearing cache
+        const oldPages = await scanPages()
+
+        // Clear cache and rescan
+        scanPages.clear()
+        const newScanResult = await scanPages()
+
+        // Check if the visible pages list changed. This can happen when:
+        // - A page's frontmatter `hidden` field changes (true <-> false)
+        // - A page's frontmatter affects its route (though we don't support this yet)
+        // If only the content changed (not frontmatter), we can use fast HMR.
+        const pageStructureChanged = !oldPages || !Arr.equalShallowly(
+          oldPages.list.map(p => Path.format(p.route.file.path.absolute)),
+          newScanResult.list.map(p => Path.format(p.route.file.path.absolute)),
+        )
+
+        if (!pageStructureChanged) {
+          debug(`Page content changed, allowing HMR`)
           // Let default HMR handle the MDX file change
           return modules
         }
+
+        //
+        // ━━ Manual Invalidation
+        //
+
+        debug(`Page structure changed, triggering full reload`)
+
+        // Invalidate virtual modules and trigger reload
+        invalidateVirtualModules(server)
+        reportDiagnostics(newScanResult.diagnostics)
+        server.ws.send({ type: `full-reload` })
+        return []
       },
       resolveId(id) {
-        if (id === viProjectPagesData.id) {
-          return viProjectPagesData.resolved
+        if (id === viProjectPagesCatalog.id) {
+          return viProjectPagesCatalog.resolved
         }
       },
       load: {
@@ -217,26 +206,14 @@ export const Pages = ({
         //   id: viProjectPagesData.resolved,
         // },
         async handler(id) {
-          if (id !== viProjectPagesData.resolved) return
-          _debug(`viProjectDataPages`)
-
-          // Get pages data from the pages plugin or load initially
-          if (!currentPagesData) {
-            _debug(`loadingPagesDataInitially`)
-            currentPagesData = await FileRouter.scan({
-              dir: config.paths.project.absolute.pages,
-              glob: `**/*.{md,mdx}`,
-            })
-            // Report any diagnostics from initial scan
-            reportDiagnostics(currentPagesData.diagnostics)
-          }
-          if (!currentTreeData) {
-            _debug(`loadingTreeDataInitially`)
-            currentTreeData = await getRouteTree(config)
-          }
-          const pagesScanResult = currentPagesData
-          const routeTree = currentTreeData
-          _debug(`usingPageRoutesFromPagesPlugin`, pagesScanResult.routes.length)
+          if (id !== viProjectPagesCatalog.resolved) return
+          debug(`viProjectPagesCatalog`)
+
+          const scanResult = await scanPages()
+
+          // Report any diagnostics
+          reportDiagnostics(scanResult.diagnostics)
+          debug(`Found ${String(scanResult.list.length)} visible pages`)
 
           //
           // ━━ Build Navbar
@@ -247,78 +224,36 @@ export const Pages = ({
             const navbarPages = navbarData.get('pages')
             navbarPages.length = 0 // Clear existing
 
-            // Process first-level children as navigation items
-            for (const child of routeTree.children) {
-              if (child.value.type === 'directory') {
-                // Check if this directory has an index file
-                const hasIndex = child.children.some(c => c.value.type === 'file' && c.value.name === 'index')
-
-                if (hasIndex) {
-                  const pathExp = FileRouter.pathToExpression([child.value.name])
-                  const title = Str.titlizeSlug(child.value.name)
-                  navbarPages.push({
-                    // IMPORTANT: Always ensure paths start with '/' for React Router compatibility.
-                    // Without the leading slash, React Router treats paths as relative, which causes
-                    // hydration mismatches between SSR (where base path is prepended) and client
-                    // (where basename is configured). This ensures consistent behavior.
-                    pathExp: pathExp.startsWith('/') ? pathExp : '/' + pathExp,
-                    title,
-                  })
-                }
-              } else if (child.value.type === 'file' && child.value.name !== 'index') {
-                const pathExp = FileRouter.pathToExpression([child.value.name])
-                const title = Str.titlizeSlug(child.value.name)
-                navbarPages.push({
-                  // IMPORTANT: Always ensure paths start with '/' for React Router compatibility.
-                  // Without the leading slash, React Router treats paths as relative, which causes
-                  // hydration mismatches between SSR (where base path is prepended) and client
-                  // (where basename is configured). This ensures consistent behavior.
-                  pathExp: pathExp.startsWith('/') ? pathExp : '/' + pathExp,
-                  title,
-                })
-              }
-            }
+            const navbarItems = createNavbar(scanResult.list)
+            navbarPages.push(...navbarItems)
           }
 
           //
           // ━━ Build Sidebar
           //
 
-          const sidebarIndex: SidebarIndex = {}
-
-          // Build sidebar for each top-level directory
-          for (const child of routeTree.children) {
-            if (child.value.type === 'directory') {
-              const pathExp = `/${child.value.name}`
-              // Create a subtree starting from this directory
-              const subtree = Tree.node(child.value, child.children)
-              // Pass the directory name as base path so paths are built correctly
-              const sidebar = FileRouter.Sidebar.buildFromTree(subtree, [child.value.name])
-              _debug(`Built sidebar for ${pathExp}:`, sidebar)
-              sidebarIndex[pathExp] = sidebar
-            }
-          }
+          const sidebarIndex = Content.buildSidebarIndex(scanResult)
 
           //
           // ━━ Put It All together
           //
 
-          const projectDataPages: ProjectDataPages = {
+          const projectPagesCatalog: ProjectPagesCatalog = {
             sidebarIndex,
-            pagesScanResult: pagesScanResult,
+            pages: scanResult.list,
           }
 
           // Return just the JSON string - let the JSON plugin handle the transformation
-          return superjson.stringify(projectDataPages)
+          return superjson.stringify(projectPagesCatalog)
         },
       },
     },
-    // Plugin 4: Virtual Module for Pages Routes
+    // Plugin 3: Virtual Module for React Router Routes
     {
-      name: 'polen:pages:routes',
+      name: 'polen:routes',
       resolveId(id) {
-        if (id === viProjectPages.id) {
-          return viProjectPages.resolved
+        if (id === viProjectRoutes.id) {
+          return viProjectRoutes.resolved
         }
       },
       load: {
@@ -326,19 +261,17 @@ export const Pages = ({
         //   id: viProjectPages.resolved,
         // },
         handler: async (id) => {
-          if (id !== viProjectPages.resolved) return
+          if (id !== viProjectRoutes.resolved) return
 
-          _debug(`Loading viProjectPages virtual module`)
+          debug(`Loading viProjectRoutes virtual module`)
 
-          // Ensure we have pages data
-          if (!currentPagesData) {
-            currentPagesData = await scanPages()
-            reportDiagnostics(currentPagesData.diagnostics)
-          }
+          const scanResult = await scanPages()
+          reportDiagnostics(scanResult.diagnostics)
+          const code = generateRoutesModule(scanResult.list)
 
           // Generate the module code
           return {
-            code: generatePagesModule(currentPagesData),
+            code,
             moduleType: 'js',
           }
         },
@@ -346,12 +279,3 @@ export const Pages = ({
     },
   ]
 }
-
-// Helper to get tree
-export const getRouteTree = async (config: Config.Config): Promise<FileRouter.RouteTreeNode> => {
-  const result = await FileRouter.scanTree({
-    dir: config.paths.project.absolute.pages,
-    glob: `**/*.{md,mdx}`,
-  })
-  return result.routeTree
-}

package/src/api/vite/plugins/serve.ts

@@ -3,7 +3,7 @@ import { reportError } from '#api/server/report-error'
 import type { Hono } from '#dep/hono/index'
 import type { Vite } from '#dep/vite/index'
 import { ResponseInternalServerError } from '#lib/kit-temp'
-import { debug } from '#singletons/debug'
+import { debugPolen } from '#singletons/debug'
 import * as HonoNodeServer from '@hono/node-server'
 import { Err } from '@wollybeard/kit'
 
@@ -16,11 +16,11 @@ interface AppServerModule {
 export const Serve = (
   config: Config.Config,
 ): Vite.PluginOption => {
-  const _debug = debug.sub(`serve`)
+  const debug = debugPolen.sub(`serve`)
   let appPromise: Promise<App | Error>
 
   const reloadApp = async ({ server }: { server: Vite.ViteDevServer }): Promise<App | Error> => {
-    _debug('reloadApp')
+    debug('reloadApp')
     return server.ssrLoadModule(config.paths.framework.template.server.app)
       .then(module => module as AppServerModule)
       .then(module => module.app)
@@ -55,12 +55,12 @@ export const Serve = (
       }
     },
     handleHotUpdate({ server }) {
-      _debug('handleHotUpdate')
+      debug('handleHotUpdate')
       // Reload app server immediately in the background
       appPromise = reloadApp({ server })
     },
     async configureServer(server) {
-      _debug('configureServer')
+      debug('configureServer')
       // Initial load
       appPromise = reloadApp({ server })
 

package/src/cli/_/self-contained-mode.ts

@@ -1,7 +1,7 @@
 import type { Vite } from '#dep/vite/index'
 import { type ImportEvent, isSpecifierFromPackage } from '#lib/kit-temp'
 import { packagePaths } from '#package-paths'
-import { debug } from '#singletons/debug'
+import { debugPolen } from '#singletons/debug'
 import type * as Module from 'node:module'
 import { fileURLToPath } from 'node:url'
 
@@ -18,7 +18,7 @@ export function initialize(data: SelfContainedModeHooksData) {
 export const resolve: Module.ResolveHook = async (specifier, context, nextResolve) => {
   if (!data_) throw new Error(`Self-contained mode not initialized`)
 
-  const _debug = debug.sub(`node-module-hooks`)
+  const debug = debugPolen.sub(`node-module-hooks`)
 
   const from: ImportEvent = {
     specifier,
@@ -32,7 +32,7 @@ export const resolve: Module.ResolveHook = async (specifier, context, nextResolv
       importerPathExpOrFileUrlExp: from.context.parentURL,
     })
   ) {
-    _debug(`resolve check`, { specifier, context })
+    debug(`resolve check`, { specifier, context })
 
     const to: ImportEvent = {
       specifier: from.specifier,
@@ -43,7 +43,7 @@ export const resolve: Module.ResolveHook = async (specifier, context, nextResolv
       },
     }
 
-    _debug(`resolve`, { from, to })
+    debug(`resolve`, { from, to })
 
     await nextResolve(to.specifier, to.context)
   }
@@ -66,7 +66,7 @@ export const checkIsSelfImportFromProject = (input: {
 }
 
 export const VitePluginSelfContainedMode = ({ projectDirPathExp }: { projectDirPathExp: string }): Vite.Plugin => {
-  const d = debug.sub(`vite-plugin:self-contained-import`)
+  const d = debugPolen.sub(`vite-plugin:self-contained-import`)
 
   return {
     name: `polen:self-contained-import`,

package/src/cli/commands/static/$default.ts

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+
+import { Arr, Cli, Path, Str } from '@wollybeard/kit'
+import $ from 'ansis'
+import console from 'console'
+
+const commandsDir = import.meta.dirname
+const thisModuleName = Path.parse(import.meta.filename).name
+const cliName = `polen static`
+
+const h2 = (str: string) => {
+  return $.bold.black.bgWhiteBright(` ${str.toUpperCase()} `)
+}
+
+const code = (str: string) => {
+  if (!$.isSupported()) return `\`${str}\``
+  return $.magenta(str)
+}
+
+const s = Str.Builder()
+const allCommands = await Cli.discoverCommandPointers(commandsDir)
+const commands = allCommands.filter(_ => _.name !== thisModuleName)
+
+s``
+s`${$.bold.redBright`POLEN 🌺`} ${$.dim(`static commands`)}`
+s`Manage static builds and deployments.`
+s``
+s``
+s`${h2(`commands`)}`
+s``
+
+if (Arr.isEmpty(commands)) {
+  s`No commands available yet.`
+} else {
+  commands.forEach(command => {
+    s`${$.dim`$ ${cliName}`} ${$.cyanBright(command.name)}`
+  })
+}
+s``
+s`${$.dim`Get help for a command with ${code(`polen static <command> --help`)}`}`
+s``
+
+console.log(Str.indent(String(s)))

package/src/cli/commands/static/rebase.ts

@@ -0,0 +1,37 @@
+/* eslint-disable */
+// @ts-nocheck
+import { Api } from '#api/index'
+import { Task } from '#lib/task'
+import { Command } from '@molt/command'
+import { Err, Path } from '@wollybeard/kit'
+import { z } from 'zod'
+
+const args = Command.create()
+  .parameter(
+    `source`,
+    z.string().describe('Path to the Polen build directory to rebase'),
+  )
+  .parameter(
+    `newBasePath`,
+    z.string().describe('New base path for the build (e.g., /new-path/)'),
+  )
+  .parameter(
+    `--target -t`,
+    z.string().optional().describe('Target directory for copy mode (if not provided, mutate in place)'),
+  )
+  .parse()
+
+const plan: Api.Static.RebasePlan = args.target
+  ? {
+    changeMode: 'copy',
+    sourcePath: args.source,
+    targetPath: args.target,
+    newBasePath: args.newBasePath,
+  }
+  : {
+    changeMode: 'mutate',
+    sourcePath: args.source,
+    newBasePath: args.newBasePath,
+  }
+
+await Task.runAndExit(Api.Static.rebase, plan)

package/src/cli/commands/static.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+import { Cli, Path } from '@wollybeard/kit'
+
+const commandsDir = Path.join(import.meta.dirname, 'static')
+await Cli.dispatch(commandsDir)

package/src/exports/components.ts

@@ -0,0 +1 @@
+export * from '#template/components/content/$$'