coursecode 0.1.54 → 0.1.55

package/README.md

@@ -235,7 +235,8 @@ coursecode preview --export
 
 | Command | Description |
 |---------|-------------|
-| `coursecode create <name>` | Create a new course project |
+| `coursecode create <name>` | Create a new course project; use `.` to initialize the current directory |
+| `coursecode init [name]` | Initialize the current directory, optionally with a course title |
 | `coursecode preview` | Preview your course locally |
 | `coursecode convert` | Convert PDFs, Word, PowerPoint to markdown |
 | `coursecode mcp` | Start the MCP server for AI integration |

package/bin/cli.js

@@ -5,6 +5,7 @@
  * 
  * Commands:
  *   coursecode create <name>  - Create a new course project
+ *   coursecode init [name]    - Initialize the current directory
  *   coursecode dev            - Start development server
  *   coursecode build          - Build course package
  *   coursecode upgrade        - Upgrade framework in current project
@@ -79,7 +80,7 @@ program
 // Create command
 program
   .command('create <name>')
-  .description('Create a new course project')
+  .description('Create a new course project (use "." for the current directory)')
   .option('--blank', 'Create without example slides (clean starter)')
   .option('--no-install', 'Skip npm install')
   .option('--start', 'Auto-start dev server after creation (skip prompt)')
@@ -88,6 +89,17 @@ program
     await create(name, options);
   });
 
+program
+  .command('init [name]')
+  .description('Initialize the current directory as a CourseCode project')
+  .option('--blank', 'Create without example content (clean starter)')
+  .option('--no-install', 'Skip npm install')
+  .option('--start', 'Auto-start dev server after creation (skip prompt)')
+  .action(async (name, options) => {
+    const { create } = await import('../lib/create.js');
+    await create(name || path.basename(process.cwd()), { ...options, currentDirectory: true });
+  });
+
 // Dev command
 program
   .command('dev')

package/framework/docs/COURSE_AUTHORING_GUIDE.md

@@ -16,6 +16,8 @@
 |---------|-------------|
 | `coursecode create <name>` | Create a new course project (includes example slides) |
 | `coursecode create <name> --blank` | Create a blank project (no example content) |
+| `coursecode create .` | Initialize the current directory using its folder name as the course title |
+| `coursecode init [name]` | Initialize the current directory, optionally with a specific course title |
 | `coursecode clean` | Remove example files and reset config to minimal starter |
 | `coursecode new slide <id>` | Create a new slide file in `course/slides/` |
 | `coursecode new assessment <id>` | Create a new assessment file in `course/slides/` |
@@ -253,7 +255,7 @@ coursecode export-content --format json -o content.json
 3. **Create slide** in `course/slides/intro.js`:
    ```javascript
    export const slide = {
-     render(root, context) {
+     render(_root, _context) {
        const container = document.createElement('div');
        container.innerHTML = `<h1>Welcome</h1><p>Content here</p>`;
        return container;  // Must return a DOM element
@@ -261,6 +263,8 @@ coursecode export-content --format json -o content.json
    };
    ```
 
+   The first render argument is reserved and currently receives `null`. Keep it as `_root` for API compatibility. Create and return a new root `HTMLElement`; use the second argument only when the slide needs navigation or assessment context.
+
    > **⚠️ No import statements.** Components, interactions, CSS classes, and icons are all globally available at runtime. The only valid `import` is for local assets (images, SVGs). Access framework APIs via `const { createXxxQuestion } = CourseCode;` (destructure from global, **not** an import).
 
 4. **Add styles** to `course/theme.css` (only for custom branding - use framework utility classes first, see CSS Quick Reference section below)

package/framework/docs/FRAMEWORK_GUIDE.md

@@ -310,7 +310,7 @@ Separates data, presentation, logic (used in `app/`, `navigation/`):
 
 - **Single ViewManager** in `main.js` controls slide navigation
 - **No caching** - views render fresh each `showView()` to prevent stale data
-- Slide signature: `render(root, context)` where `root` is framework-provided container
+- Slide signature: `render(_root, context)`. The first argument is reserved and currently `null`; slides create and return their own root `HTMLElement`. The second argument carries navigation/render context.
 - Components with sub-views (assessments) create own ViewManager
 
 ### Event Delegation

package/framework/version.json

@@ -1,8 +1,8 @@
 {
-  "version": "0.1.54",
+  "version": "0.1.55",
   "name": "CourseCode Framework",
   "description": "Multi-format course authoring and learner runtime framework",
-  "released": "2026-07-10",
+  "released": "2026-07-11",
   "formats": [
     "SCORM 2004 4th Edition",
     "SCORM 1.2",

package/lib/create.js

@@ -77,6 +77,42 @@ function copyDir(src, dest, options = {}) {
   }
 }
 
+function mergeProjectControlFile(sourcePath, destinationPath) {
+  const source = fs.readFileSync(sourcePath, 'utf-8').trimEnd();
+  if (!fs.existsSync(destinationPath)) {
+    fs.writeFileSync(destinationPath, `${source}\n`, 'utf-8');
+    return;
+  }
+
+  const current = fs.readFileSync(destinationPath, 'utf-8');
+  const existingLines = new Set(current.split(/\r?\n/).map(line => line.trim()));
+  const missingRules = source
+    .split(/\r?\n/)
+    .filter(line => line.trim() && !line.trim().startsWith('#') && !existingLines.has(line.trim()));
+
+  if (missingRules.length === 0) return;
+
+  const separator = current.endsWith('\n') ? '\n' : '\n\n';
+  fs.appendFileSync(
+    destinationPath,
+    `${separator}# CourseCode project defaults\n${missingRules.join('\n')}\n`,
+    'utf-8'
+  );
+}
+
+function assertCurrentDirectoryCanBeInitialized(targetDir, templateDir) {
+  const managedPaths = fs.readdirSync(templateDir)
+    .filter(name => !['.DS_Store', 'gitignore', 'gitattributes'].includes(name))
+    .concat(['framework', 'schemas', 'lib', '.coursecoderc.json']);
+  const conflicts = managedPaths.filter(name => fs.existsSync(path.join(targetDir, name)));
+
+  if (conflicts.length > 0) {
+    throw new Error(
+      `Cannot initialize the current directory because CourseCode-managed paths already exist: ${conflicts.join(', ')}`
+    );
+  }
+}
+
 /**
  * Run npm install in directory
  */
@@ -123,7 +159,10 @@ function gitInit(cwd) {
 }
 
 export async function create(name, options = {}) {
-  const displayName = String(name || '').trim();
+  const requestedName = String(name || '').trim();
+  const currentDirectory = options.currentDirectory === true || requestedName === '.';
+  const inferredName = path.basename(process.cwd()).replace(/[-_]+/g, ' ');
+  const displayName = currentDirectory && requestedName === '.' ? inferredName : requestedName;
   const directoryName = toProjectDirectoryName(displayName);
 
   if (!displayName) {
@@ -136,16 +175,18 @@ export async function create(name, options = {}) {
     process.exit(1);
   }
 
-  const targetDir = path.resolve(process.cwd(), directoryName);
+  const targetDir = currentDirectory ? path.resolve(process.cwd()) : path.resolve(process.cwd(), directoryName);
+  const templateDir = path.join(PACKAGE_ROOT, 'template');
 
-  // Check if directory already exists
-  if (fs.existsSync(targetDir)) {
+  if (currentDirectory) {
+    assertCurrentDirectoryCanBeInitialized(targetDir, templateDir);
+  } else if (fs.existsSync(targetDir)) {
     console.error(`\n❌ Directory "${directoryName}" already exists.\n`);
     process.exit(1);
   }
 
   console.log(`\n🚀 Creating CourseCode project: ${displayName}\n`);
-  if (directoryName !== displayName) {
+  if (!currentDirectory && directoryName !== displayName) {
     console.log(`   Project folder: ${directoryName}`);
   }
 
@@ -153,11 +194,12 @@ export async function create(name, options = {}) {
   fs.mkdirSync(targetDir, { recursive: true });
 
   // Copy template files (course directory and vite config)
-  const templateDir = path.join(PACKAGE_ROOT, 'template');
   console.log('   Copying template files...');
   copyDir(templateDir, targetDir, {
-    exclude: [/^\.DS_Store$/, /^node_modules$/]
+    exclude: [/^\.DS_Store$/, /^node_modules$/, /^gitignore$/, /^gitattributes$/]
   });
+  mergeProjectControlFile(path.join(templateDir, 'gitignore'), path.join(targetDir, '.gitignore'));
+  mergeProjectControlFile(path.join(templateDir, 'gitattributes'), path.join(targetDir, '.gitattributes'));
 
   // Copy framework
   const frameworkSrc = path.join(PACKAGE_ROOT, 'framework');
@@ -189,14 +231,19 @@ export async function create(name, options = {}) {
   console.log('   Copying proxy packaging templates...');
   copyDir(proxyTemplatesSrc, proxyTemplatesDest);
 
-  // Read and customize package.json
+  // Read and customize package.json. Pin the authoring/build CLI to the
+  // version that created the project so an isolated checkout can build.
+  const frameworkPkg = JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, 'package.json'), 'utf-8'));
   const pkgPath = path.join(targetDir, 'package.json');
   const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
   pkg.name = directoryName;
+  pkg.devDependencies = {
+    ...pkg.devDependencies,
+    coursecode: `^${frameworkPkg.version}`
+  };
   fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2));
 
   // Create .coursecoderc.json to track framework version
-  const frameworkPkg = JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, 'package.json'), 'utf-8'));
   const coursecoderc = {
     frameworkVersion: frameworkPkg.version,
     createdAt: new Date().toISOString(),
@@ -212,7 +259,7 @@ export async function create(name, options = {}) {
   // If --blank, remove example files and reset config
   if (options.blank) {
     const { clean } = await import('./scaffold.js');
-    clean({ basePath: targetDir });
+    clean({ basePath: targetDir, blank: true });
   }
 
   writeCourseTitle(targetDir, displayName);
@@ -229,12 +276,16 @@ export async function create(name, options = {}) {
   }
 
   // Initialize git repository
-  console.log('\n   Initializing git repository...');
-  try {
-    await gitInit(targetDir);
-    console.log('   ✅ Git repository initialized');
-  } catch (_error) {
-    console.warn('   ⚠️  Git init failed. You can run "git init" manually.');
+  if (fs.existsSync(path.join(targetDir, '.git'))) {
+    console.log('\n   ✅ Existing Git repository preserved');
+  } else {
+    console.log('\n   Initializing git repository...');
+    try {
+      await gitInit(targetDir);
+      console.log('   ✅ Git repository initialized');
+    } catch (_error) {
+      console.warn('   ⚠️  Git init failed. You can run "git init" manually.');
+    }
   }
 
   // Print success message
@@ -287,12 +338,14 @@ export async function create(name, options = {}) {
       console.log(`      cd ${directoryName} && coursecode dev\n`);
     });
   } else {
-    console.log(`\n   To start developing:\n\n      cd ${directoryName}\n      coursecode dev\n`);
+    const changeDirectory = currentDirectory ? '' : `cd ${directoryName}\n      `;
+    console.log(`\n   To start developing:\n\n      ${changeDirectory}coursecode dev\n`);
   }
 
   return {
     displayName,
     directoryName,
-    targetDir
+    targetDir,
+    currentDirectory
   };
 }

package/lib/scaffold.js

@@ -34,13 +34,24 @@ const MINIMAL_CONFIG = `export const courseConfig = {
 };
 `;
 
+const DEMO_ASSETS = [
+    'docs/example_md_1.md',
+    'docs/example_md_2.md',
+    'docs/example_pdf_1_thumbnail.png',
+    'docs/example_pdf_2.pdf',
+    'images/course-architecture.svg',
+    'images/logo.svg',
+    'widgets/counter-demo.html',
+    'widgets/gravity-painter.html'
+];
+
 /**
  * Minimal slide template
  */
 function slideTemplate(id) {
     const title = id.replace(/[-_]/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
     return `export const slide = {
-    render(root, context) {
+    render(_root, _context) {
         const container = document.createElement('div');
         container.innerHTML = \`
             <h1>${title}</h1>
@@ -83,9 +94,11 @@ const questions = [
 ];
 
 export const slide = {
-    render(root) {
-        const assessment = AssessmentManager.createAssessment(config, questions);
-        return assessment.render(root);
+    render(_root, context = {}) {
+        const container = document.createElement('div');
+        const assessment = AssessmentManager.createAssessment({ ...config, questions });
+        assessment.render(container, context);
+        return container;
     }
 };
 `;
@@ -128,6 +141,22 @@ export function clean(options = {}) {
         }
     }
 
+    // Remove the known demo documents, images, and widgets without touching
+    // any author-created assets that may already exist in the project.
+    const assetsDir = path.join(coursePath, 'assets');
+    for (const relativePath of DEMO_ASSETS) {
+        const assetPath = path.join(assetsDir, relativePath);
+        if (fs.existsSync(assetPath)) {
+            fs.rmSync(assetPath, { force: true });
+            removed++;
+        }
+    }
+
+    // A freshly blank scaffold must not inherit the example narration cache.
+    if (options.blank) {
+        fs.rmSync(path.join(basePath, '.narration-cache.json'), { force: true });
+    }
+
     // Rewrite course-config.js to minimal starter
     const configPath = path.join(coursePath, 'course-config.js');
     if (fs.existsSync(configPath)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coursecode",
-  "version": "0.1.54",
+  "version": "0.1.55",
   "description": "Multi-format course authoring framework with CLI tools (SCORM 2004, SCORM 1.2, cmi5, LTI 1.3)",
   "type": "module",
   "bin": {
@@ -14,7 +14,6 @@
     "!framework/dist/**",
     "schemas",
     "template",
-    "!template/.gitattributes",
     "!template/**/.gitkeep",
     "README.md",
     "THIRD_PARTY_NOTICES.md"
@@ -51,6 +50,7 @@
     "lint:responsive:structure": "node scripts/check-responsive-structure-scoping.mjs",
     "lint:fix": "eslint . --fix",
     "smoke:responsive": "node scripts/responsive-visual-smoke.mjs",
+    "smoke:packed-create": "node scripts/smoke-packed-create.mjs",
     "build": "npx vite build --config vite.framework-dev.config.js",
     "build:dev": "npx vite build --config vite.framework-dev.config.js",
     "build:scorm2004": "LMS_FORMAT=scorm2004 npx vite build --config vite.framework-dev.config.js",
@@ -69,7 +69,7 @@
     "test:cloud": "vitest run --config tests/vitest.cloud.config.js",
     "test:watch": "vitest --config tests/vitest.config.js",
     "test:coverage": "vitest run --config tests/vitest.config.js --coverage",
-    "prerelease:check": "npm run lint && npm run lint:responsive && npm run lint:responsive:structure && npm run test:coverage && npm run build",
+    "prerelease:check": "npm run lint && npm run lint:responsive && npm run lint:responsive:structure && npm run test:coverage && npm run build && npm run smoke:packed-create",
     "prerelease:check:full": "npm run prerelease:check && npm run test:e2e && npm run test:drivers && npm run smoke:responsive -- --profile=expanded",
     "prepublishOnly": "npm run prerelease:check"
   },

package/template/gitattributes

@@ -0,0 +1,44 @@
+# Auto detect text files and perform LF normalization
+* text=auto
+
+# Force LF line endings for text files
+*.js text eol=lf
+*.mjs text eol=lf
+*.cjs text eol=lf
+*.json text eol=lf
+*.css text eol=lf
+*.html text eol=lf
+*.htm text eol=lf
+*.xml text eol=lf
+*.xsd text eol=lf
+*.dtd text eol=lf
+*.md text eol=lf
+*.txt text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf
+*.env text eol=lf
+
+# Binary files
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.webp binary
+*.svg binary
+*.mp3 binary
+*.mp4 binary
+*.wav binary
+*.ogg binary
+*.webm binary
+*.woff binary
+*.woff2 binary
+*.ttf binary
+*.eot binary
+*.otf binary
+*.pdf binary
+*.zip binary
+
+# Linguist overrides for GitHub stats
+*.css linguist-detectable=false
+*.xsd linguist-detectable=false

package/template/gitignore

@@ -0,0 +1,38 @@
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+*.zip
+
+# Preview export (comment this line to include in repo for GitHub Pages deployment)
+course-preview/
+
+# Environment
+.env
+.env.local
+
+# Google Cloud service account credentials (NEVER commit these!)
+**/service-account*.json
+**/*-credentials.json
+**/*-keyfile.json
+
+# System files
+.DS_Store
+Thumbs.db
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# CourseCode Cloud (project binding)
+.coursecode/
+
+# Narration cache
+.narration-cache.json
+
+# Logs
+*.log
+npm-debug.log*

package/template/vite.config.js

@@ -16,6 +16,13 @@ const ROOT_DIR = path.resolve(__dirname);
 const DIST_DIR = path.join(ROOT_DIR, 'dist');
 const SUPPORTED_BROWSER_TARGETS = ['chrome111', 'edge111', 'firefox114', 'safari16.4'];
 
+function directoryContainsFiles(directory) {
+  if (!fs.existsSync(directory)) return false;
+  return fs.readdirSync(directory, { withFileTypes: true }).some(entry => (
+    entry.isFile() || (entry.isDirectory() && directoryContainsFiles(path.join(directory, entry.name)))
+  ));
+}
+
 async function loadBuildUtils() {
   if (
     generateManifest &&
@@ -382,7 +389,10 @@ export default defineConfig(async ({ mode }) => {
           { src: 'schemas/common/*', dest: 'common', rename: { stripBase: 2 } },
           // Publish runtime assets only. Never ship authoring references,
           // configuration source, assessment source, or hidden project files.
-          { src: 'course/assets', dest: 'course', rename: { stripBase: 1 } },
+          // A blank course is valid and may not contain any assets yet.
+          ...(directoryContainsFiles(path.join(ROOT_DIR, 'course', 'assets'))
+            ? [{ src: 'course/assets', dest: 'course', rename: { stripBase: 1 } }]
+            : []),
           { src: 'framework/js/vendor/**/*', dest: 'js/vendor', rename: { stripBase: 3 } }
         ],
         watch: isDev ? { rerun: true } : undefined