@lessonkit/lxpack 1.4.0 → 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";
@@ -344,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) => {
@@ -543,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
       }
     ]
@@ -623,22 +665,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,
@@ -672,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));
       }
     }
@@ -692,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);
@@ -716,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 = [
@@ -725,40 +859,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({
@@ -769,6 +924,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;
@@ -787,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,
@@ -795,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 {
@@ -811,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;
 }
@@ -827,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;
@@ -1009,8 +1200,11 @@ async function walkDistDir(rootReal, current, label) {
     let entryReal;
     try {
       entryReal = realpathSync2(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()) {
@@ -1033,9 +1227,7 @@ async function writeLxpackProject(options) {
     throw new Error(injectableIssues.map((i) => `${i.path}: ${i.message}`).join("; "));
   }
   const outDir = resolve4(options.outDir);
-  if (options.projectRoot) {
-    assertRealPathUnderRoot(resolve4(options.projectRoot), outDir);
-  }
+  assertRealPathUnderRoot(resolve4(options.projectRoot), outDir);
   const spaDirs = await resolveSpaDirs({ ...options, descriptor });
   await assertSpaDistContentsSafe(spaDirs, options.projectRoot);
   const interchange = descriptorToInterchange(descriptor);
@@ -1234,21 +1426,36 @@ function promoteLockPath(outDir) {
   const hash = createHash("sha256").update(resolve6(outDir)).digest("hex").slice(0, 16);
   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;
   }
@@ -1261,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) {
@@ -1292,22 +1501,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 = 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);
+    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);
@@ -1364,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 */
@@ -1381,6 +1659,7 @@ import { packageLessonkit } from "@lxpack/api";
 async function buildStagingPackage(options) {
   const { target, output, dir, outputBaseDir, descriptor, ...writeOpts } = options;
   const stagingDir = await fsp2.mkdtemp(join8(tmpdir(), "lessonkit-lxpack-"));
+  let succeeded = false;
   try {
     let spaDirs;
     try {
@@ -1436,6 +1715,7 @@ async function buildStagingPackage(options) {
         }))
       };
     }
+    succeeded = true;
     return {
       ok: true,
       stagingDir,
@@ -1449,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) {
@@ -1513,24 +1800,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,
@@ -1589,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
     };
@@ -1603,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 */
@@ -1726,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) {
@@ -1770,6 +2072,7 @@ export {
   buildStagingPackage,
   descriptorToInterchange,
   ensureOutDirParent,
+  escapeShellText,
   extractAssessments,
   lessonkitInterchangeSchema,
   loadLessonkitManifestFromFile,