coursecode 0.1.24 → 0.1.25

package/framework/docs/FRAMEWORK_GUIDE.md

@@ -662,6 +662,10 @@ Runs **in Node.js** during build (via `vite.framework-dev.config.js` `closeBundl
 
 **Errors fail the build; warnings print but don't block.**
 
+### MCP `coursecode_lint` — Unified Results
+
+The MCP `coursecode_lint` tool always runs the build linter. When the preview server is running and the headless browser is connected, it also merges runtime lint results (contrast, touch targets, spacing, layout) into the same response. Runtime-sourced items are tagged with `source: 'runtime'` and `rule: 'runtime-lint'`. The `runtimeLintIncluded` flag in the response indicates whether runtime checks were included. This gives AI agents a single, low-token-cost tool for all lint results without needing to pull the full course state via `coursecode_state`.
+
 ### Shared Rules (`lib/validation-rules.js`)
 
 Pure validation functions used by **both** linters. No environment-specific code (no DOM, no `fs`). Includes assessment validation, engagement validation, and result formatting.

package/lib/mcp-prompts.js

@@ -306,14 +306,17 @@ Use to discover available interactions before creating assessments.`,
 
     {
         name: 'coursecode_lint',
-        description: `Run the build-time linter and get structured results.
+        description: `Run the course linter and get structured results.
+
+Always runs build-time lint (config, CSS classes, structure). When the preview server is running and the headless browser is connected, also includes runtime lint results (contrast, touch targets, spacing, layout).
 
 Returns:
-- errors: [{slideId, rule, message, severity}]
-- warnings: [{slideId, rule, message, severity, class?, suggestion?}]
+- errors: [{slideId?, rule, message, severity, source?, hint?}]
+- warnings: [{slideId?, rule, message, severity, source?, class?, suggestion?, hint?}]
 - passed: boolean
+- runtimeLintIncluded: boolean (true when runtime checks were included)
 
-Rules detected:
+Build-time rules (always checked):
 - undefined-css-class: hallucinated or stale class names (with fix suggestions)
 - unknown-component: unregistered data-component types
 - requirement-missing-component: engagement requirement without matching component
@@ -322,9 +325,11 @@ Rules detected:
 - assessment-id-mismatch: config ID doesn't match assessment ID
 - invalid-gating: bad gating condition configuration
 
-The runtime linter (visible via coursecode_state errors/warnings) also checks:
-- Spacing: flex/grid containers without gap, adjacent elements with no margin, containers with no padding
-- Contrast, touch targets, text proximity to borders, element overlap, styled lists
+Runtime rules (included when preview is running, source='runtime'):
+- Contrast ratio violations
+- Touch target size violations
+- Spacing issues (missing gap, margin, padding)
+- Text proximity to borders, element overlap, styled lists
 
 Suppression: Add data-lint-ignore to any HTML element to suppress warnings for it and children.
   data-lint-ignore           — suppress all warnings

package/lib/mcp-server.js

@@ -247,6 +247,46 @@ export async function startMcpServer(options = {}) {
                     break;
                 case 'coursecode_lint':
                     result = await lintCourse();
+                    // Merge runtime lint errors if headless browser is already connected
+                    if (headless.isRunning()) {
+                        try {
+                            const runtimeErrors = await headless.evaluateParent(() => {
+                                return window._stubPlayerState?.errorLog || [];
+                            });
+                            if (runtimeErrors.length > 0) {
+                                const runtimeWarnings = runtimeErrors.filter(e => e.isWarning);
+                                const runtimeErrs = runtimeErrors.filter(e => !e.isWarning);
+                                if (runtimeWarnings.length > 0) {
+                                    result.warnings = (result.warnings || []).concat(
+                                        runtimeWarnings.map(e => ({
+                                            severity: 'warning',
+                                            message: e.message,
+                                            hint: e.hint,
+                                            rule: 'runtime-lint',
+                                            source: 'runtime'
+                                        }))
+                                    );
+                                    result.warningCount = result.warnings.length;
+                                }
+                                if (runtimeErrs.length > 0) {
+                                    result.errors = (result.errors || []).concat(
+                                        runtimeErrs.map(e => ({
+                                            severity: 'error',
+                                            message: e.message,
+                                            hint: e.hint,
+                                            rule: 'runtime-lint',
+                                            source: 'runtime'
+                                        }))
+                                    );
+                                    result.errorCount = result.errors.length;
+                                    result.passed = result.errors.length === 0;
+                                }
+                                result.runtimeLintIncluded = true;
+                            }
+                        } catch {
+                            // Headless browser may have disconnected — non-fatal, build lint still valid
+                        }
+                    }
                     break;
 
                 case 'coursecode_export_content':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coursecode",
-  "version": "0.1.24",
+  "version": "0.1.25",
   "description": "Multi-format course authoring framework with CLI tools (SCORM 2004, SCORM 1.2, cmi5, LTI 1.3)",
   "type": "module",
   "bin": {