canopycms 0.0.0

package/src/branch-schema-cache.ts

@@ -0,0 +1,189 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+import type { RootCollectionConfig } from './config'
+import type { FlatSchemaItem } from './config/types'
+import type { EntrySchemaRegistry } from './schema/types'
+import type { OperatingMode } from './operating-mode'
+import { resolveSchema, isValidSchema } from './schema/resolver'
+import { flattenSchema } from './config/flatten'
+
+/** Bump when BranchSchemaCacheEntry shape changes to auto-invalidate stale caches */
+const SCHEMA_CACHE_VERSION = 2
+
+/**
+ * Schema cache structure stored in {branchRoot}/.canopy-meta/schema-cache.json
+ */
+export interface BranchSchemaCacheEntry {
+  version: number
+  schema: RootCollectionConfig
+  flatSchema: FlatSchemaItem[]
+  cachedAt: string // ISO timestamp
+}
+
+/**
+ * Manages per-branch schema caching with lazy loading and automatic invalidation.
+ *
+ * Caching Strategy:
+ * - Prod/Prod-sim: File-based cache at {branchRoot}/.canopy-meta/schema-cache.json
+ * - Dev mode: In-memory singleton (no file I/O)
+ * - Invalidation: Writers create .stale marker, causing cache regeneration on next access
+ *
+ * Multi-User Support:
+ * - User A modifies schema via SchemaOps → writes .stale marker
+ * - User B loads schema later → sees .stale marker → regenerates cache
+ * - Atomic file operations prevent corruption during concurrent access
+ */
+export class BranchSchemaCache {
+  private devModeCache?: {
+    schema: RootCollectionConfig
+    flatSchema: FlatSchemaItem[]
+  }
+
+  constructor(private readonly mode: OperatingMode) {}
+
+  /**
+   * Get schema for a branch (loads from cache or resolves fresh).
+   *
+   * @param branchRoot - Root directory of the branch (e.g., .canopy-prod-sim/content-branches/main)
+   * @param entrySchemaRegistry - Map of schema names to field definitions
+   * @param contentRootName - Name of content directory (e.g., "content") from config
+   * @returns Resolved schema tree and flattened schema
+   */
+  async getSchema(
+    branchRoot: string,
+    entrySchemaRegistry: EntrySchemaRegistry,
+    contentRootName: string = 'content',
+  ): Promise<{ schema: RootCollectionConfig; flatSchema: FlatSchemaItem[] }> {
+    // Dev mode: use in-memory singleton
+    if (this.mode === 'dev') {
+      if (!this.devModeCache) {
+        const contentRoot = path.join(branchRoot, contentRootName)
+        const result = await resolveSchema(contentRoot, entrySchemaRegistry)
+
+        // Validate schema has content
+        if (!isValidSchema(result.schema)) {
+          throw new Error(
+            `No schema found in ${contentRoot}. Create .collection.json files ` +
+              'with references to field schemas defined in your entry schema registry.',
+          )
+        }
+
+        // Use configured contentRoot name as base path for logical paths
+        const flatSchema = flattenSchema(result.schema, contentRootName)
+        this.devModeCache = {
+          schema: result.schema,
+          flatSchema,
+        }
+      }
+      return this.devModeCache
+    }
+
+    // Prod/prod-sim: use file-based cache with stale marker invalidation
+    return this.loadFromCacheOrResolve(branchRoot, entrySchemaRegistry, contentRootName)
+  }
+
+  /**
+   * Load schema from cache or resolve fresh if cache is missing or stale.
+   */
+  private async loadFromCacheOrResolve(
+    branchRoot: string,
+    entrySchemaRegistry: EntrySchemaRegistry,
+    contentRootName: string,
+  ): Promise<{ schema: RootCollectionConfig; flatSchema: FlatSchemaItem[] }> {
+    const contentRoot = path.join(branchRoot, contentRootName)
+    const cacheDir = path.join(branchRoot, '.canopy-meta')
+    const cachePath = path.join(cacheDir, 'schema-cache.json')
+    const stalePath = path.join(cacheDir, 'schema-cache.stale')
+
+    // Check if cache exists and is not marked stale
+    let cacheData: BranchSchemaCacheEntry | null = null
+    try {
+      const staleExists = await fs
+        .access(stalePath)
+        .then(() => true)
+        .catch(() => false)
+      if (!staleExists) {
+        const cacheContent = await fs.readFile(cachePath, 'utf-8')
+        cacheData = JSON.parse(cacheContent) as BranchSchemaCacheEntry
+      }
+    } catch {
+      // Cache doesn't exist or can't be read
+      cacheData = null
+    }
+
+    if (cacheData && cacheData.version === SCHEMA_CACHE_VERSION) {
+      return { schema: cacheData.schema, flatSchema: cacheData.flatSchema }
+    }
+
+    // Cache miss or stale - regenerate
+    const result = await resolveSchema(contentRoot, entrySchemaRegistry)
+
+    // Validate schema has content
+    if (!isValidSchema(result.schema)) {
+      throw new Error(
+        `No schema found in ${contentRoot}. Create .collection.json files ` +
+          'with references to field schemas defined in your entry schema registry.',
+      )
+    }
+
+    // Use configured contentRoot name as base path for logical paths
+    const flatSchema = flattenSchema(result.schema, contentRootName)
+
+    // Save to cache
+    await fs.mkdir(cacheDir, { recursive: true })
+    const newCache: BranchSchemaCacheEntry = {
+      version: SCHEMA_CACHE_VERSION,
+      schema: result.schema,
+      flatSchema,
+      cachedAt: new Date().toISOString(),
+    }
+
+    // Atomic write: write to temp file, then rename
+    const tmpPath = path.join(cacheDir, `schema-cache.tmp.${Date.now()}.${Math.random()}.json`)
+    await fs.writeFile(tmpPath, JSON.stringify(newCache, null, 2), 'utf-8')
+    await fs.rename(tmpPath, cachePath)
+
+    // Remove stale marker if exists
+    try {
+      await fs.unlink(stalePath)
+    } catch {
+      // Stale marker may not exist - that's fine
+    }
+
+    return { schema: result.schema, flatSchema }
+  }
+
+  /**
+   * Invalidate cache for a branch (creates .stale marker).
+   *
+   * @param branchRoot - Root directory of the branch
+   */
+  async invalidate(branchRoot: string): Promise<void> {
+    if (this.mode === 'dev') {
+      // Clear in-memory cache
+      this.devModeCache = undefined
+      return
+    }
+
+    // Prod/prod-sim: create stale marker (empty file)
+    const cacheDir = path.join(branchRoot, '.canopy-meta')
+    const stalePath = path.join(cacheDir, 'schema-cache.stale')
+
+    await fs.mkdir(cacheDir, { recursive: true })
+    await fs.writeFile(stalePath, '', 'utf-8')
+  }
+
+  /**
+   * Clear all caches (for testing).
+   * In dev mode, clears in-memory cache.
+   * In prod/prod-sim modes, this would need to traverse all branch directories.
+   */
+  async clearAll(): Promise<void> {
+    if (this.mode === 'dev') {
+      this.devModeCache = undefined
+    }
+    // For prod/prod-sim, clearing all caches would require knowing all branch roots
+    // For now, just clear dev mode cache. Tests can invalidate specific branches.
+  }
+}

package/src/branch-workspace.test.ts

@@ -0,0 +1,183 @@
+import fs from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+
+import { describe, expect, it } from 'vitest'
+import { simpleGit } from 'simple-git'
+
+import { BranchWorkspaceManager, loadBranchContext } from './branch-workspace'
+import { defineCanopyTestConfig } from './config-test'
+import { BranchRegistry } from './branch-registry'
+import { initBareRepo } from './__integration__/test-utils/test-workspace'
+
+const tmpDir = async () => fs.mkdtemp(path.join(os.tmpdir(), 'canopycms-branchws-'))
+
+describe('BranchWorkspaceManager', () => {
+  it('dev mode does not support branching', async () => {
+    const root = await tmpDir()
+    const git = simpleGit({ baseDir: root })
+    await git.init()
+    const manager = new BranchWorkspaceManager(
+      defineCanopyTestConfig({
+        schema: {
+          collections: [
+            {
+              name: 'posts',
+              path: 'posts',
+              entries: [
+                {
+                  name: 'post',
+                  format: 'md',
+                  schema: [{ name: 'title', type: 'string' }],
+                },
+              ],
+            },
+          ],
+        },
+      }),
+    )
+
+    // Dev mode should throw when trying to use branching functions
+    await expect(
+      manager.openOrCreateBranch({
+        branchName: 'feature/foo',
+        mode: 'dev',
+        basePathOverride: root,
+        createdBy: 'user-1',
+        title: 'Foo Feature',
+      }),
+    ).rejects.toThrow('No branching in dev mode')
+  })
+
+  it('creates metadata and registry entry when opening a branch in multi-branch mode', async () => {
+    const root = await tmpDir()
+    const remotePath = path.join(root, 'remote.git')
+    const seedPath = path.join(root, 'seed')
+
+    // Set up a bare remote repo
+    await initBareRepo(remotePath)
+    await fs.mkdir(seedPath, { recursive: true })
+    const seedGit = simpleGit({ baseDir: seedPath })
+    await seedGit.init()
+    await seedGit.raw(['branch', '-M', 'main'])
+    await fs.writeFile(path.join(seedPath, 'README.md'), '# seed\n', 'utf8')
+    await seedGit.add(['.'])
+    await seedGit.commit('init')
+    await seedGit.addRemote('origin', remotePath)
+    await seedGit.push('origin', 'main', { '--set-upstream': null })
+
+    const manager = new BranchWorkspaceManager(
+      defineCanopyTestConfig({
+        defaultBaseBranch: 'main',
+        defaultRemoteUrl: remotePath,
+        schema: {
+          collections: [
+            {
+              name: 'posts',
+              path: 'posts',
+              entries: [
+                {
+                  name: 'post',
+                  format: 'md',
+                  schema: [{ name: 'title', type: 'string' }],
+                },
+              ],
+            },
+          ],
+        },
+      }),
+    )
+
+    const workspace = await manager.openOrCreateBranch({
+      branchName: 'feature/foo',
+      mode: 'prod-sim',
+      basePathOverride: root,
+      createdBy: 'user-1',
+      title: 'Foo Feature',
+    })
+
+    // In prod-sim, strategy creates .canopy-prod-sim/content-branches structure
+    const expectedBranchesRoot = path.join(root, '.canopy-prod-sim', 'content-branches')
+
+    // Note: Still using .canopycms for now - Phase 2 will migrate to .canopy-meta
+    const metaFile = path.join(workspace.branchRoot, '.canopy-meta/branch.json')
+    const meta = JSON.parse(await fs.readFile(metaFile, 'utf8'))
+    expect(meta.branch.name).toBe('feature-foo')
+    expect(meta.branch.title).toBe('Foo Feature')
+    expect(workspace.branchRoot).toBeDefined()
+    expect(workspace.baseRoot).toBe(expectedBranchesRoot)
+
+    // In multi-branch mode, registry can scan subdirectories and find the branch
+    const registry = new BranchRegistry(expectedBranchesRoot)
+    const entry = await registry.get('feature-foo')
+    expect(entry?.branch.name).toBe('feature-foo')
+  })
+
+  it('clones a remote and checks out the branch when remoteUrl is provided', async () => {
+    const root = await tmpDir()
+    const remotePath = path.join(root, 'remote.git')
+    const seedPath = path.join(root, 'seed')
+    await initBareRepo(remotePath)
+
+    await fs.mkdir(seedPath, { recursive: true })
+    const seedGit = simpleGit({ baseDir: seedPath })
+    await seedGit.init()
+    await seedGit.raw(['branch', '-M', 'main'])
+    await fs.writeFile(path.join(seedPath, 'README.md'), '# seed\n', 'utf8')
+    await seedGit.add(['.'])
+    await seedGit.commit('init')
+    await seedGit.addRemote('origin', remotePath)
+    await seedGit.push('origin', 'main', { '--set-upstream': null })
+
+    const branchesRoot = path.join(root, 'branches')
+    const manager = new BranchWorkspaceManager(
+      defineCanopyTestConfig({
+        defaultBaseBranch: 'main',
+        defaultRemoteUrl: remotePath,
+        schema: {
+          collections: [
+            {
+              name: 'posts',
+              path: 'posts',
+              entries: [
+                {
+                  name: 'post',
+                  format: 'md',
+                  schema: [{ name: 'title', type: 'string' }],
+                },
+              ],
+            },
+          ],
+        },
+      }),
+    )
+
+    const workspace = await manager.openOrCreateBranch({
+      branchName: 'feature/foo',
+      mode: 'prod-sim',
+      basePathOverride: branchesRoot,
+      createdBy: 'user-1',
+    })
+
+    const git = simpleGit({ baseDir: workspace.branchRoot })
+    const status = await git.status()
+    expect(status.current).toBe('feature-foo')
+    const remotes = await git.getRemotes(true)
+    expect(remotes.find((r) => r.name === 'origin')?.refs.fetch).toBe(remotePath)
+  })
+
+  it('dev mode throws when trying to load branch state', async () => {
+    const root = await tmpDir()
+    const git = simpleGit({ baseDir: root })
+    await git.init()
+
+    // Dev mode doesn't support branching, so loadBranchContext should throw
+    await expect(
+      loadBranchContext({
+        branchName: 'main',
+        mode: 'dev',
+        basePathOverride: root,
+      }),
+    ).rejects.toThrow('No branching in dev mode')
+  })
+})

package/src/branch-workspace.ts

@@ -0,0 +1,124 @@
+import type { CanopyConfig } from './config'
+import { ensureBranchRoot } from './paths'
+import { getBranchMetadataFileManager } from './branch-metadata'
+import type { BranchAccessControl, BranchContext, CanopyUserId } from './types'
+import type { OperatingMode } from './operating-mode'
+import { GitManager } from './git-manager'
+import { createDebugLogger } from './utils/debug'
+
+const log = createDebugLogger({ prefix: 'BranchWorkspace' })
+
+// In-memory lock to prevent concurrent workspace initialization
+const workspaceInitLocks = new Map<string, Promise<void>>()
+
+export interface OpenBranchOptions {
+  branchName: string
+  mode: OperatingMode
+  basePathOverride?: string
+  title?: string
+  description?: string
+  access?: BranchAccessControl
+  createdBy: CanopyUserId
+  remoteUrl?: string
+}
+
+/**
+ * Manages per-branch filesystem workspace: resolves root, ensures metadata,
+ * and updates the branch registry.
+ */
+export class BranchWorkspaceManager {
+  private readonly config: CanopyConfig
+
+  constructor(config: CanopyConfig) {
+    this.config = config
+  }
+
+  private async ensureGitWorkspace(options: {
+    branchRoot: string
+    branchName: string
+    mode: OperatingMode
+    remoteUrl?: string
+  }) {
+    return log.timed('workspace', 'ensureGitWorkspace', async () => {
+      // Serialize access per branch workspace to prevent race conditions
+      const existingLock = workspaceInitLocks.get(options.branchRoot)
+      if (existingLock) {
+        await existingLock
+        return
+      }
+
+      // Create new lock promise
+      const lockPromise = (async () => {
+        try {
+          log.debug('workspace', 'Ensuring git workspace', {
+            branchName: options.branchName,
+            mode: options.mode,
+          })
+
+          // Delegate git initialization to GitManager
+          await GitManager.initializeWorkspace({
+            workspacePath: options.branchRoot,
+            branchName: options.branchName,
+            mode: options.mode,
+            baseBranch: this.config.defaultBaseBranch,
+            sourceRoot: this.config.sourceRoot,
+            defaultRemoteUrl: this.config.defaultRemoteUrl,
+            remoteUrl: options.remoteUrl,
+            remoteName: this.config.defaultRemoteName,
+            branchType: 'content',
+          })
+        } finally {
+          // Always clean up the lock when done (success or failure)
+          workspaceInitLocks.delete(options.branchRoot)
+        }
+      })()
+
+      // Store the lock promise
+      workspaceInitLocks.set(options.branchRoot, lockPromise)
+
+      // Wait for initialization to complete
+      await lockPromise
+    })
+  }
+
+  async openOrCreateBranch(options: OpenBranchOptions): Promise<BranchContext> {
+    const { branchName, mode, basePathOverride, title, description, access, createdBy, remoteUrl } =
+      options
+    const {
+      branchRoot,
+      baseRoot,
+      branchName: safeName,
+    } = await ensureBranchRoot({
+      mode,
+      branchName,
+      basePathOverride,
+    })
+
+    await this.ensureGitWorkspace({
+      branchRoot,
+      branchName: safeName,
+      mode,
+      remoteUrl,
+    })
+
+    // save() handles both creation and updates, preserving existing values and invalidating registry
+    const metadata = getBranchMetadataFileManager(branchRoot, baseRoot)
+    const meta = await metadata.save({
+      branch: {
+        name: safeName,
+        title,
+        description,
+        access,
+        createdBy,
+      },
+    })
+
+    return {
+      branch: meta.branch,
+      branchRoot,
+      baseRoot,
+    }
+  }
+}
+
+export { loadBranchContext } from './branch-metadata'

package/src/build/generate-ai-content.ts

@@ -0,0 +1,78 @@
+/**
+ * Static build utility for AI content generation.
+ *
+ * Writes generated AI content to disk as static files.
+ * Used during `npm run build` or via the CLI.
+ */
+
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+import { ContentStore } from '../content-store'
+import { BranchSchemaCache } from '../branch-schema-cache'
+import type { CanopyConfig, FlatSchemaItem } from '../config'
+import type { EntrySchemaRegistry } from '../schema/types'
+import { generateAIContent } from '../ai/generate'
+import { resolveBranchRoot } from '../ai/resolve-branch'
+import type { AIContentConfig } from '../ai/types'
+
+export interface GenerateAIContentFilesOptions {
+  config: CanopyConfig
+  entrySchemaRegistry: EntrySchemaRegistry
+  /** Output directory (e.g., 'public/ai') */
+  outputDir: string
+  aiConfig?: AIContentConfig
+  /** @internal Test-only: pre-resolved schema to bypass BranchSchemaCache */
+  _testFlatSchema?: FlatSchemaItem[]
+}
+
+/**
+ * Generate AI content files and write them to disk.
+ *
+ * @returns Count of files written and the output directory.
+ */
+export async function generateAIContentFiles(
+  options: GenerateAIContentFilesOptions,
+): Promise<{ fileCount: number; outputDir: string }> {
+  const { config, entrySchemaRegistry, outputDir, aiConfig, _testFlatSchema } = options
+  const contentRootName = config.contentRoot || 'content'
+
+  // Resolve branch root
+  const branchRoot = await resolveBranchRoot(config)
+
+  // Load schema
+  let flatSchema: FlatSchemaItem[]
+  if (_testFlatSchema) {
+    flatSchema = _testFlatSchema
+  } else {
+    const schemaCache = new BranchSchemaCache(config.mode)
+    const cached = await schemaCache.getSchema(branchRoot, entrySchemaRegistry, contentRootName)
+    flatSchema = cached.flatSchema
+  }
+
+  // Create store and generate
+  const store = new ContentStore(branchRoot, flatSchema)
+  const result = await generateAIContent({
+    store,
+    flatSchema,
+    contentRoot: contentRootName,
+    config: aiConfig,
+  })
+
+  // Write files to disk
+  const absoluteOutputDir = path.resolve(outputDir) + path.sep
+  let fileCount = 0
+
+  for (const [filePath, content] of result.files) {
+    const absolutePath = path.resolve(path.join(absoluteOutputDir, filePath))
+    // Security: prevent path traversal in output (e.g., malicious bundle names)
+    if (!absolutePath.startsWith(absoluteOutputDir)) {
+      throw new Error(`Path traversal detected in AI content output: ${filePath}`)
+    }
+    await fs.mkdir(path.dirname(absolutePath), { recursive: true })
+    await fs.writeFile(absolutePath, content, 'utf-8')
+    fileCount++
+  }
+
+  return { fileCount, outputDir: absoluteOutputDir }
+}

package/src/build/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Public exports for canopycms/build entrypoint.
+ *
+ * Provides static build utilities for pre-generating content.
+ */
+
+export { generateAIContentFiles } from './generate-ai-content'
+export type { GenerateAIContentFilesOptions } from './generate-ai-content'

package/src/build-mode.ts

@@ -0,0 +1,27 @@
+import type { AuthenticatedUser } from './user'
+
+/**
+ * Detect if running in static build mode.
+ * Framework-agnostic - checks common build environment variables.
+ */
+export const isBuildMode = (): boolean => {
+  // Next.js build phase
+  if (process.env.NEXT_PHASE === 'phase-production-build') return true
+
+  // Generic build mode flag (can be set by any framework)
+  if (process.env.CANOPY_BUILD_MODE === 'true') return true
+
+  return false
+}
+
+/**
+ * Special user for build-time content access.
+ * Has Admin privileges to bypass all permission checks during static generation.
+ */
+export const BUILD_USER: AuthenticatedUser = Object.freeze({
+  type: 'authenticated',
+  userId: '__build__',
+  groups: ['Admins'],
+  email: 'build@canopycms',
+  name: 'Build Process',
+}) as AuthenticatedUser