coursecode 0.1.0

package/lib/mcp-server.js

@@ -0,0 +1,316 @@
+#!/usr/bin/env node
+
+/**
+ * MCP Server for CourseCode
+ * 
+ * Standalone Model Context Protocol server with persistent headless browser.
+ * Runtime tools (state, navigate, interact, screenshot) execute directly in
+ * a headless Chrome via puppeteer. Authoring tools work on the filesystem.
+ * 
+ * The MCP never starts its own preview server — it connects to one that's
+ * already running (started by the human or via `coursecode preview`).
+ * 
+ * Tool definitions and instructions live in mcp-prompts.js.
+ * 
+ * Usage: coursecode mcp [--port 4173]
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+    CallToolRequestSchema,
+    ListToolsRequestSchema
+} from '@modelcontextprotocol/sdk/types.js';
+import {
+    getCssCatalog,
+    getPreviewStatus,
+    getComponentCatalog,
+    getInteractionCatalog,
+    getIconCatalog,
+    lintCourse,
+    buildCourse
+} from './authoring-api.js';
+import { getContentExport } from './export-content.js';
+import headless from './headless-browser.js';
+import { TOOLS, buildInstructions, getWorkflowStatusWithInstructions } from './mcp-prompts.js';
+
+const DEFAULT_PORT = 4173;
+
+/**
+ * Ensure headless browser is connected to preview server.
+ * Fails fast if preview is not running — humans own the preview lifecycle.
+ */
+async function ensureHeadless(port) {
+    if (!headless.isRunning()) {
+        const status = await getPreviewStatus(port);
+        if (!status.running) {
+            throw new Error(
+                'Preview server not running. Start it first:\n' +
+                '  • Human: run `coursecode preview` in a terminal\n' +
+                '  • AI agent: use run_command to execute `npm run preview`\n' +
+                'Then retry this tool call.'
+            );
+        }
+        await headless.launch(port);
+    }
+}
+
+/**
+ * Create and run the MCP server
+ */
+export async function startMcpServer(options = {}) {
+    const port = options.port || DEFAULT_PORT;
+    
+    // Build dynamic instructions for current authoring stage
+    const instructions = await buildInstructions(port);
+
+    const server = new Server(
+        {
+            name: 'coursecode',
+            version: '2.0.0',
+            instructions
+        },
+        {
+            capabilities: {
+                tools: {}
+            }
+        }
+    );
+
+    // ========================================
+    // Tool Request Handlers
+    // ========================================
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        return { tools: TOOLS };
+    });
+
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        
+        try {
+            let result;
+            
+            switch (name) {
+                // === Runtime tools (headless browser) ===
+                case 'coursecode_state':
+                    await ensureHeadless(port);
+                    result = await headless.evaluate(() => {
+                        const api = window.CourseCodeAutomation;
+                        return {
+                            slide: api.getCurrentSlide(),
+                            toc: api.getToc(),
+                            interactions: api.listInteractions(),
+                            engagement: api.getEngagementState(),
+                            frameworkLogs: api.getFrameworkLogs(),
+                            lmsState: api.getLmsState()
+                        };
+                    });
+                    // Read last 20 API log entries from parent window (stub player diagnostic)
+                    result.apiLog = await headless.evaluateParent(() => {
+                        return window._stubPlayerState?.apiLog?.slice(0, 20) || [];
+                    });
+                    // Read error log from parent window (stub player diagnostic)
+                    result.errors = await headless.evaluateParent(() => {
+                        return window._stubPlayerState?.errorLog || [];
+                    });
+                    // Append console errors/warnings captured from the page
+                    result.consoleLogs = headless.getConsoleLogs();
+                    break;
+
+                case 'coursecode_navigate':
+                    if (!args?.slideId) throw new Error('slideId is required');
+                    await ensureHeadless(port);
+                    // Apply accessibility preferences before navigation
+                    if (args.theme || args.highContrast !== undefined) {
+                        await headless.evaluate(({ theme, highContrast }) => {
+                            const api = window.CourseCodeAutomation;
+                            if (theme) api.setAccessibilityPreference('theme', theme);
+                            if (highContrast !== undefined) api.setAccessibilityPreference('highContrast', highContrast);
+                        }, { theme: args.theme, highContrast: args.highContrast });
+                        // Allow DOM to update after preference change
+                        await new Promise(resolve => setTimeout(resolve, 50));
+                    }
+                    // Validate slide ID exists before navigating (avoids EventBus error cascades)
+                    {
+                        const validSlide = await headless.evaluate((slideId) => {
+                            const toc = window.CourseCodeAutomation.getToc();
+                            return toc.some(item => item.id === slideId);
+                        }, args.slideId);
+                        if (!validSlide) {
+                            throw new Error(`Slide "${args.slideId}" not found. Use coursecode_state to get valid slide IDs.`);
+                        }
+                    }
+                    await headless.evaluate((slideId) => {
+                        window.CourseCodeAutomation.goToSlide(slideId);
+                    }, args.slideId);
+                    // State updates asynchronously after navigation
+                    await new Promise(resolve => setTimeout(resolve, 50));
+                    result = await headless.evaluate(() => {
+                        const api = window.CourseCodeAutomation;
+                        return {
+                            slide: api.getCurrentSlide(),
+                            interactions: api.listInteractions(),
+                            engagement: api.getEngagementState(),
+                            accessibility: api.getAccessibilityState()
+                        };
+                    });
+                    break;
+
+                case 'coursecode_interact':
+                    if (!args?.interactionId) throw new Error('interactionId is required');
+                    if (args.response === undefined) throw new Error('response is required');
+                    await ensureHeadless(port);
+                    result = await headless.evaluate(({ interactionId, response }) => {
+                        const api = window.CourseCodeAutomation;
+                        api.setResponse(interactionId, response);
+                        const checkResult = api.checkAnswer(interactionId);
+                        return {
+                            ...checkResult,
+                            state: {
+                                slide: api.getCurrentSlide(),
+                                interactions: api.listInteractions()
+                            }
+                        };
+                    }, { interactionId: args.interactionId, response: args.response });
+                    break;
+
+                case 'coursecode_reset':
+                    await ensureHeadless(port);
+                    await headless.evaluate(() => {
+                        localStorage.clear();
+                    });
+                    // Full browser restart to ensure clean state
+                    await headless.shutdown();
+                    await headless.launch(port);
+                    result = { reset: true };
+                    break;
+
+                case 'coursecode_screenshot':
+                    await ensureHeadless(port);
+                    // Validate slide ID if provided (same guard as navigate)
+                    if (args?.slideId) {
+                        const validSlide = await headless.evaluate((slideId) => {
+                            const toc = window.CourseCodeAutomation.getToc();
+                            return toc.some(item => item.id === slideId);
+                        }, args.slideId);
+                        if (!validSlide) {
+                            throw new Error(`Slide "${args.slideId}" not found. Use coursecode_state to get valid slide IDs.`);
+                        }
+                    }
+                    result = await headless.screenshot({
+                        slideId: args?.slideId,
+                        fullPage: args?.fullPage,
+                        detailed: args?.detailed,
+                        scrollY: args?.scrollY
+                    });
+                    return {
+                        content: [{
+                            type: 'image',
+                            data: result.data,
+                            mimeType: result.mimeType
+                        }]
+                    };
+
+                // === Workflow & build tools ===
+                case 'coursecode_workflow_status':
+                    result = await getWorkflowStatusWithInstructions(port);
+                    break;
+
+                case 'coursecode_build':
+                    result = await buildCourse(args || {});
+                    break;
+
+                // === Catalog & validation tools (filesystem, no preview needed) ===
+                case 'coursecode_css_catalog':
+                    result = getCssCatalog(args?.category);
+                    break;
+
+                case 'coursecode_component_catalog':
+                    result = getComponentCatalog(args?.type);
+                    break;
+                case 'coursecode_interaction_catalog':
+                    result = getInteractionCatalog(args?.type);
+                    break;
+                case 'coursecode_icon_catalog':
+                    result = getIconCatalog(args?.name);
+                    break;
+                case 'coursecode_lint':
+                    result = await lintCourse();
+                    break;
+
+                case 'coursecode_export_content':
+                    result = await getContentExport(args || {});
+                    if (result === null) {
+                        throw new Error('Failed to export content. Ensure course-config.js exists in course/');
+                    }
+                    return {
+                        content: [{
+                            type: 'text',
+                            text: result
+                        }]
+                    };
+
+                default:
+                    throw new Error(`Unknown tool: ${name}`);
+            }
+            
+            return {
+                content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2)
+                }]
+            };
+        } catch (error) {
+            return {
+                content: [{
+                    type: 'text',
+                    text: `Error: ${error.message}`
+                }],
+                isError: true
+            };
+        }
+    });
+
+    // Graceful shutdown — clean up headless browser only.
+    // browser.close() tears down the entire Chrome process tree (parent + all
+    // child processes like GPU, renderer, utility). No manual PID hunting needed.
+    let cleaningUp = false;
+    const cleanup = async () => {
+        if (cleaningUp) return;
+        cleaningUp = true;
+        if (headless.isRunning()) {
+            await headless.shutdown();
+        }
+    };
+
+    process.on('SIGINT', async () => { await cleanup(); process.exit(0); });
+    process.on('SIGTERM', async () => { await cleanup(); process.exit(0); });
+
+    // Detect MCP host disconnect — when the IDE/editor drops the stdio pipe,
+    // stdin emits 'close'. This is the primary cleanup signal since SIGINT/SIGTERM
+    // are NOT sent when the host simply closes the transport.
+    process.stdin.on('close', async () => { await cleanup(); process.exit(0); });
+
+    process.on('uncaughtException', async (err) => {
+        process.stderr.write(`MCP uncaught exception: ${err.message}\n`);
+        await cleanup();
+        process.exit(1);
+    });
+    process.on('unhandledRejection', async (err) => {
+        process.stderr.write(`MCP unhandled rejection: ${err}\n`);
+        await cleanup();
+        process.exit(1);
+    });
+
+    // Start the server
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+
+// CLI entry point
+if (process.argv[1]?.endsWith('mcp-server.js')) {
+    const args = process.argv.slice(2);
+    const portArg = args.find(a => a.startsWith('--port='));
+    const port = portArg ? parseInt(portArg.split('=')[1], 10) : DEFAULT_PORT;
+    startMcpServer({ port });
+}

package/lib/narration.js

@@ -0,0 +1,53 @@
+/**
+ * Narration command - generate audio narration from text
+ */
+
+import { spawn } from 'child_process';
+import path from 'path';
+import fs from 'fs';
+import { validateProject } from './project-utils.js';
+
+
+export async function narration(options = {}) {
+  validateProject();
+  
+  const scriptPath = path.join(process.cwd(), 'framework', 'scripts', 'generate-narration.js');
+  
+  if (!fs.existsSync(scriptPath)) {
+    console.error(`
+❌ Narration script not found at: framework/scripts/generate-narration.js
+
+   Make sure your framework is up to date:
+   scorm upgrade
+`);
+    process.exit(1);
+  }
+  
+  console.log(`
+🎙️  Generating audio narration...
+`);
+  
+  // Build args
+  const args = [scriptPath];
+  if (options.force) args.push('--force');
+  if (options.slide) args.push('--slide', options.slide);
+  if (options.dryRun) args.push('--dry-run');
+  
+  return new Promise((resolve, reject) => {
+    const child = spawn('node', args, {
+      cwd: process.cwd(),
+      stdio: 'inherit',
+      shell: true
+    });
+    
+    child.on('close', (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new Error(`Narration generation failed with code ${code}`));
+      }
+    });
+    
+    child.on('error', reject);
+  });
+}

package/lib/pdf-structure.js

@@ -0,0 +1,142 @@
+import PDFParser from 'pdf2json';
+
+
+/**
+ * Custom PDF Structure Parser
+ * Uses pdf2json to extract text with layout information, then applies heuristics
+ * to identify headers and reconstruct document structure.
+ */
+export function parsePdfStructure(filePath) {
+    const pdfParser = new PDFParser();
+
+    return new Promise((resolve, reject) => {
+        pdfParser.on('pdfParser_dataError', errData => reject(errData.parserError));
+        pdfParser.on('pdfParser_dataReady', pdfData => {
+            try {
+                const structure = processPdfData(pdfData);
+                resolve(structure);
+            } catch (err) {
+                reject(err);
+            }
+        });
+
+        pdfParser.loadPDF(filePath);
+    });
+}
+
+function processPdfData(pdfData) {
+    const pages = pdfData.Pages || [];
+    let allTextBlocks = [];
+
+    // 1. Flatten all text blocks across pages
+    pages.forEach((page, pageIndex) => {
+        const texts = page.Texts || [];
+        texts.forEach(text => {
+            // text.R is an array of runs (usually 1)
+            // text.x, text.y are position units (approx 1/25th of an inch?)
+            
+            const content = text.R.map(run => decodeURIComponent(run.T)).join('');
+            
+            // TS = [fontId, fontSize, isBold, isItalic]
+            // We need to parse TS from the first run
+            const run = text.R[0];
+            const fontSize = run?.TS?.[1] || 12; 
+            const isBold = run?.TS?.[2] === 1;
+
+            if (content.trim()) {
+                allTextBlocks.push({
+                    text: content,
+                    x: text.x, 
+                    y: text.y + (pageIndex * 100), // Global Y including page offset (heuristic 100 units per page)
+                    w: text.w,
+                    fontSize,
+                    isBold,
+                    page: pageIndex + 1
+                });
+            }
+        });
+    });
+
+    // 2. Determine "Body Text" font size (most common size)
+    const sizeCounts = {};
+    allTextBlocks.forEach(block => {
+        const size = Math.round(block.fontSize * 10) / 10;
+        sizeCounts[size] = (sizeCounts[size] || 0) + 1;
+    });
+    
+    let bodySize = 0;
+    let maxCount = 0;
+    for (const [size, count] of Object.entries(sizeCounts)) {
+        if (count > maxCount) {
+            maxCount = count;
+            bodySize = parseFloat(size);
+        }
+    }
+
+    // 3. Sort by Page -> Y -> X
+    allTextBlocks.sort((a, b) => {
+        if (a.page !== b.page) return a.page - b.page;
+        if (Math.abs(a.y - b.y) > 0.5) return a.y - b.y; // Roughly same line
+        return a.x - b.x;
+    });
+
+    // 4. Cluster into elements
+    const elements = [];
+    let currentElement = null;
+
+    allTextBlocks.forEach((block, index) => {
+        const isHeader = block.fontSize > bodySize * 1.1 || (block.isBold && block.fontSize >= bodySize);
+        const headingLevel = isHeader ? calculateHeaderLevel(block.fontSize, bodySize) : 0;
+        const type = isHeader ? `h${headingLevel}` : 'p';
+
+        // Check proximity to previous block
+        const prevBlock = allTextBlocks[index - 1];
+        
+        // Vertical gap check (heuristic)
+        // If gap is small, it's likely the same paragraph
+        // If gap is large, it's a new paragraph
+        // If type changed (header <-> p), it's a new element
+
+        let isSameElement = false;
+        if (currentElement && currentElement.type === type && prevBlock) {
+             const verticalGap = block.y - prevBlock.y;
+             // Line height heuristic: adjacent lines are usually < 1.5 units apart in pdf2json coords
+             if (verticalGap < 2 && verticalGap > -0.5) { 
+                 isSameElement = true;
+             }
+        }
+
+        if (isSameElement) {
+            currentElement.text += ' ' + decode(block.text);
+        } else {
+            if (currentElement) elements.push(currentElement);
+            currentElement = {
+                type,
+                text: decode(block.text),
+                page: block.page,
+                metadata: {
+                  fontSize: block.fontSize,
+                  isBold: block.isBold
+                }
+            };
+        }
+    });
+
+    if (currentElement) elements.push(currentElement);
+
+    return {
+        metadata: pdfData.Meta,
+        elements
+    };
+}
+
+function calculateHeaderLevel(size, bodySize) {
+    const ratio = size / bodySize;
+    if (ratio > 1.5) return 1;
+    if (ratio > 1.2) return 2;
+    return 3;
+}
+
+function decode(str) {
+    return str.replace(/\s+/g, ' ').trim();
+}