canopycms 0.0.0 → 0.0.2

package/src/paths/__tests__/normalize.test.ts

@@ -1,141 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import {
-  normalizeFilesystemPath,
-  normalizeCollectionPath,
-  hasTraversalSequence,
-  createLogicalPath,
-  createPhysicalPath,
-  joinPath,
-} from '../normalize'
-import { validateAndNormalizePath } from '../normalize-server'
-
-describe('normalizeFilesystemPath', () => {
-  it('converts backslashes to forward slashes', () => {
-    expect(normalizeFilesystemPath('content\\posts\\my-post')).toBe('content/posts/my-post')
-  })
-
-  it('removes empty segments from double slashes', () => {
-    expect(normalizeFilesystemPath('content//posts///my-post')).toBe('content/posts/my-post')
-  })
-
-  it('removes leading and trailing slashes', () => {
-    expect(normalizeFilesystemPath('/content/posts/')).toBe('content/posts')
-  })
-
-  it('handles mixed separators', () => {
-    expect(normalizeFilesystemPath('content\\\\posts//my-post')).toBe('content/posts/my-post')
-  })
-
-  it('returns empty string for empty input', () => {
-    expect(normalizeFilesystemPath('')).toBe('')
-  })
-
-  it('returns empty string for only slashes', () => {
-    expect(normalizeFilesystemPath('///')).toBe('')
-  })
-})
-
-describe('normalizeCollectionPath', () => {
-  it('removes content/ prefix', () => {
-    expect(normalizeCollectionPath('content/posts')).toBe('posts')
-  })
-
-  it('removes content/ prefix from nested paths', () => {
-    expect(normalizeCollectionPath('content/docs/api')).toBe('docs/api')
-  })
-
-  it('leaves paths without content/ prefix unchanged', () => {
-    expect(normalizeCollectionPath('posts')).toBe('posts')
-    expect(normalizeCollectionPath('docs/api')).toBe('docs/api')
-  })
-
-  it('normalizes slashes before stripping prefix', () => {
-    expect(normalizeCollectionPath('content\\blog\\posts')).toBe('blog/posts')
-  })
-
-  it('handles custom content root', () => {
-    expect(normalizeCollectionPath('src/posts', 'src')).toBe('posts')
-  })
-})
-
-describe('validateAndNormalizePath', () => {
-  it('returns valid result for path within root', () => {
-    const result = validateAndNormalizePath('/root/content', '/root/content/posts/my-post')
-    expect(result.valid).toBe(true)
-    expect(result.normalizedPath).toBe('posts/my-post')
-  })
-
-  it('returns valid for root itself', () => {
-    const result = validateAndNormalizePath('/root/content', '/root/content')
-    expect(result.valid).toBe(true)
-    expect(result.normalizedPath).toBe('')
-  })
-
-  it('returns invalid for path traversal attempt', () => {
-    const result = validateAndNormalizePath('/root/content', '/root/evil')
-    expect(result.valid).toBe(false)
-    expect(result.error).toBe('Path traversal detected')
-  })
-
-  it('returns invalid for parent directory escape', () => {
-    const result = validateAndNormalizePath('/root/content', '/root/content/../evil')
-    expect(result.valid).toBe(false)
-    expect(result.error).toBe('Path traversal detected')
-  })
-})
-
-describe('hasTraversalSequence', () => {
-  it('detects double dots', () => {
-    expect(hasTraversalSequence('../evil')).toBe(true)
-    expect(hasTraversalSequence('content/../posts')).toBe(true)
-  })
-
-  it('returns false for safe paths', () => {
-    expect(hasTraversalSequence('content/posts')).toBe(false)
-    expect(hasTraversalSequence('file.name.txt')).toBe(false)
-  })
-})
-
-describe('createLogicalPath', () => {
-  it('joins segments with forward slashes', () => {
-    expect(createLogicalPath('content', 'posts', 'my-post')).toBe('content/posts/my-post')
-  })
-
-  it('filters empty segments', () => {
-    expect(createLogicalPath('content', '', 'posts')).toBe('content/posts')
-  })
-
-  it('normalizes each segment', () => {
-    expect(createLogicalPath('content\\posts', 'my-post')).toBe('content/posts/my-post')
-  })
-
-  it('throws on traversal sequence', () => {
-    expect(() => createLogicalPath('content', '..', 'evil')).toThrow(
-      'Invalid path: contains traversal sequence',
-    )
-  })
-})
-
-describe('createPhysicalPath', () => {
-  it('joins segments with forward slashes', () => {
-    expect(createPhysicalPath('content', 'posts', 'my-post.ABC123.mdx')).toBe(
-      'content/posts/my-post.ABC123.mdx',
-    )
-  })
-
-  it('throws on traversal sequence', () => {
-    expect(() => createPhysicalPath('content', '../evil')).toThrow(
-      'Invalid path: contains traversal sequence',
-    )
-  })
-})
-
-describe('joinPath', () => {
-  it('joins segments without validation', () => {
-    expect(joinPath('content', 'posts', 'my-post')).toBe('content/posts/my-post')
-  })
-
-  it('normalizes each segment', () => {
-    expect(joinPath('content\\posts', '', 'my-post')).toBe('content/posts/my-post')
-  })
-})

package/src/paths/__tests__/resolve.test.ts

@@ -1,207 +0,0 @@
-import { describe, it, expect } from 'vitest'
-import { resolveLogicalPath } from '../resolve'
-import { unsafeAsLogicalPath } from '../test-utils'
-import type { FlatSchemaItem } from '../../config'
-
-describe('resolveLogicalPath', () => {
-  const createMockSchemaItems = (): FlatSchemaItem[] => [
-    {
-      type: 'collection',
-      logicalPath: unsafeAsLogicalPath('content/authors'),
-      name: 'authors',
-      label: 'Authors',
-    } as FlatSchemaItem,
-    {
-      type: 'collection',
-      logicalPath: unsafeAsLogicalPath('content/posts'),
-      name: 'posts',
-      label: 'Posts',
-    } as FlatSchemaItem,
-    {
-      type: 'collection',
-      logicalPath: unsafeAsLogicalPath('content/docs'),
-      name: 'docs',
-      label: 'Docs',
-    } as FlatSchemaItem,
-    {
-      type: 'collection',
-      logicalPath: unsafeAsLogicalPath('content/docs/api'),
-      name: 'api',
-      label: 'API',
-    } as FlatSchemaItem,
-    {
-      type: 'collection',
-      logicalPath: unsafeAsLogicalPath('content/post'),
-      name: 'post',
-      label: 'Post (singular)',
-    } as FlatSchemaItem,
-  ]
-
-  describe('basic path matching', () => {
-    it('should match physical path to logical path with ID suffix', () => {
-      const schemaItems = createMockSchemaItems()
-      const result = resolveLogicalPath('content/authors.q52DCVPuH4ga', schemaItems)
-      expect(result).toBe('content/authors')
-    })
-
-    it('should match exact path without ID suffix', () => {
-      const schemaItems = createMockSchemaItems()
-      const result = resolveLogicalPath('content/authors', schemaItems)
-      expect(result).toBe('content/authors')
-    })
-
-    it('should return physical path when no match found', () => {
-      const schemaItems = createMockSchemaItems()
-      const result = resolveLogicalPath('content/unknown.ABC123', schemaItems)
-      expect(result).toBe('content/unknown.ABC123')
-    })
-  })
-
-  describe('nested collections', () => {
-    it('should match nested collection with IDs at all levels', () => {
-      const schemaItems = createMockSchemaItems()
-      const result = resolveLogicalPath('content/docs.bChqT78gcaLd/api.meiuwxTSo7UN', schemaItems)
-      expect(result).toBe('content/docs/api')
-    })
-
-    it('should match nested collection with ID only on parent', () => {
-      const schemaItems = createMockSchemaItems()
-      const result = resolveLogicalPath('content/docs.bChqT78gcaLd/api', schemaItems)
-      expect(result).toBe('content/docs/api')
-    })
-
-    it('should match nested collection with ID only on child', () => {
-      const schemaItems = createMockSchemaItems()
-      const result = resolveLogicalPath('content/docs/api.meiuwxTSo7UN', schemaItems)
-      expect(result).toBe('content/docs/api')
-    })
-
-    it('should not match if segment count differs', () => {
-      const schemaItems = createMockSchemaItems()
-      const result = resolveLogicalPath('content/docs.ABC/api.DEF/extra.GHI', schemaItems)
-      expect(result).toBe('content/docs.ABC/api.DEF/extra.GHI')
-    })
-  })
-
-  describe('edge cases with similar names', () => {
-    it('should not match collection with similar prefix (post vs posts)', () => {
-      const schemaItems = createMockSchemaItems()
-      // "posts-archive" does NOT match "posts" because there's no dot after "posts"
-      const result = resolveLogicalPath('content/posts-archive.ID123', schemaItems)
-      expect(result).toBe('content/posts-archive.ID123')
-    })
-
-    it('should match collection with exact name followed by dot', () => {
-      const schemaItems = createMockSchemaItems()
-      const result = resolveLogicalPath('content/posts.ID123', schemaItems)
-      expect(result).toBe('content/posts')
-    })
-
-    it('should distinguish between "post" and "posts"', () => {
-      const schemaItems = createMockSchemaItems()
-
-      // "post.ID" should match "post", not "posts"
-      const result1 = resolveLogicalPath('content/post.ABC123', schemaItems)
-      expect(result1).toBe('content/post')
-
-      // "posts.ID" should match "posts", not "post"
-      const result2 = resolveLogicalPath('content/posts.XYZ789', schemaItems)
-      expect(result2).toBe('content/posts')
-    })
-
-    it('should not match if physical segment is shorter than logical', () => {
-      const schemaItems = createMockSchemaItems()
-      // "pos.ID" should not match "post" or "posts"
-      const result = resolveLogicalPath('content/pos.ABC', schemaItems)
-      expect(result).toBe('content/pos.ABC')
-    })
-  })
-
-  describe('deeply nested collections', () => {
-    it('should handle 5+ levels of nesting', () => {
-      const deepSchemaItems: FlatSchemaItem[] = [
-        {
-          type: 'collection',
-          logicalPath: unsafeAsLogicalPath('content/level1/level2/level3/level4/level5'),
-          name: 'level5',
-          label: 'Level 5',
-        } as FlatSchemaItem,
-      ]
-
-      const result = resolveLogicalPath(
-        'content/level1.A/level2.B/level3.C/level4.D/level5.E',
-        deepSchemaItems,
-      )
-      expect(result).toBe('content/level1/level2/level3/level4/level5')
-    })
-  })
-
-  describe('special characters and dots in names', () => {
-    it('should handle collection names with dots in logical path', () => {
-      const schemaItems: FlatSchemaItem[] = [
-        {
-          type: 'collection',
-          logicalPath: unsafeAsLogicalPath('content/v1.0'),
-          name: 'v1.0',
-          label: 'Version 1.0',
-        } as FlatSchemaItem,
-      ]
-
-      // This is a tricky case: the logical name itself has a dot
-      // Physical path would be "v1.0.ID123", so it has TWO dots
-      const result = resolveLogicalPath('content/v1.0.ABC123', schemaItems)
-      expect(result).toBe('content/v1.0')
-    })
-
-    it('should not match if physical segment has multiple dots but wrong prefix', () => {
-      const schemaItems = createMockSchemaItems()
-      // "post.extra.ID" has a dot but doesn't match "post.ID" pattern
-      const result = resolveLogicalPath('content/post.extra.ID', schemaItems)
-      // This will match because "post.extra.ID" starts with "post."
-      expect(result).toBe('content/post')
-    })
-  })
-
-  describe('empty and root paths', () => {
-    it('should handle empty schema items', () => {
-      const result = resolveLogicalPath('content/authors.ID', [])
-      expect(result).toBe('content/authors.ID')
-    })
-
-    it('should handle root-level collection', () => {
-      const schemaItems: FlatSchemaItem[] = [
-        {
-          type: 'collection',
-          logicalPath: unsafeAsLogicalPath('content'),
-          name: 'content',
-          label: 'Content',
-        } as FlatSchemaItem,
-      ]
-
-      const result = resolveLogicalPath('content', schemaItems)
-      expect(result).toBe('content')
-    })
-  })
-
-  describe('non-collection schema items', () => {
-    it('should skip entry-type schema items', () => {
-      const schemaItems: FlatSchemaItem[] = [
-        {
-          type: 'entry-type',
-          logicalPath: unsafeAsLogicalPath('content/posts/article'),
-          name: 'article',
-          label: 'Article',
-        } as FlatSchemaItem,
-        {
-          type: 'collection',
-          logicalPath: unsafeAsLogicalPath('content/posts'),
-          name: 'posts',
-          label: 'Posts',
-        } as FlatSchemaItem,
-      ]
-
-      const result = resolveLogicalPath('content/posts.ID123', schemaItems)
-      expect(result).toBe('content/posts')
-    })
-  })
-})

package/src/paths/__tests__/validation.test.ts

@@ -1,61 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { validateContentPath, isValidCollectionPath, sanitizeForPath } from '../validation'
-
-describe('validateContentPath', () => {
-  it('returns valid for safe paths', () => {
-    const result = validateContentPath('content/posts/my-post.mdx', '/root')
-    expect(result.valid).toBe(true)
-  })
-
-  it('returns invalid for traversal attempts', () => {
-    const result = validateContentPath('../../../etc/passwd', '/root')
-    expect(result.valid).toBe(false)
-    expect(result.error).toContain('traversal')
-  })
-})
-
-describe('isValidCollectionPath', () => {
-  it('accepts valid collection paths', () => {
-    expect(isValidCollectionPath('posts')).toBe(true)
-    expect(isValidCollectionPath('docs/api')).toBe(true)
-    expect(isValidCollectionPath('blog-posts')).toBe(true)
-  })
-
-  it('rejects collection paths with traversal', () => {
-    expect(isValidCollectionPath('../evil')).toBe(false)
-    expect(isValidCollectionPath('posts/../evil')).toBe(false)
-  })
-
-  it('rejects empty collection paths', () => {
-    expect(isValidCollectionPath('')).toBe(false)
-  })
-})
-
-describe('sanitizeForPath', () => {
-  it('removes invalid filesystem characters', () => {
-    expect(sanitizeForPath('file<name>:test')).toBe('filenametest')
-    expect(sanitizeForPath('file|name?test')).toBe('filenametest')
-    expect(sanitizeForPath('file*name"test')).toBe('filenametest')
-  })
-
-  it('removes backslashes', () => {
-    expect(sanitizeForPath('path\\to\\file')).toBe('pathtofile')
-  })
-
-  it('collapses multiple dots', () => {
-    expect(sanitizeForPath('hello...world')).toBe('hello.world')
-    expect(sanitizeForPath('a..b..c')).toBe('a.b.c')
-  })
-
-  it('removes leading dots', () => {
-    expect(sanitizeForPath('.hidden')).toBe('hidden')
-  })
-
-  it('trims whitespace', () => {
-    expect(sanitizeForPath('  hello  ')).toBe('hello')
-  })
-
-  it('preserves valid characters', () => {
-    expect(sanitizeForPath('hello-world_123')).toBe('hello-world_123')
-  })
-})

package/src/paths/branch.ts

@@ -1,115 +0,0 @@
-/**
- * Branch path resolution utilities.
- *
- * Handles resolving branch names to workspace directories.
- */
-
-import fs from 'node:fs/promises'
-import path from 'node:path'
-
-import type { BranchContext } from '../types'
-import { OperatingMode, operatingStrategy } from '../operating-mode'
-import type { SanitizedBranchName } from './types'
-
-export interface BranchPathOptions {
-  mode: OperatingMode
-  branchName: string
-  basePathOverride?: string
-}
-
-export interface BranchPathResult {
-  branchRoot: string
-  baseRoot: string
-  branchName: string
-}
-
-export class BranchPathError extends Error {}
-
-/**
- * Sanitize a branch name for use in filesystem paths.
- * - Replaces invalid characters with hyphens
- * - Collapses multiple hyphens
- * - Trims leading/trailing dots
- */
-export function sanitizeBranchName(branchName: string): SanitizedBranchName {
-  const replaced = branchName.replace(/[^a-zA-Z0-9._-]/g, '-')
-  const squashed = replaced.replace(/-+/g, '-')
-  const trimmedDots = squashed.replace(/^\.+/, '').replace(/\.+$/, '')
-  return (trimmedDots || 'branch') as SanitizedBranchName
-}
-
-const resolveContentBranchesRoot = (mode: OperatingMode, override?: string): string => {
-  return operatingStrategy(mode).getContentBranchesRoot(override)
-}
-
-/**
- * Resolve branch name to workspace paths.
- * Validates for path traversal attacks.
- */
-export function resolveBranchPath(options: BranchPathOptions): BranchPathResult {
-  if (options.branchName.includes('..')) {
-    throw new BranchPathError('Branch name cannot contain traversal segments')
-  }
-  const safeBranch = sanitizeBranchName(options.branchName)
-  const strategy = operatingStrategy(options.mode)
-  const baseRoot = resolveContentBranchesRoot(options.mode, options.basePathOverride)
-  const normalizedBase = path.resolve(baseRoot)
-  const baseWithSep = normalizedBase.endsWith(path.sep)
-    ? normalizedBase
-    : `${normalizedBase}${path.sep}`
-  const branchRoot = strategy.getContentBranchRoot(safeBranch, options.basePathOverride)
-
-  const withinBase = (target: string) => {
-    const resolved = path.resolve(target)
-    return resolved === normalizedBase || resolved.startsWith(baseWithSep)
-  }
-
-  if (!withinBase(branchRoot)) {
-    throw new BranchPathError('Branch path resolves outside the base root')
-  }
-
-  return { branchRoot, baseRoot: normalizedBase, branchName: safeBranch }
-}
-
-/**
- * Ensure the branch workspace directory exists.
- */
-export async function ensureBranchRoot(options: BranchPathOptions): Promise<BranchPathResult> {
-  const result = resolveBranchPath(options)
-  await fs.mkdir(result.branchRoot, { recursive: true })
-  return result
-}
-
-/**
- * Get the default base directory for branch workspaces.
- */
-export function getDefaultBranchBase(mode: OperatingMode, override?: string): string {
-  return resolveContentBranchesRoot(mode, override)
-}
-
-/**
- * Resolve branch paths from a branch context.
- */
-export function resolveBranchPaths(
-  branchContext: BranchContext,
-  mode: OperatingMode,
-  basePathOverride?: string,
-): BranchPathResult {
-  if (branchContext.branchRoot || branchContext.baseRoot) {
-    const baseRoot = path.resolve(
-      branchContext.baseRoot ?? resolveContentBranchesRoot(mode, basePathOverride),
-    )
-    const branchRoot = path.resolve(branchContext.branchRoot ?? baseRoot)
-    return {
-      branchRoot,
-      baseRoot,
-      branchName: sanitizeBranchName(branchContext.branch.name),
-    }
-  }
-
-  return resolveBranchPath({
-    mode,
-    branchName: branchContext.branch.name,
-    basePathOverride,
-  })
-}

package/src/paths/index.ts

@@ -1,73 +0,0 @@
-/**
- * Path utilities for CanopyCMS
- *
- * This module consolidates path handling utilities that were previously
- * scattered across multiple files:
- * - normalize.ts: Path normalization and creation
- * - validation.ts: Security validation for paths
- * - branch.ts: Branch workspace path resolution
- * - types.ts: Branded types for type safety
- *
- * Usage:
- * ```ts
- * import { normalizeFilesystemPath, createLogicalPath, parseSlug } from '../paths'
- * ```
- */
-
-// Types
-export type {
-  LogicalPath,
-  PhysicalPath,
-  SanitizedBranchName,
-  BranchName,
-  ContentId,
-  CollectionSlug,
-  EntrySlug,
-  PathValidationResult,
-} from './types'
-
-// Normalization utilities (client-safe)
-export {
-  normalizeFilesystemPath,
-  normalizeCollectionPath,
-  hasTraversalSequence,
-  createLogicalPath,
-  createPhysicalPath,
-  joinPath,
-} from './normalize'
-
-// Normalization utilities (server-only, requires Node.js path module)
-export { validateAndNormalizePath } from './normalize-server'
-
-// Validation utilities
-export {
-  validateContentPath,
-  isValidCollectionPath,
-  sanitizeForPath,
-  // Path type detection and parsing
-  hasEmbeddedContentId,
-  looksLikePhysicalPath,
-  looksLikeLogicalPath,
-  parseLogicalPath,
-  parsePhysicalPath,
-  isValidContentId,
-  // Branded type validation and parsing
-  parseContentId,
-  parseBranchName,
-  parseSlug,
-} from './validation'
-
-// Path resolution utilities
-export { resolveLogicalPath } from './resolve'
-
-// Branch path utilities
-export {
-  resolveBranchPath,
-  ensureBranchRoot,
-  getDefaultBranchBase,
-  resolveBranchPaths,
-  sanitizeBranchName,
-  BranchPathError,
-  type BranchPathOptions,
-  type BranchPathResult,
-} from './branch'

package/src/paths/normalize-server.ts

@@ -1,40 +0,0 @@
-/**
- * Server-only path normalization utilities.
- *
- * These functions depend on Node.js 'path' module and cannot be used in client code.
- * Client-safe functions are in normalize.ts.
- */
-
-import { sep, resolve, relative } from 'node:path'
-import type { PathValidationResult } from './types'
-
-/**
- * Validate and normalize a path relative to a root directory.
- * Checks for path traversal attacks.
- *
- * NOTE: This function uses Node.js path module and is server-only.
- * For client code, use the pure functions in normalize.ts.
- *
- * @param root - The root directory
- * @param target - The target path to validate
- * @returns Validation result with normalized relative path if valid
- */
-export function validateAndNormalizePath(root: string, target: string): PathValidationResult {
-  const resolvedRoot = resolve(root)
-  const withSep = resolvedRoot.endsWith(sep) ? resolvedRoot : `${resolvedRoot}${sep}`
-  const resolvedTarget = resolve(target)
-
-  if (!resolvedTarget.startsWith(withSep) && resolvedTarget !== resolvedRoot) {
-    return {
-      valid: false,
-      error: 'Path traversal detected',
-    }
-  }
-
-  const relativePath = relative(resolvedRoot, resolvedTarget).split(sep).join('/')
-
-  return {
-    valid: true,
-    normalizedPath: relativePath,
-  }
-}