canopycms 0.0.0

package/src/ai/json-to-markdown.ts

@@ -0,0 +1,424 @@
+/**
+ * Schema-driven entry-to-markdown converter for AI content generation.
+ *
+ * Converts a single entry's data + schema fields to clean markdown.
+ * Handles all CanopyCMS field types including nested objects and blocks.
+ */
+
+import type { FieldConfig, ObjectFieldConfig, BlockFieldConfig, SelectFieldConfig } from '../config'
+import type { AIEntry, AIContentConfig } from './types'
+
+/**
+ * Convert an entry to clean markdown suitable for AI consumption.
+ *
+ * For MD/MDX entries: renders frontmatter fields as metadata, appends body verbatim.
+ * For JSON entries: full schema-driven conversion of all fields.
+ */
+export function entryToMarkdown(entry: AIEntry, config?: AIContentConfig): string {
+  const parts: string[] = []
+
+  // Entry header with YAML-style frontmatter
+  parts.push('---')
+  if (entry.data.title) {
+    parts.push(`title: ${yamlValue(String(entry.data.title))}`)
+  }
+  parts.push(`slug: ${yamlValue(entry.slug)}`)
+  parts.push(`collection: ${yamlValue(entry.collection)}`)
+  parts.push(`type: ${yamlValue(entry.entryType)}`)
+  parts.push('---')
+  parts.push('')
+
+  // Fields already in frontmatter — skip from body rendering to avoid duplication
+  const skipFields = new Set<string>()
+  if (entry.data.title) skipFields.add('title')
+
+  if (entry.format === 'md' || entry.format === 'mdx') {
+    // For MD/MDX: render non-body fields as metadata, then body verbatim
+    parts.push(...renderMarkdownEntry(entry, config, skipFields))
+  } else {
+    // For JSON: full schema-driven conversion
+    parts.push(...renderJsonEntry(entry, config, skipFields))
+  }
+
+  return parts.join('\n')
+}
+
+/**
+ * Render a MD/MDX entry: metadata fields as a section, body verbatim.
+ */
+function renderMarkdownEntry(
+  entry: AIEntry,
+  config: AIContentConfig | undefined,
+  skipFields: Set<string>,
+): string[] {
+  const parts: string[] = []
+
+  // Render frontmatter fields (excluding body-like fields and already-rendered fields)
+  const bodyFieldTypes = new Set(['rich-text', 'markdown', 'mdx'])
+  const metadataFields = entry.fields.filter(
+    (f) => !bodyFieldTypes.has(f.type) && !skipFields.has(f.name),
+  )
+
+  for (const field of metadataFields) {
+    const value = entry.data[field.name]
+    if (value === undefined || value === null) continue
+
+    // Check for field transform
+    const transformed = applyFieldTransform(entry, field, value, config)
+    if (transformed !== undefined) {
+      parts.push(transformed)
+      parts.push('')
+      continue
+    }
+
+    // Simple inline rendering for metadata
+    const label = field.label || field.name
+    parts.push(`**${label}:** ${formatInlineValue(field, value)}`)
+  }
+
+  if (parts.length > 0) {
+    parts.push('')
+  }
+
+  // Append body verbatim
+  if (entry.body) {
+    parts.push(entry.body.trim())
+    parts.push('')
+  }
+
+  return parts
+}
+
+/**
+ * Render a JSON entry: full schema-driven conversion of all fields.
+ */
+function renderJsonEntry(
+  entry: AIEntry,
+  config: AIContentConfig | undefined,
+  skipFields: Set<string>,
+): string[] {
+  const parts: string[] = []
+
+  for (const field of entry.fields) {
+    if (skipFields.has(field.name)) continue
+    const value = entry.data[field.name]
+    if (value === undefined || value === null) continue
+
+    const rendered = renderField(field, value, 2, entry, config)
+    if (rendered) {
+      parts.push(rendered)
+      parts.push('')
+    }
+  }
+
+  return parts
+}
+
+/**
+ * Render a single field to markdown.
+ *
+ * @param field - Field configuration from schema
+ * @param value - The field's value
+ * @param depth - Heading depth (2 = ##, 3 = ###, etc.)
+ * @param entry - The parent entry (for transform lookups)
+ * @param config - AI content config (for field transforms)
+ */
+function renderField(
+  field: FieldConfig,
+  value: unknown,
+  depth: number,
+  entry: AIEntry,
+  config?: AIContentConfig,
+): string {
+  // Check for field transform override
+  const transformed = applyFieldTransform(entry, field, value, config)
+  if (transformed !== undefined) {
+    return transformed
+  }
+
+  const label = field.label || field.name
+  const heading = '#'.repeat(Math.min(depth, 6))
+  const descriptionLine =
+    'description' in field && field.description ? `\n\n*${field.description}*` : ''
+
+  // Handle list fields
+  if (field.list && Array.isArray(value)) {
+    return renderListField(field, value, depth, label, heading, descriptionLine, entry, config)
+  }
+
+  switch (field.type) {
+    case 'string':
+    case 'number':
+    case 'datetime':
+      return `${heading} ${label}${descriptionLine}\n\n${String(value)}`
+
+    case 'boolean':
+      return `${heading} ${label}${descriptionLine}\n\n${value ? 'Yes' : 'No'}`
+
+    case 'rich-text':
+    case 'markdown':
+    case 'mdx':
+      return `${heading} ${label}${descriptionLine}\n\n${String(value)}`
+
+    case 'image':
+      return `${heading} ${label}${descriptionLine}\n\n![${label}](${String(value)})`
+
+    case 'code':
+      return `${heading} ${label}${descriptionLine}\n\n\`\`\`\n${String(value)}\n\`\`\``
+
+    case 'select':
+      return renderSelectField(field as SelectFieldConfig, value, heading, label, descriptionLine)
+
+    case 'reference':
+      return renderReferenceField(value, heading, label, descriptionLine)
+
+    case 'object':
+      return renderObjectField(
+        field as ObjectFieldConfig,
+        value,
+        depth,
+        heading,
+        label,
+        descriptionLine,
+        entry,
+        config,
+      )
+
+    case 'block':
+      return renderBlockField(
+        field as BlockFieldConfig,
+        value,
+        depth,
+        heading,
+        label,
+        descriptionLine,
+        entry,
+        config,
+      )
+
+    default:
+      // Custom or unknown field type — render as string
+      return `${heading} ${label}${descriptionLine}\n\n${String(value)}`
+  }
+}
+
+/**
+ * Render a list field (field with list: true).
+ */
+function renderListField(
+  field: FieldConfig,
+  values: unknown[],
+  depth: number,
+  label: string,
+  heading: string,
+  descriptionLine: string,
+  entry: AIEntry,
+  config?: AIContentConfig,
+): string {
+  if (values.length === 0) return ''
+
+  const isComplex = field.type === 'object' || field.type === 'block'
+
+  if (isComplex) {
+    // For complex types, render each item as a subsection
+    const items = values
+      .map((item, i) => {
+        const itemLabel = `${label} ${i + 1}`
+        const itemHeading = '#'.repeat(Math.min(depth + 1, 6))
+        if (field.type === 'object' && typeof item === 'object' && item !== null) {
+          const objectField = field as ObjectFieldConfig
+          const subFields = objectField.fields
+            .map((f) => {
+              const v = (item as Record<string, unknown>)[f.name]
+              if (v === undefined || v === null) return ''
+              return renderField(f, v, depth + 2, entry, config)
+            })
+            .filter(Boolean)
+          return `${itemHeading} ${itemLabel}\n\n${subFields.join('\n\n')}`
+        }
+        return `${itemHeading} ${itemLabel}\n\n${String(item)}`
+      })
+      .filter(Boolean)
+    return `${heading} ${label}${descriptionLine}\n\n${items.join('\n\n')}`
+  }
+
+  // For primitive types, render as markdown list
+  const items = values.map((v) => `- ${formatInlineValue(field, v)}`).join('\n')
+  return `${heading} ${label}${descriptionLine}\n\n${items}`
+}
+
+/**
+ * Render a select field.
+ */
+function renderSelectField(
+  field: SelectFieldConfig,
+  value: unknown,
+  heading: string,
+  label: string,
+  descriptionLine: string,
+): string {
+  if (Array.isArray(value)) {
+    return `${heading} ${label}${descriptionLine}\n\n${value.map((v) => resolveSelectLabel(field, v)).join(', ')}`
+  }
+  return `${heading} ${label}${descriptionLine}\n\n${resolveSelectLabel(field, value)}`
+}
+
+/**
+ * Resolve a select value to its display label.
+ */
+function resolveSelectLabel(field: SelectFieldConfig, value: unknown): string {
+  const strValue = String(value)
+  for (const opt of field.options) {
+    if (typeof opt === 'string') {
+      if (opt === strValue) return opt
+    } else {
+      if (opt.value === strValue) return opt.label
+    }
+  }
+  return strValue
+}
+
+/**
+ * Render a reference field.
+ */
+function renderReferenceField(
+  value: unknown,
+  heading: string,
+  label: string,
+  descriptionLine: string,
+): string {
+  if (Array.isArray(value)) {
+    const items = value.map((v) => `- ${formatReference(v)}`).join('\n')
+    return `${heading} ${label}${descriptionLine}\n\n${items}`
+  }
+  return `${heading} ${label}${descriptionLine}\n\n${formatReference(value)}`
+}
+
+/**
+ * Format a single reference value.
+ * References may be resolved (objects with data) or unresolved (string IDs).
+ */
+function formatReference(value: unknown): string {
+  if (typeof value === 'object' && value !== null) {
+    const ref = value as Record<string, unknown>
+    // Resolved reference — use title, name, or slug
+    const display = ref.title || ref.name || ref.slug || ref.id
+    if (display) return String(display)
+  }
+  // Unresolved — raw ID or string
+  return String(value)
+}
+
+/**
+ * Render an object field with nested fields.
+ */
+function renderObjectField(
+  field: ObjectFieldConfig,
+  value: unknown,
+  depth: number,
+  heading: string,
+  label: string,
+  descriptionLine: string,
+  entry: AIEntry,
+  config?: AIContentConfig,
+): string {
+  if (typeof value !== 'object' || value === null) {
+    return `${heading} ${label}${descriptionLine}\n\n${String(value)}`
+  }
+
+  const obj = value as Record<string, unknown>
+  const subFields = field.fields
+    .map((f) => {
+      const v = obj[f.name]
+      if (v === undefined || v === null) return ''
+      return renderField(f, v, depth + 1, entry, config)
+    })
+    .filter(Boolean)
+
+  if (subFields.length === 0) return ''
+  return `${heading} ${label}${descriptionLine}\n\n${subFields.join('\n\n')}`
+}
+
+/**
+ * Render a block field (array of typed block items).
+ */
+function renderBlockField(
+  field: BlockFieldConfig,
+  value: unknown,
+  depth: number,
+  heading: string,
+  label: string,
+  descriptionLine: string,
+  entry: AIEntry,
+  config?: AIContentConfig,
+): string {
+  if (!Array.isArray(value)) return ''
+
+  const items = value
+    .map((item) => {
+      if (typeof item !== 'object' || item === null) return ''
+      const blockItem = item as Record<string, unknown>
+
+      // Block items use _type (field traversal) or template (ContentStore)
+      const templateName = (blockItem._type || blockItem.template) as string | undefined
+      if (!templateName) return ''
+
+      const template = field.templates.find((t) => t.name === templateName)
+      if (!template) return ''
+
+      const blockHeading = '#'.repeat(Math.min(depth + 1, 6))
+      const blockLabel = template.label || template.name
+      const blockFields = template.fields
+        .map((f) => {
+          const v = blockItem[f.name] ?? (blockItem.value as Record<string, unknown>)?.[f.name]
+          if (v === undefined || v === null) return ''
+          return renderField(f, v, depth + 2, entry, config)
+        })
+        .filter(Boolean)
+
+      if (blockFields.length === 0) return ''
+      return `${blockHeading} ${blockLabel}\n\n${blockFields.join('\n\n')}`
+    })
+    .filter(Boolean)
+
+  if (items.length === 0) return ''
+  return `${heading} ${label}${descriptionLine}\n\n${items.join('\n\n')}`
+}
+
+/**
+ * Apply a field transform if one exists for this entry type + field name.
+ * Returns undefined if no transform applies.
+ */
+function applyFieldTransform(
+  entry: AIEntry,
+  field: FieldConfig,
+  value: unknown,
+  config?: AIContentConfig,
+): string | undefined {
+  if (!config?.fieldTransforms) return undefined
+  const typeTransforms = config.fieldTransforms[entry.entryType]
+  if (!typeTransforms) return undefined
+  const fn = typeTransforms[field.name]
+  if (!fn) return undefined
+  return fn(value, field)
+}
+
+/**
+ * Format a value for inline display (metadata lines, list items).
+ */
+function formatInlineValue(field: FieldConfig, value: unknown): string {
+  if (field.type === 'boolean') return value ? 'Yes' : 'No'
+  if (field.type === 'reference') return formatReference(value)
+  return String(value)
+}
+
+/**
+ * Escape a value for YAML frontmatter.
+ * Wraps in quotes if value contains special characters.
+ */
+function yamlValue(value: string): string {
+  if (/[:#{}[\],&*?|>!%@`]/.test(value) || value.includes('\n')) {
+    return `"${value.replace(/"/g, '\\"')}"`
+  }
+  return value
+}

package/src/ai/resolve-branch.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared branch root resolution for AI content generation.
+ * Used by both the route handler and build utility.
+ */
+
+import { loadBranchContext } from '../branch-metadata'
+import type { CanopyConfig } from '../config'
+
+/**
+ * Resolve the branch root directory for reading content.
+ *
+ * - Dev mode: current working directory (content is in the checkout)
+ * - Prod/prod-sim: load the default base branch context
+ */
+export async function resolveBranchRoot(config: CanopyConfig): Promise<string> {
+  if (config.mode === 'dev') {
+    return process.cwd()
+  }
+
+  const baseBranch = config.defaultBaseBranch ?? 'main'
+  const context = await loadBranchContext({
+    branchName: baseBranch,
+    mode: config.mode,
+  })
+
+  if (!context) {
+    throw new Error(
+      `Could not load branch context for "${baseBranch}". ` +
+        'Ensure the branch exists and has been initialized.',
+    )
+  }
+
+  return context.branchRoot
+}

package/src/ai/types.ts

@@ -0,0 +1,160 @@
+/**
+ * Type definitions for AI-ready content generation.
+ *
+ * These types define the configuration for generating AI-consumable markdown
+ * from CanopyCMS content, and the output manifest/metadata structures.
+ */
+
+import type { FieldConfig } from '../config'
+
+// ---------------------------------------------------------------------------
+// Configuration types
+// ---------------------------------------------------------------------------
+
+/**
+ * Metadata about an entry, provided to filter/predicate functions.
+ * Does not include the full data payload — use `where` predicates for
+ * data-level filtering.
+ */
+export interface AIEntryMeta {
+  slug: string
+  /** Clean collection path without content root (e.g., 'posts', 'datasets/openstax') */
+  collection: string
+  collectionName: string
+  entryType: string
+  format: string
+  /** The entry's parsed data (frontmatter for MD/MDX, full data for JSON) */
+  data: Record<string, unknown>
+}
+
+/**
+ * Exclusion config — opt-out model. Everything is included unless excluded.
+ */
+export interface ExcludeConfig {
+  /** Collection paths to skip (e.g., 'content/drafts'). Matches with or without content root prefix. */
+  collections?: string[]
+  /** Entry type names to skip everywhere (e.g., 'internal-note') */
+  entryTypes?: string[]
+  /** Custom predicate — return true to exclude the entry */
+  where?: (entry: AIEntryMeta) => boolean
+}
+
+/**
+ * Filter criteria for bundles. Filters are AND'd when combined.
+ */
+export interface BundleFilter {
+  /** Include entries under these collection paths */
+  collections?: string[]
+  /** Include entries of these type names */
+  entryTypes?: string[]
+  /** Include entries matching glob patterns on clean path */
+  paths?: string[]
+  /** Custom predicate — return true to include the entry */
+  where?: (entry: AIEntryMeta) => boolean
+}
+
+/**
+ * A named bundle — an additive filtered view producing a concatenated markdown file.
+ */
+export interface BundleConfig {
+  /** Unique name, used in URLs/filenames (e.g., 'openstax-researcher') */
+  name: string
+  /** Human description, included in the bundle header and manifest */
+  description?: string
+  /** Filter criteria (AND'd when multiple are specified) */
+  filter: BundleFilter
+}
+
+/**
+ * Per-field markdown override function.
+ * Return a markdown string to replace the default conversion for this field.
+ */
+export type FieldTransformFn = (value: unknown, fieldConfig: FieldConfig) => string
+
+/**
+ * Field transform overrides, keyed by entry type name, then field name.
+ *
+ * @example
+ * ```ts
+ * {
+ *   dataset: {
+ *     dataFields: (value, fieldConfig) =>
+ *       `## Data Fields\n| Name | Type |\n|---|---|\n${value.map(f => `| ${f.name} | ${f.type} |`).join('\n')}`,
+ *   },
+ * }
+ * ```
+ */
+export type FieldTransforms = Record<string, Record<string, FieldTransformFn>>
+
+/**
+ * Main AI content configuration. Shared by route handler and build utility.
+ */
+export interface AIContentConfig {
+  /** Opt-out exclusions — content to skip */
+  exclude?: ExcludeConfig
+  /** Custom bundles — filtered content subsets */
+  bundles?: BundleConfig[]
+  /** Per-entry-type, per-field markdown overrides */
+  fieldTransforms?: FieldTransforms
+}
+
+/**
+ * Identity function for type-checking AI content config.
+ * Similar to `defineCanopyConfig` — validates the shape at the type level.
+ */
+export function defineAIContentConfig(config: AIContentConfig): AIContentConfig {
+  return config
+}
+
+// ---------------------------------------------------------------------------
+// Output / manifest types
+// ---------------------------------------------------------------------------
+
+/** Manifest entry metadata */
+export interface AIManifestEntry {
+  slug: string
+  title?: string
+  file: string
+}
+
+/** Manifest collection metadata (recursive for subcollections) */
+export interface AIManifestCollection {
+  name: string
+  label?: string
+  description?: string
+  path: string
+  /** Path to the concatenated all.md file. Absent when the collection has no entries. */
+  allFile?: string
+  entryCount: number
+  entries: AIManifestEntry[]
+  subcollections?: AIManifestCollection[]
+}
+
+/** Manifest bundle metadata */
+export interface AIManifestBundle {
+  name: string
+  description?: string
+  file: string
+  entryCount: number
+}
+
+/** Top-level manifest for AI content */
+export interface AIManifest {
+  generated: string
+  /** Root-level entries (outside any collection) */
+  entries: AIManifestEntry[]
+  collections: AIManifestCollection[]
+  bundles: AIManifestBundle[]
+}
+
+// ---------------------------------------------------------------------------
+// Internal generation types
+// ---------------------------------------------------------------------------
+
+/** A fully-loaded entry ready for markdown conversion */
+export interface AIEntry extends AIEntryMeta {
+  /** Markdown body for MD/MDX entries */
+  body?: string
+  /** Schema fields for this entry type */
+  fields: readonly FieldConfig[]
+}

package/src/api/AGENTS.md

@@ -0,0 +1,81 @@
+# API Development Guidelines for Agents
+
+## Generated Files
+
+- **Do not edit `client.ts` or `__test__/mock-client.ts` directly** - these files are auto-generated
+- To modify the client, edit `packages/canopycms/scripts/generate-client.ts` and run `npm run generate:client`
+
+## Declarative Guards
+
+Use the `guards` array in `defineEndpoint()` for access control and context loading. Guards run before the handler and provide typed context via the `gc` first argument.
+
+```typescript
+// Branch access + schema loading
+const getSchema = defineEndpoint({
+  guards: ['branchAccessWithSchema'] as const,
+  handler: async (gc, ctx, req, params) => {
+    const { branchContext } = gc // BranchContextWithSchema — flatSchema guaranteed
+  },
+})
+
+// Role guard + branch loading
+const createCollection = defineEndpoint({
+  guards: ['admin', 'branch'] as const,
+  handler: async (gc, ctx, req, params, body) => {
+    const { branchContext } = gc // BranchContext — admin access already verified
+  },
+})
+```
+
+Available guards: `branch`, `branchAccess`, `schema`, `branchAccessWithSchema`, `admin`, `reviewer`, `privileged`. See `guards.ts` for details.
+
+## Adding New API Endpoints
+
+When adding a new API endpoint with a request body, follow these steps to ensure full type safety:
+
+1. **Export the body type** in the endpoint's module (e.g., `permissions.ts`, `comments.ts`)
+
+   ```typescript
+   export interface UpdatePermissionsBody {
+     permissions: PathPermission[]
+   }
+   ```
+
+2. **Add the `bodyType` field** to the `defineEndpoint()` call
+
+   ```typescript
+   const updatePermissions = defineEndpoint({
+     namespace: 'permissions',
+     name: 'update',
+     method: 'PUT',
+     path: '/permissions',
+     body: updatePermissionsBodySchema, // Zod schema for runtime validation
+     bodyType: 'UpdatePermissionsBody', // TypeScript type for codegen
+     responseType: 'PermissionsResponse',
+     response: {} as PermissionsResponse,
+     handler: updatePermissionsHandler,
+   })
+   ```
+
+3. **Regenerate the client** with `npm run generate:client`
+   - The generated client will have typed methods like `update(body: UpdatePermissionsBody)` instead of `update(body: unknown)`
+
+## Why Both `body` and `bodyType`?
+
+- **`body`** (Zod schema) - Runtime validation of incoming requests
+- **`bodyType`** (string) - Type name used by the code generator to create typed client methods
+- This dual approach provides both compile-time type safety and runtime validation
+
+## Finding Endpoints Missing Body Types
+
+Search for endpoints with bodies but no `bodyType`:
+
+```bash
+# Find all endpoints with body schemas
+grep -r "body: \w\+Schema" packages/canopycms/src/api/*.ts
+
+# Check which have bodyType specified
+grep -r "bodyType:" packages/canopycms/src/api/*.ts
+```
+
+Any endpoint with a `body` field but no `bodyType` field will generate a client method with `body: unknown`.