canopycms 0.0.0

package/src/config/helpers.ts

@@ -0,0 +1,167 @@
+/**
+ * Helper functions for authoring CanopyCMS configuration files.
+ */
+
+import { validateCanopyConfig } from './validation'
+import type {
+  CanopyConfig,
+  CanopyConfigFragment,
+  CanopyConfigInput,
+  CanopyClientConfig,
+  ClientOnlyFields,
+  ContentRoot,
+  DefaultBaseBranch,
+  DefaultBranchAccess,
+  DefaultPathAccess,
+  DefaultRemoteName,
+  DefaultRemoteUrl,
+  GitBotAuthorEmail,
+  GitBotAuthorName,
+  CanopyOperatingMode,
+  MediaConfig,
+  SourceRoot,
+} from './types'
+
+export type CanopyConfigAuthoring = CanopyConfigInput
+
+/**
+ * Helper for authoring typed config files (canopycms.config.ts).
+ * Performs runtime validation using the CanopyConfig schema.
+ * Returns a bundle with `server` (full config) and `client(overrides)` (safe subset).
+ *
+ * @example
+ * ```ts
+ * // canopycms.config.ts
+ * import { defineCanopyConfig } from 'canopycms'
+ *
+ * export const canopyConfig = defineCanopyConfig({
+ *   gitBotAuthorName: 'Bot',
+ *   gitBotAuthorEmail: 'bot@example.com',
+ *   schema: {
+ *     collections: [...]
+ *   }
+ * })
+ * ```
+ */
+export function defineCanopyConfig(config: CanopyConfigInput | CanopyConfigAuthoring) {
+  const validated = validateCanopyConfig(config as CanopyConfigInput)
+
+  return {
+    // Full server config - all fields including sensitive data
+    server: validated,
+
+    // Client config helper - extracts safe subset and merges overrides
+    // Note: flatSchema is loaded dynamically by the editor via API (from .collection.json files)
+    client: (clientOverrides?: ClientOnlyFields): CanopyClientConfig => {
+      const { defaultBaseBranch, contentRoot, editor, mode } = validated
+      const clientConfig: CanopyClientConfig = {
+        defaultBaseBranch,
+        contentRoot,
+        editor,
+        mode,
+        flatSchema: [], // Loaded dynamically by editor via API
+      }
+
+      // Merge client overrides (e.g., auth handlers from useClerkAuthConfig)
+      if (clientOverrides?.editor) {
+        clientConfig.editor = {
+          ...clientConfig.editor,
+          ...clientOverrides.editor,
+        }
+      }
+
+      return clientConfig
+    },
+  }
+}
+
+/**
+ * Helper to compose config fragments defined across multiple files.
+ * Useful for splitting large configurations into domain-specific modules.
+ * Later fragments can override media.
+ *
+ * @example
+ * ```ts
+ * // posts.config.ts
+ * export const postsConfig = { media: {...}, contentRoot: 'content/posts' }
+ *
+ * // canopycms.config.ts
+ * import { composeCanopyConfig } from 'canopycms'
+ * import { postsConfig } from './posts.config'
+ * import { pagesConfig } from './pages.config'
+ *
+ * export const config = composeCanopyConfig(postsConfig, pagesConfig)
+ * ```
+ */
+export const composeCanopyConfig = (...fragments: CanopyConfigFragment[]): CanopyConfig => {
+  let media: MediaConfig | undefined
+  let contentRoot: ContentRoot | undefined
+  let sourceRoot: SourceRoot | undefined
+  let defaultBranchAccess: DefaultBranchAccess | undefined
+  let defaultPathAccess: DefaultPathAccess | undefined
+  let defaultBaseBranch: DefaultBaseBranch | undefined
+  let defaultRemoteName: DefaultRemoteName | undefined
+  let defaultRemoteUrl: DefaultRemoteUrl | undefined
+  let gitBotAuthorName: GitBotAuthorName | undefined
+  let gitBotAuthorEmail: GitBotAuthorEmail | undefined
+  let mode: CanopyOperatingMode | undefined
+  let deploymentName: string | undefined
+
+  for (const fragment of fragments) {
+    if (fragment.media) {
+      media = fragment.media
+    }
+    if (fragment.contentRoot) {
+      contentRoot = fragment.contentRoot
+    }
+    if (fragment.sourceRoot) {
+      sourceRoot = fragment.sourceRoot
+    }
+    if (fragment.defaultBranchAccess) {
+      defaultBranchAccess = fragment.defaultBranchAccess
+    }
+    if (fragment.defaultPathAccess) {
+      defaultPathAccess = fragment.defaultPathAccess
+    }
+    if (fragment.defaultBaseBranch) {
+      defaultBaseBranch = fragment.defaultBaseBranch
+    }
+    if (fragment.defaultRemoteName) {
+      defaultRemoteName = fragment.defaultRemoteName
+    }
+    if (fragment.defaultRemoteUrl) {
+      defaultRemoteUrl = fragment.defaultRemoteUrl
+    }
+    if (fragment.gitBotAuthorName) {
+      gitBotAuthorName = fragment.gitBotAuthorName
+    }
+    if (fragment.gitBotAuthorEmail) {
+      gitBotAuthorEmail = fragment.gitBotAuthorEmail
+    }
+    if (fragment.mode) {
+      mode = fragment.mode
+    }
+    if (fragment.deploymentName) {
+      deploymentName = fragment.deploymentName
+    }
+  }
+
+  const merged: CanopyConfigInput = {
+    gitBotAuthorName: gitBotAuthorName ?? '',
+    gitBotAuthorEmail: gitBotAuthorEmail ?? '',
+    ...(media ? { media } : {}),
+    ...(contentRoot ? { contentRoot } : {}),
+    ...(sourceRoot ? { sourceRoot } : {}),
+    ...(defaultBranchAccess ? { defaultBranchAccess } : {}),
+    ...(defaultPathAccess ? { defaultPathAccess } : {}),
+    ...(defaultBaseBranch ? { defaultBaseBranch } : {}),
+    ...(defaultRemoteName ? { defaultRemoteName } : {}),
+    ...(defaultRemoteUrl ? { defaultRemoteUrl } : {}),
+    ...(gitBotAuthorName ? { gitBotAuthorName } : {}),
+    ...(gitBotAuthorEmail ? { gitBotAuthorEmail } : {}),
+    ...(mode ? { mode } : {}),
+    ...(deploymentName ? { deploymentName } : {}),
+  }
+
+  return validateCanopyConfig(merged)
+}

package/src/config/index.ts

@@ -0,0 +1,86 @@
+/**
+ * CanopyCMS Configuration Module
+ *
+ * This module provides types, schemas, and utilities for configuring CanopyCMS.
+ *
+ * @example
+ * ```ts
+ * import { defineCanopyConfig, type FieldConfig } from 'canopycms/config'
+ * ```
+ */
+
+// Re-export all types
+export type {
+  // Field types
+  PrimitiveFieldType,
+  FieldType,
+  ContentFormat,
+  MediaAdapterKind,
+  // Permission types
+  PermissionLevel,
+  PermissionTarget,
+  PathPermission,
+  // Field configs
+  SelectOption,
+  ReferenceOption,
+  FieldConfig,
+  BlockConfig,
+  BlockFieldConfig,
+  SelectFieldConfig,
+  ReferenceFieldConfig,
+  ObjectFieldConfig,
+  CustomFieldConfig,
+  // Schema types
+  EntrySchema,
+  BranchSchema,
+  EntryTypeConfig,
+  CollectionConfig,
+  RootCollectionConfig,
+  // Media
+  MediaConfig,
+  // Editor
+  CanopyEditorConfig,
+  // Config types
+  DefaultBranchAccess,
+  DefaultPathAccess,
+  DefaultBaseBranch,
+  DefaultRemoteName,
+  DefaultRemoteUrl,
+  GitBotAuthorName,
+  GitBotAuthorEmail,
+  GithubTokenEnvVar,
+  CanopyOperatingMode,
+  ContentRoot,
+  SourceRoot,
+  CanopyConfig,
+  CanopyConfigInput,
+  CanopyConfigFragment,
+  FlatSchemaItem,
+  CanopyClientConfig,
+  ClientOnlyFields,
+} from './types'
+
+// Re-export type constants
+export { primitiveFieldTypes, fieldTypes } from './types'
+
+// Re-export schemas (for advanced use cases)
+export { CanopyConfigSchema, getConfigDefaults, DEFAULT_PROD_WORKSPACE } from './schemas/config'
+export {
+  fieldSchema,
+  blockSchema,
+  selectOptionSchema,
+  referenceOptionSchema,
+} from './schemas/field'
+export {
+  collectionSchema,
+  rootCollectionSchema,
+  entryTypeSchema,
+  relativePathSchema,
+} from './schemas/collection'
+export { permissionTargetSchema, pathPermissionSchema } from './schemas/permissions'
+export { mediaSchema } from './schemas/media'
+
+// Re-export utilities
+export { flattenSchema, normalizePathValue, normalizeSchemaPathsRoot } from './flatten'
+export { validateCanopyConfig, ensureSelectFieldsHaveOptions } from './validation'
+export { defineCanopyConfig, composeCanopyConfig, type CanopyConfigAuthoring } from './helpers'

package/src/config/schemas/collection.ts

@@ -0,0 +1,67 @@
+/**
+ * Zod schemas for collection configuration validation.
+ */
+
+import { z } from 'zod'
+import { isAbsolute } from 'pathe'
+
+import { fieldSchema } from './field'
+
+// Relative path schema - validates and normalizes paths
+export const relativePathSchema = z
+  .string()
+  .min(1)
+  .refine((val) => !isAbsolute(val), { message: 'Path must be relative' })
+  .refine((val) => !val.split(/[\\/]+/).includes('..'), {
+    message: 'Path must not contain ".."',
+  })
+  .transform((val) =>
+    val
+      .split(/[\\/]+/)
+      .filter(Boolean)
+      .join('/'),
+  )
+
+/**
+ * Entry type schema: defines a type of content within a collection.
+ * Each type has its own 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 const entryTypeSchema = z.object({
+  name: z.string().min(1),
+  format: z.enum(['md', 'mdx', 'json']),
+  schema: z.array(z.lazy(() => fieldSchema)).min(1),
+  label: z.string().optional(),
+  description: z.string().optional(),
+  default: z.boolean().optional(),
+  maxItems: z.number().int().positive().optional(),
+})
+
+// Recursive collection schema
+const collectionSchema: z.ZodTypeAny = z.lazy(() =>
+  z
+    .object({
+      name: z.string().min(1),
+      path: relativePathSchema,
+      label: z.string().optional(),
+      description: z.string().optional(),
+      entries: z.array(entryTypeSchema).optional(),
+      collections: z.array(collectionSchema).optional(),
+      order: z.array(z.string()).optional(), // Embedded IDs for ordering items
+    })
+    .refine((data) => data.entries || data.collections, {
+      message: 'Collection must have entries or collections',
+    }),
+)
+
+// Root collection: no name/path required (top-level schema)
+export const rootCollectionSchema = z.object({
+  entries: z.array(entryTypeSchema).optional(),
+  collections: z.array(collectionSchema).optional(),
+  order: z.array(z.string()).optional(), // Embedded IDs for ordering items
+})
+
+export { collectionSchema }

package/src/config/schemas/config.ts

@@ -0,0 +1,77 @@
+/**
+ * Main CanopyConfig Zod schema - composes all sub-schemas.
+ */
+
+import { z } from 'zod'
+
+import type { AuthPlugin } from '../../auth/plugin'
+import { rootCollectionSchema, relativePathSchema } from './collection'
+import { mediaSchema } from './media'
+
+// Default value schemas
+export const defaultBranchAccessSchema = z.enum(['allow', 'deny']).default('deny')
+export const defaultPathAccessSchema = z.enum(['allow', 'deny']).default('deny')
+export const defaultBaseBranchSchema = z.string().default('main')
+export const defaultRemoteNameSchema = z.string().default('origin')
+export const defaultRemoteUrlSchema = z.string().min(1)
+export const gitBotAuthorNameSchema = z.string().min(1)
+export const gitBotAuthorEmailSchema = z.string().email()
+export const githubTokenEnvVarSchema = z.string().default('GITHUB_BOT_TOKEN')
+export const operatingModeSchema = z.enum(['prod', 'prod-sim', 'dev']).default('dev')
+export const contentRootSchema = relativePathSchema.default('content')
+export const sourceRootSchema = z.string().min(1).optional()
+export const deploymentNameSchema = z.string().default('prod')
+
+// Editor configuration schema
+export const editorConfigSchema = z.object({
+  title: z.string().optional(),
+  subtitle: z.string().optional(),
+  theme: z.unknown().optional(),
+  previewBase: z.record(z.string()).optional(),
+  // UI handler functions (runtime only, don't serialize)
+  onAccountClick: z.function().returns(z.void()).optional(),
+  onLogoutClick: z.function().returns(z.void()).optional(),
+  // Optional: custom account component (e.g., Clerk's UserButton)
+  AccountComponent: z.custom<React.ComponentType>().optional(),
+})
+
+// Main CanopyConfig schema
+export const CanopyConfigSchema = z.object({
+  schema: rootCollectionSchema.optional(),
+  media: mediaSchema.optional(),
+  defaultBranchAccess: defaultBranchAccessSchema.optional(),
+  defaultPathAccess: defaultPathAccessSchema.optional(),
+  defaultBaseBranch: defaultBaseBranchSchema.optional(),
+  defaultRemoteName: defaultRemoteNameSchema.optional(),
+  defaultRemoteUrl: defaultRemoteUrlSchema.optional(),
+  gitBotAuthorName: gitBotAuthorNameSchema,
+  gitBotAuthorEmail: gitBotAuthorEmailSchema,
+  githubTokenEnvVar: githubTokenEnvVarSchema.optional(),
+  mode: operatingModeSchema, // Has .default(), so not optional in output type
+  settingsBranch: z.string().optional(),
+  autoCreateSettingsPR: z.boolean().optional(),
+  deploymentName: deploymentNameSchema.optional(),
+  contentRoot: contentRootSchema.default('content'),
+  sourceRoot: sourceRootSchema.optional(),
+  editor: editorConfigSchema.optional(),
+  authPlugin: z.custom<AuthPlugin>().optional(),
+})
+
+/**
+ * Helper to get schema default values.
+ * This centralizes default value extraction from Zod schemas.
+ */
+/** Default workspace path for prod mode (used when CANOPYCMS_WORKSPACE_ROOT is not set) */
+export const DEFAULT_PROD_WORKSPACE = '/mnt/efs/workspace'
+
+export const getConfigDefaults = () => ({
+  baseBranch: defaultBaseBranchSchema.parse(undefined),
+  remoteName: defaultRemoteNameSchema.parse(undefined),
+  pathAccess: defaultPathAccessSchema.parse(undefined),
+  branchAccess: defaultBranchAccessSchema.parse(undefined),
+  contentRoot: contentRootSchema.parse(undefined),
+  mode: operatingModeSchema.parse(undefined),
+  githubTokenEnvVar: githubTokenEnvVarSchema.parse(undefined),
+  deploymentName: deploymentNameSchema.parse(undefined),
+  prodWorkspace: DEFAULT_PROD_WORKSPACE,
+})

package/src/config/schemas/field.ts

@@ -0,0 +1,108 @@
+/**
+ * Zod schemas for field configuration validation.
+ */
+
+import { z } from 'zod'
+
+import { primitiveFieldTypes, fieldTypes } from '../types'
+import type { FieldType } from '../types'
+
+// Base field schema - shared properties
+export const fieldBaseSchema = z.object({
+  name: z.string().min(1),
+  label: z.string().optional(),
+  description: z.string().optional(),
+  required: z.boolean().optional(),
+  list: z.boolean().optional(),
+})
+
+// Select option schema
+export const selectOptionSchema = z.union([
+  z.string(),
+  z.object({
+    label: z.string().min(1),
+    value: z.string().min(1),
+  }),
+])
+
+// Reference option schema
+export const referenceOptionSchema = z.union([
+  z.string(),
+  z.object({
+    label: z.string().min(1),
+    value: z.string().min(1),
+  }),
+])
+
+// Primitive field (string, number, boolean, etc.)
+export const primitiveFieldSchema = fieldBaseSchema.extend({
+  type: z.enum(primitiveFieldTypes),
+})
+
+// Select field with options
+export const selectFieldSchema = fieldBaseSchema.extend({
+  type: z.literal('select'),
+  options: z.array(selectOptionSchema).min(1),
+})
+
+// Reference field pointing to other collections
+export const referenceFieldSchema = fieldBaseSchema.extend({
+  type: z.literal('reference'),
+  collections: z.array(z.string().min(1)).min(1),
+  displayField: z.string().min(1).optional(),
+  options: z.array(referenceOptionSchema).optional(),
+})
+
+// Use a mutable holder to enable forward references in recursive z.lazy() closures.
+// blockSchema/objectFieldSchema reference fieldHolder[0] via z.lazy, which is resolved
+// after the full fieldSchema is constructed below.
+const fieldHolder: [z.ZodTypeAny] = [z.never()]
+
+// Block template schema
+export const blockSchema = z.object({
+  name: z.string().min(1),
+  label: z.string().optional(),
+  description: z.string().optional(),
+  fields: z.array(z.lazy(() => fieldHolder[0])).min(1),
+})
+
+// Block field with templates
+export const blockFieldSchema = fieldBaseSchema.extend({
+  type: z.literal('block'),
+  templates: z.array(blockSchema).min(1),
+})
+
+// Object field with nested fields
+export const objectFieldSchema = fieldBaseSchema.extend({
+  type: z.literal('object'),
+  fields: z.array(z.lazy(() => fieldHolder[0])).min(1),
+})
+
+// Custom field (user-defined type)
+export const customFieldSchema = z.lazy(() =>
+  fieldBaseSchema
+    .extend({
+      type: z
+        .string()
+        .min(1)
+        .refine((val) => !fieldTypes.includes(val as FieldType), {
+          message: 'Custom field types must not conflict with built-in types',
+        }),
+    })
+    .passthrough(),
+)
+
+// Known built-in field types (discriminated union)
+const knownFieldSchema: z.ZodTypeAny = z.discriminatedUnion('type', [
+  primitiveFieldSchema,
+  selectFieldSchema,
+  referenceFieldSchema,
+  objectFieldSchema,
+  blockFieldSchema,
+])
+
+// Complete field schema (built-in or custom)
+const fieldSchema: z.ZodTypeAny = z.lazy(() => z.union([knownFieldSchema, customFieldSchema]))
+fieldHolder[0] = fieldSchema
+
+export { fieldSchema, knownFieldSchema }

package/src/config/schemas/media.ts

@@ -0,0 +1,27 @@
+/**
+ * Zod schemas for media adapter configuration validation.
+ */
+
+import { z } from 'zod'
+
+// Media adapter configuration schema
+export const mediaSchema = z.union([
+  z.object({
+    adapter: z.literal('local'),
+    publicBaseUrl: z.string().url().optional(),
+  }),
+  z.object({
+    adapter: z.literal('s3'),
+    bucket: z.string().min(1),
+    region: z.string().min(1),
+    publicBaseUrl: z.string().url().optional(),
+  }),
+  z.object({
+    adapter: z.literal('lfs'),
+    publicBaseUrl: z.string().url().optional(),
+  }),
+  z.object({
+    adapter: z.string().min(1),
+    publicBaseUrl: z.string().url().optional(),
+  }),
+])

package/src/config/schemas/permissions.ts

@@ -0,0 +1,21 @@
+/**
+ * Zod schemas for permission configuration validation.
+ */
+
+import { z } from 'zod'
+
+import type { CanopyGroupId, CanopyUserId } from '../../types'
+
+// Permission target schema
+export const permissionTargetSchema = z.object({
+  allowedUsers: z.array(z.string() as z.ZodType<CanopyUserId>).optional(),
+  allowedGroups: z.array(z.string() as z.ZodType<CanopyGroupId>).optional(),
+})
+
+// Path permission schema
+export const pathPermissionSchema = z.object({
+  path: z.string().min(1),
+  read: permissionTargetSchema.optional(),
+  edit: permissionTargetSchema.optional(),
+  review: permissionTargetSchema.optional(),
+})