coursecode 0.1.10 → 0.1.13

package/bin/cli.js

@@ -166,12 +166,13 @@ program
 // Convert command
 program
   .command('convert [source]')
-  .description('Convert docx, pptx, and pdf files to markdown for course authoring')
+  .description('Convert docx, pptx, and pdf files to markdown for course authoring (PDF JSON sidecars optional)')
   .option('-o, --output <dir>', 'Output directory for converted files', './course/references/converted')
   .option('-f, --format <type>', 'Limit to format: docx, pptx, pdf, or all', 'all')
   .option('--dry-run', 'Show what would be converted without writing files')
   .option('--overwrite', 'Overwrite existing markdown files')
   .option('--flatten', 'Output all files to single directory (no subdirs)')
+  .option('--pdf-json', 'Also write PDF structure JSON sidecars (.json) next to converted markdown')
   .action(async (source = './course/references', options) => {
     const { convert } = await import('../lib/convert.js');
     await convert(source, options);
@@ -317,10 +318,11 @@ program
   .command('logout')
   .description('Log out of CourseCode Cloud')
   .option('--local', 'Use local Cloud instance (http://localhost:3000)')
+  .option('--json', 'Emit machine-readable JSON')
   .action(async (options) => {
     const { logout, setLocalMode } = await import('../lib/cloud.js');
     if (options.local) setLocalMode();
-    await logout();
+    await logout({ json: options.json });
   });
 
 program
@@ -338,33 +340,66 @@ program
   .command('courses')
   .description('List courses on CourseCode Cloud')
   .option('--local', 'Use local Cloud instance (http://localhost:3000)')
+  .option('--json', 'Output raw JSON array')
   .action(async (options) => {
     const { listCourses, setLocalMode } = await import('../lib/cloud.js');
     if (options.local) setLocalMode();
-    await listCourses();
+    await listCourses({ json: options.json });
   });
 
 program
   .command('deploy')
   .description('Build and deploy course to CourseCode Cloud')
-  .option('--preview', 'Deploy as preview (expires in 7 days)')
-  .option('--password', 'Password-protect preview (interactive prompt)')
+  .option('--preview', 'Deploy as preview-only (production untouched, preview pointer always moved). Combine with --promote or --stage for a full deploy that also moves the preview pointer.')
+  .option('--promote', 'Force-promote: always move production pointer regardless of deploy_mode setting. Mutually exclusive with --stage.')
+  .option('--stage', 'Force-stage: never move production pointer regardless of deploy_mode setting. Mutually exclusive with --promote.')
+  .option('--password', 'Password-protect preview (interactive prompt, requires --preview)')
   .option('-m, --message <message>', 'Deploy reason (e.g. "Fixed accessibility issues")')
   .option('--local', 'Use local Cloud instance (http://localhost:3000)')
+  .option('--json', 'Emit machine-readable JSON result')
   .action(async (options) => {
     const { deploy, setLocalMode } = await import('../lib/cloud.js');
     if (options.local) setLocalMode();
     await deploy(options);
   });
 
+program
+  .command('promote')
+  .description('Promote a deployment to production or preview pointer')
+  .option('--production', 'Promote to the production pointer')
+  .option('--preview', 'Promote to the preview pointer')
+  .option('--deployment <id>', 'Deployment ID to promote (skip interactive prompt)')
+  .option('-m, --message <message>', 'Reason for promotion')
+  .option('--local', 'Use local Cloud instance (http://localhost:3000)')
+  .option('--json', 'Emit machine-readable JSON result')
+  .action(async (options) => {
+    const { promote, setLocalMode } = await import('../lib/cloud.js');
+    if (options.local) setLocalMode();
+    await promote(options);
+  });
+
+
 program
   .command('status')
   .description('Show deployment status for current course')
   .option('--local', 'Use local Cloud instance (http://localhost:3000)')
+  .option('--json', 'Output raw JSON')
   .action(async (options) => {
     const { status, setLocalMode } = await import('../lib/cloud.js');
     if (options.local) setLocalMode();
-    await status();
+    await status({ json: options.json });
+  });
+
+program
+  .command('delete')
+  .description('Remove course from CourseCode Cloud (does not delete local files)')
+  .option('--force', 'Skip confirmation prompt')
+  .option('--local', 'Use local Cloud instance (http://localhost:3000)')
+  .option('--json', 'Emit machine-readable JSON result')
+  .action(async (options) => {
+    const { deleteCourse, setLocalMode } = await import('../lib/cloud.js');
+    if (options.local) setLocalMode();
+    await deleteCourse({ force: options.force, json: options.json });
   });
 
 program.parse();

package/framework/docs/FRAMEWORK_GUIDE.md

@@ -123,7 +123,7 @@ The browser only downloads the one chunk matching the meta tag. Unused driver ch
 | `coursecode build` | `dist/` | Universal build + format manifest + meta tag stamped |
 | `coursecode build` (with `PACKAGE=true`) | `dist/` + ZIP | Same + format-specific ZIP for LMS upload |
 | `coursecode preview --export` | `course-preview/` | Copy of `dist/` wrapped in stub player (for Netlify/GitHub Pages) |
-| `coursecode deploy` | Uploads `dist/` | Cloud hosts universal build, assembles format ZIPs on demand |
+| `coursecode deploy` | Uploads `dist/` | Cloud hosts universal build, assembles format ZIPs on demand. Flags: `--promote` (force live), `--stage` (force staged), `--preview` (preview-only: production untouched, preview always moved). `--promote`/`--stage` are mutually exclusive; `--preview` stacks with either. |
 
 The ZIP never includes preview/stub player assets. Preview is a separate concern (see below).
 

package/framework/docs/USER_GUIDE.md

@@ -723,12 +723,23 @@ Running `coursecode login` displays a URL and a short code in your terminal:
 
 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
-- Share preview links for stakeholder review
-- 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
+**Deploy flags:**
+
+`coursecode deploy` accepts flags that control how the production and preview pointers are updated after upload:
+
+| Command | Production pointer | Preview pointer |
+|---|---|---|
+| `cc deploy` | Follows your deploy_mode setting | Follows your preview_deploy_mode setting |
+| `cc deploy --promote` | Always moved to new version | Follows your preview_deploy_mode setting |
+| `cc deploy --stage` | Never moved (stays on old version) | Follows your preview_deploy_mode setting |
+| `cc deploy --preview` | **Untouched** (preview-only upload) | Always moved to new version |
+| `cc deploy --promote --preview` | Always moved to new version | Always moved to new version |
+| `cc deploy --stage --preview` | Never moved | Always moved to new version |
+
+- **Production pointer** — the version learners see when they launch your course.
+- **Preview pointer** — the version served on the cloud preview link (for stakeholder review).
+- **deploy_mode** — a per-course or org setting in the Cloud dashboard. Default is auto-promote (new uploads immediately go live). Can be set to staged (new uploads require a manual promote step).
+- `--promote` and `--stage` are mutually exclusive.
 
 **Typical Cloud workflow:**
 1. Run `coursecode login` once, open the URL shown, and enter the code.

package/lib/cloud.js

@@ -29,6 +29,7 @@ const DEFAULT_CLOUD_URL = 'https://coursecodecloud.com';
 const FALLBACK_CLOUD_URL = 'https://coursecode-cloud-web.vercel.app';
 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';
@@ -93,12 +94,19 @@ function writeCredentials(token, cloudUrl = DEFAULT_CLOUD_URL) {
   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;
 }
 
@@ -108,6 +116,7 @@ function getCloudUrl() {
  */
 export function setLocalMode() {
   useLocal = true;
+  activeCloudUrl = LOCAL_CLOUD_URL;
 }
 
 // =============================================================================
@@ -127,9 +136,11 @@ function readProjectConfig() {
 function writeProjectConfig(data) {
   const dir = path.join(process.cwd(), PROJECT_CONFIG_DIR);
   fs.mkdirSync(dir, { recursive: true });
+  const existing = readProjectConfig() || {};
+  Object.assign(existing, data);
   fs.writeFileSync(
     path.join(process.cwd(), PROJECT_CONFIG_PATH),
-    JSON.stringify(data, null, 2) + '\n'
+    JSON.stringify(existing, null, 2) + '\n'
   );
 }
 
@@ -151,12 +162,13 @@ function readRcConfig() {
 }
 
 /**
- * Stamp cloudId into .coursecoderc.json without clobbering other fields.
+ * Merge fields into .coursecoderc.json without clobbering unrelated fields.
+ * Use this for any cloud binding state (cloudId, orgId, etc.).
  */
-function writeRcCloudId(cloudId) {
+function writeRcConfig(fields) {
   const rcPath = path.join(process.cwd(), '.coursecoderc.json');
   const existing = readRcConfig() || {};
-  existing.cloudId = cloudId;
+  Object.assign(existing, fields);
   fs.writeFileSync(rcPath, JSON.stringify(existing, null, 2) + '\n');
 }
 
@@ -200,7 +212,10 @@ async function cloudFetch(urlPath, options = {}, token = null) {
     // Primary unreachable — try fallback before giving up
     if (!useLocal) {
       const fallback = await attemptFetch(FALLBACK_CLOUD_URL);
-      if (fallback) return fallback;
+      if (fallback) {
+        activeCloudUrl = FALLBACK_CLOUD_URL;
+        return fallback;
+      }
     }
     console.error('\n❌ Could not connect to CourseCode Cloud. Check your internet connection.\n');
     process.exit(1);
@@ -209,11 +224,29 @@ async function cloudFetch(urlPath, options = {}, token = null) {
   // 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();
+
+  // 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);
       }
@@ -224,6 +257,7 @@ async function cloudFetch(urlPath, options = {}, token = null) {
   }
 
   // Primary response is fine — return a synthetic Response with the buffered text
+  activeCloudUrl = primaryUrl;
   return syntheticResponse(text, res.status);
 }
 
@@ -330,7 +364,7 @@ function openBrowser(url) {
   const platform = process.platform;
   const cmd = platform === 'darwin' ? 'open'
     : platform === 'win32' ? 'start'
-    : 'xdg-open';
+      : 'xdg-open';
   exec(`${cmd} "${url}"`);
 }
 
@@ -459,7 +493,7 @@ async function runLoginFlow({ jsonMode = false } = {}) {
     if (data.pending) continue;
 
     if (data.token) {
-      writeCredentials(data.token, getCloudUrl());
+      writeCredentials(data.token, activeCloudUrl || getCloudUrl());
       log('  ✓ Logged in successfully\n');
       return data.token;
     }
@@ -477,7 +511,7 @@ async function runLoginFlow({ jsonMode = false } = {}) {
  */
 async function runLegacyLoginFlow() {
   const nonce = crypto.randomBytes(32).toString('hex');
-  const cloudUrl = getCloudUrl();
+  const initialCloudUrl = getCloudUrl();
 
   console.log('  → Registering session...');
   const createRes = await cloudFetch('/api/auth/connect', {
@@ -493,7 +527,8 @@ async function runLegacyLoginFlow() {
     process.exit(1);
   }
 
-  const loginUrl = `${cloudUrl}/auth/connect?session=${nonce}`;
+  const effectiveCloudUrl = activeCloudUrl || initialCloudUrl;
+  const loginUrl = `${effectiveCloudUrl}/auth/connect?session=${nonce}`;
   console.log('  → Opening browser for authentication...');
   openBrowser(loginUrl);
 
@@ -514,7 +549,7 @@ async function runLegacyLoginFlow() {
     if (data.pending) continue;
 
     if (data.token) {
-      writeCredentials(data.token, cloudUrl);
+      writeCredentials(data.token, activeCloudUrl || initialCloudUrl);
       console.log('  ✓ Logged in successfully');
       return data.token;
     }
@@ -552,22 +587,21 @@ export async function ensureAuthenticated() {
  * Returns { orgId, courseId, orgName } or prompts the user.
  */
 async function resolveOrgAndCourse(slug, token) {
-  // 1. Check .coursecoderc.json for cloudId (committed, shared across team)
+  // Shared binding (committed): cloudId in .coursecoderc.json.
+  // Local binding (per-user): orgId/courseId in .coursecode/project.json.
+  // This keeps login global while allowing per-course auth context.
   const rcConfig = readRcConfig();
-  if (rcConfig?.cloudId) {
-    // Still need orgId from local project.json if available
-    const projectConfig = readProjectConfig();
-    if (projectConfig?.orgId) {
-      return { orgId: projectConfig.orgId, courseId: rcConfig.cloudId };
-    }
-    // Have cloudId but no orgId — fall through to API resolution
-    // which will match on courseId
+  const projectConfig = readProjectConfig();
+  const rcCloudId = rcConfig?.cloudId;
+  const localOrgId = projectConfig?.orgId;
+  const localCourseId = projectConfig?.courseId;
+
+  if (rcCloudId && localOrgId) {
+    return { orgId: localOrgId, courseId: rcCloudId };
   }
 
-  // 2. Check cached project config (gitignored, per-developer)
-  const projectConfig = readProjectConfig();
-  if (projectConfig?.orgId && projectConfig?.courseId) {
-    return { orgId: projectConfig.orgId, courseId: projectConfig.courseId };
+  if (localOrgId && localCourseId) {
+    return { orgId: localOrgId, courseId: localCourseId };
   }
 
   // Call resolve endpoint
@@ -576,8 +610,8 @@ async function resolveOrgAndCourse(slug, token) {
 
   // Found in exactly one org
   if (data.found) {
-    const binding = { orgId: data.orgId, courseId: data.courseId, slug };
-    writeProjectConfig(binding);
+    writeProjectConfig({ slug, orgId: data.orgId, courseId: data.courseId });
+    writeRcConfig({ cloudId: data.courseId, orgId: data.orgId });
     return { orgId: data.orgId, courseId: data.courseId, orgName: data.orgName };
   }
 
@@ -594,8 +628,8 @@ async function resolveOrgAndCourse(slug, token) {
       process.exit(1);
     }
     const match = data.matches[idx];
-    const binding = { orgId: match.orgId, courseId: match.courseId, slug };
-    writeProjectConfig(binding);
+    writeProjectConfig({ slug, orgId: match.orgId, courseId: match.courseId });
+    writeRcConfig({ cloudId: match.courseId, orgId: match.orgId });
     return { orgId: match.orgId, courseId: match.courseId, orgName: match.orgName };
   }
 
@@ -675,16 +709,16 @@ export async function login(options = {}) {
 }
 
 /**
- * coursecode logout — delete credentials and local project.json
+ * coursecode logout — delete Cloud credentials
  */
-export async function logout() {
+export async function logout(options = {}) {
   deleteCredentials();
 
-  // Also delete local project.json if it exists
-  const localConfig = path.join(process.cwd(), PROJECT_CONFIG_PATH);
-  try { fs.unlinkSync(localConfig); } catch { /* not there */ }
-
-  console.log('\n✓ Logged out of CourseCode Cloud.\n');
+  if (options.json) {
+    process.stdout.write(JSON.stringify({ success: true }) + '\n');
+  } else {
+    console.log('\n✓ Logged out of CourseCode Cloud.\n');
+  }
 }
 
 /**
@@ -719,7 +753,7 @@ export async function whoami(options = {}) {
 /**
  * coursecode courses — list courses across all orgs
  */
-export async function listCourses() {
+export async function listCourses(options = {}) {
   await ensureAuthenticated();
 
   const makeRequest = async (_isRetry = false) => {
@@ -730,6 +764,11 @@ export async function listCourses() {
 
   const courses = await makeRequest();
 
+  if (options.json) {
+    process.stdout.write(JSON.stringify(courses) + '\n');
+    return;
+  }
+
   if (!courses.length) {
     console.log('\n  No courses found. Deploy one with: coursecode deploy\n');
     return;
@@ -763,8 +802,24 @@ export async function deploy(options = {}) {
 
   await ensureAuthenticated();
   const slug = resolveSlug();
+  const log = (...args) => { if (!options.json) console.log(...args); };
+  const logErr = (...args) => { if (!options.json) console.error(...args); };
 
-  console.log('\n📦 Building...\n');
+  // Validate mutually exclusive flags
+  if (options.promote && options.stage) {
+    logErr('\n❌ --promote and --stage are mutually exclusive.\n');
+    if (options.json) process.stdout.write(JSON.stringify({ success: false, error: '--promote and --stage are mutually exclusive' }) + '\n');
+    process.exit(1);
+  }
+
+  // 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');
 
   // Step 1: Build
   const { build } = await import('./build.js');
@@ -773,7 +828,8 @@ export async function deploy(options = {}) {
   // Step 2: Verify dist/ exists
   const distPath = path.join(process.cwd(), 'dist');
   if (!fs.existsSync(distPath)) {
-    console.error('\n❌ Build did not produce a dist/ directory.\n');
+    logErr('\n❌ Build did not produce a dist/ directory.\n');
+    if (options.json) process.stdout.write(JSON.stringify({ success: false, error: 'Build did not produce a dist/ directory' }) + '\n');
     process.exit(1);
   }
 
@@ -786,13 +842,28 @@ export async function deploy(options = {}) {
   await zipDirectory(distPath, zipPath);
 
   // Step 5: Upload
-  const mode = options.preview ? 'preview' : 'production';
-  console.log(`\nDeploying ${slug}${displayOrg} as ${mode}...\n`);
+  let modeLabel;
+  if (previewOnly) {
+    modeLabel = 'preview only';
+  } else if (options.promote && options.preview) {
+    modeLabel = 'force-promote + preview';
+  } else if (options.stage && options.preview) {
+    modeLabel = 'staged + preview';
+  } else if (options.promote) {
+    modeLabel = 'force-promote';
+  } else if (options.stage) {
+    modeLabel = 'staged';
+  } else {
+    modeLabel = 'production';
+  }
+  log(`\nDeploying ${slug}${displayOrg} [${modeLabel}]...\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));
 
   if (options.message) {
     formData.append('message', options.message);
@@ -803,7 +874,7 @@ export async function deploy(options = {}) {
     formData.append('password', pw);
   }
 
-  const queryString = options.preview ? '?mode=preview' : '';
+  const queryString = previewOnly ? '?mode=preview' : '';
 
   const makeRequest = async (_isRetry = false) => {
     const token = readCredentials()?.token;
@@ -817,29 +888,34 @@ export async function deploy(options = {}) {
 
   const result = await makeRequest();
 
-  // Step 6: Write project.json + stamp cloudId
+  // Step 6: Persist per-user binding and stamp cloud identity into .coursecoderc.json
   const finalCourseId = result.courseId || courseId;
-  writeProjectConfig({
+  writeProjectConfig({ slug, orgId: result.orgId || orgId, courseId: finalCourseId });
+  writeRcConfig({
+    cloudId: finalCourseId,
     orgId: result.orgId || orgId,
-    courseId: finalCourseId,
-    slug,
   });
 
-  // Stamp cloudId into .coursecoderc.json (committed, shared with team)
-  const rc = readRcConfig();
-  if (finalCourseId && (!rc || rc.cloudId !== finalCourseId)) {
-    writeRcCloudId(finalCourseId);
-  }
-
   // Step 7: Display result
-  if (result.mode === 'preview') {
+  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(`  URL: ${result.url}`);
-    if (result.expiresAt) console.log(`  Expires: ${formatDate(result.expiresAt)}`);
+    console.log(`  Preview URL: ${result.url}`);
+    console.log(`  Dashboard:   ${result.dashboardUrl}`);
   } else {
-    console.log(`✓ Deployed to production (${result.fileCount} files, ${formatBytes(result.size)})`);
-    const cloudUrl = getCloudUrl();
-    console.log(`  ${cloudUrl}/dashboard/courses/${result.courseId}`);
+    const prodTag = result.promoted ? 'live' : 'staged';
+    const previewTag = result.previewPromoted ? ' + preview' : '';
+    console.log(`✓ Deployed (${result.fileCount} files) — ${prodTag}${previewTag}`);
+    if (!result.promoted) {
+      console.log(`  Production pointer not updated. Promote from Deploy History or run:`);
+      console.log(`  coursecode promote --production`);
+    }
+    if (result.previewPromoted) {
+      console.log(`  Preview pointer updated.`);
+    }
+    console.log(`  Dashboard: ${result.dashboardUrl}`);
   }
   console.log('');
 
@@ -847,15 +923,109 @@ export async function deploy(options = {}) {
   try { fs.unlinkSync(zipPath); } catch { /* fine */ }
 }
 
+/**
+ * coursecode promote — promote a deployment to production or preview
+ */
+export async function promote(options = {}) {
+  await ensureAuthenticated();
+  const slug = resolveSlug();
+  const rcConfig = readRcConfig();
+
+  // Validate target flag
+  if (!options.production && !options.preview) {
+    console.error('\n❌ Specify a target: --production or --preview\n');
+    process.exit(1);
+  }
+  if (options.production && options.preview) {
+    console.error('\n❌ Specify only one target: --production or --preview\n');
+    process.exit(1);
+  }
+  const target = options.production ? 'production' : 'preview';
+
+  // Resolve deployment ID interactively if not provided
+  let deploymentId = options.deployment;
+  if (!deploymentId) {
+    const orgQuery = rcConfig?.orgId ? `?orgId=${rcConfig.orgId}` : '';
+    const makeVersionsRequest = async (_isRetry = false) => {
+      const token = readCredentials()?.token;
+      const res = await cloudFetch(
+        `/api/cli/courses/${encodeURIComponent(slug)}/versions${orgQuery}`,
+        {},
+        token
+      );
+      return handleResponse(res, { retryFn: makeVersionsRequest, _isRetry });
+    };
+    const data = await makeVersionsRequest();
+    const deployments = data.deployments ?? [];
+
+    if (deployments.length === 0) {
+      console.error('\n❌ No deployments found for this course.\n');
+      process.exit(1);
+    }
+
+    console.log(`\n  Deployments for ${slug}:\n`);
+    deployments.slice(0, 10).forEach((d, i) => {
+      const marker = d.id === data.production_deployment_id
+        ? ' [production]'
+        : d.id === data.preview_deployment_id
+          ? ' [preview]'
+          : '';
+      console.log(`    ${i + 1}. ${new Date(d.created_at).toLocaleString()} — ${d.file_count} files${marker}`);
+    });
+
+    const answer = await prompt('\n  Which deployment to promote? ');
+    const idx = parseInt(answer, 10) - 1;
+    if (idx < 0 || idx >= deployments.length) {
+      console.error('\n❌ Invalid selection.\n');
+      process.exit(1);
+    }
+    deploymentId = deployments[idx].id;
+  }
+
+  const reason = options.message || `Promoted to ${target} via CLI`;
+
+  const makeRequest = async (_isRetry = false) => {
+    const token = readCredentials()?.token;
+    const res = await cloudFetch(
+      `/api/cli/courses/${encodeURIComponent(slug)}/promote`,
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ deployment_id: deploymentId, target, reason }),
+      },
+      token
+    );
+    return handleResponse(res, { retryFn: makeRequest, _isRetry });
+  };
+
+  const result = await makeRequest();
+
+  if (options.json) {
+    process.stdout.write(JSON.stringify({ success: true, ...result }) + '\n');
+    return;
+  }
+
+  if (result.already_promoted) {
+    console.log(`\n  Already the active ${target} deployment. Nothing to do.\n`);
+    return;
+  }
+
+  console.log(`\n✓ Promoted to ${target}`);
+  if (result.url) {
+    console.log(`  Preview URL: ${result.url}`);
+  }
+  console.log('');
+}
+
 /**
  * coursecode status — show deployment status for current course
  */
-export async function status() {
+export async function status(options = {}) {
   await ensureAuthenticated();
   const slug = resolveSlug();
 
-  const projectConfig = readProjectConfig();
-  const orgQuery = projectConfig?.orgId ? `?orgId=${projectConfig.orgId}` : '';
+  const rcConfig = readRcConfig();
+  const orgQuery = rcConfig?.orgId ? `?orgId=${rcConfig.orgId}` : '';
 
   const makeRequest = async (_isRetry = false) => {
     const token = readCredentials()?.token;
@@ -869,8 +1039,20 @@ export async function status() {
 
   const data = await makeRequest();
 
+  if (options.json) {
+    process.stdout.write(JSON.stringify(data) + '\n');
+    return;
+  }
+
   console.log(`\n${data.slug} — ${data.name} (${data.orgName})\n`);
 
+  if (data.source_type === 'github' && data.github_repo) {
+    console.log(`Source:         GitHub — ${data.github_repo}`);
+    console.log(`                (changes deploy via GitHub, not direct upload)`);
+  } else if (data.source_type) {
+    console.log(`Source:         ${data.source_type}`);
+  }
+
   if (data.lastDeploy) {
     console.log(`Last deploy:    ${formatDate(data.lastDeploy)} (${data.lastDeployFileCount} files, ${formatBytes(data.lastDeploySize)})`);
   } else {
@@ -888,6 +1070,74 @@ export async function status() {
   console.log('');
 }
 
+/**
+ * coursecode delete — remove course record from CourseCode Cloud.
+ *
+ * Cloud-only: this command does not delete local files. CLI users can remove
+ * their project directory themselves; the Desktop handles local deletion via
+ * shell.trashItem after calling this command.
+ *
+ * Response includes source_type + github_repo so callers can warn the user
+ * when the deleted course was GitHub-linked (repo is unaffected, integration
+ * is only disconnected on the Cloud side).
+ */
+export async function deleteCourse(options = {}) {
+  await ensureAuthenticated();
+  const slug = resolveSlug();
+  const log = (...args) => { if (!options.json) console.log(...args); };
+
+  const rcConfig = readRcConfig();
+  if (!rcConfig?.cloudId) {
+    if (options.json) {
+      process.stdout.write(JSON.stringify({ success: false, error: 'Course has not been deployed to Cloud. Nothing to delete.' }) + '\n');
+    } else {
+      console.error('\n❌ Course has not been deployed to Cloud. Nothing to delete.\n');
+    }
+    process.exit(1);
+  }
+
+  const orgQuery = rcConfig?.orgId ? `?orgId=${rcConfig.orgId}` : '';
+
+  if (!options.force && !options.json) {
+    const answer = await prompt(`\n  Delete "${slug}" from CourseCode Cloud? This cannot be undone. [y/N] `);
+    if (answer.toLowerCase() !== 'y') {
+      console.log('  Cancelled.\n');
+      process.exit(0);
+    }
+  }
+
+  log(`\nDeleting ${slug} from Cloud...\n`);
+
+  const makeRequest = async (_isRetry = false) => {
+    const token = readCredentials()?.token;
+    const res = await cloudFetch(
+      `/api/cli/courses/${encodeURIComponent(slug)}${orgQuery}`,
+      {
+        method: 'DELETE',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ cloudId: rcConfig.cloudId }),
+      },
+      token
+    );
+    return handleResponse(res, { retryFn: makeRequest, _isRetry });
+  };
+
+  const result = await makeRequest();
+
+  if (options.json) {
+    process.stdout.write(JSON.stringify({ success: true, ...result }) + '\n');
+    return;
+  }
+
+  console.log(`✓ "${slug}" deleted from CourseCode Cloud.`);
+  if (result.source_type === 'github' && result.github_repo) {
+    console.log(`\n  ⚠️  This course was linked to GitHub (${result.github_repo}).`);
+    console.log(`     The GitHub integration has been disconnected.`);
+    console.log(`     Your repository and its files are unaffected.`);
+  }
+  console.log('');
+}
+
 // =============================================================================
 // ZIP HELPER
 // =============================================================================

package/lib/convert.js

@@ -18,7 +18,8 @@ export async function convert(source, options) {
         format = 'all',
         dryRun = false,
         overwrite = false,
-        flatten = false
+        flatten = false,
+        pdfJson = false
     } = options;
 
     console.log('\n📄 Converting documents to markdown...\n');
@@ -111,8 +112,8 @@ export async function convert(source, options) {
             // Write output
             await fs.writeFile(outputFile, result.markdown, 'utf-8');
 
-            // Write structured data if available (for AI analysis)
-            if (result.data) {
+            // PDF structure sidecar is optional because it is much larger/token-heavier than markdown.
+            if (result.data && pdfJson) {
                 const jsonPath = outputFile.replace(/\.md$/, '.json');
                 await fs.writeFile(jsonPath, JSON.stringify(result.data, null, 2), 'utf-8');
             }

package/lib/stub-player/lms-api.js

@@ -9,7 +9,7 @@
  * Enforces real LMS behavior — lifecycle violations return 'false' with proper
  * error codes, read-only elements reject SetValue, and format-specific rules
  * are enforced. This catches bugs that silently pass in dev but explode in
- * production LMSs like SCORM Cloud, Moodle, Cornerstone, etc.
+ * production SCORM/cmi5/LTI environments and LMSs like Moodle or Cornerstone.
  */
 
 const isBrowser = typeof window !== 'undefined';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coursecode",
-  "version": "0.1.10",
+  "version": "0.1.13",
   "description": "Multi-format course authoring framework with CLI tools (SCORM 2004, SCORM 1.2, cmi5, LTI 1.3)",
   "type": "module",
   "bin": {
@@ -125,4 +125,4 @@
     "vite-plugin-static-copy": "^3.1.4",
     "vitest": "^4.0.18"
   }
-}
+}