polen 0.10.0 → 0.11.0-next.1

package/src/api/config/configurator.ts

@@ -289,6 +289,13 @@ const buildPaths = (rootDir: string): Config[`paths`] => {
 
   const publicAbsolutePath = rootAbsolute(`public`)
   const publicAbsolute = Path.ensureAbsoluteWith(publicAbsolutePath)
+
+  const assetsAbsolute = Path.ensureAbsoluteWith(buildAbsolute(`assets`))
+
+  // Dev assets paths
+  const devAssetsRelative = 'node_modules/.vite/polen-assets'
+  const devAssetsAbsolute = Path.join(packagePaths.rootDir, devAssetsRelative)
+
   return {
     project: {
       rootDir,
@@ -297,7 +304,12 @@ const buildPaths = (rootDir: string): Config[`paths`] => {
           root: `build`,
           relative: {
             serverEntrypoint: `app.js`,
-            assets: `assets`,
+            assets: {
+              root: `assets`,
+              relative: {
+                schemas: `schemas`,
+              },
+            },
           },
         },
         pages: `pages`,
@@ -311,7 +323,10 @@ const buildPaths = (rootDir: string): Config[`paths`] => {
         build: {
           root: buildAbsolute(`.`),
           serverEntrypoint: buildAbsolute(`app.js`),
-          assets: buildAbsolute(`assets`),
+          assets: {
+            root: buildAbsolute(`assets`),
+            schemas: assetsAbsolute(`schemas`),
+          },
         },
         public: {
           root: publicAbsolute(`.`),
@@ -319,7 +334,14 @@ const buildPaths = (rootDir: string): Config[`paths`] => {
         },
       },
     },
-    framework: packagePaths,
+    framework: {
+      ...packagePaths,
+      devAssets: {
+        relative: devAssetsRelative,
+        absolute: devAssetsAbsolute,
+        schemas: Path.join(devAssetsAbsolute, 'schemas'),
+      },
+    },
   }
 }
 
@@ -331,6 +353,9 @@ export interface Config {
   }
   server: {
     port: number
+    routes: {
+      assets: string
+    }
   }
   watch: {
     also: string[]
@@ -353,7 +378,12 @@ export interface Config {
         build: {
           root: string
           relative: {
-            assets: string
+            assets: {
+              root: string
+              relative: {
+                schemas: string
+              }
+            }
             serverEntrypoint: string
           }
         }
@@ -366,7 +396,10 @@ export interface Config {
       absolute: {
         build: {
           root: string
-          assets: string
+          assets: {
+            root: string
+            schemas: string
+          }
           serverEntrypoint: string
         }
         pages: string
@@ -376,7 +409,13 @@ export interface Config {
         }
       }
     }
-    framework: PackagePaths
+    framework: PackagePaths & {
+      devAssets: {
+        relative: string
+        absolute: string
+        schemas: string
+      }
+    }
   }
   advanced: {
     isSelfContainedMode: boolean
@@ -401,6 +440,9 @@ const configInputDefaults: Config = {
   },
   server: {
     port: 3000,
+    routes: {
+      assets: '/assets',
+    },
   },
   schema: null,
   ssr: {
@@ -507,6 +549,9 @@ export const normalizeInput = async (
     config.server.port = configInput.server.port
   }
 
+  // Server routes are not configurable by users yet, use defaults
+  // config.server.routes is already set from defaultConfig
+
   // Process warnings configuration
   if (configInput?.warnings?.interactiveWithoutSchema?.enabled !== undefined) {
     config.warnings.interactiveWithoutSchema.enabled = configInput.warnings.interactiveWithoutSchema.enabled

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

@@ -2,7 +2,7 @@ import { Grafaid } from '#lib/grafaid/index'
 import { GraphqlChange } from '#lib/graphql-change/index'
 import type { GraphqlChangeset } from '#lib/graphql-changeset/index'
 import { Arr } from '@wollybeard/kit'
-import type { Schema } from '../../schema.js'
+import type { NonEmptyChangeSets } from '../../schema.js'
 
 /**
  * Configuration for defining schemas programmatically in memory.
@@ -68,7 +68,7 @@ export const normalize = (configInput: ConfigInput): Config => {
 
 export const read = async (
   configInput: ConfigInput,
-): Promise<null | Schema> => {
+): Promise<null | NonEmptyChangeSets> => {
   const config = normalize(configInput)
 
   if (!Arr.isntEmpty(config.versions)) {
@@ -109,9 +109,7 @@ export const read = async (
 
   changesets.reverse()
 
-  const schema: Schema = {
-    versions: changesets,
-  }
+  const schema: NonEmptyChangeSets = changesets
 
   return schema
 }

package/src/api/schema/data-sources/schema-directory/file-name-expression/file-name-expression.ts

@@ -1,6 +1,6 @@
 import { Path } from '@wollybeard/kit'
 
-export type Expression = ExpressionPrevious
+export type Expression = ExpressionVersioned | ExpressionSingle
 
 export const parseOrThrow = (fileNameOrSerializedExpression: string): Expression => {
   const result = parse(fileNameOrSerializedExpression)
@@ -18,41 +18,57 @@ export const parse = (fileName: string): null | Expression => {
   }
   const serializedExpression = path.name
 
-  const previous = parseExpressionPreviousSerialized(serializedExpression)
-  if (previous) return { ...previous, filePath: fileName, type: `FileNameExpressionPrevious` }
+  const versioned = parseExpressionVersionedSerialized(serializedExpression)
+  if (versioned) return { ...versioned, filePath: fileName, type: `FileNameExpressionVersioned` }
 
-  // const latest = parseExpressionLatestSerialized(serializedExpression)
-  // if (latest) return { ...latest, filePath: fileName, type: `FileNameExpressionLatest` }
+  const single = parseExpressionSingleSerialized(serializedExpression)
+  if (single) return { ...single, filePath: fileName, type: `FileNameExpressionSingle` }
 
   return null
 }
 
 // ----
 
-export interface ExpressionPrevious {
-  type: `FileNameExpressionPrevious`
+export interface ExpressionVersioned {
+  type: `FileNameExpressionVersioned`
   date: Date
   filePath: string
 }
 
-const parseExpressionPreviousSerialized = (
+const parseExpressionVersionedSerialized = (
   serializedExpression: string,
-): Pick<ExpressionPrevious, `date`> | null => {
-  const match = expressionPreviousSerializedPattern.exec(serializedExpression)
+): Pick<ExpressionVersioned, `date`> | null => {
+  const match = expressionVersionedSerializedPattern.exec(serializedExpression)
   if (!match) return null
   const { year, month, day } = match.groups as { year: string; month: string; day: string }
   const date = new Date(parseInt(year), parseInt(month) - 1, parseInt(day))
   return { date }
 }
 
-const expressionPreviousSerializedPattern = /^(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})$/
+const expressionVersionedSerializedPattern = /^(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})$/
 
-// export const isExpressionPrevious = (expression: Expression): expression is ExpressionPrevious => {
-//   return expression.type === `FileNameExpressionPrevious`
+// export const isExpressionVersioned = (expression: Expression): expression is ExpressionVersioned => {
+//   return expression.type === `FileNameExpressionVersioned`
 // }
 
 // ----
 
+export interface ExpressionSingle {
+  type: `FileNameExpressionSingle`
+  filePath: string
+}
+
+const parseExpressionSingleSerialized = (
+  serializedExpression: string,
+): {} | null => {
+  if (serializedExpression === `schema`) {
+    return {}
+  }
+  return null
+}
+
+// ----
+
 // export interface ExpressionLatest {
 //   type: `FileNameExpressionLatest`
 //   filePath: string

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

@@ -4,7 +4,8 @@ import type { GraphqlChangeset } from '#lib/graphql-changeset/index'
 import { debugPolen } from '#singletons/debug'
 import { Arr, Path } from '@wollybeard/kit'
 import { glob } from 'tinyglobby'
-import type { Schema } from '../../schema.js'
+import type { NonEmptyChangeSets } from '../../schema.js'
+import { readSingleSchemaFile } from '../schema-file/schema-file.js'
 import { FileNameExpression } from './file-name-expression/index.js'
 
 // const debug = debugPolen.sub([`schema`, `data-source-schema-directory`])
@@ -15,15 +16,19 @@ const defaultPaths = {
 }
 
 /**
- * Configuration for loading multiple schema versions from a directory.
+ * Configuration for loading schema(s) from a directory.
  *
- * Enables the schema changelog feature by loading SDL files with date prefixes.
+ * Supports two modes:
+ * 1. Multiple versioned schemas with date prefixes (enables changelog feature)
+ * 2. Single schema file named 'schema.graphql' (non-versioned, like file data source)
  */
 export interface ConfigInput {
   /**
-   * Path to the directory containing dated SDL files.
+   * Path to the directory containing schema files.
    *
-   * Files should be named with ISO date prefixes: `YYYY-MM-DD.graphql`
+   * Supports two patterns:
+   * 1. Multiple versioned files with ISO date prefixes: `YYYY-MM-DD.graphql`
+   * 2. Single file named: `schema.graphql`
    *
    * @default './schema'
    *
@@ -36,12 +41,17 @@ export interface ConfigInput {
    * path: './graphql/versions'
    * ```
    *
-   * Directory structure example:
+   * Directory structure examples:
    * ```
+   * // Versioned schemas (enables changelog)
    * schema/
    *   2024-01-15.graphql
    *   2024-03-20.graphql
    *   2024-06-10.graphql
+   *
+   * // Single schema (non-versioned)
+   * schema/
+   *   schema.graphql
    * ```
    */
   path?: string
@@ -61,7 +71,7 @@ export const normalizeConfig = (configInput: ConfigInput): Config => {
   return config
 }
 
-export const readOrThrow = async (configInput: ConfigInput): Promise<null | Schema> => {
+export const readOrThrow = async (configInput: ConfigInput): Promise<null | NonEmptyChangeSets> => {
   const config = normalizeConfig(configInput)
 
   debug(`will search`, config)
@@ -80,7 +90,42 @@ export const readOrThrow = async (configInput: ConfigInput): Promise<null | Sche
   const fileNameExpressions = Arr.map(filePaths, FileNameExpression.parseOrThrow)
   debug(`parsed file names`, fileNameExpressions)
 
-  const versions = await Promise.all(Arr.map(fileNameExpressions, async fileNameExpression => {
+  // Separate versioned (dated) and single schema files
+  const versionedExpressions = fileNameExpressions.filter(
+    (expr): expr is FileNameExpression.ExpressionVersioned => expr.type === `FileNameExpressionVersioned`,
+  )
+  const singleExpressions = fileNameExpressions.filter(
+    (expr): expr is FileNameExpression.ExpressionSingle => expr.type === `FileNameExpressionSingle`,
+  )
+
+  // If we have versioned files, use them (versioned takes precedence)
+  if (Arr.isntEmpty(versionedExpressions)) {
+    return await readVersionedSchemas(versionedExpressions)
+  }
+
+  // If we have a single schema file, use it
+  if (Arr.isntEmpty(singleExpressions)) {
+    if (singleExpressions.length > 1) {
+      throw new Error(
+        `Multiple single schema files found, expected exactly one: ${
+          singleExpressions.map(e => e.filePath).join(', ')
+        }`,
+      )
+    }
+    return await readSingleSchemaFile(singleExpressions[0].filePath)
+  }
+
+  // Should not happen since we already checked for empty filePaths
+  throw new Error(`No schema files found despite non-empty file paths`)
+}
+
+/**
+ * Read multiple versioned schema files and create changesets
+ */
+const readVersionedSchemas = async (
+  versionedExpressions: FileNameExpression.ExpressionVersioned[],
+): Promise<NonEmptyChangeSets> => {
+  const versions = await Promise.all(Arr.map(versionedExpressions, async fileNameExpression => {
     const schemaFile = await Grafaid.Schema.read(fileNameExpression.filePath)
     // Should never happen since these paths come from the glob.
     if (!schemaFile) throw new Error(`Failed to read schema file: ${fileNameExpression.filePath}`)
@@ -90,7 +135,7 @@ export const readOrThrow = async (configInput: ConfigInput): Promise<null | Sche
       schema: schemaFile.content,
     }
   }))
-  debug(`read schemas`)
+  debug(`read versioned schemas`)
 
   versions.sort((a, b) => a.date.getTime() - b.date.getTime())
 
@@ -118,11 +163,6 @@ export const readOrThrow = async (configInput: ConfigInput): Promise<null | Sche
 
   changesets.reverse()
 
-  const schema: Schema = {
-    versions: changesets,
-  }
-
-  debug(`computed schema`)
-
-  return schema
+  debug(`computed versioned schema`)
+  return changesets as NonEmptyChangeSets
 }

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

@@ -2,7 +2,7 @@ import { Grafaid } from '#lib/grafaid/index'
 import { GraphqlChange } from '#lib/graphql-change/index'
 import type { GraphqlChangeset } from '#lib/graphql-changeset/index'
 import { Path } from '@wollybeard/kit'
-import type { Schema } from '../../schema.js'
+import type { NonEmptyChangeSets } from '../../schema.js'
 
 const defaultPaths = {
   schemaFile: `./schema.graphql`,
@@ -46,13 +46,24 @@ export const normalizeConfig = (configInput: ConfigInput): Config => {
 
 export const readOrThrow = async (
   configInput: ConfigInput,
-): Promise<null | Schema> => {
+): Promise<null | NonEmptyChangeSets> => {
   const config = normalizeConfig(configInput)
 
   const schemaFile = await Grafaid.Schema.read(config.path)
   if (!schemaFile) return null
 
-  const date = new Date()
+  return await readSingleSchemaFile(config.path)
+}
+
+/**
+ * Create a single changeset from a schema file path.
+ * This is the core logic for handling single (unversioned) schemas.
+ */
+export const readSingleSchemaFile = async (filePath: string): Promise<NonEmptyChangeSets> => {
+  const schemaFile = await Grafaid.Schema.read(filePath)
+  if (!schemaFile) throw new Error(`Failed to read schema file: ${filePath}`)
+
+  const date = new Date() // Generate date here for unversioned schema
   const after = schemaFile.content
   const before = Grafaid.Schema.empty
   const changes = await GraphqlChange.calcChangeset({
@@ -60,16 +71,14 @@ export const readOrThrow = async (
     after,
   })
 
-  const schemaVersion: GraphqlChangeset.ChangeSet = {
+  const changeset: GraphqlChangeset.ChangeSet = {
     date,
     after,
     before,
     changes,
   }
 
-  const schema: Schema = {
-    versions: [schemaVersion],
-  }
+  const schema: NonEmptyChangeSets = [changeset]
 
   return schema
 }

package/src/api/schema/metadata.ts

@@ -0,0 +1,23 @@
+import { Fs } from '@wollybeard/kit'
+import { z } from 'zod/v4'
+
+export const SchemaMetadataSchema = z.object({
+  /** Whether a schema is present in the project */
+  hasSchema: z.boolean(),
+  /** Array of available version identifiers */
+  versions: z.array(z.string()),
+})
+
+export type SchemaMetadata = z.infer<typeof SchemaMetadataSchema>
+
+export const getMetadata = async (path: string): Promise<SchemaMetadata> => {
+  const result = await Fs.readJson(path)
+  if (!result) {
+    return {
+      hasSchema: false,
+      versions: [],
+    }
+  }
+
+  return SchemaMetadataSchema.parse(result)
+}

package/src/api/schema/read.ts

@@ -1,6 +1,6 @@
 import { Arr } 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`
 
@@ -55,14 +55,14 @@ export interface Config {
     /**
      * Pre-built schema object to use directly.
      */
-    data?: Schema
+    data?: NonEmptyChangeSets
   }
   projectRoot: string
 }
 
 export const readOrThrow = async (
   config: Config,
-): Promise<null | Schema> => {
+): Promise<null | NonEmptyChangeSets> => {
   if (config.enabled === false) {
     return null
   }

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'