polen 0.10.0-next.9 → 0.11.0-next.1

package/src/api/content/scan.ts

@@ -1,8 +1,8 @@
 import { FileRouter } from '#lib/file-router/index'
 import { Fs, Path, Tree } from '@wollybeard/kit'
 import matter from 'gray-matter'
-import { MetadataSchema } from './metadata.ts'
-import type { Page } from './page.ts'
+import { MetadataSchema } from './metadata.js'
+import type { Page } from './page.js'
 
 export interface ScanResult {
   list: Page[]
@@ -23,7 +23,7 @@ export const scan = async (options: {
   // Scan for routes
   const routeScanResult = await FileRouter.scan({
     dir: options.dir,
-    glob: options.glob ?? '**/*.{md,mdx}',
+    glob: options.glob ?? `**/*.{md,mdx}`,
   })
 
   // Create pages with metadata (id/parentId now come from route)
@@ -44,7 +44,42 @@ export const scan = async (options: {
     parentId: page.route.parentId,
   }))
 
-  const tree = Tree.fromList(pagesWithIds)
+  // Handle cases where there might be multiple root nodes
+  // If all pages are at root level (no parentId), create a virtual root
+  const hasMultipleRoots = pagesWithIds.filter(p => !p.parentId).length > 1
+
+  let tree: Tree.Tree<Page>
+  if (hasMultipleRoots) {
+    // Create a virtual root node to hold all root-level pages
+    const virtualRoot: Page & { id: string; parentId: null } = {
+      route: {
+        id: `__virtual_root__`,
+        parentId: null,
+        file: {
+          path: {
+            absolute: Path.parse(``),
+            relative: Path.parse(``),
+          },
+        },
+        logical: {
+          path: [],
+        },
+      },
+      metadata: { hidden: true },
+      id: `__virtual_root__`,
+      parentId: null,
+    }
+
+    // Update pages to have virtual root as parent if they don't have one
+    const pagesWithVirtualRoot = pagesWithIds.map(page => ({
+      ...page,
+      parentId: page.parentId ?? `__virtual_root__`,
+    }))
+
+    tree = Tree.fromList([virtualRoot, ...pagesWithVirtualRoot])
+  } else {
+    tree = Tree.fromList(pagesWithIds)
+  }
 
   return {
     list: pages,

package/src/api/content/sidebar.test.ts

@@ -1,8 +1,8 @@
 import * as fc from 'fast-check'
 import { describe, expect, it } from 'vitest'
-import type { Page } from './page.ts'
-import type { ScanResult } from './scan.ts'
-import { buildSidebarIndex, type Item, type SidebarIndex } from './sidebar.ts'
+import type { Page } from './page.js'
+import type { ScanResult } from './scan.js'
+import { buildSidebarIndex } from './sidebar.js'
 
 // Generators
 const pathSegmentArb = fc.stringMatching(/^[a-z][a-z0-9-]{0,19}$/)

package/src/api/content/sidebar.ts

@@ -1,7 +1,7 @@
 import { FileRouter } from '#lib/file-router/index'
 import { Str } from '@wollybeard/kit'
-import type { Page } from './page.ts'
-import type { ScanResult } from './scan.ts'
+import type { Page } from './page.js'
+import type { ScanResult } from './scan.js'
 
 /**
  * Represents a complete sidebar structure with navigation items.
@@ -27,17 +27,17 @@ export type Item = ItemLink | ItemSection
  * ```ts
  * const link: ItemLink = {
  *   type: 'ItemLink',
- *   title: 'Getting Started',
- *   pathExp: 'guide/getting-started'
+ *   title: 'Get Started',
+ *   pathExp: 'guide/get-started'
  * }
  * ```
  */
 export interface ItemLink {
   /** Discriminator for TypeScript union types */
   type: `ItemLink`
-  /** Display title for the link (e.g., "Getting Started") */
+  /** Display title for the link (e.g., "Get Started") */
   title: string
-  /** Path expression relative to the base path, without leading slash (e.g., "guide/getting-started") */
+  /** Path expression relative to the base path, without leading slash (e.g., "guide/get-started") */
   pathExp: string
 }
 
@@ -164,7 +164,7 @@ const buildSidebarForDirectory = (topLevelDir: string, pages: Page[]): Sidebar =
     }
 
     // Get the immediate parent path (e.g., for ['guide', 'advanced', 'tips'], parent is ['guide', 'advanced'])
-    const parentPath = page.route.logical.path.slice(0, -1).join('/')
+    const parentPath = page.route.logical.path.slice(0, -1).join(`/`)
 
     if (!pagesByParent.has(parentPath)) {
       pagesByParent.set(parentPath, [])
@@ -173,17 +173,17 @@ const buildSidebarForDirectory = (topLevelDir: string, pages: Page[]): Sidebar =
   }
 
   // Process top-level pages (direct children of the directory)
-  const topLevelPages = pagesByParent.get(topLevelDir) || []
+  const topLevelPages = pagesByParent.get(topLevelDir) ?? []
 
   // Sort pages by their directory order (extracted from file path)
   const sortedTopLevelPages = [...topLevelPages].sort((a, b) => {
     // For sections, we need to look at the directory name in the file path
-    const dirA = a.route.file.path.relative.dir.split('/').pop() || ''
-    const dirB = b.route.file.path.relative.dir.split('/').pop() || ''
+    const dirA = a.route.file.path.relative.dir.split(`/`).pop() ?? ``
+    const dirB = b.route.file.path.relative.dir.split(`/`).pop() ?? ``
 
     // Extract order from directory names like "10_b", "20_c"
-    const orderMatchA = dirA.match(/^(\d+)[_-]/)
-    const orderMatchB = dirB.match(/^(\d+)[_-]/)
+    const orderMatchA = /^(\d+)[_-]/.exec(dirA)
+    const orderMatchB = /^(\d+)[_-]/.exec(dirB)
 
     const orderA = orderMatchA ? parseInt(orderMatchA[1]!, 10) : Number.MAX_SAFE_INTEGER
     const orderB = orderMatchB ? parseInt(orderMatchB[1]!, 10) : Number.MAX_SAFE_INTEGER
@@ -196,15 +196,15 @@ const buildSidebarForDirectory = (topLevelDir: string, pages: Page[]): Sidebar =
 
   for (const page of sortedTopLevelPages) {
     const pageName = page.route.logical.path[page.route.logical.path.length - 1]!
-    const childPath = page.route.logical.path.join('/')
-    const childPages = pagesByParent.get(childPath) || []
+    const childPath = page.route.logical.path.join(`/`)
+    const childPages = pagesByParent.get(childPath) ?? []
 
     if (childPages.length > 0 || FileRouter.routeIsFromIndexFile(page.route)) {
       // This is a section (has children or is an index page for a subdirectory)
       const hasIndex = FileRouter.routeIsFromIndexFile(page.route)
 
       const section: ItemSection = {
-        type: 'ItemSection',
+        type: `ItemSection`,
         title: Str.titlizeSlug(pageName),
         pathExp: childPath,
         isLinkToo: hasIndex,
@@ -221,9 +221,9 @@ const buildSidebarForDirectory = (topLevelDir: string, pages: Page[]): Sidebar =
       for (const childPage of sortedChildPages) {
         if (!FileRouter.routeIsFromIndexFile(childPage.route)) {
           section.links.push({
-            type: 'ItemLink',
+            type: `ItemLink`,
             title: Str.titlizeSlug(childPage.route.logical.path[childPage.route.logical.path.length - 1]!),
-            pathExp: childPage.route.logical.path.join('/'),
+            pathExp: childPage.route.logical.path.join(`/`),
           })
         }
       }
@@ -232,7 +232,7 @@ const buildSidebarForDirectory = (topLevelDir: string, pages: Page[]): Sidebar =
       const allDescendants: Page[] = []
       for (const [parentPath, pagesInParent] of pagesByParent) {
         // Check if this path is a descendant (but not direct child)
-        if (parentPath.startsWith(childPath + '/')) {
+        if (parentPath.startsWith(childPath + `/`)) {
           for (const descendantPage of pagesInParent) {
             if (!FileRouter.routeIsFromIndexFile(descendantPage.route)) {
               allDescendants.push(descendantPage)
@@ -258,11 +258,11 @@ const buildSidebarForDirectory = (topLevelDir: string, pages: Page[]): Sidebar =
 
       for (const descendantPage of allDescendants) {
         section.links.push({
-          type: 'ItemLink',
+          type: `ItemLink`,
           title: Str.titlizeSlug(
             descendantPage.route.logical.path[descendantPage.route.logical.path.length - 1]!,
           ),
-          pathExp: descendantPage.route.logical.path.join('/'),
+          pathExp: descendantPage.route.logical.path.join(`/`),
         })
       }
 
@@ -272,9 +272,9 @@ const buildSidebarForDirectory = (topLevelDir: string, pages: Page[]): Sidebar =
     } else {
       // This is a simple link
       items.push({
-        type: 'ItemLink',
+        type: `ItemLink`,
         title: Str.titlizeSlug(pageName),
-        pathExp: page.route.logical.path.join('/'),
+        pathExp: page.route.logical.path.join(`/`),
       })
     }
   }

package/src/api/content/utils.ts

@@ -0,0 +1,7 @@
+/**
+ * Check if a file path represents a page file (markdown or MDX)
+ */
+export const isPageFile = (filePath: string, pagesDirectory: string): boolean => {
+  return (filePath.endsWith(`.md`) || filePath.endsWith(`.mdx`))
+    && filePath.includes(pagesDirectory)
+}

package/src/api/index.ts

@@ -1 +1 @@
-export * as Api from './api.ts'
+export * as Api from './api.js'

package/src/api/project/index.ts

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

package/src/api/project/validate.ts

@@ -0,0 +1,41 @@
+import { Fs } from '@wollybeard/kit'
+import consola from 'consola'
+
+export interface ValidateProjectOptions {
+  mustExist?: boolean
+  mustBeEmpty?: boolean
+  silent?: boolean
+}
+
+/**
+ * Validate a project directory for Polen operations.
+ * Used by CLI commands to ensure valid project paths.
+ */
+export async function validateProjectDirectory(
+  dir: string,
+  options: ValidateProjectOptions = {},
+): Promise<boolean> {
+  const { mustExist = true, mustBeEmpty = false, silent = false } = options
+
+  const stat = await Fs.stat(dir)
+
+  if (Fs.isNotFoundError(stat)) {
+    if (mustExist) {
+      if (!silent) consola.error(`Project directory does not exist: ${dir}`)
+      return false
+    }
+    return true
+  }
+
+  if (!stat.isDirectory()) {
+    if (!silent) consola.error(`Project path is not a directory: ${dir}`)
+    return false
+  }
+
+  if (mustBeEmpty && !(await Fs.isEmptyDir(dir))) {
+    if (!silent) consola.error(`Project directory is not empty: ${dir}`)
+    return false
+  }
+
+  return true
+}

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

@@ -1,3 +1,3 @@
-export * as Memory from './memory/memory.ts'
-export * as SchemaDirectory from './schema-directory/schema-directory.ts'
-export * as SchemaFile from './schema-file/schema-file.ts'
+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/index.ts

@@ -1 +1 @@
-export * as DataSources from './data-sources.ts'
+export * as DataSources from './data-sources.js'

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

@@ -2,9 +2,44 @@ 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.ts'
+import type { NonEmptyChangeSets } from '../../schema.js'
 
+/**
+ * Configuration for defining schemas programmatically in memory.
+ *
+ * Useful for demos, testing, or when schemas are generated dynamically.
+ */
 export interface ConfigInput {
+  /**
+   * Schema versions defined as SDL strings.
+   *
+   * Can be:
+   * - A single SDL string (no changelog)
+   * - Array of SDL strings (uses current date for all)
+   * - Array of objects with date and SDL (full changelog support)
+   *
+   * @example
+   * ```ts
+   * // Single schema
+   * versions: `
+   *   type Query {
+   *     hello: String
+   *   }
+   * `
+   *
+   * // Multiple versions with explicit dates
+   * versions: [
+   *   {
+   *     date: new Date('2024-01-15'),
+   *     value: `type Query { users: [User] }`
+   *   },
+   *   {
+   *     date: new Date('2024-03-20'),
+   *     value: `type Query { users: [User], posts: [Post] }`
+   *   }
+   * ]
+   * ```
+   */
   versions:
     | string
     | string[]
@@ -33,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)) {
@@ -74,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,47 +18,62 @@ 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
 // }
 
-// // eslint-disable-next-line
 // const parseExpressionLatestSerialized = (serializedExpression: string): null | {} => {
 //   if (serializedExpression === `latest`) return {}
 //   return null

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

@@ -1 +1 @@
-export * as FileNameExpression from './file-name-expression.ts'
+export * as FileNameExpression from './file-name-expression.js'

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

@@ -4,8 +4,9 @@ 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.ts'
-import { FileNameExpression } from './file-name-expression/index.ts'
+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`])
 const debug = debugPolen.sub(`schema:data-source-schema-directory`)
@@ -14,7 +15,45 @@ const defaultPaths = {
   schemaDirectory: `./schema`,
 }
 
+/**
+ * Configuration for loading schema(s) from a directory.
+ *
+ * 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 schema files.
+   *
+   * Supports two patterns:
+   * 1. Multiple versioned files with ISO date prefixes: `YYYY-MM-DD.graphql`
+   * 2. Single file named: `schema.graphql`
+   *
+   * @default './schema'
+   *
+   * @example
+   * ```ts
+   * // Default location
+   * path: './schema'
+   *
+   * // Custom location
+   * path: './graphql/versions'
+   * ```
+   *
+   * 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
   projectRoot?: string
 }
@@ -32,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)
@@ -51,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}`)
@@ -61,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())
 
@@ -89,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,13 +2,32 @@ 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.ts'
+import type { NonEmptyChangeSets } from '../../schema.js'
 
 const defaultPaths = {
   schemaFile: `./schema.graphql`,
 }
 
+/**
+ * Configuration for loading schema from a single SDL file.
+ */
 export interface ConfigInput {
+  /**
+   * Path to the GraphQL SDL file.
+   *
+   * Can be absolute or relative to the project root.
+   *
+   * @default './schema.graphql'
+   *
+   * @example
+   * ```ts
+   * // Default location
+   * path: './schema.graphql'
+   *
+   * // Custom location
+   * path: './src/graphql/schema.sdl'
+   * ```
+   */
   path?: string
   projectRoot?: string
 }
@@ -27,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({
@@ -41,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/index.ts

@@ -1 +1 @@
-export * as Schema from './schema.ts'
+export * as Schema from './schema.js'

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)
+}