polen 0.11.0-next.15 → 0.11.0-next.17

package/src/lib/ai-image-generation/ai-image-generation.ts

@@ -0,0 +1,231 @@
+import * as S from 'effect/Schema'
+import type { GraphQLSchema } from 'graphql'
+
+// ============================================================================
+// Schemas & Types
+// ============================================================================
+
+/**
+ * Art style preferences for generated images
+ */
+export const ArtStyle = S.Literal(
+  'modern',
+  'minimalist',
+  'abstract',
+  'technical',
+  'vibrant',
+  'professional',
+  'futuristic',
+  'gradient',
+  'geometric',
+  'illustration',
+)
+export type ArtStyle = typeof ArtStyle.Type
+
+/**
+ * Configuration for AI image generation using Pollinations
+ */
+export const AiImageConfig = S.Struct({
+  /**
+   * Enable AI hero image generation
+   * @default false
+   */
+  enabled: S.Boolean,
+  /**
+   * Custom prompt override (if not provided, will generate from schema)
+   */
+  prompt: S.optional(S.String),
+  /**
+   * Art style for the generated image
+   * @default 'modern'
+   */
+  style: S.optional(ArtStyle),
+  /**
+   * Image dimensions
+   */
+  width: S.optional(S.Number),
+  height: S.optional(S.Number),
+  /**
+   * Random seed for reproducible generation
+   */
+  seed: S.optional(S.Number),
+  /**
+   * Whether to include Pollinations logo
+   * @default false
+   */
+  nologo: S.optional(S.Boolean),
+  /**
+   * Whether to cache generated images
+   * @default true
+   */
+  cache: S.optional(S.Boolean),
+})
+
+export type AiImageConfig = typeof AiImageConfig.Type
+
+/**
+ * Result of image generation
+ */
+export const GeneratedImage = S.Struct({
+  url: S.String,
+  prompt: S.String,
+  cached: S.Boolean,
+})
+
+export type GeneratedImage = typeof GeneratedImage.Type
+
+// ============================================================================
+// Schema Context Extraction
+// ============================================================================
+
+export interface SchemaContext {
+  name?: string | undefined
+  description?: string | undefined
+  mainTypes: string[]
+  queryNames: string[]
+  mutationNames: string[]
+  subscriptionNames: string[]
+  domain?: string | undefined // e.g., 'e-commerce', 'social', 'analytics'
+  suggestedTheme?: string | undefined // e.g., 'data visualization', 'connectivity', 'growth'
+  topics?: string[] | undefined // Custom or inferred topics
+}
+
+/**
+ * Analyzes a GraphQL schema to extract contextual information for image generation
+ */
+export const analyzeSchema = (schema: GraphQLSchema): SchemaContext => {
+  const typeMap = schema.getTypeMap()
+  const queryType = schema.getQueryType()
+  const mutationType = schema.getMutationType()
+  const subscriptionType = schema.getSubscriptionType()
+
+  // Extract main types (excluding built-ins)
+  const mainTypes = Object.keys(typeMap)
+    .filter(name => !name.startsWith('__') && !['Query', 'Mutation', 'Subscription'].includes(name))
+    .slice(0, 10) // Limit to most important types
+
+  // Extract operation names
+  const queryNames = queryType
+    ? Object.keys(queryType.getFields()).slice(0, 5)
+    : []
+
+  const mutationNames = mutationType
+    ? Object.keys(mutationType.getFields()).slice(0, 5)
+    : []
+
+  const subscriptionNames = subscriptionType
+    ? Object.keys(subscriptionType.getFields()).slice(0, 5)
+    : []
+
+  // Infer domain from type/operation names
+  const allNames = [...mainTypes, ...queryNames, ...mutationNames].join(' ').toLowerCase()
+
+  let domain: string | undefined
+  let suggestedTheme: string | undefined
+
+  if (allNames.includes('product') || allNames.includes('cart') || allNames.includes('order')) {
+    domain = 'e-commerce'
+    suggestedTheme = 'digital marketplace'
+  } else if (allNames.includes('user') || allNames.includes('post') || allNames.includes('comment')) {
+    domain = 'social'
+    suggestedTheme = 'connected network'
+  } else if (allNames.includes('metric') || allNames.includes('report') || allNames.includes('dashboard')) {
+    domain = 'analytics'
+    suggestedTheme = 'data visualization'
+  } else if (allNames.includes('pokemon') || allNames.includes('game')) {
+    domain = 'gaming'
+    suggestedTheme = 'digital adventure'
+  }
+
+  return {
+    mainTypes,
+    queryNames,
+    mutationNames,
+    subscriptionNames,
+    domain,
+    suggestedTheme,
+  }
+}
+
+// ============================================================================
+// Prompt Building
+// ============================================================================
+
+/**
+ * Default topics for each domain
+ */
+const DEFAULT_TOPICS_BY_DOMAIN: Record<string, string[]> = {
+  'e-commerce': ['transactions', 'style', 'markets', 'trade', 'living'],
+  'social': ['community', 'connections', 'sharing', 'communication', 'networks'],
+  'analytics': ['data', 'insights', 'metrics', 'visualization', 'trends'],
+  'gaming': ['adventure', 'competition', 'strategy', 'fantasy', 'achievement'],
+  'technology': ['innovation', 'connectivity', 'automation', 'digital', 'future'],
+}
+
+/**
+ * Builds an image generation prompt from schema context and configuration
+ */
+export const buildPrompt = (
+  context: SchemaContext,
+  style: ArtStyle = 'modern',
+  customPrompt?: string,
+  layout?: 'asymmetric' | 'cinematic' | 'auto',
+): string => {
+  // If custom prompt provided, use it with style suffix and ensure no text
+  if (customPrompt) {
+    return `${customPrompt}, ${getStyleDescription(style)}, no text, no words, no letters, no typography`
+  }
+
+  // Build automatic prompt from context
+  const theme = context.suggestedTheme || 'modern API'
+  const domain = context.domain || 'technology'
+
+  // Create a descriptive prompt based on the schema analysis
+  let prompt = layout === 'asymmetric'
+    ? `Floating ${theme} illustration for a GraphQL API, no text, no words, no letters, isolated graphic element, clean edges, no background, white space around subject, perfect for placing alongside typography`
+    : `Abstract ${theme} hero banner for a GraphQL API, no text, no words, no letters`
+
+  // Use topics if provided, otherwise fall back to domain defaults
+  const topics = context.topics || DEFAULT_TOPICS_BY_DOMAIN[domain] || DEFAULT_TOPICS_BY_DOMAIN['technology']
+
+  // Add topics to the prompt
+  if (topics && topics.length > 0) {
+    prompt += `, all about ${topics.join(', ')}`
+  }
+
+  // Add style description
+  prompt += `, ${getStyleDescription(style)}`
+
+  // Add technical specifications and reinforce no text
+  prompt += ', high quality, absolutely no text or typography or letters or words'
+
+  return prompt
+}
+
+/**
+ * Gets a description for the art style
+ */
+const getStyleDescription = (style: ArtStyle): string => {
+  const styleMap: Record<ArtStyle, string> = {
+    modern: 'modern clean design with subtle gradients',
+    minimalist: 'minimalist flat design with simple shapes',
+    abstract: 'abstract artistic representation',
+    technical: 'technical blueprint style with grid patterns',
+    vibrant: 'vibrant colors and dynamic composition',
+    professional: 'professional corporate style',
+    futuristic: 'futuristic sci-fi aesthetic with neon accents',
+    gradient: 'smooth gradient mesh with flowing colors',
+    geometric: 'geometric patterns and angular shapes',
+    illustration: 'vector illustration style with clean lines, suitable for placement on backgrounds',
+  }
+
+  return styleMap[style]
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export const make = AiImageConfig.make
+export const decode = S.decode(AiImageConfig)
+export const encode = S.encode(AiImageConfig)

package/src/lib/ai-image-generation/providers/pollinations.ts

@@ -0,0 +1,65 @@
+/**
+ * Pollinations.ai provider for AI image generation
+ * Free service, no API key required
+ */
+
+import type { GeneratedImage } from '../ai-image-generation.js'
+
+export interface PollinationsOptions {
+  prompt: string
+  width?: number
+  height?: number
+  seed?: number
+  nologo?: boolean
+}
+
+/**
+ * Generate an image using Pollinations.ai
+ * This is a free service that doesn't require authentication
+ */
+export const generateImage = async (options: PollinationsOptions): Promise<GeneratedImage> => {
+  const {
+    prompt,
+    width = 1200,
+    height = 400,
+    seed,
+    nologo = true,
+  } = options
+
+  // Build the URL with query parameters
+  const params = new URLSearchParams({
+    prompt,
+    width: width.toString(),
+    height: height.toString(),
+    nologo: nologo.toString(),
+  })
+
+  if (seed !== undefined) {
+    params.append('seed', seed.toString())
+  }
+
+  // Pollinations.ai URL format
+  const url = `https://image.pollinations.ai/prompt/${encodeURIComponent(prompt)}?${params.toString()}`
+
+  // The URL itself is the image endpoint - no need to fetch
+  // Pollinations generates the image on-demand when the URL is accessed
+  return {
+    url,
+    prompt,
+    cached: false,
+  }
+}
+
+/**
+ * Check if the Pollinations service is available
+ */
+export const isAvailable = async (): Promise<boolean> => {
+  try {
+    const response = await fetch('https://image.pollinations.ai/prompt/test', {
+      method: 'HEAD',
+    })
+    return response.ok || response.status === 200
+  } catch {
+    return false
+  }
+}

package/src/lib/ai-image-generation/service.ts

@@ -0,0 +1,185 @@
+/**
+ * AI Image Generation Service
+ * Manages Pollinations.ai image generation with caching
+ */
+
+import type { GraphQLSchema } from 'graphql'
+import * as FS from 'node:fs/promises'
+import * as Path from 'node:path'
+import {
+  type AiImageConfig,
+  analyzeSchema,
+  type ArtStyle,
+  buildPrompt,
+  type GeneratedImage,
+} from './ai-image-generation.js'
+import * as Pollinations from './providers/pollinations.js'
+
+export interface GenerateOptions {
+  config: AiImageConfig
+  schema?: GraphQLSchema | undefined
+  projectName?: string | undefined
+  cacheDir?: string | undefined
+  layout?: 'asymmetric' | 'cinematic' | 'auto' | undefined
+}
+
+/**
+ * Main service for generating AI hero images
+ */
+export class AiImageGenerationService {
+  private cacheDir: string
+
+  constructor(cacheDir: string = 'node_modules/.vite/polen-assets/ai-images') {
+    this.cacheDir = cacheDir
+  }
+
+  /**
+   * Generate a hero image based on configuration and schema
+   */
+  async generate(options: GenerateOptions): Promise<GeneratedImage | null> {
+    const { config, schema, projectName, layout } = options
+
+    if (!config.enabled) {
+      return null
+    }
+
+    const style = config.style || 'modern'
+    const width = config.width || 1200
+    const height = config.height || 400
+    const seed = config.seed
+    const nologo = config.nologo !== false
+    const shouldCache = config.cache !== false
+
+    // Build or use custom prompt
+    let prompt: string
+    if (config.prompt) {
+      prompt = config.prompt
+    } else if (schema) {
+      const context = analyzeSchema(schema)
+      if (projectName) {
+        context.name = projectName
+      }
+      prompt = buildPrompt(context, style as ArtStyle, config.prompt, layout)
+    } else {
+      // Fallback generic prompt
+      prompt = buildPrompt(
+        {
+          mainTypes: [],
+          queryNames: [],
+          mutationNames: [],
+          subscriptionNames: [],
+          suggestedTheme: 'modern API',
+        },
+        style as ArtStyle,
+        undefined,
+        layout,
+      )
+    }
+
+    // Skip cache for now to ensure fresh images
+    // TODO: Consider adding timestamp to cache key for time-based invalidation
+    // if (shouldCache) {
+    //   const cached = await this.getCachedImage(prompt)
+    //   if (cached) {
+    //     return cached
+    //   }
+    // }
+
+    // Generate image using Pollinations
+    // Use provided seed or generate random one for unique images
+    const finalSeed = seed || Math.floor(Math.random() * 1000000)
+    const result = await Pollinations.generateImage({
+      prompt,
+      width,
+      height,
+      seed: finalSeed,
+      nologo,
+    })
+
+    // Skip caching for now to ensure fresh images
+    // TODO: Consider adding timestamp to cache key
+    // if (shouldCache) {
+    //   await this.cacheImage(result)
+    // }
+
+    return result
+  }
+
+  /**
+   * Get a cached image if it exists
+   */
+  private async getCachedImage(
+    prompt: string,
+  ): Promise<GeneratedImage | null> {
+    try {
+      const cacheKey = this.getCacheKey(prompt)
+      const cachePath = Path.join(this.cacheDir, `${cacheKey}.json`)
+
+      const exists = await FS.access(cachePath).then(() => true).catch(() => false)
+      if (!exists) {
+        return null
+      }
+
+      const data = await FS.readFile(cachePath, 'utf-8')
+      const cached = JSON.parse(data) as GeneratedImage
+
+      // Return with cached flag set to true
+      return {
+        ...cached,
+        cached: true,
+      }
+    } catch (error) {
+      console.warn('Failed to read cached image:', error)
+      return null
+    }
+  }
+
+  /**
+   * Cache an image result
+   */
+  private async cacheImage(image: GeneratedImage): Promise<void> {
+    try {
+      const cacheKey = this.getCacheKey(image.prompt)
+      const cachePath = Path.join(this.cacheDir, `${cacheKey}.json`)
+
+      // Ensure cache directory exists
+      await FS.mkdir(this.cacheDir, { recursive: true })
+
+      // Write cache file
+      await FS.writeFile(cachePath, JSON.stringify(image, null, 2))
+    } catch (error) {
+      console.warn('Failed to cache image:', error)
+    }
+  }
+
+  /**
+   * Generate a cache key from prompt
+   */
+  private getCacheKey(prompt: string): string {
+    // Create a simple hash from the prompt
+    const hash = prompt
+      .split('')
+      .reduce((acc, char) => {
+        const charCode = char.charCodeAt(0)
+        return ((acc << 5) - acc) + charCode
+      }, 0)
+      .toString(36)
+      .replace('-', 'n') // Replace negative sign
+
+    return `hero-pollinations-${hash}`
+  }
+
+  /**
+   * Clear the cache
+   */
+  async clearCache(): Promise<void> {
+    try {
+      await FS.rm(this.cacheDir, { recursive: true, force: true })
+    } catch (error) {
+      console.warn('Failed to clear cache:', error)
+    }
+  }
+}
+
+// Default service instance
+export const defaultService = new AiImageGenerationService()

package/src/lib/catalog/catalog.ts

@@ -1,6 +1,7 @@
 import { S } from '#lib/kit-temp/effect'
 import { Schema } from '#lib/schema/$'
 import { Version } from '#lib/version/$'
+import { HashMap, Match } from 'effect'
 import * as Unversioned from './unversioned.js'
 import * as Versioned from './versioned.js'
 
@@ -17,7 +18,7 @@ export const Catalog = S.Union(Versioned.Versioned, Unversioned.Unversioned).ann
   description: 'A catalog of GraphQL schemas and their revision history',
 })
 
-export type Catalog = S.Schema.Type<typeof Catalog>
+export type Catalog = typeof Catalog.Type
 
 // ============================================================================
 // Type Guard
@@ -40,7 +41,9 @@ export const fold = <$A>(
 // ============================================================================
 
 export const decode = S.decode(Catalog)
+export const decodeSync = S.decodeSync(Catalog)
 export const encode = S.encode(Catalog)
+export const encodeSync = S.encodeSync(Catalog)
 
 // ============================================================================
 // Equivalence
@@ -59,7 +62,7 @@ export const equivalence = S.equivalence(Catalog)
  */
 export const getVersionCount = (catalog: Catalog): number =>
   fold(
-    (versioned) => versioned.entries.length,
+    (versioned) => HashMap.size(versioned.entries),
     (_unversioned) => 1, // Unversioned catalog is effectively one version
   )(catalog)
 
@@ -69,5 +72,29 @@ export const getVersionCount = (catalog: Catalog): number =>
  */
 export const getSchemaVersionString = (schema: Schema.Schema): string => {
   const version = Schema.getVersion(schema)
-  return version ? Version.toString(version) : '__UNVERSIONED__'
+  return version ? Version.encodeSync(version) : '__UNVERSIONED__'
+}
+
+/**
+ * Get the version string from a schema.
+ * Returns the stringified version for versioned schemas, or '__UNVERSIONED__' for unversioned schemas.
+ */
+export const getLatest = (catalog: Catalog): Schema.Schema =>
+  Match.value(catalog).pipe(Match.tagsExhaustive({
+    CatalogVersioned: Versioned.getLatestOrThrow,
+    CatalogUnversioned: (unversioned) => unversioned.schema,
+  }))
+
+/**
+ * Get the latest version identifier from a catalog.
+ * Returns the version for versioned catalogs, or null for unversioned catalogs.
+ */
+export const getLatestVersion = (catalog?: Catalog): Version.Version | null => {
+  if (!catalog) return null
+  return Match.value(catalog).pipe(
+    Match.tagsExhaustive({
+      CatalogUnversioned: () => null,
+      CatalogVersioned: (cat) => Versioned.getVersions(cat)[0] ?? null,
+    }),
+  )
 }

package/src/lib/catalog/unversioned.ts

@@ -14,7 +14,7 @@ export const Unversioned = S.TaggedStruct('CatalogUnversioned', {
   adt: { name: 'Catalog' },
 })
 
-export type Unversioned = S.Schema.Type<typeof Unversioned>
+export type Unversioned = typeof Unversioned.Type
 
 // ============================================================================
 // Constructors

package/src/lib/catalog/versioned.ts

@@ -1,12 +1,17 @@
 import { S } from '#lib/kit-temp/effect'
+import { Array, HashMap, Iterable, Order, pipe } from 'effect'
 import { Schema } from '../schema/$.js'
+import { Version } from '../version/$.js'
 
 // ============================================================================
 // Schema
 // ============================================================================
 
 export const Versioned = S.TaggedStruct('CatalogVersioned', {
-  entries: S.Array(Schema.Versioned.Versioned),
+  entries: S.HashMap({
+    key: Version.Version,
+    value: Schema.Versioned.Versioned,
+  }),
 }).annotations({
   identifier: 'CatalogVersioned',
   title: 'Versioned Catalog',
@@ -14,7 +19,7 @@ export const Versioned = S.TaggedStruct('CatalogVersioned', {
   adt: { name: 'Catalog' },
 })
 
-export type Versioned = S.Schema.Type<typeof Versioned>
+export type Versioned = typeof Versioned.Type
 
 // ============================================================================
 // Constructors
@@ -40,3 +45,47 @@ export const encode = S.encode(Versioned)
 // ============================================================================
 
 export const equivalence = S.equivalence(Versioned)
+
+// ============================================================================
+// Domain Logic
+// ============================================================================
+
+/**
+ * Get the latest schema definition from a versioned catalog.
+ * The latest version is determined by Version.max comparison.
+ *
+ * @param catalog - The versioned catalog
+ * @returns The GraphQL schema definition of the latest version
+ * @throws {Error} If the catalog has no entries
+ */
+export const getLatestOrThrow = (catalog: Versioned): Schema.Versioned.Versioned => {
+  const schema = getAll(catalog)[0]
+  if (!schema) {
+    throw new Error('Versioned catalog has no entries - cannot get latest schema')
+  }
+  return schema
+}
+
+/**
+ * Get all schemas sorted by version (newest first)
+ */
+export const getAll = (catalog: Versioned): Schema.Versioned.Versioned[] => {
+  return pipe(
+    catalog.entries,
+    HashMap.values,
+    Array.fromIterable,
+    // Put newest versions first in array
+    Array.sort(Order.reverse(Schema.Versioned.order)),
+  )
+}
+
+/**
+ * Get all versions sorted (newest first)
+ */
+export const getVersions = (catalog: Versioned): Version.Version[] => {
+  return pipe(
+    catalog,
+    getAll,
+    Array.map(_ => _.version),
+  )
+}

package/src/lib/catalog-statistics/$$.ts

@@ -0,0 +1,4 @@
+export * from './analyze-catalog.js'
+export * from './analyze-options.js'
+export * from './analyze-schema.js'
+export * from './data.js'