canopycms 0.0.0

package/src/operating-mode/client-unsafe-strategy.ts

@@ -0,0 +1,303 @@
+/**
+ * Client-Unsafe Operating Mode Strategies
+ *
+ * Full strategy implementations that extend client-safe base classes.
+ * INCLUDES Node.js imports (fs, path, process) - can only be imported server-side.
+ *
+ * These classes inherit all client-safe methods and add client-unsafe functionality.
+ */
+
+import path from 'node:path'
+import {
+  ProdClientSafeStrategy,
+  LocalProdSimClientSafeStrategy,
+  LocalSimpleClientSafeStrategy,
+} from './client-safe-strategy'
+import type { OperatingMode, ClientUnsafeStrategy } from './types'
+import type { CanopyConfig } from '../config'
+import { DEFAULT_PROD_WORKSPACE } from '../config'
+
+// ============================================================================
+// Production Mode - Full Strategy
+// ============================================================================
+
+class ProdStrategy extends ProdClientSafeStrategy implements ClientUnsafeStrategy {
+  // All client-safe methods inherited automatically from ProdClientSafeStrategy:
+  // - mode, supportsBranching(), supportsStatusBadge(), supportsComments()
+  // - supportsPullRequests(), getPermissionsFileName(), getGroupsFileName()
+  // - shouldCommit(), shouldPush()
+
+  // Add client-unsafe methods (use Node.js APIs)
+
+  getContentRoot(sourceRoot?: string): string {
+    // In prod, content is at workspace root (not project root)
+    // This is called with sourceRoot = workspace path
+    return path.resolve(sourceRoot ?? process.cwd(), 'content')
+  }
+
+  getContentBranchesRoot(_sourceRoot?: string): string {
+    const envWorkspace = process.env.CANOPYCMS_WORKSPACE_ROOT
+    const workspace = path.resolve(envWorkspace ?? DEFAULT_PROD_WORKSPACE)
+    return path.join(workspace, 'content-branches')
+  }
+
+  getContentBranchRoot(branchName: string, sourceRoot?: string): string {
+    return path.resolve(this.getContentBranchesRoot(sourceRoot), branchName)
+  }
+
+  getGitExcludePattern(): string {
+    return '.canopy-meta/'
+  }
+
+  getPermissionsFilePath(root: string): string {
+    return path.join(root, this.getPermissionsFileName())
+  }
+
+  getGroupsFilePath(root: string): string {
+    return path.join(root, this.getGroupsFileName())
+  }
+
+  getRemoteUrlConfig(): import('./types').RemoteUrlConfig {
+    const envWorkspace = process.env.CANOPYCMS_WORKSPACE_ROOT
+    const workspace = path.resolve(envWorkspace ?? DEFAULT_PROD_WORKSPACE)
+    return {
+      shouldAutoInitLocal: false,
+      defaultRemotePath: '',
+      envVarName: 'CANOPYCMS_REMOTE_URL',
+      autoDetectRemotePath: path.join(workspace, 'remote.git'),
+    }
+  }
+
+  requiresExistingRepo(): boolean {
+    return false // Will clone if needed
+  }
+
+  getSettingsBranchName(config: {
+    settingsBranch?: string
+    deploymentName?: string
+    defaultBaseBranch?: string
+  }): string {
+    if (config.settingsBranch) return config.settingsBranch
+    const deploymentName = config.deploymentName ?? 'prod'
+    return `canopycms-settings-${deploymentName}`
+  }
+
+  getSettingsRoot(_sourceRoot?: string): string {
+    const envWorkspace = process.env.CANOPYCMS_WORKSPACE_ROOT
+    const workspace = path.resolve(envWorkspace ?? DEFAULT_PROD_WORKSPACE)
+    return path.join(workspace, 'settings')
+  }
+
+  usesSeparateSettingsBranch(): boolean {
+    return true
+  }
+
+  validateConfig(config: Partial<CanopyConfig>): void {
+    if (!config.gitBotAuthorName || !config.gitBotAuthorEmail) {
+      throw new Error('gitBotAuthorName and gitBotAuthorEmail are required in prod mode')
+    }
+  }
+
+  shouldCreateSettingsPR(config: { autoCreateSettingsPR?: boolean }): boolean {
+    return config.autoCreateSettingsPR ?? true
+  }
+}
+
+// ============================================================================
+// Local Production Simulation - Full Strategy
+// ============================================================================
+
+class LocalProdSimStrategy extends LocalProdSimClientSafeStrategy implements ClientUnsafeStrategy {
+  // Inherits client-safe methods from LocalProdSimClientSafeStrategy
+
+  private getProdSimRoot(sourceRoot?: string): string {
+    return path.resolve(sourceRoot ?? process.cwd(), '.canopy-prod-sim')
+  }
+
+  getContentRoot(sourceRoot?: string): string {
+    return path.resolve(sourceRoot ?? process.cwd(), 'content')
+  }
+
+  getContentBranchesRoot(sourceRoot?: string): string {
+    return path.join(this.getProdSimRoot(sourceRoot), 'content-branches')
+  }
+
+  getContentBranchRoot(branchName: string, sourceRoot?: string): string {
+    return path.resolve(this.getContentBranchesRoot(sourceRoot), branchName)
+  }
+
+  getGitExcludePattern(): string {
+    return '.canopy-meta/'
+  }
+
+  getPermissionsFilePath(root: string): string {
+    return path.join(root, this.getPermissionsFileName())
+  }
+
+  getGroupsFilePath(root: string): string {
+    return path.join(root, this.getGroupsFileName())
+  }
+
+  getRemoteUrlConfig(): import('./types').RemoteUrlConfig {
+    return {
+      shouldAutoInitLocal: true,
+      defaultRemotePath: '.canopy-prod-sim/remote.git',
+      envVarName: 'CANOPYCMS_REMOTE_URL',
+    }
+  }
+
+  requiresExistingRepo(): boolean {
+    return false
+  }
+
+  getSettingsBranchName(config: {
+    settingsBranch?: string
+    deploymentName?: string
+    defaultBaseBranch?: string
+  }): string {
+    if (config.settingsBranch) return config.settingsBranch
+    const deploymentName = config.deploymentName ?? 'prod'
+    return `canopycms-settings-${deploymentName}`
+  }
+
+  getSettingsRoot(sourceRoot?: string): string {
+    return path.join(this.getProdSimRoot(sourceRoot), 'settings')
+  }
+
+  usesSeparateSettingsBranch(): boolean {
+    return true
+  }
+
+  validateConfig(_config: Partial<CanopyConfig>): void {
+    // No special validation for prod-sim
+  }
+
+  shouldCreateSettingsPR(_config: { autoCreateSettingsPR?: boolean }): boolean {
+    return false // No real GitHub in simulation
+  }
+}
+
+// ============================================================================
+// Local Simple Mode - Full Strategy
+// ============================================================================
+
+class LocalSimpleStrategy extends LocalSimpleClientSafeStrategy implements ClientUnsafeStrategy {
+  // Inherits: supportsBranching() returns false, getPermissionsFileName() returns 'permissions.local.json'
+
+  private getDevConfigRoot(sourceRoot?: string): string {
+    return path.resolve(sourceRoot ?? process.cwd(), '.canopy-dev')
+  }
+
+  getContentRoot(sourceRoot?: string): string {
+    return path.resolve(sourceRoot ?? process.cwd(), 'content')
+  }
+
+  getContentBranchesRoot(_sourceRoot?: string): string {
+    throw new Error('No branching in dev mode')
+  }
+
+  getContentBranchRoot(_branchName: string, _sourceRoot?: string): string {
+    throw new Error('No branching in dev mode')
+  }
+
+  getGitExcludePattern(): string {
+    return '.canopy-meta/'
+  }
+
+  getPermissionsFilePath(root: string): string {
+    // Returns: {projectRoot}/.canopy-dev/settings/permissions.json
+    return path.join(this.getDevConfigRoot(root), 'settings', 'permissions.json')
+  }
+
+  getGroupsFilePath(root: string): string {
+    // Returns: {projectRoot}/.canopy-dev/settings/groups.json
+    return path.join(this.getDevConfigRoot(root), 'settings', 'groups.json')
+  }
+
+  getRemoteUrlConfig(): import('./types').RemoteUrlConfig {
+    return {
+      shouldAutoInitLocal: false,
+      defaultRemotePath: '',
+      envVarName: 'CANOPYCMS_REMOTE_URL',
+    }
+  }
+
+  requiresExistingRepo(): boolean {
+    return true // Must have existing repo
+  }
+
+  getSettingsBranchName(config: {
+    settingsBranch?: string
+    deploymentName?: string
+    defaultBaseBranch?: string
+  }): string {
+    // Use main branch for settings in dev (no separate settings branch)
+    return config.defaultBaseBranch ?? 'main'
+  }
+
+  getSettingsRoot(sourceRoot?: string): string {
+    return path.join(this.getDevConfigRoot(sourceRoot), 'settings')
+  }
+
+  usesSeparateSettingsBranch(): boolean {
+    return false
+  }
+
+  validateConfig(_config: Partial<CanopyConfig>): void {
+    // No special validation for dev
+  }
+
+  shouldCreateSettingsPR(_config: { autoCreateSettingsPR?: boolean }): boolean {
+    return false // No GitHub in dev
+  }
+}
+
+// ============================================================================
+// Factory with Memoization
+// ============================================================================
+
+const strategyCache = new Map<OperatingMode, ClientUnsafeStrategy>()
+
+/**
+ * Get the full strategy (client-unsafe) for an operating mode.
+ *
+ * Strategies are memoized - one instance per mode for the entire process lifetime.
+ * Safe to call inline: operatingStrategy(mode).getBaseRoot()
+ *
+ * Includes all client-safe methods (inherited) plus client-unsafe methods (Node.js APIs).
+ *
+ * @param mode - The operating mode
+ * @returns Full strategy instance with client-unsafe methods
+ */
+export function operatingStrategy(mode: OperatingMode): ClientUnsafeStrategy {
+  const cached = strategyCache.get(mode)
+  if (cached) return cached
+
+  let strategy: ClientUnsafeStrategy
+  switch (mode) {
+    case 'prod':
+      strategy = new ProdStrategy()
+      break
+    case 'prod-sim':
+      strategy = new LocalProdSimStrategy()
+      break
+    case 'dev':
+      strategy = new LocalSimpleStrategy()
+      break
+    default: {
+      // Exhaustiveness check - TypeScript will error if a mode is not handled
+      const _exhaustive: never = mode
+      throw new Error(`Unknown operating mode: ${_exhaustive}`)
+    }
+  }
+
+  strategyCache.set(mode, strategy)
+  return strategy
+}
+
+/**
+ * Clear the strategy cache (mainly for testing)
+ */
+export function clearStrategyCache(): void {
+  strategyCache.clear()
+}

package/src/operating-mode/client.ts

@@ -0,0 +1,13 @@
+/**
+ * Client-Safe Operating Mode Strategy - Client Bundle Entry Point
+ *
+ * This module ONLY exports client-safe functionality with NO Node.js imports.
+ * Safe to import in 'use client' React components.
+ *
+ * Usage in client components:
+ *   import { clientOperatingStrategy } from '@/operating-mode/client'
+ */
+
+export { clientOperatingStrategy, clearClientStrategyCache } from './client-safe-strategy'
+export type { ClientSafeStrategy } from './types'
+export type { OperatingMode } from './types'

package/src/operating-mode/index.ts

@@ -0,0 +1,34 @@
+/**
+ * Operating Mode Strategy Pattern - Public API
+ *
+ * Two-layer architecture:
+ * 1. Client-safe strategies - safe for 'use client' React components (no Node.js imports)
+ * 2. Client-unsafe strategies - full server-side functionality (uses fs, path, process)
+ *
+ * Usage:
+ *
+ * Client components:
+ *   import { clientOperatingStrategy } from '@/operating-mode'
+ *   const strategy = clientOperatingStrategy(mode)
+ *   if (strategy.supportsBranching()) { ... }
+ *
+ * Server code:
+ *   import { operatingStrategy } from '@/operating-mode'
+ *   const strategy = operatingStrategy(mode)
+ *   const contentRoot = strategy.getContentRoot()
+ *   const branchesRoot = strategy.getContentBranchesRoot() // throws in dev mode
+ *   const branchRoot = strategy.getContentBranchRoot('my-branch') // throws in dev mode
+ *   const settingsRoot = strategy.getSettingsRoot()
+ *   if (strategy.supportsBranching()) { ... } // can also use client-safe methods
+ */
+
+// Client-safe factory and strategy (safe for client bundles)
+export { clientOperatingStrategy, clearClientStrategyCache } from './client-safe-strategy'
+
+// Client-unsafe factory and strategy (server-side only)
+export { operatingStrategy, clearStrategyCache } from './client-unsafe-strategy'
+
+export type OperatingMode = 'prod' | 'prod-sim' | 'dev'
+
+// Type exports
+export type { ClientSafeStrategy, ClientUnsafeStrategy, ResolveRemoteUrlOptions } from './types'

package/src/operating-mode/types.ts

@@ -0,0 +1,186 @@
+/**
+ * Operating Mode Strategy Types
+ *
+ * This module defines the two-layer strategy pattern for operating modes:
+ * - ClientSafeStrategy: Methods safe for client-side bundles (no Node.js APIs)
+ * - ClientUnsafeStrategy: Full strategy with Node.js APIs (server-side only)
+ */
+
+import type { OperatingMode as OM } from '.'
+import type { CanopyConfig } from '../config'
+
+// Re-export OperatingMode so it's available from this module
+export type OperatingMode = OM
+
+/**
+ * Options for resolving git remote URL
+ */
+export interface ResolveRemoteUrlOptions {
+  mode: OperatingMode
+  remoteUrl?: string
+  defaultRemoteUrl?: string
+  baseBranch?: string
+  sourceRoot?: string
+}
+
+/**
+ * Configuration for remote URL resolution
+ * Strategies return this data; GitManager executes the logic
+ */
+export interface RemoteUrlConfig {
+  /** Whether to auto-initialize a local remote */
+  shouldAutoInitLocal: boolean
+  /** Default path for local remote (e.g., '.canopycms/remote.git') */
+  defaultRemotePath: string
+  /** Environment variable name for remote URL */
+  envVarName: string
+  /**
+   * Absolute path to check for auto-detection of a pre-existing local remote.
+   * If this path exists on disk, it's used as the remote URL (file:// protocol).
+   * Used in prod mode where the EC2 worker creates remote.git on EFS.
+   * Unlike shouldAutoInitLocal, this does NOT create the remote — just detects it.
+   */
+  autoDetectRemotePath?: string
+}
+
+/**
+ * Client-Safe Strategy
+ *
+ * Methods that can be safely imported in 'use client' React components.
+ * NO Node.js APIs (fs, path, process, etc.) - only pure logic and simple data.
+ */
+export interface ClientSafeStrategy {
+  /** The operating mode this strategy represents */
+  readonly mode: OperatingMode
+
+  // ========================================================================
+  // UI Feature Flags
+  // ========================================================================
+
+  /** Whether this mode supports multiple branch workspaces */
+  supportsBranching(): boolean
+
+  /** Whether to show status badge in UI */
+  supportsStatusBadge(): boolean
+
+  /** Whether comments/collaboration features are enabled */
+  supportsComments(): boolean
+
+  /** Whether pull request features are available */
+  supportsPullRequests(): boolean
+
+  // ========================================================================
+  // Simple Data Methods (no I/O)
+  // ========================================================================
+
+  /** Get the permissions file name (e.g., 'permissions.json' or 'permissions.local.json') */
+  getPermissionsFileName(): string
+
+  /** Get the groups file name (e.g., 'groups.json' or 'groups.local.json') */
+  getGroupsFileName(): string
+
+  /** Whether git commits should be made in this mode */
+  shouldCommit(): boolean
+
+  /** Whether git pushes should be made in this mode */
+  shouldPush(): boolean
+}
+
+/**
+ * Client-Unsafe Strategy
+ *
+ * Full strategy including Node.js APIs. Can only be imported server-side.
+ * Extends ClientSafeStrategy, so all client-safe methods are available.
+ */
+export interface ClientUnsafeStrategy extends ClientSafeStrategy {
+  // ========================================================================
+  // Path Resolution (needs path, process.cwd, env vars)
+  // ========================================================================
+
+  /**
+   * Get the content directory path (at project/workspace root).
+   * - dev/prod-sim: {cwd}/content
+   * - prod (in workspaces): {workspaceRoot}/content
+   */
+  getContentRoot(sourceRoot?: string): string
+
+  /**
+   * Get the parent directory of all content branch workspaces (contains branches.json and branch directories).
+   * - prod-sim: {cwd}/.canopy-prod-sim/content-branches
+   * - prod: $CANOPYCMS_WORKSPACE_ROOT/content-branches or /mnt/efs/workspace/content-branches
+   * @throws Error in dev mode (no branching)
+   */
+  getContentBranchesRoot(sourceRoot?: string): string
+
+  /**
+   * Get individual content branch workspace directory.
+   * Returns: {contentBranchesRoot}/{branchName}
+   * @throws Error in dev mode (no branching)
+   */
+  getContentBranchRoot(branchName: string, sourceRoot?: string): string
+
+  /**
+   * Get the git exclude pattern for runtime metadata (e.g., '.canopy-meta/').
+   * Used by GitManager to add to .git/info/exclude in content branch workspaces.
+   */
+  getGitExcludePattern(): string
+
+  // ========================================================================
+  // File Paths (needs path.join)
+  // ========================================================================
+
+  /** Get the full path to the permissions file */
+  getPermissionsFilePath(root: string): string
+
+  /** Get the full path to the groups file */
+  getGroupsFilePath(root: string): string
+
+  // ========================================================================
+  // Git Operations
+  // ========================================================================
+
+  /** Get configuration for remote URL resolution (GitManager executes the logic) */
+  getRemoteUrlConfig(): RemoteUrlConfig
+
+  /** Whether this mode requires an existing git repository */
+  requiresExistingRepo(): boolean
+
+  // ========================================================================
+  // Settings
+  // ========================================================================
+
+  /**
+   * Get the branch name to use for settings (permissions/groups).
+   * Returns: canopycms-settings-{deploymentName}
+   */
+  getSettingsBranchName(config: {
+    settingsBranch?: string
+    deploymentName?: string
+    defaultBaseBranch?: string
+  }): string
+
+  /**
+   * Get the root directory for settings storage.
+   * - prod: $CANOPYCMS_WORKSPACE_ROOT/settings or /mnt/efs/workspace/settings
+   * - prod-sim: {cwd}/.canopy-prod-sim/settings
+   * - dev: {cwd}/.canopy-dev/settings
+   */
+  getSettingsRoot(sourceRoot?: string): string
+
+  /** Whether settings should be stored in a separate branch */
+  usesSeparateSettingsBranch(): boolean
+
+  // ========================================================================
+  // Validation
+  // ========================================================================
+
+  /** Validate configuration for this mode */
+  validateConfig(config: Partial<CanopyConfig>): void
+
+  // ========================================================================
+  // GitHub
+  // ========================================================================
+
+  /** Whether PRs should be auto-created for permissions/groups changes */
+  shouldCreateSettingsPR(config: { autoCreateSettingsPR?: boolean }): boolean
+}

package/src/paths/__tests__/branch.test.ts

@@ -0,0 +1,53 @@
+import fs from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+
+import { describe, expect, it } from 'vitest'
+
+import {
+  BranchPathError,
+  ensureBranchRoot,
+  getDefaultBranchBase,
+  resolveBranchPath,
+} from '../branch'
+
+describe('paths', () => {
+  it('resolves prod content branches root from default workspace', () => {
+    // In prod mode, uses default workspace path (or CANOPYCMS_WORKSPACE_ROOT env var)
+    // Override parameter is not used in prod mode - workspace comes from env
+    const base = getDefaultBranchBase('prod')
+    expect(base).toContain('content-branches')
+  })
+
+  it('sanitizes branch names and prevents traversal', () => {
+    expect(() =>
+      resolveBranchPath({
+        mode: 'prod-sim',
+        branchName: '../evil',
+      }),
+    ).toThrow(BranchPathError)
+  })
+
+  it('ensures branch root is created under base in prod-sim', async () => {
+    const temp = await fs.mkdtemp(path.join(os.tmpdir(), 'canopycms-branches-'))
+    const { branchRoot, baseRoot } = await ensureBranchRoot({
+      mode: 'prod-sim',
+      branchName: 'feature/test',
+      basePathOverride: temp,
+    })
+    const stat = await fs.stat(branchRoot)
+    expect(stat.isDirectory()).toBe(true)
+    // baseRoot is now .canopy-prod-sim/content-branches inside the override path
+    expect(baseRoot).toBe(path.resolve(temp, '.canopy-prod-sim', 'content-branches'))
+    expect(branchRoot.startsWith(baseRoot)).toBe(true)
+  })
+
+  it('throws error when using branching functions in dev mode', () => {
+    expect(() =>
+      resolveBranchPath({
+        mode: 'dev',
+        branchName: 'current',
+      }),
+    ).toThrow('No branching in dev mode')
+  })
+})