@spfn/cms 0.1.0-alpha.8 → 0.1.0-alpha.81

package/README.md

@@ -4,94 +4,26 @@ Content Management System for Next.js with JSON-based labels and automatic datab
 
 ## 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**
+- 📁 JSON file-based labels
+- 🔄 Auto-sync to database
+- 🌐 50+ languages support
+- 🍪 Cookie-based locale management
+- 🔥 Hot reload during development
+- 💾 Published cache (17x faster)
+- 📝 Draft system & version control
 
 ## 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)
-
-### Manual Installation
-
-```bash
-pnpm add @spfn/cms
-```
-
-Then run database migrations:
-
-```bash
-pnpm spfn db generate  # Generate migrations
-pnpm spfn db migrate   # Apply migrations
-```
-
-**Note:** Manual installation requires that you have `DATABASE_URL` configured in your `.env.local` file.
-
 ## Quick Start
 
 ### 1. Create Label Files
 
-Create JSON files organized by sections and categories:
-
-```
-src/cms/labels/
-  layout/              ← Section name
-    nav.json           ← Category
-    footer.json
-  home/
-    hero.json
-    features.json
-```
-
-**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"
-  }
-}
-```
-
-**Multi-language example:** `src/cms/labels/home/hero.json`
-
 ```json
+// src/lib/labels/home/hero.json
 {
   "title": {
     "key": "home.hero.title",
@@ -99,66 +31,24 @@ src/cms/labels/
       "ko": "혁신적인 솔루션",
       "en": "Innovative Solutions"
     }
-  },
-  "subtitle": {
-    "key": "home.hero.subtitle",
-    "defaultValue": {
-      "ko": "비즈니스 성장을 위한 최고의 파트너",
-      "en": "Your Best Partner for Business Growth"
-    }
   }
 }
 ```
 
-**Variable substitution:** `src/cms/labels/layout/footer.json`
-
-```json
-{
-  "copyright": {
-    "key": "layout.footer.copyright",
-    "defaultValue": "© {year} Company. All rights reserved."
-  }
-}
-```
-
-### 2. Enable Auto-Sync on Server Startup
-
-Configure `src/server/server.config.ts`:
+### 2. Enable Auto-Sync
 
 ```typescript
-import type { ServerConfig } from '@spfn/core/server';
-import { initLabelSync } from '@spfn/cms';
+// src/server/server.config.ts
+import { initLabelSync } from '@spfn/cms/server';
 
 export default {
   beforeRoutes: async (app) => {
-    await initLabelSync({
-      verbose: true,
-      labelsDir: 'src/cms/labels'  // Optional, this is the default
-    });
+    await initLabelSync({ verbose: true });
   },
 } satisfies ServerConfig;
 ```
 
-### 3. Enable Auto-Sync During Development
-
-Your `.spfnrc.json` should include:
-
-```json
-{
-  "codegen": {
-    "generators": [
-      {
-        "name": "@spfn/cms:label-sync",
-        "enabled": true
-      }
-    ]
-  }
-}
-```
-
-This is automatically configured when you run `pnpm spfn add @spfn/cms`.
-
-### 4. Use Labels in Your App
+### 3. Use in Your App
 
 **Server Component:**
 
@@ -166,22 +56,11 @@ This is automatically configured when you run `pnpm spfn add @spfn/cms`.
 import { getSection } from '@spfn/cms/server';
 
 export default async function HomePage() {
-  const { t } = await getSection('layout', 'ko');
-
-  return <h1>{t('nav.team')}</h1>;
+  const { t } = await getSection('home');
+  return <h1>{t('hero.title')}</h1>;
 }
 ```
 
-**With variable substitution:**
-
-```typescript
-const { t } = await getSection('layout');
-const copyright = t('footer.copyright', undefined, {
-  year: new Date().getFullYear()
-});
-// → "© 2025 Company. All rights reserved."
-```
-
 **Client Component:**
 
 ```typescript
@@ -189,301 +68,34 @@ const copyright = t('footer.copyright', undefined, {
 import { useSection } from '@spfn/cms/client';
 
 export default function Nav() {
-  const { t, loading } = useSection('layout', { autoLoad: true });
-
-  if (loading) return <div>Loading...</div>;
-
-  return (
-    <nav>
-      <a>{t('nav.about')}</a>
-      <a>{t('nav.services')}</a>
-    </nav>
-  );
+  const { t } = useSection('layout', { autoLoad: true });
+  return <nav><a>{t('nav.about')}</a></nav>;
 }
 ```
 
-## File Structure
-
-```
-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
-
-Example:
-```
-src/cms/labels/layout/nav.json:
-  key: "layout.nav.team" → t('nav.team') in code
-```
-
-## JSON Label Format
-
-```typescript
-{
-  "labelName": {
-    "key": "section.category.name",       // Required: Unique identifier
-    "defaultValue": "Text" | {...},       // Required: String or i18n object
-    "description": "Optional description" // Optional: For documentation
-  }
-}
-```
+## Documentation
 
-**Single language:**
-```json
-{
-  "welcome": {
-    "key": "home.welcome",
-    "defaultValue": "Welcome"
-  }
-}
-```
+📖 **[Full Documentation](../../docs/ecosystem/cms/index.md)**
 
-**Multi-language:**
-```json
-{
-  "welcome": {
-    "key": "home.welcome",
-    "defaultValue": {
-      "ko": "환영합니다",
-      "en": "Welcome",
-      "ja": "ようこそ"
-    }
-  }
-}
-```
-
-**Variable placeholders:**
-```json
-{
-  "greeting": {
-    "key": "home.greeting",
-    "defaultValue": "Hello, {name}!"
-  }
-}
-```
-
-Usage:
-```typescript
-t('greeting', undefined, { name: 'John' })
-// → "Hello, John!"
-```
+- [Getting Started](../../docs/ecosystem/cms/getting-started.md) - Setup and configuration
+- [Label Sync Guide](../../docs/ecosystem/cms/label-sync.md) - Auto-sync options
+- [Advanced Features](../../docs/ecosystem/cms/advanced-features.md) - Breakpoints, value types, Draft Mode
+- [Locale Management](../../docs/ecosystem/cms/locale-management.md) - 50+ languages guide
+- [API Reference](../../docs/ecosystem/cms/api-reference.md) - Complete API docs
+- [Draft & Versioning](../../docs/ecosystem/cms/draft-versioning.md) - Version control & audit logs
 
 ## Configuration
 
-### Environment Variables
-
-Configure CMS behavior via environment variables in `.env.local`:
-
 ```bash
-# Default locale (default: 'en')
+# .env.local
 SPFN_CMS_DEFAULT_LOCALE=ko
-
-# Supported locales, comma-separated (default: 'en,ko')
 SPFN_CMS_SUPPORTED_LOCALES=en,ko,ja
-
-# Auto-detect browser language (default: true)
 SPFN_CMS_DETECT_BROWSER_LANGUAGE=true
 ```
 
-### Runtime Configuration
-
-Override configuration at runtime (mainly for testing):
-
-```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
-
-### Automatic Locale Detection
-
-The CMS automatically manages user locale with the following priority:
-
-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
-
-### Server Actions (`@spfn/cms/actions`)
-
-Use Server Actions for locale management in both server and client components:
-
-**Get current locale:**
-
-```typescript
-// Server Component
-import { getLocale } from '@spfn/cms/actions';
-
-export default async function RootLayout({ children }) {
-  const locale = await getLocale();
-
-  return <html lang={locale}>{children}</html>;
-}
-```
-
-```typescript
-// Client Component
-'use client';
-import { getLocale } from '@spfn/cms/actions';
-import { useEffect, useState } from 'react';
-
-export default function LanguageSwitcher() {
-  const [locale, setLocale] = useState('');
-
-  useEffect(() => {
-    getLocale().then(setLocale);
-  }, []);
-
-  return <div>Current: {locale}</div>;
-}
-```
-
-**Change locale:**
-
-```typescript
-import { setLocale } from '@spfn/cms/actions';
-
-async function changeLanguage(newLocale: string) {
-  await setLocale(newLocale);
-  window.location.reload(); // Reload to apply changes
-}
-```
+## Development Status
 
-**Get supported locales:**
-
-```typescript
-import { getLocales } from '@spfn/cms/actions';
-
-const locales = await getLocales(); // ['ko', 'en', 'ja']
-```
-
-### Auto-detect Locale in Server Components
-
-When `locale` is not specified, `getSection()` automatically uses the detected locale:
-
-```typescript
-import { getSection } from '@spfn/cms/server';
-
-// Auto-detects locale from cookie → browser → default
-const { t } = await getSection('home');
-
-// Or explicitly specify locale
-const { t: tEn } = await getSection('home', 'en');
-```
-
-## Documentation
-
-- **[Label Auto-Sync Guide](./LABEL_SYNC_GUIDE.md)** - Detailed configuration guide
-- **[Examples](./examples/)** - Usage examples
-
-## Architecture
-
-```
-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
-
-- `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`)
-
-Available for both server and client components:
-
-- `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
-
-### Configuration API
-
-- `getCmsConfig()` - Get current CMS configuration
-- `configureCms(config)` - Update configuration (runtime)
-- `resetCmsConfig()` - Reset configuration to defaults
-
-### Client-side API (`@spfn/cms/client`)
-
-- `useSection(section, options?)` - Section labels hook
-- `useSections(sections)` - Multiple sections hook
-- `useCmsStore()` - CMS store hook
-- `cmsApi` - CMS API client
-- `InitCms` - Client initialization component
-
-### Sync API
-
-- `loadLabelsFromJson(labelsDir)` - Load labels from JSON files
-- `syncAll(sections, options?)` - Sync all sections
-- `syncSection(definition, options?)` - Sync specific section
-
-### Codegen Integration
-
-- `createLabelSyncGenerator(config?)` - Generator factory
-- `LabelSyncGenerator` - Generator class
-
-## Development Workflow
-
-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()`
-
-**Example:**
-
-```bash
-# Terminal 1: Start dev server
-pnpm dev
-
-# Terminal 2: Edit label file
-echo '{"test": {"key": "layout.test", "defaultValue": "Test"}}' > src/cms/labels/layout/test.json
-
-# Auto-sync triggers
-# ✅ Label sync completed
-#    Created: 1
-```
+This package is currently in alpha. APIs may change.
 
 ## License
 

package/dist/{helpers/locale.actions.d.ts → actions-BEFWwQsh.d.ts}

@@ -1,3 +1,5 @@
+import { f as LocaleInfo } from './locale.constants-BNkSdNP1.js';
+
 /**
  * 현재 locale 가져오기 (Server Action)
  *
@@ -13,7 +15,7 @@
  * @example
  * ```tsx
  * // Server Component
- * import { getLocale } from '@spfn/cms';
+ * import { getLocale } from '@spfn/cms/actions';
  *
  * export default async function Page()
  * {
@@ -40,7 +42,7 @@
  * }
  * ```
  */
-export declare function getLocale(): Promise<string>;
+declare function getLocale(): Promise<string>;
 /**
  * Locale 설정하기 (Server Action)
  *
@@ -53,7 +55,7 @@ export declare function getLocale(): Promise<string>;
  * @example
  * ```tsx
  * // Server Component (Server Action)
- * import { setLocale } from '@spfn/cms';
+ * import { setLocale } from '@spfn/cms/actions';
  *
  * export default async function Page()
  * {
@@ -84,7 +86,7 @@ export declare function getLocale(): Promise<string>;
  * }
  * ```
  */
-export declare function setLocale(locale: string): Promise<void>;
+declare function setLocale(locale: string): Promise<void>;
 /**
  * 지원하는 locale 목록 가져오기 (Server Action)
  *
@@ -95,7 +97,7 @@ export declare function setLocale(locale: string): Promise<void>;
  * @example
  * ```tsx
  * // Server Component
- * import { getLocales } from '@spfn/cms';
+ * import { getLocales } from '@spfn/cms/actions';
  *
  * export default async function Page()
  * {
@@ -128,5 +130,66 @@ export declare function setLocale(locale: string): Promise<void>;
  * }
  * ```
  */
-export declare function getLocales(): Promise<string[]>;
-//# sourceMappingURL=locale.actions.d.ts.map
+declare function getLocales(): Promise<string[]>;
+/**
+ * 현재 locale과 상세 정보 함께 가져오기 (Server Action)
+ *
+ * locale 코드와 함께 국가 코드, 국기, 전화번호 코드 등의 상세 정보를 반환합니다.
+ *
+ * @returns Locale 코드와 LocaleInfo 객체
+ *
+ * @example
+ * ```tsx
+ * // Server Component
+ * import { getLocaleWithInfo } from '@spfn/cms/actions';
+ *
+ * export default async function Page()
+ * {
+ *     const { locale, info } = await getLocaleWithInfo();
+ *
+ *     return (
+ *         <div>
+ *             <span>{info?.flag}</span>
+ *             <span>{info?.nativeName}</span>
+ *             <span>{info?.dialCode}</span>
+ *         </div>
+ *     );
+ * }
+ * ```
+ */
+declare function getLocaleWithInfo(): Promise<{
+    locale: string;
+    info: LocaleInfo | undefined;
+}>;
+/**
+ * 지원하는 모든 locale과 상세 정보 가져오기 (Server Action)
+ *
+ * 시스템이 지원하는 모든 locale의 상세 정보를 배열로 반환합니다.
+ * 언어 선택 UI를 만들 때 유용합니다.
+ *
+ * @returns LocaleInfo 배열
+ *
+ * @example
+ * ```tsx
+ * // Server Component
+ * import { getLocalesWithInfo } from '@spfn/cms/actions';
+ *
+ * export default async function LanguageSelector()
+ * {
+ *     const locales = await getLocalesWithInfo();
+ *
+ *     return (
+ *         <select>
+ *             {locales.map(info => (
+ *                 <option key={info.locale} value={info.locale}>
+ *                     {info.flag} {info.nativeName}
+ *                 </option>
+ *             ))}
+ *         </select>
+ *     );
+ * }
+ * ```
+ */
+declare function getLocalesWithInfo(): Promise<LocaleInfo[]>;
+
+export { getLocales as a, getLocaleWithInfo as b, getLocalesWithInfo as c, getLocale as g, setLocale as s };

package/dist/actions.d.ts

@@ -1,9 +1,2 @@
-/**
- * @spfn/cms/actions
- *
- * Server Actions
- * 서버/클라이언트 컴포넌트 양쪽에서 사용 가능한 Server Actions
- */
-export { getLocale, setLocale, getLocales, } from './helpers/locale.actions.js';
-export { LOCALE_COOKIE_KEY } from './helpers/locale.constants.js';
-//# sourceMappingURL=actions.d.ts.map
+export { g as getLocale, a as getLocales, s as setLocale } from './actions-BEFWwQsh.js';
+export { L as LOCALE_COOKIE_KEY } from './locale.constants-BNkSdNP1.js';