@lessonkit/lxpack 1.4.0 → 1.5.0

package/dist/index.cjs

@@ -36,6 +36,7 @@ __export(index_exports, {
   buildStagingPackage: () => buildStagingPackage,
   descriptorToInterchange: () => descriptorToInterchange,
   ensureOutDirParent: () => ensureOutDirParent,
+  escapeShellText: () => escapeShellText,
   extractAssessments: () => extractAssessments,
   lessonkitInterchangeSchema: () => import_validators2.lessonkitInterchangeSchema,
   loadLessonkitManifestFromFile: () => loadLessonkitManifestFromFile,
@@ -404,8 +405,30 @@ var ASSESSMENT_VALIDATORS = {
     }
   },
   fillInBlanks: (assessment, path, issues) => {
-    if (assessment.kind === "fillInBlanks" && !assessment.template?.trim()) {
+    if (assessment.kind !== "fillInBlanks") return;
+    if (!assessment.template?.trim()) {
       issues.push({ path: `${path}.template`, message: "template is required for fillInBlanks" });
+      return;
+    }
+    const templateBlankCount = countStarDelimitedBlanks(assessment.template);
+    if (templateBlankCount === 0) {
+      issues.push({
+        path: `${path}.template`,
+        message: "template must include at least one blank wrapped in asterisks for fillInBlanks"
+      });
+    }
+    const explicitBlanks = assessment.blanks?.map((b) => ({ id: b.id?.trim() ?? "", answer: b.answer?.trim() ?? "" })).filter((b) => b.id.length > 0 && b.answer.length > 0) ?? [];
+    if (assessment.blanks !== void 0 && explicitBlanks.length === 0) {
+      issues.push({
+        path: `${path}.blanks`,
+        message: "blanks must include at least one entry with non-empty id and answer"
+      });
+    }
+    if (explicitBlanks.length > 0 && explicitBlanks.length !== templateBlankCount) {
+      issues.push({
+        path: `${path}.blanks`,
+        message: `blanks length (${explicitBlanks.length}) must match template blank count (${templateBlankCount})`
+      });
     }
   },
   findHotspot: (assessment, path, issues) => {
@@ -603,27 +626,47 @@ function validateCourseDescriptor(input) {
 }
 
 // src/assessments.ts
+function escapeShellText(text) {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+function decodeShellEntities(text) {
+  return text.replace(/&amp;/gi, "&").replace(/&lt;/gi, "<").replace(/&gt;/gi, ">").replace(/&quot;/gi, '"').replace(/&#39;/gi, "'").replace(/&#x([0-9a-f]+);/gi, (_, hex) => String.fromCharCode(parseInt(hex, 16))).replace(/&#(\d+);/g, (_, num) => String.fromCharCode(Number(num)));
+}
+function containsUnsafeShellMarkup(text) {
+  const decoded = decodeShellEntities(text);
+  return /<\/script/i.test(decoded) || /<!--/.test(decoded) || /</.test(decoded);
+}
+function sanitizeShellField(text) {
+  if (containsUnsafeShellMarkup(text)) return null;
+  return escapeShellText(text);
+}
 function slugChoiceId(text, index) {
   const base = text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 32);
   const stem = base.length ? base : "choice";
   return `${stem}-${index + 1}`;
 }
 function mcqToLxpack(assessment) {
+  const checkId = sanitizeShellField(assessment.checkId);
+  const prompt = sanitizeShellField(assessment.question);
+  if (!checkId || !prompt) return null;
   const choices = assessment.choices.map((text, index) => {
+    const sanitizedText = sanitizeShellField(text);
+    if (!sanitizedText) return null;
     const id = slugChoiceId(text, index);
     return {
       id,
-      text,
+      text: sanitizedText,
       correct: text === assessment.answer
     };
   });
+  if (choices.some((choice) => choice === null)) return null;
   return {
-    id: assessment.checkId,
+    id: checkId,
     passingScore: assessment.passingScore ?? 1,
     questions: [
       {
         id: "q1",
-        prompt: assessment.question,
+        prompt,
         choices
       }
     ]
@@ -683,22 +726,29 @@ var LMS_SHELL_TARGETS = /* @__PURE__ */ new Set([
   "xapi",
   "cmi5"
 ]);
+function appendActivityIriIssues(issues, descriptor, target) {
+  const hasXapiTracking = Boolean(descriptor.tracking?.xapi);
+  const requiresForTarget = target === "xapi" || target === "cmi5";
+  if (!hasXapiTracking && !requiresForTarget) return;
+  const activityIri = descriptor.tracking?.xapi?.activityIri?.trim();
+  const targetSuffix = target === "xapi" || target === "cmi5" ? ` for ${target} export targets` : " when tracking.xapi is configured";
+  if (!activityIri) {
+    issues.push({
+      path: "tracking.xapi.activityIri",
+      message: `tracking.xapi.activityIri is required${targetSuffix}`
+    });
+    return;
+  }
+  if (!/^https:\/\/.+/i.test(activityIri)) {
+    issues.push({
+      path: "tracking.xapi.activityIri",
+      message: `tracking.xapi.activityIri must be an HTTPS URL${targetSuffix}`
+    });
+  }
+}
 function validateDescriptorForExportTarget(descriptor, target) {
   const issues = [];
-  if (target === "xapi" || target === "cmi5") {
-    const activityIri = descriptor.tracking?.xapi?.activityIri?.trim();
-    if (!activityIri) {
-      issues.push({
-        path: "tracking.xapi.activityIri",
-        message: "tracking.xapi.activityIri is required for xapi and cmi5 export targets"
-      });
-    } else if (!/^https:\/\/.+/i.test(activityIri)) {
-      issues.push({
-        path: "tracking.xapi.activityIri",
-        message: "tracking.xapi.activityIri must be an HTTPS URL for xapi and cmi5 export targets"
-      });
-    }
-  }
+  appendActivityIriIssues(issues, descriptor, target);
   if (LMS_SHELL_TARGETS.has(target)) {
     issues.push(...validateInjectableAssessments(descriptor).map((issue) => ({
       ...issue,
@@ -735,16 +785,50 @@ function validateDescriptorForTarget(input, target) {
 var import_node_fs2 = require("fs");
 var import_node_path2 = require("path");
 var SCANNABLE_EXTENSIONS = [".tsx", ".ts", ".jsx", ".js"];
-function collectSourceUnderSrc(projectRoot) {
+function collectSourceUnderSrc(projectRoot, issues) {
   const srcDir = (0, import_node_path2.join)(projectRoot, "src");
   if (!(0, import_node_fs2.existsSync)(srcDir)) return [];
   const results = [];
   const walk = (dir) => {
     for (const entry of (0, import_node_fs2.readdirSync)(dir)) {
       const abs = (0, import_node_path2.join)(dir, entry);
-      if ((0, import_node_fs2.statSync)(abs).isDirectory()) {
+      let stat2;
+      try {
+        stat2 = (0, import_node_fs2.lstatSync)(abs);
+      } catch {
+        continue;
+      }
+      if (stat2.isSymbolicLink()) {
+        issues.push({
+          path: (0, import_node_path2.relative)(projectRoot, abs),
+          message: `Source tree contains symlink (rejected for parity scan): ${(0, import_node_path2.relative)(projectRoot, abs)}`,
+          severity: "error"
+        });
+        continue;
+      }
+      if (stat2.isDirectory()) {
+        try {
+          assertRealPathUnderRoot(projectRoot, abs);
+        } catch {
+          issues.push({
+            path: (0, import_node_path2.relative)(projectRoot, abs),
+            message: `Source directory escapes project root: ${(0, import_node_path2.relative)(projectRoot, abs)}`,
+            severity: "error"
+          });
+          continue;
+        }
         walk(abs);
       } else if (SCANNABLE_EXTENSIONS.some((ext) => entry.endsWith(ext))) {
+        try {
+          assertRealPathUnderRoot(projectRoot, abs);
+        } catch {
+          issues.push({
+            path: (0, import_node_path2.relative)(projectRoot, abs),
+            message: `Source file escapes project root: ${(0, import_node_path2.relative)(projectRoot, abs)}`,
+            severity: "error"
+          });
+          continue;
+        }
         results.push((0, import_node_path2.relative)(projectRoot, abs));
       }
     }
@@ -752,20 +836,69 @@ function collectSourceUnderSrc(projectRoot) {
   walk(srcDir);
   return results;
 }
-function readAppSources(projectRoot, appSources) {
-  return appSources.map((rel) => (0, import_node_path2.join)(projectRoot, rel)).filter((abs) => (0, import_node_fs2.existsSync)(abs)).map((abs) => (0, import_node_fs2.readFileSync)(abs, "utf8")).join("\n");
+function readAppSources(projectRoot, appSources, issues, customSourcesProvided) {
+  return appSources.map((rel) => {
+    if (!isSafeRelativeSpaPath(rel)) {
+      if (customSourcesProvided) {
+        issues.push({
+          path: rel,
+          message: `Unsafe appSources path skipped: ${rel}`,
+          severity: "warning"
+        });
+      }
+      return null;
+    }
+    const abs = (0, import_node_path2.join)(projectRoot, rel);
+    try {
+      assertRealPathUnderRoot(projectRoot, abs);
+      if ((0, import_node_fs2.existsSync)(abs) && (0, import_node_fs2.lstatSync)(abs).isSymbolicLink()) {
+        issues.push({
+          path: rel,
+          message: `appSources path is a symlink: ${rel}`,
+          severity: "error"
+        });
+        return null;
+      }
+    } catch {
+      issues.push({
+        path: rel,
+        message: `appSources path escapes project root: ${rel}`,
+        severity: "error"
+      });
+      return null;
+    }
+    if (!(0, import_node_fs2.existsSync)(abs)) return null;
+    return (0, import_node_fs2.readFileSync)(abs, "utf8");
+  }).filter((content) => content != null).join("\n");
 }
 function stripComments(source) {
   return source.replace(/\/\*[\s\S]*?\*\//g, " ").replace(/\/\/[^\n]*/g, " ");
 }
-function idPropPatterns(prop, id) {
-  return [
-    `${prop}="${id}"`,
-    `${prop}='${id}'`,
-    `${prop}={'${id}'}`,
-    `${prop}={"${id}"}`,
-    `${prop}={\`${id}\`}`
-  ];
+function maskUnrelatedStringLiterals(source) {
+  return source.replace(/(["'`])(?:\\.|(?!\1).)*\1/g, (match, _quote, offset, full) => {
+    const before = full.slice(Math.max(0, offset - 24), offset);
+    if (/\b(?:courseId|checkId|lessonId)\s*=\s*$/.test(before)) {
+      return match;
+    }
+    return '""';
+  });
+}
+function idPropPresent(source, prop, id) {
+  const stripped = stripComments(source);
+  const masked = maskUnrelatedStringLiterals(stripped);
+  return jsxPropRegex(prop, id).test(masked);
+}
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function jsxPropRegex(prop, id) {
+  const escapedId = escapeRegExp(id);
+  return new RegExp(
+    `(?<![A-Za-z0-9_$])${prop}\\s*=\\s*(?:"${escapedId}"|'${escapedId}'|\\{\\s*["'\`]${escapedId}["'\`]\\s*\\}|\\{\\s*\`${escapedId}\`\\s*\\})`
+  );
+}
+function maskStringLiterals(source) {
+  return source.replace(/(["'`])(?:\\.|(?!\1).)*\1/g, '""');
 }
 function extractStringConstants(source) {
   const stripped = stripComments(source);
@@ -776,7 +909,9 @@ function extractStringConstants(source) {
   }
   return map;
 }
-function idUsedViaConstant(stripped, prop, id, constants) {
+function idUsedViaConstant(source, prop, id, constants) {
+  const stripped = stripComments(source);
+  const masked = maskStringLiterals(stripped);
   for (const [name, value] of constants) {
     if (value !== id) continue;
     const jsxPatterns = [
@@ -785,40 +920,61 @@ function idUsedViaConstant(stripped, prop, id, constants) {
       `${prop}={${name} }`,
       `${prop}={ ${name}}`
     ];
-    if (jsxPatterns.some((p) => stripped.includes(p))) return true;
-    const objPatterns = [`${prop}: ${name}`, `${prop}:${name}`];
-    if (objPatterns.some((p) => stripped.includes(p))) return true;
+    if (jsxPatterns.some((p) => masked.includes(p))) return true;
   }
   return false;
 }
-function courseIdPresent(source, courseId) {
+function lessonIdInDataLiteral(source, lessonId) {
   const stripped = stripComments(source);
-  if (idPropPatterns("courseId", courseId).some((p) => stripped.includes(p))) return true;
-  return idUsedViaConstant(stripped, "courseId", courseId, extractStringConstants(source));
+  const escaped = escapeRegExp(lessonId);
+  return new RegExp(`\\bid\\s*:\\s*["'\`]${escaped}["'\`]`).test(stripped);
 }
-function checkIdPresent(source, checkId) {
+function lessonIdPresent(source, lessonId) {
+  if (idPropPresent(source, "lessonId", lessonId)) return true;
+  if (idUsedViaConstant(source, "lessonId", lessonId, extractStringConstants(source))) return true;
+  return lessonIdInDataLiteral(source, lessonId);
+}
+function courseConfigCourseIdPresent(source, courseId) {
   const stripped = stripComments(source);
-  if (idPropPatterns("checkId", checkId).some((p) => stripped.includes(p))) return true;
-  return idUsedViaConstant(stripped, "checkId", checkId, extractStringConstants(source));
+  const escaped = escapeRegExp(courseId);
+  const literalPattern = new RegExp(
+    `(?<![A-Za-z0-9_$])courseId\\s*:\\s*(?:"${escaped}"|'${escaped}')`
+  );
+  if (literalPattern.test(stripped)) return true;
+  return idUsedViaConstant(source, "courseId", courseId, extractStringConstants(source));
+}
+function courseIdPresent(source, courseId) {
+  if (idPropPresent(source, "courseId", courseId)) return true;
+  if (idUsedViaConstant(source, "courseId", courseId, extractStringConstants(source))) return true;
+  return courseConfigCourseIdPresent(source, courseId);
+}
+function checkIdPresent(source, checkId) {
+  if (idPropPresent(source, "checkId", checkId)) return true;
+  return idUsedViaConstant(source, "checkId", checkId, extractStringConstants(source));
 }
 var ID_SYNC_DOC = "https://lessonkit.readthedocs.io/en/latest/guides/react-developers/quickstart.html#keep-react-ids-in-sync-with-lessonkitjson";
 function parityHint(message) {
   return `${message} See ${ID_SYNC_DOC}`;
 }
 function validateReactManifestParity(opts) {
-  const appSources = opts.appSources ?? collectSourceUnderSrc(opts.projectRoot);
-  const source = readAppSources(opts.projectRoot, appSources);
+  const issues = [];
+  const customSourcesProvided = opts.appSources !== void 0;
+  const appSources = opts.appSources ?? collectSourceUnderSrc(opts.projectRoot, issues);
+  const source = readAppSources(
+    opts.projectRoot,
+    appSources,
+    issues,
+    customSourcesProvided
+  );
   const hasDescriptorIds = Boolean(opts.descriptor.courseId) || (opts.descriptor.assessments?.length ?? 0) > 0;
   if (!source.trim()) {
-    return [
-      {
-        path: appSources.length > 0 ? appSources.join(", ") : "src/",
-        message: hasDescriptorIds ? "React app source not found for ID parity check" : "React app source not found for ID parity check",
-        severity: hasDescriptorIds ? "error" : "warning"
-      }
-    ];
+    issues.push({
+      path: appSources.length > 0 ? appSources.join(", ") : "src/",
+      message: hasDescriptorIds ? "React app source required for ID parity check when descriptor defines courseId or assessments" : "React app source not found for ID parity check",
+      severity: hasDescriptorIds ? "error" : "warning"
+    });
+    return issues;
   }
-  const issues = [];
   const courseId = opts.descriptor.courseId;
   if (!courseIdPresent(source, courseId)) {
     issues.push({
@@ -829,6 +985,19 @@ function validateReactManifestParity(opts) {
       severity: "error"
     });
   }
+  for (const lesson of opts.descriptor.lessons ?? []) {
+    const lessonId = lesson.id;
+    if (!lessonId) continue;
+    if (!lessonIdPresent(source, lessonId)) {
+      issues.push({
+        path: `lessons.id:${lessonId}`,
+        message: parityHint(
+          `React app source missing lessonId="${lessonId}" declared in lessonkit.json.`
+        ),
+        severity: "error"
+      });
+    }
+  }
   for (const assessment of opts.descriptor.assessments ?? []) {
     const checkId = assessment.checkId;
     if (!checkId) continue;
@@ -847,7 +1016,13 @@ function validateReactManifestParity(opts) {
 
 // src/validateProjectPaths.ts
 var import_node_path3 = require("path");
-function validatePathField(value, fieldPath, projectRoot, issues) {
+var RESERVED_OUTPUT_SEGMENTS = /* @__PURE__ */ new Set([".git", "node_modules", ".github"]);
+function isReservedOutputPath(value) {
+  const normalized = value.replace(/\\/g, "/").replace(/^\/+|\/+$/g, "");
+  const segments = normalized.split("/").filter(Boolean);
+  return segments.some((segment) => RESERVED_OUTPUT_SEGMENTS.has(segment));
+}
+function validatePathField(value, fieldPath, projectRoot, issues, options) {
   if (!isSafeRelativeSpaPath(value)) {
     issues.push({
       path: fieldPath,
@@ -855,6 +1030,13 @@ function validatePathField(value, fieldPath, projectRoot, issues) {
     });
     return;
   }
+  if (options?.rejectReserved && isReservedOutputPath(value)) {
+    issues.push({
+      path: fieldPath,
+      message: "path must not target reserved directories (.git, node_modules, .github)"
+    });
+    return;
+  }
   try {
     assertRealPathUnderRoot(projectRoot, (0, import_node_path3.resolve)(projectRoot, value));
   } catch {
@@ -871,10 +1053,14 @@ function validateProjectPaths(projectRoot, paths) {
     validatePathField(paths.spaDistDir.trim(), "paths.spaDistDir", root, issues);
   }
   if (paths.lxpackOutDir?.trim()) {
-    validatePathField(paths.lxpackOutDir.trim(), "paths.lxpackOutDir", root, issues);
+    validatePathField(paths.lxpackOutDir.trim(), "paths.lxpackOutDir", root, issues, {
+      rejectReserved: true
+    });
   }
   if (paths.outputBaseDir?.trim()) {
-    validatePathField(paths.outputBaseDir.trim(), "paths.outputBaseDir", root, issues);
+    validatePathField(paths.outputBaseDir.trim(), "paths.outputBaseDir", root, issues, {
+      rejectReserved: true
+    });
   }
   return issues;
 }
@@ -887,11 +1073,17 @@ function resolveSafePackageOutputOverride(projectRoot, override) {
   if ((0, import_node_path3.isAbsolute)(trimmed)) {
     const resolved2 = (0, import_node_path3.resolve)(trimmed);
     assertRealPathUnderRoot(root, resolved2);
+    if (isReservedOutputPath(trimmed)) {
+      throw new Error(`unsafe output path: ${override} targets a reserved directory`);
+    }
     return resolved2;
   }
   if (!isSafeRelativeSpaPath(trimmed)) {
     throw new Error(`unsafe output path: ${override}`);
   }
+  if (isReservedOutputPath(trimmed)) {
+    throw new Error(`unsafe output path: ${override} targets a reserved directory`);
+  }
   const resolved = (0, import_node_path3.resolve)(root, trimmed);
   assertRealPathUnderRoot(root, resolved);
   return resolved;
@@ -1069,8 +1261,11 @@ async function walkDistDir(rootReal, current, label) {
     let entryReal;
     try {
       entryReal = (0, import_node_fs3.realpathSync)(entryPath);
-    } catch {
-      entryReal = entryPath;
+    } catch (err) {
+      throw new Error(
+        `spa dist for "${label}" could not resolve path: ${entryPath}`,
+        { cause: err }
+      );
     }
     assertResolvedPathUnderRoot(rootReal, entryReal);
     if (stat2.isDirectory()) {
@@ -1093,9 +1288,7 @@ async function writeLxpackProject(options) {
     throw new Error(injectableIssues.map((i) => `${i.path}: ${i.message}`).join("; "));
   }
   const outDir = (0, import_node_path6.resolve)(options.outDir);
-  if (options.projectRoot) {
-    assertRealPathUnderRoot((0, import_node_path6.resolve)(options.projectRoot), outDir);
-  }
+  assertRealPathUnderRoot((0, import_node_path6.resolve)(options.projectRoot), outDir);
   const spaDirs = await resolveSpaDirs({ ...options, descriptor });
   await assertSpaDistContentsSafe(spaDirs, options.projectRoot);
   const interchange = descriptorToInterchange(descriptor);
@@ -1291,21 +1484,36 @@ function promoteLockPath(outDir) {
   const hash = (0, import_node_crypto.createHash)("sha256").update((0, import_node_path8.resolve)(outDir)).digest("hex").slice(0, 16);
   return (0, import_node_path8.join)(parent, `.lk-promote-lock-${hash}`);
 }
-var STALE_LOCK_TTL_MS = 5 * 60 * 1e3;
+var STALE_ARTIFACT_TTL_MS = 5 * 60 * 1e3;
+var MAX_LOCK_AGE_MS = 30 * 60 * 1e3;
+var LOCK_TOKEN_RE = /^(\d+)\n([0-9a-f-]{36})(?:\n(\d+))?\n?$/i;
 async function isStalePromoteLock(lockPath) {
   try {
+    const stat2 = await fsp.stat(lockPath);
     const content = await fsp.readFile(lockPath, "utf8");
-    const pid = Number.parseInt(content.trim(), 10);
-    if (Number.isFinite(pid) && pid > 0) {
-      try {
-        process.kill(pid, 0);
-        return false;
-      } catch {
-        return true;
+    const match = content.match(LOCK_TOKEN_RE);
+    let lockAgeMs = Date.now() - stat2.mtimeMs;
+    if (match?.[3]) {
+      const startedAt = Number.parseInt(match[3], 10);
+      if (Number.isFinite(startedAt) && startedAt > 0) {
+        lockAgeMs = Date.now() - startedAt;
       }
     }
-    const stat2 = await fsp.stat(lockPath);
-    return Date.now() - stat2.mtimeMs > STALE_LOCK_TTL_MS;
+    if (lockAgeMs > MAX_LOCK_AGE_MS) {
+      return true;
+    }
+    if (match) {
+      const pid = Number.parseInt(match[1], 10);
+      if (Number.isFinite(pid) && pid > 0) {
+        try {
+          process.kill(pid, 0);
+          return false;
+        } catch {
+          return true;
+        }
+      }
+    }
+    return lockAgeMs > STALE_ARTIFACT_TTL_MS;
   } catch {
     return true;
   }
@@ -1318,6 +1526,8 @@ async function withPromoteLock(outDir, fn) {
     try {
       lockHandle = await fsp.open(lockPath, "wx");
       await lockHandle.writeFile(`${process.pid}
+${(0, import_node_crypto.randomUUID)()}
+${Date.now()}
 `, "utf8");
       break;
     } catch (err) {
@@ -1349,22 +1559,77 @@ async function withPromoteLock(outDir, fn) {
     );
   }
 }
-async function assertNoLegacyPromoteArtifacts(outDir) {
+async function removeStaleLegacyPromoteArtifacts(outDir) {
   const legacyTmp = `${outDir}.tmp-promote`;
   const legacyBak = `${outDir}.bak`;
-  const stale = [];
-  if (await pathExists(legacyTmp)) stale.push(legacyTmp);
-  if (await pathExists(legacyBak)) stale.push(legacyBak);
-  if (stale.length) {
+  const blocked = [];
+  for (const legacyPath of [legacyTmp, legacyBak]) {
+    if (!await pathExists(legacyPath)) continue;
+    try {
+      const stat2 = await fsp.stat(legacyPath);
+      if (Date.now() - stat2.mtimeMs > STALE_ARTIFACT_TTL_MS) {
+        await fsp.rm(legacyPath, { recursive: true, force: true }).catch(
+          /* v8 ignore next */
+          () => void 0
+        );
+        continue;
+      }
+    } catch {
+    }
+    blocked.push(legacyPath);
+  }
+  if (blocked.length) {
+    const rmHint = blocked.map((p) => `rm -rf ${JSON.stringify(p)}`).join("; ");
     throw new Error(
-      `[lessonkit/lxpack] cannot promote: remove stale packaging artifacts from a previous failed run: ${stale.join(", ")}`
+      `[lessonkit/lxpack] cannot promote: remove stale packaging artifacts from a previous failed run: ${blocked.join(", ")}. Try: ${rmHint}`
     );
   }
 }
-async function promoteStagingToOutDir(stagingDir, outDir) {
+async function listRelativePaths(root, dir = root) {
+  const entries = await fsp.readdir(dir, { withFileTypes: true });
+  const paths = [];
+  for (const entry of entries) {
+    const full = (0, import_node_path8.join)(dir, entry.name);
+    if (entry.isDirectory()) {
+      paths.push(...await listRelativePaths(root, full));
+    } else if (entry.isFile()) {
+      paths.push(full.slice(root.length + 1));
+    } else {
+    }
+  }
+  return paths;
+}
+async function mergePreservedOutArtifacts(priorArtifactsDir, destArtifactsDir, newArtifactPaths) {
+  if (!await pathExists(priorArtifactsDir)) return;
+  for (const rel of await listRelativePaths(priorArtifactsDir)) {
+    if (newArtifactPaths.has(rel)) continue;
+    const src = (0, import_node_path8.join)(priorArtifactsDir, rel);
+    const dest = (0, import_node_path8.join)(destArtifactsDir, rel);
+    await fsp.mkdir((0, import_node_path8.dirname)(dest), { recursive: true });
+    await fsp.cp(src, dest, { force: true });
+  }
+}
+async function promoteStagingToOutDir(stagingDir, outDir, options) {
+  const outputBaseDir = options?.outputBaseDir ?? ".lxpack/out";
+  if (options?.projectRoot) {
+    assertRealPathUnderRoot((0, import_node_path8.resolve)(options.projectRoot), (0, import_node_path8.resolve)(outDir));
+  }
   return withPromoteLock(outDir, async () => {
-    await assertNoLegacyPromoteArtifacts(outDir);
+    await removeStaleLegacyPromoteArtifacts(outDir);
+    const stagingArtifactsDir = (0, import_node_path8.join)(stagingDir, outputBaseDir);
+    const newArtifactPaths = /* @__PURE__ */ new Set();
+    if (await pathExists(stagingArtifactsDir)) {
+      for (const rel of await listRelativePaths(stagingArtifactsDir)) {
+        newArtifactPaths.add(rel);
+      }
+    }
     const parent = (0, import_node_path8.dirname)(outDir);
+    let priorArtifactsBackup;
+    const existingArtifactsDir = (0, import_node_path8.join)(outDir, outputBaseDir);
+    if (await pathExists(outDir) && await pathExists(existingArtifactsDir)) {
+      priorArtifactsBackup = await fsp.mkdtemp((0, import_node_path8.join)(parent, ".lk-prior-out-"));
+      await fsp.cp(existingArtifactsDir, (0, import_node_path8.join)(priorArtifactsBackup, outputBaseDir), { recursive: true });
+    }
     const tmpPromote = await fsp.mkdtemp((0, import_node_path8.join)(parent, ".lk-promote-"));
     await renameOrCopy(stagingDir, tmpPromote);
     const hadOutDir = await pathExists(outDir);
@@ -1421,6 +1686,20 @@ async function promoteStagingToOutDir(stagingDir, outDir) {
       }
       throw promoteError;
     }
+    if (priorArtifactsBackup) {
+      try {
+        await mergePreservedOutArtifacts(
+          (0, import_node_path8.join)(priorArtifactsBackup, outputBaseDir),
+          (0, import_node_path8.join)(outDir, outputBaseDir),
+          newArtifactPaths
+        );
+      } finally {
+        await fsp.rm(priorArtifactsBackup, { recursive: true, force: true }).catch(
+          /* v8 ignore next */
+          () => void 0
+        );
+      }
+    }
     if (backup) {
       await fsp.rm(backup, { recursive: true, force: true }).catch(
         /* v8 ignore next */
@@ -1438,6 +1717,7 @@ var import_api = require("@lxpack/api");
 async function buildStagingPackage(options) {
   const { target, output, dir, outputBaseDir, descriptor, ...writeOpts } = options;
   const stagingDir = await fsp2.mkdtemp((0, import_node_path9.join)((0, import_node_os.tmpdir)(), "lessonkit-lxpack-"));
+  let succeeded = false;
   try {
     let spaDirs;
     try {
@@ -1493,6 +1773,7 @@ async function buildStagingPackage(options) {
         }))
       };
     }
+    succeeded = true;
     return {
       ok: true,
       stagingDir,
@@ -1506,6 +1787,13 @@ async function buildStagingPackage(options) {
       () => void 0
     );
     throw err;
+  } finally {
+    if (!succeeded) {
+      await fsp2.rm(stagingDir, { recursive: true, force: true }).catch(
+        /* v8 ignore next */
+        () => void 0
+      );
+    }
   }
 }
 async function ensureOutDirParent(outDir) {
@@ -1570,24 +1858,22 @@ async function packageLessonkitCourse(options) {
     };
   }
   const descriptor = descriptorValidation.descriptor;
-  if (writeOpts.projectRoot) {
-    const parityIssues = validateReactManifestParity({
-      projectRoot: writeOpts.projectRoot,
-      descriptor
-    });
-    const parityErrors = parityIssues.filter((i) => i.severity === "error");
-    if (parityErrors.length > 0) {
-      return {
-        ok: false,
-        courseDir: outDir,
-        target,
-        issues: parityErrors.map((i) => ({
-          path: i.path,
-          message: i.message,
-          severity: i.severity
-        }))
-      };
-    }
+  const parityIssues = validateReactManifestParity({
+    projectRoot: writeOpts.projectRoot,
+    descriptor
+  });
+  const parityFailures = writeOpts.strictParity ? parityIssues : parityIssues.filter((i) => i.severity === "error");
+  if (parityFailures.length > 0) {
+    return {
+      ok: false,
+      courseDir: outDir,
+      target,
+      issues: parityFailures.map((i) => ({
+        path: i.path,
+        message: i.message,
+        severity: i.severity
+      }))
+    };
   }
   const staged = await buildStagingPackage({
     ...writeOpts,
@@ -1646,7 +1932,7 @@ async function packageLessonkitCourse(options) {
       ok: false,
       courseDir: outDir,
       target,
-      validation: { ok: true, manifest: build.manifest, issues: build.issues },
+      validation: { ok: false, manifest: build.manifest, issues: build.issues },
       build,
       issues: artifactIssues
     };
@@ -1660,7 +1946,10 @@ async function packageLessonkitCourse(options) {
   };
   try {
     await ensureOutDirParent(outDir);
-    await promoteStagingToOutDir(stagingDir, outDir);
+    await promoteStagingToOutDir(stagingDir, outDir, {
+      outputBaseDir: outputBaseDir ?? ".lxpack/out",
+      projectRoot: writeOpts.projectRoot
+    });
   } catch (err) {
     await fsp3.rm(stagingDir, { recursive: true, force: true }).catch(
       /* v8 ignore next */
@@ -1783,6 +2072,20 @@ function parseLessonkitManifest(raw, label = "lessonkit.json", projectRoot) {
       message: `"course.spaDistDir" (${courseSpaDistDir}) differs from "paths.spaDistDir" (${paths.spaDistDir}). Use paths.spaDistDir for CLI build and package.`
     });
   }
+  for (const key of ["spaDistDir", "lxpackOutDir", "outputBaseDir"]) {
+    const value = paths[key];
+    if (!isSafeRelativeSpaPath(value)) {
+      issues.push({
+        path: `paths.${key}`,
+        message: "path must be relative without '..' segments or absolute prefixes"
+      });
+    } else if ((key === "lxpackOutDir" || key === "outputBaseDir") && isReservedOutputPath(value)) {
+      issues.push({
+        path: `paths.${key}`,
+        message: "path must not target reserved directories (.git, node_modules, .github)"
+      });
+    }
+  }
   if (projectRoot) {
     const pathIssues = validateProjectPaths(projectRoot, paths);
     for (const pi of pathIssues) {
@@ -1814,37 +2117,56 @@ var import_tracking_schema2 = require("@lxpack/tracking-schema");
 
 // src/telemetry.ts
 var import_tracking_schema = require("@lxpack/tracking-schema");
-var SUPPORTED = new Set(import_tracking_schema.LESSONKIT_TELEMETRY_EVENTS);
+var BRANCH_TELEMETRY_EVENTS = ["branch_node_viewed", "branch_selected"];
+var ASSESSMENT_TELEMETRY_EVENTS = ["assessment_answered"];
+var SUPPORTED = /* @__PURE__ */ new Set([
+  ...import_tracking_schema.LESSONKIT_TELEMETRY_EVENTS,
+  ...BRANCH_TELEMETRY_EVENTS,
+  ...ASSESSMENT_TELEMETRY_EVENTS
+]);
 function isQuizAnsweredData(data) {
-  return typeof data === "object" && data !== null && typeof data.checkId === "string";
+  return typeof data === "object" && data !== null && typeof data.checkId === "string" && data.checkId.length > 0;
 }
 function isQuizCompletedData(data) {
-  return typeof data === "object" && data !== null && typeof data.checkId === "string";
+  return typeof data === "object" && data !== null && typeof data.checkId === "string" && data.checkId.length > 0;
+}
+function isAssessmentAnsweredData(data) {
+  return typeof data === "object" && data !== null && typeof data.checkId === "string" && data.checkId.length > 0;
 }
 function isInteractionData(data) {
   return typeof data === "object" && data !== null;
 }
+function isBranchNodeViewedData(data) {
+  return typeof data === "object" && data !== null && typeof data.blockId === "string" && typeof data.nodeId === "string";
+}
+function isBranchSelectedData(data) {
+  return typeof data === "object" && data !== null && typeof data.blockId === "string" && typeof data.fromNodeId === "string" && typeof data.toNodeId === "string";
+}
 function telemetryEventToLessonkit(event) {
   if (!SUPPORTED.has(event.name)) {
     return null;
   }
-  const name = event.name;
   const mapped = {
-    name,
+    name: event.name,
     lessonId: event.lessonId
   };
-  if (name === "quiz_completed" || name === "quiz_answered") {
+  if (event.name === "quiz_completed" || event.name === "quiz_answered" || event.name === "assessment_answered") {
     const data = event.data;
-    if (isQuizAnsweredData(data) || isQuizCompletedData(data)) {
-      mapped.assessmentId = data.checkId;
-      if ("score" in data) {
-        mapped.score = data.score;
-        mapped.maxScore = data.maxScore;
-        mapped.passingScore = data.passingScore;
-      }
-      mapped.data = data;
+    if (!isQuizAnsweredData(data) && !isQuizCompletedData(data) && !isAssessmentAnsweredData(data)) {
+      return null;
+    }
+    mapped.assessmentId = data.checkId;
+    if ("score" in data) {
+      mapped.score = data.score;
+      mapped.maxScore = data.maxScore;
+      mapped.passingScore = data.passingScore;
     }
-  } else if (name === "interaction" && event.data && isInteractionData(event.data)) {
+    mapped.data = data;
+  } else if (mapped.name === "interaction" && event.data && isInteractionData(event.data)) {
+    mapped.data = event.data;
+  } else if (event.name === "branch_node_viewed" && isBranchNodeViewedData(event.data)) {
+    mapped.data = event.data;
+  } else if (event.name === "branch_selected" && isBranchSelectedData(event.data)) {
     mapped.data = event.data;
   }
   return mapped;
@@ -1860,6 +2182,7 @@ var import_validators2 = require("@lxpack/validators");
   buildStagingPackage,
   descriptorToInterchange,
   ensureOutDirParent,
+  escapeShellText,
   extractAssessments,
   lessonkitInterchangeSchema,
   loadLessonkitManifestFromFile,