@nextsparkjs/core 0.1.0-beta.84 → 0.1.0-beta.85

package/templates/app/api/v1/devtools/blocks/route.ts

@@ -0,0 +1,82 @@
+/**
+ * DevTools Blocks API
+ *
+ * GET /api/v1/devtools/blocks
+ *
+ * Returns the block registry with field definitions and test coverage.
+ * Requires superadmin or developer user role.
+ */
+
+import { NextRequest, NextResponse } from 'next/server'
+import { authenticateRequest } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import {
+  canAccessDevtoolsApi,
+  createDevtoolsAccessDeniedResponse,
+  createDevtoolsUnauthorizedResponse,
+} from '@nextsparkjs/core/lib/api/auth/devtools-auth'
+import { BLOCK_REGISTRY } from '@nextsparkjs/registries/block-registry'
+import { TAGS_REGISTRY, COVERAGE_SUMMARY } from '@nextsparkjs/registries/testing-registry'
+
+export async function GET(request: NextRequest) {
+  // Authenticate request
+  const authResult = await authenticateRequest(request)
+
+  if (!authResult.success) {
+    return createDevtoolsUnauthorizedResponse()
+  }
+
+  // Check DevTools access permission
+  if (!canAccessDevtoolsApi(authResult)) {
+    return createDevtoolsAccessDeniedResponse()
+  }
+
+  // Merge blocks with test coverage data
+  // Type assertion needed because TAGS_REGISTRY uses 'as const' with readonly arrays
+  const blockTags = TAGS_REGISTRY.blocks as unknown as Record<string, { tag: string; testCount: number; files: readonly string[] }>
+  const blocksWithCoverage = Object.values(BLOCK_REGISTRY).map((block) => {
+    const tagData = blockTags[block.slug]
+    return {
+      ...block,
+      testing: {
+        hasTests: (tagData?.testCount || 0) > 0,
+        testCount: tagData?.testCount || 0,
+        files: tagData?.files ? [...tagData.files] : [],
+        tag: `@b-${block.slug}`,
+      },
+    }
+  })
+
+  // Calculate summary stats
+  const total = blocksWithCoverage.length
+  const withTests = blocksWithCoverage.filter((b) => b.testing.hasTests).length
+
+  // Get unique categories
+  const categories = [...new Set(blocksWithCoverage.map((b) => b.category))].sort()
+
+  return NextResponse.json({
+    success: true,
+    data: {
+      blocks: blocksWithCoverage,
+      summary: {
+        total,
+        withTests,
+        withoutTests: total - withTests,
+        categories,
+      },
+      meta: {
+        theme: COVERAGE_SUMMARY.theme,
+        generatedAt: COVERAGE_SUMMARY.generatedAt,
+      },
+    },
+  })
+}
+
+export async function OPTIONS() {
+  return new NextResponse(null, {
+    status: 204,
+    headers: {
+      'Access-Control-Allow-Methods': 'GET, OPTIONS',
+      'Access-Control-Allow-Headers': 'Content-Type, Authorization, x-api-key',
+    },
+  })
+}

package/templates/app/api/v1/devtools/docs/route.ts

@@ -0,0 +1,150 @@
+/**
+ * DevTools API Documentation Endpoint
+ *
+ * Serves markdown documentation files for API endpoints.
+ * Used by the API Explorer to display endpoint documentation.
+ *
+ * Supports both monorepo and npm modes:
+ * - Monorepo: themes at repo root (themes/{theme}/...)
+ * - NPM: themes in contents directory (contents/themes/{theme}/...)
+ *
+ * GET /api/v1/devtools/docs?path={path}
+ */
+
+import { NextRequest, NextResponse } from 'next/server'
+import { readFile } from 'fs/promises'
+import { join, dirname } from 'path'
+import { existsSync } from 'fs'
+
+/**
+ * Valid path patterns for documentation files
+ * Supports both monorepo mode (themes/) and npm mode (contents/themes/)
+ */
+const VALID_PATH_PATTERNS = [
+  // Entity folders
+  /^(contents\/)?themes\/[\w-]+\/entities\/[\w-]+\/api\/docs\.md$/,
+  // Theme routes
+  /^(contents\/)?themes\/[\w-]+\/app\/api\/.*\/docs\.md$/,
+  // Core routes (monorepo mode)
+  /^packages\/core\/templates\/app\/api\/.*\/docs\.md$/,
+  // Core routes (NPM mode)
+  /^node_modules\/@nextsparkjs\/core\/templates\/app\/api\/.*\/docs\.md$/,
+  // Legacy devtools/api location (for backwards compatibility)
+  /^(contents\/)?themes\/[\w-]+\/devtools\/api\/[\w-]+\.md$/
+]
+
+/**
+ * Validate that a path matches one of the allowed patterns
+ */
+function isValidPath(path: string): boolean {
+  return VALID_PATH_PATTERNS.some(pattern => pattern.test(path))
+}
+
+/**
+ * Detect monorepo root by searching for pnpm-workspace.yaml
+ */
+function detectMonorepoRoot(startDir: string): string | null {
+  let dir = startDir
+  const maxDepth = 10
+  let depth = 0
+
+  while (dir !== '/' && depth < maxDepth) {
+    if (existsSync(join(dir, 'pnpm-workspace.yaml'))) {
+      return dir
+    }
+    dir = dirname(dir)
+    depth++
+  }
+
+  return null
+}
+
+/**
+ * Get all possible base paths for resolving doc files
+ * Handles both monorepo and npm modes
+ */
+function getBasePaths(): string[] {
+  const cwd = process.cwd()
+  const paths: string[] = []
+
+  // Always try cwd first (works for npm mode with contents/)
+  paths.push(cwd)
+
+  // Check if we're in monorepo mode
+  const monorepoRoot = detectMonorepoRoot(cwd)
+  if (monorepoRoot && monorepoRoot !== cwd) {
+    // In monorepo, themes are at repo root
+    paths.push(monorepoRoot)
+  }
+
+  return paths
+}
+
+export async function GET(request: NextRequest) {
+  const searchParams = request.nextUrl.searchParams
+  const docPath = searchParams.get('path')
+
+  if (!docPath) {
+    return NextResponse.json(
+      { error: 'Missing path parameter' },
+      { status: 400 }
+    )
+  }
+
+  // Validate path to prevent directory traversal
+  if (docPath.includes('..')) {
+    return NextResponse.json(
+      { error: 'Invalid path: directory traversal not allowed' },
+      { status: 400 }
+    )
+  }
+
+  // Validate path matches allowed patterns
+  if (!isValidPath(docPath)) {
+    return NextResponse.json(
+      { error: 'Invalid path: does not match allowed patterns' },
+      { status: 400 }
+    )
+  }
+
+  // Only allow .md files
+  if (!docPath.endsWith('.md')) {
+    return NextResponse.json(
+      { error: 'Only markdown files are allowed' },
+      { status: 400 }
+    )
+  }
+
+  try {
+    // Try all possible base paths
+    const basePaths = getBasePaths()
+
+    let fullPath: string | null = null
+    for (const base of basePaths) {
+      const testPath = join(base, docPath)
+      if (existsSync(testPath)) {
+        fullPath = testPath
+        break
+      }
+    }
+
+    // Check if file exists
+    if (!fullPath) {
+      return NextResponse.json(
+        { error: 'Document not found' },
+        { status: 404 }
+      )
+    }
+
+    // Read the markdown file
+    const content = await readFile(fullPath, 'utf-8')
+
+    return NextResponse.json({ content })
+  } catch (error) {
+    console.error('Error reading documentation:', error)
+    return NextResponse.json(
+      { error: 'Failed to read document' },
+      { status: 500 }
+    )
+  }
+}

package/templates/app/api/v1/devtools/docs.md

@@ -0,0 +1,204 @@
+# DevTools API
+
+Development and debugging utilities for the NextSpark framework.
+
+## Overview
+
+The DevTools API provides endpoints for development-time utilities including documentation serving, feature registry access, scheduled action management, test flows, and block metadata. These endpoints are restricted to superadmin and developer users.
+
+## Authentication
+
+All endpoints require authentication via:
+- **Session cookie** with superadmin or developer role
+- **API Key** header with appropriate permissions
+
+Only superadmin and developer users can access these endpoints.
+
+## Endpoints
+
+### Get Documentation
+`GET /api/v1/devtools/docs?path={path}`
+
+Serves markdown documentation files for API endpoints. Used by the API Explorer to display endpoint documentation.
+
+**Query Parameters:**
+- `path` (string, required): Path to the markdown file
+
+**Valid Path Patterns:**
+- `themes/{theme}/entities/{entity}/api/docs.md`
+- `themes/{theme}/app/api/.../docs.md`
+- `packages/core/templates/app/api/.../docs.md`
+- `node_modules/@nextsparkjs/core/templates/app/api/.../docs.md`
+
+**Example Request:**
+```
+GET /api/v1/devtools/docs?path=packages/core/templates/app/api/v1/teams/docs.md
+```
+
+**Response:**
+```json
+{
+  "content": "# Teams API\n\nManage teams..."
+}
+```
+
+### List Features
+`GET /api/v1/devtools/features`
+
+Returns the feature registry with test coverage information.
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "features": [
+      {
+        "id": "auth-login",
+        "name": "User Login",
+        "category": "auth",
+        "hasTests": true,
+        "testFile": "auth/login.cy.ts"
+      }
+    ],
+    "summary": {
+      "total": 25,
+      "withTests": 20,
+      "withoutTests": 5
+    },
+    "meta": {
+      "theme": "default",
+      "generatedAt": "2024-01-15T10:00:00Z"
+    }
+  }
+}
+```
+
+### List Blocks
+`GET /api/v1/devtools/blocks`
+
+Returns block registry metadata for development inspection.
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "blocks": [
+      {
+        "slug": "hero-simple",
+        "name": "Simple Hero",
+        "category": "hero",
+        "hasPreview": true
+      }
+    ],
+    "categories": ["hero", "content", "cta", "faq"],
+    "total": 15
+  }
+}
+```
+
+### List Test Flows
+`GET /api/v1/devtools/flows`
+
+Returns test flows for end-to-end testing scenarios.
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "flows": [
+      {
+        "id": "user-onboarding",
+        "name": "User Onboarding Flow",
+        "steps": ["signup", "verify-email", "complete-profile"],
+        "testFile": "flows/onboarding.cy.ts"
+      }
+    ]
+  }
+}
+```
+
+### List Scheduled Actions
+`GET /api/v1/devtools/scheduled-actions`
+
+Returns scheduled actions with filtering and pagination.
+
+**Query Parameters:**
+- `status` (string, optional): Filter by status (pending, running, completed, failed)
+- `action_type` (string, optional): Filter by action type
+- `page` (number, optional): Page number. Default: 1
+- `limit` (number, optional): Items per page. Default: 20
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "actions": [
+      {
+        "id": "action_123",
+        "actionType": "send-email",
+        "status": "completed",
+        "payload": { "to": "user@example.com" },
+        "scheduledAt": "2024-01-15T10:00:00Z",
+        "completedAt": "2024-01-15T10:00:05Z",
+        "attempts": 1
+      }
+    ],
+    "pagination": {
+      "total": 50,
+      "page": 1,
+      "limit": 20,
+      "totalPages": 3
+    },
+    "meta": {
+      "registeredActionTypes": ["send-email", "cleanup-expired", "sync-data"]
+    }
+  }
+}
+```
+
+### Testing Information
+`GET /api/v1/devtools/testing`
+
+Returns testing configuration and utilities information.
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "cypress": {
+      "baseUrl": "http://localhost:5173",
+      "specPattern": "cypress/e2e/**/*.cy.ts"
+    },
+    "testUsers": [
+      { "email": "superadmin@test.com", "role": "superadmin" },
+      { "email": "admin@test.com", "role": "admin" }
+    ],
+    "coverage": {
+      "enabled": true,
+      "threshold": 80
+    }
+  }
+}
+```
+
+## Error Responses
+
+| Status | Description |
+|--------|-------------|
+| 400 | Bad Request - Missing or invalid path parameter |
+| 401 | Unauthorized - Authentication required |
+| 403 | Forbidden - Requires superadmin or developer role |
+| 404 | Not Found - Document or resource not found |
+| 500 | Server Error - Failed to read or process request |
+
+## Security Notes
+
+- Path traversal (`..`) is blocked to prevent unauthorized file access
+- Only `.md` files are allowed for documentation endpoints
+- All endpoints validate user role before processing
+- DevTools API is only accessible in development environments by default

package/templates/app/api/v1/devtools/features/route.ts

@@ -0,0 +1,61 @@
+/**
+ * DevTools Features API
+ *
+ * GET /api/v1/devtools/features
+ *
+ * Returns the feature registry with test coverage information.
+ * Requires superadmin or developer user role.
+ */
+
+import { NextRequest, NextResponse } from 'next/server'
+import { authenticateRequest } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import {
+  canAccessDevtoolsApi,
+  createDevtoolsAccessDeniedResponse,
+  createDevtoolsUnauthorizedResponse,
+} from '@nextsparkjs/core/lib/api/auth/devtools-auth'
+import {
+  FEATURE_REGISTRY,
+  COVERAGE_SUMMARY,
+} from '@nextsparkjs/registries/testing-registry'
+
+export async function GET(request: NextRequest) {
+  // Authenticate request
+  const authResult = await authenticateRequest(request)
+
+  if (!authResult.success) {
+    return createDevtoolsUnauthorizedResponse()
+  }
+
+  // Check DevTools access permission
+  if (!canAccessDevtoolsApi(authResult)) {
+    return createDevtoolsAccessDeniedResponse()
+  }
+
+  // Return feature registry data
+  return NextResponse.json({
+    success: true,
+    data: {
+      features: Object.values(FEATURE_REGISTRY),
+      summary: {
+        total: COVERAGE_SUMMARY.features.total,
+        withTests: COVERAGE_SUMMARY.features.withTests,
+        withoutTests: COVERAGE_SUMMARY.features.withoutTests,
+      },
+      meta: {
+        theme: COVERAGE_SUMMARY.theme,
+        generatedAt: COVERAGE_SUMMARY.generatedAt,
+      },
+    },
+  })
+}
+
+export async function OPTIONS() {
+  return new NextResponse(null, {
+    status: 204,
+    headers: {
+      'Access-Control-Allow-Methods': 'GET, OPTIONS',
+      'Access-Control-Allow-Headers': 'Content-Type, Authorization, x-api-key',
+    },
+  })
+}

package/templates/app/api/v1/devtools/flows/route.ts

@@ -0,0 +1,61 @@
+/**
+ * DevTools Flows API
+ *
+ * GET /api/v1/devtools/flows
+ *
+ * Returns the flow registry with test coverage information.
+ * Requires superadmin or developer user role.
+ */
+
+import { NextRequest, NextResponse } from 'next/server'
+import { authenticateRequest } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import {
+  canAccessDevtoolsApi,
+  createDevtoolsAccessDeniedResponse,
+  createDevtoolsUnauthorizedResponse,
+} from '@nextsparkjs/core/lib/api/auth/devtools-auth'
+import {
+  FLOW_REGISTRY,
+  COVERAGE_SUMMARY,
+} from '@nextsparkjs/registries/testing-registry'
+
+export async function GET(request: NextRequest) {
+  // Authenticate request
+  const authResult = await authenticateRequest(request)
+
+  if (!authResult.success) {
+    return createDevtoolsUnauthorizedResponse()
+  }
+
+  // Check DevTools access permission
+  if (!canAccessDevtoolsApi(authResult)) {
+    return createDevtoolsAccessDeniedResponse()
+  }
+
+  // Return flow registry data
+  return NextResponse.json({
+    success: true,
+    data: {
+      flows: Object.values(FLOW_REGISTRY),
+      summary: {
+        total: COVERAGE_SUMMARY.flows.total,
+        withTests: COVERAGE_SUMMARY.flows.withTests,
+        withoutTests: COVERAGE_SUMMARY.flows.withoutTests,
+      },
+      meta: {
+        theme: COVERAGE_SUMMARY.theme,
+        generatedAt: COVERAGE_SUMMARY.generatedAt,
+      },
+    },
+  })
+}
+
+export async function OPTIONS() {
+  return new NextResponse(null, {
+    status: 204,
+    headers: {
+      'Access-Control-Allow-Methods': 'GET, OPTIONS',
+      'Access-Control-Allow-Headers': 'Content-Type, Authorization, x-api-key',
+    },
+  })
+}

package/templates/app/api/v1/devtools/presets.ts

@@ -0,0 +1,113 @@
+/**
+ * API Presets for DevTools
+ *
+ * These presets appear in the DevTools API Explorer's "Presets" tab.
+ */
+
+import { defineApiEndpoint } from '@nextsparkjs/core/types/api-presets'
+
+export default defineApiEndpoint({
+  endpoint: '/api/v1/devtools',
+  summary: 'Development and debugging utilities',
+  presets: [
+    // Documentation
+    {
+      id: 'get-teams-docs',
+      title: 'Get Teams Docs',
+      description: 'Fetch Teams API documentation',
+      method: 'GET',
+      path: '/docs',
+      queryParams: {
+        path: 'packages/core/templates/app/api/v1/teams/docs.md'
+      },
+      tags: ['read', 'docs']
+    },
+    {
+      id: 'get-billing-docs',
+      title: 'Get Billing Docs',
+      description: 'Fetch Billing API documentation',
+      method: 'GET',
+      path: '/docs',
+      queryParams: {
+        path: 'packages/core/templates/app/api/v1/billing/docs.md'
+      },
+      tags: ['read', 'docs']
+    },
+
+    // Features
+    {
+      id: 'list-features',
+      title: 'List Features',
+      description: 'Get feature registry with test coverage',
+      method: 'GET',
+      path: '/features',
+      tags: ['read', 'testing']
+    },
+
+    // Blocks
+    {
+      id: 'list-devtools-blocks',
+      title: 'List Blocks Metadata',
+      description: 'Get block registry metadata',
+      method: 'GET',
+      path: '/blocks',
+      tags: ['read', 'blocks']
+    },
+
+    // Test Flows
+    {
+      id: 'list-flows',
+      title: 'List Test Flows',
+      description: 'Get available test flows',
+      method: 'GET',
+      path: '/flows',
+      tags: ['read', 'testing']
+    },
+
+    // Scheduled Actions
+    {
+      id: 'list-scheduled-actions',
+      title: 'List Scheduled Actions',
+      description: 'Get all scheduled actions',
+      method: 'GET',
+      path: '/scheduled-actions',
+      queryParams: {
+        page: '1',
+        limit: '20'
+      },
+      tags: ['read', 'scheduled-actions']
+    },
+    {
+      id: 'list-pending-actions',
+      title: 'List Pending Actions',
+      description: 'Filter scheduled actions by pending status',
+      method: 'GET',
+      path: '/scheduled-actions',
+      queryParams: {
+        status: 'pending'
+      },
+      tags: ['read', 'scheduled-actions', 'filter']
+    },
+    {
+      id: 'list-failed-actions',
+      title: 'List Failed Actions',
+      description: 'Filter scheduled actions by failed status',
+      method: 'GET',
+      path: '/scheduled-actions',
+      queryParams: {
+        status: 'failed'
+      },
+      tags: ['read', 'scheduled-actions', 'filter']
+    },
+
+    // Testing
+    {
+      id: 'get-testing-info',
+      title: 'Get Testing Info',
+      description: 'Get testing configuration and utilities',
+      method: 'GET',
+      path: '/testing',
+      tags: ['read', 'testing']
+    }
+  ]
+})