polen 0.10.0-next.9 → 0.11.0-next.1

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

@@ -2,28 +2,93 @@ import type { Config } from '#api/config/index'
 import { reportError } from '#api/server/report-error'
 import type { Hono } from '#dep/hono/index'
 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
+import * as NodePath from 'node:path'
 
 interface AppServerModule {
-  app: App
+  createApp: (options: AppOptions) => App
 }
 
 export const Serve = (
   config: Config.Config,
 ): Vite.PluginOption => {
   const debug = debugPolen.sub(`serve`)
+  const appModulePath = config.paths.framework.template.absolute.server.app
+
   let appPromise: Promise<App | Error>
 
-  const reloadApp = async ({ server }: { server: Vite.ViteDevServer }): Promise<App | Error> => {
-    debug('reloadApp')
-    return server.ssrLoadModule(config.paths.framework.template.server.app)
+  const isNeedAppLoadOrReload = (server: Vite.ViteDevServer): boolean => {
+    const appModule = server.moduleGraph.getModuleById(appModulePath)
+    if (!appModule) return true // Not loaded yet
+
+    // Check if the module or any of its dependencies are invalidated
+    const checkInvalidated = (mod: Vite.ModuleNode, visited = new Set<string>()): boolean => {
+      if (!mod.id || visited.has(mod.id)) return false
+      visited.add(mod.id)
+
+      // Check if this module is invalidated
+      // SSR modules use ssrInvalidationState, client modules use invalidationState
+      if (mod.ssrInvalidationState === `HARD_INVALIDATED` || mod.invalidationState === `HARD_INVALIDATED`) {
+        return true
+      }
+
+      // Also check if transformResult is null (indicates invalidation)
+      if (mod.ssrTransformResult === null && mod.transformResult === null) {
+        return true
+      }
+
+      // Check all imported modules recursively
+      for (const imported of mod.importedModules) {
+        if (checkInvalidated(imported, visited)) return true
+      }
+
+      return false
+    }
+
+    return checkInvalidated(appModule)
+  }
+
+  const reloadApp = async (server: Vite.ViteDevServer): Promise<App | Error> => {
+    debug(`reloadApp`)
+
+    return server.ssrLoadModule(config.paths.framework.template.absolute.server.app)
       .then(module => module as AppServerModule)
-      .then(module => module.app)
+      .then(module => {
+        return module.createApp({
+          hooks: {
+            transformHtml: [
+              // Inject entry client script for development
+              createHtmlTransformer((html, ___ctx) => {
+                const entryClientPath = `/${config.paths.framework.template.relative.client.entrypoint}`
+                const entryClientScript = `<script type="module" src="${entryClientPath}"></script>`
+                return html.replace(`</body>`, `${entryClientScript}\n</body>`)
+              }),
+              // Apply Vite's transformations
+              createHtmlTransformer(async (html, ctx) => {
+                return await server.transformIndexHtml(ctx.req.url, html)
+              }),
+            ],
+          },
+          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) => {
         if (Err.is(error)) {
           // ━ Clean Stack Trace
@@ -41,7 +106,7 @@ export const Serve = (
     config() {
       return {
         server: {
-          port: 3000,
+          port: config.server.port,
           watch: {
             disableGlobbing: false,
           },
@@ -55,14 +120,14 @@ export const Serve = (
       }
     },
     handleHotUpdate({ server }) {
-      debug('handleHotUpdate')
+      debug(`handleHotUpdate`)
       // Reload app server immediately in the background
-      appPromise = reloadApp({ server })
+      appPromise = reloadApp(server)
     },
     async configureServer(server) {
-      debug('configureServer')
+      debug(`configureServer`)
       // Initial load
-      appPromise = reloadApp({ server })
+      appPromise = reloadApp(server)
 
       return () => {
         // Remove index.html serving middleware.
@@ -74,6 +139,11 @@ export const Serve = (
 
         // Add middleware that runs our entry server
         server.middlewares.use((req, res, ___next) => {
+          // Check if app needs reloading due to module invalidation
+          if (isNeedAppLoadOrReload(server)) {
+            appPromise = reloadApp(server)
+          }
+
           void HonoNodeServer.getRequestListener(async request => {
             // Always await the current app promise
             const app = await appPromise
@@ -81,8 +151,8 @@ export const Serve = (
               // Err.log(app)
               return ResponseInternalServerError()
             }
-            const response = await app.fetch(request, { viteDevServer: server })
-            return response
+
+            return await app.fetch(request)
           })(req, res)
         })
       }

package/src/cli/_/parameters.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod'
+
+/**
+ * Common parameter schemas for CLI commands
+ */
+
+export const projectParameter = z
+  .string()
+  .optional()
+  .describe(`The path to the project directory. Default is CWD (current working directory).`)

package/src/cli/commands/build.ts

@@ -1,12 +1,16 @@
-/* eslint-disable */
 // @ts-nocheck
 import { Api } from '#api/index'
-import { Vite } from '#dep/vite/index'
+import { projectParameter } from '#cli/_/parameters'
+import { ensureOptionalAbsoluteWithCwd } from '#lib/kit-temp'
 import { Command } from '@molt/command'
 import { z } from 'zod'
 
 const args = Command.create()
   .parameter(`--debug -d`, z.boolean().default(false))
+  .parameter(
+    `--project -p`,
+    projectParameter,
+  )
   .parameter(
     `--architecture -a`,
     Api.Config.BuildArchitecture.default('ssg').describe('Which kind of application architecture to output.'),
@@ -15,6 +19,10 @@ const args = Command.create()
     `--base -b`,
     z.string().optional().describe('Base public path for deployment (e.g., /my-project/)'),
   )
+  .parameter(
+    `--port`,
+    z.number().optional().describe('Default port for the SSR application'),
+  )
   .settings({
     parameters: {
       environment: {
@@ -28,14 +36,24 @@ const args = Command.create()
   })
   .parse()
 
-// HACK:
-// todo
-// we don't want to  lose pretty preting of defaults in Molt but
-// we don't want cli defaults to override explicit inputs in the config file either
-// we need something like setset and/or an ability in molt to show a default but then have undefined internally etc.
-// and now if user passes --no-debug/ --debug false it has no effect which is wrong since its not via default anymore, ... ugh
+const dir = ensureOptionalAbsoluteWithCwd(args.project)
+
+if (!await Api.Project.validateProjectDirectory(dir)) {
+  process.exit(1)
+}
+
 await Api.Builder.build({
-  ...(args.debug === false ? {} : { debug: args.debug }),
-  ...(args.architecture === 'ssg' ? {} : { architecture: args.architecture }),
-  ...(args.base ? { base: args.base } : {}),
+  dir,
+  overrides: {
+    build: {
+      architecture: args.architecture,
+      base: args.base,
+    },
+    server: {
+      port: args.port,
+    },
+    advanced: {
+      debug: args.debug,
+    },
+  },
 })

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

@@ -0,0 +1,7 @@
+import { consola } from 'consola'
+
+consola.info(`Available config commands:`)
+console.log(``)
+console.log(`  polen config create    Create a Polen configuration file`)
+console.log(``)
+consola.info(`Run a command to see its help.`)

package/src/cli/commands/config/create.ts

@@ -0,0 +1,42 @@
+import { Api } from '#api/index'
+import { projectParameter } from '#cli/_/parameters'
+import { ensureOptionalAbsoluteWithCwd } from '#lib/kit-temp'
+import { Command } from '@molt/command'
+import { Fs, Path } from '@wollybeard/kit'
+import consola from 'consola'
+
+const args = Command.create()
+  .parameter(
+    `--project -p`,
+    projectParameter,
+  )
+  .parse()
+
+const dir = ensureOptionalAbsoluteWithCwd(args.project)
+
+if (!await Api.Project.validateProjectDirectory(dir)) {
+  process.exit(1)
+}
+
+const fileName = 'polen.config.ts'
+const fileContent = `import { Polen } from 'polen'
+
+export default Polen.defineConfig({
+  // Your configuration options
+})
+`
+
+const filePath = Path.join(dir, fileName)
+
+const exists = await Fs.exists(filePath)
+if (exists) {
+  consola.info(`Polen configuration file already exists at ${fileName}`)
+  process.exit(0)
+}
+
+await Fs.write({
+  path: filePath,
+  content: fileContent,
+})
+
+consola.success(`Created Polen configuration file at ${fileName}`)

package/src/cli/commands/config.ts

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

package/src/cli/commands/create.ts

@@ -1,5 +1,5 @@
-/* eslint-disable */
 // @ts-nocheck
+import { Api } from '#api/index'
 import { Command } from '@molt/command'
 import { Err, Fs, Manifest, Name, Path, Str } from '@wollybeard/kit'
 import * as Ansis from 'ansis'
@@ -7,7 +7,7 @@ import consola from 'consola'
 import { z } from 'zod'
 import { $ } from 'zx'
 
-const Examples = z.enum([`github`, `pokemon`])
+const Examples = z.enum([`hive`])
 
 const args = Command
   .create()
@@ -33,7 +33,7 @@ const args = Command
     `version`,
     z.string().optional().describe(`Version of Polen to use. Defaults to latest release. Ignored if --link is used.`),
   )
-  .parameter(`example`, Examples.default(`pokemon`).describe(`The example to use to scaffold your project.`))
+  .parameter(`example`, Examples.default(`hive`).describe(`The example to use to scaffold your project.`))
   .settings({
     parameters: {
       environment: {
@@ -49,10 +49,9 @@ const args = Command
 
 const getProjectRoot = async (): Promise<string> => {
   if (args.path) {
-    const stat = await Fs.stat(args.path)
-    if (Fs.isNotFoundError(stat)) return args.path
-    if (stat.isDirectory() && await Fs.isEmptyDir(args.path)) return args.path
-    consola.error(`The given path ${args.path} already exists and is not an empty directory`)
+    if (await Api.Project.validateProjectDirectory(args.path, { mustExist: false, mustBeEmpty: true })) {
+      return args.path
+    }
     process.exit(1)
   }
 

package/src/cli/commands/dev.ts

@@ -1,10 +1,10 @@
-/* eslint-disable */
 // @ts-nocheck
 import { Api } from '#api/index'
+import { projectParameter } from '#cli/_/parameters'
 import { Vite } from '#dep/vite/index'
-import { ensureOptionalAbsolute, ensureOptionalAbsoluteWithCwd } from '#lib/kit-temp'
+import { ensureOptionalAbsoluteWithCwd } from '#lib/kit-temp'
 import { Command } from '@molt/command'
-import { Err, Path } from '@wollybeard/kit'
+import { Err } from '@wollybeard/kit'
 import { z } from 'zod'
 
 const args = Command.create()
@@ -12,12 +12,16 @@ const args = Command.create()
   .parameter(
     `--project -p`,
     // @ts-expect-error
-    z.string().optional().describe(`The path to the project directory. Default is CWD (current working directory).`),
+    projectParameter,
   )
   .parameter(
     `--base -b`,
     z.string().optional().describe('Base public path for deployment (e.g., /my-project/)'),
   )
+  .parameter(
+    `--port`,
+    z.number().optional().describe('Port to run the development server on'),
+  )
   .settings({
     parameters: {
       environment: {
@@ -31,12 +35,21 @@ const args = Command.create()
   })
   .parse()
 
-const dir = ensureOptionalAbsoluteWithCwd(args.project) as string
+const dir = ensureOptionalAbsoluteWithCwd(args.project)
+
+if (!await Api.Project.validateProjectDirectory(dir)) {
+  process.exit(1)
+}
 
 const viteUserConfig = await Api.ConfigResolver.fromFile({
   dir,
   overrides: {
-    ...(args.base ? { build: { base: args.base } } : {}),
+    build: {
+      base: args.base,
+    },
+    server: {
+      port: args.port,
+    },
     advanced: {
       debug: args.debug,
     },