coursecode 0.1.19 → 0.1.21

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. Flags: `--promote` (force live), `--stage` (force staged), `--preview` (preview-only: production untouched, preview always moved), `--repair-binding` (clear stale local cloud binding first if the remote course was deleted). `--promote`/`--stage` are mutually exclusive; `--preview` stacks with either. |
+| `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), `--repair-binding` (clear stale local cloud binding first if the remote course was deleted). `--promote`/`--stage` are mutually exclusive; `--preview` stacks with either. **GitHub-linked courses**: production deploy blocked; only `--preview` allowed (see GitHub Source Guard below). |
 
 The ZIP never includes preview/stub player assets. Preview is a separate concern (see below).
 
@@ -610,6 +610,20 @@ User: coursecode build → uploads dist/
 
 **Security boundary:** The cloud never executes `course-config.js` or any user-authored JavaScript. The meta tag and manifest are the only format-specific artifacts, and both are generated from trusted framework source code.
 
+#### GitHub Source Guard
+
+Courses linked to GitHub for production deploys are protected from accidental CLI overwrites via two layers:
+
+| Layer | Mechanism | Key |
+|-------|-----------|-----|
+| **CLI (local)** | `deploy()` reads `sourceType` from `.coursecoderc.json` | Fast fail before build — no wasted time |
+| **Server (safety net)** | Deploy endpoint rejects non-preview uploads for `source_type = 'github'` | Can't bypass via old CLI or `curl` |
+
+- **`--preview` always allowed** — useful for testing without touching production pointer
+- **`.coursecoderc.json`** carries `sourceType` and `githubRepo` (committed to repo by cloud's GitHub integration), so anyone cloning gets the guard automatically
+- **Self-healing on unlink:** If the cloud course is unlinked from GitHub, both `status()` and `deploy()` reconcile — they detect the server no longer reports `source_type: 'github'` and clear the local `sourceType`/`githubRepo` from `.coursecoderc.json`. No manual cleanup or repo commit needed.
+- CLI error code: `github_source_blocked` (structured JSON for Desktop/CI consumers)
+
 ---
 
 ## Course Validation

package/framework/docs/USER_GUIDE.md

@@ -740,6 +740,7 @@ Open the URL in any browser, log in with your CourseCode account, and enter the
 - **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.
+- **GitHub-linked courses:** If your course is connected to a GitHub repo in the Cloud dashboard, production deploys happen via `git push` — the CLI blocks direct production uploads. Use `coursecode deploy --preview` to push a preview build for stakeholder review.
 - If a cloud deployment was deleted outside the CLI and this project still has the old local binding, rerun with `coursecode deploy --repair-binding`. To clear the stale binding without deploying yet, run `coursecode status --repair-binding`.
 
 **Typical Cloud workflow:**

package/lib/cloud.js

@@ -982,6 +982,45 @@ export async function deploy(options = {}) {
       if (handled) return;
     } else if (!statusRes.ok) {
       await handleResponse(statusRes);
+    } else {
+      // Reconcile local sourceType with cloud truth (handles unlink-via-dashboard)
+      try {
+        const statusData = JSON.parse(await statusRes.text());
+        const serverSourceType = statusData.source?.type || statusData.source_type;
+        const localRc = readRcConfig();
+        if (localRc?.sourceType === 'github' && serverSourceType !== 'github') {
+          updateRcConfig((rc) => {
+            delete rc.sourceType;
+            delete rc.githubRepo;
+            return rc;
+          });
+          log('  ℹ️  GitHub link removed on Cloud — updated local config.\n');
+        }
+      } catch { /* non-critical — guard will use whatever rcConfig has */ }
+    }
+  }
+
+  // Block production deploys for GitHub-linked courses
+  const rcConfig = readRcConfig();
+  if (rcConfig?.sourceType === 'github') {
+    if (options.preview) {
+      log('  ℹ️  GitHub-linked course — deploying preview only.\n');
+    } else {
+      const repo = rcConfig.githubRepo || 'unknown';
+      logErr(`\n❌ This course deploys to production via GitHub, not CLI.`);
+      logErr(`   Repo: ${repo}`);
+      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: repo,
+          hint: 'Use --preview for preview deploys, or push to GitHub for production.',
+        }) + '\n');
+      }
+      process.exit(1);
     }
   }
 
@@ -1294,6 +1333,20 @@ export async function status(options = {}) {
 
   const data = await handleResponse(firstRes, { retryFn: makeRequest, _isRetry: false });
 
+  // Reconcile local sourceType with cloud truth (handles unlink-via-dashboard)
+  const localRc = readRcConfig();
+  const serverSourceType = data.source?.type || data.source_type;
+  if (localRc?.sourceType === 'github' && serverSourceType !== 'github') {
+    updateRcConfig((rc) => {
+      delete rc.sourceType;
+      delete rc.githubRepo;
+      return rc;
+    });
+    if (!options.json) {
+      console.log('  ℹ️  GitHub link removed on Cloud — updated local config.\n');
+    }
+  }
+
   if (options.json) {
     process.stdout.write(JSON.stringify(data) + '\n');
     return;
@@ -1301,14 +1354,13 @@ export async function status(options = {}) {
 
   console.log(`\n${data.slug} — ${data.name} (${data.orgName})\n`);
 
-  if (data.source?.type === 'github' && data.source?.githubRepo) {
-    console.log(`Source:         GitHub — ${data.source.githubRepo}`);
-    console.log('                direct production deploy disabled; preview deploy allowed');
-  } else 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}`);
+  const sourceType = data.source?.type || data.source_type;
+  const githubRepo = data.source?.githubRepo || data.github_repo;
+  if (sourceType === 'github' && githubRepo) {
+    console.log(`Source:         GitHub — ${githubRepo}`);
+    console.log('                production=github | preview=cli+github');
+  } else if (sourceType) {
+    console.log(`Source:         ${sourceType}`);
   }
 
   if (data.courseId) console.log(`Course ID:      ${data.courseId}`);

package/package.json

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