@nextsparkjs/core 0.1.0-beta.1 → 0.1.0-beta.3

package/dist/templates/features/pages/entities/pages/pages.config.ts

@@ -0,0 +1,105 @@
+/**
+ * Pages Entity Configuration
+ *
+ * Pages are builder-enabled entities that render at root URLs (e.g., /about, /contact).
+ * This configuration enables the WordPress-like page builder experience for content creation.
+ */
+
+import { FileText } from 'lucide-react'
+import type { EntityConfig } from '@nextsparkjs/core/lib/entities/types'
+import { pagesFields } from './pages.fields'
+
+export const pagesEntityConfig: EntityConfig = {
+  // ==========================================
+  // 1. BASIC IDENTIFICATION
+  // ==========================================
+  slug: 'pages',
+  enabled: true,
+
+  names: {
+    singular: 'page',
+    plural: 'Pages',
+  },
+
+  icon: FileText,
+  tableName: 'pages',
+
+  // ==========================================
+  // 2. ACCESS AND SCOPE CONFIGURATION
+  // ==========================================
+  access: {
+    public: true,    // Pages are public content
+    api: true,       // Has external API endpoints
+    metadata: false, // Pages don't use metadata system
+    shared: true,    // All authenticated users can see all pages
+    basePath: '/',   // Pages render at root: /about, /contact, etc.
+  },
+
+  // ==========================================
+  // 3. UI/UX FEATURES
+  // ==========================================
+  ui: {
+    dashboard: {
+      showInMenu: true,
+      showInTopbar: true,
+      filters: [
+        { field: 'status', type: 'multiSelect' },
+      ],
+    },
+    public: {
+      hasArchivePage: false, // Pages don't have an archive page
+      hasSinglePage: true,   // Individual pages render at /[slug]
+    },
+    features: {
+      searchable: true,
+      sortable: true,
+      filterable: true,
+      bulkOperations: true,
+      importExport: false,
+    },
+  },
+
+  // ==========================================
+  // 4. PERMISSIONS SYSTEM
+  // ==========================================
+  // Permissions are now centralized in permissions.config.ts
+  // See: contents/themes/default/permissions.config.ts -> entities.pages
+
+  // ==========================================
+  // 5. INTERNATIONALIZATION
+  // ==========================================
+  i18n: {
+    fallbackLocale: 'en',
+    loaders: {
+      en: () => import('./messages/en.json'),
+      es: () => import('./messages/es.json'),
+    },
+  },
+
+  // ==========================================
+  // 6. BUILDER CONFIGURATION
+  // ==========================================
+  builder: {
+    enabled: true,
+    sidebarFields: ['locale'], // Pages don't have extra sidebar fields beyond basic settings
+    seo: true, // Enable SEO fields panel in editor
+  },
+
+  // ==========================================
+  // 7. TAXONOMIES CONFIGURATION
+  // ==========================================
+  taxonomies: {
+    enabled: false, // Pages don't use taxonomies by default
+    types: [],
+  },
+
+  // ==========================================
+  // FIELDS
+  // ==========================================
+  fields: pagesFields,
+
+  // ==========================================
+  // METADATA
+  // ==========================================
+  source: 'theme',
+}

package/dist/templates/features/pages/entities/pages/pages.fields.ts

@@ -0,0 +1,101 @@
+/**
+ * Pages Entity Fields Configuration
+ *
+ * Fields required for builder-enabled pages.
+ * Note: 'blocks' field is NOT in fields[] - it's managed by the builder view automatically.
+ */
+
+import type { EntityField } from '@nextsparkjs/core/lib/entities/types'
+
+export const pagesFields: EntityField[] = [
+  {
+    name: 'title',
+    type: 'text',
+    required: true,
+    display: {
+      label: 'Title',
+      description: 'Page title',
+      placeholder: 'Enter page title...',
+      showInList: true,
+      showInDetail: true,
+      showInForm: true,
+      order: 1,
+    },
+    api: {
+      searchable: true,
+      sortable: true,
+      readOnly: false,
+    },
+  },
+  {
+    name: 'slug',
+    type: 'text',
+    required: true,
+    display: {
+      label: 'Slug',
+      description: 'URL-friendly identifier',
+      placeholder: 'page-slug',
+      showInList: true,
+      showInDetail: true,
+      showInForm: true,
+      order: 2,
+    },
+    api: {
+      searchable: true,
+      sortable: true,
+      readOnly: false,
+    },
+  },
+  {
+    name: 'status',
+    type: 'select',
+    required: true,
+    defaultValue: 'draft',
+    options: [
+      { value: 'draft', label: 'Draft' },
+      { value: 'published', label: 'Published' },
+      { value: 'scheduled', label: 'Scheduled' },
+      { value: 'archived', label: 'Archived' },
+    ],
+    display: {
+      label: 'Status',
+      description: 'Publication status',
+      showInList: true,
+      showInDetail: true,
+      showInForm: true,
+      order: 3,
+    },
+    api: {
+      searchable: false,
+      sortable: true,
+      filterable: true,
+      readOnly: false,
+    },
+  },
+  {
+    name: 'locale',
+    type: 'select',
+    required: true,
+    defaultValue: 'en',
+    options: [
+      { value: 'en', label: 'English' },
+      { value: 'es', label: 'Español' },
+    ],
+    display: {
+      label: 'Locale',
+      description: 'Page language',
+      showInList: true,
+      showInDetail: true,
+      showInForm: true,
+      order: 4,
+    },
+    api: {
+      searchable: false,
+      sortable: true,
+      filterable: true,
+      readOnly: false,
+    },
+  },
+  // Note: SEO fields (seoTitle, seoDescription, etc.) are managed by the builder SEO panel
+  // Note: 'blocks' field is a system field for builder-enabled entities - NOT defined here
+]

package/dist/templates/features/pages/entities/pages/pages.service.ts

@@ -0,0 +1,290 @@
+/**
+ * Pages Service
+ *
+ * Provides data access methods for pages, separating public queries
+ * (without RLS) from authenticated queries (with RLS).
+ *
+ * @module PagesService
+ */
+
+import { query, queryOne, queryOneWithRLS } from '@nextsparkjs/core/lib/db'
+import type {
+  PagePublic,
+  PageMetadata,
+  PageListOptions,
+  PageListResult,
+  Block,
+} from './pages.types'
+
+// Database row type for page
+interface DbPage {
+  id: string
+  slug: string
+  title: string
+  blocks: Block[]
+  locale: string
+  status: string
+  createdAt: string
+}
+
+// Database row type for metadata query
+interface DbPageMetadata {
+  title: string
+  seoTitle: string | null
+  seoDescription: string | null
+  ogImage: string | null
+}
+
+export class PagesService {
+  // ============================================
+  // PUBLIC METHODS (sin RLS)
+  // ============================================
+
+  /**
+   * Get a published page by slug
+   *
+   * Fetches the full page data including blocks.
+   * Only returns published pages.
+   *
+   * @param slug - Page slug
+   * @param locale - Optional locale filter (defaults to 'en')
+   * @returns Page data or null if not found/not published
+   *
+   * @example
+   * const page = await PagesService.getPublishedBySlug('about')
+   * if (!page) notFound()
+   */
+  static async getPublishedBySlug(
+    slug: string,
+    locale: string = 'en'
+  ): Promise<PagePublic | null> {
+    try {
+      if (!slug || slug.trim() === '') {
+        throw new Error('Page slug is required')
+      }
+
+      const page = await queryOne<DbPage>(
+        `
+        SELECT
+          id,
+          slug,
+          title,
+          blocks,
+          locale,
+          status,
+          "createdAt"
+        FROM pages
+        WHERE slug = $1 AND status = 'published' AND locale = $2
+        `,
+        [slug, locale]
+      )
+
+      if (!page) {
+        return null
+      }
+
+      return {
+        id: page.id,
+        slug: page.slug,
+        title: page.title,
+        blocks: page.blocks,
+        locale: page.locale,
+      }
+    } catch (error) {
+      console.error('PagesService.getPublishedBySlug error:', error)
+      throw new Error(
+        error instanceof Error ? error.message : 'Failed to fetch page'
+      )
+    }
+  }
+
+  /**
+   * Get page metadata for SEO/head tags
+   *
+   * Lightweight query that only fetches SEO-related fields.
+   * Used in generateMetadata for better performance.
+   *
+   * @param slug - Page slug
+   * @param locale - Optional locale filter (defaults to 'en')
+   * @returns Metadata or null if not found/not published
+   *
+   * @example
+   * const metadata = await PagesService.getPublishedMetadata('about')
+   * return { title: metadata?.seoTitle || metadata?.title }
+   */
+  static async getPublishedMetadata(
+    slug: string,
+    locale: string = 'en'
+  ): Promise<PageMetadata | null> {
+    try {
+      if (!slug || slug.trim() === '') {
+        throw new Error('Page slug is required')
+      }
+
+      const result = await query<DbPageMetadata>(
+        `
+        SELECT
+          title,
+          "seoTitle",
+          "seoDescription",
+          "ogImage"
+        FROM pages
+        WHERE slug = $1 AND status = 'published' AND locale = $2
+        `,
+        [slug, locale]
+      )
+
+      if (result.rows.length === 0) {
+        return null
+      }
+
+      const page = result.rows[0]
+
+      return {
+        title: page.title,
+        seoTitle: page.seoTitle ?? undefined,
+        seoDescription: page.seoDescription ?? undefined,
+        ogImage: page.ogImage ?? undefined,
+      }
+    } catch (error) {
+      console.error('PagesService.getPublishedMetadata error:', error)
+      throw new Error(
+        error instanceof Error ? error.message : 'Failed to fetch page metadata'
+      )
+    }
+  }
+
+  /**
+   * List published pages with pagination
+   *
+   * @param options - List options (limit, offset, locale, orderBy, orderDir)
+   * @returns Object with pages array and total count
+   *
+   * @example
+   * const { pages, total } = await PagesService.listPublished({ limit: 10 })
+   */
+  static async listPublished(
+    options: PageListOptions = {}
+  ): Promise<PageListResult> {
+    try {
+      const {
+        limit = 10,
+        offset = 0,
+        locale = 'en',
+        orderBy = 'createdAt',
+        orderDir = 'desc',
+      } = options
+
+      // Validate orderBy to prevent SQL injection
+      const validOrderBy = ['createdAt', 'title'].includes(orderBy) ? orderBy : 'createdAt'
+      const validOrderDir = orderDir === 'asc' ? 'ASC' : 'DESC'
+      const orderColumn = validOrderBy === 'createdAt' ? '"createdAt"' : 'title'
+
+      // Get total count
+      const countResult = await query<{ count: string }>(
+        `SELECT COUNT(*)::text as count FROM pages WHERE status = 'published' AND locale = $1`,
+        [locale]
+      )
+      const total = parseInt(countResult.rows[0]?.count || '0', 10)
+
+      // Get pages
+      const pagesResult = await query<DbPage>(
+        `
+        SELECT
+          id,
+          slug,
+          title,
+          blocks,
+          locale,
+          status,
+          "createdAt"
+        FROM pages
+        WHERE status = 'published' AND locale = $1
+        ORDER BY ${orderColumn} ${validOrderDir}
+        LIMIT $2 OFFSET $3
+        `,
+        [locale, limit, offset]
+      )
+
+      const pages: PagePublic[] = pagesResult.rows.map((page) => ({
+        id: page.id,
+        slug: page.slug,
+        title: page.title,
+        blocks: page.blocks,
+        locale: page.locale,
+      }))
+
+      return { pages, total }
+    } catch (error) {
+      console.error('PagesService.listPublished error:', error)
+      throw new Error(
+        error instanceof Error ? error.message : 'Failed to list pages'
+      )
+    }
+  }
+
+  // ============================================
+  // AUTHENTICATED METHODS (con RLS)
+  // ============================================
+
+  /**
+   * Get a page by ID (authenticated)
+   *
+   * For dashboard/admin views. Respects RLS policies.
+   *
+   * @param id - Page ID
+   * @param userId - Current user ID for RLS
+   * @returns Page data or null if not found/not authorized
+   *
+   * @example
+   * const page = await PagesService.getById('page-uuid', currentUserId)
+   */
+  static async getById(
+    id: string,
+    userId: string
+  ): Promise<PagePublic | null> {
+    try {
+      if (!id || id.trim() === '') {
+        throw new Error('Page ID is required')
+      }
+
+      if (!userId || userId.trim() === '') {
+        throw new Error('User ID is required for authentication')
+      }
+
+      const page = await queryOneWithRLS<DbPage>(
+        `
+        SELECT
+          id,
+          slug,
+          title,
+          blocks,
+          locale,
+          status,
+          "createdAt"
+        FROM pages
+        WHERE id = $1
+        `,
+        [id],
+        userId
+      )
+
+      if (!page) {
+        return null
+      }
+
+      return {
+        id: page.id,
+        slug: page.slug,
+        title: page.title,
+        blocks: page.blocks,
+        locale: page.locale,
+      }
+    } catch (error) {
+      console.error('PagesService.getById error:', error)
+      throw new Error(
+        error instanceof Error ? error.message : 'Failed to fetch page'
+      )
+    }
+  }
+}

package/dist/templates/features/pages/entities/pages/pages.types.ts

@@ -0,0 +1,124 @@
+/**
+ * Pages Service Types
+ *
+ * Type definitions for the PagesService.
+ * Separates public types (for rendering) from internal types.
+ *
+ * @module PagesTypes
+ */
+
+/**
+ * Block structure for page builder content
+ */
+export interface Block {
+  id: string
+  blockSlug: string
+  props: Record<string, unknown>
+}
+
+/**
+ * Page data for public rendering
+ * Includes blocks for full page display
+ */
+export interface PagePublic {
+  id: string
+  slug: string
+  title: string
+  blocks: Block[]
+  locale: string
+}
+
+/**
+ * Lightweight page metadata for SEO/head tags
+ * Does not include blocks
+ */
+export interface PageMetadata {
+  title: string
+  seoTitle?: string
+  seoDescription?: string
+  ogImage?: string
+}
+
+/**
+ * Options for listing published pages
+ */
+export interface PageListOptions {
+  limit?: number
+  offset?: number
+  locale?: string
+  orderBy?: 'createdAt' | 'title'
+  orderDir?: 'asc' | 'desc'
+}
+
+/**
+ * Result of listing pages with pagination
+ */
+export interface PageListResult {
+  pages: PagePublic[]
+  total: number
+}
+
+// ============================================
+// MANAGEMENT TYPES (for authenticated CRUD)
+// ============================================
+
+/**
+ * Full page data including status and SEO fields
+ * Used for dashboard/admin operations
+ */
+export interface PageFull extends PagePublic {
+  status: 'draft' | 'published'
+  seoTitle?: string
+  seoDescription?: string
+  ogImage?: string
+  createdAt: string
+  updatedAt: string
+}
+
+/**
+ * Data for creating a new page
+ */
+export interface PageCreateData {
+  slug: string
+  title: string
+  blocks?: Block[]
+  locale?: string
+  status?: 'draft' | 'published'
+  seoTitle?: string
+  seoDescription?: string
+  ogImage?: string
+  teamId: string
+}
+
+/**
+ * Data for updating a page (metadata only, not blocks)
+ */
+export interface PageUpdateData {
+  slug?: string
+  title?: string
+  status?: 'draft' | 'published'
+  seoTitle?: string
+  seoDescription?: string
+  ogImage?: string
+}
+
+/**
+ * Options for listing pages in management context
+ */
+export interface PageManagementListOptions {
+  limit?: number
+  offset?: number
+  locale?: string
+  status?: 'draft' | 'published' | 'all'
+  orderBy?: 'createdAt' | 'updatedAt' | 'title'
+  orderDir?: 'asc' | 'desc'
+  teamId?: string
+}
+
+/**
+ * Result of listing pages in management context
+ */
+export interface PageManagementListResult {
+  pages: PageFull[]
+  total: number
+}

package/package.json

@@ -1,7 +1,32 @@
 {
   "name": "@nextsparkjs/core",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.3",
   "description": "NextSpark - The complete SaaS framework for Next.js",
+  "license": "MIT",
+  "author": "NextSpark <hello@nextspark.dev>",
+  "homepage": "https://nextspark.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NextSpark-js/nextspark.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/NextSpark-js/nextspark/issues"
+  },
+  "keywords": [
+    "nextjs",
+    "saas",
+    "boilerplate",
+    "starter",
+    "framework",
+    "authentication",
+    "stripe",
+    "payments",
+    "teams",
+    "typescript",
+    "react",
+    "tailwindcss"
+  ],
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -191,10 +216,11 @@
     "nextspark": "./bin/dist/init.js"
   },
   "scripts": {
-    "build": "tsup && pnpm build:dts && pnpm build:ui-css",
+    "build": "tsup && pnpm build:dts && pnpm build:ui-css && pnpm build:cli",
     "build:js": "tsup",
     "build:dts": "tsc -p tsconfig.dts.json || echo '⚠️  DTS generation completed with some type errors (partial coverage)'",
     "build:ui-css": "node scripts/build/build-ui-css.mjs",
+    "build:cli": "tsc -p bin/tsconfig.json",
     "dev": "tsup --watch",
     "test": "jest",
     "test:watch": "jest --watch",
@@ -218,11 +244,16 @@
     "jest-environment-jsdom": "^29.7.0",
     "@tailwindcss/cli": "^4",
     "tailwindcss": "^4",
+    "@types/fs-extra": "^11.0.4",
     "ts-jest": "^29.2.5",
     "tsup": "^8.5.1",
     "typescript": "^5"
   },
   "dependencies": {
+    "@inquirer/prompts": "^7.2.0",
+    "chalk": "^5.4.1",
+    "fs-extra": "^11.2.0",
+    "ora": "^8.1.1",
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",