@lessonkit/lxpack 0.9.3 → 1.0.0

package/dist/index.cjs

@@ -33,21 +33,28 @@ __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,
   validateLessonkitProject: () => validateLessonkitProject,
+  validatePackageInputs: () => validatePackageInputs,
   validateProjectPaths: () => validateProjectPaths,
   writeLxpackProject: () => writeLxpackProject
 });
@@ -57,7 +64,14 @@ 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;
@@ -67,13 +81,43 @@ function isSafeRelativeSpaPath(spaPath) {
   return true;
 }
 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 isResolvedPathUnderRoot(root, target) {
+  const rootResolved = resolveComparablePath(root);
+  const targetResolved = resolveComparablePath(target);
+  if (targetResolved === rootResolved) return true;
+  const prefix = rootResolved.endsWith(import_node_path.sep) ? rootResolved : rootResolved + import_node_path.sep;
+  const win32Prefix = rootResolved.endsWith(import_node_path.win32.sep) ? rootResolved : rootResolved + import_node_path.win32.sep;
+  return targetResolved.startsWith(prefix) || targetResolved.startsWith(win32Prefix);
+}
 
 // src/theme.ts
 var import_themes = require("@lessonkit/themes");
@@ -249,7 +293,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)"
@@ -415,13 +459,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 +483,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;
   }
@@ -476,26 +537,105 @@ async function writeLxpackProject(options) {
 }
 
 // src/packageCourse.ts
-var fsp = __toESM(require("fs/promises"), 1);
+var import_node_path7 = 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
-  });
+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) {
+    try {
+      assertResolvedPathUnderRoot(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 {
+      ok: false,
+      courseDir: outDir,
+      target,
+      issues: [{ path: "outputBaseDir", message: `unsafe outputBaseDir: ${outputBaseDir}` }]
+    };
+  }
+  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 {
+      assertRealPathUnderRoot(projectRoot, resolvedOutputBase);
+    } catch (err) {
+      return {
+        ok: false,
+        courseDir: outDir,
+        target,
+        issues: [
+          {
+            path: "outputBaseDir",
+            message: err instanceof Error ? err.message : String(err)
+          }
+        ]
+      };
+    }
+  }
+  if (projectRoot && output) {
+    const resolvedOutput = (0, import_node_path5.resolve)(projectRoot, output);
+    try {
+      assertResolvedPathUnderRoot(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 };
 }
-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
-  });
+function validateArtifactInStaging(stagingRoot, artifactPath, field) {
+  if (!artifactPath) return null;
+  const resolved = resolveComparablePath(artifactPath);
+  if (!isResolvedPathUnderRoot(stagingRoot, resolved)) {
+    return {
+      path: field,
+      message: `${field} is outside the staging directory: ${artifactPath}`
+    };
+  }
+  return null;
 }
+function remapArtifactPaths(stagingRoot, outDir, artifactPath) {
+  if (!artifactPath) return void 0;
+  const resolved = resolveComparablePath(artifactPath);
+  if (!isResolvedPathUnderRoot(stagingRoot, resolved)) {
+    return artifactPath;
+  }
+  const stagingResolved = resolveComparablePath(stagingRoot);
+  const relative2 = resolved === stagingResolved ? "" : resolved.slice(stagingResolved.length).replace(/^[/\\]/, "");
+  if (!relative2) return outDir;
+  if (/^[a-zA-Z]:[/\\]/.test(outDir)) {
+    return import_node_path5.win32.join(outDir, relative2.replace(/\//g, import_node_path5.win32.sep));
+  }
+  return (0, import_node_path5.join)(outDir, relative2);
+}
+
+// src/packaging/promote.ts
+var fsp = __toESM(require("fs/promises"), 1);
 async function pathExists(path) {
   try {
     await fsp.access(path);
@@ -504,82 +644,76 @@ async function pathExists(path) {
     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 promoteStagingToOutDir(stagingDir, outDir) {
   const tmpPromote = `${outDir}.tmp-promote`;
   const backup = `${outDir}.bak`;
-  await fsp.rename(stagingDir, tmpPromote);
+  await renameOrCopy(stagingDir, tmpPromote);
   const hadOutDir = await pathExists(outDir);
   if (hadOutDir) {
-    await fsp.rename(outDir, backup);
+    await renameOrCopy(outDir, backup);
   }
   try {
-    await fsp.rename(tmpPromote, outDir);
+    await renameOrCopy(tmpPromote, outDir);
   } catch (promoteError) {
     if (hadOutDir) {
       try {
-        await fsp.rename(backup, outDir);
+        await renameOrCopy(backup, outDir);
+      } catch (restoreError) {
+        const failedPromote2 = `${outDir}.failed-promote-${Date.now()}`;
+        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 ${outDir} after promote error:`,
+          `[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 = `${outDir}.failed-promote-${Date.now()}`;
+    try {
+      await renameOrCopy(tmpPromote, failedPromote);
+    } catch {
+      await fsp.rm(tmpPromote, { recursive: true, force: true }).catch(() => void 0);
     }
-    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;
-  if (projectRoot) {
-    assertResolvedPathUnderRoot(projectRoot, outDir);
-  }
-  if (outputBaseDir && !isSafeRelativeSpaPath(outputBaseDir)) {
-    return {
-      ok: false,
-      courseDir: outDir,
-      target,
-      issues: [{ path: "outputBaseDir", message: `unsafe outputBaseDir: ${outputBaseDir}` }]
-    };
-  }
-  if (projectRoot && output) {
-    const resolvedOutput = (0, import_node_path5.resolve)(projectRoot, output);
-    try {
-      assertResolvedPathUnderRoot(projectRoot, resolvedOutput);
-    } catch (err) {
-      return {
-        ok: false,
-        courseDir: outDir,
-        target,
-        issues: [
-          {
-            path: "output",
-            message: err instanceof Error ? err.message : String(err)
-          }
-        ]
-      };
-    }
-  }
-  const descriptorValidation = validateDescriptor(writeOpts.descriptor);
-  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 stagingDir = await fsp.mkdtemp((0, import_node_path5.join)((0, import_node_os.tmpdir)(), "lessonkit-lxpack-"));
-  let promoted = false;
+
+// src/packaging/staging.ts
+var fsp2 = __toESM(require("fs/promises"), 1);
+var import_node_path6 = 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_path6.join)((0, import_node_os.tmpdir)(), "lessonkit-lxpack-"));
   try {
     let spaDirs;
     try {
@@ -587,8 +721,7 @@ async function packageLessonkitCourse(options) {
     } catch (err) {
       return {
         ok: false,
-        courseDir: outDir,
-        target,
+        stagingDir,
         issues: [
           {
             path: "spaDirs",
@@ -599,8 +732,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_path6.join)(stagingDir, outputBase), { recursive: true });
+    const defaultOutput = output ?? (dir ? (0, import_node_path6.join)(outputBase, target) : (0, import_node_path6.join)(outputBase, `course-${target}.zip`));
     const build = await (0, import_api.packageLessonkit)({
       interchange,
       spaDirs,
@@ -613,15 +746,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 +757,266 @@ 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_path6.dirname)(outDir), { recursive: true });
+}
+
+// src/packageCourse.ts
+async function validateLessonkitProject(options) {
+  return (0, import_api2.validateCourse)({
+    courseDir: (0, import_node_path7.resolve)(options.courseDir),
+    target: options.target
+  });
+}
+async function buildLessonkitProject(options) {
+  return (0, import_api2.buildCourse)({
+    courseDir: (0, import_node_path7.resolve)(options.courseDir),
+    target: options.target,
+    output: options.output,
+    dir: options.dir,
+    outputBaseDir: options.outputBaseDir,
+    assessments: options.assessments
+  });
+}
+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 });
-    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;
+  }
+  const outDir = inputValidation.outDir;
+  const descriptorValidation = validateDescriptor(writeOpts.descriptor);
+  if (!descriptorValidation.ok) {
+    return {
+      ok: false,
+      courseDir: outDir,
+      target,
+      issues: descriptorValidation.issues.map((i) => ({
+        path: i.path,
+        message: i.message
+      }))
+    };
+  }
+  const descriptor = descriptorValidation.descriptor;
+  if (target === "xapi" || target === "cmi5") {
+    const activityIri = descriptor.tracking?.xapi?.activityIri?.trim();
+    if (!activityIri) {
+      return {
+        ok: false,
+        courseDir: outDir,
+        target,
+        issues: [
+          {
+            path: "course.tracking.xapi.activityIri",
+            message: "tracking.xapi.activityIri is required for xapi and cmi5 export targets"
+          }
+        ]
+      };
     }
+  }
+  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: true,
+      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);
+  } catch (err) {
+    return {
+      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 = [];
+  if (config.schemaVersion !== 1) {
+    issues.push({
+      path: "schemaVersion",
+      message: `must be 1 (got ${String(config.schemaVersion)})`
+    });
+  }
+  const name = config.name;
+  if (typeof name !== "string" || !name.trim()) {
+    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" }] };
   }
 }
 
@@ -714,21 +1059,28 @@ 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,
   validateLessonkitProject,
+  validatePackageInputs,
   validateProjectPaths,
   writeLxpackProject
 });