canopycms 0.0.0

package/src/test-utils/api-test-helpers.ts

@@ -0,0 +1,445 @@
+import { vi } from 'vitest'
+import type { ApiContext } from '../api/types'
+import type { BranchContext, BranchStatus, BranchAccessControl } from '../types'
+import type { CanopyServices } from '../services'
+import type { CanopyUser } from '../user'
+import type { CanopyConfig, PathPermission } from '../config'
+import { RESERVED_GROUPS } from '../authorization'
+
+/**
+ * Options for creating a mock BranchContext
+ */
+export interface MockBranchContextOptions {
+  branchName?: string
+  status?: BranchStatus
+  createdBy?: string
+  access?: BranchAccessControl
+  baseRoot?: string
+  branchRoot?: string
+  pullRequestNumber?: number
+  pullRequestUrl?: string
+  title?: string
+  description?: string
+  createdAt?: string
+  updatedAt?: string
+}
+
+/**
+ * Create a mock BranchContext with sensible defaults.
+ *
+ * @param options - Override any default values
+ * @returns A complete BranchContext object for testing
+ *
+ * @example
+ * // Default: main branch in editing status
+ * const ctx = createMockBranchContext()
+ *
+ * @example
+ * // Custom branch with PR info
+ * const ctx = createMockBranchContext({
+ *   branchName: 'feature/test',
+ *   status: 'submitted',
+ *   pullRequestNumber: 123
+ * })
+ */
+export function createMockBranchContext(options: MockBranchContextOptions = {}): BranchContext {
+  const branchName = options.branchName ?? 'main'
+  const baseRoot = options.baseRoot ?? '/tmp/base'
+  const branchRoot =
+    options.branchRoot ?? (branchName === 'main' ? baseRoot : `${baseRoot}/${branchName}`)
+
+  return {
+    baseRoot,
+    branchRoot,
+    branch: {
+      name: branchName,
+      status: options.status ?? 'editing',
+      access: options.access ?? {},
+      createdBy: options.createdBy ?? 'u1',
+      createdAt: options.createdAt ?? 'now',
+      updatedAt: options.updatedAt ?? 'now',
+      ...(options.title && { title: options.title }),
+      ...(options.description && { description: options.description }),
+      ...(options.pullRequestNumber && {
+        pullRequestNumber: options.pullRequestNumber,
+      }),
+      ...(options.pullRequestUrl && { pullRequestUrl: options.pullRequestUrl }),
+    },
+  }
+}
+
+/**
+ * Options for creating a mock user
+ */
+export interface MockUserOptions {
+  userId?: string
+  groups?: string[]
+}
+
+/**
+ * Create a mock CanopyUser with common role presets.
+ *
+ * @param role - User role preset: 'admin', 'reviewer', or 'user'
+ * @param options - Override userId or groups
+ * @returns A CanopyUser object for testing
+ *
+ * @example
+ * const admin = createMockUser('admin')
+ * const reviewer = createMockUser('reviewer')
+ * const user = createMockUser() // default is regular user
+ * const custom = createMockUser('user', { userId: 'custom-user', groups: ['editors'] })
+ */
+export function createMockUser(
+  role: 'admin' | 'reviewer' | 'user' = 'user',
+  options: MockUserOptions = {},
+): CanopyUser {
+  const defaults = {
+    admin: { userId: 'admin', groups: [RESERVED_GROUPS.ADMINS] },
+    reviewer: { userId: 'reviewer', groups: [RESERVED_GROUPS.REVIEWERS] },
+    user: { userId: 'u1', groups: [] },
+  }
+
+  const preset = defaults[role]
+
+  return {
+    type: 'authenticated',
+    userId: options.userId ?? preset.userId,
+    groups: options.groups ?? preset.groups,
+  }
+}
+
+/**
+ * Create a mock GitManager with all required methods.
+ *
+ * @returns A mock GitManager object with vi.fn() for all methods
+ *
+ * @example
+ * const gitManager = createMockGitManager()
+ * gitManager.status.mockResolvedValue({ files: [], ahead: 0, behind: 0, current: 'main' })
+ */
+export function createMockGitManager() {
+  return {
+    checkoutBranch: vi.fn().mockResolvedValue(undefined),
+    status: vi.fn().mockResolvedValue({
+      files: [],
+      ahead: 0,
+      behind: 0,
+      current: 'main',
+    }),
+    add: vi.fn().mockResolvedValue(undefined),
+    commit: vi.fn().mockResolvedValue(undefined),
+    push: vi.fn().mockResolvedValue(undefined),
+    ensureAuthor: vi.fn().mockResolvedValue(undefined),
+  }
+}
+
+/**
+ * Options for creating mock CanopyServices
+ */
+export interface MockServicesOptions {
+  config?: Partial<CanopyConfig>
+  entrySchemaRegistry?: any
+  branchSchemaCache?: any
+  checkBranchAccess?: any
+  checkPathAccess?: any
+  checkContentAccess?: any
+  createGitManagerFor?: any
+  registry?: any
+  githubService?: any
+  bootstrapAdminIds?: Set<string>
+  commitFiles?: any
+  submitBranch?: any
+  commitToSettingsBranch?: any
+  getSettingsBranchRoot?: any
+}
+
+/**
+ * Create mock CanopyServices with sensible defaults.
+ *
+ * @param options - Override any service properties
+ * @returns A complete CanopyServices object for testing
+ *
+ * @example
+ * const services = createMockServices({
+ *   config: { mode: 'prod-sim' }
+ * })
+ */
+export function createMockServices(options: MockServicesOptions = {}): CanopyServices {
+  const defaultConfig: Partial<CanopyConfig> = {
+    defaultBaseBranch: 'main',
+    mode: 'dev',
+    ...options.config,
+  }
+
+  return {
+    config: defaultConfig as any,
+    entrySchemaRegistry: options.entrySchemaRegistry ?? {},
+    branchSchemaCache:
+      options.branchSchemaCache ??
+      ({
+        getSchema: vi.fn().mockResolvedValue({
+          schema: {},
+          flatSchema: [],
+        }),
+        invalidate: vi.fn().mockResolvedValue(undefined),
+        clearAll: vi.fn().mockResolvedValue(undefined),
+      } as any),
+    checkBranchAccess:
+      options.checkBranchAccess ?? vi.fn().mockReturnValue({ allowed: true, reason: 'allowed' }),
+    checkPathAccess: options.checkPathAccess ?? (undefined as any),
+    checkContentAccess:
+      options.checkContentAccess ??
+      vi.fn().mockResolvedValue({ allowed: true, branch: {}, path: {} }),
+    createGitManagerFor: options.createGitManagerFor ?? vi.fn(() => createMockGitManager()),
+    registry: options.registry ?? (undefined as any),
+    githubService: options.githubService,
+    bootstrapAdminIds: options.bootstrapAdminIds ?? new Set<string>(),
+    commitFiles: options.commitFiles ?? vi.fn().mockResolvedValue(undefined),
+    submitBranch: options.submitBranch ?? vi.fn().mockResolvedValue(undefined),
+    commitToSettingsBranch:
+      options.commitToSettingsBranch ??
+      vi.fn().mockResolvedValue({ committed: true, pushed: true }),
+    getSettingsBranchRoot:
+      options.getSettingsBranchRoot ?? vi.fn().mockResolvedValue('/mock/settings'),
+  }
+}
+
+/**
+ * Options for creating mock ApiContext
+ */
+export interface MockApiContextOptions {
+  services?: Partial<CanopyServices>
+  getBranchContext?: any
+  assetStore?: any
+  authPlugin?: any
+  // Convenience options
+  branchContext?: BranchContext | null
+  allowBranchAccess?: boolean
+  allowContentAccess?: boolean
+}
+
+/**
+ * Create a mock ApiContext with sensible defaults.
+ *
+ * @param options - Override any context properties
+ * @returns A complete ApiContext object for testing
+ *
+ * @example
+ * // Simple context with default main branch
+ * const ctx = createMockApiContext()
+ *
+ * @example
+ * // Context with custom branch and access control
+ * const ctx = createMockApiContext({
+ *   branchContext: createMockBranchContext({ branchName: 'feature/test' }),
+ *   allowBranchAccess: false
+ * })
+ *
+ * @example
+ * // Context with branch not found
+ * const ctx = createMockApiContext({ branchContext: null })
+ */
+export function createMockApiContext(options: MockApiContextOptions = {}): ApiContext {
+  // Handle convenience options for access control
+  const servicesOptions: MockServicesOptions = {}
+
+  if (options.allowBranchAccess !== undefined) {
+    servicesOptions.checkBranchAccess = vi.fn().mockReturnValue({
+      allowed: options.allowBranchAccess,
+      reason: options.allowBranchAccess ? 'allowed' : 'denied',
+    })
+  }
+
+  if (options.allowContentAccess !== undefined) {
+    servicesOptions.checkContentAccess = vi.fn().mockResolvedValue({
+      allowed: options.allowContentAccess,
+      branch: {},
+      path: {},
+    })
+  }
+
+  // Merge with user-provided services
+  const services = createMockServices({
+    ...servicesOptions,
+    ...options.services,
+  })
+
+  // Handle branchContext convenience option
+  let getBranchContext = options.getBranchContext
+  if (options.branchContext !== undefined && !options.getBranchContext) {
+    getBranchContext = vi.fn().mockResolvedValue(options.branchContext)
+  }
+
+  return {
+    services,
+    getBranchContext: getBranchContext ?? vi.fn().mockResolvedValue(createMockBranchContext()),
+    ...(options.assetStore && { assetStore: options.assetStore }),
+    ...(options.authPlugin && { authPlugin: options.authPlugin }),
+  }
+}
+
+/**
+ * Create a mock BranchRegistry with default branches.
+ *
+ * @param branches - Optional array of branch contexts to include
+ * @returns A mock registry with list, get, and invalidate methods
+ *
+ * @example
+ * const registry = createMockRegistry()
+ *
+ * @example
+ * const registry = createMockRegistry([
+ *   createMockBranchContext({ branchName: 'feature/a', createdBy: 'u1' }),
+ *   createMockBranchContext({ branchName: 'feature/b', createdBy: 'u2' })
+ * ])
+ */
+export function createMockRegistry(branches?: BranchContext[]) {
+  const defaultBranches = branches ?? [
+    createMockBranchContext({ branchName: 'feature/a', createdBy: 'u1' }),
+    createMockBranchContext({ branchName: 'feature/b', createdBy: 'u2' }),
+    createMockBranchContext({
+      branchName: 'feature/c',
+      createdBy: 'u3',
+      access: { allowedUsers: ['u1'] },
+    }),
+    createMockBranchContext({
+      branchName: 'feature/d',
+      createdBy: 'u3',
+      access: { allowedGroups: ['editors'] },
+    }),
+  ]
+
+  return {
+    list: vi.fn().mockResolvedValue(defaultBranches),
+    get: vi.fn().mockResolvedValue(undefined),
+    invalidate: vi.fn().mockResolvedValue(undefined),
+  }
+}
+
+/**
+ * Create a mock GitHub service.
+ *
+ * @returns A mock GitHub service with common methods
+ *
+ * @example
+ * const githubService = createMockGitHubService()
+ * githubService.convertToDraft.mockResolvedValue(undefined)
+ */
+export function createMockGitHubService() {
+  return {
+    convertToDraft: vi.fn().mockResolvedValue(undefined),
+    markReadyForReview: vi.fn().mockResolvedValue(undefined),
+    closePullRequest: vi.fn().mockResolvedValue(undefined),
+  }
+}
+
+/**
+ * Create a mock BranchMetadataFileManager for use with vi.mock().
+ *
+ * @param saveImpl - Optional custom implementation for save method
+ * @returns Mock implementation object
+ *
+ * @example
+ * vi.mock('../branch-metadata', () => createMockBranchMetadata())
+ *
+ * @example
+ * const mockSave = vi.fn().mockResolvedValue({ branch: { status: 'submitted' } })
+ * vi.mock('../branch-metadata', () => createMockBranchMetadata(mockSave))
+ */
+export function createMockBranchMetadata(saveImpl?: any) {
+  const defaultSave = vi.fn().mockResolvedValue({
+    schemaVersion: 1,
+    branch: {
+      name: 'feature/x',
+      status: 'editing',
+      access: {},
+      createdBy: 'u1',
+      createdAt: 'now',
+      updatedAt: 'now',
+    },
+  })
+
+  const save = saveImpl ?? defaultSave
+
+  return {
+    BranchMetadataFileManager: vi.fn().mockImplementation(() => ({
+      save,
+    })),
+    getBranchMetadataFileManager: vi.fn().mockImplementation(() => ({
+      save,
+    })),
+  }
+}
+
+/**
+ * Create mock permissions loader for use with vi.mock().
+ *
+ * @param permissions - Default permissions to return
+ * @returns Mock implementation object
+ *
+ * @example
+ * vi.mock('../permissions-loader', () => createMockPermissionsLoader())
+ *
+ * @example
+ * vi.mock('../permissions-loader', () =>
+ *   createMockPermissionsLoader([{ path: 'content/**', edit: { allowedUsers: ['u1'] } }])
+ * )
+ */
+export function createMockPermissionsLoader(permissions: PathPermission[] = []) {
+  return {
+    loadPathPermissions: vi.fn().mockResolvedValue(permissions),
+    loadPermissionsFile: vi.fn().mockResolvedValue(null),
+    savePathPermissions: vi.fn().mockResolvedValue(undefined),
+  }
+}
+
+/**
+ * Create mock BranchWorkspaceManager for use with vi.mock().
+ *
+ * @param branchContext - Optional branch context to return from openOrCreateBranch
+ * @returns Mock implementation object
+ *
+ * @example
+ * vi.mock('../branch-workspace', () => createMockBranchWorkspace())
+ */
+export function createMockBranchWorkspace(branchContext?: BranchContext) {
+  const defaultContext =
+    branchContext ??
+    createMockBranchContext({
+      branchName: 'feature/test',
+    })
+
+  return {
+    BranchWorkspaceManager: vi.fn().mockImplementation(() => ({
+      openOrCreateBranch: vi.fn().mockResolvedValue(defaultContext),
+    })),
+  }
+}
+
+/**
+ * Create mock CommentStore for use with vi.mock().
+ *
+ * @returns Mock implementation object
+ *
+ * @example
+ * vi.mock('../comment-store', () => createMockCommentStore())
+ */
+export function createMockCommentStore() {
+  return {
+    CommentStore: vi.fn().mockImplementation(() => ({
+      listThreads: vi.fn().mockResolvedValue([]),
+      addComment: vi.fn().mockResolvedValue({ threadId: 'thread1', commentId: 'c1' }),
+      getThread: vi.fn().mockResolvedValue({
+        id: 'thread1',
+        comments: [],
+        resolved: false,
+        type: 'field',
+        entryPath: 'posts/hello',
+        canopyPath: 'title',
+        authorId: 'u1',
+        createdAt: 'now',
+      }),
+      resolveThread: vi.fn().mockResolvedValue(true),
+    })),
+  }
+}

package/src/test-utils/console-spy.test.ts

@@ -0,0 +1,14 @@
+import { describe, it, expect } from 'vitest'
+import { mockConsole } from './console-spy.js'
+
+describe('mockConsole', () => {
+  it('captures console.warn', () => {
+    const consoleSpy = mockConsole()
+    console.warn('test warning message')
+    console.error('test error message')
+    console.log('All captured:', JSON.stringify(consoleSpy.all()))
+    expect(consoleSpy).toHaveWarned('test warning')
+    expect(consoleSpy).toHaveErrored('test error')
+    consoleSpy.restore()
+  })
+})

package/src/test-utils/console-spy.ts

@@ -0,0 +1,125 @@
+import { vi, expect } from 'vitest'
+
+type ConsoleMethod = 'log' | 'warn' | 'error' | 'info' | 'debug'
+
+interface CapturedMessages {
+  log: string[]
+  warn: string[]
+  error: string[]
+  info: string[]
+  debug: string[]
+}
+
+export interface MockConsole {
+  /** Restore all original console methods */
+  restore: () => void
+  /** Get all captured messages by method */
+  all: () => CapturedMessages
+}
+
+/**
+ * Mocks all console methods, capturing messages for assertion.
+ * All console output is swallowed (not printed to terminal).
+ * Use the custom matchers to assert on captured messages.
+ *
+ * @example
+ * ```ts
+ * const consoleSpy = mockConsole()
+ * doSomething()
+ * expect(consoleSpy).toHaveWarned('deprecated')
+ * expect(consoleSpy).toHaveErrored(/token not found/)
+ * consoleSpy.restore()
+ * ```
+ */
+export function mockConsole(): MockConsole {
+  const captured: CapturedMessages = {
+    log: [],
+    warn: [],
+    error: [],
+    info: [],
+    debug: [],
+  }
+
+  const spies: any[] = []
+
+  const methods: ConsoleMethod[] = ['log', 'warn', 'error', 'info', 'debug']
+
+  for (const method of methods) {
+    const spy = vi.spyOn(console, method).mockImplementation((...args: unknown[]) => {
+      const message = args.map((arg) => (typeof arg === 'string' ? arg : String(arg))).join(' ')
+      captured[method].push(message)
+      // Swallow all output - don't print anything
+    })
+    spies.push(spy)
+  }
+
+  return {
+    restore: () => spies.forEach((spy) => spy.mockRestore()),
+    all: () => ({ ...captured }),
+  }
+}
+
+// Custom matchers for cleaner assertions
+declare module 'vitest' {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  interface Assertion<T> {
+    toHaveLogged(expected: string | RegExp): void
+    toHaveWarned(expected: string | RegExp): void
+    toHaveErrored(expected: string | RegExp): void
+  }
+  interface AsymmetricMatchersContaining {
+    toHaveLogged(expected: string | RegExp): void
+    toHaveWarned(expected: string | RegExp): void
+    toHaveErrored(expected: string | RegExp): void
+  }
+}
+
+function matchesPattern(messages: string[], pattern: string | RegExp): boolean {
+  return messages.some((msg) =>
+    typeof pattern === 'string' ? msg.includes(pattern) : pattern.test(msg),
+  )
+}
+
+function formatMessages(label: string, messages: string[]): string {
+  if (messages.length === 0) return ''
+  return `${label}:\n${messages.map((m) => `  - "${m}"`).join('\n')}`
+}
+
+export const consoleMatchers = {
+  toHaveLogged(received: MockConsole, expected: string | RegExp) {
+    const all = received.all()
+    const pass = matchesPattern(all.log, expected)
+    return {
+      pass,
+      message: () =>
+        pass
+          ? `Expected console.log NOT to have logged matching ${expected}`
+          : `Expected console.log to have logged matching ${expected}\n\n${formatMessages('Received', all.log) || '  (no messages)'}`,
+    }
+  },
+  toHaveWarned(received: MockConsole, expected: string | RegExp) {
+    const all = received.all()
+    const pass = matchesPattern(all.warn, expected)
+    return {
+      pass,
+      message: () =>
+        pass
+          ? `Expected console.warn NOT to have warned matching ${expected}`
+          : `Expected console.warn to have warned matching ${expected}\n\n${formatMessages('Received', all.warn) || '  (no messages)'}`,
+    }
+  },
+  toHaveErrored(received: MockConsole, expected: string | RegExp) {
+    const all = received.all()
+    const pass = matchesPattern(all.error, expected)
+    return {
+      pass,
+      message: () =>
+        pass
+          ? `Expected console.error NOT to have errored matching ${expected}`
+          : `Expected console.error to have errored matching ${expected}\n\n${formatMessages('Received', all.error) || '  (no messages)'}`,
+    }
+  },
+}
+
+// Auto-register matchers when this module is imported
+expect.extend(consoleMatchers)

package/src/test-utils/git-helpers.ts

@@ -0,0 +1,31 @@
+import { simpleGit, type SimpleGit } from 'simple-git'
+
+/**
+ * Initialize a test git repository with CanopyCMS marker and user config.
+ * This ensures the repo can be used with GitManager.ensureAuthor().
+ *
+ * @param baseDir - Directory to initialize git repo in
+ * @param options - Optional configuration
+ * @returns SimpleGit instance for the initialized repo
+ *
+ * @example
+ * const git = await initTestRepo(tmpDir)
+ * await git.add(['.'])
+ * await git.commit('Initial commit')
+ */
+export async function initTestRepo(
+  baseDir: string,
+  options?: {
+    /** Git user name (default: 'Test Bot') */
+    userName?: string
+    /** Git user email (default: 'test@canopycms.test') */
+    userEmail?: string
+  },
+): Promise<SimpleGit> {
+  const git = simpleGit({ baseDir })
+  await git.init()
+  await git.addConfig('canopycms.managed', 'true')
+  await git.addConfig('user.name', options?.userName ?? 'Test Bot')
+  await git.addConfig('user.email', options?.userEmail ?? 'test@canopycms.test')
+  return git
+}

package/src/test-utils/index.ts

@@ -0,0 +1,4 @@
+export * from './api-test-helpers'
+export { mockConsole, consoleMatchers } from './console-spy.js'
+export type { MockConsole } from './console-spy.js'
+export { initTestRepo } from './git-helpers'

package/src/types.ts

@@ -0,0 +1,54 @@
+import type { ContentId } from './paths/types'
+
+export type CanopyUserId = string
+export type CanopyGroupId = string
+
+export type BranchStatus = 'editing' | 'submitted' | 'approved' | 'locked' | 'archived'
+export type SyncStatus = 'synced' | 'pending-sync' | 'sync-failed'
+export type ConflictStatus = 'clean' | 'conflicts-detected'
+
+export interface BranchAccessControl {
+  allowedUsers?: CanopyUserId[]
+  allowedGroups?: CanopyGroupId[]
+  managerOrAdminAllowed?: boolean
+  adminOnly?: boolean
+}
+
+export interface BranchMetadata {
+  name: string
+  title?: string
+  description?: string
+  status: BranchStatus
+  access: BranchAccessControl
+  createdBy: CanopyUserId
+  createdAt: string
+  updatedAt: string
+  pullRequestUrl?: string
+  pullRequestNumber?: number
+  /** Sync status for async GitHub operations (used when Lambda has no internet) */
+  syncStatus?: SyncStatus
+  /** Whether this branch has unresolved merge conflicts with the base branch */
+  conflictStatus?: ConflictStatus
+  /** ContentIds of entries where --theirs was applied during rebase; cleared on clean rebase */
+  conflictFiles?: ContentId[]
+}
+
+export interface BranchPaths {
+  /** Root where all branches live (e.g., /mnt/efs/site, ~/.canopycms/branches) */
+  baseRoot: string
+
+  /** This branch's directory. Usually {baseRoot}/{branchName}, equals baseRoot in dev mode */
+  branchRoot: string
+}
+
+export interface BranchContext extends BranchPaths {
+  branch: BranchMetadata
+
+  /** Per-branch flattened schema (lazy-loaded via getBranchContext with loadSchema: true) */
+  flatSchema?: import('./config').FlatSchemaItem[]
+}
+
+/** BranchContext with guaranteed flatSchema (loaded via schema guard or loadSchema: true) */
+export interface BranchContextWithSchema extends BranchContext {
+  flatSchema: import('./config').FlatSchemaItem[]
+}