polen 0.10.0 → 0.11.0-next.10

package/src/api/schema/read.ts

@@ -1,38 +1,104 @@
-import { Arr } from '@wollybeard/kit'
+import { Arr, Fs, Path } from '@wollybeard/kit'
 import * as DataSources from './data-sources/data-sources.js'
-import type { Schema } from './schema.js'
+import type { NonEmptyChangeSets } from './schema.js'
 
-export type DataSourceType = `file` | `directory` | `memory` | `data`
+export type DataSourceType =
+  | `file`
+  | `directory`
+  | `memory`
+  | `data`
+  | `introspection`
+  | `introspectionFile`
+  | `introspectionAuto`
+
+/**
+ * Result of schema reading with provenance tracking for file watching and debugging.
+ */
+export interface SchemaReadResult {
+  data: NonEmptyChangeSets | null
+  source: {
+    type: DataSourceType
+    /**
+     * Recreate the schema data and file after it has been deleted.
+     *
+     * This function re-fetches data from the original source and recreates
+     * the schema file on disk. Only called by file watchers after deletion.
+     *
+     * @returns Promise resolving to the recreated schema data, or null if recreation fails
+     */
+    reCreate?: () => Promise<NonEmptyChangeSets | null>
+  }
+}
 
 /**
  * Schema configuration for Polen.
+ *
+ * Polen supports multiple ways to load your GraphQL schema, from simple files
+ * to dynamic introspection. Configure which sources to use and in what order.
+ *
+ * @example
+ * ```ts
+ * // Load from a file (default)
+ * schema: {} // Looks for schema.graphql
+ *
+ * // Load via introspection
+ * schema: {
+ *   dataSources: {
+ *     introspection: {
+ *       url: 'https://api.example.com/graphql',
+ *       headers: { 'Authorization': 'Bearer token' }
+ *     }
+ *   }
+ * }
+ *
+ * // Try multiple sources in order
+ * schema: {
+ *   useDataSources: ['introspection', 'file'],
+ *   dataSources: {
+ *     introspection: { url: 'https://api.example.com/graphql' },
+ *     file: { path: './fallback-schema.graphql' }
+ *   }
+ * }
+ * ```
  */
 export interface Config {
   /**
    * Whether to enable schema loading.
    *
-   * Set to `false` to disable schema features entirely.
+   * Set to `false` to disable schema features entirely. This removes
+   * the Reference and Changelog pages from your portal.
    *
-   * @default `true`
+   * @default true
+   *
+   * @example
+   * ```ts
+   * // Disable schema features
+   * schema: { enabled: false }
+   * ```
    */
   enabled?: boolean
   /**
    * Which data sources to use for loading schemas.
    *
-   * - `file` - Load from a single SDL file
-   * - `directory` - Load multiple SDL files from a directory
+   * - `file` - Load from a single SDL file (default: `./schema.graphql`)
+   * - `directory` - Load multiple SDL files from a directory (default: `./schema/`)
    * - `memory` - Use schemas defined in configuration
    * - `data` - Use a pre-built schema object
+   * - `introspection` - Load schema via GraphQL introspection
    *
-   * If not specified, Polen will try all sources in order until one succeeds.
+   * If not specified, Polen tries all sources in this order:
+   * 1. `data` 2. `directory` 3. `file` 4. `memory` 5. `introspection`
    *
    * @example
    * ```ts
    * // Use only file source
    * useDataSources: 'file'
    *
-   * // Try multiple sources
-   * useDataSources: ['directory', 'file']
+   * // Try multiple sources in custom order
+   * useDataSources: ['introspection', 'file']
+   *
+   * // Default behavior (try all sources)
+   * // useDataSources: undefined
    * ```
    */
   useDataSources?: Arr.Maybe<DataSourceType>
@@ -55,23 +121,39 @@ export interface Config {
     /**
      * Pre-built schema object to use directly.
      */
-    data?: Schema
+    data?: NonEmptyChangeSets
+    /**
+     * Configuration for loading schema via GraphQL introspection.
+     *
+     * Introspection fetches your schema directly from a running GraphQL endpoint.
+     * The schema is saved to `schema.introspection.json` in your project root.
+     * Delete this file to force a fresh introspection on the next build.
+     *
+     * @example
+     * ```ts
+     * introspection: {
+     *   url: 'https://api.example.com/graphql',
+     *   headers: { 'Authorization': 'Bearer token' }
+     * }
+     * ```
+     */
+    introspection?: DataSources.Introspection.ConfigInput
   }
   projectRoot: string
 }
 
 export const readOrThrow = async (
   config: Config,
-): Promise<null | Schema> => {
+): Promise<SchemaReadResult> => {
   if (config.enabled === false) {
-    return null
+    return { data: null, source: { type: 'data' } }
   }
 
   const useDataSources = config.useDataSources ? Arr.sure(config.useDataSources) : null
   const usingDataSource = (dataSource: DataSourceType) => useDataSources === null || useDataSources.includes(dataSource)
 
   if (usingDataSource(`data`) && config.dataSources?.data) {
-    return config.dataSources.data
+    return { data: config.dataSources.data, source: { type: 'data' } }
   }
 
   if (usingDataSource(`directory`)) {
@@ -80,7 +162,7 @@ export const readOrThrow = async (
       ...config.dataSources?.directory,
     }
     const result = await DataSources.SchemaDirectory.readOrThrow(directoryConfig)
-    if (result) return result
+    if (result) return { data: result, source: { type: 'directory' } }
   }
 
   if (usingDataSource(`file`)) {
@@ -89,7 +171,7 @@ export const readOrThrow = async (
       ...config.dataSources?.file,
     }
     const result = await DataSources.SchemaFile.readOrThrow(fileConfig)
-    if (result) return result
+    if (result) return { data: result, source: { type: 'file' } }
   }
 
   if (usingDataSource(`memory`) && config.dataSources?.memory) {
@@ -98,8 +180,17 @@ export const readOrThrow = async (
       ...config.dataSources.memory,
     }
     const result = await DataSources.Memory.read(memoryConfig)
-    if (result) return result
+    if (result) return { data: result, source: { type: 'memory' } }
+  }
+
+  if (usingDataSource(`introspection`) && config.dataSources?.introspection) {
+    const introspectionConfig = {
+      projectRoot: config.projectRoot,
+      ...config.dataSources.introspection,
+    }
+    const result = await DataSources.Introspection.readOrThrow(introspectionConfig)
+    if (result.data) return result
   }
 
-  return null
+  return { data: null, source: { type: 'data' } }
 }

package/src/api/schema/schema.ts

@@ -4,6 +4,66 @@ export * as DataSources from './data-sources/data-sources.js'
 
 export * from './read.js'
 
-export interface Schema {
-  versions: [GraphqlChangeset.ChangeSet, ...GraphqlChangeset.ChangeSet[]]
+export * from './metadata.js'
+
+export type ChangeSets = GraphqlChangeset.ChangeSet[]
+
+export type NonEmptyChangeSets = [GraphqlChangeset.ChangeSet, ...GraphqlChangeset.ChangeSet[]]
+
+/**
+ * Changelog data structure for JSON serialization
+ */
+export interface ChangelogData {
+  changes: GraphqlChangeset.ChangeSet['changes']
+  date: string
+}
+
+/**
+ * Constants for schema versioning
+ */
+
+/**
+ * The version identifier for the latest schema
+ */
+export const VERSION_LATEST = `latest`
+
+/**
+ * Fallback version name when date parsing fails
+ */
+export const VERSION_UNKNOWN_FALLBACK = `unknown`
+
+/**
+ * Convert a date to a version string in YYYY-MM-DD format
+ */
+export const dateToVersionString = (date: Date): string => {
+  return date.toLocaleDateString('en-CA')
+}
+
+/**
+ * Determine if a version at the given index should have a changelog file.
+ * Only non-oldest versions get changelog files.
+ */
+export const shouldVersionHaveChangelog = (versionIndex: number, totalVersions: number): boolean => {
+  return versionIndex < totalVersions - 1
+}
+
+/**
+ * Convert a version string back to a Date
+ */
+export const versionStringToDate = (version: string): Date => {
+  if (version === VERSION_LATEST) {
+    return new Date()
+  }
+
+  // Use modern date parsing - the version string should be in YYYY-MM-DD format
+  // which is ISO 8601 compatible
+  const parsedDate = new Date(version + 'T00:00:00Z')
+
+  // Check if the date is valid
+  if (!isNaN(parsedDate.getTime())) {
+    return parsedDate
+  }
+
+  // Throw error for invalid dates instead of silently defaulting
+  throw new Error(`Invalid version string: ${version}`)
 }

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

@@ -0,0 +1 @@
+export * from './schema-source.js'

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>>['data'],
+      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/static/manifest.ts

@@ -5,7 +5,7 @@ export const PolenBuildManifestSchema = z.object({
   type: z.enum([`ssg`, `ssr`]),
   version: z.string(),
   basePath: z.string(),
-}).loose()
+})
 
 export type PolenBuildManifest = z.infer<typeof PolenBuildManifestSchema>
 

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

@@ -75,6 +75,9 @@ export const Build = (config: Config.Config): Vite.Plugin[] => {
           // @see https://github.com/vitejs/vite/issues/20098
           ssr: {
             noExternal: true,
+            // Exclude lightningcss from bundling due to native bindings
+            // @see https://github.com/parcel-bundler/lightningcss/issues/701
+            external: ['lightningcss'],
           },
           environments: {
             ssr: {

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[]
@@ -29,15 +35,15 @@ export const Core = (config: Config.Config): Vite.PluginOption[] => {
 
   const readSchema = async () => {
     if (schemaCache === null) {
-      const schema = await Schema.readOrThrow({
+      const schemaResult = await Schema.readOrThrow({
         ...config.schema,
         projectRoot: config.paths.project.rootDir,
       })
       // todo: augmentations scoped to a version
-      schema?.versions.forEach(version => {
+      schemaResult.data?.forEach(version => {
         SchemaAugmentation.apply(version.after, config.schemaAugmentations)
       })
-      schemaCache = schema
+      schemaCache = schemaResult
     }
     return schemaCache
   }
@@ -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 schemaResult = await readSchema()
+            return superjson.stringify(schemaResult.data)
+          },
+        },
         {
           identifier: viTemplateVariables,
           loader() {
@@ -174,18 +191,18 @@ export const Core = (config: Config.Config): Vite.PluginOption[] => {
 
             debug(`load`, { id: viProjectData.id })
 
-            const schema = await readSchema()
+            const schemaResult = await readSchema()
 
             const navbar = []
 
             // ━ Schema presence causes adding some navbar items
-            if (schema) {
+            if (schemaResult.data) {
               // 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.
               navbar.push({ pathExp: `/reference`, title: `Reference` })
-              if (schema.versions.length > 1) {
+              if (schemaResult.data.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/main.ts

@@ -2,9 +2,8 @@ import type { Config } from '#api/config/index'
 import type { Vite } from '#dep/vite/index'
 import { vitePluginSsrCss } from '@hiogawa/vite-plugin-ssr-css'
 import ViteReact from '@vitejs/plugin-react-oxc'
-import { Arr, Path } from '@wollybeard/kit'
+import { Path } from '@wollybeard/kit'
 import Inspect from 'vite-plugin-inspect'
-import Restart from 'vite-plugin-restart'
 import { Branding } from './branding.js'
 import { Build } from './build.js'
 import { Core } from './core.js'
@@ -26,13 +25,6 @@ export const Main = (
     plugins.push(plugin)
   }
 
-  if (Arr.isntEmpty(config.watch.also)) {
-    const plugin = Restart({
-      restart: config.watch.also,
-    })
-    plugins.push(plugin)
-  }
-
   plugins.push(
     ViteReact(),
     vitePluginSsrCss({