canopycms 0.0.0 → 0.0.2

package/src/branch-schema-cache.ts

@@ -1,189 +0,0 @@
-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

@@ -1,183 +0,0 @@
-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

@@ -1,124 +0,0 @@
-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

@@ -1,78 +0,0 @@
-/**
- * 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

@@ -1,8 +0,0 @@
-/**
- * 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

@@ -1,27 +0,0 @@
-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