canopycms 0.0.0 → 0.0.2

package/src/paths/normalize.ts

@@ -1,107 +0,0 @@
-/**
- * Path normalization utilities (client-safe).
- *
- * Consolidates the various path normalization patterns used across the codebase
- * into a single, well-tested module.
- *
- * NOTE: These functions are pure and can be used in both client and server code.
- * Server-only functions that depend on Node.js 'path' module are in normalize-server.ts.
- */
-
-import type { LogicalPath, PhysicalPath } from './types'
-
-/**
- * Normalize a filesystem path by:
- * - Converting backslashes to forward slashes
- * - Removing empty segments
- * - Removing leading/trailing slashes
- *
- * This is the foundational normalization used by most path operations.
- *
- * @example
- * normalizeFilesystemPath('content\\posts\\\\my-post') // 'content/posts/my-post'
- * normalizeFilesystemPath('/content/posts/') // 'content/posts'
- */
-export function normalizeFilesystemPath(path: string): string {
-  return path
-    .split(/[\\/]+/)
-    .filter(Boolean)
-    .join('/')
-}
-
-/**
- * Normalize a collection path by removing any content root prefix
- * and normalizing separators.
- *
- * @example
- * normalizeCollectionPath('content/posts') // 'posts'
- * normalizeCollectionPath('content\\blog\\posts') // 'blog/posts'
- * normalizeCollectionPath('posts') // 'posts'
- */
-export function normalizeCollectionPath(collectionPath: string, contentRoot = 'content'): string {
-  const normalized = normalizeFilesystemPath(collectionPath)
-  const prefix = `${contentRoot}/`
-  if (normalized.startsWith(prefix)) {
-    return normalized.slice(prefix.length)
-  }
-  return normalized
-}
-
-/**
- * Check if a path contains traversal sequences (.., etc.)
- */
-export function hasTraversalSequence(path: string): boolean {
-  const normalized = normalizeFilesystemPath(path)
-  return normalized.includes('..')
-}
-
-/**
- * Create a logical path from segments.
- * Validates that no segment contains path traversal.
- *
- * @example
- * createLogicalPath('content', 'posts', 'my-post') // 'content/posts/my-post' as LogicalPath
- */
-export function createLogicalPath(...segments: string[]): LogicalPath {
-  const normalized = segments
-    .map((s) => normalizeFilesystemPath(s))
-    .filter(Boolean)
-    .join('/')
-
-  if (hasTraversalSequence(normalized)) {
-    throw new Error(`Invalid path: contains traversal sequence: ${normalized}`)
-  }
-
-  return normalized as LogicalPath
-}
-
-/**
- * Create a physical path from segments.
- * This is for paths that may contain embedded IDs.
- *
- * @example
- * createPhysicalPath('content', 'posts', 'my-post.ABC123.mdx') // as PhysicalPath
- */
-export function createPhysicalPath(...segments: string[]): PhysicalPath {
-  const normalized = segments
-    .map((s) => normalizeFilesystemPath(s))
-    .filter(Boolean)
-    .join('/')
-
-  if (hasTraversalSequence(normalized)) {
-    throw new Error(`Invalid path: contains traversal sequence: ${normalized}`)
-  }
-
-  return normalized as PhysicalPath
-}
-
-/**
- * Join path segments with forward slashes.
- * Does not validate - use createLogicalPath/createPhysicalPath for validation.
- */
-export function joinPath(...segments: string[]): string {
-  return segments
-    .map((s) => normalizeFilesystemPath(s))
-    .filter(Boolean)
-    .join('/')
-}

package/src/paths/resolve.ts

@@ -1,61 +0,0 @@
-/**
- * Path resolution utilities for converting between physical and logical paths.
- */
-
-import type { FlatSchemaItem } from '../config'
-import type { LogicalPath } from './types'
-
-/**
- * Resolve a physical collection path to its logical path.
- *
- * Physical paths contain embedded IDs (e.g., "content/authors.q52DCVPuH4ga"),
- * while logical paths are schema-defined (e.g., "content/authors").
- *
- * This function matches physical path segments to logical path segments,
- * accounting for ID suffixes in physical paths.
- *
- * @param physicalPath - The physical filesystem path with embedded IDs
- * @param schemaItems - Iterable of schema items to search
- * @returns The matching logical path, or the physical path if no match found
- *
- * @example
- * // Match physical to logical
- * resolveLogicalPath("content/authors.q52DCVPuH4ga", schemaItems)
- * // Returns: "content/authors"
- *
- * @example
- * // Nested collections
- * resolveLogicalPath("content/docs.ABC/api.DEF", schemaItems)
- * // Returns: "content/docs/api"
- */
-export function resolveLogicalPath(
-  physicalPath: string,
-  schemaItems: Iterable<FlatSchemaItem>,
-): LogicalPath | string {
-  const pathSegments = physicalPath.split('/')
-
-  for (const schemaItem of schemaItems) {
-    if (schemaItem.type === 'collection') {
-      const logicalSegments = schemaItem.logicalPath.split('/')
-
-      // Check if all logical segments match the corresponding physical segments
-      // (ignoring the ID part after the dot in directory names)
-      if (pathSegments.length === logicalSegments.length) {
-        const matches = logicalSegments.every((logicalSeg, i) => {
-          const physicalSeg = pathSegments[i]
-          // Physical segment might have ID: "authors.q52DCVPuH4ga"
-          // Logical segment: "authors"
-          // Match if identical OR if physical starts with logical + '.'
-          return physicalSeg === logicalSeg || physicalSeg.startsWith(logicalSeg + '.')
-        })
-
-        if (matches) {
-          return schemaItem.logicalPath
-        }
-      }
-    }
-  }
-
-  // Fallback: return the physical path if we can't find a match
-  return physicalPath
-}

package/src/paths/test-utils.ts

@@ -1,37 +0,0 @@
-/**
- * Test utilities for path types.
- *
- * These are unsafe casts with NO validation. Import only from test files.
- * For production code, use the parse* or create* functions instead.
- *
- * @example
- * // In test files only:
- * import { unsafeAsLogicalPath, unsafeAsEntrySlug } from '../paths/test-utils'
- */
-
-import type {
-  BranchName,
-  CollectionSlug,
-  ContentId,
-  LogicalPath,
-  PhysicalPath,
-  EntrySlug,
-} from './types'
-
-/** Test-only: cast a string to LogicalPath without validation. */
-export const unsafeAsLogicalPath = (path: string): LogicalPath => path as LogicalPath
-
-/** Test-only: cast a string to PhysicalPath without validation. */
-export const unsafeAsPhysicalPath = (path: string): PhysicalPath => path as PhysicalPath
-
-/** Test-only: cast a string to EntrySlug without validation. */
-export const unsafeAsEntrySlug = (slug: string): EntrySlug => slug as EntrySlug
-
-/** Test-only: cast a string to BranchName without validation. */
-export const unsafeAsBranchName = (name: string): BranchName => name as BranchName
-
-/** Test-only: cast a string to CollectionSlug without validation. */
-export const unsafeAsCollectionSlug = (slug: string): CollectionSlug => slug as CollectionSlug
-
-/** Test-only: cast a string to ContentId without validation. */
-export const unsafeAsContentId = (id: string): ContentId => id as ContentId

package/src/paths/types.ts

@@ -1,68 +0,0 @@
-/**
- * Path type definitions for CanopyCMS
- *
- * These branded types provide compile-time safety to prevent accidentally
- * mixing logical paths (content/posts/my-post) with physical filesystem
- * paths (content/posts/my-post.ABC123.mdx).
- */
-
-/**
- * A logical content path without embedded IDs.
- * Used in APIs, URLs, and user-facing contexts.
- * Example: "content/posts/my-post"
- */
-export type LogicalPath = string & { readonly __brand: 'LogicalPath' }
-
-/**
- * A physical filesystem path that may contain embedded IDs.
- * Used for actual file operations.
- * Example: "content/posts/my-post.ABC123.mdx"
- */
-export type PhysicalPath = string & { readonly __brand: 'PhysicalPath' }
-
-/**
- * A branch name that has been sanitized for filesystem use.
- */
-export type SanitizedBranchName = string & {
-  readonly __brand: 'SanitizedBranchName'
-}
-
-/**
- * A git branch name (before sanitization for filesystem use).
- * Example: "feature/add-dark-mode" or "main"
- */
-export type BranchName = string & { readonly __brand: 'BranchName' }
-
-/**
- * A 12-character Base58-encoded content ID.
- * Used to uniquely identify entries and collections in filenames.
- * Example: "bChqT78gcaLd"
- */
-export type ContentId = string & { readonly __brand: 'ContentId' }
-
-/**
- * Sentinel ContentId for the root content directory (which has no embedded ID in its name).
- * Uses underscores — can never collide with real 12-char Base58 IDs (which exclude `_`).
- */
-export const ROOT_COLLECTION_ID = '__rootcoll__' as ContentId
-
-/**
- * A collection slug (validated segment of a collection path).
- * Example: "posts" or "api-docs"
- */
-export type CollectionSlug = string & { readonly __brand: 'CollectionSlug' }
-
-/**
- * An entry slug (last segment of an entry path, used in URLs and filenames).
- * Example: "my-first-post" or "getting-started"
- */
-export type EntrySlug = string & { readonly __brand: 'EntrySlug' }
-
-/**
- * Path validation result.
- */
-export interface PathValidationResult {
-  valid: boolean
-  error?: string
-  normalizedPath?: string
-}