polen 0.10.0 → 0.11.0-next.1

package/src/api/schema-source/schema-source.ts

@@ -0,0 +1,189 @@
+import { Schema } from '#api/schema/index'
+import { Grafaid } from '#lib/grafaid/index'
+import type { GraphqlChangeset } from '#lib/graphql-changeset/index'
+import { astToSchema } from '#template/lib/schema-utils/schema-utils'
+import { Cache } from '@wollybeard/kit'
+import type { GraphQLSchema } from 'graphql'
+
+type WriteFile = (path: string, content: string) => Promise<void>
+
+type ReadFile = (locator: string) => Promise<string>
+
+type ClearDirectory = (path: string) => Promise<void>
+
+type RemoveFile = (path: string) => Promise<void>
+
+const NoImplementationWriteFile: WriteFile = async (path: string, content: string) => {
+  throw new Error('Write operations not supported in this environment')
+}
+
+const NoImplementationClearDirectory: ClearDirectory = async (path: string) => {
+  throw new Error('Directory operations not supported in this environment')
+}
+
+const NoImplementationRemoveFile: RemoveFile = async (path: string) => {
+  throw new Error('File removal operations not supported in this environment')
+}
+
+interface SchemaSourceConfig {
+  io: {
+    read: ReadFile
+    write?: WriteFile
+    clearDirectory?: ClearDirectory
+    removeFile?: RemoveFile
+  }
+  versions: string[]
+  assetsPath: string
+}
+
+export const createSchemaSource = (config: SchemaSourceConfig) => {
+  const getSchemaPath = (version: string) => `${config.assetsPath}/schemas/${version}.json`
+
+  const getChangelogPath = (version: string) => `${config.assetsPath}/schemas/${version}.changelog.json`
+
+  const getSchemasDirectory = () => `${config.assetsPath}/schemas`
+
+  const getMetadataPath = () => `${config.assetsPath}/schemas/metadata.json`
+
+  const ioWrite = config.io.write || NoImplementationWriteFile
+  const ioClearDirectory = config.io.clearDirectory || NoImplementationClearDirectory
+  const ioRemoveFile = config.io.removeFile || NoImplementationRemoveFile
+
+  // Memoize only the base IO read operation
+  const ioReadMemoized = Cache.memoize(config.io.read)
+
+  const get = async (version: string): Promise<GraphQLSchema> => {
+    const content = await ioReadMemoized(getSchemaPath(version))
+    const schemaAst = JSON.parse(content)
+    const schema = astToSchema(schemaAst)
+    return schema
+  }
+
+  const getChangelog = async (version: string): Promise<Schema.ChangelogData> => {
+    const content = await ioReadMemoized(getChangelogPath(version))
+    return JSON.parse(content)
+  }
+
+  const getAllChangesets = async (): Promise<GraphqlChangeset.ChangeSet[]> => {
+    const changesets: GraphqlChangeset.ChangeSet[] = []
+
+    for (let i = 0; i < config.versions.length; i++) {
+      const version = config.versions[i]
+      if (!version) continue
+
+      const schema = await get(version)
+      if (!schema) continue
+
+      // Only try to read changelog for non-oldest versions (matching writeDevAssets logic)
+      let changelogData = null
+      if (i < config.versions.length - 1) {
+        changelogData = await getChangelog(version)
+      }
+
+      if (changelogData) {
+        const prevVersion = config.versions[i + 1]
+        const prevSchema = prevVersion ? await get(prevVersion) : null
+
+        if (prevSchema) {
+          changesets.push({
+            after: schema,
+            before: prevSchema,
+            changes: changelogData.changes,
+            date: new Date(changelogData.date),
+          })
+        }
+      } else {
+        // Oldest version - no changelog, use existing utility
+        changesets.push({
+          after: schema,
+          before: Grafaid.Schema.empty,
+          changes: [],
+          date: Schema.versionStringToDate(version),
+        })
+      }
+    }
+
+    return changesets
+  }
+
+  return {
+    //
+    // Properties
+    //
+    versions: config.versions,
+    isEmpty: config.versions.length === 0,
+
+    //
+    // Methods
+    //
+    get,
+    getChangelog,
+    getAllChangesets,
+
+    // Expose the memoized reader's clear method
+    clearCache: ioReadMemoized.clear,
+
+    // Write operations (use the writer, which throws if not provided)
+    writeSchema: async (version: string, schema: GraphQLSchema) => {
+      const ast = Grafaid.Schema.AST.parse(Grafaid.Schema.print(schema))
+      await ioWrite(getSchemaPath(version), JSON.stringify(ast))
+    },
+
+    writeChangelog: async (version: string, changelog: Schema.ChangelogData) => {
+      await ioWrite(getChangelogPath(version), JSON.stringify(changelog))
+    },
+
+    // Directory operations
+    clearAllAssets: async () => {
+      await ioClearDirectory(getSchemasDirectory())
+    },
+
+    removeAsset: async (version: string) => {
+      try {
+        await ioRemoveFile(getSchemaPath(version))
+      } catch (error) {
+        // Swallow errors for file removal as requested
+      }
+
+      try {
+        await ioRemoveFile(getChangelogPath(version))
+      } catch (error) {
+        // Swallow errors for file removal as requested
+      }
+    },
+
+    writeMetadata: async (metadata: Schema.SchemaMetadata) => {
+      await ioWrite(getMetadataPath(), JSON.stringify(metadata, null, 2))
+    },
+
+    writeAllAssets: async (
+      schemaData: Awaited<ReturnType<typeof Schema.readOrThrow>>,
+      metadata: Schema.SchemaMetadata,
+    ) => {
+      if (!schemaData) return
+
+      // Write schema and changelog files
+      for (const [index, version] of schemaData.entries()) {
+        const versionName = index === 0 ? Schema.VERSION_LATEST : Schema.dateToVersionString(version.date)
+
+        // Write schema file
+        await ioWrite(
+          getSchemaPath(versionName),
+          JSON.stringify(Grafaid.Schema.AST.parse(Grafaid.Schema.print(version.after))),
+        )
+
+        // Write changelog file (except for the oldest/last version)
+        if (Schema.shouldVersionHaveChangelog(index, schemaData.length)) {
+          const changelogData = {
+            changes: version.changes,
+            date: version.date.toISOString(),
+          }
+          await ioWrite(getChangelogPath(versionName), JSON.stringify(changelogData))
+        }
+      }
+
+      // Write metadata file
+      await ioWrite(getMetadataPath(), JSON.stringify(metadata, null, 2))
+    },
+  }
+}

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

@@ -2,23 +2,29 @@ import type { Config } from '#api/config/index'
 import { Content } from '#api/content/$'
 import { createNavbar } from '#api/content/navbar'
 import { VitePluginSelfContainedMode } from '#cli/_/self-contained-mode'
+import { Hono } from '#dep/hono/index'
 import type { ReactRouter } from '#dep/react-router/index'
 import type { Vite } from '#dep/vite/index'
 import { VitePluginJson } from '#lib/vite-plugin-json/index'
 import { ViteVirtual } from '#lib/vite-virtual/index'
 import { debugPolen } from '#singletons/debug'
 import { superjson } from '#singletons/superjson'
+import * as HonoNodeServer from '@hono/node-server'
+import { serveStatic } from '@hono/node-server/serve-static'
 import { Json, Str } from '@wollybeard/kit'
+import * as NodePath from 'node:path'
 import type { ProjectData } from '../../../project-data.js'
 import { SchemaAugmentation } from '../../schema-augmentation/index.js'
 import { Schema } from '../../schema/index.js'
 import { createLogger } from '../logger.js'
 import { polenVirtual } from '../vi.js'
 import { Pages } from './pages.js'
+import { SchemaAssets } from './schema-assets.js'
 
 const viTemplateVariables = polenVirtual([`template`, `variables`])
 const viTemplateSchemaAugmentations = polenVirtual([`template`, `schema-augmentations`])
 export const viProjectData = polenVirtual([`project`, `data.jsonsuper`], { allowPluginProcessing: true })
+export const viProjectSchema = polenVirtual([`project`, `schema.jsonsuper`], { allowPluginProcessing: true })
 
 export interface ProjectRoutesModule {
   routes: ReactRouter.RouteObject[]
@@ -34,7 +40,7 @@ export const Core = (config: Config.Config): Vite.PluginOption[] => {
         projectRoot: config.paths.project.rootDir,
       })
       // todo: augmentations scoped to a version
-      schema?.versions.forEach(version => {
+      schema?.forEach(version => {
         SchemaAugmentation.apply(version.after, config.schemaAugmentations)
       })
       schemaCache = schema
@@ -68,6 +74,7 @@ export const Core = (config: Config.Config): Vite.PluginOption[] => {
 
   return [
     ...plugins,
+    SchemaAssets(config),
     /**
      * If a `polen*` import is encountered from the user's project, resolve it to the currently
      * running source code of Polen rather than the user's node_modules.
@@ -133,11 +140,11 @@ export const Core = (config: Config.Config): Vite.PluginOption[] => {
             __BUILD_ARCHITECTURE_SSG__: Json.encode(config.build.architecture === `ssg`),
             'process.env.NODE_ENV': Json.encode(config.advanced.debug ? 'development' : 'production'),
           },
-          customLogger: createLogger(config),
+          // customLogger: createLogger(config),
           esbuild: false,
           build: {
             target: `esnext`,
-            assetsDir: config.paths.project.relative.build.relative.assets,
+            assetsDir: config.paths.project.relative.build.relative.assets.root,
             rollupOptions: {
               treeshake: {
                 // Aggressive tree-shaking for smallest bundles
@@ -153,6 +160,16 @@ export const Core = (config: Config.Config): Vite.PluginOption[] => {
         }
       },
       ...ViteVirtual.IdentifiedLoader.toHooks(
+        {
+          identifier: viProjectSchema,
+          async loader() {
+            const debug = debugPolen.sub(`module-project-schema`)
+            debug(`load`, { id: viProjectSchema.id })
+
+            const schema = await readSchema()
+            return superjson.stringify(schema)
+          },
+        },
         {
           identifier: viTemplateVariables,
           loader() {
@@ -185,7 +202,7 @@ export const Core = (config: Config.Config): Vite.PluginOption[] => {
               // hydration mismatches between SSR (where base path is prepended) and client
               // (where basename is configured). This ensures consistent behavior.
               navbar.push({ pathExp: `/reference`, title: `Reference` })
-              if (schema.versions.length > 1) {
+              if (schema.length > 1) {
                 navbar.push({ pathExp: `/changelog`, title: `Changelog` })
               }
             }
@@ -204,22 +221,10 @@ export const Core = (config: Config.Config): Vite.PluginOption[] => {
             //
 
             const projectData: ProjectData = {
-              schema,
               basePath: config.build.base,
-              paths: config.paths.project,
+              paths: config.paths,
               navbar, // Complete navbar with schema and pages
-              server: {
-                port: config.server.port,
-                static: {
-                  // todo
-                  // relative from CWD of process that boots n1ode server
-                  // can easily break! Use path relative in server??
-                  directory: `./` + config.paths.project.relative.build.root,
-                  // Uses Hono route syntax - includes base path
-                  route: config.build.base.slice(0, -1) + `/` + config.paths.project.relative.build.relative.assets
-                    + `/*`,
-                },
-              },
+              server: config.server,
               warnings: config.warnings,
             }
 

package/src/api/vite/plugins/schema-assets.ts

@@ -0,0 +1,317 @@
+import type { Config } from '#api/config/index'
+import { SchemaAugmentation } from '#api/schema-augmentation/index'
+import { createSchemaSource } from '#api/schema-source/index'
+import { Schema } from '#api/schema/index'
+import type { Vite } from '#dep/vite/index'
+import { Grafaid } from '#lib/grafaid/index'
+import { ViteVirtual } from '#lib/vite-virtual/index'
+import { debugPolen } from '#singletons/debug'
+import { Cache } from '@wollybeard/kit'
+import * as NodeFs from 'node:fs/promises'
+import * as NodePath from 'node:path'
+import { polenVirtual } from '../vi.js'
+
+export const viProjectSchemaMetadata = polenVirtual([`project`, `schema-metadata`])
+
+/**
+ * Vite plugin that generates JSON assets for GraphQL schemas at build time.
+ *
+ * This plugin:
+ * - Reads GraphQL schema files from the project
+ * - Applies schema augmentations
+ * - Converts schemas to AST format and emits as JSON assets
+ * - Creates a metadata file with available versions
+ * - Provides a virtual module for accessing schema metadata
+ *
+ * The generated assets enable client-side loading of different schema versions
+ * without requiring all schemas to be bundled into the main JavaScript bundle.
+ *
+ * @param config - Polen configuration object
+ * @returns Vite plugin instance
+ */
+export const SchemaAssets = (config: Config.Config): Vite.Plugin => {
+  const debug = debugPolen.sub(`vite-plugin:schema-assets`)
+  let viteServer: Vite.ViteDevServer | null = null
+
+  // Helper to load and process schema data
+  const loadAndProcessSchemaData = Cache.memoize(async () => {
+    const schemaData = await Schema.readOrThrow({
+      ...config.schema,
+      projectRoot: config.paths.project.rootDir,
+    })
+
+    if (!schemaData) {
+      const metadata: Schema.SchemaMetadata = { hasSchema: false, versions: [] }
+      return {
+        schemaData: null,
+        metadata,
+      }
+    }
+
+    // Apply augmentations
+    schemaData.forEach(version => {
+      SchemaAugmentation.apply(version.after, config.schemaAugmentations)
+    })
+
+    // Build metadata
+    const versionStrings: string[] = []
+    for (const [index, version] of schemaData.entries()) {
+      const versionName = index === 0 ? Schema.VERSION_LATEST : Schema.dateToVersionString(version.date)
+      versionStrings.push(versionName)
+    }
+
+    const metadata = {
+      hasSchema: true,
+      versions: versionStrings,
+    }
+
+    debug(`schemaDataLoaded`, { versionCount: schemaData.length })
+
+    return {
+      schemaData,
+      metadata,
+    }
+  })
+
+  // Helper to create schema source with filesystem IO
+  const createDevSchemaSource = (metadata: Schema.SchemaMetadata) => {
+    return createSchemaSource({
+      io: {
+        read: async () => {
+          throw new Error('Read not supported in dev asset writer')
+        },
+        write: async (path: string, content: string) => {
+          await NodeFs.writeFile(path, content, 'utf-8')
+        },
+        clearDirectory: async (path: string) => {
+          try {
+            const files = await NodeFs.readdir(path)
+            await Promise.all(files.map(file => NodeFs.rm(NodePath.join(path, file), { force: true })))
+          } catch (error) {
+            // Directory might not exist, which is fine
+          }
+        },
+        removeFile: async (path: string) => {
+          await NodeFs.rm(path, { force: true })
+        },
+      },
+      versions: metadata.versions,
+      assetsPath: config.paths.framework.devAssets.absolute,
+    })
+  }
+
+  // Helper to write assets using schema-source API
+  const writeDevAssets = async (
+    schemaData: Awaited<ReturnType<typeof Schema.readOrThrow>>,
+    metadata: Schema.SchemaMetadata,
+  ) => {
+    if (!schemaData) return
+
+    const devAssetsDir = config.paths.framework.devAssets.schemas
+    await NodeFs.mkdir(devAssetsDir, { recursive: true })
+
+    const schemaSource = createDevSchemaSource(metadata)
+    await schemaSource.writeAllAssets(schemaData, metadata)
+    debug(`devAssetsWritten`, { versionCount: schemaData.length })
+  }
+
+  return {
+    name: `polen:schema-assets`,
+
+    configureServer(server) {
+      viteServer = server
+
+      // Clear all assets when dev server starts
+      const clearAssets = async () => {
+        try {
+          // Create a basic schema source just for clearing
+          const schemaSource = createDevSchemaSource({ hasSchema: false, versions: [] })
+          await schemaSource.clearAllAssets()
+          debug(`devAssetsCleared`, {})
+        } catch (error) {
+          // Ignore errors during clearing
+        }
+      }
+
+      // Clear assets immediately
+      void clearAssets()
+
+      // Set up file watching for schema source files
+      if (config.schema?.dataSources?.directory?.path) {
+        // Watch the entire directory for directory mode
+        server.watcher.add(config.schema.dataSources.directory.path)
+        debug(`watchingSchemaDirectory`, { path: config.schema.dataSources.directory.path })
+      }
+
+      if (config.schema?.dataSources?.file?.path) {
+        // Watch the specific file for file mode
+        server.watcher.add(config.schema.dataSources.file.path)
+        debug(`watchingSchemaFile`, { path: config.schema.dataSources.file.path })
+      }
+
+      // Handle file removal
+      server.watcher.on('unlink', async (file) => {
+        const isSchemaFile = config.schema && (() => {
+          const absoluteFile = NodePath.resolve(file)
+
+          // Check if file path matches the configured schema file
+          if (config.schema.dataSources?.file?.path) {
+            const absoluteSchemaFile = NodePath.resolve(
+              config.paths.project.rootDir,
+              config.schema.dataSources.file.path,
+            )
+            if (absoluteFile === absoluteSchemaFile) return true
+          }
+
+          // Check if file path is within the configured schema directory
+          if (config.schema.dataSources?.directory?.path) {
+            const absoluteSchemaDir = NodePath.resolve(
+              config.paths.project.rootDir,
+              config.schema.dataSources.directory.path,
+            )
+            if (absoluteFile.startsWith(absoluteSchemaDir + NodePath.sep)) return true
+          }
+
+          return false
+        })()
+
+        if (isSchemaFile) {
+          debug(`schemaFileRemoved`, { file })
+
+          try {
+            // Clear cache and regenerate
+            loadAndProcessSchemaData.clear()
+            const { schemaData, metadata } = await loadAndProcessSchemaData()
+
+            if (schemaData) {
+              // Write new assets without the removed file
+              await writeDevAssets(schemaData, metadata)
+              debug(`hmr:schemaAssetsUpdatedAfterRemoval`, { versionCount: schemaData.length })
+            } else {
+              // No schema data - clear all assets
+              const schemaSource = createDevSchemaSource({ hasSchema: false, versions: [] })
+              await schemaSource.clearAllAssets()
+              debug(`hmr:allAssetsCleared`, {})
+            }
+          } catch (error) {
+            debug(`hmr:schemaRemovalFailed`, { error })
+          }
+
+          // Send HMR invalidation signal
+          server.ws.send({
+            type: 'custom',
+            event: 'polen:schema-invalidate',
+            data: { timestamp: Date.now() },
+          })
+
+          debug(`hmr:schemaInvalidationSent`, {})
+        }
+      })
+    },
+
+    async buildStart() {
+      debug(`buildStart`, {})
+
+      // Load and process schema data
+      const { schemaData, metadata } = await loadAndProcessSchemaData()
+
+      if (!schemaData) {
+        debug(`noSchemaFound`, {})
+        return
+      }
+
+      // Handle asset generation differently for dev vs build
+      if (viteServer) {
+        // Dev mode: Write assets directly to filesystem
+        await writeDevAssets(schemaData, metadata)
+        debug(`devMode:schemaAssetsWritten`, {})
+        return
+      }
+
+      // Build mode: Create schema source for emitting files
+      const schemaSource = createSchemaSource({
+        io: {
+          read: async () => {
+            throw new Error('Read not supported in build asset emitter')
+          },
+          write: async (path: string, content: string) => {
+            // Convert absolute path to relative filename for Vite
+            const relativePath = NodePath.relative(config.paths.framework.devAssets.absolute, path)
+            const fileName = `${config.paths.project.relative.build.relative.assets.root}/${relativePath}`
+
+            this.emitFile({
+              type: `asset`,
+              fileName,
+              source: content,
+            })
+          },
+        },
+        versions: metadata.versions,
+        assetsPath: config.paths.framework.devAssets.absolute,
+      })
+
+      // Emit all assets using the high-level API
+      await schemaSource.writeAllAssets(schemaData, metadata)
+      debug(`buildMode:allAssetsEmitted`, { versionCount: schemaData.length })
+    },
+
+    async handleHotUpdate({ file, server }) {
+      const isSchemaFile = config.schema && (() => {
+        const absoluteFile = NodePath.resolve(file)
+
+        // Check if file path matches the configured schema file
+        if (config.schema.dataSources?.file?.path) {
+          const absoluteSchemaFile = NodePath.resolve(config.paths.project.rootDir, config.schema.dataSources.file.path)
+          if (absoluteFile === absoluteSchemaFile) return true
+        }
+
+        // Check if file path is within the configured schema directory
+        if (config.schema.dataSources?.directory?.path) {
+          const absoluteSchemaDir = NodePath.resolve(
+            config.paths.project.rootDir,
+            config.schema.dataSources.directory.path,
+          )
+          if (absoluteFile.startsWith(absoluteSchemaDir + NodePath.sep)) return true
+        }
+
+        return false
+      })()
+      if (isSchemaFile) {
+        debug(`schemaFileChanged`, { file })
+
+        // Regenerate schema assets
+        try {
+          loadAndProcessSchemaData.clear()
+          const { schemaData, metadata } = await loadAndProcessSchemaData()
+
+          if (schemaData) {
+            debug(`hmr:schemaRegenerated`, { versionCount: schemaData.length })
+
+            // Write new assets to filesystem
+            await writeDevAssets(schemaData, metadata)
+          }
+        } catch (error) {
+          debug(`hmr:schemaRegenerationFailed`, { error })
+        }
+
+        // Send HMR invalidation signal
+        server.ws.send({
+          type: 'custom',
+          event: 'polen:schema-invalidate',
+          data: { timestamp: Date.now() },
+        })
+
+        debug(`hmr:schemaInvalidationSent`, {})
+      }
+    },
+
+    ...ViteVirtual.IdentifiedLoader.toHooks({
+      identifier: viProjectSchemaMetadata,
+      async loader() {
+        debug(`virtualModuleLoad`, { id: viProjectSchemaMetadata.id })
+        const { metadata } = await loadAndProcessSchemaData()
+        return `export default ${JSON.stringify(metadata)}`
+      },
+    }),
+  }
+}

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

@@ -5,16 +5,10 @@ import type { Vite } from '#dep/vite/index'
 import { createHtmlTransformer } from '#lib/html-utils/html-transformer'
 import { ResponseInternalServerError } from '#lib/kit-temp'
 import { debugPolen } from '#singletons/debug'
+import type { App, AppOptions } from '#template/server/app'
 import * as HonoNodeServer from '@hono/node-server'
 import { Err } from '@wollybeard/kit'
-
-type App = Hono.Hono
-
-interface AppOptions {
-  hooks?: {
-    transformHtml?: ((html: string, ctx: Hono.Context) => Promise<string> | string)[]
-  }
-}
+import * as NodePath from 'node:path'
 
 interface AppServerModule {
   createApp: (options: AppOptions) => App
@@ -80,6 +74,19 @@ export const Serve = (
               }),
             ],
           },
+          paths: {
+            base: config.build.base,
+            assets: {
+              // Calculate relative path from CWD to Polen's assets
+              // CWD is user's project directory where they run 'pnpm dev'
+              // Assets are in Polen's dev assets directory
+              directory: NodePath.relative(
+                process.cwd(),
+                config.paths.framework.devAssets.absolute,
+              ),
+              route: config.server.routes.assets,
+            },
+          },
         })
       })
       .catch(async (error) => {