canopycms 0.0.0 → 0.0.2

package/src/paths/validation.ts

@@ -1,391 +0,0 @@
-/**
- * Path validation utilities.
- *
- * Security-focused validation for content paths and slugs.
- */
-
-import { normalizeFilesystemPath, hasTraversalSequence } from './normalize'
-import type {
-  LogicalPath,
-  PhysicalPath,
-  ContentId,
-  BranchName,
-  EntrySlug,
-  CollectionSlug,
-} from './types'
-
-/**
- * Base58 alphabet used for content IDs (excludes ambiguous: 0, O, I, l)
- */
-const BASE58_PATTERN = '[123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]'
-
-/**
- * Pattern matching exactly a 12-character content ID
- */
-const CONTENT_ID_PATTERN = new RegExp(`^${BASE58_PATTERN}{12}$`)
-
-/**
- * Pattern matching a physical path segment with embedded ID.
- * Matches patterns like:
- * - `post.my-slug.abc123def456.json` (entry)
- * - `posts.abc123def456` (collection directory)
- */
-const PHYSICAL_SEGMENT_PATTERN = new RegExp(`\\.${BASE58_PATTERN}{12}(?:\\.[a-z]+)?$`)
-
-/**
- * Validate a content path for security.
- *
- * @param path - The path to validate
- * @param rootPath - The root directory (for traversal check)
- * @returns Validation result
- */
-export function validateContentPath(
-  path: string,
-  rootPath: string,
-): { valid: boolean; error?: string } {
-  const normalized = normalizeFilesystemPath(path)
-
-  // Check for traversal sequences
-  if (hasTraversalSequence(normalized)) {
-    return { valid: false, error: 'Path contains traversal sequence' }
-  }
-
-  // Check path doesn't escape root
-  const normalizedRoot = normalizeFilesystemPath(rootPath)
-  if (!normalized.startsWith(normalizedRoot) && normalized !== normalizedRoot) {
-    // Allow paths that are relative within the root
-    const normalizedPath = `${normalizedRoot}/${normalized}`
-    if (hasTraversalSequence(normalizedPath)) {
-      return { valid: false, error: 'Path escapes root directory' }
-    }
-  }
-
-  return { valid: true }
-}
-
-/**
- * Validate a collection path.
- *
- * @param collectionPath - The collection path to validate
- * @returns true if valid, false otherwise
- */
-export function isValidCollectionPath(collectionPath: string): boolean {
-  if (!collectionPath || collectionPath.length === 0) {
-    return false
-  }
-
-  // Normalize and check for traversal
-  const normalized = normalizeFilesystemPath(collectionPath)
-  if (hasTraversalSequence(normalized)) {
-    return false
-  }
-
-  // Collection paths should only contain alphanumeric, hyphens, underscores, and forward slashes
-  const validPattern = /^[a-zA-Z0-9_/-]+$/
-  return validPattern.test(normalized)
-}
-
-/**
- * Sanitize a string for use in paths by removing dangerous characters.
- *
- * @param input - The string to sanitize
- * @returns Sanitized string safe for path use
- */
-export function sanitizeForPath(input: string): string {
-  return input
-    .replace(/[<>:"|?*\\]/g, '') // Remove invalid filesystem chars
-    .replace(/\.{2,}/g, '.') // Collapse multiple dots
-    .replace(/^\./, '') // Remove leading dot
-    .trim()
-}
-
-/**
- * Check if a path segment contains an embedded content ID.
- *
- * Physical paths have segments with embedded 12-char IDs:
- * - `post.my-slug.abc123def456.json` (entry file)
- * - `posts.abc123def456` (collection directory)
- *
- * @param segment - A single path segment (no slashes)
- * @returns true if segment contains embedded ID pattern
- */
-export function hasEmbeddedContentId(segment: string): boolean {
-  return PHYSICAL_SEGMENT_PATTERN.test(segment)
-}
-
-/**
- * Check if a path appears to be a physical path (contains embedded content IDs).
- *
- * Physical paths have the format:
- * - `content/posts.abc123/post.hello.def456.json`
- *
- * Logical paths do not have embedded IDs:
- * - `content/posts/hello` or `posts/hello`
- *
- * @param path - The path to check
- * @returns true if any segment contains an embedded content ID
- */
-export function looksLikePhysicalPath(path: string): boolean {
-  const segments = path.split('/')
-  return segments.some(hasEmbeddedContentId)
-}
-
-/**
- * Check if a path appears to be a logical path (no embedded content IDs).
- *
- * @param path - The path to check
- * @returns true if no segments contain embedded content IDs
- */
-export function looksLikeLogicalPath(path: string): boolean {
-  return !looksLikePhysicalPath(path)
-}
-
-/**
- * Validate and cast a string to LogicalPath.
- *
- * Use this at API boundaries to validate incoming path strings
- * and cast them to the branded LogicalPath type.
- *
- * @param path - The path string to validate
- * @returns Object with success flag and either the typed path or an error
- *
- * @example
- * ```ts
- * const result = parseLogicalPath(params.collectionPath)
- * if (!result.ok) {
- *   return { ok: false, status: 400, error: result.error }
- * }
- * const collectionPath: LogicalPath = result.path
- * ```
- */
-export function parseLogicalPath(
-  path: string,
-): { ok: true; path: LogicalPath } | { ok: false; error: string } {
-  // Basic validation
-  if (!path || typeof path !== 'string') {
-    return { ok: false, error: 'Path is required' }
-  }
-
-  // Normalize backslashes to forward slashes (consistent with parsePermissionPath)
-  const normalized = path.replace(/\\/g, '/')
-
-  // Security check
-  if (hasTraversalSequence(normalized)) {
-    return { ok: false, error: 'Path contains traversal sequence' }
-  }
-
-  // Check it's not a physical path
-  if (looksLikePhysicalPath(normalized)) {
-    return {
-      ok: false,
-      error:
-        'Path appears to be a physical path (contains embedded content ID). Expected a logical path.',
-    }
-  }
-
-  return { ok: true, path: normalized as LogicalPath }
-}
-
-/**
- * Validate and cast a string to PhysicalPath.
- *
- * Use this at API boundaries to validate incoming path strings
- * and cast them to the branded PhysicalPath type.
- *
- * @param path - The path string to validate
- * @returns Object with success flag and either the typed path or an error
- */
-export function parsePhysicalPath(
-  path: string,
-): { ok: true; path: PhysicalPath } | { ok: false; error: string } {
-  // Basic validation
-  if (!path || typeof path !== 'string') {
-    return { ok: false, error: 'Path is required' }
-  }
-
-  // Normalize backslashes to forward slashes (consistent with parseLogicalPath)
-  const normalized = path.replace(/\\/g, '/')
-
-  // Security check
-  if (hasTraversalSequence(normalized)) {
-    return { ok: false, error: 'Path contains traversal sequence' }
-  }
-
-  // Check it looks like a physical path
-  if (!looksLikePhysicalPath(normalized)) {
-    return {
-      ok: false,
-      error:
-        'Path appears to be a logical path (no embedded content ID). Expected a physical path.',
-    }
-  }
-
-  return { ok: true, path: normalized as PhysicalPath }
-}
-
-/**
- * Check if a string is a valid 12-character content ID.
- *
- * @param id - The string to check
- * @returns true if valid Base58 12-char ID
- */
-export function isValidContentId(id: string): boolean {
-  return CONTENT_ID_PATTERN.test(id)
-}
-
-/**
- * Parse and validate a ContentId from a string.
- * Validates Base58 format and 12-character length.
- *
- * @param id - The string to validate
- * @returns Object with success flag and either the typed ID or an error
- *
- * @example
- * ```ts
- * const result = parseContentId(fileId)
- * if (!result.ok) {
- *   throw new Error(result.error)
- * }
- * const contentId: ContentId = result.id
- * ```
- */
-export function parseContentId(
-  id: string,
-): { ok: true; id: ContentId } | { ok: false; error: string } {
-  if (!id || typeof id !== 'string') {
-    return { ok: false, error: 'Content ID is required' }
-  }
-
-  if (!isValidContentId(id)) {
-    return {
-      ok: false,
-      error: `Invalid content ID format (expected 12 Base58 characters, got: ${id})`,
-    }
-  }
-
-  return { ok: true, id: id as ContentId }
-}
-
-/**
- * Parse and validate a BranchName.
- * Checks git branch naming rules.
- *
- * @param name - The branch name to validate
- * @returns Object with success flag and either the typed name or an error
- *
- * @example
- * ```ts
- * const result = parseBranchName(params.branch)
- * if (!result.ok) {
- *   return { ok: false, status: 400, error: result.error }
- * }
- * const branchName: BranchName = result.name
- * ```
- */
-export function parseBranchName(
-  name: string,
-): { ok: true; name: BranchName } | { ok: false; error: string } {
-  if (!name || typeof name !== 'string') {
-    return { ok: false, error: 'Branch name is required' }
-  }
-
-  // Length limit (branch names become directory names)
-  if (name.length > 250) {
-    return { ok: false, error: 'Branch name too long (max 250 characters)' }
-  }
-
-  // Git branch name rules
-  if (name.includes('..')) {
-    return { ok: false, error: 'Branch name cannot contain ".."' }
-  }
-
-  if (name.startsWith('/') || name.endsWith('/') || name.includes('//')) {
-    return { ok: false, error: 'Invalid branch name format (invalid slashes)' }
-  }
-
-  if (name.includes(' ')) {
-    return { ok: false, error: 'Branch name cannot contain spaces' }
-  }
-
-  // Additional git restrictions
-  if (name.startsWith('.') || name.endsWith('.')) {
-    return { ok: false, error: 'Branch name cannot start or end with a dot' }
-  }
-
-  if (name.includes('@{')) {
-    return { ok: false, error: 'Branch name cannot contain "@{"' }
-  }
-
-  // Git-forbidden characters: ~ ^ : ? * [ \ and control chars
-  // eslint-disable-next-line no-control-regex -- intentional: git forbids control characters in branch names
-  if (/[~^:?*[\\\x00-\x1f\x7f]/.test(name)) {
-    return { ok: false, error: 'Branch name contains invalid characters' }
-  }
-
-  if (name.endsWith('.lock')) {
-    return { ok: false, error: 'Branch name cannot end with ".lock"' }
-  }
-
-  return { ok: true, name: name as BranchName }
-}
-
-/**
- * Parse and validate a slug (collection or entry).
- * Validates format and length constraints.
- *
- * @param slug - The slug to validate
- * @param type - Whether this is a collection or entry slug
- * @returns Object with success flag and either the typed slug or an error
- *
- * @example
- * ```ts
- * const result = parseSlug(params.slug, 'entry')
- * if (!result.ok) {
- *   return { ok: false, status: 400, error: result.error }
- * }
- * const entrySlug: EntrySlug = result.slug
- * ```
- */
-export function parseSlug(
-  slug: string,
-  type: 'collection' | 'entry',
-): { ok: true; slug: CollectionSlug | EntrySlug } | { ok: false; error: string } {
-  if (!slug || typeof slug !== 'string') {
-    return {
-      ok: false,
-      error: `${type === 'collection' ? 'Collection' : 'Entry'} slug is required`,
-    }
-  }
-
-  // Check length (filesystem path safety)
-  if (slug.length > 64) {
-    return { ok: false, error: 'Slug too long (max 64 characters)' }
-  }
-
-  // Check for path separators and traversal
-  if (slug.includes('/') || slug.includes('\\')) {
-    return {
-      ok: false,
-      error: 'Slug cannot contain path separators',
-    }
-  }
-
-  if (slug === '.' || slug === '..') {
-    return {
-      ok: false,
-      error: 'Slug cannot be a traversal sequence',
-    }
-  }
-
-  // Validation from ContentStore.renameEntry
-  if (!/^[a-z0-9][a-z0-9-]*$/.test(slug)) {
-    return {
-      ok: false,
-      error:
-        'Slug must start with a letter or number and contain only lowercase letters, numbers, and hyphens',
-    }
-  }
-
-  // Cast to appropriate branded type
-  return { ok: true, slug: slug as CollectionSlug | EntrySlug }
-}

package/src/reference-resolver.test.ts

@@ -1,107 +0,0 @@
-import fs from 'node:fs/promises'
-import os from 'node:os'
-import path from 'node:path'
-
-import { afterEach, beforeEach, describe, expect, it } from 'vitest'
-
-import type { CanopyConfig } from './config'
-import { flattenSchema } from './config'
-import { ContentIdIndex } from './content-id-index'
-import { ContentStore } from './content-store'
-import { ReferenceResolver } from './reference-resolver'
-import { unsafeAsLogicalPath } from './paths/test-utils'
-
-describe('ReferenceResolver', () => {
-  let tempDir: string
-  let store: ContentStore
-  let idIndex: ContentIdIndex
-  let resolver: ReferenceResolver
-
-  beforeEach(async () => {
-    // Create temp directory with content structure
-    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'canopy-test-'))
-    await fs.mkdir(path.join(tempDir, 'content', 'authors'), {
-      recursive: true,
-    })
-
-    // Create test author files with embedded IDs: {type}.{slug}.{id}.{ext}
-    const aliceId = 'aXice123ABC4' // 12 chars, valid Base58
-    const bobId = 'bob456XYZ789' // 12 chars, valid Base58
-
-    await fs.writeFile(
-      path.join(tempDir, 'content', 'authors', `author.alice.${aliceId}.json`),
-      JSON.stringify({ slug: 'alice', name: 'Alice' }),
-    )
-    await fs.writeFile(
-      path.join(tempDir, 'content', 'authors', `author.bob.${bobId}.json`),
-      JSON.stringify({ slug: 'bob', name: 'Bob' }),
-    )
-
-    // Initialize store and index
-    const schema = {
-      collections: [
-        {
-          name: 'authors',
-          path: 'authors',
-          entries: [
-            {
-              name: 'author',
-              format: 'json' as const,
-              schema: [{ name: 'name', type: 'string' as const, label: 'Name' }],
-            },
-          ],
-        },
-      ],
-    } as const
-
-    const config: CanopyConfig = {
-      contentRoot: 'content',
-      gitBotAuthorName: 'Test Bot',
-      gitBotAuthorEmail: 'test@example.com',
-      mode: 'prod',
-    }
-
-    store = new ContentStore(tempDir, flattenSchema(schema, config.contentRoot))
-    idIndex = await store.idIndex()
-    resolver = new ReferenceResolver(store, idIndex)
-  })
-
-  afterEach(async () => {
-    // Clean up temp directory
-    await fs.rm(tempDir, { recursive: true, force: true })
-  })
-
-  describe('loadReferenceOptions', () => {
-    it('loads options when collection path does not include content/ prefix', async () => {
-      // REGRESSION TEST: ID index stores "content/authors" but schema specifies "authors"
-      // This ensures the collection path normalization works correctly
-      const options = await resolver.loadReferenceOptions([unsafeAsLogicalPath('authors')], 'name')
-
-      expect(options).toHaveLength(2)
-      const labels = options.map((o) => o.label).sort()
-      expect(labels).toEqual(['Alice', 'Bob'])
-      expect(options.every((o) => o.id && o.collection)).toBe(true)
-    })
-
-    it('loads options when collection path includes content/ prefix', async () => {
-      // REGRESSION TEST: Should also work if "content/authors" is explicitly specified
-      const options = await resolver.loadReferenceOptions(
-        [unsafeAsLogicalPath('content/authors')],
-        'name',
-      )
-
-      expect(options).toHaveLength(2)
-      const labels = options.map((o) => o.label).sort()
-      expect(labels).toEqual(['Alice', 'Bob'])
-    })
-
-    it('returns empty array for non-existent collection', async () => {
-      const options = await resolver.loadReferenceOptions(
-        [unsafeAsLogicalPath('nonexistent')],
-        'name',
-      )
-
-      expect(options).toHaveLength(0)
-    })
-  })
-})

package/src/reference-resolver.ts

@@ -1,157 +0,0 @@
-import path from 'node:path'
-
-import type { ContentStore } from './content-store'
-import type { ContentIdIndex } from './content-id-index'
-import { extractSlugFromFilename } from './content-id-index'
-import type { LogicalPath, PhysicalPath, EntrySlug } from './paths'
-
-export interface ResolvedReference {
-  id: string
-  exists: boolean
-  displayValue: string
-  collection?: LogicalPath
-  slug?: EntrySlug
-}
-
-export interface ReferenceOption {
-  id: string
-  label: string
-  collection: string
-}
-
-/**
- * ReferenceResolver resolves content IDs to display values for reference fields.
- *
- * This class provides utilities for:
- * - Resolving a single ID to its display value (e.g., title)
- * - Loading all available options for a reference field
- * - Filtering options by collection constraints
- * - Searching options by display value
- */
-export class ReferenceResolver {
-  constructor(
-    private store: ContentStore,
-    private idIndex: ContentIdIndex,
-  ) {}
-
-  /**
-   * Resolve a content ID to a display value.
-   * Returns null if the ID doesn't exist or points to a collection.
-   *
-   * @param id - The content ID to resolve
-   * @param displayField - The field to use for display value (default: 'title')
-   */
-  async resolve(id: string, displayField = 'title'): Promise<ResolvedReference | null> {
-    const location = this.idIndex.findById(id)
-
-    if (!location || location.type !== 'entry') {
-      return {
-        id,
-        exists: false,
-        displayValue: id, // Fallback to showing the ID itself
-      }
-    }
-
-    try {
-      const doc = await this.store.read(location.collection!, location.slug!)
-      const displayValue = String(doc.data[displayField] || doc.data.title || location.slug)
-
-      return {
-        id,
-        exists: true,
-        displayValue,
-        collection: location.collection,
-        slug: location.slug,
-      }
-    } catch (error) {
-      console.error('Failed to resolve reference:', { id, error })
-      return {
-        id,
-        exists: false,
-        displayValue: id,
-      }
-    }
-  }
-
-  /**
-   * Load all available reference options for a reference field.
-   *
-   * This method scans the specified collections and returns options
-   * suitable for a dropdown/select field.
-   *
-   * @param collections - Collection paths to search (e.g., ['posts', 'docs'])
-   * @param displayField - Field to use for option labels (default: 'title')
-   * @param search - Optional search string to filter options
-   */
-  async loadReferenceOptions(
-    collections: LogicalPath[],
-    displayField = 'title',
-    search?: string,
-  ): Promise<ReferenceOption[]> {
-    const options: ReferenceOption[] = []
-
-    for (const collectionPath of collections) {
-      // Get all entries in this collection
-      const entries = await this.listEntriesInCollection(collectionPath)
-
-      for (const entry of entries) {
-        const id = this.idIndex.findByPath(entry.relativePath)
-        if (!id) continue
-
-        try {
-          // The slug from the index may include the entry type prefix for new-format files
-          // (e.g., "author.alice" instead of just "alice"). We need to strip the type prefix
-          // before passing to store.read() to avoid double-prefixing.
-          // Use extractSlugFromFilename to properly extract just the slug part.
-          const filename = path.basename(entry.relativePath)
-          const normalizedSlug = extractSlugFromFilename(filename)
-
-          const doc = await this.store.read(entry.collection, normalizedSlug as EntrySlug)
-          const label = String(doc.data[displayField] || doc.data.title || normalizedSlug)
-
-          // Apply search filter if provided
-          if (search && !label.toLowerCase().includes(search.toLowerCase())) {
-            continue
-          }
-
-          options.push({
-            id,
-            label,
-            collection: entry.collection,
-          })
-        } catch (error) {
-          // Skip entries that can't be read
-          console.error('Failed to read entry for reference options:', {
-            collection: entry.collection,
-            slug: entry.slug,
-            error,
-          })
-          continue
-        }
-      }
-    }
-
-    return options.sort((a, b) => a.label.localeCompare(b.label))
-  }
-
-  /**
-   * Helper to list all entries in a collection.
-   */
-  private async listEntriesInCollection(collectionPath: LogicalPath): Promise<
-    Array<{
-      relativePath: PhysicalPath
-      collection: LogicalPath
-      slug: EntrySlug
-    }>
-  > {
-    return this.store.listCollectionEntries(collectionPath)
-  }
-
-  /**
-   * Resolve multiple IDs at once.
-   * Useful for displaying lists of referenced items.
-   */
-  async resolveMany(ids: string[], displayField = 'title'): Promise<(ResolvedReference | null)[]> {
-    return Promise.all(ids.map((id) => this.resolve(id, displayField)))
-  }
-}

package/src/schema/index.ts

@@ -1,29 +0,0 @@
-/**
- * Schema Module
- *
- * This module provides schema loading and resolution for CanopyCMS.
- * Schema structure is defined in .collection.json files (single source of truth)
- * while field schemas are defined in an entry schema registry for reusability.
- *
- * @example
- * ```ts
- * import { resolveSchema } from 'canopycms/schema'
- *
- * const { schema, sources } = await resolveSchema(contentRoot, entrySchemaRegistry)
- * ```
- */
-
-// Types
-export type { EntrySchemaRegistry, SchemaSourceInfo, SchemaResolutionResult } from './types'
-
-// Meta loader (low-level API)
-export {
-  loadCollectionMetaFiles,
-  resolveCollectionReferences,
-  watchCollectionMetaFiles,
-  type CollectionMeta,
-  type RootCollectionMeta,
-} from './meta-loader'
-
-// Resolver (high-level API)
-export { resolveSchema, hasSchemaFiles, isValidSchema } from './resolver'