linting-improvement

Author: svincent240

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);

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}`;

lib/narration-parser.js framework/scripts/narration-parser.jslib/narration-parser.js renamed to framework/scripts/narration-parser.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, {

lib/authoring-api.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,

lib/build-linter.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: []

lib/mcp-prompts.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;
 

lib/mcp-server.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, {

lib/narration.js

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

package.json

@@ -27,9 +27,6 @@ Thumbs.db
 *.swp
 *.swo
 
-# Narration cache
-.narration-cache.json
-
 # CourseCode Cloud (project binding)
 .coursecode/