canopycms 0.0.0

package/src/config/types.ts

@@ -0,0 +1,321 @@
+/**
+ * Type definitions for CanopyCMS configuration.
+ * These are pure TypeScript types - Zod schemas are in ./schemas/
+ */
+
+import type { CanopyGroupId, CanopyUserId } from '../types'
+import type { OperatingMode } from '../operating-mode'
+import type { AuthPlugin } from '../auth/plugin'
+import type { LogicalPath, ContentId } from '../paths/types'
+import type { PermissionPath } from '../authorization/types'
+
+// Field types
+export const primitiveFieldTypes = [
+  'string',
+  'number',
+  'boolean',
+  'datetime',
+  'rich-text',
+  'markdown',
+  'mdx',
+  'image',
+  'code',
+] as const
+
+export const fieldTypes = [
+  ...primitiveFieldTypes,
+  'select',
+  'reference',
+  'object',
+  'block',
+] as const
+
+export type PrimitiveFieldType = (typeof primitiveFieldTypes)[number]
+export type FieldType = (typeof fieldTypes)[number]
+export type ContentFormat = 'md' | 'mdx' | 'json'
+export type MediaAdapterKind = 'local' | 's3' | 'lfs' | (string & {})
+
+// Permission types
+export type PermissionLevel = 'read' | 'edit' | 'review'
+
+export interface PermissionTarget {
+  allowedUsers?: CanopyUserId[]
+  allowedGroups?: CanopyGroupId[]
+}
+
+export interface PathPermission {
+  path: PermissionPath
+  read?: PermissionTarget
+  edit?: PermissionTarget
+  review?: PermissionTarget
+}
+
+// Select/Reference options
+export type SelectOption = string | { label: string; value: string }
+export type ReferenceOption = string | { label: string; value: string }
+
+// Field configuration types
+export interface BaseFieldConfig {
+  name: string
+  label?: string
+  description?: string
+  required?: boolean
+  list?: boolean
+}
+
+export interface PrimitiveFieldConfig extends BaseFieldConfig {
+  type: PrimitiveFieldType
+}
+
+export interface SelectFieldConfig extends BaseFieldConfig {
+  type: 'select'
+  options: SelectOption[]
+}
+
+export interface ReferenceFieldConfig extends BaseFieldConfig {
+  type: 'reference'
+  collections: string[]
+  displayField?: string
+  options?: ReferenceOption[]
+}
+
+export interface BlockConfig {
+  name: string
+  label?: string
+  description?: string
+  fields: FieldConfig[]
+}
+
+export interface BlockFieldConfig extends BaseFieldConfig {
+  type: 'block'
+  templates: BlockConfig[]
+}
+
+export interface ObjectFieldConfig extends BaseFieldConfig {
+  type: 'object'
+  fields: FieldConfig[]
+}
+
+/**
+ * Custom field config for user-defined field types.
+ * The type must not conflict with built-in types.
+ * Note: We use a branded type approach to avoid index signature issues.
+ */
+export type CustomFieldConfig = BaseFieldConfig & {
+  type: Exclude<string, FieldType>
+}
+
+export type FieldConfig =
+  | PrimitiveFieldConfig
+  | SelectFieldConfig
+  | ReferenceFieldConfig
+  | BlockFieldConfig
+  | ObjectFieldConfig
+  | CustomFieldConfig
+
+// Media configuration
+export type MediaConfig =
+  | { adapter: 'local'; publicBaseUrl?: string }
+  | { adapter: 's3'; bucket: string; region: string; publicBaseUrl?: string }
+  | { adapter: 'lfs'; publicBaseUrl?: string }
+  | { adapter: string; publicBaseUrl?: string }
+
+/**
+ * Field definitions for one entry type — the array of FieldConfig that
+ * describes which fields an entry of this type contains.
+ *
+ * Contrast with BranchSchema, which is the full collection tree for a branch.
+ */
+export type EntrySchema = readonly FieldConfig[]
+
+/**
+ * Entry type config: defines a type of content within a collection.
+ * Each type has its own entry schema (fields) and can have cardinality constraints.
+ *
+ * Examples:
+ * - { name: 'post', format: 'mdx', schema: postSchema } - unlimited posts
+ * - { name: 'settings', format: 'json', schema: settingsSchema, maxItems: 1 } - restricted to one instance
+ */
+export type EntryTypeConfig = {
+  readonly name: string
+  readonly format: ContentFormat
+  readonly schema: EntrySchema
+  /** Entry schema registry key (e.g., "postSchema"). Set during schema resolution. */
+  readonly schemaRef?: string
+  readonly label?: string
+  readonly description?: string
+  readonly default?: boolean // Is this the default type for "Add" button?
+  readonly maxItems?: number // Limit instances (e.g., 1 = only one entry allowed)
+}
+
+/**
+ * Collection: contains nested collections and typed entries.
+ * The entries array defines the types of content allowed in this collection.
+ */
+export type CollectionConfig = {
+  readonly name: string
+  readonly path: string
+  readonly label?: string
+  readonly description?: string
+  /** 12-char content ID from the collection's directory name. Optional: absent in static configs. */
+  readonly contentId?: ContentId
+  /** Array of entry types allowed in this collection */
+  readonly entries?: readonly EntryTypeConfig[]
+  readonly collections?: readonly CollectionConfig[]
+  /** Ordering of items by embedded ID. Items not in order appear at end alphabetically. */
+  readonly order?: readonly string[]
+}
+
+/**
+ * Root schema configuration for CanopyCMS.
+ * Contains top-level collections and entries (typed content at the root level).
+ */
+export type RootCollectionConfig = {
+  /** Optional label for the root collection (e.g., "All Files", "Content") */
+  readonly label?: string
+  /** Entry types at the root level */
+  readonly entries?: readonly EntryTypeConfig[]
+  readonly collections?: readonly CollectionConfig[]
+  /** Ordering of root items by embedded ID. Items not in order appear at end alphabetically. */
+  readonly order?: readonly string[]
+}
+
+/**
+ * The full collection structure tree for one branch — the resolved schema
+ * describing all collections, entry types, and their fields.
+ *
+ * Contrast with EntrySchema, which is the field definitions for a single entry type.
+ */
+export type BranchSchema = RootCollectionConfig
+
+// Editor configuration
+export interface CanopyEditorConfig {
+  title?: string
+  subtitle?: string
+  theme?: unknown
+  previewBase?: Record<string, string>
+  onAccountClick?: () => void
+  onLogoutClick?: () => void
+  AccountComponent?: React.ComponentType
+}
+
+// Default value types
+export type DefaultBranchAccess = 'allow' | 'deny'
+export type DefaultPathAccess = 'allow' | 'deny'
+export type DefaultBaseBranch = string
+export type DefaultRemoteName = string
+export type DefaultRemoteUrl = string
+export type GitBotAuthorName = string
+export type GitBotAuthorEmail = string
+export type GithubTokenEnvVar = string
+export type CanopyOperatingMode = OperatingMode
+export type ContentRoot = string
+export type SourceRoot = string | undefined
+
+/**
+ * Validated CanopyConfig - the runtime configuration object.
+ */
+export interface CanopyConfig {
+  media?: MediaConfig
+  defaultBranchAccess?: DefaultBranchAccess
+  defaultPathAccess?: DefaultPathAccess
+  defaultBaseBranch?: DefaultBaseBranch
+  defaultRemoteName?: DefaultRemoteName
+  defaultRemoteUrl?: DefaultRemoteUrl
+  gitBotAuthorName: GitBotAuthorName
+  gitBotAuthorEmail: GitBotAuthorEmail
+  githubTokenEnvVar?: GithubTokenEnvVar
+  mode: CanopyOperatingMode
+  settingsBranch?: string
+  autoCreateSettingsPR?: boolean
+  deploymentName?: string
+  contentRoot: ContentRoot
+  sourceRoot?: SourceRoot
+  editor?: CanopyEditorConfig
+  authPlugin?: AuthPlugin
+}
+
+/**
+ * Input type for config authoring (allows looser types before validation)
+ */
+export interface CanopyConfigInput {
+  media?: MediaConfig
+  defaultBranchAccess?: DefaultBranchAccess
+  defaultPathAccess?: DefaultPathAccess
+  defaultBaseBranch?: string
+  defaultRemoteName?: string
+  defaultRemoteUrl?: string
+  gitBotAuthorName: string
+  gitBotAuthorEmail: string
+  githubTokenEnvVar?: string
+  mode?: OperatingMode
+  settingsBranch?: string
+  autoCreateSettingsPR?: boolean
+  deploymentName?: string
+  contentRoot?: string
+  sourceRoot?: string
+  editor?: CanopyEditorConfig
+  authPlugin?: AuthPlugin
+}
+
+export type CanopyConfigFragment = Partial<CanopyConfigInput>
+
+/**
+ * Flattened schema item for efficient lookups.
+ * Discriminated union of collection or entry type with logical path resolved.
+ * Used for O(1) schema lookups via Map<logicalPath, FlatSchemaItem>.
+ */
+export type FlatSchemaItem =
+  | {
+      type: 'collection'
+      logicalPath: LogicalPath
+      name: string
+      label?: string
+      description?: string
+      /** 12-char content ID from the collection's directory name. Optional: absent in static configs. */
+      contentId?: ContentId
+      parentPath?: LogicalPath
+      /** Array of entry types in this collection */
+      entries?: readonly EntryTypeConfig[]
+      collections?: readonly CollectionConfig[]
+      /** Ordering of items by embedded ID. Items not in order appear at end alphabetically. */
+      order?: readonly string[]
+    }
+  | {
+      /** An entry type within a collection */
+      type: 'entry-type'
+      logicalPath: LogicalPath
+      /** The entry type name (e.g., 'post', 'doc') */
+      name: string
+      label?: string
+      description?: string
+      /** Path of the parent collection */
+      parentPath: LogicalPath
+      format: ContentFormat
+      schema: EntrySchema
+      /** Entry schema registry key (e.g., "postSchema"). Set during schema resolution. */
+      schemaRef?: string
+      default?: boolean
+      maxItems?: number
+    }
+
+/**
+ * Client config - subset safe for browser (DRY - derived from CanopyConfig)
+ * Use flatSchema for O(1) cached access to the flattened schema structure.
+ * Schema is loaded from .collection.json files on the server and provided as flatSchema.
+ */
+export type CanopyClientConfig = Pick<
+  CanopyConfig,
+  'defaultBaseBranch' | 'contentRoot' | 'editor' | 'mode'
+> & {
+  flatSchema: FlatSchemaItem[]
+}
+
+// Client-only fields that can be provided as overrides (e.g., from auth providers)
+export interface ClientOnlyFields {
+  editor?: {
+    onAccountClick?: () => void
+    onLogoutClick?: () => void | Promise<void>
+    AccountComponent?: React.ComponentType
+  }
+}

package/src/config/validation.ts

@@ -0,0 +1,70 @@
+/**
+ * Configuration validation utilities.
+ */
+
+import { CanopyConfigSchema } from './schemas/config'
+import { normalizePathValue, normalizeSchemaPathsRoot } from './flatten'
+import type { CanopyConfig } from './types'
+
+/**
+ * Recursively check that all select fields have options defined.
+ * Throws an error if a select field is missing options.
+ */
+export const ensureSelectFieldsHaveOptions = (config: unknown): void => {
+  const checkFields = (fields: unknown[] | undefined) => {
+    if (!Array.isArray(fields)) return
+    for (const field of fields) {
+      const f = field as Record<string, unknown>
+      if (f?.type === 'select' && (!Array.isArray(f.options) || f.options.length === 0)) {
+        const fieldName = (f?.name as string) ?? 'unknown'
+        throw new Error(`Select field "${fieldName}" requires options`)
+      }
+      if (f?.type === 'object') {
+        checkFields(f.fields as unknown[])
+      }
+      if (f?.type === 'block' && Array.isArray(f.templates)) {
+        for (const template of f.templates as Array<{ fields?: unknown[] }>) {
+          checkFields(template.fields)
+        }
+      }
+    }
+  }
+
+  const walkSchema = (root: Record<string, unknown> | undefined) => {
+    if (!root) return
+    // Check entries fields (now an array of entry types)
+    if (Array.isArray(root.entries)) {
+      for (const entryType of root.entries as Array<{ schema?: unknown[] }>) {
+        checkFields(entryType?.schema)
+      }
+    }
+    // Recursively check nested collections
+    if (Array.isArray(root.collections)) {
+      for (const collection of root.collections as Array<Record<string, unknown>>) {
+        walkSchema(collection)
+      }
+    }
+  }
+
+  walkSchema((config as Record<string, unknown>)?.schema as Record<string, unknown>)
+}
+
+/**
+ * Validate and normalize a CanopyConfig object.
+ * Performs Zod validation, checks select field options, and normalizes paths.
+ *
+ * @param config - Raw configuration input
+ * @returns Validated and normalized CanopyConfig
+ * @throws Error if validation fails
+ */
+export const validateCanopyConfig = (config: unknown): CanopyConfig => {
+  ensureSelectFieldsHaveOptions(config)
+  const parsed = CanopyConfigSchema.parse(config)
+  const normalized = {
+    ...parsed,
+    contentRoot: normalizePathValue(parsed.contentRoot ?? 'content'),
+    schema: parsed.schema ? normalizeSchemaPathsRoot(parsed.schema) : undefined,
+  }
+
+  return normalized as CanopyConfig
+}

package/src/config-test.ts

@@ -0,0 +1,65 @@
+import type { CanopyConfig, CanopyConfigInput, RootCollectionConfig } from './config'
+import { defineCanopyConfig, flattenSchema } from './config'
+import {
+  createTestCanopyServices,
+  type CanopyServices,
+  type CreateCanopyServicesOptions,
+} from './services'
+
+const FALLBACK_AUTHOR = {
+  gitBotAuthorName: 'CanopyCMS Test Bot',
+  gitBotAuthorEmail: 'canopycms-test@example.com',
+}
+
+type TestConfigInput = Omit<
+  CanopyConfigInput,
+  'gitBotAuthorName' | 'gitBotAuthorEmail' | 'schema'
+> & {
+  schema: RootCollectionConfig
+} & Partial<Pick<CanopyConfigInput, 'gitBotAuthorName' | 'gitBotAuthorEmail'>>
+
+/**
+ * Test-only helper that fills required author fields for convenience.
+ * Do not use in production code; prefer defineCanopyConfig.
+ */
+export const defineCanopyTestConfig = (
+  config: TestConfigInput,
+  overrides?: Partial<CanopyConfigInput>,
+): CanopyConfig => {
+  // Destructure to exclude schema from being spread into defineCanopyConfig
+  const { schema: _schema, ...configWithoutSchema } = config
+  return defineCanopyConfig({
+    ...FALLBACK_AUTHOR,
+    ...configWithoutSchema,
+    ...(overrides ?? {}),
+  }).server
+}
+
+/**
+ * Test-only helper that creates CanopyServices with inline schema.
+ * Creates a mock branchSchemaCache that returns the test schema without requiring .collection.json files.
+ * Do not use in production code; use createCanopyServices with entrySchemaRegistry.
+ */
+export const createTestServices = async (
+  config: TestConfigInput,
+  options?: CreateCanopyServicesOptions,
+): Promise<CanopyServices> => {
+  const canopyConfig = defineCanopyTestConfig(config)
+  const flatSchema = flattenSchema(config.schema, canopyConfig.contentRoot)
+
+  // Create a mock branchSchemaCache that returns the test schema
+  const mockBranchSchemaCache = {
+    getSchema: async () => ({
+      schema: config.schema,
+      flatSchema,
+    }),
+    invalidate: async () => {},
+    clearAll: async () => {},
+  }
+
+  return createTestCanopyServices(canopyConfig, {
+    ...options,
+    branchSchemaCache:
+      mockBranchSchemaCache as unknown as CreateCanopyServicesOptions['branchSchemaCache'],
+  })
+}

package/src/config.ts

@@ -0,0 +1,11 @@
+/**
+ * CanopyCMS Configuration
+ *
+ * This file re-exports from the config module for backward compatibility.
+ * New code should import directly from './config/index' or './config'.
+ *
+ * @module config
+ */
+
+// Re-export everything from the config module
+export * from './config/index'