coursecode 0.1.53 → 0.1.55

package/lib/create.js

@@ -77,6 +77,42 @@ function copyDir(src, dest, options = {}) {
   }
 }
 
+function mergeProjectControlFile(sourcePath, destinationPath) {
+  const source = fs.readFileSync(sourcePath, 'utf-8').trimEnd();
+  if (!fs.existsSync(destinationPath)) {
+    fs.writeFileSync(destinationPath, `${source}\n`, 'utf-8');
+    return;
+  }
+
+  const current = fs.readFileSync(destinationPath, 'utf-8');
+  const existingLines = new Set(current.split(/\r?\n/).map(line => line.trim()));
+  const missingRules = source
+    .split(/\r?\n/)
+    .filter(line => line.trim() && !line.trim().startsWith('#') && !existingLines.has(line.trim()));
+
+  if (missingRules.length === 0) return;
+
+  const separator = current.endsWith('\n') ? '\n' : '\n\n';
+  fs.appendFileSync(
+    destinationPath,
+    `${separator}# CourseCode project defaults\n${missingRules.join('\n')}\n`,
+    'utf-8'
+  );
+}
+
+function assertCurrentDirectoryCanBeInitialized(targetDir, templateDir) {
+  const managedPaths = fs.readdirSync(templateDir)
+    .filter(name => !['.DS_Store', 'gitignore', 'gitattributes'].includes(name))
+    .concat(['framework', 'schemas', 'lib', '.coursecoderc.json']);
+  const conflicts = managedPaths.filter(name => fs.existsSync(path.join(targetDir, name)));
+
+  if (conflicts.length > 0) {
+    throw new Error(
+      `Cannot initialize the current directory because CourseCode-managed paths already exist: ${conflicts.join(', ')}`
+    );
+  }
+}
+
 /**
  * Run npm install in directory
  */
@@ -123,7 +159,10 @@ function gitInit(cwd) {
 }
 
 export async function create(name, options = {}) {
-  const displayName = String(name || '').trim();
+  const requestedName = String(name || '').trim();
+  const currentDirectory = options.currentDirectory === true || requestedName === '.';
+  const inferredName = path.basename(process.cwd()).replace(/[-_]+/g, ' ');
+  const displayName = currentDirectory && requestedName === '.' ? inferredName : requestedName;
   const directoryName = toProjectDirectoryName(displayName);
 
   if (!displayName) {
@@ -136,16 +175,18 @@ export async function create(name, options = {}) {
     process.exit(1);
   }
 
-  const targetDir = path.resolve(process.cwd(), directoryName);
+  const targetDir = currentDirectory ? path.resolve(process.cwd()) : path.resolve(process.cwd(), directoryName);
+  const templateDir = path.join(PACKAGE_ROOT, 'template');
 
-  // Check if directory already exists
-  if (fs.existsSync(targetDir)) {
+  if (currentDirectory) {
+    assertCurrentDirectoryCanBeInitialized(targetDir, templateDir);
+  } else if (fs.existsSync(targetDir)) {
     console.error(`\n❌ Directory "${directoryName}" already exists.\n`);
     process.exit(1);
   }
 
   console.log(`\n🚀 Creating CourseCode project: ${displayName}\n`);
-  if (directoryName !== displayName) {
+  if (!currentDirectory && directoryName !== displayName) {
     console.log(`   Project folder: ${directoryName}`);
   }
 
@@ -153,11 +194,12 @@ export async function create(name, options = {}) {
   fs.mkdirSync(targetDir, { recursive: true });
 
   // Copy template files (course directory and vite config)
-  const templateDir = path.join(PACKAGE_ROOT, 'template');
   console.log('   Copying template files...');
   copyDir(templateDir, targetDir, {
-    exclude: [/^\.DS_Store$/, /^node_modules$/]
+    exclude: [/^\.DS_Store$/, /^node_modules$/, /^gitignore$/, /^gitattributes$/]
   });
+  mergeProjectControlFile(path.join(templateDir, 'gitignore'), path.join(targetDir, '.gitignore'));
+  mergeProjectControlFile(path.join(templateDir, 'gitattributes'), path.join(targetDir, '.gitattributes'));
 
   // Copy framework
   const frameworkSrc = path.join(PACKAGE_ROOT, 'framework');
@@ -189,14 +231,19 @@ export async function create(name, options = {}) {
   console.log('   Copying proxy packaging templates...');
   copyDir(proxyTemplatesSrc, proxyTemplatesDest);
 
-  // Read and customize package.json
+  // Read and customize package.json. Pin the authoring/build CLI to the
+  // version that created the project so an isolated checkout can build.
+  const frameworkPkg = JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, 'package.json'), 'utf-8'));
   const pkgPath = path.join(targetDir, 'package.json');
   const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
   pkg.name = directoryName;
+  pkg.devDependencies = {
+    ...pkg.devDependencies,
+    coursecode: `^${frameworkPkg.version}`
+  };
   fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2));
 
   // Create .coursecoderc.json to track framework version
-  const frameworkPkg = JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, 'package.json'), 'utf-8'));
   const coursecoderc = {
     frameworkVersion: frameworkPkg.version,
     createdAt: new Date().toISOString(),
@@ -212,7 +259,7 @@ export async function create(name, options = {}) {
   // If --blank, remove example files and reset config
   if (options.blank) {
     const { clean } = await import('./scaffold.js');
-    clean({ basePath: targetDir });
+    clean({ basePath: targetDir, blank: true });
   }
 
   writeCourseTitle(targetDir, displayName);
@@ -229,12 +276,16 @@ export async function create(name, options = {}) {
   }
 
   // Initialize git repository
-  console.log('\n   Initializing git repository...');
-  try {
-    await gitInit(targetDir);
-    console.log('   ✅ Git repository initialized');
-  } catch (_error) {
-    console.warn('   ⚠️  Git init failed. You can run "git init" manually.');
+  if (fs.existsSync(path.join(targetDir, '.git'))) {
+    console.log('\n   ✅ Existing Git repository preserved');
+  } else {
+    console.log('\n   Initializing git repository...');
+    try {
+      await gitInit(targetDir);
+      console.log('   ✅ Git repository initialized');
+    } catch (_error) {
+      console.warn('   ⚠️  Git init failed. You can run "git init" manually.');
+    }
   }
 
   // Print success message
@@ -287,12 +338,14 @@ export async function create(name, options = {}) {
       console.log(`      cd ${directoryName} && coursecode dev\n`);
     });
   } else {
-    console.log(`\n   To start developing:\n\n      cd ${directoryName}\n      coursecode dev\n`);
+    const changeDirectory = currentDirectory ? '' : `cd ${directoryName}\n      `;
+    console.log(`\n   To start developing:\n\n      ${changeDirectory}coursecode dev\n`);
   }
 
   return {
     displayName,
     directoryName,
-    targetDir
+    targetDir,
+    currentDirectory
   };
 }

package/lib/manifest/cmi5-manifest.js

@@ -10,6 +10,8 @@
  * For cmi5-remote format, the AU URL is absolute (pointing to CDN).
  */
 
+import { escapeXmlAttribute, escapeXmlText } from './xml-utils.js';
+
 /**
  * Generates the cmi5 course structure XML.
  * @param {Object} config - Course configuration
@@ -23,39 +25,46 @@ export function generateCmi5Manifest(config, _files, options = {}) {
   const courseId = config.identifier ||
     `urn:coursecode:${config.title.replace(/[^a-zA-Z0-9]/g, '-').toLowerCase()}`;
 
-  // Calculate mastery score from passing percentage (convert percentage to 0-1 scale)
-  const masteryScore = config.passingScore ? (config.passingScore / 100).toFixed(2) : '0.8';
+  // Package-level mastery is optional. Do not invent a value from one
+  // assessment because a course can contain multiple thresholds.
+  const masteryAttribute = Number.isFinite(config.masteryScore)
+    ? ` masteryScore="${(config.masteryScore / 100).toFixed(2)}"`
+    : '';
 
   // AU identifier - derive from course ID
   const auId = `${courseId}/au/1`;
 
   // URL: absolute for cmi5-remote (use as-is), relative for standard cmi5
   const auUrl = options.externalUrl || 'index.html';
+  const escapedCourseId = escapeXmlAttribute(courseId);
+  const escapedAuId = escapeXmlAttribute(auId);
+  const escapedLanguage = escapeXmlAttribute(config.language);
+  const title = escapeXmlText(config.title);
+  const description = escapeXmlText(config.description);
 
   return `<?xml version="1.0" encoding="UTF-8"?>
 <!-- cmi5 Course Structure - GENERATED FILE - DO NOT EDIT MANUALLY -->
 <courseStructure xmlns="https://w3id.org/xapi/profiles/cmi5/v1/CourseStructure.xsd">
 
-  <course id="${courseId}">
+  <course id="${escapedCourseId}">
     <title>
-      <langstring lang="${config.language}">${config.title}</langstring>
+      <langstring lang="${escapedLanguage}">${title}</langstring>
     </title>
     <description>
-      <langstring lang="${config.language}">${config.description}</langstring>
+      <langstring lang="${escapedLanguage}">${description}</langstring>
     </description>
   </course>
 
-  <au id="${auId}" moveOn="Completed" masteryScore="${masteryScore}" launchMethod="OwnWindow">
+  <au id="${escapedAuId}" moveOn="Completed"${masteryAttribute} launchMethod="OwnWindow">
     <title>
-      <langstring lang="${config.language}">${config.title}</langstring>
+      <langstring lang="${escapedLanguage}">${title}</langstring>
     </title>
     <description>
-      <langstring lang="${config.language}">${config.description}</langstring>
+      <langstring lang="${escapedLanguage}">${description}</langstring>
     </description>
-    <url>${auUrl}</url>
+    <url>${escapeXmlText(auUrl)}</url>
   </au>
 
 </courseStructure>
 `;
 }
-

package/lib/manifest/lti-tool-config.js

@@ -12,7 +12,21 @@
  * @returns {string} JSON string of tool configuration
  */
 export function generateLtiToolConfig(config, options = {}) {
-    const baseUrl = options.externalUrl || config.externalUrl || 'https://your-course-host.example.com';
+    const configuredUrl = options.externalUrl || config.externalUrl;
+    if (!configuredUrl) {
+        throw new Error('LTI builds require externalUrl for a trusted server-side OIDC/AGS backend');
+    }
+
+    let parsedBaseUrl;
+    try {
+        parsedBaseUrl = new URL(configuredUrl);
+    } catch {
+        throw new Error(`Invalid LTI externalUrl: ${configuredUrl}`);
+    }
+    if (!['https:', 'http:'].includes(parsedBaseUrl.protocol)) {
+        throw new Error('LTI externalUrl must use https (or http for local development)');
+    }
+    const baseUrl = parsedBaseUrl.toString().replace(/\/$/, '');
     const title = config.title || 'CourseCode Course';
     const description = config.description || '';
 
@@ -24,7 +38,6 @@ export function generateLtiToolConfig(config, options = {}) {
         'grant_types': ['implicit', 'client_credentials'],
         'initiate_login_uri': `${baseUrl}/lti/login`,
         'redirect_uris': [
-            `${baseUrl}/index.html`,
             `${baseUrl}/lti/launch`
         ],
         'client_name': title,
@@ -35,14 +48,14 @@ export function generateLtiToolConfig(config, options = {}) {
 
         // LTI-specific claims
         'https://purl.imsglobal.org/spec/lti-tool-configuration': {
-            'domain': new URL(baseUrl).hostname,
+            'domain': parsedBaseUrl.hostname,
             'description': description,
-            'target_link_uri': `${baseUrl}/index.html`,
+            'target_link_uri': `${baseUrl}/lti/launch`,
             'claims': ['iss', 'sub', 'name', 'given_name', 'family_name', 'email'],
             'messages': [
                 {
                     'type': 'LtiResourceLinkRequest',
-                    'target_link_uri': `${baseUrl}/index.html`,
+                    'target_link_uri': `${baseUrl}/lti/launch`,
                     'label': title
                 }
             ]

package/lib/manifest/scorm-12-manifest.js

@@ -8,6 +8,8 @@
  * - 4th Edition schema references
  */
 
+import { escapeXmlAttribute, escapeXmlText } from './xml-utils.js';
+
 /**
  * Generates the SCORM 1.2 manifest.
  * @param {Object} config - Course configuration
@@ -22,13 +24,18 @@ export function generateScorm12Manifest(config, files) {
         !f.startsWith('common/')
     );
 
-    const fileEntries = resourceFiles.map(f => `      <file href="${f}"/>`).join('\n');
+    const fileEntries = resourceFiles.map(f => `      <file href="${escapeXmlAttribute(f)}"/>`).join('\n');
+    const version = escapeXmlAttribute(config.version);
+    const title = escapeXmlText(config.title);
+    const masteryScore = Number.isFinite(config.masteryScore)
+        ? `\n        <adlcp:masteryscore>${config.masteryScore}</adlcp:masteryscore>`
+        : '';
 
     // SCORM 1.2 uses ADLCP 1.2 schema and doesn't include sequencing
     return `<?xml version="1.0" encoding="UTF-8"?>
 <!-- SCORM 1.2 manifest - GENERATED FILE - DO NOT EDIT MANUALLY -->
 <manifest identifier="${config.title.replace(/[^a-zA-Z0-9]/g, '-')}"
-          version="${config.version}"
+          version="${version}"
           xmlns="http://www.imsproject.org/xsd/imscp_rootv1p1p2"
           xmlns:adlcp="http://www.adlnet.org/xsd/adlcp_rootv1p2"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -43,10 +50,9 @@ export function generateScorm12Manifest(config, files) {
 
   <organizations default="org-1">
     <organization identifier="org-1">
-      <title>${config.title}</title>
+      <title>${title}</title>
       <item identifier="item-1" identifierref="res-1" isvisible="true">
-        <title>${config.title}</title>
-        <adlcp:masteryscore>80</adlcp:masteryscore>
+        <title>${title}</title>${masteryScore}
       </item>
     </organization>
   </organizations>

package/lib/manifest/scorm-2004-manifest.js

@@ -3,6 +3,8 @@
  * @description Generates imsmanifest.xml for SCORM 2004 4th Edition packages.
  */
 
+import { escapeXmlAttribute, escapeXmlText } from './xml-utils.js';
+
 /**
  * Generates the SCORM 2004 4th Edition manifest.
  * @param {Object} config - Course configuration
@@ -17,12 +19,17 @@ export function generateScorm2004Manifest(config, files) {
         !f.startsWith('common/')
     );
 
-    const fileEntries = resourceFiles.map(f => `      <file href="${f}"/>`).join('\n');
+    const fileEntries = resourceFiles.map(f => `      <file href="${escapeXmlAttribute(f)}"/>`).join('\n');
+    const version = escapeXmlAttribute(config.version);
+    const language = escapeXmlAttribute(config.language);
+    const title = escapeXmlText(config.title);
+    const description = escapeXmlText(config.description);
+    const author = escapeXmlText(config.author);
 
     return `<?xml version="1.0" encoding="UTF-8"?>
 <!-- SCORM 2004 4th Edition manifest - GENERATED FILE - DO NOT EDIT MANUALLY -->
 <manifest identifier="${config.title.replace(/[^a-zA-Z0-9]/g, '-')}"
-            version="${config.version}"
+            version="${version}"
             xmlns="http://www.imsglobal.org/xsd/imscp_v1p1"
             xmlns:imscp="http://www.imsglobal.org/xsd/imscp_v1p1"
             xmlns:imsss="http://www.imsglobal.org/xsd/imsss"
@@ -45,18 +52,18 @@ export function generateScorm2004Manifest(config, files) {
     <schemaversion>2004 4th Edition</schemaversion>
     <lom:lom>
       <lom:general>
-        <lom:title><lom:string language="${config.language}">${config.title}</lom:string></lom:title>
-        <lom:description><lom:string language="${config.language}">${config.description}</lom:string></lom:description>
-        <lom:language>${config.language}</lom:language>
+        <lom:title><lom:string language="${language}">${title}</lom:string></lom:title>
+        <lom:description><lom:string language="${language}">${description}</lom:string></lom:description>
+        <lom:language>${escapeXmlText(config.language)}</lom:language>
       </lom:general>
       <lom:lifecycle>
-        <lom:version><lom:string>${config.version}</lom:string></lom:version>
+        <lom:version><lom:string>${escapeXmlText(config.version)}</lom:string></lom:version>
         <lom:contribute>
           <lom:role>
             <lom:source><lom:string>LOMv1.0</lom:string></lom:source>
             <lom:value><lom:string>author</lom:string></lom:value>
           </lom:role>
-          <lom:entity>${config.author}</lom:entity>
+          <lom:entity>${author}</lom:entity>
         </lom:contribute>
       </lom:lifecycle>
       <lom:technical>
@@ -67,9 +74,9 @@ export function generateScorm2004Manifest(config, files) {
 
   <organizations default="org-1">
     <organization identifier="org-1" adlseq:objectivesGlobalToSystem="false">
-      <title>${config.title}</title>
+      <title>${title}</title>
       <item identifier="item-1" identifierref="res-1" isvisible="true">
-        <title>${config.title}</title>
+        <title>${title}</title>
         <imsss:sequencing>
           <imsss:controlMode choiceExit="true" forwardOnly="false"/>
           <imsss:deliveryControls tracked="true" completionSetByContent="true" objectiveSetByContent="true"/>

package/lib/manifest/xml-utils.js

@@ -0,0 +1,14 @@
+/** Escape text inserted into XML element content. */
+export function escapeXmlText(value) {
+    return String(value ?? '')
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}
+
+/** Escape text inserted into a double-quoted XML attribute. */
+export function escapeXmlAttribute(value) {
+    return escapeXmlText(value)
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}

package/lib/preview-routes-api.js

@@ -13,6 +13,7 @@ import { generateContentHtml } from './stub-player/content-generator.js';
 import { parseCourse } from './course-parser.js';
 import { getComponentCatalog, getInteractionCatalog, getIconCatalog, getWorkflowStatus, getRefsStatus, buildCourse } from './authoring-api.js';
 import { getAllIcons, getAllSchemas } from './schema-extractor.js';
+import { escapeHtml, resolveWithinRoot } from './project-utils.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -657,12 +658,19 @@ export async function handleApiRoutes(ctx, req, res, url) {
     if (url === '/__stub-player/ref-preview') {
         const params = new URL(req.url, 'http://localhost').searchParams;
         const fileName = params.get('file');
-        if (!fileName || fileName.includes('..')) {
+        if (!fileName) {
             res.writeHead(400, { 'Content-Type': 'text/plain' });
             res.end('Invalid file parameter');
             return true;
         }
-        const filePath = path.join(paths.coursePath, 'references', 'converted', fileName);
+        let filePath;
+        try {
+            filePath = resolveWithinRoot(path.join(paths.coursePath, 'references', 'converted'), fileName);
+        } catch {
+            res.writeHead(403, { 'Content-Type': 'text/plain' });
+            res.end('Forbidden');
+            return true;
+        }
         if (!fs.existsSync(filePath)) {
             res.writeHead(404, { 'Content-Type': 'text/plain' });
             res.end('File not found');
@@ -676,7 +684,7 @@ export async function handleApiRoutes(ctx, req, res, url) {
 <head>
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>${fileName} – Reference Preview</title>
+    <title>${escapeHtml(fileName)} – Reference Preview</title>
     <link rel="stylesheet" href="/__stub-player/styles.css">
     <style>
         body { padding: 40px; max-width: 900px; margin: 0 auto; font-family: system-ui, -apple-system, sans-serif; line-height: 1.6; background: var(--color-primary-deep, #0b1628); color: var(--color-gray-200, #d1d5db); }
@@ -686,7 +694,7 @@ export async function handleApiRoutes(ctx, req, res, url) {
     </style>
 </head>
 <body>
-    <h1>${fileName}</h1>
+    <h1>${escapeHtml(fileName)}</h1>
     ${html}
 </body>
 </html>`);
@@ -696,13 +704,14 @@ export async function handleApiRoutes(ctx, req, res, url) {
     // Stub player static files
     if (url.startsWith('/__stub-player/')) {
         const relativePath = url.slice('/__stub-player/'.length);
-        if (relativePath.includes('..')) {
+        let filePath;
+        try {
+            filePath = resolveWithinRoot(path.join(__dirname, 'stub-player'), relativePath);
+        } catch {
             res.writeHead(403);
             res.end('Forbidden');
             return true;
         }
-
-        const filePath = path.join(__dirname, 'stub-player', relativePath);
         fs.stat(filePath, (err, stats) => {
             if (err || !stats.isFile()) {
                 res.writeHead(404);

package/lib/preview-server.js

@@ -12,7 +12,8 @@
 import fs from 'fs';
 import path from 'path';
 import http from 'http';
-import { spawn, exec } from 'child_process';
+import crypto from 'crypto';
+import { spawn } from 'child_process';
 import { fileURLToPath } from 'url';
 
 import { generateStubPlayer } from './stub-player.js';
@@ -24,7 +25,7 @@ import { handleEditingRoutes } from './preview-routes-editing.js';
 import { handleLmsRoutes, createLmsStore } from './preview-routes-lms.js';
 import {
     validateProject, escapeHtml, getMimeType, serveFile,
-    countSlides, findSlideById, collectSlideIds
+    countSlides, findSlideById, collectSlideIds, resolveWithinRoot
 } from './project-utils.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -196,6 +197,15 @@ function getCourseTitle(coursePath) {
     }
 }
 
+export function requiresPreviewMutationToken(method, url) {
+    return !['GET', 'HEAD', 'OPTIONS'].includes(String(method || 'GET').toUpperCase()) &&
+        url.startsWith('/__') && !url.startsWith('/__lms/');
+}
+
+export function hasValidPreviewMutationToken(headers, expectedToken) {
+    return Boolean(expectedToken) && headers?.['x-coursecode-preview-token'] === expectedToken;
+}
+
 
 
 // ============================================================================
@@ -207,6 +217,8 @@ export async function previewServer(options = {}) {
     const paths = validateProject({ frameworkDev });
     const title = options.title || getCourseTitle(paths.coursePath);
     const previewPort = parseInt(options.port || '4173', 10);
+    const previewHost = options.host || '127.0.0.1';
+    const previewToken = crypto.randomBytes(32).toString('base64url');
     const distDir = path.join(process.cwd(), 'dist');
 
     console.log('\n🚀 Starting preview server...');
@@ -347,6 +359,7 @@ export async function previewServer(options = {}) {
         password: null,
         isLive: true,
         liveReload: true,
+        previewToken,
         courseContent,
         isDesktop: options.desktop || false
     });
@@ -374,6 +387,16 @@ export async function previewServer(options = {}) {
     const server = http.createServer(async (req, res) => {
         const url = req.url.split('?')[0];
 
+        // All source/file mutations require a per-process capability token.
+        // LMS state synchronization is intentionally exempt: it only touches
+        // the in-memory test store and is used directly by E2E helpers.
+        const isMutation = requiresPreviewMutationToken(req.method, url);
+        if (isMutation && !hasValidPreviewMutationToken(req.headers, previewToken)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Invalid or missing preview mutation token' }));
+            return;
+        }
+
         // LMS routes (state sync + testing API)
         if (handleLmsRoutes(ctx, req, res, url)) return;
 
@@ -393,7 +416,14 @@ export async function previewServer(options = {}) {
         // Serve files from dist/ for /course/* requests
         if (url.startsWith('/course/')) {
             const relativePath = url.slice('/course/'.length) || 'index.html';
-            const filePath = path.join(distDir, relativePath);
+            let filePath;
+            try {
+                filePath = resolveWithinRoot(distDir, relativePath);
+            } catch {
+                res.writeHead(403);
+                res.end('Forbidden');
+                return;
+            }
             serveFile(filePath, res);
             return;
         }
@@ -490,12 +520,24 @@ export async function previewServer(options = {}) {
 
     const contentNote = options.content !== false ? '   • Content viewer (📄 button in toolbar)\n' : '';
 
-    const startListening = (retried = false) => {
-        server.listen(previewPort, () => {
+    server.on('error', (err) => {
+        if (err.code === 'EADDRINUSE') {
+            console.error(`\n❌ Port ${previewPort} is already in use. Stop that process or choose another port with --port.`);
+            viteProcess.kill();
+            process.exitCode = 1;
+            return;
+        }
+        throw err;
+    });
+
+    const startListening = () => {
+        server.listen(previewPort, previewHost, () => {
+            const displayHost = previewHost === '127.0.0.1' ? 'localhost' : previewHost;
             console.log(`
 ✅ Preview server running!
 
-   🎯 Open: http://localhost:${previewPort}
+   🎯 Open: http://${displayHost}:${previewPort}
+   🔒 Bound to: ${previewHost}
    
    Features:
    • Live reload - browser updates automatically on rebuild
@@ -511,28 +553,6 @@ ${contentNote}
    Press Ctrl+C to stop
 `);
         });
-
-        server.on('error', (err) => {
-            if (err.code === 'EADDRINUSE' && !retried) {
-                console.warn(`\n⚠️  STALE PROCESS DETECTED — port ${previewPort} is already in use.`);
-                console.warn('   Killing stale process and retrying...');
-                exec(`lsof -ti :${previewPort}`, (_, stdout) => {
-                    const pids = (stdout || '').trim();
-                    if (pids) console.warn(`   Killed PID(s): ${pids.split('\n').join(', ')}`);
-                    exec(`lsof -ti :${previewPort} | xargs kill -9 2>/dev/null`, () => {
-                        setTimeout(() => {
-                            server.close();
-                            startListening(true);
-                        }, 500);
-                    });
-                });
-            } else if (err.code === 'EADDRINUSE') {
-                console.error(`\n❌ Port ${previewPort} is still in use after retry. Kill it manually:\n   lsof -ti :${previewPort} | xargs kill -9`);
-                process.exit(1);
-            } else {
-                throw err;
-            }
-        });
     };
 
     startListening();
@@ -563,6 +583,7 @@ if (process.argv[1] && process.argv[1].endsWith('preview-server.js')) {
     const options = {
         frameworkDev: args.includes('--framework-dev'),
         port: args.find(a => a.startsWith('--port='))?.split('=')[1] || '4173',
+        host: args.find(a => a.startsWith('--host='))?.split('=')[1] || '127.0.0.1',
         format: process.env.LMS_FORMAT || null
     };
     previewServer(options);

package/lib/project-utils.js

@@ -178,6 +178,40 @@ export function getMimeType(filePath) {
     return mimeTypes[path.extname(filePath).toLowerCase()] || 'application/octet-stream';
 }
 
+/**
+ * Resolve a user-controlled relative path while guaranteeing that the result
+ * remains inside the supplied root directory.
+ *
+ * @param {string} rootDir - Absolute directory that contains all allowed files
+ * @param {string} relativePath - URL/path fragment supplied by a caller
+ * @returns {string} Safe absolute path
+ * @throws {Error} If the path is malformed or escapes rootDir
+ */
+export function resolveWithinRoot(rootDir, relativePath) {
+    if (typeof rootDir !== 'string' || typeof relativePath !== 'string') {
+        throw new Error('Root directory and relative path must be strings');
+    }
+
+    let decodedPath;
+    try {
+        decodedPath = decodeURIComponent(relativePath);
+    } catch {
+        throw new Error('Invalid URL encoding in path');
+    }
+
+    if (decodedPath.includes('\0')) {
+        throw new Error('Path contains a null byte');
+    }
+
+    const root = path.resolve(rootDir);
+    const resolved = path.resolve(root, decodedPath.replace(/^[/\\]+/, ''));
+    if (resolved !== root && !resolved.startsWith(root + path.sep)) {
+        throw new Error('Path escapes the allowed root directory');
+    }
+
+    return resolved;
+}
+
 // =============================================================================
 // FILE SERVING
 // =============================================================================