coursecode 0.1.0

package/lib/project-utils.js

@@ -0,0 +1,269 @@
+/**
+ * Project Utilities
+ * 
+ * Shared helpers used across multiple CLI commands and lib/ modules.
+ * Single source of truth for project validation and common utilities.
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+// =============================================================================
+// PROJECT VALIDATION
+// =============================================================================
+
+/**
+ * Validate that the current working directory is a valid CourseCode project.
+ * Consolidates 6 former copies into one with options.
+ * 
+ * @param {Object} [options={}]
+ * @param {boolean} [options.frameworkDev=false] - Expect framework repo layout
+ * @param {boolean} [options.warnMissingRc=false] - Warn if .coursecoderc.json is missing
+ * @returns {{ coursePath: string, viteConfig: string|null }} Resolved paths
+ */
+export function validateProject(options = {}) {
+    const { frameworkDev = false, warnMissingRc = false } = options;
+    const cwd = process.cwd();
+
+    if (frameworkDev) {
+        const hasTemplateCourse = fs.existsSync(path.join(cwd, 'template', 'course'));
+        const hasFrameworkDir = fs.existsSync(path.join(cwd, 'framework'));
+        const hasViteDevConfig = fs.existsSync(path.join(cwd, 'vite.framework-dev.config.js'));
+
+        if (!hasTemplateCourse || !hasFrameworkDir || !hasViteDevConfig) {
+            console.error(`
+❌ Not a valid CourseCode framework repository.
+
+   Missing required paths:
+   ${!hasTemplateCourse ? '   - template/course/' : ''}
+   ${!hasFrameworkDir ? '   - framework/' : ''}
+   ${!hasViteDevConfig ? '   - vite.framework-dev.config.js' : ''}
+
+   Run this command from the framework source repository root.
+`);
+            process.exit(1);
+        }
+
+        return {
+            coursePath: path.join(cwd, 'template', 'course'),
+            viteConfig: 'vite.framework-dev.config.js'
+        };
+    }
+
+    const hasCourseDir = fs.existsSync(path.join(cwd, 'course'));
+    const hasFrameworkDir = fs.existsSync(path.join(cwd, 'framework'));
+
+    if (!hasCourseDir || !hasFrameworkDir) {
+        // Detect framework repo for helpful error message
+        const isFrameworkRepo = fs.existsSync(path.join(cwd, 'lib', 'preview-server.js')) &&
+            fs.existsSync(path.join(cwd, 'template', 'course'));
+
+        if (isFrameworkRepo) {
+            console.error(`
+❌ Detected framework source repository.
+
+   Use --framework-dev flag to run in framework development mode:
+   
+   coursecode preview --framework-dev
+`);
+        } else {
+            console.error(`
+❌ Not a valid CourseCode project directory.
+
+   Missing required directories:
+   ${!hasCourseDir ? '   - course/' : ''}
+   ${!hasFrameworkDir ? '   - framework/' : ''}
+
+   Run this command from a CourseCode project root, or create a new project:
+   
+   coursecode create my-course
+`);
+        }
+        process.exit(1);
+    }
+
+    if (warnMissingRc && !fs.existsSync(path.join(cwd, '.coursecoderc.json'))) {
+        console.warn(`
+⚠️  No .coursecoderc.json found. This project may not have been created with the CourseCode CLI.
+   Framework upgrades may not work correctly.
+`);
+    }
+
+    return {
+        coursePath: path.join(cwd, 'course'),
+        viteConfig: null
+    };
+}
+
+/**
+ * Validate that a specific course path contains a course-config.js.
+ * Used by export-content which takes an explicit path rather than using cwd.
+ * 
+ * @param {string} coursePath - Path to course directory (absolute or relative)
+ * @param {Object} [options={}]
+ * @param {boolean} [options.silent=false] - Return null instead of exiting on error
+ * @returns {string|null} Resolved absolute path, or null if silent and invalid
+ */
+export function validateCoursePath(coursePath, options = {}) {
+    const { silent = false } = options;
+    const cwd = process.cwd();
+    const fullCoursePath = path.isAbsolute(coursePath) ? coursePath : path.join(cwd, coursePath);
+
+    if (!fs.existsSync(path.join(fullCoursePath, 'course-config.js'))) {
+        if (silent) return null;
+        console.error(`
+❌ Could not find course-config.js in ${fullCoursePath}
+
+   Make sure you're running this command from a CourseCode project root,
+   or specify the correct path with --course-path.
+`);
+        process.exit(1);
+    }
+
+    return fullCoursePath;
+}
+
+// =============================================================================
+// HTML UTILITIES
+// =============================================================================
+
+/**
+ * Escape HTML special characters in a string.
+ * @param {string} str - Input string
+ * @returns {string} Escaped string
+ */
+export function escapeHtml(str) {
+    return str.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+}
+
+// =============================================================================
+// MIME TYPES
+// =============================================================================
+
+const mimeTypes = {
+    '.html': 'text/html',
+    '.css': 'text/css',
+    '.js': 'application/javascript',
+    '.mjs': 'application/javascript',
+    '.json': 'application/json',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.svg': 'image/svg+xml',
+    '.webp': 'image/webp',
+    '.ico': 'image/x-icon',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+    '.ttf': 'font/ttf',
+    '.eot': 'application/vnd.ms-fontobject',
+    '.mp3': 'audio/mpeg',
+    '.mp4': 'video/mp4',
+    '.webm': 'video/webm',
+    '.ogg': 'audio/ogg',
+    '.wav': 'audio/wav',
+    '.xml': 'application/xml',
+    '.xsd': 'application/xml',
+    '.pdf': 'application/pdf',
+    '.zip': 'application/zip'
+};
+
+/**
+ * Get MIME type for a file path based on extension.
+ * @param {string} filePath
+ * @returns {string}
+ */
+export function getMimeType(filePath) {
+    return mimeTypes[path.extname(filePath).toLowerCase()] || 'application/octet-stream';
+}
+
+// =============================================================================
+// FILE SERVING
+// =============================================================================
+
+/**
+ * Serve a static file over HTTP with proper Content-Type and Content-Length.
+ * @param {string} filePath - Absolute path to file
+ * @param {import('http').ServerResponse} res
+ */
+export function serveFile(filePath, res) {
+    fs.stat(filePath, (statErr, stats) => {
+        if (statErr) {
+            res.writeHead(404);
+            res.end('Not found');
+            return;
+        }
+
+        fs.readFile(filePath, (err, data) => {
+            if (err) {
+                res.writeHead(404);
+                res.end('Not found');
+                return;
+            }
+
+            res.writeHead(200, {
+                'Content-Type': getMimeType(filePath),
+                'Content-Length': stats.size,
+                'Accept-Ranges': 'bytes'
+            });
+            res.end(data);
+        });
+    });
+}
+
+// =============================================================================
+// COURSE STRUCTURE HELPERS
+// =============================================================================
+
+/**
+ * Count total slides in a course structure (including nested sections).
+ * @param {Array} items - Structure array
+ * @returns {number}
+ */
+export function countSlides(items) {
+    let count = 0;
+    for (const item of items) {
+        if (item.type === 'slide' || item.type === 'assessment') {
+            count++;
+        } else if (item.children) {
+            count += countSlides(item.children);
+        }
+    }
+    return count;
+}
+
+/**
+ * Find a slide by ID in a nested structure.
+ * @param {Array} items - Structure array
+ * @param {string} id - Slide ID to find
+ * @returns {object|null}
+ */
+export function findSlideById(items, id) {
+    for (const item of items) {
+        if (item.id === id) return item;
+        if (item.children) {
+            const found = findSlideById(item.children, id);
+            if (found) return found;
+        }
+    }
+    return null;
+}
+
+/**
+ * Collect all slide IDs from a nested structure into a flat array.
+ * @param {Array} items - Structure array
+ * @returns {Array<{id: string, title: string, type: string}>}
+ */
+export function collectSlideIds(items) {
+    const slides = [];
+    for (const item of items) {
+        if (item.type === 'slide' || item.type === 'assessment') {
+            slides.push({ id: item.id, title: item.title || item.id, type: item.type });
+        }
+        if (item.children) {
+            slides.push(...collectSlideIds(item.children));
+        }
+    }
+    return slides;
+}

package/lib/proxy-templates/proxy.html

@@ -0,0 +1,68 @@
+<!DOCTYPE html>
+<!--
+  SCORM Proxy - Loads course from external CDN
+  Generated by CourseCode - Do not edit manually
+  
+  This page:
+  1. Embeds the course in an iframe from the external URL
+  2. Bridges postMessage calls to the LMS SCORM API via pipwerks
+-->
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Loading Course...</title>
+    <style>
+        * { margin: 0; padding: 0; box-sizing: border-box; }
+        html, body { width: 100%; height: 100%; overflow: hidden; }
+        iframe { width: 100%; height: 100%; border: none; }
+        .loading {
+            position: absolute;
+            top: 50%;
+            left: 50%;
+            transform: translate(-50%, -50%);
+            font-family: system-ui, sans-serif;
+            text-align: center;
+            color: #666;
+        }
+        .loading .spinner {
+            width: 40px;
+            height: 40px;
+            margin: 0 auto 16px;
+            border: 3px solid #eee;
+            border-top-color: #333;
+            border-radius: 50%;
+            animation: spin 1s linear infinite;
+        }
+        @keyframes spin { to { transform: rotate(360deg); } }
+    </style>
+</head>
+<body>
+    <div class="loading" id="loading">
+        <div class="spinner"></div>
+        <div>Loading course...</div>
+    </div>
+    
+    <iframe id="course" style="display:none"></iframe>
+    
+    <script src="scorm-bridge.js"></script>
+    <script>
+        // Course URL is injected at build time
+        const COURSE_URL = '{{EXTERNAL_URL}}';
+        
+        const iframe = document.getElementById('course');
+        const loading = document.getElementById('loading');
+        
+        iframe.onload = function() {
+            loading.style.display = 'none';
+            iframe.style.display = 'block';
+        };
+        
+        iframe.onerror = function() {
+            loading.innerHTML = '<div style="color:#c00">Failed to load course</div>';
+        };
+        
+        iframe.src = COURSE_URL;
+    </script>
+</body>
+</html>

package/lib/proxy-templates/scorm-bridge.js

@@ -0,0 +1,112 @@
+/**
+ * SCORM Bridge - Connects postMessage from iframe to LMS API
+ * Generated by CourseCode - Do not edit manually
+ * 
+ * Uses pipwerks wrapper which auto-detects SCORM 1.2 or 2004 API.
+ */
+
+// Import pipwerks (bundled with proxy package)
+// Note: pipwerks is loaded as a global in the proxy package
+// We check for it and initialize on load
+
+(function() {
+    'use strict';
+
+    // Wait for pipwerks to be available
+    if (typeof pipwerks === 'undefined') {
+        console.error('SCORM Bridge: pipwerks not loaded');
+        return;
+    }
+
+    const scorm = pipwerks.SCORM;
+    const iframe = document.getElementById('course');
+    let initialized = false;
+
+    // Derive expected course origin from build-time URL for postMessage validation
+    // COURSE_URL is injected by the build system (e.g., 'https://cdn.example.com/my-course')
+    let courseOrigin = '*'; // Fallback if URL parsing fails
+    try {
+        if (typeof COURSE_URL === 'string' && COURSE_URL && !COURSE_URL.startsWith('{{')) {
+            courseOrigin = new URL(COURSE_URL).origin;
+            console.log('SCORM Bridge: Expected course origin:', courseOrigin);
+        }
+    } catch (e) {
+        console.warn('SCORM Bridge: Could not parse COURSE_URL for origin validation:', e.message);
+    }
+
+    // Disable pipwerks auto-handling - we manage status ourselves
+    scorm.handleCompletionStatus = false;
+    scorm.handleExitMode = false;
+
+    /**
+     * Handle messages from course iframe
+     */
+    window.addEventListener('message', function(event) {
+        const { data } = event;
+
+        // Ignore non-proxy messages
+        if (!data || data.type !== 'scorm-proxy-request') {
+            return;
+        }
+
+        // Validate origin when we have a known course origin
+        if (courseOrigin !== '*' && event.origin !== courseOrigin) {
+            console.warn('SCORM Bridge: Rejected message from unexpected origin:', event.origin);
+            return;
+        }
+
+        const { id, method, args = [] } = data;
+        let result;
+        let error = null;
+
+        try {
+            switch (method) {
+                case 'Initialize':
+                    if (!initialized) {
+                        result = scorm.init();
+                        initialized = result;
+                    } else {
+                        result = true;
+                    }
+                    break;
+
+                case 'GetValue':
+                    result = scorm.get(args[0]);
+                    break;
+
+                case 'SetValue':
+                    result = scorm.set(args[0], args[1]);
+                    break;
+
+                case 'Commit':
+                    result = scorm.save();
+                    break;
+
+                case 'Terminate':
+                    result = scorm.quit();
+                    initialized = false;
+                    break;
+
+                default:
+                    error = `Unknown method: ${method}`;
+            }
+        } catch (e) {
+            error = e.message || String(e);
+            console.error('SCORM Bridge error:', method, e);
+        }
+
+        // Send response back to iframe (targeted to known origin)
+        if (iframe && iframe.contentWindow) {
+            iframe.contentWindow.postMessage({
+                type: 'scorm-proxy-response',
+                id,
+                result,
+                error
+            }, courseOrigin);
+        }
+    });
+
+    // Log bridge ready
+    console.log('SCORM Bridge: Ready (pipwerks v' + (pipwerks.version || '1.x') + ')');
+
+})();

package/lib/scaffold.js

@@ -0,0 +1,193 @@
+/**
+ * Scaffold commands — create, clean, and generate course files
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Minimal course-config.js content for blank projects
+ */
+const MINIMAL_CONFIG = `export const courseConfig = {
+    metadata: {
+        title: 'Course Title',
+        description: 'Course description',
+        version: '1.0.0',
+        language: 'en'
+    },
+    layout: 'article',
+    structure: [
+        {
+            type: 'slide',
+            id: 'intro',
+            component: '@slides/intro.js',
+            title: 'Introduction',
+            engagement: { required: false }
+        }
+    ],
+    navigation: {
+        sidebar: { enabled: true }
+    },
+    environment: {
+        automation: { enabled: true, exposeCorrectAnswers: true }
+    }
+};
+`;
+
+/**
+ * Minimal slide template
+ */
+function slideTemplate(id) {
+    const title = id.replace(/[-_]/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+    return `export const slide = {
+    render(root, context) {
+        const container = document.createElement('div');
+        container.innerHTML = \`
+            <h1>${title}</h1>
+            <p>Content goes here.</p>
+        \`;
+        return container;
+    }
+};
+`;
+}
+
+/**
+ * Minimal assessment template
+ */
+function assessmentTemplate(id) {
+    return `const { AssessmentManager, createMultipleChoiceQuestion } = CourseCode;
+
+export const config = {
+    id: '${id}',
+    assessmentObjective: null,
+    settings: {
+        passingScore: 80,
+        randomizeQuestions: false,
+        allowUnansweredSubmission: true
+    }
+};
+
+const questions = [
+    createMultipleChoiceQuestion({
+        id: '${id}-q1',
+        prompt: 'Question text?',
+        choices: [
+            { value: 'a', text: 'Option A' },
+            { value: 'b', text: 'Option B' },
+            { value: 'c', text: 'Option C' }
+        ],
+        correctAnswer: 'a',
+        controlled: true
+    })
+];
+
+export const slide = {
+    render(root) {
+        const assessment = AssessmentManager.createAssessment(config, questions);
+        return assessment.render(root);
+    }
+};
+`;
+}
+
+/**
+ * Remove all example-* files and reset config to minimal starter.
+ * Looks for course/ directory relative to cwd or a provided base path.
+ */
+export function clean(options = {}) {
+    const basePath = options.basePath || process.cwd();
+    const coursePath = path.join(basePath, 'course');
+
+    if (!fs.existsSync(coursePath)) {
+        console.error('\n❌ No course/ directory found. Are you in a CourseCode project?\n');
+        process.exit(1);
+    }
+
+    let removed = 0;
+
+    // Remove example slides
+    const slidesDir = path.join(coursePath, 'slides');
+    if (fs.existsSync(slidesDir)) {
+        for (const file of fs.readdirSync(slidesDir)) {
+            if (file.startsWith('example-')) {
+                fs.unlinkSync(path.join(slidesDir, file));
+                removed++;
+            }
+        }
+    }
+
+    // Remove example audio
+    const audioDir = path.join(coursePath, 'assets', 'audio');
+    if (fs.existsSync(audioDir)) {
+        for (const file of fs.readdirSync(audioDir)) {
+            if (file.startsWith('example-')) {
+                fs.unlinkSync(path.join(audioDir, file));
+                removed++;
+            }
+        }
+    }
+
+    // Rewrite course-config.js to minimal starter
+    const configPath = path.join(coursePath, 'course-config.js');
+    if (fs.existsSync(configPath)) {
+        fs.writeFileSync(configPath, MINIMAL_CONFIG);
+    }
+
+    // Create the intro slide if it doesn't exist
+    const introPath = path.join(slidesDir, 'intro.js');
+    if (!fs.existsSync(introPath)) {
+        fs.mkdirSync(slidesDir, { recursive: true });
+        fs.writeFileSync(introPath, slideTemplate('intro'));
+    }
+
+    console.log(`\n✅ Cleaned project — removed ${removed} example file${removed !== 1 ? 's' : ''}, reset course-config.js\n`);
+}
+
+/**
+ * Create a new slide file.
+ */
+export function newSlide(id) {
+    const slidePath = path.join(process.cwd(), 'course', 'slides', `${id}.js`);
+
+    if (fs.existsSync(slidePath)) {
+        console.error(`\n❌ Slide file already exists: course/slides/${id}.js\n`);
+        process.exit(1);
+    }
+
+    fs.mkdirSync(path.dirname(slidePath), { recursive: true });
+    fs.writeFileSync(slidePath, slideTemplate(id));
+    console.log(`\n✅ Created slide: course/slides/${id}.js\n`);
+}
+
+/**
+ * Create a new assessment file.
+ */
+export function newAssessment(id) {
+    const assessmentPath = path.join(process.cwd(), 'course', 'slides', `${id}.js`);
+
+    if (fs.existsSync(assessmentPath)) {
+        console.error(`\n❌ File already exists: course/slides/${id}.js\n`);
+        process.exit(1);
+    }
+
+    fs.mkdirSync(path.dirname(assessmentPath), { recursive: true });
+    fs.writeFileSync(assessmentPath, assessmentTemplate(id));
+    console.log(`\n✅ Created assessment: course/slides/${id}.js\n`);
+}
+
+/**
+ * Create a new course-config.js file.
+ */
+export function newConfig() {
+    const configPath = path.join(process.cwd(), 'course', 'course-config.js');
+
+    if (fs.existsSync(configPath)) {
+        console.error('\n❌ course/course-config.js already exists. Use `coursecode clean` to reset it.\n');
+        process.exit(1);
+    }
+
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, MINIMAL_CONFIG);
+    console.log('\n✅ Created course/course-config.js\n');
+}