@lessonkit/lxpack 1.3.1 → 1.5.0

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   telemetryEventToLessonkit
-} from "./chunk-DYQI222N.js";
+} from "./chunk-HTZR4CF3.js";
 
 // src/descriptor/normalize.ts
 import { validateId } from "@lessonkit/core";
@@ -315,6 +315,10 @@ var validateMcqLike = (assessment, path, issues) => {
   } else if (trimmedChoices.length && !trimmedChoices.includes(assessment.answer.trim())) {
     issues.push({ path: `${path}.answer`, message: "answer must match a choice" });
   }
+  const uniqueChoices = new Set(trimmedChoices);
+  if (trimmedChoices.length !== uniqueChoices.size) {
+    issues.push({ path: `${path}.choices`, message: "choices must be unique" });
+  }
 };
 function countStarDelimitedBlanks(template) {
   const matches = template.match(/\*[^*]+\*/g);
@@ -340,8 +344,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) => {
@@ -539,27 +565,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
       }
     ]
@@ -582,15 +628,8 @@ function assessmentDescriptorToLxpack(assessment) {
   if (kind === "fillInBlanks") {
     return null;
   }
-  if (kind === "findHotspot" && assessment.kind === "findHotspot") {
-    return mcqToLxpack({
-      kind: "mcq",
-      checkId: assessment.checkId,
-      question: assessment.question,
-      choices: [assessment.correctTargetId, "other"],
-      answer: assessment.correctTargetId,
-      passingScore: assessment.passingScore
-    });
+  if (kind === "findHotspot") {
+    return null;
   }
   if (kind === "findMultipleHotspots") {
     return null;
@@ -604,6 +643,20 @@ function extractAssessments(descriptor) {
   return (descriptor.assessments ?? []).map(assessmentDescriptorToLxpack).filter((a) => a !== null);
 }
 
+// src/descriptor/validateInjectableAssessments.ts
+function validateInjectableAssessments(descriptor) {
+  const issues = [];
+  (descriptor.assessments ?? []).forEach((assessment, index) => {
+    if (assessmentDescriptorToLxpack(assessment) === null) {
+      issues.push({
+        path: `assessments[${index}]`,
+        message: `assessment kind "${assessment.kind ?? "mcq"}" (checkId "${assessment.checkId}") is not injected into LMS shell quizzes`
+      });
+    }
+  });
+  return issues;
+}
+
 // src/descriptor/validateForTarget.ts
 var LMS_SHELL_TARGETS = /* @__PURE__ */ new Set([
   "scorm12",
@@ -612,26 +665,34 @@ 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: "course.tracking.xapi.activityIri",
-        message: "tracking.xapi.activityIri is required for xapi and cmi5 export targets"
-      });
-    }
-  }
+  appendActivityIriIssues(issues, descriptor, target);
   if (LMS_SHELL_TARGETS.has(target)) {
-    (descriptor.assessments ?? []).forEach((assessment, index) => {
-      if (assessmentDescriptorToLxpack(assessment) === null) {
-        issues.push({
-          path: `assessments[${index}]`,
-          message: `assessment kind "${assessment.kind ?? "mcq"}" (checkId "${assessment.checkId}") is not injected into LMS shell quizzes for target "${target}"`
-        });
-      }
-    });
+    issues.push(...validateInjectableAssessments(descriptor).map((issue) => ({
+      ...issue,
+      message: `${issue.message} for target "${target}"`
+    })));
   }
   return issues;
 }
@@ -660,19 +721,53 @@ function validateDescriptorForTarget(input, target) {
 }
 
 // src/validateReactParity.ts
-import { readFileSync, existsSync as existsSync2, readdirSync, statSync } from "fs";
+import { readFileSync, existsSync as existsSync2, readdirSync, lstatSync } from "fs";
 import { join as join2, relative as relative2 } from "path";
 var SCANNABLE_EXTENSIONS = [".tsx", ".ts", ".jsx", ".js"];
-function collectSourceUnderSrc(projectRoot) {
+function collectSourceUnderSrc(projectRoot, issues) {
   const srcDir = join2(projectRoot, "src");
   if (!existsSync2(srcDir)) return [];
   const results = [];
   const walk = (dir) => {
     for (const entry of readdirSync(dir)) {
       const abs = join2(dir, entry);
-      if (statSync(abs).isDirectory()) {
+      let stat2;
+      try {
+        stat2 = lstatSync(abs);
+      } catch {
+        continue;
+      }
+      if (stat2.isSymbolicLink()) {
+        issues.push({
+          path: relative2(projectRoot, abs),
+          message: `Source tree contains symlink (rejected for parity scan): ${relative2(projectRoot, abs)}`,
+          severity: "error"
+        });
+        continue;
+      }
+      if (stat2.isDirectory()) {
+        try {
+          assertRealPathUnderRoot(projectRoot, abs);
+        } catch {
+          issues.push({
+            path: relative2(projectRoot, abs),
+            message: `Source directory escapes project root: ${relative2(projectRoot, abs)}`,
+            severity: "error"
+          });
+          continue;
+        }
         walk(abs);
       } else if (SCANNABLE_EXTENSIONS.some((ext) => entry.endsWith(ext))) {
+        try {
+          assertRealPathUnderRoot(projectRoot, abs);
+        } catch {
+          issues.push({
+            path: relative2(projectRoot, abs),
+            message: `Source file escapes project root: ${relative2(projectRoot, abs)}`,
+            severity: "error"
+          });
+          continue;
+        }
         results.push(relative2(projectRoot, abs));
       }
     }
@@ -680,20 +775,69 @@ function collectSourceUnderSrc(projectRoot) {
   walk(srcDir);
   return results;
 }
-function readAppSources(projectRoot, appSources) {
-  return appSources.map((rel) => join2(projectRoot, rel)).filter((abs) => existsSync2(abs)).map((abs) => 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 = join2(projectRoot, rel);
+    try {
+      assertRealPathUnderRoot(projectRoot, abs);
+      if (existsSync2(abs) && 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 (!existsSync2(abs)) return null;
+    return 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);
@@ -704,7 +848,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 = [
@@ -713,51 +859,93 @@ 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({
       path: "course.courseId",
-      message: `React app source does not reference courseId="${courseId}" from lessonkit.json`,
+      message: parityHint(
+        `React app source does not reference courseId="${courseId}" from lessonkit.json.`
+      ),
       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;
     if (!checkIdPresent(source, checkId)) {
       issues.push({
         path: `assessments.checkId:${checkId}`,
-        message: `React app source missing checkId="${checkId}" declared in lessonkit.json`,
+        message: parityHint(
+          `React app source missing checkId="${checkId}" declared in lessonkit.json.`
+        ),
         severity: "error"
       });
     }
@@ -767,7 +955,13 @@ function validateReactManifestParity(opts) {
 
 // src/validateProjectPaths.ts
 import { isAbsolute as isAbsolute2, resolve as resolve2 } from "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,
@@ -775,6 +969,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, resolve2(projectRoot, value));
   } catch {
@@ -791,10 +992,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;
 }
@@ -807,11 +1012,17 @@ function resolveSafePackageOutputOverride(projectRoot, override) {
   if (isAbsolute2(trimmed)) {
     const resolved2 = resolve2(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 = resolve2(root, trimmed);
   assertRealPathUnderRoot(root, resolved);
   return resolved;
@@ -888,7 +1099,7 @@ function descriptorToInterchange(descriptor) {
 }
 
 // src/writeProject.ts
-import { join as join4, resolve as resolve4 } from "path";
+import { join as join5, resolve as resolve4 } from "path";
 import { materializeLessonkitProject } from "@lxpack/validators";
 
 // src/spaDirs.ts
@@ -946,6 +1157,62 @@ async function resolveSpaDirs(options) {
   return dirs;
 }
 
+// src/spaDistValidation.ts
+import { lstat, readdir } from "fs/promises";
+import { realpathSync as realpathSync2 } from "fs";
+import { join as join4 } from "path";
+async function assertSpaDistContentsSafe(spaDirs, projectRoot) {
+  for (const [label, dir] of Object.entries(spaDirs)) {
+    const dirResolved = resolveComparablePath(dir);
+    const dirStat = await lstat(dirResolved);
+    if (dirStat.isSymbolicLink()) {
+      throw new Error(`spa dist for "${label}" cannot be a symlink: ${dir}`);
+    }
+    let rootReal;
+    try {
+      rootReal = realpathSync2(dirResolved);
+    } catch {
+      throw new Error(`spa dist for "${label}" is not readable: ${dir}`);
+    }
+    if (projectRoot) {
+      assertRealPathUnderRoot(projectRoot, dir);
+    }
+    assertResolvedPathUnderRoot(rootReal, rootReal);
+    await walkDistDir(rootReal, rootReal, label);
+  }
+}
+async function walkDistDir(rootReal, current, label) {
+  let entries;
+  try {
+    entries = await readdir(current, { withFileTypes: true });
+  } catch (err) {
+    throw new Error(
+      `spa dist for "${label}" is not readable: ${err instanceof Error ? err.message : String(err)}`,
+      { cause: err }
+    );
+  }
+  for (const entry of entries) {
+    const entryPath = join4(current, entry.name);
+    const stat2 = await lstat(entryPath);
+    if (stat2.isSymbolicLink()) {
+      throw new Error(`spa dist for "${label}" contains symlink: ${entryPath}`);
+    }
+    let entryReal;
+    try {
+      entryReal = realpathSync2(entryPath);
+    } catch (err) {
+      throw new Error(
+        `spa dist for "${label}" could not resolve path: ${entryPath}`,
+        { cause: err }
+      );
+    }
+    assertResolvedPathUnderRoot(rootReal, entryReal);
+    if (stat2.isDirectory()) {
+      await walkDistDir(rootReal, entryPath, label);
+    }
+  }
+}
+
 // src/writeProject.ts
 async function writeLxpackProject(options) {
   const validation = validateDescriptor(options.descriptor);
@@ -955,11 +1222,14 @@ async function writeLxpackProject(options) {
     );
   }
   const descriptor = validation.descriptor;
-  const outDir = resolve4(options.outDir);
-  if (options.projectRoot) {
-    assertRealPathUnderRoot(resolve4(options.projectRoot), outDir);
+  const injectableIssues = validateInjectableAssessments(descriptor);
+  if (injectableIssues.length > 0) {
+    throw new Error(injectableIssues.map((i) => `${i.path}: ${i.message}`).join("; "));
   }
+  const outDir = resolve4(options.outDir);
+  assertRealPathUnderRoot(resolve4(options.projectRoot), outDir);
   const spaDirs = await resolveSpaDirs({ ...options, descriptor });
+  await assertSpaDistContentsSafe(spaDirs, options.projectRoot);
   const interchange = descriptorToInterchange(descriptor);
   const materialized = await materializeLessonkitProject({
     interchange,
@@ -975,8 +1245,8 @@ async function writeLxpackProject(options) {
   const courseDir = materialized.courseDir;
   return {
     outDir: courseDir,
-    courseYamlPath: join4(courseDir, "course.yaml"),
-    lessonkitJsonPath: join4(courseDir, "lessonkit.json")
+    courseYamlPath: join5(courseDir, "course.yaml"),
+    lessonkitJsonPath: join5(courseDir, "lessonkit.json")
   };
 }
 
@@ -989,7 +1259,7 @@ import {
 } from "@lxpack/api";
 
 // src/packaging/validateInputs.ts
-import { isAbsolute as isAbsolute3, join as join5, resolve as resolve5, win32 as win322 } from "path";
+import { isAbsolute as isAbsolute3, join as join6, resolve as resolve5, win32 as win322 } from "path";
 function validatePackageInputs(options) {
   const { target, output, outputBaseDir } = options;
   const outDir = resolve5(options.outDir);
@@ -1126,13 +1396,13 @@ function remapArtifactPaths(stagingRoot, outDir, artifactPath) {
   if (/^[a-zA-Z]:[/\\]/.test(outDir)) {
     return win322.join(outDir, rel.replace(/\//g, win322.sep));
   }
-  return join5(outDir, rel);
+  return join6(outDir, rel);
 }
 
 // src/packaging/promote.ts
 import * as fsp from "fs/promises";
 import { createHash, randomUUID } from "crypto";
-import { dirname, join as join6, resolve as resolve6 } from "path";
+import { dirname, join as join7, resolve as resolve6 } from "path";
 async function pathExists(path) {
   try {
     await fsp.access(path);
@@ -1154,23 +1424,38 @@ async function renameOrCopy(from, to) {
 function promoteLockPath(outDir) {
   const parent = dirname(outDir);
   const hash = createHash("sha256").update(resolve6(outDir)).digest("hex").slice(0, 16);
-  return join6(parent, `.lk-promote-lock-${hash}`);
+  return join7(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;
   }
@@ -1183,6 +1468,8 @@ async function withPromoteLock(outDir, fn) {
     try {
       lockHandle = await fsp.open(lockPath, "wx");
       await lockHandle.writeFile(`${process.pid}
+${randomUUID()}
+${Date.now()}
 `, "utf8");
       break;
     } catch (err) {
@@ -1214,26 +1501,81 @@ 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 = join7(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 = join7(priorArtifactsDir, rel);
+    const dest = join7(destArtifactsDir, rel);
+    await fsp.mkdir(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(resolve6(options.projectRoot), resolve6(outDir));
+  }
   return withPromoteLock(outDir, async () => {
-    await assertNoLegacyPromoteArtifacts(outDir);
+    await removeStaleLegacyPromoteArtifacts(outDir);
+    const stagingArtifactsDir = join7(stagingDir, outputBaseDir);
+    const newArtifactPaths = /* @__PURE__ */ new Set();
+    if (await pathExists(stagingArtifactsDir)) {
+      for (const rel of await listRelativePaths(stagingArtifactsDir)) {
+        newArtifactPaths.add(rel);
+      }
+    }
     const parent = dirname(outDir);
-    const tmpPromote = await fsp.mkdtemp(join6(parent, ".lk-promote-"));
+    let priorArtifactsBackup;
+    const existingArtifactsDir = join7(outDir, outputBaseDir);
+    if (await pathExists(outDir) && await pathExists(existingArtifactsDir)) {
+      priorArtifactsBackup = await fsp.mkdtemp(join7(parent, ".lk-prior-out-"));
+      await fsp.cp(existingArtifactsDir, join7(priorArtifactsBackup, outputBaseDir), { recursive: true });
+    }
+    const tmpPromote = await fsp.mkdtemp(join7(parent, ".lk-promote-"));
     await renameOrCopy(stagingDir, tmpPromote);
     const hadOutDir = await pathExists(outDir);
-    const backup = hadOutDir ? await fsp.mkdtemp(join6(parent, ".lk-backup-")) : void 0;
+    const backup = hadOutDir ? await fsp.mkdtemp(join7(parent, ".lk-backup-")) : void 0;
     if (hadOutDir && backup) {
       await renameOrCopy(outDir, backup);
     }
@@ -1244,7 +1586,7 @@ async function promoteStagingToOutDir(stagingDir, outDir) {
         try {
           await renameOrCopy(backup, outDir);
         } catch (restoreError) {
-          const failedPromote2 = join6(parent, `.lk-failed-promote-${randomUUID()}`);
+          const failedPromote2 = join7(parent, `.lk-failed-promote-${randomUUID()}`);
           try {
             await renameOrCopy(tmpPromote, failedPromote2);
           } catch {
@@ -1256,7 +1598,8 @@ async function promoteStagingToOutDir(stagingDir, outDir) {
           const promoteMsg = promoteError instanceof Error ? promoteError.message : String(promoteError);
           const restoreMsg = restoreError instanceof Error ? restoreError.message : String(restoreError);
           throw new Error(
-            `[lessonkit/lxpack] promote failed (${promoteMsg}) and could not restore ${outDir} (${restoreMsg}). Recovery: previous output may be in ${backup}; staged package may be in ${failedPromote2}.`
+            `[lessonkit/lxpack] promote failed (${promoteMsg}) and could not restore ${outDir} (${restoreMsg}). Recovery: previous output may be in ${backup}; staged package may be in ${failedPromote2}.`,
+            { cause: restoreError }
           );
         }
       } else {
@@ -1274,7 +1617,7 @@ async function promoteStagingToOutDir(stagingDir, outDir) {
         }
         throw promoteError;
       }
-      const failedPromote = join6(parent, `.lk-failed-promote-${randomUUID()}`);
+      const failedPromote = join7(parent, `.lk-failed-promote-${randomUUID()}`);
       try {
         await renameOrCopy(tmpPromote, failedPromote);
       } catch {
@@ -1285,6 +1628,20 @@ async function promoteStagingToOutDir(stagingDir, outDir) {
       }
       throw promoteError;
     }
+    if (priorArtifactsBackup) {
+      try {
+        await mergePreservedOutArtifacts(
+          join7(priorArtifactsBackup, outputBaseDir),
+          join7(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 */
@@ -1296,16 +1653,18 @@ async function promoteStagingToOutDir(stagingDir, outDir) {
 
 // src/packaging/staging.ts
 import * as fsp2 from "fs/promises";
-import { dirname as dirname2, join as join7 } from "path";
+import { dirname as dirname2, join as join8 } from "path";
 import { tmpdir } from "os";
 import { packageLessonkit } from "@lxpack/api";
 async function buildStagingPackage(options) {
   const { target, output, dir, outputBaseDir, descriptor, ...writeOpts } = options;
-  const stagingDir = await fsp2.mkdtemp(join7(tmpdir(), "lessonkit-lxpack-"));
+  const stagingDir = await fsp2.mkdtemp(join8(tmpdir(), "lessonkit-lxpack-"));
+  let succeeded = false;
   try {
     let spaDirs;
     try {
       spaDirs = await resolveSpaDirs({ ...writeOpts, descriptor });
+      await assertSpaDistContentsSafe(spaDirs, writeOpts.projectRoot);
     } catch (err) {
       return {
         ok: false,
@@ -1318,10 +1677,21 @@ async function buildStagingPackage(options) {
         ]
       };
     }
+    const injectableIssues = validateInjectableAssessments(descriptor);
+    if (injectableIssues.length > 0) {
+      return {
+        ok: false,
+        stagingDir,
+        issues: injectableIssues.map((i) => ({
+          path: i.path,
+          message: i.message
+        }))
+      };
+    }
     const interchange = descriptorToInterchange(descriptor);
     const outputBase = outputBaseDir ?? ".lxpack/out";
-    await fsp2.mkdir(join7(stagingDir, outputBase), { recursive: true });
-    const defaultOutput = output ?? (dir ? join7(outputBase, target) : join7(outputBase, `course-${target}.zip`));
+    await fsp2.mkdir(join8(stagingDir, outputBase), { recursive: true });
+    const defaultOutput = output ?? (dir ? join8(outputBase, target) : join8(outputBase, `course-${target}.zip`));
     const build = await packageLessonkit({
       interchange,
       spaDirs,
@@ -1345,6 +1715,7 @@ async function buildStagingPackage(options) {
         }))
       };
     }
+    succeeded = true;
     return {
       ok: true,
       stagingDir,
@@ -1358,6 +1729,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) {
@@ -1422,34 +1800,20 @@ 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 nonInjectableAssessments = (descriptor.assessments ?? []).map((assessment, index) => ({ assessment, index })).filter(({ assessment }) => assessmentDescriptorToLxpack(assessment) === null);
-  if (nonInjectableAssessments.length > 0) {
+  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: nonInjectableAssessments.map(({ assessment, index }) => ({
-        path: `assessments[${index}]`,
-        message: `assessment kind "${assessment.kind ?? "mcq"}" (checkId "${assessment.checkId}") is not injected into LMS shell quizzes for target "${target}"`
+      issues: parityFailures.map((i) => ({
+        path: i.path,
+        message: i.message,
+        severity: i.severity
       }))
     };
   }
@@ -1510,7 +1874,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
     };
@@ -1524,7 +1888,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 */
@@ -1647,6 +2014,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) {
@@ -1691,6 +2072,7 @@ export {
   buildStagingPackage,
   descriptorToInterchange,
   ensureOutDirParent,
+  escapeShellText,
   extractAssessments,
   lessonkitInterchangeSchema,
   loadLessonkitManifestFromFile,