coursecode 0.1.8 → 0.1.9

package/bin/cli.js

@@ -20,6 +20,33 @@ import { fileURLToPath } from 'url';
 import path from 'path';
 import fs from 'fs';
 
+// =============================================================================
+// CORPORATE NETWORK: System CA cert auto-injection
+//
+// On corporate machines with SSL-inspecting proxies (e.g. Zscaler), the proxy
+// presents its own CA certificate. Node.js ships its own CA bundle and ignores
+// the OS trust store, so TLS verification fails.
+//
+// Fix: export the OS root cert store to a temp PEM file and re-exec with
+// NODE_EXTRA_CA_CERTS pointing to it. Node picks it up before any TLS
+// handshakes. Transparent to users — completes in < 200ms.
+//
+// The NODE_EXTRA_CA_CERTS guard prevents an infinite re-exec loop.
+// =============================================================================
+
+if (!process.env.NODE_EXTRA_CA_CERTS) {
+  const { exportSystemCerts } = await import('../lib/cloud-certs.js');
+  const certPath = await exportSystemCerts();
+  if (certPath) {
+    const { execFileSync } = await import('child_process');
+    execFileSync(process.execPath, process.argv.slice(1), {
+      env: { ...process.env, NODE_EXTRA_CA_CERTS: certPath },
+      stdio: 'inherit',
+    });
+    process.exit(0);
+  }
+}
+
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const packageJson = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf-8'));
 
@@ -200,7 +227,6 @@ program
   .description('Send a test error to verify error reporting is configured correctly')
   .option('-t, --type <type>', 'Type of test: error or report', 'error')
   .option('-m, --message <message>', 'Custom message to include in the test')
-  .option('--insecure', 'Skip TLS certificate verification (for corporate proxies)')
   .action(async (options) => {
     const { testErrorReporting } = await import('../lib/test-error-reporting.js');
     await testErrorReporting(options);
@@ -212,7 +238,6 @@ program
   .description('Send a test data record to verify data reporting is configured correctly')
   .option('-t, --type <type>', 'Type of record: assessment, objective, or interaction', 'assessment')
   .option('-m, --message <message>', 'Custom message to include in the test')
-  .option('--insecure', 'Skip TLS certificate verification (for corporate proxies)')
   .action(async (options) => {
     const { testDataReporting } = await import('../lib/test-data-reporting.js');
     await testDataReporting(options);
@@ -280,10 +305,11 @@ program
   .command('login')
   .description('Log in to CourseCode Cloud')
   .option('--local', 'Use local Cloud instance (http://localhost:3000)')
+  .option('--json', 'Emit machine-readable JSON (for GUI/desktop integration)')
   .action(async (options) => {
     const { login, setLocalMode } = await import('../lib/cloud.js');
     if (options.local) setLocalMode();
-    await login();
+    await login({ json: options.json });
   });
 
 program

package/framework/docs/COURSE_AUTHORING_GUIDE.md

@@ -660,7 +660,7 @@ createLikertQuestion({
 
 ### Custom Interactions
 
-Add a `.js` file to `course/interactions/`. File `rating-scale.js` → factory `CourseCode.createRatingScaleQuestion()`. See `course/interactions/PLUGIN_GUIDE.md`.
+Add a `.js` file to `course/interactions/`. File `rating-scale.js` → factory `CourseCode.createRatingScaleQuestion()`. See "Extending with Plugins" in `framework/docs/USER_GUIDE.md`.
 
 ### Interaction Methods
 

package/framework/docs/FRAMEWORK_GUIDE.md

@@ -1122,7 +1122,7 @@ Exposed globally via `CourseCode.breakpointManager`.
 
 ## Adding New Interaction Types
 
-> **Course Authors:** See `course/interactions/PLUGIN_GUIDE.md`. Steps below are for framework developers.
+> **Course Authors:** See "Extending with Plugins" in `framework/docs/USER_GUIDE.md`. Steps below are for framework developers.
 
 1. Create file in `framework/js/components/interactions/`
 2. Export `create(container, config)`, `metadata`, and `schema`

package/framework/docs/USER_GUIDE.md

@@ -43,7 +43,12 @@ A complete guide to creating interactive e-learning courses with AI assistance.
    - [Learning Objectives](#learning-objectives)
    - [Course Completion Feedback](#course-completion-feedback)
    - [Updating Live Courses Safely](#updating-live-courses-safely)
-8. [Sharing and Deploying](#sharing-and-deploying)
+8. [Extending with Plugins](#extending-with-plugins)
+   - [Custom Interactions](#custom-interactions)
+   - [Custom UI Components](#custom-ui-components)
+   - [Custom Icons](#custom-icons)
+   - [Custom Styles](#custom-styles)
+9. [Sharing and Deploying](#sharing-and-deploying)
    - [Sharing Previews](#sharing-previews)
    - [Preview Export Options](#preview-export-options)
    - [Understanding LMS Formats](#understanding-lms-formats)
@@ -51,8 +56,8 @@ A complete guide to creating interactive e-learning courses with AI assistance.
    - [CDN Deployment (Advanced)](#cdn-deployment-advanced)
    - [Cloud Deployment](#cloud-deployment)
    - [Exporting Content for Review](#exporting-content-for-review)
-9. [Generating Audio Narration](#generating-audio-narration)
-10. [Troubleshooting](#troubleshooting)
+10. [Generating Audio Narration](#generating-audio-narration)
+11. [Troubleshooting](#troubleshooting)
 
 ---
 
@@ -514,6 +519,93 @@ Best practice: set and increment `metadata.version` in `course/course-config.js`
 
 ---
 
+## Extending with Plugins
+
+CourseCode has a built-in plugin system. You can extend it with your own interaction types, UI components, icons, and styles — all auto-discovered from your `course/` folder without any framework changes.
+
+| Extension Point | Where to Put It | What It Adds |
+|-----------------|-----------------|-------------|
+| Custom interactions | `course/interactions/*.js` | New question/activity types |
+| Custom UI components | `course/components/*.js` | New reusable HTML components |
+| Custom icons | `course/icons.js` | New icons available everywhere |
+| Custom styles | `course/theme.css` | Global CSS for your plugins and brand |
+
+Plugins are just JavaScript files that follow a simple contract. Your AI assistant can write them — describe what you want and share `framework/docs/USER_GUIDE.md` (see "Extending with Plugins") as context.
+
+### Custom Interactions
+
+Create a new question or activity type by dropping a `.js` file in `course/interactions/`. It registers automatically.
+
+A minimal plugin exports one function:
+
+```javascript
+// course/interactions/rating-scale.js
+export function create(container, config) {
+  let response = null;
+  container.innerHTML = `<div data-interaction-id="${config.id}">...</div>`;
+  return {
+    getResponse: () => response,
+    setResponse: (val) => { response = val; },
+    checkAnswer: () => ({ correct: response === config.correctAnswer, score: 1 }),
+    reset: () => { response = null; }
+  };
+}
+```
+
+Then use it in a slide:
+
+```javascript
+const rating = CourseCode.createRatingScaleQuestion(container, {
+  id: 'my-rating',
+  prompt: 'How would you rate this?',
+  options: ['Poor', 'Fair', 'Good', 'Excellent']
+});
+```
+
+The factory name is derived from the filename: `rating-scale.js` → `createRatingScaleQuestion`.
+
+For a complete example with schema and metadata (which enable linting and AI tooling), see the "Extending with Plugins" section in `framework/docs/USER_GUIDE.md`.
+
+### Custom UI Components
+
+Add reusable HTML components (info boxes, custom cards, branded banners) by dropping a `.js` file in `course/components/`. Use them in slides via `data-component`:
+
+```html
+<div data-component="info-box" data-icon="warning">
+  Important note here
+</div>
+```
+
+See the "Extending with Plugins" section in `framework/docs/USER_GUIDE.md` for the component contract.
+
+### Custom Icons
+
+Add icons to `course/icons.js` and they're available throughout the course:
+
+```javascript
+// course/icons.js
+export const customIcons = {
+  'rocket': '<path d="M12 2L8 8H4l8 14 8-14h-4L12 2z" />'
+};
+```
+
+### Custom Styles
+
+`course/theme.css` is always loaded. It's the right place for plugin-specific CSS as well as brand colors and fonts:
+
+```css
+/* course/theme.css */
+:root {
+  --primary: #0066cc;
+}
+
+.info-box { border-left: 4px solid var(--primary); padding: 1rem; }
+```
+
+Use CSS variables from the design system (`--primary`, `--border`, `--radius`, etc.) so your plugins automatically respect the course theme.
+
+---
+
 ## Sharing and Deploying
 
 ### Sharing Previews
@@ -614,6 +706,23 @@ coursecode deploy    # Build + upload to cloud
 Cloud-served launches also auto-configure runtime error reporting, data reporting, and channel relay endpoints (zero-config cloud wiring).
 If you configured manual endpoints in `course-config.js` for self-hosted workflows, Cloud launches override them with cloud-injected runtime config.
 
+**Signing in (`coursecode login`):**
+
+Running `coursecode login` displays a URL and a short code in your terminal:
+
+```
+  ┌─────────────────────────────────────────────────────┐
+  │  Open this URL in your browser:                     │
+  │  https://coursecodecloud.com/activate               │
+  │                                                     │
+  │  Enter your code:  ABCD-1234                        │
+  │                                                     │
+  │  Expires in 15 minutes                              │
+  └─────────────────────────────────────────────────────┘
+```
+
+Open the URL in any browser, log in with your CourseCode account, and enter the code. The terminal confirms login automatically — no redirect back required. The code is valid for 15 minutes and works from any device or browser.
+
 **What CourseCode Cloud helps with (plain English):**
 - Host your course online so learners/reviewers can access it without you manually hosting files
 - Generate the LMS package you need later (SCORM/cmi5) from the same upload
@@ -621,10 +730,10 @@ If you configured manual endpoints in `course-config.js` for self-hosted workflo
 - Manage deployment updates without rebuilding separate packages for each LMS format
 - Provide cloud-managed runtime services (reporting/channel) without extra endpoint setup in your course files
 
-**Typical Cloud workflow (CLI):**
-1. Run `coursecode login` once and sign in.
+**Typical Cloud workflow:**
+1. Run `coursecode login` once, open the URL shown, and enter the code.
 2. Run `coursecode deploy` from your project folder.
-3. Open the CourseCode Cloud course page/dashboard link shown after deploy.
+3. Open the CourseCode Cloud dashboard link shown after deploy.
 4. Use Cloud preview links for review.
 5. Download the LMS format you need from Cloud when you're ready to deliver.
 

package/lib/cloud-certs.js

@@ -0,0 +1,141 @@
+/**
+ * cloud-certs.js — System CA certificate export for corporate network compatibility.
+ *
+ * Exports the OS trusted root store to a temp PEM file so Node.js can verify
+ * TLS connections that pass through SSL-inspecting proxies (e.g. Zscaler).
+ *
+ * Returns the path to the PEM file on success, null on failure.
+ * Never throws — silent fallback for non-corporate machines.
+ */
+
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import crypto from 'crypto';
+
+const execFileAsync = promisify(execFile);
+
+/** Cached result — only export once per process lifetime. */
+let _cachedCertPath = undefined;
+
+/**
+ * Export the OS system root certificate store to a temp PEM file.
+ *
+ * @returns {Promise<string|null>} Absolute path to the PEM file, or null if unavailable.
+ */
+export async function exportSystemCerts() {
+  if (_cachedCertPath !== undefined) return _cachedCertPath;
+
+  try {
+    const pem = await readSystemCerts();
+    if (!pem || !pem.trim()) {
+      _cachedCertPath = null;
+      return null;
+    }
+
+    // Write to a stable temp path (same content = same hash, avoids accumulation)
+    const hash = crypto.createHash('sha1').update(pem).digest('hex').slice(0, 8);
+    const certPath = path.join(os.tmpdir(), `coursecode-ca-${hash}.pem`);
+
+    if (!fs.existsSync(certPath)) {
+      fs.writeFileSync(certPath, pem, { mode: 0o600 });
+    }
+
+    _cachedCertPath = certPath;
+    return certPath;
+  } catch {
+    _cachedCertPath = null;
+    return null;
+  }
+}
+
+/**
+ * Read system certificates as a PEM string.
+ * Platform-specific — returns null if the platform is unsupported or export fails.
+ */
+async function readSystemCerts() {
+  const platform = process.platform;
+
+  if (platform === 'darwin') {
+    return readMacosCerts();
+  }
+
+  if (platform === 'win32') {
+    return readWindowsCerts();
+  }
+
+  // Linux/other: read well-known bundle paths directly
+  return readLinuxCerts();
+}
+
+/**
+ * macOS: export the system root keychain via the `security` CLI tool.
+ * This includes all roots installed via Apple MDM / System Preferences.
+ */
+async function readMacosCerts() {
+  // Export from all common keychains — ignore errors on missing keychains
+  const keychains = [
+    '/Library/Keychains/SystemRootCertificates.keychain',
+    '/System/Library/Keychains/SystemRootCertificates.keychain',
+    '/Library/Keychains/System.keychain',
+  ];
+
+  const pems = [];
+  for (const keychain of keychains) {
+    try {
+      const { stdout } = await execFileAsync('security', [
+        'find-certificate', '-a', '-p', keychain,
+      ], { maxBuffer: 16 * 1024 * 1024 });
+      if (stdout) pems.push(stdout);
+    } catch {
+      // Keychain not present on this OS version — skip
+    }
+  }
+
+  return pems.join('\n');
+}
+
+/**
+ * Windows: export LocalMachine\Root via PowerShell.
+ * This includes certs deployed via Group Policy / MDM.
+ */
+async function readWindowsCerts() {
+  const script = [
+    '$certs = Get-ChildItem -Path Cert:\\LocalMachine\\Root',
+    '$pems = $certs | ForEach-Object {',
+    '  $bytes = $_.Export([System.Security.Cryptography.X509Certificates.X509ContentType]::Cert)',
+    '  $b64 = [System.Convert]::ToBase64String($bytes, "InsertLineBreaks")',
+    '  "-----BEGIN CERTIFICATE-----`n" + $b64 + "`n-----END CERTIFICATE-----"',
+    '}',
+    '$pems -join "`n"',
+  ].join('; ');
+
+  const { stdout } = await execFileAsync('powershell', [
+    '-NoProfile', '-NonInteractive', '-Command', script,
+  ], { maxBuffer: 16 * 1024 * 1024 });
+
+  return stdout;
+}
+
+/**
+ * Linux: read the system CA bundle from well-known locations.
+ * No subprocess needed — just read the file directly.
+ */
+function readLinuxCerts() {
+  const candidatePaths = [
+    '/etc/ssl/certs/ca-certificates.crt',       // Debian/Ubuntu
+    '/etc/pki/tls/certs/ca-bundle.crt',          // RHEL/CentOS/Fedora
+    '/etc/ssl/ca-bundle.pem',                     // OpenSUSE
+    '/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem', // RHEL 7+
+  ];
+
+  for (const p of candidatePaths) {
+    if (fs.existsSync(p)) {
+      return fs.readFileSync(p, 'utf-8');
+    }
+  }
+
+  return null;
+}

package/lib/cloud.js

@@ -23,6 +23,10 @@ const packageJson = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'packa
 // =============================================================================
 
 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 LOCAL_CLOUD_URL = 'http://localhost:3000';
 let useLocal = false;
 const CREDENTIALS_DIR = path.join(os.homedir(), '.coursecode');
@@ -31,8 +35,9 @@ const PROJECT_CONFIG_DIR = '.coursecode';
 const PROJECT_CONFIG_PATH = path.join(PROJECT_CONFIG_DIR, 'project.json');
 
 const POLL_INTERVAL_MS = 2000;
-const POLL_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+const POLL_TIMEOUT_MS = 15 * 60 * 1000; // 15 minutes (device code expiry)
 const USER_AGENT = `coursecode-cli/${packageJson.version}`;
+const ACTIVATION_PATH = '/activate';
 
 // =============================================================================
 // SLUG UTILITIES
@@ -163,38 +168,123 @@ function writeRcCloudId(cloudId) {
  * 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)
- * @returns {Promise<Response>}
+ * @returns {Promise<Response>} A Response whose body has been replaced with
+ *   the raw text so handleResponse can always call res.text() safely.
  */
 async function cloudFetch(urlPath, options = {}, token = null) {
-  const cloudUrl = getCloudUrl();
-  const url = `${cloudUrl}${urlPath}`;
-
   const headers = {
     'User-Agent': USER_AGENT,
     ...options.headers,
   };
+  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
+    }
+  };
 
-  if (token) {
-    headers['Authorization'] = `Bearer ${token}`;
-  }
+  const primaryUrl = getCloudUrl();
+  const res = await attemptFetch(primaryUrl);
 
-  try {
-    return await fetch(url, { ...options, headers });
-  } catch (_error) {
+  if (!res) {
+    // Primary unreachable — try fallback before giving up
+    if (!useLocal) {
+      const fallback = await attemptFetch(FALLBACK_CLOUD_URL);
+      if (fallback) return fallback;
+    }
     console.error('\n❌ Could not connect to CourseCode Cloud. Check your internet connection.\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.
+  const text = await res.text();
+  if (isBlockPage(text) && !useLocal) {
+    const fallbackRes = await attemptFetch(FALLBACK_CLOUD_URL);
+    if (fallbackRes) {
+      const fallbackText = await fallbackRes.text();
+      if (!isBlockPage(fallbackText)) {
+        // Fallback succeeded — return a synthetic Response with the buffered text
+        return syntheticResponse(fallbackText, fallbackRes.status);
+      }
+    }
+    // Both primary and fallback are blocked — surface the error
+    reportBlockPage(text, res);
+    process.exit(1);
+  }
+
+  // Primary response is fine — return a synthetic Response with the buffered text
+  return syntheticResponse(text, res.status);
+}
+
+/** Quick check whether a response body looks like an HTML block page. */
+function isBlockPage(text) {
+  const lower = text.toLowerCase();
+  return lower.includes('<!doctype') || lower.startsWith('<html');
+}
+
+/**
+ * Create a minimal synthetic Response that wraps already-buffered text.
+ * handleResponse always calls res.text() — this keeps the interface uniform.
+ */
+function syntheticResponse(text, status) {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    text: () => Promise.resolve(text),
+  };
+}
+
+/**
+ * Print a vendor-specific block page error message.
+ *
+ * @param {string} body - Raw response body text
+ * @param {Response} res - The fetch Response object
+ */
+function reportBlockPage(body, res) {
+  const lower = body.toLowerCase();
+  if (lower.includes('zscaler')) {
+    console.error('\n❌ coursecodecloud.com 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.');
+  } else if (lower.includes('barracuda')) {
+    console.error('\n❌ coursecodecloud.com is blocked by Barracuda on your network.');
+  } else {
+    console.error(`\n❌ Your network blocked coursecodecloud.com (HTTP ${res.status}).`);
+  }
+  console.error('   Ask your IT team to whitelist: coursecodecloud.com\n');
 }
 
 /**
  * Handle HTTP error responses per §7.
  * Returns the parsed JSON body, or exits on error.
+ *
+ * Reads the body as text first so we can detect non-JSON responses. By the
+ * time this is called, cloudFetch has already handled block page detection
+ * and fallback retry — so text here should always be valid JSON.
  */
 async function handleResponse(res, { retryFn, _isRetry = false } = {}) {
-  if (res.ok) return res.json();
+  const text = await res.text();
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    // Should not happen after cloudFetch filtering — treat as server error
+    console.error(`\n❌ Unexpected response from Cloud (HTTP ${res.status}). Try again later.\n`);
+    process.exit(1);
+  }
+
+  if (res.ok) return body;
 
   const status = res.status;
 
@@ -206,10 +296,15 @@ async function handleResponse(res, { retryFn, _isRetry = false } = {}) {
     return retryFn(true);
   }
 
-  // Parse error body
-  let body;
-  try { body = await res.json(); } catch { body = {}; }
-  const message = body.error || `HTTP ${status}`;
+  return handleResponseError(status, body);
+}
+
+/**
+ * Handle a known HTTP error status code with a parsed body.
+ * Exits the process with an appropriate message.
+ */
+function handleResponseError(status, body) {
+  const message = body?.error || `HTTP ${status}`;
 
   if (status === 403 || status === 409) {
     console.error(`\n❌ ${message}\n`);
@@ -260,18 +355,130 @@ function sleep(ms) {
 }
 
 /**
- * Run the nonce exchange login flow.
- * 1. Generate nonce
- * 2. POST /api/auth/connect to create session
- * 3. Open browser
- * 4. Poll until token received or timeout
- * 5. Store credentials
+ * Run the device code login flow (primary).
+ *
+ * Flow:
+ *   1. POST /api/auth/device  → get { deviceCode, userCode, verificationUri, expiresIn, interval }
+ *   2. Display userCode + activation URLs prominently
+ *   3. Open browser as a convenience (user can ignore if ZBI isolates it)
+ *   4. Poll GET /api/auth/device?code={deviceCode} until token or expiry
+ *   5. Store credentials
+ *
+ * Resilient to Zscaler Browser Isolation: the browser session is fully decoupled
+ * from the CLI. The user can open the activation URL in any browser, on any device.
+ *
+ * Falls back to the legacy nonce flow if the cloud returns 404 (not yet deployed).
+ */
+async function runLoginFlow({ jsonMode = false } = {}) {
+  // Helper: emit a JSON event line (JSON mode) or nothing (normal mode)
+  const emit = (obj) => process.stdout.write(JSON.stringify(obj) + '\n');
+  const log = (...args) => { if (!jsonMode) console.log(...args); };
+
+  // Step 1: Request device code
+  const deviceRes = await cloudFetch('/api/auth/device', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+  });
+
+  // Graceful fallback: cloud not yet updated to support device flow
+  if (deviceRes.status === 404) {
+    return runLegacyLoginFlow();
+  }
+
+  if (!deviceRes.ok) {
+    let body = {};
+    try { body = JSON.parse(await deviceRes.text()); } catch { /* ignore */ }
+    const msg = body.error || `HTTP ${deviceRes.status}`;
+    if (jsonMode) { emit({ type: 'error', error: msg }); } else { console.error(`\n❌ Failed to start login: ${msg}\n`); }
+    process.exit(1);
+  }
+
+  let devicePayload;
+  try {
+    devicePayload = JSON.parse(await deviceRes.text());
+  } catch {
+    console.error('\n❌ Unexpected response from Cloud during login. Try again.\n');
+    process.exit(1);
+  }
+  const { deviceCode, userCode, verificationUri, expiresIn, interval } = devicePayload;
+
+  const pollIntervalMs = (interval || 5) * 1000;
+  const expiryMs = (expiresIn || 900) * 1000;
+
+  // Derive the activation URL from the server response or fall back to the primary domain
+  const primaryActivationUrl = verificationUri || `${getCloudUrl()}${ACTIVATION_PATH}`;
+
+  if (jsonMode) {
+    // Emit structured event for GUI to display its own device code UI
+    emit({
+      type: 'device_code',
+      userCode,
+      verificationUri: primaryActivationUrl,
+      deviceCode,
+      expiresIn: expiresIn || 900,
+      interval: interval || 5,
+    });
+  } else {
+    // Step 2: Display code prominently
+    const line = '─'.repeat(51);
+    log(`\n  ┌${line}┐`);
+    log('  │  Open this URL in your browser:                   │');
+    log(`  │  ${primaryActivationUrl.padEnd(49)}│`);
+    log('  │                                                   │');
+    log(`  │  Enter your code:  ${userCode.padEnd(31)}│`);
+    log('  │                                                   │');
+    const expiryMins = Math.round(expiryMs / 60000);
+    log(`  │  Expires in ${String(expiryMins + ' minutes').padEnd(37)}│`);
+    log(`  └${line}┘\n`);
+  }
+
+  // Step 3: Poll for token
+  log('  Waiting for authorization...');
+  const startTime = Date.now();
+  while (Date.now() - startTime < expiryMs) {
+    await sleep(pollIntervalMs);
+
+    const pollRes = await cloudFetch(`/api/auth/device?code=${encodeURIComponent(deviceCode)}`);
+
+    if (pollRes.status === 410) {
+      const msg = 'Login code expired. Run `coursecode login` to try again.';
+      if (jsonMode) { emit({ type: 'error', error: 'expired' }); } else { console.error(`\n❌ ${msg}\n`); }
+      process.exit(1);
+    }
+
+    if (pollRes.status === 400) {
+      let body = {};
+      try { body = JSON.parse(await pollRes.text()); } catch { /* ignore */ }
+      if (jsonMode) { emit({ type: 'error', error: body.error || 'denied' }); } else { console.error(`\n❌ Login ${body.error || 'failed'}. Run \`coursecode login\` to try again.\n`); }
+      process.exit(1);
+    }
+
+    if (!pollRes.ok) continue;
+
+    const data = JSON.parse(await pollRes.text());
+    if (data.pending) continue;
+
+    if (data.token) {
+      writeCredentials(data.token, getCloudUrl());
+      log('  ✓ Logged in successfully\n');
+      return data.token;
+    }
+  }
+
+  const timeoutMsg = 'Login timed out. Run `coursecode login` to try again.';
+  if (jsonMode) { emit({ type: 'error', error: 'timeout' }); } else { console.error(`\n❌ ${timeoutMsg}\n`); }
+  process.exit(1);
+}
+
+/**
+ * Legacy nonce-exchange login flow.
+ * Used as a fallback when the cloud has not yet deployed the device code endpoint.
+ * Can be removed once the device code flow is fully rolled out.
  */
-async function runLoginFlow() {
+async function runLegacyLoginFlow() {
   const nonce = crypto.randomBytes(32).toString('hex');
   const cloudUrl = getCloudUrl();
 
-  // Step 1: Create CLI session
   console.log('  → Registering session...');
   const createRes = await cloudFetch('/api/auth/connect', {
     method: 'POST',
@@ -280,17 +487,16 @@ async function runLoginFlow() {
   });
 
   if (!createRes.ok) {
-    const body = await createRes.json().catch(() => ({}));
+    let body = {};
+    try { body = JSON.parse(await createRes.text()); } catch { /* ignore */ }
     console.error(`\n❌ Failed to start login: ${body.error || `HTTP ${createRes.status}`}\n`);
     process.exit(1);
   }
 
-  // Step 2: Open browser
   const loginUrl = `${cloudUrl}/auth/connect?session=${nonce}`;
   console.log('  → Opening browser for authentication...');
   openBrowser(loginUrl);
 
-  // Step 3: Poll for token
   const startTime = Date.now();
   while (Date.now() - startTime < POLL_TIMEOUT_MS) {
     await sleep(POLL_INTERVAL_MS);
@@ -304,7 +510,7 @@ async function runLoginFlow() {
 
     if (!pollRes.ok) continue;
 
-    const data = await pollRes.json();
+    const data = JSON.parse(await pollRes.text());
     if (data.pending) continue;
 
     if (data.token) {
@@ -446,21 +652,26 @@ function formatDate(isoString) {
 /**
  * coursecode login — explicit (re-)authentication
  */
-export async function login() {
-  console.log('\n🔑 Logging in to CourseCode Cloud...\n');
-  await runLoginFlow();
+export async function login(options = {}) {
+  const jsonMode = Boolean(options.json);
+  if (!jsonMode) console.log('\n🔑 Logging in to CourseCode Cloud...\n');
+  await runLoginFlow({ jsonMode });
 
   // Show who they are
   const token = readCredentials()?.token;
   if (token) {
     const res = await cloudFetch('/api/cli/whoami', {}, token);
     if (res.ok) {
-      const data = await res.json();
-      console.log(`  ✓ Logged in as ${data.full_name} (${data.email})\n`);
+      const data = JSON.parse(await res.text());
+      if (jsonMode) {
+        process.stdout.write(JSON.stringify({ type: 'success', email: data.email, name: data.full_name }) + '\n');
+      } else {
+        console.log(`  ✓ Logged in as ${data.full_name} (${data.email})\n`);
+      }
       return;
     }
   }
-  console.log('');
+  if (!jsonMode) console.log('');
 }
 
 /**

package/lib/mcp-prompts.js

@@ -715,7 +715,7 @@ All runtime tools (state, navigate, interact, screenshot, viewport, reset) execu
 ### Customization (all in course/, never in framework/)
 - **CSS overrides**: Edit \`course/theme.css\` — override palette tokens to rebrand (all colors cascade via color-mix). Use framework utility classes first (\`coursecode_css_catalog\`), \`theme.css\` only for brand-specific overrides.
 - **Custom components**: Add \`.js\` files to \`course/components/\` — auto-discovered at build time. Use \`coursecode_component_catalog\` for built-in options first.
-- **Custom interactions**: Add \`.js\` files to \`course/interactions/\` — auto-discovered. See \`course/interactions/PLUGIN_GUIDE.md\` for the template.
+- **Custom interactions**: Add \`.js\` files to \`course/interactions/\` — auto-discovered. See "Extending with Plugins" in \`framework/docs/USER_GUIDE.md\` for the contract.
 - **Custom icons**: Add SVG definitions to \`course/icons.js\` — merged with built-in icons. Use icon_catalog to check existing icons first.`;
 }
 

package/lib/test-data-reporting.js

@@ -15,11 +15,6 @@ import { pathToFileURL } from 'url';
  * @param {string} options.message - Custom message to include
  */
 export async function testDataReporting(options = {}) {
-    // Handle TLS certificate issues (corporate proxies)
-    if (options.insecure) {
-        process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';
-    }
-
     const cwd = process.cwd();
     const configPath = path.join(cwd, 'course', 'course-config.js');
 

package/lib/test-error-reporting.js

@@ -15,11 +15,6 @@ import { pathToFileURL } from 'url';
  * @param {string} options.message - Custom message to include
  */
 export async function testErrorReporting(options = {}) {
-    // Handle TLS certificate issues (corporate proxies)
-    if (options.insecure) {
-        process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';
-    }
-    
     const cwd = process.cwd();
     const configPath = path.join(cwd, 'course', 'course-config.js');
     

package/package.json

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

package/template/course/components/components-readme.md

@@ -0,0 +1,5 @@
+# Custom Components
+
+Drop `.js` files here to add new UI components. They are auto-discovered and registered at build time.
+
+See **"Extending with Plugins"** in `framework/docs/USER_GUIDE.md` for the plugin contract and examples.

package/template/course/interactions/interactions-readme.md

@@ -0,0 +1,5 @@
+# Custom Interactions
+
+Drop `.js` files here to add new interaction types. They are auto-discovered and registered at build time.
+
+See **"Extending with Plugins"** in `framework/docs/USER_GUIDE.md` for the plugin contract and examples.

package/template/course/interactions/PLUGIN_GUIDE.md

@@ -1,97 +0,0 @@
-# Custom Interactions
-
-Drop a `.js` file here to auto-register a custom interaction type.
-
-## Quick Start
-
-**File:** `rating-scale.js` → **Factory:** `CourseCode.createRatingScaleQuestion()`
-
-```javascript
-// Optional: Schema for linting/AI assistance
-export const schema = {
-  type: 'rating-scale',
-  properties: {
-    options: { type: 'array', required: true, description: 'Rating options' },
-    correctAnswer: { type: 'string', description: 'Correct option index' }
-  }
-};
-
-// Optional: Metadata for UI tools
-export const metadata = {
-  label: 'Rating Scale',
-  category: 'interactive',
-  scormType: 'choice'
-};
-
-// Required: Creator function
-export function create(container, config) {
-  let response = null;
-  
-  // Inject styles once
-  if (!document.getElementById('rating-scale-styles')) {
-    const el = document.createElement('style');
-    el.id = 'rating-scale-styles';
-    el.textContent = `
-      .rating-scale { display: flex; gap: 0.5rem; }
-      .rating-scale-option { cursor: pointer; padding: 0.5rem 1rem; border: 1px solid var(--border); border-radius: var(--radius); }
-      .rating-scale-option.selected { background: var(--primary); color: white; }
-    `;
-    document.head.appendChild(el);
-  }
-  
-  container.innerHTML = `
-    <div class="interaction" data-interaction-id="${config.id}">
-      <p class="prompt">${config.prompt}</p>
-      <div class="rating-scale">
-        ${config.options.map((opt, i) => 
-          `<button type="button" class="rating-scale-option" data-value="${i}">${opt}</button>`
-        ).join('')}
-      </div>
-    </div>
-  `;
-  
-  container.querySelectorAll('.rating-scale-option').forEach(btn => {
-    btn.addEventListener('click', () => {
-      container.querySelectorAll('.rating-scale-option').forEach(b => b.classList.remove('selected'));
-      btn.classList.add('selected');
-      response = btn.dataset.value;
-    });
-  });
-  
-  return {
-    getResponse: () => response,
-    setResponse: (val) => {
-      response = val;
-      container.querySelectorAll('.rating-scale-option').forEach(btn => {
-        btn.classList.toggle('selected', btn.dataset.value === String(val));
-      });
-    },
-    checkAnswer: () => ({ correct: response === config.correctAnswer, score: response === config.correctAnswer ? 1 : 0 }),
-    reset: () => {
-      response = null;
-      container.querySelectorAll('.rating-scale-option').forEach(b => b.classList.remove('selected'));
-    }
-  };
-}
-```
-
-## Exports
-
-| Export | Required | Purpose |
-|--------|----------|---------|
-| `create(container, config)` | ✅ | Factory function |
-| `schema` | Optional | Enables linting, AI assistance, preview editor |
-| `metadata` | Optional | UI labels, categories, SCORM interaction type |
-
-## Usage in Slides
-
-```javascript
-const rating = CourseCode.createRatingScaleQuestion(container, {
-  id: 'my-rating',
-  prompt: 'How would you rate this?',
-  options: ['Poor', 'Fair', 'Good', 'Excellent'],
-  correctAnswer: '3'
-});
-```
-
-See `COURSE_AUTHORING_GUIDE.md` for full interaction API.