@lessonkit/cli 1.6.0 → 1.7.1

package/README.md

@@ -30,7 +30,7 @@ lessonkit package --target scorm12   # LMS artifact
 | Flag | Purpose |
 | --- | --- |
 | `--here` | Scaffold in the current directory |
-| `--force` | Overwrite existing files in the target directory |
+| `--force` | With `--here`: scaffold in a non-empty directory; conflicting template files (e.g. `.gitignore`, `README.md`) are backed up to `.lessonkit-init-backup/` before overwrite. Non-conflicting files are kept. |
 | `--skip-install` | Skip `npm install` after copying the template |
 
 ### Package targets
@@ -57,7 +57,7 @@ Subprocess timeout defaults to **30 minutes** (`LESSONKIT_CMD_TIMEOUT_MS`).
 
 ## Docs
 
-[5-minute guide](https://lessonkit.readthedocs.io/en/latest/guides/react-developers/getting-started-in-5-minutes.html) · [CLI reference](https://lessonkit.readthedocs.io/en/latest/reference/cli.html) · [Ship to LMS checklist](https://lessonkit.readthedocs.io/en/latest/guides/react-developers/ship-to-lms.html) · [Packaging guide](https://lessonkit.readthedocs.io/en/latest/guides/react-developers/packaging-and-cli.html) · [Published template](https://github.com/eddiethedean/lessonkit/tree/main/packages/cli/template/vite-react) (monorepo source: [`templates/vite-react`](https://github.com/eddiethedean/lessonkit/tree/main/templates/vite-react))
+[5-minute guide](https://lessonkit.readthedocs.io/en/latest/guides/react-developers/getting-started-in-5-minutes.html) · [CLI reference](https://lessonkit.readthedocs.io/en/latest/reference/cli.html) · [LMS Go-Live](https://lessonkit.readthedocs.io/en/latest/guides/react-developers/lms-go-live.html) · [Packaging guide](https://lessonkit.readthedocs.io/en/latest/guides/react-developers/packaging-and-cli.html) · [Published template](https://github.com/eddiethedean/lessonkit/tree/main/packages/cli/template/vite-react) (monorepo source: [`templates/vite-react`](https://github.com/eddiethedean/lessonkit/tree/main/templates/vite-react))
 
 ## License
 

package/dist/bin.js

@@ -127,6 +127,7 @@ async function runNpmInstall(cwd) {
 // src/commands/init.ts
 var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", "dist", ".lxpack", ".git", "coverage", ".nyc_output"]);
 var SKIP_FILES = /* @__PURE__ */ new Set([".DS_Store"]);
+var INIT_BACKUP_DIR = ".lessonkit-init-backup";
 function getTemplateDir() {
   const thisDir = dirname(fileURLToPath(import.meta.url));
   const candidates = [
@@ -195,29 +196,94 @@ async function applyTemplateSubstitutions(projectDir, projectName, slug) {
   appSource = appSource.replace(/\{\{courseTitle\}\}/g, escapeJsxString(projectName));
   await writeFile(appPath, appSource, "utf8");
 }
+function toPosixRelativePath(relativePath) {
+  return relativePath.replace(/\\/g, "/");
+}
+async function listStagingFiles(stagingDir, relativeDir = "") {
+  const dir = relativeDir ? join(stagingDir, relativeDir) : stagingDir;
+  const entries = await readdir(dir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    if (SKIP_DIRS.has(entry.name) || SKIP_FILES.has(entry.name)) continue;
+    const rel = relativeDir ? join(relativeDir, entry.name) : entry.name;
+    const relPosix = toPosixRelativePath(rel);
+    if (entry.isDirectory()) {
+      files.push(...await listStagingFiles(stagingDir, rel));
+    } else if (entry.isFile()) {
+      files.push(relPosix);
+    } else {
+    }
+  }
+  return files;
+}
+async function listProjectFiles(projectDir, relativeDir = "") {
+  const files = /* @__PURE__ */ new Set();
+  const dir = relativeDir ? join(projectDir, relativeDir) : projectDir;
+  if (!existsSync(dir)) return files;
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (relativeDir === "" && entry.name === INIT_BACKUP_DIR) continue;
+    if (relativeDir === "" && entry.name.startsWith(".lessonkit-init-")) continue;
+    if (SKIP_DIRS.has(entry.name) || SKIP_FILES.has(entry.name)) continue;
+    const rel = relativeDir ? join(relativeDir, entry.name) : entry.name;
+    const relPosix = toPosixRelativePath(rel);
+    if (entry.isDirectory()) {
+      for (const nested of await listProjectFiles(projectDir, rel)) {
+        files.add(nested);
+      }
+    } else if (entry.isFile()) {
+      files.add(relPosix);
+    }
+  }
+  return files;
+}
 async function backupConflictingFiles(stagingDir, projectDir) {
   const backups = /* @__PURE__ */ new Map();
-  const stagingEntries = await readdir(stagingDir, { withFileTypes: true });
-  for (const entry of stagingEntries) {
-    const destPath = join(projectDir, entry.name);
+  for (const relPath of await listStagingFiles(stagingDir)) {
+    const destPath = join(projectDir, relPath);
     if (!existsSync(destPath)) continue;
     const destStat = await stat(destPath);
     if (destStat.isFile()) {
-      backups.set(entry.name, await readFile(destPath));
+      backups.set(relPath, await readFile(destPath));
     }
   }
   return backups;
 }
-async function rollbackPromotedFiles(projectDir, stagingDir, preExisting, backups) {
+async function writeInitBackupDir(projectDir, backups) {
+  const backupDir = join(projectDir, INIT_BACKUP_DIR);
+  await mkdir(backupDir, { recursive: true });
+  for (const [relPath, content] of backups) {
+    const outPath = join(backupDir, relPath);
+    await mkdir(dirname(outPath), { recursive: true });
+    await writeFile(outPath, content);
+  }
+  return backupDir;
+}
+async function rollbackPromotedFiles(projectDir, stagingDir, preExistingRoots, preExistingFiles, backups) {
   const failures = [];
+  const stagingFiles = await listStagingFiles(stagingDir);
+  for (const relPath of stagingFiles) {
+    if (backups.has(relPath) || preExistingFiles.has(relPath)) continue;
+    try {
+      await rm(join(projectDir, relPath), { force: true });
+    } catch (err) {
+      failures.push(`remove ${relPath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
   let stagingEntries;
   try {
     stagingEntries = await readdir(stagingDir, { withFileTypes: true });
   } catch {
+    if (failures.length > 0) {
+      throw new CliError(`Init rollback failed: ${failures.join("; ")}`, {
+        code: "RUNTIME",
+        exitCode: EXIT_INVALID_PROJECT
+      });
+    }
     return;
   }
   for (const entry of stagingEntries) {
-    if (preExisting.has(entry.name)) continue;
+    if (preExistingRoots.has(entry.name)) continue;
     try {
       await rm(join(projectDir, entry.name), { recursive: true, force: true });
     } catch (err) {
@@ -226,11 +292,13 @@ async function rollbackPromotedFiles(projectDir, stagingDir, preExisting, backup
       );
     }
   }
-  for (const [name, content] of backups) {
+  for (const [relPath, content] of backups) {
     try {
-      await writeFile(join(projectDir, name), content);
+      const destPath = join(projectDir, relPath);
+      await mkdir(dirname(destPath), { recursive: true });
+      await writeFile(destPath, content);
     } catch (err) {
-      failures.push(`restore ${name}: ${err instanceof Error ? err.message : String(err)}`);
+      failures.push(`restore ${relPath}: ${err instanceof Error ? err.message : String(err)}`);
     }
   }
   if (failures.length > 0) {
@@ -240,12 +308,16 @@ async function rollbackPromotedFiles(projectDir, stagingDir, preExisting, backup
     });
   }
 }
+var PROMOTE_REPLACE_ENTRIES = /* @__PURE__ */ new Set(["node_modules", "package-lock.json"]);
 async function promoteStagingToProjectDir(stagingDir, projectDir) {
   await mkdir(projectDir, { recursive: true });
   const entries = await readdir(stagingDir, { withFileTypes: true });
   for (const entry of entries) {
     const srcPath = join(stagingDir, entry.name);
     const destPath = join(projectDir, entry.name);
+    if (PROMOTE_REPLACE_ENTRIES.has(entry.name) && existsSync(destPath)) {
+      await rm(destPath, { recursive: true, force: true });
+    }
     if (entry.isDirectory()) {
       await cp(srcPath, destPath, { recursive: true });
     } else if (entry.isFile()) {
@@ -262,7 +334,11 @@ var __testInitHelpers = {
   copyTemplate,
   promoteStagingToProjectDir,
   rollbackPromotedFiles,
-  backupConflictingFiles
+  backupConflictingFiles,
+  writeInitBackupDir,
+  listStagingFiles,
+  listProjectFiles,
+  INIT_BACKUP_DIR
 };
 async function runInit(opts, logger) {
   const cwd = process.cwd();
@@ -293,16 +369,7 @@ async function runInit(opts, logger) {
   }
   if (opts.here && !await isDirEmptyOrDotfilesOnly(projectDir) && !opts.force) {
     throw new CliError(
-      `Directory is not empty: ${projectDir}. Use --here --force only when the directory is empty or contains dotfiles only (e.g. .git).`,
-      {
-        code: "INVALID_PROJECT",
-        exitCode: EXIT_INVALID_PROJECT
-      }
-    );
-  }
-  if (opts.here && opts.force && !await isDirEmptyOrDotfilesOnly(projectDir)) {
-    throw new CliError(
-      `Directory is not empty: ${projectDir}. --force only initializes when the directory is empty or contains dotfiles only (e.g. .git).`,
+      `Directory is not empty: ${projectDir}. Use --here --force to scaffold anyway (conflicting files are backed up under ${INIT_BACKUP_DIR}/).`,
       {
         code: "INVALID_PROJECT",
         exitCode: EXIT_INVALID_PROJECT
@@ -325,13 +392,38 @@ async function runInit(opts, logger) {
       await runNpmInstall(stagingDir);
     }
     if (opts.here) {
-      const preExisting = new Set(await readdir(projectDir));
+      const preExistingRoots = new Set(await readdir(projectDir));
+      const preExistingFiles = await listProjectFiles(projectDir);
       const backups = await backupConflictingFiles(stagingDir, projectDir);
+      const conflicts = [...backups.keys()].sort();
+      if (conflicts.length > 0 && !opts.force) {
+        throw new CliError(
+          `Would overwrite existing file(s): ${conflicts.join(", ")}. Re-run with --force to back them up under ${INIT_BACKUP_DIR}/ and continue.`,
+          {
+            code: "INVALID_PROJECT",
+            exitCode: EXIT_INVALID_PROJECT
+          }
+        );
+      }
+      if (conflicts.length > 0 && opts.force && !opts.json) {
+        const backupDir = await writeInitBackupDir(projectDir, backups);
+        logger.log(
+          `Backed up ${conflicts.length} conflicting file(s) to ${backupDir}: ${conflicts.join(", ")}`
+        );
+      } else if (conflicts.length > 0 && opts.force) {
+        await writeInitBackupDir(projectDir, backups);
+      }
       try {
         await __testInitHelpers.promoteStagingToProjectDir(stagingDir, projectDir);
       } catch (promoteErr) {
         try {
-          await rollbackPromotedFiles(projectDir, stagingDir, preExisting, backups);
+          await rollbackPromotedFiles(
+            projectDir,
+            stagingDir,
+            preExistingRoots,
+            preExistingFiles,
+            backups
+          );
         } catch (rollbackErr) {
           const promoteMessage = promoteErr instanceof Error ? promoteErr.message : String(promoteErr);
           const rollbackMessage = rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr);
@@ -632,13 +724,13 @@ async function runBuild(opts) {
       { code: "INVALID_PROJECT", exitCode: EXIT_INVALID_PROJECT }
     );
   }
+  await assertSpaDistContentsSafe({ main: distDir }, project.root);
   return { ok: true, command: "build", projectRoot: project.root };
 }
 
 // src/commands/package.ts
 import { existsSync as existsSync4 } from "fs";
-import { isAbsolute } from "path";
-import { packageLessonkitCourse } from "@lessonkit/lxpack";
+import { assertSpaDistContentsSafe as assertSpaDistContentsSafe2, packageLessonkitCourse } from "@lessonkit/lxpack";
 async function runPackage(opts) {
   let target;
   try {
@@ -674,6 +766,7 @@ async function runPackage(opts) {
         exitCode: EXIT_INVALID_PROJECT
       });
     }
+    await assertSpaDistContentsSafe2({ main: distDir }, project.root);
     return { ok: true, command: "package", target, projectRoot: project.root, distDir };
   }
   assertNode18ForLxpack();
@@ -687,20 +780,19 @@ async function runPackage(opts) {
     });
   }
   const outDir = resolveLxpackOutDir(project);
+  const trimmedOut = opts.out?.trim();
   const { output: resolvedOutput, dir, outputBaseDir } = resolvePackageOutput(
     project,
     target,
-    opts.out
+    trimmedOut
   );
-  const trimmedOut = opts.out?.trim();
-  const output = trimmedOut && !isAbsolute(trimmedOut) ? trimmedOut : resolvedOutput;
   const result = await packageLessonkitCourse({
     descriptor: project.course,
     outDir,
     spaDistDir: distDir,
     projectRoot: project.root,
     target,
-    output,
+    output: trimmedOut ? resolvedOutput : void 0,
     dir,
     outputBaseDir,
     strictParity: opts.strictParity,
@@ -879,7 +971,7 @@ function createProgram(baseLogger = console) {
   program.name("lessonkit").description("LessonKit CLI").version(version);
   program.command("init").description("Initialize a LessonKit project from the Vite + React template").argument("[name]", "Project directory name").option("--here", "Initialize in the current directory").option("--skip-install", "Skip npm install").option(
     "--force",
-    "Requires --here: allow init when the directory is empty or contains only dotfiles"
+    "With --here: scaffold in a non-empty directory; back up conflicting template paths under .lessonkit-init-backup/ before overwrite"
   ).option("--json", "Emit structured JSON result").action(async (name, opts) => {
     const logger = createLogger({ json: opts.json });
     await handleCommand(

package/dist/index.js

@@ -125,6 +125,7 @@ async function runNpmInstall(cwd) {
 // src/commands/init.ts
 var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", "dist", ".lxpack", ".git", "coverage", ".nyc_output"]);
 var SKIP_FILES = /* @__PURE__ */ new Set([".DS_Store"]);
+var INIT_BACKUP_DIR = ".lessonkit-init-backup";
 function getTemplateDir() {
   const thisDir = dirname(fileURLToPath(import.meta.url));
   const candidates = [
@@ -193,29 +194,94 @@ async function applyTemplateSubstitutions(projectDir, projectName, slug) {
   appSource = appSource.replace(/\{\{courseTitle\}\}/g, escapeJsxString(projectName));
   await writeFile(appPath, appSource, "utf8");
 }
+function toPosixRelativePath(relativePath) {
+  return relativePath.replace(/\\/g, "/");
+}
+async function listStagingFiles(stagingDir, relativeDir = "") {
+  const dir = relativeDir ? join(stagingDir, relativeDir) : stagingDir;
+  const entries = await readdir(dir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    if (SKIP_DIRS.has(entry.name) || SKIP_FILES.has(entry.name)) continue;
+    const rel = relativeDir ? join(relativeDir, entry.name) : entry.name;
+    const relPosix = toPosixRelativePath(rel);
+    if (entry.isDirectory()) {
+      files.push(...await listStagingFiles(stagingDir, rel));
+    } else if (entry.isFile()) {
+      files.push(relPosix);
+    } else {
+    }
+  }
+  return files;
+}
+async function listProjectFiles(projectDir, relativeDir = "") {
+  const files = /* @__PURE__ */ new Set();
+  const dir = relativeDir ? join(projectDir, relativeDir) : projectDir;
+  if (!existsSync(dir)) return files;
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (relativeDir === "" && entry.name === INIT_BACKUP_DIR) continue;
+    if (relativeDir === "" && entry.name.startsWith(".lessonkit-init-")) continue;
+    if (SKIP_DIRS.has(entry.name) || SKIP_FILES.has(entry.name)) continue;
+    const rel = relativeDir ? join(relativeDir, entry.name) : entry.name;
+    const relPosix = toPosixRelativePath(rel);
+    if (entry.isDirectory()) {
+      for (const nested of await listProjectFiles(projectDir, rel)) {
+        files.add(nested);
+      }
+    } else if (entry.isFile()) {
+      files.add(relPosix);
+    }
+  }
+  return files;
+}
 async function backupConflictingFiles(stagingDir, projectDir) {
   const backups = /* @__PURE__ */ new Map();
-  const stagingEntries = await readdir(stagingDir, { withFileTypes: true });
-  for (const entry of stagingEntries) {
-    const destPath = join(projectDir, entry.name);
+  for (const relPath of await listStagingFiles(stagingDir)) {
+    const destPath = join(projectDir, relPath);
     if (!existsSync(destPath)) continue;
     const destStat = await stat(destPath);
     if (destStat.isFile()) {
-      backups.set(entry.name, await readFile(destPath));
+      backups.set(relPath, await readFile(destPath));
     }
   }
   return backups;
 }
-async function rollbackPromotedFiles(projectDir, stagingDir, preExisting, backups) {
+async function writeInitBackupDir(projectDir, backups) {
+  const backupDir = join(projectDir, INIT_BACKUP_DIR);
+  await mkdir(backupDir, { recursive: true });
+  for (const [relPath, content] of backups) {
+    const outPath = join(backupDir, relPath);
+    await mkdir(dirname(outPath), { recursive: true });
+    await writeFile(outPath, content);
+  }
+  return backupDir;
+}
+async function rollbackPromotedFiles(projectDir, stagingDir, preExistingRoots, preExistingFiles, backups) {
   const failures = [];
+  const stagingFiles = await listStagingFiles(stagingDir);
+  for (const relPath of stagingFiles) {
+    if (backups.has(relPath) || preExistingFiles.has(relPath)) continue;
+    try {
+      await rm(join(projectDir, relPath), { force: true });
+    } catch (err) {
+      failures.push(`remove ${relPath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
   let stagingEntries;
   try {
     stagingEntries = await readdir(stagingDir, { withFileTypes: true });
   } catch {
+    if (failures.length > 0) {
+      throw new CliError(`Init rollback failed: ${failures.join("; ")}`, {
+        code: "RUNTIME",
+        exitCode: EXIT_INVALID_PROJECT
+      });
+    }
     return;
   }
   for (const entry of stagingEntries) {
-    if (preExisting.has(entry.name)) continue;
+    if (preExistingRoots.has(entry.name)) continue;
     try {
       await rm(join(projectDir, entry.name), { recursive: true, force: true });
     } catch (err) {
@@ -224,11 +290,13 @@ async function rollbackPromotedFiles(projectDir, stagingDir, preExisting, backup
       );
     }
   }
-  for (const [name, content] of backups) {
+  for (const [relPath, content] of backups) {
     try {
-      await writeFile(join(projectDir, name), content);
+      const destPath = join(projectDir, relPath);
+      await mkdir(dirname(destPath), { recursive: true });
+      await writeFile(destPath, content);
     } catch (err) {
-      failures.push(`restore ${name}: ${err instanceof Error ? err.message : String(err)}`);
+      failures.push(`restore ${relPath}: ${err instanceof Error ? err.message : String(err)}`);
     }
   }
   if (failures.length > 0) {
@@ -238,12 +306,16 @@ async function rollbackPromotedFiles(projectDir, stagingDir, preExisting, backup
     });
   }
 }
+var PROMOTE_REPLACE_ENTRIES = /* @__PURE__ */ new Set(["node_modules", "package-lock.json"]);
 async function promoteStagingToProjectDir(stagingDir, projectDir) {
   await mkdir(projectDir, { recursive: true });
   const entries = await readdir(stagingDir, { withFileTypes: true });
   for (const entry of entries) {
     const srcPath = join(stagingDir, entry.name);
     const destPath = join(projectDir, entry.name);
+    if (PROMOTE_REPLACE_ENTRIES.has(entry.name) && existsSync(destPath)) {
+      await rm(destPath, { recursive: true, force: true });
+    }
     if (entry.isDirectory()) {
       await cp(srcPath, destPath, { recursive: true });
     } else if (entry.isFile()) {
@@ -260,7 +332,11 @@ var __testInitHelpers = {
   copyTemplate,
   promoteStagingToProjectDir,
   rollbackPromotedFiles,
-  backupConflictingFiles
+  backupConflictingFiles,
+  writeInitBackupDir,
+  listStagingFiles,
+  listProjectFiles,
+  INIT_BACKUP_DIR
 };
 async function runInit(opts, logger) {
   const cwd = process.cwd();
@@ -291,16 +367,7 @@ async function runInit(opts, logger) {
   }
   if (opts.here && !await isDirEmptyOrDotfilesOnly(projectDir) && !opts.force) {
     throw new CliError(
-      `Directory is not empty: ${projectDir}. Use --here --force only when the directory is empty or contains dotfiles only (e.g. .git).`,
-      {
-        code: "INVALID_PROJECT",
-        exitCode: EXIT_INVALID_PROJECT
-      }
-    );
-  }
-  if (opts.here && opts.force && !await isDirEmptyOrDotfilesOnly(projectDir)) {
-    throw new CliError(
-      `Directory is not empty: ${projectDir}. --force only initializes when the directory is empty or contains dotfiles only (e.g. .git).`,
+      `Directory is not empty: ${projectDir}. Use --here --force to scaffold anyway (conflicting files are backed up under ${INIT_BACKUP_DIR}/).`,
       {
         code: "INVALID_PROJECT",
         exitCode: EXIT_INVALID_PROJECT
@@ -323,13 +390,38 @@ async function runInit(opts, logger) {
       await runNpmInstall(stagingDir);
     }
     if (opts.here) {
-      const preExisting = new Set(await readdir(projectDir));
+      const preExistingRoots = new Set(await readdir(projectDir));
+      const preExistingFiles = await listProjectFiles(projectDir);
       const backups = await backupConflictingFiles(stagingDir, projectDir);
+      const conflicts = [...backups.keys()].sort();
+      if (conflicts.length > 0 && !opts.force) {
+        throw new CliError(
+          `Would overwrite existing file(s): ${conflicts.join(", ")}. Re-run with --force to back them up under ${INIT_BACKUP_DIR}/ and continue.`,
+          {
+            code: "INVALID_PROJECT",
+            exitCode: EXIT_INVALID_PROJECT
+          }
+        );
+      }
+      if (conflicts.length > 0 && opts.force && !opts.json) {
+        const backupDir = await writeInitBackupDir(projectDir, backups);
+        logger.log(
+          `Backed up ${conflicts.length} conflicting file(s) to ${backupDir}: ${conflicts.join(", ")}`
+        );
+      } else if (conflicts.length > 0 && opts.force) {
+        await writeInitBackupDir(projectDir, backups);
+      }
       try {
         await __testInitHelpers.promoteStagingToProjectDir(stagingDir, projectDir);
       } catch (promoteErr) {
         try {
-          await rollbackPromotedFiles(projectDir, stagingDir, preExisting, backups);
+          await rollbackPromotedFiles(
+            projectDir,
+            stagingDir,
+            preExistingRoots,
+            preExistingFiles,
+            backups
+          );
         } catch (rollbackErr) {
           const promoteMessage = promoteErr instanceof Error ? promoteErr.message : String(promoteErr);
           const rollbackMessage = rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr);
@@ -630,13 +722,13 @@ async function runBuild(opts) {
       { code: "INVALID_PROJECT", exitCode: EXIT_INVALID_PROJECT }
     );
   }
+  await assertSpaDistContentsSafe({ main: distDir }, project.root);
   return { ok: true, command: "build", projectRoot: project.root };
 }
 
 // src/commands/package.ts
 import { existsSync as existsSync4 } from "fs";
-import { isAbsolute } from "path";
-import { packageLessonkitCourse } from "@lessonkit/lxpack";
+import { assertSpaDistContentsSafe as assertSpaDistContentsSafe2, packageLessonkitCourse } from "@lessonkit/lxpack";
 async function runPackage(opts) {
   let target;
   try {
@@ -672,6 +764,7 @@ async function runPackage(opts) {
         exitCode: EXIT_INVALID_PROJECT
       });
     }
+    await assertSpaDistContentsSafe2({ main: distDir }, project.root);
     return { ok: true, command: "package", target, projectRoot: project.root, distDir };
   }
   assertNode18ForLxpack();
@@ -685,20 +778,19 @@ async function runPackage(opts) {
     });
   }
   const outDir = resolveLxpackOutDir(project);
+  const trimmedOut = opts.out?.trim();
   const { output: resolvedOutput, dir, outputBaseDir } = resolvePackageOutput(
     project,
     target,
-    opts.out
+    trimmedOut
   );
-  const trimmedOut = opts.out?.trim();
-  const output = trimmedOut && !isAbsolute(trimmedOut) ? trimmedOut : resolvedOutput;
   const result = await packageLessonkitCourse({
     descriptor: project.course,
     outDir,
     spaDistDir: distDir,
     projectRoot: project.root,
     target,
-    output,
+    output: trimmedOut ? resolvedOutput : void 0,
     dir,
     outputBaseDir,
     strictParity: opts.strictParity,
@@ -877,7 +969,7 @@ function createProgram(baseLogger = console) {
   program.name("lessonkit").description("LessonKit CLI").version(version);
   program.command("init").description("Initialize a LessonKit project from the Vite + React template").argument("[name]", "Project directory name").option("--here", "Initialize in the current directory").option("--skip-install", "Skip npm install").option(
     "--force",
-    "Requires --here: allow init when the directory is empty or contains only dotfiles"
+    "With --here: scaffold in a non-empty directory; back up conflicting template paths under .lessonkit-init-backup/ before overwrite"
   ).option("--json", "Emit structured JSON result").action(async (name, opts) => {
     const logger = createLogger({ json: opts.json });
     await handleCommand(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessonkit/cli",
-  "version": "1.6.0",
+  "version": "1.7.1",
   "private": false,
   "description": "LessonKit CLI — init, dev, build, and package learning experiences.",
   "license": "Apache-2.0",
@@ -36,8 +36,8 @@
   ],
   "scripts": {
     "copy-template": "node scripts/copy-template.mjs",
-    "build": "npm run copy-template && tsup src/index.ts src/bin.ts --format esm --splitting=false --platform node --target node18 --dts",
-    "dev": "npm run copy-template && tsup src/index.ts src/bin.ts --format esm --watch --splitting=false --platform node --target node18 --dts",
+    "build": "npm run copy-template && tsup src/index.ts src/bin.ts --format esm --splitting=false --platform node --target node18 --dts --tsconfig tsconfig.build.json",
+    "dev": "npm run copy-template && tsup src/index.ts src/bin.ts --format esm --watch --splitting=false --platform node --target node18 --dts --tsconfig tsconfig.build.json",
     "prepublishOnly": "npm run build",
     "typecheck": "tsc -p tsconfig.json",
     "test": "vitest run --passWithNoTests",
@@ -45,9 +45,9 @@
     "lint": "eslint --max-warnings 0 \"src/**/*.{ts,tsx}\" \"test/**/*.{ts,tsx}\""
   },
   "dependencies": {
-    "@lessonkit/core": "1.6.0",
-    "@lessonkit/lxpack": "1.6.0",
-    "@lessonkit/react": "1.6.0",
+    "@lessonkit/core": "1.7.1",
+    "@lessonkit/lxpack": "1.7.1",
+    "@lessonkit/react": "1.7.1",
     "commander": "^15.0.0"
   },
   "engines": {

package/template/vite-react/README.md

@@ -45,8 +45,8 @@ After `npm run package:scorm12`, the CLI prints the resolved ZIP path. Default:
 
 ## Production
 
-Copy `.env.example` to `.env` and set your LRS/analytics proxy URLs before `npm run build`. See the [production checklist](https://lessonkit.readthedocs.io/en/latest/guides/react-developers/production-checklist.html) and [Ship to LMS checklist](https://lessonkit.readthedocs.io/en/latest/guides/react-developers/ship-to-lms.html).
+Copy `.env.example` to `.env` and set your LRS/analytics proxy URLs before `npm run build`. See [LMS Go-Live](https://lessonkit.readthedocs.io/en/latest/guides/react-developers/lms-go-live.html) and the [backend proxy cookbook](https://lessonkit.readthedocs.io/en/latest/guides/react-developers/backend-proxy-cookbook.html).
 
 ## Docs
 
-[5-minute guide](https://lessonkit.readthedocs.io/en/latest/guides/react-developers/getting-started-in-5-minutes.html) · [First LMS export](https://lessonkit.readthedocs.io/en/latest/guides/react-developers/first-lms-export.html) · [CLI reference](https://lessonkit.readthedocs.io/en/latest/reference/cli.html) · [Packaging guide](https://lessonkit.readthedocs.io/en/latest/guides/react-developers/packaging-and-cli.html)
+[5-minute guide](https://lessonkit.readthedocs.io/en/latest/guides/react-developers/getting-started-in-5-minutes.html) · [LMS Go-Live](https://lessonkit.readthedocs.io/en/latest/guides/react-developers/lms-go-live.html) · [CLI reference](https://lessonkit.readthedocs.io/en/latest/reference/cli.html) · [Packaging guide](https://lessonkit.readthedocs.io/en/latest/guides/react-developers/packaging-and-cli.html)

package/template/vite-react/package.json

@@ -16,16 +16,16 @@
     "test:coverage": "vitest run --coverage --passWithNoTests=false"
   },
   "dependencies": {
-    "@lessonkit/core": "^1.6.0",
-    "@lessonkit/react": "^1.6.0",
-    "@lessonkit/themes": "^1.6.0",
-    "@lessonkit/xapi": "^1.6.0",
+    "@lessonkit/core": "^1.7.1",
+    "@lessonkit/react": "^1.7.1",
+    "@lessonkit/themes": "^1.7.1",
+    "@lessonkit/xapi": "^1.7.1",
     "react": "^19.2.7",
     "react-dom": "^19.2.7"
   },
   "devDependencies": {
-    "@lessonkit/cli": "^1.6.0",
-    "@lessonkit/lxpack": "^1.6.0",
+    "@lessonkit/cli": "^1.7.1",
+    "@lessonkit/lxpack": "^1.7.1",
     "@testing-library/react": "^16.3.0",
     "@testing-library/dom": "^10.4.1",
     "@types/react": "^19.2.17",

package/template/vite-react/src/courseConfig.test.ts

@@ -46,6 +46,11 @@ describe("createCourseConfig", () => {
     config.observability?.onXapiTransportError?.(new Error("transport"));
     config.observability?.onXapiMappingError?.(new Error("mapping"));
     config.observability?.onLxpackBridgeError?.(new Error("bridge"));
+    config.observability?.onInvalidSessionId?.({
+      invalidId: "bad:id",
+      fallbackId: "tab-1",
+      source: "provided",
+    });
 
     expect(warn).toHaveBeenCalled();
     warn.mockRestore();

package/template/vite-react/src/courseConfig.ts

@@ -34,6 +34,9 @@ function createObservability(): NonNullable<LessonkitConfig["observability"]> {
     onLxpackBridgeError: (err) => report("lxpack-bridge-error", { err }),
     onXapiTransportError: (err) => report("xapi-transport", { err }),
     onXapiMappingError: (err) => report("xapi-mapping", { err }),
+    onXapiDeadLetterPersistError: (err, ctx) =>
+      report("xapi-dead-letter-persist", { err, statementId: ctx.statement.id }),
+    onInvalidSessionId: (ctx) => report("invalid-session-id", ctx),
   };
 }