canopycms 0.0.0

package/src/http/router.ts

@@ -0,0 +1,164 @@
+import type { ApiResponse } from '../api/types'
+import { BRANCH_ROUTES } from '../api/branch'
+import { WORKFLOW_ROUTES } from '../api/branch-status'
+import { COMMENT_ROUTES } from '../api/comments'
+import { CONTENT_ROUTES } from '../api/content'
+import { REFERENCE_OPTIONS_ROUTES } from '../api/reference-options'
+import { RESOLVE_REFERENCES_ROUTES } from '../api/resolve-references'
+import { ENTRY_ROUTES } from '../api/entries'
+import { ASSET_ROUTES } from '../api/assets'
+import { PERMISSION_ROUTES } from '../api/permissions'
+import { GROUP_ROUTES } from '../api/groups'
+import { USER_ROUTES } from '../api/user'
+import { SCHEMA_ROUTES } from '../api/schema'
+
+/**
+ * Handler function signature for Canopy API routes.
+ * Uses `any` to accommodate different handler signatures in the codebase.
+ * Some handlers take (ctx, req, params), others take (ctx, params) directly.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type CanopyHandler = (...args: any[]) => Promise<ApiResponse<any>>
+
+/**
+ * Route definition for the Canopy API.
+ * Maps HTTP method + path pattern to a handler.
+ */
+export interface RouteDefinition {
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
+  pattern: readonly string[] // e.g., [':branch', 'content', ':collection', '...slug']
+  handler: CanopyHandler
+  // Optional validation function for routes defined with defineEndpoint()
+  validate?: (extracted: { params?: Record<string, string>; body?: unknown }) =>
+    | {
+        ok: true
+        params?: unknown
+        body?: unknown
+      }
+    | {
+        ok: false
+        error: string
+      }
+}
+
+/**
+ * Result of route matching.
+ */
+export interface RouteMatch {
+  handler: CanopyHandler
+  params: Record<string, string>
+  // Optional validation function for new-style routes
+  validate?: RouteDefinition['validate']
+}
+
+/**
+ * Core router - framework-agnostic route matching.
+ */
+export interface CanopyRouter {
+  /** All registered routes */
+  readonly routes: RouteDefinition[]
+
+  /** Find a matching route for the given method and path segments */
+  match(method: string, segments: string[]): RouteMatch | null
+}
+
+/**
+ * Build the standard route definitions for the Canopy API.
+ * Assembled from co-located route definitions in each API module.
+ *
+ * This is a function (not a top-level constant) to ensure all route modules
+ * have been fully initialized before we try to access their exports.
+ * This prevents module initialization timing issues with ES modules.
+ */
+function buildCanopyRoutes(): RouteDefinition[] {
+  return [
+    ...Object.values(BRANCH_ROUTES),
+    ...Object.values(WORKFLOW_ROUTES),
+    ...Object.values(COMMENT_ROUTES),
+    ...Object.values(CONTENT_ROUTES),
+    ...Object.values(REFERENCE_OPTIONS_ROUTES),
+    ...Object.values(RESOLVE_REFERENCES_ROUTES),
+    ...Object.values(ENTRY_ROUTES),
+    ...Object.values(ASSET_ROUTES),
+    ...Object.values(PERMISSION_ROUTES),
+    ...Object.values(GROUP_ROUTES),
+    ...Object.values(USER_ROUTES),
+    ...Object.values(SCHEMA_ROUTES),
+  ].map(
+    (route): RouteDefinition => ({
+      method: route.method,
+      pattern: route.pattern,
+      handler: route.handler,
+      // Include validation function if present (new-style routes from defineEndpoint)
+      validate: 'validate' in route ? (route.validate as RouteDefinition['validate']) : undefined,
+    }),
+  )
+}
+
+/**
+ * Match a route pattern against actual path segments.
+ * Supports :param for single-segment params and ...slug for catch-all.
+ */
+const matchPattern = (
+  pattern: readonly string[],
+  actual: string[],
+): { params: Record<string, string> } | null => {
+  const params: Record<string, string> = {}
+  const actualCopy = [...actual]
+
+  for (const part of pattern) {
+    // Catch-all: consume remaining segments
+    if (part.startsWith('...')) {
+      const paramName = part.slice(3) // Remove '...' prefix
+      params[paramName] = actualCopy.join('/')
+      actualCopy.length = 0
+      break
+    }
+
+    const next = actualCopy.shift()
+    if (!next) return null
+
+    if (part.startsWith(':')) {
+      // Dynamic segment - extract param
+      params[part.slice(1)] = decodeURIComponent(next)
+    } else if (part !== next) {
+      // Static segment - must match exactly
+      return null
+    }
+  }
+
+  // If there are leftover segments, no match
+  if (actualCopy.length > 0) return null
+
+  return { params }
+}
+
+/**
+ * Create the standard Canopy router with all API routes.
+ */
+export function createCanopyRouter(): CanopyRouter {
+  const routes = buildCanopyRoutes()
+
+  return {
+    routes,
+
+    match(method: string, segments: string[]): RouteMatch | null {
+      const upperMethod = method.toUpperCase()
+
+      for (const route of routes) {
+        if (route.method !== upperMethod) continue
+
+        const match = matchPattern(route.pattern, segments)
+        if (match) {
+          return {
+            handler: route.handler,
+            params: match.params,
+            validate: route.validate, // Include validation function if present
+          }
+        }
+      }
+
+      return null
+    },
+  }
+}

package/src/http/types.ts

@@ -0,0 +1,44 @@
+/**
+ * Framework-agnostic HTTP request interface.
+ * Minimal surface area - only what CanopyCMS actually needs.
+ */
+export interface CanopyRequest {
+  /** HTTP method (GET, POST, PUT, DELETE, etc.) */
+  readonly method: string
+
+  /** Full request URL as string */
+  readonly url: string
+
+  /**
+   * Get request header value (case-insensitive).
+   * Returns null if header not present.
+   */
+  header(name: string): string | null
+
+  /**
+   * Parse request body as JSON.
+   * Returns undefined for GET requests or empty bodies.
+   */
+  json(): Promise<unknown>
+}
+
+/**
+ * Framework-agnostic HTTP response.
+ * Represents the response data to be sent back.
+ */
+export interface CanopyResponse<T = unknown> {
+  readonly status: number
+  readonly body: T
+  readonly headers?: Record<string, string>
+}
+
+/**
+ * Create a JSON response with the given body and status code.
+ */
+export function jsonResponse<T>(
+  body: T,
+  status = 200,
+  headers?: Record<string, string>,
+): CanopyResponse<T> {
+  return { status, body, headers }
+}

package/src/id.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest'
+
+import { generateId, isValidId } from './id'
+
+describe('id utilities', () => {
+  describe('generateId', () => {
+    it('generates a 12-character string', () => {
+      const id = generateId()
+      expect(id).toHaveLength(12)
+    })
+
+    it('generates unique IDs', () => {
+      const id1 = generateId()
+      const id2 = generateId()
+      expect(id1).not.toBe(id2)
+    })
+
+    it('generates URL-safe characters only', () => {
+      const id = generateId()
+      // Base58 alphabet (no 0, O, I, l to avoid confusion)
+      expect(id).toMatch(/^[123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]+$/)
+    })
+  })
+
+  describe('isValidId', () => {
+    it('returns true for valid 12-character IDs', () => {
+      const id = generateId()
+      expect(isValidId(id)).toBe(true)
+    })
+
+    it('returns true for 12-character IDs', () => {
+      expect(isValidId('a1b2c3d4e5f6')).toBe(true)
+      expect(isValidId('XYZ123abc789')).toBe(true)
+    })
+
+    it('returns false for IDs with invalid length', () => {
+      expect(isValidId('abc123')).toBe(false) // Too short
+      expect(isValidId('abc123def456ghi789jkm2')).toBe(false) // Too long (22 chars)
+      expect(isValidId('abc123def456ghi789jkm234567')).toBe(false) // Too long
+    })
+
+    it('returns false for IDs with invalid characters', () => {
+      expect(isValidId('abc123!@#$%^')).toBe(false) // Special chars
+      expect(isValidId('abc123 space')).toBe(false) // Space
+      expect(isValidId('0OIlabc12345')).toBe(false) // Ambiguous chars (0, O, I, l)
+    })
+  })
+})

package/src/id.ts

@@ -0,0 +1,22 @@
+import { generate } from 'short-uuid'
+import type { ContentId } from './paths/types'
+import { isValidContentId } from './paths/validation'
+
+/**
+ * Generate a new 12-character content ID.
+ * Uses Base58-encoded UUID, truncated for shorter filenames.
+ *
+ * Collision probability with 12 chars:
+ * - ~58^12 = 2.6 × 10^21 possible IDs
+ * - With 10,000 entries: collision chance ~0.000000002%
+ */
+export function generateId(): ContentId {
+  const full = generate() // 22 chars
+  return full.substring(0, 12) as ContentId // Truncate to 12 chars
+}
+
+/**
+ * Validate that a string is a valid content ID format.
+ * Standard format: 12 characters using Base58 alphabet (no ambiguous characters: 0, O, I, l).
+ */
+export const isValidId = isValidContentId

package/src/index.ts

@@ -0,0 +1,26 @@
+export * from './config'
+export * from './entry-schema'
+export * from './types'
+export * from './user'
+// AI content config helper — client-safe (no node: imports).
+// Server-only AI features (handler, generator) are in 'canopycms/ai'.
+export { defineAIContentConfig } from './ai/types'
+export type {
+  AIContentConfig,
+  ExcludeConfig,
+  BundleConfig,
+  BundleFilter,
+  FieldTransformFn,
+  FieldTransforms,
+} from './ai/types'
+// Only re-export client-safe types from auth. Server-only implementations
+// (CachingAuthPlugin, FileBasedAuthCache) are available via 'canopycms/auth/cache'.
+export type { AuthPlugin, AuthPluginFactory } from './auth/plugin'
+export type { UserSearchResult, GroupMetadata, AuthenticationResult } from './auth/types'
+export {
+  isCanopyRequest,
+  isHeadersLike,
+  extractHeaders,
+  validateAuthContext,
+} from './auth/context-helpers'
+export type { HeadersLike } from './auth/context-helpers'