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

package/dist/templates/contents/themes/starter/tests/cypress/support/commands.ts

@@ -0,0 +1,192 @@
+/**
+ * Custom Cypress Commands for Starter Theme
+ *
+ * Add custom commands here that can be used across all tests.
+ * Commands are available via cy.commandName()
+ *
+ * @example
+ * // Define a command
+ * Cypress.Commands.add('login', (email, password) => { ... })
+ *
+ * // Use it in tests
+ * cy.login('user@example.com', 'password')
+ */
+
+// Declare custom commands for TypeScript
+declare global {
+  namespace Cypress {
+    interface Chainable {
+      /**
+       * Login with email and password
+       */
+      login(email: string, password: string): Chainable<void>
+
+      /**
+       * Login as a specific role using DevKeyring users
+       * @param role - 'owner' | 'admin' | 'member' | 'viewer'
+       */
+      loginAs(role: 'owner' | 'admin' | 'member' | 'viewer'): Chainable<void>
+
+      /**
+       * Login as owner using session helpers
+       */
+      loginAsOwner(): Chainable<void>
+
+      /**
+       * Login as member using session helpers
+       */
+      loginAsMember(): Chainable<void>
+
+      /**
+       * Login as admin using session helpers
+       */
+      loginAsAdmin(): Chainable<void>
+
+      /**
+       * Login as viewer using session helpers
+       */
+      loginAsViewer(): Chainable<void>
+
+      /**
+       * Logout from the application
+       */
+      logout(): Chainable<void>
+
+      /**
+       * Create a task via API
+       */
+      createTask(data: {
+        title: string
+        description?: string
+        status?: string
+        priority?: string
+      }): Chainable<Cypress.Response<unknown>>
+
+      /**
+       * Delete a task via API
+       */
+      deleteTask(id: string): Chainable<Cypress.Response<unknown>>
+    }
+  }
+}
+
+// Import session helpers for login commands
+import {
+  loginAsOwner,
+  loginAsMember,
+  loginAsAdmin,
+  loginAsViewer,
+  THEME_USERS,
+} from '../src/session-helpers'
+
+// Test password
+const TEST_PASSWORD = 'Test1234'
+
+// Register login commands
+Cypress.Commands.add('loginAsOwner', loginAsOwner)
+Cypress.Commands.add('loginAsMember', loginAsMember)
+Cypress.Commands.add('loginAsAdmin', loginAsAdmin)
+Cypress.Commands.add('loginAsViewer', loginAsViewer)
+
+/**
+ * Login with email and password via API
+ */
+Cypress.Commands.add('login', (email: string, password: string) => {
+  cy.request({
+    method: 'POST',
+    url: '/api/auth/sign-in/email',
+    body: { email, password },
+    failOnStatusCode: false,
+  }).then((response) => {
+    if (response.status === 200) {
+      cy.visit('/dashboard')
+      cy.url().should('include', '/dashboard')
+    } else {
+      throw new Error(`Login failed: ${response.body?.error || 'Unknown error'}`)
+    }
+  })
+})
+
+/**
+ * Login as a specific role
+ */
+Cypress.Commands.add('loginAs', (role: 'owner' | 'admin' | 'member' | 'viewer') => {
+  const roleMap = {
+    owner: loginAsOwner,
+    admin: loginAsAdmin,
+    member: loginAsMember,
+    viewer: loginAsViewer,
+  }
+
+  const loginFn = roleMap[role]
+  if (loginFn) {
+    loginFn()
+  } else {
+    throw new Error(`Unknown role: ${role}`)
+  }
+})
+
+/**
+ * Logout from the application
+ */
+Cypress.Commands.add('logout', () => {
+  cy.request({
+    method: 'POST',
+    url: '/api/auth/sign-out',
+    failOnStatusCode: false,
+  })
+  cy.clearCookies()
+  cy.clearLocalStorage()
+})
+
+/**
+ * Create a task via API
+ */
+Cypress.Commands.add('createTask', (data) => {
+  return cy.window().then((win) => {
+    const teamId = win.localStorage.getItem('activeTeamId')
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+    }
+    if (teamId) {
+      headers['x-team-id'] = teamId
+    }
+
+    return cy.request({
+      method: 'POST',
+      url: '/api/v1/tasks',
+      headers,
+      body: {
+        title: data.title,
+        description: data.description || '',
+        status: data.status || 'todo',
+        priority: data.priority || 'medium',
+      },
+      failOnStatusCode: false,
+    })
+  })
+})
+
+/**
+ * Delete a task via API
+ */
+Cypress.Commands.add('deleteTask', (id: string) => {
+  return cy.window().then((win) => {
+    const teamId = win.localStorage.getItem('activeTeamId')
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+    }
+    if (teamId) {
+      headers['x-team-id'] = teamId
+    }
+
+    return cy.request({
+      method: 'DELETE',
+      url: `/api/v1/tasks/${id}`,
+      headers,
+      failOnStatusCode: false,
+    })
+  })
+})
+
+export {}

package/dist/templates/contents/themes/starter/tests/cypress/support/doc-commands.ts

@@ -0,0 +1,260 @@
+/**
+ * Documentation Commands for Cypress
+ *
+ * Custom commands for generating documentation videos with narration.
+ * Uses cypress-slow-down for controlled execution speed.
+ *
+ * @example
+ * // In your test file:
+ * import '../support/doc-commands'
+ *
+ * describe('Tutorial: Login', { tags: ['@doc'] }, () => {
+ *   before(() => {
+ *     cy.startDocMode(800)
+ *   })
+ *
+ *   it('shows how to login', () => {
+ *     cy.narrate('First, navigate to the login page')
+ *     cy.visit('/login')
+ *   })
+ * })
+ */
+
+import { slowCypressDown } from 'cypress-slow-down'
+import 'cypress-slow-down/commands'
+
+// Store narrations for extraction
+interface NarrationEntry {
+  timestamp: number
+  time: string        // "M:SS" format from start (for subtitles)
+  timeMs: number      // Milliseconds from start
+  stepNumber: number
+  text: string
+  highlight?: string
+  duration: number
+  chapter?: string
+}
+
+let narrations: NarrationEntry[] = []
+let stepCounter = 0
+let docModeActive = false
+let startTime = 0     // Timestamp when recording started
+
+/**
+ * Format milliseconds to M:SS or MM:SS string
+ */
+function formatTime(ms: number): string {
+  const totalSeconds = Math.floor(ms / 1000)
+  const minutes = Math.floor(totalSeconds / 60)
+  const seconds = totalSeconds % 60
+  return `${minutes}:${seconds.toString().padStart(2, '0')}`
+}
+
+// Declare custom commands
+declare global {
+  namespace Cypress {
+    interface Chainable {
+      /**
+       * Start documentation mode with specified delay between commands
+       * @param delayMs - Milliseconds to wait between each command (default: 800)
+       */
+      startDocMode(delayMs?: number): Chainable<void>
+
+      /**
+       * End documentation mode and save narrations
+       */
+      endDocMode(): Chainable<void>
+
+      /**
+       * Add narration text for the current step
+       * @param text - The narration text to display/speak
+       * @param options - Optional settings like highlight selector
+       */
+      narrate(text: string, options?: { highlight?: string; pause?: number }): Chainable<void>
+
+      /**
+       * Add a chapter/section marker in the narration
+       * @param title - Chapter title
+       */
+      chapter(title: string): Chainable<void>
+
+      /**
+       * Pause for emphasis (used after important actions)
+       * @param ms - Milliseconds to pause
+       */
+      pauseForEmphasis(ms?: number): Chainable<void>
+
+      /**
+       * Highlight an element visually (adds temporary outline)
+       * @param selector - Element selector to highlight
+       */
+      highlightElement(selector: string): Chainable<void>
+    }
+  }
+}
+
+/**
+ * Calculate reading time based on text length
+ * Average reading speed: ~150-180 words per minute for narration
+ * We use ~4 characters = 1 syllable, ~1.5 syllables/second for clear speech
+ */
+function calculateNarrationDuration(text: string): number {
+  const words = text.split(/\s+/).length
+  const wordsPerSecond = 2.5 // Slow, clear narration speed
+  const baseTime = (words / wordsPerSecond) * 1000
+  // Add minimum time and buffer
+  return Math.max(1500, baseTime + 500)
+}
+
+/**
+ * Start documentation mode - slows down Cypress execution
+ */
+Cypress.Commands.add('startDocMode', (delayMs = 800) => {
+  docModeActive = true
+  narrations = []
+  stepCounter = 0
+  startTime = Date.now()  // Record start time
+
+  // Activate slow mode
+  slowCypressDown(delayMs)
+
+  // Log start marker (visible in video)
+  cy.log('**DOCUMENTATION MODE STARTED**')
+
+  // Add initial narration entry
+  narrations.push({
+    timestamp: startTime,
+    time: '0:00',
+    timeMs: 0,
+    stepNumber: 0,
+    text: '--- Documentation Recording Started ---',
+    duration: 0,
+  })
+})
+
+/**
+ * End documentation mode and save narrations to file
+ */
+Cypress.Commands.add('endDocMode', () => {
+  if (!docModeActive) return
+
+  cy.log('**DOCUMENTATION MODE ENDED**')
+
+  // Add final narration entry
+  const now = Date.now()
+  const elapsedMs = now - startTime
+  narrations.push({
+    timestamp: now,
+    time: formatTime(elapsedMs),
+    timeMs: elapsedMs,
+    stepNumber: stepCounter + 1,
+    text: '--- Documentation Recording Ended ---',
+    duration: 0,
+  })
+
+  // Save narrations to file via task
+  const specName = Cypress.spec.name.replace('.cy.ts', '').replace('.cy.js', '')
+  cy.task('saveNarrations', {
+    specName,
+    narrations,
+    totalDuration: formatTime(elapsedMs),
+    totalDurationMs: elapsedMs,
+  }, { log: false })
+
+  cy.log(`**Total Duration: ${formatTime(elapsedMs)}**`)
+
+  docModeActive = false
+  narrations = []
+  stepCounter = 0
+  startTime = 0
+})
+
+/**
+ * Add narration for current step
+ */
+Cypress.Commands.add('narrate', (text: string, options?: { highlight?: string; pause?: number }) => {
+  stepCounter++
+  const duration = calculateNarrationDuration(text)
+  const now = Date.now()
+  const elapsedMs = now - startTime
+  const timeStr = formatTime(elapsedMs)
+
+  // Store narration data
+  narrations.push({
+    timestamp: now,
+    time: timeStr,
+    timeMs: elapsedMs,
+    stepNumber: stepCounter,
+    text,
+    highlight: options?.highlight,
+    duration,
+  })
+
+  // Visual feedback in Cypress runner (will show in video)
+  cy.log(`**[${timeStr}]** ${text}`)
+
+  // If highlight specified, add visual indicator
+  if (options?.highlight) {
+    cy.highlightElement(options.highlight)
+  }
+
+  // Wait for narration duration (so video has time for the narration)
+  const waitTime = options?.pause ?? duration
+  cy.wait(waitTime, { log: false })
+})
+
+/**
+ * Add chapter marker
+ */
+Cypress.Commands.add('chapter', (title: string) => {
+  stepCounter++
+  const now = Date.now()
+  const elapsedMs = now - startTime
+  const timeStr = formatTime(elapsedMs)
+
+  narrations.push({
+    timestamp: now,
+    time: timeStr,
+    timeMs: elapsedMs,
+    stepNumber: stepCounter,
+    text: `=== ${title} ===`,
+    chapter: title,
+    duration: 2000,
+  })
+
+  // Large visual marker
+  cy.log(`**[${timeStr}] === ${title.toUpperCase()} ===**`)
+  cy.wait(2000, { log: false })
+})
+
+/**
+ * Pause for emphasis after important actions
+ */
+Cypress.Commands.add('pauseForEmphasis', (ms = 1500) => {
+  cy.log('*pause*')
+  cy.wait(ms, { log: false })
+})
+
+/**
+ * Highlight an element with a visual indicator
+ */
+Cypress.Commands.add('highlightElement', (selector: string) => {
+  cy.get(selector).then($el => {
+    // Add highlight class
+    $el.css({
+      outline: '3px solid #ff6b6b',
+      outlineOffset: '2px',
+      transition: 'outline 0.3s ease',
+    })
+
+    // Remove highlight after a delay
+    cy.wait(800, { log: false }).then(() => {
+      $el.css({
+        outline: 'none',
+        outlineOffset: '0',
+      })
+    })
+  })
+})
+
+export {}

package/dist/templates/contents/themes/starter/tests/cypress/support/e2e.ts

@@ -0,0 +1,21 @@
+/**
+ * Cypress E2E Support File for Starter Theme
+ *
+ * This file is loaded automatically before test files.
+ * Use it to load plugins, add global hooks, and import commands.
+ */
+
+// Import custom commands
+import './commands'
+
+// Import documentation commands (optional - for demo videos)
+// import './doc-commands'
+
+// Disable uncaught exception handling to prevent test failures
+// from application errors that don't affect test assertions
+Cypress.on('uncaught:exception', (err) => {
+  // Returning false here prevents Cypress from failing the test
+  // You may want to be more selective about which errors to ignore
+  console.error('Uncaught exception:', err.message)
+  return false
+})

package/dist/templates/contents/themes/starter/tests/cypress.config.ts

@@ -0,0 +1,155 @@
+/**
+ * Cypress Configuration for Starter Theme
+ *
+ * This config is theme-specific and used by scripts/cy.mjs.
+ * Run with: NEXT_PUBLIC_ACTIVE_THEME=starter pnpm cy:open
+ */
+
+import { defineConfig } from 'cypress'
+import path from 'path'
+import fs from 'fs'
+
+// Paths relative to this config file
+const themeRoot = path.resolve(__dirname, '..')
+const projectRoot = path.resolve(__dirname, '../../../..')
+const narrationsOutputDir = path.join(__dirname, 'cypress/videos/narrations')
+
+// Load environment variables
+import dotenv from 'dotenv'
+dotenv.config({ path: path.join(projectRoot, '.env') })
+
+// Server port (from .env or default 5173)
+const port = process.env.PORT || 5173
+
+export default defineConfig({
+  e2e: {
+    // Base URL for the application
+    baseUrl: `http://localhost:${port}`,
+
+    // Spec patterns: core tests + theme tests
+    specPattern: [
+      // Core tests (always included)
+      path.join(projectRoot, 'core/tests/cypress/e2e/core/**/*.cy.{js,ts}'),
+      // Theme-specific tests
+      path.join(__dirname, 'cypress/e2e/**/*.cy.{js,ts}'),
+    ],
+
+    // Support file (shared across themes)
+    supportFile: path.join(projectRoot, 'core/tests/cypress/support/e2e.ts'),
+
+    // Fixtures folder (theme-specific)
+    fixturesFolder: path.join(__dirname, 'cypress/fixtures'),
+
+    // Output folders (theme-specific)
+    downloadsFolder: path.join(__dirname, 'cypress/downloads'),
+    screenshotsFolder: path.join(__dirname, 'cypress/screenshots'),
+    videosFolder: path.join(__dirname, 'cypress/videos'),
+
+    // Viewport settings
+    viewportWidth: 1280,
+    viewportHeight: 720,
+
+    // Video and screenshot settings
+    video: true,
+    screenshotOnRunFailure: true,
+
+    // Timeouts
+    defaultCommandTimeout: 10000,
+    requestTimeout: 10000,
+    responseTimeout: 10000,
+    pageLoadTimeout: 30000,
+
+    // Browser settings
+    chromeWebSecurity: false,
+
+    // Test isolation
+    testIsolation: true,
+
+    // Retry settings
+    retries: {
+      runMode: 1,
+      openMode: 0,
+    },
+
+    // Environment variables
+    env: {
+      // Theme info
+      ACTIVE_THEME: 'starter',
+      THEME_PATH: themeRoot,
+
+      // Test user credentials (update with your test users)
+      TEST_USER_EMAIL: 'owner@starter.dev',
+      TEST_USER_PASSWORD: 'Test1234',
+
+      // Feature flags
+      ENABLE_ALLURE: true,
+
+      // Allure reporting
+      allureResultsPath: path.join(__dirname, 'cypress/allure-results'),
+
+      // API settings
+      API_URL: `http://localhost:${port}/api`,
+      API_BASE_URL: `http://localhost:${port}`,
+
+      // @cypress/grep - filter specs by tags
+      grepFilterSpecs: true,
+      grepOmitFiltered: true,
+    },
+
+    setupNodeEvents(on, config) {
+      // Allure plugin setup (allure-cypress)
+      const { allureCypress } = require('allure-cypress/reporter')
+      allureCypress(on, config, {
+        resultsDir: path.join(__dirname, 'cypress/allure-results'),
+      })
+
+      // @cypress/grep plugin for test filtering by tags
+      require('@cypress/grep/src/plugin')(config)
+
+      // Documentation video tasks
+      on('task', {
+        /**
+         * Save narrations to JSON file for post-processing
+         */
+        saveNarrations({
+          specName,
+          narrations,
+        }: {
+          specName: string
+          narrations: unknown[]
+        }) {
+          // Ensure output directory exists
+          if (!fs.existsSync(narrationsOutputDir)) {
+            fs.mkdirSync(narrationsOutputDir, { recursive: true })
+          }
+
+          const filename = `${specName}-narrations.json`
+          const filepath = path.join(narrationsOutputDir, filename)
+
+          fs.writeFileSync(filepath, JSON.stringify(narrations, null, 2))
+          console.log(`Narrations saved to: ${filepath}`)
+
+          return null
+        },
+
+        /**
+         * Add narration entry (called per narration)
+         */
+        addNarration(narration: unknown) {
+          console.log('Narration:', narration)
+          return null
+        },
+      })
+
+      return config
+    },
+  },
+
+  // Component testing (future use)
+  component: {
+    devServer: {
+      framework: 'next',
+      bundler: 'webpack',
+    },
+  },
+})

package/dist/templates/contents/themes/starter/tests/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../../../tsconfig.cypress.json",
+  "compilerOptions": {
+    "baseUrl": "../../../..",
+    "paths": {
+      "@/*": ["./*"],
+      "@/core/*": ["./core/*"],
+      "@/contents/*": ["./contents/*"]
+    }
+  },
+  "include": [
+    "../../../../cypress.d.ts",
+    "cypress/**/*.ts"
+  ]
+}

package/dist/templates/eslint.config.mjs

@@ -0,0 +1,16 @@
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { FlatCompat } from "@eslint/eslintrc";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const compat = new FlatCompat({
+  baseDirectory: __dirname,
+});
+
+const eslintConfig = [
+  ...compat.extends("next/core-web-vitals", "next/typescript"),
+];
+
+export default eslintConfig;