@lessonkit/lxpack 0.9.3 → 1.0.1

package/dist/index.cjs

@@ -33,21 +33,29 @@ __export(index_exports, {
   LESSONKIT_TELEMETRY_EVENTS: () => import_tracking_schema2.LESSONKIT_TELEMETRY_EVENTS,
   assessmentDescriptorToLxpack: () => assessmentDescriptorToLxpack,
   buildLessonkitProject: () => buildLessonkitProject,
+  buildStagingPackage: () => buildStagingPackage,
   descriptorToInterchange: () => descriptorToInterchange,
+  ensureOutDirParent: () => ensureOutDirParent,
   extractAssessments: () => extractAssessments,
   lessonkitInterchangeSchema: () => import_validators2.lessonkitInterchangeSchema,
+  loadLessonkitManifestFromFile: () => loadLessonkitManifestFromFile,
   mapLessonkitIds: () => mapLessonkitIds,
   mapLessonkitTelemetryToBridgeAction: () => import_tracking_schema2.mapLessonkitTelemetryToBridgeAction,
   mapLessonkitTelemetryToLxpack: () => import_tracking_schema2.mapLessonkitTelemetryToLxpack,
   materializeLessonkitProject: () => import_validators2.materializeLessonkitProject,
   packageLessonkitCourse: () => packageLessonkitCourse,
   parseLessonkitInterchange: () => import_validators2.parseLessonkitInterchange,
+  parseLessonkitManifest: () => parseLessonkitManifest,
+  promoteStagingToOutDir: () => promoteStagingToOutDir,
+  remapArtifactPaths: () => remapArtifactPaths,
   resolveSafePackageOutputOverride: () => resolveSafePackageOutputOverride,
   resolveSpaLessons: () => resolveSpaLessons,
   telemetryEventToLessonkit: () => telemetryEventToLessonkit,
   themeToLxpackRuntime: () => themeToLxpackRuntime,
   validateDescriptor: () => validateDescriptor,
+  validateDescriptorForTarget: () => validateDescriptorForTarget,
   validateLessonkitProject: () => validateLessonkitProject,
+  validatePackageInputs: () => validatePackageInputs,
   validateProjectPaths: () => validateProjectPaths,
   writeLxpackProject: () => writeLxpackProject
 });
@@ -57,23 +65,73 @@ module.exports = __toCommonJS(index_exports);
 var import_core = require("@lessonkit/core");
 
 // src/spaPath.ts
+var import_node_fs = require("fs");
 var import_node_path = require("path");
+function resolveComparablePath(p) {
+  if (/^[a-zA-Z]:[/\\]/.test(p)) {
+    return import_node_path.win32.resolve(p);
+  }
+  return (0, import_node_path.resolve)(p);
+}
 function isSafeRelativeSpaPath(spaPath) {
   if (!spaPath.length || spaPath.includes("\0")) return false;
   if (spaPath.startsWith("/") || spaPath.startsWith("\\")) return false;
-  if (/^[a-zA-Z]:[/\\]/.test(spaPath)) return false;
-  const segments = spaPath.split(/[/\\]/).filter((s) => s.length > 0);
+  if (/^[a-zA-Z]:/.test(spaPath)) return false;
+  if (spaPath === "." || spaPath === "./") return false;
+  const segments = spaPath.split(/[/\\]/).filter((s) => s.length > 0 && s !== ".");
   if (segments.some((s) => s === "..")) return false;
-  return true;
+  return segments.length > 0;
 }
 function assertResolvedPathUnderRoot(root, target) {
-  const rootResolved = (0, import_node_path.resolve)(root);
-  const targetResolved = (0, import_node_path.resolve)(target);
+  const rootResolved = resolveComparablePath(root);
+  const targetResolved = resolveComparablePath(target);
   const prefix = rootResolved.endsWith(import_node_path.sep) ? rootResolved : rootResolved + import_node_path.sep;
-  if (targetResolved !== rootResolved && !targetResolved.startsWith(prefix)) {
+  const win32Prefix = rootResolved.endsWith(import_node_path.win32.sep) ? rootResolved : rootResolved + import_node_path.win32.sep;
+  if (targetResolved !== rootResolved && !targetResolved.startsWith(prefix) && !targetResolved.startsWith(win32Prefix)) {
     throw new Error(`unsafe path escapes project root: ${target}`);
   }
 }
+function assertRealPathUnderRoot(root, target) {
+  const rootResolved = resolveComparablePath(root);
+  const targetResolved = resolveComparablePath(target);
+  let rootReal;
+  try {
+    rootReal = (0, import_node_fs.realpathSync)(rootResolved);
+  } catch {
+    rootReal = rootResolved;
+  }
+  let targetCheck;
+  try {
+    targetCheck = (0, import_node_fs.realpathSync)(targetResolved);
+  } catch {
+    const rel = (0, import_node_path.relative)(rootResolved, targetResolved);
+    if (rel.startsWith("..") || rel.includes(`..${import_node_path.sep}`)) {
+      throw new Error(`unsafe path escapes project root: ${target}`);
+    }
+    targetCheck = (0, import_node_path.resolve)(rootReal, rel);
+  }
+  assertResolvedPathUnderRoot(rootReal, targetCheck);
+}
+function normalizePathForComparison(p) {
+  const resolved = resolveComparablePath(p);
+  return /^[a-zA-Z]:[/\\]/.test(resolved) ? resolved.toLowerCase() : resolved;
+}
+function relativePathUnderRoot(root, target) {
+  const rootResolved = normalizePathForComparison(root);
+  const targetResolved = normalizePathForComparison(target);
+  if (/^[a-zA-Z]:[/\\]/.test(rootResolved)) {
+    return import_node_path.win32.relative(rootResolved, targetResolved);
+  }
+  return (0, import_node_path.relative)(rootResolved, targetResolved);
+}
+function isResolvedPathUnderRoot(root, target) {
+  const rootResolved = normalizePathForComparison(root);
+  const targetResolved = normalizePathForComparison(target);
+  if (targetResolved === rootResolved) return true;
+  const rel = relativePathUnderRoot(root, target);
+  if (!rel) return true;
+  return !rel.startsWith("..") && !(0, import_node_path.isAbsolute)(rel);
+}
 
 // src/theme.ts
 var import_themes = require("@lessonkit/themes");
@@ -93,6 +151,70 @@ function themeToLxpackRuntime(input) {
 // src/validateDescriptor.ts
 var VALID_LAYOUTS = ["single-spa", "per-lesson-spa"];
 var VALID_THEME_PRESETS = ["default", "light", "dark", "brand"];
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseLessonDescriptor(raw) {
+  if (!isRecord(raw)) {
+    return { id: "", title: "" };
+  }
+  return {
+    id: typeof raw.id === "string" ? raw.id : "",
+    title: typeof raw.title === "string" ? raw.title : "",
+    spaPath: typeof raw.spaPath === "string" ? raw.spaPath : void 0
+  };
+}
+function parseAssessmentDescriptor(raw) {
+  if (!isRecord(raw)) {
+    return { checkId: "", question: "", choices: [], answer: "" };
+  }
+  return {
+    checkId: typeof raw.checkId === "string" ? raw.checkId : "",
+    question: typeof raw.question === "string" ? raw.question : "",
+    choices: Array.isArray(raw.choices) ? raw.choices.filter((c) => typeof c === "string") : [],
+    answer: typeof raw.answer === "string" ? raw.answer : "",
+    passingScore: typeof raw.passingScore === "number" ? raw.passingScore : void 0
+  };
+}
+function parseCourseDescriptorInput(input) {
+  if (!isRecord(input)) return null;
+  const trackingRaw = input.tracking;
+  let tracking;
+  if (isRecord(trackingRaw)) {
+    const completionRaw = trackingRaw.completion;
+    const xapiRaw = trackingRaw.xapi;
+    tracking = {
+      completion: isRecord(completionRaw) ? {
+        threshold: typeof completionRaw.threshold === "number" ? completionRaw.threshold : void 0
+      } : void 0,
+      xapi: isRecord(xapiRaw) ? {
+        activityIri: typeof xapiRaw.activityIri === "string" ? xapiRaw.activityIri : void 0
+      } : void 0
+    };
+  }
+  const themeRaw = input.theme;
+  let theme;
+  if (isRecord(themeRaw)) {
+    theme = {
+      preset: typeof themeRaw.preset === "string" ? themeRaw.preset : void 0
+    };
+    if (isRecord(themeRaw.theme)) {
+      theme.theme = themeRaw.theme;
+    }
+  }
+  return {
+    courseId: typeof input.courseId === "string" ? input.courseId : "",
+    title: typeof input.title === "string" ? input.title : "",
+    version: typeof input.version === "string" ? input.version : void 0,
+    layout: typeof input.layout === "string" ? input.layout : void 0,
+    lessons: Array.isArray(input.lessons) ? input.lessons.map(parseLessonDescriptor) : [],
+    assessments: Array.isArray(input.assessments) ? input.assessments.map(parseAssessmentDescriptor) : void 0,
+    theme,
+    tracking,
+    spaDistDir: typeof input.spaDistDir === "string" ? input.spaDistDir : void 0,
+    spaLessonId: typeof input.spaLessonId === "string" ? input.spaLessonId : void 0
+  };
+}
 function normalizeDescriptor(input) {
   const course = (0, import_core.validateId)(input.courseId, "courseId");
   if (!course.ok) throw new Error("normalizeDescriptor called with invalid courseId");
@@ -126,6 +248,31 @@ function normalizeDescriptor(input) {
   };
 }
 function validateDescriptor(input) {
+  const parsed = parseCourseDescriptorInput(input);
+  if (parsed === null) {
+    return { ok: false, issues: [{ path: "course", message: "must be an object" }] };
+  }
+  return validateDescriptorParsed(parsed);
+}
+function validateDescriptorForTarget(input, target) {
+  const result = validateDescriptor(input);
+  if (!result.ok || !target) return result;
+  if (target !== "xapi" && target !== "cmi5") return result;
+  const activityIri = result.descriptor.tracking?.xapi?.activityIri?.trim();
+  if (!activityIri) {
+    return {
+      ok: false,
+      issues: [
+        {
+          path: "course.tracking.xapi.activityIri",
+          message: "tracking.xapi.activityIri is required for xapi and cmi5 export targets"
+        }
+      ]
+    };
+  }
+  return result;
+}
+function validateDescriptorParsed(input) {
   const issues = [];
   const course = (0, import_core.validateId)(input.courseId, "courseId");
   if (!course.ok) issues.push(...course.issues.map((i) => ({ path: i.path, message: i.message })));
@@ -249,7 +396,7 @@ function validateDescriptor(input) {
       issues.push({ path: `${path}.answer`, message: "answer must match a choice" });
     }
     const passingScore = assessment.passingScore;
-    if (passingScore !== void 0 && !(passingScore > 0)) {
+    if (passingScore !== void 0 && !(Number.isFinite(passingScore) && passingScore > 0)) {
       issues.push({
         path: `${path}.passingScore`,
         message: "passingScore must be greater than 0 (absolute point threshold)"
@@ -271,7 +418,7 @@ function validatePathField(value, fieldPath, projectRoot, issues) {
     return;
   }
   try {
-    assertResolvedPathUnderRoot(projectRoot, (0, import_node_path2.resolve)(projectRoot, value));
+    assertRealPathUnderRoot(projectRoot, (0, import_node_path2.resolve)(projectRoot, value));
   } catch {
     issues.push({
       path: fieldPath,
@@ -301,14 +448,14 @@ function resolveSafePackageOutputOverride(projectRoot, override) {
   }
   if ((0, import_node_path2.isAbsolute)(trimmed)) {
     const resolved2 = (0, import_node_path2.resolve)(trimmed);
-    assertResolvedPathUnderRoot(root, resolved2);
+    assertRealPathUnderRoot(root, resolved2);
     return resolved2;
   }
   if (!isSafeRelativeSpaPath(trimmed)) {
     throw new Error(`unsafe output path: ${override}`);
   }
   const resolved = (0, import_node_path2.resolve)(root, trimmed);
-  assertResolvedPathUnderRoot(root, resolved);
+  assertRealPathUnderRoot(root, resolved);
   return resolved;
 }
 
@@ -355,6 +502,18 @@ function extractAssessments(descriptor) {
 }
 
 // src/interchange.ts
+function mapDescriptorTracking(tracking) {
+  if (!tracking) return void 0;
+  const mapped = {};
+  if (tracking.completion?.threshold !== void 0) {
+    mapped.completion = { threshold: tracking.completion.threshold };
+  }
+  const activityIri = tracking.xapi?.activityIri?.trim();
+  if (activityIri) {
+    mapped.xapi = { activityIri };
+  }
+  return Object.keys(mapped).length > 0 ? mapped : void 0;
+}
 function resolveSpaLessons(descriptor) {
   const mapped = mapLessonkitIds(descriptor);
   if (descriptor.layout === "single-spa") {
@@ -392,7 +551,7 @@ function descriptorToInterchange(descriptor) {
       type: "spa",
       path: l.path
     })),
-    tracking: descriptor.tracking,
+    tracking: mapDescriptorTracking(descriptor.tracking),
     runtime: runtime ? {
       theme: runtime.theme,
       cssVariables: runtime.cssVariables
@@ -415,13 +574,18 @@ async function resolveSpaDirs(options) {
     const spaDistRelative = spaDistDir ?? descriptor.spaDistDir ?? "dist";
     const srcDist = projectRoot ? (0, import_node_path3.resolve)(projectRoot, spaDistRelative) : (0, import_node_path3.resolve)(spaDistRelative);
     if (projectRoot) {
-      assertResolvedPathUnderRoot((0, import_node_path3.resolve)(projectRoot), srcDist);
+      assertRealPathUnderRoot((0, import_node_path3.resolve)(projectRoot), srcDist);
     }
     try {
       await (0, import_promises.access)(srcDist);
     } catch {
       throw new Error(`spaDistDir not found: ${srcDist}`);
     }
+    try {
+      await (0, import_promises.access)((0, import_node_path3.join)(srcDist, "index.html"));
+    } catch {
+      throw new Error(`spaDistDir must contain index.html: ${(0, import_node_path3.join)(srcDist, "index.html")}`);
+    }
     const lessonId = spaLessons[0]?.id ?? "main";
     return { [lessonId]: srcDist };
   }
@@ -434,7 +598,19 @@ async function resolveSpaDirs(options) {
     }
     const resolved = projectRoot ? (0, import_node_path3.resolve)(projectRoot, src) : (0, import_node_path3.resolve)(src);
     if (projectRoot) {
-      assertResolvedPathUnderRoot((0, import_node_path3.resolve)(projectRoot), resolved);
+      assertRealPathUnderRoot((0, import_node_path3.resolve)(projectRoot), resolved);
+    }
+    try {
+      await (0, import_promises.access)(resolved);
+    } catch {
+      throw new Error(`lessonSpaDirs path not found for lesson "${lesson.id}": ${resolved}`);
+    }
+    try {
+      await (0, import_promises.access)((0, import_node_path3.join)(resolved, "index.html"));
+    } catch {
+      throw new Error(
+        `lessonSpaDirs must contain index.html for lesson "${lesson.id}": ${(0, import_node_path3.join)(resolved, "index.html")}`
+      );
     }
     dirs[lesson.id] = resolved;
   }
@@ -452,7 +628,7 @@ async function writeLxpackProject(options) {
   const descriptor = validation.descriptor;
   const outDir = (0, import_node_path4.resolve)(options.outDir);
   if (options.projectRoot) {
-    assertResolvedPathUnderRoot((0, import_node_path4.resolve)(options.projectRoot), outDir);
+    assertRealPathUnderRoot((0, import_node_path4.resolve)(options.projectRoot), outDir);
   }
   const spaDirs = await resolveSpaDirs({ ...options, descriptor });
   const interchange = descriptorToInterchange(descriptor);
@@ -476,68 +652,27 @@ async function writeLxpackProject(options) {
 }
 
 // src/packageCourse.ts
-var fsp = __toESM(require("fs/promises"), 1);
+var import_node_path8 = require("path");
+var fsp3 = __toESM(require("fs/promises"), 1);
+var import_api2 = require("@lxpack/api");
+
+// src/packaging/validateInputs.ts
 var import_node_path5 = require("path");
-var import_node_os = require("os");
-var import_api = require("@lxpack/api");
-async function validateLessonkitProject(options) {
-  return (0, import_api.validateCourse)({
-    courseDir: (0, import_node_path5.resolve)(options.courseDir),
-    target: options.target
-  });
-}
-async function buildLessonkitProject(options) {
-  return (0, import_api.buildCourse)({
-    courseDir: (0, import_node_path5.resolve)(options.courseDir),
-    target: options.target,
-    output: options.output,
-    dir: options.dir,
-    outputBaseDir: options.outputBaseDir,
-    assessments: options.assessments
-  });
-}
-async function pathExists(path) {
-  try {
-    await fsp.access(path);
-    return true;
-  } catch {
-    return false;
-  }
-}
-async function promoteStagingToOutDir(stagingDir, outDir) {
-  const tmpPromote = `${outDir}.tmp-promote`;
-  const backup = `${outDir}.bak`;
-  await fsp.rename(stagingDir, tmpPromote);
-  const hadOutDir = await pathExists(outDir);
-  if (hadOutDir) {
-    await fsp.rename(outDir, backup);
-  }
-  try {
-    await fsp.rename(tmpPromote, outDir);
-  } catch (promoteError) {
-    if (hadOutDir) {
-      try {
-        await fsp.rename(backup, outDir);
-      } catch (restoreError) {
-        console.warn(
-          `[lessonkit/lxpack] failed to restore ${outDir} after promote error:`,
-          restoreError instanceof Error ? restoreError.message : restoreError
-        );
-      }
-    }
-    await fsp.rm(tmpPromote, { recursive: true, force: true }).catch(() => void 0);
-    throw promoteError;
-  }
-  if (hadOutDir) {
-    await fsp.rm(backup, { recursive: true, force: true }).catch(() => void 0);
-  }
-}
-async function packageLessonkitCourse(options) {
-  const { target, output, dir, outputBaseDir, ...writeOpts } = options;
-  const outDir = (0, import_node_path5.resolve)(writeOpts.outDir);
-  const projectRoot = writeOpts.projectRoot ? (0, import_node_path5.resolve)(writeOpts.projectRoot) : void 0;
+function validatePackageInputs(options) {
+  const { target, output, outputBaseDir } = options;
+  const outDir = (0, import_node_path5.resolve)(options.outDir);
+  const projectRoot = options.projectRoot ? (0, import_node_path5.resolve)(options.projectRoot) : void 0;
   if (projectRoot) {
-    assertResolvedPathUnderRoot(projectRoot, outDir);
+    try {
+      assertRealPathUnderRoot(projectRoot, outDir);
+    } catch (err) {
+      return {
+        ok: false,
+        courseDir: outDir,
+        target,
+        issues: [{ path: "outDir", message: err instanceof Error ? err.message : String(err) }]
+      };
+    }
   }
   if (outputBaseDir && !isSafeRelativeSpaPath(outputBaseDir)) {
     return {
@@ -547,10 +682,18 @@ async function packageLessonkitCourse(options) {
       issues: [{ path: "outputBaseDir", message: `unsafe outputBaseDir: ${outputBaseDir}` }]
     };
   }
-  if (projectRoot && output) {
-    const resolvedOutput = (0, import_node_path5.resolve)(projectRoot, output);
+  if (output && !projectRoot && !isSafeRelativeSpaPath(output)) {
+    return {
+      ok: false,
+      courseDir: outDir,
+      target,
+      issues: [{ path: "output", message: `unsafe output: ${output}` }]
+    };
+  }
+  if (projectRoot && outputBaseDir) {
+    const resolvedOutputBase = (0, import_node_path5.resolve)(projectRoot, outputBaseDir);
     try {
-      assertResolvedPathUnderRoot(projectRoot, resolvedOutput);
+      assertRealPathUnderRoot(projectRoot, resolvedOutputBase);
     } catch (err) {
       return {
         ok: false,
@@ -558,28 +701,152 @@ async function packageLessonkitCourse(options) {
         target,
         issues: [
           {
-            path: "output",
+            path: "outputBaseDir",
             message: err instanceof Error ? err.message : String(err)
           }
         ]
       };
     }
   }
-  const descriptorValidation = validateDescriptor(writeOpts.descriptor);
-  if (!descriptorValidation.ok) {
+  if (projectRoot && output) {
+    const resolvedOutput = (0, import_node_path5.resolve)(projectRoot, output);
+    try {
+      assertRealPathUnderRoot(projectRoot, resolvedOutput);
+    } catch (err) {
+      return {
+        ok: false,
+        courseDir: outDir,
+        target,
+        issues: [{ path: "output", message: err instanceof Error ? err.message : String(err) }]
+      };
+    }
+  }
+  return { ok: true, outDir, projectRoot };
+}
+function validateArtifactInStaging(stagingRoot, artifactPath, field) {
+  if (!artifactPath) return null;
+  const resolved = resolveComparablePath(artifactPath);
+  if (!isResolvedPathUnderRoot(stagingRoot, resolved)) {
     return {
-      ok: false,
-      courseDir: outDir,
-      target,
-      issues: descriptorValidation.issues.map((i) => ({
-        path: i.path,
-        message: i.message
-      }))
+      path: field,
+      message: `${field} is outside the staging directory: ${artifactPath}`
     };
   }
-  const descriptor = descriptorValidation.descriptor;
-  const stagingDir = await fsp.mkdtemp((0, import_node_path5.join)((0, import_node_os.tmpdir)(), "lessonkit-lxpack-"));
-  let promoted = false;
+  return null;
+}
+function remapArtifactPaths(stagingRoot, outDir, artifactPath) {
+  if (!artifactPath) return void 0;
+  const resolved = resolveComparablePath(artifactPath);
+  if (!isResolvedPathUnderRoot(stagingRoot, resolved)) {
+    return artifactPath;
+  }
+  const rel = relativePathUnderRoot(stagingRoot, resolved);
+  if (rel.startsWith("..") || (0, import_node_path5.isAbsolute)(rel)) {
+    return artifactPath;
+  }
+  if (!rel) return outDir;
+  if (/^[a-zA-Z]:[/\\]/.test(outDir)) {
+    return import_node_path5.win32.join(outDir, rel.replace(/\//g, import_node_path5.win32.sep));
+  }
+  return (0, import_node_path5.join)(outDir, rel);
+}
+
+// src/packaging/promote.ts
+var fsp = __toESM(require("fs/promises"), 1);
+var import_node_crypto = require("crypto");
+var import_node_path6 = require("path");
+async function pathExists(path) {
+  try {
+    await fsp.access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function renameOrCopy(from, to) {
+  try {
+    await fsp.rename(from, to);
+  } catch (err) {
+    const code = err && typeof err === "object" && "code" in err ? String(err.code) : "";
+    if (code !== "EXDEV") throw err;
+    await fsp.cp(from, to, { recursive: true });
+    await fsp.rm(from, { recursive: true, force: true });
+  }
+}
+async function assertNoLegacyPromoteArtifacts(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) {
+    throw new Error(
+      `[lessonkit/lxpack] cannot promote: remove stale packaging artifacts from a previous failed run: ${stale.join(", ")}`
+    );
+  }
+}
+async function promoteStagingToOutDir(stagingDir, outDir) {
+  await assertNoLegacyPromoteArtifacts(outDir);
+  const parent = (0, import_node_path6.dirname)(outDir);
+  const tmpPromote = await fsp.mkdtemp((0, import_node_path6.join)(parent, ".lk-promote-"));
+  await renameOrCopy(stagingDir, tmpPromote);
+  const hadOutDir = await pathExists(outDir);
+  const backup = hadOutDir ? await fsp.mkdtemp((0, import_node_path6.join)(parent, ".lk-backup-")) : void 0;
+  if (hadOutDir && backup) {
+    await renameOrCopy(outDir, backup);
+  }
+  try {
+    await renameOrCopy(tmpPromote, outDir);
+  } catch (promoteError) {
+    if (hadOutDir && backup) {
+      try {
+        await renameOrCopy(backup, outDir);
+      } catch (restoreError) {
+        const failedPromote2 = (0, import_node_path6.join)(parent, `.lk-failed-promote-${(0, import_node_crypto.randomUUID)()}`);
+        try {
+          await renameOrCopy(tmpPromote, failedPromote2);
+        } catch {
+          await fsp.rm(tmpPromote, { recursive: true, force: true }).catch(() => void 0);
+        }
+        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}.`
+        );
+      }
+    } else {
+      try {
+        await renameOrCopy(tmpPromote, stagingDir);
+      } catch (restoreError) {
+        console.warn(
+          `[lessonkit/lxpack] failed to restore ${stagingDir} after promote error:`,
+          restoreError instanceof Error ? restoreError.message : restoreError
+        );
+        await fsp.rm(tmpPromote, { recursive: true, force: true }).catch(() => void 0);
+      }
+      throw promoteError;
+    }
+    const failedPromote = (0, import_node_path6.join)(parent, `.lk-failed-promote-${(0, import_node_crypto.randomUUID)()}`);
+    try {
+      await renameOrCopy(tmpPromote, failedPromote);
+    } catch {
+      await fsp.rm(tmpPromote, { recursive: true, force: true }).catch(() => void 0);
+    }
+    throw promoteError;
+  }
+  if (backup) {
+    await fsp.rm(backup, { recursive: true, force: true }).catch(() => void 0);
+  }
+}
+
+// src/packaging/staging.ts
+var fsp2 = __toESM(require("fs/promises"), 1);
+var import_node_path7 = require("path");
+var import_node_os = require("os");
+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_path7.join)((0, import_node_os.tmpdir)(), "lessonkit-lxpack-"));
   try {
     let spaDirs;
     try {
@@ -587,8 +854,7 @@ async function packageLessonkitCourse(options) {
     } catch (err) {
       return {
         ok: false,
-        courseDir: outDir,
-        target,
+        stagingDir,
         issues: [
           {
             path: "spaDirs",
@@ -599,8 +865,8 @@ async function packageLessonkitCourse(options) {
     }
     const interchange = descriptorToInterchange(descriptor);
     const outputBase = outputBaseDir ?? ".lxpack/out";
-    await fsp.mkdir((0, import_node_path5.join)(stagingDir, outputBase), { recursive: true });
-    const defaultOutput = output ?? (dir ? (0, import_node_path5.join)(outputBase, target) : (0, import_node_path5.join)(outputBase, `course-${target}.zip`));
+    await fsp2.mkdir((0, import_node_path7.join)(stagingDir, outputBase), { recursive: true });
+    const defaultOutput = output ?? (dir ? (0, import_node_path7.join)(outputBase, target) : (0, import_node_path7.join)(outputBase, `course-${target}.zip`));
     const build = await (0, import_api.packageLessonkit)({
       interchange,
       spaDirs,
@@ -613,15 +879,9 @@ async function packageLessonkitCourse(options) {
       writeAuthoringFiles: true
     });
     if (!build.ok) {
-      const validation2 = {
-        ok: false,
-        issues: build.issues
-      };
       return {
         ok: false,
-        courseDir: outDir,
-        target,
-        validation: validation2,
+        stagingDir,
         build,
         issues: build.issues.map((i) => ({
           path: i.path,
@@ -630,48 +890,256 @@ async function packageLessonkitCourse(options) {
         }))
       };
     }
-    const validation = {
+    return {
       ok: true,
-      manifest: build.manifest,
-      issues: build.issues
+      stagingDir,
+      build,
+      outputPath: "outputPath" in build ? build.outputPath : void 0,
+      outputDir: "outputDir" in build ? build.outputDir : void 0
     };
-    const stagingRoot = await fsp.realpath(stagingDir);
-    const remapArtifactPath = (artifactPath) => {
-      if (!artifactPath) return void 0;
-      const resolved = (0, import_node_path5.resolve)(artifactPath);
-      if (resolved === stagingRoot || resolved.startsWith(`${stagingRoot}/`)) {
-        return (0, import_node_path5.join)(outDir, resolved.slice(stagingRoot.length + 1));
-      }
-      return artifactPath;
+  } catch (err) {
+    await fsp2.rm(stagingDir, { recursive: true, force: true }).catch(() => void 0);
+    throw err;
+  }
+}
+async function ensureOutDirParent(outDir) {
+  await fsp2.mkdir((0, import_node_path7.dirname)(outDir), { recursive: true });
+}
+
+// src/packageCourse.ts
+async function validateLessonkitProject(options) {
+  return (0, import_api2.validateCourse)({
+    courseDir: (0, import_node_path8.resolve)(options.courseDir),
+    target: options.target
+  });
+}
+async function buildLessonkitProject(options) {
+  const buildOptions = {
+    courseDir: (0, import_node_path8.resolve)(options.courseDir),
+    target: options.target,
+    output: options.output,
+    dir: options.dir,
+    outputBaseDir: options.outputBaseDir,
+    assessments: options.assessments
+  };
+  return (0, import_api2.buildCourse)(buildOptions);
+}
+async function packageLessonkitCourse(options) {
+  const { target, output, dir, outputBaseDir, ...writeOpts } = options;
+  const inputValidation = validatePackageInputs({
+    target,
+    output,
+    outputBaseDir,
+    outDir: writeOpts.outDir,
+    projectRoot: writeOpts.projectRoot
+  });
+  if (!inputValidation.ok) {
+    return {
+      ok: false,
+      courseDir: inputValidation.courseDir,
+      target: inputValidation.target,
+      issues: inputValidation.issues
     };
-    const remappedOutputPath = remapArtifactPath(
-      "outputPath" in build ? build.outputPath : void 0
-    );
-    const remappedOutputDir = remapArtifactPath("outputDir" in build ? build.outputDir : void 0);
-    await fsp.mkdir((0, import_node_path5.dirname)(outDir), { recursive: true });
+  }
+  const outDir = inputValidation.outDir;
+  const descriptorValidation = validateDescriptorForTarget(writeOpts.descriptor, target);
+  if (!descriptorValidation.ok) {
+    return {
+      ok: false,
+      courseDir: outDir,
+      target,
+      issues: descriptorValidation.issues.map((i) => ({
+        path: i.path,
+        message: i.message
+      }))
+    };
+  }
+  const descriptor = descriptorValidation.descriptor;
+  const staged = await buildStagingPackage({
+    ...writeOpts,
+    descriptor,
+    target,
+    output,
+    dir,
+    outputBaseDir
+  });
+  if (!staged.ok) {
+    await fsp3.rm(staged.stagingDir, { recursive: true, force: true }).catch(() => void 0);
+    const validation2 = staged.build ? { ok: false, issues: staged.build.issues } : void 0;
+    return {
+      ok: false,
+      courseDir: outDir,
+      target,
+      validation: validation2,
+      build: staged.build,
+      issues: staged.issues
+    };
+  }
+  const { stagingDir, build } = staged;
+  const stagingRoot = await fsp3.realpath(stagingDir);
+  const artifactIssues = [
+    validateArtifactInStaging(stagingRoot, staged.outputPath, "outputPath"),
+    validateArtifactInStaging(stagingRoot, staged.outputDir, "outputDir")
+  ].filter((issue) => issue != null);
+  if (artifactIssues.length > 0) {
+    await fsp3.rm(stagingDir, { recursive: true, force: true }).catch(() => void 0);
+    return {
+      ok: false,
+      courseDir: outDir,
+      target,
+      validation: { ok: true, manifest: build.manifest, issues: build.issues },
+      build,
+      issues: artifactIssues
+    };
+  }
+  const remappedOutputPath = remapArtifactPaths(stagingRoot, outDir, staged.outputPath);
+  const remappedOutputDir = remapArtifactPaths(stagingRoot, outDir, staged.outputDir);
+  const validation = {
+    ok: true,
+    manifest: build.manifest,
+    issues: build.issues
+  };
+  try {
+    await ensureOutDirParent(outDir);
     await promoteStagingToOutDir(stagingDir, outDir);
-    promoted = true;
-    const remappedBuild = { ...build };
-    if ("outputPath" in remappedBuild && remappedOutputPath !== void 0) {
-      remappedBuild.outputPath = remappedOutputPath;
-    }
-    if ("outputDir" in remappedBuild && remappedOutputDir !== void 0) {
-      remappedBuild.outputDir = remappedOutputDir;
-    }
+  } catch (err) {
     return {
-      ok: true,
+      ok: false,
       courseDir: outDir,
       target,
-      outputPath: remappedOutputPath,
-      outputDir: remappedOutputDir,
-      fileCount: build.fileCount,
       validation,
-      build: remappedBuild
+      build,
+      issues: [
+        {
+          path: "promote",
+          message: err instanceof Error ? err.message : String(err)
+        }
+      ]
     };
-  } finally {
-    if (!promoted) {
-      await fsp.rm(stagingDir, { recursive: true, force: true }).catch(() => void 0);
+  }
+  const remappedBuild = { ...build };
+  if ("outputPath" in remappedBuild && remappedOutputPath !== void 0) {
+    remappedBuild.outputPath = remappedOutputPath;
+  }
+  if ("outputDir" in remappedBuild && remappedOutputDir !== void 0) {
+    remappedBuild.outputDir = remappedOutputDir;
+  }
+  return {
+    ok: true,
+    courseDir: outDir,
+    target,
+    outputPath: remappedOutputPath,
+    outputDir: remappedOutputDir,
+    fileCount: build.fileCount,
+    validation,
+    build: remappedBuild
+  };
+}
+
+// src/manifest.ts
+var DEFAULT_PATHS = {
+  spaDistDir: "dist",
+  lxpackOutDir: ".lxpack/course",
+  outputBaseDir: ".lxpack/out"
+};
+function parseLessonkitManifest(raw, label = "lessonkit.json", projectRoot) {
+  if (!raw || typeof raw !== "object") {
+    return { ok: false, issues: [{ path: label, message: "must be a JSON object" }] };
+  }
+  const config = raw;
+  const issues = [];
+  let schemaVersion = config.schemaVersion;
+  if (schemaVersion === "1") {
+    schemaVersion = 1;
+  }
+  if (schemaVersion !== 1) {
+    issues.push({
+      path: "schemaVersion",
+      message: `must be 1 (got ${String(config.schemaVersion)})`
+    });
+  }
+  const nameRaw = config.name;
+  const name = typeof nameRaw === "string" ? nameRaw.trim() : "";
+  if (!name) {
+    issues.push({ path: "name", message: "must be a non-empty string" });
+  }
+  const courseRaw = config.course;
+  if (Array.isArray(courseRaw)) {
+    issues.push({ path: "course", message: "must be an object, not an array" });
+    return { ok: false, issues };
+  }
+  if (!courseRaw || typeof courseRaw !== "object") {
+    issues.push({ path: "course", message: "must be an object" });
+    return { ok: false, issues };
+  }
+  const courseObj = courseRaw;
+  if (courseObj.lessons !== void 0 && !Array.isArray(courseObj.lessons)) {
+    issues.push({ path: "course.lessons", message: "must be an array" });
+  }
+  if (courseObj.assessments !== void 0 && !Array.isArray(courseObj.assessments)) {
+    issues.push({ path: "course.assessments", message: "must be an array" });
+  }
+  if (issues.length) return { ok: false, issues };
+  const validation = validateDescriptor(courseRaw);
+  if (!validation.ok) {
+    for (const i of validation.issues) {
+      issues.push({
+        path: i.path.startsWith("course.") ? i.path : `course.${i.path}`,
+        message: i.message
+      });
+    }
+  } else if (validation.descriptor.layout === "per-lesson-spa") {
+    issues.push({
+      path: "course.layout",
+      message: "per-lesson-spa is not supported by lessonkit package yet. Use single-spa or package via @lessonkit/lxpack directly."
+    });
+  }
+  const paths = { ...DEFAULT_PATHS };
+  const pathsRaw = config.paths;
+  if (pathsRaw !== void 0 && (typeof pathsRaw !== "object" || pathsRaw === null)) {
+    issues.push({ path: "paths", message: "must be an object" });
+  } else if (pathsRaw && typeof pathsRaw === "object") {
+    const p = pathsRaw;
+    for (const key of ["spaDistDir", "lxpackOutDir", "outputBaseDir"]) {
+      if (p[key] !== void 0) {
+        if (typeof p[key] !== "string" || !p[key].trim()) {
+          issues.push({ path: `paths.${key}`, message: "must be a non-empty string" });
+        } else {
+          paths[key] = p[key].trim();
+        }
+      }
+    }
+  }
+  const courseSpaDistDir = validation.ok ? validation.descriptor.spaDistDir?.trim() : void 0;
+  if (courseSpaDistDir && courseSpaDistDir !== paths.spaDistDir) {
+    issues.push({
+      path: "course.spaDistDir",
+      message: `"course.spaDistDir" (${courseSpaDistDir}) differs from "paths.spaDistDir" (${paths.spaDistDir}). Use paths.spaDistDir for CLI build and package.`
+    });
+  }
+  if (projectRoot) {
+    const pathIssues = validateProjectPaths(projectRoot, paths);
+    for (const pi of pathIssues) {
+      issues.push({ path: pi.path, message: pi.message });
+    }
+  }
+  if (issues.length) return { ok: false, issues };
+  if (!validation.ok) return { ok: false, issues };
+  return {
+    ok: true,
+    manifest: {
+      schemaVersion: 1,
+      name,
+      course: validation.descriptor,
+      paths
     }
+  };
+}
+async function loadLessonkitManifestFromFile(readJson, label = "lessonkit.json", projectRoot) {
+  try {
+    return parseLessonkitManifest(await readJson(), label, projectRoot);
+  } catch {
+    return { ok: false, issues: [{ path: label, message: "failed to read or parse JSON" }] };
   }
 }
 
@@ -681,6 +1149,15 @@ 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);
+function isQuizAnsweredData(data) {
+  return typeof data === "object" && data !== null && typeof data.checkId === "string";
+}
+function isQuizCompletedData(data) {
+  return typeof data === "object" && data !== null && typeof data.checkId === "string";
+}
+function isInteractionData(data) {
+  return typeof data === "object" && data !== null;
+}
 function telemetryEventToLessonkit(event) {
   if (!SUPPORTED.has(event.name)) {
     return null;
@@ -692,16 +1169,16 @@ function telemetryEventToLessonkit(event) {
   };
   if (name === "quiz_completed" || name === "quiz_answered") {
     const data = event.data;
-    mapped.assessmentId = data?.checkId;
-    if (data && "score" in data) {
-      mapped.score = data.score;
-      mapped.maxScore = data.maxScore;
-      mapped.passingScore = data.passingScore;
-    }
-    if (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;
     }
-  } else if (name === "interaction" && event.data) {
+  } else if (name === "interaction" && event.data && isInteractionData(event.data)) {
     mapped.data = event.data;
   }
   return mapped;
@@ -714,21 +1191,29 @@ var import_validators2 = require("@lxpack/validators");
   LESSONKIT_TELEMETRY_EVENTS,
   assessmentDescriptorToLxpack,
   buildLessonkitProject,
+  buildStagingPackage,
   descriptorToInterchange,
+  ensureOutDirParent,
   extractAssessments,
   lessonkitInterchangeSchema,
+  loadLessonkitManifestFromFile,
   mapLessonkitIds,
   mapLessonkitTelemetryToBridgeAction,
   mapLessonkitTelemetryToLxpack,
   materializeLessonkitProject,
   packageLessonkitCourse,
   parseLessonkitInterchange,
+  parseLessonkitManifest,
+  promoteStagingToOutDir,
+  remapArtifactPaths,
   resolveSafePackageOutputOverride,
   resolveSpaLessons,
   telemetryEventToLessonkit,
   themeToLxpackRuntime,
   validateDescriptor,
+  validateDescriptorForTarget,
   validateLessonkitProject,
+  validatePackageInputs,
   validateProjectPaths,
   writeLxpackProject
 });