canopycms 0.0.0

package/src/branch-registry.test.ts

@@ -0,0 +1,248 @@
+import fs from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+
+import { describe, expect, it } from 'vitest'
+
+import { BranchRegistry } from './branch-registry'
+import { getBranchMetadataFileManager } from './branch-metadata'
+
+const tmpDir = async () => fs.mkdtemp(path.join(os.tmpdir(), 'canopycms-registry-'))
+
+/**
+ * Create a branch directory with a valid branch.json metadata file
+ */
+const createBranchWithMetadata = async (
+  root: string,
+  branchName: string,
+  status: 'editing' | 'submitted' = 'editing',
+) => {
+  const branchDir = path.join(root, branchName)
+  const metaDir = path.join(branchDir, '.canopy-meta')
+  await fs.mkdir(metaDir, { recursive: true })
+
+  const metadata = getBranchMetadataFileManager(branchDir, root)
+  await metadata.save({
+    branch: {
+      name: branchName,
+      status,
+      createdBy: 'user-1',
+    },
+  })
+}
+
+describe('BranchRegistry', () => {
+  describe('list()', () => {
+    it('returns empty array when no branches exist', async () => {
+      const root = await tmpDir()
+      const registry = new BranchRegistry(root)
+
+      const branches = await registry.list()
+      expect(branches).toEqual([])
+    })
+
+    it('scans branch directories and returns branches', async () => {
+      const root = await tmpDir()
+      await createBranchWithMetadata(root, 'feature-a')
+      await createBranchWithMetadata(root, 'feature-b')
+
+      const registry = new BranchRegistry(root)
+      const branches = await registry.list()
+
+      expect(branches).toHaveLength(2)
+      expect(branches.map((b) => b.branch.name).sort()).toEqual(['feature-a', 'feature-b'])
+    })
+
+    it('skips directories without branch.json', async () => {
+      const root = await tmpDir()
+      await createBranchWithMetadata(root, 'feature-a')
+      // Create a directory without metadata
+      await fs.mkdir(path.join(root, 'empty-dir'), { recursive: true })
+
+      const registry = new BranchRegistry(root)
+      const branches = await registry.list()
+
+      expect(branches).toHaveLength(1)
+      expect(branches[0].branch.name).toBe('feature-a')
+    })
+
+    it('skips hidden directories like .canopycms', async () => {
+      const root = await tmpDir()
+      await createBranchWithMetadata(root, 'feature-a')
+      // Create .canopycms directory at root (registry storage)
+      await fs.mkdir(path.join(root, '.canopy-meta'), { recursive: true })
+
+      const registry = new BranchRegistry(root)
+      const branches = await registry.list()
+
+      expect(branches).toHaveLength(1)
+    })
+
+    it('creates cache file after first list()', async () => {
+      const root = await tmpDir()
+      await createBranchWithMetadata(root, 'feature-a')
+
+      const registry = new BranchRegistry(root)
+      await registry.list()
+
+      // Cache file should exist
+      const cacheFile = path.join(root, 'branches.json')
+      const exists = await fs
+        .stat(cacheFile)
+        .then(() => true)
+        .catch(() => false)
+      expect(exists).toBe(true)
+    })
+
+    it('uses cached result on subsequent calls', async () => {
+      const root = await tmpDir()
+      await createBranchWithMetadata(root, 'feature-a')
+
+      const registry = new BranchRegistry(root)
+
+      // First call regenerates
+      const first = await registry.list()
+      expect(first).toHaveLength(1)
+
+      // Add another branch directly by writing file (bypassing invalidation)
+      const branchDir = path.join(root, 'feature-b')
+      const metaDir = path.join(branchDir, '.canopy-meta')
+      await fs.mkdir(metaDir, { recursive: true })
+      await fs.writeFile(
+        path.join(metaDir, 'branch.json'),
+        JSON.stringify({
+          schemaVersion: 1,
+          branch: {
+            name: 'feature-b',
+            status: 'editing',
+            access: {},
+            createdBy: 'user-1',
+            createdAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+          },
+        }),
+      )
+
+      // Second call should return cached result (still 1 branch)
+      const second = await registry.list()
+      expect(second).toHaveLength(1)
+    })
+  })
+
+  describe('get()', () => {
+    it('returns branch by name', async () => {
+      const root = await tmpDir()
+      await createBranchWithMetadata(root, 'feature-a')
+
+      const registry = new BranchRegistry(root)
+      const branch = await registry.get('feature-a')
+
+      expect(branch?.branch.name).toBe('feature-a')
+    })
+
+    it('returns undefined for non-existent branch', async () => {
+      const root = await tmpDir()
+      await createBranchWithMetadata(root, 'feature-a')
+
+      const registry = new BranchRegistry(root)
+      const branch = await registry.get('does-not-exist')
+
+      expect(branch).toBeUndefined()
+    })
+  })
+
+  describe('invalidate()', () => {
+    it('causes next list() to regenerate cache', async () => {
+      const root = await tmpDir()
+      await createBranchWithMetadata(root, 'feature-a')
+
+      const registry = new BranchRegistry(root)
+
+      // First call populates cache
+      const first = await registry.list()
+      expect(first).toHaveLength(1)
+
+      // Add another branch
+      await createBranchWithMetadata(root, 'feature-b')
+
+      // Without invalidation, cache would still show 1
+      // But with invalidation, it should regenerate
+      await registry.invalidate()
+
+      const after = await registry.list()
+      expect(after).toHaveLength(2)
+    })
+
+    it('is safe to call when no cache exists', async () => {
+      const root = await tmpDir()
+      const registry = new BranchRegistry(root)
+
+      // Should not throw
+      await registry.invalidate()
+    })
+
+    it('renames cache file to stale file', async () => {
+      const root = await tmpDir()
+      await createBranchWithMetadata(root, 'feature-a')
+
+      const registry = new BranchRegistry(root)
+      await registry.list() // Create cache
+
+      const cacheFile = path.join(root, 'branches.json')
+      const staleFile = path.join(root, 'branches.stale.json')
+
+      // Cache exists, stale doesn't
+      expect(
+        await fs
+          .stat(cacheFile)
+          .then(() => true)
+          .catch(() => false),
+      ).toBe(true)
+      expect(
+        await fs
+          .stat(staleFile)
+          .then(() => true)
+          .catch(() => false),
+      ).toBe(false)
+
+      await registry.invalidate()
+
+      // Now stale exists, cache doesn't
+      expect(
+        await fs
+          .stat(cacheFile)
+          .then(() => true)
+          .catch(() => false),
+      ).toBe(false)
+      expect(
+        await fs
+          .stat(staleFile)
+          .then(() => true)
+          .catch(() => false),
+      ).toBe(true)
+    })
+  })
+
+  describe('cache integrity', () => {
+    it('includes workspace paths in branch state', async () => {
+      const root = await tmpDir()
+      await createBranchWithMetadata(root, 'feature-a')
+
+      const registry = new BranchRegistry(root)
+      const branches = await registry.list()
+
+      expect(branches[0].branchRoot).toBe(path.join(root, 'feature-a'))
+      expect(branches[0].baseRoot).toBe(root)
+    })
+
+    it('reflects status from branch.json', async () => {
+      const root = await tmpDir()
+      await createBranchWithMetadata(root, 'feature-a', 'submitted')
+
+      const registry = new BranchRegistry(root)
+      const branches = await registry.list()
+
+      expect(branches[0].branch.status).toBe('submitted')
+    })
+  })
+})

package/src/branch-registry.ts

@@ -0,0 +1,152 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+import type { BranchContext } from './types'
+import { BranchMetadataFileManager } from './branch-metadata'
+import { isNotFoundError } from './utils/error'
+
+// Registry files are stored directly in the branches root (not in a subdirectory)
+const REGISTRY_FILE = 'branches.json'
+const REGISTRY_STALE_FILE = 'branches.stale.json'
+const REGISTRY_TEMP_FILE = 'branches.tmp.json'
+const REGISTRY_VERSION = 1
+
+export interface BranchRegistrySnapshot {
+  version: number
+  branches: BranchContext[]
+}
+
+/**
+ * BranchRegistry is a read-only cache for fast branch listing.
+ * Individual branch.json files are the source of truth.
+ *
+ * Design:
+ * - list() returns cached data if fresh, regenerates from branch.json files if stale
+ * - invalidate() marks cache as stale (called when branch state changes)
+ * - Concurrent regeneration is safe (all processes produce identical output)
+ */
+export class BranchRegistry {
+  private readonly root: string
+  private readonly registryPath: string
+  private readonly stalePath: string
+  private readonly tempPath: string
+
+  constructor(root: string) {
+    this.root = path.resolve(root)
+    this.registryPath = path.join(this.root, REGISTRY_FILE)
+    this.stalePath = path.join(this.root, REGISTRY_STALE_FILE)
+    this.tempPath = path.join(this.root, REGISTRY_TEMP_FILE)
+  }
+
+  /**
+   * Returns all branches. Uses cache if fresh, regenerates if stale.
+   */
+  async list(): Promise<BranchContext[]> {
+    try {
+      const raw = await fs.readFile(this.registryPath, 'utf8')
+      const parsed = JSON.parse(raw) as BranchRegistrySnapshot
+      if (!parsed.version || !Array.isArray(parsed.branches)) {
+        // Invalid cache, regenerate
+        return await this.regenerate()
+      }
+      return parsed.branches
+    } catch (err: unknown) {
+      if (isNotFoundError(err)) {
+        // Cache missing or stale, regenerate
+        return await this.regenerate()
+      }
+      throw err
+    }
+  }
+
+  /**
+   * Returns a single branch by name. Uses cache if available.
+   */
+  async get(name: string): Promise<BranchContext | undefined> {
+    const branches = await this.list()
+    return branches.find((b) => b.branch.name === name)
+  }
+
+  /**
+   * Marks the cache as stale. Next list() call will regenerate.
+   * Uses atomic rename for safety.
+   */
+  async invalidate(): Promise<void> {
+    try {
+      await fs.rename(this.registryPath, this.stalePath)
+    } catch (err: unknown) {
+      // ENOENT means already stale or never existed, which is fine
+      if (!isNotFoundError(err)) {
+        throw err
+      }
+    }
+  }
+
+  /**
+   * Scans branch directories and rebuilds the cache.
+   * Concurrent calls are safe - all produce identical content.
+   */
+  private async regenerate(): Promise<BranchContext[]> {
+    const branches = await this.scanBranchDirectories()
+
+    // Write to unique temp file first, then atomic rename
+    // Use random suffix to avoid conflicts between concurrent regenerations
+    const uniqueTempPath = `${this.tempPath}.${Date.now()}.${Math.random().toString(36).slice(2)}`
+    await fs.mkdir(this.root, { recursive: true })
+    const snapshot: BranchRegistrySnapshot = {
+      version: REGISTRY_VERSION,
+      branches,
+    }
+    await fs.writeFile(uniqueTempPath, JSON.stringify(snapshot, null, 2) + '\n', 'utf8')
+
+    try {
+      await fs.rename(uniqueTempPath, this.registryPath)
+    } catch (err: unknown) {
+      // Clean up temp file if rename fails
+      await fs.unlink(uniqueTempPath).catch(() => {})
+      throw err
+    }
+
+    // Clean up stale file (ignore errors)
+    await fs.unlink(this.stalePath).catch(() => {})
+
+    return branches
+  }
+
+  /**
+   * Scans the root directory for branch subdirectories with valid branch.json files.
+   */
+  private async scanBranchDirectories(): Promise<BranchContext[]> {
+    const branches: BranchContext[] = []
+
+    try {
+      const entries = await fs.readdir(this.root, { withFileTypes: true })
+
+      for (const entry of entries) {
+        // Skip non-directories and hidden directories (like .canopy-meta, .canopy-prod-sim)
+        if (!entry.isDirectory() || entry.name.startsWith('.')) {
+          continue
+        }
+
+        const branchRoot = path.join(this.root, entry.name)
+        const meta = await BranchMetadataFileManager.loadOnly(branchRoot)
+
+        if (meta) {
+          branches.push({
+            branch: meta.branch,
+            branchRoot,
+            baseRoot: this.root,
+          })
+        }
+      }
+    } catch (err: unknown) {
+      // If root doesn't exist yet, return empty list
+      if (isNotFoundError(err)) {
+        return []
+      }
+      throw err
+    }
+
+    return branches
+  }
+}

package/src/branch-schema-cache.test.ts

@@ -0,0 +1,275 @@
+import { describe, expect, it, beforeEach, afterEach } from 'vitest'
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import os from 'node:os'
+import { BranchSchemaCache } from './branch-schema-cache'
+import type { FieldConfig } from './config'
+
+describe('BranchSchemaCache', () => {
+  let tempDir: string
+  let branchRoot: string
+
+  beforeEach(async () => {
+    // Create temp directory for testing
+    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'schema-cache-test-'))
+    branchRoot = path.join(tempDir, 'branch-workspace')
+    await fs.mkdir(branchRoot, { recursive: true })
+
+    // Create content directory structure
+    const contentRoot = path.join(branchRoot, 'content')
+    await fs.mkdir(contentRoot, { recursive: true })
+
+    // Create a simple .collection.json file
+    await fs.writeFile(
+      path.join(contentRoot, '.collection.json'),
+      JSON.stringify({
+        label: 'Root',
+        entries: [
+          {
+            name: 'page',
+            format: 'md',
+            schema: 'pageSchema',
+          },
+        ],
+        order: [],
+      }),
+      'utf-8',
+    )
+  })
+
+  afterEach(async () => {
+    // Clean up temp directory
+    await fs.rm(tempDir, { recursive: true, force: true })
+  })
+
+  describe('prod-sim mode', () => {
+    it('should load schema from .collection.json files on first access (cache miss)', async () => {
+      const registry = new BranchSchemaCache('prod-sim')
+      const entrySchemaRegistry: Record<string, readonly FieldConfig[]> = {
+        pageSchema: [{ name: 'title', type: 'string', label: 'Title' }],
+      }
+
+      const result = await registry.getSchema(branchRoot, entrySchemaRegistry)
+
+      expect(result.schema).toBeDefined()
+      expect(result.flatSchema).toBeDefined()
+      expect(result.schema.entries).toBeDefined()
+      expect(result.schema.entries?.length).toBe(1)
+      expect(result.schema.entries?.[0].name).toBe('page')
+    })
+
+    it('should use cache on second access (cache hit)', async () => {
+      const registry = new BranchSchemaCache('prod-sim')
+      const entrySchemaRegistry: Record<string, readonly FieldConfig[]> = {
+        pageSchema: [{ name: 'title', type: 'string', label: 'Title' }],
+      }
+
+      // First access - cache miss
+      const result1 = await registry.getSchema(branchRoot, entrySchemaRegistry)
+
+      // Second access - should be faster (cache hit)
+      const start2 = Date.now()
+      const result2 = await registry.getSchema(branchRoot, entrySchemaRegistry)
+      const duration2 = Date.now() - start2
+
+      // Results should be the same
+      expect(result2.schema).toEqual(result1.schema)
+      expect(result2.flatSchema).toEqual(result1.flatSchema)
+
+      // Second access (cache hit) should be very fast (no filesystem I/O)
+      expect(duration2).toBeLessThan(10)
+    })
+
+    it('should write cache file to .canopy-meta/schema-cache.json', async () => {
+      const registry = new BranchSchemaCache('prod-sim')
+      const entrySchemaRegistry: Record<string, readonly FieldConfig[]> = {
+        pageSchema: [{ name: 'title', type: 'string', label: 'Title' }],
+      }
+
+      await registry.getSchema(branchRoot, entrySchemaRegistry)
+
+      const cachePath = path.join(branchRoot, '.canopy-meta', 'schema-cache.json')
+      const cacheExists = await fs
+        .access(cachePath)
+        .then(() => true)
+        .catch(() => false)
+
+      expect(cacheExists).toBe(true)
+
+      // Verify cache structure
+      const cacheContent = await fs.readFile(cachePath, 'utf-8')
+      const cache = JSON.parse(cacheContent)
+      expect(cache.version).toBe(2)
+      expect(cache.schema).toBeDefined()
+      expect(cache.flatSchema).toBeDefined()
+      expect(cache.cachedAt).toBeDefined()
+    })
+
+    it('should invalidate cache when invalidate() is called', async () => {
+      const registry = new BranchSchemaCache('prod-sim')
+      const entrySchemaRegistry: Record<string, readonly FieldConfig[]> = {
+        pageSchema: [{ name: 'title', type: 'string', label: 'Title' }],
+      }
+
+      // Load schema (creates cache)
+      await registry.getSchema(branchRoot, entrySchemaRegistry)
+
+      // Invalidate cache (creates .stale marker)
+      await registry.invalidate(branchRoot)
+
+      const stalePath = path.join(branchRoot, '.canopy-meta', 'schema-cache.stale')
+      const staleExists = await fs
+        .access(stalePath)
+        .then(() => true)
+        .catch(() => false)
+
+      expect(staleExists).toBe(true)
+    })
+
+    it('should regenerate cache when .stale marker exists', async () => {
+      const registry = new BranchSchemaCache('prod-sim')
+      const entrySchemaRegistry: Record<string, readonly FieldConfig[]> = {
+        pageSchema: [{ name: 'title', type: 'string', label: 'Title' }],
+      }
+
+      // First load (creates cache)
+      await registry.getSchema(branchRoot, entrySchemaRegistry)
+      const cachePath = path.join(branchRoot, '.canopy-meta', 'schema-cache.json')
+      const cache1Stat = await fs.stat(cachePath)
+
+      // Wait a bit to ensure modification time is different
+      await new Promise((resolve) => setTimeout(resolve, 10))
+
+      // Invalidate cache
+      await registry.invalidate(branchRoot)
+
+      // Second load (should regenerate because of .stale marker)
+      await registry.getSchema(branchRoot, entrySchemaRegistry)
+      const cache2Stat = await fs.stat(cachePath)
+
+      // Cache file should have been regenerated (newer modification time)
+      expect(cache2Stat.mtimeMs).toBeGreaterThan(cache1Stat.mtimeMs)
+
+      // Stale marker should be removed
+      const stalePath = path.join(branchRoot, '.canopy-meta', 'schema-cache.stale')
+      const staleExists = await fs
+        .access(stalePath)
+        .then(() => true)
+        .catch(() => false)
+      expect(staleExists).toBe(false)
+    })
+
+    it('should handle missing cache file gracefully', async () => {
+      const registry = new BranchSchemaCache('prod-sim')
+      const entrySchemaRegistry: Record<string, readonly FieldConfig[]> = {
+        pageSchema: [{ name: 'title', type: 'string', label: 'Title' }],
+      }
+
+      // First load without any cache
+      const result = await registry.getSchema(branchRoot, entrySchemaRegistry)
+
+      expect(result.schema).toBeDefined()
+      expect(result.flatSchema).toBeDefined()
+    })
+  })
+
+  describe('dev mode', () => {
+    it('should use in-memory cache (no file I/O)', async () => {
+      const registry = new BranchSchemaCache('dev')
+      const entrySchemaRegistry: Record<string, readonly FieldConfig[]> = {
+        pageSchema: [{ name: 'title', type: 'string', label: 'Title' }],
+      }
+
+      // Load schema
+      await registry.getSchema(branchRoot, entrySchemaRegistry)
+
+      // No cache file should be created in dev mode
+      const cachePath = path.join(branchRoot, '.canopy-meta', 'schema-cache.json')
+      const cacheExists = await fs
+        .access(cachePath)
+        .then(() => true)
+        .catch(() => false)
+
+      expect(cacheExists).toBe(false)
+    })
+
+    it('should use singleton in-memory cache', async () => {
+      const registry = new BranchSchemaCache('dev')
+      const entrySchemaRegistry: Record<string, readonly FieldConfig[]> = {
+        pageSchema: [{ name: 'title', type: 'string', label: 'Title' }],
+      }
+
+      // First access
+      const result1 = await registry.getSchema(branchRoot, entrySchemaRegistry)
+
+      // Second access (should use in-memory cache)
+      const result2 = await registry.getSchema(branchRoot, entrySchemaRegistry)
+
+      // Results should be the exact same object (reference equality)
+      expect(result2).toBe(result1)
+    })
+
+    it('should clear in-memory cache when invalidate() is called', async () => {
+      const registry = new BranchSchemaCache('dev')
+      const entrySchemaRegistry: Record<string, readonly FieldConfig[]> = {
+        pageSchema: [{ name: 'title', type: 'string', label: 'Title' }],
+      }
+
+      // Load schema
+      const result1 = await registry.getSchema(branchRoot, entrySchemaRegistry)
+
+      // Invalidate
+      await registry.invalidate(branchRoot)
+
+      // Load again (should be a new object)
+      const result2 = await registry.getSchema(branchRoot, entrySchemaRegistry)
+
+      // Should not be the same reference (cache was cleared)
+      expect(result2).not.toBe(result1)
+
+      // But content should be the same
+      expect(result2.schema).toEqual(result1.schema)
+    })
+
+    it('should not create .stale marker in dev mode', async () => {
+      const registry = new BranchSchemaCache('dev')
+      const entrySchemaRegistry: Record<string, readonly FieldConfig[]> = {
+        pageSchema: [{ name: 'title', type: 'string', label: 'Title' }],
+      }
+
+      // Load and invalidate
+      await registry.getSchema(branchRoot, entrySchemaRegistry)
+      await registry.invalidate(branchRoot)
+
+      // No .stale marker should exist
+      const stalePath = path.join(branchRoot, '.canopy-meta', 'schema-cache.stale')
+      const staleExists = await fs
+        .access(stalePath)
+        .then(() => true)
+        .catch(() => false)
+
+      expect(staleExists).toBe(false)
+    })
+  })
+
+  describe('clearAll', () => {
+    it('should clear in-memory cache in dev mode', async () => {
+      const registry = new BranchSchemaCache('dev')
+      const entrySchemaRegistry: Record<string, readonly FieldConfig[]> = {
+        pageSchema: [{ name: 'title', type: 'string', label: 'Title' }],
+      }
+
+      // Load schema
+      const result1 = await registry.getSchema(branchRoot, entrySchemaRegistry)
+
+      // Clear all
+      await registry.clearAll()
+
+      // Load again
+      const result2 = await registry.getSchema(branchRoot, entrySchemaRegistry)
+
+      // Should not be the same reference
+      expect(result2).not.toBe(result1)
+    })
+  })
+})