coursecode 0.1.0 → 0.1.2

package/README.md

@@ -6,18 +6,20 @@ Drop in your existing PDFs, Word docs, or PowerPoints — AI converts them into
 
 ## Features
 
-- 🔌 **MCP integration**: AI connects directly to your course — previews, screenshots, linting, and testing without manual file sharing
-- 🎓 **Full LMS integration**: SCORM 1.2, SCORM 2004, cmi5, and LTI with complete tracking records
-- 🤖 **AI-ready authoring**: Structured guides and MCP tools for AI-assisted course development
-- 🧩 **Rich UI components**: Images, video, accordions, tabs, and custom sandboxed HTML/JS embeds
-- 🎯 **Rich interactions**: Multiple choice, drag-drop, fill-in-the-blank, matching, sequencing, and more
-- ♿ **Fully accessible**: WCAG 2.1 AA compliant with dark mode, high contrast, and reduced motion
-- 🔊 **TTS audio narration**: Built-in player with AI text-to-speech generation (ElevenLabs, Deepgram, Google, BYO API Key)
-- 📊 **Smart tracking**: Engagement requirements, learning objectives, and progress persistence
-- 🎨 **Themeable design**: CSS custom properties for easy brand customization
-- 🔗 **Custom endpoints**: Optional webhooks for error reporting and learning record storage
-- 📥 **Drop-in content conversion**: Feed existing PDFs, Word docs, or PowerPoint files to AI and get a complete, interactive course
-- 🖥️ **Live preview**: Visual editing, status dashboard, config panels, catalog browser, and full LMS simulation with debug tools
+- **MCP integration**: AI connects directly to your course — previews, screenshots, linting, and testing without manual file sharing
+- **Full LMS integration**: SCORM 1.2, SCORM 2004, cmi5, and LTI with complete tracking records
+- **AI-ready authoring**: Structured guides and MCP tools for AI-assisted course development
+- **Rich UI components**: Images, video, accordions, tabs, and custom sandboxed HTML/JS embeds
+- **Rich interactions**: Multiple choice, drag-drop, fill-in-the-blank, matching, sequencing, and more
+- **Fully accessible**: WCAG 2.1 AA compliant with dark mode, high contrast, and reduced motion
+- **TTS audio narration**: Built-in player with AI text-to-speech generation (ElevenLabs, Deepgram, Google, BYO API Key)
+- **Smart tracking**: Engagement requirements, learning objectives, and progress persistence
+- **Themeable design**: CSS custom properties for easy brand customization
+- **Custom endpoints**: Optional webhooks for error reporting and learning record storage
+- **Drop-in content conversion**: Feed existing PDFs, Word docs, or PowerPoint files to AI and get a complete, interactive course
+- **Live preview**: Visual editing, status dashboard, config panels, catalog browser, and full LMS simulation with debug tools
+- **[CourseCode Cloud](https://www.coursecodecloud.com)** *(coming soon)*: Deploy from CLI, share preview links, download any LMS format on demand — no rebuilds
+- **CourseCode Desktop** *(coming soon)*: Native app for Mac and Windows with AI-assisted editing, built-in preview, and no code required
 
 ---
 
@@ -55,7 +57,7 @@ Open `http://localhost:4173` to view and edit your course.
 
 The example course included with every new project is a complete guide to using CourseCode.
 
-📖 **New to CourseCode?** Read the [User Guide](framework/docs/USER_GUIDE.md) for step-by-step instructions.
+**New to CourseCode?** Read the [User Guide](framework/docs/USER_GUIDE.md) for step-by-step instructions.
 
 ---
 
@@ -93,8 +95,8 @@ my-course/
 │   ├── assets/                 # Images, audio, video
 │   │   ├── images/
 │   │   └── audio/
-│   ├── theme.css               # Brand customization
-
+│   └── theme.css               # Brand customization
+│
 ├── framework/                  # Framework code (don't edit)
 │   └── docs/                   # Guides and templates
 ```
@@ -114,11 +116,11 @@ All guides are in `framework/docs/`:
 
 | Document | Audience | Purpose |
 |----------|----------|---------|
-| `README.md` | Humans | Project overview and getting started |
 | `USER_GUIDE.md` | Humans | Complete guide — workflows, features, deployment |
 | `COURSE_AUTHORING_GUIDE.md` | AI Agents | Slide authoring, interactions, CSS styling |
 | `COURSE_OUTLINE_GUIDE.md` | AI Agents | How to write effective course outlines |
 | `COURSE_OUTLINE_TEMPLATE.md` | AI Agents | Blank template to start an outline |
+| `DATA_MODEL.md` | AI Agents | LMS data model and tracking fields |
 | `FRAMEWORK_GUIDE.md` | AI Agents | Framework internals (advanced) |
 
 ---
@@ -167,22 +169,26 @@ The preview server provides:
 - **Component catalog**: Browse available UI elements with live previews
 - **Debug tools**: Inspect LMS state, test interactions, verify tracking
 
-When ready, build and deploy:
+When ready, deploy:
+
+**With [CourseCode Cloud](https://www.coursecodecloud.com)** *(coming soon)*: Push your course and get a live link. Cloud handles hosting, generates any LMS format on demand, and gives you sharable preview links with optional password protection. No ZIP files, no manual uploads.
 
 ```bash
-coursecode build
+coursecode deploy
 ```
 
-This creates a ZIP package ready for upload to any LMS.
+**Without Cloud**: Build a ZIP package and upload it to your LMS manually:
+
+```bash
+coursecode build
+```
 
-**Share for review:** Export a standalone preview for stakeholders:
+**Share for review**: Export a standalone preview for stakeholders. Deploy to GitHub Pages, Netlify, or any static host:
 
 ```bash
 coursecode preview --export
 ```
 
-Deploy to GitHub Pages, Netlify, or any static host. Optional password protection keeps content secure.
-
 ---
 
 ## CLI Commands
@@ -194,10 +200,22 @@ Deploy to GitHub Pages, Netlify, or any static host. Optional password protectio
 | `coursecode build` | Build course package (ZIP for LMS upload) |
 | `coursecode build --format scorm1.2` | Build for specific LMS format |
 | `coursecode mcp` | Start the MCP server for AI integration |
+| `coursecode lint` | Validate course configuration and structure |
 | `coursecode narration` | Generate audio narration from text |
 | `coursecode convert` | Convert PDFs, Word, PowerPoint to markdown |
 | `coursecode upgrade` | Upgrade to latest version |
 
+### Cloud Commands
+
+| Command | Description |
+|---------|-------------|
+| `coursecode login` | Log in to CourseCode Cloud |
+| `coursecode logout` | Log out of CourseCode Cloud |
+| `coursecode whoami` | Show current Cloud user and organizations |
+| `coursecode courses` | List courses on CourseCode Cloud |
+| `coursecode deploy` | Build and deploy to CourseCode Cloud |
+| `coursecode status` | Show deployment status for current course |
+
 ### Output Format Options
 
 ```bash

package/framework/docs/FRAMEWORK_GUIDE.md

@@ -130,18 +130,17 @@ The ZIP never includes preview/stub player assets. Preview is a separate concern
 
 #### Re-Stamping for Different Formats
 
-`lib/build-packaging.js` exports `stampFormatInHtml(htmlPath, format)` for re-stamping the meta tag:
+`lib/build-packaging.js` exports `stampFormat(html, format)` for re-stamping the meta tag:
 
 ```javascript
-import { stampFormatInHtml } from 'coursecode/build-packaging';
+import { stampFormat } from 'coursecode/build-packaging';
 import { generateManifest } from 'coursecode/manifest';
 
-// Re-stamp dist/index.html for a different format
-stampFormatInHtml('/path/to/dist/index.html', 'scorm2004');
+// Re-stamp HTML string for a different format (no filesystem needed)
+const stampedHtml = stampFormat(indexHtml, 'scorm2004');
 
 // Generate the format-specific manifest
 const { filename, content } = generateManifest('scorm2004', config, files, options);
-fs.writeFileSync(`/path/to/dist/${filename}`, content);
 ```
 
 Both are pure Node utilities
@@ -152,7 +151,7 @@ Both are pure Node utilities
 |------|---------|
 | `framework/js/state/lms-connection.js` | `getLMSFormat()` — runtime priority chain (meta → env → default) |
 | `framework/js/drivers/driver-factory.js` | Dynamic `import()` switch — loads one driver at runtime |
-| `lib/build-packaging.js` | `stampFormatInHtml()` — meta tag re-stamping utility |
+| `lib/build-packaging.js` | `stampFormat()` — pure string meta tag re-stamping; `stampFormatInHtml()` — file-based wrapper |
 | `lib/manifest/manifest-factory.js` | `generateManifest()` — generates format-specific manifests |
 | Both `vite.config.js` files | Post-build `closeBundle` hook stamps meta tag into `dist/index.html` |
 
@@ -586,7 +585,7 @@ User: coursecode build → uploads dist/
     └────────────┘
 ```
 
-**Cloud dependencies:** The cloud app imports `stampFormatInHtml` and `generateManifest` directly from the `coursecode` npm package. These are pure Node utilities — no Vite, no dynamic imports of user code, no `eval`. All inputs (title, version, file list) come from scanning the uploaded `dist/` or the cloud's own database.
+**Cloud dependencies:** The cloud app imports `stampFormat` and `generateManifest` directly from the `coursecode` npm package. These are pure functions — no filesystem, no Vite, no dynamic imports of user code, no `eval`. All inputs (title, version, file list) come from scanning the uploaded `dist/` or the cloud's own database.
 
 **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.
 ---

package/lib/build-packaging.d.ts

@@ -0,0 +1,33 @@
+export function stampFormat(html: string, format: string): string
+export function stampFormatInHtml(htmlPath: string, format: string): void
+
+export function validateExternalHostingConfig(config: Record<string, unknown>): void
+
+export function createStandardPackage(options: {
+  rootDir: string
+  distDir: string
+  config: Record<string, unknown>
+  outputDir?: string
+}): Promise<string>
+
+export function createProxyPackage(options: {
+  rootDir: string
+  config: Record<string, unknown>
+  clientId?: string
+  token?: string
+  outputDir?: string
+}): Promise<string>
+
+export function createRemotePackage(options: {
+  rootDir: string
+  config: Record<string, unknown>
+  clientId?: string
+  token?: string
+  outputDir?: string
+}): Promise<string>
+
+export function createExternalPackagesForClients(options: {
+  rootDir: string
+  config: Record<string, unknown>
+  outputDir?: string
+}): Promise<void>

package/lib/build-packaging.js

@@ -61,24 +61,31 @@ export function validateExternalHostingConfig(config) {
 }
 
 /**
- * Re-stamp the lms-format meta tag in an index.html file.
- * Used when creating format-specific ZIPs from a universal dist/.
- * @param {string} htmlPath - Absolute path to the index.html to modify
+ * Re-stamp the lms-format meta tag in an HTML string.
+ * Pure string transform — no filesystem access. Use this in cloud/serverless environments.
+ * @param {string} html - The HTML string to modify
  * @param {string} format - The LMS format to stamp (e.g., 'scorm2004', 'cmi5')
+ * @returns {string} The modified HTML string
  */
-export function stampFormatInHtml(htmlPath, format) {
-    let html = fs.readFileSync(htmlPath, 'utf-8');
-    // Replace existing meta tag or insert after charset
+export function stampFormat(html, format) {
     const existingMeta = /<meta\s+name="lms-format"\s+content="[^"]*"\s*\/?>/;
     if (existingMeta.test(html)) {
-        html = html.replace(existingMeta, `<meta name="lms-format" content="${format}" />`);
-    } else {
-        html = html.replace(
-            '<meta charset="UTF-8" />',
-            `<meta charset="UTF-8" />\n  <meta name="lms-format" content="${format}" />`
-        );
+        return html.replace(existingMeta, `<meta name="lms-format" content="${format}" />`);
     }
-    fs.writeFileSync(htmlPath, html, 'utf-8');
+    return html.replace(
+        '<meta charset="UTF-8" />',
+        `<meta charset="UTF-8" />\n  <meta name="lms-format" content="${format}" />`
+    );
+}
+
+/**
+ * Re-stamp the lms-format meta tag in an index.html file on disk.
+ * @param {string} htmlPath - Absolute path to the index.html to modify
+ * @param {string} format - The LMS format to stamp (e.g., 'scorm2004', 'cmi5')
+ */
+export function stampFormatInHtml(htmlPath, format) {
+    const html = fs.readFileSync(htmlPath, 'utf-8');
+    fs.writeFileSync(htmlPath, stampFormat(html, format), 'utf-8');
 }
 
 export async function createStandardPackage({ rootDir, distDir, config, outputDir }) {

package/lib/index.d.ts

@@ -0,0 +1,52 @@
+// Stub Player
+export { generateStubPlayer } from './stub-player.js'
+export type { StubPlayerConfig } from './stub-player.js'
+
+// Manifest Generation
+export function generateManifest(
+  format: string,
+  config: Record<string, unknown>,
+  files: string[],
+  options?: Record<string, unknown>
+): { filename: string; content: string }
+
+export function getSchemaFiles(format: string): string[]
+
+// Content Parsing
+export function parseCourse(coursePath: string): Promise<Record<string, unknown>>
+export function parseSlideSource(source: string, slideId: string): Record<string, unknown>
+export function extractAssessment(source: string, slideId: string): Record<string, unknown> | null
+export function extractNarration(source: string): Record<string, unknown> | null
+export function extractInteractions(content: string, slideId: string): Record<string, unknown>[]
+export function parseElements(html: string): Record<string, unknown>[]
+export function resolveElementByPath(elements: Record<string, unknown>[], targetPath: string): Record<string, unknown> | null
+
+// Build
+export function build(options?: Record<string, unknown>): Promise<void>
+
+// Build Packaging
+export function stampFormat(html: string, format: string): string
+export function stampFormatInHtml(htmlPath: string, format: string): void
+export function validateExternalHostingConfig(config: Record<string, unknown>): void
+export function createStandardPackage(options: Record<string, unknown>): Promise<string>
+export function createProxyPackage(options: Record<string, unknown>): Promise<string>
+export function createRemotePackage(options: Record<string, unknown>): Promise<string>
+export function createExternalPackagesForClients(options: Record<string, unknown>): Promise<void>
+
+// Build Linter
+export function lintCourse(courseConfig: Record<string, unknown>, coursePath: string): { errors: string[]; warnings: string[] }
+export function lint(options?: Record<string, unknown>): Promise<void>
+
+// Validation Rules
+export function flattenStructure(structure: unknown[]): unknown[]
+export function validateAssessmentConfig(...args: unknown[]): void
+export function validateQuestionConfig(...args: unknown[]): void
+export function validateEngagement(...args: unknown[]): void
+export function validateRequirementConfig(...args: unknown[]): void
+export function validateGlobalConfig(...args: unknown[]): { warnings: string[]; objectiveIds: Set<string> }
+export function formatLintResults(results: { errors: string[]; warnings: string[] }): string
+
+// Path utilities
+export function getTemplatePath(): string
+export function getFrameworkPath(): string
+export function getSchemasPath(): string

package/lib/index.js

@@ -24,6 +24,7 @@ export {
 // Build utilities
 export { build } from './build.js';
 export {
+  stampFormat,
   createStandardPackage,
   createProxyPackage,
   createRemotePackage,

package/lib/manifest/manifest-factory.d.ts

@@ -0,0 +1,10 @@
+export function generateManifest(
+  format: 'scorm2004' | 'scorm1.2' | 'cmi5' | 'scorm1.2-proxy' | 'scorm2004-proxy' | 'cmi5-remote' | 'lti',
+  config: Record<string, unknown>,
+  files: string[],
+  options?: { externalUrl?: string }
+): { filename: string; content: string }
+
+export function getSchemaFiles(
+  format: 'scorm2004' | 'scorm1.2' | 'cmi5' | 'lti'
+): string[]

package/lib/stub-player.d.ts

@@ -0,0 +1,15 @@
+export interface StubPlayerConfig {
+  title: string
+  launchUrl: string
+  storageKey: string
+  passwordHash?: string
+  isLive?: boolean
+  liveReload?: boolean
+  courseContent?: string
+  startSlide?: string | number
+  isDesktop?: boolean
+  moduleBasePath?: string
+}
+
+export function generateStubPlayer(config: StubPlayerConfig): string
+export function escapeHtml(str: string): string

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coursecode",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Multi-format course authoring framework with CLI tools (SCORM 2004, SCORM 1.2, cmi5, LTI 1.3)",
   "type": "module",
   "bin": {
@@ -20,12 +20,22 @@
     "THIRD_PARTY_NOTICES.md"
   ],
   "exports": {
-    ".": "./lib/index.js",
-    "./manifest": "./lib/manifest/manifest-factory.js",
-    "./build-packaging": "./lib/build-packaging.js",
-    "./stub-player": "./lib/stub-player.js",
-    "./course-parser": "./lib/course-parser.js",
-    "./vite-plugin-content-discovery": "./lib/vite-plugin-content-discovery.js"
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./manifest": {
+      "types": "./lib/manifest/manifest-factory.d.ts",
+      "default": "./lib/manifest/manifest-factory.js"
+    },
+    "./build-packaging": {
+      "types": "./lib/build-packaging.d.ts",
+      "default": "./lib/build-packaging.js"
+    },
+    "./stub-player": {
+      "types": "./lib/stub-player.d.ts",
+      "default": "./lib/stub-player.js"
+    }
   },
   "scripts": {
     "dev": "VITE_COURSECODE_LOCAL=true npx vite build --config vite.framework-dev.config.js --mode development --watch",