canopycms 0.0.0 → 0.0.2

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

@@ -1,424 +0,0 @@
-/**
- * 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

@@ -1,34 +0,0 @@
-/**
- * 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

@@ -1,160 +0,0 @@
-/**
- * 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

@@ -1,81 +0,0 @@
-# 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`.