coursecode 0.1.38 → 0.1.40

package/bin/cli.js

@@ -141,6 +141,7 @@ program
   .option('-f, --force', 'Regenerate all narration (ignore cache)')
   .option('-s, --slide <id>', 'Generate narration for a specific slide only')
   .option('--dry-run', 'Preview what would be generated')
+  .option('--rebuild-cache', 'Rebuild .narration-cache.json from existing audio (no TTS calls)')
   .action(async (options) => {
     const { narration } = await import('../lib/narration.js');
     await narration(options);

package/framework/js/dev/runtime-linter.js

@@ -205,6 +205,23 @@ export async function lintCourse(courseConfig) {
     // Cleanup offscreen container
     cleanupOffscreenContainer();
 
+    // --- 4. Filesystem-backed checks via preview server ---
+    // The browser can't read .narration-cache.json or hash slide source files,
+    // so the preview server exposes /__lint/narration to do that work and
+    // return any stale-narration warnings. Silently ignored if the endpoint
+    // is unavailable (e.g. running outside the preview server).
+    try {
+        const resp = await fetch('/__lint/narration', { cache: 'no-store' });
+        if (resp.ok) {
+            const data = await resp.json();
+            if (Array.isArray(data.warnings)) {
+                warnings.push(...data.warnings);
+            }
+        }
+    } catch {
+        // Endpoint absent (e.g. SCORM package preview) — skip silently.
+    }
+
     // Display warnings individually so each appears as a separate entry in the debug panel
     if (warnings.length > 0) {
         for (const w of warnings) {

package/framework/scripts/generate-narration.js

@@ -40,7 +40,7 @@ import {
     loadNarrationCache,
     narrationCacheKey,
     VOICE_SETTING_KEYS as _SHARED_VOICE_KEYS
-} from '../../lib/narration-parser.js';
+} from './narration-parser.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -65,6 +65,10 @@ const VERBOSE = args.includes('--verbose') || args.includes('-v');
 const SLIDE_FILTER = args.includes('--slide') ? args[args.indexOf('--slide') + 1] : null;
 const SHOW_PROVIDERS = args.includes('--providers') || args.includes('--provider');
 const SHOW_HELP = args.includes('--help') || args.includes('-h');
+// Rebuild .narration-cache.json from current slide text without calling any
+// TTS provider. Useful when audio is committed but the cache is missing
+// (e.g. after a fresh clone or migrating a project).
+const REBUILD_CACHE = args.includes('--rebuild-cache');
 
 /**
  * Load environment variables from .env file
@@ -224,7 +228,7 @@ function parseSlideNarration(filePath, baseName) {
 }
 
 // Removed: original inline parseSlideNarration / parseNarrationObject implementations
-// now live in lib/narration-parser.js so the build linter can reuse them.
+// now live in framework/scripts/narration-parser.js so the build linter can reuse them.
 
 /**
  * Main execution
@@ -244,11 +248,12 @@ async function main() {
 
 Usage:
    npm run narration                  Generate all changed narration
-   npm run narration -- --force       Regenerate all (ignore cache)
-   npm run narration -- --dry-run     Preview without generating
-   npm run narration -- --slide <id>  Generate specific slide only
-   npm run narration -- --providers   List available TTS providers
-   npm run narration -- --verbose     Show detailed output
+   npm run narration -- --force          Regenerate all (ignore cache)
+   npm run narration -- --dry-run        Preview without generating
+   npm run narration -- --slide <id>     Generate specific slide only
+   npm run narration -- --rebuild-cache  Rebuild cache from existing audio (no TTS calls)
+   npm run narration -- --providers      List available TTS providers
+   npm run narration -- --verbose        Show detailed output
 
 Provider Selection:
    Set TTS_PROVIDER env var to: elevenlabs, openai, or azure
@@ -266,17 +271,22 @@ Examples:
     // Load environment variables
     loadEnv();
     
-    // Initialize TTS provider
+    // Initialize TTS provider — skipped in --rebuild-cache mode since we
+    // never call the provider when only refreshing the cache file.
     let provider;
-    try {
-        provider = getActiveProvider();
-        provider.validateConfig();
-        const defaultVoice = provider.getDefaultVoiceId();
-        console.log(`🔊 Using TTS provider: ${provider.getName()} (voice: ${defaultVoice})\n`);
-    } catch (error) {
-        console.error(`❌ Provider error: ${error.message}\n`);
-        printProviderHelp();
-        process.exit(1);
+    if (REBUILD_CACHE) {
+        console.log('🔁 Rebuild-cache mode: hashing existing audio, no TTS calls.\n');
+    } else {
+        try {
+            provider = getActiveProvider();
+            provider.validateConfig();
+            const defaultVoice = provider.getDefaultVoiceId();
+            console.log(`🔊 Using TTS provider: ${provider.getName()} (voice: ${defaultVoice})\n`);
+        } catch (error) {
+            console.error(`❌ Provider error: ${error.message}\n`);
+            printProviderHelp();
+            process.exit(1);
+        }
     }
     
     // Load course config
@@ -375,7 +385,24 @@ Examples:
             const cacheKey = key === 'slide' ? source.src : `${source.src}#${key}`;
             const cachedHash = cache[cacheKey];
             const outputExists = fs.existsSync(outputPath);
-            
+
+            // --rebuild-cache: hash text+settings for existing audio and move on.
+            // Never call TTS, never write or delete audio files.
+            if (REBUILD_CACHE) {
+                if (outputExists) {
+                    newCache[cacheKey] = contentHash;
+                    skipped++;
+                    if (VERBOSE) {
+                        const label = key === 'slide' ? source.slideId : `${source.slideId}#${key}`;
+                        console.log(`   ✅ ${label}: cached (${path.relative(ROOT_DIR, outputPath)})`);
+                    }
+                } else if (VERBOSE) {
+                    const label = key === 'slide' ? source.slideId : `${source.slideId}#${key}`;
+                    console.log(`   ⏭️  ${label}: no audio yet, skipping`);
+                }
+                continue;
+            }
+
             if (cachedHash === contentHash && outputExists && !FORCE_REGENERATE) {
                 if (VERBOSE) {
                     const label = key === 'slide' ? source.slideId : `${source.slideId}#${key}`;

package/lib/authoring-api.js

@@ -1117,13 +1117,14 @@ export async function buildCourse(options = {}) {
  * picks up the same .env, course-config, and slide files a manual run would.
  *
  * @param {object} options
- * @param {boolean} [options.dryRun=false] - Show what would be generated without calling TTS
- * @param {boolean} [options.force=false]  - Regenerate everything, ignoring the cache
- * @param {string}  [options.slide]        - Limit to a single slide ID
+ * @param {boolean} [options.dryRun=false]      - Show what would be generated without calling TTS
+ * @param {boolean} [options.force=false]       - Regenerate everything, ignoring the cache
+ * @param {string}  [options.slide]             - Limit to a single slide ID
+ * @param {boolean} [options.rebuildCache=false] - Rebuild .narration-cache.json from existing audio without calling TTS
  * @returns {Promise<{success, dryRun, summary, generated, skipped, errors, warnings, output, duration}>}
  */
 export async function generateNarration(options = {}) {
-    const { dryRun = false, force = false, slide } = options;
+    const { dryRun = false, force = false, slide, rebuildCache = false } = options;
     const startTime = Date.now();
 
     let courseRoot;
@@ -1157,6 +1158,7 @@ export async function generateNarration(options = {}) {
     if (force) args.push('--force');
     if (dryRun) args.push('--dry-run');
     if (slide) args.push('--slide', slide);
+    if (rebuildCache) args.push('--rebuild-cache');
 
     return new Promise((resolve) => {
         const child = spawn('node', args, {

package/lib/build-linter.js

@@ -19,7 +19,7 @@ import {
   loadNarrationCache,
   narrationCacheKey,
   classifyNarrationFreshness
-} from './narration-parser.js';
+} from '../framework/scripts/narration-parser.js';
 import { fileURLToPath, pathToFileURL } from 'url';
 import {
   flattenStructure,

package/lib/mcp-prompts.js

@@ -448,6 +448,10 @@ NOT idempotent: real runs call paid TTS APIs and write files. Prefer dryRun firs
                 slide: {
                     type: 'string',
                     description: 'Optional slide ID filter (e.g. "intro"). Only narration for this slide is processed.'
+                },
+                rebuildCache: {
+                    type: 'boolean',
+                    description: 'Rebuild .narration-cache.json from existing audio files without calling TTS (default: false). Use after a fresh clone or when the cache is missing but audio is committed. Free; no API calls.'
                 }
             },
             required: []

package/lib/mcp-server.js

@@ -287,7 +287,8 @@ export async function startMcpServer(options = {}) {
                     result = await generateNarration({
                         dryRun: args?.dryRun === true,
                         force: args?.force === true,
-                        slide: args?.slide
+                        slide: args?.slide,
+                        rebuildCache: args?.rebuildCache === true
                     });
                     break;
 

package/lib/narration.js

@@ -32,6 +32,7 @@ export async function narration(options = {}) {
   if (options.force) args.push('--force');
   if (options.slide) args.push('--slide', options.slide);
   if (options.dryRun) args.push('--dry-run');
+  if (options.rebuildCache) args.push('--rebuild-cache');
   
   return new Promise((resolve, reject) => {
     const child = spawn('node', args, {

package/lib/preview-routes-api.js

@@ -67,6 +67,47 @@ export async function handleApiRoutes(ctx, req, res, url) {
         return true;
     }
 
+    // Narration freshness check — runtime linter fetches this since it can't
+    // read the filesystem directly. Returns warnings for stale .mp3 files
+    // (audio exists but cached hash differs from current text+settings).
+    // Silent when audio is absent or .narration-cache.json is missing.
+    if (url === '/__lint/narration') {
+        try {
+            const { checkNarrationFreshness } = await import('./build-linter.js');
+            const { flattenStructure } = await import('./validation-rules.js');
+            const configPath = path.join(paths.coursePath, 'course-config.js');
+            if (!fs.existsSync(configPath)) {
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ warnings: [] }));
+                return true;
+            }
+            // Cache-bust import so edits to course-config.js are picked up
+            const configUrl = `${pathToFileURL(configPath).href}?t=${Date.now()}`;
+            const configModule = await import(configUrl);
+            const courseConfig = configModule.courseConfig || configModule.default;
+            if (!courseConfig?.structure) {
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ warnings: [] }));
+                return true;
+            }
+            // Respect the same opt-out as the build linter
+            if (courseConfig.lint?.narrationFreshness === false) {
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ warnings: [], disabled: true }));
+                return true;
+            }
+            const slides = flattenStructure(courseConfig.structure);
+            const warnings = [];
+            checkNarrationFreshness(slides, paths.coursePath, warnings);
+            res.writeHead(200, { 'Content-Type': 'application/json', 'Cache-Control': 'no-cache' });
+            res.end(JSON.stringify({ warnings }));
+        } catch (err) {
+            res.writeHead(500, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ warnings: [], error: err.message }));
+        }
+        return true;
+    }
+
     // Refresh course content HTML
     if (url === '/__content') {
         generateContentHtml({ coursePath: paths.coursePath, includeNarration: true })

package/package.json

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