canopycms 0.0.0

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

@@ -0,0 +1,141 @@
+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

@@ -0,0 +1,207 @@
+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

@@ -0,0 +1,61 @@
+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

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

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

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