@nextsparkjs/core 0.1.0-beta.7 → 0.1.0-beta.71

package/templates/contents/themes/starter/config/features.config.ts

@@ -0,0 +1,156 @@
+/**
+ * Starter Theme - Features Configuration
+ *
+ * Defines all features of the application for this theme.
+ * Each feature key becomes a tag: @feat-{key}
+ *
+ * Features are enriched at build-time with:
+ * - Entity metadata (from entity-registry)
+ * - Permission details (from permissions-registry)
+ * - Documentation links (from docs-registry)
+ * - Test coverage (from tags-registry + test files)
+ */
+
+import { defineFeatures } from '@nextsparkjs/core/lib/config/features-types'
+
+export default defineFeatures({
+  // ===========================================================================
+  // ENTITY FEATURES
+  // Business entity CRUD features
+  // ===========================================================================
+
+  tasks: {
+    name: 'Tasks',
+    description: 'Task tracking and assignment',
+    category: 'entities',
+    icon: 'check-square',
+    entities: ['tasks'],
+    permissions: ['tasks.*'],
+    docs: [],
+  },
+
+  // ===========================================================================
+  // CONTENT FEATURES
+  // Content creation and editing tools
+  // ===========================================================================
+
+  'page-builder': {
+    name: 'Page Builder',
+    description: 'Visual block editor for page content',
+    category: 'content',
+    icon: 'layout',
+    entities: [],
+    permissions: ['blocks.*'],
+    docs: ['18-page-builder/*'],
+  },
+
+  patterns: {
+    name: 'Patterns',
+    description: 'Reusable block patterns for page builder',
+    category: 'content',
+    icon: 'grid',
+    entities: ['patterns'],
+    permissions: ['patterns.*'],
+    docs: [],
+  },
+
+  // ===========================================================================
+  // CORE FEATURES
+  // Platform-level features that exist in all themes
+  // ===========================================================================
+
+  auth: {
+    name: 'Authentication',
+    description: 'User authentication, sessions, and account security',
+    category: 'core',
+    icon: 'shield',
+    entities: [],
+    permissions: ['auth.*'],
+    docs: ['06-authentication/*'],
+  },
+
+  teams: {
+    name: 'Teams',
+    description: 'Multi-tenant team management and membership',
+    category: 'core',
+    icon: 'users',
+    entities: [],
+    permissions: ['teams.*', 'members.*', 'invitations.*'],
+    docs: ['10-teams/*'],
+  },
+
+  // ===========================================================================
+  // BILLING FEATURES
+  // Plans, subscriptions, and payments
+  // ===========================================================================
+
+  plans: {
+    name: 'Plans',
+    description: 'Plan catalog, comparison, and selection',
+    category: 'settings',
+    icon: 'credit-card',
+    entities: [],
+    permissions: ['plans.*'],
+    docs: ['19-billing/02-configuration.md', '19-billing/07-pricing-strategies.md'],
+  },
+
+  billing: {
+    name: 'Billing',
+    description: 'Subscription management, payments, and invoices',
+    category: 'settings',
+    icon: 'receipt',
+    entities: [],
+    permissions: ['billing.*', 'subscriptions.*', 'invoices.*'],
+    docs: ['19-billing/*'],
+  },
+
+  // ===========================================================================
+  // SETTINGS FEATURES
+  // User and team settings
+  // ===========================================================================
+
+  users: {
+    name: 'User Profile',
+    description: 'User profile management and preferences',
+    category: 'settings',
+    icon: 'user',
+    entities: [],
+    permissions: ['profile.*'],
+    docs: [],
+  },
+
+  'api-keys': {
+    name: 'API Keys',
+    description: 'API key generation and management for integrations',
+    category: 'settings',
+    icon: 'key',
+    entities: [],
+    permissions: ['api-keys.*'],
+    docs: ['05-api/*'],
+  },
+
+  // ===========================================================================
+  // ADMIN FEATURES
+  // Superadmin and developer tools
+  // ===========================================================================
+
+  superadmin: {
+    name: 'Superadmin',
+    description: 'Superadmin dashboard and system management',
+    category: 'admin',
+    icon: 'shield-check',
+    entities: [],
+    permissions: ['superadmin.*'],
+    docs: ['19-restricted-zones/02-admin.md'],
+  },
+
+  devtools: {
+    name: 'Developer Tools',
+    description: 'Development tools, test viewers, and configuration inspectors',
+    category: 'admin',
+    icon: 'terminal',
+    entities: [],
+    permissions: ['developer.*'],
+    docs: ['19-restricted-zones/03-devtools.md'],
+  },
+})

package/templates/contents/themes/starter/config/permissions.config.ts

@@ -47,6 +47,17 @@ export const PERMISSIONS_CONFIG_OVERRIDES: ThemePermissionsConfig = {
   // ==========================================
   // Define CRUD permissions for each entity in your theme
   entities: {
+    // ------------------------------------------
+    // PATTERNS ENTITY (Core entity - reusable block compositions)
+    // ------------------------------------------
+    patterns: [
+      { action: 'create', label: 'Create Patterns', description: 'Can create reusable patterns', roles: ['owner', 'admin'] },
+      { action: 'read', label: 'View Patterns', description: 'Can view pattern details', roles: ['owner', 'admin', 'member', 'viewer'] },
+      { action: 'list', label: 'List Patterns', description: 'Can see the patterns list', roles: ['owner', 'admin', 'member', 'viewer'] },
+      { action: 'update', label: 'Edit Patterns', description: 'Can modify patterns', roles: ['owner', 'admin'] },
+      { action: 'delete', label: 'Delete Patterns', description: 'Can delete patterns', roles: ['owner', 'admin'], dangerous: true },
+    ],
+
     // ------------------------------------------
     // TASKS ENTITY
     // ------------------------------------------
@@ -58,6 +69,34 @@ export const PERMISSIONS_CONFIG_OVERRIDES: ThemePermissionsConfig = {
       { action: 'delete', label: 'Delete tasks', description: 'Can delete tasks', roles: ['owner', 'admin'], dangerous: true },
       { action: 'assign', label: 'Assign tasks', description: 'Can assign tasks to team members', roles: ['owner', 'admin'] },
     ],
+
+    // ------------------------------------------
+    // PAGES ENTITY (uncommented by CLI if pages feature enabled)
+    // ------------------------------------------
+    // __PAGES_PERMISSIONS_START__
+    // pages: [
+    //   { action: 'create', label: 'Create Pages', description: 'Can create new pages', roles: ['owner', 'admin'] },
+    //   { action: 'read', label: 'View Pages', description: 'Can view page details', roles: ['owner', 'admin', 'member', 'viewer'] },
+    //   { action: 'list', label: 'List Pages', description: 'Can see the pages list', roles: ['owner', 'admin', 'member', 'viewer'] },
+    //   { action: 'update', label: 'Edit Pages', description: 'Can modify page content', roles: ['owner', 'admin'] },
+    //   { action: 'delete', label: 'Delete Pages', description: 'Can delete pages', roles: ['owner', 'admin'], dangerous: true },
+    //   { action: 'publish', label: 'Publish Pages', description: 'Can publish pages to make them public', roles: ['owner', 'admin'] },
+    // ],
+    // __PAGES_PERMISSIONS_END__
+
+    // ------------------------------------------
+    // POSTS ENTITY (uncommented by CLI if blog feature enabled)
+    // ------------------------------------------
+    // __POSTS_PERMISSIONS_START__
+    // posts: [
+    //   { action: 'create', label: 'Create Posts', description: 'Can create new blog posts', roles: ['owner', 'admin', 'member'] },
+    //   { action: 'read', label: 'View Posts', description: 'Can view post details', roles: ['owner', 'admin', 'member', 'viewer'] },
+    //   { action: 'list', label: 'List Posts', description: 'Can see the posts list', roles: ['owner', 'admin', 'member', 'viewer'] },
+    //   { action: 'update', label: 'Edit Posts', description: 'Can modify post content', roles: ['owner', 'admin', 'member'] },
+    //   { action: 'delete', label: 'Delete Posts', description: 'Can delete posts', roles: ['owner', 'admin'], dangerous: true },
+    //   { action: 'publish', label: 'Publish Posts', description: 'Can publish posts to make them public', roles: ['owner', 'admin'] },
+    // ],
+    // __POSTS_PERMISSIONS_END__
   },
 }
 

package/templates/contents/themes/starter/docs/superadmin/01-setup/01-configuration.md

@@ -0,0 +1,31 @@
+# Admin Configuration
+
+This guide covers the configuration options available to administrators.
+
+## Environment Variables
+
+Configure your application through environment variables:
+
+```bash
+# Database
+DATABASE_URL="postgresql://..."
+
+# Authentication
+BETTER_AUTH_SECRET="your-secret"
+
+# Application
+NEXT_PUBLIC_APP_URL="https://your-domain.com"
+```
+
+## Configuration Files
+
+Customize your application through config files in `config/`:
+
+- `app.config.ts` - Main application settings
+- `permissions.config.ts` - Roles and permissions
+- `billing.config.ts` - Subscription plans
+- `dev.config.ts` - Development settings
+
+## Next Steps
+
+Refer to the main documentation for detailed guides on each configuration area.

package/templates/contents/themes/starter/docs/superadmin/02-entities/01-tasks.md

@@ -0,0 +1,176 @@
+---
+title: Tasks Management
+description: Guide for administrators to manage the tasks entity in the application.
+---
+
+# Tasks Management
+
+Tasks are the core entity in this starter theme. This guide covers administrative operations for managing tasks across all users and teams.
+
+## Overview
+
+The tasks entity provides:
+
+- **CRUD Operations**: Create, read, update, and delete tasks
+- **Team Scoping**: Tasks are automatically scoped to the user's active team
+- **Status Tracking**: Track task progress through customizable statuses
+- **Assignment**: Assign tasks to team members
+
+## Entity Configuration
+
+Tasks are configured in the theme's entity definition:
+
+```typescript
+// entities/tasks/config.ts
+export const tasksConfig = {
+  slug: 'tasks',
+  names: {
+    singular: 'Task',
+    plural: 'Tasks'
+  },
+  fields: [
+    { name: 'title', type: 'text', required: true },
+    { name: 'description', type: 'textarea' },
+    { name: 'status', type: 'select', options: ['pending', 'in_progress', 'completed'] },
+    { name: 'dueDate', type: 'date' },
+    { name: 'assignedTo', type: 'relation', target: 'users' }
+  ]
+}
+```
+
+## Admin Operations
+
+### Viewing All Tasks
+
+As a superadmin, you can view tasks across all teams:
+
+1. Navigate to **Superadmin > Dashboard**
+2. Access the tasks overview panel
+3. Use filters to narrow by team, status, or date range
+
+### Bulk Operations
+
+Perform bulk actions on multiple tasks:
+
+```typescript
+// API: Bulk status update
+POST /api/v1/tasks/bulk
+{
+  "ids": ["task-1", "task-2", "task-3"],
+  "action": "updateStatus",
+  "data": { "status": "completed" }
+}
+```
+
+### Data Export
+
+Export task data for reporting:
+
+1. Go to **Superadmin > Tasks**
+2. Apply desired filters
+3. Click **Export** and select format (CSV, JSON)
+
+## Database Schema
+
+The tasks table structure:
+
+| Column | Type | Description |
+|--------|------|-------------|
+| id | uuid | Primary key |
+| title | varchar(255) | Task title |
+| description | text | Detailed description |
+| status | varchar(50) | Current status |
+| dueDate | timestamp | Due date (optional) |
+| assignedTo | uuid | FK to users table |
+| teamId | uuid | FK to teams table |
+| createdBy | uuid | FK to users table |
+| createdAt | timestamp | Creation timestamp |
+| updatedAt | timestamp | Last update |
+
+## API Endpoints
+
+### List Tasks (Admin)
+
+```bash
+GET /api/v1/tasks?teamId=all
+Authorization: Bearer {admin-token}
+```
+
+### Get Task Statistics
+
+```bash
+GET /api/v1/tasks/stats
+Authorization: Bearer {admin-token}
+```
+
+Response:
+
+```json
+{
+  "total": 150,
+  "byStatus": {
+    "pending": 45,
+    "in_progress": 30,
+    "completed": 75
+  },
+  "overdue": 12
+}
+```
+
+## Permissions
+
+Task-related permissions for team roles:
+
+| Permission | Owner | Admin | Member | Viewer |
+|------------|-------|-------|--------|--------|
+| tasks.create | Yes | Yes | Yes | No |
+| tasks.read | Yes | Yes | Yes | Yes |
+| tasks.update | Yes | Yes | Own | No |
+| tasks.delete | Yes | Yes | No | No |
+
+## Customization
+
+### Adding Custom Fields
+
+Extend the tasks entity with custom fields:
+
+1. Update the entity config
+2. Create a migration for new columns
+3. Update the form schema
+
+### Custom Statuses
+
+Modify available statuses in the entity configuration:
+
+```typescript
+{
+  name: 'status',
+  type: 'select',
+  options: [
+    { value: 'backlog', label: 'Backlog' },
+    { value: 'todo', label: 'To Do' },
+    { value: 'in_progress', label: 'In Progress' },
+    { value: 'review', label: 'In Review' },
+    { value: 'done', label: 'Done' }
+  ]
+}
+```
+
+## Troubleshooting
+
+### Tasks Not Appearing
+
+- Verify the user has `tasks.read` permission
+- Check that the team filter is correct
+- Ensure RLS policies are properly configured
+
+### Assignment Issues
+
+- Confirm the assignee is a member of the same team
+- Verify the `users` relation is properly configured
+
+## Related
+
+- [Entity System](/docs/entities/overview)
+- [Permissions](/docs/permissions/overview)
+- [API Reference](/docs/api/entities)

package/templates/contents/themes/starter/entities/pages/api/docs.md

@@ -0,0 +1,120 @@
+# Pages API
+
+Manage builder-enabled pages in the system. Pages render at root URLs (e.g., /about, /contact) and support the page builder for content creation.
+
+## Overview
+
+The Pages API allows you to create, read, update, and delete pages with builder content. Pages are public content and can be accessed by all authenticated users.
+
+## Authentication
+
+All endpoints require authentication via:
+- **Session cookie** (for browser-based requests)
+- **API Key** header (for server-to-server requests)
+
+## Endpoints
+
+### List Pages
+`GET /api/v1/pages`
+
+Returns a paginated list of pages.
+
+**Query Parameters:**
+- `limit` (number, optional): Maximum records to return. Default: 20
+- `offset` (number, optional): Number of records to skip. Default: 0
+- `status` (string, optional): Filter by status (draft, published, scheduled, archived)
+- `locale` (string, optional): Filter by locale (en, es)
+- `search` (string, optional): Search term for title/slug
+- `sortBy` (string, optional): Field to sort by
+- `sortOrder` (string, optional): Sort direction (asc, desc)
+
+**Example Response:**
+```json
+{
+  "data": [
+    {
+      "id": "page_123",
+      "title": "About Us",
+      "slug": "about",
+      "status": "published",
+      "locale": "en",
+      "blocks": [...],
+      "createdAt": "2024-01-15T10:30:00Z"
+    }
+  ],
+  "pagination": {
+    "total": 15,
+    "limit": 20,
+    "offset": 0
+  }
+}
+```
+
+### Get Single Page
+`GET /api/v1/pages/[id]`
+
+Returns a single page by ID.
+
+**Path Parameters:**
+- `id` (string, required): Page ID
+
+### Create Page
+`POST /api/v1/pages`
+
+Create a new page record.
+
+**Request Body:**
+```json
+{
+  "title": "Contact Us",
+  "slug": "contact",
+  "status": "draft",
+  "locale": "en",
+  "blocks": []
+}
+```
+
+### Update Page
+`PATCH /api/v1/pages/[id]`
+
+Update an existing page.
+
+**Path Parameters:**
+- `id` (string, required): Page ID
+
+**Request Body:**
+Any fields to update (partial update supported).
+
+### Delete Page
+`DELETE /api/v1/pages/[id]`
+
+Delete a page record.
+
+**Path Parameters:**
+- `id` (string, required): Page ID
+
+## Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| title | text | Yes | Page title |
+| slug | text | Yes | URL-friendly identifier |
+| status | select | Yes | draft, published, scheduled, archived |
+| locale | select | Yes | en, es |
+| blocks | json | No | Page builder content |
+
+## Error Responses
+
+| Status | Description |
+|--------|-------------|
+| 400 | Bad Request - Invalid parameters |
+| 401 | Unauthorized - Missing or invalid auth |
+| 403 | Forbidden - Insufficient permissions |
+| 404 | Not Found - Page doesn't exist |
+| 422 | Validation Error - Invalid data |
+
+## Related APIs
+
+- **[Dynamic Entity API](/api/v1/{entity})** - Generic entity operations documentation
+- **[Blocks](/api/v1/blocks)** - Available page builder blocks
+- **[Media](/api/v1/media)** - Upload images for pages

package/templates/contents/themes/starter/entities/pages/api/presets.ts

@@ -0,0 +1,72 @@
+/**
+ * API Presets for Pages Entity
+ *
+ * These presets appear in the DevTools API Explorer's "Presets" tab.
+ * The endpoint is automatically derived from the entity name: /api/v1/pages
+ */
+
+import { defineApiEndpoint } from '@nextsparkjs/core/types/api-presets'
+
+export default defineApiEndpoint({
+  summary: 'Manage builder-enabled pages',
+  presets: [
+    {
+      id: 'list-all',
+      title: 'List All Pages',
+      description: 'Fetch all pages with default pagination',
+      method: 'GET',
+      params: {
+        limit: 10,
+        offset: 0
+      },
+      tags: ['read', 'list']
+    },
+    {
+      id: 'list-published',
+      title: 'List Published Pages',
+      description: 'Fetch only published pages',
+      method: 'GET',
+      params: {
+        status: 'published',
+        limit: 20
+      },
+      tags: ['read', 'filter']
+    },
+    {
+      id: 'list-by-locale',
+      title: 'List Spanish Pages',
+      description: 'Fetch pages in Spanish locale',
+      method: 'GET',
+      params: {
+        locale: 'es',
+        limit: 10
+      },
+      tags: ['read', 'filter', 'i18n']
+    },
+    {
+      id: 'create-draft',
+      title: 'Create Draft Page',
+      description: 'Create a new page as draft',
+      method: 'POST',
+      payload: {
+        title: 'New Page',
+        slug: 'new-page',
+        status: 'draft',
+        locale: 'en',
+        blocks: []
+      },
+      tags: ['write', 'create']
+    },
+    {
+      id: 'search-title',
+      title: 'Search by Title',
+      description: 'Search pages by title',
+      method: 'GET',
+      params: {
+        search: 'About',
+        searchField: 'title'
+      },
+      tags: ['read', 'search']
+    }
+  ]
+})

package/templates/contents/themes/starter/entities/pages/messages/en.json

@@ -0,0 +1,41 @@
+{
+  "entity": {
+    "singular": "Page",
+    "plural": "Pages"
+  },
+  "fields": {
+    "title": {
+      "label": "Title",
+      "placeholder": "Enter page title...",
+      "description": "Page title displayed in browser and navigation"
+    },
+    "slug": {
+      "label": "Slug",
+      "placeholder": "page-slug",
+      "description": "URL-friendly identifier (e.g., 'about' for /about)"
+    },
+    "status": {
+      "label": "Status",
+      "description": "Publication status",
+      "options": {
+        "draft": "Draft",
+        "published": "Published",
+        "scheduled": "Scheduled",
+        "archived": "Archived"
+      }
+    }
+  },
+  "actions": {
+    "create": "Create Page",
+    "edit": "Edit Page",
+    "delete": "Delete Page",
+    "publish": "Publish",
+    "unpublish": "Unpublish"
+  },
+  "messages": {
+    "created": "Page created successfully",
+    "updated": "Page updated successfully",
+    "deleted": "Page deleted successfully",
+    "published": "Page published successfully"
+  }
+}

package/templates/contents/themes/starter/entities/pages/messages/es.json

@@ -0,0 +1,41 @@
+{
+  "entity": {
+    "singular": "Pagina",
+    "plural": "Paginas"
+  },
+  "fields": {
+    "title": {
+      "label": "Titulo",
+      "placeholder": "Ingresa el titulo de la pagina...",
+      "description": "Titulo de la pagina mostrado en el navegador y navegacion"
+    },
+    "slug": {
+      "label": "Slug",
+      "placeholder": "slug-pagina",
+      "description": "Identificador amigable para URL (ej: 'acerca' para /acerca)"
+    },
+    "status": {
+      "label": "Estado",
+      "description": "Estado de publicacion",
+      "options": {
+        "draft": "Borrador",
+        "published": "Publicado",
+        "scheduled": "Programado",
+        "archived": "Archivado"
+      }
+    }
+  },
+  "actions": {
+    "create": "Crear Pagina",
+    "edit": "Editar Pagina",
+    "delete": "Eliminar Pagina",
+    "publish": "Publicar",
+    "unpublish": "Despublicar"
+  },
+  "messages": {
+    "created": "Pagina creada exitosamente",
+    "updated": "Pagina actualizada exitosamente",
+    "deleted": "Pagina eliminada exitosamente",
+    "published": "Pagina publicada exitosamente"
+  }
+}