@nextsparkjs/theme-default 0.1.0-beta.28 → 0.1.0-beta.29

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 NextSpark
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/config/app.config.ts

@@ -91,78 +91,51 @@ export const APP_CONFIG_OVERRIDES = {
   // =============================================================================
   // DOCUMENTATION CONFIGURATION
   // =============================================================================
+  /**
+   * Documentation system configuration
+   *
+   * Structure:
+   * - public: User-facing documentation at /docs
+   * - superadmin: Admin documentation at /superadmin/docs
+   *
+   * NOTE: Plugin docs are NOT in the registry - they are for developer reference only (IDE/LLM).
+   */
   docs: {
-    /**
-     * Enable/disable documentation system
-     */
+    /** Enable/disable documentation system */
     enabled: true,
 
-    /**
-     * Public access to documentation
-     * - true: Documentation accessible without authentication
-     * - false: Requires user to be logged in
-     */
-    public: true,
+    /** Make public documentation accessible without authentication */
+    publicAccess: true,
 
-    /**
-     * Enable search functionality in documentation
-     */
+    /** Enable search functionality in documentation */
     searchEnabled: true,
 
-    /**
-     * Show breadcrumbs in documentation pages
-     */
+    /** Show breadcrumbs in documentation pages */
     breadcrumbs: true,
 
     /**
-     * Theme Documentation Configuration
-     * Controls how theme-level documentation appears in the sidebar
+     * Public Documentation Configuration
+     * Controls public-facing documentation at /docs routes
      */
-    theme: {
-      /** Show/hide theme documentation category */
+    public: {
+      /** Show/hide public documentation */
       enabled: true,
-      /** Expand theme category by default on page load */
+      /** Expand sections by default on page load */
       open: true,
-      /** Custom label displayed in sidebar for theme category */
-      label: "Default Theme",
+      /** Custom label displayed in sidebar */
+      label: "Documentation",
     },
 
     /**
-     * Plugins Documentation Configuration
-     * Controls how plugin documentation appears in the sidebar
+     * Superadmin Documentation Configuration
+     * Controls admin documentation at /superadmin/docs routes
      */
-    plugins: {
-      /** Show/hide plugin documentation category */
+    superadmin: {
+      /** Show/hide superadmin documentation */
       enabled: true,
-      /** Expand plugins category by default on page load */
-      open: false,
-      /** Custom label displayed in sidebar for plugins category */
-      label: "Plugins",
+      /** Custom label displayed in sidebar */
+      label: "Admin Docs",
     },
-
-    /**
-     * Core Documentation Configuration
-     * Controls how core framework documentation appears in the sidebar
-     */
-    core: {
-      /** Show/hide core documentation category */
-      enabled: true,
-      /** Expand core category by default on page load */
-      open: true,
-      /** Custom label displayed in sidebar for core category */
-      label: "Core",
-    },
-
-    /**
-     * Additional environment-based check for plugin docs in production
-     * Plugin docs will only show if BOTH conditions are met:
-     * 1. plugins.enabled is true
-     * 2. Either in development OR showPluginsDocsInProd is true
-     *
-     * @deprecated Prefer using plugins.enabled for simpler control
-     * By default plugins documentation is not available in prod environments
-     */
-    showPluginsDocsInProd: false,
   },
 
   // =============================================================================

package/docs/superadmin/01-setup/01-configuration.md

@@ -0,0 +1,74 @@
+# Configuration Guide
+
+This guide covers the configuration options available to administrators for setting up and customizing your NextSpark application.
+
+## Environment Variables
+
+### Required Variables
+
+```bash
+# Database
+DATABASE_URL="postgresql://user:password@localhost:5432/dbname"
+
+# Authentication
+BETTER_AUTH_SECRET="your-secret-key"
+
+# Application
+NEXT_PUBLIC_APP_URL="https://your-domain.com"
+```
+
+### Optional Variables
+
+```bash
+# Email (for notifications)
+SMTP_HOST="smtp.example.com"
+SMTP_PORT="587"
+SMTP_USER="user@example.com"
+SMTP_PASSWORD="password"
+
+# Billing (Stripe)
+STRIPE_SECRET_KEY="sk_..."
+STRIPE_WEBHOOK_SECRET="whsec_..."
+NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_..."
+```
+
+## Configuration Files
+
+### app.config.ts
+
+The main application configuration file located at `config/app.config.ts`:
+
+```typescript
+export const APP_CONFIG_OVERRIDES = {
+  app: {
+    name: 'Your App Name',
+    version: '1.0.0',
+  },
+  teams: {
+    mode: 'multi-tenant', // or 'single-tenant', 'single-user'
+  },
+  i18n: {
+    supportedLocales: ['en', 'es'],
+    defaultLocale: 'en',
+  },
+}
+```
+
+### permissions.config.ts
+
+Define roles and permissions in `config/permissions.config.ts`:
+
+```typescript
+export const PERMISSIONS_CONFIG = {
+  roles: {
+    additionalRoles: ['editor'],
+    hierarchy: { editor: 5 },
+  },
+  // ... permissions
+}
+```
+
+## Next Steps
+
+- [Deployment Guide](./02-deployment.md)
+- [User Management](../02-management/01-users.md)

package/docs/superadmin/01-setup/02-deployment.md

@@ -0,0 +1,77 @@
+# Deployment Guide
+
+This guide covers deploying your NextSpark application to production environments.
+
+## Prerequisites
+
+- Node.js 18+ installed
+- PostgreSQL database provisioned
+- Domain configured with SSL
+
+## Vercel Deployment
+
+### 1. Connect Repository
+
+1. Go to [Vercel Dashboard](https://vercel.com/dashboard)
+2. Click "Add New Project"
+3. Import your Git repository
+
+### 2. Configure Environment Variables
+
+Add all required environment variables in Vercel project settings:
+
+```
+DATABASE_URL=postgresql://...
+BETTER_AUTH_SECRET=...
+NEXT_PUBLIC_APP_URL=https://your-domain.com
+```
+
+### 3. Deploy
+
+Vercel will automatically build and deploy your application.
+
+## Docker Deployment
+
+### Build Image
+
+```bash
+docker build -t nextspark-app .
+```
+
+### Run Container
+
+```bash
+docker run -p 3000:3000 \
+  -e DATABASE_URL="postgresql://..." \
+  -e BETTER_AUTH_SECRET="..." \
+  nextspark-app
+```
+
+## Database Migrations
+
+Run migrations before starting the application:
+
+```bash
+pnpm db:migrate
+```
+
+## Health Checks
+
+The application exposes health check endpoints:
+
+- `/api/health` - Basic health check
+- `/api/health/db` - Database connectivity check
+
+## Monitoring
+
+Configure monitoring and alerting for:
+
+- Application errors
+- Database connection issues
+- API response times
+- Memory and CPU usage
+
+## Next Steps
+
+- [Configuration Guide](./01-configuration.md)
+- [User Management](../02-management/01-users.md)

package/docs/superadmin/02-management/01-users.md

@@ -0,0 +1,78 @@
+# User Management
+
+This guide covers managing users and teams in your NextSpark application.
+
+## User Roles
+
+### System Roles
+
+| Role | Description |
+|------|-------------|
+| `superadmin` | Full system access, can manage all users and teams |
+| `developer` | Access to developer tools and debugging features |
+| `member` | Standard user role |
+
+### Team Roles
+
+| Role | Description |
+|------|-------------|
+| `owner` | Team creator, full team management |
+| `admin` | Can manage team settings and members |
+| `member` | Standard team member |
+| `viewer` | Read-only access |
+
+## Managing Users
+
+### View All Users
+
+Access the user management panel at `/superadmin/users`:
+
+1. Navigate to Superadmin Dashboard
+2. Click on "Users" in the sidebar
+3. Use filters to search by name, email, or role
+
+### Update User Role
+
+1. Find the user in the list
+2. Click on the user row to open details
+3. Select new role from dropdown
+4. Click "Save Changes"
+
+### Deactivate User
+
+1. Open user details
+2. Click "Deactivate Account"
+3. Confirm the action
+
+## Managing Teams
+
+### View All Teams
+
+Access team management at `/superadmin/teams`:
+
+- See all teams across the platform
+- View team member counts
+- Monitor team activity
+
+### Team Impersonation
+
+Superadmins can view the application as any team member:
+
+1. Navigate to team details
+2. Click "Impersonate" on a team member
+3. You'll see the app from their perspective
+4. Click "Exit Impersonation" when done
+
+## Audit Logs
+
+All administrative actions are logged. View logs at `/superadmin/logs`:
+
+- User creation/deletion
+- Role changes
+- Team modifications
+- Login attempts
+
+## Next Steps
+
+- [Configuration Guide](../01-setup/01-configuration.md)
+- [Deployment Guide](../01-setup/02-deployment.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextsparkjs/theme-default",
-  "version": "0.1.0-beta.28",
+  "version": "0.1.0-beta.29",
   "private": false,
   "type": "module",
   "main": "./config/theme.config.ts",
@@ -23,4 +23,4 @@
     "type": "theme",
     "name": "default"
   }
-}
+}

package/tests/cypress.config.ts

@@ -2,17 +2,17 @@
  * Cypress Configuration for Default Theme
  *
  * This config works in both monorepo and npm mode.
- * Run with: NEXT_PUBLIC_ACTIVE_THEME=default pnpm cy:open
+ * Run with: pnpm cy:open or pnpm cy:run
+ *
+ * Filter by tags: pnpm cy:tags "@smoke" or pnpm cy:run --env grepTags="@smoke"
  */
 
 import { defineConfig } from 'cypress'
 import path from 'path'
 import fs from 'fs'
-import { fileURLToPath } from 'url'
 
-// ESM-compatible __dirname
-const __filename = fileURLToPath(import.meta.url)
-const __dirname = path.dirname(__filename)
+// __dirname is available because ts-node processes this file as CommonJS
+// (Next.js projects don't use "type": "module" in package.json)
 
 // Paths relative to this config file
 const themeRoot = path.resolve(__dirname, '..')