polen 0.11.0-next.13 → 0.11.0-next.15

package/src/api/config/input.ts

@@ -0,0 +1,340 @@
+import { ConfigSchema } from '#api/schema/config-schema'
+import { Vite } from '#dep/vite/index'
+import { spreadShallow } from '#lib/kit-temp'
+import { S } from '#lib/kit-temp/effect'
+import type { WritableDeep } from 'type-fest'
+
+// ============================================================================
+// Schema - Build
+// ============================================================================
+
+export const BuildArchitecture = S.Enums(
+  {
+    ssg: 'ssg',
+    spa: 'spa',
+    ssr: 'ssr',
+  } as const,
+)
+export type BuildArchitecture = S.Schema.Type<typeof BuildArchitecture>
+
+// ============================================================================
+// Schema - Template Variables
+// ============================================================================
+
+const TemplateVariablesSchema = S.Struct({
+  /**
+   * Title of the app.
+   *
+   * Used in the navigation bar and in the title tag.
+   *
+   * If not provided, Polen will try to use your project's package.json name
+   * field, converting it to title case (e.g., "my-project" → "My Project").
+   *
+   * @default Your package.json name (title-cased) or "My Developer Portal"
+   * @example
+   * ```ts
+   * // Explicit title
+   * title: 'Acme GraphQL API'
+   *
+   * // Falls back to package.json name
+   * // If package.json has { "name": "acme-graphql" }
+   * // Title will be "Acme Graphql"
+   * ```
+   */
+  title: S.optional(S.String),
+}).annotations({
+  identifier: 'TemplateVariables',
+  description: 'Template variables for customizing the developer portal.',
+})
+export type TemplateVariables = S.Schema.Type<typeof TemplateVariablesSchema>
+
+// ============================================================================
+// Schema - Build Config
+// ============================================================================
+
+const BuildConfigSchema = S.Struct({
+  /**
+   * The build architecture for your developer portal.
+   *
+   * - `ssg` - Static Site Generation: Pre-renders all pages at build time. Best for public docs.
+   * - `ssr` - Server-Side Rendering: Renders pages on each request. Enables dynamic features.
+   * - `spa` - Single Page Application: Client-side rendering only.
+   *
+   * @default 'ssg'
+   */
+  architecture: S.optional(BuildArchitecture),
+  /**
+   * Base public path for the deployed site.
+   *
+   * Use this when deploying to a subdirectory (e.g., GitHub Pages project sites).
+   *
+   * @example
+   * ```ts
+   * // Deploy to root
+   * base: '/'
+   *
+   * // Deploy to subdirectory
+   * base: '/my-project/'
+   *
+   * // PR preview deployments
+   * base: '/pr-123/'
+   * ```
+   *
+   * Must start and end with `/`.
+   *
+   * @default `/`
+   */
+  base: S.optional(S.String),
+}).annotations({
+  identifier: 'BuildConfig',
+  description: 'Build configuration for your developer portal.',
+})
+
+// ============================================================================
+// Schema - Server Config
+// ============================================================================
+
+const ServerConfigSchema = S.Struct({
+  /**
+   * Port for the server to listen on.
+   *
+   * - In development: The port for the Vite dev server
+   * - In production SSR: The default port for the Node.js server
+   *
+   * For production SSR builds, this can be overridden at runtime
+   * using the PORT environment variable.
+   *
+   * @default 3000
+   * @example
+   * ```ts
+   * // Use a specific port
+   * server: {
+   *   port: 4000
+   * }
+   *
+   * // Or via CLI flags:
+   * // polen dev --port 4000
+   * // polen build --port 4000
+   * ```
+   */
+  port: S.optional(S.Number),
+}).annotations({
+  identifier: 'ServerConfig',
+  description: 'Server configuration for development and production.',
+})
+
+// ============================================================================
+// Schema - Warnings Config
+// ============================================================================
+
+const WarningsConfigSchema = S.Struct({
+  /**
+   * Warning shown when GraphQL code blocks have the `interactive` flag
+   * but no schema is configured.
+   *
+   * Interactive features require a schema to provide field validation,
+   * type information, and auto-completion.
+   *
+   * @default { enabled: true }
+   */
+  interactiveWithoutSchema: S.optional(
+    S.Struct({
+      /**
+       * Whether to show this warning.
+       *
+       * @default true
+       */
+      enabled: S.optional(S.Boolean),
+    }),
+  ),
+}).annotations({
+  identifier: 'WarningsConfig',
+  description:
+    `Configuration for developer experience warnings. Polen can show helpful warnings for common issues or misconfigurations. Each warning type can be individually enabled or disabled.
+
+@example
+\`\`\`ts
+warnings: {
+  interactiveWithoutSchema: {
+    enabled: false // Disable warning when interactive code blocks are used without a schema
+  }
+}
+\`\`\``,
+})
+
+// ============================================================================
+// Schema - Advanced Config
+// ============================================================================
+
+const AdvancedPathsSchema = S.Struct({
+  devAssets: S.optional(S.String),
+})
+
+const AdvancedConfigSchema = S.Struct({
+  /**
+   * Enable a special module explorer for the source code that Polen assembles for your app.
+   *
+   * This opens an interactive UI to inspect the module graph and transformations.
+   * Useful for debugging build issues or understanding Polen's internals.
+   *
+   * Access the explorer at `/__inspect/` when running the dev server.
+   *
+   * Powered by [Vite Inspect](https://github.com/antfu-collective/vite-plugin-inspect).
+   *
+   * @default false
+   */
+  explorer: S.optional(S.Boolean),
+  /**
+   * Force the CLI to resolve Polen imports in your project to itself rather than
+   * to what you have installed in your project.
+   *
+   * If you are using a Polen CLI from your local project against your local project
+   * then there can be no effect from this setting.
+   *
+   * This is mostly useful for:
+   *
+   * - Development of Polen itself
+   * - Global CLI usage against ephemeral projects e.g. a directory with just a
+   *   GraphQL Schema file.
+   *
+   * @default false
+   */
+  isSelfContainedMode: S.optional(S.Boolean),
+  /**
+   * Whether to enable debug mode.
+   *
+   * When enabled the following happens:
+   *
+   * - build output is NOT minified.
+   *
+   * @default false
+   */
+  debug: S.optional(S.Boolean),
+  /**
+   * Additional {@link vite.UserConfig} that is merged with the one created by Polen using {@link Vite.mergeConfig}.
+   *
+   * @see https://vite.dev/config/
+   * @see https://vite.dev/guide/api-javascript.html#mergeconfig
+   */
+  vite: S.optional(S.transform(
+    S.Unknown,
+    S.Any, // or S.typeSchema<Vite.UserConfig>() if you have the type
+    {
+      decode: (value) => value as Vite.UserConfig,
+      encode: (value) => value,
+    },
+  )),
+  paths: S.optional(AdvancedPathsSchema),
+}).annotations({
+  identifier: 'AdvancedConfig',
+  description: 'Advanced configuration options. These settings are for advanced use cases and debugging.',
+})
+
+// ============================================================================
+// Schema - Main Config Input
+// ============================================================================
+
+/**
+ * Polen configuration input.
+ *
+ * All options are optional. Polen provides sensible defaults for a great developer experience out of the box.
+ */
+export const ConfigInputSchema = S.Struct({
+  schema: S.optional(ConfigSchema),
+  templateVariables: S.optional(TemplateVariablesSchema),
+  build: S.optional(BuildConfigSchema),
+  server: S.optional(ServerConfigSchema),
+  warnings: S.optional(WarningsConfigSchema),
+  advanced: S.optional(AdvancedConfigSchema),
+}).annotations({
+  identifier: 'ConfigInput',
+  title: 'Polen Configuration',
+  description: 'Configuration for your Polen developer portal. All options are optional with sensible defaults.',
+})
+
+export type ConfigInput = S.Schema.Type<typeof ConfigInputSchema>
+
+// ============================================================================
+// Codecs
+// ============================================================================
+
+export const decodeConfigInput = S.decodeSync(ConfigInputSchema)
+export const validateConfigInput = S.validateSync(ConfigInputSchema)
+export const validateConfigInputEffect = S.validate(ConfigInputSchema)
+
+// -- merge
+//
+//
+
+/**
+ * Deep merge two Polen config inputs.
+ * The second config (overrides) takes precedence over the first (base).
+ */
+export const mergeInputs = (
+  base?: ConfigInput | undefined,
+  overrides?: ConfigInput | undefined,
+): ConfigInput => {
+  const base_as_writable = base as WritableDeep<ConfigInput> | undefined
+  const overrides_as_writable = overrides as WritableDeep<ConfigInput> | undefined
+
+  if (!base_as_writable) {
+    return overrides_as_writable ?? {}
+  }
+
+  if (!overrides_as_writable) {
+    return base_as_writable ?? {}
+  }
+
+  const merged: WritableDeep<ConfigInput> = spreadShallow(base_as_writable, overrides_as_writable)
+
+  // Merge schema if both have it
+  if (base_as_writable.schema ?? overrides_as_writable.schema) {
+    merged.schema = overrides_as_writable.schema ?? base_as_writable.schema
+  }
+
+  // Merge build config
+  if (base_as_writable.build ?? overrides_as_writable.build) {
+    merged.build = spreadShallow(base_as_writable.build, overrides_as_writable.build)
+  }
+
+  // Merge server config
+  if (base_as_writable.server ?? overrides_as_writable.server) {
+    merged.server = spreadShallow(base_as_writable.server, overrides_as_writable.server)
+  }
+
+  // Merge warnings config
+  if (base_as_writable.warnings ?? overrides_as_writable.warnings) {
+    merged.warnings = spreadShallow(base_as_writable.warnings, overrides_as_writable.warnings)
+
+    // Merge interactiveWithoutSchema config
+    if (
+      base_as_writable.warnings?.interactiveWithoutSchema ?? overrides_as_writable.warnings?.interactiveWithoutSchema
+    ) {
+      merged.warnings.interactiveWithoutSchema = spreadShallow(
+        base_as_writable.warnings?.interactiveWithoutSchema,
+        overrides_as_writable.warnings?.interactiveWithoutSchema,
+      )
+    }
+  }
+
+  // Merge advanced config
+  if (base_as_writable.advanced ?? overrides_as_writable.advanced) {
+    merged.advanced = spreadShallow(base_as_writable.advanced, overrides_as_writable.advanced)
+
+    // Merge Vite configs if present
+    if (base_as_writable.advanced?.vite ?? overrides_as_writable.advanced?.vite) {
+      merged.advanced.vite = Vite.mergeConfig(
+        base_as_writable.advanced?.vite ?? {},
+        overrides_as_writable.advanced?.vite ?? {},
+      )
+    }
+
+    if (base_as_writable.advanced?.paths ?? overrides_as_writable.advanced?.paths) {
+      merged.advanced.paths = spreadShallow(base_as_writable.advanced?.paths, overrides_as_writable.advanced?.paths)
+    }
+  }
+
+  return merged
+}
+
+export const defineConfig = ConfigInputSchema.make

package/src/api/config/load.ts

@@ -2,10 +2,15 @@ import type { SelfContainedModeHooksData } from '#cli/_/self-contained-mode'
 import { assertOptionalPathAbsolute, pickFirstPathExisting } from '#lib/kit-temp'
 import { packagePaths } from '#package-paths'
 import { debugPolen } from '#singletons/debug'
+import * as NodeFileSystem from '@effect/platform-node/NodeFileSystem'
+import { FileSystem } from '@effect/platform/FileSystem'
 import type { Prom } from '@wollybeard/kit'
 import { Path } from '@wollybeard/kit'
+import { Effect, ParseResult } from 'effect'
 import * as Module from 'node:module'
-import type { ConfigInput } from './configurator.js'
+import type { WritableDeep } from 'type-fest'
+import type { ConfigInput } from './input.js'
+import { validateConfigInput, validateConfigInputEffect } from './input.js'
 
 export const fileNameBases = [`polen.config`, `.polen.config`]
 export const fileNameExtensionsTypeScript = [`.ts`, `.js`, `.mjs`, `.mts`]
@@ -19,82 +24,101 @@ export interface LoadOptions {
 
 let isSelfContainedModeRegistered = false
 
-export const load = async (options: LoadOptions): Promise<ConfigInput> => {
-  const debug = debugPolen.sub(`load`)
-  assertOptionalPathAbsolute(options.dir)
-
-  //
-  // ━━ Enable Self-Contained Mode
-  //
-  //  - When we're running CLI from source code
-  //  - Do this BEFORE trying to load the config file
-  //
-
-  const isSelfContainedModeEnabled = packagePaths.isRunningFromSource
-  if (isSelfContainedModeEnabled && !isSelfContainedModeRegistered) {
-    const initializeData: SelfContainedModeHooksData = {
-      projectDirPathExp: options.dir,
+export const load = (options: LoadOptions): Effect.Effect<ConfigInput, Error, FileSystem> =>
+  Effect.gen(function*() {
+    const debug = debugPolen.sub(`load`)
+    assertOptionalPathAbsolute(options.dir)
+
+    //
+    // ━━ Enable Self-Contained Mode
+    //
+    //  - When we're running CLI from source code
+    //  - Do this BEFORE trying to load the config file
+    //
+
+    const isSelfContainedModeEnabled = packagePaths.isRunningFromSource
+    if (isSelfContainedModeEnabled && !isSelfContainedModeRegistered) {
+      const initializeData: SelfContainedModeHooksData = {
+        projectDirPathExp: options.dir,
+      }
+      debug(`register node module hooks`, { data: initializeData })
+      // TODO: would be simpler to use sync hooks
+      // https://nodejs.org/api/module.html#synchronous-hooks-accepted-by-moduleregisterhooks
+      // Requires NodeJS 22.15+ -- which is not working with PW until its next release.
+      Module.register(`#cli/_/self-contained-mode`, import.meta.url, { data: initializeData })
+      isSelfContainedModeRegistered = true
     }
-    debug(`register node module hooks`, { data: initializeData })
-    // TODO: would be simpler to use sync hooks
-    // https://nodejs.org/api/module.html#synchronous-hooks-accepted-by-moduleregisterhooks
-    // Requires NodeJS 22.15+ -- which is not working with PW until its next release.
-    Module.register(`#cli/_/self-contained-mode`, import.meta.url, { data: initializeData })
-    isSelfContainedModeRegistered = true
-  }
-
-  //
-  // ━━ Fetch the Config
-  //
-
-  const filePaths = fileNames.map(fileName => Path.join(options.dir, fileName))
-  const filePath = await pickFirstPathExisting(filePaths)
-
-  let configInput: ConfigInput | undefined = undefined
-  if (!filePath) {
-    configInput = {}
-  } else {
-    // If the user's config is a TypeScript file, we will use TSX to import it.
-
-    let module: { default?: Prom.Maybe<ConfigInput>; config?: Prom.Maybe<ConfigInput> }
-    if (fileNameExtensionsTypeScript.some(_ => filePath.endsWith(_))) {
-      // @see https://tsx.is/dev-api/ts-import#usage
-      const { tsImport } = await import(`tsx/esm/api`)
-      module = await tsImport(filePath, import.meta.url)
-    } else {
-      module = await import(filePath)
-    }
-    debug(`imported config module`)
-
-    //       // Use dynamic import with file URL to support Windows
-    //       const configUrl = pathToFileURL(configPath).href
 
-    // todo: report errors nicely if this fails
-    const configInputFromFile = await (module.default ?? module.config)
+    //
+    // ━━ Fetch the Config
+    //
 
-    // todo: check schema of configInput
+    const filePaths = fileNames.map(fileName => Path.join(options.dir, fileName))
+    const filePath = yield* pickFirstPathExisting(filePaths)
 
-    // todo: report errors nicely
-    if (!configInputFromFile) {
-      throw new Error(
-        `Your Polen config module (${filePath}) must export a config. You can use a default export or named export of \`config\`.`,
+    let configInput: ConfigInput
+    if (!filePath) {
+      // No config file found, use empty config (will use all defaults)
+      configInput = validateConfigInput({})
+    } else {
+      // If the user's config is a TypeScript file, we will use TSX to import it.
+
+      const module = yield* Effect.tryPromise({
+        try: async () => {
+          if (fileNameExtensionsTypeScript.some(_ => filePath.endsWith(_))) {
+            // @see https://tsx.is/dev-api/ts-import#usage
+            const { tsImport } = await import(`tsx/esm/api`)
+            return await tsImport(filePath, import.meta.url) as {
+              default?: Prom.Maybe<ConfigInput>
+              config?: Prom.Maybe<ConfigInput>
+            }
+          } else {
+            return await import(filePath) as { default?: Prom.Maybe<ConfigInput>; config?: Prom.Maybe<ConfigInput> }
+          }
+        },
+        catch: (error) => new Error(`Failed to import config module from ${filePath}: ${error}`),
+      })
+      debug(`imported config module`)
+
+      //       // Use dynamic import with file URL to support Windows
+      //       const configUrl = pathToFileURL(configPath).href
+
+      const configInputFromFile = yield* Effect.tryPromise({
+        try: async () => await (module.default ?? module.config),
+        catch: (error) => new Error(`Failed to resolve config from module: ${error}`),
+      })
+
+      if (!configInputFromFile) {
+        return yield* Effect.fail(
+          new Error(
+            `Your Polen config module (${filePath}) must export a config. You can use a default export or named export of \`config\`.`,
+          ),
+        )
+      }
+
+      // Validate the config against the schema using Effect
+      configInput = yield* validateConfigInputEffect(configInputFromFile).pipe(
+        Effect.mapError((parseError) =>
+          new Error(
+            `Invalid Polen configuration in ${filePath}:\n${ParseResult.TreeFormatter.formatErrorSync(parseError)}`,
+          )
+        ),
       )
     }
-    configInput = configInputFromFile
-  }
 
-  //
-  // ━━ Record Any Change of Self-Contained Mode
-  //
-  //  - This will enable a Vite plugin to handle polen imports from non-JS files
-  //    in the user's project (like Markdown) in a self-contained way.
+    //
+    // ━━ Record Any Change of Self-Contained Mode
+    //
+    //  - This will enable a Vite plugin to handle polen imports from non-JS files
+    //    in the user's project (like Markdown) in a self-contained way.
 
-  if (isSelfContainedModeEnabled) {
-    configInput.advanced ??= {}
-    configInput.advanced.isSelfContainedMode = true
-  }
+    if (isSelfContainedModeEnabled) {
+      const configInput_as_writable = configInput as WritableDeep<ConfigInput>
+      configInput_as_writable.advanced ??= {}
+      configInput_as_writable.advanced.isSelfContainedMode = true
+    }
 
-  debug(`loaded config input`, configInput)
+    debug(`loaded config input`, configInput)
 
-  return configInput
-}
+    return configInput
+  })