@lessonkit/lxpack 0.9.2 → 1.0.0

package/dist/index.js

@@ -6,7 +6,14 @@ import {
 import { validateId } from "@lessonkit/core";
 
 // src/spaPath.ts
-import { resolve, sep } from "path";
+import { realpathSync } from "fs";
+import { relative, resolve, sep, win32 } from "path";
+function resolveComparablePath(p) {
+  if (/^[a-zA-Z]:[/\\]/.test(p)) {
+    return win32.resolve(p);
+  }
+  return resolve(p);
+}
 function isSafeRelativeSpaPath(spaPath) {
   if (!spaPath.length || spaPath.includes("\0")) return false;
   if (spaPath.startsWith("/") || spaPath.startsWith("\\")) return false;
@@ -16,13 +23,43 @@ function isSafeRelativeSpaPath(spaPath) {
   return true;
 }
 function assertResolvedPathUnderRoot(root, target) {
-  const rootResolved = resolve(root);
-  const targetResolved = resolve(target);
+  const rootResolved = resolveComparablePath(root);
+  const targetResolved = resolveComparablePath(target);
   const prefix = rootResolved.endsWith(sep) ? rootResolved : rootResolved + sep;
-  if (targetResolved !== rootResolved && !targetResolved.startsWith(prefix)) {
+  const win32Prefix = rootResolved.endsWith(win32.sep) ? rootResolved : rootResolved + 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 = realpathSync(rootResolved);
+  } catch {
+    rootReal = rootResolved;
+  }
+  let targetCheck;
+  try {
+    targetCheck = realpathSync(targetResolved);
+  } catch {
+    const rel = relative(rootResolved, targetResolved);
+    if (rel.startsWith("..") || rel.includes(`..${sep}`)) {
+      throw new Error(`unsafe path escapes project root: ${target}`);
+    }
+    targetCheck = 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(sep) ? rootResolved : rootResolved + sep;
+  const win32Prefix = rootResolved.endsWith(win32.sep) ? rootResolved : rootResolved + win32.sep;
+  return targetResolved.startsWith(prefix) || targetResolved.startsWith(win32Prefix);
+}
 
 // src/theme.ts
 import { getPresetTheme, themeToCssVariables } from "@lessonkit/themes";
@@ -198,7 +235,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)"
@@ -351,12 +388,12 @@ function descriptorToInterchange(descriptor) {
 }
 
 // src/writeProject.ts
-import { join, resolve as resolve4 } from "path";
+import { join as join2, resolve as resolve4 } from "path";
 import { materializeLessonkitProject } from "@lxpack/validators";
 
 // src/spaDirs.ts
 import { access } from "fs/promises";
-import { resolve as resolve3 } from "path";
+import { join, resolve as resolve3 } from "path";
 async function resolveSpaDirs(options) {
   const { descriptor, spaDistDir, lessonSpaDirs, projectRoot } = options;
   const spaLessons = resolveSpaLessons(descriptor);
@@ -364,13 +401,18 @@ async function resolveSpaDirs(options) {
     const spaDistRelative = spaDistDir ?? descriptor.spaDistDir ?? "dist";
     const srcDist = projectRoot ? resolve3(projectRoot, spaDistRelative) : resolve3(spaDistRelative);
     if (projectRoot) {
-      assertResolvedPathUnderRoot(resolve3(projectRoot), srcDist);
+      assertRealPathUnderRoot(resolve3(projectRoot), srcDist);
     }
     try {
       await access(srcDist);
     } catch {
       throw new Error(`spaDistDir not found: ${srcDist}`);
     }
+    try {
+      await access(join(srcDist, "index.html"));
+    } catch {
+      throw new Error(`spaDistDir must contain index.html: ${join(srcDist, "index.html")}`);
+    }
     const lessonId = spaLessons[0]?.id ?? "main";
     return { [lessonId]: srcDist };
   }
@@ -381,7 +423,23 @@ async function resolveSpaDirs(options) {
     if (!src) {
       throw new Error(`lessonSpaDirs missing build output for lesson "${lesson.id}"`);
     }
-    dirs[lesson.id] = resolve3(src);
+    const resolved = projectRoot ? resolve3(projectRoot, src) : resolve3(src);
+    if (projectRoot) {
+      assertRealPathUnderRoot(resolve3(projectRoot), resolved);
+    }
+    try {
+      await access(resolved);
+    } catch {
+      throw new Error(`lessonSpaDirs path not found for lesson "${lesson.id}": ${resolved}`);
+    }
+    try {
+      await access(join(resolved, "index.html"));
+    } catch {
+      throw new Error(
+        `lessonSpaDirs must contain index.html for lesson "${lesson.id}": ${join(resolved, "index.html")}`
+      );
+    }
+    dirs[lesson.id] = resolved;
   }
   return dirs;
 }
@@ -415,36 +473,114 @@ async function writeLxpackProject(options) {
   const courseDir = materialized.courseDir;
   return {
     outDir: courseDir,
-    courseYamlPath: join(courseDir, "course.yaml"),
-    lessonkitJsonPath: join(courseDir, "lessonkit.json")
+    courseYamlPath: join2(courseDir, "course.yaml"),
+    lessonkitJsonPath: join2(courseDir, "lessonkit.json")
   };
 }
 
 // src/packageCourse.ts
-import * as fsp from "fs/promises";
-import { dirname, join as join2, resolve as resolve5 } from "path";
-import { tmpdir } from "os";
+import { resolve as resolve6 } from "path";
+import * as fsp3 from "fs/promises";
 import {
   buildCourse,
-  packageLessonkit,
   validateCourse
 } from "@lxpack/api";
-async function validateLessonkitProject(options) {
-  return validateCourse({
-    courseDir: resolve5(options.courseDir),
-    target: options.target
-  });
+
+// src/packaging/validateInputs.ts
+import { join as join3, resolve as resolve5, win32 as win322 } from "path";
+function validatePackageInputs(options) {
+  const { target, output, outputBaseDir } = options;
+  const outDir = resolve5(options.outDir);
+  const projectRoot = options.projectRoot ? resolve5(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 = resolve5(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 = resolve5(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 buildCourse({
-    courseDir: resolve5(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 win322.join(outDir, relative2.replace(/\//g, win322.sep));
+  }
+  return join3(outDir, relative2);
 }
+
+// src/packaging/promote.ts
+import * as fsp from "fs/promises";
 async function pathExists(path) {
   try {
     await fsp.access(path);
@@ -453,82 +589,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 = resolve5(writeOpts.outDir);
-  const projectRoot = writeOpts.projectRoot ? resolve5(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 = resolve5(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(join2(tmpdir(), "lessonkit-lxpack-"));
-  let promoted = false;
+
+// src/packaging/staging.ts
+import * as fsp2 from "fs/promises";
+import { dirname, join as join4 } from "path";
+import { tmpdir } from "os";
+import { packageLessonkit } from "@lxpack/api";
+async function buildStagingPackage(options) {
+  const { target, output, dir, outputBaseDir, descriptor, ...writeOpts } = options;
+  const stagingDir = await fsp2.mkdtemp(join4(tmpdir(), "lessonkit-lxpack-"));
   try {
     let spaDirs;
     try {
@@ -536,8 +666,7 @@ async function packageLessonkitCourse(options) {
     } catch (err) {
       return {
         ok: false,
-        courseDir: outDir,
-        target,
+        stagingDir,
         issues: [
           {
             path: "spaDirs",
@@ -548,8 +677,8 @@ async function packageLessonkitCourse(options) {
     }
     const interchange = descriptorToInterchange(descriptor);
     const outputBase = outputBaseDir ?? ".lxpack/out";
-    await fsp.mkdir(join2(stagingDir, outputBase), { recursive: true });
-    const defaultOutput = output ?? (dir ? join2(outputBase, target) : join2(outputBase, `course-${target}.zip`));
+    await fsp2.mkdir(join4(stagingDir, outputBase), { recursive: true });
+    const defaultOutput = output ?? (dir ? join4(outputBase, target) : join4(outputBase, `course-${target}.zip`));
     const build = await packageLessonkit({
       interchange,
       spaDirs,
@@ -562,15 +691,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,
@@ -579,48 +702,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 = resolve5(artifactPath);
-      if (resolved === stagingRoot || resolved.startsWith(`${stagingRoot}/`)) {
-        return join2(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(dirname(outDir), { recursive: true });
+}
+
+// src/packageCourse.ts
+async function validateLessonkitProject(options) {
+  return validateCourse({
+    courseDir: resolve6(options.courseDir),
+    target: options.target
+  });
+}
+async function buildLessonkitProject(options) {
+  return buildCourse({
+    courseDir: resolve6(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(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" }] };
   }
 }
 
@@ -639,21 +980,28 @@ export {
   LESSONKIT_TELEMETRY_EVENTS,
   assessmentDescriptorToLxpack,
   buildLessonkitProject,
+  buildStagingPackage,
   descriptorToInterchange,
+  ensureOutDirParent,
   extractAssessments,
   lessonkitInterchangeSchema,
+  loadLessonkitManifestFromFile,
   mapLessonkitIds,
   mapLessonkitTelemetryToBridgeAction,
   mapLessonkitTelemetryToLxpack,
   materializeLessonkitProject2 as materializeLessonkitProject,
   packageLessonkitCourse,
   parseLessonkitInterchange,
+  parseLessonkitManifest,
+  promoteStagingToOutDir,
+  remapArtifactPaths,
   resolveSafePackageOutputOverride,
   resolveSpaLessons,
   telemetryEventToLessonkit,
   themeToLxpackRuntime,
   validateDescriptor,
   validateLessonkitProject,
+  validatePackageInputs,
   validateProjectPaths,
   writeLxpackProject
 };