coursecode 0.1.53 → 0.1.54

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
 // =============================================================================

package/lib/proxy-templates/proxy.html

@@ -44,11 +44,15 @@
     </div>
     
     <iframe id="course" style="display:none"></iframe>
-    
+
+    <script src="pipwerks.js"></script>
+    <script>
+        // Injected as a JSON string by the build system before the bridge loads.
+        window.COURSECODE_PROXY_CONFIG = { courseUrl: {{EXTERNAL_URL_JSON}} };
+    </script>
     <script src="scorm-bridge.js"></script>
     <script>
-        // Course URL is injected at build time
-        const COURSE_URL = '{{EXTERNAL_URL}}';
+        const COURSE_URL = window.COURSECODE_PROXY_CONFIG.courseUrl;
         
         const iframe = document.getElementById('course');
         const loading = document.getElementById('loading');

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

@@ -22,16 +22,17 @@
     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
+    // Derive the exact expected course origin from build-time configuration.
+    // Fail closed: wildcard origins would allow unrelated frames to operate the LMS API.
+    let courseOrigin;
     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);
-        }
+        const courseUrl = window.COURSECODE_PROXY_CONFIG?.courseUrl;
+        if (!courseUrl) throw new Error('Missing proxy course URL');
+        courseOrigin = new URL(courseUrl).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);
+        console.error('SCORM Bridge: Invalid course URL; bridge disabled:', e.message);
+        return;
     }
 
     // Disable pipwerks auto-handling - we manage status ourselves
@@ -49,8 +50,13 @@
             return;
         }
 
+        if (!iframe || event.source !== iframe.contentWindow) {
+            console.warn('SCORM Bridge: Rejected message not sent by the course iframe');
+            return;
+        }
+
         // Validate origin when we have a known course origin
-        if (courseOrigin !== '*' && event.origin !== courseOrigin) {
+        if (event.origin !== courseOrigin) {
             console.warn('SCORM Bridge: Rejected message from unexpected origin:', event.origin);
             return;
         }

package/lib/stub-player.js

@@ -58,7 +58,7 @@ export { escapeHtml };
  * @returns {string} - Complete HTML for the player page
  */
 export function generateStubPlayer(config) {
-    const { title, launchUrl, storageKey, passwordHash, isLive, liveReload, courseContent, startSlide, isDesktop, showHeader = true, skipGating = null, moduleBasePath = '/__stub-player' } = config;
+    const { title, launchUrl, storageKey, passwordHash, isLive, liveReload, courseContent, startSlide, isDesktop, showHeader = true, skipGating = null, moduleBasePath = '/__stub-player', previewToken = null } = config;
     const hasPassword = !!passwordHash;
     const hasContent = !!courseContent;
     const headerVisible = showHeader !== false;
@@ -115,8 +115,25 @@ ${stubPlayerStyles}
         showHeader: ${headerVisible},
         skipGating: ${typeof skipGating === 'boolean' ? skipGating : 'null'},
         isDesktop: ${isDesktop || false},
-        isCI: ${!!process.env.CI}
+        isCI: ${!!process.env.CI},
+        previewToken: ${previewToken ? JSON.stringify(previewToken) : 'null'}
     };
+
+    // Protect source-mutating preview endpoints from cross-site requests. The
+    // token is random for each preview process and is never used by exports.
+    if (window.STUB_CONFIG.previewToken) {
+        const nativeFetch = window.fetch.bind(window);
+        window.fetch = function(input, init = {}) {
+            const requestUrl = typeof input === 'string' ? input : input?.url;
+            const requestMethod = String(init.method || input?.method || 'GET').toUpperCase();
+            if (requestUrl?.startsWith('/__') && !['GET', 'HEAD', 'OPTIONS'].includes(requestMethod)) {
+                const headers = new Headers(init.headers || input?.headers || {});
+                headers.set('X-CourseCode-Preview-Token', window.STUB_CONFIG.previewToken);
+                init = { ...init, headers };
+            }
+            return nativeFetch(input, init);
+        };
+    }
     </script>
     <script type="module" src="${moduleBasePath}/${isLive ? 'app' : 'app-viewer'}.js"></script>
     

package/lib/token.js

@@ -3,7 +3,7 @@
  * 
  * Usage:
  *   coursecode token                    # Generate random token
- *   coursecode token --add client-name  # Add client to course-config
+ *   coursecode token --add client-name  # Add client to gitignored access file
  */
 
 import crypto from 'crypto';
@@ -25,51 +25,48 @@ export function generateToken(length = 24) {
 export async function token(options = {}) {
     const newToken = generateToken();
 
-    // If --add specified, add to course-config
+    // If --add specified, add to the non-published access file. Credentials
+    // must never live in course-config.js because that module is bundled into
+    // learner-facing JavaScript.
     if (options.add) {
         const clientId = options.add;
-        const courseDir = path.join(process.cwd(), 'course');
-        const configPath = path.join(courseDir, 'course-config.js');
+        if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(clientId)) {
+            throw new Error('Client ID must use letters, numbers, dots, underscores, or hyphens');
+        }
+
+        const configPath = path.join(process.cwd(), 'course', 'course-config.js');
 
         if (!fs.existsSync(configPath)) {
             console.error('\n❌ No course-config.js found. Run from a CourseCode project directory.\n');
             process.exit(1);
         }
 
-        let content = fs.readFileSync(configPath, 'utf-8');
+        const accessDir = path.join(process.cwd(), '.coursecode');
+        const accessPath = path.join(accessDir, 'access-control.json');
+        fs.mkdirSync(accessDir, { recursive: true });
 
-        // Check if accessControl already exists
-        if (content.includes('accessControl:')) {
-            // Add to existing clients object
-            const clientsMatch = content.match(/accessControl:\s*\{[\s\S]*?clients:\s*\{/);
-            if (clientsMatch) {
-                const insertPos = clientsMatch.index + clientsMatch[0].length;
-                const newClient = `\n            '${clientId}': { token: '${newToken}' },`;
-                content = content.slice(0, insertPos) + newClient + content.slice(insertPos);
+        let accessConfig = { clients: {} };
+        if (fs.existsSync(accessPath)) {
+            try {
+                accessConfig = JSON.parse(fs.readFileSync(accessPath, 'utf-8'));
+            } catch (error) {
+                throw new Error(`Cannot parse ${accessPath}: ${error.message}`);
             }
-        } else {
-            // Add accessControl section before closing brace
-            const accessControlBlock = `
-    accessControl: {
-        enabled: true,
-        clients: {
-            '${clientId}': { token: '${newToken}' }
         }
-    },`;
-            // Find the last closing brace of courseConfig
-            const lastBrace = content.lastIndexOf('};');
-            if (lastBrace !== -1) {
-                content = content.slice(0, lastBrace) + accessControlBlock + '\n' + content.slice(lastBrace);
-            }
+        if (!accessConfig.clients || typeof accessConfig.clients !== 'object') {
+            accessConfig.clients = {};
         }
-
-        fs.writeFileSync(configPath, content, 'utf-8');
+        accessConfig.clients[clientId] = { token: newToken };
+        fs.writeFileSync(accessPath, JSON.stringify(accessConfig, null, 2) + '\n', { mode: 0o600 });
+        try { fs.chmodSync(accessPath, 0o600); } catch { /* Windows/filesystem may not support chmod */ }
 
         console.log(`
-✅ Added client '${clientId}' to accessControl
+✅ Added client '${clientId}' to .coursecode/access-control.json
 
    Token: ${newToken}
 
+   Keep accessControl.enforcement = 'server' in course-config.js.
+   Your CDN/backend must validate this token before serving course files.
    Build will generate: ${clientId}_proxy.zip
 `);
     } else {

package/lib/upgrade.js

@@ -113,6 +113,46 @@ export function addMissingRuntimeDependencies(projectPkg, templatePkg) {
   return added;
 }
 
+const OBSOLETE_MANAGED_DEV_DEPENDENCIES = ['@vitejs/plugin-legacy'];
+
+/**
+ * Synchronize the build tooling that accompanies a replaced template config.
+ * This only runs with `coursecode upgrade --configs`, keeping the default
+ * framework-only upgrade from changing a project's custom build stack.
+ */
+export function syncManagedBuildTooling(projectPkg, templatePkg) {
+  const projectDevDeps = { ...(projectPkg.devDependencies || {}) };
+  const templateDevDeps = templatePkg.devDependencies || {};
+  const updated = [];
+  const removed = [];
+
+  for (const [name, version] of Object.entries(templateDevDeps)) {
+    if (projectDevDeps[name] !== version) {
+      projectDevDeps[name] = version;
+      updated.push(`${name}@${version}`);
+    }
+  }
+
+  for (const name of OBSOLETE_MANAGED_DEV_DEPENDENCIES) {
+    if (projectDevDeps[name]) {
+      delete projectDevDeps[name];
+      removed.push(name);
+    }
+  }
+
+  projectPkg.devDependencies = Object.fromEntries(
+    Object.entries(projectDevDeps).sort(([a], [b]) => a.localeCompare(b))
+  );
+
+  const nodeEngine = templatePkg.engines?.node;
+  const engineUpdated = Boolean(nodeEngine && projectPkg.engines?.node !== nodeEngine);
+  if (engineUpdated) {
+    projectPkg.engines = { ...(projectPkg.engines || {}), node: nodeEngine };
+  }
+
+  return { updated, removed, engineUpdated };
+}
+
 export async function upgrade(options = {}) {
   const cwd = process.cwd();
   const rcPath = path.join(cwd, '.coursecoderc.json');
@@ -175,7 +215,8 @@ export async function upgrade(options = {}) {
     if (options.configs) {
       dryRunMsg += `
    - vite.config.js (replace, backup original)
-   - eslint.config.js (replace, backup original)`;
+   - eslint.config.js (replace, backup original)
+   - package.json (sync managed Vite/ESLint tooling and remove plugin-legacy)`;
     }
 
     dryRunMsg += `
@@ -266,10 +307,18 @@ export async function upgrade(options = {}) {
   // the project's existing version ranges.
   const pkgPath = path.join(cwd, 'package.json');
   let addedRuntimeDeps = [];
+  let toolingChanges = null;
   if (fs.existsSync(pkgPath)) {
     const projectPkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
     addedRuntimeDeps = addMissingRuntimeDependencies(projectPkg, templatePkg);
-    if (addedRuntimeDeps.length > 0) {
+    if (options.configs) {
+      toolingChanges = syncManagedBuildTooling(projectPkg, templatePkg);
+    }
+    const packageChanged = addedRuntimeDeps.length > 0 ||
+      toolingChanges?.updated.length > 0 ||
+      toolingChanges?.removed.length > 0 ||
+      toolingChanges?.engineUpdated;
+    if (packageChanged) {
       fs.writeFileSync(pkgPath, JSON.stringify(projectPkg, null, 2) + '\n');
     }
   }
@@ -290,6 +339,31 @@ export async function upgrade(options = {}) {
    Run npm install to update node_modules and your lockfile.`;
   }
 
+  if (toolingChanges && (
+    toolingChanges.updated.length > 0 ||
+    toolingChanges.removed.length > 0 ||
+    toolingChanges.engineUpdated
+  )) {
+    successMsg += `
+
+   Managed build tooling synchronized for the new config:`;
+    if (toolingChanges.updated.length > 0) {
+      successMsg += `
+   - Updated: ${toolingChanges.updated.join(', ')}`;
+    }
+    if (toolingChanges.removed.length > 0) {
+      successMsg += `
+   - Removed: ${toolingChanges.removed.join(', ')}`;
+    }
+    if (toolingChanges.engineUpdated) {
+      successMsg += `
+   - Updated Node engine requirement to ${templatePkg.engines.node}`;
+    }
+    successMsg += `
+
+   Run npm install to update node_modules and your lockfile.`;
+  }
+
   if (configUpdates.length > 0) {
     successMsg += `