coursecode 0.1.33 → 0.1.36

package/bin/cli.js

@@ -38,12 +38,14 @@ if (!process.env.NODE_EXTRA_CA_CERTS) {
   const certPath = await injectSystemCerts();
   if (certPath) {
     // macOS/Linux: re-exec with NODE_EXTRA_CA_CERTS pointing to PEM file
-    const { execFileSync } = await import('child_process');
-    execFileSync(process.execPath, process.argv.slice(1), {
+    const { spawnSync } = await import('child_process');
+    const result = spawnSync(process.execPath, process.argv.slice(1), {
       env: { ...process.env, NODE_EXTRA_CA_CERTS: certPath },
       stdio: 'inherit',
     });
-    process.exit(0);
+    if (result.error) throw result.error;
+    if (result.signal) process.kill(process.pid, result.signal);
+    process.exit(result.status ?? 0);
   }
   // Windows: win-ca already injected certs in-process — continue normally
 }
@@ -425,4 +427,37 @@ program
     await deleteCourse({ force: options.force, json: options.json, repairBinding: options.repairBinding });
   });
 
-program.parse();
+// Centralized failure handler for async command actions. Friendly errors
+// (anything thrown with a non-Node-internal `.message`) are printed as-is;
+// raw Node/undici errors are reduced to their message + code so users never
+// see deep internal stack frames.
+function reportFatal(err) {
+  if (!err) {
+    console.error('coursecode: command failed');
+    process.exit(1);
+  }
+  if (err.isUploadError) {
+    console.error('\n✗ ' + err.message + '\n');
+    process.exit(1);
+  }
+  const code = (err.cause && err.cause.code) || err.code;
+  const msg = err.message || String(err);
+  console.error('\n✗ ' + msg + (code ? `  (${code})` : ''));
+  if (process.env.COURSECODE_DEBUG) {
+    console.error('\n' + (err.stack || ''));
+    if (err.cause) console.error('Caused by:', err.cause);
+  } else {
+    console.error('  Re-run with COURSECODE_DEBUG=1 for a full stack trace.');
+  }
+  console.error('');
+  process.exit(1);
+}
+
+process.on('unhandledRejection', reportFatal);
+process.on('uncaughtException', reportFatal);
+
+if (process.argv.length <= 2) {
+  program.help();
+}
+
+program.parseAsync().catch(reportFatal);

package/lib/cloud.js

@@ -22,14 +22,9 @@ const packageJson = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'packa
 // CONSTANTS
 // =============================================================================
 
-const DEFAULT_CLOUD_URL = 'https://coursecodecloud.com';
-// Fallback URL used automatically when the primary domain is blocked by a
-// corporate web filter (e.g. Zscaler URL categorization). *.vercel.app is
-// in a trusted platform category and is unlikely to be categorized as unknown.
-const FALLBACK_CLOUD_URL = 'https://coursecode-cloud-web.vercel.app';
+const DEFAULT_CLOUD_URL = 'https://www.coursecodecloud.com';
 const LOCAL_CLOUD_URL = 'http://localhost:3000';
 let useLocal = false;
-let activeCloudUrl = null;
 const CREDENTIALS_DIR = path.join(os.homedir(), '.coursecode');
 const CREDENTIALS_PATH = path.join(CREDENTIALS_DIR, 'credentials.json');
 const PROJECT_CONFIG_DIR = '.coursecode';
@@ -88,26 +83,18 @@ function readCredentials() {
   }
 }
 
-function writeCredentials(token, cloudUrl = DEFAULT_CLOUD_URL) {
+function writeCredentials(token) {
   fs.mkdirSync(CREDENTIALS_DIR, { recursive: true });
-  const data = JSON.stringify({ token, cloud_url: cloudUrl }, null, 2);
+  const data = JSON.stringify({ token }, null, 2);
   fs.writeFileSync(getCredentialsPath(), data, { mode: 0o600 });
 }
 
-function updateCredentialsCloudUrl(cloudUrl) {
-  const creds = readCredentials();
-  if (!creds?.token) return;
-  writeCredentials(creds.token, cloudUrl);
-}
-
 function deleteCredentials() {
   try { fs.unlinkSync(getCredentialsPath()); } catch { /* already gone */ }
 }
 
 function getCloudUrl() {
-  if (useLocal) return LOCAL_CLOUD_URL;
-  if (activeCloudUrl) return activeCloudUrl;
-  return readCredentials()?.cloud_url || DEFAULT_CLOUD_URL;
+  return useLocal ? LOCAL_CLOUD_URL : DEFAULT_CLOUD_URL;
 }
 
 /**
@@ -116,7 +103,6 @@ function getCloudUrl() {
  */
 export function setLocalMode() {
   useLocal = true;
-  activeCloudUrl = LOCAL_CLOUD_URL;
 }
 
 // =============================================================================
@@ -300,9 +286,6 @@ async function resolveStaleBinding({
  * Make an authenticated request to the Cloud API.
  * Handles User-Agent, Bearer token, and error formatting per §7.
  *
- * Automatically retries against FALLBACK_CLOUD_URL when the primary URL
- * returns an HTML block page (corporate web filter / Zscaler URL categorization).
- *
  * @param {string} urlPath - API path (e.g. '/api/cli/whoami')
  * @param {object} options - fetch options (method, body, headers, etc.)
  * @param {string} [token] - Override token (for unauthenticated requests)
@@ -316,68 +299,29 @@ async function cloudFetch(urlPath, options = {}, token = null) {
   };
   if (token) headers['Authorization'] = `Bearer ${token}`;
 
-  const attemptFetch = async (baseUrl) => {
-    const url = `${baseUrl}${urlPath}`;
-    try {
-      return await fetch(url, { ...options, headers });
-    } catch {
-      return null; // Connection failed
-    }
-  };
-
-  const primaryUrl = getCloudUrl();
-  const res = await attemptFetch(primaryUrl);
-
-  if (!res) {
-    // Primary unreachable — try fallback before giving up
-    if (!useLocal) {
-      const fallback = await attemptFetch(FALLBACK_CLOUD_URL);
-      if (fallback) {
-        activeCloudUrl = FALLBACK_CLOUD_URL;
-        return fallback;
-      }
-    }
-    console.error('\n❌ Could not connect to CourseCode Cloud. Check your internet connection.\n');
+  const baseUrl = getCloudUrl();
+  const url = `${baseUrl}${urlPath}`;
+  let res;
+  try {
+    res = await fetch(url, { ...options, headers });
+  } catch (err) {
+    const host = new URL(baseUrl).host;
+    const code = (err && err.cause && err.cause.code) || err?.code;
+    console.error(`\n❌ Could not connect to ${host}${code ? ` (${code})` : ''}.`);
+    console.error('   Check your internet connection. If on a corporate or school network,');
+    console.error(`   ask IT to whitelist ${host}.\n`);
     process.exit(1);
   }
 
-  // Peek at the body: if it's an HTML block page, silently retry on the fallback.
-  // We must buffer the text here since Response bodies can only be read once.
+  // Buffer the body once so handleResponse can re-read it, and so we can
+  // detect HTML block pages from corporate web filters (Zscaler, etc.).
   const text = await res.text();
 
-  // Token may be valid on the alternate cloud origin. Before triggering re-auth,
-  // retry authenticated 401s once on the other known origin.
-  if (res.status === 401 && token && !useLocal) {
-    const alternateUrl = primaryUrl === FALLBACK_CLOUD_URL ? DEFAULT_CLOUD_URL : FALLBACK_CLOUD_URL;
-    const alternateRes = await attemptFetch(alternateUrl);
-    if (alternateRes) {
-      const alternateText = await alternateRes.text();
-      if (!isBlockPage(alternateText) && alternateRes.status !== 401) {
-        activeCloudUrl = alternateUrl;
-        updateCredentialsCloudUrl(alternateUrl);
-        return syntheticResponse(alternateText, alternateRes.status);
-      }
-    }
-  }
-
-  if (isBlockPage(text) && !useLocal) {
-    const fallbackRes = await attemptFetch(FALLBACK_CLOUD_URL);
-    if (fallbackRes) {
-      const fallbackText = await fallbackRes.text();
-      if (!isBlockPage(fallbackText)) {
-        activeCloudUrl = FALLBACK_CLOUD_URL;
-        updateCredentialsCloudUrl(FALLBACK_CLOUD_URL);
-        // Fallback succeeded — return a synthetic Response with the buffered text
-        return syntheticResponse(fallbackText, fallbackRes.status);
-      }
-    }
-    // Both primary and fallback are blocked — surface the error
+  if (isBlockPage(text)) {
     reportBlockPage(text, res);
     process.exit(1);
   }
 
-  // Primary response is fine — return a synthetic Response with the buffered text
-  activeCloudUrl = primaryUrl;
   return syntheticResponse(text, res.status);
 }
 
@@ -406,17 +350,18 @@ function syntheticResponse(text, status) {
  * @param {Response} res - The fetch Response object
  */
 function reportBlockPage(body, res) {
+  const host = new URL(getCloudUrl()).host;
   const lower = body.toLowerCase();
   if (lower.includes('zscaler')) {
-    console.error('\n❌ coursecodecloud.com is blocked by Zscaler on your network.');
+    console.error(`\n❌ ${host} is blocked by Zscaler on your network.`);
   } else if (lower.includes('forcepoint') || lower.includes('websense')) {
-    console.error('\n❌ coursecodecloud.com is blocked by Forcepoint on your network.');
+    console.error(`\n❌ ${host} is blocked by Forcepoint on your network.`);
   } else if (lower.includes('barracuda')) {
-    console.error('\n❌ coursecodecloud.com is blocked by Barracuda on your network.');
+    console.error(`\n❌ ${host} is blocked by Barracuda on your network.`);
   } else {
-    console.error(`\n❌ Your network blocked coursecodecloud.com (HTTP ${res.status}).`);
+    console.error(`\n❌ Your network blocked ${host} (HTTP ${res.status}).`);
   }
-  console.error('   Ask your IT team to whitelist: coursecodecloud.com\n');
+  console.error(`   Ask your IT team to whitelist: ${host}\n`);
 }
 
 /**
@@ -613,7 +558,7 @@ async function runLoginFlow({ jsonMode = false } = {}) {
     if (data.pending) continue;
 
     if (data.token) {
-      writeCredentials(data.token, activeCloudUrl || getCloudUrl());
+      writeCredentials(data.token);
       log('  ✓ Logged in successfully\n');
       return data.token;
     }
@@ -647,8 +592,7 @@ async function runLegacyLoginFlow() {
     process.exit(1);
   }
 
-  const effectiveCloudUrl = activeCloudUrl || initialCloudUrl;
-  const loginUrl = `${effectiveCloudUrl}/auth/connect?session=${nonce}`;
+  const loginUrl = `${initialCloudUrl}/auth/connect?session=${nonce}`;
   console.log('  → Opening browser for authentication...');
   openBrowser(loginUrl);
 
@@ -669,7 +613,7 @@ async function runLegacyLoginFlow() {
     if (data.pending) continue;
 
     if (data.token) {
-      writeCredentials(data.token, activeCloudUrl || initialCloudUrl);
+      writeCredentials(data.token);
       console.log('  ✓ Logged in successfully');
       return data.token;
     }
@@ -941,7 +885,61 @@ export async function listCourses(options = {}) {
 }
 
 /**
- * coursecode deploy — build, zip, resolve org, upload
+ * Translate low-level fetch/undici errors from R2 PUTs into a friendly,
+ * actionable CLI error. Identifies the failing file and host, and attaches
+ * a hint when the cause is a known network condition (connect timeout, DNS,
+ * reset, TLS). The original error is preserved on `.cause`.
+ */
+function wrapUploadError(err, item) {
+  let host = '';
+  try { host = new URL(item.uploadUrl).host; } catch {}
+  const cause = err && err.cause;
+  const code = (cause && cause.code) || err.code || err.name;
+
+  let summary = `Failed to upload ${item.filePath}`;
+  let hint = '';
+
+  switch (code) {
+    case 'UND_ERR_CONNECT_TIMEOUT':
+    case 'ETIMEDOUT':
+    case 'TimeoutError':
+      summary += ` — could not reach ${host} (connect timeout)`;
+      hint = [
+        'This is a network problem between your machine and Cloudflare R2, not the Cloud service.',
+        'Try:',
+        '  • If on VPN or a corporate/school network, disconnect or whitelist *.r2.cloudflarestorage.com',
+        '  • Re-run with IPv4 first:  NODE_OPTIONS=--dns-result-order=ipv4first coursecode deploy',
+        '  • Test connectivity:       curl -v https://' + host + '/',
+      ].join('\n  ');
+      break;
+    case 'ENOTFOUND':
+    case 'EAI_AGAIN':
+      summary += ` — DNS lookup failed for ${host}`;
+      hint = 'Check your internet connection and DNS settings (e.g. switch to 1.1.1.1 or 8.8.8.8).';
+      break;
+    case 'ECONNRESET':
+    case 'UND_ERR_SOCKET':
+      summary += ` — connection to ${host} was reset mid-transfer`;
+      hint = 'Likely a flaky network or proxy interfering with the upload. Re-run the deploy.';
+      break;
+    case 'CERT_HAS_EXPIRED':
+    case 'UNABLE_TO_VERIFY_LEAF_SIGNATURE':
+    case 'SELF_SIGNED_CERT_IN_CHAIN':
+      summary += ` — TLS handshake with ${host} failed (${code})`;
+      hint = 'A SSL-inspecting proxy (e.g. Zscaler) is intercepting the connection. Trust the corporate root CA or whitelist *.r2.cloudflarestorage.com.';
+      break;
+    default:
+      summary += ` — ${err.message || code || 'unknown error'}`;
+  }
+
+  const wrapped = new Error(hint ? `${summary}\n  ${hint}` : summary);
+  wrapped.cause = err;
+  wrapped.isUploadError = true;
+  return wrapped;
+}
+
+/**
+ * coursecode deploy — build, read files, batch presign + upload + finalize
  */
 export async function deploy(options = {}) {
   const { validateProject } = await import('./project-utils.js');
@@ -951,6 +949,9 @@ export async function deploy(options = {}) {
   const slug = resolveSlug();
   const log = (...args) => { if (!options.json) console.log(...args); };
   const logErr = (...args) => { if (!options.json) console.error(...args); };
+  const emitProgress = (stage, uploaded, total) => {
+    if (options.json) process.stdout.write(JSON.stringify({ type: 'progress', stage, uploaded, total }) + '\n');
+  };
 
   // Preflight a cached binding so deleted cloud courses can be repaired
   // before we spend time building and uploading.
@@ -1034,11 +1035,10 @@ export async function deploy(options = {}) {
   // Determine promote_mode and preview_force
   const promoteMode = options.promote ? 'promote' : options.stage ? 'stage' : 'auto';
   const previewForce = !!options.preview;
-  // --preview alone = preview_only deploy (production pointer untouched, preview always moved)
-  // --preview + --promote/--stage = full production deploy + always move preview pointer
   const previewOnly = previewForce && promoteMode === 'auto';
 
   log('\n📦 Building...\n');
+  emitProgress('building');
 
   // Step 1: Build
   const { build } = await import('./build.js');
@@ -1052,15 +1052,45 @@ export async function deploy(options = {}) {
     process.exit(1);
   }
 
-  // Step 3: Resolve org
-  const { orgId, courseId, orgName } = await resolveOrgAndCourse(slug, readCredentials()?.token);
+  // Step 3: Resolve org + ensure course exists
+  const { orgId, courseId: existingCourseId, orgName } = await resolveOrgAndCourse(slug, readCredentials()?.token);
   const displayOrg = orgName ? ` to ${orgName}` : '';
 
-  // Step 4: Zip dist/ contents
-  const zipPath = path.join(os.tmpdir(), `coursecode-deploy-${Date.now()}.zip`);
-  await zipDirectory(distPath, zipPath);
+  // Ensure course exists on Cloud (resolve or create)
+  const ensureRes = await cloudFetch(
+    `/api/cli/courses/${encodeURIComponent(slug)}/ensure`,
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ orgId }),
+    },
+    readCredentials()?.token
+  );
+  const ensureData = await handleResponse(ensureRes);
+  const courseId = ensureData.courseId || existingCourseId;
+
+  // Server-side safety net: reject non-preview deploys for GitHub-linked courses
+  if (ensureData.githubRepo && !previewOnly) {
+    logErr('\n❌ This course deploys to production via GitHub, not CLI.');
+    logErr(`   Repo: ${ensureData.githubRepo}`);
+    logErr('   Push to your repo to trigger a production deploy.');
+    logErr('   Use --preview to deploy a preview build via CLI.\n');
+    if (options.json) {
+      process.stdout.write(JSON.stringify({
+        success: false,
+        error: 'Production deploy blocked — course is GitHub-linked',
+        errorCode: 'github_source_blocked',
+        githubRepo: ensureData.githubRepo,
+        hint: 'Use --preview for preview deploys, or push to GitHub for production.',
+      }) + '\n');
+    }
+    process.exit(1);
+  }
+
+  // Step 4: Read dist/ files
+  const distFiles = collectDistFiles(distPath);
+  const totalSize = distFiles.reduce((sum, f) => sum + f.size, 0);
 
-  // Step 5: Upload
   let modeLabel;
   if (previewOnly) {
     modeLabel = 'preview only';
@@ -1075,58 +1105,144 @@ export async function deploy(options = {}) {
   } else {
     modeLabel = 'production';
   }
-  log(`\nDeploying ${slug}${displayOrg} [${modeLabel}]...\n`);
+  log(`\nDeploying ${slug}${displayOrg} [${modeLabel}] — ${distFiles.length} files, ${formatBytes(totalSize)}\n`);
 
-  const formData = new FormData();
-  const zipBuffer = fs.readFileSync(zipPath);
-  formData.append('file', new Blob([zipBuffer], { type: 'application/zip' }), 'deploy.zip');
-  formData.append('orgId', orgId);
-  formData.append('promote_mode', promoteMode);
-  formData.append('preview_force', String(previewForce));
+  // Step 5: Batch presign
+  const presignRes = await cloudFetch(
+    `/api/courses/${courseId}/upload/presign/batch`,
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        files: distFiles.map(f => ({ path: f.relativePath, contentType: guessContentTypeLocal(f.relativePath) })),
+        totalSize,
+      }),
+    },
+    readCredentials()?.token
+  );
+  const presignData = await handleResponse(presignRes);
 
-  if (options.message) {
-    formData.append('message', options.message);
-  }
+  // Step 6: Upload files to R2 via presigned URLs
+  emitProgress('uploading', 0, distFiles.length);
+  log('  Uploading files...');
+
+  const CONCURRENCY = 8;
+  const MAX_RETRIES = 3;
+  let uploaded = 0;
 
-  if (options.preview && options.password) {
-    const pw = await prompt('  Preview password: ');
-    formData.append('password', pw);
+  const uploadQueue = presignData.uploads.map((u, i) => ({
+    uploadUrl: u.uploadUrl,
+    filePath: path.join(distPath, distFiles[i].relativePath),
+    contentType: guessContentTypeLocal(distFiles[i].relativePath),
+  }));
+
+  // Concurrent upload with retry
+  const chunks = [];
+  for (let i = 0; i < uploadQueue.length; i += CONCURRENCY) {
+    chunks.push(uploadQueue.slice(i, i + CONCURRENCY));
+  }
+
+  for (const chunk of chunks) {
+    await Promise.all(chunk.map(async (item) => {
+      const fileData = fs.readFileSync(item.filePath);
+      let lastErr = null;
+      for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+        try {
+          // 60s per attempt covers slow links; default undici connect timeout
+          // is only 10s which can fail spuriously on flaky networks/VPNs.
+          const putRes = await fetch(item.uploadUrl, {
+            method: 'PUT',
+            headers: { 'Content-Type': item.contentType },
+            body: fileData,
+            signal: AbortSignal.timeout(60_000),
+          });
+          if (!putRes.ok) {
+            throw new Error(`R2 responded ${putRes.status} ${putRes.statusText}`);
+          }
+          lastErr = null;
+          break;
+        } catch (err) {
+          lastErr = err;
+          if (attempt === MAX_RETRIES - 1) break;
+          // Exponential backoff with jitter: ~1s, ~2s, ~4s.
+          const base = 1000 * Math.pow(2, attempt);
+          const jitter = Math.floor(Math.random() * 500);
+          await new Promise(r => setTimeout(r, base + jitter));
+        }
+      }
+      if (lastErr) {
+        throw wrapUploadError(lastErr, item);
+      }
+      uploaded++;
+      emitProgress('uploading', uploaded, distFiles.length);
+      if (!options.json && process.stdout.isTTY) {
+        process.stdout.write(`\r  Uploading ${uploaded}/${distFiles.length} files...`);
+      }
+    }));
   }
 
-  const queryString = previewOnly ? '?mode=preview' : '';
+  if (!options.json && process.stdout.isTTY) process.stdout.write('\n');
+  log(`  ✓ Uploaded ${uploaded} files`);
 
-  const makeRequest = async (_isRetry = false) => {
-    const token = readCredentials()?.token;
-    const res = await cloudFetch(
-      `/api/cli/courses/${encodeURIComponent(slug)}/deploy${queryString}`,
-      { method: 'POST', body: formData },
-      token
-    );
-    return handleResponse(res, { retryFn: makeRequest, _isRetry });
+  // Step 7: Finalize
+  emitProgress('finalizing');
+
+  const finalizeBody = {
+    versionTimestamp: presignData.versionTimestamp,
+    filename: slug,
+    fileCount: distFiles.length,
+    totalSize,
+    promoteMode,
+    previewForce,
+    previewOnly,
   };
+  if (options.message) finalizeBody.message = options.message;
 
-  const result = await makeRequest();
+  const finalizeRes = await cloudFetch(
+    `/api/courses/${courseId}/upload/finalize`,
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(finalizeBody),
+    },
+    readCredentials()?.token
+  );
+  const result = await handleResponse(finalizeRes);
 
-  // Step 6: Persist per-user binding and stamp cloud identity into .coursecoderc.json
-  const finalCourseId = result.courseId || courseId;
-  writeProjectConfig({ slug, orgId: result.orgId || orgId, courseId: finalCourseId });
+  // Step 8: Persist per-user binding
+  writeProjectConfig({ slug, orgId: ensureData.orgId || orgId, courseId });
   writeRcConfig({
-    cloudId: finalCourseId,
-    orgId: result.orgId || orgId,
+    cloudId: courseId,
+    orgId: ensureData.orgId || orgId,
   });
 
-  // Step 7: Display result
+  // Step 9: Display result
+  const appUrl = getCloudUrl();
+  const dashboardUrl = `${appUrl}/dashboard/courses/${courseId}`;
+
   if (options.json) {
-    process.stdout.write(JSON.stringify({ success: true, ...result }) + '\n');
-  } else if (result.mode === 'preview') {
-    // preview_only=true deployment (--preview alone)
-    console.log(`✓ Preview deployed (${result.fileCount} files)`);
-    console.log(`  Preview URL: ${result.url}`);
-    console.log(`  Dashboard:   ${result.dashboardUrl}`);
+    process.stdout.write(JSON.stringify({
+      type: 'result',
+      success: true,
+      courseId,
+      slug,
+      mode: previewOnly ? 'preview' : 'production',
+      fileCount: distFiles.length,
+      size: totalSize,
+      deploymentId: result.deploymentId,
+      promoted: result.promoted,
+      previewPromoted: result.previewPromoted,
+      previewUrl: result.previewUrl,
+      dashboardUrl,
+    }) + '\n');
+  } else if (previewOnly) {
+    console.log(`✓ Preview deployed (${distFiles.length} files)`);
+    if (result.previewUrl) console.log(`  Preview URL: ${result.previewUrl}`);
+    console.log(`  Dashboard:   ${dashboardUrl}`);
   } else {
     const prodTag = result.promoted ? 'live' : 'staged';
     const previewTag = result.previewPromoted ? ' + preview' : '';
-    console.log(`✓ Deployed (${result.fileCount} files) — ${prodTag}${previewTag}`);
+    console.log(`✓ Deployed (${distFiles.length} files) — ${prodTag}${previewTag}`);
     if (!result.promoted) {
       console.log('  Production pointer not updated. Promote from Deploy History or run:');
       console.log('  coursecode promote --production');
@@ -1134,12 +1250,46 @@ export async function deploy(options = {}) {
     if (result.previewPromoted) {
       console.log('  Preview pointer updated.');
     }
-    console.log(`  Dashboard: ${result.dashboardUrl}`);
+    console.log(`  Dashboard: ${dashboardUrl}`);
   }
   console.log('');
+}
 
-  // Cleanup temp zip
-  try { fs.unlinkSync(zipPath); } catch { /* fine */ }
+/** Recursively collect all files in a directory with relative paths and sizes. */
+export function collectDistFiles(dirPath, basePath = '') {
+  const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const relativePath = basePath ? `${basePath}/${entry.name}` : entry.name;
+    const fullPath = path.join(dirPath, entry.name);
+    if (entry.name === '__MACOSX' || entry.name.startsWith('.')) continue;
+    if (entry.isDirectory()) {
+      files.push(...collectDistFiles(fullPath, relativePath));
+    } else {
+      files.push({
+        relativePath,
+        fullPath,
+        size: fs.statSync(fullPath).size,
+      });
+    }
+  }
+  return files;
+}
+
+/** Minimal content-type guesser for CLI uploads. */
+export function guessContentTypeLocal(filePath) {
+  const ext = filePath.split('.').pop()?.toLowerCase();
+  const types = {
+    html: 'text/html', htm: 'text/html', css: 'text/css',
+    js: 'application/javascript', mjs: 'application/javascript',
+    json: 'application/json', xml: 'application/xml',
+    svg: 'image/svg+xml', png: 'image/png', jpg: 'image/jpeg',
+    jpeg: 'image/jpeg', gif: 'image/gif', webp: 'image/webp',
+    mp4: 'video/mp4', webm: 'video/webm', mp3: 'audio/mpeg',
+    wav: 'audio/wav', woff: 'font/woff', woff2: 'font/woff2',
+    ttf: 'font/ttf', pdf: 'application/pdf', txt: 'text/plain',
+  };
+  return types[ext] || 'application/octet-stream';
 }
 
 /**
@@ -1645,23 +1795,3 @@ export async function deleteCourse(options = {}) {
   console.log('');
 }
 
-// =============================================================================
-// ZIP HELPER
-// =============================================================================
-
-/**
- * Zip a directory's contents using archiver (cross-platform, no native tools needed).
- */
-async function zipDirectory(sourceDir, outputPath) {
-  const archiver = (await import('archiver')).default;
-  return new Promise((resolve, reject) => {
-    const output = fs.createWriteStream(outputPath);
-    const archive = archiver('zip', { zlib: { level: 9 } });
-
-    output.on('close', () => resolve());
-    archive.on('error', reject);
-    archive.pipe(output);
-    archive.directory(sourceDir, false);
-    archive.finalize();
-  });
-}

package/lib/headless-browser.js

@@ -72,6 +72,8 @@ class HeadlessBrowser {
         this._stopped = false;
         this._consoleLogs = [];
         this._viewport = { width: 1280, height: 720 };
+        /** @type {Promise<void>|null} Tracks an in-flight reload so tool calls wait for it */
+        this._reloadPromise = null;
     }
 
     /**
@@ -136,6 +138,11 @@ class HeadlessBrowser {
      * @private
      */
     async _navigateToPreview() {
+        // Clear stale console errors from the previous page load.
+        // The page.goto() below will trigger teardown console noise from the
+        // dying page — we only want post-reload errors.
+        this._consoleLogs = [];
+
         const url = `http://localhost:${this.port}?headless`;
         await this.page.goto(url, { waitUntil: 'domcontentloaded', timeout: 3000 });
 
@@ -189,10 +196,16 @@ class HeadlessBrowser {
                     if (this._stopped) return;
                     const data = chunk.toString();
                     if (data.includes('data: reload')) {
+                        // Track the reload so concurrent tool calls wait for it
+                        let resolveReload;
+                        this._reloadPromise = new Promise(r => { resolveReload = r; });
                         try {
                             await this._navigateToPreview();
                         } catch (_e) {
                             // Preview may be mid-rebuild, retry will happen on next SSE
+                        } finally {
+                            this._reloadPromise = null;
+                            resolveReload();
                         }
                     }
                 });
@@ -425,9 +438,24 @@ class HeadlessBrowser {
      * @private
      */
     async _ensureCourseFrame() {
+        // If an SSE-triggered reload is in progress, wait for it to finish.
+        // This prevents tool calls from hitting a mid-reinitializing framework
+        // ("NavigationActions not initialized" errors after file edits).
+        if (this._reloadPromise) {
+            await this._reloadPromise;
+        }
+
         try {
-            // Quick check that the frame is still attached
-            await this.courseFrame.evaluate(() => true);
+            // Check that the frame is still attached AND the framework is ready.
+            // The stub player (in-page JS) may reload the iframe before the Node-side
+            // SSE handler sets _reloadPromise, so we must also verify readiness here.
+            const ready = await this.courseFrame.evaluate(
+                () => window.CourseCodeAutomation?.ready === true
+            );
+            if (!ready) {
+                // Frame is attached but framework is reinitializing — wait for it
+                await this._locateCourseFrame();
+            }
         } catch (_e) {
             // Frame detached (page reloaded), re-locate it
             await this._locateCourseFrame();

package/package.json

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

package/template/package.json

@@ -19,10 +19,10 @@
     "marked-gfm-heading-id": "^4.1.3"
   },
   "devDependencies": {
-    "@vitejs/plugin-legacy": "^7.2.1",
+    "@vitejs/plugin-legacy": "~7.2.1",
     "archiver": "^7.0.1",
     "eslint": "^9.39.1",
-    "vite": "^7.2.2",
+    "vite": "~7.2.2",
     "vite-plugin-static-copy": "^3.1.4"
   }
 }