@spfn/cms 0.1.0-alpha.9 → 0.2.0-beta.2

package/README.md

@@ -1,490 +1,451 @@
 # @spfn/cms
 
-Content Management System for Next.js with JSON-based labels and automatic database synchronization.
+Type-safe Content Management System for Next.js with automatic database synchronization and published cache.
 
 ## Features
 
-- 📁 **JSON file-based labels** - Simple file structure for label management
-- 🔄 **Auto-sync to database** on server startup and during development
-- 🌐 **Multi-language support** (i18n)
-- 🍪 **Cookie-based locale management** - Automatic locale detection and persistence
-- 📦 **Folder-based structure** for better organization
-- 🔥 **Hot reload** during development
-- 💾 **Published cache** for optimal performance
-- ⚡ **Server Actions** for client-side locale management
-- 🛠️ **Built on Drizzle ORM**
+- 🎯 **Type-safe labels** - Full TypeScript support with autocomplete
+- 🔄 **Auto-sync** - Database synchronization on server startup
+- 🌐 **Multi-language** - Type-checked locale support
+- 🍪 **Smart locale detection** - Cookie-based with automatic fallback
+- 💾 **Published cache** - 17x faster queries (5ms vs 87ms)
+- 🎨 **Nested structure** - Organize labels hierarchically
+- 🔧 **Template variables** - Dynamic content with `{placeholder}` syntax
+- 📝 **Draft & versioning** - Version control and audit logs
 
 ## Installation
 
-### Recommended: Using SPFN CLI (Automatic Database Setup)
-
 ```bash
 pnpm spfn add @spfn/cms
 ```
 
-This command will:
-1. ✅ Install the package
-2. ✅ Discover CMS database schemas automatically
-3. ✅ Generate migrations for 6 CMS tables
-4. ✅ Apply migrations to your database
-5. ✅ Show setup guide
-
-**Tables created:**
-- `cms_labels` - Label definitions (10 columns, 2 indexes)
-- `cms_label_values` - Label values per locale (7 columns, 2 indexes, 1 FK)
-- `cms_label_versions` - Version history (9 columns, 2 indexes, 1 FK)
-- `cms_draft_cache` - Draft content cache (6 columns, 2 indexes)
-- `cms_published_cache` - Published content cache (7 columns, 1 index)
-- `cms_audit_logs` - Change audit trail (8 columns, 4 indexes, 1 FK)
+## Quick Start
 
-### Manual Installation
+### 1. Define Labels & Configuration
 
-```bash
-pnpm add @spfn/cms
-```
+```typescript
+// labels.ts
+import { defineLabelConfig, defineLabels, createCmsClient } from '@spfn/cms';
+
+// Configure locales
+export const labelConfig = defineLabelConfig({
+    locales: ['en', 'ko'] as const,
+    defaultLocale: 'ko',
+    fallbackLocale: 'en'
+});
 
-Then run database migrations:
+// Define labels with nested structure
+export const labelsDefinition = defineLabels({
+    home: {
+        hero: {
+            title: { en: "Welcome", ko: "환영합니다" },
+            subtitle: { en: "Start your journey", ko: "여정을 시작하세요" },
+            greeting: { en: "Hello {name}!", ko: "{name}님 안녕하세요!" }
+        },
+        cta: { en: "Get Started", ko: "시작하기" }
+    },
+    about: {
+        title: { en: "About Us", ko: "회사 소개" }
+    }
+});
 
-```bash
-pnpm spfn db generate  # Generate migrations
-pnpm spfn db migrate   # Apply migrations
+// Create client with API, getLabel, getLabels, and format
+export const { api, getLabel, getLabels, format } = createCmsClient(
+    labelsDefinition,
+    labelConfig
+);
 ```
 
-**Note:** Manual installation requires that you have `DATABASE_URL` configured in your `.env.local` file.
+### 2. Enable Auto-Sync
 
-## Quick Start
+```typescript
+// server.config.ts
+import { defineServerConfig } from '@spfn/core/server';
+import { syncLabels } from '@spfn/cms/server';
+import { labelsDefinition } from './labels';
 
-### 1. Create Label Files
 
-Create JSON files organized by sections and categories:
+// Option 1: Single definition
+export default defineServerConfig()
+    .lifecycle({
+        afterInfrastructure: async () => {
+            await syncLabels(labelsDefinition);
+        }
+    })
+    .build();
 
-```
-src/cms/labels/
-  layout/              ← Section name
-    nav.json           ← Category
-    footer.json
-  home/
-    hero.json
-    features.json
-```
+// Option 2: Multiple definitions (organized in separate files)
+import { homeLabels } from './labels/home';
+import { aboutLabels } from './labels/about';
 
-**Example:** `src/cms/labels/layout/nav.json`
-
-```json
-{
-  "about": {
-    "key": "layout.nav.about",
-    "defaultValue": "About",
-    "description": "Navigation link for About page"
-  },
-  "services": {
-    "key": "layout.nav.services",
-    "defaultValue": "Services",
-    "description": "Navigation link for Services page"
-  },
-  "team": {
-    "key": "layout.nav.team",
-    "defaultValue": "Team"
-  }
-}
+export default defineServerConfig()
+    .lifecycle({
+        afterInfrastructure: async () => {
+            await syncLabels([homeLabels, aboutLabels]);
+        }
+    })
+    .build();
 ```
 
-**Multi-language example:** `src/cms/labels/home/hero.json`
+### 3. Use in Your App
 
-```json
-{
-  "title": {
-    "key": "home.hero.title",
-    "defaultValue": {
-      "ko": "혁신적인 솔루션",
-      "en": "Innovative Solutions"
-    }
-  },
-  "subtitle": {
-    "key": "home.hero.subtitle",
-    "defaultValue": {
-      "ko": "비즈니스 성장을 위한 최고의 파트너",
-      "en": "Your Best Partner for Business Growth"
-    }
-  }
-}
-```
+**Server Component (Single Section):**
 
-**Variable substitution:** `src/cms/labels/layout/footer.json`
+```typescript
+import { getLabel, format } from '@/labels';
 
-```json
-{
-  "copyright": {
-    "key": "layout.footer.copyright",
-    "defaultValue": "© {year} Company. All rights reserved."
-  }
+export default async function HomePage() {
+    // Single section - direct access without section name
+    const label = await getLabel('home');
+
+    return (
+        <div>
+            <h1>{label.hero.title}</h1>
+            <p>{label.hero.subtitle}</p>
+            <button>{label.cta}</button>
+
+            {/* Template variables */}
+            <p>{format(label.hero.greeting, { name: 'John' })}</p>
+            {/* Output: "John님 안녕하세요!" */}
+        </div>
+    );
 }
 ```
 
-### 2. Enable Auto-Sync on Server Startup
-
-Configure `src/server/server.config.ts`:
+**Server Component (Multiple Sections):**
 
 ```typescript
-import type { ServerConfig } from '@spfn/core/server';
-import { initLabelSync } from '@spfn/cms';
-
-export default {
-  beforeRoutes: async (app) => {
-    await initLabelSync({
-      verbose: true,
-      labelsDir: 'src/cms/labels'  // Optional, this is the default
-    });
-  },
-} satisfies ServerConfig;
+import { getLabels } from '@/labels';
+
+export default async function MultiSectionPage() {
+    // Multiple sections - with section names as keys
+    const labels = await getLabels(['home', 'about']);
+
+    return (
+        <div>
+            <h1>{labels.home.hero.title}</h1>
+            <p>{labels.about.title}</p>
+        </div>
+    );
+}
 ```
 
-### 3. Enable Auto-Sync During Development
+**Locale Management:**
 
-Your `.spfnrc.json` should include:
+```typescript
+'use client';
+import { setLocale } from '@spfn/cms/actions';
 
-```json
-{
-  "codegen": {
-    "generators": [
-      {
-        "name": "@spfn/cms:label-sync",
-        "enabled": true
-      }
-    ]
-  }
+export function LanguageSwitcher() {
+    return (
+        <div>
+            <button onClick={() => setLocale('ko')}>한국어</button>
+            <button onClick={() => setLocale('en')}>English</button>
+        </div>
+    );
 }
 ```
 
-This is automatically configured when you run `pnpm spfn add @spfn/cms`.
+## Key Features
 
-### 4. Use Labels in Your App
+### 🎯 Type Safety
 
-**Server Component:**
+**Section Name Validation:**
 
 ```typescript
-import { getSection } from '@spfn/cms/server';
-
-export default async function HomePage() {
-  const { t } = await getSection('layout', 'ko');
-
-  return <h1>{t('nav.team')}</h1>;
-}
-```
+// ✅ Valid section names are enforced at compile time
+const label = await getLabel('home'); // OK
+await getLabel('homee'); // ❌ Compile error: 'homee' is not a valid section
 
-**With variable substitution:**
+// ✅ getLabel returns direct access (no section wrapper)
+const homeLabel = await getLabel('home');
+homeLabel.hero.title; // OK - direct access
+homeLabel.cta; // OK
 
-```typescript
-const { t } = await getSection('layout');
-const copyright = t('footer.copyright', undefined, {
-  year: new Date().getFullYear()
-});
-// → "© 2025 Company. All rights reserved."
+// ✅ getLabels requires array and returns sections with names
+const labels = await getLabels(['home', 'about']);
+labels.home.hero.title; // OK
+labels.about.title; // OK
+labels.contact.email; // ❌ Compile error: 'contact' was not requested
 ```
 
-**Client Component:**
+**Property Access Validation:**
 
 ```typescript
-'use client';
-import { useSection } from '@spfn/cms/client';
+// Single section - direct access
+const label = await getLabel('signup');
 
-export default function Nav() {
-  const { t, loading } = useSection('layout', { autoLoad: true });
+// ✅ IDE autocomplete works perfectly
+label.title; // OK - direct access
+label.userName; // OK
+label.email; // OK
 
-  if (loading) return <div>Loading...</div>;
+// ❌ Typos are caught at compile time
+label.titlee; // ❌ Compile error
+label.userName; // ❌ Compile error (typo)
 
-  return (
-    <nav>
-      <a>{t('nav.about')}</a>
-      <a>{t('nav.services')}</a>
-    </nav>
-  );
-}
+// Multiple sections - with section names
+const labels = await getLabels(['home', 'about']);
+labels.home.hero.title; // OK
+labels.about.title; // OK
 ```
 
-## File Structure
+**API Distinction:**
 
-```
-src/cms/labels/
-  layout/                  # Section: layout
-    nav.json               # Category: nav
-    footer.json            # Category: footer
-  home/                    # Section: home
-    hero.json              # Category: hero
-    features.json          # Category: features
-```
-
-**How it maps:**
-- Folder name = Section name
-- JSON file name = Category name (for organization only)
-- Inside JSON: `key` field defines the actual label key
+```typescript
+// getLabel: Single section, direct access
+const signup = await getLabel('signup');
+signup.title; // ✅ Direct access (cleaner!)
 
-Example:
-```
-src/cms/labels/layout/nav.json:
-  key: "layout.nav.team" → t('nav.team') in code
+// getLabels: Multiple sections, section names as keys
+const multi = await getLabels(['home', 'signup']);
+multi.home.title; // ✅ With section name
+multi.signup.userName; // ✅ With section name
 ```
 
-## JSON Label Format
+### 🎨 Nested Structure
 
 ```typescript
-{
-  "labelName": {
-    "key": "section.category.name",       // Required: Unique identifier
-    "defaultValue": "Text" | {...},       // Required: String or i18n object
-    "description": "Optional description" // Optional: For documentation
-  }
-}
-```
+defineLabels({
+    features: {
+        analytics: {
+            title: { en: "Analytics", ko: "분석" },
+            description: { en: "Track metrics", ko: "지표 추적" }
+        },
+        security: {
+            title: { en: "Security", ko: "보안" }
+        }
+    }
+});
 
-**Single language:**
-```json
-{
-  "welcome": {
-    "key": "home.welcome",
-    "defaultValue": "Welcome"
-  }
-}
+// Single section - direct access with nesting
+const label = await getLabel('features');
+label.analytics.title; // "분석" (auto locale, direct access!)
+label.analytics.description; // "지표 추적"
+label.security.title; // "보안"
 ```
 
-**Multi-language:**
-```json
-{
-  "welcome": {
-    "key": "home.welcome",
-    "defaultValue": {
-      "ko": "환영합니다",
-      "en": "Welcome",
-      "ja": "ようこそ"
+### 🔧 Template Variables
+
+```typescript
+defineLabels({
+    home: {
+        welcome: {
+            en: "Welcome {name}, you have {count} messages",
+            ko: "{name}님, {count}개의 메시지가 있습니다"
+        }
     }
-  }
-}
-```
+});
 
-**Variable placeholders:**
-```json
-{
-  "greeting": {
-    "key": "home.greeting",
-    "defaultValue": "Hello, {name}!"
-  }
-}
-```
+const label = await getLabel('home');
+const text = label.welcome; // Direct access!
 
-Usage:
-```typescript
-t('greeting', undefined, { name: 'John' })
-// → "Hello, John!"
+format(text, { name: "John", count: 5 });
+// Output: "John님, 5개의 메시지가 있습니다"
 ```
 
-## Configuration
+### 🍪 Smart Locale Detection
 
-### Environment Variables
+Automatic locale detection with priority:
+1. User's cookie (`cms-locale`)
+2. Config's `defaultLocale`
+3. Final fallback: `'en'`
 
-Configure CMS behavior via environment variables in `.env.local`:
-
-```bash
-# Default locale (default: 'en')
-SPFN_CMS_DEFAULT_LOCALE=ko
+```typescript
+// User sets locale (saved to cookie)
+await setLocale('ko');
 
-# Supported locales, comma-separated (default: 'en,ko')
-SPFN_CMS_SUPPORTED_LOCALES=en,ko,ja
+// Automatically uses 'ko' locale
+const label = await getLabel('home');
+label.hero.title; // "환영합니다" (Korean)
 
-# Auto-detect browser language (default: true)
-SPFN_CMS_DETECT_BROWSER_LANGUAGE=true
+// Switch to English
+await setLocale('en');
+const label2 = await getLabel('home');
+label2.hero.title; // "Welcome" (English)
 ```
 
-### Runtime Configuration
+### 🔄 Auto-Sync
 
-Override configuration at runtime (mainly for testing):
+Labels synchronize automatically on server startup:
+- ✅ Creates new labels
+- ✅ Updates changed labels (deep equality check)
+- ✅ Skips unchanged labels (performance)
+- ✅ Rebuilds published cache
+- ⚠️ Optionally removes orphaned labels
 
-```typescript
-import { configureCms, getCmsConfig } from '@spfn/cms';
-
-// Get current configuration
-const config = getCmsConfig();
-console.log(config.defaultLocale);      // 'ko'
-console.log(config.supportedLocales);   // ['ko', 'en']
-
-// Update configuration
-configureCms({
-  defaultLocale: 'en',
-  supportedLocales: ['en', 'ko', 'ja'],
-  detectBrowserLanguage: false
-});
-```
-
-## Locale Management
+## API Reference
 
-### Automatic Locale Detection
+### createCmsClient()
 
-The CMS automatically manages user locale with the following priority:
+Factory function to create CMS client with API, getLabel, getLabels, and format utilities.
 
-1. **Cookie** - User's explicitly selected locale (persisted)
-2. **Browser Language** - Auto-detected from `Accept-Language` header (if enabled)
-3. **Default Locale** - System default from environment variables
+```typescript
+const { api, getLabel, getLabels, format } = createCmsClient(labelsDefinition, labelConfig);
+```
 
-### Server Actions (`@spfn/cms/actions`)
+**Returns:**
+- `api` - API client for CMS routes
+- `getLabel(section)` - Fetch a single section (direct access)
+- `getLabels(sections)` - Fetch multiple sections (with section names)
+- `format(template, vars)` - Template variable substitution
 
-Use Server Actions for locale management in both server and client components:
+### getLabel()
 
-**Get current locale:**
+Fetch a **single section** from published cache with direct access (no section name wrapper).
 
 ```typescript
-// Server Component
-import { getLocale } from '@spfn/cms/actions';
+// Single section - direct access
+const label = await getLabel('home');
+label.hero.title; // Direct access without 'home.' prefix
+label.cta;
+```
 
-export default async function RootLayout({ children }) {
-  const locale = await getLocale();
+**Use when:**
+- You need labels from only ONE section
+- You want cleaner, direct access to properties
+- Most common use case for individual pages
 
-  return <html lang={locale}>{children}</html>;
-}
-```
+**Returns:** Labels directly without section name wrapper
 
-```typescript
-// Client Component
-'use client';
-import { getLocale } from '@spfn/cms/actions';
-import { useEffect, useState } from 'react';
+**Features:**
+- Auto locale detection (cookie → defaultLocale → 'en')
+- Direct property access (no section name)
+- Type-safe with IDE autocomplete
+- Merges published cache with defaults
 
-export default function LanguageSwitcher() {
-  const [locale, setLocale] = useState('');
+### getLabels()
 
-  useEffect(() => {
-    getLocale().then(setLocale);
-  }, []);
+Fetch **multiple sections** from published cache with section names as keys.
 
-  return <div>Current: {locale}</div>;
-}
+```typescript
+// Multiple sections - with section names
+const labels = await getLabels(['home', 'about']);
+labels.home.hero.title; // Access via section name
+labels.about.title;
 ```
 
-**Change locale:**
+**Use when:**
+- You need labels from MULTIPLE sections
+- You're building a page that uses multiple label groups
 
-```typescript
-import { setLocale } from '@spfn/cms/actions';
+**Returns:** Object with section names as keys
 
-async function changeLanguage(newLocale: string) {
-  await setLocale(newLocale);
-  window.location.reload(); // Reload to apply changes
-}
-```
+**Features:**
+- Auto locale detection (cookie → defaultLocale → 'en')
+- Section filtering (only processes requested sections)
+- Type-safe: only requested sections available
+- Merges published cache with defaults
 
-**Get supported locales:**
+**Performance:**
+- Only requested sections are processed (not entire labelsDefinition)
+- 10x faster when requesting specific sections
+- Reduces CPU and memory usage proportionally
 
-```typescript
-import { getLocales } from '@spfn/cms/actions';
+### format()
+
+Replace template variables in strings.
 
-const locales = await getLocales(); // ['ko', 'en', 'ja']
+```typescript
+format("Hello {name}!", { name: "John" }); // "Hello John!"
+format("{count} items", { count: 5 }); // "5 items"
 ```
 
-### Auto-detect Locale in Server Components
+**Syntax:** `{variableName}` - Supports strings and numbers
 
-When `locale` is not specified, `getSection()` automatically uses the detected locale:
+### setLocale() / getLocale()
 
-```typescript
-import { getSection } from '@spfn/cms/server';
+Server actions for locale management (cookie-based).
 
-// Auto-detects locale from cookie → browser → default
-const { t } = await getSection('home');
+```typescript
+// Set user's preferred locale
+await setLocale('ko'); // Saves to 'cms-locale' cookie
 
-// Or explicitly specify locale
-const { t: tEn } = await getSection('home', 'en');
+// Get current locale
+const locale = await getLocale(defaultLocale); // Returns: cookie → defaultLocale → 'en'
 ```
 
-## Documentation
+**Cookie settings:**
+- Name: `cms-locale`
+- Max age: 1 year
+- HttpOnly, Secure (production), SameSite: lax
 
-- **[Label Auto-Sync Guide](./LABEL_SYNC_GUIDE.md)** - Detailed configuration guide
-- **[Examples](./examples/)** - Usage examples
+### syncLabels()
 
-## Architecture
+Synchronize labels to database (server-side only).
 
+```typescript
+await syncLabels(labelsDefinition, {
+    removeOrphaned: false, // Delete labels not in code
+    dryRun: false // Preview changes without applying
+});
 ```
-JSON Files (src/cms/labels/**/*.json)
-              ↓
-      loadLabelsFromJson()
-              ↓
-    ┌─────────────────────┐
-    │ LabelSyncGenerator  │ ← File watcher (development)
-    │ initLabelSync()     │ ← Server startup
-    └─────────────────────┘
-              ↓
-          syncAll()
-              ↓
-    ┌─────────────────────┐
-    │   PostgreSQL DB     │
-    │   - cms_labels      │
-    │   - published_cache │ ⭐ Used by API
-    └─────────────────────┘
-              ↓ HTTP API
-    ┌─────────────────────┐
-    │  Application        │
-    │  - getSection()     │
-    │  - useSection()     │
-    └─────────────────────┘
-```
-
-## API Reference
 
-### Server-side API
+**Returns:** `{ added, updated, removed, unchanged }`
 
-- `getSection(section, locale?)` - Get section labels (auto-detects locale if not specified)
-- `getSections(sections, locale?)` - Get multiple sections (auto-detects locale if not specified)
-- `initLabelSync(options?)` - Sync labels on server startup
-
-### Server Actions API (`@spfn/cms/actions`)
+## Architecture
 
-Available for both server and client components:
+### Database Schema
 
-- `getLocale()` - Get current locale (cookie → browser → default)
-- `setLocale(locale)` - Set locale (saves to cookie)
-- `getLocales()` - Get supported locale list
-- `LOCALE_COOKIE_KEY` - Locale cookie key constant
+```
+cms_labels (metadata)
+  ├─ id, key, section, type, defaultValue
+  └─ publishedVersion
 
-### Configuration API
+cms_label_values (actual content)
+  ├─ labelId, version, locale, breakpoint
+  └─ value (JSONB)
 
-- `getCmsConfig()` - Get current CMS configuration
-- `configureCms(config)` - Update configuration (runtime)
-- `resetCmsConfig()` - Reset configuration to defaults
+cms_published_cache (performance)
+  ├─ section, locale, content (JSONB)
+  └─ version (for cache invalidation)
 
-### Client-side API (`@spfn/cms/client`)
+cms_audit_logs (tracking)
+  └─ action, userId, changes, metadata
+```
 
-- `useSection(section, options?)` - Section labels hook
-- `useSections(sections)` - Multiple sections hook
-- `useCmsStore()` - CMS store hook
-- `cmsApi` - CMS API client
-- `InitCms` - Client initialization component
+### Query Flow
 
-### Sync API
+1. **getLabels()** → published_cache (single query, 5ms)
+2. **Fallback** → bindLocale(defaults)
+3. **Merge** → cache overrides defaults
+4. **Return** → type-safe nested object
 
-- `loadLabelsFromJson(labelsDir)` - Load labels from JSON files
-- `syncAll(sections, options?)` - Sync all sections
-- `syncSection(definition, options?)` - Sync specific section
+## Performance
 
-### Codegen Integration
+- **Published cache:** 5ms (vs 87ms with JOINs) - 17x faster
+- **N+1 prevention:** Bulk section queries with `inArray()`
+- **Section filtering:** Only requested sections processed (10x faster for selective access)
+- **Unchanged labels:** Skipped during sync (deep equality check)
+- **Client caching:** Version-based invalidation
 
-- `createLabelSyncGenerator(config?)` - Generator factory
-- `LabelSyncGenerator` - Generator class
+### Example: Large Scale
 
-## Development Workflow
+```typescript
+// 10 sections with 100 labels each = 1,000 total labels
+const labelsDefinition = {
+    home: { /* 100 labels */ },
+    about: { /* 100 labels */ },
+    products: { /* 100 labels */ },
+    // ... 7 more sections
+};
 
-1. **Create/Edit JSON files** in `src/cms/labels/`
-2. **Auto-sync happens** (if dev server is running)
-3. **Labels immediately available** via `getSection()` or `useSection()`
+// Only request 'home' - direct access
+const label = await getLabel('home');
 
-**Example:**
+// ✅ Performance: Processes only 100 labels (10% of total)
+// ❌ Without filtering: Would process all 1,000 labels
+```
 
-```bash
-# Terminal 1: Start dev server
-pnpm dev
+**Benefits:**
+- CPU usage: 10x reduction (100 vs 1,000 labels)
+- Memory usage: 10x reduction
+- Response time: Proportionally faster
 
-# Terminal 2: Edit label file
-echo '{"test": {"key": "layout.test", "defaultValue": "Test"}}' > src/cms/labels/layout/test.json
+## Development Status
 
-# Auto-sync triggers
-# ✅ Label sync completed
-#    Created: 1
-```
+This package is currently in alpha. APIs may change.
 
 ## License
 
-MIT
+MIT