polen 0.11.0-next.1 → 0.11.0-next.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polen",
-  "version": "0.11.0-next.1",
+  "version": "0.11.0-next.10",
   "type": "module",
   "description": "A framework for delightful GraphQL developer portals",
   "author": {
@@ -87,18 +87,18 @@
     "@graphql-inspector/core": "^6.2.1",
     "@graphql-tools/load": "^8.1.0",
     "@hiogawa/vite-plugin-ssr-css": "^0.0.1",
-    "@hono/node-server": "^1.15.0",
+    "@hono/node-server": "^1.16.0",
     "@mdx-js/mdx": "^3.1.0",
     "@mdx-js/react": "^3.1.0",
     "@mdx-js/rollup": "^3.1.0",
     "@radix-ui/react-icons": "^1.3.2",
     "@radix-ui/themes": "^3.2.1",
-    "@rolldown/pluginutils": "1.0.0-beta.24",
+    "@rolldown/pluginutils": "1.0.0-beta.27",
     "@rollup/pluginutils": "^5.2.0",
     "@types/jsesc": "^3.0.3",
     "@vitejs/plugin-react": "^4.6.0",
     "@vitejs/plugin-react-oxc": "^0.2.3",
-    "@vltpkg/semver": "0.0.0-16",
+    "@vltpkg/semver": "0.0.0-17",
     "@vue/reactivity": "^3.5.17",
     "@wollybeard/kit": "^0.41.0",
     "@wollybeard/projector": "^0.3.0",
@@ -107,12 +107,12 @@
     "codehike": "^1.0.7",
     "consola": "^3.4.2",
     "defu": "^6.1.4",
-    "es-toolkit": "^1.39.6",
+    "es-toolkit": "^1.39.7",
     "fuse.js": "^7.1.0",
     "graffle": "8.0.0-next.163",
     "graphql": "^16.11.0",
     "gray-matter": "^4.0.3",
-    "hono": "^4.8.4",
+    "hono": "^4.8.5",
     "jsesc": "^3.1.0",
     "jsonc-parser": "^3.3.1",
     "react": "^19.1.0",
@@ -126,22 +126,21 @@
     "remark-parse": "^11.0.0",
     "remark-rehype": "^11.1.2",
     "resolve.imports": "^2.0.3",
-    "rolldown": "1.0.0-beta.24",
+    "rolldown": "1.0.0-beta.27",
     "simple-git": "^3.28.0",
     "source-map": "^0.7.4",
     "superjson": "^2.2.2",
     "tinyglobby": "^0.2.14",
-    "tree-sitter-graphql-grammar-wasm": "^1.0.0",
+    "tree-sitter-graphql-grammar-wasm": "^1.1.0",
     "tsx": "^4.20.3",
     "typescript": "^5.8.3",
     "unified": "^11.0.5",
     "vfile": "^6.0.3",
-    "vite": "npm:rolldown-vite@^7.0.4",
+    "vite": "npm:rolldown-vite@^7.0.9",
     "vite-plugin-inspect": "^11.3.0",
-    "vite-plugin-restart": "^0.4.2",
-    "web-tree-sitter": "^0.25.6",
+    "web-tree-sitter": "^0.25.8",
     "youch-core": "^0.3.3",
-    "zx": "8.6.1"
+    "zx": "8.7.1"
   },
   "devDependencies": {
     "@actions/core": "^1.11.1",
@@ -151,15 +150,15 @@
     "@actions/io": "^1.1.3",
     "@changesets/cli": "^2.29.5",
     "@molt/command": "^0.9.0",
-    "@octokit/core": "^7.0.2",
+    "@octokit/core": "^7.0.3",
     "@octokit/types": "^14.1.0",
-    "@playwright/browser-chromium": "^1.53.2",
+    "@playwright/browser-chromium": "^1.54.1",
     "@testing-library/react": "^16.3.0",
     "@tsconfig/node-lts": "^22.0.2",
     "@tsconfig/node22": "^22.0.2",
     "@tsconfig/strictest": "^2.0.5",
     "@types/jsdom": "^21.1.7",
-    "@types/node": "^24.0.10",
+    "@types/node": "^24.0.14",
     "@types/react": "^19.1.8",
     "@types/react-dom": "^19.1.6",
     "@types/semver": "^7.7.0",
@@ -167,10 +166,10 @@
     "dripip": "^0.10.0",
     "fast-check": "^4.2.0",
     "fs-jetpack": "^5.1.0",
-    "get-port-please": "^3.1.2",
+    "get-port-please": "^3.2.0",
     "globals": "^16.3.0",
     "jsdom": "^26.1.0",
-    "playwright": "1.53.2",
+    "playwright": "1.54.1",
     "publint": "^0.3.12",
     "semver": "^7.7.2",
     "strip-ansi": "^7.1.0",

package/src/api/config/configurator.ts

@@ -31,25 +31,56 @@ export interface ConfigInput {
    * - `file` - Load from a single SDL file (default: schema.graphql)
    * - `directory` - Load multiple SDL files with date prefixes (enables changelog)
    * - `memory` - Define schemas programmatically in configuration
+   * - `introspection` - Fetch schema from a GraphQL endpoint
+   * - `data` - Use pre-built schema objects
    *
    * @example
    * ```ts
-   * // Single file
+   * // Default: looks for schema.graphql
+   * schema: {}
+   *
+   * // Load via introspection
    * schema: {
-   *   useDataSources: 'file',
    *   dataSources: {
-   *     file: { path: './my-schema.graphql' }
+   *     introspection: {
+   *       url: 'https://api.example.com/graphql',
+   *       headers: { 'Authorization': `Bearer ${process.env.API_TOKEN}` }
+   *     }
    *   }
    * }
    *
    * // Multiple versions for changelog
    * schema: {
-   *   useDataSources: 'directory',
    *   dataSources: {
    *     directory: { path: './schema' }
    *   }
    * }
+   *
+   * // Custom source order
+   * schema: {
+   *   useDataSources: ['introspection', 'file'],
+   *   dataSources: {
+   *     introspection: { url: 'https://api.example.com/graphql' },
+   *     file: { path: './fallback.graphql' }
+   *   }
+   * }
    * ```
+   *
+   * **Two introspection features**:
+   * 1. **File Convention**: Polen auto-detects `schema.introspection.json` files
+   * 2. **Config-driven**: Polen fetches and caches introspection for you
+   *
+   * **Interoperability**: The `schema.introspection.json` file uses the standard
+   * GraphQL introspection format, compatible with GraphQL Codegen, Apollo CLI, etc.
+   *
+   * **Lifecycle**:
+   * - First run: Fetches from endpoint, saves to `schema.introspection.json`
+   * - Subsequent runs: Loads from JSON file (no network request)
+   * - To refresh: Delete the JSON file
+   * - Runs during `polen dev` and `polen build`, never at runtime
+   *
+   * **Query details**: Uses the standard introspection query from the GraphQL spec
+   * @see https://spec.graphql.org/draft/#sec-Introspection
    */
   schema?: SchemaConfigInput
   /**
@@ -240,22 +271,6 @@ export interface ConfigInput {
      * @default false
      */
     isSelfContainedMode?: boolean
-    /**
-     * Tweak the watch behavior.
-     */
-    watch?: {
-      /**
-       * Restart the development server when some arbitrary files change.
-       *
-       * Use this to restart when files that are not already watched by vite change.
-       *
-       * @see https://github.com/antfu/vite-plugin-restart
-       */
-      /**
-       * File paths to watch and restart the development server when they change.
-       */
-      also?: string[]
-    }
     /**
      * Whether to enable debug mode.
      *
@@ -357,9 +372,6 @@ export interface Config {
       assets: string
     }
   }
-  watch: {
-    also: string[]
-  }
   templateVariables: TemplateVariables
   schemaAugmentations: SchemaAugmentation.Augmentation[]
   schema: null | SchemaConfigInput
@@ -431,9 +443,6 @@ const configInputDefaults: Config = {
     title: `My Developer Portal`,
   },
   schemaAugmentations: [],
-  watch: {
-    also: [],
-  },
   build: {
     architecture: BuildArchitecture.enum.ssg,
     base: `/`,
@@ -541,10 +550,6 @@ export const normalizeInput = async (
     config.advanced.explorer = configInput.advanced.explorer
   }
 
-  if (configInput?.advanced?.watch?.also) {
-    config.watch.also = configInput.advanced.watch.also
-  }
-
   if (configInput?.server?.port !== undefined) {
     config.server.port = configInput.server.port
   }

package/src/api/config/merge.ts

@@ -48,22 +48,6 @@ export const mergeInputs = (
   if (base.advanced ?? overrides.advanced) {
     merged.advanced = spreadShallow(base.advanced, overrides.advanced)
 
-    // Merge advanced.watch config
-    if (base.advanced?.watch ?? overrides.advanced?.watch) {
-      merged.advanced.watch = spreadShallow(
-        base.advanced?.watch,
-        overrides.advanced?.watch,
-      )
-
-      // Merge watch.also arrays
-      if (base.advanced?.watch?.also ?? overrides.advanced?.watch?.also) {
-        merged.advanced.watch.also = [
-          ...(base.advanced?.watch?.also ?? []),
-          ...(overrides.advanced?.watch?.also ?? []),
-        ]
-      }
-    }
-
     // Merge Vite configs if present
     if (base.advanced?.vite ?? overrides.advanced?.vite) {
       merged.advanced.vite = Vite.mergeConfig(

package/src/api/content/metadata.ts

@@ -1,4 +1,4 @@
-import { z } from 'zod/v4'
+import { z } from 'zod'
 
 /**
  * Schema for validating front matter content

package/src/api/schema/data-sources/data-sources.ts

@@ -1,3 +1,4 @@
+export * as Introspection from './introspection/introspection.js'
 export * as Memory from './memory/memory.js'
 export * as SchemaDirectory from './schema-directory/schema-directory.js'
 export * as SchemaFile from './schema-file/schema-file.js'

package/src/api/schema/data-sources/introspection/introspection.ts

@@ -0,0 +1,213 @@
+import { Grafaid } from '#lib/grafaid/index'
+import { GraphqlChange } from '#lib/graphql-change/index'
+import type { GraphqlChangeset } from '#lib/graphql-changeset/index'
+import { GraphqlSchemaLoader } from '#lib/graphql-schema-loader/index'
+import { Fs, Json, Path } from '@wollybeard/kit'
+import type { NonEmptyChangeSets, SchemaReadResult } from '../../schema.js'
+
+/**
+ * Configuration for loading schema via GraphQL introspection.
+ *
+ * Polen supports two introspection features:
+ * 1. **File Convention**: Automatically detects `schema.introspection.json` if present
+ * 2. **Automatic Introspection**: Fetches from your endpoint and creates the file
+ *
+ * When configured, Polen will:
+ * - Execute the standard GraphQL introspection query against your endpoint
+ * - Save the result to `schema.introspection.json` in your project root
+ * - Use this cached file for subsequent builds (no network requests)
+ *
+ * The saved file contains a standard GraphQL introspection query result as defined
+ * in the GraphQL specification, making it compatible with any tool that works with
+ * introspection data (GraphQL Codegen, Apollo CLI, etc.).
+ *
+ * To refresh the schema, delete `schema.introspection.json` and rebuild.
+ *
+ * **Technical details**:
+ * - Uses Graffle's introspection extension
+ * - Performs the full introspection query (all types, fields, descriptions, etc.)
+ * - No customization of the query is currently supported
+ *
+ * @see https://spec.graphql.org/draft/#sec-Introspection - GraphQL Introspection spec
+ * @see https://github.com/graphql/graphql-js/blob/main/src/utilities/getIntrospectionQuery.ts - Reference implementation
+ *
+ * @example
+ * ```ts
+ * // Basic introspection
+ * introspection: {
+ *   url: 'https://api.example.com/graphql'
+ * }
+ *
+ * // With authentication
+ * introspection: {
+ *   url: 'https://api.example.com/graphql',
+ *   headers: {
+ *     'Authorization': `Bearer ${process.env.API_TOKEN}`
+ *   }
+ * }
+ * ```
+ */
+export interface ConfigInput {
+  /**
+   * The GraphQL endpoint URL to introspect.
+   *
+   * Must be a valid GraphQL endpoint that supports introspection queries.
+   *
+   * @example 'https://api.example.com/graphql'
+   */
+  url?: string
+  /**
+   * Optional headers to include in the introspection request.
+   *
+   * Use this for authentication, API keys, or any custom headers
+   * required by your GraphQL endpoint.
+   *
+   * @example
+   * ```ts
+   * headers: {
+   *   'Authorization': `Bearer ${process.env.API_TOKEN}`,
+   *   'X-API-Key': process.env.API_KEY
+   * }
+   * ```
+   */
+  headers?: Record<string, string>
+  projectRoot?: string
+}
+
+export interface Config {
+  url: string
+  headers?: Record<string, string>
+  projectRoot: string
+}
+
+export const normalizeConfig = (configInput: ConfigInput): Config => {
+  if (!configInput.url) {
+    throw new Error(`Introspection data source requires a URL`)
+  }
+
+  if (!configInput.projectRoot) {
+    throw new Error(`Introspection data source requires a projectRoot`)
+  }
+
+  const config: Config = {
+    url: configInput.url,
+    headers: configInput.headers,
+    projectRoot: configInput.projectRoot,
+  }
+
+  return config
+}
+
+const INTROSPECTION_FILE_NAME = `schema.introspection.json`
+
+const getIntrospectionFilePath = (projectRoot: string) => {
+  return Path.join(projectRoot, INTROSPECTION_FILE_NAME)
+}
+
+export const readOrThrow = async (
+  configInput: ConfigInput,
+): Promise<SchemaReadResult> => {
+  const config = normalizeConfig(configInput)
+  const introspectionFilePath = getIntrospectionFilePath(config.projectRoot)
+
+  // Check if introspection file exists
+  const introspectionFileContent = await Fs.read(introspectionFilePath)
+  let schema: Grafaid.Schema.Schema
+
+  if (introspectionFileContent) {
+    // Load from existing file - no reCreate capability
+    try {
+      const introspectionData = Json.codec.decode(introspectionFileContent)
+
+      // Validate introspection data structure before passing to fromIntrospectionQuery
+      if (!introspectionData || typeof introspectionData !== 'object') {
+        throw new Error('Introspection data must be a valid JSON object')
+      }
+
+      // Allow fromIntrospectionQuery to handle validation of the introspection format
+      // It will provide more specific GraphQL-related error messages
+      if (!('data' in introspectionData)) {
+        throw new Error(
+          'Introspection data missing required "data" property (expected GraphQL introspection result format)',
+        )
+      }
+
+      schema = Grafaid.Schema.fromIntrospectionQuery(introspectionData as any)
+    } catch (error) {
+      if (error instanceof SyntaxError) {
+        throw new Error(`Invalid JSON in ${introspectionFilePath}: ${error.message}`)
+      } else {
+        throw new Error(
+          `Invalid introspection data in ${introspectionFilePath}: ${
+            error instanceof Error ? error.message : String(error)
+          }. Delete this file to fetch fresh introspection data.`,
+        )
+      }
+    }
+
+    const schemaData = await createSingleSchemaChangeset(schema)
+    return {
+      data: schemaData,
+      source: { type: 'introspectionFile' },
+    }
+  } else {
+    // Fetch via introspection - can reCreate
+    const introspectionResult = await GraphqlSchemaLoader.load({
+      type: `introspect`,
+      url: config.url,
+      headers: config.headers,
+    })
+
+    schema = introspectionResult
+
+    // Get the raw introspection result for saving
+    const __schema = Grafaid.Schema.toIntrospectionQuery(schema)
+
+    // Wrap in GraphQL response format for consistency with API responses
+    const introspectionData = { data: { __schema } }
+
+    // Write to file
+    await Fs.write({
+      path: introspectionFilePath,
+      content: Json.codec.encode(introspectionData as any),
+    })
+
+    const schemaData = await createSingleSchemaChangeset(schema)
+    return {
+      data: schemaData,
+      source: {
+        type: 'introspectionAuto',
+        reCreate: async () => {
+          // Re-fetch using captured config - capture closure
+          const result = await readOrThrow(configInput)
+          return result.data
+        },
+      },
+    }
+  }
+}
+
+/**
+ * Create a single changeset from a schema object.
+ * This is the core logic for handling single (unversioned) schemas from introspection.
+ */
+export const createSingleSchemaChangeset = async (schema: Grafaid.Schema.Schema): Promise<NonEmptyChangeSets> => {
+  const date = new Date() // Generate date here for unversioned schema
+  const after = schema
+  const before = Grafaid.Schema.empty
+  const changes = await GraphqlChange.calcChangeset({
+    before,
+    after,
+  })
+
+  const changeset: GraphqlChangeset.ChangeSet = {
+    date,
+    after,
+    before,
+    changes,
+  }
+
+  const result: NonEmptyChangeSets = [changeset]
+
+  return result
+}

package/src/api/schema/metadata.ts

@@ -1,5 +1,5 @@
 import { Fs } from '@wollybeard/kit'
-import { z } from 'zod/v4'
+import { z } from 'zod'
 
 export const SchemaMetadataSchema = z.object({
   /** Whether a schema is present in the project */

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 { 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>
@@ -56,22 +122,38 @@ export interface Config {
      * Pre-built schema object to use directly.
      */
     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 | NonEmptyChangeSets> => {
+): 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-source/schema-source.ts

@@ -157,13 +157,13 @@ export const createSchemaSource = (config: SchemaSourceConfig) => {
     },
 
     writeAllAssets: async (
-      schemaData: Awaited<ReturnType<typeof Schema.readOrThrow>>,
+      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()) {
+      for (const [index, version] of schemaData!.entries()) {
         const versionName = index === 0 ? Schema.VERSION_LATEST : Schema.dateToVersionString(version.date)
 
         // Write schema file
@@ -173,7 +173,7 @@ export const createSchemaSource = (config: SchemaSourceConfig) => {
         )
 
         // Write changelog file (except for the oldest/last version)
-        if (Schema.shouldVersionHaveChangelog(index, schemaData.length)) {
+        if (Schema.shouldVersionHaveChangelog(index, schemaData!.length)) {
           const changelogData = {
             changes: version.changes,
             date: version.date.toISOString(),