canopycms 0.0.0

package/src/http/handler.test.ts

@@ -0,0 +1,275 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest'
+import { createCanopyRequestHandler } from './handler'
+import type { CanopyRequest } from './types'
+import type { AuthPlugin } from '../auth/plugin'
+import { mockConsole } from '../test-utils/console-spy'
+
+// Mock the BranchWorkspaceManager to avoid git operations
+vi.mock('../branch-workspace', () => ({
+  BranchWorkspaceManager: vi.fn().mockImplementation(() => ({
+    openOrCreateBranch: vi.fn().mockResolvedValue({
+      branch: {
+        name: 'new-branch',
+        status: 'editing',
+        createdBy: 'test-user',
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+        access: {},
+      },
+      branchRoot: '/tmp/test',
+      baseRoot: '/tmp/base',
+    }),
+  })),
+  loadBranchContext: vi.fn().mockResolvedValue(null),
+}))
+
+// Mock the permissions loader to avoid file system operations
+vi.mock('../authorization/permissions', () => ({
+  loadPathPermissions: vi.fn().mockResolvedValue([]),
+}))
+
+const ADMINS = 'Admins'
+
+/**
+ * Create a mock AuthPlugin for testing.
+ */
+const createMockAuthPlugin = (
+  user = {
+    type: 'authenticated' as const,
+    userId: 'test-user',
+    groups: [ADMINS],
+  },
+): AuthPlugin => ({
+  authenticate: async () => ({
+    success: true,
+    user: {
+      userId: user.userId,
+      externalGroups: user.groups,
+    },
+  }),
+  searchUsers: async () => [],
+  getUserMetadata: async () => null,
+  getGroupMetadata: async () => null,
+  listGroups: async () => [],
+})
+
+/**
+ * Create a mock AuthPlugin that rejects all authentication.
+ */
+const createRejectingAuthPlugin = (error = 'Unauthorized'): AuthPlugin => ({
+  authenticate: async () => ({ success: false, error }),
+  searchUsers: async () => [],
+  getUserMetadata: async () => null,
+  getGroupMetadata: async () => null,
+  listGroups: async () => [],
+})
+
+/**
+ * Create a mock CanopyRequest for testing.
+ */
+const createMockRequest = (overrides: Partial<CanopyRequest> = {}): CanopyRequest => ({
+  method: 'GET',
+  url: 'http://localhost:3000/api/canopycms/branches',
+  header: () => null,
+  json: async () => undefined,
+  ...overrides,
+})
+
+/**
+ * Create mock services for testing.
+ */
+const createMockServices = () => ({
+  config: {
+    schema: [],
+    contentRoot: 'content',
+    gitBotAuthorName: 'Test Bot',
+    gitBotAuthorEmail: 'bot@test.com',
+    mode: 'dev' as const,
+  },
+  checkBranchAccess: vi.fn().mockReturnValue({ allowed: true, reason: '' }),
+  checkPathAccess: vi.fn().mockReturnValue({ allowed: true }),
+  checkContentAccess: vi.fn().mockReturnValue({ allowed: true, branch: {}, path: {} }),
+  pathPermissions: [],
+  createGitManagerFor: vi.fn(),
+  registry: {
+    get: vi.fn().mockResolvedValue(null),
+    list: vi.fn().mockResolvedValue([]),
+  },
+  bootstrapAdminIds: new Set<string>(),
+})
+
+describe('createCanopyRequestHandler', () => {
+  beforeEach(() => {
+    mockConsole()
+  })
+
+  it('routes requests to handlers and returns response', async () => {
+    const services: any = createMockServices()
+    const authPlugin = createMockAuthPlugin()
+
+    const handler = createCanopyRequestHandler({
+      services,
+      authPlugin,
+      getBranchContext: async () => null,
+    })
+
+    const req = createMockRequest({
+      method: 'GET',
+      url: 'http://localhost:3000/api/canopycms/branches',
+    })
+
+    const response = await handler(req, ['branches'])
+
+    expect(response.status).toBe(200)
+    expect(response.body).toHaveProperty('ok', true)
+  })
+
+  it('returns 404 for unknown routes', async () => {
+    const services: any = createMockServices()
+    const authPlugin = createMockAuthPlugin()
+
+    const handler = createCanopyRequestHandler({
+      services,
+      authPlugin,
+      getBranchContext: async () => null,
+    })
+
+    const req = createMockRequest()
+    const response = await handler(req, ['unknown', 'route'])
+
+    expect(response.status).toBe(404)
+    expect(response.body).toHaveProperty('error', 'Not found')
+  })
+
+  it('returns 401 for unauthenticated requests', async () => {
+    const services: any = createMockServices()
+    const authPlugin = createRejectingAuthPlugin('No token')
+
+    const handler = createCanopyRequestHandler({
+      services,
+      authPlugin,
+      getBranchContext: async () => null,
+    })
+
+    const req = createMockRequest()
+    const response = await handler(req, ['branches'])
+
+    expect(response.status).toBe(401)
+    expect(response.body).toHaveProperty('error', 'No token')
+  })
+
+  it('handles POST requests with empty body gracefully', async () => {
+    const services: any = createMockServices()
+    const authPlugin = createMockAuthPlugin()
+
+    const handler = createCanopyRequestHandler({
+      services,
+      authPlugin,
+      getBranchContext: async () => ({
+        baseRoot: '/tmp/base',
+        branchRoot: '/tmp/base/test',
+        branch: {
+          name: 'test',
+          status: 'editing',
+          access: {},
+          createdBy: 'user1',
+          createdAt: new Date().toISOString(),
+          updatedAt: new Date().toISOString(),
+        },
+      }),
+    })
+
+    const req = createMockRequest({
+      method: 'POST',
+      url: 'http://localhost:3000/api/canopycms/test/submit',
+      json: async () => {
+        throw new SyntaxError('Unexpected end of JSON input')
+      },
+    })
+
+    // Should not crash, should handle gracefully
+    const response = await handler(req, ['test', 'submit'])
+    expect(response).toBeDefined()
+  })
+
+  it('handles POST requests with valid body', async () => {
+    const services: any = createMockServices()
+    const authPlugin = createMockAuthPlugin()
+
+    const handler = createCanopyRequestHandler({
+      services,
+      authPlugin,
+      getBranchContext: async () => null,
+    })
+
+    const req = createMockRequest({
+      method: 'POST',
+      url: 'http://localhost:3000/api/canopycms/branches',
+      json: async () => ({ branch: 'new-branch', title: 'Test Branch' }),
+    })
+
+    const response = await handler(req, ['branches'])
+    expect(response.status).toBe(200)
+  })
+
+  it('parses query parameters from URL', async () => {
+    const services: any = createMockServices()
+    const authPlugin = createMockAuthPlugin()
+
+    const handler = createCanopyRequestHandler({
+      services,
+      authPlugin,
+      getBranchContext: async () => null,
+    })
+
+    const req = createMockRequest({
+      method: 'GET',
+      url: 'http://localhost:3000/api/canopycms/users/search?query=test&limit=5',
+    })
+
+    const response = await handler(req, ['users', 'search'])
+    // The handler should parse the query params - we're just verifying it doesn't crash
+    expect(response).toBeDefined()
+  })
+
+  it('applies bootstrap admin groups to user', async () => {
+    const services: any = createMockServices()
+    services.bootstrapAdminIds = new Set(['test-user'])
+
+    // User without Admins group
+    const authPlugin = createMockAuthPlugin({
+      type: 'authenticated',
+      userId: 'test-user',
+      groups: [],
+    })
+
+    const handler = createCanopyRequestHandler({
+      services,
+      authPlugin,
+      getBranchContext: async () => null,
+    })
+
+    const req = createMockRequest()
+    const response = await handler(req, ['branches'])
+
+    // Should succeed because bootstrap admin gets Admins group added
+    expect(response.status).toBe(200)
+  })
+
+  it('throws error when no config or services provided', async () => {
+    const authPlugin = createMockAuthPlugin()
+
+    expect(() =>
+      createCanopyRequestHandler({
+        authPlugin,
+      } as any),
+    ).not.toThrow() // Factory doesn't throw, handler will throw on first request
+
+    const handler = createCanopyRequestHandler({
+      authPlugin,
+    } as any)
+
+    const req = createMockRequest()
+    await expect(handler(req, ['branches'])).rejects.toThrow('config or services is required')
+  })
+})

package/src/http/handler.ts

@@ -0,0 +1,280 @@
+import type { CanopyRequest, CanopyResponse } from './types'
+import { jsonResponse } from './types'
+import { createCanopyRouter } from './router'
+import type { ApiContext, ApiResponse } from '../api/types'
+import type { AuthPlugin } from '../auth/plugin'
+import { createCanopyServices, type CanopyServices } from '../services'
+import type { CanopyConfig } from '../config'
+import type { BranchContext } from '../types'
+import { loadBranchContext, BranchWorkspaceManager } from '../branch-workspace'
+import { authResultToCanopyUser } from '../user'
+import { loadInternalGroups, RESERVED_GROUPS } from '../authorization'
+import { clientOperatingStrategy } from '../operating-mode'
+
+let warnedNoAdmins = false
+
+/**
+ * Options for creating a Canopy request handler.
+ * This is framework-agnostic - adapters convert their framework's
+ * request/response types to/from CanopyRequest/CanopyResponse.
+ */
+export interface CanopyHandlerOptions {
+  services?: CanopyServices
+  config?: CanopyConfig
+  assetStore?: ApiContext['assetStore']
+  getBranchContext?: (branch: string) => Promise<BranchContext | null>
+  authPlugin: AuthPlugin
+}
+
+/**
+ * Build API context from options.
+ */
+const buildContext = async (options: CanopyHandlerOptions): Promise<ApiContext> => {
+  const services =
+    options.services ?? (options.config ? await createCanopyServices(options.config) : undefined)
+  if (!services) {
+    throw new Error('CanopyCMS: config or services is required')
+  }
+  const operatingMode = services.config.mode
+  const baseBranch = services.config.defaultBaseBranch ?? 'main'
+  const settingsBranch = services.config.settingsBranch ?? 'canopycms-settings'
+
+  const getBranchContext =
+    options.getBranchContext ??
+    (async (branch: string, opts?: { loadSchema?: boolean }): Promise<BranchContext | null> => {
+      // Try to load existing branch
+      const existing = await loadBranchContext({
+        branchName: branch,
+        mode: operatingMode,
+      })
+      if (existing) {
+        // Optionally load per-branch schema
+        if (opts?.loadSchema) {
+          const contentRootName = services.config.contentRoot || 'content'
+          const cached = await services.branchSchemaCache.getSchema(
+            existing.branchRoot,
+            services.entrySchemaRegistry,
+            contentRootName,
+          )
+          existing.flatSchema = cached.flatSchema
+        }
+        return existing
+      }
+
+      // In modes that support branching, auto-create system branches if they don't exist
+      const shouldAutoCreate =
+        clientOperatingStrategy(operatingMode).supportsBranching() &&
+        (branch === baseBranch || branch === settingsBranch)
+
+      if (shouldAutoCreate) {
+        const manager = new BranchWorkspaceManager(services.config)
+        const context = await manager.openOrCreateBranch({
+          branchName: branch,
+          mode: operatingMode,
+          createdBy: 'canopycms-system',
+        })
+
+        // Optionally load per-branch schema for auto-created branches
+        if (opts?.loadSchema && context) {
+          const contentRootName = services.config.contentRoot || 'content'
+          const cached = await services.branchSchemaCache.getSchema(
+            context.branchRoot,
+            services.entrySchemaRegistry,
+            contentRootName,
+          )
+          context.flatSchema = cached.flatSchema
+        }
+
+        return context
+      }
+
+      return null
+    })
+
+  return {
+    services,
+    assetStore: options.assetStore,
+    getBranchContext,
+    authPlugin: options.authPlugin,
+  }
+}
+
+/**
+ * Parse query parameters from URL.
+ */
+const parseQueryParams = (url: string): Record<string, string> => {
+  try {
+    const urlObj = new URL(url, 'http://localhost')
+    return Object.fromEntries(urlObj.searchParams.entries())
+  } catch {
+    return {}
+  }
+}
+
+/**
+ * Core request handler result type.
+ */
+export type CanopyRequestHandler = (
+  req: CanopyRequest,
+  pathSegments: string[],
+) => Promise<CanopyResponse<ApiResponse>>
+
+/**
+ * Create a framework-agnostic Canopy request handler.
+ *
+ * This is the core handler that processes all Canopy API requests.
+ * Framework adapters (Next.js, Express, Hono, etc.) should:
+ * 1. Convert their framework's request to CanopyRequest
+ * 2. Extract path segments from the URL
+ * 3. Call this handler
+ * 4. Convert the CanopyResponse to their framework's response
+ *
+ * @example
+ * ```ts
+ * // In a framework adapter
+ * const coreHandler = createCanopyRequestHandler({
+ *   config: myConfig,
+ *   authPlugin: myAuthPlugin,
+ * })
+ *
+ * // Framework-specific handler
+ * async function handleRequest(frameworkReq) {
+ *   const canopyReq = convertToCanopyRequest(frameworkReq)
+ *   const segments = extractPathSegments(frameworkReq)
+ *   const response = await coreHandler(canopyReq, segments)
+ *   return convertToFrameworkResponse(response)
+ * }
+ * ```
+ */
+export function createCanopyRequestHandler(options: CanopyHandlerOptions): CanopyRequestHandler {
+  const router = createCanopyRouter()
+
+  // Build context once at initialization, not per-request
+  let apiCtxPromise: Promise<ApiContext> | null = null
+  const getContext = () => {
+    if (!apiCtxPromise) {
+      apiCtxPromise = buildContext(options)
+    }
+    return apiCtxPromise
+  }
+
+  return async (
+    req: CanopyRequest,
+    pathSegments: string[],
+  ): Promise<CanopyResponse<ApiResponse>> => {
+    // Route matching (fast, do first before async work)
+    const match = router.match(req.method, pathSegments)
+    if (!match) {
+      return jsonResponse({ ok: false, status: 404, error: 'Not found' }, 404)
+    }
+
+    // Get cached context
+    const apiCtx = await getContext()
+
+    // Authenticate and convert to CanopyUser
+    const authResult = await options.authPlugin.authenticate(req)
+
+    // Load internal groups from main branch and merge with user groups
+    const baseBranch = apiCtx.services.config.defaultBaseBranch ?? 'main'
+    const mainBranchContext = await apiCtx.getBranchContext(baseBranch)
+    const operatingMode = apiCtx.services.config.mode
+    const internalGroups = mainBranchContext
+      ? await loadInternalGroups(
+          mainBranchContext.branchRoot,
+          operatingMode,
+          apiCtx.services.bootstrapAdminIds,
+        ).catch((err: unknown) => {
+          console.warn('CanopyCMS: Failed to load internal groups from main branch:', err)
+          return []
+        })
+      : []
+
+    if (!warnedNoAdmins && Array.isArray(internalGroups)) {
+      const adminsGroup = internalGroups.find((g) => g.id === RESERVED_GROUPS.ADMINS)
+      const hasAdmins =
+        (adminsGroup && adminsGroup.members.length > 0) ||
+        apiCtx.services.bootstrapAdminIds.size > 0
+      if (!hasAdmins) {
+        console.warn(
+          'CanopyCMS: No admin users configured. Set CANOPY_BOOTSTRAP_ADMIN_IDS or add members to the Admins group.',
+        )
+      }
+      warnedNoAdmins = true
+    }
+
+    const user = authResultToCanopyUser(
+      authResult,
+      apiCtx.services.bootstrapAdminIds,
+      internalGroups,
+    )
+
+    // API routes require authentication - reject anonymous users
+    if (user.type === 'anonymous') {
+      return jsonResponse(
+        { ok: false, status: 401, error: authResult.error ?? 'Unauthorized' },
+        401,
+      )
+    }
+
+    // Parse query params and merge with route params
+    const queryParams = parseQueryParams(req.url)
+    const mergedParams = { ...queryParams, ...match.params }
+
+    // Parse body for non-GET requests
+    let body: unknown
+    if (req.method !== 'GET') {
+      try {
+        body = await req.json()
+      } catch {
+        body = undefined
+      }
+    }
+
+    // Build API request
+    const branch =
+      (mergedParams as Record<string, string>)?.branch ??
+      (body as Record<string, unknown> | undefined)?.branch
+    const apiReq = { user, body, branch, query: queryParams }
+
+    // Validate params and body using the route's validation function (if available)
+    if (match.validate) {
+      const validationResult = match.validate({ params: mergedParams, body })
+      if (!validationResult.ok) {
+        return jsonResponse({ ok: false, status: 400, error: validationResult.error }, 400)
+      }
+
+      // Call handler with validated params/body based on what's defined
+      const handlerArgs: unknown[] = [apiCtx, apiReq]
+      if (validationResult.params !== undefined) {
+        handlerArgs.push(validationResult.params)
+      }
+      if (validationResult.body !== undefined) {
+        handlerArgs.push(validationResult.body)
+      }
+
+      const result = await match.handler(...handlerArgs)
+      return jsonResponse(result, result.status)
+    } else {
+      // Should not happen - all routes should use defineEndpoint now
+      // This is here for safety in case any route doesn't have validation
+      const result = await match.handler(
+        apiCtx as unknown,
+        apiReq as unknown,
+        mergedParams as unknown,
+      )
+      return jsonResponse(result, result.status)
+    }
+  }
+}
+
+/**
+ * Create a handler with pre-built services from config.
+ */
+export async function createCanopyRequestHandlerFromConfig(
+  options: { config: CanopyConfig } & Omit<CanopyHandlerOptions, 'services' | 'config'>,
+): Promise<CanopyRequestHandler> {
+  return createCanopyRequestHandler({
+    ...options,
+    services: await createCanopyServices(options.config),
+  })
+}

package/src/http/index.ts

@@ -0,0 +1,11 @@
+// HTTP types
+export type { CanopyRequest, CanopyResponse } from './types'
+export { jsonResponse } from './types'
+
+// Router
+export type { CanopyHandler, RouteDefinition, RouteMatch, CanopyRouter } from './router'
+export { createCanopyRouter } from './router'
+
+// Core request handler
+export type { CanopyHandlerOptions, CanopyRequestHandler } from './handler'
+export { createCanopyRequestHandler, createCanopyRequestHandlerFromConfig } from './handler'